Set up npm release workflow for @onkernel/cua-cli

[rgarcia]

Summary

• Set up npm trusted-publishing release machinery for @onkernel/cua-cli,
  mirroring the existing release-cua-ai.yml / release-cua-agent.yml
  workflows triggered by package-specific tags.
• Made packages/cli/package.json publish-ready: added license: MIT,
  repository (with directory: packages/cli), bugs, homepage,
  publishConfig.access: public, and engines.node: >=22.19.0 to match the
  workspace root.
• Added .github/workflows/release-cua-cli.yml on tag cua-cli/v* that
  verifies the tag commit is on main, installs Node 24 + npm >= 11.5.1 for
  OIDC trusted publishing, runs npm ci, asserts the tag version matches
  packages/cli/package.json, sets up Zig 0.15.2 + caches for the ptywright
  native build (replicating the cli-unit job in ci.yml), builds the
  workspace, verifies the pinned @onkernel/cua-ai and @onkernel/cua-agent
  runtime dependency versions are published on npm, runs the cua-cli unit
  tests with PTYWRIGHT_REQUIRED=1, packs the tarball, installs it into a
  fresh temp project and runs ./node_modules/.bin/cua --help (asserting
  exit 0 and that the usage banner is present), then npm publish --access public via OIDC.
• Updated docs/npm-releases.md: added the cua-cli row to the tag list,
  trusted-publisher table, and npm trust example, and a new
  "Releasing @onkernel/cua-cli 0.1.0" section that spells out the manual
  first-publish steps (npm requires the package to exist before a trusted
  publisher can be configured) plus the post-publish trusted-publisher
  configuration and the subsequent tag-driven release flow.

Why

@onkernel/cua-cli (now at packages/cli) is the third workspace package in
the release series and previously had no release pipeline. This wires it up
following the same tag + OIDC pattern already used by @onkernel/cua-ai and
@onkernel/cua-agent.

Test plan

• npm ci clean from a fresh checkout
• npm run build --workspace @onkernel/cua-ai succeeds
• npm run build --workspace @onkernel/cua-agent succeeds
• npm run build --workspace @onkernel/cua-cli succeeds (tsc -b)
• npm test --workspace @onkernel/cua-cli passes (29 passed, 4 skipped
  due to missing ptywright native binding in this sandbox)
• npm pack --workspace @onkernel/cua-cli produces
  onkernel-cua-cli-0.1.0.tgz
• Live OIDC publish — only verifiable on the first tag push after the
  manual 0.1.0 bootstrap publish and trusted-publisher configuration
• First manual npm publish --workspace @onkernel/cua-cli from a
  maintainer machine — out of scope for this PR (see
  docs/npm-releases.md)

Open concern

The packed cua bin currently fails when invoked as Node ESM because the CLI
source uses bare relative imports (e.g. from "./cli-harness") and
tsc -b does not rewrite them to ./cli-harness.js. Vitest masks this
during tests, and the workflow's smoke step (./node_modules/.bin/cua --help) will surface it the moment the workflow runs end-to-end. Fixing it
(switch the cli build to tsdown like cua-ai/cua-agent, or add .js
extensions to the source imports) is intentionally out of scope for this PR
since the rule was to set up release machinery without modifying CLI source
beyond package.json; the smoke test is the safety net before any tarball
goes to npm.

---

Note

Low Risk
Changes are CI, package metadata, and documentation only; no runtime application logic. Publish gates (tests, dependency checks, bin smoke test) reduce release risk.

Overview
Adds tag-driven npm releases for @onkernel/cua-cli via a new workflow on cua-cli/v*, aligned with the existing cua-ai / cua-agent release pattern.

release-cua-cli.yml checks the tag is on main and matches packages/cli/package.json, uses OIDC trusted publishing (Node 24, npm ≥ 11.5.1), builds workspace packages plus the ptywright native binding (Zig 0.15.2 + cache), confirms pinned @onkernel/cua-ai / @onkernel/cua-agent versions exist on npm, runs CLI tests with PTYWRIGHT_REQUIRED=1, pack + install smoke test (cua --help), then publishes publicly.

packages/cli/package.json is made publish-ready (MIT license, repo/bugs/homepage, publishConfig.access: public, engines.node).

docs/npm-releases.md documents the cua-cli tag, trusted publisher row/npm trust command, and a manual first publish path before trusted publishing can be configured, then tag-based releases from 0.1.1+.

^{Reviewed by Cursor Bugbot for commit 62a47ed. Bugbot is set up for automated code reviews on this repo. Configure here.}

[rgarcia]

Reviewed against release-cua-ai.yml / release-cua-agent.yml, ci.yml's cli-unit job, and the existing docs/npm-releases.md conventions. Verified locally from a clean checkout of this branch: npm ci, builds for cua-ai/cua-agent/cua-cli, cua-cli unit tests (29 passed, 4 skipped without the native binding), npm pack, actionlint on the new workflow (clean), and npm view for every pinned runtime dep (@onkernel/cua-ai@0.3.0, @onkernel/cua-agent@0.3.3, @onkernel/sdk@0.49.0, @earendil-works/*@0.79.1 — all published).

Workflow fidelity checks out: correct tag prefix and version-check path, tag-on-main guard, id-token: write, npm >= 11.5.1 for trusted publishing, zig/ptywright cache + install steps verbatim from ci.yml, dep-publish verification fails correctly on missing versions (E404 → xargs exit 123 → step failure), the smoke test invokes the installed bin rather than importing the module (required, since dist/cli.js runs main() on import), and publish can only fire on cua-cli/v* tags whose commit is on main. package.json metadata matches the packages/ai / packages/agent conventions; ptywright is dev-only and nothing under packages/cli/src imports it; the tarball contains dist + README.md only, with both smoke-test grep targets present in the help text.

Findings

1. (major) The manual first-publish runbook publishes a broken bin as of this branch. Reproduced: pack the tarball, install into a fresh project, ./node_modules/.bin/cua --help → ERR_MODULE_NOT_FOUND for dist/cli-harness (tsc under moduleResolution: Bundler emits extensionless relative specifiers that Node ESM rejects). The release workflow's smoke test guards tag-driven releases, but the "Releasing @onkernel/cua-cli 0.1.0" section has no equivalent check — a maintainer following it verbatim today ships a broken 0.1.0, and published npm versions are immutable. Fix within this PR's scope: add a pre-publish smoke step to the doc between steps 3 and 4 (npm pack --workspace @onkernel/cua-cli --pack-destination "$(mktemp -d)", npm install the tarball into a fresh temp project, run ./node_modules/.bin/cua --help), and state that the publish must not proceed until it passes. The underlying specifier fix (bundler build like tsdown, or explicit .js extensions in source) is rightly out of scope here, but the runbook must not green-light a publish before that lands. Relatedly, the PR body's "the smoke test is the safety net before any tarball goes to npm" only holds for the tag-driven path — the manual path this PR documents has no safety net.

2. (minor) package-lock.json wasn't regenerated for the packages/cli metadata change. The lockfile's packages/cli entry lacks the new license and engines fields (the packages/ai and packages/agent entries carry "license": "MIT"). npm ci still passes, but the next npm install anyone runs will dirty the lockfile with this PR's leftovers. Apply just the packages/cli entry update — note a full npm install --package-lock-only also picks up ~411 lines of pre-existing drift already present on main, which should stay out of this PR.

3. (nit) The doc's dependency note reads as exhaustive but isn't. It lists @onkernel/cua-ai, @onkernel/cua-agent, @onkernel/sdk as the runtime deps that must be on npm, but @earendil-works/pi-coding-agent and @earendil-works/pi-tui are also exact-pinned runtime deps (both published at 0.79.1). Either drop the parenthetical or make the list complete.

Scope is otherwise exactly right — three files, no source changes, and the judgment calls (30-minute timeout for the serialized native build, dual dep verification, verbatim ci.yml toolchain steps, specific usage-line greps) are all sound.

[firetiger-agent]

Created a monitoring plan for this PR.

What this PR does: Wires up @onkernel/cua-cli for automated npm releases via GitHub Actions OIDC trusted publishing, mirroring the existing cua-ai / cua-agent release workflows. No production service code changed.

Intended effect: No production telemetry signal exists for this CI/tooling change. The only observable output is a successful Release CUA CLI Actions run when a cua-cli/v* tag is pushed, followed by @onkernel/cua-cli@<version> appearing on the npm registry.

Risks:

• Bare-import ESM bug breaks smoke test — the PR author flags that tsc -b doesn't rewrite relative imports to .js, so ./node_modules/.bin/cua --help will likely fail with ERR_MODULE_NOT_FOUND; alert if the "CLI bin smoke test" step fails on the first tag push (no npm publish occurs — safe-fail, no user impact)
• Trusted publisher not yet configured — OIDC publish requires the manual 0.1.0 bootstrap publish and npm trusted-publisher setup first; alert if the "Publish to npm" step exits with E401/EOTP
• Runtime dep version not on npm — workflow asserts @onkernel/cua-ai and @onkernel/cua-agent at pinned versions exist before publishing; alert if "Verify runtime dependencies are published" step fails
• Zig/ptywright native build failure — Zig 0.15.2 cache miss or CDN unavailability can block the build; alert if "Install Zig" or "Build ptywright" step fails

Status updates will be posted automatically on this PR as monitoring progresses.

View monitor