berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
wifi-densepose/docs/adr/ADR-265-ruview-npm-distribu...

6.9 KiB
Raw Blame History

ADR-265: RuView npm Distribution Strategy — CI Gate, Provenance, Version Single-Sourcing, Namespace

Field Value
Status Accepted — D1–D4 implemented: .github/workflows/npm-packages.yml (matrix gate: tests, version-literal grep, pack-content/size gate, tarball-install smoke test, README claim-check), .github/workflows/ruview-npm-release.yml (publish-from-CI with npm publish --provenance), version single-sourcing (all three packages read package.json), ruview bin owned by @ruvnet/ruview (@ruv/ruview-cli bin renamed ruview-cli), ci.yml NODE_VERSION 18→20. D5 (no workspace) stands as recorded
Date 2026-07-02
Deciders ruv
Codename RUVIEW-NPM-DIST
Supersedes / amends none (cross-cutting layer above ADR-263 and ADR-264; complements ADR-182 P3/P4)

Context

The monorepo now ships (or stages) three Node packages with no shared distribution engineering:

Package Dir Published Bin(s) Tests in CI
@ruvnet/ruview harness/ruview/ 0.1.0 (live) ruview none
@ruvnet/rvagent tools/ruview-mcp/ 0.1.0 (live) rvagent, ruview-mcp none
@ruv/ruview-cli tools/ruview-cli/ private ruview (collides) none

Cross-cutting facts established during the ADR-263/264 reviews:

  • Zero CI coverage. No workflow under .github/workflows/ references any of the three directories. Two of the packages are live on the registry and were published from a laptop state CI never saw. Meanwhile the Rust side has a 1,031+-test gate and a witness-bundle culture (ADR-028) — the npm surface is the only shipped artifact class with no verification gate at all.
  • ci.yml pins NODE_VERSION: '18' while all three packages declare engines.node >= 20.
  • Version triplication. Each package hardcodes its version in source at least once beyond package.json (harness SERVER_INFO, rvagent PACKAGE_VERSION, cli .version("0.0.1")).
  • Bin-name collision. Two packages claim the ruview bin.
  • No provenance. Neither published package carries npm provenance attestations, in a project whose differentiator is signed, reproducible evidence (ADR-028 witness bundles, ADR-182 P4 ed25519/SLSA design).
  • No pack-content gate. ADR-264 F1/F2 (broken require target, 33% dead map weight — MEASURED, tarball listing — and a phantom CHANGELOG.md in files) are exactly the defect class an npm pack --dry-run assertion catches in seconds.

Decision

Adopt one distribution layer for all Node packages. Per-package code fixes live in ADR-263/264; this ADR fixes the machinery around them.

D1 — One npm-packages.yml CI workflow (the gate)

Matrix over [harness/ruview, tools/ruview-mcp, tools/ruview-cli] × Node [20, 22]:

  1. npm ci where a lockfile is committed (the TS packages); the harness installs with npm install — repo policy gitignores lockfiles under harness/, and the package is dependency-free after ADR-263 O3 so there is nothing to pin.
  2. npm test (harness: node --test test/*.test.mjs — pin the glob form, the directory form fails on Node 22; TS packages: build + jest or node:test per ADR-264 O8).
  3. Pack gate: npm pack --dry-run --json asserted against a checked-in expected file list + a max unpacked-size budget per package (harness ≤ 60 kB; rvagent ≤ 130 kB post ADR-264 O2). Any new/missing/renamed shipped file is a reviewed diff, not a surprise.
  4. Tarball smoke test: install the packed tarball into a temp dir; run ruview --version, ruview doctor, rvagent --help-equivalent, and a Node import() of each declared export condition — this is the test that would have caught ADR-264 F1 (require → nonexistent dist/index.cjs).
  5. Bump ci.yml NODE_VERSION to '20' (independent of the matrix above).

D2 — Publish only from CI, with provenance

Manual npm publish from laptops stops. A tag-triggered workflow (ruview-npm-release.yml, mirroring the firmware release discipline) runs the D1 gate, then npm publish --provenance --access public under the GitHub OIDC token. Consequence: every published version is attested to a public commit + workflow run — the npm-side analogue of the ADR-028 witness bundle. The prepublishOnly script in each package runs the pack gate locally as a belt-and-braces (publishing outside CI fails loudly, not silently).

D3 — Version single-sourcing

Rule: package.json is the only place a version string lives. Runtime code reads it (createRequire(import.meta.url)('./package.json').version or a build-time define for the TS packages). CI greps for \d+\.\d+\.\d+ literals in src/ of each package and fails on match (allowlist: test fixtures). This retires ADR-263 F6 and ADR-264 F9 permanently instead of per-incident.

D4 — Namespace and bin ownership

  • @ruvnet/ruview owns the ruview bin (it is the published front door, ADR-182). @ruv/ruview-cli renames its bin or folds into rvagent (ADR-264 O9) — decided here so neither package ADR relitigates it.
  • New Node packages in this repo use the @ruvnet/ scope (the @ruv/ scope holds rvcsi legacies; do not grow it).
  • Every package README + description must pass npx ruview claim-check — enforced in the D1 gate. The guardrail package linting its sibling packages' claims is the cheapest dogfooding we have (ADR-264 F3 is the standing example of why).

D5 — Shared-code policy (bounded)

Do not introduce an npm workspace or a shared runtime package yet: three packages, two of which may merge (ADR-264 O9), do not justify workspace machinery, and the harness's zero-dep property is load-bearing. Revisit if a fourth package appears or if the http/cog/config duplication survives the ADR-264 O9 fold. Record the duplication as intentional in each file header (the CLI already does this).

Consequences

  • The npm artifacts get the same class of gate the Rust workspace has had since ADR-028: no publish without tests, no shipped file set without an asserted manifest, no version without provenance. The two defects that reached the registry (broken require condition, dead maps) become CI-impossible.
  • Cold-path costs stay near zero: the D1 matrix is 6 fast jobs (the harness suite runs in ~108 ms MEASURED; TS builds dominate at a few tens of seconds).
  • Publishing gains one constraint (must go through CI) and loses one failure mode (laptop-state publishes) — the right trade for a project whose brand is reproducible evidence.
  • D3's grep gate is blunt but cheap; if it over-fires, scope it to version-adjacent identifiers before weakening it.
  • Follow-ups tracked elsewhere: per-package code fixes (ADR-263 O1–O8, ADR-264 O1–O9); ADR-182 P4 (metaharness router + ed25519 provenance chain) remains the deeper provenance story that D2's npm attestations complement, not replace.