codetrap 0.1.0

package/src/lib/store.ts

@@ -0,0 +1,272 @@
+import { openGlobal, openProject } from "../db/connection";
+import { TrapRepository, type TrapStats } from "../db/repository";
+import {
+  type Trap,
+  type TrapDetails,
+  type TrapEvidenceInput,
+  type TrapExportRecord,
+  type TrapImportRecord,
+  type TrapInput,
+  type TrapSearchResult,
+  type TrapUpdate,
+} from "../domain/trap";
+import type { SearchMode, TrapStatus } from "./constants";
+import { createDefaultEmbeddingProvider, type EmbeddingProvider } from "./embedder";
+import { findProjectRoot } from "./scope";
+import { importTrapArchive } from "./trap-archive";
+
+export {
+  type TrapInput,
+  type TrapSearchResult,
+  type Trap,
+  type TrapDetails,
+  type TrapExportRecord,
+  type TrapImportRecord,
+  type TrapUpdate,
+  type TrapStats,
+};
+
+type Scope = "project" | "global";
+
+export class TrapStore {
+  private projectRoot: string | null;
+  private globalRepository?: TrapRepository;
+  private projectRepository?: TrapRepository;
+  private readonly embedder?: EmbeddingProvider;
+
+  constructor(cwd: string, embedder: EmbeddingProvider | undefined = createDefaultEmbeddingProvider()) {
+    this.projectRoot = findProjectRoot(cwd);
+    this.embedder = embedder;
+  }
+
+  add(input: TrapInput): { id: number; scope: string } {
+    const scope = normalizeScope(input.scope);
+    if (scope === "project" && !this.projectRoot) {
+      throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
+    }
+
+    const id = this.repositoryFor(scope).add({
+      ...input,
+      scope,
+      project_path: scope === "project" ? this.projectRoot : null,
+    });
+    return { id, scope };
+  }
+
+  async search(
+    query: string,
+    opts: { category?: string; scope?: string; limit?: number; mode?: SearchMode; status?: TrapStatus | "all" } = {}
+  ): Promise<{ results: TrapSearchResult[]; scope: string }[]> {
+    const out: { results: TrapSearchResult[]; scope: string }[] = [];
+    const limit = opts.limit ?? 20;
+
+    for (const scoped of this.repositoriesForRead(opts.scope)) {
+      const results = await scoped.repository.search(query, {
+        category: opts.category,
+        scope: scoped.scope,
+        limit,
+        mode: opts.mode ?? "hybrid",
+        status: opts.status,
+      });
+      if (results.length > 0) out.push({ results, scope: scoped.scope });
+    }
+
+    return out;
+  }
+
+  get(id: number, scope?: string): { trap: Trap; scope: string } | null {
+    for (const scoped of this.repositoriesForRead(scope)) {
+      const trap = scoped.repository.get(id);
+      if (trap) return { trap, scope: scoped.scope };
+    }
+    return null;
+  }
+
+  getDetails(id: number, scope?: string): TrapDetails | null {
+    for (const scoped of this.repositoriesForRead(scope)) {
+      const details = scoped.repository.getDetails(id, scoped.scope);
+      if (details) return details;
+    }
+    return null;
+  }
+
+  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all" } = {}): { traps: Trap[]; scope: string }[] {
+    const out: { traps: Trap[]; scope: string }[] = [];
+
+    for (const scoped of this.repositoriesForRead(opts.scope)) {
+      const traps = scoped.repository.list({ ...opts, scope: scoped.scope });
+      if (traps.length > 0) out.push({ traps, scope: scoped.scope });
+    }
+
+    return out;
+  }
+
+  update(id: number, input: TrapUpdate, scope?: string): { scope: string; success: boolean } {
+    for (const scoped of this.repositoriesForWrite(scope)) {
+      const success = scoped.repository.update(id, input);
+      if (success || scope) return { scope: scoped.scope, success };
+    }
+    return { scope: "global", success: false };
+  }
+
+  delete(id: number, scope?: string): { scope: string; success: boolean } {
+    for (const scoped of this.repositoriesForWrite(scope)) {
+      const success = scoped.repository.delete(id);
+      if (success || scope) return { scope: scoped.scope, success };
+    }
+    return { scope: "global", success: false };
+  }
+
+  addEvidence(id: number, input: TrapEvidenceInput, scope?: string): { scope: string; evidence_id: number | null; success: boolean } {
+    for (const scoped of this.repositoriesForWrite(scope)) {
+      const evidenceId = scoped.repository.addEvidence(id, input);
+      if (evidenceId || scope) return { scope: scoped.scope, evidence_id: evidenceId, success: evidenceId !== null };
+    }
+    return { scope: "global", evidence_id: null, success: false };
+  }
+
+  archive(id: number, scope?: string): { scope: string; success: boolean } {
+    for (const scoped of this.repositoriesForWrite(scope)) {
+      const success = scoped.repository.archive(id);
+      if (success || scope) return { scope: scoped.scope, success };
+    }
+    return { scope: "global", success: false };
+  }
+
+  supersede(
+    id: number,
+    supersededById: number,
+    scope?: string,
+    stateKey?: string
+  ): { scope: string; success: boolean } {
+    for (const scoped of this.repositoriesForWrite(scope)) {
+      const success = scoped.repository.supersede(id, supersededById, stateKey);
+      if (success || scope) return { scope: scoped.scope, success };
+    }
+    return { scope: "global", success: false };
+  }
+
+  hit(id: number, scope?: string): void {
+    for (const scoped of this.repositoriesForRead(scope)) {
+      if (scope || scoped.repository.get(id)) {
+        scoped.repository.hit(id);
+        return;
+      }
+    }
+  }
+
+  topTraps(scope: string, limit = 20): Trap[] {
+    const resolvedScope = normalizeScope(scope);
+    return this.repositoryFor(resolvedScope).top(resolvedScope, limit);
+  }
+
+  stats(): { project: TrapStats | null; global: TrapStats } {
+    const project = this.projectRoot ? this.projectRepo().stats() : null;
+    return { project, global: this.globalRepo().stats() };
+  }
+
+  exportAll(opts: { scope?: string } = {}): TrapExportRecord[] {
+    const traps: TrapExportRecord[] = [];
+    for (const scoped of this.repositoriesForRead(opts.scope)) {
+      traps.push(...scoped.repository.exportAll());
+    }
+    return traps;
+  }
+
+  importAll(traps: TrapImportRecord[]): number {
+    return importTrapArchive(traps, {
+      add: (input) => this.add(input),
+      addEvidence: (id, input, scope) => this.addEvidence(id, input, scope),
+    });
+  }
+
+  hasProject(): boolean {
+    return this.projectRoot !== null;
+  }
+
+  getProjectRoot(): string | null {
+    return this.projectRoot;
+  }
+
+  async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
+    generated: number;
+    skipped: number;
+    batches: number;
+    scopes: { scope: string; generated: number; skipped: number; batches: number }[];
+  }> {
+    const scopes: { scope: string; generated: number; skipped: number; batches: number }[] = [];
+    let generated = 0;
+    let skipped = 0;
+    let batches = 0;
+
+    for (const scoped of this.repositoriesForRead(opts.scope)) {
+      const result = await scoped.repository.ensureEmbeddings({
+        scope: scoped.scope,
+        category: opts.category,
+        limit: opts.limit,
+        force: opts.force,
+        batchSize: opts.batchSize,
+      });
+      scopes.push({ scope: scoped.scope, ...result });
+      generated += result.generated;
+      skipped += result.skipped;
+      batches += result.batches;
+    }
+
+    return { generated, skipped, batches, scopes };
+  }
+
+  private repositoriesForRead(scope?: string): { scope: Scope; repository: TrapRepository }[] {
+    const resolvedScope = optionalScope(scope);
+    if (resolvedScope) return this.repositoryEntry(resolvedScope) ? [this.repositoryEntry(resolvedScope)!] : [];
+
+    const repositories: { scope: Scope; repository: TrapRepository }[] = [];
+    const project = this.repositoryEntry("project");
+    if (project) repositories.push(project);
+    repositories.push({ scope: "global", repository: this.globalRepo() });
+    return repositories;
+  }
+
+  private repositoriesForWrite(scope?: string): { scope: Scope; repository: TrapRepository }[] {
+    return this.repositoriesForRead(scope);
+  }
+
+  private repositoryEntry(scope: Scope): { scope: Scope; repository: TrapRepository } | null {
+    if (scope === "project") {
+      return this.projectRoot ? { scope, repository: this.projectRepo() } : null;
+    }
+    return { scope, repository: this.globalRepo() };
+  }
+
+  private repositoryFor(scope: Scope): TrapRepository {
+    if (scope === "project") return this.projectRepo();
+    return this.globalRepo();
+  }
+
+  private projectRepo(): TrapRepository {
+    if (!this.projectRoot) {
+      throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
+    }
+    if (!this.projectRepository) {
+      this.projectRepository = new TrapRepository(openProject(this.projectRoot), this.embedder);
+    }
+    return this.projectRepository;
+  }
+
+  private globalRepo(): TrapRepository {
+    if (!this.globalRepository) {
+      this.globalRepository = new TrapRepository(openGlobal(), this.embedder);
+    }
+    return this.globalRepository;
+  }
+}
+
+function normalizeScope(scope: string): Scope {
+  if (scope === "project" || scope === "global") return scope;
+  throw new Error(`Invalid scope: ${scope}`);
+}
+
+function optionalScope(scope?: string): Scope | null {
+  if (!scope) return null;
+  return normalizeScope(scope);
+}

package/src/lib/trap-archive.ts

@@ -0,0 +1,91 @@
+import {
+  buildTrapEvidenceInput,
+  type TrapEvidence,
+  type TrapEvidenceInput,
+  type TrapExportEvidence,
+  type TrapImportEvidence,
+  type TrapImportRecord,
+  type TrapInput,
+} from "../domain/trap";
+import {
+  parseEvidenceRelatedFiles,
+  parseOptionalEvidenceRelatedFiles,
+  parseOptionalTrapTags,
+} from "./trap-json-fields";
+
+export interface TrapArchiveImportAdapter {
+  add(input: TrapInput): { id: number; scope: string };
+  addEvidence(
+    id: number,
+    input: TrapEvidenceInput,
+    scope?: string
+  ): { scope: string; evidence_id: number | null; success: boolean };
+}
+
+export function normalizeEvidenceForExport(evidence: TrapEvidence): TrapExportEvidence {
+  return {
+    ...evidence,
+    related_files: parseEvidenceRelatedFiles(evidence.related_files),
+  };
+}
+
+export function importTrapArchive(
+  records: TrapImportRecord[],
+  adapter: TrapArchiveImportAdapter
+): number {
+  let count = 0;
+  for (const record of records) {
+    try {
+      const result = adapter.add(toTrapInput(record));
+      importEvidenceRecords(record.evidence ?? [], result, adapter);
+      count++;
+    } catch {
+      // Preserve legacy behavior: import valid traps even if another trap is malformed.
+    }
+  }
+  return count;
+}
+
+function importEvidenceRecords(
+  records: TrapImportEvidence[],
+  trap: { id: number; scope: string },
+  adapter: TrapArchiveImportAdapter
+): void {
+  for (const evidence of records) {
+    try {
+      adapter.addEvidence(
+        trap.id,
+        buildTrapEvidenceInput(toEvidenceInput(evidence)),
+        trap.scope
+      );
+    } catch {
+      // Preserve valid trap imports even if one evidence record is malformed.
+    }
+  }
+}
+
+function toTrapInput(record: TrapImportRecord): TrapInput {
+  return {
+    title: record.title,
+    category: record.category,
+    tags: parseOptionalTrapTags(record.tags),
+    scope: record.scope,
+    context: record.context,
+    mistake: record.mistake,
+    fix: record.fix,
+    before_code: record.before_code ?? undefined,
+    after_code: record.after_code ?? undefined,
+    severity: record.severity ?? undefined,
+    project_path: record.project_path ?? undefined,
+  };
+}
+
+function toEvidenceInput(evidence: TrapImportEvidence): Record<string, unknown> {
+  return {
+    source_type: evidence.source_type,
+    source_ref: evidence.source_ref ?? undefined,
+    observed_at: evidence.observed_at ?? undefined,
+    related_files: parseOptionalEvidenceRelatedFiles(evidence.related_files),
+    note: evidence.note ?? undefined,
+  };
+}

package/src/lib/trap-json-fields.ts

@@ -0,0 +1,42 @@
+export type TrapStringArrayInput = string[] | string | null | undefined;
+
+export function parseTrapTags(value: TrapStringArrayInput): string[] {
+  return parseStringArrayField(value);
+}
+
+export function parseOptionalTrapTags(value: TrapStringArrayInput): string[] | undefined {
+  return emptyToUndefined(parseTrapTags(value));
+}
+
+export function encodeTrapTags(value: TrapStringArrayInput): string {
+  return JSON.stringify(parseTrapTags(value));
+}
+
+export function parseEvidenceRelatedFiles(value: TrapStringArrayInput): string[] {
+  return parseStringArrayField(value);
+}
+
+export function parseOptionalEvidenceRelatedFiles(value: TrapStringArrayInput): string[] | undefined {
+  return emptyToUndefined(parseEvidenceRelatedFiles(value));
+}
+
+export function encodeEvidenceRelatedFiles(value: TrapStringArrayInput): string {
+  return JSON.stringify(parseEvidenceRelatedFiles(value));
+}
+
+function parseStringArrayField(value: TrapStringArrayInput): string[] {
+  if (Array.isArray(value)) return value.map(String);
+  if (value === null || value === undefined || value === "") return [];
+
+  try {
+    const parsed = JSON.parse(value);
+    if (Array.isArray(parsed)) return parsed.map(String);
+    return typeof parsed === "string" && parsed !== "" ? [parsed] : [];
+  } catch {
+    return [value];
+  }
+}
+
+function emptyToUndefined(values: string[]): string[] | undefined {
+  return values.length > 0 ? values : undefined;
+}

package/src/lib/trap-operations.ts

@@ -0,0 +1,127 @@
+import {
+  buildTrapEvidenceInput,
+  buildTrapInput,
+  parseTrapStatus,
+  pickTrapUpdate,
+  type Trap,
+  type TrapActionCard,
+  type TrapDetails,
+  type TrapImportRecord,
+  type TrapSearchResult,
+} from "../domain/trap";
+import type { TrapStore, TrapStats } from "./store";
+import type { SearchMode } from "./constants";
+import { toTrapActionCards } from "./search-result-card";
+
+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 TrapStatsResult = { project: TrapStats | null; global: TrapStats };
+
+export interface SearchTrapsArgs {
+  query: string;
+  category?: string;
+  scope?: string;
+  limit?: number;
+  mode?: SearchMode;
+  status?: string;
+}
+
+export interface ListTrapsArgs {
+  category?: string;
+  scope?: string;
+  limit?: number;
+  offset?: number;
+  status?: string;
+}
+
+export class TrapOperations {
+  constructor(private readonly store: TrapStore) {}
+
+  addTrap(args: Record<string, unknown>): { id: number; scope: string } {
+    return this.store.add(buildTrapInput(args));
+  }
+
+  async searchTrapGroups(args: SearchTrapsArgs): Promise<TrapSearchGroup[]> {
+    return this.store.search(args.query, {
+      category: args.category,
+      scope: args.scope,
+      limit: args.limit ?? 20,
+      mode: args.mode,
+      status: parseTrapStatus(args.status),
+    });
+  }
+
+  async searchTrapCards(args: SearchTrapsArgs): Promise<TrapActionCard[]> {
+    return toTrapActionCards(await this.searchTrapGroups(args));
+  }
+
+  getTrapDetails(id: number, scope?: string): TrapDetails | null {
+    return this.store.getDetails(id, scope);
+  }
+
+  hitTrap(id: number, scope?: string): void {
+    this.store.hit(id, scope);
+  }
+
+  listTraps(args: ListTrapsArgs = {}): TrapListGroup[] {
+    return this.store.list({
+      category: args.category,
+      scope: args.scope,
+      status: parseTrapStatus(args.status),
+      limit: args.limit ?? 50,
+      offset: args.offset,
+    });
+  }
+
+  updateTrap(
+    id: number,
+    args: Record<string, unknown>,
+    scope?: string
+  ): TrapMutationResult {
+    return this.store.update(id, pickTrapUpdate(args), scope);
+  }
+
+  deleteTrap(id: number, scope?: string): TrapMutationResult {
+    return this.store.delete(id, scope);
+  }
+
+  addTrapEvidence(
+    id: number,
+    args: Record<string, unknown>,
+    scope?: string
+  ): AddTrapEvidenceResult {
+    return this.store.addEvidence(id, buildTrapEvidenceInput(args), scope);
+  }
+
+  archiveTrap(id: number, scope?: string): TrapMutationResult {
+    return this.store.archive(id, scope);
+  }
+
+  supersedeTrap(
+    id: number,
+    supersededById: number,
+    scope?: string,
+    stateKey?: string
+  ): TrapMutationResult {
+    return this.store.supersede(id, supersededById, scope, stateKey);
+  }
+
+  getStats(): TrapStatsResult {
+    return this.store.stats();
+  }
+
+  exportTraps(scope?: string): ReturnType<TrapStore["exportAll"]> {
+    return this.store.exportAll({ scope });
+  }
+
+  importTraps(records: TrapImportRecord[]): number {
+    return this.store.importAll(records);
+  }
+}

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

@@ -0,0 +1,73 @@
+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";
+
+export const PASSAGE_VERSION = 1;
+
+export const PASSAGE_FIELD_NAMES = [
+  "title",
+  "category",
+  "context",
+  "mistake",
+  "fix",
+  "tags",
+  "before_code",
+  "after_code",
+  "severity",
+] as const;
+
+export type TrapSearchDocumentFields = SearchTextFields & {
+  title?: string;
+  category?: string;
+  severity?: string;
+};
+
+export function buildTrapSearchText(fields: SearchTextFields): string {
+  return buildSearchText(fields);
+}
+
+export function buildTrapPassage(trap: TrapSearchDocumentFields): string {
+  const tags = parseTrapTags(trap.tags).join(", ");
+  return [
+    trap.title ? `Title: ${trap.title}` : "",
+    trap.category ? `Category: ${trap.category}` : "",
+    trap.severity ? `Severity: ${trap.severity}` : "",
+    tags ? `Tags: ${tags}` : "",
+    trap.context ? `Context: ${trap.context}` : "",
+    trap.mistake ? `Mistake: ${trap.mistake}` : "",
+    trap.fix ? `Fix: ${trap.fix}` : "",
+    trap.before_code ? `Before code:\n${trap.before_code}` : "",
+    trap.after_code ? `After code:\n${trap.after_code}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function hashTrapPassage(passage: string): string {
+  return createHash("sha256").update(passage).digest("hex");
+}
+
+export function passageHashForTrap(trap: TrapSearchDocumentFields): string {
+  return hashTrapPassage(buildTrapPassage(trap));
+}
+
+export function searchTextFieldsChanged(input: Partial<TrapInput>): boolean {
+  return SEARCH_TEXT_FIELD_NAMES.some((field) => input[field] !== undefined);
+}
+
+export function passageFieldsChanged(input: TrapUpdate): boolean {
+  return PASSAGE_FIELD_NAMES.some((field) => input[field] !== undefined);
+}
+
+export function embeddingIsFresh(trap: Trap, embedding: StoredEmbedding | null, config: EmbeddingConfig): boolean {
+  return Boolean(
+    embedding &&
+      embedding.provider === config.provider &&
+      embedding.model === config.model &&
+      embedding.dimensions === config.dimensions &&
+      embedding.passage_version === config.passageVersion &&
+      embedding.passage_hash === passageHashForTrap(trap)
+  );
+}

package/src/mcp/resources.ts

@@ -0,0 +1,26 @@
+export const resourceDefinitions = [
+  {
+    uri: "codetrap://project/recent",
+    name: "Project Recent Traps",
+    description: "The 10 most recently updated traps in the current project",
+    mimeType: "application/json",
+  },
+  {
+    uri: "codetrap://global/recent",
+    name: "Global Recent Traps",
+    description: "The 10 most recently updated traps in the global database",
+    mimeType: "application/json",
+  },
+  {
+    uri: "codetrap://project/top",
+    name: "Project Top Traps",
+    description: "The 20 most frequently hit traps in the current project",
+    mimeType: "application/json",
+  },
+  {
+    uri: "codetrap://global/top",
+    name: "Global Top Traps",
+    description: "The 20 most frequently hit traps in the global database",
+    mimeType: "application/json",
+  },
+];