How Archify Ensures Reproducible Builds Without External Dependencies

Archify achieves fully reproducible builds by generating deterministic ZIP archives using only Node.js core modules, ensuring byte-for-byte identical output regardless of environment, timezone, or operating system.

The tt-a1i/archify repository demonstrates how to build portable software artifacts without relying on external build tools or package managers. By implementing a custom deterministic ZIP generator that uses only Node.js standard library modules, Archify guarantees that every build produces identical binary output. This approach enables cryptographic verification and trustworthy distribution across heterogeneous environments.

Core Deterministic ZIP Implementation

At the heart of Archify’s reproducibility guarantee sits scripts/write-deterministic-zip.mjs, a purpose-built archive generator that eliminates every source of non-determinism inherent in conventional ZIP utilities.

Normalized Metadata and Timestamps

The deterministic writer eliminates timestamp variability by setting a fixed DOS timestamp of 1980-01-01 for every entry in the archive. Entries are sorted alphabetically before processing to ensure consistent ordering, and the script writes both local file headers and the central directory using identical metadata for every build.

Compression strategy is locked to Z_FIXED in Node.js’s zlib module, preventing compression algorithm variations from affecting output. CRC32 checksums are computed manually using Node’s crypto module rather than relying on platform-specific implementations, ensuring the same input bytes always produce the same archive structure.

Zero External Runtime Dependencies

scripts/write-deterministic-zip.mjs imports only four Node.js core modules: fs, path, crypto, and zlib. This constraint means the build pipeline runs on any Node.js ≥ 18 environment without executing npm install or pulling third-party packages. By avoiding external binaries, the system eliminates variability introduced by different zip utility versions across macOS, Linux, or Windows environments.

Build Scripts Without System Dependencies

The scripts/build-zip.sh wrapper script provides a thin abstraction over the deterministic writer. Unlike conventional build pipelines that invoke the system zip command or require build-time dependency resolution, this script directly executes write-deterministic-zip.mjs to package the skill.

Because the entire pipeline operates without external tools, Archify delivers a "no-install" build path. The shell script never calls npm install, git archive, or platform-specific packaging utilities, guaranteeing that the only requirement for generating a release artifact is a standard Node.js runtime.

CI Gating and Reproducibility Verification

Reproducibility is enforced programmatically in archify/test/release-package-gates.test.mjs, which implements strict validation gates that must pass before any release.

Cross-Timezone Byte-For-Byte Validation

The test suite specifically validates that "archive build is byte-for-byte reproducible across caller time zones without system zip". The CI pipeline builds the archive twice—once with TZ=UTC and once with TZ=Pacific/Honolulu—then asserts that the resulting files are identical using byte-level comparison. This proves that the fixed timestamp implementation successfully neutralizes timezone-related variability.

Canonical Archive Integrity

Beyond cross-timezone validation, the same test verifies that the freshly built archive matches the committed archify.zip stored in the repository. This check ensures that no uncommitted changes or environment-specific artifacts have contaminated the build output, creating a cryptographic chain of trust between source code and distributed binary.

Strict Content Boundaries

The builder refuses to include files that could introduce non-determinism or security risks. As validated by the "archive build excludes untracked files and external symlinks" test, the generator halts if it encounters:

• Untracked files (ensuring only committed content is packaged)
• External symlinks (preventing file system traversal outside the repository)
• Conflicted git index entries (blocking builds with unresolved merge states)

These safety checks guarantee that the archive contains exactly the repository-tracked content, nothing more and nothing less.

Generating Reproducible Archives Locally

You can verify Archify’s reproducibility guarantees on your local machine using the deterministic writer directly.

Generate a reproducible ZIP from the repository root:

node scripts/write-deterministic-zip.mjs archify archify.zip

The resulting archify.zip will be byte-identical to the repository’s committed archive. To explicitly test timezone independence:

# Build in UTC

TZ=UTC node scripts/write-deterministic-zip.mjs archify utc.zip

# Build in Honolulu time

TZ=Pacific/Honolulu node scripts/write-deterministic-zip.mjs archify honolulu.zip

# Verify identical output

cmp -s utc.zip honolulu.zip && echo "✅ reproducible"

For standard packaging without any dependency installation:

scripts/build-zip.sh archify.zip

This produces archify.zip containing only tracked files and the embedded notifier runtime, suitable for distribution.

Summary

• Deterministic ZIP generation: scripts/write-deterministic-zip.mjs creates archives with fixed timestamps (1980-01-01), sorted entries, and Z_FIXED compression to guarantee identical output.
• Zero external dependencies: The build uses only Node.js core modules (fs, path, crypto, zlib) and runs on Node ≥ 18 without npm install or system zip binaries.
• CI-enforced reproducibility: archify/test/release-package-gates.test.mjs validates byte-for-byte identity across timezones and against the canonical committed archive.
• Content sanitization: The builder excludes untracked files, external symlinks, and conflicted index entries to ensure hermetic builds.
• Cross-platform consistency: Identical archive bytes are produced regardless of operating system, timezone, or build environment.

Frequently Asked Questions

Why does Archify use 1980-01-01 as the fixed timestamp?

Archify uses the DOS epoch date of 1980-01-01 because it is the earliest valid timestamp in the ZIP file format specification. By fixing all entries to this specific date, the system eliminates modification-time variability that would otherwise cause different archive hashes across builds, while remaining compliant with ZIP standards.

Can I run the build without installing npm dependencies?

Yes. Because scripts/write-deterministic-zip.mjs imports only Node.js built-in modules and scripts/build-zip.sh invokes it directly, you can generate archify.zip on any system with Node.js ≥ 18 installed without running npm install or downloading external packages.

How does Archify prevent non-deterministic content from entering the archive?

The deterministic writer in scripts/write-deterministic-zip.mjs performs strict safety checks validated by archify/test/release-package-gates.test.mjs. It refuses to package untracked files, external symlinks, or repositories with conflicted git index entries, ensuring that only the exact committed state of the repository is archived.

What Node.js version is required for reproducible builds?

Archify requires Node.js 18 or higher. The build script relies on modern Node.js standard library APIs, particularly the zlib module’s Z_FIXED compression strategy and the crypto module’s CRC32 capabilities, which are stable and consistent across all supported Node.js versions.

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