codetrap 0.1.3 → 0.1.5

package/src/domain/trap.ts

@@ -60,10 +60,15 @@ export interface TrapSearchResult {
   rank: number;
   sources?: ("fts" | "semantic")[];
   score?: number;
-  diagnostics?: { code: string; message: string }[];
+  diagnostics?: TrapSearchDiagnostic[];
   ranking_signals?: RankingSignal[];
 }
 
+export interface TrapSearchDiagnostic {
+  code: string;
+  message: string;
+}
+
 export interface RankingSignal {
   code: string;
   weight: number;
@@ -80,14 +85,8 @@ export interface TrapActionCard {
   severity: string;
   score: number | null;
   sources: ("fts" | "semantic")[];
+  diagnostics?: TrapSearchDiagnostic[];
   ranking_signals?: RankingSignal[];
-  next_action: {
-    details_tool: "get_trap";
-    details_args: {
-      id: number;
-      scope: Scope;
-    };
-  };
 }
 
 export type TrapUpdate = Partial<Omit<TrapInput, "scope" | "project_path">>;
@@ -247,7 +246,7 @@ export function trapEvidenceInputSchema(): JsonSchema {
         enum: [...EVIDENCE_SOURCE_TYPES] as string[],
         description: "Where this evidence came from",
       },
-      source_ref: { type: "string", description: "Optional file path, commit SHA, issue URL, or transcript ID" },
+      source_ref: { type: "string", description: "Optional file path, commit SHA, issue/article URL, or transcript ID" },
       observed_at: { type: "string", description: "When this was observed (ISO-like timestamp, optional)" },
       related_files: {
         type: "array",

package/src/index.ts

@@ -59,6 +59,7 @@ function showHelp(): void {
   console.log("  --path <file>           Filter/boost traps scoped to a file path");
   console.log("  --module <name>         Filter/boost traps scoped to a module");
   console.log("  --owner <name>          Filter/boost traps scoped to an owner/team");
+  console.log("  --source_type <type>    Evidence source: manual, conversation, commit, issue, test_failure, article");
   console.log("  --no-rerank             Disable query-aware search reranking");
   console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");

package/src/lib/command-requests.ts

@@ -0,0 +1,133 @@
+import { SEARCH_MODES, type SearchMode } from "./constants";
+import type { SearchDefaults } from "./config";
+import type { SearchTrapsArgs, ListTrapsArgs } from "./trap-operations";
+
+type RawArgs = Record<string, unknown>;
+
+export type EmbedRequest = {
+  scope?: string;
+  category?: string;
+  limit?: number;
+  force?: boolean;
+  batchSize?: number;
+};
+
+export type StatsRequest = {
+  scope?: string;
+};
+
+export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
+  return {
+    query,
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope") ?? defaults.scope,
+    limit: intOption(args, "limit", defaults.limit),
+    mode: searchModeOption(args, "mode") ?? defaults.mode,
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    rerank: flagPresent(args, "no-rerank") ? false : booleanOption(args, "rerank") ?? defaults.rerank,
+    includeRankingSignals: booleanOption(args, "ranking_signals", "ranking-signals") ?? false,
+  };
+}
+
+export function listRequestFromArgs(args: RawArgs): ListTrapsArgs {
+  return {
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope"),
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    limit: intOption(args, "limit", 50),
+  };
+}
+
+export function statsRequestFromArgs(args: RawArgs): StatsRequest {
+  return {
+    scope: stringOption(args, "scope"),
+  };
+}
+
+export function embedRequestFromArgs(args: RawArgs): EmbedRequest {
+  return {
+    scope: stringOption(args, "scope"),
+    category: stringOption(args, "category"),
+    limit: optionalIntOption(args, "limit"),
+    force: booleanOption(args, "force") === true,
+    batchSize: optionalIntOption(args, "batch_size", "batch-size"),
+  };
+}
+
+export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
+  return {
+    source_type: stringOption(args, "source_type", "source-type"),
+    source_ref: stringOption(args, "source_ref", "source-ref"),
+    observed_at: stringOption(args, "observed_at", "observed-at"),
+    related_files: csvOrArrayOption(args, "related_files", "related-files"),
+    note: stringOption(args, "note"),
+  };
+}
+
+function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+}
+
+function intOption(args: RawArgs, key: string, fallback: number): number {
+  return optionalIntOption(args, key) ?? fallback;
+}
+
+function optionalIntOption(args: RawArgs, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+    throw new Error(`Invalid number: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function searchModeOption(args: RawArgs, key: string): SearchMode | undefined {
+  const value = stringOption(args, key);
+  if (!value) return undefined;
+  if ((SEARCH_MODES as readonly string[]).includes(value)) return value as SearchMode;
+  throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
+}
+
+function booleanOption(args: RawArgs, ...keys: string[]): boolean | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      if (["true", "1", "yes", "on"].includes(value.toLowerCase())) return true;
+      if (["false", "0", "no", "off"].includes(value.toLowerCase())) return false;
+    }
+    throw new Error(`Invalid boolean: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function flagPresent(args: RawArgs, key: string): boolean {
+  return args[key] !== undefined;
+}
+
+function csvOrArrayOption(args: RawArgs, ...keys: string[]): string[] | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (Array.isArray(value)) return value.map(String);
+    if (typeof value === "string" && value.trim() !== "") {
+      return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    }
+  }
+  return undefined;
+}

package/src/lib/constants.ts

@@ -37,7 +37,7 @@ export type Scope = (typeof SCOPES)[number];
 export const TRAP_STATUSES = ["active", "superseded", "archived"] as const;
 export type TrapStatus = (typeof TRAP_STATUSES)[number];
 
-export const EVIDENCE_SOURCE_TYPES = ["manual", "conversation", "commit", "issue", "test_failure"] as const;
+export const EVIDENCE_SOURCE_TYPES = ["manual", "conversation", "commit", "issue", "test_failure", "article"] as const;
 export type EvidenceSourceType = (typeof EVIDENCE_SOURCE_TYPES)[number];
 
 export const SEARCH_MODES = ["fts", "semantic", "hybrid"] as const;

package/src/lib/doctor.ts

@@ -18,6 +18,11 @@ export type DoctorReport = {
     semantic_available: boolean;
     fallback_reason: HybridFallbackReason | null;
   };
+  diagnostics: {
+    mis_scoped_traps: {
+      global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
+    };
+  };
   mcp_hint: string;
 };
 
@@ -35,13 +40,16 @@ export function buildDoctorReport(
     ...scope,
     traps: {
       project: stats.project?.total ?? null,
-      global: stats.global.total,
+      global: stats.global?.total ?? 0,
     },
     embeddings,
     hybrid_search: {
       semantic_available: semanticAvailable,
       fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
     },
+    diagnostics: {
+      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+    },
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -60,6 +68,8 @@ export function formatDoctorText(report: DoctorReport): string {
     "Hybrid search:",
     `  semantic_available: ${report.hybrid_search.semantic_available ? "yes" : "no"}`,
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
+    "Diagnostics:",
+    `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
     `mcp_hint: ${report.mcp_hint}`,
   ].join("\n");
 }

package/src/lib/embedding-health.ts

@@ -17,7 +17,7 @@ export type EmbeddingStateSummary = EmbeddingStateCounts & {
 
 export type EmbeddingStatsResult = {
   project: EmbeddingStateSummary | null;
-  global: EmbeddingStateSummary;
+  global: EmbeddingStateSummary | null;
 };
 
 export type HybridFallbackReason = "semantic_unavailable" | "semantic_no_candidates";
@@ -42,8 +42,8 @@ export function hybridFallbackReason(
 ): HybridFallbackReason | null {
   if (!providerAvailable) return "semantic_unavailable";
 
-  const fresh = (embeddings.project?.fresh ?? 0) + embeddings.global.fresh;
-  const total = (embeddings.project?.total ?? 0) + embeddings.global.total;
+  const fresh = (embeddings.project?.fresh ?? 0) + (embeddings.global?.fresh ?? 0);
+  const total = (embeddings.project?.total ?? 0) + (embeddings.global?.total ?? 0);
   if (total > 0 && fresh === 0) return "semantic_no_candidates";
   return null;
 }

package/src/lib/embedding-index.ts

@@ -0,0 +1,53 @@
+import type { Database } from "bun:sqlite";
+import * as embeddingQueries from "../db/embedding-queries";
+import type { Trap } from "../domain/trap";
+import type { TrapStatus } from "./constants";
+import type {
+  EmbeddingConfig,
+  FreshEmbedding,
+  StoredEmbedding,
+} from "./embedder";
+import type { EmbeddingStateCounts } from "./embedding-health";
+
+export type EmbeddingIndexFilter = {
+  scope?: string;
+  category?: string;
+  status?: TrapStatus | "all";
+};
+
+export type EmbeddingRefreshFilter = EmbeddingIndexFilter & {
+  force?: boolean;
+  limit?: number;
+};
+
+export class DatabaseEmbeddingIndex {
+  constructor(private readonly db: Database) {}
+
+  get(trapId: number): StoredEmbedding | null {
+    return embeddingQueries.getEmbedding(this.db, trapId);
+  }
+
+  save(record: StoredEmbedding): void {
+    embeddingQueries.upsertEmbedding(this.db, record);
+  }
+
+  delete(trapId: number): void {
+    embeddingQueries.deleteEmbedding(this.db, trapId);
+  }
+
+  freshEmbeddings(config: EmbeddingConfig, filter: EmbeddingIndexFilter = {}): FreshEmbedding[] {
+    return embeddingQueries.getAllFreshEmbeddings(this.db, config, filter);
+  }
+
+  trapsNeedingEmbeddings(config: EmbeddingConfig, filter: EmbeddingRefreshFilter = {}): Trap[] {
+    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, filter);
+  }
+
+  countEmbeddable(filter: EmbeddingIndexFilter = {}): number {
+    return embeddingQueries.countEmbeddableTraps(this.db, filter);
+  }
+
+  stateCounts(config: EmbeddingConfig | null, filter: EmbeddingIndexFilter = {}): EmbeddingStateCounts {
+    return embeddingQueries.getEmbeddingStateCounts(this.db, config, filter);
+  }
+}

package/src/lib/format.ts

@@ -18,7 +18,7 @@ Why relevant: ${card.why_relevant}
 Avoid: ${card.avoid}
 Do instead: ${card.do_instead}
 Score: ${formatScore(card.score)} (${sourceLabel})
-Next: get_trap id=${card.next_action.details_args.id} scope=${card.next_action.details_args.scope}`;
+Next: codetrap show ${card.trap_id} --scope ${card.scope} --json`;
 }
 
 export function formatTrapDetail(t: Trap, scopeLabel: string): string {

package/src/lib/output-json.ts

@@ -1,4 +1,4 @@
-import type { RankingSignal, TrapActionCard, TrapDetails } from "../domain/trap";
+import type { RankingSignal, TrapActionCard, TrapDetails, TrapSearchDiagnostic } from "../domain/trap";
 import type { Scope } from "./constants";
 import type { DoctorReport } from "./doctor";
 import type { EmbeddingStatsResult } from "./embedding-health";
@@ -16,11 +16,24 @@ export type JsonTrapDetails = {
   evidence: JsonTrapEvidence[];
 };
 
-export type CliTrapActionCard = Omit<TrapActionCard, "next_action"> & {
+export type CliTrapActionCard = TrapActionCard & {
   next_action: {
     command: string;
   };
   ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
+};
+
+export type McpTrapActionCard = TrapActionCard & {
+  next_action: {
+    details_tool: "get_trap";
+    details_args: {
+      id: number;
+      scope: Scope;
+    };
+  };
+  ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
 };
 
 export type McpTextResult = {
@@ -43,6 +56,7 @@ export function toCliSearchJson(cards: TrapActionCard[]): CliTrapActionCard[] {
     severity: card.severity,
     score: card.score,
     sources: card.sources,
+    ...(card.diagnostics ? { diagnostics: card.diagnostics } : {}),
     ...(card.ranking_signals ? { ranking_signals: card.ranking_signals } : {}),
     next_action: {
       command: `codetrap show ${card.trap_id} --scope ${card.scope} --json`,
@@ -50,8 +64,17 @@ export function toCliSearchJson(cards: TrapActionCard[]): CliTrapActionCard[] {
   }));
 }
 
-export function toMcpSearchJson(cards: TrapActionCard[]): TrapActionCard[] {
-  return cards;
+export function toMcpSearchJson(cards: TrapActionCard[]): McpTrapActionCard[] {
+  return cards.map((card) => ({
+    ...card,
+    next_action: {
+      details_tool: "get_trap",
+      details_args: {
+        id: card.trap_id,
+        scope: card.scope,
+      },
+    },
+  }));
 }
 
 export function toMcpTextJson(value: unknown, isError = false): McpTextResult {
@@ -102,10 +125,12 @@ export function toStatsJson(stats: TrapStatsResult, embeddings?: EmbeddingStatsR
           embeddings: embeddings?.project ?? null,
         }
       : null,
-    global: {
-      ...stats.global,
-      embeddings: embeddings?.global ?? null,
-    },
+    global: stats.global
+      ? {
+          ...stats.global,
+          embeddings: embeddings?.global ?? null,
+        }
+      : null,
   };
 }
 

package/src/lib/scope-context.ts

@@ -1,10 +1,12 @@
-import { join, resolve } from "node:path";
 import { openGlobal, openProject } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
 import type { Scope } from "./constants";
 import type { EmbeddingProvider } from "./embedder";
-import { findProjectRoot, getGlobalDB } from "./scope";
+import { findProjectRoot, getGlobalDB, resolveScopePath } from "./scope";
+import { ScopePathResolver } from "./scope-path";
+
+const scopePath = new ScopePathResolver();
 
 export type ScopeContext = {
   cwd: string;
@@ -14,12 +16,12 @@ export type ScopeContext = {
 };
 
 export function createScopeContext(cwd = process.cwd()): ScopeContext {
-  const resolvedCwd = resolve(cwd);
+  const resolvedCwd = resolveScopePath(cwd);
   const projectRoot = findProjectRoot(resolvedCwd);
   return {
     cwd: resolvedCwd,
     project_root: projectRoot,
-    project_db: projectRoot ? join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
+    project_db: projectRoot ? scopePath.join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
     global_db: getGlobalDB(),
   };
 }

package/src/lib/scope-maintenance.ts

@@ -0,0 +1,71 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { TrapRepository } from "../db/repository";
+import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import { ScopePathResolver } from "./scope-path";
+
+const scopePath = new ScopePathResolver();
+
+export type ScopeMaintenanceCommand = "repair-scope" | "migrate-project";
+
+export type ScopeMaintenancePaths = {
+  command: ScopeMaintenanceCommand;
+  fromProjectPath: string;
+  toProjectPath: string;
+  sourceDb: string;
+  destinationDb: string;
+};
+
+export function buildScopeMaintenancePaths(input: {
+  command: ScopeMaintenanceCommand;
+  fromProjectPath: string;
+  toProjectPath: string;
+}): ScopeMaintenancePaths {
+  return {
+    command: input.command,
+    fromProjectPath: input.fromProjectPath,
+    toProjectPath: input.toProjectPath,
+    sourceDb: projectDbPath(input.fromProjectPath),
+    destinationDb: projectDbPath(input.toProjectPath),
+  };
+}
+
+export function validateScopeMaintenancePaths(input: ScopeMaintenancePaths): void {
+  if (input.command === "migrate-project" && scopePath.same(input.fromProjectPath, input.toProjectPath)) {
+    throw new Error("--from-project-path and --to-project-path must be different.");
+  }
+  if (scopePath.same(input.sourceDb, input.destinationDb)) {
+    throw new Error("Source and destination database paths are the same.");
+  }
+  if (!existsSync(scopePath.join(input.toProjectPath, CODETRAP_DIR))) {
+    throw new Error(`Destination project is not initialized: ${input.toProjectPath}. Run 'codetrap init' first.`);
+  }
+}
+
+export function projectDbPath(projectPath: string): string {
+  return scopePath.join(projectPath, CODETRAP_DIR, TRAPS_DB_FILE);
+}
+
+export function withReadOnlyScopeRepository<T>(dbPath: string, callback: (repository: TrapRepository) => T): T {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    return callback(new TrapRepository(db));
+  } finally {
+    db.close();
+  }
+}
+
+export function backupScopeDatabase(dbPath: string, label: string): string {
+  const backupDir = join(dirname(dbPath), "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = join(backupDir, `${basename(dbPath)}.${label}.${timestamp}.backup`);
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    writeFileSync(backupPath, db.serialize());
+  } finally {
+    db.close();
+  }
+  return backupPath;
+}

package/src/lib/scope-migration.ts

@@ -1,19 +1,23 @@
-import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
 import { openDatabase } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import type { TrapExportRecord } from "../domain/trap";
-import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
-import { findProjectRoot } from "./scope";
+import { findProjectRoot, resolveScopePath } from "./scope";
+import {
+  backupScopeDatabase,
+  buildScopeMaintenancePaths,
+  validateScopeMaintenancePaths,
+  withReadOnlyScopeRepository,
+  type ScopeMaintenanceCommand,
+} from "./scope-maintenance";
 import {
   deleteTransferredSourceTraps,
   importProjectTrapTransfer,
   type TrapTransferMapping,
 } from "./trap-transfer";
 
-export type ScopeMigrationCommand = "repair-scope" | "migrate-project";
+export type ScopeMigrationCommand = ScopeMaintenanceCommand;
 export type ScopeMigrationMode = "dry-run" | "apply";
 
 export type ScopeMigrationCandidate = {
@@ -151,16 +155,16 @@ export function formatScopeMigrationText(result: ScopeMigrationResult): string {
 
 function buildScopeMigrationPlan(options: ScopeMigrationOptions): ScopeMigrationPlan {
   const resolved = resolveScopeMigrationOptions(options);
-  validateMigrationPaths(resolved);
+  validateScopeMaintenancePaths(resolved);
   const sourceDbExists = existsSync(resolved.sourceDb);
   const destinationDbExists = existsSync(resolved.destinationDb);
   const records = sourceDbExists
-    ? withReadOnlyRepository(resolved.sourceDb, (repository) =>
+    ? withReadOnlyScopeRepository(resolved.sourceDb, (repository) =>
         repository.exportProjectTrapsByPath(resolved.fromProjectPath)
       )
     : [];
   const destinationBefore = destinationDbExists
-    ? withReadOnlyRepository(resolved.destinationDb, (repository) =>
+    ? withReadOnlyScopeRepository(resolved.destinationDb, (repository) =>
         repository.countProjectTrapsByPath(resolved.toProjectPath)
       )
     : 0;
@@ -177,8 +181,8 @@ function buildScopeMigrationPlan(options: ScopeMigrationOptions): ScopeMigration
 
 function applyScopeMigrationPlan(plan: ScopeMigrationPlan): ScopeMigrationApplyResult {
   const backups = {
-    source_db: backupDatabase(plan.sourceDb, "source"),
-    destination_db: plan.destinationDbExists ? backupDatabase(plan.destinationDb, "destination") : null,
+    source_db: backupScopeDatabase(plan.sourceDb, "source"),
+    destination_db: plan.destinationDbExists ? backupScopeDatabase(plan.destinationDb, "destination") : null,
   };
 
   const applyResult = applyScopeMigration(
@@ -197,45 +201,27 @@ function applyScopeMigrationPlan(plan: ScopeMigrationPlan): ScopeMigrationApplyR
 }
 
 function resolveScopeMigrationOptions(options: ScopeMigrationOptions): ResolvedScopeMigration {
-  const cwd = resolve(options.cwd ?? process.cwd());
+  const cwd = resolveScopePath(options.cwd ?? process.cwd());
   const projectRoot = findProjectRoot(cwd);
-  const fromProjectPath = resolve(options.fromProjectPath ?? homedir());
+  const fromProjectPath = resolveScopePath(options.fromProjectPath ?? homedir());
   const rawToProjectPath = options.toProjectPath ?? projectRoot;
 
   if (!rawToProjectPath) {
     throw new Error("Destination project not found. Run 'codetrap init' first, or pass --to-project-path.");
   }
-  const toProjectPath = resolve(rawToProjectPath);
+  const toProjectPath = resolveScopePath(rawToProjectPath);
 
   return {
-    command: options.command,
+    ...buildScopeMaintenancePaths({
+      command: options.command,
+      fromProjectPath,
+      toProjectPath,
+    }),
     mode: options.apply ? "apply" : "dry-run",
     apply: options.apply === true,
-    fromProjectPath,
-    toProjectPath,
-    sourceDb: projectDbPath(fromProjectPath),
-    destinationDb: projectDbPath(toProjectPath),
   };
 }
 
-function validateMigrationPaths(input: {
-  command: ScopeMigrationCommand;
-  fromProjectPath: string;
-  toProjectPath: string;
-  sourceDb: string;
-  destinationDb: string;
-}): void {
-  if (input.command === "migrate-project" && input.fromProjectPath === input.toProjectPath) {
-    throw new Error("--from-project-path and --to-project-path must be different.");
-  }
-  if (canonicalPath(input.sourceDb) === canonicalPath(input.destinationDb)) {
-    throw new Error("Source and destination database paths are the same.");
-  }
-  if (!existsSync(join(input.toProjectPath, CODETRAP_DIR))) {
-    throw new Error(`Destination project is not initialized: ${input.toProjectPath}. Run 'codetrap init' first.`);
-  }
-}
-
 function applyScopeMigration(
   sourceDbPath: string,
   destinationDbPath: string,
@@ -307,29 +293,6 @@ function toCandidate(record: TrapExportRecord): ScopeMigrationCandidate {
   };
 }
 
-function withReadOnlyRepository<T>(dbPath: string, callback: (repository: TrapRepository) => T): T {
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    return callback(new TrapRepository(db));
-  } finally {
-    db.close();
-  }
-}
-
-function backupDatabase(dbPath: string, label: string): string {
-  const backupDir = join(dirname(dbPath), "backups");
-  mkdirSync(backupDir, { recursive: true });
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const backupPath = join(backupDir, `${basename(dbPath)}.${label}.${timestamp}.backup`);
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    writeFileSync(backupPath, db.serialize());
-  } finally {
-    db.close();
-  }
-  return backupPath;
-}
-
 function buildApplyCommand(
   command: ScopeMigrationCommand,
   fromProjectPath: string,
@@ -347,14 +310,6 @@ function buildApplyCommand(
   ].join(" ");
 }
 
-function projectDbPath(projectPath: string): string {
-  return join(projectPath, CODETRAP_DIR, TRAPS_DB_FILE);
-}
-
-function canonicalPath(path: string): string {
-  return existsSync(path) ? realpathSync(path) : path;
-}
-
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }