trekoon 0.2.0 → 0.2.4

package/src/storage/worktree-recovery.ts

@@ -0,0 +1,376 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+
+import { DomainError } from "../domain/types";
+import {
+  resolveLegacyWorktreeDatabaseFile,
+  TREKOON_DATABASE_FILENAME,
+  type StoragePaths,
+} from "./path";
+
+function formatShellPath(filePath: string): string {
+  return `'${filePath.replaceAll("'", `'\\''`)}'`;
+}
+
+function formatSqliteDotCommandPath(filePath: string): string {
+  return `"${filePath.replaceAll('"', '""')}"`;
+}
+
+export type WorktreeRecoveryStatus =
+  | "no_legacy_state"
+  | "safe_auto_migrate"
+  | "ambiguous_recovery"
+  | "tracked_ignored_mismatch";
+
+export interface WorktreeRecoveryDiagnostics {
+  readonly status: WorktreeRecoveryStatus;
+  readonly legacyDatabaseFiles: readonly string[];
+  readonly backupFiles: readonly string[];
+  readonly trackedStorageFiles: readonly string[];
+  readonly autoMigrated: boolean;
+  readonly importedFrom: string | null;
+  readonly operatorAction: string;
+}
+
+interface WorktreeRecoveryOptions {
+  readonly applyRecovery?: boolean;
+}
+
+function readGitLines(workingDirectory: string, args: readonly string[]): string[] {
+  const result = spawnSync("git", args, {
+    cwd: workingDirectory,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+
+  if (result.status !== 0) {
+    return [];
+  }
+
+  const stdout: string = typeof result.stdout === "string" ? result.stdout : "";
+
+  return stdout
+    .split(/\r?\n/u)
+    .map((line: string) => line.trim())
+    .filter((line: string) => line.length > 0);
+}
+
+function listWorktreeRoots(paths: StoragePaths): string[] {
+  if (paths.repoCommonDir === null) {
+    return [paths.worktreeRoot];
+  }
+
+  const lines = readGitLines(paths.worktreeRoot, ["worktree", "list", "--porcelain"]);
+  const worktreeRoots = new Set<string>();
+
+  for (const line of lines) {
+    if (!line.startsWith("worktree ")) {
+      continue;
+    }
+
+    const rawPath: string = line.slice("worktree ".length).trim();
+    if (!rawPath) {
+      continue;
+    }
+
+    try {
+      worktreeRoots.add(realpathSync(rawPath));
+    } catch {
+      worktreeRoots.add(resolve(rawPath));
+    }
+  }
+
+  if (worktreeRoots.size === 0) {
+    worktreeRoots.add(paths.worktreeRoot);
+  }
+
+  return [...worktreeRoots];
+}
+
+function listTrackedStorageFiles(paths: StoragePaths): string[] {
+  if (paths.repoCommonDir === null) {
+    return [];
+  }
+
+  const trackedFiles = new Set<string>();
+
+  for (const worktreeRoot of listWorktreeRoots(paths)) {
+    for (const entry of readGitLines(worktreeRoot, ["ls-files", "--cached", "--", ".trekoon"])) {
+      trackedFiles.add(resolve(worktreeRoot, entry));
+    }
+  }
+
+  return [...trackedFiles].sort();
+}
+
+function listLegacyDatabaseFiles(paths: StoragePaths): string[] {
+  const files = new Set<string>();
+
+  for (const worktreeRoot of listWorktreeRoots(paths)) {
+    const legacyDatabaseFile: string = resolveLegacyWorktreeDatabaseFile(worktreeRoot);
+    if (legacyDatabaseFile === paths.databaseFile || !existsSync(legacyDatabaseFile)) {
+      continue;
+    }
+
+    files.add(legacyDatabaseFile);
+  }
+
+  return [...files].sort();
+}
+
+function fingerprintDatabaseFile(filePath: string): string {
+  const dumpResult = spawnSync("sqlite3", [filePath, ".dump"], {
+    cwd: dirname(filePath),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+
+  if (dumpResult.status === 0 && typeof dumpResult.stdout === "string") {
+    return createHash("sha256").update(dumpResult.stdout).digest("hex");
+  }
+
+  const content = readFileSync(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function createBackupFilePath(filePath: string): string {
+  const maxAttempts = 1000;
+  let attempt = 0;
+
+  while (attempt < maxAttempts) {
+    const suffix = attempt === 0 ? ".pre-shared-import.bak" : `.pre-shared-import.${attempt}.bak`;
+    const candidate = `${filePath}${suffix}`;
+    if (!existsSync(candidate)) {
+      return candidate;
+    }
+
+    attempt += 1;
+  }
+
+  throw new DomainError({
+    code: "legacy_import_failed",
+    message: `Unable to find available backup path after ${maxAttempts} attempts for ${filePath}`,
+  });
+}
+
+function createDatabaseSnapshot(sourcePath: string, targetPath: string): void {
+  const backupResult = spawnSync("sqlite3", [sourcePath, `.backup ${formatSqliteDotCommandPath(targetPath)}`], {
+    cwd: dirname(sourcePath),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (backupResult.status !== 0) {
+    const stderr: string = typeof backupResult.stderr === "string" ? backupResult.stderr.trim() : "";
+    const stdout: string = typeof backupResult.stdout === "string" ? backupResult.stdout.trim() : "";
+    const detail: string = stderr || stdout || `sqlite3 exited with status ${backupResult.status ?? "unknown"}`;
+
+    throw new DomainError({
+      code: "legacy_import_failed",
+      message: `Failed to snapshot legacy database state from ${sourcePath} to ${targetPath}: ${detail}`,
+    });
+  }
+}
+
+function backupLegacyDatabaseFile(filePath: string): string {
+  const backupPath: string = createBackupFilePath(filePath);
+  mkdirSync(dirname(backupPath), { recursive: true });
+  createDatabaseSnapshot(filePath, backupPath);
+  return backupPath;
+}
+
+function resolveTrackedFileWorktreeRoot(paths: StoragePaths, trackedFilePath: string): string {
+  const worktreeRoots: string[] = listWorktreeRoots(paths).sort(
+    (left: string, right: string) => right.length - left.length,
+  );
+
+  for (const worktreeRoot of worktreeRoots) {
+    if (trackedFilePath === worktreeRoot || trackedFilePath.startsWith(`${worktreeRoot}${sep}`)) {
+      return worktreeRoot;
+    }
+  }
+
+  return paths.worktreeRoot;
+}
+
+function formatTrackedMismatchAction(paths: StoragePaths, trackedStorageFiles: readonly string[]): string {
+  const commandsByWorktree = new Map<string, string[]>();
+
+  for (const trackedFilePath of trackedStorageFiles) {
+    const worktreeRoot: string = resolveTrackedFileWorktreeRoot(paths, trackedFilePath);
+    const relativeTrackedPath: string = relative(worktreeRoot, trackedFilePath);
+    const trackedPathsForWorktree: string[] = commandsByWorktree.get(worktreeRoot) ?? [];
+    trackedPathsForWorktree.push(relativeTrackedPath);
+    commandsByWorktree.set(worktreeRoot, trackedPathsForWorktree);
+  }
+
+  const suggestedCommands: string = [...commandsByWorktree.entries()]
+    .map(([worktreeRoot, trackedPaths]: [string, string[]]) => (
+      `git -C ${formatShellPath(worktreeRoot)} rm --cached -- ${trackedPaths
+        .map((trackedPath: string) => formatShellPath(trackedPath))
+        .join(" ")}`
+    ))
+    .join(" ; ");
+
+  return [
+    "Remove tracked .trekoon files from every worktree index before continuing.",
+    `Tracked path(s): ${trackedStorageFiles.map(formatShellPath).join(", ")}`,
+    `Suggested action: ${suggestedCommands}`,
+    "Commit the index cleanup, keep .trekoon ignored, then rerun trekoon init.",
+  ].join(" ");
+}
+
+function formatAmbiguousRecoveryAction(paths: StoragePaths, legacyFiles: readonly string[]): string {
+  const sharedDatabaseFile: string = paths.databaseFile;
+  const firstLegacyFile: string = legacyFiles[0] ?? resolveLegacyWorktreeDatabaseFile(paths.worktreeRoot);
+  const sharedDatabaseDirectory: string = dirname(sharedDatabaseFile);
+  const remainingLegacyFiles: string[] = legacyFiles.filter((filePath: string) => filePath !== firstLegacyFile);
+  const reconciliationStep: string = remainingLegacyFiles.length === 0
+    ? `After verifying ${sharedDatabaseFile}, remove the remaining divergent legacy database before rerunning trekoon init.`
+    : `After verifying ${sharedDatabaseFile}, remove or reconcile the other divergent legacy database files before rerunning trekoon init: ${remainingLegacyFiles.map(formatShellPath).join(", ")}.`;
+
+  return [
+    "Multiple divergent legacy databases were found.",
+    `Choose one source database, ensure ${sharedDatabaseDirectory} exists, then use sqlite3 .backup to create a WAL-safe snapshot at ${sharedDatabaseFile}.`,
+    `Example: mkdir -p ${formatShellPath(sharedDatabaseDirectory)} && sqlite3 ${formatShellPath(firstLegacyFile)} '.backup ${formatSqliteDotCommandPath(sharedDatabaseFile)}'`,
+    reconciliationStep,
+  ].join(" ");
+}
+
+function assertNoSplitState(
+  paths: StoragePaths,
+  legacyDatabaseFiles: readonly string[],
+  trackedStorageFiles: readonly string[],
+): void {
+  if (!existsSync(paths.databaseFile)) {
+    return;
+  }
+
+  const sharedFingerprint: string = fingerprintDatabaseFile(paths.databaseFile);
+  const divergentLegacyFiles: string[] = legacyDatabaseFiles.filter(
+    (legacyDatabaseFile: string) => fingerprintDatabaseFile(legacyDatabaseFile) !== sharedFingerprint,
+  );
+
+  if (divergentLegacyFiles.length === 0) {
+    return;
+  }
+
+  throw new DomainError({
+    code: "ambiguous_legacy_state",
+    message: "Shared storage conflicts with divergent legacy worktree databases.",
+    details: {
+      status: "ambiguous_recovery",
+      legacyDatabaseFiles,
+      trackedStorageFiles,
+      operatorAction: formatAmbiguousRecoveryAction(paths, divergentLegacyFiles),
+    },
+  });
+}
+
+export function recoverWorktreeDatabaseState(paths: StoragePaths): WorktreeRecoveryDiagnostics {
+  return inspectWorktreeDatabaseState(paths, { applyRecovery: true });
+}
+
+export function inspectWorktreeDatabaseState(
+  paths: StoragePaths,
+  options: WorktreeRecoveryOptions = {},
+): WorktreeRecoveryDiagnostics {
+  const applyRecovery: boolean = options.applyRecovery ?? false;
+  const trackedStorageFiles: string[] = listTrackedStorageFiles(paths);
+  const legacyDatabaseFiles: string[] = listLegacyDatabaseFiles(paths);
+
+  if (trackedStorageFiles.length > 0) {
+    throw new DomainError({
+      code: "tracked_ignored_mismatch",
+      message: "Tracked .trekoon files conflict with ignored shared storage.",
+      details: {
+        status: "tracked_ignored_mismatch",
+        legacyDatabaseFiles,
+        trackedStorageFiles,
+        operatorAction: formatTrackedMismatchAction(paths, trackedStorageFiles),
+      },
+    });
+  }
+
+  if (legacyDatabaseFiles.length === 0) {
+    return {
+      status: "no_legacy_state",
+      legacyDatabaseFiles,
+      backupFiles: [],
+      trackedStorageFiles,
+      autoMigrated: false,
+      importedFrom: null,
+      operatorAction: "No legacy worktree-local database detected.",
+    };
+  }
+
+  if (existsSync(paths.databaseFile)) {
+    assertNoSplitState(paths, legacyDatabaseFiles, trackedStorageFiles);
+
+    return {
+      status: "safe_auto_migrate",
+      legacyDatabaseFiles,
+      backupFiles: [],
+      trackedStorageFiles,
+      autoMigrated: false,
+      importedFrom: null,
+      operatorAction: "Shared database already exists and matches legacy worktree-local databases. Review and remove stale legacy worktree-local databases after verification.",
+    };
+  }
+
+  const distinctHashes: string[] = [...new Set(legacyDatabaseFiles.map(fingerprintDatabaseFile))];
+
+  if (distinctHashes.length !== 1) {
+    throw new DomainError({
+      code: "ambiguous_legacy_state",
+      message: "Multiple divergent legacy worktree databases require explicit recovery.",
+      details: {
+        status: "ambiguous_recovery",
+        legacyDatabaseFiles,
+        trackedStorageFiles,
+        operatorAction: formatAmbiguousRecoveryAction(paths, legacyDatabaseFiles),
+      },
+    });
+  }
+
+  const importSource: string | undefined = legacyDatabaseFiles[0];
+  if (importSource === undefined) {
+    throw new DomainError({
+      code: "legacy_import_failed",
+      message: "Legacy import could not determine a source database.",
+    });
+  }
+
+  if (!applyRecovery) {
+    return {
+      status: "safe_auto_migrate",
+      legacyDatabaseFiles,
+      backupFiles: [],
+      trackedStorageFiles,
+      autoMigrated: false,
+      importedFrom: null,
+      operatorAction: `Legacy worktree database can be imported into shared storage during init/open. Source: ${importSource}`,
+    };
+  }
+
+  const backupFiles: string[] = legacyDatabaseFiles.map(backupLegacyDatabaseFile);
+  mkdirSync(dirname(paths.databaseFile), { recursive: true });
+  createDatabaseSnapshot(importSource, paths.databaseFile);
+
+  return {
+    status: "safe_auto_migrate",
+    legacyDatabaseFiles,
+    backupFiles,
+    trackedStorageFiles,
+    autoMigrated: true,
+    importedFrom: importSource,
+    operatorAction: `Imported legacy worktree database into shared storage and backed up ${legacyDatabaseFiles.length} original file(s).`,
+  };
+}
+
+export function isLegacyDatabaseBackup(filePath: string): boolean {
+  return filePath.endsWith(`${TREKOON_DATABASE_FILENAME}.pre-shared-import.bak`)
+    || /\.pre-shared-import\.\d+\.bak$/u.test(filePath);
+}

package/src/sync/branch-db.ts

@@ -1,49 +1,101 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 
-import { Database } from "bun:sqlite";
+import { type Database } from "bun:sqlite";
 
-export interface BranchDatabaseSnapshot {
-  readonly branch: string;
-  readonly path: string;
-  readonly db: Database;
-  close(): void;
+import { DomainError } from "../domain/types";
+
+export interface BranchEventRow {
+  readonly id: string;
+  readonly entity_kind: string;
+  readonly entity_id: string;
+  readonly operation: string;
+  readonly payload: string;
+  readonly git_branch: string | null;
+  readonly git_head: string | null;
+  readonly created_at: number;
+  readonly updated_at: number;
+  readonly version: number;
 }
 
-export class MissingBranchDatabaseError extends Error {
-  constructor(branch: string) {
-    super(`Unable to read .trekoon/trekoon.db from branch '${branch}'.`);
-    this.name = "MissingBranchDatabaseError";
-  }
+interface ParsedCursorToken {
+  readonly createdAt: number;
+  readonly id: string | null;
+}
+
+function parseCursorToken(token: string): ParsedCursorToken {
+  const [createdAtRaw, idRaw] = token.split(":");
+  const createdAt: number = Number.parseInt(createdAtRaw ?? "0", 10);
+
+  return {
+    createdAt: Number.isFinite(createdAt) ? createdAt : 0,
+    id: idRaw && idRaw.length > 0 ? idRaw : null,
+  };
 }
 
-export function openBranchDatabaseSnapshot(branch: string, cwd: string): BranchDatabaseSnapshot {
-  const show = Bun.spawnSync({
-    cmd: ["git", "show", `${branch}:.trekoon/trekoon.db`],
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
+export function assertValidSourceRef(workingDirectory: string, sourceRef: string): void {
+  const verification = spawnSync("git", ["rev-parse", "--verify", "--quiet", `${sourceRef}^{commit}`], {
+    cwd: workingDirectory,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
   });
 
-  if (show.exitCode !== 0 || show.stdout.byteLength === 0) {
-    throw new MissingBranchDatabaseError(branch);
+  if (verification.status === 0) {
+    return;
   }
 
-  const tempDir: string = mkdtempSync(join(tmpdir(), "trekoon-sync-branch-"));
-  const tempDbPath: string = join(tempDir, "remote.db");
+  throw new DomainError({
+    code: "invalid_source",
+    message: `Source ref '${sourceRef}' was not found.`,
+    details: {
+      status: "invalid_source",
+      sourceBranch: sourceRef,
+      operatorAction: `Verify '${sourceRef}' exists with git rev-parse --verify --quiet ${sourceRef}^{commit} and rerun sync.`,
+    },
+  });
+}
 
-  writeFileSync(tempDbPath, show.stdout);
+export function queryBranchEventsSince(db: Database, branch: string, cursorToken: string): BranchEventRow[] {
+  const cursor = parseCursorToken(cursorToken);
 
-  const db: Database = new Database(tempDbPath);
+  return db
+    .query(
+      `
+      SELECT id, entity_kind, entity_id, operation, payload, git_branch, git_head, created_at, updated_at, version
+      FROM events
+      WHERE git_branch = @branch
+        AND (
+          created_at > @createdAt
+          OR (created_at = @createdAt AND id > @id)
+        )
+      ORDER BY created_at ASC, id ASC;
+      `,
+    )
+    .all({
+      "@branch": branch,
+      "@createdAt": cursor.createdAt,
+      "@id": cursor.id ?? "",
+    }) as BranchEventRow[];
+}
 
-  return {
-    branch,
-    path: tempDbPath,
-    db,
-    close(): void {
-      db.close(false);
-      rmSync(tempDir, { recursive: true, force: true });
-    },
-  };
+export function countBranchEventsSince(db: Database, branch: string, cursorToken: string): number {
+  const cursor = parseCursorToken(cursorToken);
+  const row = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM events
+      WHERE git_branch = @branch
+        AND (
+          created_at > @createdAt
+          OR (created_at = @createdAt AND id > @id)
+        );
+      `,
+    )
+    .get({
+      "@branch": branch,
+      "@createdAt": cursor.createdAt,
+      "@id": cursor.id ?? "",
+    }) as { count: number } | null;
+
+  return row?.count ?? 0;
 }

package/src/sync/git-context.ts

@@ -1,5 +1,6 @@
 import { type Database } from "bun:sqlite";
 
+import { resolveStoragePaths } from "../storage/path";
 import { type GitContextSnapshot } from "./types";
 
 function runGit(args: readonly string[], cwd: string): string | null {
@@ -19,11 +20,12 @@ function runGit(args: readonly string[], cwd: string): string | null {
 }
 
 export function resolveGitContext(cwd: string): GitContextSnapshot {
+  const storagePaths = resolveStoragePaths(cwd);
   const branchName: string | null = runGit(["branch", "--show-current"], cwd);
   const headSha: string | null = runGit(["rev-parse", "HEAD"], cwd);
 
   return {
-    worktreePath: cwd,
+    worktreePath: storagePaths.worktreeRoot,
     branchName,
     headSha,
   };
@@ -36,6 +38,7 @@ export function persistGitContext(db: Database, git: GitContextSnapshot): void {
     `
     INSERT INTO git_context (
       id,
+      metadata_scope,
       worktree_path,
       branch_name,
       head_sha,
@@ -43,7 +46,8 @@ export function persistGitContext(db: Database, git: GitContextSnapshot): void {
       updated_at,
       version
     ) VALUES (
-      'current',
+      @worktreePath,
+      'worktree',
       @worktreePath,
       @branchName,
       @headSha,
@@ -52,6 +56,7 @@ export function persistGitContext(db: Database, git: GitContextSnapshot): void {
       1
     )
     ON CONFLICT(id) DO UPDATE SET
+      metadata_scope = excluded.metadata_scope,
       worktree_path = excluded.worktree_path,
       branch_name = excluded.branch_name,
       head_sha = excluded.head_sha,