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 { 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 test from 'node:test';
import assert from 'node:assert/strict';
import { startPreview } from '../archify/bin/preview.mjs';
const root = fileURLToPath(new URL('../archify/', import.meta.url));
const cli = path.join(root, 'bin/archify.mjs');
const workflow = path.join(root, 'examples/agent-tool-call.workflow.json');
const architecture = path.join(root, 'examples/web-app.architecture.json');
const base = path.join(root, 'examples/checkout-platform.base.architecture.json');
const head = path.join(root, 'examples/checkout-platform.head.architecture.json');
const marker = 'MARKER=do-not-destroy';
function workspace(t) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-cli-types-'));
t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
return dir;
}
function run(args, cwd) {
return spawnSync(process.execPath, [cli, ...args], { cwd, encoding: 'utf8' });
}
for (const command of ['render', 'deliver', 'compare']) {
test(`${command} rejects a non-HTML target without replacing existing bytes`, t => {
const dir = workspace(t);
const cwd = path.join(dir, 'working');
fs.mkdirSync(cwd);
const output = path.join(dir, 'marker.env');
fs.writeFileSync(output, marker);
const args = command === 'compare' ? ['compare', 'architecture', base, head] : [command, 'workflow', workflow];
const result = run([...args, '../marker.env', ...(command === 'render' ? [] : ['--json'])], cwd);
assert.equal(result.status, 1, result.stderr);
if (command === 'render') assert.match(result.stderr, /output\/cli-extension/);
else assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/cli-extension');
assert.equal(fs.readFileSync(output, 'utf8'), marker);
assert.deepEqual(fs.readdirSync(cwd), []);
});
}
test('preview rejects a non-HTML target before publishing or starting a server', async t => {
const cwd = workspace(t);
const output = path.join(cwd, 'marker.env');
fs.writeFileSync(output, marker);
let session;
try {
await assert.rejects(async () => {
session = await startPreview({ type: 'workflow', input: workflow, output, cwd, open: false });
}, error => error.archifyDiagnostics?.[0]?.code === 'output/cli-extension');
} finally {
if (session) { session.stop(); await session.closed; }
}
assert.equal(fs.readFileSync(output, 'utf8'), marker);
});
test('render and deliver reject HTML symlinks resolving to non-HTML files', t => {
const cwd = workspace(t);
const target = path.join(cwd, 'marker.env');
const output = path.join(cwd, 'diagram.html');
fs.writeFileSync(target, marker);
try { fs.symlinkSync(target, output, 'file'); }
catch (error) {
if (error.code === 'EPERM') { t.skip('symlink creation requires permission'); return; }
throw error;
}
for (const command of ['render', 'deliver']) {
const result = run([command, 'workflow', workflow, output, ...(command === 'deliver' ? ['--json'] : [])], cwd);
assert.equal(result.status, 1, result.stderr);
if (command === 'deliver') assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/cli-resolved-extension');
else assert.match(result.stderr, /output\/cli-resolved-extension/);
assert.equal(fs.readFileSync(target, 'utf8'), marker);
assert.equal(fs.lstatSync(output).isSymbolicLink(), true);
}
});
test('compare rejects a non-JSON receipt before writing either output', t => {
const cwd = workspace(t);
const output = path.join(cwd, 'delta.html');
const receipt = path.join(cwd, 'marker.env');
fs.writeFileSync(output, marker);
fs.writeFileSync(receipt, marker);
const result = run(['compare', 'architecture', base, head, output, '--receipt', receipt, '--json'], cwd);
assert.equal(result.status, 1, result.stderr);
assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/cli-extension');
assert.equal(fs.readFileSync(output, 'utf8'), marker);
assert.equal(fs.readFileSync(receipt, 'utf8'), marker);
});
for (const aliasKind of ['same path', 'symlink alias']) {
test(`compare reports target alias before CLI extension for ${aliasKind}`, t => {
const cwd = workspace(t);
const output = path.join(cwd, 'same.json');
const receipt = aliasKind === 'same path'
? output
: path.join(cwd, 'receipt.json');
fs.writeFileSync(output, marker);
if (aliasKind === 'symlink alias') {
try { fs.symlinkSync(output, receipt, 'file'); }
catch (error) {
if (error.code === 'EPERM') { t.skip('symlink creation requires permission'); return; }
throw error;
}
}
const result = run([
'compare', 'architecture', base, head, output,
'--receipt', receipt, '--json',
], cwd);
assert.equal(result.status, 1, result.stderr);
assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/target-alias');
assert.equal(fs.readFileSync(output, 'utf8'), marker);
if (aliasKind === 'symlink alias') assert.equal(fs.readlinkSync(receipt), output);
});
}
test('compare keeps CLI extension precedence for distinct invalid outputs', t => {
const cwd = workspace(t);
const output = path.join(cwd, 'artifact.json');
const receipt = path.join(cwd, 'receipt.txt');
fs.writeFileSync(output, marker);
fs.writeFileSync(receipt, marker);
const result = run([
'compare', 'architecture', base, head, output,
'--receipt', receipt, '--json',
], cwd);
assert.equal(result.status, 1, result.stderr);
assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/cli-extension');
assert.equal(fs.readFileSync(output, 'utf8'), marker);
assert.equal(fs.readFileSync(receipt, 'utf8'), marker);
});
test('compare reports target alias before CLI extension for a derived receipt symlink', t => {
const cwd = workspace(t);
const output = path.join(cwd, 'artifact.json');
const receipt = path.join(cwd, 'artifact.receipt.json');
fs.writeFileSync(output, marker);
try { fs.symlinkSync(output, receipt, 'file'); }
catch (error) {
if (error.code === 'EPERM') { t.skip('symlink creation requires permission'); return; }
throw error;
}
const result = run(['compare', 'architecture', base, head, output, '--json'], cwd);
assert.equal(result.status, 1, result.stderr);
assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/target-alias');
assert.equal(fs.readFileSync(output, 'utf8'), marker);
assert.equal(fs.readlinkSync(receipt), output);
});
test('absolute HTML and JSON outputs outside cwd remain supported', t => {
const dir = workspace(t);
const cwd = path.join(dir, 'working');
fs.mkdirSync(cwd);
const output = path.join(dir, 'diagram.HTML');
const delivered = run(['deliver', 'workflow', workflow, output, '--json'], cwd);
assert.equal(delivered.status, 0, delivered.stderr);
assert.equal(JSON.parse(delivered.stdout).ok, true);
assert.match(fs.readFileSync(output, 'utf8'), /<!DOCTYPE html>/i);
const receipt = path.join(dir, 'delta.JSON');
const compared = run(['compare', 'architecture', base, head, output, '--receipt', receipt, '--json'], cwd);
assert.equal(compared.status, 0, compared.stderr || compared.stdout);
assert.equal(JSON.parse(fs.readFileSync(receipt, 'utf8')).ok, true);
});
test('validate, inspect and layout JSON retain their internal no-output behavior', t => {
const cwd = workspace(t);
for (const args of [
['validate', 'architecture', architecture, '--json'],
['inspect', 'architecture', architecture],
['validate', 'workflow', workflow, '--layout-json'],
]) {
const result = run(args, cwd);
assert.equal(result.status, 0, result.stderr);
assert.doesNotThrow(() => JSON.parse(result.stdout));
assert.deepEqual(fs.readdirSync(cwd), []);
}
});
test('compare rejects a JSON receipt symlink to a non-JSON target', t => {
const cwd = workspace(t);
const target = path.join(cwd, 'marker.env');
const receipt = path.join(cwd, 'receipt.json');
const output = path.join(cwd, 'delta.html');
fs.writeFileSync(target, marker);
try { fs.symlinkSync(target, receipt, 'file'); }
catch (error) {
if (error.code === 'EPERM') { t.skip('symlink creation requires permission'); return; }
throw error;
}
const result = run(['compare', 'architecture', base, head, output, '--receipt', receipt, '--json'], cwd);
assert.equal(result.status, 1, result.stderr);
assert.equal(JSON.parse(result.stdout).diagnostics[0].code, 'output/cli-resolved-extension');
assert.equal(fs.readFileSync(target, 'utf8'), marker);
assert.equal(fs.existsSync(output), false);
});
test('compare accepts artifact and receipt parents that are aliases of the same directory', t => {
const cwd = workspace(t);
const outputDirectory = path.join(cwd, 'physical-output');
const directoryAlias = path.join(cwd, 'output-alias');
fs.mkdirSync(outputDirectory);
try {
fs.symlinkSync(outputDirectory, directoryAlias, process.platform === 'win32' ? 'junction' : 'dir');
} catch (error) {
if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) {
t.skip('directory aliases require permission');
return;
}
throw error;
}
const output = path.join(outputDirectory, 'delta.html');
const receipt = path.join(directoryAlias, 'delta.receipt.json');
const result = run([
'compare', 'architecture', base, head, output,
'--receipt', receipt, '--json',
], cwd);
assert.equal(result.status, 0, result.stderr || result.stdout);
assert.equal(JSON.parse(result.stdout).ok, true);
assert.equal(fs.existsSync(output), true);
assert.equal(JSON.parse(fs.readFileSync(receipt, 'utf8')).ok, true);
});
test('compare fails closed when artifact and receipt parent identity is indeterminate', t => {
const cwd = workspace(t);
const outputDirectory = path.join(cwd, 'output');
fs.mkdirSync(outputDirectory);
const output = path.join(outputDirectory, 'delta.html');
const receipt = path.join(outputDirectory, 'delta.receipt.json');
const wrapper = path.join(cwd, 'compare-parent-identity-wrapper.mjs');
fs.writeFileSync(wrapper, `
import fs from 'node:fs';
import path from 'node:path';
const originalReadFileSync = fs.readFileSync;
const originalRealpathSyncNative = fs.realpathSync.native;
const blockedDirectory = originalRealpathSyncNative(${JSON.stringify(outputDirectory)});
let inputsRead = false;
fs.readFileSync = (file, ...args) => {
const contents = originalReadFileSync(file, ...args);
if (path.resolve(String(file)) === ${JSON.stringify(path.resolve(head))}) inputsRead = true;
return contents;
};
fs.realpathSync.native = (file, ...args) => {
if (inputsRead && path.resolve(String(file)) === path.resolve(blockedDirectory)) {
throw Object.assign(new Error('injected parent identity failure'), { code: 'EACCES' });
}
return originalRealpathSyncNative(file, ...args);
};
process.argv = [process.execPath, ${JSON.stringify(cli)}, 'compare', 'architecture', ${JSON.stringify(base)}, ${JSON.stringify(head)}, ${JSON.stringify(output)}, '--receipt', ${JSON.stringify(receipt)}, '--json'];
await import(${JSON.stringify(pathToFileURL(cli).href)});
`);
const result = spawnSync(process.execPath, [wrapper], { cwd, encoding: 'utf8' });
assert.equal(result.status, 1, result.stderr || result.stdout);
const failure = JSON.parse(result.stdout);
assert.equal(failure.diagnostics[0].code, 'delta/receipt-directory-identity-indeterminate');
assert.equal(failure.diagnostics[0].evidence.pathIdentity.systemCode, 'EACCES');
assert.equal(fs.existsSync(output), false);
assert.equal(fs.existsSync(receipt), false);
});
test('delivery provenance accepts an artifact reached through a directory alias', t => {
const cwd = workspace(t);
const outputDirectory = path.join(cwd, 'physical-output');
const directoryAlias = path.join(cwd, 'output-alias');
fs.mkdirSync(outputDirectory);
try {
fs.symlinkSync(outputDirectory, directoryAlias, process.platform === 'win32' ? 'junction' : 'dir');
} catch (error) {
if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) {
t.skip('directory aliases require permission');
return;
}
throw error;
}
const output = path.join(outputDirectory, 'delivered.html');
const alias = path.join(directoryAlias, 'delivered.html');
const delivered = run(['deliver', 'workflow', workflow, output, '--json'], cwd);
assert.equal(delivered.status, 0, delivered.stderr || delivered.stdout);
const checked = run(['check', alias, '--require-provenance'], cwd);
assert.equal(checked.status, 0, checked.stderr || checked.stdout);
assert.equal(JSON.parse(checked.stdout).provenance, 'current');
});
test('delivery provenance fails closed when recorded output identity is indeterminate', t => {
const cwd = workspace(t);
const output = path.join(cwd, 'delivered.html');
const delivered = run(['deliver', 'workflow', workflow, output, '--json'], cwd);
assert.equal(delivered.status, 0, delivered.stderr || delivered.stdout);
const artifactBefore = fs.readFileSync(output);
const provenancePath = output.replace(/\.html$/i, '.delivery.json');
const provenance = JSON.parse(fs.readFileSync(provenancePath, 'utf8'));
provenance.output = path.join(cwd, 'missing-recorded-output.html');
fs.writeFileSync(provenancePath, `${JSON.stringify(provenance, null, 2)}\n`);
const checked = run(['check', output, '--require-provenance'], cwd);
assert.equal(checked.status, 1, checked.stderr || checked.stdout);
const failure = JSON.parse(checked.stdout);
assert.equal(failure.diagnostics[0].code, 'delivery/provenance-output-indeterminate');
assert.equal(failure.diagnostics[0].subject.recordedOutput, provenance.output);
assert.equal(failure.diagnostics[0].evidence.pathIdentity.code, 'entry-missing');
assert.deepEqual(failure.diagnostics[0].evidence.pathIdentity.missing, ['left']);
assert.deepEqual(fs.readFileSync(output), artifactBefore);
assert.equal(JSON.parse(fs.readFileSync(provenancePath, 'utf8')).output, provenance.output);
});