feat(bindings): publish the Bundle Pin scripts as the npm package zingolib-bundle-pin

[zancas]

zingolib#2930 rules that the scripts a consumer runs to hold its Bundle Pin and fetch the Prebuilt Bundles are defined in one place. This pull request adds that place. Nothing is deleted.

What changes

bindings/pin is the npm package zingolib-bundle-pin. It carries the modules kitchen-sync proved in kitchen-sync#1 and kitchen-sync#2 under lib/. Two commands under bin/ replace the entry scripts: pin-binding-layer <commit> moves the pin, and fetch-binding-layer --platform <platform> prints the path of the pinned bundle. Both take the consumer's root from the working directory, with --root and --pin overrides, because a file under node_modules cannot find that root by its own path.

The modules differ from the kitchen-sync copies in four ways. The registry obtains one token per repository and passes it to the manifest and blob requests. parsePin returns a malformed-pin outcome for text that is not JSON. The android bundle's directory holds a marker file that names the bundle's file, as the iOS placement's marker names its digest, so a held bundle is matched by name. The disk helpers for an absent file and for the atomic replacement of a directory live once, in lib/disk.mjs.

The package depends on nothing. Its 26 tests run on the test runner that Node ships, so zingolib gains no Node dependency and no lock file.

bundle-pin.yaml is a new workflow with two jobs. The check job runs the tests, lists the files npm pack would publish, and fails a pull request that changes the package without raising its version. The publish job runs on a push to dev and publishes the package when npm lacks the version package.json names. The published content is therefore always a merged commit, and the provenance names that commit. The publish uses npm trusted publishing, so only that job holds id-token: write, and no npm token is stored. binding-layer-publish.yaml is unchanged.

Set up by hand, once

The npm scope zingolabs is held by an account that has published nothing, so the package is unscoped and needs no organization.

1. Publish version 0.1.0 by hand from bindings/pin with npm publish --access public. npm configures a trusted publisher on a package that exists, so the first version cannot come from the workflow.
2. On npmjs.com, in the package's settings, add a trusted publisher that names this repository and the workflow file bundle-pin.yaml. The workflow publishes every later version.
3. Add the check Bundle Pin package to the required checks of dev.

Open

AGENTS.md's scripting rule names Rust in the workbench crate for committed tooling. The consumers of this package hold no Rust, so the package is Node. The rule needs an exception for bindings/pin, which this pull request does not write.

bindings/published.toml could record the package version beside each entry's digests. That is deferred.

Follow-ups

After the first publish, kitchen-sync installs the package and deletes its scripts/. Step 4 of zingolib#2930 installs it in zingo-mobile.

🤖 Generated with Claude Code

[juanky201271]

Tests pass 25/25 on Node 22, npm pack lists only bin, lib and package.json, the annotation keys and repository names match binding_publish.rs, and the lib diff against kitchen-sync is exactly what the last commit describes.

• The PR body is stale on the setup: step 2 names binding-layer-publish.yaml as the trusted publisher workflow, but the publish now lives in bundle-pin.yaml. Whoever follows the body configures the wrong workflow and every publish fails. Same for "publishes the package after the bundles" and "unchanged".
• Duplication: the ENOENT-to-fallback catch is written four times (readPin, held, text, exists), the atomic replace (rm partial, mkdir, write, rm home, rename) twice in fetchBundle and placeSwiftPackage, and the default pin path in both bins. The gate only scans Rust, so CI will not catch it.
• held() treats any directory with one visible file as the bundle, whatever its name, while two stray files get replaced. Low risk since downloads are atomic, but inconsistent.

[zancas]

Commits d5a8b08 and 0fd6850 answer the ten findings of the recall review and the three points above.

1. Publish source. The npm publish leaves the /publish job. It is now the publish job of bundle-pin.yaml, which runs on a push to dev. The published content is always a merged commit, and the provenance names that commit.
2. No retry after a failed publish. The publish no longer shares a job with binding-publish. A failed publish leaves npm without the version, and the next push to dev publishes it.
3. held and a stray dotfile. held no longer counts entries. See the marker below.
4. parsePin and invalid JSON. parsePin returns malformedPin with the field JSON for text that does not parse, and with the field commit for null.
5. yarn pin in the messages. Every message names pin-binding-layer.
6. Version lockout. The publish from dev removes the race. A pull request can no longer publish its own interim version.
7. Header comments. The seven // headers are gone from lib and bin.
8. id-token: write at the workflow level. Only the publish job holds the grant. binding-layer-publish.yaml is unchanged from dev.
9. --platform omitted. pinnedBundle returns unnamedPlatform before it reads the pin. The message names both platforms.
10. Two tokens per fetch. access runs once per repository, and resolveBundle and download take the grant. resolveTag is the one-shot that pin-binding-layer uses. The publish job installs npm 12.2.0 rather than npm@latest.

On the three points above:

• The PR body is corrected. It names bundle-pin.yaml, the two jobs, and the four differences from the kitchen-sync copies.
• The duplication is folded. lib/disk.mjs holds text and exists, which share one ENOENT fallback, and replaceDirectory, which both fetchBundle and placeSwiftPackage call. pinPath gives both bins the default pin path.
• held matches by name. The android bundle's directory holds a marker file, bundle, that names the bundle's file. The marker is written inside the partial directory after the download verifies, so its presence proves a complete bundle. The directory's own name is the digest, so the marker names the file rather than repeating the digest. A directory written before this commit has no marker and is downloaded once more.

The suite is 26 tests. A live pin-binding-layer and fetch-binding-layer of ba7336710 for android ran against ghcr.io, and a second fetch came from disk through the marker.

[juanky201271]

goooood!