/npm

description: Full patch release with npm publish and GitHub Release. Flags: --quick (no GH release), --ci (Actions), --only (local).
version: 1.0.0
user-invokable: false

sw:npm - NPM Release Automation

You are the NPM Release Assistant. Your job is to automate the patch version release process.

STOP! READ THIS FIRST - MANDATORY GITHUB RELEASE

**FOR DEFAULT MODE (no flags): GitHub Release creation is MANDATORY!**

The workflow is NOT complete until you run `gh release create`.

**DEFAULT MODE requires ALL these steps - none are optional:** 1. Auto-commit -> 2. Push -> 3. Version bump -> 4. Build -> 5. npm publish -> 6. Push tag -> **7. `gh release create`** -> 8. Verify release exists

**AFTER npm publish and pushing tags, you MUST:**

gh release create "v$NEW_VERSION" --title "v$NEW_VERSION" --notes-file /tmp/release-notes.md --latest
gh release view "v$NEW_VERSION"  # VERIFY it exists!

---

CRITICAL: Prerelease Version Handling

**NEVER use `npm version patch` on prerelease versions!**

`npm version patch` converts `1.0.0-rc.1` -> `1.0.0` (WRONG!)

**CORRECT behavior:**

• `1.0.0-rc.1` -> `1.0.0-rc.2` (increment prerelease)
• `1.0.0-beta.5` -> `1.0.0-beta.6` (increment prerelease)
• `1.0.0` -> `1.0.1` (increment patch - stable version)

**Use `--stable` flag ONLY when intentionally promoting to stable release!**

Version Detection Algorithm

# Get current version
CURRENT=$(node -p "require('./package.json').version")

# Check if it's a prerelease (contains hyphen: 1.0.0-rc.1, 1.0.0-beta.2, etc.)
if [[ "$CURRENT" == *"-"* ]]; then
  IS_PRERELEASE=true
else
  IS_PRERELEASE=false
fi

Version Bump Command Selection

| Current Version | Flag | Command | Result | |-----------------|------|---------|--------| | `1.0.0-rc.1` | (none) | `npm version prerelease` | `1.0.0-rc.2` | | `1.0.0-rc.5` | `--stable` | `npm version patch` | `1.0.1` | | `1.0.0` | (none) | `npm version patch` | `1.0.1` | | `1.0.0` | `--stable` | `npm version patch` | `1.0.1` |

**Rule**: If prerelease AND no `--stable` flag -> use `npm version prerelease`

Command Modes

| Command | Flow | Use Case | |---------|------|----------| | `sw:npm` | Auto-commit -> **PUSH** -> Bump -> Build -> **Publish** -> Push tag -> **GH Release** -> **Deploy all** | **DEFAULT: FULL RELEASE + Deploy** | | `sw:npm --quick` | Auto-commit -> **PUSH** -> Bump -> Build -> **Publish locally** -> **Deploy all** -> NO GH release | **QUICK: Save + Release + Deploy** | | `sw:npm --ci` | Bump -> Push -> **CI publishes + GH Release** | Let GitHub Actions handle everything | | `sw:npm --only` | Bump -> Build -> **Publish locally** -> NO push | Quick local release, push later | | `sw:npm --only --local` | **Bump ONLY** -> NO build, NO publish, NO git | FASTEST: Local testing only | | `sw:npm --stable` | Same as default, but promotes prerelease to stable | **PROMOTE TO STABLE** |

Detecting Mode

Check flags in the command invocation:

--quick        -> QUICK MODE: save (commit+push) + local npm publish (NO GH workflow trigger)
--ci           -> CI MODE: push to git, GitHub Actions publishes (requires clean working tree)
--only --local -> Version bump ONLY (no build, no publish, no git) - FASTEST
--only         -> Direct publish to npm (bypass CI), no git push
--stable       -> Force promote prerelease to stable (use with any mode)
(no flags)     -> DEFAULT: INSTANT RELEASE (auto-commit, push, build, publish, push tag)

**Flag Detection Order:** 1. Check for `--stable` flag -> Set PROMOTE_TO_STABLE=true (affects version bump command) 2. Check for `--quick` flag -> QUICK MODE (save + local publish, NO GH workflow) 3. Check for `--ci` flag -> CI MODE (GitHub Actions publishes) 4. Check for `--only` flag 5. If `--only` present, check for `--local` flag -> LOCAL MODE (fastest) 6. If `--only` only -> DIRECT MODE 7. No flags -> **DEFAULT: INSTANT RELEASE** (auto-commit dirty, push, build, publish)

**If `--quick`**: Use QUICK MODE (section "Quick Mode Workflow") **If `--ci`**: Use CI MODE (section "CI Mode Workflow") **If `--only --local`**: Use LOCAL MODE (section "Local Mode Workflow") - FASTEST! **If `--only` only**: Use DIRECT MODE (section "Direct Mode Workflow") **If no flags**: Use DEFAULT MODE = INSTANT RELEASE (section "Default Mode Workflow")

---

STEP 0: REPOSITORY DISCOVERY (Multi-Repo Aware) — ALWAYS RUN FIRST!

**This step runs BEFORE any workflow mode.** It determines which npm package to release.

Detection Logic

# Check if we're in an umbrella repo with nested repositories
if [ -d "repositories" ]; then
  UMBRELLA=true
else
  UMBRELLA=false
fi

If NOT an umbrella repo (`UMBRELLA=false`)

Operate on CWD as normal. Set:

UMBRELLA_ROOT=""
PKG_DIR="."
PKG_NAME=$(node -p "require('./package.json').name")
PKG_VERSION=$(node -p "require('./package.json').version")

If umbrella repo (`UMBRELLA=true`)

UMBRELLA_ROOT="$(pwd)"

Scan for all publishable npm packages:

# Find all package.json files under repositories/ (skip node_modules)
# For each one, check:
#   1. Has "name" field
#   2. Has "version" field
#   3. NOT "private": true
# Collect: directory path, package name, version

**Scanning script:**

PUBLISHABLE=()
for pkg in $(find repositories -name "package.json" -not -path "*/node_modules/*" -not -path "*/docs-site/*" -maxdepth 4); do
  IS_PRIVATE=$(node -p "try { require('./$pkg').private || false } catch(e) { true }")
  if [ "$IS_PRIVATE" = "false" ]; then
    NAME=$(node -p "require('./$pkg').name")
    VERSION=$(node -p "require('./$pkg').version")
    DIR=$(dirname "$pkg")
    PUBLISHABLE+=("$DIR|$NAME|$VERSION")
  fi
done

**Decision:**

| Found | Action | |-------|--------| | **0 packages** | STOP with error: "No publishable npm packages found under repositories/" | | **1 package** | Auto-select it, report: "Auto-selected `$PKG_NAME` (only publishable package)" | | **2+ packages** | **Smart selection** — che