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
feat(visual-check): add --out-dir to write sidecars outside the artifact's folder
julianwirawan-hashac3dfa573608
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex 2b8cc7a7..11ebd97e 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -22,7 +22,7 @@ function usage() {archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]archify inspect <type> <input.json>archify check <output.html>- archify visual-check <output.html> [--json]+ archify visual-check <output.html> [--json] [--out-dir <dir>]archify guide [scenario or question] [--json] [--lang en|zh]archify brands [name, alias, domain, or category] [--json]archify brands capture <url> [--json]@@ -101,6 +101,27 @@ function extractRepoRootArgs(args) {return { rest, repoRoot: repoRoot ? path.resolve(repoRoot) : undefined };}+function extractOutDirArgs(args) {+ const rest = [];+ let outDir;+ for (let index = 0; index < args.length; index += 1) {+ const arg = args[index];+ if (arg === '--out-dir') {+ outDir = args[index + 1];+ if (!outDir || outDir.startsWith('--')) fail('--out-dir requires a directory path.');+ index += 1;+ continue;+ }+ if (arg.startsWith('--out-dir=')) {+ outDir = arg.slice('--out-dir='.length);+ if (!outDir) fail('--out-dir requires a directory path.');+ continue;+ }+ rest.push(arg);+ }+ return { rest, outDir: outDir ? path.resolve(outDir) : undefined };+}+function rendererEnv(quality, repoRoot, diagnosticJson = false) {return {...(quality ? { ARCHIFY_QUALITY_PROFILE: quality } : {}),@@ -1153,7 +1174,8 @@ function commandCheck(args) {if (result.status !== 0) exitFrom(result);}-async function commandVisualCheck(args) {+async function commandVisualCheck(rawArgs) {+ const { rest: args, outDir } = extractOutDirArgs(rawArgs);const json = args.includes('--json');const knownOptions = new Set(['--json']);const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));@@ -1170,7 +1192,7 @@ async function commandVisualCheck(args) {let result;try {- result = await runVisualCheck({ artifactPath: positional[0] });+ result = await runVisualCheck({ artifactPath: positional[0], outDir });} catch (error) {if (json) {console.log(JSON.stringify({@@ -1194,11 +1216,12 @@ async function commandVisualCheck(args) {if (json) {console.log(JSON.stringify(result.receipt, null, 2));} else {+ const sidecarDirectory = outDir || path.dirname(result.receipt.artifact.path);console.log(`automated browser evidence ${result.receipt.status}: ${result.receipt.artifact.path}`);console.log(`visual-check containment ${result.receipt.containment.status}; captures ${result.receipt.captures.status}; perceptual visual review pending`);- console.log(`receipt ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.sidecars.receipt)}`);+ console.log(`receipt ${path.join(sidecarDirectory, result.receipt.sidecars.receipt)}`);if (result.receipt.captures.contactSheet) {- console.log(`contact sheet ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.captures.contactSheet)}`);+ console.log(`contact sheet ${path.join(sidecarDirectory, result.receipt.captures.contactSheet)}`);}if (result.receipt.error) console.error(result.receipt.error);}diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjsindex 8adb154b..8a6e51c7 100644--- a/archify/bin/visual-check.mjs+++ b/archify/bin/visual-check.mjs@@ -56,10 +56,12 @@ function screenshotKey(width, height, theme) {return `${width}x${height}:${theme}`;}-export function sidecarPaths(artifactPath) {+export function sidecarPaths(artifactPath, { outDir } = {}) {const artifact = path.resolve(artifactPath);- const stem = artifact.replace(/\.html?$/i, '');- const base = `${stem}.visual-check`;+ const stem = path.basename(artifact).replace(/\.html?$/i, '');+ const directory = outDir ? path.resolve(outDir) : path.dirname(artifact);+ if (outDir) fs.mkdirSync(directory, { recursive: true });+ const base = path.join(directory, `${stem}.visual-check`);const screenshots = CAPTURE_VIEWPORTS.flatMap(({ width, height }) => THEMES.map((theme) => ({width,height,@@ -693,6 +695,7 @@ function persistReceipt(outputs, receipt) {export async function runVisualCheck({artifactPath,+ outDir,chromePath,resolveChrome = findChrome,browserFactory = async (resolvedChrome) => new ChromeVisualBrowser(resolvedChrome),@@ -701,7 +704,7 @@ export async function runVisualCheck({const artifact = path.resolve(artifactPath);if (!/\.html?$/i.test(artifact)) throw new Error('visual-check requires an .html artifact.');const artifactBytes = fs.readFileSync(artifact);- const outputs = sidecarPaths(artifact);+ const outputs = sidecarPaths(artifact, { outDir });cleanupCaptureSidecars(outputs);safeUnlink(outputs.receipt);diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 31f2c1dc..89925d8d 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -37,7 +37,10 @@ The zero-dependency command uses Chrome/Chromium through the DevTools pipe. Itmeasures light-theme containment at 1440×900, 1600×1000, 1920×1080, and2048×1320, then captures light/dark screenshots at 1440×900 and 2048×1320. Itwrites four PNG sidecars, one relative-path HTML contact sheet, and one JSON-receipt beside the artifact. The receipt binds the source artifact SHA-256 and+receipt beside the artifact by default — pass `--out-dir <dir>` to write all of+them into a separate directory instead (created if missing) when a project+keeps its testing/evidence artifacts apart from the delivered `.json`/`.html`+result pair. The receipt binds the source artifact SHA-256 andbyte count, identifies `evidenceKind: "automated-browser"`, records READ plusStill runtime state, and always reports `visualReview: "pending"`; automatedbrowser evidence cannot claim perceptual review.diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjsindex 8cf6198e..ca26a8d5 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -249,6 +249,31 @@ test('cli: visual-check returns a skipped receipt with exit 2 when Chrome is unaassert.equal(fs.existsSync(out.replace(/\.html$/, '.visual-check.json')), true);});+test('cli: visual-check --out-dir writes the receipt into that directory, not beside the artifact', () => {+ const out = path.join(tmp, 'visual-check-outdir.html');+ fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');+ const missingChrome = path.join(tmp, 'missing-chrome-outdir');+ const outDir = path.join(tmp, 'visual-check-outdir-evidence');+ const result = run(['visual-check', out, '--json', '--out-dir', outDir], {+ env: { ...process.env, ARCHIFY_CHROME: missingChrome },+ });++ assert.equal(result.status, 2, result.stderr);+ const receipt = JSON.parse(result.stdout);+ assert.equal(receipt.status, 'skipped');+ assert.equal(fs.existsSync(path.join(outDir, 'visual-check-outdir.visual-check.json')), true);+ assert.equal(fs.existsSync(out.replace(/\.html$/, '.visual-check.json')), false, 'no receipt should land beside the artifact when --out-dir is set');+});++test('cli: visual-check rejects --out-dir with no value', () => {+ const out = path.join(tmp, 'visual-check-outdir-missing-value.html');+ fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');+ const result = run(['visual-check', out, '--out-dir']);++ assert.notEqual(result.status, 0);+ assert.match(result.stderr, /--out-dir requires a directory path/);+});+test('cli: visual-check describes human output as automated browser evidence, not visual approval', () => {const out = path.join(tmp, 'visual-check-browser-evidence.html');fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');diff --git a/archify/test/visual-check.test.mjs b/archify/test/visual-check.test.mjsindex 2f488144..c16a43ac 100644--- a/archify/test/visual-check.test.mjs+++ b/archify/test/visual-check.test.mjs@@ -210,6 +210,48 @@ test('visual-check records four containment viewports and four endpoint theme ca}});+test('sidecarPaths places outputs in outDir instead of beside the artifact', () => {+ const input = artifact('outdir-source.html');+ const separateDir = path.join(tmp, 'evidence-nested', 'deeper');+ assert.equal(fs.existsSync(separateDir), false, 'precondition: outDir must not exist yet');++ const outputs = sidecarPaths(input, { outDir: separateDir });++ assert.equal(fs.existsSync(separateDir), true, 'sidecarPaths must create a missing outDir');+ assert.equal(path.dirname(outputs.receipt), separateDir);+ assert.equal(path.dirname(outputs.contactSheet), separateDir);+ assert.equal(outputs.screenshots.every((entry) => path.dirname(entry.path) === separateDir), true);+ assert.equal(path.basename(outputs.receipt), 'outdir-source.visual-check.json');++ // Omitting outDir keeps the existing beside-the-artifact behavior unchanged.+ const defaultOutputs = sidecarPaths(input);+ assert.equal(path.dirname(defaultOutputs.receipt), path.dirname(input));+});++test('visual-check writes all sidecars into --out-dir end-to-end, none beside the artifact', async () => {+ const input = artifact('outdir-e2e.html');+ const outDir = path.join(tmp, 'outdir-e2e-evidence');+ const browser = fakeBrowser();+ const result = await runVisualCheck({+ artifactPath: input,+ outDir,+ chromePath: '/fake/chrome',+ browserFactory: async () => browser,+ });++ assert.equal(result.exitCode, 0);+ assert.equal(result.receipt.status, 'pass');++ const outputs = sidecarPaths(input, { outDir });+ assert.equal(fs.existsSync(outputs.receipt), true);+ assert.equal(fs.existsSync(outputs.contactSheet), true);+ assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);++ const besideArtifact = sidecarPaths(input);+ assert.equal(fs.existsSync(besideArtifact.receipt), false, 'no sidecar should land beside the artifact when outDir is set');+ assert.equal(fs.existsSync(besideArtifact.contactSheet), false);+});+test('visual-check returns 1 and preserves evidence when any viewport overflows', async () => {const input = artifact('overflow.html');const result = await runVisualCheck({