500 lines
14 KiB
Markdown
500 lines
14 KiB
Markdown
---
|
|
name: specweave-release:npm
|
|
description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Automates the complete release workflow with pre-flight checks, version bumping, tag creation, and GitHub Actions triggering. Use --only flag for quick local release (bumps version, builds, publishes to npm directly - NO git push, NO pipeline). Add --push to --only for complete local release with git sync. Use --only --local for FASTEST local-only version bump (no npm publish, no git, just version increment for local testing).
|
|
---
|
|
|
|
# /specweave-release:npm - NPM Release Automation
|
|
|
|
You are the NPM Release Assistant. Your job is to automate the patch version release process.
|
|
|
|
## Command Modes
|
|
|
|
| Command | Flow | Use Case |
|
|
|---------|------|----------|
|
|
| `/specweave-release:npm` | Bump → Push → **CI publishes** | Standard release (CI handles npm) |
|
|
| `/specweave-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
|
|
| `/specweave-release:npm --only --push` | Bump → Build → **Publish locally** → Push | Complete local release + git sync |
|
|
| `/specweave-release:npm --only --local` | **Bump ONLY** → NO build, NO publish, NO git | FASTEST: Local testing only |
|
|
|
|
## Detecting Mode
|
|
|
|
Check flags in the command invocation:
|
|
|
|
```
|
|
--only --local → Version bump ONLY (no build, no publish, no git) - FASTEST
|
|
--only --push → Direct publish + push to git after
|
|
--only → Direct publish to npm (bypass CI)
|
|
(no flags) → Default: push to git, CI publishes
|
|
```
|
|
|
|
**Flag Detection Order:**
|
|
1. Check for `--only` flag
|
|
2. If `--only` present, check for `--local` flag → LOCAL MODE (fastest)
|
|
3. If `--only` present, check for `--push` flag → DIRECT MODE + PUSH
|
|
4. If `--only` only → DIRECT MODE
|
|
5. No flags → DEFAULT MODE
|
|
|
|
**If `--only --local`**: Use LOCAL MODE (section "Local Mode Workflow") - FASTEST!
|
|
**If `--only --push`**: Use DIRECT MODE WITH PUSH (section "Direct Mode + Push Workflow")
|
|
**If `--only` only**: Use DIRECT MODE (section "Direct Mode Workflow")
|
|
**If no flags**: Use DEFAULT MODE (continue with steps below)
|
|
|
|
## Your Task
|
|
|
|
Execute the following steps in order:
|
|
|
|
### 1. Pre-flight Checks
|
|
|
|
```bash
|
|
# Verify we're on develop branch
|
|
git rev-parse --abbrev-ref HEAD
|
|
|
|
# Check for uncommitted changes
|
|
git status --porcelain
|
|
|
|
# Verify current version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
**STOP if**:
|
|
- Not on `develop` branch (ask user to switch)
|
|
- Uncommitted changes exist (ask user to commit first)
|
|
|
|
### 2. Bump Patch Version
|
|
|
|
```bash
|
|
# This creates commit + tag automatically
|
|
npm version patch -m "chore: bump version to %s"
|
|
```
|
|
|
|
**What this does**:
|
|
- Updates `package.json` and `package-lock.json`
|
|
- Creates git commit with message "chore: bump version to X.Y.Z"
|
|
- Creates git tag `vX.Y.Z`
|
|
|
|
### 3. Extract New Version
|
|
|
|
```bash
|
|
# Get the new version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
### 4. Push to GitHub
|
|
|
|
```bash
|
|
# Push commit and tag to trigger GitHub Actions
|
|
git push origin develop --follow-tags
|
|
```
|
|
|
|
**What happens next**:
|
|
- GitHub Actions workflow detects the tag
|
|
- Runs tests
|
|
- Publishes to npm
|
|
- Creates GitHub release
|
|
|
|
### 5. Report Results
|
|
|
|
Show the user:
|
|
```markdown
|
|
✅ Release initiated successfully!
|
|
|
|
📦 **Version**: vX.Y.Z
|
|
🔗 **Tag**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
|
|
⏳ **GitHub Actions**: https://github.com/anton-abyzov/specweave/actions
|
|
|
|
**Next steps**:
|
|
1. Monitor GitHub Actions workflow (1-2 minutes)
|
|
2. Verify npm publish: https://www.npmjs.com/package/specweave
|
|
3. Check GitHub release notes
|
|
|
|
**Note**: GitHub Actions will automatically:
|
|
- Build and test the package
|
|
- Publish to npm
|
|
- Create GitHub release with CHANGELOG notes
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**If `npm version` fails**:
|
|
- Check if version already exists
|
|
- Verify package.json is valid
|
|
- Ask user to manually fix and retry
|
|
|
|
**If `git push` fails**:
|
|
- Check network connection
|
|
- Verify git credentials
|
|
- Check branch protection rules
|
|
|
|
## Safety Rules
|
|
|
|
- ✅ ONLY bump patch version (never minor/major without confirmation)
|
|
- ✅ ALWAYS check for uncommitted changes first
|
|
- ✅ ALWAYS verify on develop branch
|
|
- ✅ NEVER force push
|
|
- ✅ NEVER skip pre-flight checks
|
|
|
|
## Success Criteria (Default Mode)
|
|
|
|
✅ Version bumped in package.json
|
|
✅ Git commit created
|
|
✅ Git tag created
|
|
✅ Changes pushed to GitHub
|
|
✅ GitHub Actions workflow triggered
|
|
|
|
---
|
|
|
|
## DIRECT MODE WORKFLOW (--only flag)
|
|
|
|
Use this workflow when `--only` flag is detected. This publishes directly to npm WITHOUT git push or GitHub Actions.
|
|
|
|
### 1. Pre-flight Checks (Same as Default)
|
|
|
|
```bash
|
|
# Verify we're on develop branch
|
|
git rev-parse --abbrev-ref HEAD
|
|
|
|
# Check for uncommitted changes
|
|
git status --porcelain
|
|
|
|
# Verify current version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
**STOP if**:
|
|
- Not on `develop` branch (ask user to switch)
|
|
- Uncommitted changes exist (ask user to commit first)
|
|
|
|
### 2. Bump Patch Version (Same as Default)
|
|
|
|
```bash
|
|
# This creates commit + tag automatically
|
|
npm version patch -m "chore: bump version to %s"
|
|
```
|
|
|
|
**What this does**:
|
|
- Updates `package.json` and `package-lock.json`
|
|
- Creates git commit with message "chore: bump version to X.Y.Z"
|
|
- Creates git tag `vX.Y.Z`
|
|
|
|
### 3. Extract New Version
|
|
|
|
```bash
|
|
# Get the new version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
### 4. Build Package
|
|
|
|
```bash
|
|
# Build the package before publishing
|
|
npm run rebuild
|
|
```
|
|
|
|
**Critical**: Must rebuild to ensure dist/ is up-to-date before publishing.
|
|
|
|
### 5. Publish to NPM Directly
|
|
|
|
```bash
|
|
# Publish directly to npm (bypasses GitHub Actions)
|
|
npm publish
|
|
```
|
|
|
|
**What this does**:
|
|
- Builds package tarball
|
|
- Publishes to npm registry immediately
|
|
- No GitHub Actions involvement
|
|
|
|
### 6. Report Results (Direct Mode)
|
|
|
|
Show the user:
|
|
```markdown
|
|
✅ **Published directly to npm!**
|
|
|
|
📦 **Version**: vX.Y.Z
|
|
🔗 **NPM**: https://www.npmjs.com/package/specweave
|
|
🏷️ **Git Tag**: vX.Y.Z (local only)
|
|
|
|
**What happened**:
|
|
- ✅ Version bumped and committed locally
|
|
- ✅ Git tag created locally
|
|
- ✅ Package built (npm run rebuild)
|
|
- ✅ Published to npm directly
|
|
- ⏸️ Git NOT pushed (use `git push origin develop --follow-tags` later if needed)
|
|
|
|
**Verify**:
|
|
- Check npm: https://www.npmjs.com/package/specweave
|
|
- Verify version: `npm view specweave version`
|
|
- Install globally: `npm install -g specweave@X.Y.Z`
|
|
|
|
**Note**: Local release only. Push to GitHub manually when ready:
|
|
`git push origin develop --follow-tags`
|
|
```
|
|
|
|
## Direct Mode Safety Rules
|
|
|
|
- ✅ ALWAYS rebuild before publishing (`npm run rebuild`)
|
|
- ✅ Use `--only` for emergency/quick releases or local testing
|
|
- ✅ Default mode (GitHub Actions) is preferred for regular releases
|
|
- ✅ Direct mode gives immediate feedback (no CI wait time)
|
|
- ⚠️ Remember to push git changes later to sync GitHub
|
|
|
|
## Success Criteria (Direct Mode)
|
|
|
|
✅ Version bumped in package.json
|
|
✅ Git commit created locally
|
|
✅ Git tag created locally
|
|
✅ Package rebuilt
|
|
✅ Published to npm directly
|
|
⏸️ Git NOT pushed (manual sync later)
|
|
|
|
---
|
|
|
|
## DIRECT MODE + PUSH WORKFLOW (--only --push flags)
|
|
|
|
Use this workflow when BOTH `--only` AND `--push` flags are detected. This is the **complete local release** - publishes to npm directly AND pushes to git.
|
|
|
|
**Use case**: You want full control - publish immediately, then sync git. No CI involvement in npm publish.
|
|
|
|
### 1. Pre-flight Checks
|
|
|
|
```bash
|
|
# Verify we're on develop branch
|
|
git rev-parse --abbrev-ref HEAD
|
|
|
|
# Check for uncommitted changes
|
|
git status --porcelain
|
|
|
|
# Verify current version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
**STOP if**:
|
|
- Not on `develop` branch (ask user to switch)
|
|
|
|
**If uncommitted changes exist → AUTO-COMMIT FIRST (Step 1b)**
|
|
|
|
### 1b. Auto-Commit Uncommitted Changes (if any)
|
|
|
|
When `--only --push` is used, uncommitted changes should be committed automatically before version bump.
|
|
|
|
**Algorithm to generate commit message:**
|
|
|
|
1. Run `git status --porcelain` and categorize files:
|
|
- `src/**` → code changes
|
|
- `*.md`, `docs/` → documentation
|
|
- `.specweave/docs/internal/**` → internal docs
|
|
- `plugins/**` → plugin changes
|
|
- `tests/**`, `*.test.ts` → test changes
|
|
- `package*.json`, `*.config.*` → config/deps
|
|
|
|
2. Determine primary category (most files) and action (add/update/remove):
|
|
- New files (`??`, `A`) → "add"
|
|
- Modified (`M`) → "update"
|
|
- Deleted (`D`) → "remove"
|
|
|
|
3. Generate concise message: `type: action description`
|
|
|
|
**Examples:**
|
|
- Many ADR renames + docs moves → `chore: reorganize internal docs structure`
|
|
- Plugin command updates → `feat(release): add --push flag to npm release`
|
|
- Mixed code + docs → `chore: update code and documentation`
|
|
|
|
**Execute auto-commit:**
|
|
```bash
|
|
git add -A
|
|
git commit -m "[generated message]"
|
|
```
|
|
|
|
Then continue with version bump.
|
|
|
|
### 2. Bump Patch Version
|
|
|
|
```bash
|
|
# This creates commit + tag automatically
|
|
npm version patch -m "chore: bump version to %s"
|
|
```
|
|
|
|
### 3. Extract New Version
|
|
|
|
```bash
|
|
# Get the new version
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
### 4. Build Package
|
|
|
|
```bash
|
|
# Build the package before publishing
|
|
npm run rebuild
|
|
```
|
|
|
|
**Critical**: Must rebuild to ensure dist/ is up-to-date before publishing.
|
|
|
|
### 5. Publish to NPM Directly
|
|
|
|
```bash
|
|
# Publish directly to npm (bypasses GitHub Actions)
|
|
npm publish
|
|
```
|
|
|
|
### 6. Push to Git (NEW!)
|
|
|
|
```bash
|
|
# Push commit and tag to sync with remote
|
|
git push origin develop --follow-tags
|
|
```
|
|
|
|
**What this does**:
|
|
- Syncs your version bump commit to GitHub
|
|
- Pushes the version tag (vX.Y.Z)
|
|
- Does NOT trigger CI npm publish (already published!)
|
|
|
|
### 7. Report Results (Direct Mode + Push)
|
|
|
|
Show the user:
|
|
```markdown
|
|
✅ **Complete local release!**
|
|
|
|
📦 **Version**: vX.Y.Z
|
|
🔗 **NPM**: https://www.npmjs.com/package/specweave
|
|
🏷️ **Git Tag**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
|
|
|
|
**What happened**:
|
|
- ✅ Version bumped and committed
|
|
- ✅ Git tag created
|
|
- ✅ Package built (npm run rebuild)
|
|
- ✅ Published to npm directly
|
|
- ✅ Pushed to GitHub (commit + tag)
|
|
|
|
**Verify**:
|
|
- NPM: https://www.npmjs.com/package/specweave
|
|
- Version: `npm view specweave version`
|
|
- GitHub: Check releases page
|
|
|
|
**Note**: This was a direct publish. GitHub Actions will NOT republish
|
|
(the tag already exists, CI skips existing versions).
|
|
```
|
|
|
|
## Direct Mode + Push Safety Rules
|
|
|
|
- ✅ ALWAYS rebuild before publishing
|
|
- ✅ Publishes FIRST, then pushes (ensures npm has the version)
|
|
- ✅ If push fails, npm already has the release (safe state)
|
|
- ✅ CI will skip publishing for this version (tag already exists)
|
|
- ⚠️ Use when you need immediate npm availability + git sync
|
|
|
|
## Success Criteria (Direct Mode + Push)
|
|
|
|
✅ Version bumped in package.json
|
|
✅ Git commit created
|
|
✅ Git tag created
|
|
✅ Package rebuilt
|
|
✅ Published to npm directly
|
|
✅ Pushed to GitHub (commit + tag synced)
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Standard release (CI handles npm publish)
|
|
/specweave-release:npm
|
|
|
|
# Quick local publish, sync git later
|
|
/specweave-release:npm --only
|
|
|
|
# Complete local release (publish + push)
|
|
/specweave-release:npm --only --push
|
|
|
|
# FASTEST: Version bump only (no publish, no git, no build)
|
|
/specweave-release:npm --only --local
|
|
```
|
|
|
|
| Scenario | Command | NPM Published By | Git Pushed |
|
|
|----------|---------|------------------|------------|
|
|
| Normal release | (no flags) | GitHub Actions | ✅ Yes |
|
|
| Quick local, push later | `--only` | You (local) | ❌ No |
|
|
| Complete local release | `--only --push` | You (local) | ✅ Yes |
|
|
| **FASTEST local test** | `--only --local` | ❌ None | ❌ No |
|
|
|
|
---
|
|
|
|
## LOCAL MODE WORKFLOW (--only --local flags) - FASTEST!
|
|
|
|
Use this workflow when BOTH `--only` AND `--local` flags are detected. This is the **fastest possible** version bump - NO npm publish, NO git operations, NO build. Just increment the version number for local testing.
|
|
|
|
**Use case**: You need to quickly test a new version locally without publishing anywhere. Perfect for:
|
|
- Testing version-dependent features
|
|
- Local development iterations
|
|
- Quick version bumps before a real release
|
|
|
|
### 1. Minimal Pre-flight Check
|
|
|
|
```bash
|
|
# Just verify current version (no git checks needed!)
|
|
node -p "require('./package.json').version"
|
|
```
|
|
|
|
**NO git checks** - we're not committing or pushing anything!
|
|
|
|
### 2. Bump Version (NO git commit, NO tag)
|
|
|
|
```bash
|
|
# Bump version WITHOUT creating git commit or tag
|
|
npm version patch --no-git-tag-version
|
|
```
|
|
|
|
**What this does**:
|
|
- Updates `package.json` version ONLY
|
|
- Updates `package-lock.json` version ONLY
|
|
- NO git commit created
|
|
- NO git tag created
|
|
- INSTANT (< 1 second)
|
|
|
|
### 3. Report Results (Local Mode)
|
|
|
|
Show the user:
|
|
```markdown
|
|
⚡ **FAST local version bump!**
|
|
|
|
📦 **Version**: X.Y.Z → X.Y.(Z+1)
|
|
|
|
**What happened**:
|
|
- ✅ package.json version bumped
|
|
- ✅ package-lock.json updated
|
|
- ⏭️ NO git commit (use `git add . && git commit` later)
|
|
- ⏭️ NO git tag (use `git tag vX.Y.Z` later)
|
|
- ⏭️ NO npm publish (use `npm publish` later)
|
|
- ⏭️ NO build (use `npm run rebuild` later)
|
|
|
|
**Next steps when ready to release**:
|
|
1. Build: `npm run rebuild`
|
|
2. Test: `npm test`
|
|
3. Commit: `git add . && git commit -m "chore: bump version to X.Y.Z"`
|
|
4. Tag: `git tag vX.Y.Z`
|
|
5. Publish: `npm publish`
|
|
6. Push: `git push origin develop --follow-tags`
|
|
|
|
**Or use**: `/specweave-release:npm --only --push` for full release
|
|
```
|
|
|
|
## Local Mode Safety Rules
|
|
|
|
- ✅ FASTEST possible - single npm command
|
|
- ✅ NO network operations (no npm publish, no git push)
|
|
- ✅ NO disk-heavy operations (no build)
|
|
- ✅ Safe to run multiple times (just increments version)
|
|
- ⚠️ Remember: version is NOT published or committed!
|
|
- ⚠️ Run `npm run rebuild` before testing locally
|
|
|
|
## Success Criteria (Local Mode)
|
|
|
|
✅ Version bumped in package.json
|
|
✅ Version bumped in package-lock.json
|
|
⏭️ NO git commit
|
|
⏭️ NO git tag
|
|
⏭️ NO npm publish
|
|
⏭️ NO build
|
|
|
|
**Time**: < 1 second
|