Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

build(zip): make canonical archive reproducible

sunsunsun99564e0c8d46
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2140fbfd..b35b125d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -74,13 +74,13 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- - name: Rebuild archify.zip and compare contents
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ - name: Rebuild archify.zip and compare exact bytes
run: |
- (cd /tmp && "$GITHUB_WORKSPACE/scripts/build-zip.sh" fresh.zip)
- mkdir /tmp/fresh /tmp/checked
- unzip -q /tmp/fresh.zip -d /tmp/fresh
- unzip -q archify.zip -d /tmp/checked
- if ! diff -r /tmp/fresh/archify /tmp/checked/archify; then
+ scripts/build-zip.sh /tmp/fresh.zip
+ if ! cmp -s /tmp/fresh.zip archify.zip; then
echo '::error::archify.zip is stale — run scripts/build-zip.sh and commit the result'
exit 1
fi
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3a92793c..3560d5f9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -67,11 +67,9 @@ jobs:
node scripts/package-smoke.mjs "$package_root/archify"
- name: Committed zip must match the build (same gate as CI)
run: |
- mkdir /tmp/fresh /tmp/checked
- unzip -q archify.zip -d /tmp/fresh
+ cp archify.zip /tmp/archify-built.zip
git checkout HEAD -- archify.zip
- unzip -q archify.zip -d /tmp/checked
- diff -r /tmp/fresh/archify /tmp/checked/archify
+ cmp -s /tmp/archify-built.zip archify.zip
- name: Create GitHub Release with the zip attached
uses: softprops/action-gh-release@v2
with:
diff --git a/archify.zip b/archify.zip
index b7fcf7d4..b4f1c653 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjs
index 6e5b46b8..90813fda 100644
--- a/archify/test/release-package-gates.test.mjs
+++ b/archify/test/release-package-gates.test.mjs
@@ -45,7 +45,7 @@ test('release smokes the exact archive built for the release before freshness an
assert.match(smoke, /node scripts\/package-smoke\.mjs "\$package_root\/archify"/);
assert.doesNotMatch(smoke, /\bnpm\s+(?:ci|install)\b/);
assert.match(freshness, /git checkout HEAD -- archify\.zip/);
- assert.match(freshness, /diff -r \/tmp\/fresh\/archify \/tmp\/checked\/archify/);
+ assert.match(freshness, /cmp -s \/tmp\/archify-built\.zip archify\.zip/);
assert.match(upload, /files: archify\.zip/);
});
@@ -175,6 +175,42 @@ test('archive build excludes untracked files and external symlinks from the live
}
});
+test('archive build is byte-for-byte reproducible across caller time zones without system zip', () => {
+ const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-reproducible-'));
+ const utcArchive = path.join(outputRoot, 'utc.zip');
+ const honoluluArchive = path.join(outputRoot, 'honolulu.zip');
+
+ try {
+ for (const [archive, timezone] of [
+ [utcArchive, 'UTC'],
+ [honoluluArchive, 'Pacific/Honolulu'],
+ ]) {
+ const build = spawnSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), [archive], {
+ cwd: repoRoot,
+ encoding: 'utf8',
+ env: { ...process.env, TZ: timezone },
+ });
+ assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
+ }
+
+ assert.deepEqual(
+ fs.readFileSync(utcArchive),
+ fs.readFileSync(honoluluArchive),
+ 'identical tracked inputs must produce identical archive bytes',
+ );
+ assert.deepEqual(
+ fs.readFileSync(utcArchive),
+ fs.readFileSync(path.join(repoRoot, 'archify.zip')),
+ 'the canonical archive toolchain must reproduce the committed archive bytes',
+ );
+ const buildScript = fs.readFileSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), 'utf8');
+ assert.match(buildScript, /write-deterministic-zip\.mjs/);
+ assert.doesNotMatch(buildScript, /(?:^|\s)zip\s/);
+ } finally {
+ fs.rmSync(outputRoot, { recursive: true, force: true });
+ }
+});
+
test('CI tests the declared Node floor plus every maintained current lane', () => {
const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'archify', 'package.json'), 'utf8'));
assert.equal(packageJson.engines?.node, '>=18');
@@ -192,4 +228,5 @@ test('CI tests the declared Node floor plus every maintained current lane', () =
const packageSmokeJob = workflowJob(workflow, 'package-smoke');
assert.match(packageSmokeJob, /os:\s*\[ubuntu-latest, macos-latest, windows-latest\]/);
assert.match(packageSmokeJob, /node-version:\s*22/);
+ assert.doesNotMatch(packageSmokeJob, /compare exact bytes/);
});
diff --git a/archify/test/route-share-card.test.mjs b/archify/test/route-share-card.test.mjs
index a2220547..b501112f 100644
--- a/archify/test/route-share-card.test.mjs
+++ b/archify/test/route-share-card.test.mjs
@@ -158,12 +158,6 @@ test('skill and READMEs describe the optional Export variant and show one real c
assert.equal(png.readUInt32BE(16), 1200);
assert.equal(png.readUInt32BE(20), 630);
- const buildZip = fs.readFileSync(path.join(repoRoot, 'scripts/build-zip.sh'), 'utf8');
- assert.match(
- buildZip,
- /git -C "\$repo_root" ls-files -z -- archify/,
- 'archive inputs must come from Git tracking so concurrent validator scratch cannot leak into archify.zip',
- );
});
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
diff --git a/scripts/build-zip.sh b/scripts/build-zip.sh
index 50c9b5fc..127dd185 100755
--- a/scripts/build-zip.sh
+++ b/scripts/build-zip.sh
@@ -23,7 +23,10 @@ if [[ ! -f "$repo_root/archify/renderers/shared/generated-validators.mjs" ]]; th
echo 'generated validators are missing — run npm run generate:validators in archify/' >&2
exit 1
fi
-while IFS= read -r -d '' tracked; do
+while IFS= read -r -d '' record; do
+ metadata="${record%%$'\t'*}"
+ tracked="${record#*$'\t'}"
+ tracked_mode="${metadata%% *}"
case "$tracked" in
archify/test | archify/test/* | \
archify/package-lock.json | \
@@ -45,8 +48,16 @@ while IFS= read -r -d '' tracked; do
target="$stage/$tracked"
mkdir -p "$(dirname "$target")"
- cp -p "$source" "$target"
-done < <(git -C "$repo_root" ls-files -z -- archify)
+ cp "$source" "$target"
+ case "$tracked_mode" in
+ 100755) chmod 0755 "$target" ;;
+ 100644) chmod 0644 "$target" ;;
+ *)
+ echo "unsupported tracked package mode $tracked_mode: $tracked" >&2
+ exit 1
+ ;;
+ esac
+done < <(git -C "$repo_root" ls-files --stage -z -- archify)
node -e "
const fs = require('fs');
const p = '$stage/archify/package.json';
@@ -58,7 +69,6 @@ node -e "
rm -f "$stage/archify/package-lock.json"
rm -f "$out"
-(cd "$stage" && zip -r -X -q "$out" archify)
+node "$repo_root/scripts/write-deterministic-zip.mjs" "$stage/archify" "$out"
-unzip -l "$out" | tail -1
echo "built $out"
diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjs
new file mode 100644
index 00000000..c9d6c319
--- /dev/null
+++ b/scripts/write-deterministic-zip.mjs
@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { constants as zlibConstants, deflateRawSync } from 'node:zlib';
+
+const [rootArg, outputArg] = process.argv.slice(2);
+if (!rootArg || !outputArg) {
+ console.error('Usage: node scripts/write-deterministic-zip.mjs <directory> <output.zip>');
+ process.exit(2);
+}
+
+const root = path.resolve(rootArg);
+const output = path.resolve(outputArg);
+const UTF8_FLAG = 0x0800;
+const DEFLATE_METHOD = 8;
+const DOS_TIME = 0;
+const DOS_DATE = 0x0021; // 1980-01-01, the earliest ZIP timestamp.
+
+function crc32(buffer) {
+ let crc = 0xffffffff;
+ for (const byte of buffer) {
+ crc ^= byte;
+ for (let bit = 0; bit < 8; bit += 1) {
+ crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+ }
+ }
+ return (crc ^ 0xffffffff) >>> 0;
+}
+
+function sortedEntries(directory, prefix = '') {
+ const entries = fs.readdirSync(directory, { withFileTypes: true })
+ .sort((left, right) => Buffer.compare(Buffer.from(left.name), Buffer.from(right.name)));
+ const files = [];
+ for (const entry of entries) {
+ const absolute = path.join(directory, entry.name);
+ const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (entry.isSymbolicLink()) throw new Error(`refusing to archive symlink: ${relative}`);
+ if (entry.isDirectory()) files.push(...sortedEntries(absolute, relative));
+ else if (entry.isFile()) files.push({ absolute, relative });
+ else throw new Error(`refusing to archive non-regular file: ${relative}`);
+ }
+ return files;
+}
+
+function localHeader({ name, crc, compressedSize, uncompressedSize }) {
+ const header = Buffer.alloc(30);
+ header.writeUInt32LE(0x04034b50, 0);
+ header.writeUInt16LE(20, 4);
+ header.writeUInt16LE(UTF8_FLAG, 6);
+ header.writeUInt16LE(DEFLATE_METHOD, 8);
+ header.writeUInt16LE(DOS_TIME, 10);
+ header.writeUInt16LE(DOS_DATE, 12);
+ header.writeUInt32LE(crc, 14);
+ header.writeUInt32LE(compressedSize, 18);
+ header.writeUInt32LE(uncompressedSize, 22);
+ header.writeUInt16LE(name.length, 26);
+ header.writeUInt16LE(0, 28);
+ return header;
+}
+
+function centralHeader({ name, crc, compressedSize, uncompressedSize, offset, mode }) {
+ const header = Buffer.alloc(46);
+ header.writeUInt32LE(0x02014b50, 0);
+ header.writeUInt16LE(0x0314, 4); // ZIP 2.0, created on Unix.
+ header.writeUInt16LE(20, 6);
+ header.writeUInt16LE(UTF8_FLAG, 8);
+ header.writeUInt16LE(DEFLATE_METHOD, 10);
+ header.writeUInt16LE(DOS_TIME, 12);
+ header.writeUInt16LE(DOS_DATE, 14);
+ header.writeUInt32LE(crc, 16);
+ header.writeUInt32LE(compressedSize, 20);
+ header.writeUInt32LE(uncompressedSize, 24);
+ header.writeUInt16LE(name.length, 28);
+ header.writeUInt16LE(0, 30);
+ header.writeUInt16LE(0, 32);
+ header.writeUInt16LE(0, 34);
+ header.writeUInt16LE(0, 36);
+ header.writeUInt32LE(((0o100000 | mode) << 16) >>> 0, 38);
+ header.writeUInt32LE(offset, 42);
+ return header;
+}
+
+const localParts = [];
+const centralParts = [];
+let offset = 0;
+
+for (const file of sortedEntries(root)) {
+ const name = Buffer.from(`${path.basename(root)}/${file.relative}`, 'utf8');
+ const content = fs.readFileSync(file.absolute);
+ const compressed = deflateRawSync(content, {
+ level: 9,
+ memLevel: 9,
+ strategy: zlibConstants.Z_FIXED,
+ });
+ const checksum = crc32(content);
+ const mode = fs.statSync(file.absolute).mode & 0o111 ? 0o755 : 0o644;
+ const local = localHeader({
+ name,
+ crc: checksum,
+ compressedSize: compressed.length,
+ uncompressedSize: content.length,
+ });
+ localParts.push(local, name, compressed);
+ centralParts.push(
+ centralHeader({
+ name,
+ crc: checksum,
+ compressedSize: compressed.length,
+ uncompressedSize: content.length,
+ offset,
+ mode,
+ }),
+ name,
+ );
+ offset += local.length + name.length + compressed.length;
+}
+
+const centralOffset = offset;
+const centralSize = centralParts.reduce((total, part) => total + part.length, 0);
+const entryCount = centralParts.length / 2;
+if (entryCount > 0xffff || centralOffset > 0xffffffff || centralSize > 0xffffffff) {
+ throw new Error('ZIP64 is not supported by the deterministic package writer');
+}
+
+const end = Buffer.alloc(22);
+end.writeUInt32LE(0x06054b50, 0);
+end.writeUInt16LE(0, 4);
+end.writeUInt16LE(0, 6);
+end.writeUInt16LE(entryCount, 8);
+end.writeUInt16LE(entryCount, 10);
+end.writeUInt32LE(centralSize, 12);
+end.writeUInt32LE(centralOffset, 16);
+end.writeUInt16LE(0, 20);
+
+fs.writeFileSync(output, Buffer.concat([...localParts, ...centralParts, end]));
+console.log(`built ${output} (${entryCount} files)`);