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
fix(zip): pin canonical toolchain and ZIP32 bounds
sunsunsun50e2e63d7742
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 309c7d5c..f610ae32 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -107,6 +107,11 @@ node scripts/build-readme-showcase.mjsscripts/build-zip.sh /tmp/archify-contrib.zip```+The runtime follows the Node range in `archify/package.json`, but canonical+`archify.zip` container bytes are built only with Node 22. The builder rejects+other Node majors so a different bundled zlib cannot publish a second byte+representation of the same package contents.+Bundled example or viewer changes normally require the Gallery rebuild. Skill runtime, schema, renderer, or published `SKILL.md` changes require checking `archify.zip` freshness and committing a rebuilt archive when the checked-in package contents differ.List every regenerated file in the PR description. Do not regenerate unrelated HTML, GIFs, screenshots, manifests, or archives merely to make the branch look current. Generated artifacts are evidence and delivery payloads, not a substitute for reviewing the source change.diff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjsindex a8774832..567268ea 100644--- a/archify/test/release-package-gates.test.mjs+++ b/archify/test/release-package-gates.test.mjs@@ -8,6 +8,13 @@ import { fileURLToPath } from 'node:url';const __dirname = path.dirname(fileURLToPath(import.meta.url));const repoRoot = path.resolve(__dirname, '..', '..');+const canonicalZipNodeMajor = 22;+const currentNodeMajor = Number(process.versions.node.split('.')[0]);+const canonicalZipTest = (name, fn) => test(name, {+ skip: currentNodeMajor === canonicalZipNodeMajor+ ? false+ : `canonical ZIP builds require Node ${canonicalZipNodeMajor}`,+}, fn);function workflowStep(workflow, name) {const marker = ` - name: ${name}`;@@ -100,7 +107,7 @@ test('package smoke rejects every dependency or repository-only artifact', () =>}});-test('package smoke rejects every dependency metadata field in a built package', () => {+canonicalZipTest('package smoke rejects every dependency metadata field in a built package', () => {const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-built-package-gate-'));try {const archive = path.join(fixture, 'archify.zip');@@ -143,7 +150,7 @@ test('package smoke rejects every dependency metadata field in a built package',}});-test('archive build excludes untracked files and external symlinks from the live working tree', () => {+canonicalZipTest('archive build excludes untracked files and external symlinks from the live working tree', () => {const marker = `.package-negative-${process.pid}-${Date.now()}`;const untracked = path.join(repoRoot, 'archify', `${marker}.txt`);const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-external-'));@@ -174,7 +181,7 @@ test('archive build excludes untracked files and external symlinks from the live}});-test('archive build rejects an unmerged index and preserves an existing archive', () => {+canonicalZipTest('archive build rejects an unmerged index and preserves an existing archive', () => {const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-unmerged-'));const scripts = path.join(fixture, 'scripts');const skill = path.join(fixture, 'archify');@@ -221,13 +228,35 @@ test('archive build rejects an unmerged index and preserves an existing archive'});assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);assert.match(build.stderr, /refusing to package unmerged index entry/);- assert.deepEqual(fs.readFileSync(archive), trusted, 'a failed build must preserve the trusted archive');+ assert.ok(fs.readFileSync(archive).equals(trusted), 'a failed build must preserve the trusted archive');} finally {fs.rmSync(fixture, { recursive: true, force: true });}});-test('archive build is byte-for-byte reproducible across caller time zones without system zip', () => {+test('archive build rejects non-canonical Node versions before publishing output', {+ skip: currentNodeMajor === canonicalZipNodeMajor+ ? `requires a Node major other than ${canonicalZipNodeMajor}`+ : false,+}, () => {+ const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-node-version-'));+ try {+ const archive = path.join(outputRoot, 'archify.zip');+ const trusted = Buffer.from('existing canonical archive');+ fs.writeFileSync(archive, trusted);+ const build = spawnSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), [archive], {+ cwd: repoRoot,+ encoding: 'utf8',+ });+ assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);+ assert.match(build.stderr, /canonical archify\.zip builds require Node 22/);+ assert.ok(fs.readFileSync(archive).equals(trusted), 'version rejection must preserve the canonical archive');+ } finally {+ fs.rmSync(outputRoot, { recursive: true, force: true });+ }+});++canonicalZipTest('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');@@ -245,14 +274,12 @@ test('archive build is byte-for-byte reproducible across caller time zones withoassert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);}- assert.deepEqual(- fs.readFileSync(utcArchive),- fs.readFileSync(honoluluArchive),+ assert.ok(+ fs.readFileSync(utcArchive).equals(fs.readFileSync(honoluluArchive)),'identical tracked inputs must produce identical archive bytes',);- assert.deepEqual(- fs.readFileSync(utcArchive),- fs.readFileSync(path.join(repoRoot, 'archify.zip')),+ assert.ok(+ fs.readFileSync(utcArchive).equals(fs.readFileSync(path.join(repoRoot, 'archify.zip'))),'the canonical archive toolchain must reproduce the committed archive bytes',);assert.deepEqual(diff --git a/scripts/build-zip.sh b/scripts/build-zip.shindex ad402bc1..ec903697 100755--- a/scripts/build-zip.sh+++ b/scripts/build-zip.sh@@ -9,6 +9,18 @@ if [[ "$out" != /* ]]; thenout="$(pwd)/$out"fi+# Runtime consumers support every Node version declared by archify/package.json,+# but canonical ZIP bytes depend on the Node/zlib toolchain. CI and releases use+# Node 22, so fail clearly instead of publishing different bytes from another+# Node major.+canonical_node_major=22+node_version="$(node -p 'process.versions.node')"+node_major="${node_version%%.*}"+if [[ "$node_major" != "$canonical_node_major" ]]; then+ echo "canonical archify.zip builds require Node $canonical_node_major (current: $node_version)" >&2+ exit 1+fi+# Stage only files tracked by Git. Paths and modes come from the index, while# bytes intentionally come from the working tree so contributors can package# tracked edits before committing them. A conflicted index is never publishable.diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjsindex d392a880..a33c56eb 100644--- a/scripts/write-deterministic-zip.mjs+++ b/scripts/write-deterministic-zip.mjs@@ -93,7 +93,7 @@ const localParts = [];const centralParts = [];let offset = 0;const files = sortedEntries(root);-requireZip32(files.length <= ZIP32_MAX_ENTRIES, `entry count ${files.length} exceeds ${ZIP32_MAX_ENTRIES}`);+requireZip32(files.length < ZIP32_MAX_ENTRIES, `entry count ${files.length} reaches ZIP64 sentinel ${ZIP32_MAX_ENTRIES}`);for (const file of files) {const name = Buffer.from(`${path.basename(root)}/${file.relative}`, 'utf8');@@ -104,9 +104,9 @@ for (const file of files) {strategy: zlibConstants.Z_FIXED,});requireZip32(name.length <= ZIP32_MAX_NAME_BYTES, `file name is too long: ${file.relative}`);- requireZip32(content.length <= ZIP32_MAX_VALUE, `file is too large: ${file.relative}`);- requireZip32(compressed.length <= ZIP32_MAX_VALUE, `compressed file is too large: ${file.relative}`);- requireZip32(offset <= ZIP32_MAX_VALUE, `local header offset is too large: ${file.relative}`);+ requireZip32(content.length < ZIP32_MAX_VALUE, `file reaches the ZIP64 size sentinel: ${file.relative}`);+ requireZip32(compressed.length < ZIP32_MAX_VALUE, `compressed file reaches the ZIP64 size sentinel: ${file.relative}`);+ requireZip32(offset < ZIP32_MAX_VALUE, `local header offset reaches the ZIP64 sentinel: ${file.relative}`);const checksum = crc32(content);const mode = fs.statSync(file.absolute).mode & 0o111 ? 0o755 : 0o644;const local = localHeader({@@ -133,8 +133,8 @@ for (const file of files) {const centralOffset = offset;const centralSize = centralParts.reduce((total, part) => total + part.length, 0);const entryCount = files.length;-requireZip32(centralOffset <= ZIP32_MAX_VALUE, `central directory offset ${centralOffset} is too large`);-requireZip32(centralSize <= ZIP32_MAX_VALUE, `central directory size ${centralSize} is too large`);+requireZip32(centralOffset < ZIP32_MAX_VALUE, `central directory offset ${centralOffset} reaches the ZIP64 sentinel`);+requireZip32(centralSize < ZIP32_MAX_VALUE, `central directory size ${centralSize} reaches the ZIP64 sentinel`);const end = Buffer.alloc(22);end.writeUInt32LE(0x06054b50, 0);