Skip to content

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

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.mjs
index 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.mjs
index 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.md
index 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. It
measures light-theme containment at 1440×900, 1600×1000, 1920×1080, and
2048×1320, then captures light/dark screenshots at 1440×900 and 2048×1320. It
writes 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 and
byte count, identifies `evidenceKind: "automated-browser"`, records READ plus
Still runtime state, and always reports `visualReview: "pending"`; automated
browser evidence cannot claim perceptual review.
diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjs
index 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 una
assert.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.mjs
index 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({