Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

This producer command builds the declared module closure and packs a disposable consumer tree. The tarball has its own README, the included adoption guides and a private manifest with the same exports and environment requirement. The repository README and development manifest stay in place. No registry publication or live migration is authorised.

Use the repository's existing pinned development dependencies and Node.js 26.8.1 or later. From the source root, choose a fresh output directory:

npm run pack:modules -- --pack-destination ../factory-packages/review-1

For machine-readable npm pack metadata:

npm --silent run pack:modules -- --json --pack-destination ../factory-packages/review-2

The packer uses the compiler function in scripts/build-modules.ts to compile directly into a private temporary directory, copies only the manifest's declared guide/type files there, supplies package/README.md and replaces its source-reference token with the current Git commit. It invokes npm's supported directory pack operation there. Staging rejects symbolic links and non-regular files. It cleans its temporary directory after success or failure and refuses to overwrite an existing tarball; retain each reviewed artefact in a separate output directory. Packing leaves the source checkout's dist/ untouched, so separate packers do not share mutable compiled output. The existing build:modules command still owns that replaceable local build output.

Producer command change: plain root npm pack now refuses and names npm run pack:modules. npm automatically includes a local README regardless of its files list, so packing the source root would ship the checkout guide. Do not bypass the guard with --ignore-scripts: that is not the supported consumer artefact. Historical source revisions keep their historical packing commands. Consumer installation and public imports are unchanged; follow Journal installation.

The installed manifest contains no source-checkout scripts or development dependencies. The source manifest remains private and retains its development commands. No source README is temporarily renamed or replaced, so interruption cannot leave consumers' copy in the checkout.

Check the installed result

node --test test/distribution.test.ts test/repository-adoption.test.ts
npm run typecheck

The existing external-consumer checks remain. A new check opens every installed Markdown link and local anchor, checks immutable source-reference URLs, rejects private Notion/workspace paths and checkout-only commands, compares the README index with the actual exports, and executes the README example twice with no repository, network or child-process permission. Negative cases prove that missing files/anchors, mutable references, private context and symlinks fail this check.

Source-reference links identify committed snapshots; the exact tarball integrity identifies the installed bytes, including any local draft edits. Freeze and record the source commit and artefact hash before independent review. Local tests do not replace independent review or acceptance. Coordinator-generated site output and full-suite verification remain separate integration steps.

Each tarball has a sibling .tgz.provenance.json: HEAD, input hashes and whether those inputs match HEAD. Untracked files, deletions and staged or unstaged differences are included; inputs are rechecked after staging. Machine-readable stdout retains npm's array shape. Add --clean-only to refuse draft differences for a reviewed hand-off. This conservative closure includes Dashboard build/validation dependencies, so changing shared HTTP or asset validation invalidates that artefact even when browser rendering is unchanged.

Source: docs/how-to/pack-modules.md