Portable Nexus Tooling

[sameera]

Epic: Portable Nexus Tooling

Description

In a multi-repo workspace the hub is a docs repo: it holds the concept store and drains the
committed queue with /nxs.distill. The hub is not a code project — it carries no node package,
no node_modules, no pnpm setup. But two of distillation's deterministic steps are today wired to
that missing toolchain: the concept validator and the atlas generator are TypeScript scripts run
through tsx, which only exists after a full workspace install. Run in a bare hub, those steps
cannot start, and distillation stalls at the gate that is supposed to block a failing concept page
from shipping.

This epic makes that deterministic tooling portable: it runs in the hub on a plain Node.js runtime,
with no workspace install and no tsx. The concept store the hub owns gets validated and its atlas
regenerated exactly as they are in a single code repo today — same findings, same output — so the
hub is a first-class place to distill from. Nothing about single-repo distillation changes.

The distributable this produces is also the foundation two later multi-repo epics build on
(workspace-setup-cli shares it; distill-multi-repo depends on it), so the packaging vehicle is
designed to grow — to carry additional deterministic tools later, including ones with real npm
dependencies — even though this epic only ships the validator and the atlas generator through it.

Success Metrics

• Distilling in a hub repo that carries no node project completes its deterministic steps — atlas
  regeneration, atlas sync-check, and concept validation — with zero manual toolchain setup (no
  pnpm/npm install, no tsx).
• Across the concept corpus, the packaged tooling and the in-repo scripts produce identical
  validator findings and byte-identical atlas output — zero diffs — and any divergence fails an
  automated check.
• Single-repo distillation is unchanged: the existing invocation still runs the deterministic steps
  and passes, with no regression.

Personas

Per docs/product/context.md. The primary engineer persona runs the full pipeline — including
/nxs.distill — and in a multi-repo product runs it from the hub docs repo.

Assumptions

• The hub machine has a Node.js runtime available — the engineer already runs Prime and the Nexus
  toolchain on it. "No local node tooling of its own" means the hub repo carries no node project
  (no package.json, node_modules, pnpm, or tsx), not that the machine lacks a node binary.
• The hub is a git repository (it holds the committed queue and concept store), so the git CLI the
  validator's --base append-only check shells out to is present.
• The in-repo scripts remain the authoritative source. Portability tracks that source rather than
  forking a second implementation, which is what makes the parity guarantee meaningful.
• The distributable is the shared vehicle later multi-repo tooling joins, so its packaging mechanism
  must be able to carry bundled npm dependencies even though the validator and atlas generator need
  none today.

Out of Scope

• The workspace resolver and its status read-out (@nexus/workspace, the nxs-workspace-status
  skill) and its yaml npm dependency — the heavy portability case, claimed by workspace-setup-cli
  and consumed by distill-multi-repo. This epic only ensures the distributable can host it later;
  packaging it is deferred to those epics.
• The GitHub-issue scripts (nxs_gh_create_epic.py, create_gh_issues.py) — already node-free
  (python stdlib) and run in code repos, not the hub. No portability gap.
• The absolute-doc-path helper (get_abs_doc_path.ts) — runs in member code repos, which have the
  node toolchain; it does not run in the bare hub.
• The reciprocity fan-out and code-anchor refresh — these are model-driven prose steps in
  /nxs.distill, not scripts, so there is nothing to package.
• Reimplementing the tooling in another language, and publishing to a public package registry —
  neither is required by the runtime contract; both are HLD's call if chosen at all.

Open Questions

[sameera]

Close Record

Epic closed. Durable record below — the queue close-record.md drains post-merge.

Key Decisions

• Vendored tools directory is .nexus/tools: a sibling of the other .nexus/* dirs, exported as portableToolsDir (PORTABLE_TOOLS_RELATIVE_PATH in libs/workspace/src/resolve.ts). Function-first naming matching the sibling dirs. Refuted .nexus/vendor — names how the artifact arrived rather than what it is.
• Vendor helper takes --tools-dir <full path> and does build + pin + copy in one command: builds each entry in-process, writes the fingerprint pin, copies each .mjs from the same bytes it hashed. Refuted importing PORTABLE_TOOLS_RELATIVE_PATH + taking --hub — blocked by the enforceBuildableLibDependency lint rule (a buildable lib cannot import the non-buildable @nexus/workspace); the full-path arg + a doc-reference satisfies Invariant 13 without the dependency.
• buildBundle pins esbuild absWorkingDir to the entry's own dir so bundle bytes/sha256 are cwd-independent — required for a reproducible fingerprint (nx test at project root vs a repo-root vendor step must hash identically). Refuted an nx vendor target locked to a shared cwd — leaves latent cwd-coupling.
• Fingerprint pin is bundle-fingerprint.json, <entry>.mjs → sha256 hex — reads as "these committed artifacts have these hashes", diff-legible, one object the spec compares in one read. Refuted per-file .sha256 sidecars.
• Corpus at libs/portable-tools/corpus/, subdivided by concern (clean/, findings/, atlas/, base/+head/) so malformed pages don't pollute the atlas graph or the --base pairs, and the cached nx test target invalidates on corpus change. Refuted one flat dir.
• Parity spec runs the source via tsx and the fresh bundle via plain node (both subprocesses over the corpus), comparator in src/parity.ts — compares the two real execution paths (node/.mjs = hub; tsx/source = single-repo), and the self-test drives the same comparator that guards real drift. Refuted an in-process runCli call + spec-local comparator.
• Hub install/placement guide is its own file (hub-tooling-install.md, linked from the feature README) — the feature README keeps its minimal epics-index role. Refuted a README section.

Deviation Rationale

• Authoritative source relocated utils/ → libs/portable-tools/src/ (Invariant 1 pinned utils/): the decision record's own "promote into a buildable library" decision entailed the move — a buildable lib cannot live in utils/ — so the invariant's wording lagged its own decision. pnpm nexus:* was repointed, preserving the single-repo executed authority. Side-effect: 4 code anchors still cite old utils/ paths (derived/self-healing; the next /nxs.distill R1 refresh rebuilds them).
• /nxs.distill selects the invocation with an inline test -f .nexus/config/{workspace,hub}.yml + hard-coded .nexus/tools/ path, not by calling resolveWorkspace()/portableToolsDir (letter of Invariants 7 & 13): distill is a markdown/bash command and cannot import the TypeScript resolver. It keys off the same authoritative committed artifacts and forbids any new heuristic, so the role rule and path hold in spirit; the prose duplication is inherent to distill being a command, not code, and won't auto-follow a future resolver change (a constraint distill-multi-repo inherits).

Pointers (durable)

• Deferred scope → docs/features/multi-repo-workspaces/backlog.md (none this epic)
• Process lesson → docs/delivery/lessons/2026-07-14-portable-nexus-tooling.md