@wipcomputer/wip-ai-devops-toolbox 1.9.20

package/tools/wip-release/README.md

@@ -0,0 +1,45 @@
+###### WIP Computer
+
+[![npm](https://img.shields.io/npm/v/@wipcomputer/wip-release)](https://www.npmjs.com/package/@wipcomputer/wip-release) [![CLI / TUI](https://img.shields.io/badge/interface-CLI_/_TUI-black)](https://github.com/wipcomputer/wip-release/blob/main/cli.js) [![OpenClaw Skill](https://img.shields.io/badge/interface-OpenClaw_Skill-black)](https://clawhub.ai/parkertoddbrooks/wip-release) [![Claude Code Skill](https://img.shields.io/badge/interface-Claude_Code_Skill-black)](https://github.com/wipcomputer/wip-release/blob/main/SKILL.md) [![Universal Interface Spec](https://img.shields.io/badge/Universal_Interface_Spec-black?style=flat&color=black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/SPEC.md)
+
+# WIP.release
+
+You ship a fix. Now you have to bump package.json, update CHANGELOG.md, sync the version in SKILL.md, commit, tag, push, publish to npm, publish to GitHub Packages, and create a GitHub release. Every time. Miss a step and versions drift.
+
+`wip-release` does all of it in one command. It also checks that product docs (dev update, roadmap, readme-first) are up to date before publishing. Patches get a warning. Minor and major releases are blocked until docs are updated.
+
+## Install
+
+Open your AI coding tool and say:
+
+```
+Read the REFERENCE.md and SKILL.md at github.com/wipcomputer/wip-release.
+Then explain to me:
+1. What is this tool?
+2. What does it do?
+3. What would it change or fix in our current release process?
+
+Then ask me:
+- Do you have more questions?
+- Do you want to integrate it into our system?
+- Do you want to clone it (use as-is) or fork it (so you can contribute back if you find bugs)?
+```
+
+Your agent will read the repo, explain the tool, and walk you through integration interactively.
+
+Also see **[wip-file-guard](https://github.com/wipcomputer/wip-file-guard)** ... the lock for the repo. Blocks AI agents from overwriting your critical files.
+
+See [REFERENCE.md](REFERENCE.md) for full usage, pipeline steps, flags, auth, and module API.
+
+---
+
+## License
+
+```
+CLI, MCP server, skills                        MIT    (use anywhere, no restrictions)
+Hosted or cloud service use                    AGPL   (network service distribution)
+```
+
+AGPL for personal use is free.
+
+Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).

package/tools/wip-release/REFERENCE.md

@@ -0,0 +1,100 @@
+###### WIP Computer
+# wip-release ... Reference
+
+Detailed usage, pipeline steps, flags, auth, and module API.
+
+## Usage
+
+Run from inside any repo:
+
+```bash
+wip-release patch                    # 1.0.0 -> 1.0.1
+wip-release minor                    # 1.0.0 -> 1.1.0
+wip-release major                    # 1.0.0 -> 2.0.0
+
+wip-release patch --notes="fix auth config"   # with changelog note
+wip-release minor --dry-run                    # preview, no changes
+wip-release patch --no-publish                 # bump + tag only
+```
+
+## What It Does
+
+```
+  wip-grok: 1.0.0 -> 1.0.1 (patch)
+  ────────────────────────────────────────
+  ✓ package.json -> 1.0.1
+  ✓ SKILL.md -> 1.0.1
+  ✓ CHANGELOG.md updated
+  ✓ Committed and tagged v1.0.1
+  ✓ Pushed to remote
+  ✓ Published to npm
+  ✓ Published to GitHub Packages
+  ✓ GitHub release v1.0.1 created
+  ✓ Published to ClawHub
+
+  Done. wip-grok v1.0.1 released.
+```
+
+## Pipeline Steps
+
+1. **Bump `package.json`** ... patch, minor, or major
+2. **Sync `SKILL.md`** ... updates version in YAML frontmatter (if file exists)
+3. **Update `CHANGELOG.md`** ... prepends new version entry with date and notes
+4. **Git commit + tag** ... commits changed files, creates `vX.Y.Z` tag
+5. **Push** ... pushes commit and tag to remote
+6. **npm publish** ... publishes to npmjs.com (auth via 1Password)
+7. **GitHub Packages** ... publishes to npm.pkg.github.com
+8. **GitHub release** ... creates release with changelog notes
+9. **ClawHub publish** ... publishes skill to ClawHub (if SKILL.md exists)
+
+## Flags
+
+| Flag | What |
+|------|------|
+| `--notes="text"` | Changelog entry text |
+| `--dry-run` | Show what would happen, change nothing |
+| `--no-publish` | Bump + tag only, skip npm and GitHub release |
+
+## Auth
+
+npm token is fetched from 1Password at publish time. No `.npmrc` files stored. No credentials in repos.
+
+Requires:
+- `op` CLI installed and configured
+- 1Password SA token at `~/.openclaw/secrets/op-sa-token`
+- "npm Token" item in "Agent Secrets" vault
+- `gh` CLI authenticated (for GitHub Packages and releases)
+- `clawhub` CLI authenticated (for ClawHub skill publishing)
+
+## As a Module
+
+```javascript
+import { release, detectCurrentVersion, bumpSemver } from '@wipcomputer/wip-release';
+
+const current = detectCurrentVersion('/path/to/repo');
+const next = bumpSemver(current, 'minor');
+console.log(`${current} -> ${next}`);
+
+await release({
+  repoPath: '/path/to/repo',
+  level: 'patch',
+  notes: 'fix auth',
+  dryRun: false,
+  noPublish: false,
+});
+```
+
+## Exports
+
+| Function | What |
+|----------|------|
+| `release({ repoPath, level, notes, dryRun, noPublish })` | Full pipeline |
+| `detectCurrentVersion(repoPath)` | Read version from package.json |
+| `bumpSemver(version, level)` | Bump a semver string |
+| `syncSkillVersion(repoPath, newVersion)` | Update SKILL.md frontmatter |
+| `updateChangelog(repoPath, newVersion, notes)` | Prepend to CHANGELOG.md |
+| `publishNpm(repoPath)` | Publish to npmjs.com |
+| `publishGitHubPackages(repoPath)` | Publish to npm.pkg.github.com |
+| `createGitHubRelease(repoPath, newVersion, notes, currentVersion)` | Create GitHub release with rich notes |
+| `buildReleaseNotes(repoPath, currentVersion, newVersion, notes)` | Generate detailed release notes |
+| `publishClawHub(repoPath, newVersion, notes)` | Publish skill to ClawHub |

package/tools/wip-release/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: wip-release
+description: One-command release pipeline. Bumps version, updates changelog + SKILL.md, publishes to npm + GitHub.
+license: MIT
+interface: [cli, module, mcp]
+metadata:
+  display-name: "Release Pipeline"
+  version: "1.2.4"
+  homepage: "https://github.com/wipcomputer/wip-release"
+  author: "Parker Todd Brooks"
+  category: dev-tools
+  capabilities:
+    - version-bump
+    - changelog-update
+    - skill-sync
+    - npm-publish
+    - github-release
+  requires:
+    bins: [git, npm, gh, op, clawhub]
+    secrets:
+      - path: ~/.openclaw/secrets/op-sa-token
+        description: 1Password service account token
+      - vault: Agent Secrets
+        item: npm Token
+        description: npm publish token
+  openclaw:
+    requires:
+      bins: [git, npm, gh, op]
+    install:
+      - id: node
+        kind: node
+        package: "@wipcomputer/wip-release"
+        bins: [wip-release]
+        label: "Install via npm"
+    emoji: "🚀"
+compatibility: Requires git, npm, gh, op (1Password CLI). Node.js 18+.
+---
+
+# wip-release
+
+Local release pipeline. One command bumps version, updates all docs, publishes everywhere.
+
+## When to Use This Skill
+
+**Use wip-release for:**
+- Releasing a new version of any @wipcomputer package
+- After merging a PR to main and you need to publish
+- Bumping version + changelog + SKILL.md in one step
+
+**Use --dry-run for:**
+- Previewing what a release would do before committing
+
+**Use --no-publish for:**
+- Bumping version and tagging without publishing to registries
+
+### Do NOT Use For
+
+- Pre-release / alpha versions (not yet supported)
+- Repos without a package.json
+
+## API Reference
+
+### CLI
+
+```bash
+wip-release patch --notes="fix X"           # full pipeline
+wip-release minor --dry-run                 # preview only
+wip-release major --no-publish              # bump + tag only
+wip-release patch --skip-product-check      # skip product docs gate
+```
+
+### Product Docs Gate
+
+wip-release checks that product docs (dev update, roadmap, readme-first) were updated before publishing. Only runs on repos with an `ai/` directory.
+
+- **patch**: warns if product docs are stale (non-blocking)
+- **minor/major**: blocks release until product docs are updated
+- **--skip-product-check**: bypasses the gate
+
+Checks:
+1. `ai/dev-updates/` has a file modified since the last release tag
+2. `ai/product/plans-prds/roadmap.md` was modified since last release
+3. `ai/product/readme-first-product.md` was modified since last release
+
+### Skill Publish to Website
+
+After publishing, wip-release auto-copies SKILL.md to your website as plain text. Any AI can fetch the URL and get clean install instructions.
+
+**Setup:** Add `.publish-skill.json` to your repo root:
+```json
+{ "name": "wip-my-tool", "websiteRepo": "/path/to/website-repo" }
+```
+
+**How it works:**
+1. If SKILL.md exists and a website repo is configured, copies SKILL.md to `{website}/wip.computer/install/{name}.txt`
+2. Runs `deploy.sh` in the website repo to push live
+3. Non-blocking: if deploy fails, the release still succeeds
+
+**Website repo resolution:**
+1. `.publish-skill.json` `websiteRepo` field (per-repo)
+2. `WIP_WEBSITE_REPO` env var (global fallback)
+
+**Name resolution (first match wins):**
+1. `.publish-skill.json` `name` field
+2. `package.json` name (with `@scope/` prefix stripped)
+3. Directory name (with `-private` suffix stripped)
+
+### Module
+
+```javascript
+import { release, detectCurrentVersion, bumpSemver, syncSkillVersion } from '@wipcomputer/wip-release';
+
+await release({ repoPath: '.', level: 'patch', notes: 'fix', dryRun: false, noPublish: false });
+```
+
+## Troubleshooting
+
+### "Could not fetch npm token from 1Password"
+Check that `~/.openclaw/secrets/op-sa-token` exists and `op` CLI is installed.
+
+### "Push failed"
+Branch protection may prevent direct pushes. Make sure you're on main after merging a PR.
+
+### SKILL.md not updated
+Only updates if the file has a YAML frontmatter `version:` field between `---` markers.
+
+## MCP
+
+Tools: `release`, `release_status`
+
+Add to `.mcp.json`:
+```json
+{
+  "wip-release": {
+    "command": "node",
+    "args": ["/path/to/tools/wip-release/mcp-server.mjs"]
+  }
+}
+```

package/tools/wip-release/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * wip-release/cli.mjs
+ * Release tool CLI. Bumps version, updates docs, publishes.
+ */
+
+import { release, detectCurrentVersion } from './core.mjs';
+
+const args = process.argv.slice(2);
+const level = args.find(a => ['patch', 'minor', 'major'].includes(a));
+
+function flag(name) {
+  const prefix = `--${name}=`;
+  const found = args.find(a => a.startsWith(prefix));
+  return found ? found.slice(prefix.length) : null;
+}
+
+const dryRun = args.includes('--dry-run');
+const noPublish = args.includes('--no-publish');
+const skipProductCheck = args.includes('--skip-product-check');
+const skipStaleCheck = args.includes('--skip-stale-check');
+const skipWorktreeCheck = args.includes('--skip-worktree-check');
+const notesFilePath = flag('notes-file');
+let notes = flag('notes');
+// Bug fix #121: use strict check, not truthiness. --notes="" is empty, not absent.
+let notesSource = (notes !== null && notes !== undefined && notes !== '') ? 'flag' : 'none';
+
+// Release notes priority (highest wins):
+//   1. --notes-file=path          Explicit file path (always wins)
+//   2. RELEASE-NOTES-v{ver}.md    In repo root (always wins over --notes flag)
+//   3. ai/dev-updates/YYYY-MM-DD* Today's dev update (wins over --notes flag if longer)
+//   4. --notes="text"             Flag fallback (only if nothing better exists)
+//
+// Rule: written release notes on disk ALWAYS beat a CLI one-liner.
+// The --notes flag is a fallback, not an override.
+{
+  const { readFileSync, existsSync } = await import('node:fs');
+  const { resolve, join } = await import('node:path');
+  const flagNotes = notes; // save original flag value for fallback
+
+  if (notesFilePath) {
+    // 1. Explicit --notes-file (highest priority)
+    const resolved = resolve(notesFilePath);
+    if (!existsSync(resolved)) {
+      console.error(`  ✗ Notes file not found: ${resolved}`);
+      process.exit(1);
+    }
+    notes = readFileSync(resolved, 'utf8').trim();
+    notesSource = 'file';
+  } else if (level) {
+    // 2. Auto-detect RELEASE-NOTES-v{version}.md (ALWAYS checks, even if --notes provided)
+    try {
+      const { detectCurrentVersion, bumpSemver } = await import('./core.mjs');
+      const cwd = process.cwd();
+      const currentVersion = detectCurrentVersion(cwd);
+      const newVersion = bumpSemver(currentVersion, level);
+      const dashed = newVersion.replace(/\./g, '-');
+      const autoFile = join(cwd, `RELEASE-NOTES-v${dashed}.md`);
+      if (existsSync(autoFile)) {
+        const fileContent = readFileSync(autoFile, 'utf8').trim();
+        if (flagNotes && flagNotes !== fileContent) {
+          console.log(`  ! --notes flag ignored: RELEASE-NOTES-v${dashed}.md takes priority`);
+        }
+        notes = fileContent;
+        notesSource = 'file';
+        console.log(`  ✓ Found RELEASE-NOTES-v${dashed}.md`);
+      }
+    } catch {}
+  }
+
+  // 3. Auto-detect dev update from ai/dev-updates/ (wins over --notes flag if longer)
+  if (level && (!notes || (notesSource === 'flag' && notes.length < 200))) {
+    try {
+      const { readdirSync } = await import('node:fs');
+      const devUpdatesDir = join(process.cwd(), 'ai', 'dev-updates');
+      if (existsSync(devUpdatesDir)) {
+        const today = new Date().toISOString().split('T')[0];
+        const todayFiles = readdirSync(devUpdatesDir)
+          .filter(f => f.startsWith(today) && f.endsWith('.md'))
+          .sort()
+          .reverse();
+
+        if (todayFiles.length > 0) {
+          const devUpdatePath = join(devUpdatesDir, todayFiles[0]);
+          const devUpdateContent = readFileSync(devUpdatePath, 'utf8').trim();
+          if (devUpdateContent.length > (notes || '').length) {
+            if (flagNotes) {
+              console.log(`  ! --notes flag ignored: dev update takes priority`);
+            }
+            notes = devUpdateContent;
+            notesSource = 'dev-update';
+            console.log(`  ✓ Found dev update: ai/dev-updates/${todayFiles[0]}`);
+          }
+        }
+      }
+    } catch {}
+  }
+}
+
+if (!level || args.includes('--help') || args.includes('-h')) {
+  const cwd = process.cwd();
+  let current = '';
+  try { current = ` (current: ${detectCurrentVersion(cwd)})`; } catch {}
+
+  console.log(`wip-release ... local release tool${current}
+
+Usage:
+  wip-release patch                    1.0.0 -> 1.0.1
+  wip-release minor                    1.0.0 -> 1.1.0
+  wip-release major                    1.0.0 -> 2.0.0
+
+Flags:
+  --notes="description"    Release narrative (what was built and why)
+  --notes-file=path        Read release narrative from a markdown file
+  --dry-run                Show what would happen, change nothing
+  --no-publish             Bump + tag only, skip npm/GitHub
+  --skip-product-check     Skip product docs check (dev update, roadmap, readme-first)
+  --skip-stale-check       Skip stale remote branch check
+  --skip-worktree-check    Skip worktree guard (allow release from worktree)
+
+Release notes (highest priority wins, files ALWAYS beat --notes flag):
+  1. --notes-file=path          Explicit file path (always wins)
+  2. RELEASE-NOTES-v{ver}.md    In repo root (wins over --notes)
+  3. ai/dev-updates/YYYY-MM-DD* Today's dev update (wins over --notes if longer)
+  4. --notes="text"             Fallback only (use for repos without release notes files)
+  Written notes on disk always take priority over a CLI one-liner.
+
+Skill publish to website:
+  Add .publish-skill.json to repo root: { "name": "my-tool" }
+  Set WIP_WEBSITE_REPO env var to your website repo path.
+  After release, SKILL.md is copied to {website}/wip.computer/install/{name}.txt
+  and deploy.sh is run to push to VPS.
+
+Pipeline:
+  1. Bump package.json version
+  2. Sync SKILL.md version (if exists)
+  3. Update CHANGELOG.md
+  4. Git commit + tag
+  5. Push to remote
+  6. npm publish (via 1Password)
+  7. GitHub Packages publish
+  8. GitHub release create
+  9. Publish SKILL.md to website (if configured)`);
+  process.exit(level ? 0 : 1);
+}
+
+release({
+  repoPath: process.cwd(),
+  level,
+  notes,
+  notesSource,
+  dryRun,
+  noPublish,
+  skipProductCheck,
+  skipStaleCheck,
+  skipWorktreeCheck,
+}).catch(err => {
+  console.error(`  ✗ ${err.message}`);
+  process.exit(1);
+});