ci(release): adopt jawcode-style npm release (workflow_dispatch + dry-run + provenance)

Replace the tag-push publish workflow with jawcode's pattern: a `workflow_dispatch`
"Release" job with version / dist-tag (latest|preview) / dry-run (default true) inputs that
verifies the input matches package.json, then `npm publish --provenance` (prepublishOnly
builds the GUI first), then a post-publish `npm view` smoke. Add scripts/release.ts
(`bun run release <version> [--publish]`) — opencodex's single-package version of jawcode's
release helper: clean-main+typecheck preflight → bump → commit → push → dispatch → watch.
release.ts is not shipped in the npm tarball; only scripts/postinstall.mjs is. Runbook
updated in devlog/65. Verified: release.ts transpiles, tsc clean, workflow YAML valid,
npm pack excludes release.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lidge-jun

.github/workflows/publish-npm.yml

@@ -0,0 +1,87 @@
+name: Release
+
+# Publish opencodex to npm — jawcode-style: triggered from the Actions tab with an explicit
+# version, dist-tag, and a dry-run-first default. Bump package.json on main BEFORE dispatching
+# (or use `bun run release <version>`, which does the bump+commit+push+dispatch for you); the
+# workflow verifies the version matches before publishing.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish — must equal package.json (e.g. 0.1.0)"
+        required: true
+        type: string
+      tag:
+        description: "npm dist-tag"
+        required: true
+        type: choice
+        options:
+          - latest
+          - preview
+        default: latest
+      dry-run:
+        description: "Dry run (build + pack, no actual publish)"
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  id-token: write # npm provenance attestation
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # opencodex is bun-native (the prepublishOnly GUI build + typecheck run under bun).
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      # node + npm perform the actual publish (with provenance); registry-url wires NODE_AUTH_TOKEN.
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Verify version matches package.json
+        run: |
+          PKG=$(node -p "require('./package.json').version")
+          echo "package.json=$PKG  input=${{ inputs.version }}"
+          test "$PKG" = "${{ inputs.version }}" || {
+            echo "::error::package.json ($PKG) != requested (${{ inputs.version }}) — bump package.json on main first";
+            exit 1;
+          }
+
+      # `npm publish` runs prepublishOnly (typecheck + build the GUI into gui/dist) first, so even a
+      # dry-run fully verifies the build. --provenance attests the tarball was built in this CI run.
+      - name: Publish (or dry-run)
+        run: |
+          if [ "${{ inputs.dry-run }}" = "true" ]; then
+            echo "::notice::DRY RUN — building + packing, not publishing"
+            npm publish --dry-run --tag "${{ inputs.tag }}" --access public --provenance
+          else
+            npm publish --tag "${{ inputs.tag }}" --access public --provenance
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Confirm the registry actually has the new version (real publishes only).
+      - name: Post-publish registry smoke
+        if: ${{ inputs.dry-run != true }}
+        run: |
+          sleep 10
+          npm view "opencodex@${{ inputs.version }}" version dist-tags

.github/workflows/release.yml

@@ -1,41 +1,38 @@
-# npm publish CI + release runbook
+# npm release CI + runbook (jawcode-style)
 
 ## Why
-`bun install -g opencodex` / `npm install -g opencodex` install from the **npm registry**, NOT from
-GitHub. Pushing to GitHub does not make those commands work — opencodex must be **published to npm**
-first. This adds a GitHub Actions workflow that publishes on a version tag.
+`bun/npm install -g opencodex` install from the **npm registry**, not GitHub — so opencodex must be
+**published to npm**. Modeled on jawcode's release flow (minus its monorepo/native-binary bits).
 
-## What shipped
-- `.github/workflows/publish-npm.yml` — on a pushed tag `vX.Y.Z` (or manual dispatch):
-  setup bun (for the `prepublishOnly` GUI build) + node (for `npm publish`), `bun install`, verify the
-  tag matches `package.json` version, then `npm publish --provenance --access public`.
-- Package was already made publish-ready (earlier `63_release-prep`):
-  `files` allowlist (src + gui/dist + scripts/postinstall.mjs + README + LICENSE), `bin` (opencodex/ocx,
-  `#!/usr/bin/env bun`), `engines.bun`, `prepublishOnly` (typecheck + build the GUI into gui/dist so the
-  published tarball always carries a fresh dashboard). `npm pack --dry-run`: 54 files / 634 KB, ships
-  gui/dist + the bin, excludes devlog/docs-site/gui-src.
+## How jawcode does it (reference)
+`jawcode/.github/workflows/release.yml` is a **`workflow_dispatch`** job with `version` + `tag`
+(latest/preview) + `dry-run` (default **true**) inputs: it verifies package.json matches the input,
+then `npm publish --tag … --access public --provenance`, then a post-publish registry smoke. A local
+`bun scripts/release.ts <version>` does preflight → bump → commit → push → dispatch → watch.
+
+## What shipped (opencodex)
+- **`.github/workflows/release.yml`** — `workflow_dispatch` with `version` / `tag` (latest|preview) /
+  `dry-run` (default true). Verifies the tag input == package.json, then `npm publish` (prepublishOnly
+  builds the GUI into gui/dist first) with `--provenance`, then `npm view` smoke on real publishes.
+  Replaces the old tag-push `publish-npm.yml`.
+- **`scripts/release.ts`** (+ `bun run release` / `release:watch`) — single-package version of
+  jawcode's helper: clean-main + typecheck preflight → `npm version --no-git-tag-version` → commit →
+  push → `gh workflow run release.yml` (dry-run unless `--publish`) → watch. Not shipped in the tarball.
+- Package already publish-ready (`files`, bin `#!/usr/bin/env bun`, `engines.bun`, `prepublishOnly`).
 
 ## One-time setup (owner)
-1. Create an npm **Automation** access token: npmjs.com → Access Tokens → Generate → *Automation*.
-2. Add it to the repo as a secret named **`NPM_TOKEN`**: GitHub → Settings → Secrets and variables →
-   Actions → New repository secret.
-3. (First publish only) the npm name `opencodex` is currently unclaimed, so the first tagged release
-   claims it under your npm account.
+1. npm **Automation** (or Granular all-packages Read+Write) token: npmjs.com → Access Tokens.
+2. Add it as the repo secret **`NPM_TOKEN`**: GitHub → Settings → Secrets and variables → Actions.
 
-## Releasing (each version)
-```bash
-# from a clean main
-npm version patch        # or minor/major — bumps package.json + creates the vX.Y.Z git tag
-git push --follow-tags   # pushes the commit AND the tag → CI publishes to npm (with provenance)
-```
-After the workflow goes green:
+## Releasing
+**Easiest (local helper):**
 ```bash
-bun install -g opencodex     # or: npm install -g opencodex
-ocx init && ocx start
+bun run release 0.1.0            # preflight → bump → commit → push → DRY-RUN dispatch → watch
+bun run release 0.1.0 --publish  # …and actually publish (after the dry-run looks good)
 ```
+**Manual (GitHub UI):** bump `version` in package.json on main, commit/push, then Actions → **Release**
+→ Run workflow → enter the version, pick the dist-tag, leave **dry-run on** first, re-run with dry-run
+off to publish.
 
-## Notes
-- opencodex is **bun-native** (the `ocx` bin is `#!/usr/bin/env bun` and the server uses `Bun.serve`),
-  so installers still need **bun** on PATH even via `npm install -g`. `engines.bun` documents this.
-- The consumer-side `postinstall` (interactive [Y/n] GitHub-star prompt) is TTY-gated → it no-ops in
-  CI / piped installs, so it never blocks an automated install.
+After a real publish: `bun install -g opencodex` / `npm install -g opencodex` work (package page:
+https://www.npmjs.com/package/opencodex). opencodex is bun-native, so installers still need **bun** on PATH.

devlog/65_npm-publish-ci/00_plan.md

@@ -24,7 +24,9 @@
     "typecheck": "bun x tsc --noEmit",
     "build:gui": "cd gui && bun install && bun run build",
     "postinstall": "node scripts/postinstall.mjs",
-    "prepublishOnly": "bun run typecheck && bun run build:gui"
+    "prepublishOnly": "bun run typecheck && bun run build:gui",
+    "release": "bun scripts/release.ts",
+    "release:watch": "bun scripts/release.ts watch"
   },
   "dependencies": {
     "zod": "^4.0.0"

package.json

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+/**
+ * Release helper (jawcode-style, single package). Not shipped in the npm tarball.
+ *
+ * Usage:
+ *   bun scripts/release.ts <version> [--tag latest|preview] [--publish]
+ *       Preflight (clean tree on main + typecheck) → bump package.json → commit → push →
+ *       dispatch the Release workflow → watch it. Dry-run by default; pass --publish to publish.
+ *   bun scripts/release.ts watch
+ *       Watch the most recent Release run.
+ *
+ * Example:  bun scripts/release.ts 0.1.0            # dry-run release of 0.1.0
+ *           bun scripts/release.ts 0.1.0 --publish  # actually publish 0.1.0
+ *
+ * Requires: gh CLI (authed) + an NPM_TOKEN repo secret for the actual publish.
+ */
+import { $ } from "bun";
+
+const args = process.argv.slice(2);
+
+async function watchLatest(): Promise<void> {
+  const id = (await $`gh run list --workflow release.yml --limit 1 --json databaseId -q '.[0].databaseId'`.text()).trim();
+  if (!id) { console.error("No Release runs found yet."); process.exit(1); }
+  console.log(`→ watching Release run ${id}`);
+  await $`gh run watch ${id} --exit-status --interval 10`;
+}
+
+if (args[0] === "watch") {
+  await watchLatest();
+  process.exit(0);
+}
+
+const version = args[0];
+if (!version || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version)) {
+  console.error("Usage: bun scripts/release.ts <version> [--tag latest|preview] [--publish]\n       bun scripts/release.ts watch");
+  process.exit(1);
+}
+const tag = args.includes("--tag") ? (args[args.indexOf("--tag") + 1] ?? "latest") : "latest";
+const dryRun = !args.includes("--publish");
+
+// 1. Preflight — must be on a clean main, and typecheck must pass.
+const branch = (await $`git rev-parse --abbrev-ref HEAD`.text()).trim();
+if (branch !== "main") { console.error(`✗ must be on main (currently ${branch}).`); process.exit(1); }
+if ((await $`git status --porcelain`.text()).trim()) { console.error("✗ working tree not clean — commit or stash first."); process.exit(1); }
+console.log("→ typecheck");
+await $`bun x tsc --noEmit`;
+
+// 2. Bump package.json (no git tag — the workflow verifies against this version).
+console.log(`→ bump package.json → ${version}`);
+await $`npm version ${version} --no-git-tag-version`;
+
+// 3. Commit + push the version bump.
+await $`git add package.json`;
+await $`git commit -m ${`release: v${version}`}`;
+console.log("→ push origin main");
+await $`git push origin main`;
+
+// 4. Dispatch the Release workflow.
+console.log(`→ dispatch Release (tag=${tag}, dry-run=${dryRun})`);
+await $`gh workflow run release.yml -f version=${version} -f tag=${tag} -f dry-run=${String(dryRun)}`;
+await Bun.sleep(4000);
+
+// 5. Watch it.
+await watchLatest();
+console.log(dryRun
+  ? "\n✓ Dry run complete. Re-run with --publish to publish for real."
+  : "\n✓ Published. Try:  bun install -g opencodex");