# 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.