# How the Archify Deliver Command Works: JSON to Self-Contained HTML Pipeline > Discover how the Archify deliver command converts JSON to self-contained HTML artifacts. Learn about atomic commits, crypto hashing, and zero-downtime replacement for reproducible builds. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: internals - Published: 2026-09-08 --- **The `archify deliver` command transforms validated JSON candidates into deterministic, self-contained HTML artifacts using atomic commits and cryptographic hashing to ensure zero-downtime replacement and reproducible builds.** The `archify deliver` command serves as the final stage in the Archify pipeline within the `tt-a1i/archify` repository. It converts intermediate JSON specifications—produced by `archify render` or `archify validate`—into standalone HTML documents suitable for sharing, archival, or gallery publication. ## CLI Syntax and Argument Structure The command entry point resides in `archify/bin/archify.mjs`, which parses three required positional arguments followed by optional configuration flags. ### Positional Arguments The invocation pattern requires strict ordering: ```bash archify deliver ``` - **``** specifies the document category: `architecture`, `workflow`, `dataflow`, or `lifecycle`. - **``** points to the validated JSON file generated by previous pipeline stages. - **``** defines the destination path for the final HTML artifact. ### Optional Flags Fine-tune delivery behavior with these flags: - **`--quality showcase`** – Requests gallery-ready visual polish for high-fidelity presentations. - **`--json`** – Emits a structured JSON receipt on `stdout` instead of plain text messages. - **`--repo-root `** – Binds the delivery to a specific repository root, enabling repository-evidence checks in the receipt. - **`--open`** – Automatically opens the generated HTML in the default browser immediately after successful atomic commit. Tests in `scripts/package-smoke.mjs` verify these flags; for example, lines 297-304 exercise workflow delivery with `--quality showcase --json`, while `archify/test/repository-evidence.test.mjs` (lines 70-91) validates the `--repo-root` integration. ## Internal Execution Flow When dispatched from `archify/bin/archify.mjs`, the deliver command executes a four-phase pipeline designed for safety and reproducibility. ### Input Re-validation The command re-validates the candidate JSON before processing. This guards against race conditions where the underlying file changes between validation and delivery steps, ensuring the HTML generation operates only on verified inputs. ### Deterministic Rendering and Hashing The validated JSON feeds into a pure rendering function—shared with the `archify render` implementation—that produces byte-identical HTML output. The system calculates a canonical **SHA-256 hash** of the rendered bytes, enabling reproducible builds and content-addressable caching. This deterministic output is verified in `archify/test/visual-check.test.mjs`. ### Atomic Commit Mechanism To prevent half-written artifacts, the command uses a temporary staging directory following the `.archify-delivery-*` naming pattern. The new HTML and its receipt write to this candidate directory first. Only after all checks pass does the system perform an atomic move to the final `` path. According to the `tt-a1i/archify` source code, `archify/test/output-path.test.mjs` (lines 243-264) explicitly verifies this atomic replacement logic, ensuring failed deliveries never corrupt existing artifacts. ### Receipt Generation and Cleanup Upon successful commit, the command generates a JSON receipt containing: - `ok: true` – Success flag - `specification.sha256` – Cryptographic hash of the final HTML - `specification.bytes` – File size in bytes - `repository` – Optional object when `--repo-root` is specified The receipt writes to both `stdout` (when `--json` is passed) and a side-car file named [`.archify-delivery-receipt.json`](https://github.com/tt-a1i/archify/blob/main/.archify-delivery-receipt.json). The `archify/test/repair-receipt.test.mjs` suite (lines 97-121) confirms that delivery receipts mirror validation receipts for clean-flow diagnostics, and line 128 verifies cleanup of temporary `.archify-delivery-*` directories post-success. ## Safety Guarantees and Delivery Contracts The implementation prioritizes data integrity and deployment safety through three core guarantees. ### Deterministic Output Every execution with identical inputs produces byte-identical HTML and matching SHA-256 hashes. This determinism supports reproducible builds and allows downstream systems to cache artifacts reliably. ### Zero-Dependency Artifacts The final HTML contains no embedded Archify binary references or runtime dependencies. As documented in [`references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/delivery-contract.md) and enforced by `archify/test/preview-contract.test.mjs` (lines 11-22), the output consists of static, self-contained markup suitable for offline viewing or long-term archival without external asset calls. ### Atomic Delivery Semantics The all-or-nothing commit strategy ensures that the filesystem never contains partially written HTML. If rendering, hashing, or disk write operations fail, the atomic move never occurs, leaving the previous artifact untouched. This guards against corruption during disk-full scenarios or process interruptions. ## Practical Usage Examples Deliver a basic workflow candidate with machine-readable output: ```bash archify deliver workflow examples/workflow.json out/workflow.html --json ``` Generate a showcase-quality architecture artifact with repository evidence: ```bash archify deliver architecture archify/examples/architecture.json \ out/archify.html --quality showcase --repo-root . --json ``` Deliver and immediately open the result in your browser: ```bash archify deliver dataflow dataflow.json out/dataflow.html --open ``` ## Key Implementation Files The deliver command logic spans these critical source locations: - **`archify/bin/archify.mjs`** – CLI entry point where argument parsing and command dispatch occur. - **`archify/test/repository-evidence.test.mjs`** – Validates `--repo-root` binding and receipt field injection (lines 70-91). - **`archify/test/output-path.test.mjs`** – Confirms atomic replacement and output path handling (lines 243-264). - **`archify/test/repair-receipt.test.mjs`** – Ensures receipt format consistency between validation and delivery phases. - **`archify/test/preview-contract.test.mjs`** – Documents the zero-dependency delivery contract (lines 11-22). - **[`references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/delivery-contract.md)** – Formal specification of delivery output guarantees. ## Summary - The `archify deliver` command converts validated JSON into self-contained HTML through a four-phase pipeline: re-validation, deterministic rendering, atomic commit, and receipt generation. - **Atomic commit mechanics** using temporary `.archify-delivery-*` directories prevent corrupted or partial artifacts during failed deliveries. - **Deterministic hashing** via SHA-256 ensures reproducible builds and content verification. - **Zero-dependency output** produces static HTML suitable for offline archival without runtime requirements. - Repository binding via `--repo-root` enriches receipts with version control context for audit trails. ## Frequently Asked Questions ### What input types does the archify deliver command support? The command accepts four document types as the first positional argument: `architecture`, `workflow`, `dataflow`, and `lifecycle`. Each type processes specific JSON schemas produced by corresponding `archify render` or `archify validate` operations. ### How does atomic delivery prevent file corruption? The system writes new artifacts to a temporary `.archify-delivery-*` directory first, then performs an atomic filesystem move to the target path only after successful HTML generation and hash verification. As tested in `archify/test/output-path.test.mjs`, this ensures that existing files remain untouched if the delivery process encounters errors or interruptions. ### What information appears in the delivery receipt? The JSON receipt includes an `ok` status flag, the artifact's SHA-256 hash under `specification.sha256`, file size in `specification.bytes`, and optional repository metadata when using `--repo-root`. The receipt emits to both `stdout` (with `--json` flag) and a side-car [`.archify-delivery-receipt.json`](https://github.com/tt-a1i/archify/blob/main/.archify-delivery-receipt.json) file for downstream automation. ### Can the deliver command automatically open the generated HTML? Yes. Passing the `--open` flag triggers browser launch immediately after successful atomic commit. This occurs only after the delivery receipt confirms success, ensuring you view the finalized, verified artifact rather than an intermediate state.