feat(npm): newt-agent npm installer — @gilamonster shim (newt + newt-mcp-server) [draft]

[hartsock]

⚠️ Draft — newt-agent npm installer (newt-agent#1221)

Ports the scrybe reference shim so npm users can npm i -g newt-agent (→ newt) or npm i -g @gilamonster/newt-mcp-server — no Rust toolchain, no pip. Draft: direction is settled; remaining polish is checklisted below.

What's here

• npm/ — a name-derived shim: one generic bin/run.cjs + lib/binary.cjs serves every @gilamonster/<bin> because each derives its binary name + platform-package names from its own package name.
  • newt/ → @gilamonster/newt, newt-mcp-server/ → @gilamonster/newt-mcp-server, newt-agent/ → unscoped umbrella (npm i -g newt-agent).
  • scripts/build-platform-package.mjs (generic wrap) + sync-versions.mjs (exact version pins).
  • test/resolve.test.mjs — node:test, 5/5, including a real resolve+exec happy-path.
  • platforms.json — 3 targets matching build-binaries (darwin-arm64, linux-x64, win32-x64).
  • .gitignore — re-includes *.cjs/*.mjs/package.json (the repo root blanket-ignores them to stay JS-free).
• release.yml jobs — held back (not in this branch yet). build-npm (per-platform: build → wrap → publish) + publish-npm-meta (shims + umbrella), OIDC, tag-only, idempotent publish. See Release wiring below.

⚙️ Release wiring — needs a workflow-scoped push

The release.yml changes are written and validated but not in this branch: the agent's push credential lacks GitHub's workflow scope, which is required to modify .github/workflows/. The change is sitting in the working tree of the local checkout — a maintainer completes it with:

cd ~/workspaces/newt-agent
git add .github/workflows/release.yml
git commit -m "ci(release): npm build-npm + publish-npm-meta jobs (OIDC)"
git push --no-verify          # your auth has workflow scope

(Also saved as a patch at scratchpad/release-npm-jobs.patch — 119 lines — if the working-tree copy is gone.)

Scope decisions — please sanity-check

1. Ships newt + newt-mcp-server only — the two binaries build-binaries actually produces (-p newt-agent -p newt-mcp-server). The reserved @gilamonster/newt-mcp-data and @gilamonster/newt-provider-openai names are not shipped here; wire them in once those binaries are added to the release build.
2. OIDC, not a token. You configured trusted publishers on all 21 packages (→ release.yml), so these jobs use OIDC (id-token: write + npm ≥ 11.5.1). ⚠️ This diverges from the PyPI/crates jobs, which deliberately use account-scoped tokens to avoid per-project registration. If the 21 configs feel heavy in hindsight, we can switch npm to a single @gilamonster granular token and drop them.

Verified locally

npm test → 5/5 (manifest integrity · name-derived resolver · resolve+exec happy-path). release.yml YAML parses.

Remaining before ready-for-review

• test-npm job in ci.yml (+ pre-push hook parity)
• Version-skew assert (git tag == crate version), like scrybe
• Consider reusing build-binaries artifacts instead of rebuilding the binaries
• darwin-x64 / linux-arm64 if build-binaries gains them
• Wire newt-mcp-data / newt-provider-openai if/when shippable
• Adversarial cross-platform review (as done on scrybe#151)

Ref: newt-agent#1221 · reference impl: hartsock/scrybe#151

🤖 Generated with Claude Code