feat(audit+auth): /audit dashboard, email-OTP auth (CLI + dashboard), SES-backed re-audit reminders, unified pixel-craft design system

__tests__/api/audit-state.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { tryAcquireRun, releaseRun, getRunState } from "../../app/api/audit/_state";
+
+const LOCK_MAX_AGE_MS = 5 * 60_000;
+
+describe("audit run-lock state", () => {
+  beforeEach(() => {
+    // Belt-and-suspenders: tests share module state, so always reset first.
+    releaseRun();
+    vi.useRealTimers();
+  });
+
+  afterEach(() => {
+    releaseRun();
+    vi.useRealTimers();
+  });
+
+  it("the first tryAcquireRun wins and the second fails", () => {
+    expect(tryAcquireRun()).toBe(true);
+    expect(tryAcquireRun()).toBe(false);
+    expect(getRunState().running).toBe(true);
+  });
+
+  it("releaseRun lets the next caller acquire", () => {
+    expect(tryAcquireRun()).toBe(true);
+    releaseRun();
+    expect(tryAcquireRun()).toBe(true);
+  });
+
+  it("a lock older than LOCK_MAX_AGE_MS auto-expires", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-06T00:00:00Z"));
+    expect(tryAcquireRun()).toBe(true);
+    // Jump past the expiry window.
+    vi.setSystemTime(new Date(Date.now() + LOCK_MAX_AGE_MS + 1000));
+    expect(getRunState().running).toBe(false);
+    expect(tryAcquireRun()).toBe(true);
+  });
+
+  it("a lock younger than LOCK_MAX_AGE_MS stays held", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-06T00:00:00Z"));
+    expect(tryAcquireRun()).toBe(true);
+    vi.setSystemTime(new Date(Date.now() + LOCK_MAX_AGE_MS - 1000));
+    expect(getRunState().running).toBe(true);
+    expect(tryAcquireRun()).toBe(false);
+  });
+
+  it("releaseRun on an unheld lock is a no-op", () => {
+    releaseRun();
+    releaseRun();
+    expect(getRunState().running).toBe(false);
+  });
+});

__tests__/audit/archetypes.test.ts

@@ -0,0 +1,115 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import { ARCHETYPES, classifyAgent, pickArchetypeVariant } from "../../src/audit/archetypes";
+import type { AuditCount, AuditResult } from "../../src/audit/types";
+
+function mkRow(name: string, hits: number, opts: Partial<AuditCount> = {}): AuditCount {
+  return {
+    name,
+    source: "builtin",
+    category: "test",
+    severity: "warn",
+    hits,
+    projects: 1,
+    examples: [],
+    displayTitle: name,
+    impact: "",
+    enabledInConfig: false,
+    installHint: "",
+    ...opts,
+  };
+}
+
+function mkResult(rows: AuditCount[]): AuditResult {
+  return {
+    version: 2,
+    scannedAt: "2026-06-01T00:00:00.000Z",
+    scope: { cli: ["claude"], projects: "all", since: null },
+    transcripts: { scanned: 0, skipped: 0, errors: 0, durationMs: 0 },
+    results: rows,
+    totals: { hits: rows.reduce((s, r) => s + r.hits, 0), projectsWithHits: 0 },
+    projectsScanned: [],
+    eventsScanned: 0,
+    enabledBuiltinNames: [],
+  };
+}
+
+describe("classifyAgent", () => {
+  it("returns precision when there is no signal at all", () => {
+    const cls = classifyAgent(mkResult([]));
+    expect(cls.archetype).toBe("precision");
+    expect(cls.secondary).toBe(ARCHETYPES.precision.secondary);
+    expect(cls.totalSignal).toBe(0);
+  });
+
+  it("returns precision when every row is zero hits", () => {
+    const cls = classifyAgent(mkResult([mkRow("failproofai/block-rm-rf", 0)]));
+    expect(cls.archetype).toBe("precision");
+  });
+
+  it("returns goldfish for broad spread (≥5 archetypes, top-3 share < 60%)", () => {
+    // Hand-built spread: 8 archetypes hit roughly evenly so top-3 ≤ 60%.
+    const cls = classifyAgent(mkResult([
+      mkRow("failproofai/block-rm-rf", 5),               // cowboy   x2.0 = 10
+      mkRow("failproofai/block-read-outside-cwd", 8),    // explorer x1.2 = 9.6
+      mkRow("failproofai/warn-large-file-write", 9),     // ghost    x1.0 = 9
+      mkRow("redundant-cd-cwd", 9, { source: "audit-detector" }), // optimist x1.0 = 9
+      mkRow("failproofai/warn-repeated-tool-calls", 6),  // hammer   x1.5 = 9
+      mkRow("failproofai/reread-after-edit", 11),        // architect x0.8 = 8.8
+    ]));
+    expect(cls.archetype).toBe("goldfish");
+    // Secondary should be the strongest signal so the UI can hint at it.
+    expect(cls.secondary).toBeDefined();
+  });
+
+  it("promotes secondary when ≥40% of primary", () => {
+    const cls = classifyAgent(mkResult([
+      mkRow("failproofai/block-rm-rf", 5),         // cowboy x2.0 = 10
+      mkRow("failproofai/block-env-files", 6),     // explorer x1.5 = 9 (>= 40% of 10)
+    ]));
+    expect(cls.archetype).toBe("cowboy");
+    expect(cls.secondary).toBe("explorer");
+  });
+
+  it("falls back to authored secondary when runner-up < 40% of primary", () => {
+    const cls = classifyAgent(mkResult([
+      mkRow("failproofai/block-rm-rf", 10),        // cowboy x2.0 = 20
+      mkRow("failproofai/block-env-files", 1),     // explorer x1.5 = 1.5 (< 40% of 20)
+    ]));
+    expect(cls.archetype).toBe("cowboy");
+    expect(cls.secondary).toBe(ARCHETYPES.cowboy.secondary);
+  });
+
+  it("ignores rows whose policy name doesn't map to a signal", () => {
+    const cls = classifyAgent(mkResult([
+      mkRow("failproofai/some-future-unmapped-policy", 50),
+    ]));
+    // No mapped signal → still treated as the clean baseline.
+    expect(cls.archetype).toBe("precision");
+  });
+
+  it("weights detector hits by hits × weight", () => {
+    const cls = classifyAgent(mkResult([
+      mkRow("sleep-polling-loop", 5, { source: "audit-detector" }), // hammer x1.2 = 6
+    ]));
+    expect(cls.archetype).toBe("hammer");
+    expect(cls.weights.hammer).toBe(6);
+  });
+});
+
+describe("pickArchetypeVariant", () => {
+  it("returns the same variant for the same seed", () => {
+    const a = pickArchetypeVariant("optimist", "my-project");
+    const b = pickArchetypeVariant("optimist", "my-project");
+    expect(a).toEqual(b);
+  });
+
+  it("can return different variants for different seeds", () => {
+    const variants = new Set(
+      ["a", "b", "c", "d", "e", "f"].map((s) => pickArchetypeVariant("optimist", s).tagline),
+    );
+    // Out of 6 seeds we expect at least 2 distinct taglines — the picker
+    // would otherwise be effectively constant.
+    expect(variants.size).toBeGreaterThan(1);
+  });
+});

__tests__/audit/dashboard-cache.test.ts

@@ -0,0 +1,95 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  readDashboardCache,
+  writeDashboardCache,
+  isCacheStale,
+} from "../../src/audit/dashboard-cache";
+import type { AuditResult } from "../../src/audit/types";
+
+const FAKE_RESULT: AuditResult = {
+  version: 2,
+  scannedAt: "2026-05-26T00:00:00.000Z",
+  scope: { cli: ["claude"], projects: "all", since: null },
+  transcripts: { scanned: 5, skipped: 0, errors: 0, durationMs: 100 },
+  results: [],
+  totals: { hits: 0, projectsWithHits: 0 },
+  projectsScanned: ["/home/u/a", "/home/u/b"],
+  eventsScanned: 42,
+  enabledBuiltinNames: ["block-failproofai-commands"],
+};
+
+describe("dashboard cache", () => {
+  let tmpHome: string;
+  let originalHome: string | undefined;
+
+  beforeEach(() => {
+    // Redirect homedir() to a tmp directory by overriding HOME — os.homedir()
+    // reads it on every call on POSIX, so the dashboard-cache module sees
+    // our tmp path without needing module mocks.
+    tmpHome = mkdtempSync(join(tmpdir(), "fpa-audit-cache-test-"));
+    originalHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (originalHome === undefined) delete process.env.HOME;
+    else process.env.HOME = originalHome;
+    try { rmSync(tmpHome, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it("returns null when no cache file exists", () => {
+    expect(readDashboardCache()).toBeNull();
+  });
+
+  it("round-trips a written entry", () => {
+    writeDashboardCache({ since: "7d" }, FAKE_RESULT);
+    const entry = readDashboardCache();
+    expect(entry).not.toBeNull();
+    expect(entry?.params).toEqual({ since: "7d" });
+    expect(entry?.result.transcripts.scanned).toBe(5);
+    expect(entry?.result.projectsScanned).toEqual(["/home/u/a", "/home/u/b"]);
+    expect(typeof entry?.cachedAt).toBe("string");
+  });
+
+  it("writes mode 0600 on the file", () => {
+    writeDashboardCache({}, FAKE_RESULT);
+    const cachePath = join(tmpHome, ".failproofai", "audit-dashboard.json");
+    expect(existsSync(cachePath)).toBe(true);
+    const mode = statSync(cachePath).mode & 0o777;
+    // Some filesystems (FAT, etc.) can't honor mode bits perfectly — just
+    // assert no world-readable bit is set.
+    expect(mode & 0o004).toBe(0);
+  });
+
+  it("returns null for a corrupt JSON cache file", () => {
+    const dir = join(tmpHome, ".failproofai");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "audit-dashboard.json"), "{ not json", "utf-8");
+    expect(readDashboardCache()).toBeNull();
+  });
+
+  it("returns null when shape is wrong", () => {
+    const dir = join(tmpHome, ".failproofai");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "audit-dashboard.json"), JSON.stringify({ foo: 1 }), "utf-8");
+    expect(readDashboardCache()).toBeNull();
+  });
+
+  it("isCacheStale returns true past the threshold", () => {
+    const old = new Date(Date.now() - 60 * 60_000).toISOString(); // 1 hour ago
+    expect(isCacheStale(old, 30)).toBe(true);
+  });
+
+  it("isCacheStale returns false within the threshold", () => {
+    const recent = new Date(Date.now() - 10 * 60_000).toISOString(); // 10 min ago
+    expect(isCacheStale(recent, 30)).toBe(false);
+  });
+
+  it("isCacheStale treats unparseable timestamps as stale", () => {
+    expect(isCacheStale("not-a-date")).toBe(true);
+  });
+});

__tests__/audit/findings.test.ts

@@ -0,0 +1,119 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import { deriveFindings } from "../../src/audit/findings";
+import type { AuditCount, AuditResult } from "../../src/audit/types";
+
+function mkRow(name: string, hits: number, opts: Partial<AuditCount> = {}): AuditCount {
+  return {
+    name,
+    source: "builtin",
+    category: "test",
+    severity: "warn",
+    hits,
+    projects: 1,
+    examples: [],
+    displayTitle: name,
+    impact: "",
+    enabledInConfig: false,
+    installHint: "",
+    ...opts,
+  };
+}
+
+function mkResult(rows: AuditCount[], extras: Partial<AuditResult> = {}): AuditResult {
+  return {
+    version: 2,
+    scannedAt: "2026-06-01T00:00:00.000Z",
+    scope: { cli: ["claude"], projects: "all", since: null },
+    transcripts: { scanned: 0, skipped: 0, errors: 0, durationMs: 0 },
+    results: rows,
+    totals: { hits: rows.reduce((s, r) => s + r.hits, 0), projectsWithHits: 0 },
+    projectsScanned: [],
+    eventsScanned: 0,
+    enabledBuiltinNames: [],
+    ...extras,
+  };
+}
+
+describe("deriveFindings", () => {
+  it("ranks by hits desc and drops zero-hit rows", () => {
+    const cards = deriveFindings(mkResult([
+      mkRow("failproofai/block-rm-rf", 3),
+      mkRow("failproofai/block-sudo", 0),       // dropped
+      mkRow("failproofai/block-curl-pipe-sh", 9),
+    ]));
+    expect(cards.map((c) => c.sourceSlug)).toEqual([
+      "block-curl-pipe-sh",
+      "block-rm-rf",
+    ]);
+    expect(cards[0].num).toBe("01");
+    expect(cards[1].num).toBe("02");
+  });
+
+  it("remaps a detector to its prescribed-fix policy slug", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("redundant-cd-cwd", 4, { source: "audit-detector" }),
+    ]));
+    expect(card.sourceSlug).toBe("redundant-cd-cwd");
+    expect(card.policy).toBe("warn-repeated-tool-calls");
+    expect(card.fix.slug).toBe("warn-repeated-tool-calls");
+    expect(card.fix.install).toContain("warn-repeated-tool-calls");
+  });
+
+  it("attaches `alsoCoveredBy` when the detector mapping carries an extra policy", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("prefer-write-over-heredoc", 2, { source: "audit-detector" }),
+    ]));
+    expect(card.fix.alsoCoveredBy).toBe("block-secrets-write");
+  });
+
+  it("marks the fix as already-enabled when the policy is in the enabled set", () => {
+    const cards = deriveFindings(mkResult(
+      [mkRow("redundant-cd-cwd", 4, { source: "audit-detector" })],
+      { enabledBuiltinNames: ["warn-repeated-tool-calls"] },
+    ));
+    expect(cards[0].alreadyEnabled).toBe(true);
+  });
+
+  it("marks already-enabled when a builtin row reports enabledInConfig", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("failproofai/block-rm-rf", 1, { enabledInConfig: true }),
+    ]));
+    expect(card.alreadyEnabled).toBe(true);
+  });
+
+  it("falls back to displayTitle/impact copy when no hand-written copy exists", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("failproofai/some-unknown-policy", 2, {
+        displayTitle: "Some unknown policy",
+        impact: "explains the impact",
+      }),
+    ]));
+    expect(card.body).toBe("explains the impact");
+    expect(card.cost).toBe("explains the impact");
+  });
+
+  it("injects a placeholder evidence entry when no examples were captured", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("failproofai/block-rm-rf", 1, { examples: [] }),
+    ]));
+    expect(card.evidence).toHaveLength(1);
+    expect(card.evidence[0].kind).toBe("comment");
+  });
+
+  it("renders a relative-time lastSeen", () => {
+    // 2h ago
+    const iso = new Date(Date.now() - 2 * 60 * 60_000).toISOString();
+    const [card] = deriveFindings(mkResult([
+      mkRow("failproofai/block-rm-rf", 1, { lastSeen: iso }),
+    ]));
+    expect(card.lastSeen).toMatch(/^\d+h ago$/);
+  });
+
+  it("returns em-dash when lastSeen is missing", () => {
+    const [card] = deriveFindings(mkResult([
+      mkRow("failproofai/block-rm-rf", 1),
+    ]));
+    expect(card.lastSeen).toBe("—");
+  });
+});