Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(cli): keep JSON argument failures machine-readable

QiuLsGbdb65677b777
diff --git a/CHANGELOG.md b/CHANGELOG.md
index de3c8bed..6442c167 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
+- **Machine-readable CLI argument failures (#330).** `validate --json` and `deliver --json` now keep invalid or missing option values, unknown options and diagram types, unsupported option combinations, and usage errors inside one versioned failure receipt on stdout. These failures use the `arguments` stage, stable diagnostic codes, and exit status 2, while human-mode stderr behavior remains unchanged.
- **Complete artifact-check receipts (#311).** The checker now lets stdout drain before exiting, so large JSON receipts remain complete through pipes. Validation, delivery, and architecture comparison retain their original success/failure status without truncated-JSON errors.
- **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.
diff --git a/archify.zip b/archify.zip
index b75a9d23..54c4318f 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index e727c8b5..2bb1c20a 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -40,9 +40,25 @@ function fail(message, code = 2) {
process.exit(code);
}
+function rejectCliArgument(message, details = {}) {
+ const error = new Error(message);
+ error.archifyArgument = {
+ code: details.code || 'cli/invalid-arguments',
+ subject: details.subject || {},
+ evidence: details.evidence || {},
+ supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
+ };
+ throw error;
+}
+
function rendererPath(type) {
if (!TYPES.has(type)) {
- fail(`Unknown diagram type "${type}". Expected one of: ${[...TYPES].join(', ')}`);
+ rejectCliArgument(`Unknown diagram type "${type}". Expected one of: ${[...TYPES].join(', ')}`, {
+ code: 'cli/unknown-diagram-type',
+ subject: { type },
+ evidence: { supportedTypes: [...TYPES] },
+ supportedFixes: [`use one of: ${[...TYPES].join(', ')}`],
+ });
}
return path.join(skillRoot, 'renderers', type, `render-${type}.mjs`);
}
@@ -63,19 +79,32 @@ function extractQualityArgs(args) {
const arg = args[index];
if (arg === '--quality') {
quality = args[index + 1];
- if (!quality || quality.startsWith('--')) fail('--quality requires standard or showcase.');
+ if (!quality || quality.startsWith('--')) rejectCliArgument('--quality requires standard or showcase.', {
+ code: 'cli/missing-option-value',
+ subject: { option: '--quality' },
+ supportedFixes: ['provide --quality standard or --quality showcase'],
+ });
index += 1;
continue;
}
if (arg.startsWith('--quality=')) {
quality = arg.slice('--quality='.length);
- if (!quality) fail('--quality requires standard or showcase.');
+ if (!quality) rejectCliArgument('--quality requires standard or showcase.', {
+ code: 'cli/missing-option-value',
+ subject: { option: '--quality' },
+ supportedFixes: ['provide --quality standard or --quality showcase'],
+ });
continue;
}
rest.push(arg);
}
if (quality !== undefined && !['standard', 'showcase'].includes(quality)) {
- fail(`Unknown quality profile "${quality}". Expected standard or showcase.`);
+ rejectCliArgument(`Unknown quality profile "${quality}". Expected standard or showcase.`, {
+ code: 'cli/invalid-option-value',
+ subject: { option: '--quality' },
+ evidence: { value: quality, supportedValues: ['standard', 'showcase'] },
+ supportedFixes: ['use --quality standard or --quality showcase'],
+ });
}
return { rest, quality };
}
@@ -87,13 +116,21 @@ function extractRepoRootArgs(args) {
const arg = args[index];
if (arg === '--repo-root') {
repoRoot = args[index + 1];
- if (!repoRoot || repoRoot.startsWith('--')) fail('--repo-root requires a repository path.');
+ if (!repoRoot || repoRoot.startsWith('--')) rejectCliArgument('--repo-root requires a repository path.', {
+ code: 'cli/missing-option-value',
+ subject: { option: '--repo-root' },
+ supportedFixes: ['provide one repository path after --repo-root'],
+ });
index += 1;
continue;
}
if (arg.startsWith('--repo-root=')) {
repoRoot = arg.slice('--repo-root='.length);
- if (!repoRoot) fail('--repo-root requires a repository path.');
+ if (!repoRoot) rejectCliArgument('--repo-root requires a repository path.', {
+ code: 'cli/missing-option-value',
+ subject: { option: '--repo-root' },
+ supportedFixes: ['provide one repository path after --repo-root'],
+ });
continue;
}
rest.push(arg);
@@ -241,7 +278,11 @@ function formatDiagnostics(error, diagnostics = []) {
function assertEvidenceType(type, repoRoot) {
if (repoRoot && type !== 'architecture') {
- fail('--repo-root is currently supported for architecture diagrams only.');
+ rejectCliArgument('--repo-root is currently supported for architecture diagrams only.', {
+ code: 'cli/unsupported-option',
+ subject: { option: '--repo-root', type },
+ supportedFixes: ['remove --repo-root or use an architecture diagram'],
+ });
}
}
@@ -743,6 +784,24 @@ function reportValidateFailure(options) {
reportArtifactFailure({ ...options, command: 'validate' });
}
+function reportArtifactArgumentFailure(command, error) {
+ const details = error.archifyArgument || {};
+ reportArtifactFailure({
+ command,
+ json: true,
+ stage: 'arguments',
+ error: error.message,
+ diagnostics: [diagnostic({
+ code: details.code || 'cli/invalid-arguments',
+ message: error.message,
+ subject: { command, ...(details.subject || {}) },
+ evidence: details.evidence || {},
+ supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
+ })],
+ status: 2,
+ });
+}
+
function sourceEvidenceFromArtifact(artifact) {
const html = artifact.toString('utf8');
const match = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);
@@ -760,20 +819,26 @@ function engineeringProfileFromArtifact(artifact) {
}
async function commandDeliver(args) {
- const { resolveOutputPath } = await import('../renderers/shared/output-path.mjs');
const qualityArgs = extractQualityArgs(args);
const repoArgs = extractRepoRootArgs(qualityArgs.rest);
const json = repoArgs.rest.includes('--json');
const open = repoArgs.rest.includes('--open');
const knownOptions = new Set(['--json', '--open']);
const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
- if (unknown.length) fail(`Unknown deliver option "${unknown[0]}".`);
+ if (unknown.length) rejectCliArgument(`Unknown deliver option "${unknown[0]}".`, {
+ code: 'cli/unknown-option',
+ subject: { option: unknown[0] },
+ supportedFixes: ['remove the unknown option and retry'],
+ });
const positional = repoArgs.rest.filter((arg) => !knownOptions.has(arg));
const [type, input, requestedOutput] = positional;
- if (!type || !input || positional.length > 3) fail(usage());
+ if (!type || !input || positional.length > 3) rejectCliArgument(usage(), {
+ code: 'cli/usage',
+ supportedFixes: ['use: archify deliver <type> <input.json> [output.html] [options]'],
+ });
assertEvidenceType(type, repoArgs.repoRoot);
-
const renderer = rendererPath(type);
+ const { resolveOutputPath } = await import('../renderers/shared/output-path.mjs');
const inputPath = path.resolve(input);
let specification;
let diagram;
@@ -1827,19 +1892,31 @@ function commandValidate(args) {
const repoRoot = repoArgs.repoRoot;
const knownOptions = new Set(['--json', '--layout-json']);
const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
- if (unknown.length) fail(`Unknown validate option "${unknown[0]}".`);
+ if (unknown.length) rejectCliArgument(`Unknown validate option "${unknown[0]}".`, {
+ code: 'cli/unknown-option',
+ subject: { option: unknown[0] },
+ supportedFixes: ['remove the unknown option and retry'],
+ });
const json = args.includes('--json');
const layoutJson = args.includes('--layout-json');
const rest = args.filter((arg) => !knownOptions.has(arg));
const [type, input] = rest;
- if (!type || !input || rest.length !== 2) fail(usage());
+ if (!type || !input || rest.length !== 2) rejectCliArgument(usage(), {
+ code: 'cli/usage',
+ supportedFixes: ['use: archify validate <type> <input.json> [options]'],
+ });
assertEvidenceType(type, repoRoot);
const renderer = rendererPath(type);
+ if (layoutJson && !['architecture', 'workflow'].includes(type)) {
+ rejectCliArgument('--layout-json is currently supported for architecture and workflow diagrams only.', {
+ code: 'cli/unsupported-option',
+ subject: { option: '--layout-json', type },
+ supportedFixes: ['remove --layout-json or use an architecture or workflow diagram'],
+ });
+ }
+
if (layoutJson) {
- if (!['architecture', 'workflow'].includes(type)) {
- fail('--layout-json is currently supported for architecture and workflow diagrams only.');
- }
// 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'], {
@@ -1947,58 +2024,67 @@ function commandValidate(args) {
const [command, ...args] = process.argv.slice(2);
-switch (command) {
- case undefined:
- case '-h':
- case '--help':
- case 'help':
- console.log(usage());
- break;
- case 'render':
- commandRender(args);
- break;
- case 'compare':
- await commandCompare(args);
- break;
- case 'deliver':
- await commandDeliver(args);
- break;
- case 'preview':
- await commandPreview(args);
- break;
- case 'validate':
- commandValidate(args);
- break;
- case 'migrate':
- await commandMigrate(args);
- break;
- case 'inspect':
- if (args[0] !== 'architecture') {
- fail('inspect is currently supported for architecture diagrams only.');
- }
- commandValidate([...args, '--layout-json']);
- break;
- case 'check':
- commandCheck(args);
- break;
- case 'visual-check':
- await commandVisualCheck(args);
- break;
- case 'guide':
- await commandGuide(args);
- break;
- case 'brands':
- await commandBrands(args);
- break;
- case 'examples':
- commandExamples();
- break;
- case 'doctor':
- await commandDoctor();
- break;
- case 'demo':
- commandDemo(args);
- break;
- default:
- fail(`Unknown command "${command}".\n\n${usage()}`);
+try {
+ switch (command) {
+ case undefined:
+ case '-h':
+ case '--help':
+ case 'help':
+ console.log(usage());
+ break;
+ case 'render':
+ commandRender(args);
+ break;
+ case 'compare':
+ await commandCompare(args);
+ break;
+ case 'deliver':
+ await commandDeliver(args);
+ break;
+ case 'preview':
+ await commandPreview(args);
+ break;
+ case 'validate':
+ commandValidate(args);
+ break;
+ case 'migrate':
+ await commandMigrate(args);
+ break;
+ case 'inspect':
+ if (args[0] !== 'architecture') {
+ fail('inspect is currently supported for architecture diagrams only.');
+ }
+ commandValidate([...args, '--layout-json']);
+ break;
+ case 'check':
+ commandCheck(args);
+ break;
+ case 'visual-check':
+ await commandVisualCheck(args);
+ break;
+ case 'guide':
+ await commandGuide(args);
+ break;
+ case 'brands':
+ await commandBrands(args);
+ break;
+ case 'examples':
+ commandExamples();
+ break;
+ case 'doctor':
+ await commandDoctor();
+ break;
+ case 'demo':
+ commandDemo(args);
+ break;
+ default:
+ fail(`Unknown command "${command}".\n\n${usage()}`);
+ }
+} catch (error) {
+ if (!error.archifyArgument) throw error;
+ if (['validate', 'deliver'].includes(command) && args.includes('--json')) {
+ reportArtifactArgumentFailure(command, error);
+ } else {
+ fail(error.message);
+ }
}
diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjs
index 702ccd54..52a8c15c 100644
--- a/archify/test/cli.test.mjs
+++ b/archify/test/cli.test.mjs
@@ -713,8 +713,8 @@ test('cli: rejects an unknown quality profile', () => {
test('cli: rejects a quality flag without a value', () => {
const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
for (const args of [
- ['validate', 'workflow', input, '--json', '--quality'],
- ['validate', 'workflow', input, '--quality', '--json'],
+ ['validate', 'workflow', input, '--quality'],
+ ['deliver', 'workflow', input, '--quality='],
['validate', 'workflow', input, '--quality='],
]) {
const result = run(args);
@@ -734,10 +734,6 @@ test('cli: validate rejects unknown flags, layout-json assignment typos, and ext
args: ['validate', 'workflow', input, '--layout-json=true'],
pattern: /Unknown validate option "--layout-json=true"/,
},
- {
- args: ['validate', 'workflow', input, '--layout-json=true', '--json'],
- pattern: /Unknown validate option "--layout-json=true"/,
- },
{
args: ['validate', 'workflow', input, 'unexpected-output.html', '--layout-json'],
pattern: /Usage:/,
@@ -752,6 +748,125 @@ test('cli: validate rejects unknown flags, layout-json assignment typos, and ext
}
});
+test('cli: validate and deliver keep argument failures machine-readable with --json', () => {
+ const workflow = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
+ const sequence = path.join(skillRoot, 'examples/cache-miss-request.sequence.json');
+ const cases = [
+ {
+ args: ['validate', '--json'],
+ command: 'validate',
+ code: 'cli/usage',
+ },
+ {
+ args: ['validate', '--json', 'workflow', workflow, '--quality', 'hero'],
+ command: 'validate',
+ code: 'cli/invalid-option-value',
+ subject: { option: '--quality' },
+ },
+ {
+ args: ['validate', 'workflow', workflow, '--quality', '--json'],
+ command: 'validate',
+ code: 'cli/missing-option-value',
+ subject: { option: '--quality' },
+ },
+ {
+ args: ['validate', 'workflow', workflow, '--quality=', '--json'],
+ command: 'validate',
+ code: 'cli/missing-option-value',
+ subject: { option: '--quality' },
+ },
+ {
+ args: ['validate', 'workflow', workflow, '--layout-json=true', '--json'],
+ command: 'validate',
+ code: 'cli/unknown-option',
+ subject: { option: '--layout-json=true' },
+ },
+ {
+ args: ['validate', '--bogus', 'payload', 'workflow', workflow, '--json'],
+ command: 'validate',
+ code: 'cli/unknown-option',
+ subject: { option: '--bogus' },
+ },
+ {
+ args: ['validate', 'workflow', workflow, 'unexpected-output.html', '--json'],
+ command: 'validate',
+ code: 'cli/usage',
+ },
+ {
+ args: ['validate', 'unknown', workflow, '--json'],
+ command: 'validate',
+ code: 'cli/unknown-diagram-type',
+ subject: { type: 'unknown' },
+ },
+ {
+ args: ['validate', 'workflow', workflow, '--repo-root', '.', '--json'],
+ command: 'validate',
+ code: 'cli/unsupported-option',
+ subject: { option: '--repo-root', type: 'workflow' },
+ },
+ {
+ args: ['validate', 'architecture', workflow, '--repo-root=', '--json'],
+ command: 'validate',
+ code: 'cli/missing-option-value',
+ subject: { option: '--repo-root' },
+ },
+ {
+ args: ['validate', 'sequence', sequence, '--layout-json', '--json'],
+ command: 'validate',
+ code: 'cli/unsupported-option',
+ subject: { option: '--layout-json', type: 'sequence' },
+ },
+ {
+ args: ['deliver', '--json', 'workflow', workflow, '--bogus'],
+ command: 'deliver',
+ code: 'cli/unknown-option',
+ subject: { option: '--bogus' },
+ },
+ {
+ args: ['deliver', '--json'],
+ command: 'deliver',
+ code: 'cli/usage',
+ },
+ {
+ args: ['deliver', 'workflow', workflow, '--repo-root', '--json'],
+ command: 'deliver',
+ code: 'cli/missing-option-value',
+ subject: { option: '--repo-root' },
+ },
+ {
+ args: ['deliver', 'unknown', workflow, '--json'],
+ command: 'deliver',
+ code: 'cli/unknown-diagram-type',
+ subject: { type: 'unknown' },
+ },
+ {
+ args: ['deliver', 'workflow', workflow, 'diagram.html', 'extra.html', '--json'],
+ command: 'deliver',
+ code: 'cli/usage',
+ },
+ ];
+
+ for (const { args, command, code, subject = {} } of cases) {
+ const result = run(args);
+ assert.equal(result.status, 2, `${args.join(' ')}\n${result.stderr}\n${result.stdout}`);
+ assert.equal(result.stderr, '');
+ const failure = JSON.parse(result.stdout);
+ assert.equal(failure.schemaVersion, 1);
+ assert.equal(failure.ok, false);
+ assert.equal(failure.command, command);
+ assert.equal(failure.stage, 'arguments');
+ assert.equal('type' in failure, false);
+ assert.equal('input' in failure, false);
+ assert.equal(failure.diagnostics.length, 1);
+ assert.equal(failure.diagnostics[0].code, code);
+ assert.equal(failure.diagnostics[0].severity, 'error');
+ assert.deepEqual(failure.diagnostics[0].subject, { command, ...subject });
+ assert.ok(failure.diagnostics[0].supportedFixes.length > 0);
+ assert.equal('stack' in failure, false);
+ assert.equal('stack' in failure.diagnostics[0], false);
+ }
+});
+
test('cli: inspect emits architecture layout json', () => {
const input = path.resolve(skillRoot, '../examples/archify-repo-grid.architecture.json');
const result = run(['inspect', 'architecture', input]);