@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/flow-store.ts

@@ -0,0 +1,207 @@
+// F082 — Lens flow-run persistence.
+//
+// Mirrors store.ts (captures): per-step screenshot BYTES go to the storage
+// adapter; the run report (one row, per-step status in steps_json) goes to the
+// daemon's SQLite. Hard-scoped to project_slug.
+
+import type { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+import type { LensFlowRunRow } from './schema.ts';
+import { artifactKeys, type LensStorage } from './storage.ts';
+import { enqueueArtifacts } from './artifact-uploads.ts';
+import type { FlowResult, FailedResponse } from './flow.ts';
+
+/** A per-step entry as persisted (screenshot bytes already offloaded to an
+ *  artifact key — null when the step took no shot). */
+export interface StoredFlowStep {
+  index: number;
+  type: string;
+  label: string;
+  status: 'pass' | 'fail' | 'skip';
+  testid: string | null;
+  detail: string | null;
+  artifact_key: string | null;
+  /** F074.29 — set when the step failed because the PROBE was broken (an assert
+   *  body that cannot compile, or one that threw every time) rather than because
+   *  the app was wrong. `status` stays 'fail' either way, so no consumer can
+   *  accidentally stop counting it. */
+  fault?: 'instrument';
+  /** F074.49 — the failed HTTP responses the app gave around this step, so the
+   *  report carries the ANSWER and not only the assertion. Persisted, because a
+   *  flow-run is read back from this row long after the browser is gone: a field
+   *  produced in flow.ts but not written here reaches nobody. */
+  network?: FailedResponse[];
+  /** F126.7 — the composition report for a screenshot step. Persisted for the
+   *  same reason `network` is: a flow-run is read back from this row long after
+   *  the browser is gone, and a field produced in flow.ts but not written here
+   *  reaches nobody. xrt81 (#21050) measured the cost of the string-only version
+   *  — a caller fixed the one finding it was shown, went green, and the rest were
+   *  silently recorded as resolved. */
+  critic?: unknown;
+  /** F213.12 — how long after the last navigation this step ran. THE THIRD TIME
+   *  this file's rule caught someone, and this time it was the author of the
+   *  rule's most recent entry: F213.11 produced the field in flow.ts, proved it
+   *  against `runFlow`'s return value, and never wrote it here — so the number
+   *  reached nobody through the MCP, which is the ONLY surface the session that
+   *  asked for it can read. Measured on the wire, not reasoned about.
+   *
+   *  UNDEFINED means the step never ran (skip). ZERO is a real, common reading —
+   *  a `goto` runs at 0ms after its own navigation — so this must be written on
+   *  a `typeof === 'number'` test, never on truthiness. Every other optional
+   *  field here is correctly gated on truthiness; copying that pattern for a
+   *  number silently reports the strongest evidence of an early write as
+   *  "not measured". */
+  ms_after_navigation?: number;
+  /** F213.13 — how long the step itself took. Written here IN THE SAME COMMIT as
+   *  the producer, which is the entire lesson of F213.12 one card earlier: a field
+   *  that exists only in flow.ts reaches nobody. Same `typeof` gate — a step that
+   *  completed in under a millisecond reports 0, and that is a reading, not a gap. */
+  ms_step_duration?: number;
+}
+
+export async function recordFlowRun(
+  db: Database,
+  storage: LensStorage,
+  projectSlug: string,
+  result: FlowResult,
+  /** F074.36 — which credential the run used, or why it had none. Persisted so a
+   *  past GREEN run can still be asked "were you even logged in?". */
+  auth?: { source: string; adapter: string | null; note?: string },
+): Promise<LensFlowRunRow> {
+  const id = randomUUID();
+  const now = Date.now();
+
+  const storedSteps: StoredFlowStep[] = [];
+  for (const s of result.steps) {
+    let artifactKey: string | null = null;
+    if (s.screenshot) {
+      artifactKey = artifactKeys.flowStep(projectSlug, id, s.index);
+      await storage.put(artifactKey, s.screenshot);
+    }
+    storedSteps.push({
+      index: s.index,
+      type: s.type,
+      label: s.label,
+      status: s.status,
+      testid: s.testid,
+      detail: s.detail,
+      artifact_key: artifactKey,
+      ...(s.fault ? { fault: s.fault } : {}),
+      ...(s.network?.length ? { network: s.network } : {}),
+      ...(s.critic ? { critic: s.critic } : {}),
+      // `typeof === 'number'`, NOT truthiness — 0 is the reading that matters most.
+      ...(typeof s.ms_after_navigation === 'number' ? { ms_after_navigation: s.ms_after_navigation } : {}),
+      ...(typeof s.ms_step_duration === 'number' ? { ms_step_duration: s.ms_step_duration } : {}),
+    });
+  }
+
+  // F255.5 — store the run's recording next to its step stills, under the same
+  // flow-run prefix so both are cleaned up together.
+  let videoKey: string | null = null;
+  if (result.video && result.video.length > 0) {
+    videoKey = artifactKeys.flowVideo(projectSlug, id);
+    await storage.put(videoKey, result.video);
+  }
+
+  const row: LensFlowRunRow = {
+    id,
+    project_slug: projectSlug,
+    flow_name: result.name,
+    status: result.status,
+    failed_at: result.failed_at,
+    reason: result.reason,
+    steps_json: JSON.stringify(storedSteps),
+    step_count: storedSteps.length,
+    duration_ms: result.duration_ms,
+    created_at: now,
+    video_key: videoKey,
+    build: result.build ?? null,
+    final_url: result.final_url ?? null,
+    // F074.59 — which motion state the run executed under. Absent on an older row.
+    reduced_motion: result.reduced_motion ?? null,
+    // F272.2 — WHERE the bytes above actually went, read off the storage adapter
+    // that just wrote them rather than from config at read time. This is the only
+    // moment the answer is certainly true.
+    artifact_backend: storage.backend,
+    // Only {source, adapter, note} — never the credential object itself. The
+    // caller already knows what it passed, and echoing statePath/url back into
+    // every report is noise in a surface many sessions read.
+    auth_json: auth
+      ? JSON.stringify({
+          source: auth.source,
+          adapter: auth.adapter,
+          ...(auth.note ? { note: auth.note } : {}),
+          // F074.36 — the measured verdict, not the intent: "a credential was
+          // configured" and "a credential can reach this host" are different
+          // facts, and only the second one means anything.
+          ...(result.auth_reach ? { reach: result.auth_reach } : {}),
+        })
+      : null,
+    // F074.99 — the run-level findings, persisted for the same reason `network`
+    // and `critic` above are: a flow-run is read back from this row long after
+    // the browser is gone. ALWAYS written, even when empty — '{}' means the run
+    // looked and found nothing, and NULL means the row predates the column. Both
+    // findings were produced in flow.ts and written nowhere until fd-sundhed
+    // measured it from a consumer's seat: correct instrument, nobody told.
+    findings_json: JSON.stringify({
+      ...(result.password_in_url ? { password_in_url: result.password_in_url } : {}),
+      ...(result.not_listening ? { not_listening: result.not_listening } : {}),
+    }),
+  };
+
+  db.prepare(
+    `INSERT INTO lens_flow_runs (
+      id, project_slug, flow_name, status, failed_at, reason,
+      steps_json, step_count, duration_ms, created_at, video_key, build,
+      final_url, auth_json, reduced_motion, artifact_backend, findings_json
+    ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+  ).run(
+    row.id, row.project_slug, row.flow_name, row.status, row.failed_at, row.reason,
+    row.steps_json, row.step_count, row.duration_ms, row.created_at, row.video_key ?? null,
+    row.build ?? null, row.final_url ?? null, row.auth_json ?? null,
+    row.reduced_motion ?? null,
+    row.artifact_backend ?? null,
+    row.findings_json ?? null,
+  );
+
+  // F276.1 — queue every still for the cloud, in the SAME function that wrote it
+  // locally. Doing it at the three call sites instead would mean a fourth call site
+  // added tomorrow silently produces phone-invisible evidence — the F213.12 lesson
+  // this file has already learned three times: a field produced in one place and not
+  // written in the other reaches nobody.
+  enqueueArtifacts(
+    db,
+    projectSlug,
+    [...storedSteps.map((s) => s.artifact_key), videoKey],
+  );
+
+  return row;
+}
+
+export interface ListFlowRunsFilter {
+  flow_name?: string;
+  status?: string;
+  limit?: number;
+}
+
+export function listFlowRuns(db: Database, projectSlug: string, filter: ListFlowRunsFilter = {}): LensFlowRunRow[] {
+  const clauses = ['project_slug = ?'];
+  const params: (string | number)[] = [projectSlug];
+  if (filter.flow_name) {
+    clauses.push('flow_name = ?');
+    params.push(filter.flow_name);
+  }
+  if (filter.status) {
+    clauses.push('status = ?');
+    params.push(filter.status);
+  }
+  const limit = Math.min(Math.max(filter.limit ?? 50, 1), 500);
+  params.push(limit);
+  return db
+    .query(`SELECT * FROM lens_flow_runs WHERE ${clauses.join(' AND ')} ORDER BY created_at DESC LIMIT ?`)
+    .all(...params) as LensFlowRunRow[];
+}
+
+export function getFlowRun(db: Database, id: string): LensFlowRunRow | null {
+  return (db.query('SELECT * FROM lens_flow_runs WHERE id = ?').get(id) as LensFlowRunRow | null) ?? null;
+}