diff --git a/README.md b/README.md index 2eb691e..1b0a5e4 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ curl -fsSL https://github.com/omerakben/code-oz/releases/download/v0.21.2-alpha. | sh -s -- --version v0.21.2-alpha.0 # npm (scoped under the TUEL AI publisher; binary still runs as `code-oz`) -npm install -g @tuel/code-oz +npm install -g @tuel/code-oz@0.21.2-alpha.0 # Homebrew brew tap omerakben/code-oz @@ -48,7 +48,7 @@ brew install omerakben/code-oz/code-oz Platform support: macOS arm64, macOS x64, Linux x64, Linux arm64. Windows and Scoop are deferred to a future distribution milestone. -If `npm install -g @tuel/code-oz` fails with a 404 or authentication error, your `~/.npmrc` is likely overriding the `@tuel` scope — see [`docs/TRUST.md` § Install gotchas](docs/TRUST.md#install-gotchas-npm-scope-routing-for-tuelcode-oz) for the fix. +If `npm install -g @tuel/code-oz@0.21.2-alpha.0` fails with a 404 or authentication error, your `~/.npmrc` is likely overriding the `@tuel` scope — see [`docs/TRUST.md` § Install gotchas](docs/TRUST.md#install-gotchas-npm-scope-routing-for-tuelcode-oz) for the fix. ## Use it inside Claude Code (plugin) @@ -59,7 +59,7 @@ code-oz ships two Claude Code plugins through a marketplace declared at this rep /plugin install code-oz@code-oz-marketplace ``` -The `code-oz` plugin is a thin wrapper. It adds `/code-oz-run`, `/code-oz-init`, `/code-oz-doctor`, and `/code-oz-resume`, and each command discovers the `code-oz` engine on your `PATH`, falling back to `npx @tuel/code-oz` when the binary is absent. Install the engine from the channels above for the fastest path. The plugin never writes gates, events, or reviews — the engine binary is the only writer, so the gate guarantees hold whether you drive code-oz from the CLI or through the plugin. +The `code-oz` plugin is a thin wrapper. It adds `/code-oz-run`, `/code-oz-init`, `/code-oz-doctor`, and `/code-oz-resume`, and each command discovers the `code-oz` engine on your `PATH`, falling back to the plugin-pinned `npx @tuel/code-oz@0.21.2-alpha.0` when the binary is absent. Install the engine from the channels above for the fastest path. The plugin never writes gates, events, or reviews — the engine binary is the only writer, so the gate guarantees hold whether you drive code-oz from the CLI or through the plugin. A second plugin, `code-oz-discipline`, is optional. It installs advisory-only skills (brainstorming, source-check, RED-first) that are guidance, not enforcement: diff --git a/docs/PROVIDER_SETUP.md b/docs/PROVIDER_SETUP.md index 8fa1c09..b216117 100644 --- a/docs/PROVIDER_SETUP.md +++ b/docs/PROVIDER_SETUP.md @@ -13,7 +13,7 @@ ## Recommended first run ```sh -npm install -g @tuel/code-oz +npm install -g @tuel/code-oz@0.21.2-alpha.0 mkdir /tmp/code-oz-first-run && cd /tmp/code-oz-first-run code-oz init code-oz run --provider fake --request "Create a tiny hello-world CLI" diff --git a/docs/RELEASE_READINESS.md b/docs/RELEASE_READINESS.md index 47595a9..195640d 100644 --- a/docs/RELEASE_READINESS.md +++ b/docs/RELEASE_READINESS.md @@ -1,6 +1,6 @@ # Release readiness -Current status as of 2026-06-14: `v0.21.2-alpha.0` is published on GitHub release assets and Homebrew. npm `@tuel/code-oz@0.21.2-alpha.0` is package-ready but still pending publish authorization; the repo-side path is `.github/workflows/npm-publish.yml`, which uses npm trusted publishing with GitHub Actions OIDC. +Current status as of 2026-06-14: `v0.21.2-alpha.0` is published on GitHub release assets, Homebrew, and npm. npm `@tuel/code-oz@0.21.2-alpha.0` is available under the `alpha` dist-tag and by exact version; the unqualified `latest` tag still points at `0.21.1-alpha.0` until it is promoted with npm 2FA. This page separates what is publishable today from what is manual, experimental, or future work. @@ -9,7 +9,7 @@ This page separates what is publishable today from what is manual, experimental, | Surface | Package or path | Status | Notes | |---|---|---|---| | CLI binary | `src/cli.ts` compiled by `bun build --compile` | Publishable for macOS/Linux | GitHub release workflow builds per-arch tarballs and `checksums.txt`. Windows is not built. | -| npm launcher | `@tuel/code-oz` | Publish-ready, auth pending | `package.json.files` includes `npm-wrapper/`, `README.md`, and `LICENSE`. The wrapper downloads the matching GitHub release binary on first run. | +| npm launcher | `@tuel/code-oz@0.21.2-alpha.0` | Published under `alpha` | `package.json.files` includes `npm-wrapper/`, `README.md`, and `LICENSE`. The wrapper downloads the matching GitHub release binary on first run. | | Homebrew formula | `docs/homebrew/code-oz.rb.template` | Published for `0.21.2-alpha.0` | Render from release checksums, then commit to `omerakben/homebrew-code-oz`. | | Claude Code plugin marketplace | `.claude-plugin/marketplace.json` | Repo-root marketplace metadata present | Contains `code-oz` engine wrapper plugin and advisory `code-oz-discipline` plugin. | | Agent skill bundle | `agent-skills/code-oz/` | Text-only integration surface | No executable. It teaches external agents how to drive the CLI without owning gates. | @@ -44,7 +44,29 @@ Do not publish npm before the GitHub release assets for the exact version exist, `scripts/release/fresh-clone-smoke.sh` clones the current branch from git, so it validates committed `HEAD`, not uncommitted working-tree edits. Run it after the release-readiness patch is committed. -## npm publish authorization +## npm publish and dist-tags + +`0.21.2-alpha.0` is published. Verify: + +```sh +npm view @tuel/code-oz@0.21.2-alpha.0 version +npm view @tuel/code-oz dist-tags --json +npx -y @tuel/code-oz@0.21.2-alpha.0 --version +``` + +Current npm install command for this exact release: + +```sh +npm install -g @tuel/code-oz@0.21.2-alpha.0 +``` + +The `latest` dist-tag still points at `0.21.1-alpha.0`. To promote this release to unqualified installs, run with npm 2FA: + +```sh +npm dist-tag add @tuel/code-oz@0.21.2-alpha.0 latest --otp= +``` + +## npm publish authorization for future releases Preferred path: use npm trusted publishing for `.github/workflows/npm-publish.yml`. @@ -138,4 +160,4 @@ Measured locally on 2026-06-14: - `code-oz-gui`: `bun install --frozen-lockfile`, `bun run typecheck`, `bun run lint`, `bun test tests/unit`, and `bun run build` pass. - Dogfood flows: first-run fake provider, `bun run demo:todo-cli`, `bun run demo:failure-gates`, `doctor providers`, `doctor tools`, `doctor git`, and `bench agent-gate --fixture todo-cli-real-tests --provider fake` pass. -These are enough to call the docs/package/plugin/GUI release-prep patch ready for review. The public release is live through GitHub release assets, curl install, and Homebrew. npm still needs one authorization step through trusted publishing or an authenticated local publish. +These are enough to call the docs/package/plugin/GUI release-prep patch ready for review. The public release is live through GitHub release assets, curl install, Homebrew, and npm exact-version or `alpha` install. Unqualified npm `latest` remains one optional dist-tag promotion step. diff --git a/docs/TRUST.md b/docs/TRUST.md index a78cf40..f6b97a6 100644 --- a/docs/TRUST.md +++ b/docs/TRUST.md @@ -90,7 +90,7 @@ All three land at the `v0.x stable` milestone. Until then, treat the alpha insta ### Install gotchas: npm scope routing for `@tuel/code-oz` -`@tuel/code-oz` is published on public npm under the `@tuel` scope. If your user-level `~/.npmrc` registers a custom registry for the `@tuel` scope (for example, a private registry from a different `@tuel`-scoped package at a previous employer), `npm install -g @tuel/code-oz` routes to that registry instead of public npm. The install fails with a 404 or an authentication error, not with a useful "scope is overridden" message. +`@tuel/code-oz` is published on public npm under the `@tuel` scope. If your user-level `~/.npmrc` registers a custom registry for the `@tuel` scope (for example, a private registry from a different `@tuel`-scoped package at a previous employer), `npm install -g @tuel/code-oz@0.21.2-alpha.0` routes to that registry instead of public npm. The install fails with a 404 or an authentication error, not with a useful "scope is overridden" message. Check your scope routing the same way npm resolves it for a global install: @@ -105,7 +105,7 @@ If the output is `undefined` (the npm CLI's literal string for an unconfigured k 1. Per-command override (preferred, leaves your config untouched): ```sh - npm install -g @tuel/code-oz --@tuel:registry=https://registry.npmjs.org/ + npm install -g @tuel/code-oz@0.21.2-alpha.0 --@tuel:registry=https://registry.npmjs.org/ ``` Use the `--@tuel:registry=` form, **not** `--registry=`. The plain `--registry=` flag sets npm's default registry, but a scope-specific `@tuel:registry` mapping in your `~/.npmrc` has higher precedence and wins; the `--@scope:registry=` form sets the scope-specific registry on the command line and overrides any `.npmrc` mapping. `npm install -g` does not consult a project-local `.npmrc`, so checking out this repo's `.npmrc` does not help — the per-command flag is the reliable path. diff --git a/docs/handoffs/2026-06-14-release-readiness-audit.md b/docs/handoffs/2026-06-14-release-readiness-audit.md index 44296d8..df31bd5 100644 --- a/docs/handoffs/2026-06-14-release-readiness-audit.md +++ b/docs/handoffs/2026-06-14-release-readiness-audit.md @@ -1,11 +1,11 @@ # 2026-06-14 release-readiness audit -This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the shipped `v0.21.1-alpha.0` line. +This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the shipped `v0.21.1-alpha.0` line. It was later updated after the actual `v0.21.2-alpha.0` publication completed. ## Current state -- Latest published release remains `v0.21.1-alpha.0`; this branch prepares `v0.21.2-alpha.0`. -- npm currently publishes `@tuel/code-oz@0.21.1-alpha.0`; this branch bumps the package and plugin marketplace metadata to `0.21.2-alpha.0`. +- GitHub release assets, curl install, Homebrew, and npm now publish `v0.21.2-alpha.0`. +- npm publishes `@tuel/code-oz@0.21.2-alpha.0` under the `alpha` dist-tag and exact version. The `latest` dist-tag still points at `0.21.1-alpha.0` until a separate npm 2FA dist-tag promotion. - Recent post-tag commits fix Claude Code plugin marketplace installation and no-argument command handling. - The root npm package is a launcher package, not a binary bundle. - `code-oz-gui` is private and local-only; it is not a standalone packaged app. @@ -36,6 +36,6 @@ This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the ## Still not proven - Live brownfield AUDIT dogfood still requires local provider credentials. -- npm/Homebrew publishing still requires a new release tag and published GitHub assets for the exact version. +- Unqualified npm installs still resolve through the `latest` dist-tag until `npm dist-tag add @tuel/code-oz@0.21.2-alpha.0 latest --otp=` runs. - The isolated Claude Code marketplace install passed; a real user-profile install can still be repeated manually before announcement if desired. - GUI standalone packaging is not designed or implemented. diff --git a/plugins/code-oz/scripts/resolve-code-oz.sh b/plugins/code-oz/scripts/resolve-code-oz.sh index f90caea..ecc636c 100755 --- a/plugins/code-oz/scripts/resolve-code-oz.sh +++ b/plugins/code-oz/scripts/resolve-code-oz.sh @@ -129,7 +129,7 @@ fi # 4. Neither code-oz nor npx/npm available — hard-stop. # --------------------------------------------------------------------------- printf 'code-oz is not installed. Install:\n' >&2 -printf ' npm i -g @tuel/code-oz\n' >&2 +printf ' npm i -g @tuel/code-oz@%s\n' "${PINNED_VERSION}" >&2 printf ' OR\n' >&2 printf ' brew install omerakben/code-oz/code-oz\n' >&2 exit 1 diff --git a/tests/plugins/bootstrap-resolver.test.ts b/tests/plugins/bootstrap-resolver.test.ts index 8c052f3..9ee8b1a 100644 --- a/tests/plugins/bootstrap-resolver.test.ts +++ b/tests/plugins/bootstrap-resolver.test.ts @@ -260,6 +260,8 @@ describe('resolve-code-oz.sh — hard-stop (no code-oz, no npm/npx)', () => { expect(result.stdout + result.stderr).toMatch(/npm/) // Must mention the package name expect(result.stdout + result.stderr).toMatch(/@tuel\/code-oz/) + // Must pin the plugin version instead of relying on npm's moving latest tag. + expect(result.stdout + result.stderr).toContain('@tuel/code-oz@0.21.2-alpha.0') // Must mention brew as alternative, with the correct tap form. expect(result.stdout + result.stderr).toMatch(/brew/) expect(result.stdout + result.stderr).toContain('omerakben/code-oz/code-oz')