@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/frames.ts

@@ -0,0 +1,195 @@
+// F312.2 / F312.3 — cut a recording into stills, and rank them.
+//
+// Frames are DERIVED. The video is the artifact; stills are cut on demand around a
+// moment the probe already named, because a 600-frame contact sheet is a disk bill
+// and a token bill that answers nothing. The default is sparse-everywhere plus
+// dense-where-it-matters.
+import { spawn } from 'node:child_process';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface Frame {
+  /** ms from the start of the recording. */
+  t: number;
+  /** Absolute path on disk. */
+  file: string;
+}
+
+export interface CutOptions {
+  /** Frames per second to extract. 4 is a good sparse pass; 15 for a burst. */
+  fps?: number;
+  /** Start of the window, ms. */
+  fromMs?: number;
+  /** Length of the window, ms. Omitted = to the end. */
+  durationMs?: number;
+}
+
+export interface CutResult {
+  frames: Frame[];
+  /** Set when frames could not be produced. The VIDEO is still fine — this must
+   *  never fail a run (F255.5's rule, inherited deliberately). */
+  unavailable?: string;
+}
+
+/** Is ffmpeg reachable at all? Answered once per call, cheaply. */
+export async function ffmpegAvailable(bin = 'ffmpeg'): Promise<boolean> {
+  return new Promise((resolve) => {
+    const p = spawn(bin, ['-version'], { stdio: 'ignore' });
+    p.on('error', () => resolve(false));
+    p.on('close', (code) => resolve(code === 0));
+  });
+}
+
+/**
+ * Cut `video` into PNGs in `outDir`.
+ *
+ * FAILS SOFT. ffmpeg missing, ffmpeg erroring, a zero-length recording — all
+ * return `unavailable` with a reason and an empty list. The caller still has the
+ * video, which is the thing a human can actually watch.
+ */
+export async function cutFrames(
+  videoPath: string,
+  outDir: string,
+  opts: CutOptions = {},
+  bin = 'ffmpeg',
+): Promise<CutResult> {
+  const fps = opts.fps ?? 4;
+  if (!(await ffmpegAvailable(bin))) {
+    return { frames: [], unavailable: `${bin} is not installed — video kept, no stills` };
+  }
+  await mkdir(outDir, { recursive: true });
+  const args: string[] = [];
+  // -ss BEFORE -i seeks by keyframe and is fast; accuracy inside a webm at 4fps is
+  // ample for pointing a human at a moment.
+  if (opts.fromMs != null) args.push('-ss', (opts.fromMs / 1000).toFixed(3));
+  args.push('-i', videoPath);
+  if (opts.durationMs != null) args.push('-t', (opts.durationMs / 1000).toFixed(3));
+  // NO `-vsync`. It was REMOVED in ffmpeg 9 (measured: "Unrecognized option
+  // 'vsync'", exit 8) and the fps filter already decides the output rate, so the
+  // flag was doing nothing even on the versions that still accepted it.
+  args.push('-vf', `fps=${fps}`, join(outDir, 'f-%05d.png'));
+
+  const code = await new Promise<number>((resolve) => {
+    const p = spawn(bin, args, { stdio: 'ignore' });
+    p.on('error', () => resolve(-1));
+    p.on('close', (c) => resolve(c ?? -1));
+  });
+  if (code !== 0) {
+    await rm(outDir, { recursive: true, force: true }).catch(() => {});
+    return { frames: [], unavailable: `ffmpeg exited ${code} — video kept, no stills` };
+  }
+  const names = (await readdir(outDir)).filter((n) => n.endsWith('.png')).sort();
+  if (names.length === 0) return { frames: [], unavailable: 'ffmpeg produced no frames' };
+
+  // F312.26 — EXIT 0 DOES NOT PROVE A PICTURE EXISTS. Asked for a window past the
+  // end of the recording, ffmpeg exits 0 and writes an EMPTY file. Reported by
+  // fd-sundhed, who found it BECAUSE they were told this file had no tests and so
+  // wrote a negative control instead of assuming coverage.
+  //
+  // The list was built from FILENAMES, so a zero-byte PNG became a Frame pointing
+  // at nothing and the failure surfaced much later — in a report, as a picture
+  // that will not render.
+  const sized = await Promise.all(
+    names.map(async (n) => {
+      const file = join(outDir, n);
+      try {
+        return { n, file, bytes: (await stat(file)).size };
+      } catch {
+        return { n, file, bytes: 0 };
+      }
+    }),
+  );
+  const real = sized.filter((f) => f.bytes > 0);
+  if (real.length === 0) {
+    // NOT an empty frame list: "the video had nothing in it" and "every file
+    // ffmpeg wrote was empty" are different facts, and only one is about the video.
+    return {
+      frames: [],
+      unavailable: `ffmpeg wrote ${names.length} empty file(s) at exit 0 — the window is probably past the end of the recording`,
+    };
+  }
+
+  const base = opts.fromMs ?? 0;
+  // The Nth extracted frame sits at N/fps into the window — the timestamp is
+  // RECONSTRUCTED, not read, so it maps onto the probe's timeline exactly.
+  // INDEXED OVER THE SURVIVING frames, and that ordering matters: numbering them
+  // before dropping the empties would shift every timestamp after a gap.
+  return {
+    frames: real.map((f, i) => ({ t: Math.round(base + (i * 1000) / fps), file: f.file })),
+  };
+}
+
+/**
+ * The frame nearest a moment — how a probe finding becomes a picture.
+ *
+ * F312.26 — AND IT REFUSES A MOMENT IT DOES NOT COVER. This used to return the
+ * nearest frame however far away it was, so asking about a second outside the
+ * recording handed back the first or last picture with nothing saying it was
+ * minutes off. A still from another minute, presented as the moment the defect
+ * happened, is a wrong answer that looks right.
+ *
+ * `toleranceMs` DEFAULTS to the frame spacing plus a little, derived from the
+ * frames themselves — so a caller asking about a moment inside the recording is
+ * unaffected, and only the out-of-range question changes its answer. fd-sundhed
+ * refused the same guess in their own build: "der gættes ikke på nærmeste frame".
+ */
+export function frameAt(frames: Frame[], tMs: number, toleranceMs?: number): Frame | null {
+  if (frames.length === 0) return null;
+  let best = frames[0]!;
+  for (const f of frames) if (Math.abs(f.t - tMs) < Math.abs(best.t - tMs)) best = f;
+
+  // The spacing is what the caller implicitly accepted by choosing an fps: a
+  // moment between two frames is always within half a step of one of them.
+  const spacing =
+    frames.length > 1
+      ? Math.abs(frames[1]!.t - frames[0]!.t)
+      : 1000;
+  const tolerance = toleranceMs ?? spacing * 2;
+  return Math.abs(best.t - tMs) <= tolerance ? best : null;
+}
+
+export interface DiffPoint {
+  t: number;
+  /** Fraction of pixels that changed between this frame and the one before. */
+  changed: number;
+}
+
+/**
+ * Consecutive-frame difference — the SECOND ranker, for defects with no numeric
+ * signal (a flash, a repaint, a colour flicker).
+ *
+ * It is deliberately dumb and deliberately free. It cannot invent a finding; it
+ * can only over-report, which a human dismisses in a second. That is the opposite
+ * failure mode from asking a model to "find the flicker" in 600 near-identical
+ * frames, which answers with the same confidence whether or not one is there.
+ */
+export async function diffTimeline(
+  frames: Frame[],
+  load: (file: string) => Promise<{ data: Buffer; width: number; height: number } | null>,
+  compare: (a: Buffer, b: Buffer, w: number, h: number) => number,
+): Promise<DiffPoint[]> {
+  const out: DiffPoint[] = [];
+  let prev: { data: Buffer; width: number; height: number } | null = null;
+  for (const f of frames) {
+    const img = await load(f.file);
+    if (!img) {
+      prev = null;
+      continue;
+    }
+    if (prev && prev.width === img.width && prev.height === img.height) {
+      const n = compare(prev.data, img.data, img.width, img.height);
+      out.push({ t: f.t, changed: n / (img.width * img.height) });
+    }
+    prev = img;
+  }
+  return out;
+}
+
+/** The busiest moments, worst first. Zero is a valid answer and is returned as
+ *  zero — never padded to look useful. */
+export function busiest(points: DiffPoint[], minChanged = 0.02, limit = 8): DiffPoint[] {
+  return points
+    .filter((p) => p.changed >= minChanged)
+    .sort((a, b) => b.changed - a.changed)
+    .slice(0, limit);
+}

package/src/gate.ts

@@ -0,0 +1,123 @@
+// F074.7 — Lens gate: strict data-testid enforcement + verdict→action.
+//
+// The verification CONTRACT made strict. F073 Auto Review (and the cardmem
+// audit) consume this:
+//
+//   1. checkAnchors() — every element-mode surface in a project's manifest
+//      must anchor on a [data-testid] that ACTUALLY EXISTS in the source
+//      (cross-checked against the testid inventory). A surface that points at
+//      a non-existent testid is a BROKEN ANCHOR (hard gate fail) — "a visual
+//      AC cannot pass without its anchor". A surface that uses a CSS/text
+//      selector instead of a testid is a CONVENTION WARNING (migrate it).
+//
+//   2. decideVerdict() — fold the catalogue result + the anchor report into a
+//      single green/red verdict + an action. F073's review loop OWNS the
+//      execution (auto-merge the PR on green; open a GitHub issue + ping
+//      Discord on red) since it holds the PR + dispatch context; this module
+//      produces the decision it acts on.
+
+import type { LensManifest } from './manifest.ts';
+
+/** Pull the testid out of a selector like [data-testid="board-column-ready"]. */
+export function testidFromSelector(selector: string | undefined): string | null {
+  if (!selector) return null;
+  const m = selector.match(/\[data-testid\s*=\s*["']?([^"'\]]+)["']?\]/);
+  return m ? m[1]! : null;
+}
+
+export type AnchorStatus = 'testid-ok' | 'testid-missing' | 'not-testid' | 'n/a';
+
+export interface AnchorCheck {
+  surface: string;
+  mode: string;
+  selector: string | null;
+  status: AnchorStatus;
+  testid: string | null;
+}
+
+export interface AnchorReport {
+  anchors: AnchorCheck[];
+  /** Element surfaces pointing at a testid that doesn't exist in source — hard. */
+  broken: AnchorCheck[];
+  /** Element surfaces using a non-testid selector — convention warning. */
+  warnings: AnchorCheck[];
+}
+
+/** Cross-check a manifest's element surfaces against the repo's testid inventory. */
+export function checkAnchors(manifest: LensManifest, inventoryTestIds: string[]): AnchorReport {
+  const present = new Set(inventoryTestIds);
+  const anchors: AnchorCheck[] = manifest.surfaces.map((s) => {
+    if (s.mode !== 'element') {
+      return { surface: s.name, mode: s.mode ?? 'viewport', selector: s.selector ?? null, status: 'n/a' as const, testid: null };
+    }
+    const testid = testidFromSelector(s.selector);
+    if (!testid) {
+      return { surface: s.name, mode: 'element', selector: s.selector ?? null, status: 'not-testid' as const, testid: null };
+    }
+    return {
+      surface: s.name,
+      mode: 'element',
+      selector: s.selector ?? null,
+      status: present.has(testid) ? ('testid-ok' as const) : ('testid-missing' as const),
+      testid,
+    };
+  });
+  return {
+    anchors,
+    broken: anchors.filter((a) => a.status === 'testid-missing'),
+    warnings: anchors.filter((a) => a.status === 'not-testid'),
+  };
+}
+
+export interface CatalogueLike {
+  total: number;
+  passed: number;
+  failed: number;
+  surfaces: Array<{ name: string; status: string; reason?: string | null }>;
+}
+
+export type Verdict = 'green' | 'red';
+export type GateAction = 'allow' | 'block';
+
+export interface GateVerdict {
+  verdict: Verdict;
+  action: GateAction;
+  reasons: string[];
+  failed_surfaces: Array<{ name: string; status: string; reason?: string | null }>;
+  broken_anchors: AnchorCheck[];
+  convention_warnings: AnchorCheck[];
+  /** A one-line summary for an issue title / Discord ping / audit row. */
+  summary: string;
+}
+
+/** Fold catalogue verdicts + the anchor report into a single gate decision.
+ *  RED (block) when any surface failed/errored OR any anchor is broken.
+ *  Convention warnings (non-testid element selectors) do NOT block on their
+ *  own — they're surfaced for migration but don't fail a working AC. */
+export function decideVerdict(catalogue: CatalogueLike, anchors: AnchorReport): GateVerdict {
+  const failed = catalogue.surfaces.filter((s) => s.status === 'fail' || s.status === 'error');
+  const reasons: string[] = [];
+  if (failed.length) reasons.push(`${failed.length}/${catalogue.total} surface(s) failed: ${failed.map((f) => f.name).join(', ')}`);
+  if (anchors.broken.length) {
+    reasons.push(`${anchors.broken.length} broken testid anchor(s): ${anchors.broken.map((a) => `${a.surface}→${a.testid}`).join(', ')}`);
+  }
+  if (anchors.warnings.length) {
+    reasons.push(`${anchors.warnings.length} surface(s) not using a [data-testid] anchor (convention): ${anchors.warnings.map((a) => a.surface).join(', ')}`);
+  }
+
+  const isRed = failed.length > 0 || anchors.broken.length > 0;
+  const verdict: Verdict = isRed ? 'red' : 'green';
+  const summary = isRed
+    ? `Lens gate RED — ${[failed.length ? `${failed.length} failed` : '', anchors.broken.length ? `${anchors.broken.length} broken anchor(s)` : ''].filter(Boolean).join(' + ')}`
+    : `Lens gate GREEN — ${catalogue.passed}/${catalogue.total} surface(s) pass`;
+
+  return {
+    verdict,
+    action: isRed ? 'block' : 'allow',
+    reasons,
+    failed_surfaces: failed,
+    broken_anchors: anchors.broken,
+    convention_warnings: anchors.warnings,
+    summary,
+  };
+}

package/src/http.ts

@@ -0,0 +1,175 @@
+// F074.5 — Lens HTTP surface (daemon /lens/*).
+//
+// Thin Hono router over the service layer. The REST surface beneath the MCP
+// tools: CLI, CI, the SPA dashboard (F074.8), and any agent that prefers HTTP
+// all hit these. Artifact bytes are served here too, so an <img> in the
+// dashboard points straight at the daemon.
+
+import { Hono } from 'hono';
+import { setSandboxResolver } from './sandbox.ts';
+import { registerDaemonRoutes } from './daemon-routes.ts';
+import {
+  lensCapture,
+  lensVerify,
+  lensCaptureCatalogue,
+  lensApproveBaseline,
+  lensClearBaseline,
+  lensListRuns,
+  lensListBaselines,
+  lensListBaselineVersions,
+  lensRevertBaseline,
+  lensBillboard,
+  lensRunFlow,
+  runFlatFlow,
+  isFlatFlowBody,
+  lensRunManuscript,
+  lensListFlowRuns,
+  type LensDeps,
+  promoteEvidence,
+  lensExport,
+} from './service.ts';
+import { drainUploads, uploadStats } from './artifact-uploads.ts';
+import { backfillFromDisk } from './artifact-backfill.ts';
+import { artifactContentType } from './storage.ts';
+
+export function createLensRouter(deps: LensDeps): Hono {
+  const r = new Hono();
+  // lens F001.5 — the daemon's sandbox is injected, never copied (sandbox.ts).
+  if (deps.resolveSandboxedPath) setSandboxResolver(deps.resolveSandboxedPath);
+  // lens F001.5 — the routes that used to be registered one by one in the
+  // daemon's index.ts. First, so their specific paths win as they did there.
+  registerDaemonRoutes(r, deps);
+
+  const handle = <T>(fn: (body: T) => Promise<unknown> | unknown) => async (c: import('hono').Context) => {
+    const body = (await c.req.json().catch(() => ({}))) as T;
+    try {
+      const result = await fn(body);
+      return c.json({ ok: true, ...(result as object) });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  };
+
+  r.post('/capture', handle((body) => lensCapture(deps, body as Parameters<typeof lensCapture>[1])));
+  r.post('/verify', handle((body) => lensVerify(deps, body as Parameters<typeof lensVerify>[1])));
+  // F074.63 — the export verb beside capture. Same pipeline, one terminal call
+  // changed: a document whose text a designer can still edit, instead of a
+  // picture of one.
+  r.post('/export', handle((body) => lensExport(deps, body as Parameters<typeof lensExport>[1])));
+  r.post('/capture-catalogue', handle((body) => lensCaptureCatalogue(deps, body as Parameters<typeof lensCaptureCatalogue>[1])));
+  r.post('/baseline/approve', handle((body) => lensApproveBaseline(deps, body as Parameters<typeof lensApproveBaseline>[1])));
+  r.post('/baseline/clear', handle((body) => lensClearBaseline(deps, body as Parameters<typeof lensClearBaseline>[1])));
+  // F094.3 — baseline version history + revert.
+  r.post('/baseline/revert', handle((body) => lensRevertBaseline(deps, body as Parameters<typeof lensRevertBaseline>[1])));
+
+  // F082 — run an E2E manuscript flow + list past flow runs. F074.24: a flat cloud
+  // FlowRequest (from @broberg/lens-client) is dispatched to runFlatFlow (engine-hosted,
+  // returns the native cloud FlowResult); the native {project, flow} body → lensRunFlow.
+  r.post('/flow', handle((body) => (isFlatFlowBody(body)
+    ? runFlatFlow(deps, body)
+    : lensRunFlow(deps, body as Parameters<typeof lensRunFlow>[1]))));
+  r.post('/manuscript', handle((body) => lensRunManuscript(deps, body as Parameters<typeof lensRunManuscript>[1])));
+
+  // F272.2 — copy a flow run's step stills into the project artifact store, so the
+  // evidence an AC cites survives this machine.
+  r.post('/promote-evidence', handle((body) => promoteEvidence(deps, body as Parameters<typeof promoteEvidence>[1])));
+
+  // F276.1/F276.4 — the upload queue: what it holds, and one drain pass.
+  r.get('/uploads', (c) => c.json({ ok: true, ...uploadStats(deps.db) }));
+  r.post('/uploads/drain', handle(async (body) => {
+    const b = (body ?? {}) as { batch?: number };
+    return drainUploads(deps.db, deps.storage, deps.cloud?.() ?? null, { batch: b.batch });
+  }));
+  // F276.4 — enqueue everything already on disk. Idempotent: artifact_key is the
+  // primary key, so re-running adds nothing and re-uploads nothing.
+  r.post('/uploads/backfill', handle(async () => backfillFromDisk(deps)));
+
+  r.get('/flow-runs', (c) => {
+    const project = c.req.query('project');
+    if (!project) return c.json({ ok: false, error: 'project query param required' }, 400);
+    try {
+      const out = lensListFlowRuns(deps, {
+        project,
+        flow_name: c.req.query('flow_name'),
+        status: c.req.query('status'),
+        limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+      });
+      return c.json({ ok: true, ...out });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  r.get('/runs', (c) => {
+    const project = c.req.query('project');
+    if (!project) return c.json({ ok: false, error: 'project query param required' }, 400);
+    try {
+      const out = lensListRuns(deps, {
+        project,
+        status: c.req.query('status'),
+        surface_key: c.req.query('surface_key'),
+        limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+      });
+      return c.json({ ok: true, ...out });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  r.get('/baselines', (c) => {
+    const project = c.req.query('project');
+    if (!project) return c.json({ ok: false, error: 'project query param required' }, 400);
+    try {
+      return c.json({ ok: true, ...lensListBaselines(deps, project) });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F094.3 — the approved-version history for one surface (newest first).
+  r.get('/baseline/versions', (c) => {
+    const project = c.req.query('project');
+    const baseline_key = c.req.query('key');
+    if (!project || !baseline_key) {
+      return c.json({ ok: false, error: 'project + key query params required' }, 400);
+    }
+    try {
+      return c.json({ ok: true, ...lensListBaselineVersions(deps, { project, baseline_key }) });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F074.8 — billboard contact-sheet: a Sharp grid of recent run thumbnails.
+  r.get('/billboard', async (c) => {
+    const project = c.req.query('project');
+    if (!project) return c.json({ ok: false, error: 'project query param required' }, 400);
+    try {
+      const png = await lensBillboard(deps, project, c.req.query('limit') ? Number(c.req.query('limit')) : undefined);
+      return new Response(new Uint8Array(png), { headers: { 'Content-Type': 'image/png', 'Cache-Control': 'no-store' } });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // Serve artifact bytes (screenshots, diffs, baselines) from the storage
+  // adapter. The dashboard <img src> + cc point here.
+  r.get('/artifact', async (c) => {
+    const key = c.req.query('key');
+    if (!key) return c.json({ ok: false, error: 'key query param required' }, 400);
+    const bytes = await deps.storage.get(key);
+    if (!bytes) return c.json({ ok: false, error: 'artifact not found' }, 404);
+    return new Response(new Uint8Array(bytes), {
+      headers: {
+        // F074.63 — one map, keyed on the extension. The two-branch guess this
+        // replaces defaulted everything-not-.webm to image/png, so a PDF export
+        // arrived at the designer labelled as an image and simply would not open
+        // — a silent failure indistinguishable from the feature not existing.
+        'Content-Type': artifactContentType(key),
+        'Cache-Control': 'private, max-age=31536000, immutable',
+      },
+    });
+  });
+
+  return r;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// @broberg/lens-daemon — the cardmem daemon's Lens module as a package (lens F001.5).
+//
+// The daemon mounts two routers and runs the Lens schema in its own DB:
+//   ensureLensSchema(db)                       inside getDb()'s schema transaction
+//   app.route('/lens', createLensRouter(deps)) every /lens/* route (incl. the ones
+//                                              that used to live in index.ts)
+//   app.route('/mcp',  createLensMcpRouter(deps))
+// deps.resolveSandboxedPath MUST be the daemon's own sandbox check.
+export { createLensRouter } from './http.ts';
+export { createLensMcpRouter } from './mcp.ts';
+export { createStorage } from './storage.ts';
+export { ensureLensSchema } from './schema.ts';
+export type { LensRunRow, LensBaselineRow, LensBaselineVersionRow, LensFlowRunRow } from './schema.ts';
+export type { LensDeps } from './service.ts';
+export { durabilityOf, type EvidenceDurability } from './durability.ts';
+export { setSandboxResolver, type SandboxResolver } from './sandbox.ts';
+// Lifecycle the daemon owns: provision Chromium at boot, drain the evidence
+// upload queue on its timer, close the warm browser on shutdown.
+export { ensureChromium } from './ensure-chromium.ts';
+export { drainUploads } from './artifact-uploads.ts';
+export { closeBrowser } from './browser.ts';
+
+/** The version the daemon reports on /health as {lens:{source, version}} (cardmem #38390). */
+export { version as LENS_DAEMON_VERSION } from '../package.json';