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
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { parse } from 'yaml';
import { stageCleanSkill } from '../scripts/stage-clean-skill.mjs';
import { verifyPackagedUpdateChecker } from '../scripts/package-update-smoke.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(__dirname, '..');
const canonicalZipNodeMajor = 22;
const canonicalZipZlibVersion = '1.3.1-e00f703';
const currentNodeMajor = Number(process.versions.node.split('.')[0]);
const canonicalZipSkip = currentNodeMajor === canonicalZipNodeMajor && process.versions.zlib === canonicalZipZlibVersion
? false
: `canonical ZIP builds require Node ${canonicalZipNodeMajor} with bundled zlib ${canonicalZipZlibVersion}`;
const canonicalZipTest = (name, fn) => test(name, {
skip: canonicalZipSkip,
}, fn);
function spawnBuildZip(outputPath, options = {}) {
const script = path.join(repoRoot, 'scripts', 'build-zip.sh');
const { cwd = repoRoot, env = process.env, ...rest } = options;
const bashCandidates = process.platform === 'win32'
? [
process.env.BASH,
'C:\\Program Files\\Git\\bin\\bash.exe',
'bash',
].filter(Boolean)
: ['bash'];
for (const bash of bashCandidates) {
if (bash.includes('\\') && !fs.existsSync(bash)) continue;
// Native Windows argv decoding and MSYS path conversion must not alter
// the deliberately unsafe raw spelling before the validator sees it.
const result = spawnSync(bash, [
'-c', 'exec bash "$ARCHIFY_ZIP_BUILD_SCRIPT" "$ARCHIFY_ZIP_BUILD_OUTPUT"',
], {
cwd,
encoding: 'utf8',
...rest,
env: {
...env,
ARCHIFY_ZIP_BUILD_SCRIPT: script,
ARCHIFY_ZIP_BUILD_OUTPUT: outputPath,
MSYS2_ARG_CONV_EXCL: outputPath,
},
});
if (result.status !== 127) return result;
}
return spawnSync(script, [outputPath], { cwd, env, encoding: 'utf8', ...rest });
}
function preparePackageIndex(indexPath, extraPaths) {
const env = { ...process.env, GIT_INDEX_FILE: indexPath };
let result = spawnSync('git', ['read-tree', 'HEAD'], { cwd: repoRoot, env, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
result = spawnSync('git', ['rev-parse', 'HEAD:archify/LICENSE'], {
cwd: repoRoot,
encoding: 'utf8',
});
assert.equal(result.status, 0, result.stderr);
const blob = result.stdout.trim();
for (const relative of extraPaths) {
result = spawnSync('git', [
'-c', 'core.protectNTFS=false',
'-c', 'core.protectHFS=false',
'update-index', '--add', '--cacheinfo', '100644', blob, relative,
], { cwd: repoRoot, env, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
}
return env;
}
function workflowStep(workflow, name) {
const marker = ` - name: ${name}`;
const start = workflow.indexOf(marker);
assert.notEqual(start, -1, `workflow is missing the "${name}" step`);
const next = workflow.indexOf('\n - ', start + marker.length);
return workflow.slice(start, next === -1 ? workflow.length : next);
}
function workflowJob(workflow, name) {
const marker = `\n ${name}:\n`;
const start = workflow.indexOf(marker);
assert.notEqual(start, -1, `workflow is missing the "${name}" job`);
const next = workflow.slice(start + marker.length).search(/\n [a-z][a-z0-9-]*:\n/);
return workflow.slice(start, next === -1 ? workflow.length : start + marker.length + next);
}
function assertPinnedAction(section, action, sha, version) {
const expected = `uses: ${action}@${sha} # ${version}`;
assert.ok(
section.includes(expected),
`${action} must remain pinned to the reviewed ${version} commit (${sha})`,
);
}
test('release prevents manifest preannouncement and smokes the exact archive before upload', () => {
const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'release.yml'), 'utf8');
const tagFetch = workflowStep(workflow, 'Fetch exact tag object');
const tagGate = workflowStep(workflow, 'Tag must match package.json version');
const annotatedTagGate = workflowStep(workflow, 'Stable release tag must be annotated');
const publicationOrder = workflowStep(workflow, 'Stable notifier manifest must remain on the previous release');
const build = workflowStep(workflow, 'Build skill archive');
const smoke = workflowStep(workflow, 'Validate the exact release archive without installing dependencies');
const freshness = workflowStep(workflow, 'Committed zip must match the build (same gate as CI)');
const upload = workflowStep(workflow, 'Create GitHub Release with the zip attached');
const followUp = workflowStep(workflow, 'Record stable notifier publication follow-up');
assert.ok(workflow.indexOf(tagFetch) < workflow.indexOf(tagGate), 'the real tag object must be fetched before release identity checks');
assert.ok(workflow.indexOf(tagGate) < workflow.indexOf(publicationOrder), 'tag/version gate must precede the publication-order gate');
assert.ok(workflow.indexOf(tagGate) < workflow.indexOf(annotatedTagGate), 'tag/version gate must precede the annotated-tag gate');
assert.ok(workflow.indexOf(annotatedTagGate) < workflow.indexOf(publicationOrder), 'annotated-tag gate must precede the publication-order gate');
assert.ok(workflow.indexOf(publicationOrder) < workflow.indexOf(build), 'manifest preannouncement must fail before 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 comparison');
assert.ok(workflow.indexOf(freshness) < workflow.indexOf(upload), 'freshness must pass before release upload');
assert.ok(workflow.indexOf(upload) < workflow.indexOf(followUp), 'manifest follow-up must be recorded only after Release creation');
assert.match(tagFetch, /git fetch --force --no-tags origin/);
assert.match(tagFetch, /refs\/tags\/\$\{GITHUB_REF_NAME\}:refs\/tags\/\$\{GITHUB_REF_NAME\}/);
assert.match(tagGate, /require\('\.\/archify\/package\.json'\)\.version/);
assert.match(tagGate, /GITHUB_REF_NAME#v/);
assert.match(annotatedTagGate, /steps\.release-kind\.outputs\.prerelease == 'false'/);
assert.match(annotatedTagGate, /git cat-file -t "refs\/tags\/\$\{GITHUB_REF_NAME\}"/);
assert.match(annotatedTagGate, /stable releases require an annotated tag/);
assert.match(publicationOrder, /compareSemver\(published\.version, releasing\) >= 0/);
assert.match(publicationOrder, /publish the manifest in a follow-up commit/);
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, /cmp -s \/tmp\/archify-built\.zip archify\.zip/);
assertPinnedAction(
upload,
'softprops/action-gh-release',
'efb35369e0ad2afab669f228072c1b0d510eae64',
'v3.0.3',
);
assert.match(upload, /files: archify\.zip/);
assert.match(followUp, /docs\/skill-updates\/archify\/stable\.json/);
});
test('an exact tag fetch restores an annotated object after a SHA-only checkout', () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-release-tag-fetch-'));
const source = path.join(fixture, 'source');
const checkout = path.join(fixture, 'checkout');
const runGit = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8' });
try {
fs.mkdirSync(source);
assert.equal(runGit(source, ['init', '--quiet']).status, 0);
assert.equal(runGit(source, ['config', 'user.name', 'Archify Test']).status, 0);
assert.equal(runGit(source, ['config', 'user.email', '[email protected]']).status, 0);
fs.writeFileSync(path.join(source, 'release.txt'), 'release\n');
assert.equal(runGit(source, ['add', 'release.txt']).status, 0);
assert.equal(runGit(source, ['commit', '--quiet', '-m', 'release fixture']).status, 0);
assert.equal(runGit(source, ['tag', '-a', 'v1.0.0', '-m', 'Release v1.0.0']).status, 0);
const commit = runGit(source, ['rev-parse', 'HEAD']).stdout.trim();
fs.mkdirSync(checkout);
assert.equal(runGit(checkout, ['init', '--quiet']).status, 0);
assert.equal(runGit(checkout, ['remote', 'add', 'origin', source]).status, 0);
assert.equal(runGit(checkout, [
'fetch', '--no-tags', '--depth=1', 'origin',
`+${commit}:refs/tags/v1.0.0`,
]).status, 0);
assert.equal(runGit(checkout, ['cat-file', '-t', 'refs/tags/v1.0.0']).stdout.trim(), 'commit');
assert.equal(runGit(checkout, [
'fetch', '--force', '--no-tags', 'origin',
'+refs/tags/v1.0.0:refs/tags/v1.0.0',
]).status, 0);
assert.equal(runGit(checkout, ['cat-file', '-t', 'refs/tags/v1.0.0']).stdout.trim(), 'tag');
assert.equal(runGit(checkout, ['rev-parse', 'refs/tags/v1.0.0^{}']).stdout.trim(), commit);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('CI binds a public notifier manifest to the Release asset, tagged archive, and tag tree build', () => {
const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'ci.yml'), 'utf8');
const job = workflowJob(workflow, 'published-update-manifest');
assert.match(job, /validateStableUpdateManifest/);
assert.match(job, /releases\/latest/);
assert.match(job, /latest_stable_tag" != "v\$\{manifest_version\}"/);
assert.match(job, /releases\/tags\/v\$\{manifest_version\}/);
assert.match(job, /select\(\.draft == false and \.prerelease == false\)/);
assert.match(job, /select\(\.name == "archify\.zip"\)/);
assert.match(job, /releases\/assets\/\$\{release_asset_id\}/);
assert.match(job, /Accept: application\/octet-stream/);
assert.match(job, /refs\/tags\/v\$\{manifest_version\}:refs\/tags\/v\$\{manifest_version\}/);
assert.match(job, /git show "v\$\{manifest_version\}:archify\.zip" > "\$tagged_archive"/);
assert.match(job, /cmp -s "\$published_archive" "\$tagged_archive"/);
assert.match(job, /check-stable-update-manifest\.mjs/);
assert.match(job, /--archive "\$published_archive"/);
assert.match(job, /--tag "v\$\{manifest_version\}"/);
assert.match(job, /--source-ref "v\$\{manifest_version\}"/);
assert.match(job, /git worktree add --detach "\$tag_checkout" "v\$\{manifest_version\}"/);
assert.match(job, /"\$tag_checkout\/scripts\/build-zip\.sh" "\$rebuilt_archive"/);
assert.match(job, /cmp -s "\$rebuilt_archive" "\$tagged_archive"/);
assert.match(job, /manifest_version" == "2\.15\.0"/);
assert.match(job, /missing the deterministic archive builder/);
});
test('release docs disclose that mutable Release assets are verified only at deployment time', () => {
const design = fs.readFileSync(
path.join(repoRoot, 'docs', 'skill-embedded-optional-update-notifier-design.md'),
'utf8',
);
assert.match(design, /部署时点/);
assert.match(design, /部署后替换[^。]*不会自动触发复验/);
assert.match(design, /immutable release/i);
assert.doesNotMatch(design, /即使 Release 资产后来可被替换,也不能脱离/);
});
test('GitHub Pages deploys the verified website artifact only after every repository gate succeeds', () => {
const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'ci.yml'), 'utf8');
const job = workflowJob(workflow, 'deploy-pages');
assert.match(workflow, /push:\n branches: \[main, dev\]/);
assert.match(job, /if: github\.event_name == 'push' && github\.ref == 'refs\/heads\/main'/);
const jobs = parse(workflow).jobs;
const dependencies = jobs['deploy-pages'].needs;
for (const gate of ['test', 'canonical-test', 'webm-artifact', 'zip-freshness', 'published-update-manifest', 'package-smoke', 'windows-test-portability', 'website']) {
assert.ok(dependencies.includes(gate), `Pages deployment must require ${gate}`);
}
assert.match(job, /pages: write/);
assert.match(job, /id-token: write/);
assert.match(job, /repos\/\$\{GITHUB_REPOSITORY\}\/git\/ref\/heads\/main/);
assert.match(job, /current_main" == "\$GITHUB_SHA"/);
assert.match(job, /Skipping obsolete Pages deployment/);
assert.match(job, /if: steps\.deployment-head\.outputs\.current == 'true'/);
assertPinnedAction(
job,
'actions/configure-pages',
'45bfe0192ca1faeb007ade9deae92b16b8254a0d',
'v6.0.0',
);
// v5 delegates to upload-artifact v7 (Node 24); v4 still embeds Node 20.
assertPinnedAction(
job,
'actions/upload-pages-artifact',
'fc324d3547104276b827a68afc52ff2a11cc49c9',
'v5.0.0',
);
assertPinnedAction(
job,
'actions/download-artifact',
'd3f86a106a0bac45b974a628896c90dbdf5c8093',
'v4.3.0',
);
assert.match(job, /name: website-dist/);
assert.match(job, /path: website\/dist/);
assertPinnedAction(
job,
'actions/deploy-pages',
'cd2ce8fcbc39b97be8ca5fce6e763baed58fa128',
'v5.0.0',
);
const website = workflowJob(workflow, 'website');
assert.match(website, /npm run check && npm run build && npm test/);
assert.match(website, /ARCHIFY_SITE_ROOT:.*website\/dist/);
assertPinnedAction(
website,
'actions/upload-artifact',
'65462800fd760344b1a7b4382951275a0abb4808',
'v4.3.3',
);
assert.match(website, /name: website-dist/);
const browser = workflowJob(workflow, 'browser-regression');
assert.match(browser, /Run shared browser regression gate/);
assert.match(browser, /npm run test:browser -- --shard=\$\{\{ matrix\.shard \}\}\/2/);
const media = workflowJob(workflow, 'webm-artifact');
assert.match(media, /needs: \[scope, browser-regression, webm-decode\]/);
assert.match(media, /test "\$BROWSER_RESULT" = success/);
assert.match(media, /test "\$WEBM_RESULT" = success/);
assert.ok(jobs['canonical-test'].needs.includes('full-regression'), 'Pages must wait for the complete regression and adapter checks');
const packageSmoke = workflowJob(workflow, 'package-smoke');
assert.match(packageSmoke, /Verify delivery-lock ownership with real subprocesses/);
assert.match(packageSmoke, /Verify macOS opener stays behind delivery-lock release/);
const windows = workflowJob(workflow, 'windows-test-portability');
assert.match(windows, /node-version: \[22, 24\]/);
assert.match(windows, /Verify maintained Windows path contracts/);
assert.match(windows, /ARCHIFY_REQUIRE_WINDOWS_REAL_PATHS: '1'/);
});
test('release tags with a SemVer prerelease are marked prerelease and never become latest', () => {
const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'release.yml'), 'utf8');
const classifier = workflowStep(workflow, 'Classify stable and prerelease tags');
const upload = workflowStep(workflow, 'Create GitHub Release with the zip attached');
assert.ok(workflow.indexOf(classifier) < workflow.indexOf(upload), 'release kind must be known before upload');
assert.match(classifier, /version="\$\{GITHUB_REF_NAME#v\}"/);
assert.match(classifier, /validateLocalRelease/);
assert.match(classifier, /update-contract\.mjs/);
assert.match(classifier, /release\.version !== process\.argv\[1\]/);
assert.match(classifier, /if \[\[ "\$channel" == "development" \]\]/);
assert.match(classifier, /echo "prerelease=true" >> "\$GITHUB_OUTPUT"/);
assert.match(classifier, /echo "make_latest=false" >> "\$GITHUB_OUTPUT"/);
assert.match(classifier, /echo "prerelease=false" >> "\$GITHUB_OUTPUT"/);
assert.match(classifier, /echo "make_latest=true" >> "\$GITHUB_OUTPUT"/);
assert.match(upload, /prerelease: \$\{\{ steps\.release-kind\.outputs\.prerelease \}\}/);
assert.match(upload, /make_latest: \$\{\{ steps\.release-kind\.outputs\.make_latest \}\}/);
});
test('package smoke rejects every dependency or repository-only artifact', () => {
const packageSmoke = path.join(repoRoot, 'scripts', 'package-smoke.mjs');
const forbidden = [
{ relative: 'node_modules', kind: 'directory' },
{ relative: 'package-lock.json', kind: 'file' },
{ relative: path.join('scripts', 'generate-validators.mjs'), kind: 'file' },
{ relative: 'test', kind: 'directory' },
{ relative: '.hive', kind: 'directory' },
{ relative: '.workbuddy', kind: 'directory' },
];
for (const { relative, kind } of forbidden) {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-gate-'));
try {
fs.mkdirSync(path.join(fixture, 'bin'), { recursive: true });
fs.writeFileSync(path.join(fixture, 'bin', 'archify.mjs'), '');
const target = path.join(fixture, relative);
if (kind === 'directory') fs.mkdirSync(target, { recursive: true });
else {
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, '');
}
const result = spawnSync(process.execPath, [packageSmoke, fixture], { encoding: 'utf8' });
assert.notEqual(result.status, 0, `${relative} must fail package smoke`);
assert.match(
`${result.stdout}\n${result.stderr}`,
new RegExp(`packaged skill must not contain ${relative.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`),
`${relative} must be rejected explicitly`,
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
}
});
test('package smoke rejects a missing or modified distribution license', () => {
const packageSmoke = path.join(repoRoot, 'scripts', 'package-smoke.mjs');
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-license-gate-'));
try {
const staged = path.join(fixture, 'archify');
stageCleanSkill({ repoRoot, destination: staged });
const licensePath = path.join(staged, 'LICENSE');
fs.rmSync(licensePath);
let result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, 'missing LICENSE must fail package smoke');
assert.match(`${result.stdout}\n${result.stderr}`, /packaged skill is missing LICENSE/);
fs.copyFileSync(path.join(repoRoot, 'LICENSE'), licensePath);
for (const name of ['LICENSE', 'LICENSE-MIT', 'NOTICE']) {
const target = path.join(staged, name);
const original = fs.readFileSync(target);
fs.rmSync(target);
result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, `missing ${name} must fail package smoke`);
assert.ok(`${result.stdout}\n${result.stderr}`.includes(`packaged skill is missing ${name}`));
fs.writeFileSync(target, 'truncated notice');
result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, `modified ${name} must fail package smoke`);
assert.ok(`${result.stdout}\n${result.stderr}`.includes(`must byte-match the repository ${name}`));
fs.writeFileSync(target, original);
}
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('package smoke rejects missing, modified, or incomplete third-party notices', () => {
const packageSmoke = path.join(repoRoot, 'scripts', 'package-smoke.mjs');
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-notices-gate-'));
try {
const staged = path.join(fixture, 'archify');
stageCleanSkill({ repoRoot, destination: staged });
const noticesPath = path.join(staged, 'THIRD_PARTY_NOTICES.md');
fs.rmSync(noticesPath);
let result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, 'missing notices must fail package smoke');
assert.match(`${result.stdout}\n${result.stderr}`, /missing THIRD_PARTY_NOTICES\.md/);
const repositoryNotices = fs.readFileSync(path.join(repoRoot, 'THIRD_PARTY_NOTICES.md'), 'utf8');
fs.writeFileSync(noticesPath, repositoryNotices.replace('Simple Icons 16.28.0', 'Simple Icons'));
result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, 'modified notices must fail package smoke');
assert.match(`${result.stdout}\n${result.stderr}`, /must byte-match the repository notice/);
fs.writeFileSync(noticesPath, 'Simple Icons 16.28.0\n');
result = spawnSync(process.execPath, [packageSmoke, staged], { encoding: 'utf8' });
assert.notEqual(result.status, 0, 'incomplete notices must fail package smoke');
assert.match(`${result.stdout}\n${result.stderr}`, /packaged THIRD_PARTY_NOTICES\.md is incomplete/);
const comparisonRoot = path.join(fixture, 'comparison-root');
fs.mkdirSync(comparisonRoot);
fs.copyFileSync(path.join(repoRoot, 'LICENSE'), path.join(comparisonRoot, 'LICENSE'));
const synchronizedIncomplete = repositoryNotices
.replace(/## OpenAI mark[\s\S]*?## No additional rights granted/, '## No additional rights granted');
fs.writeFileSync(path.join(comparisonRoot, 'THIRD_PARTY_NOTICES.md'), synchronizedIncomplete);
fs.writeFileSync(noticesPath, synchronizedIncomplete);
result = spawnSync(process.execPath, [packageSmoke, staged], {
encoding: 'utf8',
env: {
...process.env,
ARCHIFY_PACKAGE_SMOKE_NOTICE_ROOT: comparisonRoot,
},
});
assert.notEqual(result.status, 0, 'byte-identical incomplete notices must fail package smoke');
assert.match(
`${result.stdout}\n${result.stderr}`,
/repository THIRD_PARTY_NOTICES\.md is incomplete; missing required disclosure: .*OpenAI/,
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('package smoke increments an arbitrary-precision SemVer patch without Number coercion', async () => {
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-bigint-version-'));
const skillRoot = path.join(scratch, 'archify');
try {
stageCleanSkill({ repoRoot, destination: skillRoot });
const packagePath = path.join(skillRoot, 'package.json');
const releasePath = path.join(skillRoot, 'skill-release.json');
const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
const release = JSON.parse(fs.readFileSync(releasePath, 'utf8'));
const version = '2.16.9007199254740993';
packageJson.version = version;
release.version = version;
release.channel = 'stable';
fs.writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
fs.writeFileSync(releasePath, `${JSON.stringify(release, null, 2)}\n`);
// The ordinary archive smoke owns renderer/distribution coverage. This
// version edge case needs only its real packaged notifier gate.
const smoke = await verifyPackagedUpdateChecker(skillRoot, path.join(scratch, 'update-cache'));
assert.equal(smoke.candidateVersion, '2.16.9007199254740994');
assert.equal(smoke.notifierReceipt.status, 'update_available');
} finally {
fs.rmSync(scratch, { recursive: true, force: true });
}
});
test('clean package staging rejects non-portable tracked names and entry collisions before copying', () => {
const cases = [
{
paths: ['archify/portable-gate/CON.txt'],
code: 'portable-path/windows-reserved-name',
},
{
paths: ['archify/portable-gate/Docs/one.txt', 'archify/portable-gate/docs/two.txt'],
code: 'portable-path/collision',
},
{
paths: [`archify/portable-gate/${'a'.repeat(256)}`],
code: 'portable-path/component-too-long',
},
];
for (const { paths, code } of cases) {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-portable-index-'));
const destination = path.join(fixture, 'staged');
const env = preparePackageIndex(path.join(fixture, 'index'), paths);
const previousIndex = process.env.GIT_INDEX_FILE;
try {
process.env.GIT_INDEX_FILE = env.GIT_INDEX_FILE;
assert.throws(
() => stageCleanSkill({ repoRoot, destination }),
(error) => error?.code === code,
);
assert.equal(fs.existsSync(destination), false, 'portable-name rejection must precede staging writes');
} finally {
if (previousIndex === undefined) delete process.env.GIT_INDEX_FILE;
else process.env.GIT_INDEX_FILE = previousIndex;
fs.rmSync(fixture, { recursive: true, force: true });
}
}
});
test('archive build rejects unsafe native output paths before creating files', () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-output-path-'));
try {
const cases = [
['C:drive-relative.zip', /\(drive-relative\)/],
['\\current-drive-rooted.zip', /\(current-drive-rooted\)/],
[String.raw`\\.\C:\device.zip`, /\(windows-device-namespace\)/],
[String.raw`//./C:/device.zip`, /\((?:current-drive-rooted|windows-device-namespace)\)/],
[String.raw`\\?\GLOBALROOT\Device\HarddiskVolume1\archive.zip`, /\(windows-device-namespace\)/],
[String.raw`//?/GLOBALROOT/Device/HarddiskVolume1/archive.zip`, /\((?:current-drive-rooted|windows-extended-root)\)/],
[String.raw`\\?\Device\HarddiskVolume1\archive.zip`, /\(windows-device-namespace\)/],
[String.raw`\\?\PIPE\archive.zip`, /\(windows-extended-root\)/],
[String.raw`\\?\foo.zip`, /\(windows-extended-root\)/],
[String.raw`\\?\Volume{00000000-0000-0000-0000-000000000000}\archive.zip`, /\(windows-extended-root\)/],
[String.raw`\\?\UNC\server`, /\(windows-extended-root\)/],
[String.raw`\\?\C:/archive.zip`, /\(windows-extended-separator\)/],
[String.raw`\\?\C:\folder\..\archive.zip`, /\(dot-segment\)/],
[String.raw`\\server.zip`, /\(windows-unc-root\)/],
[String.raw`\\`, /\(trailing-separator\)/],
[String.raw`\\\share\archive.zip`, /\(windows-unc-root\)/],
[String.raw`\\server\\archive.zip`, /\(windows-unc-root\)/],
[String.raw`\\server/share/archive.zip`, /\(windows-unc-root\)/],
[String.raw`archive.zip:stream`, /\(windows-ads\)/],
[String.raw`folder\safe.zip:stream`, /\(windows-ads\)/],
[String.raw`folder\CON.zip`, /\(windows-reserved-name\)/],
[String.raw`folder\NUL.zip`, /\(windows-reserved-name\)/],
[String.raw`folder.\archive.zip`, /\(windows-trailing-dot-space\)/],
[String.raw`folder \archive.zip`, /\(windows-trailing-dot-space\)/],
[String.raw`archive.zip/`, /\(trailing-separator\)/],
['folder\\archive.zip\\', /\(trailing-separator\)/],
[String.raw`bad<name.zip`, /\(windows-invalid-character\)/],
[String.raw`bad|name.zip`, /\(windows-invalid-character\)/],
[`folder\\${'x'.repeat(256)}.zip`, /\(component-too-long\)/],
];
for (const [output, expectedReason] of cases) {
const build = spawnBuildZip(output, { cwd: fixture });
assert.equal(build.status, 2, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /archive output is not a valid native filesystem path/);
assert.match(build.stderr, expectedReason);
assert.ok(build.stderr.includes(JSON.stringify(output)),
'the archive validator must receive the exact raw output spelling');
assert.deepEqual(fs.readdirSync(fixture), [], 'a rejected output spelling must not create files');
}
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive build keeps unsafe-path diagnostics ahead of the canonical Node gate', {
skip: process.platform === 'win32' ? 'the POSIX node shim is unnecessary on the real Windows Node 24 lane' : false,
}, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-node-gate-order-'));
const shimDirectory = path.join(fixture, 'bin');
const nodeShim = path.join(shimDirectory, 'node');
fs.mkdirSync(shimDirectory);
fs.writeFileSync(nodeShim, `#!/usr/bin/env bash
if [[ "$1" == "-p" && "$2" == "process.versions.node" ]]; then
printf '%s\\n' '24.0.0'
exit 0
fi
exec "$ARCHIFY_REAL_NODE" "$@"
`);
fs.chmodSync(nodeShim, 0o755);
const env = {
...process.env,
ARCHIFY_REAL_NODE: process.execPath,
PATH: `${shimDirectory}${path.delimiter}${process.env.PATH || ''}`,
};
try {
const unsafe = spawnBuildZip('C:drive-relative.zip', { cwd: fixture, env });
assert.equal(unsafe.status, 2, `${unsafe.stdout}\n${unsafe.stderr}`);
assert.match(unsafe.stderr, /archive output is not a valid native filesystem path \(drive-relative\)/);
const safeParent = path.join(fixture, 'missing-parent');
const safeOutput = path.join(safeParent, 'safe.zip');
const safe = spawnBuildZip(safeOutput, { cwd: fixture, env });
assert.equal(safe.status, 1, `${safe.stdout}\n${safe.stderr}`);
assert.match(safe.stderr, /canonical archify[.]zip builds require Node 22 with bundled zlib /);
assert.match(safe.stderr, /\(current: Node 24[.]0[.]0, zlib [^)]+\)/);
assert.equal(fs.existsSync(safeOutput), false);
assert.equal(fs.existsSync(safeParent), false, 'path-only validation must not create output parents');
assert.deepEqual(fs.readdirSync(fixture).sort(), ['bin']);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive output rejection preserves an existing unsafe target byte-for-byte', {
skip: process.platform === 'win32' ? 'Windows cannot create the reserved-name fixture' : false,
}, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-output-preserve-'));
const output = path.join(fixture, 'CON.zip');
const sentinel = Buffer.from('existing archive sentinel\n');
try {
fs.writeFileSync(output, sentinel);
const build = spawnBuildZip(output, { cwd: fixture });
assert.equal(build.status, 2, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /archive output is not a valid native filesystem path/);
assert.ok(fs.readFileSync(output).equals(sentinel));
assert.deepEqual(fs.readdirSync(fixture), ['CON.zip']);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
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');
const build = spawnBuildZip(archive);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
const extracted = path.join(fixture, 'extracted');
fs.mkdirSync(extracted);
const unzip = spawnSync('unzip', ['-q', archive, '-d', extracted], { encoding: 'utf8' });
assert.equal(unzip.status, 0, `${unzip.stdout}\n${unzip.stderr}`);
const builtPackage = path.join(extracted, 'archify');
const dependencyFields = {
dependencies: { runtime: '1.0.0' },
devDependencies: { build: '1.0.0' },
optionalDependencies: { optional: '1.0.0' },
peerDependencies: { peer: '1.0.0' },
bundledDependencies: ['bundled'],
bundleDependencies: ['bundle-alias'],
};
const packagePath = path.join(builtPackage, 'package.json');
const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
// These failures stop at metadata validation, before running the package.
// Start each case from the pristine manifest without copying the whole ZIP.
for (const [field, value] of Object.entries(dependencyFields)) {
fs.writeFileSync(packagePath, `${JSON.stringify({ ...packageJson, [field]: value }, null, 2)}\n`);
const result = spawnSync(process.execPath, [path.join(repoRoot, 'scripts', 'package-smoke.mjs'), builtPackage], {
encoding: 'utf8',
});
assert.notEqual(result.status, 0, `${field} must fail package smoke`);
assert.match(`${result.stdout}\n${result.stderr}`, new RegExp(`dependency metadata: ${field}\\b`));
}
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
canonicalZipTest('built archives contain the embedded notifier runtime', () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-notifier-package-gate-'));
try {
const archive = path.join(fixture, 'archify.zip');
const build = spawnBuildZip(archive);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
const listing = spawnSync('unzip', ['-Z1', archive], { encoding: 'utf8' });
assert.equal(listing.status, 0, `${listing.stdout}\n${listing.stderr}`);
const entries = new Set(listing.stdout.trim().split('\n'));
assert.ok(entries.has('archify/skill-release.json'));
assert.ok(entries.has('archify/scripts/check-update.mjs'));
assert.ok(entries.has('archify/scripts/delivery-update-child.mjs'));
assert.ok(entries.has('archify/bin/delivery-update.mjs'));
assert.ok(entries.has('archify/scripts/update-contract.mjs'));
assert.ok(entries.has('archify/renderers/shared/atomic-output.mjs'));
assert.ok(entries.has('archify/renderers/shared/sidecar-path.mjs'));
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
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-'));
const externalTarget = path.join(externalRoot, 'secret.txt');
const externalLink = path.join(repoRoot, 'archify', `${marker}.link`);
const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-negative-'));
const archive = path.join(outputRoot, 'archify.zip');
try {
fs.writeFileSync(untracked, 'must not ship\n');
fs.writeFileSync(externalTarget, 'external content must not ship\n');
fs.symlinkSync(externalTarget, externalLink, 'file');
const build = spawnBuildZip(archive);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
const listing = spawnSync('unzip', ['-Z1', archive], { encoding: 'utf8' });
assert.equal(listing.status, 0, `${listing.stdout}\n${listing.stderr}`);
assert.doesNotMatch(listing.stdout, new RegExp(marker), 'untracked files and symlinks must not enter the archive');
} finally {
fs.rmSync(untracked, { force: true });
fs.rmSync(externalLink, { force: true });
fs.rmSync(externalRoot, { recursive: true, force: true });
fs.rmSync(outputRoot, { recursive: true, force: true });
}
});
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');
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(path.join(skill, 'scripts'), { 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.copyFileSync(
path.join(repoRoot, 'scripts', 'stage-clean-skill.mjs'),
path.join(scripts, 'stage-clean-skill.mjs'),
);
fs.copyFileSync(
path.join(repoRoot, 'scripts', 'third-party-notices-contract.mjs'),
path.join(scripts, 'third-party-notices-contract.mjs'),
);
fs.copyFileSync(
path.join(repoRoot, 'archify', 'renderers', 'shared', 'portable-path.mjs'),
path.join(skill, 'renderers', 'shared', 'portable-path.mjs'),
);
fs.copyFileSync(
path.join(repoRoot, 'archify', 'renderers', 'shared', 'path-semantics.mjs'),
path.join(skill, 'renderers', 'shared', 'path-semantics.mjs'),
);
fs.copyFileSync(
path.join(repoRoot, 'archify', 'renderers', 'shared', 'output-path.mjs'),
path.join(skill, 'renderers', 'shared', 'output-path.mjs'),
);
fs.copyFileSync(
path.join(repoRoot, 'archify', 'renderers', 'shared', 'atomic-output.mjs'),
path.join(skill, 'renderers', 'shared', 'atomic-output.mjs'),
);
fs.writeFileSync(path.join(skill, 'renderers', 'shared', 'generated-validators.mjs'), 'export default {};\n');
fs.writeFileSync(path.join(skill, 'scripts', 'check-update.mjs'), 'export {};\n');
fs.writeFileSync(path.join(skill, 'scripts', 'update-contract.mjs'), 'export {};\n');
fs.writeFileSync(path.join(skill, 'skill-release.json'), '{}\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.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 rejects incompatible zlib before publishing output', {
skip: currentNodeMajor !== canonicalZipNodeMajor ? 'requires Node 22 to isolate the zlib gate' : false,
}, () => {
const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-zlib-'));
try {
const archive = path.join(outputRoot, 'archify.zip');
const trusted = Buffer.from('existing canonical archive');
const preload = path.join(outputRoot, 'noncanonical-zlib.cjs');
fs.writeFileSync(preload, "Object.defineProperty(process.versions, 'zlib', { value: '0.0.0-test' });\n");
fs.writeFileSync(archive, trusted);
const build = spawnBuildZip(archive, {
env: { ...process.env, NODE_OPTIONS: `--require ${JSON.stringify(preload)}` },
});
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /canonical archify\.zip builds require Node 22 with bundled zlib/);
assert.match(build.stderr, /0\.0\.0-test/);
assert.ok(fs.readFileSync(archive).equals(trusted), 'toolchain rejection must preserve the canonical archive');
assert.deepEqual(fs.readdirSync(outputRoot).sort(), ['archify.zip', 'noncanonical-zlib.cjs']);
} finally {
fs.rmSync(outputRoot, { recursive: true, force: true });
}
});
test('archive build rejects non-canonical Node/zlib toolchains before publishing output', {
skip: canonicalZipSkip ? false : 'requires a non-canonical Node/zlib toolchain',
}, () => {
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 = spawnBuildZip(archive);
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');
try {
for (const [archive, timezone] of [
[utcArchive, 'UTC'],
[honoluluArchive, 'Pacific/Honolulu'],
]) {
const build = spawnBuildZip(archive, {
env: { ...process.env, TZ: timezone },
});
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
}
assert.ok(
fs.readFileSync(utcArchive).equals(fs.readFileSync(honoluluArchive)),
'identical tracked inputs must produce identical archive bytes',
);
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(
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 });
}
});
test('archive build accepts Windows-style absolute output paths', {
skip: process.platform !== 'win32'
? 'Windows drive paths only reach build-zip.sh on win32'
: canonicalZipSkip,
}, () => {
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, '/');
try {
for (const archive of [backslashArchive, slashArchive]) {
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]) {
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', '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, options = {}) {
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', ...options });
}
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 publishes over a maximum-length output component without an oversized candidate name', () => {
const { fixture, staged } = stagedFixture({
'README.md': { content: 'bounded archive candidate\n', mode: 0o644 },
});
try {
const manifest = path.join(fixture, 'modes.json');
fs.writeFileSync(manifest, JSON.stringify({ 'README.md': '100644' }));
const archive = path.join(fixture, `${'a'.repeat(251)}.zip`);
fs.writeFileSync(archive, 'trusted previous archive');
const build = writeArchive(staged, archive, manifest);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.equal(fs.readFileSync(archive).readUInt32LE(0), 0x04034b50);
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'successful publication must not leave a temporary candidate behind',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
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 writer rejects existing and dangling output symlinks without mutation', (t) => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
try {
const external = path.join(fixture, 'external.zip');
const sentinel = Buffer.from('external sentinel\n');
fs.writeFileSync(external, sentinel);
const linked = path.join(fixture, 'linked.zip');
try {
fs.symlinkSync(external, linked, process.platform === 'win32' ? 'file' : undefined);
} catch (error) {
if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error?.code)) {
t.skip(`file symlinks unavailable: ${error.code}`);
return;
}
throw error;
}
let build = writeArchive(staged, linked, manifest);
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /requested-entry-symbolic-link/);
assert.equal(fs.lstatSync(linked).isSymbolicLink(), true);
assert.ok(fs.readFileSync(external).equals(sentinel));
const dangling = path.join(fixture, 'dangling.zip');
const missing = path.join(fixture, 'missing.zip');
fs.symlinkSync(missing, dangling, process.platform === 'win32' ? 'file' : undefined);
build = writeArchive(staged, dangling, manifest);
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /requested-entry-symbolic-link/);
assert.equal(fs.lstatSync(dangling).isSymbolicLink(), true);
assert.equal(fs.existsSync(missing), false);
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'rejected output symlinks must not leave temporary files behind',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer rejects a special output entry without replacing it', {
skip: process.platform === 'win32' ? 'the FIFO fixture is POSIX-only' : false,
}, () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const fifo = path.join(fixture, 'special.zip');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
try {
const mkfifo = spawnSync('mkfifo', [fifo], { encoding: 'utf8' });
assert.equal(mkfifo.status, 0, mkfifo.stderr);
const build = writeArchive(staged, fifo, manifest);
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /requested-entry-not-regular-file/);
assert.equal(fs.lstatSync(fifo).isFIFO(), true);
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'special-entry rejection must happen before a temporary archive is created',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer rejects a hard-linked output without changing either name', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const external = path.join(fixture, 'external.zip');
const archive = path.join(fixture, 'archive.zip');
const sentinel = Buffer.from('shared archive sentinel\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(external, sentinel);
fs.linkSync(external, archive);
try {
const before = fs.statSync(archive, { bigint: true });
const build = writeArchive(staged, archive, manifest);
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /requested-entry-hardlinked/);
assert.ok(fs.readFileSync(archive).equals(sentinel));
assert.ok(fs.readFileSync(external).equals(sentinel));
const after = fs.statSync(archive, { bigint: true });
assert.equal(after.dev, before.dev);
assert.equal(after.ino, before.ino);
assert.equal(after.nlink, 2n);
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'hard-link rejection must happen before a temporary archive is created',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer verifies the output binding immediately before publication', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const replacement = path.join(fixture, 'replacement.zip');
const preload = path.join(fixture, 'swap-before-rename.cjs');
const original = Buffer.from('original archive\n');
const claimant = Buffer.from('replacement claimant\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, original);
fs.writeFileSync(replacement, claimant);
fs.writeFileSync(preload, String.raw`
const fs = require('node:fs');
const path = require('node:path');
const output = process.env.ARCHIFY_TEST_SWAP_OUTPUT;
const replacement = process.env.ARCHIFY_TEST_SWAP_REPLACEMENT;
const originalOpen = fs.openSync;
const originalClose = fs.closeSync;
let temporaryDescriptor;
let swapped = false;
fs.openSync = function patchedOpen(file, ...args) {
const descriptor = originalOpen.call(this, file, ...args);
if (typeof file === 'string'
&& /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(path.basename(file))) {
temporaryDescriptor = descriptor;
}
return descriptor;
};
fs.closeSync = function patchedClose(descriptor) {
const result = originalClose.call(this, descriptor);
if (!swapped && descriptor === temporaryDescriptor) {
swapped = true;
fs.unlinkSync(output);
fs.renameSync(replacement, output);
}
return result;
};
require('node:module').syncBuiltinESMExports();
`);
try {
const build = writeArchive(staged, archive, manifest, {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
ARCHIFY_TEST_SWAP_OUTPUT: archive,
ARCHIFY_TEST_SWAP_REPLACEMENT: replacement,
},
});
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /(?:requested-entry-changed|target-identity-changed)/);
assert.ok(fs.readFileSync(archive).equals(claimant), 'the replacement claimant must not be overwritten');
assert.equal(fs.existsSync(replacement), false, 'the fixture must actually move the claimant into place');
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'a failed pre-rename verification must remove the unpublished temporary archive',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer preserves a target claimant that arrives after the previous output is backed up', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const preload = path.join(fixture, 'claim-archive-target.cjs');
const original = Buffer.from('previous archive\n');
const claimant = Buffer.from('concurrent archive claimant\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, original);
fs.writeFileSync(preload, String.raw`
const fs = require('node:fs');
const path = require('node:path');
const output = process.env.ARCHIFY_TEST_ARCHIVE_OUTPUT;
const claimant = process.env.ARCHIFY_TEST_ARCHIVE_CLAIMANT;
const originalLink = fs.linkSync;
const originalWriteFile = fs.writeFileSync;
let injected = false;
fs.linkSync = function patchedLink(source, destination) {
if (!injected
&& path.basename(destination) === path.basename(output)
&& /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(path.basename(source))) {
originalWriteFile(output, claimant, { flag: 'wx' });
injected = true;
}
return originalLink.call(this, source, destination);
};
require('node:module').syncBuiltinESMExports();
`);
try {
const build = writeArchive(staged, archive, manifest, {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
ARCHIFY_TEST_ARCHIVE_OUTPUT: archive,
ARCHIFY_TEST_ARCHIVE_CLAIMANT: claimant.toString('utf8'),
},
});
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /requires recovery/);
assert.ok(fs.readFileSync(archive).equals(claimant), 'the concurrent target claimant must remain public');
const backups = fs.readdirSync(fixture)
.filter((name) => /^\.archify-zip-backup-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(name));
assert.equal(backups.length, 1, 'the displaced previous output must remain recoverable');
assert.ok(fs.readFileSync(path.join(fixture, backups[0])).equals(original));
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer rejects a candidate changed while the final output state is checked', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const preload = path.join(fixture, 'mutate-archive-candidate.cjs');
const original = Buffer.from('original archive\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, original);
fs.writeFileSync(preload, String.raw`
const fs = require('node:fs');
const path = require('node:path');
const output = process.env.ARCHIFY_TEST_ARCHIVE_OUTPUT;
const originalOpen = fs.openSync;
const originalLstat = fs.lstatSync;
const originalWriteFile = fs.writeFileSync;
let candidatePath;
let candidateOpens = 0;
let mutated = false;
fs.openSync = function patchedOpen(file, ...args) {
const descriptor = originalOpen.call(this, file, ...args);
if (typeof file === 'string'
&& /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(path.basename(file))) {
candidatePath = file;
candidateOpens += 1;
}
return descriptor;
};
fs.lstatSync = function patchedLstat(file, ...args) {
if (!mutated && candidateOpens >= 2 && path.resolve(file) === path.resolve(output)) {
mutated = true;
originalWriteFile(candidatePath, 'mutated candidate bytes\n');
}
return originalLstat.call(this, file, ...args);
};
require('node:module').syncBuiltinESMExports();
`);
try {
const build = writeArchive(staged, archive, manifest, {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
ARCHIFY_TEST_ARCHIVE_OUTPUT: archive,
},
});
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /archive-candidate-content-changed/);
assert.ok(fs.readFileSync(archive).equals(original));
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'an in-place candidate mutation must be rejected and cleaned up by identity',
);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer preserves a successor that replaces its temporary candidate', {
skip: process.platform === 'win32'
? 'Windows does not unlink an archive candidate while its verification handle is open'
: false,
}, () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const preload = path.join(fixture, 'replace-archive-candidate.cjs');
const original = Buffer.from('original archive\n');
const successor = Buffer.from('candidate successor claimant\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, original);
fs.writeFileSync(preload, String.raw`
const fs = require('node:fs');
const path = require('node:path');
const output = process.env.ARCHIFY_TEST_ARCHIVE_OUTPUT;
const successor = process.env.ARCHIFY_TEST_ARCHIVE_SUCCESSOR;
const originalOpen = fs.openSync;
const originalLstat = fs.lstatSync;
const originalUnlink = fs.unlinkSync;
const originalWriteFile = fs.writeFileSync;
let candidatePath;
let candidateOpens = 0;
let swapped = false;
fs.openSync = function patchedOpen(file, ...args) {
const descriptor = originalOpen.call(this, file, ...args);
if (typeof file === 'string'
&& /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(path.basename(file))) {
candidatePath = file;
candidateOpens += 1;
}
return descriptor;
};
fs.lstatSync = function patchedLstat(file, ...args) {
if (!swapped && candidateOpens >= 2 && path.resolve(file) === path.resolve(output)) {
swapped = true;
originalUnlink(candidatePath);
originalWriteFile(candidatePath, successor, { flag: 'wx' });
}
return originalLstat.call(this, file, ...args);
};
require('node:module').syncBuiltinESMExports();
`);
try {
const build = writeArchive(staged, archive, manifest, {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
ARCHIFY_TEST_ARCHIVE_OUTPUT: archive,
ARCHIFY_TEST_ARCHIVE_SUCCESSOR: successor.toString('utf8'),
},
});
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, /archive-candidate-identity-changed/);
assert.ok(fs.readFileSync(archive).equals(original));
const candidates = fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp'));
assert.equal(candidates.length, 1, 'the replacement claimant must remain named');
assert.ok(fs.readFileSync(path.join(fixture, candidates[0])).equals(successor));
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer keeps the candidate identity bound through commit and preserves a release-time successor', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const preload = path.join(fixture, 'replace-candidate-on-release.cjs');
const successor = Buffer.from('release-time candidate claimant\n');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, 'previous archive\n');
fs.writeFileSync(preload, String.raw`
const fs = require('node:fs');
const path = require('node:path');
const successor = process.env.ARCHIFY_TEST_ARCHIVE_SUCCESSOR;
const originalOpen = fs.openSync;
const originalClose = fs.closeSync;
const originalUnlink = fs.unlinkSync;
const originalWriteFile = fs.writeFileSync;
let candidatePath;
let candidateOpens = 0;
let bindingDescriptor;
let swapped = false;
fs.openSync = function patchedOpen(file, ...args) {
const descriptor = originalOpen.call(this, file, ...args);
if (typeof file === 'string'
&& /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(path.basename(file))) {
candidatePath = file;
candidateOpens += 1;
if (candidateOpens === 2) bindingDescriptor = descriptor;
}
return descriptor;
};
fs.closeSync = function patchedClose(descriptor) {
const result = originalClose.call(this, descriptor);
if (!swapped && descriptor === bindingDescriptor) {
swapped = true;
try { originalUnlink(candidatePath); } catch (error) {
if (error.code !== 'ENOENT') throw error;
}
originalWriteFile(candidatePath, successor, { flag: 'wx' });
}
return result;
};
require('node:module').syncBuiltinESMExports();
`);
try {
const build = writeArchive(staged, archive, manifest, {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
ARCHIFY_TEST_ARCHIVE_SUCCESSOR: successor.toString('utf8'),
},
});
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.equal(fs.readFileSync(archive).readUInt32LE(0), 0x04034b50);
const candidates = fs.readdirSync(fixture)
.filter((name) => /^\.archify-zip-[a-f\d]{16}-[a-f\d]{32}\.tmp$/.test(name));
assert.equal(candidates.length, 1, 'the release-time successor must remain named');
assert.ok(fs.readFileSync(path.join(fixture, candidates[0])).equals(successor));
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer preserves an existing regular output mode despite a restrictive umask', {
skip: process.platform === 'win32' ? 'Windows does not expose POSIX creation modes' : false,
}, () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const manifest = path.join(fixture, 'modes.json');
const archive = path.join(fixture, 'archive.zip');
const fresh = path.join(fixture, 'fresh.zip');
const preload = path.join(fixture, 'restrict-umask.cjs');
fs.writeFileSync(manifest, JSON.stringify({ 'safe.txt': '100644' }));
fs.writeFileSync(archive, 'existing archive\n');
fs.chmodSync(archive, 0o664);
fs.writeFileSync(preload, 'process.umask(0o077);\n');
const options = {
env: {
...process.env,
NODE_OPTIONS: `${process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : ''}--import=${pathToFileURL(preload).href}`,
},
};
try {
let build = writeArchive(staged, archive, manifest, options);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.equal(fs.statSync(archive).mode & 0o777, 0o664);
build = writeArchive(staged, fresh, manifest, options);
assert.equal(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.equal(fs.statSync(fresh).mode & 0o777, 0o600);
} finally {
fs.rmSync(fixture, { recursive: true, force: true });
}
});
test('archive writer rejects non-portable manifest entries and collisions before publication', () => {
const { fixture, staged } = stagedFixture({
'safe.txt': { content: 'safe\n', mode: 0o644 },
});
const archive = path.join(fixture, 'trusted.zip');
const trusted = Buffer.from('trusted archive bytes');
const manifest = path.join(fixture, 'modes.json');
try {
const cases = [
[
{ 'safe.txt': '100644', 'CON.txt': '100644' },
/Portable path must not use a reserved Windows device name/,
],
[
{ 'safe.txt': '100644', 'Docs/one.txt': '100644', 'docs/two.txt': '100644' },
/collide under portable filesystem semantics/,
],
];
for (const [contents, expected] of cases) {
fs.writeFileSync(archive, trusted);
fs.writeFileSync(manifest, JSON.stringify(contents));
const build = writeArchive(staged, archive, manifest);
assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
assert.match(build.stderr, expected);
assert.ok(fs.readFileSync(archive).equals(trusted), 'portable-name rejection must preserve the prior archive');
assert.deepEqual(
fs.readdirSync(fixture).filter((name) => name.endsWith('.tmp')),
[],
'portable-name rejection 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');
const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'ci.yml'), 'utf8');
const testJob = workflowJob(workflow, 'test');
const versions = testJob.match(/node-version:\s*\[([^\]]+)\]/)?.[1]
.split(',')
.map((version) => Number(version.trim()));
assert.ok(versions, 'test job must declare an explicit Node version matrix');
for (const version of [18, 20, 24]) {
assert.ok(versions.includes(version), `test matrix must cover Node ${version}`);
}
const canonicalJob = workflowJob(workflow, 'canonical-test');
assert.match(canonicalJob, /name: test \(22\)/);
assert.match(canonicalJob, /node-version:\s*22/);
const packageSmokeJob = workflowJob(workflow, 'package-smoke');
assert.match(packageSmokeJob, /os:\s*\[ubuntu-latest, macos-latest, windows-latest\]/);
assert.match(packageSmokeJob, /node-version:\s*22/);
});
test('CI and tagged releases keep real Windows paths on both Nodes and detailed matrices on canonical Node', () => {
const runnerPath = path.join(repoRoot, 'scripts', 'run-windows-path-tests.mjs');
const runner = fs.readFileSync(runnerPath, 'utf8');
const list = (...options) => {
const result = spawnSync(process.execPath, [runnerPath, '--list', ...options], {
cwd: os.tmpdir(), encoding: 'utf8', timeout: 10_000,
});
assert.equal(result.status, 0, result.stderr);
return JSON.parse(result.stdout);
};
const complete = list();
const smoke = list('--smoke');
assert.equal(complete.controlledPaths, true);
assert.equal(smoke.controlledPaths, true);
assert.deepEqual(smoke.groups.flat().filter(arg => arg.endsWith('.test.mjs')),
['test/core-smoke.test.mjs'], 'The compatibility profile selects only core product coverage.');
const invalid = spawnSync(process.execPath, [runnerPath, '--list', '--smkoe'], { encoding: 'utf8', timeout: 10_000 });
assert.notEqual(invalid.status, 0, 'A misspelled profile must not silently reduce coverage.');
if (process.platform !== 'win32') {
const wrongHost = spawnSync(process.execPath, [runnerPath, '--smoke'], {
encoding: 'utf8', timeout: 10_000,
env: { ...process.env, ARCHIFY_REQUIRE_WINDOWS_REAL_PATHS: '1' },
});
assert.notEqual(wrongHost.status, 0);
assert.match(wrongHost.stderr, /ARCHIFY_REQUIRE_WINDOWS_REAL_PATHS=1 requires Windows/,
'The smoke profile must still enter the required real-path gate.');
}
const fullSuites = [
'test/release-package-gates.test.mjs',
'test/copy-site-assets.test.mjs',
'test/path-boundary-contract.test.mjs',
'test/path-semantics.test.mjs',
'test/portable-path.test.mjs',
'test/native-output-path.test.mjs',
'test/meta-output-contract.test.mjs',
'test/output-path.test.mjs',
'test/cli-output-types.test.mjs',
'test/delivery-sidecar-path.test.mjs',
'test/sidecar-path-length.test.mjs',
'test/open-artifact.test.mjs',
'test/repository-evidence.test.mjs',
'test/renderer-atomic-write.test.mjs',
'test/atomic-output-recovery.test.mjs',
];
for (const suite of fullSuites) {
assert.ok(complete.groups.flat().includes(suite), `canonical runner must execute ${suite}`);
}
for (const fixture of [
'test/checkout-line-endings.test.mjs',
'test/clean-skill-staging.test.mjs',
'test/workflow-migration.test.mjs',
'test/cli.test.mjs',
'test/preview.test.mjs',
'test/update-notifier.test.mjs',
'test/visual-check.test.mjs',
]) {
assert.ok(runner.includes(`'${fixture}'`), `shared runner must execute ${fixture}`);
}
assert.match(runner, /canonical watch target/);
assert.match(runner, /entry detection/);
assert.match(runner, /workflow migration rejects a dangling destination symlink/);
assert.match(runner, /workflow migration preserves a destination claimant created before final verification/);
assert.match(runner, /workflow migration preserves an existing destination replaced during candidate mode finalization/);
assert.match(runner, /Windows 8\.3 short path/);
assert.match(runner, /preview: publishing through an existing output symlink/);
assert.match(runner, /preview: a hardlinked existing output/);
assert.match(runner, /'visual-check'/);
assert.match(runner, /updater rejects a case-only alias/);
assert.match(runner, /symlink cache root/);
assert.match(runner, /symlink cache ancestor/);
assert.match(runner, /authored symlink is rejected/);
assert.match(runner, /trusted directory through a symlink/);
assert.match(runner, /preview runs from an installed skill/);
assert.match(runner, /watcher accepts/);
assert.match(runner, /findChrome/);
assert.match(runner, /doctor identifies an incomplete installation/);
assert.match(runner, /ARCHIFY_REQUIRE_WINDOWS_REAL_PATHS/);
assert.match(runner, /ARCHIFY_WINDOWS_CASE_SENSITIVE_ROOT/);
assert.match(runner, /ARCHIFY_WINDOWS_UNC_ROOT/);
assert.match(runner, /ARCHIFY_WINDOWS_EXTENDED_UNC_ROOT/);
assert.match(runner, /ARCHIFY_WINDOWS_8DOT3_ROOT/);
assert.match(runner, /ARCHIFY_WINDOWS_8DOT3_SHORT_ROOT/);
assert.match(runner, /sameLocation\(uncRoot, extendedUncRoot\)\.status, 'match'/);
assert.doesNotMatch(runner, /extendedUncRoot\.toLocaleLowerCase/);
assert.doesNotMatch(runner, /controlled real-path fixture belongs to the canonical Node 22 lane/);
assert.match(runner, /driveLetterCaseAlias/);
assert.match(runner, /strict check through drive-letter case alias/);
assert.match(runner, /fs\.symlinkSync\(junctionTarget, junctionAlias, 'junction'\)/);
assert.match(runner, /fs\.symlinkSync\(fileTarget, fileSymlink, 'file'\)/);
assert.match(runner, /fs\.linkSync\(fileTarget, hardlink\)/);
assert.match(runner, /runCli\(\[\s*'visual-check'/);
assert.match(runner, /--require-provenance/);
assert.match(runner, /architecture compare to extended UNC/);
assert.match(runner, /repository root through drive-letter case alias/);
assert.match(runner, /stageCleanSkill\(\{ repoRoot: driveCaseRepoRoot/);
assert.match(runner, /checkForUpdate\(\{/);
assert.match(runner, /let ordinaryLongDirectory = uncRoot/);
assert.match(runner, /ordinary UNC delivery beyond traditional MAX_PATH/);
assert.match(runner, /ordinary UNC visual-check beyond traditional MAX_PATH/);
assert.match(runner, /let extendedLongDirectory = extendedUncRoot/);
assert.match(runner, /extended UNC delivery beyond traditional MAX_PATH/);
assert.match(runner, /path\.win32\.join\(ordinaryLongDirectory, `\$\{token\}-preview[.]html`\)/);
assert.match(
runner,
/assertNoPrivateStaging\(ordinaryLongDirectory, '[.]archify-delivery-', ordinaryLongDelivery\)/,
);
assert.match(runner, /fs[.]lstatSync\(path[.]toNamespacedPath\(path[.]join\(directory, entry\)\)\)/);
assert.match(runner, /assertNoPrivateStaging\(evidenceDirectory, '[.]archify-visual-check-'\)/);
assert.match(runner, /assertNoPrivateStaging\(ordinaryLongDirectory, '[.]archify-preview-'\)/);
assert.match(runner, /case-sensitive upper artifact visual-check to shared UNC/);
assert.match(runner, /case-sensitive lower artifact visual-check to shared UNC/);
assert.match(runner, /case-variant artifacts must receive distinct evidence names/);
assert.match(runner, /normalization-sensitive render \(NFC\)/);
assert.match(runner, /normalization-sensitive render \(NFD\)/);
assert.match(runner, /normalization-sensitive NFC artifact visual-check to shared UNC/);
assert.match(runner, /normalization-sensitive NFD artifact visual-check to shared UNC/);
assert.match(runner, /normalization-distinct artifacts must receive distinct evidence names/);
assert.match(runner, /build-zip[.]sh/);
const cliSource = fs.readFileSync(path.join(repoRoot, 'archify', 'bin', 'archify.mjs'), 'utf8');
const previewSource = fs.readFileSync(path.join(repoRoot, 'archify', 'bin', 'preview.mjs'), 'utf8');
const visualCheckSource = fs.readFileSync(
path.join(repoRoot, 'archify', 'bin', 'visual-check.mjs'),
'utf8',
);
assert.match(cliSource, /mkdtempSync\(path[.]toNamespacedPath\(prefix\)\)/);
assert.match(previewSource, /mkdtempSync\(path[.]toNamespacedPath\(\s*path[.]join\(physicalOutputDirectory, '[.]archify-preview-'\),\s*\)\)/);
assert.match(visualCheckSource, /mkdtempSync\(path[.]toNamespacedPath\(\s*path[.]join\(parent[.]parentPath, '[.]archify-visual-check-'\),\s*\)\)/);
const previewSuite = fs.readFileSync(path.join(repoRoot, 'test', 'preview.test.mjs'), 'utf8');
assert.match(previewSuite, /process\.env\.ARCHIFY_REQUIRE_WINDOWS_8DOT3 === '1'/);
assert.match(previewSuite, /process\.env\.ARCHIFY_WINDOWS_8DOT3_ROOT/);
assert.match(previewSuite, /process\.env\.ARCHIFY_WINDOWS_8DOT3_SHORT_ROOT/);
assert.match(previewSuite, /assignWindowsShortName\(realDirectory, shortName\)/);
const deliverySuite = fs.readFileSync(
path.join(repoRoot, 'test', 'delivery-sidecar-path.test.mjs'),
'utf8',
);
assert.match(deliverySuite, /process\.env\.ARCHIFY_WINDOWS_8DOT3_ROOT/);
assert.match(deliverySuite, /process\.env\.ARCHIFY_WINDOWS_8DOT3_SHORT_ROOT/);
assert.match(deliverySuite, /assignWindowsShortName\(output, 'ARCHDL~1[.]HTM'\)/);
const visualSidecarSuite = fs.readFileSync(
path.join(repoRoot, 'test', 'sidecar-path-length.test.mjs'),
'utf8',
);
assert.match(visualSidecarSuite, /assignWindowsShortName\(artifact, 'ARCHVS~1[.]HTM'\)/);
const workflows = [
['CI', fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'ci.yml'), 'utf8')],
['release', fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'release.yml'), 'utf8')],
];
const fixtureScript = fs.readFileSync(
path.join(repoRoot, 'scripts', 'windows-path-fixtures.ps1'),
'utf8',
);
assert.match(fixtureScript, /node\$NodeVersion/);
assert.match(fixtureScript, /fsutil[.]exe file setCaseSensitiveInfo/);
assert.match(fixtureScript, /New-SmbShare[^\n]*-Temporary[^\n]*-ChangeAccess \$identity/);
assert.match(fixtureScript, /\\\\localhost\\\$shareName/);
assert.match(fixtureScript, /\\\\[?]\\UNC\\localhost\\\$shareName/);
assert.match(fixtureScript, /ARCHIFY_WINDOWS_CASE_SENSITIVE_ROOT/);
assert.match(fixtureScript, /ARCHIFY_WINDOWS_UNC_ROOT/);
assert.match(fixtureScript, /ARCHIFY_WINDOWS_EXTENDED_UNC_ROOT/);
assert.match(fixtureScript, /fsutil[.]exe file setshortname/);
assert.doesNotMatch(fixtureScript, /fsutil[.]exe 8dot3name set/);
assert.match(fixtureScript, /ARCHIFY_WINDOWS_8DOT3_ROOT/);
assert.match(fixtureScript, /ARCHIFY_WINDOWS_8DOT3_SHORT_ROOT/);
assert.match(fixtureScript, /Remove-SmbShare/);
for (const [label, workflow] of workflows) {
const job = workflowJob(workflow, 'windows-test-portability');
assert.match(job, /runs-on:\s*windows-latest/);
assert.match(job, /node-version:\s*\[22, 24\]/);
assert.match(job, /node-version:\s*\$\{\{ matrix\.node-version \}\}/);
assert.match(job, /npm ci --ignore-scripts/);
assert.match(job, /node scripts\/run-windows-path-tests\.mjs/);
assert.ok(job.includes("matrix.node-version == 24 && '--smoke' || ''"),
`${label} must select smoke only for Node 24; Node 22 retains the complete matrices`);
assert.match(job, label === 'CI'
? /name: Provision controlled Windows path fixtures\n\s+if: needs\.scope\.outputs\.windows == 'true'\n\s+shell: pwsh/
: /name: Provision controlled Windows path fixtures\n\s+shell: pwsh/);
assert.match(
job,
/scripts\/windows-path-fixtures[.]ps1 -NodeVersion '\$\{\{ matrix[.]node-version \}\}'/,
);
assert.match(
job,
label === 'CI'
? /name: Clean up controlled Windows path fixtures\n\s+if: \$\{\{ always\(\) && needs\.scope\.outputs\.windows == 'true' \}\}/
: /name: Clean up controlled Windows path fixtures\n\s+if: \$\{\{ always\(\) \}\}/,
);
assert.match(
job,
/scripts\/windows-path-fixtures[.]ps1 -NodeVersion '\$\{\{ matrix[.]node-version \}\}' -Cleanup/,
);
assert.match(
job,
/ARCHIFY_REQUIRE_WINDOWS_8DOT3:\s*'1'/,
`${label} must require real 8.3 coverage on every maintained Node lane`,
);
assert.match(
job,
/ARCHIFY_REQUIRE_WINDOWS_REAL_PATHS:\s*'1'/,
`${label} must require controlled UNC and case-sensitive NTFS coverage on every lane`,
);
for (const suite of fullSuites) {
assert.equal(job.includes(suite), false, `${label} must get ${suite} from the shared runner`);
}
}
const ci = workflows[0][1];
const deploy = workflowJob(ci, 'deploy-pages');
assert.match(deploy, /needs: \[[^\]]*windows-test-portability[^\]]*\]/);
const releaseWorkflow = workflows[1][1];
const release = workflowJob(releaseWorkflow, 'release');
assert.match(release, /needs:\s*windows-test-portability/);
});