How Archify Validators Are Generated and Shipped: A Complete Technical Guide

Archify validators are automatically generated from TypeScript JSON schemas at build time, bundled into a deterministic ZIP archive, and shipped with the npm package so downstream projects can perform runtime validation without installing development dependencies.

The tt-a1i/archify repository implements a sophisticated build pipeline where validation logic is derived directly from source schemas. This approach ensures that workflow definitions, skill manifests, and update contracts are validated against the exact same structural rules at both compile time and runtime.

Schema Definitions as the Single Source of Truth

All validation logic originates in the TypeScript schema files located in archify/src/schema/. These modules—such as archify/src/schema/workflow.ts—define the canonical shape of workflow contracts, skill metadata, and update manifests using strong typing.

By maintaining schemas as the definitive source, the system guarantees that any change to a data structure automatically propagates to its corresponding validator. This eliminates drift between documentation, type definitions, and runtime checks.

The Generator Pipeline: From Types to Validators

The transformation from static schemas to executable validation code is handled by scripts/write-deterministic-zip.mjs. This Node.js script imports the schema modules and uses internal zod/ajv helpers to transpile them into plain-JavaScript validator functions.

Unlike generic validation libraries that parse schemas at runtime, these generated functions are static code optimized for performance. The script writes the output into a temporary directory structure that mirrors the final package layout.

Creating the Deterministic Archive

Once the JavaScript files are generated, scripts/build-zip.sh packages them into archify.zip. This archive contains the compiled validator modules under a validators/ directory.

The build process ensures the ZIP is deterministic, meaning identical source inputs always produce byte-for-byte identical archives. This property is critical for reproducible releases and cryptographic verification of the distributed package.

Packaging and Distribution

The generated validators are integrated into the release workflow defined in .github/workflows/release.yml. When maintainers publish a new version, the CI pipeline executes the generator scripts and includes the resulting archify.zip within the npm tarball.

Consumers install the package via npm i archify and access validators directly from the archify/validators namespace. The validators ship as production dependencies, requiring no additional build tooling in downstream projects.

Runtime Usage and Validation

Client code imports specific validators as needed. For example, to validate a workflow definition:

// Import a generated validator
import { workflowValidator } from "archify/validators/workflow.js";

// Validate a workflow definition
const result = workflowValidator(myWorkflow);
if (!result.success) {
  console.error("Invalid workflow:", result.error);
}

These validators are pure functions that return a boolean status or throw detailed error objects. This design enables both compile-time type safety through TypeScript and defensive runtime checks in production environments.

Summary

• Single source of truth: Schemas in archify/src/schema/ define all valid data structures, ensuring validators never drift from specifications.
• Automated generation: scripts/write-deterministic-zip.mjs converts TypeScript schemas into optimized JavaScript validation functions using zod/ajv helpers.
• Deterministic bundling: scripts/build-zip.sh creates reproducible archify.zip archives containing the validators/ directory, guaranteeing identical builds across environments.
• Zero-dependency consumption: The CI pipeline in .github/workflows/release.yml ships generated validators with the npm package, allowing runtime validation via archify/validators without development tooling.

Frequently Asked Questions

Why does Archify generate validators instead of using a runtime validation library?

Archify generates validators to eliminate runtime overhead and distribution bloat. When schemas are parsed by libraries like ajv or zod at runtime, they incur both memory and CPU costs. By generating plain-JavaScript functions at build time, Archify ships only the necessary validation logic, resulting in smaller bundle sizes and faster execution while maintaining perfect synchronization with the source schemas.

What makes the ZIP archive "deterministic" and why does it matter?

A deterministic archive produces identical byte-for-byte output when given the same input. The scripts/build-zip.sh process sorts files, normalizes timestamps, and uses consistent compression settings to ensure archify.zip is reproducible. This matters for security auditing, build caching, and verifying that published packages match the source code exactly, preventing supply-chain attacks where build artifacts might differ unexpectedly.

How do I regenerate validators if I modify the source schemas?

Run the generator script locally and rebuild the archive. Execute node scripts/write-deterministic-zip.mjs to transpile the updated TypeScript schemas in archify/src/schema/ into JavaScript validators. Then run bash scripts/build-zip.sh to recreate the deterministic ZIP. These steps are automatically performed by the CI pipeline in .github/workflows/release.yml during publication, but maintainers can run them manually for local testing.

Are the generated validators compatible with TypeScript type checking?

Yes, the validators provide runtime enforcement that complements compile-time types. While TypeScript checks types during development, the generated validators from archify/validators/ verify data at runtime—for example, when ingesting external JSON payloads. This dual-layer approach catches structural violations that bypass type systems, such as malformed API responses or corrupted configuration files.

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