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
#!/usr/bin/env node
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 { assertThirdPartyNotices } from './third-party-notices-contract.mjs';
import { verifyPackagedUpdateChecker } from './package-update-smoke.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(__dirname, '..');
const noticeComparisonRoot = path.resolve(
process.env.ARCHIFY_PACKAGE_SMOKE_NOTICE_ROOT || repoRoot,
);
const defaultPackageRoot = process.env.RUNNER_TEMP
? path.join(process.env.RUNNER_TEMP, 'archify-package', 'archify')
: path.join(repoRoot, 'archify');
const skillRoot = path.resolve(process.argv[2] || defaultPackageRoot);
const cli = path.join(skillRoot, 'bin', 'archify.mjs');
const updateChecker = path.join(skillRoot, 'scripts', 'check-update.mjs');
const updateContract = path.join(skillRoot, 'scripts', 'update-contract.mjs');
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-smoke-'));
function requireAbsent(relative) {
if (fs.existsSync(path.join(skillRoot, relative))) {
throw new Error(`packaged skill must not contain ${relative}`);
}
}
function run(args, options = {}) {
const result = spawnSync(process.execPath, [cli, ...args], {
cwd: skillRoot,
encoding: 'utf8',
...options,
});
if (result.status !== 0) {
throw new Error([
`archify ${args.join(' ')} failed with ${result.status}`,
result.stdout,
result.stderr,
].filter(Boolean).join('\n'));
}
return result.stdout;
}
function runExpectFailure(args, options = {}) {
const result = spawnSync(process.execPath, [cli, ...args], {
cwd: skillRoot,
encoding: 'utf8',
...options,
});
if (result.status === 0) throw new Error(`archify ${args.join(' ')} unexpectedly passed`);
return result.stdout;
}
async function verifyPackagedExplainer() {
// Exercise the installed parser, preparation, native diagram runtime, reader
// assets, document checker and patcher through public CLI calls outside cwd.
const explainerInput = path.join(scratch, 'package-explainer.md');
const explainerOutput = path.join(scratch, 'package-explainer.html');
const explainerText = '# How does the request move? {#package-explainer}\n\nThe API sends the request to Redis.\n\n'
+ '## What is the route? {#route}\n\nRead the [API](node:request.api) before following the request.\n\n'
+ '@sequence id=request\n| actor api | API | backend |\n| actor redis | Redis | database |\n| api | redis | GET key |\n\n'
+ '## What can change? {#notes}\n\nThis panel can be revised independently.\n';
fs.writeFileSync(explainerInput, explainerText);
const explainerOptions = { cwd: scratch, env: { ...process.env, ARCHIFY_UPDATE_CHECK_DISABLED: '1' } };
const validateExplainer = JSON.parse(run(['validate', 'explainer', explainerInput, '--json'], explainerOptions));
if (!validateExplainer.ok || validateExplainer.type !== 'explainer' || !validateExplainer.candidate?.sha256) {
throw new Error('packaged explainer did not validate the authored parser input');
}
const deliveredExplainer = JSON.parse(run(['deliver', 'explainer', explainerInput, explainerOutput, '--json'], explainerOptions));
const checkedExplainer = JSON.parse(run(['check', explainerOutput, '--require-provenance', '--json'], explainerOptions));
if (!deliveredExplainer.ok || !checkedExplainer.ok || checkedExplainer.deliveryReceiptId !== deliveredExplainer.receiptId) {
throw new Error('packaged explainer delivery did not bind its strict checker receipt');
}
const { scanHtml } = await import(pathToFileURL(path.join(skillRoot, 'explainer/check.mjs')).href);
const preparedExplainer = file => {
const payload = scanHtml(fs.readFileSync(file, 'utf8')).scripts.find(script => script.attrs.id === 'archify-explainer-prepared');
return JSON.parse(payload?.text || 'null');
};
const originalExplainer = preparedExplainer(explainerOutput);
const requestDiagram = originalExplainer?.preparedDiagrams?.diagrams?.request;
if (originalExplainer?.sourceText !== explainerText || requestDiagram?.checks?.check?.ok !== true
|| !requestDiagram.semantic.nodes.some(node => node.id === 'api')
|| !requestDiagram.semantic.nodes.some(node => node.id === 'redis')
|| !requestDiagram.semantic.edges.some(edge => edge.from === 'api' && edge.to === 'redis')) {
throw new Error('packaged explainer lost authored text or native semantic graph evidence');
}
const replacementPanel = path.join(scratch, 'package-replacement.md');
const patchedExplainerOutput = path.join(scratch, 'package-explainer-patched.html');
fs.writeFileSync(replacementPanel, '## What can change? {#notes}\n\nThe selected panel has updated content.\n');
const patchedExplainer = JSON.parse(run(['patch', 'explainer', explainerOutput, 'notes', replacementPanel, patchedExplainerOutput, '--json'], explainerOptions));
const patchedPrepared = preparedExplainer(patchedExplainerOutput);
if (!patchedExplainer.ok || patchedExplainer.command !== 'patch'
|| patchedPrepared.document.panels[1].blocks[0].text !== 'The selected panel has updated content.'
|| JSON.stringify(patchedPrepared.document.panels[0]) !== JSON.stringify(originalExplainer.document.panels[0])
|| patchedPrepared.preparedDiagrams.diagrams.request.sha256 !== requestDiagram.sha256) {
throw new Error('packaged explainer patch changed an untouched native diagram or failed to replace its panel');
}
run(['check', patchedExplainerOutput, '--require-provenance', '--json'], explainerOptions);
const browserUnavailable = JSON.parse(runExpectFailure(['browser-check', explainerOutput, '--require-provenance', '--json'], {
...explainerOptions, env: { ...explainerOptions.env, ARCHIFY_CHROME: path.join(scratch, 'missing-explainer-chrome') },
}));
if (browserUnavailable.status !== 'skipped' || browserUnavailable.chrome?.status !== 'unavailable') {
throw new Error('packaged explainer browser runtime did not report the explicit unavailable browser');
}
process.stdout.write('packaged explainer parser, native graph, delivery, strict check and panel patch passed without dependencies\n');
}
async function verifyPackage() {
if (!fs.existsSync(cli)) throw new Error(`packaged CLI not found at ${cli}`);
requireAbsent('node_modules');
requireAbsent('package-lock.json');
requireAbsent(path.join('scripts', 'generate-validators.mjs'));
requireAbsent(path.join('scripts', 'generate-brand-marks.mjs'));
requireAbsent('test');
requireAbsent('.hive');
requireAbsent('.workbuddy');
if (process.argv.includes('--explainer-only')) {
await verifyPackagedExplainer();
process.stdout.write(`explainer package smoke passed on ${process.platform} (${skillRoot})\n`);
return;
}
const packageLicensePath = path.join(skillRoot, 'LICENSE');
if (!fs.existsSync(packageLicensePath)) {
throw new Error('packaged skill is missing LICENSE');
}
const packageLicense = fs.readFileSync(packageLicensePath, 'utf8');
const repositoryLicense = fs.readFileSync(path.join(repoRoot, 'LICENSE'), 'utf8');
if (packageLicense !== repositoryLicense) {
throw new Error('packaged LICENSE must byte-match the repository LICENSE');
}
for (const name of ['LICENSE-MIT', 'NOTICE']) {
const target = path.join(skillRoot, name);
if (!fs.existsSync(target)) throw new Error(`packaged skill is missing ${name}`);
if (!fs.readFileSync(target).equals(fs.readFileSync(path.join(repoRoot, name)))) {
throw new Error(`packaged ${name} must byte-match the repository ${name}`);
}
}
const legacyLicense = fs.readFileSync(path.join(skillRoot, 'LICENSE-MIT'), 'utf8');
if (!legacyLicense.split(/\r?\n/).includes('Copyright (c) 2025 Cocoon AI') ||
!legacyLicense.includes('The above copyright notice and this permission notice shall be included in all')) {
throw new Error('packaged LICENSE-MIT is missing the original MIT copyright and permission notice');
}
const packageNoticesPath = path.join(skillRoot, 'THIRD_PARTY_NOTICES.md');
if (!fs.existsSync(packageNoticesPath)) {
throw new Error('packaged skill is missing THIRD_PARTY_NOTICES.md');
}
const packageNotices = fs.readFileSync(packageNoticesPath, 'utf8');
const repositoryNotices = fs.readFileSync(path.join(noticeComparisonRoot, 'THIRD_PARTY_NOTICES.md'), 'utf8');
const embeddedFonts = /data:font\/woff2/.test(fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8'));
if (embeddedFonts && !fs.existsSync(path.join(skillRoot, 'assets/JetBrainsMono-OFL.txt'))) {
throw new Error('embedded viewer font requires assets/JetBrainsMono-OFL.txt');
}
assertThirdPartyNotices(repositoryNotices, 'repository THIRD_PARTY_NOTICES.md', { embeddedFonts });
assertThirdPartyNotices(packageNotices, 'packaged THIRD_PARTY_NOTICES.md', { embeddedFonts });
if (packageNotices !== repositoryNotices) {
throw new Error('packaged THIRD_PARTY_NOTICES.md must byte-match the repository notice');
}
if (!fs.existsSync(updateChecker)) {
throw new Error(`packaged update checker not found at ${updateChecker}`);
}
if (!fs.existsSync(updateContract)) {
throw new Error(`packaged update contract not found at ${updateContract}`);
}
const packageJson = JSON.parse(fs.readFileSync(path.join(skillRoot, 'package.json'), 'utf8'));
const dependencyFields = [
'dependencies',
'devDependencies',
'optionalDependencies',
'peerDependencies',
'bundledDependencies',
'bundleDependencies',
];
const declaredDependencyField = dependencyFields.find((field) => (
Object.prototype.hasOwnProperty.call(packageJson, field)
));
if (declaredDependencyField) {
throw new Error(`packaged skill must not declare dependency metadata: ${declaredDependencyField}`);
}
const skillRelease = JSON.parse(fs.readFileSync(path.join(skillRoot, 'skill-release.json'), 'utf8'));
const contract = await import(pathToFileURL(updateContract).href);
let validatedRelease;
try {
validatedRelease = contract.validateLocalRelease(skillRelease);
} catch {
throw new Error('packaged skill-release.json violates the shared update contract');
}
if (validatedRelease.version !== packageJson.version) {
throw new Error('packaged skill-release.json does not match the package release identity');
}
await verifyPackagedUpdateChecker(skillRoot, path.join(scratch, 'update-cache'));
const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
const skillReferences = [...skill.matchAll(
/`((?:assets|bin|examples|explainer|recipes|references|renderers|schemas|scripts)\/[^`\s]+)`/g,
)]
.map((match) => match[1])
.filter((reference) => !/[<>{}*\[\]]/.test(reference));
if (skillReferences.length === 0) {
throw new Error('packaged SKILL.md did not expose any literal package paths');
}
for (const reference of new Set(skillReferences)) {
if (!fs.existsSync(path.join(skillRoot, reference))) {
throw new Error(`packaged SKILL.md references missing path ${reference}`);
}
}
run(['--help']);
run(['doctor']);
const brands = JSON.parse(run(['brands', 'openai', '--json']));
if (!brands.marks.some((mark) => mark.id === 'openai')) {
throw new Error('packaged brand catalogue did not resolve openai');
}
const capturedPreset = JSON.parse(run(['brands', 'capture', 'https://github.com/', '--json']));
if (capturedPreset.brand !== 'github' || capturedPreset.evidence.status !== 'preset') {
throw new Error('packaged brand capture did not resolve a known domain without network capture');
}
run(['demo', path.join(scratch, 'demo')]);
run(['examples']);
const fixtures = [
['architecture', 'production-deployment.architecture.json'],
['workflow', 'agent-tool-call.workflow.json'],
['sequence', 'cache-miss-request.sequence.json'],
['dataflow', 'product-analytics.dataflow.json'],
['lifecycle', 'agent-run.lifecycle.json'],
];
for (const [mode, fixture] of fixtures) {
const receipt = JSON.parse(run([
'validate', mode, path.join(skillRoot, 'examples', fixture), '--json',
]));
if (!receipt.ok || receipt.type !== mode) {
throw new Error(`${mode} package validation returned an invalid receipt`);
}
if (mode === 'architecture' && receipt.engineeringProfile !== 'deployment-ownership') {
throw new Error('deployment package validation omitted the engineering profile receipt');
}
}
await verifyPackagedExplainer();
const workflowLayout = JSON.parse(run([
'validate', 'workflow', path.join(skillRoot, 'examples', fixtures[1][1]),
'--layout-json', '--quality', 'showcase',
]));
if (workflowLayout.contract !== 'readable-v2'
|| workflowLayout.columns?.length !== 6
|| workflowLayout.diagnostics?.length !== 0) {
throw new Error('packaged workflow compiler did not expose a passing readable-v2 layout receipt');
}
const legacyWorkflow = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Package migration smoke',
output: 'package-migration-smoke.html',
viewBox: [720, 400],
legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'source', lane: 'main', col: 0, type: 'frontend', label: 'Source' },
{ id: 'target', lane: 'main', col: 2, type: 'backend', label: 'Target' },
],
edges: [{ id: 'flow', from: 'source', to: 'target', label: 'request' }],
};
const legacyWorkflowPath = path.join(scratch, 'legacy.workflow.json');
const migratedWorkflowPath = path.join(scratch, 'migrated.workflow.json');
const migratedAgainPath = path.join(scratch, 'migrated-again.workflow.json');
fs.writeFileSync(legacyWorkflowPath, `${JSON.stringify(legacyWorkflow, null, 2)}\n`);
const migrationReceipt = JSON.parse(run([
'migrate', 'workflow', legacyWorkflowPath, migratedWorkflowPath,
'--to-schema', '2', '--json',
]));
if (!migrationReceipt.ok || migrationReceipt.fromSchemaVersion !== 1
|| migrationReceipt.toSchemaVersion !== 2 || !fs.existsSync(migratedWorkflowPath)) {
throw new Error('packaged workflow migrator did not produce a schema-v2 destination');
}
const idempotenceReceipt = JSON.parse(run([
'migrate', 'workflow', migratedWorkflowPath, migratedAgainPath,
'--to-schema', '2', '--json',
]));
if (!idempotenceReceipt.ok || idempotenceReceipt.fromSchemaVersion !== 2
|| idempotenceReceipt.source?.sha256 !== idempotenceReceipt.destination?.sha256
|| !fs.readFileSync(migratedWorkflowPath).equals(fs.readFileSync(migratedAgainPath))) {
throw new Error('packaged workflow migrator did not preserve byte-identical v2 idempotence');
}
const deployment = path.join(scratch, 'deployment.html');
run(['render', 'architecture', path.join(skillRoot, 'examples', fixtures[0][1]), deployment]);
run(['check', deployment]);
// Bundled Viewer catalogs resolve from the installed package, not the cwd,
// and the artifact embeds only the selected catalog.
const manifest = JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales', 'manifest.json'), 'utf8'));
for (const { file } of manifest.catalogs) {
if (!fs.existsSync(path.join(skillRoot, 'locales', file))) {
throw new Error(`packaged locale manifest lists a missing catalog: ${file}`);
}
}
const localized = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', fixtures[0][1]), 'utf8'));
localized.meta.locale = 'ko';
localized.meta.output = 'localized.html';
const localizedInput = path.join(scratch, 'localized.architecture.json');
const localizedOutput = path.join(scratch, 'localized.html');
fs.writeFileSync(localizedInput, JSON.stringify(localized));
run(['render', 'architecture', localizedInput, localizedOutput], { cwd: os.tmpdir() });
const localizedHtml = fs.readFileSync(localizedOutput, 'utf8');
const embeddedLocale = localizedHtml.match(/<script id="archify-i18n-data" type="application\/json">([\s\S]*?)<\/script>/);
if (!localizedHtml.startsWith('<!DOCTYPE html>\n<html lang="ko"')
|| !localizedHtml.includes('>범례</text>')
|| JSON.parse(embeddedLocale?.[1] || '{}').locale !== 'ko') {
throw new Error('packaged renderer did not select the bundled ko catalog from meta.locale');
}
const compareReceipt = JSON.parse(run([
'compare', 'architecture',
path.join(skillRoot, 'examples', 'checkout-platform.base.architecture.json'),
path.join(skillRoot, 'examples', 'checkout-platform.head.architecture.json'),
path.join(scratch, 'architecture-delta.html'), '--json',
]));
if (!compareReceipt.ok || compareReceipt.completeness !== 'complete'
|| compareReceipt.validation?.checksPassed !== compareReceipt.validation?.checkCount) {
throw new Error('packaged Architecture compare did not return a complete passing receipt');
}
const delivered = JSON.parse(run([
'deliver', 'workflow', path.join(skillRoot, 'examples', fixtures[1][1]),
path.join(scratch, 'workflow-delivered.html'), '--quality', 'showcase', '--json',
]));
if (!delivered.ok || delivered.validation?.compositionStatus !== 'pass'
|| !/^[a-f0-9]{64}$/.test(delivered.specification?.sha256 || '')
|| !(delivered.specification?.bytes > 0)) {
throw new Error('packaged workflow delivery did not return a passing receipt');
}
const visualSkipped = JSON.parse(runExpectFailure([
'visual-check', delivered.output, '--json',
], {
env: { ...process.env, ARCHIFY_CHROME: path.join(scratch, 'missing-chrome') },
}));
if (visualSkipped.status !== 'skipped' || visualSkipped.visualReview !== 'pending'
|| visualSkipped.chrome?.status !== 'unavailable') {
throw new Error('packaged visual-check did not return the expected Chrome-unavailable receipt');
}
const emptyPath = path.join(scratch, 'empty-path');
fs.mkdirSync(emptyPath);
const openReceipt = JSON.parse(run([
'deliver', 'workflow', path.join(skillRoot, 'examples', fixtures[1][1]),
path.join(scratch, 'workflow-open-fallback.html'), '--open', '--json',
], { env: { ...process.env, PATH: emptyPath } }));
if (!openReceipt.ok || openReceipt.open?.status !== 'unsupported') {
throw new Error('packaged open fallback did not remain a successful unsupported handoff');
}
const invalidWorkflow = JSON.parse(fs.readFileSync(
path.join(skillRoot, 'examples', fixtures[1][1]), 'utf8',
));
invalidWorkflow.nodes[0].colour = 'cyan';
const invalidPath = path.join(scratch, 'invalid-workflow.json');
fs.writeFileSync(invalidPath, JSON.stringify(invalidWorkflow));
const failure = JSON.parse(runExpectFailure(['validate', 'workflow', invalidPath, '--json']));
if (failure.ok || !failure.diagnostics?.some((diagnostic) => diagnostic.code === 'schema/additionalProperties')) {
throw new Error('packaged skill did not return the expected unknown-field diagnostic');
}
const tangentEndpoint = {
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Endpoint direction smoke', output: 'endpoint-direction-smoke.html' },
components: [
{ id: 'source', type: 'external', label: 'Source', pos: [300, 100], size: [100, 60] },
{ id: 'target', type: 'backend', label: 'Target', pos: [100, 240], size: [100, 60] },
],
connections: [{
id: 'tangent',
from: 'source',
to: 'target',
fromSide: 'bottom',
toSide: 'top',
via: [[350, 200], [100, 200], [100, 240]],
}],
};
const tangentPath = path.join(scratch, 'tangent-endpoint.architecture.json');
fs.writeFileSync(tangentPath, JSON.stringify(tangentEndpoint));
const tangentFailure = JSON.parse(runExpectFailure(['validate', 'architecture', tangentPath, '--json']));
const tangentDiagnostic = tangentFailure.diagnostics?.find((diagnostic) => (
diagnostic.code === 'clean-flow/endpoint-side-direction'
));
if (tangentFailure.ok || tangentDiagnostic?.evidence?.authoredField !== 'toSide'
|| tangentDiagnostic?.evidence?.side !== 'top') {
throw new Error('packaged skill did not reject a tangential target-port entry with structured repair evidence');
}
const inferredBridge = {
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Inferred endpoint bridge smoke', output: 'inferred-endpoint-bridge.html' },
components: [
{ id: 'workspace', type: 'frontend', label: 'Workspace UI', pos: [40, 300], size: [120, 60] },
{ id: 'runtime-server', type: 'backend', label: 'Runtime Server', pos: [220, 300], size: [120, 60] },
{ id: 'runtime-store', type: 'backend', label: 'Runtime Store', pos: [400, 300], size: [120, 60] },
{ id: 'stream-hub', type: 'messagebus', label: 'Terminal Stream Hub', pos: [700, 100], size: [120, 60] },
],
connections: [{ id: 'terminal-return', from: 'stream-hub', to: 'workspace' }],
};
const inferredBridgePath = path.join(scratch, 'inferred-bridge.architecture.json');
const inferredBridgeHtml = path.join(scratch, 'inferred-bridge.html');
fs.writeFileSync(inferredBridgePath, JSON.stringify(inferredBridge));
run(['render', 'architecture', inferredBridgePath, inferredBridgeHtml]);
run(['check', inferredBridgeHtml]);
const inferredBridgeArtifact = fs.readFileSync(inferredBridgeHtml, 'utf8');
const bridgePoints = inferredBridgeArtifact.match(/data-edge-id="terminal-return"[^>]*data-composition-points="([^"]+)"/)?.[1]
.split(';').map(point => point.split(',').map(Number));
// Automatic sides and port offsets may improve; attachment and normals must hold.
const leavesBoxNormally = ([px, py], [nx, ny], { pos: [x, y], size: [w, h] }) => (
(px === x && py >= y && py <= y + h && nx < px && ny === py)
|| (px === x + w && py >= y && py <= y + h && nx > px && ny === py)
|| (py === y && px >= x && px <= x + w && ny < py && nx === px)
|| (py === y + h && px >= x && px <= x + w && ny > py && nx === px)
);
if (!bridgePoints || bridgePoints.length < 2
|| !bridgePoints.every(point => point.length === 2 && point.every(Number.isFinite))
|| !leavesBoxNormally(bridgePoints[0], bridgePoints[1], inferredBridge.components[3])
|| !leavesBoxNormally(bridgePoints.at(-1), bridgePoints.at(-2), inferredBridge.components[0])) {
throw new Error('packaged skill did not preserve inferred endpoint normals with a side-aware bridge');
}
process.stdout.write(`package smoke passed on ${process.platform} (${skillRoot})\n`);
}
try {
await verifyPackage();
} finally {
fs.rmSync(scratch, { recursive: true, force: true });
}