@vellumai/assistant 0.8.6 → 0.8.7

package/src/cli/commands/db/repair-step-integrity.ts

@@ -0,0 +1,146 @@
+/**
+ * Repair step: integrity check.
+ *
+ * Runs `PRAGMA integrity_check` on a read-only handle. The pragma is the
+ * authoritative SQLite corruption probe — it walks every page, verifies
+ * b-tree linkage, checks index ↔ table consistency, and surfaces results
+ * as one or more rows of text. The canonical "everything ok" response is
+ * a single row containing the literal string "ok"; any other rows are
+ * error messages we surface verbatim.
+ *
+ * We use the full `integrity_check` rather than `quick_check` because the
+ * user typing `assistant db repair` is explicitly signing up for a slow
+ * thorough probe. On the workspace's current ~4 GB DB the full check runs
+ * in single-digit-minutes; that's acceptable for "the DB might be broken,
+ * please tell me everything that's wrong".
+ *
+ * The step never mutates the database. If corruption is found the step
+ * returns a non-halting error — subsequent steps may still produce useful
+ * work even on a partially-corrupt DB.
+ */
+
+import { Database } from "bun:sqlite";
+
+import type { RepairContext, RepairStep, StepResult } from "./repair-steps.js";
+
+/**
+ * Maximum number of corruption error lines to surface in the human output
+ * before truncating with a "+N more" suffix. The JSON payload always
+ * carries the full list; this cap only affects the rendered text so a
+ * massively corrupt DB doesn't drown the terminal.
+ */
+const MAX_REPORTED_ERROR_LINES = 20;
+
+async function runIntegrityCheck(ctx: RepairContext): Promise<StepResult> {
+  // Open-failure (file unreadable, file is a directory, header so corrupt
+  // SQLite refuses to attach) needs to surface as a normal step error, not
+  // get caught by the runner's generic "step threw — this is a bug"
+  // fallback. Catch the constructor failure and convert it into a
+  // structured diagnostic.
+  let db: Database;
+  try {
+    db = new Database(ctx.dbPath, { readonly: true });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: "error",
+      summary: "could not open database for integrity check",
+      detailLines: [msg],
+      data: {
+        pageCount: 0,
+        errorCount: 1,
+        errors: [msg],
+        openFailed: true,
+      },
+    };
+  }
+
+  try {
+    // `PRAGMA integrity_check` returns rows of a single TEXT column also
+    // named `integrity_check`. When the DB is healthy this is exactly one
+    // row whose value is the literal "ok"; any other shape means errors.
+    //
+    // Severely corrupted DBs (header damaged, b-tree root unreadable) can
+    // cause the pragma itself to throw "database disk image is malformed"
+    // before yielding any rows. Catch that and surface it as the
+    // corruption signal it actually is — not a step bug, the DB telling
+    // us it's structurally invalid.
+    let messages: string[];
+    try {
+      const rows = db
+        .query<{ integrity_check: string }, []>("PRAGMA integrity_check")
+        .all();
+      messages = rows.map((r) => r.integrity_check);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const pageCount = safePageCount(db);
+      return {
+        status: "error",
+        summary: "database is too corrupt to complete integrity check",
+        detailLines: [msg, `page count: ${pageCount.toLocaleString("en-US")}`],
+        data: {
+          pageCount,
+          errorCount: 1,
+          errors: [msg],
+          checkFailed: true,
+        },
+      };
+    }
+
+    const healthy = messages.length === 1 && messages[0] === "ok";
+    const pageCount = safePageCount(db);
+
+    if (healthy) {
+      return {
+        status: "ok",
+        summary: "no corruption detected",
+        detailLines: [`scanned ${pageCount.toLocaleString("en-US")} pages`],
+        data: { pageCount, errorCount: 0 },
+      };
+    }
+
+    const truncated = messages.slice(0, MAX_REPORTED_ERROR_LINES);
+    const detailLines =
+      messages.length > MAX_REPORTED_ERROR_LINES
+        ? [
+            ...truncated,
+            `+ ${messages.length - MAX_REPORTED_ERROR_LINES} more (use --json for full list)`,
+          ]
+        : truncated;
+
+    return {
+      status: "error",
+      summary: `${messages.length} integrity violation${messages.length === 1 ? "" : "s"} reported`,
+      detailLines,
+      data: {
+        pageCount,
+        errorCount: messages.length,
+        errors: messages,
+      },
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * `PRAGMA page_count` is cheap and works even on damaged DBs (it reads
+ * from the header), but on truly malformed files it can throw too. Wrap
+ * it so the integrity step always has a number to report.
+ */
+function safePageCount(db: Database): number {
+  try {
+    return (
+      db.query<{ page_count: number }, []>("PRAGMA page_count").get()
+        ?.page_count ?? 0
+    );
+  } catch {
+    return 0;
+  }
+}
+
+export const integrityCheckStep: RepairStep = {
+  name: "integrity-check",
+  description: "Walk every database page and verify b-tree consistency",
+  run: runIntegrityCheck,
+};

package/src/cli/commands/db/repair-steps.ts

@@ -0,0 +1,164 @@
+/**
+ * Step framework for `assistant db repair`.
+ *
+ * `repair` runs a sequence of discrete remediation passes. Each step is a
+ * `RepairStep` with a `name`, a one-line `description`, and a `run(ctx)`
+ * that returns a `StepResult`.
+ *
+ * The runner:
+ *   - executes steps sequentially in the order supplied
+ *   - continues past non-halting failures (a corrupt DB doesn't preclude
+ *     re-deriving conversations from disk)
+ *   - stops only when a step returns `halt: true`
+ *   - never throws — uncaught errors from a step body are captured as a
+ *     synthetic `error` result so a bug in one step can't crash the run
+ *
+ * `RepairContext` holds the per-run state every step shares — currently
+ * just the DB path. Steps open their own bun:sqlite connections (read-only
+ * or read-write as needed) rather than sharing a handle through the context.
+ */
+
+import type { Database } from "bun:sqlite";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RepairContext {
+  /** Absolute path to the assistant SQLite database file. */
+  dbPath: string;
+}
+
+export type StepResult =
+  | {
+      status: "ok";
+      /** One-line human summary, e.g. "no corruption detected". */
+      summary: string;
+      /** Optional structured payload surfaced in --json mode. */
+      data?: Record<string, unknown>;
+      /** Optional secondary lines printed under the summary in human mode. */
+      detailLines?: string[];
+      /** Wall-clock duration of the step, set by the runner. */
+      durationMs?: number;
+    }
+  | {
+      status: "error";
+      /** One-line human summary, e.g. "database disk image is malformed". */
+      summary: string;
+      data?: Record<string, unknown>;
+      detailLines?: string[];
+      durationMs?: number;
+      /** When true, the runner stops the remaining sequence. */
+      halt?: boolean;
+    };
+
+export interface RepairStep {
+  /** Short identifier; appears in logs as `[i/N] <name>`. */
+  name: string;
+  /** Human one-liner explaining what the step does. */
+  description: string;
+  run: (ctx: RepairContext) => Promise<StepResult>;
+}
+
+export interface StepRun {
+  name: string;
+  description: string;
+  result: StepResult;
+}
+
+export interface RepairReport {
+  dbPath: string;
+  steps: StepRun[];
+  /** Convenience counters for renderers; derived from `steps`. */
+  okCount: number;
+  errorCount: number;
+  /** True when the sequence was cut short by a `halt: true` failure. */
+  halted: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+
+export interface RunnerHooks {
+  /** Called when a step is about to start. */
+  onStart?: (idx: number, total: number, step: RepairStep) => void;
+  /** Called when a step finishes (whether ok or error). */
+  onFinish?: (
+    idx: number,
+    total: number,
+    step: RepairStep,
+    result: StepResult,
+  ) => void;
+}
+
+/**
+ * Run a sequence of repair steps. Never throws — all step failures land in
+ * the returned `RepairReport`. Errors thrown from a step's `run` are
+ * captured as a synthetic `status: "error"` result so a bug in one step
+ * can't take down the whole repair.
+ */
+export async function runRepairSteps(
+  ctx: RepairContext,
+  steps: RepairStep[],
+  hooks: RunnerHooks = {},
+): Promise<RepairReport> {
+  const runs: StepRun[] = [];
+  let halted = false;
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]!;
+    hooks.onStart?.(i + 1, steps.length, step);
+
+    const startedAt = performance.now();
+    let result: StepResult;
+    try {
+      result = await step.run(ctx);
+    } catch (err) {
+      result = {
+        status: "error",
+        summary: err instanceof Error ? err.message : String(err),
+        detailLines: ["step threw an unexpected error — this is a bug"],
+      };
+    }
+    result.durationMs = performance.now() - startedAt;
+
+    hooks.onFinish?.(i + 1, steps.length, step, result);
+    runs.push({ name: step.name, description: step.description, result });
+
+    if (result.status === "error" && result.halt) {
+      halted = true;
+      break;
+    }
+  }
+
+  const okCount = runs.filter((r) => r.result.status === "ok").length;
+  const errorCount = runs.filter((r) => r.result.status === "error").length;
+  return { dbPath: ctx.dbPath, steps: runs, okCount, errorCount, halted };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers used by step implementations
+// ---------------------------------------------------------------------------
+
+/** Convenience: format a duration as `12.3s` or `450ms`. */
+export function formatDurationMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Open a connection inside a step, ensuring the handle is closed even when
+ * the step's body throws. The callback may return any `StepResult`.
+ */
+export async function withDb<T>(
+  open: () => Database,
+  fn: (db: Database) => Promise<T> | T,
+): Promise<T> {
+  const db = open();
+  try {
+    return await fn(db);
+  } finally {
+    db.close();
+  }
+}

package/src/cli/commands/db/repair.ts

@@ -0,0 +1,141 @@
+/**
+ * `assistant db repair` — run the database repair sequence.
+ *
+ * Composes the step framework in `repair-steps.ts` with the concrete steps
+ * imported from `repair-step-*.ts` files. Each step logs its own
+ * starting/success/error lines; the runner aggregates results into a
+ * `RepairReport` that renders either as plain text or as a single JSON
+ * payload (`--json`).
+ *
+ * Adding a new step is a one-line edit to the `STEPS` array.
+ *
+ * Transport: `local`. The whole point of this surface is that it works when
+ * the daemon is down, so it opens the DB file directly and never goes
+ * through IPC.
+ */
+
+import { existsSync } from "node:fs";
+
+import type { Command } from "commander";
+
+import { getDbPath } from "../../../util/platform.js";
+import { dim, green, red } from "../../lib/cli-colors.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+import { conversationBackfillStep } from "./repair-step-conversation-backfill.js";
+import { integrityCheckStep } from "./repair-step-integrity.js";
+import type { RepairReport, RepairStep, StepResult } from "./repair-steps.js";
+import { formatDurationMs, runRepairSteps } from "./repair-steps.js";
+
+// ---------------------------------------------------------------------------
+// Step sequence
+// ---------------------------------------------------------------------------
+
+/**
+ * Repair steps run in the order listed here. Integrity check runs first so
+ * structural damage surfaces before subsequent steps touch the same pages.
+ */
+const STEPS: RepairStep[] = [integrityCheckStep, conversationBackfillStep];
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+function renderMissingDb(path: string): string {
+  return (
+    `${red("ERROR")}  Database not found at ${path}\n\n` +
+    `Nothing to repair — the assistant SQLite database is missing. If you\n` +
+    `have a backup, restore it first:\n` +
+    `  assistant backup list\n`
+  );
+}
+
+function emitStepStart(idx: number, total: number, step: RepairStep): void {
+  process.stdout.write(
+    `[${idx}/${total}] ${step.name} — ${dim("starting")}\n` +
+      `        ${dim(step.description)}\n`,
+  );
+}
+
+function emitStepFinish(
+  idx: number,
+  total: number,
+  step: RepairStep,
+  result: StepResult,
+): void {
+  const duration = formatDurationMs(result.durationMs ?? 0);
+  if (result.status === "ok") {
+    process.stdout.write(
+      `[${idx}/${total}] ${step.name} — ${green("ok")}  ` +
+        `${result.summary}  ${dim(`(${duration})`)}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `[${idx}/${total}] ${step.name} — ${red("error")}  ` +
+        `${result.summary}  ${dim(`(${duration})`)}\n`,
+    );
+  }
+  for (const line of result.detailLines ?? []) {
+    process.stdout.write(`        ${dim(line)}\n`);
+  }
+}
+
+function renderSummary(report: RepairReport): string {
+  const { okCount, errorCount, halted } = report;
+  const total = report.steps.length;
+  let line =
+    `\nDone. ${total} step${total === 1 ? "" : "s"} ran: ` +
+    `${okCount} ok, ${errorCount} failed`;
+  if (halted) line += "  (sequence halted)";
+  return line + "\n";
+}
+
+// ---------------------------------------------------------------------------
+// Command wiring
+// ---------------------------------------------------------------------------
+
+export function registerDbRepair(parent: Command): void {
+  parent
+    .command("repair")
+    .description("Run the database repair sequence (integrity check, …)")
+    .action(async function (this: Command) {
+      const dbPath = getDbPath();
+
+      if (!existsSync(dbPath)) {
+        if (shouldOutputJson(this)) {
+          writeOutput(this, {
+            dbPath,
+            missing: true,
+            steps: [],
+            okCount: 0,
+            errorCount: 0,
+            halted: false,
+          });
+        } else {
+          process.stderr.write(renderMissingDb(dbPath));
+        }
+        process.exit(1);
+      }
+
+      const isJson = shouldOutputJson(this);
+
+      const report = await runRepairSteps(
+        { dbPath },
+        STEPS,
+        isJson
+          ? {}
+          : {
+              onStart: emitStepStart,
+              onFinish: emitStepFinish,
+            },
+      );
+
+      if (isJson) {
+        writeOutput(this, report);
+      } else {
+        process.stdout.write(renderSummary(report));
+      }
+
+      // Exit non-zero if any step failed — makes the command scriptable.
+      if (report.errorCount > 0) process.exit(1);
+    });
+}