How the Archify Deliver Command Works: JSON to Self-Contained HTML Pipeline

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:

archify deliver <type> <candidate.json> <output.html>

• <type> specifies the document category: architecture, workflow, dataflow, or lifecycle.
• <candidate.json> points to the validated JSON file generated by previous pipeline stages.
• <output.html> 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 <path> – 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 <output.html> 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. 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 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:

archify deliver workflow examples/workflow.json out/workflow.html --json

Generate a showcase-quality architecture artifact with repository evidence:

archify deliver architecture archify/examples/architecture.json \
    out/archify.html --quality showcase --repo-root . --json

Deliver and immediately open the result in your browser:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}