codetrap 0.1.2 → 0.1.4

package/src/lib/trap-operations.ts

@@ -12,17 +12,14 @@ import {
 import type { TrapStore, TrapStats } from "./store";
 import type { SearchMode } from "./constants";
 import { toTrapActionCards } from "./search-result-card";
+import type { AddTrapEvidenceResult, TrapMutationResult } from "./trap-mutation-result";
 
 export type TrapListGroup = { traps: Trap[]; scope: string };
 export type TrapSearchGroup = { results: TrapSearchResult[]; scope: string };
-export type TrapMutationResult = { scope: string; success: boolean };
-export type AddTrapEvidenceResult = {
-  scope: string;
-  evidence_id: number | null;
-  success: boolean;
-};
+export type { AddTrapEvidenceResult, TrapMutationResult };
 
-export type TrapStatsResult = { project: TrapStats | null; global: TrapStats };
+export type TrapStatsResult = { project: TrapStats | null; global: TrapStats | null };
+export type EmbeddingStatsResult = ReturnType<TrapStore["embeddingStats"]>;
 
 export interface SearchTrapsArgs {
   query: string;
@@ -31,6 +28,11 @@ export interface SearchTrapsArgs {
   limit?: number;
   mode?: SearchMode;
   status?: string;
+  path?: string;
+  module?: string;
+  owner?: string;
+  rerank?: boolean;
+  includeRankingSignals?: boolean;
 }
 
 export interface ListTrapsArgs {
@@ -39,6 +41,9 @@ export interface ListTrapsArgs {
   limit?: number;
   offset?: number;
   status?: string;
+  path?: string;
+  module?: string;
+  owner?: string;
 }
 
 export class TrapOperations {
@@ -55,6 +60,11 @@ export class TrapOperations {
       limit: args.limit ?? 20,
       mode: args.mode,
       status: parseTrapStatus(args.status),
+      path: args.path,
+      module: args.module,
+      owner: args.owner,
+      rerank: args.rerank,
+      includeRankingSignals: args.includeRankingSignals,
     });
   }
 
@@ -77,9 +87,16 @@ export class TrapOperations {
       status: parseTrapStatus(args.status),
       limit: args.limit ?? 50,
       offset: args.offset,
+      path: args.path,
+      module: args.module,
+      owner: args.owner,
     });
   }
 
+  topTraps(scope: string, limit = 20): TrapListGroup[] {
+    return [{ traps: this.store.topTraps(scope, limit), scope }];
+  }
+
   updateTrap(
     id: number,
     args: Record<string, unknown>,
@@ -113,8 +130,12 @@ export class TrapOperations {
     return this.store.supersede(id, supersededById, scope, stateKey);
   }
 
-  getStats(): TrapStatsResult {
-    return this.store.stats();
+  getStats(scope?: string): TrapStatsResult {
+    return this.store.stats({ scope });
+  }
+
+  getEmbeddingStats(scope?: string): EmbeddingStatsResult {
+    return this.store.embeddingStats({ scope });
   }
 
   exportTraps(scope?: string): ReturnType<TrapStore["exportAll"]> {

package/src/lib/trap-scope-match.ts

@@ -0,0 +1,112 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import type { Trap } from "../domain/trap";
+import { parseTrapPathGlobs } from "./trap-json-fields";
+
+export type ApplicabilityFilter = {
+  path?: string;
+  module?: string;
+  owner?: string;
+};
+
+export function trapMatchesApplicability(trap: Trap, filter: ApplicabilityFilter): boolean {
+  return (
+    trapAppliesToPath(trap, filter.path) &&
+    trapAppliesToModule(trap, filter.module) &&
+    trapAppliesToOwner(trap, filter.owner)
+  );
+}
+
+export function trapAppliesToPath(trap: Trap, path?: string): boolean {
+  if (!path) return true;
+  const globs = parseTrapPathGlobs(trap.path_globs);
+  if (globs.length === 0) return true;
+  const candidates = pathCandidates(trap, path);
+  return globs.some((glob) => candidates.some((candidate) => globMatchesPath(glob, candidate)));
+}
+
+export function trapAppliesToModule(trap: Trap, module?: string): boolean {
+  if (!module || !trap.module) return true;
+  return trap.module === module;
+}
+
+export function trapAppliesToOwner(trap: Trap, owner?: string): boolean {
+  if (!owner || !trap.owner) return true;
+  return trap.owner === owner;
+}
+
+export function hasSpecificPathMatch(trap: Trap, path?: string): boolean {
+  if (!path) return false;
+  const globs = parseTrapPathGlobs(trap.path_globs);
+  const candidates = pathCandidates(trap, path);
+  return globs.length > 0 && globs.some((glob) => candidates.some((candidate) => globMatchesPath(glob, candidate)));
+}
+
+export function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function globMatchesPath(glob: string, path: string): boolean {
+  const normalizedGlob = normalizePath(glob);
+  return new RegExp(`^${globToRegExp(normalizedGlob)}$`).test(path);
+}
+
+function pathCandidates(trap: Trap, path: string): string[] {
+  const candidates = new Set([normalizePath(path)]);
+  if (trap.project_path && isAbsolute(path)) {
+    for (const root of projectPathAliases(trap.project_path)) {
+      const relativePath = relative(root, path);
+      const normalizedRelative = normalizePath(relativePath);
+      if (
+        normalizedRelative &&
+        normalizedRelative !== ".." &&
+        !normalizedRelative.startsWith("../") &&
+        !isAbsolute(relativePath)
+      ) {
+        candidates.add(normalizedRelative);
+      }
+    }
+  }
+  return [...candidates];
+}
+
+function projectPathAliases(projectPath: string): string[] {
+  const roots = new Set([projectPath]);
+  try {
+    roots.add(realpathSync(projectPath));
+  } catch {
+    // The project may have moved since the trap was recorded; use the stored path.
+  }
+
+  for (const root of [...roots]) {
+    if (root.startsWith("/private/var/")) {
+      roots.add(root.replace(/^\/private\/var\//, "/var/"));
+    } else if (root.startsWith("/var/")) {
+      roots.add(`/private${root}`);
+    }
+  }
+  return [...roots];
+}
+
+function globToRegExp(glob: string): string {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    const next = glob[i + 1];
+    if (char === "*" && next === "*") {
+      out += ".*";
+      i++;
+    } else if (char === "*") {
+      out += "[^/]*";
+    } else if (char === "?") {
+      out += "[^/]";
+    } else {
+      out += escapeRegExp(char);
+    }
+  }
+  return out;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+}

package/src/lib/trap-search-document.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import type { Trap, TrapInput, TrapUpdate } from "../domain/trap";
 import type { EmbeddingConfig, StoredEmbedding } from "./embedder";
 import { buildSearchText, SEARCH_TEXT_FIELD_NAMES, type SearchTextFields } from "./search-normalizer";
-import { parseTrapTags } from "./trap-json-fields";
+import { parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
 
 export const PASSAGE_VERSION = 1;
 
@@ -16,6 +16,9 @@ export const PASSAGE_FIELD_NAMES = [
   "before_code",
   "after_code",
   "severity",
+  "path_globs",
+  "module",
+  "owner",
 ] as const;
 
 export type TrapSearchDocumentFields = SearchTextFields & {
@@ -30,11 +33,15 @@ export function buildTrapSearchText(fields: SearchTextFields): string {
 
 export function buildTrapPassage(trap: TrapSearchDocumentFields): string {
   const tags = parseTrapTags(trap.tags).join(", ");
+  const pathGlobs = parseTrapPathGlobs(trap.path_globs).join(", ");
   return [
     trap.title ? `Title: ${trap.title}` : "",
     trap.category ? `Category: ${trap.category}` : "",
     trap.severity ? `Severity: ${trap.severity}` : "",
     tags ? `Tags: ${tags}` : "",
+    pathGlobs ? `Path globs: ${pathGlobs}` : "",
+    trap.module ? `Module: ${trap.module}` : "",
+    trap.owner ? `Owner: ${trap.owner}` : "",
     trap.context ? `Context: ${trap.context}` : "",
     trap.mistake ? `Mistake: ${trap.mistake}` : "",
     trap.fix ? `Fix: ${trap.fix}` : "",

package/src/lib/trap-transfer.ts

@@ -0,0 +1,88 @@
+import type { TrapRecordInsert, TrapRepository } from "../db/repository";
+import type { TrapExportEvidence, TrapExportRecord } from "../domain/trap";
+import { DEFAULT_SEVERITY, DEFAULT_TRAP_STATUS } from "./constants";
+import { buildTrapSearchText } from "./trap-search-document";
+import { encodeTrapPathGlobs } from "./trap-json-fields";
+
+export type TrapTransferMapping = {
+  source_id: number;
+  destination_id: number;
+  title: string;
+};
+
+export function importProjectTrapTransfer(
+  destination: TrapRepository,
+  records: TrapExportRecord[],
+  projectPath: string
+): TrapTransferMapping[] {
+  const mappings: TrapTransferMapping[] = [];
+  const idMap = new Map<number, number>();
+
+  destination.transaction(() => {
+    for (const record of records) {
+      const destinationId = destination.insertTrapRecord(toProjectTransferRecord(record, projectPath));
+      idMap.set(record.id, destinationId);
+      mappings.push({ source_id: record.id, destination_id: destinationId, title: record.title });
+
+      for (const evidence of record.evidence ?? []) {
+        destination.addEvidence(destinationId, toEvidenceInput(evidence));
+      }
+    }
+
+    for (const record of records) {
+      if (record.supersedes_id === null) continue;
+      const destinationId = idMap.get(record.id);
+      const destinationSupersedesId = idMap.get(record.supersedes_id);
+      if (destinationId !== undefined && destinationSupersedesId !== undefined) {
+        destination.updateTrapSupersedesId(destinationId, destinationSupersedesId);
+      }
+    }
+  });
+
+  return mappings;
+}
+
+export function deleteTransferredSourceTraps(
+  source: TrapRepository,
+  records: TrapExportRecord[]
+): number {
+  return source.deleteTrapsByIds(records.map((record) => record.id));
+}
+
+function toProjectTransferRecord(record: TrapExportRecord, projectPath: string): TrapRecordInsert {
+  return {
+    title: record.title,
+    category: record.category,
+    tags: record.tags,
+    scope: "project",
+    context: record.context,
+    mistake: record.mistake,
+    fix: record.fix,
+    search_text: record.search_text || buildTrapSearchText(record),
+    before_code: record.before_code,
+    after_code: record.after_code,
+    severity: record.severity ?? DEFAULT_SEVERITY,
+    state_key: record.state_key,
+    status: record.status ?? DEFAULT_TRAP_STATUS,
+    supersedes_id: null,
+    valid_from: record.valid_from,
+    valid_until: record.valid_until,
+    project_path: projectPath,
+    path_globs: encodeTrapPathGlobs(record.path_globs),
+    module: record.module,
+    owner: record.owner,
+    hit_count: record.hit_count ?? 0,
+    created_at: record.created_at,
+    updated_at: record.updated_at,
+  };
+}
+
+function toEvidenceInput(evidence: TrapExportEvidence) {
+  return {
+    source_type: evidence.source_type,
+    source_ref: evidence.source_ref,
+    observed_at: evidence.observed_at,
+    related_files: evidence.related_files,
+    note: evidence.note,
+  };
+}

package/src/mcp/server.ts

@@ -10,88 +10,130 @@ import { TrapStore } from "../lib/store";
 import { toolDefinitions } from "./tools";
 import { resourceDefinitions } from "./resources";
 import { TrapOperations } from "../lib/trap-operations";
+import {
+  toListJson,
+  toMcpResourceJson,
+  toMcpResourceText,
+  toMcpSearchJson,
+  toMcpTextError,
+  toMcpTextJson,
+  toStatsJson,
+  toTrapDetailsJson,
+} from "../lib/output-json";
+import { storeForScopeContext } from "../lib/scope-context";
+import {
+  listRequestFromArgs,
+  searchRequestFromArgs,
+  statsRequestFromArgs,
+} from "../lib/command-requests";
 
 type ToolArgs = Record<string, any>;
 
 export async function handleToolCall(store: TrapStore, name: string, args: ToolArgs) {
-  const operations = new TrapOperations(store);
+  const scopedStore = storeForScopeContext(store, args.cwd);
+  const operations = new TrapOperations(scopedStore);
   try {
     switch (name) {
       case "search_traps": {
-        const cards = await operations.searchTrapCards({
-          query: args.query,
-          scope: args.scope,
-          category: args.category,
-          mode: args.mode,
-          limit: args.limit ?? 20,
-          status: args.status,
-        });
-        return { content: [{ type: "text", text: JSON.stringify(cards, null, 2) }] };
+        const defaults = { mode: "hybrid" as const, limit: args.limit ?? 20, rerank: true };
+        const cards = await operations.searchTrapCards(searchRequestFromArgs(args.query, args, defaults));
+        return toMcpTextJson(toMcpSearchJson(cards));
       }
 
       case "add_trap": {
         const result = operations.addTrap(args);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        return toMcpTextJson(result);
       }
 
       case "get_trap": {
         const result = operations.getTrapDetails(args.id, args.scope);
         if (!result) {
-          return { content: [{ type: "text", text: JSON.stringify({ error: "not found" }) }], isError: true };
+          return toMcpTextError("not found");
         }
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return toMcpTextJson(toTrapDetailsJson(result));
       }
 
       case "list_traps": {
-        const groups = operations.listTraps({
-          scope: args.scope,
-          category: args.category,
-          status: args.status,
-          limit: args.limit ?? 50,
-        });
-        const flat = groups.flatMap((g) =>
-          g.traps.map((t) => ({ ...t, scope: g.scope }))
-        );
-        return { content: [{ type: "text", text: JSON.stringify(flat, null, 2) }] };
+        const groups = operations.listTraps(listRequestFromArgs(args));
+        return toMcpTextJson(toListJson(groups));
       }
 
       case "update_trap": {
         const result = operations.updateTrap(args.id, args, args.scope);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        return toMcpTextJson(result, !result.success);
       }
 
       case "delete_trap": {
         const result = operations.deleteTrap(args.id, args.scope);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        return toMcpTextJson(result, !result.success);
       }
 
       case "add_trap_evidence": {
         const result = operations.addTrapEvidence(args.id, args, args.scope);
-        return { content: [{ type: "text", text: JSON.stringify(result) }], isError: !result.success };
+        return toMcpTextJson(result, !result.success);
       }
 
       case "archive_trap": {
         const result = operations.archiveTrap(args.id, args.scope);
-        return { content: [{ type: "text", text: JSON.stringify(result) }], isError: !result.success };
+        return toMcpTextJson(result, !result.success);
       }
 
       case "supersede_trap": {
         const result = operations.supersedeTrap(args.id, args.superseded_by_id, args.scope, args.state_key);
-        return { content: [{ type: "text", text: JSON.stringify(result) }], isError: !result.success };
+        return toMcpTextJson(result, !result.success);
       }
 
       case "get_stats": {
-        const stats = operations.getStats();
-        const out: Record<string, unknown> = { global: stats.global };
-        if (stats.project) out.project = stats.project;
-        return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+        const request = statsRequestFromArgs(args);
+        const stats = operations.getStats(request.scope);
+        return toMcpTextJson(toStatsJson(stats, operations.getEmbeddingStats(request.scope)));
       }
 
       default:
-        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+        return toMcpTextError(`Unknown tool: ${name}`);
     }
   } catch (e: any) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
+    return toMcpTextError(e instanceof Error ? e.message : String(e));
+  }
+}
+
+export function handleResourceRead(store: TrapStore, uri: string) {
+  const parsed = parseResourceUri(uri);
+  const scopedStore = storeForScopeContext(store, parsed.cwd);
+  const operations = new TrapOperations(scopedStore);
+  try {
+    switch (parsed.baseUri) {
+      case "codetrap://project/recent":
+        return toMcpResourceJson(uri, toListJson(operations.listTraps({ scope: "project", limit: 10 })));
+      case "codetrap://global/recent":
+        return toMcpResourceJson(uri, toListJson(operations.listTraps({ scope: "global", limit: 10 })));
+      case "codetrap://project/top":
+        return toMcpResourceJson(uri, toListJson(operations.topTraps("project", 20)));
+      case "codetrap://global/top":
+        return toMcpResourceJson(uri, toListJson(operations.topTraps("global", 20)));
+      default: {
+        const match = parsed.baseUri.match(/^codetrap:\/\/(project|global)\/trap\/(\d+)$/);
+        if (match) {
+          const details = operations.getTrapDetails(Number.parseInt(match[2], 10), match[1]);
+          return toMcpResourceJson(uri, details ? toTrapDetailsJson(details) : { error: "not found" });
+        }
+        return toMcpResourceText(uri, "Unknown resource");
+      }
+    }
+  } catch (e: any) {
+    return toMcpResourceText(uri, e instanceof Error ? e.message : String(e));
+  }
+}
+
+function parseResourceUri(uri: string): { baseUri: string; cwd?: string } {
+  try {
+    const parsed = new URL(uri);
+    return {
+      baseUri: `${parsed.protocol}//${parsed.hostname}${parsed.pathname}`,
+      cwd: parsed.searchParams.get("cwd") ?? undefined,
+    };
+  } catch {
+    return { baseUri: uri };
   }
 }
 
@@ -122,44 +164,7 @@ export async function start(): Promise<void> {
 
   // Read resource
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const uri = request.params.uri;
-    try {
-      switch (uri) {
-        case "codetrap://project/recent": {
-          const groups = store.list({ scope: "project", limit: 10 });
-          const traps = groups.flatMap((g) => g.traps);
-          return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(traps, null, 2) }] };
-        }
-        case "codetrap://global/recent": {
-          const groups = store.list({ scope: "global", limit: 10 });
-          const traps = groups.flatMap((g) => g.traps);
-          return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(traps, null, 2) }] };
-        }
-        case "codetrap://project/top": {
-          const traps = store.topTraps("project", 20);
-          return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(traps, null, 2) }] };
-        }
-        case "codetrap://global/top": {
-          const traps = store.topTraps("global", 20);
-          return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(traps, null, 2) }] };
-        }
-        default: {
-          // Handle codetrap://{scope}/trap/{id}
-          const match = uri.match(/^codetrap:\/\/(project|global)\/trap\/(\d+)$/);
-          if (match) {
-            const result = store.get(parseInt(match[2]), match[1]);
-            if (!result) {
-              return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: "not found" }) }] };
-            }
-            const details = store.getDetails(parseInt(match[2]), match[1]);
-            return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(details ?? result.trap, null, 2) }] };
-          }
-          return { contents: [{ uri, mimeType: "text/plain", text: "Unknown resource" }] };
-        }
-      }
-    } catch (e: any) {
-      return { contents: [{ uri, mimeType: "text/plain", text: e.message }] };
-    }
+    return handleResourceRead(store, request.params.uri);
   });
 
   const transport = new StdioServerTransport();

package/src/mcp/tools.ts

@@ -11,6 +11,10 @@ const categoryEnum = [...CATEGORIES] as string[];
 const scopeEnum = [...SCOPES] as string[];
 const searchModeEnum = [...SEARCH_MODES] as string[];
 const statusEnum = [...TRAP_STATUSES, "all"] as string[];
+const cwdProperty = {
+  type: "string",
+  description: "Optional working directory used to resolve project scope for this tool call.",
+};
 
 export const toolDefinitions = [
   {
@@ -26,6 +30,12 @@ export const toolDefinitions = [
         mode: { type: "string", enum: searchModeEnum, description: "Search mode (default hybrid)" },
         limit: { type: "number", description: "Max results (default 20)" },
         status: { type: "string", enum: statusEnum, description: "Lifecycle filter (default active; use all for history)" },
+        path: { type: "string", description: "Optional file path used to filter path-scoped traps" },
+        module: { type: "string", description: "Optional module/subsystem filter" },
+        owner: { type: "string", description: "Optional owner/team filter" },
+        rerank: { type: "boolean", description: "Whether query-aware reranking is enabled" },
+        ranking_signals: { type: "boolean", description: "Include ranking signal diagnostics in returned cards" },
+        cwd: cwdProperty,
       },
       required: ["query"],
     },
@@ -34,7 +44,7 @@ export const toolDefinitions = [
     name: "add_trap",
     description:
       "Record a new coding pitfall. Call this when the user wants to save a lesson learned: an AI mistake pattern and the correct approach.",
-    inputSchema: trapInputSchema(),
+    inputSchema: withCwd(trapInputSchema()),
   },
   {
     name: "get_trap",
@@ -44,6 +54,7 @@ export const toolDefinitions = [
       properties: {
         id: { type: "number", description: "Trap ID" },
         scope: { type: "string", enum: scopeEnum, description: "Which scope to look in" },
+        cwd: cwdProperty,
       },
       required: ["id"],
     },
@@ -58,13 +69,17 @@ export const toolDefinitions = [
         category: { type: "string", enum: categoryEnum },
         status: { type: "string", enum: statusEnum, description: "Lifecycle filter (default active; use all for history)" },
         limit: { type: "number", description: "Max results (default 50)" },
+        path: { type: "string", description: "Optional file path used to filter path-scoped traps" },
+        module: { type: "string", description: "Optional module/subsystem filter" },
+        owner: { type: "string", description: "Optional owner/team filter" },
+        cwd: cwdProperty,
       },
     },
   },
   {
     name: "update_trap",
     description: "Update an existing trap's fields.",
-    inputSchema: trapUpdateSchema(),
+    inputSchema: withCwd(trapUpdateSchema()),
   },
   {
     name: "delete_trap",
@@ -74,6 +89,7 @@ export const toolDefinitions = [
       properties: {
         id: { type: "number", description: "Trap ID to delete" },
         scope: { type: "string", enum: scopeEnum },
+        cwd: cwdProperty,
       },
       required: ["id"],
     },
@@ -81,17 +97,17 @@ export const toolDefinitions = [
   {
     name: "add_trap_evidence",
     description: "Attach traceable evidence/source metadata to an existing trap.",
-    inputSchema: trapEvidenceInputSchema(),
+    inputSchema: withCwd(trapEvidenceInputSchema()),
   },
   {
     name: "archive_trap",
     description: "Archive an active trap so default search no longer returns it while history remains recoverable.",
-    inputSchema: archiveTrapInputSchema(),
+    inputSchema: withCwd(archiveTrapInputSchema()),
   },
   {
     name: "supersede_trap",
     description: "Mark one trap as superseded by another trap in the same scope.",
-    inputSchema: supersedeTrapInputSchema(),
+    inputSchema: withCwd(supersedeTrapInputSchema()),
   },
   {
     name: "get_stats",
@@ -100,7 +116,18 @@ export const toolDefinitions = [
       type: "object",
       properties: {
         scope: { type: "string", enum: scopeEnum },
+        cwd: cwdProperty,
       },
     },
   },
 ];
+
+function withCwd<T extends { properties: Record<string, unknown> }>(schema: T): T {
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      cwd: cwdProperty,
+    },
+  };
+}