Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
build(zip): make canonical archive reproducible
sunsunsun99564e0c8d46
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 2140fbfd..b35b125d 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -74,13 +74,13 @@ jobs:runs-on: ubuntu-lateststeps:- 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 bytesrun: |- (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; thenecho '::error::archify.zip is stale — run scripts/build-zip.sh and commit the result'exit 1fidiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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.zipgit 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 attacheduses: softprops/action-gh-release@v2with:diff --git a/archify.zip b/archify.zipindex b7fcf7d4..b4f1c653 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjsindex 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 anassert.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.mjsindex 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 cassert.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.shindex 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" ]]; thecho 'generated validators are missing — run npm run generate:validators in archify/' >&2exit 1fi-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" inarchify/test | archify/test/* | \archify/package-lock.json | \@@ -45,8 +48,16 @@ while IFS= read -r -d '' tracked; dotarget="$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 -1echo "built $out"diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjsnew file mode 100644index 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)`);