@drewpayment/mink 0.11.0-beta.4 → 0.12.0-beta.1

package/src/storage/db.ts

@@ -0,0 +1,121 @@
+// Project database lifecycle. The handle is opened lazily and cached per
+// process (hook commands are short-lived; their first call to a repository
+// triggers the open, and the handle is closed via the registered exit hook).
+//
+// On first open for a project that has on-disk JSON state, the lazy JSON
+// importer runs (see `migrate-json.ts`). The importer is idempotent — once
+// `meta.migrated_from_json_at` is set, it returns immediately.
+
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { projectDbPath } from "../core/paths";
+import { openDriver, type DbDriver } from "./driver";
+import { applySchema } from "./schema";
+import { migrateJsonIfNeeded } from "./migrate-json";
+
+export { projectDbPath } from "../core/paths";
+
+interface ConnectionEntry {
+  driver: DbDriver;
+  closed: boolean;
+}
+
+const handles = new Map<string, ConnectionEntry>();
+let exitHookInstalled = false;
+
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  const closeAll = (): void => {
+    for (const entry of handles.values()) {
+      if (entry.closed) continue;
+      try {
+        entry.driver.close();
+      } catch {
+        // best effort — process is shutting down
+      }
+      entry.closed = true;
+    }
+  };
+  process.on("exit", closeAll);
+}
+
+// Test-only — drop cached handles between tests that wipe MINK_ROOT_OVERRIDE.
+// Production code never calls this; the exit hook handles real shutdown.
+export function _resetDbCacheForTests(): void {
+  for (const entry of handles.values()) {
+    if (entry.closed) continue;
+    try {
+      entry.driver.close();
+    } catch {
+      // ignore
+    }
+    entry.closed = true;
+  }
+  handles.clear();
+}
+
+function applyPragmas(db: DbDriver): void {
+  // WAL: enables concurrent readers during a writer; survives crashes.
+  // synchronous=NORMAL: safe with WAL, ~2-5x faster than FULL.
+  // foreign_keys=ON: required for bug_tags / bug_related cascades.
+  // busy_timeout: matches the existing 5s hook safety timeout in
+  // src/core/runtime.ts — under contention SQLite will retry rather than
+  // throw SQLITE_BUSY immediately.
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 5000");
+}
+
+export function openProjectDb(cwd: string): DbDriver {
+  const path = projectDbPath(cwd);
+  const cached = handles.get(path);
+  if (cached && !cached.closed) return cached.driver;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const driver = openDriver(path);
+  applyPragmas(driver);
+  applySchema(driver);
+
+  // Run migration AFTER applySchema so the importer can write into existing
+  // tables. The importer no-ops once `meta.migrated_from_json_at` is set.
+  try {
+    migrateJsonIfNeeded(driver, cwd);
+  } catch (err) {
+    // Migration failures should not block the process — log and continue
+    // with an empty DB. Phase 2 callers will fall back to legacy JSON reads.
+    // (We rethrow for tests via MINK_DB_STRICT_MIGRATE=1.)
+    if (process.env.MINK_DB_STRICT_MIGRATE === "1") throw err;
+    console.warn(
+      `[mink] JSON → SQLite migration failed for ${cwd}: ${
+        (err as Error).message
+      }`
+    );
+  }
+
+  installExitHook();
+  handles.set(path, { driver, closed: false });
+  return driver;
+}
+
+// Force a WAL checkpoint and close the handle for the given cwd. Used by
+// `mink sync` before pushing so the .db is self-contained (the -wal/-shm
+// sidecars are not synced).
+export function checkpointAndClose(cwd: string): void {
+  const path = projectDbPath(cwd);
+  const entry = handles.get(path);
+  if (!entry || entry.closed) return;
+  try {
+    entry.driver.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  } catch {
+    // best effort
+  }
+  try {
+    entry.driver.close();
+  } catch {
+    // best effort
+  }
+  entry.closed = true;
+  handles.delete(path);
+}

package/src/storage/driver.bun.ts

@@ -0,0 +1,99 @@
+// bun:sqlite implementation of the DbDriver interface.
+// Selected at build time when MINK_RUNTIME === "bun" and via `typeof Bun`
+// detection when running unbundled.
+
+import type { DbDriver, DriverModule, SqlParam, Statement } from "./driver";
+
+// Use require() so the type-only import path doesn't trip Node when this
+// file is loaded under the wrong runtime by mistake (the runtime dispatcher
+// in driver.ts is supposed to prevent that).
+const { Database } = require("bun:sqlite") as typeof import("bun:sqlite");
+
+class BunStatement implements Statement {
+  constructor(private readonly stmt: import("bun:sqlite").Statement) {}
+
+  run(...params: SqlParam[]): { changes: number | bigint; lastInsertRowid: number | bigint } {
+    const r = this.stmt.run(...(params as never[]));
+    return { changes: r.changes, lastInsertRowid: r.lastInsertRowid };
+  }
+
+  get(...params: SqlParam[]) {
+    const row = this.stmt.get(...(params as never[]));
+    return (row ?? undefined) as Record<string, unknown> | undefined;
+  }
+
+  all(...params: SqlParam[]) {
+    return this.stmt.all(...(params as never[])) as Record<string, unknown>[];
+  }
+}
+
+class BunDriver implements DbDriver {
+  readonly filename: string;
+  private readonly db: import("bun:sqlite").Database;
+  private readonly txnDepth = { value: 0 };
+
+  constructor(filename: string) {
+    this.filename = filename;
+    this.db = new Database(filename, { create: true });
+  }
+
+  prepare(sql: string): Statement {
+    return new BunStatement(this.db.prepare(sql));
+  }
+
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  // We implement transactions manually (rather than using bun:sqlite's
+  // `db.transaction(fn)` wrapper) so semantics match node:sqlite exactly:
+  // synchronous, nestable via savepoints, IMMEDIATE locking to fail fast
+  // when another writer is mid-transaction.
+  transaction<T>(fn: () => T): T {
+    if (this.txnDepth.value > 0) {
+      const sp = `sp_${this.txnDepth.value}`;
+      this.db.exec(`SAVEPOINT ${sp}`);
+      this.txnDepth.value++;
+      try {
+        const result = fn();
+        this.db.exec(`RELEASE SAVEPOINT ${sp}`);
+        this.txnDepth.value--;
+        return result;
+      } catch (err) {
+        this.db.exec(`ROLLBACK TO SAVEPOINT ${sp}`);
+        this.db.exec(`RELEASE SAVEPOINT ${sp}`);
+        this.txnDepth.value--;
+        throw err;
+      }
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    this.txnDepth.value++;
+    try {
+      const result = fn();
+      this.db.exec("COMMIT");
+      this.txnDepth.value--;
+      return result;
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      this.txnDepth.value--;
+      throw err;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  pragma(stmt: string): unknown {
+    // bun:sqlite has no dedicated pragma() helper; route through exec/query.
+    // Pragmas that return a value (e.g. `journal_mode`) are SELECT-shaped.
+    if (/^[a-z_]+\s*=/i.test(stmt) || /^[a-z_]+\s*\([^)]*\)/i.test(stmt)) {
+      // Assignment or call form — no result expected, but the sqlite engine
+      // still returns the new value. Query so callers can read it.
+      return this.db.prepare(`PRAGMA ${stmt}`).all();
+    }
+    return this.db.prepare(`PRAGMA ${stmt}`).all();
+  }
+}
+
+export const open: DriverModule["open"] = (filename) => new BunDriver(filename);

package/src/storage/driver.node.ts

@@ -0,0 +1,107 @@
+// node:sqlite implementation of the DbDriver interface.
+// Selected at build time when MINK_RUNTIME === "node" and via runtime
+// detection when running unbundled under Node.
+
+import type { DbDriver, DriverModule, SqlParam, Statement } from "./driver";
+
+// Suppress Node 22's `ExperimentalWarning: SQLite is an experimental feature`
+// the first (and only) time the module is required. We do it inline rather
+// than via NODE_NO_WARNINGS so users don't lose warnings from other modules.
+const originalEmit = process.emit;
+process.emit = function patchedEmit(
+  this: NodeJS.Process,
+  event: string | symbol,
+  ...args: unknown[]
+): boolean {
+  if (
+    event === "warning" &&
+    args[0] instanceof Error &&
+    (args[0] as Error & { name: string }).name === "ExperimentalWarning" &&
+    /sqlite/i.test((args[0] as Error).message)
+  ) {
+    return false;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (originalEmit as any).call(this, event, ...args);
+} as typeof process.emit;
+
+const { DatabaseSync } = require("node:sqlite") as typeof import("node:sqlite");
+
+class NodeStatement implements Statement {
+  // node:sqlite uses StatementSync from its types
+  constructor(private readonly stmt: import("node:sqlite").StatementSync) {}
+
+  run(...params: SqlParam[]): { changes: number | bigint; lastInsertRowid: number | bigint } {
+    const r = this.stmt.run(...(params as never[]));
+    return { changes: r.changes, lastInsertRowid: r.lastInsertRowid };
+  }
+
+  get(...params: SqlParam[]) {
+    const row = this.stmt.get(...(params as never[]));
+    return (row ?? undefined) as Record<string, unknown> | undefined;
+  }
+
+  all(...params: SqlParam[]) {
+    return this.stmt.all(...(params as never[])) as Record<string, unknown>[];
+  }
+}
+
+class NodeDriver implements DbDriver {
+  readonly filename: string;
+  private readonly db: import("node:sqlite").DatabaseSync;
+  private readonly txnDepth = { value: 0 };
+
+  constructor(filename: string) {
+    this.filename = filename;
+    this.db = new DatabaseSync(filename);
+  }
+
+  prepare(sql: string): Statement {
+    return new NodeStatement(this.db.prepare(sql));
+  }
+
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  transaction<T>(fn: () => T): T {
+    if (this.txnDepth.value > 0) {
+      const sp = `sp_${this.txnDepth.value}`;
+      this.db.exec(`SAVEPOINT ${sp}`);
+      this.txnDepth.value++;
+      try {
+        const result = fn();
+        this.db.exec(`RELEASE SAVEPOINT ${sp}`);
+        this.txnDepth.value--;
+        return result;
+      } catch (err) {
+        this.db.exec(`ROLLBACK TO SAVEPOINT ${sp}`);
+        this.db.exec(`RELEASE SAVEPOINT ${sp}`);
+        this.txnDepth.value--;
+        throw err;
+      }
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    this.txnDepth.value++;
+    try {
+      const result = fn();
+      this.db.exec("COMMIT");
+      this.txnDepth.value--;
+      return result;
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      this.txnDepth.value--;
+      throw err;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  pragma(stmt: string): unknown {
+    return this.db.prepare(`PRAGMA ${stmt}`).all();
+  }
+}
+
+export const open: DriverModule["open"] = (filename) => new NodeDriver(filename);

package/src/storage/driver.ts

@@ -0,0 +1,76 @@
+// Build-time-selected SQLite driver adapter. The actual import of
+// `bun:sqlite` or `node:sqlite` happens in the runtime-specific
+// `driver.bun.ts` / `driver.node.ts` siblings; this file picks one based on
+// the `MINK_RUNTIME` define injected by `bun build --define`. When neither
+// define is set (e.g. running TypeScript directly under `bun test`), it
+// falls back to `typeof Bun` detection.
+//
+// The adapter exposes a stable 5-method surface — `prepare`, `exec`,
+// `transaction`, `close`, `pragma` — chosen as the minimal set that covers
+// every call site in `src/repositories/`. Both backends' `Statement.run/get/all`
+// methods are compatible enough that we pass them through unchanged.
+
+declare const MINK_RUNTIME: string | undefined;
+
+export type SqlParam = string | number | bigint | Uint8Array | null;
+export type SqlRow = Record<string, unknown>;
+
+export interface Statement {
+  run(...params: SqlParam[]): { changes: number | bigint; lastInsertRowid: number | bigint };
+  get(...params: SqlParam[]): SqlRow | undefined;
+  all(...params: SqlParam[]): SqlRow[];
+  iterate?(...params: SqlParam[]): IterableIterator<SqlRow>;
+}
+
+export interface DbDriver {
+  prepare(sql: string): Statement;
+  exec(sql: string): void;
+  transaction<T>(fn: () => T): T;
+  close(): void;
+  pragma(stmt: string): unknown;
+  readonly filename: string;
+}
+
+export interface DriverModule {
+  open(filename: string): DbDriver;
+}
+
+function pickRuntime(): "bun" | "node" {
+  // `MINK_RUNTIME` is replaced at bundle time. When running source directly
+  // (tests, `bun src/cli.ts`), the symbol is undefined and we fall back to
+  // feature detection.
+  try {
+    if (typeof MINK_RUNTIME !== "undefined") {
+      if (MINK_RUNTIME === "bun" || MINK_RUNTIME === "node") return MINK_RUNTIME;
+    }
+  } catch {
+    // ReferenceError when the symbol is not declared — proceed to detect.
+  }
+  return typeof Bun !== "undefined" ? "bun" : "node";
+}
+
+let cached: DriverModule | undefined;
+
+function loadDriver(): DriverModule {
+  if (cached) return cached;
+  const runtime = pickRuntime();
+  // Conditional `require` keeps the unused branch out of the active bundle
+  // when `bun build` does constant-folding on `pickRuntime()`'s result via
+  // the `MINK_RUNTIME` define. At runtime, only the matching branch ever
+  // executes, so the other module's `import 'bun:sqlite'` /
+  // `import 'node:sqlite'` is never evaluated.
+  if (runtime === "bun") {
+    cached = require("./driver.bun") as DriverModule;
+  } else {
+    cached = require("./driver.node") as DriverModule;
+  }
+  return cached;
+}
+
+export function openDriver(filename: string): DbDriver {
+  return loadDriver().open(filename);
+}
+
+export function currentRuntime(): "bun" | "node" {
+  return pickRuntime();
+}