feat(npm): distribute the ant CLI via npm as @withautonomi/ant

[jacderida]

Linear issue

Closes V2-1152

https://linear.app/autonominetwork/issue/V2-1152/distribute-the-ant-cli-via-npm
(mirrors #190)

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Mostly packaging and CI, which alone would be T0. Proposed as T1 because two
client-side behaviours do change: ant update refuses to self-replace on a
package-manager-owned install, and ant now falls back to a bootstrap peer list
compiled into the binary when no config file is present. Neither touches node
behaviour, the wire protocol, stored-data format, or payments. The upgrade
mechanism is narrowed rather than altered — self-replacement is unchanged for
every install that exists today, and is only declined where it would corrupt a
package manager's view of its own files.

Compatibility

• Wire: none.
• Storage: none. bootstrap_peers.toml moved from resources/ to
  ant-core/resources/ in the repo, but the release archives contain the same
  file with the same bytes at the same path inside the archive, and both
  installers copy it to the same config-directory destination as before.
• API: additive only. New: ant_core::install (InstallMethod, detect,
  classify_path), ant_core::update::DeferredUpdate,
  ant_core::config::embedded_bootstrap_peers. No existing signature changed.
  ant_core::update::perform_update gains an early error return for
  package-manager-owned installs — a new failure mode on a path that previously
  always attempted replacement.

Semver impact

• breaking
• feature
• fix

Test evidence

Gates, mirroring what ci.yml runs:

Command	Result
cargo fmt --all -- --check	clean
cargo clippy --all-targets --all-features -- -D warnings	clean
cargo test --lib --all	623 passed, 0 failed (run 4×)
cargo test -p ant-core --test unit_self_encrypt	16 passed, 2 ignored
cargo test -p ant-core --test merkle_unit	8 passed
cargo test -p ant-core --test daemon_integration --test node_add_integration -- --test-threads=1	6 + 3 passed

The devnet-dependent e2e suites (e2e_chunk, e2e_data, e2e_file, e2e_payment,
e2e_security, e2e_cost_estimate, e2e_adr0004, e2e_merkle) were not run
locally — they need a live devnet, and CI runs them in their own jobs. Nothing here
touches the upload, payment or chunk paths.

One flake seen and not reproduced: cached_single::roundtrip_save_load_delete
failed once in a full-workspace run, then passed in isolation and in four
subsequent --lib --all runs. It is a filesystem-receipt test untouched by this
change.

New unit tests: 11 in ant-core/src/install.rs covering npm global, npm local,
nested node_modules, Windows paths, install.sh/cargo/local-build locations,
and a directory whose name merely contains the substring; 2 in
ant-core/src/config.rs covering the embedded peer list parsing to usable
addresses, and an explicitly selected empty devnet manifest still erroring rather
than falling through to the embedded list.

End-to-end dry run

All six packages built by npm/build-packages.sh from staged release archives,
served from a local verdaccio registry, installed with a scratch npm_config_prefix
and XDG_CONFIG_HOME:

Acceptance criterion	Result
AC1 — npm install -g @withautonomi/ant gives a working ant --version	pass (ant 0.3.6)
AC2 — published binaries byte-identical to the release assets	pass (cmp clean, sha256 7d7847f1…)
AC3 — npm uninstall -g removes everything except the config directory	pass

Beyond the ACs:

• With postinstall blocked (npm 12's default), ant -v chunk get … logged
  No bootstrap config file; using 7 embedded bootstrap peer(s) and connected.
• With --allow-scripts, the postinstall wrote bootstrap_peers.toml to the
  config directory, and a reinstall over a user-edited file left it untouched.
• ant update --json on the npm-installed binary returned
  "install_method": "npm" with "update_command": "npm update -g @withautonomi/ant";
  ant update --force explained the refusal instead of silently doing nothing.

dist-tag behaviour on a pre-release debut

Tested after the first commit, because the next release is a beta. npm sets latest
from a package's very first publish even when --tag names something else, and
later pre-release publishes move only their own tag:

first publish of 0.3.7-beta.1 with --tag beta
  -> {'latest': '0.3.7-beta.1', 'beta': '0.3.7-beta.1'}
then publish 0.3.8-beta.1 with --tag beta
  -> {'latest': '0.3.7-beta.1', 'beta': '0.3.8-beta.1'}

A bare npm install -g @withautonomi/ant against that registry resolved to
@withautonomi/ant@0.3.7-beta.1 — i.e. a beta debut would have made the command this
PR documents serve a beta, with latest stuck there until a stable release. Publishing
a stable 0.3.7 with --tag latest afterwards reclaimed the tag cleanly
({'beta': '0.3.8-beta.1', 'latest': '0.3.7'}).

The second commit adds a guard: a pre-release is not published when the package does not
yet exist on the registry, so the npm distribution debuts on a stable release. The
dist-tag mapping and gate were replayed offline across 0.3.7, -beta.N, -rc.N,
-alpha.N and -betamax.N against both a 200 and a 404 registry response, and the
registry probe itself was checked against the real registry (@withautonomi/ant → 404,
@stripe/cli → 200).

Not verified locally: cross-platform binaries (only the host target was built;
the other four packages carried a stand-in binary), the real npm registry, OIDC
provenance, and the publish job itself. install-test.yml gains four
workflow_dispatch jobs — npm install on Linux/macOS/Windows plus an
--ignore-scripts job — to cover those against a real published version.

New dependency

None — no new Rust crates. The npm packages declare no runtime dependencies;
the launcher and postinstall use only Node's standard library. Node ≥18 becomes a
requirement for the npm install path only, and the release workflow gains
actions/setup-node.

ADR

n/a — Tier 1.

Mitigation / rollback

The publish job is the last job in the release workflow and runs only after the
GitHub release has been created, so a failure there cannot affect the release. It
also skips itself with a warning when NPM_TOKEN is absent, so merging this before
the token is configured cannot turn a release red. Backing the distribution out
means deprecating the npm packages and deleting the job; no released artifact
changes.

The two client-side behaviours are independently reversible. The ant update
deferral only triggers on a node_modules path — no existing install can reach it.
The embedded peer fallback only runs where the previous code returned
Error::NoBootstrapPeers, so it can turn a hard failure into a success but never
change the outcome of a currently-working configuration.

🤖 Generated with Claude Code

https://claude.ai/code/session_012H3LsaffUstGkhHQdZeQD3