Initial commit
This commit is contained in:
Zhongwei Li
499
commands/specweave-release-npm.md
Normal file
499
commands/specweave-release-npm.md
Normal file
@@ -0,0 +1,499 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user