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(packaging): make the canonical archify.zip reproducible on Windows (#385)
Chaoran Hu93ffea49f032
diff --git a/archify/test/clean-skill-staging.test.mjs b/archify/test/clean-skill-staging.test.mjsindex df19d201..59d455c1 100644--- a/archify/test/clean-skill-staging.test.mjs+++ b/archify/test/clean-skill-staging.test.mjs@@ -113,6 +113,122 @@ test('clean staging preserves index modes and strips repository-only package met}});+test('clean staging records Git index modes in a manifest outside the staged tree', () => {+ const root = repositoryFixture();+ const destination = path.join(root, 'staged-skill');+ const manifest = path.join(root, 'staged-modes.json');+ try {+ write(root, 'archify/bin/executable.mjs', '#!/usr/bin/env node\n');+ write(root, 'archify/renderers/shared/plain.mjs', 'export {};\n');+ git(root, ['add', 'archify']);+ // Set the index modes explicitly so the expectation does not depend on+ // whether this checkout can represent executable bits (core.fileMode).+ git(root, ['update-index', '--chmod=+x', 'archify/bin/executable.mjs']);+ git(root, ['update-index', '--chmod=-x', 'archify/renderers/shared/plain.mjs']);++ const result = stageCleanSkill({ repoRoot: root, destination, modeManifest: manifest });++ const recorded = JSON.parse(fs.readFileSync(manifest, 'utf8'));+ assert.equal(recorded['bin/executable.mjs'], '100755');+ assert.equal(recorded['renderers/shared/plain.mjs'], '100644');+ assert.deepEqual(result.modes, recorded);+ assert.deepEqual(Object.keys(recorded), [...Object.keys(recorded)].sort(), 'manifest keys are sorted');++ const stagedFiles = [];+ const walk = (directory, prefix) => {+ for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {+ const relative = prefix ? `${prefix}/${entry.name}` : entry.name;+ if (entry.isDirectory()) walk(path.join(directory, entry.name), relative);+ else stagedFiles.push(relative);+ }+ };+ walk(destination, '');+ assert.deepEqual(+ Object.keys(recorded).sort(),+ stagedFiles.sort(),+ 'the manifest must list every staged file and nothing else',+ );+ } finally {+ fs.rmSync(root, { recursive: true, force: true });+ }+});++test('clean staging refuses to write the mode manifest inside the staged tree', () => {+ const root = repositoryFixture();+ const destination = path.join(root, 'staged-skill');+ try {+ git(root, ['add', 'archify']);+ const rejected = [+ destination,+ path.join(destination, 'modes.json'),+ path.join(destination, 'nested', 'modes.json'),+ ];+ for (const manifest of rejected) {+ assert.throws(+ () => stageCleanSkill({ repoRoot: root, destination, modeManifest: manifest }),+ /mode manifest must be written outside the staged Skill tree/,+ );+ assert.equal(fs.existsSync(destination), false, 'a rejected manifest location must not leave a staged tree behind');+ }+ } finally {+ fs.rmSync(root, { recursive: true, force: true });+ }+});++test('clean staging refuses an existing mode manifest path and leaves it untouched', () => {+ const root = repositoryFixture();+ const destination = path.join(root, 'staged-skill');+ const manifest = path.join(root, 'existing-modes.json');+ try {+ git(root, ['add', 'archify']);+ fs.writeFileSync(manifest, 'not ours\n');+ assert.throws(+ () => stageCleanSkill({ repoRoot: root, destination, modeManifest: manifest }),+ /mode manifest path already exists/,+ );+ assert.equal(fs.readFileSync(manifest, 'utf8'), 'not ours\n', 'an existing file at the manifest path must be preserved');+ assert.equal(fs.existsSync(destination), false, 'a refused manifest path must not leave a staged tree behind');+ } finally {+ fs.rmSync(root, { recursive: true, force: true });+ }+});++test('clean staging rejects a mode manifest that aliases the staged tree through a symlinked ancestor', (t) => {+ const root = repositoryFixture();+ const physical = path.join(root, 'physical');+ const alias = path.join(root, 'alias');+ try {+ git(root, ['add', 'archify']);+ fs.mkdirSync(physical);+ try {+ fs.symlinkSync(physical, alias, process.platform === 'win32' ? 'junction' : 'dir');+ } catch (error) {+ if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error?.code)) {+ t.skip(`symlinks unavailable: ${error.code}`);+ return;+ }+ throw error;+ }+ const cases = [+ { destination: path.join(alias, 'staged'), modeManifest: path.join(physical, 'staged', 'modes.json') },+ { destination: path.join(physical, 'staged'), modeManifest: path.join(alias, 'staged', 'modes.json') },+ ];+ for (const { destination, modeManifest } of cases) {+ assert.throws(+ () => stageCleanSkill({ repoRoot: root, destination, modeManifest }),+ /mode manifest must be written outside the staged Skill tree/,+ );+ assert.equal(+ fs.existsSync(path.join(physical, 'staged')),+ false,+ 'a rejected manifest location must not leave a staged tree behind',+ );+ }+ } finally {+ fs.rmSync(root, { recursive: true, force: true });+ }+});+test('clean staging rejects a symlink in a tracked file ancestor before copying bytes', (t) => {const root = repositoryFixture();const destination = path.join(root, 'staged-skill');diff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjsindex 1e3402e1..0cf1c487 100644--- a/archify/test/release-package-gates.test.mjs+++ b/archify/test/release-package-gates.test.mjs@@ -577,6 +577,155 @@ canonicalZipTest('archive build is byte-for-byte reproducible across caller time}});+test('archive build accepts Windows-style absolute output paths', {+ skip: process.platform !== 'win32'+ ? 'Windows drive paths only reach build-zip.sh on win32'+ : currentNodeMajor === canonicalZipNodeMajor+ ? false+ : `canonical ZIP builds require Node ${canonicalZipNodeMajor}`,+}, () => {+ const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-windows-path-'));+ const backslashArchive = path.win32.join(outputRoot, 'backslash.zip');+ const slashArchive = path.win32.join(outputRoot, 'slash.zip').replace(/\\/g, '/');+ // The \\.\ device-namespace form is a \\-prefixed absolute path like a UNC+ // share: MSYS passes it to bash unchanged from a native parent and Node+ // resolves it natively. A real network share cannot be assumed in the suite,+ // and the \\?\ extended-length prefix is stripped by MSYS's command-line+ // parsing when bash is started from a native process.+ const deviceArchive = `\\\\.\\${path.win32.join(outputRoot, 'device.zip')}`;++ try {+ for (const archive of [backslashArchive, slashArchive, deviceArchive]) {+ const build = spawnBuildZip(archive);+ assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);+ assert.ok(fs.existsSync(archive), `archive must be written to the requested path: ${archive}`);+ }+ const reference = fs.readFileSync(backslashArchive);+ for (const archive of [slashArchive, deviceArchive]) {+ assert.ok(+ reference.equals(fs.readFileSync(archive)),+ `every Windows path form must produce identical archive bytes: ${archive}`,+ );+ }+ assert.deepEqual(+ fs.readdirSync(outputRoot).sort(),+ ['backslash.zip', 'device.zip', 'slash.zip'],+ 'successful archive publication must not leave temporary files behind',+ );+ } finally {+ fs.rmSync(outputRoot, { recursive: true, force: true });+ }+});++function centralDirectoryModes(archive) {+ const buffer = fs.readFileSync(archive);+ const end = buffer.length - 22;+ assert.equal(buffer.readUInt32LE(end), 0x06054b50, 'archive must end with an end-of-central-directory record');+ const entryCount = buffer.readUInt16LE(end + 10);+ let offset = buffer.readUInt32LE(end + 16);+ const modes = {};+ for (let index = 0; index < entryCount; index += 1) {+ assert.equal(buffer.readUInt32LE(offset), 0x02014b50, 'central directory entry signature');+ const nameLength = buffer.readUInt16LE(offset + 28);+ const extraLength = buffer.readUInt16LE(offset + 30);+ const commentLength = buffer.readUInt16LE(offset + 32);+ const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength);+ modes[name] = (buffer.readUInt32LE(offset + 38) >>> 16) & 0o7777;+ offset += 46 + nameLength + extraLength + commentLength;+ }+ return modes;+}++function writeArchive(stagedRoot, archive, modeManifest) {+ const args = [path.join(repoRoot, 'scripts', 'write-deterministic-zip.mjs'), stagedRoot, archive];+ if (modeManifest !== null) args.push('--mode-manifest', modeManifest);+ return spawnSync(process.execPath, args, { encoding: 'utf8' });+}++function stagedFixture(files) {+ const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-zip-modes-'));+ const staged = path.join(fixture, 'archify');+ for (const [relative, { content, mode }] of Object.entries(files)) {+ const target = path.join(staged, ...relative.split('/'));+ fs.mkdirSync(path.dirname(target), { recursive: true });+ fs.writeFileSync(target, content);+ fs.chmodSync(target, mode);+ }+ return { fixture, staged };+}++test('archive writer records Git index modes from the manifest, not filesystem bits', () => {+ const { fixture, staged } = stagedFixture({+ 'bin/tool.mjs': { content: '#!/usr/bin/env node\n', mode: 0o644 },+ 'docs/notes.txt': { content: 'notes\n', mode: 0o755 },+ });+ try {+ const manifest = path.join(fixture, 'modes.json');+ fs.writeFileSync(manifest, JSON.stringify({ 'bin/tool.mjs': '100755', 'docs/notes.txt': '100644' }));++ const first = path.join(fixture, 'first.zip');+ const build = writeArchive(staged, first, manifest);+ assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);+ assert.deepEqual(centralDirectoryModes(first), {+ 'archify/bin/tool.mjs': 0o755,+ 'archify/docs/notes.txt': 0o644,+ });++ // Flip the on-disk bits; the recorded modes must still decide the bytes.+ fs.chmodSync(path.join(staged, 'bin', 'tool.mjs'), 0o755);+ fs.chmodSync(path.join(staged, 'docs', 'notes.txt'), 0o644);+ const second = path.join(fixture, 'second.zip');+ const rebuild = writeArchive(staged, second, manifest);+ assert.equal(rebuild.status, 0, `${rebuild.stdout}\n${rebuild.stderr}`);+ assert.ok(+ fs.readFileSync(first).equals(fs.readFileSync(second)),+ 'archive bytes must not depend on filesystem permission bits',+ );+ } finally {+ fs.rmSync(fixture, { recursive: true, force: true });+ }+});++test('archive writer fails closed when the mode manifest and the staged tree disagree', () => {+ const { fixture, staged } = stagedFixture({+ 'bin/tool.mjs': { content: '#!/usr/bin/env node\n', mode: 0o755 },+ 'docs/notes.txt': { content: 'notes\n', mode: 0o644 },+ });+ try {+ const archive = path.join(fixture, 'out.zip');+ const cases = [+ [null, /--mode-manifest/, 2],+ [{ 'bin/tool.mjs': '100755' }, /no recorded Git mode: docs\/notes\.txt/, 1],+ [{ 'bin/tool.mjs': '100755', 'docs/notes.txt': '100644', 'extra.txt': '100644' }, /not staged: extra\.txt/, 1],+ [{ 'bin/tool.mjs': '100777', 'docs/notes.txt': '100644' }, /unsupported Git mode "100777"/, 1],+ ];+ for (const [manifestContent, expected, status] of cases) {+ let manifest = null;+ if (manifestContent !== null) {+ manifest = path.join(fixture, 'modes.json');+ fs.writeFileSync(manifest, JSON.stringify(manifestContent));+ }+ const build = writeArchive(staged, archive, manifest);+ assert.equal(build.status, status, `${build.stdout}\n${build.stderr}`);+ assert.match(build.stderr, expected);+ assert.equal(fs.existsSync(archive), false, 'a rejected build must not publish an archive');+ assert.deepEqual(+ fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),+ [],+ 'a rejected build must not leave temporary files behind',+ );+ }+ } finally {+ fs.rmSync(fixture, { recursive: true, force: true });+ }+});++test('archive build hands the recorded Git index modes from the stager to the writer', () => {+ const buildSource = fs.readFileSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), 'utf8');+ assert.match(buildSource, /stage-clean-skill\.mjs[\s\S]*?--mode-manifest "\$stage\/modes\.json"/);+ assert.match(buildSource, /write-deterministic-zip\.mjs"[^\n]*\n\s*--mode-manifest "\$stage\/modes\.json"/);+});+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');diff --git a/scripts/build-zip.sh b/scripts/build-zip.shindex c6c863e5..cc686bdf 100755--- a/scripts/build-zip.sh+++ b/scripts/build-zip.sh@@ -5,7 +5,12 @@ set -euo pipefailrepo_root="$(cd "$(dirname "$0")/.." && pwd)"out="${1:-$repo_root/archify.zip}"-if [[ "$out" != /* ]]; then+# Git Bash callers may pass Windows-style absolute paths: drive paths (C:\...+# or C:/...) and \\-prefixed forms such as UNC shares or the \\?\ extended-length+# prefix. Node resolves those natively, so only genuinely relative paths get the+# cwd prefix; prefixing a Windows path would send MSYS a malformed mixed path.+windows_absolute='^([A-Za-z]:[/\\]|\\\\)'+if [[ "$out" != /* && ! "$out" =~ $windows_absolute ]]; thenout="$(pwd)/$out"fi@@ -28,8 +33,12 @@ stage="$(mktemp -d)"trap 'rm -rf "$stage"' EXITnode "$repo_root/scripts/stage-clean-skill.mjs" \--root "$repo_root" \- --dest "$stage/archify" >/dev/null+ --dest "$stage/archify" \+ --mode-manifest "$stage/modes.json" >/dev/null-node "$repo_root/scripts/write-deterministic-zip.mjs" "$stage/archify" "$out"+# Entry modes come from the recorded Git index modes, not from stat(), so the+# archive bytes do not depend on the building platform's permission support.+node "$repo_root/scripts/write-deterministic-zip.mjs" "$stage/archify" "$out" \+ --mode-manifest "$stage/modes.json"echo "built $out"diff --git a/scripts/stage-clean-skill.mjs b/scripts/stage-clean-skill.mjsindex 9515a305..fc1fd16c 100644--- a/scripts/stage-clean-skill.mjs+++ b/scripts/stage-clean-skill.mjs@@ -181,6 +181,23 @@ function snapshotSourceEntry(entry) {}}+function canonicalizeExistingPrefix(target) {+ // realpathSync rejects paths that do not exist yet, so resolve the deepest+ // existing ancestor through symlinks and re-append the missing tail.+ const pending = [];+ let current = path.resolve(target);+ for (;;) {+ try {+ return path.join(fs.realpathSync(current), ...pending);+ } catch {+ const parent = path.dirname(current);+ if (parent === current) return path.join(current, ...pending);+ pending.unshift(path.basename(current));+ current = parent;+ }+ }+}+function cleanPackageManifest(destination) {const packagePath = path.join(destination, 'package.json');const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));@@ -219,13 +236,43 @@ function validateThirdPartyNoticeInputs(repoRoot, packageEntries) {}}-export function stageCleanSkill({ repoRoot = scriptRoot, destination }) {+export function stageCleanSkill({ repoRoot = scriptRoot, destination, modeManifest = null }) {const resolvedRoot = fs.realpathSync(path.resolve(repoRoot));if (!destination) throw new Error('clean Skill staging requires a destination');const resolvedDestination = path.resolve(destination);if (fs.existsSync(resolvedDestination)) {throw new Error(`clean Skill staging destination already exists: ${resolvedDestination}`);}+ // The manifest records each staged file's Git index mode for the archive+ // writer. Filesystem permission bits are not portable (Windows cannot store+ // an executable bit), so the archive must not re-derive modes from stat.+ const resolvedModeManifest = modeManifest === null ? null : path.resolve(modeManifest);+ if (resolvedModeManifest !== null) {+ // Compare physical locations: a symlinked ancestor on either side must not+ // let the manifest land inside the staged tree, where the writer would see+ // an unrecorded file and refuse the archive.+ const canonicalDestination = canonicalizeExistingPrefix(resolvedDestination);+ const canonicalManifest = canonicalizeExistingPrefix(resolvedModeManifest);+ const relativeToDestination = path.relative(canonicalDestination, canonicalManifest);+ const outsideDestination = relativeToDestination === '..'+ || relativeToDestination.startsWith(`..${path.sep}`)+ || path.isAbsolute(relativeToDestination);+ if (!outsideDestination) {+ throw new Error(`mode manifest must be written outside the staged Skill tree: ${resolvedModeManifest}`);+ }+ // The manifest belongs to this invocation only: never overwrite, and never+ // later remove, a file that already existed at that path.+ let manifestExists = true;+ try {+ fs.lstatSync(resolvedModeManifest);+ } catch (error) {+ if (error.code !== 'ENOENT') throw error;+ manifestExists = false;+ }+ if (manifestExists) {+ throw new Error(`mode manifest path already exists: ${resolvedModeManifest}`);+ }+ }const entries = trackedEntries(resolvedRoot);for (const entry of entries) {@@ -247,8 +294,15 @@ export function stageCleanSkill({ repoRoot = scriptRoot, destination }) {.map((entry) => snapshotSourceEntry(entry));validateThirdPartyNoticeInputs(resolvedRoot, packageEntries);+ const modes = Object.fromEntries(+ packageEntries+ .map((entry) => [entry.relative.slice('archify/'.length), entry.mode])+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),+ );+fs.mkdirSync(resolvedDestination, { recursive: true, mode: 0o755 });let fileCount = 0;+ let manifestWritten = false;try {for (const entry of packageEntries) {const relativeInsideSkill = entry.relative.slice('archify/'.length);@@ -260,12 +314,17 @@ export function stageCleanSkill({ repoRoot = scriptRoot, destination }) {fileCount += 1;}cleanPackageManifest(resolvedDestination);+ if (resolvedModeManifest !== null) {+ fs.writeFileSync(resolvedModeManifest, `${JSON.stringify(modes, null, 2)}\n`, { flag: 'wx' });+ manifestWritten = true;+ }} catch (error) {fs.rmSync(resolvedDestination, { recursive: true, force: true });+ if (manifestWritten) fs.rmSync(resolvedModeManifest, { force: true });throw error;}- return { destination: resolvedDestination, fileCount };+ return { destination: resolvedDestination, fileCount, modes };}function isMainModule() {@@ -280,11 +339,15 @@ function isMainModule() {if (isMainModule()) {try {+ const modeManifest = argument('--mode-manifest');const result = stageCleanSkill({repoRoot: argument('--root', scriptRoot),destination: argument('--dest'),+ modeManifest,});- process.stdout.write(`${JSON.stringify(result)}\n`);+ const summary = { destination: result.destination, fileCount: result.fileCount };+ if (modeManifest) summary.modeManifest = path.resolve(modeManifest);+ process.stdout.write(`${JSON.stringify(summary)}\n`);} catch (error) {process.stderr.write(`${error.message}\n`);process.exitCode = 1;diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjsindex a33c56eb..a4297144 100644--- a/scripts/write-deterministic-zip.mjs+++ b/scripts/write-deterministic-zip.mjs@@ -5,14 +5,64 @@ 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);-if (!rootArg || !outputArg) {- console.error('Usage: node scripts/write-deterministic-zip.mjs <directory> <output.zip>');+function usage() {+ console.error('Usage: node scripts/write-deterministic-zip.mjs <directory> <output.zip> --mode-manifest <modes.json>');process.exit(2);}+const positionals = [];+let modeManifestArg = null;+const argv = process.argv.slice(2);+for (let index = 0; index < argv.length; index += 1) {+ if (argv[index] === '--mode-manifest') {+ modeManifestArg = argv[index + 1] ?? null;+ index += 1;+ } else if (argv[index].startsWith('--')) {+ usage();+ } else {+ positionals.push(argv[index]);+ }+}+const [rootArg, outputArg] = positionals;+if (!rootArg || !outputArg || positionals.length !== 2 || !modeManifestArg) usage();+const root = path.resolve(rootArg);const output = path.resolve(outputArg);++// Entry modes come from the Git index, recorded by scripts/stage-clean-skill.mjs.+// Filesystem permission bits are not portable across platforms (Windows cannot+// store an executable bit), so deriving them from stat() would change the+// archive bytes depending on where it was built.+function loadModeManifest(manifestPath) {+ let parsed;+ try {+ parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));+ } catch (error) {+ throw new Error(`unreadable mode manifest ${manifestPath}: ${error.message}`);+ }+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {+ throw new Error(`mode manifest must be a JSON object: ${manifestPath}`);+ }+ const modes = new Map();+ for (const [relative, gitMode] of Object.entries(parsed)) {+ if (gitMode !== '100644' && gitMode !== '100755') {+ throw new Error(`unsupported Git mode ${JSON.stringify(gitMode)} for ${relative} in mode manifest`);+ }+ modes.set(relative, gitMode === '100755' ? 0o755 : 0o644);+ }+ return modes;+}++const recordedModes = loadModeManifest(path.resolve(modeManifestArg));+const unusedModes = new Set(recordedModes.keys());++function recordedMode(relative) {+ if (!recordedModes.has(relative)) {+ throw new Error(`staged file has no recorded Git mode: ${relative}`);+ }+ unusedModes.delete(relative);+ return recordedModes.get(relative);+}const UTF8_FLAG = 0x0800;const DEFLATE_METHOD = 8;const DOS_TIME = 0;@@ -108,7 +158,7 @@ for (const file of files) {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 mode = recordedMode(file.relative);const local = localHeader({name,crc: checksum,@@ -129,6 +179,9 @@ for (const file of files) {);offset += local.length + name.length + compressed.length;}+if (unusedModes.size > 0) {+ throw new Error(`mode manifest lists files that were not staged: ${[...unusedModes].sort().join(', ')}`);+}const centralOffset = offset;const centralSize = centralParts.reduce((total, part) => total + part.length, 0);