trekoon 0.4.0 → 0.4.2

package/src/storage/backup.ts

@@ -0,0 +1,166 @@
+import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { Database } from "bun:sqlite";
+
+import { DomainError } from "../domain/types";
+import { LATEST_MIGRATION_VERSION, readCurrentMigrationVersionReadOnly } from "./migrations";
+import { resolveStoragePaths } from "./path";
+
+export interface MigrateBackupResult {
+  readonly backupPath: string;
+  readonly bytes: number;
+  readonly migrationVersion: number;
+  readonly latestVersion: number;
+  readonly timestamp: string;
+  readonly retainedCount: number;
+  readonly prunedPaths: readonly string[];
+}
+
+/** Default retention count when --retain is not provided. */
+export const DEFAULT_BACKUP_RETENTION = 10;
+
+/** Filename prefix shared by every backup snapshot. */
+const BACKUP_FILENAME_PREFIX = "trekoon.db.backup-";
+
+function isoTimestampForFilename(now: Date): string {
+  // ISO 8601 with colons and dots replaced for filesystem-safe use across
+  // macOS/Linux/Windows. Resolution is millisecond-precise so two backups in
+  // the same second still produce distinct filenames.
+  // Example input: 2026-05-02T13:45:30.123Z -> 2026-05-02T13-45-30-123Z
+  return now.toISOString().replace(/[:.]/gu, "-");
+}
+
+function quoteForVacuumInto(filePath: string): string {
+  // SQLite path literal: wrap in single quotes and escape embedded single quotes by doubling.
+  return `'${filePath.replace(/'/gu, "''")}'`;
+}
+
+interface CreateMigrationBackupOptions {
+  readonly cwd: string;
+  readonly now?: Date;
+  /**
+   * Maximum number of timestamped backup siblings to retain (including the
+   * one being created). Older snapshots are pruned. Defaults to
+   * {@link DEFAULT_BACKUP_RETENTION}. Pass `Infinity` or any non-positive
+   * number to disable pruning.
+   */
+  readonly retain?: number;
+}
+
+interface ListedBackup {
+  readonly filename: string;
+  readonly fullPath: string;
+}
+
+function listExistingBackups(storageDir: string): ListedBackup[] {
+  if (!existsSync(storageDir)) {
+    return [];
+  }
+
+  return readdirSync(storageDir)
+    .filter((entry) => entry.startsWith(BACKUP_FILENAME_PREFIX))
+    .map((entry) => ({ filename: entry, fullPath: resolve(storageDir, entry) }));
+}
+
+function pruneOlderBackups(storageDir: string, keepCount: number): string[] {
+  if (!Number.isFinite(keepCount) || keepCount <= 0) {
+    return [];
+  }
+
+  const existing = listExistingBackups(storageDir);
+  if (existing.length <= keepCount) {
+    return [];
+  }
+
+  // Filename suffix is a millisecond-precise ISO timestamp, so a lexicographic
+  // sort is equivalent to chronological order. Most-recent first.
+  const sorted = [...existing].sort((left, right) => {
+    if (left.filename < right.filename) {
+      return 1;
+    }
+    if (left.filename > right.filename) {
+      return -1;
+    }
+    return 0;
+  });
+
+  const toPrune = sorted.slice(keepCount);
+  const pruned: string[] = [];
+
+  for (const candidate of toPrune) {
+    try {
+      unlinkSync(candidate.fullPath);
+      pruned.push(candidate.fullPath);
+    } catch {
+      // Best-effort prune: a transient unlink failure (concurrent backup,
+      // permissions, etc.) must not abort the surrounding backup operation.
+    }
+  }
+
+  return pruned;
+}
+
+export function createMigrationBackup(options: CreateMigrationBackupOptions): MigrateBackupResult {
+  const cwd: string = options.cwd;
+  const now: Date = options.now ?? new Date();
+  const retainRaw: number = options.retain ?? DEFAULT_BACKUP_RETENTION;
+  const retainCount: number =
+    Number.isFinite(retainRaw) && retainRaw > 0 ? Math.floor(retainRaw) : Number.POSITIVE_INFINITY;
+  const storagePaths = resolveStoragePaths(cwd);
+  const databaseFile: string = storagePaths.databaseFile;
+
+  if (!existsSync(databaseFile)) {
+    throw new DomainError({
+      code: "backup_database_missing",
+      message: `Cannot back up Trekoon database: ${databaseFile} does not exist. Run 'trekoon init' first.`,
+      details: { databaseFile },
+    });
+  }
+
+  const timestamp: string = isoTimestampForFilename(now);
+  const storageDir: string = dirname(databaseFile);
+  const backupFilename = `${BACKUP_FILENAME_PREFIX}${timestamp}`;
+  const backupPath: string = resolve(storageDir, backupFilename);
+
+  if (existsSync(backupPath)) {
+    throw new DomainError({
+      code: "backup_already_exists",
+      message:
+        `Backup already exists at ${backupPath}. ` +
+        `Backup filenames are millisecond-precise; two backups can only collide ` +
+        `when the same explicit timestamp is reused. Wait at least one millisecond ` +
+        `between backups or pass a distinct now/timestamp.`,
+      details: { backupPath },
+    });
+  }
+
+  // VACUUM INTO writes a fully-consistent snapshot at a single transaction
+  // boundary, including any uncommitted WAL state once the read transaction
+  // is taken. This is the SQLite-recommended way to atomically clone a DB.
+  // Open read-only so we never mutate the live DB while snapshotting.
+  const sourceDb = new Database(databaseFile, { readonly: true });
+  let migrationVersion = 0;
+  const latestVersion: number = LATEST_MIGRATION_VERSION;
+  try {
+    migrationVersion = readCurrentMigrationVersionReadOnly(sourceDb);
+    sourceDb.exec(`VACUUM INTO ${quoteForVacuumInto(backupPath)};`);
+  } finally {
+    sourceDb.close(false);
+  }
+
+  const stats = statSync(backupPath);
+
+  const prunedPaths: readonly string[] = pruneOlderBackups(storageDir, retainCount);
+  const retainedCount: number = listExistingBackups(storageDir).length;
+
+  return {
+    backupPath,
+    bytes: stats.size,
+    migrationVersion,
+    latestVersion,
+    timestamp,
+    retainedCount,
+    prunedPaths,
+  };
+}

package/src/storage/database.ts

@@ -1,16 +1,55 @@
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 
 import { Database } from "bun:sqlite";
 
 import { DomainError } from "../domain/types";
-import { migrateDatabase } from "./migrations";
-import { resolveStoragePaths, type StoragePaths } from "./path";
+import { LATEST_MIGRATION_VERSION, migrateDatabase, readCurrentMigrationVersionReadOnly } from "./migrations";
+import { resolveLegacyWorktreeDatabaseFile, resolveStoragePaths, type StoragePaths } from "./path";
 import {
   inspectWorktreeDatabaseState,
   recoverWorktreeDatabaseState,
   type WorktreeRecoveryDiagnostics,
 } from "./worktree-recovery";
 
+/**
+ * Re-inspect worktree state on a daemon-mode cache hit so out-of-band changes
+ * to the worktree (e.g. an operator restoring a legacy `.trekoon/trekoon.db`
+ * after the daemon started, or a new tracked-vs-ignored conflict) surface to
+ * the caller through `diagnostics.recoveryRequired` instead of being masked
+ * by the cached handle's stale snapshot. Returns NO_LEGACY_RECOVERY when the
+ * fast-path no-legacy-DB shortcut applies and falls back to the
+ * DomainError-aware capture used by `resolveStorageResolutionDiagnostics`
+ * when inspection itself raises (e.g. tracked_ignored_mismatch).
+ */
+function reinspectRecoveryForCacheHit(paths: StoragePaths): WorktreeRecoveryDiagnostics {
+  const legacyDbFile: string = resolveLegacyWorktreeDatabaseFile(paths.worktreeRoot);
+  if (legacyDbFile !== paths.databaseFile && !existsSync(legacyDbFile)) {
+    return NO_LEGACY_RECOVERY;
+  }
+
+  try {
+    return inspectWorktreeDatabaseState(paths);
+  } catch (error) {
+    if (!(error instanceof DomainError)) {
+      throw error;
+    }
+    const details: Record<string, unknown> = error.details ?? {};
+    return {
+      status: (details.status as WorktreeRecoveryDiagnostics["status"] | undefined) ?? "no_legacy_state",
+      legacyDatabaseFiles: Array.isArray(details.legacyDatabaseFiles)
+        ? (details.legacyDatabaseFiles as string[])
+        : [],
+      backupFiles: Array.isArray(details.backupFiles) ? (details.backupFiles as string[]) : [],
+      trackedStorageFiles: Array.isArray(details.trackedStorageFiles)
+        ? (details.trackedStorageFiles as string[])
+        : [],
+      autoMigrated: details.autoMigrated === true,
+      importedFrom: typeof details.importedFrom === "string" ? details.importedFrom : null,
+      operatorAction: typeof details.operatorAction === "string" ? details.operatorAction : error.message,
+    };
+  }
+}
+
 export interface StorageResolutionDiagnostics {
   readonly invocationCwd: string;
   readonly storageMode: StoragePaths["storageMode"];
@@ -140,12 +179,208 @@ export function writeTransaction<T>(db: Database, fn: (db: Database) => T): T {
   }
 }
 
+/** Sentinel recovery result for the common case: no legacy worktree DB present. */
+const NO_LEGACY_RECOVERY: WorktreeRecoveryDiagnostics = {
+  status: "no_legacy_state",
+  legacyDatabaseFiles: [],
+  backupFiles: [],
+  trackedStorageFiles: [],
+  autoMigrated: false,
+  importedFrom: null,
+  operatorAction: "No legacy worktree-local database detected.",
+};
+
+/**
+ * Process-level cache of opened TrekoonDatabase handles. Enabled only when
+ * `TREKOON_DAEMON_INPROCESS=1` is set (the daemon spike sets this on startup).
+ * In normal one-shot CLI invocations this map stays empty and the cache layer
+ * is bypassed entirely, so default behavior is unchanged.
+ *
+ * Cached handles override `close()` so callers that follow the
+ * `try { ... } finally { db?.close(); }` pattern do not actually tear down
+ * the shared connection — instead, `close()` decrements an in-use refcount.
+ * The daemon shutdown path calls `closeCachedDatabases()`.
+ *
+ * The cache is bounded LRU (insertion-order on Map; touched on access) so a
+ * long-running daemon serving many distinct cwds does not accumulate open
+ * SQLite connections / FDs without bound. Eviction closes the underlying
+ * database after a passive WAL checkpoint.
+ *
+ * In-use protection: each `openTrekoonDatabase` call increments the entry's
+ * refcount; the matching `close()` decrements it. Eviction skips entries
+ * whose refcount is > 0 — closing them mid-query would surface as
+ * SQLITE_MISUSE on the in-flight handler. If every cached entry is in use
+ * when a new cwd is opened, we permit temporary growth past the cap and
+ * emit a single warning; the next eviction-check after a `close()` will
+ * reduce the cache back under the cap.
+ */
+const CACHED_DATABASES_CAPACITY = 16;
+
+interface CachedEntry {
+  readonly handle: TrekoonDatabase;
+  refcount: number;
+}
+
+const cachedDatabases: Map<string, CachedEntry> = new Map();
+let warnedOnTransientOvergrowth = false;
+
+function isDaemonInProcessCacheEnabled(): boolean {
+  return process.env.TREKOON_DAEMON_INPROCESS === "1";
+}
+
+function closeCachedHandle(handle: TrekoonDatabase): void {
+  try {
+    handle.db.exec("PRAGMA wal_checkpoint(PASSIVE);");
+  } catch {
+    /* best effort */
+  }
+  try {
+    handle.db.close(false);
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Evict the least-recently-used handle when the cache is at capacity. Map
+ * iteration order in JS is insertion order; we re-insert on access (`touch`)
+ * to model LRU semantics. Entries whose refcount is > 0 are SKIPPED — closing
+ * an in-use handle would surface as SQLITE_MISUSE for the caller currently
+ * borrowing it. A subsequent `releaseCachedDatabase` after the caller's
+ * `close()` will re-run eviction so transient over-cap growth is bounded by
+ * the number of concurrently-borrowed entries, which is in practice tiny.
+ */
+function evictLruIfNeeded(): void {
+  while (cachedDatabases.size >= CACHED_DATABASES_CAPACITY) {
+    let evicted = false;
+    for (const [key, entry] of cachedDatabases) {
+      if (entry.refcount > 0) {
+        continue;
+      }
+      cachedDatabases.delete(key);
+      closeCachedHandle(entry.handle);
+      evicted = true;
+      break;
+    }
+
+    if (!evicted) {
+      // Every cached entry is currently borrowed. Allow temporary growth
+      // past the cap rather than closing an in-use handle. Surface a single
+      // warning so an operator can spot pathological concurrency.
+      if (!warnedOnTransientOvergrowth) {
+        warnedOnTransientOvergrowth = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[trekoon daemon] all ${CACHED_DATABASES_CAPACITY} cached database handles are in use; temporarily growing cache past the cap`,
+        );
+      }
+      return;
+    }
+  }
+}
+
+function touchCachedDatabase(key: string, entry: CachedEntry): void {
+  // Re-insert to move to the most-recently-used (tail) end of insertion order.
+  cachedDatabases.delete(key);
+  cachedDatabases.set(key, entry);
+}
+
+/**
+ * Decrement the refcount for a cached entry. Called from the cached handle's
+ * `close()` method. After a release, re-run eviction in case the cache had
+ * grown past the cap because every entry was borrowed.
+ */
+function releaseCachedDatabase(key: string): void {
+  const entry = cachedDatabases.get(key);
+  if (!entry) {
+    return;
+  }
+  if (entry.refcount > 0) {
+    entry.refcount -= 1;
+  }
+  if (cachedDatabases.size > CACHED_DATABASES_CAPACITY) {
+    evictLruIfNeeded();
+  }
+}
+
+export function closeCachedDatabases(): void {
+  for (const entry of cachedDatabases.values()) {
+    closeCachedHandle(entry.handle);
+  }
+  cachedDatabases.clear();
+  warnedOnTransientOvergrowth = false;
+}
+
+/**
+ * Test-only: report the current size of the daemon-mode database cache.
+ * Production code never inspects this — used by `tests/runtime/cache-bound`.
+ */
+export function cachedDatabasesSize(): number {
+  return cachedDatabases.size;
+}
+
 export function openTrekoonDatabase(
   workingDirectory: string = process.cwd(),
   options: OpenTrekoonDatabaseOptions = {},
 ): TrekoonDatabase {
   const paths: StoragePaths = resolveStoragePaths(workingDirectory);
-  const recovery: WorktreeRecoveryDiagnostics = recoverWorktreeDatabaseState(paths);
+
+  // Daemon-mode reuse: when running inside `trekoon serve`, return a cached
+  // connection so each request avoids the migration probe and database open.
+  if (isDaemonInProcessCacheEnabled()) {
+    const cachedEntry = cachedDatabases.get(paths.databaseFile);
+    if (cachedEntry) {
+      // Honor autoMigrate on the cached-handle path: a previous request that
+      // opened this DB with `{autoMigrate: false}` (e.g. migrate-status) may
+      // have left the schema below LATEST_MIGRATION_VERSION. The next request
+      // that asks for autoMigrate (the default) must still get a migrated DB.
+      if (
+        (options.autoMigrate ?? true)
+        && readCurrentMigrationVersionReadOnly(cachedEntry.handle.db) < LATEST_MIGRATION_VERSION
+      ) {
+        migrateDatabase(cachedEntry.handle.db);
+      }
+
+      // Re-inspect worktree state on every cache hit so out-of-band changes
+      // (legacy DB restored after daemon start, fresh tracked/ignored
+      // mismatch, etc.) surface to callers through fresh diagnostics. The
+      // cached `handle.diagnostics` is a frozen snapshot from the original
+      // open and would otherwise mask a freshly-required recovery — leading
+      // `session` and friends to silently proceed against a stale state.
+      const refreshedRecovery: WorktreeRecoveryDiagnostics = reinspectRecoveryForCacheHit(paths);
+      const refreshedDiagnostics: StorageResolutionDiagnostics =
+        buildStorageResolutionDiagnostics(paths, refreshedRecovery);
+
+      // Refresh LRU position on access and increment the in-use refcount so
+      // `evictLruIfNeeded` cannot close this entry under the borrower.
+      cachedEntry.refcount += 1;
+      touchCachedDatabase(paths.databaseFile, cachedEntry);
+
+      const cacheKey: string = paths.databaseFile;
+      // Return a per-request handle wrapper that exposes the refreshed
+      // diagnostics while sharing the underlying connection. The wrapper's
+      // close() releases the same cache key the cached entry's close()
+      // does, so refcount accounting stays consistent regardless of which
+      // handle the caller holds.
+      return {
+        db: cachedEntry.handle.db,
+        paths: cachedEntry.handle.paths,
+        diagnostics: refreshedDiagnostics,
+        close(): void {
+          releaseCachedDatabase(cacheKey);
+        },
+      };
+    }
+  }
+
+  // Fast path: if no legacy .trekoon/trekoon.db exists in the current worktree,
+  // skip the git-heavy recoverWorktreeDatabaseState entirely.
+  const legacyDbFile: string = resolveLegacyWorktreeDatabaseFile(paths.worktreeRoot);
+  const recovery: WorktreeRecoveryDiagnostics =
+    legacyDbFile !== paths.databaseFile && !existsSync(legacyDbFile)
+      ? NO_LEGACY_RECOVERY
+      : recoverWorktreeDatabaseState(paths);
+
   const diagnostics: StorageResolutionDiagnostics = buildStorageResolutionDiagnostics(paths, recovery);
 
   mkdirSync(paths.storageDir, { recursive: true });
@@ -160,6 +395,28 @@ export function openTrekoonDatabase(
     migrateDatabase(db);
   }
 
+  if (isDaemonInProcessCacheEnabled()) {
+    const cacheKey: string = paths.databaseFile;
+    const cachedHandle: TrekoonDatabase = {
+      db,
+      paths,
+      diagnostics,
+      close(): void {
+        // The daemon owns the lifetime (freed via closeCachedDatabases()), but
+        // we still need to track in-use refcount so eviction does not close a
+        // handle that an in-flight request is still using.
+        releaseCachedDatabase(cacheKey);
+      },
+    };
+    // Bound the cache before insertion so a daemon serving many distinct
+    // cwds doesn't accumulate open FDs without limit. Eviction will skip
+    // entries that other requests are currently borrowing.
+    evictLruIfNeeded();
+    // Initial refcount = 1 reflects the borrow taken by THIS caller.
+    cachedDatabases.set(cacheKey, { handle: cachedHandle, refcount: 1 });
+    return cachedHandle;
+  }
+
   return {
     db,
     paths,