What Is the Staging Directory in Archify’s Delivery Process?

Archify’s delivery pipeline creates a private, same-directory staging folder to isolate candidate artifacts, enable atomic commits, and ensure crash-resilient deliveries.

The staging directory is a core mechanism in the tt-a1i/archify CLI that guarantees safe, deterministic output generation. Each time you run a deliver command, the tool creates a temporary workspace—named *.archify-delivery-*—to hold candidate files before committing them to the final destination. This design ensures that your existing artifacts remain untouched until every validation gate passes, as documented in the project’s architectural roadmap at ROADMAP.md (line 22).

Core Functions of the Staging Directory

Isolation and Safety

The staging directory provides a sandboxed workspace where all intermediate files live during the delivery pipeline. If any step—render, validate, composition, or receipt verification—fails, Archify simply discards the temporary folder. Your existing output file remains intact, preventing partial or corrupted updates.

Atomic Commit Guarantees

Only after all deterministic gates pass does Archify perform an atomic move from the staging area to the final destination. This ensures that the output is either completely new or completely unchanged, eliminating the risk of users encountering half-written files during a crash.

Concurrency and Deterministic Naming

Because Archify creates the staging folder using fs.mkdtempSync with a unique temporary suffix (*.archify-delivery-*), concurrent deliveries cannot clash. Each process writes to its own isolated path, ensuring that parallel runs never alias or corrupt intermediate files.

Implementation in the Archify Source Code

According to the archify/bin/archify.mjs implementation, the staging directory lifecycle follows three distinct phases.

Creation with mkdtempSync

At line 850, the CLI initializes the staging path:

stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'));

This generates a private, same-directory folder with a cryptographically random suffix, placing it adjacent to the target output for efficient atomic moves.

Storing Candidate Artifacts

Between lines 870–872, the pipeline assembles candidate files inside the staging area:

const candidatePath = path.join(stagingDirectory, path.basename(outputPath));

This holds the rendered HTML, generated receipt, specification snapshots, and any auxiliary files while validation runs.

Cleanup and Error Handling

At line 1118, after a successful delivery, Archify attempts recursive removal:

console.error(`Warning: could not remove delivery staging directory "${stagingDirectory}": ${error.message}`);

If fs.rmSync fails to remove the staging directory, the CLI emits a non-fatal warning rather than crashing. This preserves diagnostic access to the temporary files without corrupting the delivered artifact.

Delivery Workflow Example

As defined in archify/references/delivery-contract.md, the following command triggers the staging workflow:

node bin/archify.mjs deliver architecture examples/web-app.architecture.json \
    /tmp/web-app.html --quality showcase --json

Inside the CLI, the workflow follows this deterministic sequence:

// Phase 1: Initialize isolated workspace
const stagingDirectory = fs.mkdtempSync(
  path.join(outputDirectory, '.archify-delivery-')
);

// Phase 2: Generate and validate candidates
const candidatePath = path.join(stagingDirectory, path.basename(outputPath));
// ... render HTML, validate schema, compute receipt ...

// Phase 3: Atomic commit or graceful discard
if (allChecksPass) {
  fs.renameSync(candidatePath, outputPath);   // Atomic move
} else {
  fs.rmSync(stagingDirectory, {recursive:true, force:true});
  // Existing output remains untouched
}

// Phase 4: Cleanup
fs.rmSync(stagingDirectory, {recursive:true, force:true});

When validation fails, the staging directory is removed without touching the destination file, maintaining side-effect-free operation.

Summary

• Isolation: The staging directory acts as a sandbox for candidate artifacts, ensuring failed deliveries never corrupt existing outputs.
• Atomicity: Verified candidates move to the final destination only after all checks pass, guaranteeing all-or-nothing updates.
• Concurrency: Unique temporary naming via fs.mkdtempSync prevents clashes between simultaneous delivery processes.
• Resilience: Non-fatal cleanup warnings preserve diagnostic capabilities without breaking the delivery contract.

Frequently Asked Questions

Where is the staging directory created?

The staging directory is created in the same directory as the target output file using fs.mkdtempSync with the prefix .archify-delivery-. This co-location enables atomic rename operations and keeps temporary files close to their final destination for optimal I/O performance.

What happens if a delivery fails?

If any validation step fails—such as schema validation or receipt mismatch—the CLI discards the staging directory via fs.rmSync without moving files to the output path. Your existing artifact remains completely untouched, and the process exits with an error code.

Is the staging directory removed automatically?

Yes. Upon successful delivery, Archify attempts to recursively remove the staging directory using fs.rmSync with force: true. If removal fails (e.g., due to permission issues), the CLI emits a warning message but considers the delivery successful, allowing you to inspect the leftover files without blocking your pipeline.

Can multiple deliveries run simultaneously?

Yes. Because each staging directory receives a unique cryptographically random suffix from fs.mkdtempSync, concurrent deliver commands cannot interfere with one another. Each process writes to its own isolated *.archify-delivery-* folder, making the pipeline safe for parallel execution.

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