feat(db): add schema repair and sentry cli fix command (#197)

## Summary

Adds automatic schema repair for SQLite database migration issues. This
fixes cases where the schema version gets out of sync with actual table
structure during development.

### Changes

**Auto-Repair on SQLiteError**
- When a query fails due to missing columns/tables, the CLI
automatically repairs the schema and retries
- Works at both query preparation (`db.query()`) and execution
(`stmt.get()`) stages
- Logs repairs to stderr without breaking JSON output
- Opt-out via `SENTRY_CLI_NO_AUTO_REPAIR=1`

**`sentry cli fix` Command**
```bash
sentry cli fix              # Diagnose and repair schema issues
sentry cli fix --dry-run    # Show what would be fixed
```

**Schema Repair Utilities**
- `EXPECTED_TABLES` / `EXPECTED_COLUMNS` - Canonical schema definitions
- `getSchemaIssues()` - Diagnostics for missing tables/columns
- `repairSchema()` - Non-destructive repair (only adds, never deletes)

### Testing
- 14 new tests for schema repair functions
- 5 new tests for fix command
- All 997 tests pass

Author: BYK

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -390,6 +390,13 @@ CLI-related commands
 
 Send feedback about the CLI
 
+#### `sentry cli fix`
+
+Diagnose and repair CLI database issues
+
+**Flags:**
+- `--dry-run - Show what would be fixed without making changes`
+
 #### `sentry cli upgrade <version>`
 
 Update the Sentry CLI to the latest version

src/commands/cli/fix.ts

@@ -0,0 +1,97 @@
+/**
+ * sentry cli fix
+ *
+ * Diagnose and repair CLI database issues.
+ */
+
+import { buildCommand } from "@stricli/core";
+import type { SentryContext } from "../../context.js";
+import { getDbPath, getRawDatabase } from "../../lib/db/index.js";
+import {
+  CURRENT_SCHEMA_VERSION,
+  getSchemaIssues,
+  repairSchema,
+  type SchemaIssue,
+} from "../../lib/db/schema.js";
+
+type FixFlags = {
+  readonly "dry-run": boolean;
+};
+
+function formatIssue(issue: SchemaIssue): string {
+  if (issue.type === "missing_table") {
+    return `Missing table: ${issue.table}`;
+  }
+  return `Missing column: ${issue.table}.${issue.column}`;
+}
+
+export const fixCommand = buildCommand({
+  docs: {
+    brief: "Diagnose and repair CLI database issues",
+    fullDescription:
+      "Check the CLI's local SQLite database for schema issues and repair them.\n\n" +
+      "This is useful when upgrading from older CLI versions or if the database\n" +
+      "becomes inconsistent due to interrupted operations.\n\n" +
+      "The command performs non-destructive repairs only - it adds missing tables\n" +
+      "and columns but never deletes data.\n\n" +
+      "Examples:\n" +
+      "  sentry cli fix              # Fix database issues\n" +
+      "  sentry cli fix --dry-run    # Show what would be fixed without making changes",
+  },
+  parameters: {
+    flags: {
+      "dry-run": {
+        kind: "boolean",
+        brief: "Show what would be fixed without making changes",
+        default: false,
+      },
+    },
+  },
+  func(this: SentryContext, flags: FixFlags): void {
+    const { stdout, stderr, process: proc } = this;
+    const dbPath = getDbPath();
+
+    stdout.write(`Database: ${dbPath}\n`);
+    stdout.write(`Expected schema version: ${CURRENT_SCHEMA_VERSION}\n\n`);
+
+    const db = getRawDatabase();
+    const issues = getSchemaIssues(db);
+
+    if (issues.length === 0) {
+      stdout.write("No issues found. Database schema is up to date.\n");
+      return;
+    }
+
+    stdout.write(`Found ${issues.length} issue(s):\n`);
+    for (const issue of issues) {
+      stdout.write(`  - ${formatIssue(issue)}\n`);
+    }
+    stdout.write("\n");
+
+    if (flags["dry-run"]) {
+      stdout.write("Run 'sentry cli fix' to apply fixes.\n");
+      return;
+    }
+
+    stdout.write("Repairing...\n");
+    const { fixed, failed } = repairSchema(db);
+
+    for (const fix of fixed) {
+      stdout.write(`  + ${fix}\n`);
+    }
+
+    if (failed.length > 0) {
+      stderr.write("\nSome repairs failed:\n");
+      for (const fail of failed) {
+        stderr.write(`  ! ${fail}\n`);
+      }
+      stderr.write(
+        `\nTry deleting the database and restarting: rm ${dbPath}\n`
+      );
+      proc.exitCode = 1;
+      return;
+    }
+
+    stdout.write("\nDatabase repaired successfully.\n");
+  },
+});

src/commands/cli/index.ts

@@ -1,16 +1,18 @@
 import { buildRouteMap } from "@stricli/core";
 import { feedbackCommand } from "./feedback.js";
+import { fixCommand } from "./fix.js";
 import { upgradeCommand } from "./upgrade.js";
 
 export const cliRoute = buildRouteMap({
   routes: {
     feedback: feedbackCommand,
+    fix: fixCommand,
     upgrade: upgradeCommand,
   },
   docs: {
     brief: "CLI-related commands",
     fullDescription:
-      "Commands for managing the Sentry CLI itself, including sending feedback " +
-      "and upgrading to newer versions.",
+      "Commands for managing the Sentry CLI itself, including sending feedback, " +
+      "upgrading to newer versions, and repairing the local database.",
   },
 });

src/lib/db/index.ts

@@ -22,7 +22,10 @@ const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Probability of running cleanup on write operations */
 const CLEANUP_PROBABILITY = 0.1;
 
+/** Traced database wrapper (returned by getDatabase) */
 let db: Database | null = null;
+/** Raw database without tracing (used for repair operations) */
+let rawDb: Database | null = null;
 let dbOpenedPath: string | null = null;
 
 export function getConfigDir(): string {
@@ -69,6 +72,7 @@ export function getDatabase(): Database {
   if (db && dbOpenedPath !== dbPath) {
     db.close();
     db = null;
+    rawDb = null;
     dbOpenedPath = null;
   }
 
@@ -78,39 +82,64 @@ export function getDatabase(): Database {
 
   ensureConfigDir();
 
-  const rawDb = new Database(dbPath);
+  rawDb = new Database(dbPath);
 
-  // 5000ms busy_timeout prevents SQLITE_BUSY errors during concurrent CLI access.
-  // When multiple CLI instances run simultaneously (e.g., parallel terminals, CI jobs),
-  // SQLite needs time to acquire locks. WAL mode allows concurrent reads, but writers
-  // must wait. Without sufficient timeout, concurrent processes fail immediately.
-  // Set busy_timeout FIRST - before WAL mode - to handle lock contention during init.
-  rawDb.exec("PRAGMA busy_timeout = 5000");
-  rawDb.exec("PRAGMA journal_mode = WAL");
-  rawDb.exec("PRAGMA foreign_keys = ON");
-  rawDb.exec("PRAGMA synchronous = NORMAL");
-
-  setDbPermissions();
-  initSchema(rawDb);
-  runMigrations(rawDb);
-  migrateFromJson(rawDb);
-
-  // Wrap with tracing proxy for automatic query instrumentation
-  db = createTracedDatabase(rawDb);
-  dbOpenedPath = dbPath;
+  try {
+    // 5000ms busy_timeout prevents SQLITE_BUSY errors during concurrent CLI access.
+    // When multiple CLI instances run simultaneously (e.g., parallel terminals, CI jobs),
+    // SQLite needs time to acquire locks. WAL mode allows concurrent reads, but writers
+    // must wait. Without sufficient timeout, concurrent processes fail immediately.
+    // Set busy_timeout FIRST - before WAL mode - to handle lock contention during init.
+    rawDb.exec("PRAGMA busy_timeout = 5000");
+    rawDb.exec("PRAGMA journal_mode = WAL");
+    rawDb.exec("PRAGMA foreign_keys = ON");
+    rawDb.exec("PRAGMA synchronous = NORMAL");
+
+    setDbPermissions();
+    initSchema(rawDb);
+    runMigrations(rawDb);
+    migrateFromJson(rawDb);
+
+    // Wrap with tracing proxy for automatic query instrumentation
+    db = createTracedDatabase(rawDb);
+    dbOpenedPath = dbPath;
 
-  return db;
+    return db;
+  } catch (error) {
+    // Clean up on initialization failure to prevent connection leak
+    rawDb.close();
+    rawDb = null;
+    throw error;
+  }
 }
 
 /** Close the database connection (used for testing). */
 export function closeDatabase(): void {
   if (db) {
     db.close();
     db = null;
+    rawDb = null;
     dbOpenedPath = null;
   }
 }
 
+/**
+ * Get the raw (unwrapped) database connection.
+ * Used for repair operations to avoid triggering the traced wrapper's
+ * auto-repair logic (which would cause infinite loops).
+ */
+export function getRawDatabase(): Database {
+  if (!rawDb) {
+    // Ensure database is initialized
+    getDatabase();
+  }
+  // After getDatabase() call, rawDb is guaranteed to be set
+  if (!rawDb) {
+    throw new Error("Database initialization failed");
+  }
+  return rawDb;
+}
+
 function shouldRunCleanup(): boolean {
   return Math.random() < CLEANUP_PROBABILITY;
 }