@kirrosh/zond 0.22.0 → 0.23.0

package/src/db/queries/collections.ts

@@ -0,0 +1,133 @@
+import { getDb } from "../schema.ts";
+import {
+  normalizePath,
+  type CollectionRecord,
+  type CollectionSummary,
+  type CreateCollectionOpts,
+  type RunRecord,
+} from "./types.ts";
+
+export function createCollection(opts: CreateCollectionOpts): number {
+  const db = getDb();
+  const stmt = db.prepare(`
+    INSERT INTO collections (name, base_dir, test_path, openapi_spec)
+    VALUES ($name, $base_dir, $test_path, $openapi_spec)
+  `);
+  const result = stmt.run({
+    $name: opts.name,
+    $base_dir: opts.base_dir ?? null,
+    $test_path: opts.test_path,
+    $openapi_spec: opts.openapi_spec ?? null,
+  });
+  return Number(result.lastInsertRowid);
+}
+
+export function getCollectionById(id: number): CollectionRecord | null {
+  const db = getDb();
+  return db.query("SELECT * FROM collections WHERE id = ?").get(id) as CollectionRecord | null;
+}
+
+export function getLatestRunByCollection(
+  collectionId: number,
+  opts: { runKind?: "regular" | "probe" | "check" | "any" } = {},
+): RunRecord | null {
+  const db = getDb();
+  // ARV-55: 'regular' is the default so coverage skips probe-only runs
+  // without an explicit predicate. 'any' opts back into the legacy
+  // behaviour (used by `coverage`'s probe-run hint logic).
+  const kind = opts.runKind ?? "regular";
+  const kindClause = kind === "any" ? "" : "AND run_kind = ?";
+  const params: (string | number)[] = [collectionId];
+  if (kind !== "any") params.push(kind);
+  const row = db.query(`
+    SELECT * FROM runs
+    WHERE collection_id = ? AND finished_at IS NOT NULL ${kindClause}
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get(...params) as (Record<string, unknown> & { tags?: unknown }) | null;
+  if (!row) return null;
+  let tags: string[] | null = null;
+  if (typeof row.tags === "string") {
+    try {
+      const v = JSON.parse(row.tags);
+      if (Array.isArray(v) && v.every((x) => typeof x === "string")) tags = v;
+    } catch {
+      // legacy/corrupt — leave null
+    }
+  }
+  // ARV-55: normalise run_kind alongside tags so RunRecord stays consistent.
+  const rk = row.run_kind;
+  const run_kind: import("../../core/runner/run-kind.ts").RunKind =
+    rk === "probe" || rk === "check" ? rk : "regular";
+  return { ...(row as unknown as RunRecord), tags, run_kind };
+}
+
+export function listCollections(): CollectionSummary[] {
+  const db = getDb();
+  return db.query(`
+    SELECT
+      c.id, c.name, c.base_dir, c.test_path, c.openapi_spec, c.created_at,
+      COUNT(r.id) AS total_runs,
+      CASE WHEN SUM(r.total) > 0
+        THEN ROUND(SUM(r.passed) * 100.0 / SUM(r.total), 1)
+        ELSE 0 END AS pass_rate,
+      MAX(r.started_at) AS last_run_at,
+      COALESCE((SELECT passed FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_passed,
+      COALESCE((SELECT failed FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_failed,
+      COALESCE((SELECT total FROM runs WHERE collection_id = c.id ORDER BY started_at DESC LIMIT 1), 0) AS last_run_total
+    FROM collections c
+    LEFT JOIN runs r ON r.collection_id = c.id AND r.finished_at IS NOT NULL
+    GROUP BY c.id
+    ORDER BY c.name
+  `).all() as CollectionSummary[];
+}
+
+export function updateCollection(id: number, opts: Partial<CreateCollectionOpts>): boolean {
+  const db = getDb();
+  const sets: string[] = [];
+  const params: Record<string, any> = { $id: id };
+
+  if (opts.name !== undefined) { sets.push("name = $name"); params.$name = opts.name; }
+  if (opts.base_dir !== undefined) { sets.push("base_dir = $base_dir"); params.$base_dir = opts.base_dir; }
+  if (opts.test_path !== undefined) { sets.push("test_path = $test_path"); params.$test_path = opts.test_path; }
+  if (opts.openapi_spec !== undefined) { sets.push("openapi_spec = $openapi_spec"); params.$openapi_spec = opts.openapi_spec; }
+
+  if (sets.length === 0) return false;
+
+  const result = db.prepare(`UPDATE collections SET ${sets.join(", ")} WHERE id = $id`).run(params);
+  return result.changes > 0;
+}
+
+export function deleteCollection(id: number, deleteRuns = false): boolean {
+  const db = getDb();
+  if (deleteRuns) {
+    const runIds = db.query("SELECT id FROM runs WHERE collection_id = ?").all(id) as { id: number }[];
+    for (const row of runIds) {
+      db.prepare("DELETE FROM results WHERE run_id = ?").run(row.id);
+    }
+    db.prepare("DELETE FROM runs WHERE collection_id = ?").run(id);
+  } else {
+    db.prepare("UPDATE runs SET collection_id = NULL WHERE collection_id = ?").run(id);
+  }
+  const result = db.prepare("DELETE FROM collections WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function findCollectionByTestPath(path: string): CollectionRecord | null {
+  const db = getDb();
+  const normalized = normalizePath(path);
+  return db.query("SELECT * FROM collections WHERE test_path = ?").get(normalized) as CollectionRecord | null;
+}
+
+export function findCollectionByNameOrId(nameOrId: string): CollectionRecord | null {
+  const db = getDb();
+  // Try as numeric ID first
+  const id = parseInt(nameOrId, 10);
+  if (!isNaN(id)) {
+    const byId = db.query("SELECT * FROM collections WHERE id = ?").get(id) as CollectionRecord | null;
+    if (byId) return byId;
+  }
+  // Then by name (case-insensitive)
+  return db.query("SELECT * FROM collections WHERE lower(name) = lower(?)").get(nameOrId) as CollectionRecord | null;
+}
+

package/src/db/queries/coverage.ts

@@ -0,0 +1,9 @@
+/**
+ * Reserved for coverage-domain DB queries. As of TASK-187, coverage
+ * tables (`coverage_runs`, etc.) are still managed entirely from
+ * `src/core/coverage/`; nothing in `queries.ts` was coverage-specific to
+ * move here. The file exists so the per-domain layout is future-proof
+ * — when a coverage table-backed feature lands, queries land here and
+ * the cli/UI imports stay stable.
+ */
+export {};

package/src/db/queries/dashboard.ts

@@ -0,0 +1,59 @@
+import { getDb } from "../schema.ts";
+import type {
+  DashboardStats,
+  PassRateTrendPoint,
+  SlowestTest,
+  FlakyTest,
+} from "./types.ts";
+
+export function getDashboardStats(): DashboardStats {
+  const db = getDb();
+  const row = db.query(`
+    SELECT
+      COUNT(*)            AS totalRuns,
+      COALESCE(SUM(total), 0)   AS totalTests,
+      CASE WHEN SUM(total) > 0
+        THEN ROUND(SUM(passed) * 100.0 / SUM(total), 1)
+        ELSE 0 END        AS overallPassRate,
+      COALESCE(ROUND(AVG(duration_ms), 0), 0) AS avgDuration
+    FROM runs
+    WHERE finished_at IS NOT NULL
+  `).get() as { totalRuns: number; totalTests: number; overallPassRate: number; avgDuration: number };
+  return row;
+}
+
+export function getPassRateTrend(limit = 30): PassRateTrendPoint[] {
+  const db = getDb();
+  return db.query(`
+    SELECT id AS run_id, started_at,
+      CASE WHEN total > 0 THEN ROUND(passed * 100.0 / total, 1) ELSE 0 END AS pass_rate
+    FROM runs
+    WHERE finished_at IS NOT NULL
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(limit) as PassRateTrendPoint[];
+}
+
+export function getSlowestTests(limit = 5): SlowestTest[] {
+  const db = getDb();
+  return db.query(`
+    SELECT suite_name, test_name, ROUND(AVG(duration_ms), 0) AS avg_duration
+    FROM results
+    GROUP BY suite_name, test_name
+    ORDER BY avg_duration DESC
+    LIMIT ?
+  `).all(limit) as SlowestTest[];
+}
+
+export function getFlakyTests(runsBack = 20, limit = 5): FlakyTest[] {
+  const db = getDb();
+  return db.query(`
+    SELECT r.suite_name, r.test_name, COUNT(DISTINCT r.status) AS distinct_statuses
+    FROM results r
+    INNER JOIN (SELECT id FROM runs ORDER BY started_at DESC LIMIT ?) recent ON r.run_id = recent.id
+    GROUP BY r.suite_name, r.test_name
+    HAVING COUNT(DISTINCT r.status) > 1
+    ORDER BY distinct_statuses DESC
+    LIMIT ?
+  `).all(runsBack, limit) as FlakyTest[];
+}

package/src/db/queries/results.ts

@@ -0,0 +1,128 @@
+import { getDb, withDbRetry } from "../schema.ts";
+import type { TestRunResult } from "../../core/runner/types.ts";
+import { getSecretRegistry } from "../../core/secrets/registry.ts";
+import type { StoredStepResult } from "./types.ts";
+
+function parseProvenance(raw: unknown): import("../../core/parser/types.ts").SourceMetadata | null {
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveResults(runId: number, suiteResults: TestRunResult[]): void {
+  const db = getDb();
+
+  const stmt = db.prepare(`
+    INSERT INTO results
+      (run_id, suite_name, test_name, status, duration_ms,
+       request_method, request_url, request_body,
+       response_status, response_body, response_headers, error_message, assertions, captures, suite_file, provenance, failure_class, failure_class_reason, spec_pointer, spec_excerpt)
+    VALUES
+      ($run_id, $suite_name, $test_name, $status, $duration_ms,
+       $request_method, $request_url, $request_body,
+       $response_status, $response_body, $response_headers, $error_message, $assertions, $captures, $suite_file, $provenance, $failure_class, $failure_class_reason, $spec_pointer, $spec_excerpt)
+  `);
+
+  // TASK-167 (m-10): every string field that can carry a leaked secret
+  // (URL with token in query, body echo on 401, Set-Cookie header, etc.)
+  // goes through the registry sanitizer before INSERT.
+  const reg = getSecretRegistry();
+  const redactString = (s: string | null | undefined): string | null =>
+    s == null ? null : reg.redact(s);
+  const redactJson = (v: unknown): string | null => {
+    if (v == null) return null;
+    if (typeof v === "string") return reg.redact(v);
+    return reg.redact(JSON.stringify(v));
+  };
+
+  withDbRetry("saveResults", () => db.transaction(() => {
+    for (const suite of suiteResults) {
+      for (const step of suite.steps) {
+        const maxBodySize = 50_000;
+        const truncBody = (s: string | null | undefined) =>
+          s && s.length > maxBodySize ? s.slice(0, maxBodySize) + "\n...[truncated]" : (s ?? null);
+        stmt.run({
+          $run_id: runId,
+          $suite_name: suite.suite_name,
+          $test_name: step.name,
+          $status: step.status,
+          $duration_ms: step.duration_ms,
+          $request_method: step.request.method,
+          $request_url: redactString(step.request.url),
+          $request_body: redactString(truncBody(step.request.body)),
+          $response_status: step.response?.status ?? null,
+          $response_body: redactString(truncBody(step.response?.body)),
+          $response_headers: step.response?.headers
+            ? redactJson(step.response.headers)
+            : null,
+          $error_message: redactString(step.error ?? null),
+          $assertions: step.assertions.length > 0 ? redactJson(step.assertions) : null,
+          $captures: Object.keys(step.captures).length > 0 ? redactJson(step.captures) : null,
+          $suite_file: suite.suite_file ?? null,
+          $provenance: step.provenance ? JSON.stringify(step.provenance) : null,
+          $failure_class: step.failure_class ?? null,
+          $failure_class_reason: step.failure_class_reason ?? null,
+          $spec_pointer: step.spec_pointer ?? null,
+          $spec_excerpt: redactString(step.spec_excerpt ?? null),
+        });
+      }
+    }
+  })());
+}
+
+export function getResultsByRunId(runId: number): StoredStepResult[] {
+  const db = getDb();
+  const rows = db.query("SELECT * FROM results WHERE run_id = ? ORDER BY id").all(runId) as Array<
+    Omit<StoredStepResult, "assertions" | "captures" | "provenance"> & {
+      assertions: string | null;
+      captures: string | null;
+      provenance: string | null;
+    }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+    provenance: parseProvenance(row.provenance),
+  }));
+}
+
+export function getFilteredResults(
+  runId: number,
+  filters: {
+    method?: string;
+    /** Compiled SQL fragment for the `--status` filter (TASK-140). */
+    statusSql?: { sql: string; params: number[] };
+  },
+): StoredStepResult[] {
+  const db = getDb();
+  const conditions = ["run_id = ?"];
+  const params: (string | number)[] = [runId];
+
+  if (filters.method) {
+    conditions.push("request_method = ?");
+    params.push(filters.method.toUpperCase());
+  }
+  if (filters.statusSql) {
+    conditions.push(filters.statusSql.sql);
+    params.push(...filters.statusSql.params);
+  }
+
+  const rows = db.query(`SELECT * FROM results WHERE ${conditions.join(" AND ")} ORDER BY id`).all(...params) as Array<
+    Omit<StoredStepResult, "assertions" | "captures" | "provenance"> & {
+      assertions: string | null;
+      captures: string | null;
+      provenance: string | null;
+    }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+    provenance: parseProvenance(row.provenance),
+  }));
+}

package/src/db/queries/runs.ts

@@ -0,0 +1,235 @@
+import { getDb, withDbRetry } from "../schema.ts";
+import type { TestRunResult } from "../../core/runner/types.ts";
+import type { CreateRunOpts, RunRecord, RunSummary, RunFilters } from "./types.ts";
+
+function buildRunFilterSQL(filters: RunFilters): { where: string; params: unknown[] } {
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+
+  if (filters.status === "has_failures") {
+    clauses.push("r.failed > 0");
+  } else if (filters.status === "all_passed") {
+    clauses.push("r.failed = 0 AND r.total > 0");
+  }
+
+  if (filters.environment) {
+    clauses.push("r.environment = ?");
+    params.push(filters.environment);
+  }
+
+  if (filters.date_from) {
+    clauses.push("r.started_at >= ?");
+    params.push(filters.date_from);
+  }
+
+  if (filters.date_to) {
+    clauses.push("r.started_at <= ?");
+    params.push(filters.date_to + "T23:59:59");
+  }
+
+  if (filters.test_name) {
+    clauses.push("r.id IN (SELECT DISTINCT run_id FROM results WHERE test_name LIKE ?)");
+    params.push(`%${filters.test_name}%`);
+  }
+
+  if (filters.trigger) {
+    clauses.push("r.trigger = ?");
+    params.push(filters.trigger);
+  }
+
+  const where = clauses.length > 0 ? "WHERE " + clauses.join(" AND ") : "";
+  return { where, params };
+}
+
+export function createRun(opts: CreateRunOpts): number {
+  const db = getDb();
+  const stmt = db.prepare(`
+    INSERT INTO runs (started_at, environment, trigger, commit_sha, branch, collection_id, session_id, tags, run_kind)
+    VALUES ($started_at, $environment, $trigger, $commit_sha, $branch, $collection_id, $session_id, $tags, $run_kind)
+  `);
+  const result = withDbRetry("createRun", () => stmt.run({
+    $started_at: opts.started_at,
+    $environment: opts.environment ?? null,
+    $trigger: opts.trigger ?? "manual",
+    $commit_sha: opts.commit_sha ?? null,
+    $branch: opts.branch ?? null,
+    $collection_id: opts.collection_id ?? null,
+    $session_id: opts.session_id ?? null,
+    $tags: opts.tags && opts.tags.length > 0 ? JSON.stringify(opts.tags) : null,
+    // ARV-55: default 'regular' here too — DB default would also catch it,
+    // but spelling it out keeps INSERTs idempotent and matches the type.
+    $run_kind: opts.run_kind ?? "regular",
+  }));
+  return Number(result.lastInsertRowid);
+}
+
+/** Decode the JSON-encoded `tags` column into a string array. Returns null
+ *  if the column is null or unparseable (legacy rows / corruption). */
+function decodeTags(raw: unknown): string[] | null {
+  if (raw == null) return null;
+  if (typeof raw !== "string") return null;
+  try {
+    const v = JSON.parse(raw);
+    if (Array.isArray(v) && v.every((x) => typeof x === "string")) return v;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function decodeRunKind(raw: unknown): "regular" | "probe" | "check" {
+  // Migration v10 backfills legacy rows; this is a belt-and-suspenders
+  // normaliser for any value SQLite returns from `run_kind`.
+  if (raw === "probe" || raw === "check") return raw;
+  return "regular";
+}
+
+function decodeRunRow(row: unknown): RunRecord | null {
+  if (!row || typeof row !== "object") return null;
+  const r = row as Record<string, unknown> & { tags?: unknown; run_kind?: unknown };
+  return {
+    ...(r as unknown as RunRecord),
+    tags: decodeTags(r.tags),
+    run_kind: decodeRunKind(r.run_kind),
+  };
+}
+
+export function finalizeRun(runId: number, results: TestRunResult[]): void {
+  const db = getDb();
+
+  const total = results.reduce((s, r) => s + r.total, 0);
+  const passed = results.reduce((s, r) => s + r.passed, 0);
+  const failed = results.reduce((s, r) => s + r.failed, 0);
+  const skipped = results.reduce((s, r) => s + r.skipped, 0);
+
+  const started = results[0]?.started_at ?? new Date().toISOString();
+  const finished = results[results.length - 1]?.finished_at ?? new Date().toISOString();
+  const durationMs = new Date(finished).getTime() - new Date(started).getTime();
+
+  const stmt = db.prepare(`
+    UPDATE runs
+    SET finished_at = $finished_at,
+        total       = $total,
+        passed      = $passed,
+        failed      = $failed,
+        skipped     = $skipped,
+        duration_ms = $duration_ms
+    WHERE id = $id
+  `);
+  withDbRetry("finalizeRun", () => stmt.run({
+    $finished_at: finished,
+    $total: total,
+    $passed: passed,
+    $failed: failed,
+    $skipped: skipped,
+    $duration_ms: durationMs,
+    $id: runId,
+  }));
+}
+
+export function getRunById(runId: number): RunRecord | null {
+  const db = getDb();
+  const row = db.query("SELECT * FROM runs WHERE id = ?").get(runId);
+  return decodeRunRow(row);
+}
+
+/** TASK-274: list runs of a collection with optional time-window or
+ *  tag-membership filters, ordered by started_at ASC (matches the
+ *  session-based loader so coverage union order is stable). NULL collection
+ *  is intentionally excluded — for tag/since selectors the user has
+ *  pinpointed an API, ad-hoc/probe runs should be tagged or use --union
+ *  session to be picked up. */
+export function listRunsByCollectionFiltered(
+  collectionId: number,
+  filters: { since?: string; tag?: string; limit?: number },
+): RunRecord[] {
+  const db = getDb();
+  const clauses: string[] = ["collection_id = ?", "finished_at IS NOT NULL"];
+  const params: unknown[] = [collectionId];
+  if (filters.since) {
+    clauses.push("started_at >= ?");
+    params.push(filters.since);
+  }
+  if (filters.tag) {
+    // tags is a JSON array of strings — match exact element via LIKE on the
+    // serialised form. Cheap and correct for our small N (one row per run);
+    // a JSON1-table-function approach would be overkill here.
+    clauses.push("tags LIKE ?");
+    params.push(`%"${filters.tag.replace(/[\\%_]/g, "\\$&")}"%`);
+  }
+  const limitClause = filters.limit && filters.limit > 0 ? ` LIMIT ${filters.limit}` : "";
+  const rows = db.query(
+    `SELECT * FROM runs WHERE ${clauses.join(" AND ")} ORDER BY started_at ASC${limitClause}`,
+  ).all(...(params as (string | number)[]));
+  const out: RunRecord[] = [];
+  for (const r of rows) {
+    const decoded = decodeRunRow(r);
+    if (decoded) out.push(decoded);
+  }
+  return out;
+}
+
+export function listRuns(limit = 20, offset = 0, filters?: RunFilters): RunSummary[] {
+  const db = getDb();
+  if (filters && Object.values(filters).some(Boolean)) {
+    const { where, params } = buildRunFilterSQL(filters);
+    return db.query(`
+      SELECT r.id, r.started_at, r.finished_at, r.total, r.passed, r.failed, r.skipped, r.environment, r.duration_ms, r.collection_id, r.session_id
+      FROM runs r
+      ${where}
+      ORDER BY r.started_at DESC
+      LIMIT ? OFFSET ?
+    `).all(...(params as (string | number)[]), limit, offset) as RunSummary[];
+  }
+  return db.query(`
+    SELECT id, started_at, finished_at, total, passed, failed, skipped, environment, duration_ms, collection_id, session_id
+    FROM runs
+    ORDER BY started_at DESC
+    LIMIT ? OFFSET ?
+  `).all(limit, offset) as RunSummary[];
+}
+
+/** TASK-266: latest run with at least one failure (for `zond db diagnose`
+ *  default and `zond-triage` skill). Returns null when no failing run exists. */
+export function getLatestFailingRunId(): number | null {
+  const db = getDb();
+  const row = db.query(`
+    SELECT id FROM runs
+    WHERE failed > 0
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get() as { id: number } | undefined;
+  return row?.id ?? null;
+}
+
+/** TASK-266: latest run regardless of status (for `--latest`). */
+export function getLatestRunId(): number | null {
+  const db = getDb();
+  const row = db.query(`
+    SELECT id FROM runs
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get() as { id: number } | undefined;
+  return row?.id ?? null;
+}
+
+export function deleteRun(runId: number): boolean {
+  const db = getDb();
+  // results are cascade-deleted via FK; but SQLite FK delete cascade requires explicit config
+  return withDbRetry("deleteRun", () => {
+    db.prepare("DELETE FROM results WHERE run_id = ?").run(runId);
+    const result = db.prepare("DELETE FROM runs WHERE id = ?").run(runId);
+    return result.changes > 0;
+  });
+}
+
+export function countRuns(filters?: RunFilters): number {
+  const db = getDb();
+  if (filters && Object.values(filters).some(Boolean)) {
+    const { where, params } = buildRunFilterSQL(filters);
+    const row = db.query(`SELECT COUNT(*) AS cnt FROM runs r ${where}`).get(...(params as (string | number)[])) as { cnt: number };
+    return row.cnt;
+  }
+  const row = db.query("SELECT COUNT(*) AS cnt FROM runs").get() as { cnt: number };
+  return row.cnt;
+}

package/src/db/queries/sessions.ts

@@ -0,0 +1,42 @@
+import { getDb } from "../schema.ts";
+import type { RunSummary, SessionSummary } from "./types.ts";
+
+export function listSessions(limit = 20, offset = 0): SessionSummary[] {
+  const db = getDb();
+  return db.query(`
+    SELECT
+      session_id,
+      MIN(started_at)        AS started_at,
+      MAX(finished_at)       AS finished_at,
+      COUNT(*)               AS run_count,
+      COALESCE(SUM(total), 0)   AS total,
+      COALESCE(SUM(passed), 0)  AS passed,
+      COALESCE(SUM(failed), 0)  AS failed,
+      COALESCE(SUM(skipped), 0) AS skipped,
+      SUM(duration_ms)       AS duration_ms,
+      MAX(environment)       AS environment
+    FROM runs
+    WHERE session_id IS NOT NULL
+    GROUP BY session_id
+    ORDER BY started_at DESC
+    LIMIT ? OFFSET ?
+  `).all(limit, offset) as SessionSummary[];
+}
+
+export function countSessions(): number {
+  const db = getDb();
+  const row = db.query(
+    "SELECT COUNT(DISTINCT session_id) AS cnt FROM runs WHERE session_id IS NOT NULL",
+  ).get() as { cnt: number };
+  return row.cnt;
+}
+
+export function listRunsBySession(sessionId: string): RunSummary[] {
+  const db = getDb();
+  return db.query(`
+    SELECT id, started_at, finished_at, total, passed, failed, skipped, environment, duration_ms, collection_id, session_id
+    FROM runs
+    WHERE session_id = ?
+    ORDER BY started_at ASC
+  `).all(sessionId) as RunSummary[];
+}

package/src/db/queries/settings.ts

@@ -0,0 +1,28 @@
+/**
+ * Generic key-value settings table. The two helpers are currently
+ * unused by any caller — kept as the canonical access point so future
+ * features (UI prefs, ephemeral run state) can use them without
+ * re-rolling SQL. See TASK-179 / TASK-187.
+ */
+import { getDb } from "../schema.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- intentional: see file docstring
+function getSetting(key: string): string | null {
+  const db = getDb();
+  const row = db.query("SELECT value FROM settings WHERE key = ?").get(key) as { value: string } | null;
+  return row?.value ?? null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- intentional: see file docstring
+function setSetting(key: string, value: string): void {
+  const db = getDb();
+  db.prepare(`
+    INSERT INTO settings (key, value) VALUES ($key, $value)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run({ $key: key, $value: value });
+}
+
+// Reference the helpers so module-private code keeps tsc/knip happy
+// while we leave the slot reserved for future settings consumers.
+void getSetting;
+void setSetting;