Skip to content

NPM_PACKAGING.md

Latest commit

 

History

History
162 lines (139 loc) · 8.79 KB

NPM_PACKAGING.md

File metadata and controls

162 lines (139 loc) · 8.79 KB
Raw

npm packaging

How @gitlawb/zero is put together on npm, why it is shaped this way, and the rules the release pipeline must follow. Read this before touching package.json, bin/zero.js, scripts/postinstall.mjs, scripts/npm/build-platform-packages.mjs, or the npm-publish steps of release-artifacts.yml.

Goals

A npm install -g @gitlawb/zero must be silent and self-contained:

  • No EBADENGINE warnings — ours or from any package in the dependency tree.
  • No install scripts anywhere in the tree, so npm's allow-scripts gating, Bun's blocked-by-default lifecycle scripts, and pnpm's strict mode all install zero without prompts, trust ceremonies, or broken binaries.
  • No network fetches outside the npm registry at install time. GitHub being down or rate-limited must not break npm install.
  • Browser control (agent-browser) and terminal control (tuistory) work out of the box.

Architecture

The model is the one used by Codex, esbuild, and Biome: a tiny wrapper package plus per-platform payloads carrying the native binaries.

@gitlawb/zero                    <- wrapper: bin/zero.js + optionalDependencies
├─ @gitlawb/zero-darwin-arm64 -> npm:@gitlawb/zero@{version}-darwin-arm64
├─ @gitlawb/zero-darwin-x64   -> npm:@gitlawb/zero@{version}-darwin-x64
├─ @gitlawb/zero-linux-arm64  -> npm:@gitlawb/zero@{version}-linux-arm64
├─ @gitlawb/zero-linux-x64    -> npm:@gitlawb/zero@{version}-linux-x64
└─ @gitlawb/zero-win32-x64    -> npm:@gitlawb/zero@{version}-win32-x64
  • The platform "packages" are versions of the same @gitlawb/zero package, published at suffixed versions (0.4.0-linux-x64) and referenced through npm: aliases in optionalDependencies. One package name means one npm trusted-publisher configuration — no new publish credentials per platform. The alias suffixes use Node's process.platform/process.arch names so bin/zero.js can derive its platform package directly.
  • Each platform version sets os and cpu, so npm installs exactly one of them and skips the rest.
  • A platform payload is assembled from the platform's release archive by scripts/npm/build-platform-packages.mjs and contains the zero binary, the platform's sandbox helpers, and the vendored helpers/ tree (see below). It has no bin, no scripts, and no dependencies — it is inert on its own; the wrapper execs the binary out of it.
  • The published wrapper has no scripts and no dependencies — the assembly script strips both from the repo package.json and injects the exact-version optionalDependencies. (The repo package.json keeps agent-browser/tuistory in dependencies purely as the version pins for the vendored helpers tree; they are never installed by consumers.)
  • There is no windows-arm64 build (matches the release matrix); Windows on ARM runs the x64 build under emulation via the first-run fallback.

Binary resolution in bin/zero.js

  1. Resolve @gitlawb/zero-<platform>-<arch> and exec the zero binary from it. This wins over any previously downloaded copy — the platform version is pinned to the wrapper release.
  2. Fall back to a binary previously downloaded next to the wrapper.
  3. If neither exists (--omit=optional, package managers that skip optional dependencies), run the fallback downloader: scripts/postinstall.mjs, the exact logic that used to run as a postinstall hook (HTTPS-only, SHA-256 verified against the release's own checksum file, no zip-slip), invoked by the wrapper itself. Failures are deliberately not cached — the fetch retries on every run until a binary is in place, so a transient network error self-heals. Platforms with no release asset (anything outside the matrix above, including windows-arm64) skip the attempt entirely rather than probing the network each run.
  4. If the download is impossible too, print build-from-source guidance.

There is deliberately no scripts.postinstall in any published package.json. The downloader exists only as a first-run fallback.

Vendored helpers (helpers/)

agent-browser (Apache-2.0, vercel-labs/agent-browser) and tuistory are vendored binaries/packages inside the platform payload, not npm dependencies of the wrapper:

  • As a dependency, agent-browser's engines: { node: ">=24", pnpm: ">=11" } and postinstall script produce EBADENGINE and allow-scripts warnings for every installer. As a vendored tree it produces none, because npm never resolves it.
  • zero-release package already stages the helpers tree into every release archive (stageLocalControlHelpers runs npm ci from the repo's package.json pins + lockfile on the native builder). The assembly script reuses that staged tree, so npm installs and install.sh installs get identical helpers.
  • The Go binary resolves helpers from <binary dir>/helpers/node_modules/.bin on its own (internal/localcontrol/browser.go, adjacentHelper) — no wrapper involvement, no configuration.
  • Symlink materialization: npm pack silently drops symlinks, and npm's own .bin shims are symlinks on POSIX. The assembly script rewrites every .bin symlink into a relocatable #!/bin/sh exec shim and dereferences any other symlink, so the vendored tree survives publishing. (Verified empirically; nested node_modules under helpers/ IS packed — only the package-root node_modules is always ignored.)
  • Binary pruning: agent-browser ships one ~11 MB native binary per platform (7 total). The assembly script keeps only the payload's own platform binary (plus the musl variant on linux, which its launcher detects at runtime) — about 65 MB saved per platform package.

Publishing rules (release pipeline)

These are the invariants release-artifacts.yml must hold. Breaking the first one is user-visible immediately.

  1. Platform versions must never become latest. 0.4.0-linux-x64 is a semver prerelease of 0.4.0; publishing it without an explicit non-latest dist-tag would clobber latest and users would install a platform payload as the CLI. The workflow publishes platform versions with --tag platform and asserts latest survived before the wrapper publish, then asserts latest equals the wrapper version after it. Both lookups tolerate a failed npm view (registry lag, or no latest tag yet on a bootstrap publish) — a missing value must not abort the job between the platform and wrapper publishes, which would strand a half-published release.
  2. Platform versions publish before the wrapper. The wrapper's optionalDependencies pin exact suffixed versions; publishing the wrapper first would create a window where installs resolve aliases that 404.
  3. Exact-version pinning. The wrapper at X.Y.Z references platform versions X.Y.Z-<platform>-<arch> exactly — never ranges — so a wrapper and its binaries can never skew.
  4. All publishes go through the existing npm OIDC trusted-publishing flow and the npm-publish environment gate; no tokens. Because the platform payloads are versions of the same package, they reuse the single trusted-publisher configuration.

zero update keeps working unchanged: it detects an npm install by finding a package.json named @gitlawb/zero next to the running binary — true inside a platform payload too — and updates via npm install -g @gitlawb/zero@latest.

Runbook: bumping the vendored helpers

The vendored helper versions are pinned by the repo package.json dependencies + package-lock.json; the release build vendors exactly what the lockfile resolves. No ^range surprises ship: a release carries what its lockfile pinned at build time.

  • Routine bump: npm install agent-browser@<version> (or tuistory@…) in the repo to update pin + lockfile, verify the browser/terminal tools end-to-end, ship with the next release.
  • Security response: if a vendored helper publishes a security fix, the bump is release-worthy on its own — cut a patch release of zero carrying only the pin change.
  • Attribution: agent-browser is Apache-2.0; its LICENSE ships inside the vendored package directory (helpers/node_modules/agent-browser/), which satisfies redistribution attribution.

History / rationale

Until v0.3.x the npm package was a wrapper with a postinstall downloader and agent-browser/tuistory as regular dependencies. That produced three warnings on every install (EBADENGINE from agent-browser's node >=24 engines pin, and allow-scripts warnings for both postinstall scripts), broke silently under Bun's default script blocking, and coupled npm install to GitHub Releases availability. The platform-package model removes the warnings structurally — there is nothing left in the tree for a package manager to warn about — rather than asking users to approve or suppress them.