@just-every/design 0.1.1 → 0.1.2

package/dist/cli.js

@@ -3,12 +3,18 @@
  * CLI entrypoint for @just-every/design
  */
 import { createInterface } from 'node:readline/promises';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
 import { runApprovalLinkLoginFlow } from './auth.js';
 import { pickAccountSlug } from './account-picker.js';
 import { clearConfig, readConfig, resolveConfigPath, writeConfig } from './config.js';
 import { DesignAppClient } from './design-client.js';
-import { detectDefaultClients, runInstall } from './install.js';
+import { detectClients, detectDefaultClients, runInstall, runRemove, } from './install.js';
 import { startMcpServer } from './server.js';
+import { buildCreateRunRequest, NOT_AUTHENTICATED_HELP, waitForRun } from './tool-logic.js';
 function parseArgs(argv) {
     const flags = {};
     const command = [];
@@ -47,7 +53,17 @@ function printHelp() {
     console.error('');
     console.error('Commands:');
     console.error('  (default)                 Start the MCP server (stdio)');
-    console.error('  install                   Install MCP config entries for common clients');
+    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('  screenshot <url>          Screenshot a URL (CLI helper)');
+    console.error('  critique                  Critique a target vs current screenshot (CLI helper)');
+    console.error('  wait                      Wait for a design run (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            List run artifacts (CLI helper)');
+    console.error('  artifacts download        Download an artifact (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');
@@ -58,14 +74,452 @@ function printHelp() {
     console.error('  --account <slug>          Preselect company/account slug (skips interactive prompt)');
     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)');
+    console.error('  --no-path                 Do not modify shell config to add ~/.local/bin to PATH');
     console.error('  --yes                     Non-interactive install (no prompts)');
     console.error('  --dry-run                 Print what would change, but do not write');
     console.error('  --force                   Overwrite existing entries');
-    console.error('  --no-skills               Do not install Codex/Code skill playbook');
+    console.error('  --no-skills               Do not install local Skills/playbooks');
     console.error('  --help, -h                Show help');
 }
+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 res = spawnSync(browser, [
+            '--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,
+        ], { encoding: 'utf8' });
+        if (res.status !== 0 || !existsSync(outPath)) {
+            const detail = (res.stderr || res.stdout || '').trim();
+            throw new Error(`Screenshot failed (exit ${res.status ?? 'unknown'}): ${detail || 'no output'}`);
+        }
+        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);
+}
+function looksExpired(iso) {
+    if (!iso)
+        return false;
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return false;
+    // Consider it expired if it will expire in the next minute.
+    return ms <= Date.now() + 60_000;
+}
+function hasAuth(cfg) {
+    const envToken = process.env.DESIGN_MCP_SESSION_TOKEN?.trim();
+    if (envToken)
+        return true;
+    if (!cfg?.sessionToken?.trim())
+        return false;
+    if (looksExpired(cfg.sessionExpiresAt))
+        return false;
+    return true;
+}
+async function readStdinText() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseJsonOrThrow(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON input: ${message}`);
+    }
+}
+async function readJsonArgs(remainingArgs, flags) {
+    const jsonFlag = resolveFlagString(flags, 'json');
+    const raw = (jsonFlag ?? remainingArgs.join(' ') ?? '').trim();
+    const fromArgs = parseJsonOrThrow(raw);
+    if (fromArgs && typeof fromArgs === 'object' && !Array.isArray(fromArgs)) {
+        return fromArgs;
+    }
+    if (raw) {
+        throw new Error('JSON input must be an object.');
+    }
+    const stdin = await readStdinText();
+    if (!stdin.trim()) {
+        throw new Error('Missing JSON input. Pass --json or pipe a JSON object via stdin.');
+    }
+    const parsed = parseJsonOrThrow(stdin);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('JSON input must be an object.');
+    }
+    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);
+}
+async function promptYesNo(question, defaultYes = false) {
+    if (!isTtyInteractive())
+        return defaultYes;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const suffix = defaultYes ? ' (Y/n) ' : ' (y/N) ';
+        const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+        if (!answer)
+            return defaultYes;
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+function pathHasEntry(entry) {
+    const list = (process.env.PATH ?? '')
+        .split(path.delimiter)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return list.includes(entry);
+}
+async function backupFileIfExists(filePath) {
+    try {
+        await readFile(filePath);
+    }
+    catch {
+        return;
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    await copyFile(filePath, `${filePath}.bak-${ts}`);
+}
+function renderPathExportSnippet(shellKind, entry) {
+    // Prefer $HOME to keep the file portable.
+    const home = os.homedir();
+    const value = entry.startsWith(home + path.sep)
+        ? `$HOME${entry.slice(home.length)}`
+        : entry;
+    return `\n# Added by Every Design\nexport PATH="${value}:$PATH"\n`;
+}
+function renderFishPathSnippet(entry) {
+    const home = os.homedir();
+    const value = entry.startsWith(home + path.sep)
+        ? `$HOME${entry.slice(home.length)}`
+        : entry;
+    return `\n# Added by Every Design\nset -gx PATH ${value} $PATH\n`;
+}
+async function ensurePathEntryOnSystem(args) {
+    if (process.platform === 'win32') {
+        return { changed: false, note: 'Skipped PATH update on Windows (add the launcher directory to PATH manually).' };
+    }
+    if (pathHasEntry(args.entry)) {
+        return { changed: false, note: `PATH already includes ${args.entry}` };
+    }
+    const shell = (process.env.SHELL ?? '').toLowerCase();
+    const home = os.homedir();
+    // Choose one or more files to edit (best-effort).
+    // We update both profile + rc files for bash/zsh so login and non-login shells
+    // both pick up the change.
+    const targets = [];
+    if (shell.includes('fish')) {
+        const xdgConfig = process.env.XDG_CONFIG_HOME?.trim() || path.join(home, '.config');
+        targets.push({ filePath: path.join(xdgConfig, 'fish', 'config.fish'), kind: 'fish' });
+    }
+    else if (shell.includes('zsh')) {
+        targets.push({ filePath: path.join(home, '.zshrc'), kind: 'zsh' });
+        targets.push({ filePath: path.join(home, '.zprofile'), kind: 'zsh' });
+    }
+    else {
+        // Default to bash/sh style.
+        targets.push({ filePath: path.join(home, '.bashrc'), kind: 'bash' });
+        targets.push({ filePath: path.join(home, '.bash_profile'), kind: 'bash' });
+        targets.push({ filePath: path.join(home, '.profile'), kind: 'bash' });
+    }
+    const labelTargets = targets.map((t) => t.filePath).join(', ');
+    if (!args.yes && isTtyInteractive()) {
+        const ok = await promptYesNo(`Your PATH does not include ${args.entry}. Add it via: ${labelTargets}?`, true);
+        if (!ok) {
+            return { changed: false, note: `Skipped PATH update (you can add ${args.entry} manually).` };
+        }
+    }
+    if (args.dryRun) {
+        return { changed: false, note: `[dry-run] Would add ${args.entry} to PATH via ${labelTargets}` };
+    }
+    const updated = [];
+    const skipped = [];
+    for (const target of targets) {
+        await mkdir(path.dirname(target.filePath), { recursive: true }).catch(() => undefined);
+        const before = await readFile(target.filePath, 'utf8').catch(() => '');
+        if (before.includes(args.entry) || before.includes('Added by Every Design')) {
+            skipped.push(target.filePath);
+            continue;
+        }
+        await backupFileIfExists(target.filePath);
+        const snippet = target.kind === 'fish' ? renderFishPathSnippet(args.entry) : renderPathExportSnippet(target.kind, args.entry);
+        await writeFile(target.filePath, `${before.replace(/\s*$/, '')}${snippet}`, 'utf8');
+        updated.push(target.filePath);
+    }
+    if (updated.length === 0) {
+        return {
+            changed: false,
+            note: skipped.length
+                ? `PATH entry already present in: ${skipped.join(', ')}`
+                : `Skipped PATH update (no writable shell config files found).`,
+        };
+    }
+    return {
+        changed: true,
+        note: `Added ${args.entry} to PATH in: ${updated.join(', ')} (restart your terminal).`,
+    };
+}
+async function promptLauncher(defaultLauncher) {
+    if (!isTtyInteractive())
+        return defaultLauncher;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        console.error('');
+        console.error('Launcher options:');
+        console.error('  1) local (recommended; installs into $XDG_DATA_HOME and creates ~/.local/bin/every-design)');
+        console.error('  2) npx   (no install; uses npm cache; easiest to keep updated)');
+        const def = defaultLauncher === 'local' ? '1' : '2';
+        const answer = (await rl.question(`Choose launcher [1/2] (default ${def}): `)).trim();
+        if (!answer)
+            return defaultLauncher;
+        if (answer === '1' || answer.toLowerCase() === 'local')
+            return 'local';
+        if (answer === '2' || answer.toLowerCase() === 'npx')
+            return 'npx';
+        console.error(`Unrecognized choice '${answer}', using default (${defaultLauncher}).`);
+        return defaultLauncher;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runAuthLoginFlow(params) {
+    const { configPath, designOrigin, loginOrigin, flags } = params;
+    const openBrowser = !flags['no-open'];
+    const result = await runApprovalLinkLoginFlow({
+        loginOrigin,
+        openBrowser,
+    });
+    const client = new DesignAppClient({
+        designOrigin,
+        sessionToken: result.sessionToken,
+    });
+    let activeAccountSlug;
+    try {
+        console.error('Fetching your companies…');
+        const accounts = await client.listAccounts();
+        const preferred = resolveFlagString(flags, 'account')?.trim() || process.env.DESIGN_MCP_ACCOUNT_SLUG?.trim() || undefined;
+        const isInteractive = isTtyInteractive();
+        const rl = isInteractive ? createInterface({ input: process.stdin, output: process.stderr }) : null;
+        const selected = await pickAccountSlug(accounts, {
+            preferredSlug: preferred,
+            isInteractive,
+            prompt: async (message) => {
+                if (!rl)
+                    return '';
+                return rl.question(message);
+            },
+            log: (message) => console.error(message),
+        });
+        if (rl)
+            rl.close();
+        if (selected) {
+            // If /api/accounts already set a default active cookie, switch only when needed.
+            if (client.activeAccountSlug && client.activeAccountSlug !== selected) {
+                await client.switchAccount(selected);
+            }
+            activeAccountSlug = selected;
+        }
+        else {
+            activeAccountSlug = client.activeAccountSlug;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[auth login] Warning: failed to resolve active account: ${message}`);
+    }
+    const nextConfig = {
+        version: 1,
+        loginOrigin,
+        designOrigin,
+        sessionToken: client.sessionToken || result.sessionToken,
+        sessionExpiresAt: result.sessionExpiresAt,
+        userId: result.userId,
+        activeAccountSlug,
+    };
+    await writeConfig(nextConfig, configPath);
+    console.error(`Saved auth to ${configPath}`);
+    if (activeAccountSlug)
+        console.error(`Active account: ${activeAccountSlug}`);
+    return nextConfig;
+}
+function recommendedMode(client, skillsEnabled) {
+    if (!client.installed)
+        return 'disabled';
+    if (client.supportsSkill && skillsEnabled)
+        return 'skill';
+    return 'mcp';
+}
+async function promptInstallPlan(clients, skillsEnabled) {
+    const installed = clients.filter((c) => c.installed);
+    const missing = clients.filter((c) => !c.installed);
+    console.error('Detected clients:');
+    installed.forEach((c, idx) => {
+        const mode = recommendedMode(c, skillsEnabled);
+        const rec = mode === 'skill' ? 'Skill (recommended)' : mode === 'mcp' ? 'MCP (recommended)' : 'Disabled';
+        const extra = c.details.length ? ` — ${c.details.join('; ')}` : '';
+        console.error(`  ${idx + 1}) ${c.label}: ${rec}${extra}`);
+    });
+    if (missing.length) {
+        console.error('Not detected:');
+        missing.forEach((c) => console.error(`  - ${c.label}`));
+    }
+    const useRecommended = await promptYesNo('Use recommended defaults for detected clients?', true);
+    const plan = Object.create(null);
+    for (const c of clients) {
+        plan[c.client] = useRecommended ? recommendedMode(c, skillsEnabled) : 'disabled';
+    }
+    if (useRecommended)
+        return plan;
+    if (!isTtyInteractive())
+        return plan;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        for (const c of installed) {
+            const def = recommendedMode(c, skillsEnabled);
+            const prompt = (() => {
+                if (c.supportsSkill && skillsEnabled) {
+                    return `${c.label} [s=skill (recommended) | m=mcp | d=disabled] (default ${def}): `;
+                }
+                return `${c.label} [m=mcp (recommended) | d=disabled] (default ${def}): `;
+            })();
+            const answer = (await rl.question(prompt)).trim().toLowerCase();
+            if (!answer) {
+                plan[c.client] = def;
+                continue;
+            }
+            if (answer === 'd' || answer === 'off' || answer === 'disabled') {
+                plan[c.client] = 'disabled';
+                continue;
+            }
+            if (answer === 'm' || answer === 'mcp') {
+                plan[c.client] = 'mcp';
+                continue;
+            }
+            if (answer === 's' || answer === 'skill') {
+                plan[c.client] = c.supportsSkill && skillsEnabled ? 'skill' : 'mcp';
+                continue;
+            }
+            console.error(`Unrecognized choice '${answer}', using default (${def}).`);
+            plan[c.client] = def;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return plan;
+}
 function resolveFlagString(flags, name) {
     const value = flags[name];
     if (typeof value === 'string')
@@ -94,14 +548,87 @@ 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 clientList = resolveFlagString(flags, 'client')?.trim() ||
-            resolveFlagString(flags, 'clients')?.trim() ||
-            'auto';
-        const requested = clientList
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean);
+        const yes = Boolean(flags.yes);
+        const dryRun = Boolean(flags['dry-run']);
+        const force = Boolean(flags.force);
+        const skillsEnabled = !flags['no-skills'];
+        const updatePath = !flags['no-path'];
+        const serverName = (resolveFlagString(flags, 'name') ?? 'every-design').trim();
+        const launcherFlag = resolveFlagString(flags, 'launcher')?.trim().toLowerCase();
+        const launcherFromFlag = launcherFlag === 'npx' ? 'npx' : launcherFlag === 'local' ? 'local' : null;
+        if (launcherFlag && !launcherFromFlag) {
+            console.error(`Invalid --launcher value: ${launcherFlag}. Expected npx|local.`);
+            process.exit(1);
+        }
+        console.error('Every Design setup');
+        console.error('');
+        console.error('Step 1/3: Authenticate');
+        const existingAuth = await readConfig(configPath);
+        let authedCfg = existingAuth;
+        if (!hasAuth(existingAuth)) {
+            if (dryRun) {
+                console.error(`Dry run: no auth found at ${configPath}. Install would run auth login first.`);
+            }
+            else if (!isTtyInteractive()) {
+                console.error(`No auth found at ${configPath}.`);
+                console.error('Run `every-design auth login` (or `npx @just-every/design auth login`) first, then re-run install.');
+                process.exit(1);
+            }
+            if (!dryRun) {
+                const proceed = yes ? true : await promptYesNo('No auth found. Login now?', true);
+                if (!proceed) {
+                    console.error('Aborted.');
+                    process.exit(1);
+                }
+                authedCfg = await runAuthLoginFlow({ configPath, designOrigin, loginOrigin, flags });
+            }
+        }
+        else {
+            console.error('Auth already configured.');
+            if (looksExpired(existingAuth?.sessionExpiresAt)) {
+                console.error('Warning: saved session looks expired; you may need to re-run auth login.');
+            }
+        }
+        console.error('');
+        console.error('Step 2/3: Choose launcher');
+        const launcher = launcherFromFlag ?? (yes ? 'local' : await promptLauncher('local'));
+        if (launcher === 'local' && updatePath) {
+            const localBin = path.join(os.homedir(), '.local', 'bin');
+            const ensured = await ensurePathEntryOnSystem({ entry: localBin, dryRun, yes });
+            if (ensured.note)
+                console.error(ensured.note);
+        }
+        console.error('');
+        console.error('Step 3/3: Configure clients');
+        const clientList = resolveFlagString(flags, 'client')?.trim() || resolveFlagString(flags, 'clients')?.trim();
+        const detections = detectClients();
         const allClients = [
             'code',
             'codex',
@@ -111,52 +638,311 @@ async function main() {
             'gemini',
             'qwen',
         ];
-        const selected = (() => {
-            if (requested.includes('all'))
-                return allClients;
-            if (requested.includes('auto'))
-                return detectDefaultClients();
-            return requested.filter((c) => allClients.includes(c));
-        })();
-        const serverName = (resolveFlagString(flags, 'name') ?? 'every-design').trim();
-        const installSkills = !flags['no-skills'];
-        const dryRun = Boolean(flags['dry-run']);
-        const force = Boolean(flags.force);
-        const yes = Boolean(flags.yes);
-        const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
-        const shouldProceed = yes
-            ? true
-            : await (async () => {
-                if (!isInteractive)
-                    return true;
-                const rl = createInterface({ input: process.stdin, output: process.stderr });
-                try {
-                    console.error('This will update MCP client config files in your home directory.');
-                    console.error(`Clients: ${selected.length ? selected.join(', ') : '(none detected)'}`);
-                    console.error(`Server name: ${serverName}`);
-                    const answer = (await rl.question('Proceed? (y/N) ')).trim().toLowerCase();
-                    return answer === 'y' || answer === 'yes';
-                }
-                finally {
-                    rl.close();
-                }
+        let plan;
+        if (clientList) {
+            const requested = clientList
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            const selected = (() => {
+                if (requested.includes('all'))
+                    return allClients;
+                if (requested.includes('auto'))
+                    return detectDefaultClients();
+                return requested.filter((c) => allClients.includes(c));
             })();
-        if (!shouldProceed) {
+            plan = Object.create(null);
+            for (const c of allClients) {
+                plan[c] = selected.includes(c)
+                    ? (c === 'code' || c === 'codex') && skillsEnabled
+                        ? 'skill'
+                        : 'mcp'
+                    : 'disabled';
+            }
+        }
+        else if (yes) {
+            plan = Object.create(null);
+            for (const c of detections) {
+                plan[c.client] = recommendedMode(c, skillsEnabled);
+            }
+        }
+        else {
+            plan = await promptInstallPlan(detections, skillsEnabled);
+        }
+        const mcpClients = [];
+        const skillClients = [];
+        for (const c of allClients) {
+            const mode = plan[c] ?? 'disabled';
+            if (mode === 'disabled')
+                continue;
+            if (mode === 'skill') {
+                if (c === 'code' || c === 'codex' || c === 'claude-code') {
+                    skillClients.push(c);
+                    continue;
+                }
+                mcpClients.push(c);
+                continue;
+            }
+            mcpClients.push(c);
+        }
+        if (mcpClients.length === 0 && skillClients.length === 0) {
+            console.error('No clients selected. Nothing to do.');
+            process.exit(1);
+        }
+        const confirm = yes ? true : await promptYesNo('Apply these changes?', true);
+        if (!confirm) {
             console.error('Aborted.');
             process.exit(1);
         }
-        if (selected.length === 0) {
-            console.error('No clients detected. Re-run with `--client all` to force installation.');
+        const results = [];
+        if (skillClients.length) {
+            results.push({
+                title: 'Skill + MCP (recommended)',
+                result: await runInstall({
+                    clients: skillClients,
+                    serverName,
+                    packageName: '@just-every/design',
+                    installSkills: true,
+                    dryRun,
+                    force,
+                    launcher,
+                }),
+            });
+        }
+        if (mcpClients.length) {
+            results.push({
+                title: 'MCP only',
+                result: await runInstall({
+                    clients: mcpClients,
+                    serverName,
+                    packageName: '@just-every/design',
+                    installSkills: false,
+                    dryRun,
+                    force,
+                    launcher,
+                }),
+            });
+        }
+        const changed = results.flatMap((r) => r.result.changed);
+        const skipped = results.flatMap((r) => r.result.skipped);
+        const notes = results.flatMap((r) => r.result.notes);
+        console.error('');
+        console.error('Summary');
+        console.error(`- Auth: ${hasAuth(authedCfg) ? 'configured' : 'missing'}`);
+        console.error(`- Server name: ${serverName}`);
+        console.error(`- Launcher: ${launcher}`);
+        console.error(`- Clients configured: ${[...new Set([...skillClients, ...mcpClients])].join(', ')}`);
+        if (dryRun) {
+            console.error('- Dry run: no files were modified');
+        }
+        if (changed.length) {
+            console.error('Updated:');
+            for (const p of changed)
+                console.error(`- ${p}`);
+        }
+        if (skipped.length) {
+            console.error('Skipped:');
+            for (const p of skipped)
+                console.error(`- ${p}`);
+        }
+        if (notes.length) {
+            console.error('Notes:');
+            for (const n of notes)
+                console.error(`- ${n}`);
+        }
+        console.error('');
+        console.error('Next steps: restart your client(s) so they pick up the new MCP config.');
+        process.exit(0);
+    }
+    // CLI helpers (non-MCP). These are mostly useful for Skills/playbooks and scripting.
+    if (verb === 'create' || verb === 'critique' || verb === 'wait' || verb === 'get' || verb === 'list' || verb === 'events' || verb === 'artifacts') {
+        const cfg = await loadMergedConfig(configPath, { designOrigin, loginOrigin });
+        const sessionToken = (process.env.DESIGN_MCP_SESSION_TOKEN ?? cfg.sessionToken ?? '').trim();
+        if (!sessionToken) {
+            console.error(NOT_AUTHENTICATED_HELP);
             process.exit(1);
         }
-        const result = await runInstall({
-            clients: selected,
-            serverName,
+        const client = new DesignAppClient({
+            designOrigin: cfg.designOrigin,
+            sessionToken,
+            activeAccountSlug: cfg.activeAccountSlug,
+        });
+        try {
+            if (verb === 'create') {
+                const input = await readJsonArgs(command.slice(1), flags);
+                const { prompt, config } = await buildCreateRunRequest(client, input);
+                const created = await client.createRun({ prompt, config });
+                console.log(pretty(created));
+                process.exit(0);
+            }
+            if (verb === 'critique') {
+                const input = await readJsonArgs(command.slice(1), flags);
+                const originalPrompt = String(input.originalPrompt ?? '').trim();
+                if (!originalPrompt)
+                    throw new Error('Missing required argument: originalPrompt');
+                const concerns = typeof input.concerns === 'string' ? input.concerns.trim() : '';
+                const target = Array.isArray(input.target) ? input.target : [];
+                const render = Array.isArray(input.render) ? input.render : [];
+                if (target.length === 0)
+                    throw new Error('Missing required argument: target (array of images)');
+                if (render.length === 0)
+                    throw new Error('Missing required argument: render (array of images)');
+                const viewportInput = input.viewport && typeof input.viewport === 'object' ? input.viewport : null;
+                const viewport = {
+                    width: Number(viewportInput?.width) || 1696,
+                    height: Number(viewportInput?.height) || 2528,
+                };
+                const targetRefs = await client.uploadSourceImages(target);
+                const renderRefs = await client.uploadSourceImages(render);
+                const created = await client.createRun({
+                    prompt: originalPrompt,
+                    config: {
+                        output: { designKind: 'interface', render: { viewport } },
+                        critique: {
+                            originalPrompt,
+                            concerns,
+                            target: targetRefs,
+                            render: renderRefs,
+                        },
+                    },
+                });
+                const runId = String(created?.run?.id ?? '').trim();
+                if (!runId)
+                    throw new Error('Critique run created but missing run id');
+                const timeoutSeconds = typeof input.timeoutSeconds === 'number' ? input.timeoutSeconds : 900;
+                const intervalSeconds = typeof input.intervalSeconds === 'number' ? input.intervalSeconds : 5;
+                await waitForRun(client, runId, {
+                    timeoutSeconds,
+                    intervalSeconds,
+                    log: (line) => console.error(line),
+                });
+                const artifacts = await client.listArtifacts(runId);
+                const list = Array.isArray(artifacts.artifacts) ? artifacts.artifacts : [];
+                const critiqueArtifact = list.find((a) => a.artifactType === 'critique') ?? null;
+                const generatedAssets = list.filter((a) => a.artifactType === 'critique-asset');
+                if (!critiqueArtifact) {
+                    console.log(pretty({
+                        runId,
+                        status: 'completed',
+                        critique: null,
+                        generatedAssets,
+                        error: 'Missing critique artifact',
+                    }));
+                    process.exit(0);
+                }
+                const downloaded = await client.downloadArtifactToCache(runId, critiqueArtifact.id, { fileNameHint: 'critique.json' });
+                const raw = await readFile(downloaded.filePath, 'utf8');
+                const parsed = parseJsonOrThrow(raw);
+                console.log(pretty({
+                    runId,
+                    critique: parsed,
+                    artifact: { id: critiqueArtifact.id, filePath: downloaded.filePath },
+                    generatedAssets,
+                }));
+                process.exit(0);
+            }
+            if (verb === 'wait') {
+                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 run = await waitForRun(client, runId, {
+                    timeoutSeconds,
+                    intervalSeconds,
+                    log: (line) => console.error(line),
+                });
+                console.log(pretty(run));
+                process.exit(0);
+            }
+            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(run));
+                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(events));
+                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(runs));
+                process.exit(0);
+            }
+            if (verb === 'artifacts' && sub === 'list') {
+                const input = await readJsonArgs(command.slice(2), flags);
+                const runId = String(input.runId ?? '').trim();
+                if (!runId)
+                    throw new Error('Missing required argument: runId');
+                const artifacts = await client.listArtifacts(runId);
+                console.log(pretty(artifacts));
+                process.exit(0);
+            }
+            if (verb === 'artifacts' && sub === 'download') {
+                const input = 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 downloaded = await client.downloadArtifactToCache(runId, artifactId);
+                console.log(pretty(downloaded));
+                process.exit(0);
+            }
+            if (verb === 'artifacts') {
+                throw new Error('Usage: artifacts list|download');
+            }
+            // Should be unreachable due to the verb guard.
+            throw new Error(`Unknown command: ${verb}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message);
+            process.exit(1);
+        }
+    }
+    if (verb === 'remove') {
+        const yes = Boolean(flags.yes);
+        const dryRun = Boolean(flags['dry-run']);
+        const force = Boolean(flags.force);
+        const detected = detectClients();
+        const installed = detected.filter((c) => c.installed);
+        console.error('This will remove Every Design (@just-every/design) from detected clients.');
+        if (installed.length) {
+            console.error('Detected:');
+            for (const c of installed) {
+                console.error(`- ${c.label}`);
+            }
+        }
+        else {
+            console.error('No clients detected.');
+        }
+        const proceed = yes ? true : await promptYesNo('Continue?', false);
+        if (!proceed) {
+            console.error('Aborted.');
+            process.exit(1);
+        }
+        const result = await runRemove({
             packageName: '@just-every/design',
-            installSkills,
             dryRun,
             force,
         });
+        console.error('');
+        console.error('Summary');
         if (result.changed.length) {
             console.error('Updated:');
             for (const p of result.changed)
@@ -172,71 +958,11 @@ async function main() {
             for (const n of result.notes)
                 console.error(`- ${n}`);
         }
-        console.error('Next: run `npx @just-every/design auth login` once to authenticate.');
+        console.error('Restart your client(s) to unload the MCP server config.');
         process.exit(0);
     }
     if (verb === 'auth' && sub === 'login') {
-        const openBrowser = !flags['no-open'];
-        const result = await runApprovalLinkLoginFlow({
-            loginOrigin,
-            openBrowser,
-        });
-        const client = new DesignAppClient({
-            designOrigin,
-            sessionToken: result.sessionToken,
-        });
-        let activeAccountSlug;
-        try {
-            const accounts = await client.listAccounts();
-            const preferred = resolveFlagString(flags, 'account')?.trim() ||
-                process.env.DESIGN_MCP_ACCOUNT_SLUG?.trim() ||
-                undefined;
-            const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
-            const rl = isInteractive
-                ? createInterface({ input: process.stdin, output: process.stderr })
-                : null;
-            const selected = await pickAccountSlug(accounts, {
-                preferredSlug: preferred,
-                isInteractive,
-                prompt: async (message) => {
-                    if (!rl)
-                        return '';
-                    return rl.question(message);
-                },
-                log: (message) => console.error(message),
-            });
-            if (rl) {
-                rl.close();
-            }
-            if (selected) {
-                // If /api/accounts already set a default active cookie, switch only when needed.
-                if (client.activeAccountSlug && client.activeAccountSlug !== selected) {
-                    await client.switchAccount(selected);
-                }
-                activeAccountSlug = selected;
-            }
-            else {
-                activeAccountSlug = client.activeAccountSlug;
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.error(`[auth login] Warning: failed to resolve active account: ${message}`);
-        }
-        const nextConfig = {
-            version: 1,
-            loginOrigin,
-            designOrigin,
-            sessionToken: client.sessionToken || result.sessionToken,
-            sessionExpiresAt: result.sessionExpiresAt,
-            userId: result.userId,
-            activeAccountSlug,
-        };
-        await writeConfig(nextConfig, configPath);
-        console.error(`Saved config to ${configPath}`);
-        if (activeAccountSlug) {
-            console.error(`Active account: ${activeAccountSlug}`);
-        }
+        await runAuthLoginFlow({ configPath, designOrigin, loginOrigin, flags });
         process.exit(0);
     }
     if (verb === 'auth' && sub === 'logout') {
@@ -248,7 +974,7 @@ async function main() {
         const cfg = await loadMergedConfig(configPath, { designOrigin, loginOrigin });
         const sessionToken = cfg.sessionToken ?? process.env.DESIGN_MCP_SESSION_TOKEN ?? '';
         if (!sessionToken) {
-            console.error('Not authenticated. Run `npx @just-every/design auth login`.');
+            console.error(NOT_AUTHENTICATED_HELP);
             process.exit(1);
         }
         const client = new DesignAppClient({