frontend-precision 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1664 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync
+} from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/config/schema.ts
+import { z } from "zod";
+
+// src/lib/safe-slug.ts
+var SAFE_SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function isSafeSlug(value) {
+  return typeof value === "string" && !value.includes("..") && !value.includes("/") && !value.includes("\\") && SAFE_SLUG_PATTERN.test(value);
+}
+function assertSafeSlug(value, label) {
+  if (!isSafeSlug(value)) {
+    throw new Error(
+      `Invalid ${label} "${String(value)}". Use a slug of letters, digits, '.', '_' or '-' (no path separators or '..').`
+    );
+  }
+  return value;
+}
+
+// src/config/schema.ts
+var ViewportSchema = z.object({
+  width: z.number().int().positive(),
+  height: z.number().int().positive()
+});
+var RouteSchema = z.object({
+  name: z.string().min(1).refine(isSafeSlug, {
+    message: "Invalid route name. Use a slug of letters, digits, '.', '_' or '-' with no path separators or '..'."
+  }),
+  path: z.string().min(1),
+  reference: z.string().optional(),
+  /**
+   * figma: 设计稿导出基线（可宣称视觉验收）
+   * regression: 实现自截图回归基线（不得当作 Figma PASS）
+   */
+  referenceKind: z.enum(["figma", "regression"]).default("figma"),
+  viewport: ViewportSchema.optional(),
+  waitFor: z.string().optional(),
+  hide: z.array(z.string()).optional()
+});
+var RoutesSchema = z.array(RouteSchema).min(1).superRefine((routes, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  routes.forEach((route, index) => {
+    if (seen.has(route.name)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [index, "name"],
+        message: `Duplicate route name: ${route.name}`
+      });
+    }
+    seen.add(route.name);
+  });
+});
+var ConfigSchema = z.object({
+  baseUrl: z.string().url(),
+  viewport: ViewportSchema,
+  routes: RoutesSchema,
+  visual: z.object({
+    pixelThreshold: z.number().min(0).max(1).default(0.1),
+    maxDiffRatio: z.number().min(0).max(1).default(0.03)
+  }).default({ pixelThreshold: 0.1, maxDiffRatio: 0.03 }),
+  testCommand: z.string().min(1),
+  maxFixAttempts: z.number().int().min(0).max(10).default(3),
+  browser: z.enum(["chromium", "firefox", "webkit"]).default("chromium"),
+  settleMs: z.number().int().nonnegative().default(300),
+  /** 绑定任务目录名，report 自动读取 acceptance.md */
+  taskId: z.string().min(1).optional(),
+  gates: z.object({
+    /** 报告必须加载到至少 1 条 AC，否则 FAIL */
+    requireAcceptance: z.boolean().default(true),
+    /** 任一 AC 为 PENDING/PARTIAL/FAIL 则整体不能 PASS */
+    requireAcceptanceAllPass: z.boolean().default(true),
+    /** 存在 referenceKind=regression 的路由时，不得宣称 Figma 视觉通过 */
+    requireFigmaVisual: z.boolean().default(false),
+    /** reference 与 actual 字节完全相同 → FAIL（防自截图冒充） */
+    rejectIdenticalBaseline: z.boolean().default(true)
+  }).default({
+    requireAcceptance: true,
+    requireAcceptanceAllPass: true,
+    requireFigmaVisual: false,
+    rejectIdenticalBaseline: true
+  }),
+  checks: z.object({
+    typecheck: z.string().optional(),
+    lint: z.string().optional(),
+    unit: z.string().optional(),
+    e2e: z.string().optional()
+  }).optional()
+});
+var CONFIG_FILENAME = "frontend-precision.config.json";
+
+// src/lib/templates.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function getTemplatesRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "templates"),
+    join(here, "..", "templates"),
+    join(here, "..", "..", "src", "templates"),
+    join(here, "..", "..", "dist", "templates")
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  throw new Error(
+    "Cannot locate templates directory. Rebuild the CLI (`pnpm build`)."
+  );
+}
+
+// src/commands/init.ts
+function copyIfNeeded(src, dest, force) {
+  if (existsSync2(dest) && !force) return "skipped";
+  mkdirSync(dirname2(dest), { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  return existsSync2(dest) && force ? "overwritten" : "created";
+}
+function runInit(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const force = options.force ?? false;
+  const templates = getTemplatesRoot();
+  const messages = [];
+  const defaultConfigPath = join2(templates, "config.default.json");
+  const configPath = join2(cwd, CONFIG_FILENAME);
+  if (existsSync2(configPath) && !force) {
+    messages.push(`Skipped ${CONFIG_FILENAME} (exists). Use --force to overwrite.`);
+  } else {
+    writeFileSync(configPath, readFileSync(defaultConfigPath));
+    messages.push(
+      existsSync2(configPath) && force ? `Overwrote ${CONFIG_FILENAME}` : `Created ${CONFIG_FILENAME}`
+    );
+  }
+  const skillSrc = join2(templates, "skill", "frontend-precision");
+  const skillDest = join2(cwd, ".cursor", "skills", "frontend-precision");
+  if (existsSync2(skillDest) && !force) {
+    messages.push(
+      "Skipped .cursor/skills/frontend-precision (exists). Use --force to overwrite."
+    );
+  } else {
+    mkdirSync(join2(cwd, ".cursor", "skills"), { recursive: true });
+    cpSync(skillSrc, skillDest, { recursive: true });
+    messages.push(
+      force ? "Overwrote .cursor/skills/frontend-precision" : "Installed .cursor/skills/frontend-precision"
+    );
+  }
+  const ruleSrc = join2(templates, "rules", "frontend-precision.mdc");
+  const ruleDest = join2(cwd, ".cursor", "rules", "frontend-precision.mdc");
+  const ruleStatus = copyIfNeeded(ruleSrc, ruleDest, force);
+  messages.push(
+    ruleStatus === "skipped" ? "Skipped .cursor/rules/frontend-precision.mdc (exists)." : `${ruleStatus === "overwritten" ? "Overwrote" : "Installed"} .cursor/rules/frontend-precision.mdc`
+  );
+  const taskTplSrc = join2(templates, "task-templates");
+  const taskTplDest = join2(
+    cwd,
+    ".frontend-precision",
+    "templates"
+  );
+  if (!existsSync2(taskTplDest) || force) {
+    mkdirSync(taskTplDest, { recursive: true });
+    cpSync(taskTplSrc, taskTplDest, { recursive: true });
+    messages.push("Installed .frontend-precision/templates (preflight/plan/acceptance)");
+  }
+  const gitignorePath = join2(cwd, ".gitignore");
+  const ignoreLine = ".frontend-precision/artifacts/";
+  if (existsSync2(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf8");
+    if (!content.includes(".frontend-precision")) {
+      appendFileSync(gitignorePath, `
+# frontend-precision
+.frontend-precision/artifacts/
+`);
+      messages.push("Appended .frontend-precision/artifacts/ to .gitignore");
+    } else {
+      messages.push(`Skipped .gitignore (already mentions frontend-precision)`);
+    }
+  } else {
+    writeFileSync(
+      gitignorePath,
+      `# frontend-precision
+${ignoreLine}
+`
+    );
+    messages.push("Created .gitignore with .frontend-precision/artifacts/");
+  }
+  messages.push("");
+  messages.push("Next steps:");
+  messages.push("  1. Edit frontend-precision.config.json (baseUrl, routes, references)");
+  messages.push("  2. Install Playwright browsers: pnpm exec playwright install chromium");
+  messages.push("  3. In Cursor: /frontend-precision with your PRD + Figma link");
+  messages.push("  4. Run: frontend-precision doctor");
+  return { messages, configPath };
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync4 } from "fs";
+import { resolve as resolve2, join as join3 } from "path";
+import { spawnSync } from "child_process";
+
+// src/config/load.ts
+import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
+import { resolve } from "path";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function loadConfig(cwd = process.cwd()) {
+  const path = resolve(cwd, CONFIG_FILENAME);
+  if (!existsSync3(path)) {
+    throw new ConfigError(
+      `Missing ${CONFIG_FILENAME}. Run \`frontend-precision init\` first.`
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (err) {
+    throw new ConfigError(
+      `Invalid JSON in ${CONFIG_FILENAME}: ${err.message}`
+    );
+  }
+  const parsed = ConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new ConfigError(`${CONFIG_FILENAME} validation failed:
+${details}`);
+  }
+  return parsed.data;
+}
+
+// src/lib/http-status.ts
+function isHealthyHttpStatus(status) {
+  return Number.isInteger(status) && status >= 200 && status < 300;
+}
+
+// src/commands/doctor.ts
+var defaultDeps = {
+  spawnSync,
+  fetch: globalThis.fetch.bind(globalThis)
+};
+function spawnOk(result) {
+  return result.status === 0;
+}
+async function runDoctor(cwd = process.cwd(), deps = defaultDeps) {
+  const checks = [];
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  checks.push({
+    name: "Node.js >= 20",
+    ok: nodeMajor >= 20,
+    detail: `Detected v${process.versions.node}`,
+    fix: "Install Node.js 20+ from https://nodejs.org/"
+  });
+  const pnpm = deps.spawnSync("pnpm", ["--version"], { encoding: "utf8" });
+  checks.push({
+    name: "pnpm",
+    ok: spawnOk(pnpm),
+    detail: spawnOk(pnpm) ? `pnpm ${pnpm.stdout.trim()}` : "pnpm not found",
+    fix: "corepack enable && corepack prepare pnpm@latest --activate"
+  });
+  let config = null;
+  let configDetail = `Missing ${CONFIG_FILENAME}`;
+  let configFix = "Run `frontend-precision init`";
+  try {
+    config = loadConfig(cwd);
+    configDetail = `Valid config at ${join3(cwd, CONFIG_FILENAME)}`;
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      configDetail = err.message;
+      configFix = err.message.includes("validation failed") ? "Fix the invalid fields listed above in frontend-precision.config.json" : "Run `frontend-precision init` (use --force only if you intend to replace the file)";
+    } else {
+      configDetail = err.message;
+    }
+  }
+  checks.push({
+    name: CONFIG_FILENAME,
+    ok: Boolean(config),
+    detail: configDetail,
+    fix: configFix
+  });
+  if (config) {
+    let reachable = false;
+    let reachDetail = "";
+    try {
+      const res = await deps.fetch(config.baseUrl, {
+        signal: AbortSignal.timeout(5e3)
+      });
+      reachable = isHealthyHttpStatus(res.status);
+      reachDetail = `HTTP ${res.status} from ${config.baseUrl}`;
+      if (!reachable) {
+        reachDetail += " (expected 2xx)";
+      }
+    } catch (err) {
+      reachDetail = `Unreachable: ${err.message}`;
+    }
+    checks.push({
+      name: "baseUrl reachable",
+      ok: reachable,
+      detail: reachDetail,
+      fix: "Start your dev server, or update baseUrl in config"
+    });
+    for (const route of config.routes) {
+      if (!route.reference) {
+        checks.push({
+          name: `reference:${route.name}`,
+          ok: false,
+          detail: "No reference path configured",
+          fix: "Set routes[].reference to a PNG baseline (from Figma export or Agent)"
+        });
+        continue;
+      }
+      const refPath = resolve2(cwd, route.reference);
+      checks.push({
+        name: `reference:${route.name}`,
+        ok: existsSync4(refPath),
+        detail: existsSync4(refPath) ? `Found ${refPath}` : `Missing ${refPath}`,
+        fix: "Export baseline PNG or ask Agent to place Figma screenshot"
+      });
+    }
+    const testCmd = config.testCommand.trim();
+    checks.push({
+      name: "testCommand non-empty",
+      ok: testCmd.length > 0,
+      detail: testCmd || "(empty)",
+      fix: 'Set testCommand e.g. "pnpm test:e2e"'
+    });
+  }
+  const pwInstall = deps.spawnSync(
+    process.platform === "win32" ? "npx.cmd" : "npx",
+    ["playwright", "--version"],
+    { cwd, encoding: "utf8" }
+  );
+  checks.push({
+    name: "Playwright CLI",
+    ok: spawnOk(pwInstall),
+    detail: spawnOk(pwInstall) ? pwInstall.stdout.trim() || "playwright available" : "Playwright not available via npx",
+    fix: "pnpm add -D playwright && pnpm exec playwright install chromium"
+  });
+  const skillPath = join3(
+    cwd,
+    ".cursor",
+    "skills",
+    "frontend-precision",
+    "SKILL.md"
+  );
+  checks.push({
+    name: "Cursor Skill installed",
+    ok: existsSync4(skillPath),
+    detail: existsSync4(skillPath) ? skillPath : "Skill not found",
+    fix: "Run `frontend-precision init`"
+  });
+  return { checks, ok: checks.every((c) => c.ok) };
+}
+function formatDoctor(checks) {
+  const lines = ["frontend-precision doctor", ""];
+  for (const c of checks) {
+    lines.push(`${c.ok ? "\u2713" : "\u2717"} ${c.name}`);
+    lines.push(`  ${c.detail}`);
+    if (!c.ok && c.fix) lines.push(`  Fix: ${c.fix}`);
+  }
+  lines.push("");
+  lines.push(
+    checks.every((c) => c.ok) ? "All checks passed." : "Some checks failed. Fix the items above before capture/visual/test."
+  );
+  return lines.join("\n");
+}
+
+// src/commands/capture.ts
+import { writeFileSync as writeFileSync3 } from "fs";
+import { join as join6 } from "path";
+
+// src/lib/screenshot.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+import { join as join5 } from "path";
+import { chromium, firefox, webkit } from "playwright";
+
+// src/lib/paths.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join4, resolve as resolve3, sep } from "path";
+
+// src/lib/run-id.ts
+function createRunId(date = /* @__PURE__ */ new Date()) {
+  const iso = date.toISOString().replace(/[:.]/g, "-");
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${iso}_${rand}`;
+}
+function assertSafeRunId(runId) {
+  return assertSafeSlug(runId, "run id");
+}
+
+// src/lib/paths.ts
+var ARTIFACTS_ROOT = ".frontend-precision";
+var ARTIFACTS_DIR = "artifacts";
+function resolveCwd(cwd) {
+  return resolve3(cwd ?? process.cwd());
+}
+function fpRoot(cwd) {
+  return join4(resolveCwd(cwd), ARTIFACTS_ROOT);
+}
+function artifactsDir(runId, cwd) {
+  const safeId = assertSafeRunId(runId);
+  const root = resolve3(join4(fpRoot(cwd), ARTIFACTS_DIR));
+  const resolved = resolve3(root, safeId);
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  if (resolved !== root && !resolved.startsWith(prefix)) {
+    throw new Error(
+      `Invalid run id "${runId}": resolved path escapes artifacts directory.`
+    );
+  }
+  return resolved;
+}
+function screenshotsDir(runId, cwd) {
+  return join4(artifactsDir(runId, cwd), "screenshots");
+}
+function assertContainedPath(root, candidate, label) {
+  const resolvedRoot = resolve3(root);
+  const resolvedCandidate = resolve3(candidate);
+  const prefix = resolvedRoot.endsWith(sep) ? resolvedRoot : resolvedRoot + sep;
+  if (resolvedCandidate !== resolvedRoot && !resolvedCandidate.startsWith(prefix)) {
+    throw new Error(`${label} escapes its output directory.`);
+  }
+  return resolvedCandidate;
+}
+function screenshotPath(runId, routeName, cwd) {
+  const safeName = assertSafeSlug(routeName, "route name");
+  const root = screenshotsDir(runId, cwd);
+  return assertContainedPath(
+    root,
+    resolve3(root, `${safeName}.png`),
+    "Route screenshot path"
+  );
+}
+function visualDir(runId, routeName, cwd) {
+  const safeName = assertSafeSlug(routeName, "route name");
+  const root = resolve3(artifactsDir(runId, cwd), "visual");
+  return assertContainedPath(
+    root,
+    resolve3(root, safeName),
+    "Route visual path"
+  );
+}
+function ensureDir(path) {
+  mkdirSync2(path, { recursive: true });
+  return path;
+}
+
+// src/lib/routes.ts
+function selectRoutes(routes, filter) {
+  if (!filter?.length) return routes;
+  const missing = filter.filter(
+    (name) => !routes.some((route) => route.name === name)
+  );
+  if (missing.length > 0) {
+    const valid = routes.map((r) => r.name).join(", ") || "(none)";
+    throw new Error(
+      `Unknown route(s): ${missing.join(", ")}. Valid routes: ${valid}`
+    );
+  }
+  return routes.filter((route) => filter.includes(route.name));
+}
+
+// src/lib/screenshot.ts
+function browserType(name) {
+  switch (name) {
+    case "firefox":
+      return firefox;
+    case "webkit":
+      return webkit;
+    default:
+      return chromium;
+  }
+}
+async function captureRoutes(options) {
+  const { config, runId, cwd, routeFilter } = options;
+  const outDir = ensureDir(screenshotsDir(runId, cwd));
+  const routes = selectRoutes(config.routes, routeFilter);
+  const browser = await browserType(config.browser).launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: config.viewport,
+    deviceScaleFactor: 1
+  });
+  const page = await context.newPage();
+  const screenshots = [];
+  const routeViewports = {};
+  try {
+    for (const route of routes) {
+      const url = new URL(route.path, config.baseUrl).toString();
+      const filePath = screenshotPath(runId, route.name, cwd);
+      const viewport = route.viewport ?? config.viewport;
+      routeViewports[route.name] = viewport;
+      try {
+        await page.setViewportSize(viewport);
+        const response = await page.goto(url, {
+          waitUntil: "load",
+          timeout: 6e4
+        });
+        const status = response?.status() ?? 0;
+        const finalUrl = page.url();
+        if (!response || !isHealthyHttpStatus(status)) {
+          throw new Error(
+            `HTTP ${status} for ${url} (final: ${finalUrl}); expected 2xx`
+          );
+        }
+        await page.waitForLoadState("networkidle", { timeout: 3e4 }).catch(
+          () => void 0
+        );
+        await page.evaluate(async () => {
+          const fonts = globalThis.document?.fonts;
+          if (fonts?.ready) await fonts.ready;
+        });
+        if (route.waitFor) {
+          await page.waitForSelector(route.waitFor, { timeout: 3e4 });
+        }
+        if (route.hide?.length) {
+          await page.addStyleTag({
+            content: route.hide.map((sel) => `${sel}{visibility:hidden !important;}`).join("\n")
+          });
+        }
+        if (config.settleMs > 0) {
+          await page.waitForTimeout(config.settleMs);
+        }
+        await page.screenshot({ path: filePath, fullPage: false });
+        screenshots.push({ name: route.name, path: filePath, url: finalUrl, ok: true });
+      } catch (err) {
+        screenshots.push({
+          name: route.name,
+          path: filePath,
+          url,
+          ok: false,
+          error: err.message
+        });
+      }
+    }
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+  const meta = {
+    runId,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    viewport: config.viewport,
+    routeViewports,
+    browser: config.browser,
+    baseUrl: config.baseUrl,
+    screenshots
+  };
+  const metaPath = join5(outDir, "capture-meta.json");
+  writeFileSync2(metaPath, JSON.stringify(meta, null, 2));
+  return { runId, screenshots, metaPath };
+}
+
+// src/commands/capture.ts
+async function runCapture(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadConfig(cwd);
+  const runId = options.runId ?? createRunId();
+  ensureDir(artifactsDir(runId, cwd));
+  const result = await captureRoutes({
+    config,
+    runId,
+    cwd,
+    routeFilter: options.routes
+  });
+  writeFileSync3(
+    join6(artifactsDir(runId, cwd), "run-id.txt"),
+    runId,
+    "utf8"
+  );
+  const failed = result.screenshots.filter((s) => !s.ok);
+  const ok = failed.length === 0;
+  const message = [
+    `Capture run: ${runId}`,
+    ...result.screenshots.map(
+      (s) => `  ${s.ok ? "\u2713" : "\u2717"} ${s.name} \u2192 ${s.path}${s.error ? ` (${s.error})` : ""}`
+    ),
+    `Meta: ${result.metaPath}`
+  ].join("\n");
+  return { runId, ok, message };
+}
+
+// src/commands/visual.ts
+import { resolve as resolve4 } from "path";
+import { existsSync as existsSync6 } from "fs";
+
+// src/lib/visual-diff.ts
+import {
+  existsSync as existsSync5,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync4,
+  mkdirSync as mkdirSync3,
+  copyFileSync
+} from "fs";
+import { createHash } from "crypto";
+import { dirname as dirname3, join as join7 } from "path";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+function sha256File(path) {
+  return createHash("sha256").update(readFileSync3(path)).digest("hex");
+}
+function ensureParent(filePath) {
+  mkdirSync3(dirname3(filePath), { recursive: true });
+}
+function compareImages(input) {
+  const {
+    name,
+    referencePath,
+    actualPath,
+    outputDir,
+    pixelThreshold,
+    maxDiffRatio,
+    referenceKind = "figma",
+    rejectIdenticalBaseline = true
+  } = input;
+  mkdirSync3(outputDir, { recursive: true });
+  const outRef = join7(outputDir, "reference.png");
+  const outActual = join7(outputDir, "actual.png");
+  const outDiff = join7(outputDir, "diff.png");
+  const outJson = join7(outputDir, "visual-result.json");
+  const base = {
+    name,
+    pixelThreshold,
+    maxDiffRatio,
+    referenceKind,
+    identicalBytes: false,
+    paths: {
+      reference: outRef,
+      actual: outActual,
+      diff: null,
+      resultJson: outJson
+    }
+  };
+  if (!existsSync5(referencePath)) {
+    const result2 = {
+      ...base,
+      width: 0,
+      height: 0,
+      diffRatio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      passed: false,
+      reason: `missing_reference: ${referencePath}`
+    };
+    writeFileSync4(outJson, JSON.stringify(result2, null, 2));
+    return result2;
+  }
+  if (!existsSync5(actualPath)) {
+    copyFileSync(referencePath, outRef);
+    const result2 = {
+      ...base,
+      width: 0,
+      height: 0,
+      diffRatio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      passed: false,
+      reason: `missing_actual: ${actualPath}`
+    };
+    writeFileSync4(outJson, JSON.stringify(result2, null, 2));
+    return result2;
+  }
+  const identicalBytes = sha256File(referencePath) === sha256File(actualPath);
+  copyFileSync(referencePath, outRef);
+  copyFileSync(actualPath, outActual);
+  const rejectIdentical = identicalBytes && rejectIdenticalBaseline && referenceKind === "figma";
+  if (rejectIdentical) {
+    const result2 = {
+      ...base,
+      identicalBytes: true,
+      width: 0,
+      height: 0,
+      diffRatio: 0,
+      diffPixels: 0,
+      totalPixels: 0,
+      passed: false,
+      reason: "self_baseline_identical: reference SHA-256 equals capture while referenceKind=figma; export a real Figma PNG or set referenceKind=regression"
+    };
+    writeFileSync4(outJson, JSON.stringify(result2, null, 2));
+    return result2;
+  }
+  let refPng;
+  let actPng;
+  try {
+    refPng = PNG.sync.read(readFileSync3(referencePath));
+    actPng = PNG.sync.read(readFileSync3(actualPath));
+  } catch (err) {
+    const result2 = {
+      ...base,
+      identicalBytes,
+      width: 0,
+      height: 0,
+      diffRatio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      passed: false,
+      reason: `image_read_error: ${err.message}`
+    };
+    writeFileSync4(outJson, JSON.stringify(result2, null, 2));
+    return result2;
+  }
+  if (refPng.width !== actPng.width || refPng.height !== actPng.height) {
+    const result2 = {
+      ...base,
+      identicalBytes,
+      width: actPng.width,
+      height: actPng.height,
+      diffRatio: 1,
+      diffPixels: 0,
+      totalPixels: refPng.width * refPng.height,
+      passed: false,
+      reason: `dimension_mismatch: reference=${refPng.width}x${refPng.height} actual=${actPng.width}x${actPng.height}`,
+      paths: { ...base.paths, diff: null }
+    };
+    writeFileSync4(outJson, JSON.stringify(result2, null, 2));
+    return result2;
+  }
+  const { width, height } = refPng;
+  const diff = new PNG({ width, height });
+  const diffPixels = pixelmatch(
+    refPng.data,
+    actPng.data,
+    diff.data,
+    width,
+    height,
+    { threshold: pixelThreshold }
+  );
+  const totalPixels = width * height;
+  const diffRatio = totalPixels === 0 ? 1 : diffPixels / totalPixels;
+  const passed = diffRatio <= maxDiffRatio;
+  ensureParent(outDiff);
+  writeFileSync4(outDiff, PNG.sync.write(diff));
+  const result = {
+    ...base,
+    identicalBytes,
+    width,
+    height,
+    diffRatio,
+    diffPixels,
+    totalPixels,
+    passed,
+    reason: passed ? identicalBytes ? "identical_bytes_allowed" : null : `diff_ratio_exceeded: ${(diffRatio * 100).toFixed(3)}% > ${(maxDiffRatio * 100).toFixed(3)}%`,
+    paths: { ...base.paths, diff: outDiff }
+  };
+  writeFileSync4(outJson, JSON.stringify(result, null, 2));
+  return result;
+}
+
+// src/commands/visual.ts
+async function runVisual(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadConfig(cwd);
+  let runId = options.runId;
+  if (!runId) {
+    runId = createRunId();
+  }
+  ensureDir(artifactsDir(runId, cwd));
+  const routes = selectRoutes(config.routes, options.routes);
+  const lines = [`Visual run: ${runId}`];
+  let ok = true;
+  for (const route of routes) {
+    const actualPath = screenshotPath(runId, route.name, cwd);
+    const referencePath = route.reference ? resolve4(cwd, route.reference) : "";
+    const outDir = visualDir(runId, route.name, cwd);
+    if (!route.reference) {
+      ok = false;
+      lines.push(`  \u2717 ${route.name}: no reference configured`);
+      compareImages({
+        name: route.name,
+        referencePath: "",
+        actualPath,
+        outputDir: outDir,
+        pixelThreshold: config.visual.pixelThreshold,
+        maxDiffRatio: config.visual.maxDiffRatio,
+        referenceKind: route.referenceKind,
+        rejectIdenticalBaseline: config.gates.rejectIdenticalBaseline
+      });
+      continue;
+    }
+    if (!existsSync6(actualPath)) {
+      ok = false;
+      lines.push(
+        `  \u2717 ${route.name}: missing actual screenshot (run capture first)`
+      );
+    }
+    const result = compareImages({
+      name: route.name,
+      referencePath,
+      actualPath,
+      outputDir: outDir,
+      pixelThreshold: config.visual.pixelThreshold,
+      maxDiffRatio: config.visual.maxDiffRatio,
+      referenceKind: route.referenceKind,
+      rejectIdenticalBaseline: config.gates.rejectIdenticalBaseline
+    });
+    if (!result.passed) ok = false;
+    const kindTag = `kind=${result.referenceKind}`;
+    const identicalTag = result.identicalBytes ? " identical" : "";
+    lines.push(
+      `  ${result.passed ? "\u2713" : "\u2717"} ${route.name}: diffRatio=${(result.diffRatio * 100).toFixed(3)}% (${kindTag}${identicalTag})${result.reason ? ` \u2014 ${result.reason}` : ""}`
+    );
+    lines.push(`    \u2192 ${result.paths.resultJson}`);
+  }
+  return { runId, ok, message: lines.join("\n") };
+}
+
+// src/lib/test-runner.ts
+import { spawn } from "child_process";
+import { writeFileSync as writeFileSync5 } from "fs";
+import { join as join8 } from "path";
+function runShell(command, cwd) {
+  return new Promise((resolve6) => {
+    const started = Date.now();
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolve6({
+        exitCode: 127,
+        stdout,
+        stderr,
+        durationMs: Date.now() - started
+      });
+    });
+    child.on("close", (code) => {
+      resolve6({
+        exitCode: code,
+        stdout,
+        stderr,
+        durationMs: Date.now() - started
+      });
+    });
+  });
+}
+async function runConfiguredTests(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const commands = [];
+  if (options.config.checks?.typecheck) {
+    commands.push({ name: "typecheck", command: options.config.checks.typecheck });
+  }
+  if (options.config.checks?.lint) {
+    commands.push({ name: "lint", command: options.config.checks.lint });
+  }
+  if (options.config.checks?.unit) {
+    commands.push({ name: "unit", command: options.config.checks.unit });
+  }
+  if (options.config.checks?.e2e) {
+    commands.push({ name: "e2e", command: options.config.checks.e2e });
+  }
+  commands.push({ name: "testCommand", command: options.config.testCommand });
+  const seen = /* @__PURE__ */ new Set();
+  const unique = commands.filter((c) => {
+    if (seen.has(c.command)) return false;
+    seen.add(c.command);
+    return true;
+  });
+  const results = [];
+  for (const item of unique) {
+    if (!item.command.trim()) {
+      results.push({
+        name: item.name,
+        command: item.command,
+        status: "FAIL",
+        exitCode: null,
+        durationMs: 0,
+        stdout: "",
+        stderr: "",
+        reason: "empty_command"
+      });
+      continue;
+    }
+    const run = await runShell(item.command, cwd);
+    const status = run.exitCode === 0 ? "PASS" : "FAIL";
+    results.push({
+      name: item.name,
+      command: item.command,
+      status,
+      exitCode: run.exitCode,
+      durationMs: run.durationMs,
+      stdout: run.stdout,
+      stderr: run.stderr,
+      reason: status === "FAIL" ? `exit_code_${run.exitCode ?? "null"}` : void 0
+    });
+  }
+  const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const suite = {
+    runId: options.runId,
+    results,
+    passed: results.every((r) => r.status === "PASS"),
+    startedAt,
+    finishedAt
+  };
+  const dir = ensureDir(artifactsDir(options.runId, cwd));
+  writeFileSync5(join8(dir, "test-result.json"), JSON.stringify(suite, null, 2));
+  return suite;
+}
+
+// src/commands/test.ts
+import { writeFileSync as writeFileSync6 } from "fs";
+import { join as join9 } from "path";
+async function runTestCommand(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadConfig(cwd);
+  const runId = options.runId ?? createRunId();
+  ensureDir(artifactsDir(runId, cwd));
+  writeFileSync6(join9(artifactsDir(runId, cwd), "run-id.txt"), runId);
+  const suite = await runConfiguredTests({ config, runId, cwd });
+  const lines = [
+    `Test run: ${runId}`,
+    ...suite.results.map(
+      (r) => `  ${r.status === "PASS" ? "\u2713" : "\u2717"} ${r.name} (${r.command}) exit=${r.exitCode} ${r.durationMs}ms`
+    ),
+    `Overall: ${suite.passed ? "PASS" : "FAIL"}`
+  ];
+  return { runId, ok: suite.passed, message: lines.join("\n") };
+}
+
+// src/commands/report.ts
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
+import { join as join12 } from "path";
+
+// src/lib/report-builder.ts
+import { existsSync as existsSync8, readFileSync as readFileSync5, readdirSync as readdirSync2, writeFileSync as writeFileSync7 } from "fs";
+import { join as join11 } from "path";
+
+// src/lib/acceptance.ts
+import { existsSync as existsSync7, readdirSync, readFileSync as readFileSync4, statSync } from "fs";
+import { join as join10, resolve as resolve5, sep as sep2 } from "path";
+var STATUS_SET = /* @__PURE__ */ new Set([
+  "PASS",
+  "FAIL",
+  "PENDING",
+  "SKIPPED",
+  "PARTIAL"
+]);
+function normalizeStatus(raw) {
+  const value = raw.trim().toUpperCase();
+  if (STATUS_SET.has(value)) {
+    return value;
+  }
+  return "PENDING";
+}
+function normalizeAcId(raw) {
+  const match = raw.trim().match(/AC-(\d+)/i);
+  const digits = match?.[1];
+  if (!digits) return raw.trim().toUpperCase();
+  return `AC-${digits.padStart(3, "0")}`;
+}
+function normalizeReqId(digits) {
+  return `REQ-${digits.padStart(3, "0")}`;
+}
+function parseAcceptanceMarkdown(markdown) {
+  const rows = [];
+  for (const line of markdown.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) continue;
+    if (/^\|\s*-+/.test(trimmed)) continue;
+    if (/AC\s*ID/i.test(trimmed) && /描述|Description/i.test(trimmed)) continue;
+    const parts = trimmed.replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+    if (parts.length < 2) continue;
+    const idRaw = parts[0];
+    if (!idRaw || !/^AC-\d+/i.test(idRaw)) continue;
+    const title = parts[1] ?? "";
+    const reqCell = parts[2] ?? "";
+    const verification = parts.length >= 5 ? parts[3] : void 0;
+    const reqMatches = [...reqCell.matchAll(/REQ-(\d+)/gi)].flatMap((m) => {
+      const digits = m[1];
+      return digits ? [normalizeReqId(digits)] : [];
+    });
+    const requirementId = reqMatches.length > 0 ? [...new Set(reqMatches)].join(", ") : void 0;
+    const statusCell = parts[parts.length - 1] ?? "PENDING";
+    const status = normalizeStatus(statusCell);
+    rows.push({
+      id: normalizeAcId(idRaw),
+      title,
+      ...requirementId ? { requirementId } : {},
+      ...verification ? { verification } : {},
+      status
+    });
+  }
+  return rows;
+}
+function deriveRequirements(acceptance) {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of acceptance) {
+    const reqIds = (row.requirementId ?? "").split(/[,，\s]+/).map((s) => s.trim()).filter((s) => /^REQ-\d+/i.test(s));
+    for (const raw of reqIds) {
+      const match = raw.match(/REQ-(\d+)/i);
+      const digits = match?.[1];
+      if (!digits) continue;
+      const id = normalizeReqId(digits);
+      const existing = map.get(id);
+      if (!existing) {
+        map.set(id, { id, title: id, status: row.status });
+        continue;
+      }
+      existing.status = mergeStatus(existing.status, row.status);
+    }
+  }
+  return [...map.values()];
+}
+function mergeStatus(a, b) {
+  if (a === "FAIL" || b === "FAIL") return "FAIL";
+  if (a === "PENDING" || b === "PENDING") return "PENDING";
+  if (a === "PARTIAL" || b === "PARTIAL") return "PARTIAL";
+  if (a === "SKIPPED" || b === "SKIPPED") return "SKIPPED";
+  return "PASS";
+}
+function isPathInside(parent, child) {
+  const root = resolve5(parent);
+  const target = resolve5(child);
+  return target === root || target.startsWith(root + sep2);
+}
+function findTaskDir(options) {
+  const tasksRoot = join10(options.cwd, ".frontend-precision", "tasks");
+  if (!existsSync7(tasksRoot)) return null;
+  if (options.taskId) {
+    if (!isSafeSlug(options.taskId)) {
+      return null;
+    }
+    const dir = join10(tasksRoot, options.taskId);
+    if (!existsSync7(dir) || !isPathInside(tasksRoot, dir)) {
+      return null;
+    }
+    return dir;
+  }
+  const entries = readdirSync(tasksRoot).filter((name) => isSafeSlug(name)).map((name) => {
+    const dir = join10(tasksRoot, name);
+    try {
+      const st = statSync(dir);
+      if (!st.isDirectory()) return null;
+      if (!isPathInside(tasksRoot, dir)) return null;
+      return { name, dir, mtime: st.mtimeMs };
+    } catch {
+      return null;
+    }
+  }).filter((e) => !!e).sort((a, b) => b.mtime - a.mtime);
+  if (options.runId) {
+    for (const entry of entries) {
+      const runIdPath = join10(entry.dir, ".run-id");
+      if (!existsSync7(runIdPath)) continue;
+      const saved = readFileSync4(runIdPath, "utf8").trim();
+      if (saved === options.runId && existsSync7(join10(entry.dir, "acceptance.md"))) {
+        return entry.dir;
+      }
+    }
+  }
+  for (const entry of entries) {
+    if (existsSync7(join10(entry.dir, "acceptance.md"))) {
+      return entry.dir;
+    }
+  }
+  return null;
+}
+function loadAcceptanceFromTask(options) {
+  const taskDir = findTaskDir(options);
+  if (!taskDir) {
+    return {
+      taskDir: null,
+      acceptance: [],
+      requirements: [],
+      codeChangeSummary: null
+    };
+  }
+  const acceptancePath = join10(taskDir, "acceptance.md");
+  const acceptance = existsSync7(acceptancePath) ? parseAcceptanceMarkdown(readFileSync4(acceptancePath, "utf8")) : [];
+  const summaryPath = join10(taskDir, "code-change-summary.md");
+  const codeChangeSummary = existsSync7(summaryPath) ? readFileSync4(summaryPath, "utf8") : null;
+  return {
+    taskDir,
+    acceptance,
+    requirements: deriveRequirements(acceptance),
+    codeChangeSummary
+  };
+}
+function evidenceHintsForRow(row) {
+  const v = `${row.verification ?? ""} ${row.title}`.toLowerCase();
+  const needsVisual = /visual|figma|像素|视觉/.test(v);
+  const needsUnitMention = /\bunit\b|单测|logic\.test/.test(v);
+  const needsTestPass = /playwright|e2e|frontend-precision test|typecheck|unit|单测|tsx --test/.test(
+    v
+  ) || needsUnitMention;
+  return { needsTestPass, needsVisual, needsUnitMention };
+}
+function evaluateAcceptanceEvidence(acceptance, options) {
+  const failures = [];
+  const unverified = [];
+  const testsPassed = Boolean(options.tests?.passed);
+  const testBlob = (options.tests?.results ?? []).map((r) => `${r.name} ${r.command} ${r.stdout} ${r.stderr}`).join("\n").toLowerCase();
+  for (const row of acceptance) {
+    if (row.status !== "PASS") continue;
+    const hints = evidenceHintsForRow(row);
+    const acToken = row.id.toLowerCase();
+    if (hints.needsTestPass) {
+      if (!options.tests) {
+        failures.push(
+          `acceptance:${row.id}: PASS without test evidence (tests_not_run)`
+        );
+        continue;
+      }
+      if (!testsPassed) {
+        failures.push(
+          `acceptance:${row.id}: PASS but testCommand failed`
+        );
+        continue;
+      }
+      if (hints.needsUnitMention && !testBlob.includes(acToken) && !/tokenDramaPreviewPlaylistLogic|playlistLogic|\.test\.ts|pass/.test(
+        testBlob
+      )) {
+        unverified.push(`acceptance_evidence_weak:${row.id}`);
+      }
+    }
+    if (hints.needsVisual) {
+      if (options.visualPassedNames.length === 0) {
+        failures.push(
+          `acceptance:${row.id}: PASS without visual evidence`
+        );
+      } else if (!options.hasFigmaVisualPass) {
+        failures.push(
+          `acceptance:${row.id}: PASS claims visual/Figma but no referenceKind=figma pass`
+        );
+      }
+    }
+  }
+  return { failures, unverified };
+}
+function evaluateAcceptanceGate(acceptance, options) {
+  const failures = [];
+  const unverified = [];
+  if (!options.requireAcceptance) {
+    return { failures, unverified };
+  }
+  if (acceptance.length === 0) {
+    failures.push(
+      "acceptance_missing: no AC rows found (pass --task-id or ensure .frontend-precision/tasks/*/acceptance.md)"
+    );
+    return { failures, unverified };
+  }
+  const pending = acceptance.filter((a) => a.status === "PENDING");
+  const failed = acceptance.filter((a) => a.status === "FAIL");
+  const partial = acceptance.filter((a) => a.status === "PARTIAL");
+  for (const row of failed) {
+    failures.push(`acceptance:${row.id}: FAIL \u2014 ${row.title}`);
+  }
+  if (options.requireAcceptanceAllPass) {
+    for (const row of pending) {
+      failures.push(`acceptance:${row.id}: PENDING \u2014 ${row.title}`);
+    }
+    for (const row of partial) {
+      failures.push(
+        `acceptance:${row.id}: PARTIAL \u2014 ${row.title} (requireAcceptanceAllPass)`
+      );
+    }
+  } else {
+    for (const row of pending) {
+      unverified.push(`acceptance_pending:${row.id}`);
+    }
+    for (const row of partial) {
+      unverified.push(`acceptance_partial:${row.id}`);
+    }
+  }
+  return { failures, unverified };
+}
+
+// src/lib/report-builder.ts
+function readJsonIfExists(path) {
+  if (!existsSync8(path)) return null;
+  try {
+    return JSON.parse(readFileSync5(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function collectVisualResults(runDir) {
+  const visualRoot = join11(runDir, "visual");
+  if (!existsSync8(visualRoot)) return [];
+  const results = [];
+  for (const name of readdirSync2(visualRoot)) {
+    const jsonPath = join11(visualRoot, name, "visual-result.json");
+    const data = readJsonIfExists(jsonPath);
+    if (data) results.push(data);
+  }
+  return results;
+}
+function collectScreenshots(runDir) {
+  const shotDir = join11(runDir, "screenshots");
+  if (!existsSync8(shotDir)) return [];
+  return readdirSync2(shotDir).filter((f) => f.endsWith(".png")).map((f) => join11(shotDir, f));
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function truncateLog(text, max = 4e3) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}
+\u2026(truncated)`;
+}
+function buildReport(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const runDir = artifactsDir(options.runId, cwd);
+  const capture = readJsonIfExists(
+    join11(runDir, "screenshots", "capture-meta.json")
+  );
+  const visual = collectVisualResults(runDir);
+  const tests = readJsonIfExists(
+    join11(runDir, "test-result.json")
+  );
+  const screenshots = collectScreenshots(runDir);
+  const gates = {
+    requireAcceptance: options.gates?.requireAcceptance ?? true,
+    requireAcceptanceAllPass: options.gates?.requireAcceptanceAllPass ?? true,
+    requireFigmaVisual: options.gates?.requireFigmaVisual ?? false,
+    rejectIdenticalBaseline: options.gates?.rejectIdenticalBaseline ?? true
+  };
+  const fromTask = loadAcceptanceFromTask({
+    cwd,
+    taskId: options.taskId,
+    runId: options.runId
+  });
+  function toAcceptanceStatus(status2) {
+    if (status2 === "BLOCKED") return "FAIL";
+    if (status2 === "PASS" || status2 === "FAIL" || status2 === "PENDING" || status2 === "SKIPPED" || status2 === "PARTIAL") {
+      return status2;
+    }
+    return "PENDING";
+  }
+  const acceptanceRows = options.acceptance && options.acceptance.length > 0 ? options.acceptance.map((a) => ({
+    id: a.id,
+    title: a.title,
+    requirementId: a.requirementId,
+    status: toAcceptanceStatus(a.status)
+  })) : fromTask.acceptance;
+  const requirementRows = options.requirements && options.requirements.length > 0 ? options.requirements.map((r) => ({
+    id: r.id,
+    title: r.title,
+    status: toAcceptanceStatus(r.status)
+  })) : fromTask.requirements;
+  const codeChangeSummary = options.codeChangeSummary ?? fromTask.codeChangeSummary ?? null;
+  const failures = [];
+  const unverified = [];
+  if (capture) {
+    for (const shot of capture.screenshots) {
+      if (!shot.ok) {
+        failures.push(
+          `capture:${shot.name}: ${shot.error ?? "failed"}${shot.url ? ` (${shot.url})` : ""}`
+        );
+      }
+    }
+  } else {
+    unverified.push("capture_not_run");
+  }
+  for (const v of visual) {
+    if (!v.passed) failures.push(`visual:${v.name}: ${v.reason ?? "failed"}`);
+    if (v.referenceKind === "regression") {
+      unverified.push(`figma_visual_not_proven:${v.name}`);
+    }
+    if (v.identicalBytes && v.referenceKind === "regression") {
+      unverified.push(`regression_identical:${v.name}`);
+    }
+  }
+  if (visual.length === 0) {
+    unverified.push("visual_not_run");
+  }
+  const hasFigmaVisualPass = visual.some(
+    (v) => v.passed && (v.referenceKind ?? "figma") === "figma" && !v.identicalBytes
+  );
+  if (gates.requireFigmaVisual && !hasFigmaVisualPass) {
+    failures.push(
+      "figma_visual_required: no passing referenceKind=figma visual (regression/self-baseline does not count)"
+    );
+  }
+  if (tests) {
+    for (const t of tests.results) {
+      if (t.status === "FAIL") {
+        failures.push(`test:${t.name}: ${t.reason ?? `exit ${t.exitCode}`}`);
+      }
+    }
+  } else {
+    unverified.push("tests_not_run");
+  }
+  const acGate = evaluateAcceptanceGate(acceptanceRows, {
+    requireAcceptance: gates.requireAcceptance,
+    requireAcceptanceAllPass: gates.requireAcceptanceAllPass
+  });
+  failures.push(...acGate.failures);
+  unverified.push(...acGate.unverified);
+  if (gates.requireAcceptance) {
+    const evidence = evaluateAcceptanceEvidence(acceptanceRows, {
+      tests,
+      visualPassedNames: visual.filter((v) => v.passed).map((v) => v.name),
+      hasFigmaVisualPass
+    });
+    failures.push(...evidence.failures);
+    unverified.push(...evidence.unverified);
+  }
+  let status = "PASS";
+  const fixAttempts = options.fixAttempts;
+  const maxFixAttempts = options.maxFixAttempts;
+  let blockedReason = options.blockedReason ?? null;
+  if (fixAttempts !== void 0 && maxFixAttempts !== void 0 && fixAttempts > maxFixAttempts) {
+    blockedReason = blockedReason ?? `fix_attempts_exceeded: ${fixAttempts} > maxFixAttempts=${maxFixAttempts}`;
+  }
+  if (blockedReason) {
+    status = "BLOCKED";
+    if (!failures.includes(blockedReason)) failures.push(blockedReason);
+  } else if (failures.length > 0) {
+    status = "FAIL";
+  } else if (unverified.length > 0) {
+    const hardUnverified = unverified.filter(
+      (u) => u === "capture_not_run" || u === "visual_not_run" || u === "tests_not_run" || u.startsWith("acceptance_pending:") || u.startsWith("acceptance_partial:")
+    );
+    if (hardUnverified.length > 0) {
+      status = "SKIPPED";
+    } else if (unverified.some((u) => u.startsWith("figma_visual_not_proven"))) {
+      status = "PASS";
+    } else {
+      status = "PASS";
+    }
+  }
+  const report = {
+    runId: options.runId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status,
+    summary: {
+      visualPassed: visual.filter((v) => v.passed).length,
+      visualFailed: visual.filter((v) => !v.passed).length,
+      visualSkipped: 0,
+      testsPassed: tests?.results.filter((r) => r.status === "PASS").length ?? 0,
+      testsFailed: tests?.results.filter((r) => r.status === "FAIL").length ?? 0,
+      capturePassed: capture?.screenshots.filter((s) => s.ok).length ?? 0,
+      captureFailed: capture?.screenshots.filter((s) => !s.ok).length ?? 0
+    },
+    requirements: requirementRows.map((r) => ({
+      id: r.id,
+      title: r.title,
+      status: r.status
+    })),
+    acceptance: acceptanceRows.map((a) => ({
+      id: a.id,
+      requirementId: a.requirementId,
+      title: a.title,
+      status: a.status
+    })),
+    capture,
+    visual,
+    tests,
+    failures,
+    unverified,
+    screenshots,
+    codeChangeSummary,
+    manualReview: [
+      "DONE \u4EC5\u5F53\uFF1Areport.status===PASS \u4E14 acceptance \u65E0 PENDING/PARTIAL/FAIL \u4E14\u65E0 figma_visual_not_proven\uFF08\u6216\u5DF2\u660E\u786E\u53EA\u8981 regression\uFF09",
+      "Review Figma vs screenshot for typography and spacing (pixel diff is not full design QA)",
+      "Confirm Loading / Error / Empty states if not covered by e2e",
+      "Confirm no secrets were committed"
+    ],
+    fixAttempts: options.fixAttempts,
+    maxFixAttempts: options.maxFixAttempts
+  };
+  const outDir = ensureDir(runDir);
+  writeFileSync7(join11(outDir, "report.json"), JSON.stringify(report, null, 2));
+  writeFileSync7(join11(outDir, "report.md"), renderMarkdown(report));
+  writeFileSync7(join11(outDir, "report.html"), renderHtml(report));
+  return report;
+}
+function renderMarkdown(report) {
+  const lines = [
+    `# Frontend Precision Report`,
+    "",
+    `- Run ID: \`${report.runId}\``,
+    `- Status: **${report.status}**`,
+    `- Generated: ${report.generatedAt}`,
+    "",
+    `## Summary`,
+    "",
+    `| Area | Passed | Failed |`,
+    `|---|---:|---:|`,
+    `| Capture | ${report.summary.capturePassed} | ${report.summary.captureFailed} |`,
+    `| Visual | ${report.summary.visualPassed} | ${report.summary.visualFailed} |`,
+    `| Tests | ${report.summary.testsPassed} | ${report.summary.testsFailed} |`,
+    ""
+  ];
+  if (report.failures.length) {
+    lines.push("## Failures", "");
+    for (const f of report.failures) lines.push(`- ${f}`);
+    lines.push("");
+  }
+  if (report.unverified.length) {
+    lines.push("## Unverified", "");
+    for (const u of report.unverified) lines.push(`- ${u}`);
+    lines.push("");
+  } else {
+    lines.push("## Unverified", "", "- (none)", "");
+  }
+  if (report.visual.length) {
+    lines.push("## Visual", "");
+    for (const v of report.visual) {
+      lines.push(
+        `- **${v.name}**: ${v.passed ? "PASS" : "FAIL"} (diffRatio=${(v.diffRatio * 100).toFixed(3)}%)${v.reason ? ` \u2014 ${v.reason}` : ""}`
+      );
+      if (v.paths.diff) lines.push(`  - Diff: \`${v.paths.diff}\``);
+      lines.push(`  - Reference: \`${v.paths.reference}\``);
+      lines.push(`  - Actual: \`${v.paths.actual}\``);
+    }
+    lines.push("");
+  }
+  if (report.tests) {
+    lines.push("## Tests", "");
+    for (const t of report.tests.results) {
+      lines.push(
+        `- **${t.name}**: ${t.status} (exit=${t.exitCode}, ${t.durationMs}ms)`
+      );
+      lines.push(`  - Command: \`${t.command}\``);
+      if (t.stdout?.trim()) {
+        lines.push("  - stdout:", "", "```", truncateLog(t.stdout).trimEnd(), "```", "");
+      }
+      if (t.stderr?.trim()) {
+        lines.push("  - stderr:", "", "```", truncateLog(t.stderr).trimEnd(), "```", "");
+      }
+    }
+    lines.push("");
+  }
+  if (report.requirements.length) {
+    lines.push("## Requirements", "");
+    for (const r of report.requirements) {
+      lines.push(`- ${r.id}: ${r.title} \u2014 ${r.status}`);
+    }
+    lines.push("");
+  }
+  if (report.acceptance.length) {
+    lines.push("## Acceptance Criteria", "");
+    for (const a of report.acceptance) {
+      lines.push(
+        `- ${a.id}${a.requirementId ? ` (${a.requirementId})` : ""}: ${a.title} \u2014 ${a.status}`
+      );
+    }
+    lines.push("");
+  }
+  if (report.codeChangeSummary) {
+    lines.push("## Code Change Summary", "", report.codeChangeSummary, "");
+  }
+  lines.push("## Manual Review", "");
+  for (const m of report.manualReview) lines.push(`- ${m}`);
+  lines.push("");
+  lines.push("## Screenshots", "");
+  if (report.screenshots.length) {
+    for (const s of report.screenshots) lines.push(`- \`${s}\``);
+  } else {
+    lines.push("- (none)");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderHtml(report) {
+  const statusColor = report.status === "PASS" ? "#067647" : report.status === "BLOCKED" ? "#b54708" : report.status === "SKIPPED" ? "#667085" : "#b42318";
+  const failureLis = report.failures.map((f) => `<li>${escapeHtml(f)}</li>`).join("");
+  const unverifiedLis = report.unverified.length ? report.unverified.map((u) => `<li>${escapeHtml(u)}</li>`).join("") : "<li>(none)</li>";
+  const screenshotLis = report.screenshots.length ? report.screenshots.map((s) => `<li><code>${escapeHtml(s)}</code></li>`).join("") : "<li>(none)</li>";
+  const visualRows = report.visual.map(
+    (v) => `<tr><td>${escapeHtml(v.name)}</td><td>${v.passed ? "PASS" : "FAIL"}</td><td>${(v.diffRatio * 100).toFixed(3)}%</td><td>${escapeHtml(v.reason ?? "")}</td><td><code>${escapeHtml(v.paths.diff ?? "")}</code></td></tr>`
+  ).join("");
+  const testRows = report.tests?.results.map((t) => {
+    const logs = [
+      t.stdout?.trim() ? `<details><summary>stdout</summary><pre>${escapeHtml(truncateLog(t.stdout))}</pre></details>` : "",
+      t.stderr?.trim() ? `<details><summary>stderr</summary><pre>${escapeHtml(truncateLog(t.stderr))}</pre></details>` : ""
+    ].filter(Boolean).join("");
+    return `<tr><td>${escapeHtml(t.name)}</td><td>${t.status}</td><td>${t.exitCode}</td><td>${t.durationMs}ms</td><td>${logs || "\u2014"}</td></tr>`;
+  }).join("") ?? "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Frontend Precision Report \u2014 ${escapeHtml(report.runId)}</title>
+  <style>
+    body{font-family:ui-sans-serif,system-ui,sans-serif;margin:2rem;color:#101828;background:#fff}
+    h1{font-size:1.5rem} table{border-collapse:collapse;width:100%;margin:1rem 0}
+    th,td{border:1px solid #e4e7ec;padding:.5rem .75rem;text-align:left;font-size:.875rem;vertical-align:top}
+    th{background:#f9fafb} .badge{display:inline-block;padding:.25rem .6rem;border-radius:999px;color:#fff;background:${statusColor};font-weight:600}
+    code{background:#f2f4f7;padding:.1rem .35rem;border-radius:4px}
+    pre{white-space:pre-wrap;background:#f2f4f7;padding:.75rem;border-radius:6px;max-height:240px;overflow:auto}
+  </style>
+</head>
+<body>
+  <h1>Frontend Precision Report</h1>
+  <p>Run: <code>${escapeHtml(report.runId)}</code></p>
+  <p>Status: <span class="badge">${escapeHtml(report.status)}</span></p>
+  <p>Generated: ${escapeHtml(report.generatedAt)}</p>
+  <h2>Failures</h2>
+  ${failureLis ? `<ul>${failureLis}</ul>` : "<p>None</p>"}
+  <h2>Unverified</h2>
+  <ul>${unverifiedLis}</ul>
+  <h2>Screenshots</h2>
+  <ul>${screenshotLis}</ul>
+  <h2>Visual</h2>
+  <table><thead><tr><th>Name</th><th>Status</th><th>Diff ratio</th><th>Reason</th><th>Diff</th></tr></thead><tbody>${visualRows || '<tr><td colspan="5">No visual results</td></tr>'}</tbody></table>
+  <h2>Tests</h2>
+  <table><thead><tr><th>Name</th><th>Status</th><th>Exit</th><th>Duration</th><th>Logs</th></tr></thead><tbody>${testRows || '<tr><td colspan="5">Tests not run</td></tr>'}</tbody></table>
+  <h2>Manual review</h2>
+  <ul>${report.manualReview.map((m) => `<li>${escapeHtml(m)}</li>`).join("")}</ul>
+</body>
+</html>`;
+}
+
+// src/commands/report.ts
+function runReport(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadConfig(cwd);
+  let runId = options.runId;
+  if (!runId) {
+    runId = createRunId();
+  }
+  const runDir = artifactsDir(runId, cwd);
+  if (!existsSync9(runDir)) {
+    return {
+      runId,
+      ok: false,
+      message: `Artifacts not found for run ${runId}. Run capture/visual/test first.`,
+      reportPath: ""
+    };
+  }
+  let codeChangeSummary = options.codeChangeSummary ?? null;
+  const summaryFile = join12(runDir, "code-change-summary.md");
+  if (!codeChangeSummary && existsSync9(summaryFile)) {
+    codeChangeSummary = readFileSync6(summaryFile, "utf8");
+  }
+  const report = buildReport({
+    runId,
+    cwd,
+    taskId: options.taskId ?? config.taskId,
+    codeChangeSummary,
+    fixAttempts: options.fixAttempts,
+    maxFixAttempts: config.maxFixAttempts,
+    blockedReason: options.blockedReason ?? null,
+    gates: config.gates
+  });
+  const reportPath = join12(runDir, "report.json");
+  const message = [
+    `Report: ${report.status}`,
+    `  JSON: ${reportPath}`,
+    `  MD:   ${join12(runDir, "report.md")}`,
+    `  HTML: ${join12(runDir, "report.html")}`,
+    report.acceptance.length ? `  Acceptance: ${report.acceptance.length} rows (${report.acceptance.filter((a) => a.status === "PASS").length} PASS / ${report.acceptance.filter((a) => a.status === "PENDING").length} PENDING)` : "  Acceptance: (none loaded)",
+    report.failures.length ? `Failures:
+${report.failures.map((f) => `  - ${f}`).join("\n")}` : "No failures recorded.",
+    report.unverified.length ? `Unverified:
+${report.unverified.map((u) => `  - ${u}`).join("\n")}` : ""
+  ].filter(Boolean).join("\n");
+  return {
+    runId,
+    ok: report.status === "PASS" && report.failures.length === 0,
+    message,
+    reportPath
+  };
+}
+
+// src/index.ts
+var program = new Command();
+program.name("frontend-precision").description(
+  "Cursor-first frontend precision toolkit (screenshot, visual diff, tests, reports)"
+).version("0.1.0");
+program.command("init").description("Initialize config, Cursor Skill, and rule templates").option("--force", "Overwrite existing files", false).action((opts) => {
+  const result = runInit({ force: opts.force });
+  console.log(result.messages.join("\n"));
+});
+program.command("doctor").description("Diagnose environment and project readiness").action(async () => {
+  const { checks, ok } = await runDoctor();
+  console.log(formatDoctor(checks));
+  process.exitCode = ok ? 0 : 1;
+});
+program.command("capture").description("Screenshot configured routes with Playwright").option("--run-id <id>", "Reuse or set run id").option("--route <name>", "Only capture named route (repeatable)", (v, acc) => {
+  acc.push(v);
+  return acc;
+}, []).action(async (opts) => {
+  try {
+    const result = await runCapture({
+      runId: opts.runId,
+      routes: opts.route.length ? opts.route : void 0
+    });
+    console.log(result.message);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (err) {
+    handleError(err);
+  }
+});
+program.command("visual").description("Compare screenshots against reference PNGs").requiredOption("--run-id <id>", "Run id from capture").option("--route <name>", "Only compare named route (repeatable)", (v, acc) => {
+  acc.push(v);
+  return acc;
+}, []).action(async (opts) => {
+  try {
+    const result = await runVisual({
+      runId: opts.runId,
+      routes: opts.route.length ? opts.route : void 0
+    });
+    console.log(result.message);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (err) {
+    handleError(err);
+  }
+});
+program.command("test").description("Run configured test commands and record results").option("--run-id <id>", "Attach results to an existing run id").action(async (opts) => {
+  try {
+    const result = await runTestCommand({ runId: opts.runId });
+    console.log(result.message);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (err) {
+    handleError(err);
+  }
+});
+program.command("report").description("Aggregate capture/visual/test into JSON/Markdown/HTML reports").requiredOption("--run-id <id>", "Run id to report").option("--task-id <id>", "Task folder under .frontend-precision/tasks/").option(
+  "--fix-attempts <n>",
+  "Current auto-fix attempt count",
+  (v) => Number(v)
+).option("--blocked <reason>", "Mark report as BLOCKED with reason").action(
+  (opts) => {
+    try {
+      const result = runReport({
+        runId: opts.runId,
+        taskId: opts.taskId,
+        fixAttempts: opts.fixAttempts,
+        blockedReason: opts.blocked
+      });
+      console.log(result.message);
+      process.exitCode = result.ok ? 0 : 1;
+    } catch (err) {
+      handleError(err);
+    }
+  }
+);
+function handleError(err) {
+  if (err instanceof ConfigError) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+program.parseAsync(process.argv).catch((err) => {
+  handleError(err);
+});
+//# sourceMappingURL=index.js.map