[JP-Ellis]

Goal

Publish @pact-foundation/pact-cli to npm from this repo on every stable release, the same way publish-pypi.yml publishes pact-python-cli. Today pact-foundation/pact-js-cli repackages these binaries in a separate release cycle, so npm trails: 18.1.2 ships crate 0.10.8 while this repo is at 0.10.9. pact-js-cli will be archived separately once a release from here is on npm.

What ships

• npm/pact-cli/: plain CommonJS wrappers for the seven existing bins (pact, pact-broker, pact-mock-server, pact-stub-server, pact-plugin, pact-verifier, pactflow).
  • No dependencies, no build step, Node ≥ 16.
  • The binary comes from an optional dependency on @pact-foundation/pact-cli-<os>-<arch>, the same layout and package names as today.
  • The wrapper spawns the binary without a shell, forwards SIGINT/SIGTERM/SIGHUP to it, and exits the way the binary exited.
• .github/scripts/build-npm.js: a dependency-free Node script. It extracts with tar and unzip, since Node has no xz or zip support. It copies the cargo-dist binaries byte for byte into six platform packages. Linux uses the static musl binary. Windows arm64 carries the x64 binary under emulation; the published pact-cli-windows-arm64@18.1.2 has no binary at all.
• .github/workflows/publish-npm.yml: a cargo-dist post-announce job (wired through Cargo.toml; release.yml regenerated with dist generate) with four stages:
  1. build: downloads and checksums the archives, then builds and packs the packages;
  2. smoke: a six-runner matrix, including windows-11-arm and macos-15-intel, that npm installs the main tarball with the host's platform tarball and runs every bin;
  3. publish: npm trusted publishing with provenance; platform packages first, main package last, already-published versions skipped;
  4. verify: installs the version from the registry and runs pact --help.
• CI: a new npm job in test.yml runs the wrapper tests on Linux, macOS and Windows, and checks that the wrapper loads on Node 16.

Decisions

• Versioning: crate X.Y.Z maps to npm (18+X).Y.Z, so v0.10.9 becomes 18.10.9. npm has no epoch and rejects four-part versions. A prerelease or build-metadata suffix would sort wrongly or drop out of ^18. The offset keeps ^18 users on the line above 18.1.2, and git-cliff makes crate minor bumps additive.

• The latest guard: npm moves latest to the most recent publish, not the highest version. The publish job reads the current latest and publishes an older version (a retry or backfill) under backfill. Any registry error other than E404 fails the job, so an outage can't pass for "not published".

• Why no postinstall download: cargo-dist's own npm installer downloads the binary at install time. That approach breaks under --ignore-scripts and in offline CI, so the binaries ship in the packages.

• Signal forwarding: the first version used spawnSync, the same as pact-js-cli. Review showed that a SIGTERM sent to the wrapper, as test harnesses, concurrently and timeout all send, left pact mock running and holding its port. The wrapper now uses async spawn and forwards signals.

• Hyphenated commands are deprecated. pact <command> is the supported form, matching the PyPI wheel, which installs only pact. The six hyphenated commands keep working, but each prints warning: pact-broker is deprecated; use 'pact broker' instead (or its equivalent) on stderr. Removing them breaks ^18, so they can go no earlier than crate 1.0.0 (npm 19.0.0).

• Why a JS shim at all: a wheel is selected per platform and drops pact straight onto PATH. npm commands come from the bin of the installed package, which can't point into an optional dependency. Bins on the platform packages only work through npm's hoisting, not under pnpm, Yarn 2+ or npx. So bin/pact.js is the minimum.

Before the first release

• On npmjs.com, set up trusted publishing on all seven packages for release.yml and publish-npm.yml, with environment npm.
• Create the npm environment in this repo.

Testing

• The wrapper tests pass locally, and the wrapper loads on Node 16.
• I ran the build script against the real v0.10.9 archives. Its output matches, file for file and mode for mode, that of the earlier Python version. The binary is byte-identical, and it stays executable after npm install. All seven bins run from the installed package.
• actionlint, shellcheck, ruff, prek and dist plan are clean.
• The publish workflow itself first runs on the next stable release, or on a manual run with a tag.