feat: publish the CLI to npm as @voiceflow/cli (COR-13588)

[Bradenream]

Part of COR-13588 — shipping the vf CLI as an agent-era distribution channel.

What

Hand-written (non-generated) npm distribution layer so npx @voiceflow/cli works cold — no postinstall scripts, no compilation, ~2–4s cold start:

• npm/cli/ — wrapper package exposing vf and voiceflow bins via a zero-dependency shim that resolves the platform binary package (@voiceflow/cli-<os>-<cpu>, optionalDependencies with os/cpu fields — npm downloads only the matching one, ~5.6MB) and hands over stdio, exit codes, and signals
• npm/scripts/prepare.ts — stages all 7 packages from goreleaser's artifacts.json, stamping the release version and restoring the executable bit the Actions artifact zip round-trip drops
• npm/scripts/publish.ts — idempotent publish: platform packages first, registry-visibility gate, wrapper last; prereleases go to the next dist-tag so latest never resolves an rc
• npm/README.md — pipeline invariants + failure recovery
• CI — one job appended to the existing tag-triggered release workflow; versions stay in lockstep with git tags by construction

Static CGO-free binaries → one linux package per arch, no musl split. Base branch: #7 (needed to build locally).

Human steps before first publish

1. npm org owner creates a granular NPM_TOKEN (scope @voiceflow, read+write, may-create-packages) → repo Actions secret
2. Dry-run with a prerelease tag (publishes under next), verify on macOS/Linux/Windows
3. Real tag → @voiceflow/cli live; then configure npm trusted publishing and retire the token

Verification

• 7/7 hermetic vitest tests (test/npm-distribution.test.ts): staging layout, version stamping, exec bits, npx bin invariant, publish ordering + dist-tags, shim exec/error paths
• Full local e2e: real binary → prepare → npm pack → install into a scratch prefix → both bins execute the CLI in 27ms, exit codes propagate, unsupported-platform error teaches
• release.yaml YAML-validated; existing goreleaser job byte-identical

[Copilot]

Pull request overview

Adds a hand-written npm distribution layer so the Voiceflow CLI can be executed via npx @voiceflow/cli by publishing a thin wrapper package plus six platform-specific binary packages, and wires this into the tag-triggered release workflow.

Changes:

• Introduces npm/scripts/prepare.ts to stage the wrapper + platform binary packages from dist/artifacts.json, stamping versions and restoring executable bits.
• Introduces npm/scripts/publish.ts to publish packages idempotently with ordering/visibility gating and prerelease dist-tag routing.
• Adds a Node bin shim (npm/cli/bin/vf.js), documentation, hermetic-ish tests, and a new npm-publish job in the release workflow.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/npm-distribution.test.ts	Adds tests for staging, publish planning, and the wrapper shim behavior.
npm/scripts/prepare.ts	Stages all npm packages from goreleaser output and stamps versions/modes.
npm/scripts/publish.ts	Publishes staged packages with ordering and prerelease dist-tag logic.
npm/README.md	Documents pipeline invariants and failure recovery for npm publishing.
npm/cli/README.md	End-user docs for installing/running the npm-distributed CLI.
npm/cli/package.json	Wrapper package definition with bins + optionalDependencies for platforms.
npm/cli/bin/vf.js	Zero-dependency launcher that resolves and spawns the platform binary.
.github/workflows/release.yaml	Adds an npm-publish job after goreleaser on tag pushes.

Suppressed comments (2)

test/npm-distribution.test.ts:113

• This test depends on side effects from a previous it(...) (the out-ok staging). If tests are filtered (e.g. vitest -t 'publish.ts') or the earlier test fails, this one will fail for unrelated reasons. Stage a fresh outDir within this test (or via a beforeAll in this describe) to keep it isolated.

  it('plans platform packages before the wrapper and never invokes a real publish', async () => {
    const outDir = path.join(workDir, 'out-ok'); // staged by the first test
    const result = await execa({ reject: false })(TSX, [PUBLISH, '--version', '0.229.0', '--out', outDir, '--dry-run']);
    expect(result.exitCode, result.stderr).toBe(0);

test/npm-distribution.test.ts:15

• This hard-codes the tsx binary path to node_modules/.bin/tsx. On Windows, Yarn will typically create tsx.cmd (and tsx.ps1) instead, and spawning an explicit path without the .cmd extension can fail. Consider selecting the correct filename based on platform so the tests are runnable on Windows too.

const TSX = path.join(REPO_ROOT, 'node_modules', '.bin', 'tsx');

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[linear-code]

COR-13587

COR-13588