@thedesignagent/mcp 0.2.5 → 0.4.0

package/dist/cli.js

@@ -0,0 +1,771 @@
+#!/usr/bin/env node
+/**
+ * thedesignagent: TheDesignAgent from a terminal, a headless agent run or CI.
+ *
+ *   check <url|file>   Score a page (screenshot) or a source file. Exit 1 below --threshold.
+ *   brief "<task>"     Write a build brief to .thedesignagent-brief.md for any agent to read.
+ *   login [key]        Save your tda_ API key to ~/.thedesignagent/credentials.
+ *
+ * Exit codes: 0 ok · 1 below threshold · 2 error · 3 page is behind login (nothing charged).
+ */
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline';
+import { captureScreenshot } from './screenshot.js';
+import { loadStoredAuth } from './auth-store.js';
+import { loadApiKey, looksLikeApiKey, saveApiKey, MISSING_KEY_HELP } from './credentials.js';
+const API_BASE = process.env.THEDESIGNAGENT_API_BASE ?? 'https://bxqifcmkydlsgwgcpqda.supabase.co/functions/v1';
+const EDGE_TIMEOUT_MS = 280_000;
+const MAX_ARTIFACT_CHARS = 60_000;
+const BRIEF_FILE = '.thedesignagent-brief.md';
+const EXIT = { ok: 0, belowThreshold: 1, error: 2, authRequired: 3 };
+const USAGE = `Usage: thedesignagent <command> [options]
+
+Commands:
+  check [url|file]    Score a page or a source file; with no target, every page in .thedesignagent
+  brief "<task>"      Write a build brief for the screen you're about to build
+  login [key]         Save your API key (or pipe it on stdin)
+
+check options:
+  --task <text>       What the screen is for (default: a generic review)
+  --checks <list>     visual, ux or visual,ux (default: visual for a URL, ux for a file)
+  --code <file>       Source of the page; needed for --checks ux on a URL
+  --threshold <n>     Exit 1 if a check's overall score is below n (0-10)
+  --base-url <url>    With no target: where the configured pages live (e.g. a preview deploy)
+  --changed           Check only the pages this branch changed (Next.js app/ routes)
+  --pr-comment        In GitHub Actions: post the results as one PR comment, updated on every run
+  --base <ref>        Branch to diff against with --changed (default: origin/main, or the PR base in GitHub Actions)
+  --json              Print the result as JSON
+
+brief options:
+  --out <file>        Where to write the brief (default: ${BRIEF_FILE}; "-" for stdout)
+  --project-model <file>  Project model JSON, for a project's first brief
+  --json              Print the raw result as JSON
+
+Both use the project_id in .thedesignagent, or --project <id>, or THEDESIGNAGENT_PROJECT_ID.
+
+Exit codes: 0 ok, 1 below threshold, 2 error, 3 page is behind login (nothing charged).`;
+// ---- Small helpers --------------------------------------------------------
+class CliError extends Error {
+    code;
+    constructor(message, code = EXIT.error) {
+        super(message);
+        this.code = code;
+    }
+}
+function version() {
+    try {
+        return createRequire(import.meta.url)('../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function requireKey() {
+    const { key } = loadApiKey();
+    if (!key)
+        throw new CliError(MISSING_KEY_HELP);
+    return key;
+}
+function gitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+let cachedConfig;
+// .thedesignagent in the working directory or the repo root.
+function loadConfig() {
+    if (cachedConfig !== undefined)
+        return cachedConfig;
+    cachedConfig = null;
+    for (const dir of [process.cwd(), gitRoot()]) {
+        if (!dir)
+            continue;
+        const file = join(dir, '.thedesignagent');
+        if (!existsSync(file) || !statSync(file).isFile())
+            continue;
+        try {
+            cachedConfig = { config: JSON.parse(readFileSync(file, 'utf-8')), dir };
+        }
+        catch {
+            throw new CliError(`${file} is not valid JSON. Expected { "project_id": "proj_..." }.`);
+        }
+        break;
+    }
+    return cachedConfig;
+}
+function resolveProject(flag) {
+    const explicit = flag ?? process.env.THEDESIGNAGENT_PROJECT_ID;
+    if (explicit)
+        return { project_id: explicit };
+    const id = loadConfig()?.config.project_id;
+    if (id)
+        return { project_id: id };
+    // Same recipe as the agent skills. CI clones often use a different remote
+    // URL (https vs ssh), which hashes differently, so commit .thedesignagent.
+    try {
+        const remote = execSync('git remote get-url origin', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (remote)
+            return { repo_hash: createHash('sha256').update(remote).digest('hex') };
+    }
+    catch { /* not a git repo */ }
+    throw new CliError('No project found. Run this in a repo with a .thedesignagent file, or pass --project <id>.');
+}
+async function callEdge(path, body) {
+    let response;
+    try {
+        response = await fetch(`${API_BASE}/${path}`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${requireKey()}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(EDGE_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        if (e instanceof CliError)
+            throw e;
+        throw new CliError(`Couldn't reach TheDesignAgent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (response.ok)
+        return await response.json();
+    let err = {};
+    try {
+        err = await response.json();
+    }
+    catch { /* non-JSON error body */ }
+    const message = err.message ?? `HTTP ${response.status}`;
+    if (response.status === 401 || response.status === 403) {
+        throw new CliError(`Authentication failed: ${message}\nCheck your API key (THEDESIGNAGENT_API_KEY or "thedesignagent login").`);
+    }
+    if (response.status === 402)
+        throw new CliError(message);
+    if (response.status === 429)
+        throw new CliError(`Rate limit reached: ${message}`);
+    throw new CliError(`${path} failed (${response.status}): ${message}${err.detail ? `\nDetail: ${err.detail}` : ''}`);
+}
+function isUrl(target) {
+    return /^https?:\/\//i.test(target);
+}
+function readArtifact(path) {
+    const abs = resolve(path);
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        throw new CliError(`File not found: ${path}`);
+    const text = readFileSync(abs, 'utf-8');
+    return text.length > MAX_ARTIFACT_CHARS ? text.slice(0, MAX_ARTIFACT_CHARS) + '\n/* truncated */' : text;
+}
+function parseChecks(raw, target) {
+    if (!raw)
+        return isUrl(target) ? ['visual'] : ['ux'];
+    const names = raw.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    for (const n of names) {
+        if (n !== 'visual' && n !== 'ux')
+            throw new CliError(`Unknown check "${n}". Use visual, ux or visual,ux.`);
+    }
+    return [...new Set(names)];
+}
+function parseThreshold(raw) {
+    if (raw === undefined)
+        return null;
+    if (raw.trim() === '')
+        throw new CliError('--threshold is empty. Pass a number from 0 to 10.');
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0 || n > 10)
+        throw new CliError(`--threshold must be a number from 0 to 10, got "${raw}".`);
+    return n;
+}
+function envAuthSeed() {
+    const raw = process.env.THEDESIGNAGENT_AUTH_SEED;
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError('THEDESIGNAGENT_AUTH_SEED is not valid JSON.');
+    }
+}
+function defaultTask(target) {
+    return isUrl(target) ? `Review the page at ${new URL(target).pathname}` : `Review the UI in ${target}`;
+}
+function validateSpec(spec) {
+    if (isUrl(spec.target) && spec.checks.includes('ux') && !spec.code) {
+        throw new CliError(`The ux check reviews source code, not a screenshot. Pass the page's source with --code <file> (or "code" in .thedesignagent), or use --checks visual. (${spec.target})`);
+    }
+}
+async function checkPage(spec, identity, json) {
+    const url = isUrl(spec.target) ? spec.target : undefined;
+    const artifact = url
+        ? (spec.code ? readArtifact(spec.code) : `The rendered page at ${url}. Judge it from the screenshot.`)
+        : readArtifact(spec.target);
+    let screenshot;
+    if (url && spec.checks.includes('visual')) {
+        status(json, `Screenshotting ${url}…`);
+        const seed = envAuthSeed() ?? loadStoredAuth(url) ?? undefined;
+        const shot = await captureScreenshot(url, seed).catch((e) => {
+            throw new CliError(`Screenshot failed: ${e instanceof Error ? e.message : String(e)}`);
+        });
+        if (shot.authRequired) {
+            return {
+                result: { target: spec.target, screenshot: null, authRequired: true, finalUrl: shot.finalUrl, outcomes: [] },
+                identity,
+            };
+        }
+        screenshot = { base64: shot.base64, localPath: shot.localPath };
+    }
+    const outcomes = [];
+    let callIdentity = identity;
+    for (const check of spec.checks) {
+        status(json, `Running ${check} review${url ? ` of ${url}` : ''}…`);
+        const result = check === 'visual'
+            ? await callEdge('visual', {
+                task: spec.task, artifact, ...callIdentity,
+                ...(screenshot && { screenshot: screenshot.base64 }),
+                ...(url && { render_url: url }),
+            })
+            : await callEdge('ux', { task: spec.task, artifact, ...callIdentity });
+        // Later calls use the project the first one resolved, so an unknown id
+        // or a repo_hash doesn't create a second project.
+        if (result.project_id)
+            callIdentity = { project_id: result.project_id };
+        const score = (check === 'visual' ? result.visual_score : result.ux_score) ?? NaN;
+        outcomes.push({
+            check,
+            score,
+            passed: spec.threshold === null ? null : score >= spec.threshold,
+            summary: result.summary,
+            scores: result.scores ?? {},
+            findings: result.findings ?? [],
+            recommendations: result.recommendations ?? [],
+            degradations: result.degradations ?? [],
+        });
+    }
+    return {
+        result: { target: spec.target, screenshot: screenshot?.localPath ?? null, authRequired: false, outcomes },
+        identity: callIdentity,
+    };
+}
+function loginHelp(r) {
+    return [
+        `${r.target} redirected to a login page (${r.finalUrl}). No review ran and nothing was charged.`,
+        'Save a session first:',
+        `  npx -y --package=@thedesignagent/mcp thedesignagent-auth capture ${r.target}`,
+        'In CI, set THEDESIGNAGENT_AUTH_SEED to an AuthSeed object ({ "cookies": [...] }), or check a preview with protection bypass.',
+    ].join('\n');
+}
+// Pages from .thedesignagent: { "check": { "base_url", "threshold", "pages": [...] } }.
+function configuredSpecs(opts, thresholdFlag) {
+    const loaded = loadConfig();
+    const cfg = loaded?.config.check;
+    if (!cfg?.pages?.length) {
+        throw new CliError([
+            'Nothing to check. Pass a URL or file, or list pages in .thedesignagent:',
+            '  { "project_id": "proj_...", "check": { "base_url": "http://localhost:3000", "threshold": 7,',
+            '    "pages": [ { "path": "/checkout", "task": "Pay for the cart" } ] } }',
+        ].join('\n'));
+    }
+    const base = opts['base-url'] ?? process.env.THEDESIGNAGENT_BASE_URL ?? cfg.base_url;
+    const flagChecks = opts.checks ? parseChecks(opts.checks, 'http://x') : undefined;
+    return cfg.pages.map((page, i) => {
+        if (!page?.path)
+            throw new CliError(`.thedesignagent check.pages[${i}] needs a "path".`);
+        const isAbsolute = isUrl(page.path);
+        if (!isAbsolute && !base) {
+            throw new CliError(`No base URL for "${page.path}". Set check.base_url in .thedesignagent, or pass --base-url.`);
+        }
+        const target = isAbsolute ? page.path : new URL(page.path, base).href;
+        const configThreshold = page.threshold ?? cfg.threshold;
+        return {
+            target,
+            task: page.task ?? defaultTask(target),
+            code: page.code && loaded ? resolve(loaded.dir, page.code) : undefined,
+            checks: flagChecks ?? page.checks ?? ['visual'],
+            threshold: thresholdFlag ?? (typeof configThreshold === 'number' ? configThreshold : null),
+        };
+    });
+}
+// ---- --changed: map a branch's changed files to the routes they render ----
+const PAGE_FILE = /^page\.(tsx|jsx|ts|js|mdx)$/;
+function changedFiles(base) {
+    const ref = base
+        ?? (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'origin/main');
+    try {
+        return execSync(`git diff --name-only --diff-filter=d ${JSON.stringify(ref)}...HEAD`, { stdio: ['ignore', 'pipe', 'pipe'] })
+            .toString().split('\n').map(l => l.trim()).filter(Boolean);
+    }
+    catch {
+        throw new CliError(`Couldn't diff against ${ref}. Fetch it first (in CI: actions/checkout with fetch-depth: 0), or pass --base <ref>.`);
+    }
+}
+// Next.js App Router: app/(group)/orders/page.tsx -> /orders. Dynamic
+// segments ([id]) have no URL to visit, so they're skipped unless
+// .thedesignagent lists a concrete page for them.
+function routeForAppDir(segments) {
+    const parts = [];
+    for (const seg of segments) {
+        if (seg.startsWith('(') && seg.endsWith(')'))
+            continue;
+        if (seg.startsWith('@') || seg.startsWith('_'))
+            return null;
+        if (seg.startsWith('['))
+            return null;
+        parts.push(seg);
+    }
+    return '/' + parts.join('/');
+}
+// For each changed file, the nearest enclosing App Router page: a change to
+// app/orders/_components/table.tsx re-checks /orders.
+function pagesForChangedFiles(root, files) {
+    const found = new Map();
+    for (const file of files) {
+        if (!/\.(tsx|jsx|ts|js|mdx|css|scss)$/.test(file))
+            continue;
+        const parts = file.split('/');
+        const appIdx = parts.findIndex((p, i) => p === 'app' && (i === 0 || (i === 1 && parts[0] === 'src')));
+        if (appIdx === -1)
+            continue;
+        for (let end = parts.length - 1; end > appIdx; end--) {
+            const dir = parts.slice(0, end);
+            const page = ['tsx', 'jsx', 'ts', 'js', 'mdx'].map(ext => [...dir, `page.${ext}`].join('/'))
+                .find(candidate => existsSync(join(root, candidate)));
+            if (!page)
+                continue;
+            const route = routeForAppDir(dir.slice(appIdx + 1));
+            if (route && !found.has(route))
+                found.set(route, { route, pageFile: page });
+            break;
+        }
+    }
+    return [...found.values()];
+}
+function changedSpecs(opts, thresholdFlag) {
+    const root = gitRoot();
+    if (!root)
+        throw new CliError('--changed needs a git repository.');
+    const files = changedFiles(opts.base);
+    const loaded = loadConfig();
+    const cfg = loaded?.config.check;
+    const base = opts['base-url'] ?? process.env.THEDESIGNAGENT_BASE_URL ?? cfg?.base_url;
+    if (!base)
+        throw new CliError('No base URL. Pass --base-url, set THEDESIGNAGENT_BASE_URL, or set check.base_url in .thedesignagent.');
+    const flagChecks = opts.checks ? parseChecks(opts.checks, 'http://x') : undefined;
+    const changed = new Set(files);
+    const specs = new Map();
+    const add = (route, page, pageFile) => {
+        const target = isUrl(route) ? route : new URL(route, base).href;
+        if (specs.has(target))
+            return;
+        const t = page?.threshold ?? cfg?.threshold;
+        specs.set(target, {
+            target,
+            task: page?.task ?? defaultTask(target),
+            code: page?.code && loaded ? resolve(loaded.dir, page.code) : pageFile ? join(root, pageFile) : undefined,
+            checks: flagChecks ?? page?.checks ?? ['visual'],
+            threshold: thresholdFlag ?? (typeof t === 'number' ? t : null),
+        });
+    };
+    // Listed pages whose source changed, then routes found from the diff
+    // (using the listed page's task and threshold when the route matches).
+    for (const page of cfg?.pages ?? []) {
+        if (page.code && changed.has(page.code.replace(/^\.\//, '')))
+            add(page.path, page, undefined);
+    }
+    for (const { route, pageFile } of pagesForChangedFiles(root, files)) {
+        add(route, cfg?.pages?.find(p => p.path === route), pageFile);
+    }
+    return [...specs.values()];
+}
+async function runCheck(target, opts) {
+    const thresholdFlag = parseThreshold(opts.threshold);
+    if (target && opts.changed)
+        throw new CliError('Pass a target or --changed, not both.');
+    const specs = opts.changed
+        ? changedSpecs(opts, thresholdFlag)
+        : target
+            ? [{
+                    target,
+                    task: opts.task ?? defaultTask(target),
+                    code: opts.code,
+                    checks: parseChecks(opts.checks, target),
+                    threshold: thresholdFlag,
+                }]
+            : configuredSpecs(opts, thresholdFlag);
+    specs.forEach(validateSpec);
+    if (!specs.length) {
+        if (opts['pr-comment'])
+            await postPrComment(`${COMMENT_MARKER}\n### TheDesignAgent design check: no UI pages changed`, opts.pr);
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, passed: true, project_id: null, pages: [] }, null, 2));
+        else
+            console.log('No changed UI pages to check.');
+        return EXIT.ok;
+    }
+    let identity = resolveProject(opts.project);
+    requireKey();
+    const results = [];
+    for (const spec of specs) {
+        const { result, identity: next } = await checkPage(spec, identity, opts.json);
+        identity = next;
+        results.push(result);
+    }
+    const failed = results.some(r => r.outcomes.some(o => o.passed === false));
+    const loginBlocked = results.filter(r => r.authRequired);
+    const anyThreshold = specs.some(s => s.threshold !== null);
+    const passed = anyThreshold ? !failed && loginBlocked.length === 0 : null;
+    if (opts.json) {
+        const pageJson = (r, spec) => ({
+            target: r.target,
+            threshold: spec.threshold,
+            screenshot: r.screenshot,
+            ...(r.authRequired && { error: 'auth_required', message: loginHelp(r), final_url: r.finalUrl }),
+            checks: r.outcomes,
+        });
+        const body = target
+            // One target keeps the flat shape.
+            ? { ok: !results[0].authRequired, passed, project_id: identity.project_id ?? null, ...pageJson(results[0], specs[0]) }
+            : { ok: loginBlocked.length === 0, passed, project_id: identity.project_id ?? null, pages: results.map((r, i) => pageJson(r, specs[i])) };
+        console.log(JSON.stringify(body, null, 2));
+    }
+    else {
+        results.forEach((r, i) => {
+            if (r.authRequired)
+                console.error(loginHelp(r));
+            else
+                console.log(formatCheck(r.target, r.outcomes, specs[i].threshold, r.screenshot ?? undefined));
+            if (i < results.length - 1)
+                console.log('');
+        });
+    }
+    results.forEach((r, i) => { if (!r.authRequired)
+        writeStepSummary(r.target, r.outcomes, specs[i].threshold); });
+    if (opts['pr-comment'])
+        await postPrComment(prCommentBody(results, specs), opts.pr);
+    if (failed)
+        return EXIT.belowThreshold;
+    if (loginBlocked.length)
+        return EXIT.authRequired;
+    return EXIT.ok;
+}
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'];
+const severityRank = (s) => { const i = SEVERITY_ORDER.indexOf(s); return i === -1 ? SEVERITY_ORDER.length : i; };
+function fmt(n) {
+    return n === null || n === undefined || Number.isNaN(n) ? 'n/a' : n.toFixed(1);
+}
+function verdict(o, threshold) {
+    if (o.passed === null)
+        return '';
+    return o.passed ? `  pass (threshold ${threshold})` : `  FAIL (threshold ${threshold})`;
+}
+function formatCheck(target, outcomes, threshold, shotPath) {
+    const lines = [`TheDesignAgent · ${target}`, ''];
+    for (const o of outcomes) {
+        lines.push(`${o.check} ${fmt(o.score)}/10${verdict(o, threshold)}`);
+        lines.push('  ' + Object.entries(o.scores).map(([k, v]) => `${k} ${fmt(v)}`).join(' · '));
+        if (o.degradations.length)
+            lines.push(`  degraded: ${o.degradations.join(', ')}`);
+        lines.push('', `  ${o.summary}`, '');
+        const top = [...o.findings]
+            .sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+            .slice(0, 5);
+        for (const f of top) {
+            const loc = f.location ? ` (${f.location})` : '';
+            lines.push(`  [${f.severity}] ${f.dimension ?? f.track ?? 'general'}: ${f.description}${loc}`);
+        }
+        if (o.recommendations.length) {
+            lines.push('', '  Fix first:');
+            for (const r of o.recommendations.slice(0, 3))
+                lines.push(`  - ${r.change}`);
+        }
+        lines.push('');
+    }
+    if (shotPath)
+        lines.push(`Screenshot: ${shotPath}`);
+    return lines.join('\n').trimEnd();
+}
+// GitHub Actions shows this file on the run's summary page.
+function writeStepSummary(target, outcomes, threshold) {
+    const path = process.env.GITHUB_STEP_SUMMARY;
+    if (!path)
+        return;
+    const rows = outcomes.map(o => {
+        const result = o.passed === null ? '' : o.passed ? 'pass' : 'fail';
+        return `| ${o.check} | ${fmt(o.score)} | ${result} |`;
+    });
+    const findings = outcomes.flatMap(o => o.findings
+        .filter(f => f.severity === 'critical' || f.severity === 'high')
+        .map(f => `- **${o.check} · ${f.severity}**: ${f.description}`));
+    const md = [
+        `### TheDesignAgent: ${target}`,
+        '',
+        `| Check | Score | ${threshold === null ? '' : `Threshold ${threshold}`} |`,
+        '| --- | --- | --- |',
+        ...rows,
+        '',
+        ...(findings.length ? ['**Critical and high findings**', '', ...findings, ''] : []),
+    ].join('\n');
+    try {
+        appendFileSync(path, md + '\n');
+    }
+    catch { /* summary is best-effort */ }
+}
+// ---- --pr-comment: one comment per pull request, updated on every run ----
+const COMMENT_MARKER = '<!-- thedesignagent-check -->';
+function prCommentBody(results, specs) {
+    const failed = results.some(r => r.outcomes.some(o => o.passed === false));
+    const blocked = results.filter(r => r.authRequired);
+    const headline = failed
+        ? '❌ Below threshold'
+        : blocked.length ? `⚠️ ${blocked.length} page${blocked.length > 1 ? 's' : ''} couldn't be checked (login)`
+            : specs.some(s => s.threshold !== null) ? '✅ Passed' : 'Scores';
+    const pagePath = (target) => { try {
+        return new URL(target).pathname;
+    }
+    catch {
+        return target;
+    } };
+    const rows = [];
+    results.forEach((r, i) => {
+        if (r.authRequired) {
+            rows.push(`| \`${pagePath(r.target)}\` | | | ${specs[i].threshold ?? ''} | login required |`);
+            return;
+        }
+        for (const o of r.outcomes) {
+            const result = o.passed === null ? '' : o.passed ? 'pass' : '**fail**';
+            rows.push(`| \`${pagePath(r.target)}\` | ${o.check} | ${fmt(o.score)} | ${specs[i].threshold ?? ''} | ${result} |`);
+        }
+    });
+    const details = [];
+    for (const r of results) {
+        for (const o of r.outcomes) {
+            const top = [...o.findings].sort((a, b) => severityRank(a.severity) - severityRank(b.severity)).slice(0, 5);
+            if (!top.length && !o.recommendations.length)
+                continue;
+            details.push(`<details><summary><code>${pagePath(r.target)}</code> · ${o.check} ${fmt(o.score)}</summary>`, '', o.summary, '', ...top.map(f => `- **${f.severity}** ${f.dimension ?? f.track ?? 'general'}: ${f.description}${f.location ? ` (${f.location})` : ''}`), ...(o.recommendations.length ? ['', '**Fix first**', ...o.recommendations.slice(0, 3).map(rc => `- ${rc.change}`)] : []), '', '</details>');
+        }
+    }
+    return [
+        COMMENT_MARKER,
+        `### TheDesignAgent design check: ${headline}`,
+        '',
+        '| Page | Check | Score | Threshold | Result |',
+        '| --- | --- | --- | --- | --- |',
+        ...rows,
+        '',
+        ...details,
+    ].join('\n');
+}
+function pullRequestNumber(flag) {
+    if (flag)
+        return Number(flag) || null;
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (!eventPath || !existsSync(eventPath))
+        return null;
+    try {
+        const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+        return event.pull_request?.number ?? event.number ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Best-effort: a failed comment never changes the check's exit code.
+async function postPrComment(body, prFlag) {
+    const token = process.env.GITHUB_TOKEN;
+    const repo = process.env.GITHUB_REPOSITORY;
+    const pr = pullRequestNumber(prFlag);
+    if (!token || !repo || !pr) {
+        console.error('--pr-comment: skipped. It needs GITHUB_TOKEN, GITHUB_REPOSITORY and a pull_request event (or --pr <number>).');
+        return;
+    }
+    const api = process.env.GITHUB_API_URL ?? 'https://api.github.com';
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+    };
+    try {
+        let existing = null;
+        for (let page = 1; page <= 10 && existing === null; page++) {
+            const res = await fetch(`${api}/repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`, { headers });
+            if (!res.ok)
+                throw new Error(`listing comments: HTTP ${res.status}`);
+            const comments = await res.json();
+            existing = comments.find(c => c.body?.startsWith(COMMENT_MARKER))?.id ?? null;
+            if (comments.length < 100)
+                break;
+        }
+        const res = existing
+            ? await fetch(`${api}/repos/${repo}/issues/comments/${existing}`, { method: 'PATCH', headers, body: JSON.stringify({ body }) })
+            : await fetch(`${api}/repos/${repo}/issues/${pr}/comments`, { method: 'POST', headers, body: JSON.stringify({ body }) });
+        if (!res.ok)
+            throw new Error(`${existing ? 'updating' : 'posting'} comment: HTTP ${res.status}`);
+    }
+    catch (e) {
+        const hint = String(e).includes('403') ? ' Give the job "permissions: pull-requests: write".' : '';
+        console.error(`--pr-comment: couldn't comment on PR #${pr}: ${e instanceof Error ? e.message : String(e)}.${hint}`);
+    }
+}
+function status(json, msg) {
+    // Progress goes to stderr so --json stdout stays parseable.
+    if (!json && process.stderr.isTTY)
+        console.error(msg);
+}
+async function runBrief(task, opts) {
+    const identity = resolveProject(opts.project);
+    let projectModel;
+    if (opts.projectModel) {
+        try {
+            projectModel = JSON.parse(readFileSync(resolve(opts.projectModel), 'utf-8'));
+        }
+        catch (e) {
+            throw new CliError(`Couldn't read --project-model: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    status(opts.json, 'Getting a build brief…');
+    const result = await callEdge('discovery', {
+        task, ...identity, ...(projectModel && { projectModel }),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result.status === 'ok' ? EXIT.ok : EXIT.error;
+    }
+    if (result.status !== 'ok') {
+        const why = result.status === 'needs_setup'
+            ? 'This project has no stored model yet.'
+            : 'The stored project model is out of date with your schema.';
+        console.error([
+            why,
+            'Run one brief from your coding agent (it scans the repo and builds the model),',
+            'or build the model yourself and pass it with --project-model <file>. The extraction task:',
+            '',
+            result.extraction_task ?? '(none returned)',
+        ].join('\n'));
+        return EXIT.error;
+    }
+    const md = [
+        `# Build brief: ${task}`,
+        '',
+        `Project ${result.project_id}${result.active_job ? ` · active job: ${result.active_job}` : ''}`,
+        `Generated by TheDesignAgent ${new Date().toISOString().slice(0, 10)}. Follow it while building this screen.`,
+        '',
+        result.brief ?? '',
+        '',
+    ].join('\n');
+    const out = opts.out ?? BRIEF_FILE;
+    if (out === '-') {
+        process.stdout.write(md);
+    }
+    else {
+        writeFileSync(resolve(out), md);
+        console.log(`Wrote ${out}. Point your agent at it, e.g. add "Read ${out} before building UI." to AGENTS.md or CLAUDE.md.`);
+    }
+    if (!identity.project_id && result.project_id) {
+        console.error(`Tip: save { "project_id": "${result.project_id}" } to .thedesignagent and commit it, so CI and every agent share this project.`);
+    }
+    return EXIT.ok;
+}
+// ---- login ----------------------------------------------------------------
+async function readKeyInteractively() {
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks).toString('utf-8').trim();
+    }
+    console.error('Get a key at https://thedesignagent.ai/dashboard/api-keys');
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    // Hide what's typed: the key is a secret and terminals get recorded.
+    const rlOut = rl;
+    let prompted = false;
+    rlOut._writeToOutput = (s) => {
+        if (!prompted) {
+            rlOut.output.write(s);
+            prompted = true;
+        }
+    };
+    rl.on('SIGINT', () => {
+        rl.close();
+        process.stderr.write('\n');
+        process.exit(130);
+    });
+    const key = await new Promise(res => rl.question('Paste your API key: ', res));
+    rl.close();
+    process.stderr.write('\n');
+    return key.trim();
+}
+async function runLogin(keyArg) {
+    const key = (keyArg ?? await readKeyInteractively()).trim();
+    if (!looksLikeApiKey(key)) {
+        throw new CliError('That doesn\'t look like a TheDesignAgent key. Keys start with tda_.');
+    }
+    const path = saveApiKey(key);
+    console.log(`Saved to ${path} (readable only by you).`);
+    if (process.env.THEDESIGNAGENT_API_KEY) {
+        console.error('Note: THEDESIGNAGENT_API_KEY is set in this shell and takes precedence over the saved key.');
+    }
+    return EXIT.ok;
+}
+// ---- main -----------------------------------------------------------------
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            task: { type: 'string' },
+            checks: { type: 'string' },
+            code: { type: 'string' },
+            threshold: { type: 'string' },
+            json: { type: 'boolean' },
+            project: { type: 'string' },
+            'base-url': { type: 'string' },
+            changed: { type: 'boolean' },
+            'pr-comment': { type: 'boolean' },
+            pr: { type: 'string' },
+            base: { type: 'string' },
+            out: { type: 'string' },
+            'project-model': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    if (values.version) {
+        console.log(version());
+        return EXIT.ok;
+    }
+    const [command, ...rest] = positionals;
+    if (values.help || !command) {
+        console.log(USAGE);
+        return command || values.help ? EXIT.ok : EXIT.error;
+    }
+    switch (command) {
+        case 'check':
+            if (rest.length > 1)
+                throw new CliError('Usage: thedesignagent check [url|file] [--threshold n] [--json]');
+            return runCheck(rest[0], values);
+        case 'brief':
+            if (!rest.length)
+                throw new CliError('Usage: thedesignagent brief "<what you are about to build>"');
+            return runBrief(rest.join(' '), { ...values, projectModel: values['project-model'] });
+        case 'login':
+            return runLogin(rest[0]);
+        default:
+            throw new CliError(`Unknown command "${command}".\n\n${USAGE}`);
+    }
+}
+// Set exitCode rather than calling process.exit(): on macOS, stdout to a pipe
+// is async, and exiting early truncates large --json output.
+const wantsJson = process.argv.includes('--json');
+main().then(code => { process.exitCode = code; }, (e) => {
+    // parseArgs throws TypeError with a readable message for bad flags.
+    const message = e instanceof Error ? e.message : String(e);
+    if (wantsJson)
+        console.log(JSON.stringify({ ok: false, error: 'error', message }, null, 2));
+    console.error(message);
+    process.exitCode = e instanceof CliError ? e.code : EXIT.error;
+});