Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(cli): prevent non-HTML output overwrites without restricting directories (#322)
tt-a1ied7f4d4b48d4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 30329104..0c81eebd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo> Development identity: `v2.17.0-dev.1`. Not a stable release.### Fixed+- **CLI output file types (#124).** Render, deliver, preview, and compare reject non-HTML artifact targets and compare rejects non-JSON receipt targets, including through symbolic links. Explicit absolute and parent-directory outputs remain supported; internal validation and inspection continue to work.- **License provenance in distributions.** Source and packaged Skill distributions retain Cocoon AI's exact MIT copyright notice, package staging and smoke tests fail closed when the notice or LICENSE is missing or altered, and the deterministic ZIP carries the same LICENSE bytes as the repository.- **Third-party mark notices in distributions.** Source and packaged Skill distributions now identify the pinned Simple Icons collection, disclose all individual icon licenses recorded by that version, preserve source and brand-guideline links, and state that Archify's MIT license does not replace third-party copyright or trademark terms. Package staging and smoke tests fail closed when the notice is missing or altered.- **Unsupported experiment source chains.** The Hivenue and Taiga Mermaid inputs and their generated derivatives are removed from the current tree because no verifiable redistribution license was available; the retained validation evidence now reports the remaining 3-source / 9-artifact set without rewriting historical results.diff --git a/archify.zip b/archify.zipindex 152a97c9..7337e82f 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex 034342ea..e727c8b5 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -444,12 +444,14 @@ async function commandCompare(args) {const basePath = path.resolve(baseInput);const headPath = path.resolve(headInput);+ const receiptTarget = options.receipt || compareReceiptPath(path.resolve(requestedOutput || 'architecture-delta.html'));let outputPath;try {({ outputPath } = resolveOutputPath({requestedOutput,defaultOutput: 'architecture-delta.html',inputPaths: [basePath, headPath],+ otherOutputPaths: [path.resolve(receiptTarget)],}));} catch (error) {const outputDiagnostic = error.archifyDiagnostics?.[0];@@ -471,6 +473,7 @@ async function commandCompare(args) {({ outputPath: receiptPath } = resolveOutputPath({requestedOutput: options.receipt || compareReceiptPath(outputPath),defaultOutput: compareReceiptPath(outputPath),+ requiredExtension: '.json',inputPaths: [basePath, headPath],otherOutputPaths: [outputPath],}));@@ -640,10 +643,12 @@ async function commandCompare(args) {requestedOutput,defaultOutput: 'architecture-delta.html',inputPaths: [basePath, headPath],+ otherOutputPaths: [receiptPath],}).outputPath;resolveOutputPath({requestedOutput: options.receipt || compareReceiptPath(currentOutput),defaultOutput: compareReceiptPath(currentOutput),+ requiredExtension: '.json',inputPaths: [basePath, headPath],otherOutputPaths: [currentOutput],});@@ -1835,7 +1840,9 @@ function commandValidate(args) {if (!['architecture', 'workflow'].includes(type)) {fail('--layout-json is currently supported for architecture and workflow diagrams only.');}- const result = runNode([renderer, input, '/dev/null', '--layout-json'], {+ // Layout mode emits JSON without writing HTML; keep its unused target typed.+ const layoutOutput = path.join(os.tmpdir(), `archify-layout-${process.pid}-${type}.html`);+ const result = runNode([renderer, input, layoutOutput, '--layout-json'], {stdio: 'pipe',env: rendererEnv(quality, repoRoot, true),});diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 31f2c1dc..301d7df7 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -2,7 +2,15 @@## Validate and deliver-Use `validate` after every candidate edit. Use final atomic delivery only after the candidate is frozen:+Use `validate` after every candidate edit. CLI HTML output paths must end in `.html`, including after symbolic-link resolution.+Compare receipt paths must end in `.json`. Explicit CLI paths may be absolute or+outside the current working directory; authored `meta.output` remains confined+to that directory. A type mismatch fails before writing with+`output/cli-extension` or `output/cli-resolved-extension`. These checks prevent+accidental file-type overwrites; they do not sandbox explicit CLI directories+or prevent replacement of an existing artifact of the expected type.++Use final atomic delivery only after the candidate is frozen:```bashnode bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --jsondiff --git a/archify/renderers/shared/output-path.mjs b/archify/renderers/shared/output-path.mjsindex ca911965..e8e480a2 100644--- a/archify/renderers/shared/output-path.mjs+++ b/archify/renderers/shared/output-path.mjs@@ -255,6 +255,7 @@ export function resolveOutputPath({inputDescription = 'an input',otherOutputPaths = [],cwd = process.cwd(),+ requiredExtension = '.html',}) {const rawOutput = requestedOutput || authoredOutput || defaultOutput;const source = requestedOutput ? 'cli' : (authoredOutput ? 'meta' : 'default');@@ -314,6 +315,24 @@ export function resolveOutputPath({});}+ // Keep explicit CLI directories unrestricted, but reject mistaken file types.+ // Alias checks above retain priority when a target would overwrite an input.+ if (source === 'cli') {+ const resolvedOutput = canonicalFuturePath(outputPath);+ const authoredMatches = path.extname(rawOutput).toLowerCase() === requiredExtension;+ const resolvedMatches = path.extname(resolvedOutput).toLowerCase() === requiredExtension;+ if (!authoredMatches || !resolvedMatches) {+ const message = `CLI output must ${authoredMatches ? 'resolve to' : 'target'} a ${requiredExtension} file.`;+ throw new OutputPathError(message, {+ code: authoredMatches ? 'output/cli-resolved-extension' : 'output/cli-extension',+ message,+ subject: { output: rawOutput },+ evidence: { resolvedOutput, requiredExtension },+ supportedFixes: [`choose a path ending in ${requiredExtension} whose symbolic-link target also ends in ${requiredExtension}`],+ });+ }+ }+return {outputPath,source,diff --git a/archify/test/cli-output-types.test.mjs b/archify/test/cli-output-types.test.mjsnew file mode 100644index 00000000..2676c479--- /dev/null+++ b/archify/test/cli-output-types.test.mjs@@ -0,0 +1,201 @@+import { spawnSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import test from 'node:test';+import assert from 'node:assert/strict';+import { startPreview } from '../bin/preview.mjs';++const root = fileURLToPath(new URL('../', 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);+});diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjsindex 56d48fb2..702ccd54 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -584,7 +584,7 @@ test('cli: invalid source output metadata still fails inside the renderer', () =test('cli: deliver reports commit failure without a false success receipt', () => {const input = path.join(skillRoot, 'examples/web-app.architecture.json');- const outputDirectory = path.join(tmp, 'commit-target-is-a-directory');+ const outputDirectory = path.join(tmp, 'commit-target-is-a-directory.html');fs.mkdirSync(outputDirectory, { recursive: true });const result = run(['deliver', 'architecture', input, outputDirectory, '--json']);diff --git a/archify/test/output-path.test.mjs b/archify/test/output-path.test.mjsindex 296be60f..51a54518 100644--- a/archify/test/output-path.test.mjs+++ b/archify/test/output-path.test.mjs@@ -94,9 +94,9 @@ test('compare rejects case-only future targets before input work when the directconst receipt = JSON.parse(result.stdout);assert.equal(receipt.diagnostics[0].code,- caseInsensitive ? 'output/target-alias' : 'delta/base-input',+ caseInsensitive ? 'output/target-alias' : 'output/cli-extension',);- assert.equal(receipt.stage, caseInsensitive ? 'prepare' : 'input');+ assert.equal(receipt.stage, 'prepare');});test('render reports an output symlink cycle as a structured output diagnostic', () => {@@ -301,8 +301,8 @@ console.log(JSON.stringify({fs.mkdirSync(inputDirectory);fs.mkdirSync(initialOutputDirectory);fs.symlinkSync(initialOutputDirectory, linkedDirectory, 'dir');- const input = path.join(inputDirectory, 'diagram.json');- const output = path.join(linkedDirectory, 'diagram.json');+ const input = path.join(inputDirectory, 'diagram.html');+ const output = path.join(linkedDirectory, 'diagram.html');const source = Buffer.from('{"meta":{"title":"race input"}}');fs.writeFileSync(input, source);const marker = path.join(cwd, 'renderer-started');@@ -434,8 +434,8 @@ test('the shared renderer rechecks its guarded output immediately before writingfs.mkdirSync(inputDirectory);fs.mkdirSync(initialOutputDirectory);fs.symlinkSync(initialOutputDirectory, linkedDirectory, 'dir');- const input = path.join(inputDirectory, 'diagram.workflow.json');- const output = path.join(linkedDirectory, 'diagram.workflow.json');+ const input = path.join(inputDirectory, 'diagram.workflow.html');+ const output = path.join(linkedDirectory, 'diagram.workflow.html');const source = fs.readFileSync(workflowFixture);fs.writeFileSync(input, source);@@ -527,9 +527,9 @@ export const validateArchitectureDeltaHtml = () => ({ checksPassed: 1, checkCounfs.mkdirSync(inputDirectory);fs.mkdirSync(initialOutputDirectory);fs.symlinkSync(initialOutputDirectory, linkedDirectory, 'dir');- const base = path.join(inputDirectory, 'diagram.json');+ const base = path.join(inputDirectory, 'diagram.html');const head = path.join(cwd, 'head.json');- const output = path.join(linkedDirectory, 'diagram.json');+ const output = path.join(linkedDirectory, 'diagram.html');const source = Buffer.from('{"side":"base"}');fs.writeFileSync(base, source);fs.writeFileSync(head, '{"side":"head"}');