@just-every/design 0.1.32 → 0.1.33

package/dist/cli.js

@@ -5,21 +5,22 @@
 import { createInterface } from 'node:readline/promises';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync, statSync } from 'node:fs';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { runApprovalLinkLoginFlow } from './auth.js';
 import { refreshLoginSession } from './auth.js';
 import { pickAccountSlug } from './account-picker.js';
-import { parseArtifactsDownloadPositional, parseArtifactsListPositional } from './artifacts-cli.js';
 import { clearConfig, readConfig, resolveConfigPath, writeConfig } from './config.js';
 import { DesignAppClient } from './design-client.js';
 import { parseJsonOrThrow } from './json.js';
 import { checkIntegrations, detectClients, detectDefaultClients, ensureLocalLauncher, resolveLocalInstallLayout, runInstall, runRemove, } from './install.js';
 import { startMcpServer } from './server.js';
 import { buildCreateRunRequest, NOT_AUTHENTICATED_HELP, watchRun } from './tool-logic.js';
-import { wrapToolResponse } from './response-guidance.js';
+import { formatSyncCompletionMarkdown, formatSyncStartMarkdown, formatToolResponseMarkdown, wrapToolResponse, } from './response-guidance.js';
+import { createSyncProgressTracker, getProgressPct } from './progress.js';
+import { runScreenshotCommand, which } from './screenshot.js';
 function parseArgs(argv) {
     const flags = {};
     const command = [];
@@ -60,25 +61,9 @@ function printHelp() {
     console.error('  (default)                 Start the MCP server (stdio)');
     console.error('  install                   Interactive setup (auth + client config)');
     console.error('  remove                    Remove Every Design from detected clients');
-    console.error('  create                    Create a design run (CLI helper)');
-    console.error('  upload-target             Upload an image and set it as the run target (CLI helper)');
-    console.error('  refine-draft              Refine a specific draft image in the same run (CLI helper)');
-    console.error('  set-target                Select a target draft for a run (CLI helper)');
-    console.error('  clear-target              Clear the explicit target for a run (CLI helper)');
-    console.error('  extract-assets            Trigger asset extraction for a run (CLI helper)');
-    console.error('  generate-html             Trigger HTML generation for a run (CLI helper)');
-    console.error('  screenshot <url>          Screenshot a URL (CLI helper)');
-    console.error('  iterate                   Iterate on a run using screenshot feedback (CLI helper)');
-    console.error('  critique                  Alias for `iterate`');
-    console.error('  watch                     Watch a design run (CLI helper)');
-    console.error('  share status              Get run share link status (CLI helper)');
-    console.error('  share enable              Enable (or rotate) a share link (CLI helper)');
-    console.error('  share revoke              Revoke the active share link (CLI helper)');
-    console.error('  get                       Fetch a run by id (CLI helper)');
-    console.error('  list                      List recent runs (CLI helper)');
-    console.error('  events                    Fetch run events (CLI helper)');
-    console.error('  artifacts list <runId>    List run artifacts (CLI helper)');
-    console.error('  artifacts download <runId>/<artifactId>  Download an artifact (CLI helper)');
+    console.error('  create                    Create a new design (CLI helper)');
+    console.error('  sync                      Wait for completion, extract assets, and sync artifacts (CLI helper)');
+    console.error('  check                     Screenshot and compare implementation against a run (CLI helper)');
     console.error('  auth login                Login via approval-link flow and save config');
     console.error('  auth status               Check current auth against /api/me');
     console.error('  auth logout               Delete the saved config file');
@@ -90,10 +75,6 @@ function printHelp() {
     console.error(`  --config <path>           Config path (default: ${configPath})`);
     console.error('  --no-open                 Do not open the approval URL in a browser (auth login)');
     console.error('  --json <string>           JSON args payload for CLI helpers (or pipe JSON via stdin)');
-    console.error('  --out <path>              Output path (screenshot)');
-    console.error('  --width <px>              Viewport width (screenshot, default 1696)');
-    console.error('  --height <px>             Viewport height (screenshot, default 2528)');
-    console.error('  --wait-ms <ms>            Extra wait budget before screenshot (screenshot, default 4000)');
     console.error('  --client <name[,name...]> Install target(s): code,codex,claude-desktop,claude-code,cursor,gemini,qwen,all,auto');
     console.error('  --name <serverName>       MCP server name key (default: every-design)');
     console.error('  --launcher <npx|local>    How clients launch the MCP server (default for install: local)');
@@ -119,221 +100,6 @@ async function resolvePackageVersion() {
         return '0.0.0';
     }
 }
-function which(bin) {
-    try {
-        const tool = process.platform === 'win32' ? 'where' : 'which';
-        const res = spawnSync(tool, [bin], { encoding: 'utf8' });
-        if (res.status !== 0)
-            return null;
-        const first = String(res.stdout || '').trim().split(/\r?\n/)[0];
-        return first ? first.trim() : null;
-    }
-    catch {
-        return null;
-    }
-}
-function resolveHeadlessBrowserBinary() {
-    const explicit = process.env.CHROME_PATH?.trim();
-    if (explicit && existsSync(explicit))
-        return explicit;
-    const candidates = [
-        'google-chrome',
-        'google-chrome-stable',
-        'chromium',
-        'chromium-browser',
-        'chrome',
-        'msedge',
-        'microsoft-edge',
-    ];
-    for (const c of candidates) {
-        const found = which(c);
-        if (found)
-            return found;
-    }
-    if (process.platform === 'darwin') {
-        const macCandidates = [
-            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-            '/Applications/Chromium.app/Contents/MacOS/Chromium',
-            '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-        ];
-        for (const c of macCandidates) {
-            if (existsSync(c))
-                return c;
-        }
-    }
-    return null;
-}
-async function runScreenshotCommand(args) {
-    const url = args.url.trim();
-    if (!url)
-        throw new Error('Missing URL. Usage: every-design screenshot http://127.0.0.1:3000/path');
-    const outPath = path.resolve(args.outPath);
-    await mkdir(path.dirname(outPath), { recursive: true });
-    const browser = resolveHeadlessBrowserBinary();
-    if (!browser) {
-        throw new Error('No headless Chrome/Chromium/Edge binary found. Install a Chromium-based browser or set CHROME_PATH to an executable path.');
-    }
-    const tmpProfile = await (async () => {
-        const base = path.join(os.tmpdir(), 'every-design-screenshot-');
-        const { mkdtemp } = await import('node:fs/promises');
-        return mkdtemp(base);
-    })();
-    try {
-        const waitMs = Number.isFinite(args.waitMs) ? Math.max(0, Math.min(120_000, Math.round(args.waitMs))) : 4000;
-        const timeoutMs = Math.max(15_000, Math.min(180_000, waitMs + 30_000));
-        const argsList = [
-            '--headless=new',
-            '--disable-gpu',
-            '--hide-scrollbars',
-            '--mute-audio',
-            '--no-first-run',
-            '--no-default-browser-check',
-            '--disable-background-networking',
-            '--disable-sync',
-            '--disable-extensions',
-            '--metrics-recording-only',
-            '--force-device-scale-factor=1',
-            `--window-size=${args.width},${args.height}`,
-            `--user-data-dir=${tmpProfile}`,
-            `--virtual-time-budget=${waitMs || 0}`,
-            `--screenshot=${outPath}`,
-            url,
-        ];
-        if (typeof process.getuid === 'function' && process.getuid() === 0) {
-            // Chromium requires no-sandbox flags when running as root.
-            argsList.unshift('--disable-setuid-sandbox', '--no-sandbox');
-        }
-        const screenshotOk = () => {
-            try {
-                return statSync(outPath).size > 0;
-            }
-            catch {
-                return false;
-            }
-        };
-        const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-        const waitForScreenshotStable = async (signal) => {
-            const start = Date.now();
-            // Chrome writes the screenshot file as a single operation most of the time, but we've seen
-            // occasional flakiness where the file exists briefly at size=0. Wait for a stable >0 size.
-            let lastSize = -1;
-            let stableTicks = 0;
-            while (Date.now() - start < timeoutMs) {
-                if (signal.aborted)
-                    return false;
-                let size = -1;
-                try {
-                    size = statSync(outPath).size;
-                }
-                catch {
-                    size = -1;
-                }
-                if (size > 0) {
-                    if (size === lastSize)
-                        stableTicks += 1;
-                    else
-                        stableTicks = 0;
-                    lastSize = size;
-                    if (stableTicks >= 2)
-                        return true;
-                }
-                await sleep(100);
-            }
-            if (signal.aborted)
-                return false;
-            throw new Error('Timed out waiting for screenshot file to be produced.');
-        };
-        // Use an isolated process group on Unix so we can reliably kill Chrome + its helpers.
-        const child = spawn(browser, argsList, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            detached: process.platform !== 'win32',
-        });
-        let stdout = '';
-        let stderr = '';
-        child.stdout?.setEncoding('utf8');
-        child.stderr?.setEncoding('utf8');
-        child.stdout?.on('data', (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr?.on('data', (chunk) => {
-            stderr += String(chunk);
-        });
-        const killChild = (signal) => {
-            if (!child.pid)
-                return;
-            try {
-                if (process.platform !== 'win32') {
-                    // Kill the whole process group (negative PID) when detached.
-                    process.kill(-child.pid, signal);
-                }
-                else {
-                    process.kill(child.pid, signal);
-                }
-            }
-            catch {
-                // ignore
-            }
-        };
-        const exitPromise = new Promise((resolve, reject) => {
-            child.once('error', reject);
-            child.once('exit', (code, signal) => resolve({ code, signal }));
-        });
-        const abort = new AbortController();
-        const screenshotPromise = waitForScreenshotStable(abort.signal)
-            .then((ok) => ({ type: 'screenshot', ok }))
-            .catch((error) => ({ type: 'screenshot_error', error }));
-        const exitPromiseHandled = exitPromise
-            .then((r) => ({ type: 'exit', ...r }))
-            .catch((error) => ({ type: 'exit_error', error }));
-        // Hard-kill after the timeout budget; Chrome can hang even after producing a screenshot.
-        const timeout = setTimeout(() => {
-            killChild('SIGKILL');
-        }, timeoutMs);
-        try {
-            const first = await Promise.race([screenshotPromise, exitPromiseHandled]);
-            abort.abort();
-            if (first.type === 'exit_error') {
-                const message = first.error instanceof Error ? first.error.message : String(first.error);
-                throw new Error(`Screenshot failed (spawn error): ${message}`);
-            }
-            if (first.type === 'screenshot_error') {
-                // Still allow a best-effort success if Chrome produced a screenshot before hanging.
-                killChild('SIGKILL');
-                await Promise.race([exitPromise.catch(() => undefined), sleep(1_500)]);
-            }
-            // If the screenshot is ready but Chrome is still running, kill it immediately instead of
-            // waiting for the timeout (which is often ~waitMs+30s).
-            if (first.type === 'screenshot' && first.ok) {
-                killChild('SIGKILL');
-                // Don't await indefinitely; cleanup is best-effort.
-                await Promise.race([exitPromise.catch(() => undefined), sleep(1_500)]);
-            }
-            const ok = screenshotOk();
-            if (!ok) {
-                // Chrome may exit without producing a screenshot; include output to help debug.
-                const detail = (stderr || stdout).trim();
-                const exit = first.type === 'exit' ? first : await exitPromise.catch(() => ({ code: null, signal: null }));
-                throw new Error(`Screenshot failed (exit ${exit.code ?? 'unknown'}, signal ${exit.signal ?? 'none'}): ${detail || 'no output'}`);
-            }
-        }
-        finally {
-            clearTimeout(timeout);
-            // Ensure Chrome isn't left running in the background.
-            killChild('SIGKILL');
-        }
-        return {
-            screenshotPath: outPath,
-            width: args.width,
-            height: args.height,
-            engine: 'chrome-headless',
-            binary: browser,
-        };
-    }
-    finally {
-        const { rm } = await import('node:fs/promises');
-        await rm(tmpProfile, { recursive: true, force: true }).catch(() => undefined);
-    }
-}
 function isTtyInteractive() {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
@@ -385,76 +151,6 @@ async function readJsonArgs(remainingArgs, flags) {
     }
     return parsed;
 }
-async function readJsonArgsOptional(remainingArgs, flags) {
-    const jsonFlag = resolveFlagString(flags, 'json');
-    const hasInline = remainingArgs.some((t) => t.trim().length > 0);
-    const hasStdin = !process.stdin.isTTY;
-    if (!jsonFlag && !hasInline && !hasStdin)
-        return {};
-    return readJsonArgs(remainingArgs, flags);
-}
-function pretty(value) {
-    return JSON.stringify(value, null, 2);
-}
-function createWatchProgressDisplay(stream, enabled) {
-    let lastRendered = '';
-    let lastSnapshot = null;
-    let spinner = 0;
-    function clearLine() {
-        stream.write('\r\x1b[2K');
-    }
-    function render(snapshot) {
-        if (!enabled)
-            return;
-        lastSnapshot = snapshot;
-        spinner = (spinner + 1) % 4;
-        const stage = snapshot.stage ? String(snapshot.stage) : '';
-        const status = snapshot.status ? String(snapshot.status) : '';
-        const progress = typeof snapshot.progress === 'number' ? snapshot.progress : null;
-        const pct = typeof progress === 'number' ? Math.max(0, Math.min(100, Math.round(progress * 100))) : null;
-        const barWidth = 24;
-        const filled = pct === null ? 0 : Math.round((pct / 100) * barWidth);
-        const bar = `[${'#'.repeat(Math.max(0, Math.min(barWidth, filled)))}${'-'.repeat(Math.max(0, barWidth - filled))}]`;
-        const spinChar = ['|', '/', '-', '\\'][spinner] ?? '|';
-        const parts = [];
-        if (pct === null) {
-            parts.push(`${spinChar} ${bar}`);
-        }
-        else {
-            parts.push(`${bar} ${String(pct).padStart(3, ' ')}%`);
-        }
-        if (stage)
-            parts.push(`stage=${stage}`);
-        if (status)
-            parts.push(`status=${status}`);
-        const line = parts.join(' ');
-        if (line === lastRendered)
-            return;
-        lastRendered = line;
-        clearLine();
-        stream.write(line);
-    }
-    function log(line) {
-        if (!enabled) {
-            stream.write(`${line}\n`);
-            return;
-        }
-        clearLine();
-        stream.write(`${line}\n`);
-        if (lastSnapshot) {
-            lastRendered = '';
-            render(lastSnapshot);
-        }
-    }
-    function finish() {
-        if (!enabled)
-            return;
-        clearLine();
-        lastRendered = '';
-        lastSnapshot = null;
-    }
-    return { render, log, finish, enabled };
-}
 async function promptYesNo(question, defaultYes = false) {
     if (!isTtyInteractive())
         return defaultYes;
@@ -927,32 +623,6 @@ async function main() {
     const loginOrigin = resolveLoginOrigin(flags);
     const verb = command[0] ?? '';
     const sub = command[1] ?? '';
-    if (verb === 'screenshot') {
-        const url = String(command[1] ?? '').trim();
-        const width = Number.parseInt(String(resolveFlagString(flags, 'width') ?? '1696'), 10);
-        const height = Number.parseInt(String(resolveFlagString(flags, 'height') ?? '2528'), 10);
-        const waitMs = Number.parseInt(String(resolveFlagString(flags, 'wait-ms') ?? '4000'), 10);
-        const out = resolveFlagString(flags, 'out')?.trim();
-        const outPath = out
-            ? out
-            : path.join(process.cwd(), `every-design-screenshot-${new Date().toISOString().replace(/[:.]/g, '-')}.png`);
-        try {
-            const result = await runScreenshotCommand({
-                url,
-                outPath,
-                width: Number.isFinite(width) && width > 0 ? width : 1696,
-                height: Number.isFinite(height) && height > 0 ? height : 2528,
-                waitMs: Number.isFinite(waitMs) ? waitMs : 4000,
-            });
-            console.log(pretty(result));
-            process.exit(0);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.error(message);
-            process.exit(1);
-        }
-    }
     if (verb === 'install') {
         const yes = Boolean(flags.yes);
         const dryRun = Boolean(flags['dry-run']);
@@ -1259,22 +929,8 @@ async function main() {
         }
         process.exit(0);
     }
-    // CLI helpers (non-MCP). These are mostly useful for Skills/playbooks and scripting.
-    if (verb === 'create'
-        || verb === 'upload-target'
-        || verb === 'refine-draft'
-        || verb === 'set-target'
-        || verb === 'clear-target'
-        || verb === 'extract-assets'
-        || verb === 'generate-html'
-        || verb === 'iterate'
-        || verb === 'critique'
-        || verb === 'watch'
-        || verb === 'share'
-        || verb === 'get'
-        || verb === 'list'
-        || verb === 'events'
-        || verb === 'artifacts') {
+    // CLI helpers (non-MCP). CLIs must follow: create -> sync -> check.
+    if (verb === 'create' || verb === 'sync' || verb === 'check') {
         const cfg = await loadMergedConfig(configPath, { designOrigin, loginOrigin });
         const sessionToken = (process.env.DESIGN_MCP_SESSION_TOKEN ?? cfg.sessionToken ?? '').trim();
         if (!sessionToken) {
@@ -1292,139 +948,116 @@ async function main() {
                 const input = await readJsonArgs(command.slice(1), flags);
                 const { prompt, config, parentRunId } = await buildCreateRunRequest(client, input);
                 const created = await client.createRun({ prompt, config, ...(parentRunId ? { parentRunId } : {}) });
-                console.log(pretty(wrap('design.create', created)));
-                process.exit(0);
-            }
-            if (verb === 'upload-target') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const sourceImage = input.sourceImage && typeof input.sourceImage === 'object' ? input.sourceImage : null;
-                if (!sourceImage) {
-                    throw new Error('Missing required argument: sourceImage');
-                }
-                const res = await client.uploadRunTarget(runId, sourceImage);
-                console.log(pretty(wrap('design.uploadTarget', res, { runId })));
-                process.exit(0);
-            }
-            if (verb === 'refine-draft') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                const artifactId = String(input.artifactId ?? '').trim();
-                const prompt = String(input.prompt ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                if (!artifactId)
-                    throw new Error('Missing required argument: artifactId');
-                if (!prompt)
-                    throw new Error('Missing required argument: prompt');
-                const res = await client.refineDraft(runId, artifactId, prompt);
-                console.log(pretty(wrap('design.refineDraft', res, { runId, artifactId })));
-                process.exit(0);
-            }
-            if (verb === 'set-target') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                const artifactId = String(input.artifactId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                if (!artifactId)
-                    throw new Error('Missing required argument: artifactId');
-                const res = await client.setRunTarget(runId, artifactId);
-                console.log(pretty(wrap('design.setTarget', res, { runId, artifactId })));
-                process.exit(0);
-            }
-            if (verb === 'clear-target') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const res = await client.clearRunTarget(runId);
-                console.log(pretty(wrap('design.clearTarget', res, { runId })));
+                console.log(formatToolResponseMarkdown(wrap('design.create', created)));
                 process.exit(0);
             }
-            if (verb === 'extract-assets') {
+            if (verb === 'sync') {
                 const input = await readJsonArgs(command.slice(1), flags);
                 const runId = String(input.runId ?? '').trim();
                 if (!runId)
                     throw new Error('Missing required argument: runId');
-                const targetArtifactId = typeof input.targetArtifactId === 'string' ? input.targetArtifactId.trim() : '';
-                const rawKind = typeof input.designKind === 'string' ? input.designKind.trim().toLowerCase() : '';
-                const designKind = rawKind === 'interface' || rawKind === 'html' ? 'interface' : undefined;
-                if (rawKind && !designKind) {
-                    throw new Error('Invalid designKind: expected "interface"');
+                const syncDirInput = typeof input.syncDir === 'string' ? input.syncDir.trim() : '';
+                const syncDir = syncDirInput || `./every-design/${runId}`;
+                const progressLines = [];
+                console.log(formatSyncStartMarkdown());
+                const tracker = createSyncProgressTracker();
+                const emitProgress = (pct) => {
+                    const line = `Progress: ${pct}%`;
+                    progressLines.push(line);
+                    console.log(line);
+                };
+                const initialPct = tracker.next(0);
+                if (initialPct !== null) {
+                    emitProgress(initialPct);
                 }
-                if (targetArtifactId) {
-                    await client.setRunTarget(runId, targetArtifactId);
+                const run = await watchRun(client, runId, {
+                    timeoutSeconds: 1800,
+                    intervalSeconds: 5,
+                    onUpdate: (snapshot) => {
+                        const pct = getProgressPct(snapshot.run);
+                        const mapped = tracker.next(pct);
+                        if (mapped !== null) {
+                            emitProgress(mapped);
+                        }
+                    },
+                    onExtractStart: () => {
+                        const mapped = tracker.markExtractStart();
+                        if (mapped !== null) {
+                            emitProgress(mapped);
+                        }
+                    },
+                    syncDir,
+                    ensureAssets: true,
+                });
+                const finalPct = getProgressPct(run);
+                const mappedFinal = tracker.finalize(finalPct);
+                if (mappedFinal !== null) {
+                    emitProgress(mappedFinal);
                 }
-                const progressed = await client.progressRun(runId, { action: 'extract_assets', ...(designKind ? { designKind } : {}) });
-                console.log(pretty(wrap('design.extractAssets', progressed, {
-                    runId,
-                    ...(targetArtifactId ? { artifactId: targetArtifactId } : {}),
-                })));
+                const payload = typeof run === 'object' && run ? { ...run, progress: progressLines } : { run, progress: progressLines };
+                console.log('');
+                console.log(formatSyncCompletionMarkdown(wrap('design.sync', payload, { runId, syncDir })));
                 process.exit(0);
             }
-            if (verb === 'generate-html') {
+            if (verb === 'check') {
                 const input = await readJsonArgs(command.slice(1), flags);
                 const runId = String(input.runId ?? '').trim();
                 if (!runId)
                     throw new Error('Missing required argument: runId');
-                const targetArtifactId = typeof input.targetArtifactId === 'string' ? input.targetArtifactId.trim() : '';
-                if (targetArtifactId) {
-                    await client.setRunTarget(runId, targetArtifactId);
-                }
-                const progressed = await client.progressRun(runId, { action: 'generate_html' });
-                console.log(pretty(wrap('design.generateHtml', progressed, {
-                    runId,
-                    ...(targetArtifactId ? { artifactId: targetArtifactId } : {}),
-                })));
-                process.exit(0);
-            }
-            if (verb === 'iterate' || verb === 'critique') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                if (verb === 'critique') {
-                    console.error('[every-design] `critique` is deprecated; use `iterate` instead.');
+                const urlInput = typeof input.url === 'string' ? input.url.trim() : '';
+                const pathInput = typeof input.path === 'string' ? input.path.trim() : '';
+                if (!urlInput && !pathInput)
+                    throw new Error('Missing required argument: url or path');
+                if (urlInput && pathInput)
+                    throw new Error('Provide only one of url or path');
+                let targetUrl = urlInput;
+                if (pathInput) {
+                    const resolved = path.resolve(pathInput);
+                    let stat;
+                    try {
+                        stat = statSync(resolved);
+                    }
+                    catch {
+                        throw new Error(`File not found: ${resolved}`);
+                    }
+                    if (!stat.isFile()) {
+                        throw new Error(`Path must be a file: ${resolved}`);
+                    }
+                    targetUrl = pathToFileURL(resolved).toString();
                 }
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const concerns = typeof input.concerns === 'string' ? input.concerns.trim() : '';
-                const render = Array.isArray(input.render) ? input.render : [];
-                if (render.length === 0)
-                    throw new Error('Missing required argument: render (array of images)');
-                const target = Array.isArray(input.target) ? input.target : [];
-                const viewportInput = input.viewport && typeof input.viewport === 'object' ? input.viewport : null;
-                const viewport = {
-                    width: Number(viewportInput?.width) || 1696,
-                    height: Number(viewportInput?.height) || 2528,
-                };
-                const renderRefs = await client.uploadSourceImages(render);
-                const targetRefs = target.length > 0 ? await client.uploadSourceImages(target) : [];
+                const screenshotOut = path.join(os.tmpdir(), `every-design-check-${runId}-${Date.now()}.png`);
+                const screenshot = await runScreenshotCommand({
+                    url: targetUrl,
+                    outPath: screenshotOut,
+                    width: 1696,
+                    height: 2528,
+                    waitMs: 4000,
+                });
+                const renderRefs = await client.uploadSourceImages([{ type: 'path', path: screenshot.screenshotPath }]);
                 const created = await client.createRunOperation(runId, {
                     type: 'iterate',
-                    ...(concerns ? { concerns } : {}),
-                    viewport,
+                    viewport: { width: screenshot.width, height: screenshot.height },
                     render: renderRefs,
-                    ...(targetRefs.length > 0 ? { target: targetRefs } : {}),
                 });
                 const operationId = String(created?.operation?.id ?? '').trim();
                 if (!operationId)
                     throw new Error('Iterate operation created but missing operation id');
-                const timeoutSeconds = typeof input.timeoutSeconds === 'number' ? input.timeoutSeconds : 3600;
-                const intervalSeconds = typeof input.intervalSeconds === 'number' ? input.intervalSeconds : 5;
-                const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-                const deadlineMs = Date.now() + Math.max(1, timeoutSeconds) * 1000;
+                const deadlineMs = Date.now() + 900 * 1000;
+                let terminalStatus = '';
                 while (true) {
                     const op = await client.getOperation(operationId);
                     const status = String(op?.operation?.status ?? '').trim().toLowerCase();
                     if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+                        terminalStatus = status;
                         break;
                     }
                     if (Date.now() > deadlineMs) {
                         throw new Error(`Timed out waiting for iterate operation (${operationId})`);
                     }
-                    await sleep(Math.max(1, intervalSeconds) * 1000);
+                    await new Promise((r) => setTimeout(r, 5_000));
+                }
+                if (terminalStatus !== 'completed') {
+                    throw new Error(`Iterate operation ${operationId} ended with status ${terminalStatus || 'unknown'}`);
                 }
                 const detail = await client.getRun(runId);
                 const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
@@ -1447,12 +1080,16 @@ async function main() {
                         runId,
                         operationId,
                         status: 'completed',
+                        screenshot: {
+                            filePath: screenshot.screenshotPath,
+                            width: screenshot.width,
+                            height: screenshot.height,
+                        },
                         iterate: null,
-                        critique: null,
                         generatedAssets,
                         error: 'Missing critique artifact for iterate operation',
                     };
-                    console.log(pretty(wrap('design.iterate', payload, { runId })));
+                    console.log(formatToolResponseMarkdown(wrap('design.check', payload, { runId })));
                     process.exit(0);
                 }
                 const url = typeof critiqueArtifact?.url === 'string' ? String(critiqueArtifact.url) : '';
@@ -1460,213 +1097,27 @@ async function main() {
                     throw new Error('Critique artifact is missing a download url');
                 const downloaded = await client.downloadUrlToCache(runId, critiqueArtifact.id, url, { fileNameHint: 'iterate.json' });
                 const raw = await readFile(downloaded.filePath, 'utf8');
-                const parsed = parseJsonOrThrow(raw);
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    parsed = raw;
+                }
                 const payload = {
                     runId,
-                    operationId,
+                    screenshot: {
+                        filePath: screenshot.screenshotPath,
+                        width: screenshot.width,
+                        height: screenshot.height,
+                    },
                     iterate: parsed,
-                    critique: parsed,
                     artifact: { id: critiqueArtifact.id, filePath: downloaded.filePath },
                     generatedAssets,
                 };
-                console.log(pretty(wrap('design.iterate', payload, { runId })));
-                process.exit(0);
-            }
-            if (verb === 'watch') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const timeoutSeconds = typeof input.timeoutSeconds === 'number' ? input.timeoutSeconds : 900;
-                const intervalSeconds = typeof input.intervalSeconds === 'number' ? input.intervalSeconds : 5;
-                const syncDir = typeof input.syncDir === 'string' && input.syncDir.trim() ? input.syncDir.trim() : undefined;
-                const ensureAssets = typeof input.ensureAssets === 'boolean' ? input.ensureAssets : undefined;
-                const targetArtifactId = typeof input.targetArtifactId === 'string' && input.targetArtifactId.trim()
-                    ? input.targetArtifactId.trim()
-                    : undefined;
-                const progressUi = createWatchProgressDisplay(process.stderr, Boolean(process.stderr.isTTY));
-                const log = (line) => {
-                    if (progressUi.enabled && line.startsWith('[design.watch] status='))
-                        return;
-                    progressUi.log(line);
-                };
-                const run = await watchRun(client, runId, {
-                    timeoutSeconds,
-                    intervalSeconds,
-                    log,
-                    onUpdate: (snapshot) => {
-                        progressUi.render(snapshot);
-                    },
-                    ...(syncDir ? { syncDir } : {}),
-                    ...(ensureAssets !== undefined ? { ensureAssets } : {}),
-                    ...(targetArtifactId ? { targetArtifactId } : {}),
-                });
-                progressUi.finish();
-                if (process.stderr.isTTY) {
-                    const synced = run?.synced;
-                    if (synced && typeof synced === 'object' && typeof synced.dir === 'string') {
-                        const dir = String(synced.dir);
-                        const downloaded = typeof synced.downloaded === 'number' ? synced.downloaded : 0;
-                        const skipped = typeof synced.skipped === 'number' ? synced.skipped : 0;
-                        const mapPath = typeof synced.mapPath === 'string' ? String(synced.mapPath) : '';
-                        console.error(`Synced: downloaded=${downloaded} skipped=${skipped} dir=${dir}`);
-                        if (mapPath)
-                            console.error(`Map: ${mapPath}`);
-                        try {
-                            const mapRaw = mapPath ? await readFile(mapPath, 'utf8') : '';
-                            const map = mapRaw ? parseJsonOrThrow(mapRaw) : null;
-                            const files = Array.isArray(map?.files) ? map.files : [];
-                            const rels = new Set(files
-                                .map((f) => (typeof f?.relPath === 'string' ? f.relPath : ''))
-                                .filter((p) => Boolean(p)));
-                            const hasPrefix = (prefix) => Array.from(rels).some((p) => p === prefix || p.startsWith(prefix + '/'));
-                            const keyFiles = [];
-                            const sorted = Array.from(rels).sort();
-                            const targets = sorted.filter((p) => p.startsWith('target/'));
-                            const assetPlan = sorted.filter((p) => p === 'assets/asset-plan.json');
-                            const assets = sorted.filter((p) => p.startsWith('assets/') && p !== 'assets/asset-plan.json');
-                            const refined = sorted.filter((p) => p.startsWith('refined/'));
-                            const drafts = sorted.filter((p) => p.startsWith('drafts/'));
-                            if (targets.length)
-                                keyFiles.push(targets[0]);
-                            if (assetPlan.length)
-                                keyFiles.push(assetPlan[0]);
-                            if (assets.length)
-                                keyFiles.push(...assets.slice(0, 3));
-                            if (refined.length)
-                                keyFiles.push(...refined.slice(0, 3));
-                            if (drafts.length)
-                                keyFiles.push(...drafts.slice(0, 3));
-                            if (keyFiles.length) {
-                                const unique = Array.from(new Set(keyFiles));
-                                console.error(`Key files: ${unique.join(', ')}${sorted.length > unique.length ? ` (+${sorted.length - unique.length} more)` : ''}`);
-                            }
-                        }
-                        catch {
-                            // Ignore summary failures.
-                        }
-                    }
-                }
-                console.log(pretty(wrap('design.watch', run, { runId, ...(syncDir ? { syncDir } : {}) })));
-                process.exit(0);
-            }
-            if (verb === 'share') {
-                const action = (sub || 'status').trim().toLowerCase();
-                const input = await readJsonArgs(command.slice(2), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                if (action === 'status') {
-                    const res = await client.getRunShareStatus(runId);
-                    console.log(pretty(res));
-                    process.exit(0);
-                }
-                if (action === 'enable' || action === 'create') {
-                    const rotate = input.rotate === true;
-                    const res = await client.createRunShare(runId, rotate ? { rotate: true } : {});
-                    console.log(pretty(res));
-                    process.exit(0);
-                }
-                if (action === 'revoke') {
-                    const res = await client.revokeRunShare(runId);
-                    console.log(pretty(res));
-                    process.exit(0);
-                }
-                throw new Error(`Unknown share action: ${action}. Expected status|enable|revoke.`);
-            }
-            if (verb === 'get') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const run = await client.getRun(runId);
-                console.log(pretty(wrap('design.get', run, { runId })));
-                process.exit(0);
-            }
-            if (verb === 'events') {
-                const input = await readJsonArgs(command.slice(1), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const events = await client.getRunEvents(runId);
-                console.log(pretty(wrap('design.events', events, { runId })));
+                console.log(formatToolResponseMarkdown(wrap('design.check', payload, { runId })));
                 process.exit(0);
             }
-            if (verb === 'list') {
-                const input = await readJsonArgsOptional(command.slice(1), flags);
-                const page = typeof input.page === 'number' ? input.page : undefined;
-                const limit = typeof input.limit === 'number' ? input.limit : undefined;
-                const runs = await client.listRuns({ page, limit });
-                console.log(pretty(wrap('design.list', runs)));
-                process.exit(0);
-            }
-            if (verb === 'artifacts' && sub === 'list') {
-                const positional = parseArtifactsListPositional(command.slice(2));
-                const input = positional ? { runId: positional.runId } : await readJsonArgs(command.slice(2), flags);
-                const runId = String(input.runId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                const detail = await client.getRun(runId);
-                const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
-                console.log(pretty(wrap('design.artifacts.list', { artifacts: outputs }, { runId })));
-                process.exit(0);
-            }
-            if (verb === 'artifacts' && sub === 'download') {
-                const positional = parseArtifactsDownloadPositional(command.slice(2));
-                const input = positional ? { runId: positional.runId, artifactId: positional.artifactId } : await readJsonArgs(command.slice(2), flags);
-                const runId = String(input.runId ?? '').trim();
-                const artifactId = String(input.artifactId ?? '').trim();
-                if (!runId)
-                    throw new Error('Missing required argument: runId');
-                if (!artifactId)
-                    throw new Error('Missing required argument: artifactId');
-                const detail = await client.getRun(runId);
-                const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
-                const found = outputs.find((entry) => String(entry?.id ?? '') === artifactId) || null;
-                const hint = await (async () => {
-                    const url = typeof found?.url === 'string' ? found.url.trim() : '';
-                    if (url) {
-                        try {
-                            const u = url.startsWith('http://') || url.startsWith('https://')
-                                ? new URL(url)
-                                : new URL(url, 'https://example.invalid');
-                            return u.pathname.split('/').filter(Boolean).pop() || undefined;
-                        }
-                        catch {
-                            return url.split('/').filter(Boolean).pop() || undefined;
-                        }
-                    }
-                    try {
-                        const artifacts = await client.listArtifacts(runId);
-                        const record = Array.isArray(artifacts?.artifacts)
-                            ? artifacts.artifacts.find((a) => String(a?.id ?? '') === artifactId)
-                            : null;
-                        const storageKey = typeof record?.storageKey === 'string' ? record.storageKey.trim() : '';
-                        return storageKey ? storageKey.split('/').filter(Boolean).pop() || undefined : undefined;
-                    }
-                    catch {
-                        return undefined;
-                    }
-                })();
-                const downloaded = await (async () => {
-                    try {
-                        return await client.downloadArtifactToCache(runId, artifactId, { fileNameHint: hint });
-                    }
-                    catch (error) {
-                        const url = typeof found?.url === 'string' ? found.url.trim() : '';
-                        if (url) {
-                            return await client.downloadUrlToCache(runId, artifactId, url, { fileNameHint: hint });
-                        }
-                        throw error;
-                    }
-                })();
-                console.log(pretty(wrap('design.artifacts.download', downloaded, { runId, artifactId })));
-                process.exit(0);
-            }
-            if (verb === 'artifacts') {
-                throw new Error('Usage: artifacts list <runId> | artifacts download <runId>/<artifactId>\n' +
-                    'Tip: you can still use --json or pipe a JSON object via stdin.');
-            }
             // Should be unreachable due to the verb guard.
             throw new Error(`Unknown command: ${verb}`);
         }
@@ -1759,6 +1210,11 @@ async function main() {
         console.log(JSON.stringify(safe, null, 2));
         process.exit(0);
     }
+    if (verb) {
+        console.error(`Unknown command: ${verb}`);
+        printHelp();
+        process.exit(1);
+    }
     // Default: run MCP server.
     const cfg = await loadMergedConfig(configPath, { designOrigin, loginOrigin });
     const sessionToken = process.env.DESIGN_MCP_SESSION_TOKEN?.trim();