npm

/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 | DEFAULT: FULL RELEASE | | /sw:npm --quick | Auto-commit → PUSH → Bump → Build → Publish locally → NO GH release | QUICK: Save + Local Release | | /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")

DEFAULT MODE WORKFLOW (no flags) - INSTANT RELEASE

This is the default workflow when no flags are provided. Auto-commits any dirty changes, syncs git FIRST, then publishes to npmjs.org. One command does everything!

Use case: You made changes and want to release immediately. No manual steps needed.

CRITICAL ORDER: Git sync FIRST, then release. This ensures:

• Your code is safe on remote before any release operations
• If npm publish fails, git is already synced (clean state)
• No risk of local-only commits that could be lost

1. Pre-flight Check (Minimal)

# Verify we're on develop branch
git rev-parse --abbrev-ref HEAD

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

STOP if: Not on develop branch (ask user to switch)

2. Auto-Commit Dirty Changes (if any)

# Check for uncommitted changes
git status --porcelain

If dirty, generate smart commit message and commit:

git add -A
git commit -m "[auto-generated message based on changed files]"

Message generation rules:

• src/** changes → fix: update implementation
• plugins/** changes → feat(plugins): update plugin
• .specweave/** changes → chore: update specweave config
• *.md changes → docs: update documentation
• Mixed → chore: update code and documentation

3. PUSH DIRTY COMMIT TO REMOTE FIRST! (CRITICAL!)

BEFORE any release operations, sync git:

# Push dirty commit to remote FIRST - ensures code is safe before release
git push origin develop

Why this order?

• ✅ Your changes are safely on GitHub BEFORE release starts
• ✅ If npm publish fails later, git is already synced
• ✅ No risk of "released but not pushed" state
• ✅ Clean recovery if anything fails mid-release

4. Smart Version Bump (Prerelease-Aware!)

CRITICAL: Detect prerelease and bump correctly!

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

# Check if prerelease (contains hyphen like 1.0.0-rc.1, 1.0.0-beta.2)
if [[ "$CURRENT" == *"-"* ]]; then
  echo "Detected PRERELEASE version"
  # Check for --stable flag in command args
  if [[ "--stable flag was passed" ]]; then
    echo "Promoting to stable (--stable flag)"
    npm version patch -m "chore: release stable version %s"
  else
    echo "Incrementing prerelease number"
    npm version prerelease -m "chore: bump version to %s"
  fi
else
  echo "Detected STABLE version"
  npm version patch -m "chore: bump version to %s"
fi

Examples:

• 1.0.0-rc.1 → 1.0.0-rc.2 (prerelease increment, DEFAULT)
• 1.0.0-rc.5 + --stable → 1.0.1 (promote to stable, EXPLICIT)
• 1.0.0 → 1.0.1 (patch increment)

This creates a NEW commit + tag locally.

5. Build Package

npm run rebuild

6. Publish to NPM (with explicit registry!)

# CRITICAL: Always specify registry to avoid ~/.npmrc redirecting to private feeds!
npm publish --registry https://registry.npmjs.org

7. Push Version Commit + Tag

# Push the version bump commit and tag
git push origin develop --follow-tags

8. MANDATORY: Create GitHub Release

THIS STEP IS REQUIRED - DO NOT SKIP!

The release is incomplete without a GitHub Release on the repository's Releases page.

# Get the new version
NEW_VERSION=$(node -p "require('./package.json').version")

# Extract release notes from CHANGELOG.md (if available)
if [ -f CHANGELOG.md ] && grep -q "## \[$NEW_VERSION\]" CHANGELOG.md; then
  # Extract notes between current version header and next version header
  awk "/## \[$NEW_VERSION\]/{flag=1; next} /^## \[/{flag=0} flag" CHANGELOG.md > /tmp/release-notes.md
else
  # Generate minimal release notes from recent commits
  echo "## What's Changed" > /tmp/release-notes.md
  echo "" >> /tmp/release-notes.md
  LAST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
  if [ -