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): protect canonical archive publication
sunsunsuneed82c9ebd51
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 3560d5f9..0590f2d7 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -57,19 +57,16 @@ jobs:echo "make_latest=true" >> "$GITHUB_OUTPUT"fi- name: Build skill archive- run: scripts/build-zip.sh+ run: scripts/build-zip.sh /tmp/archify-built.zip- name: Validate the exact release archive without installing dependenciesrun: |set -euo pipefailpackage_root="$RUNNER_TEMP/archify-release-package"mkdir -p "$package_root"- unzip -q archify.zip -d "$package_root"+ unzip -q /tmp/archify-built.zip -d "$package_root"node scripts/package-smoke.mjs "$package_root/archify"- name: Committed zip must match the build (same gate as CI)- run: |- cp archify.zip /tmp/archify-built.zip- git checkout HEAD -- archify.zip- cmp -s /tmp/archify-built.zip archify.zip+ run: 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/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjsindex 90813fda..a8774832 100644--- a/archify/test/release-package-gates.test.mjs+++ b/archify/test/release-package-gates.test.mjs@@ -35,16 +35,15 @@ test('release smokes the exact archive built for the release before freshness anassert.ok(workflow.indexOf(tagGate) < workflow.indexOf(build), 'tag/version gate must precede the release build');assert.ok(workflow.indexOf(build) < workflow.indexOf(smoke), 'release smoke must follow the archive build');- assert.ok(workflow.indexOf(smoke) < workflow.indexOf(freshness), 'release smoke must inspect the built archive before it is restored');+ assert.ok(workflow.indexOf(smoke) < workflow.indexOf(freshness), 'release smoke must inspect the built archive before comparison');assert.ok(workflow.indexOf(freshness) < workflow.indexOf(upload), 'freshness must pass before release upload');assert.match(tagGate, /require\('\.\/archify\/package\.json'\)\.version/);assert.match(tagGate, /GITHUB_REF_NAME#v/);- assert.match(build, /run: scripts\/build-zip\.sh/);- assert.match(smoke, /unzip -q archify\.zip -d "\$package_root"/);+ assert.match(build, /run: scripts\/build-zip\.sh \/tmp\/archify-built\.zip/);+ assert.match(smoke, /unzip -q \/tmp\/archify-built\.zip -d "\$package_root"/);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, /cmp -s \/tmp\/archify-built\.zip archify\.zip/);assert.match(upload, /files: archify\.zip/);});@@ -175,6 +174,59 @@ test('archive build excludes untracked files and external symlinks from the live}});+test('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');+ const license = path.join(skill, 'LICENSE');+ const archive = path.join(fixture, 'trusted.zip');+ const trusted = Buffer.from('trusted archive bytes');+ const git = (args, options = {}) => spawnSync('git', args, {+ cwd: fixture,+ encoding: 'utf8',+ ...options,+ });++ try {+ fs.mkdirSync(path.join(skill, 'renderers', 'shared'), { recursive: true });+ fs.mkdirSync(scripts);+ fs.copyFileSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), path.join(scripts, 'build-zip.sh'));+ fs.copyFileSync(+ path.join(repoRoot, 'scripts', 'write-deterministic-zip.mjs'),+ path.join(scripts, 'write-deterministic-zip.mjs'),+ );+ fs.writeFileSync(path.join(skill, 'renderers', 'shared', 'generated-validators.mjs'), 'export default {};\n');+ fs.writeFileSync(path.join(skill, 'package.json'), '{"name":"archify"}\n');+ fs.writeFileSync(license, 'base\n');+ assert.equal(git(['init']).status, 0);+ assert.equal(git(['add', '.']).status, 0);++ const base = git(['hash-object', '-w', '--stdin'], { input: 'base\n' });+ const ours = git(['hash-object', '-w', '--stdin'], { input: 'ours\n' });+ const theirs = git(['hash-object', '-w', '--stdin'], { input: 'theirs\n' });+ for (const result of [base, ours, theirs]) assert.equal(result.status, 0, result.stderr);+ const indexInfo = [+ `100644 ${base.stdout.trim()} 1\tarchify/LICENSE`,+ `100644 ${ours.stdout.trim()} 2\tarchify/LICENSE`,+ `100644 ${theirs.stdout.trim()} 3\tarchify/LICENSE`,+ '',+ ].join('\n');+ assert.equal(git(['update-index', '--index-info'], { input: indexInfo }).status, 0);+ fs.writeFileSync(license, '<<<<<<< ours\n=======\n>>>>>>> theirs\n');+ fs.writeFileSync(archive, trusted);++ const build = spawnSync('bash', [path.join(scripts, 'build-zip.sh'), archive], {+ cwd: fixture,+ encoding: 'utf8',+ });+ 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');+ } finally {+ fs.rmSync(fixture, { recursive: true, force: true });+ }+});+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');@@ -203,9 +255,11 @@ test('archive build is byte-for-byte reproducible across caller time zones withofs.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/);+ assert.deepEqual(+ fs.readdirSync(outputRoot).sort(),+ ['honolulu.zip', 'utc.zip'],+ 'successful archive publication must not leave temporary files behind',+ );} finally {fs.rmSync(outputRoot, { recursive: true, force: true });}@@ -228,5 +282,4 @@ 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/integrations/deepseek-harness/scripts/distribution-acceptance.mjs b/integrations/deepseek-harness/scripts/distribution-acceptance.mjsindex 2d9af956..36fd4298 100644--- a/integrations/deepseek-harness/scripts/distribution-acceptance.mjs+++ b/integrations/deepseek-harness/scripts/distribution-acceptance.mjs@@ -22,7 +22,7 @@ const receipt = {dsh: { spec: DSH_SPEC },node: process.version,platform: process.platform,- zipContainerNote: 'Fresh builder ZIP vs committed ZIP: unzip contents match; ZIP container bytes do not. Existing baseline behavior, not a DSH regression.',+ zipContainerNote: 'Canonical Linux CI verifies ZIP container bytes; cross-platform DSH acceptance verifies extracted package content.',stages: [],};@@ -413,8 +413,9 @@ const skipFreshZipRebuild = process.platform === 'win32';const committedZip = path.join(repoRoot, 'archify.zip');const packedSkill = path.join(inspectRoot, 'package', 'skills', 'archify');let unzipContentsIdentical = false;+let canonicalZipBytes = 'not-asserted';if (skipFreshZipRebuild) {- receipt.zipContainerNote = 'Fresh ZIP rebuild skipped on Windows (rsync/zip are not on GitHub Windows runners). Used committed archify.zip for content comparison; known text files normalize checkout CRLF while all other files remain byte-exact. ZIP container bytes are already known non-reproducible.';+ receipt.zipContainerNote = 'Windows validates committed ZIP contents with checkout text EOL normalization; canonical container-byte reproduction is owned by Linux CI.';const checkedDir = path.join(scratch, 'checked');fs.mkdirSync(checkedDir);fs.copyFileSync(committedZip, path.join(checkedDir, 'committed.zip'));@@ -437,6 +438,12 @@ if (skipFreshZipRebuild) {if (unzipDiff.status !== 0) {fail('zero-regression', 'fresh ZIP contents drifted from the committed ZIP', { diff: unzipDiff.stdout });}+ if (process.platform === 'linux') {+ if (!fs.readFileSync(freshZip).equals(fs.readFileSync(committedZip))) {+ fail('zero-regression', 'canonical Linux ZIP bytes drifted from the committed archive');+ }+ canonicalZipBytes = 'verified';+ }unzipContentsIdentical = true;}const skillsList = run('npx', ['-y', 'skills', 'add', repoRoot, '--list', '--full-depth'], { cwd: repoRoot, timeout: 120_000 });@@ -445,7 +452,8 @@ pass('zero-regression', {archifyZipBlob: zipBlob.stdout.trim(),archifyPackageBlob: pkgBlob.stdout.trim(),unzipContentsIdentical,- zipContainerBytesReproducible: false,+ canonicalZipBytes,+ crossPlatformZipCheck: 'extracted-content',...(skipFreshZipRebuild ? { freshZipRebuildSkipped: true, checkoutTextEolNormalized: true } : {}),skillsCli: skillsList.stdout.trim().slice(0, 500),});diff --git a/integrations/deepseek-harness/test/package-contract.test.mjs b/integrations/deepseek-harness/test/package-contract.test.mjsindex f9a08e15..5043ca34 100644--- a/integrations/deepseek-harness/test/package-contract.test.mjs+++ b/integrations/deepseek-harness/test/package-contract.test.mjs@@ -80,3 +80,14 @@ test('distribution acceptance reserves stdout for its machine-readable JSON receassert.doesNotMatch(source, /stdio:\s*['"]inherit['"]/);assert.equal([...source.matchAll(/process\.stdout\.write/g)].length, 2);});++test('distribution receipt separates canonical ZIP bytes from cross-platform content checks', () => {+ const source = fs.readFileSync(+ path.join(integrationRoot, 'scripts', 'distribution-acceptance.mjs'),+ 'utf8',+ );+ assert.match(source, /canonicalZipBytes/);+ assert.match(source, /crossPlatformZipCheck:\s*'extracted-content'/);+ assert.doesNotMatch(source, /zipContainerBytesReproducible/);+ assert.doesNotMatch(source, /rsync\/zip are not on GitHub Windows runners/);+});diff --git a/scripts/build-zip.sh b/scripts/build-zip.shindex 127dd185..ad402bc1 100755--- a/scripts/build-zip.sh+++ b/scripts/build-zip.sh@@ -9,9 +9,11 @@ if [[ "$out" != /* ]]; thenout="$(pwd)/$out"fi-# Stage only files tracked by Git. This keeps untracked working-tree content out-# of the archive, and rejecting tracked paths that are symlinks prevents an-# archive build from reading through links to content outside the repository.+# 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.+# Rejecting tracked paths that are symlinks prevents an archive build from+# reading through links to content outside the repository.# test/ is repo-only (the golden harness compares against ../examples at the# repo root, which does not exist in an installed skill). The npm scripts and# build-only dependencies are stripped from the shipped package.json. Runtime@@ -27,6 +29,11 @@ while IFS= read -r -d '' record; dometadata="${record%%$'\t'*}"tracked="${record#*$'\t'}"tracked_mode="${metadata%% *}"+ tracked_stage="${metadata##* }"+ if [[ "$tracked_stage" != 0 ]]; then+ echo "refusing to package unmerged index entry (stage $tracked_stage): $tracked" >&2+ exit 1+ ficase "$tracked" inarchify/test | archify/test/* | \archify/package-lock.json | \@@ -68,7 +75,6 @@ node -e ""rm -f "$stage/archify/package-lock.json"-rm -f "$out"node "$repo_root/scripts/write-deterministic-zip.mjs" "$stage/archify" "$out"echo "built $out"diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjsindex c9d6c319..d392a880 100644--- a/scripts/write-deterministic-zip.mjs+++ b/scripts/write-deterministic-zip.mjs@@ -2,6 +2,7 @@import fs from 'node:fs';import path from 'node:path';+import { randomBytes } from 'node:crypto';import { constants as zlibConstants, deflateRawSync } from 'node:zlib';const [rootArg, outputArg] = process.argv.slice(2);@@ -16,6 +17,13 @@ const UTF8_FLAG = 0x0800;const DEFLATE_METHOD = 8;const DOS_TIME = 0;const DOS_DATE = 0x0021; // 1980-01-01, the earliest ZIP timestamp.+const ZIP32_MAX_ENTRIES = 0xffff;+const ZIP32_MAX_NAME_BYTES = 0xffff;+const ZIP32_MAX_VALUE = 0xffffffff;++function requireZip32(condition, detail) {+ if (!condition) throw new Error(`ZIP64 is not supported: ${detail}`);+}function crc32(buffer) {let crc = 0xffffffff;@@ -84,8 +92,10 @@ function centralHeader({ name, crc, compressedSize, uncompressedSize, offset, moconst localParts = [];const centralParts = [];let offset = 0;+const files = sortedEntries(root);+requireZip32(files.length <= ZIP32_MAX_ENTRIES, `entry count ${files.length} exceeds ${ZIP32_MAX_ENTRIES}`);-for (const file of sortedEntries(root)) {+for (const file of files) {const name = Buffer.from(`${path.basename(root)}/${file.relative}`, 'utf8');const content = fs.readFileSync(file.absolute);const compressed = deflateRawSync(content, {@@ -93,6 +103,10 @@ for (const file of sortedEntries(root)) {memLevel: 9,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}`);const checksum = crc32(content);const mode = fs.statSync(file.absolute).mode & 0o111 ? 0o755 : 0o644;const local = localHeader({@@ -118,10 +132,9 @@ for (const file of sortedEntries(root)) {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 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`);const end = Buffer.alloc(22);end.writeUInt32LE(0x06054b50, 0);@@ -133,5 +146,21 @@ end.writeUInt32LE(centralSize, 12);end.writeUInt32LE(centralOffset, 16);end.writeUInt16LE(0, 20);-fs.writeFileSync(output, Buffer.concat([...localParts, ...centralParts, end]));+const archive = Buffer.concat([...localParts, ...centralParts, end]);+const temporary = path.join(+ path.dirname(output),+ `.${path.basename(output)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`,+);+let descriptor;+try {+ descriptor = fs.openSync(temporary, 'wx', 0o666);+ fs.writeFileSync(descriptor, archive);+ fs.fsyncSync(descriptor);+ fs.closeSync(descriptor);+ descriptor = undefined;+ fs.renameSync(temporary, output);+} finally {+ if (descriptor !== undefined) fs.closeSync(descriptor);+ fs.rmSync(temporary, { force: true });+}console.log(`built ${output} (${entryCount} files)`);