codetrap 0.1.0

package/src/db/schema.ts

@@ -0,0 +1,205 @@
+import type { Database } from "bun:sqlite";
+import { CATEGORIES, SEVERITIES, SCOPES, SCHEMA_VERSION } from "../lib/constants";
+import { buildTrapSearchText } from "../lib/trap-search-document";
+
+export function initSchema(db: Database): void {
+  // Schema version table — add migrations here when breaking schema changes are needed
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER NOT NULL
+    );
+  `);
+
+  const versionRow = db.query("SELECT version FROM schema_version").get() as { version: number } | null;
+  const current = versionRow?.version ?? 0;
+
+  if (current < SCHEMA_VERSION) {
+    applyMigrations(db, current);
+  }
+
+  if (!versionRow) {
+    db.exec(`
+      INSERT INTO schema_version (version) VALUES (${SCHEMA_VERSION})
+    `);
+  } else if (current === 0) {
+    db.prepare("UPDATE schema_version SET version = ?").run(SCHEMA_VERSION);
+  }
+}
+
+function applyMigrations(db: Database, from: number): void {
+  // v0 → v1: initial schema
+  if (from < 1) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS traps (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title TEXT NOT NULL,
+        category TEXT NOT NULL CHECK(category IN ('${CATEGORIES.join("','")}')),
+        tags TEXT NOT NULL DEFAULT '[]',
+        scope TEXT NOT NULL CHECK(scope IN ('${SCOPES.join("','")}')),
+        context TEXT NOT NULL,
+        mistake TEXT NOT NULL,
+        fix TEXT NOT NULL,
+        before_code TEXT,
+        after_code TEXT,
+        severity TEXT NOT NULL DEFAULT 'warning' CHECK(severity IN ('${SEVERITIES.join("','")}')),
+        project_path TEXT,
+        hit_count INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS traps_fts USING fts5(
+        title, context, mistake, fix, tags,
+        content='traps',
+        content_rowid='id'
+      );
+    `);
+
+    createFTSTriggersV1(db);
+    db.prepare("UPDATE schema_version SET version = ?").run(1);
+  }
+
+  if (from < 2) {
+    if (!columnExists(db, "traps", "search_text")) {
+      db.exec("ALTER TABLE traps ADD COLUMN search_text TEXT NOT NULL DEFAULT ''");
+    }
+
+    const rows = db
+      .query("SELECT id, title, context, mistake, fix, tags, before_code, after_code FROM traps")
+      .all() as {
+      id: number;
+      title: string;
+      context: string;
+      mistake: string;
+      fix: string;
+      tags: string;
+      before_code: string | null;
+      after_code: string | null;
+    }[];
+
+    const update = db.prepare("UPDATE traps SET search_text = ? WHERE id = ?");
+    for (const row of rows) {
+      update.run(buildTrapSearchText(row), row.id);
+    }
+
+    dropFTS(db);
+    createFTSWithSearchText(db);
+    db.exec(`
+      INSERT INTO traps_fts(rowid, title, context, mistake, fix, tags, search_text)
+      SELECT id, title, context, mistake, fix, tags, search_text FROM traps;
+    `);
+    db.prepare("UPDATE schema_version SET version = ?").run(2);
+  }
+
+  if (from < 3) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS trap_embeddings (
+        trap_id INTEGER PRIMARY KEY REFERENCES traps(id) ON DELETE CASCADE,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        dimensions INTEGER NOT NULL,
+        passage_version INTEGER NOT NULL,
+        passage_hash TEXT NOT NULL,
+        embedding BLOB NOT NULL,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+    db.prepare("UPDATE schema_version SET version = ?").run(3);
+  }
+
+  if (from < 4) {
+    if (!columnExists(db, "traps", "state_key")) {
+      db.exec("ALTER TABLE traps ADD COLUMN state_key TEXT");
+    }
+    if (!columnExists(db, "traps", "status")) {
+      db.exec("ALTER TABLE traps ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+    }
+    if (!columnExists(db, "traps", "supersedes_id")) {
+      db.exec("ALTER TABLE traps ADD COLUMN supersedes_id INTEGER REFERENCES traps(id) ON DELETE SET NULL");
+    }
+    if (!columnExists(db, "traps", "valid_from")) {
+      db.exec("ALTER TABLE traps ADD COLUMN valid_from TEXT");
+      db.exec("UPDATE traps SET valid_from = COALESCE(created_at, datetime('now')) WHERE valid_from IS NULL");
+    }
+    if (!columnExists(db, "traps", "valid_until")) {
+      db.exec("ALTER TABLE traps ADD COLUMN valid_until TEXT");
+    }
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS trap_evidence (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        trap_id INTEGER NOT NULL REFERENCES traps(id) ON DELETE CASCADE,
+        source_type TEXT NOT NULL,
+        source_ref TEXT,
+        observed_at TEXT NOT NULL DEFAULT (datetime('now')),
+        related_files TEXT NOT NULL DEFAULT '[]',
+        note TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+
+    db.prepare("UPDATE schema_version SET version = ?").run(4);
+  }
+}
+
+function columnExists(db: Database, table: string, column: string): boolean {
+  const rows = db.query(`PRAGMA table_info(${table})`).all() as { name: string }[];
+  return rows.some((row) => row.name === column);
+}
+
+function dropFTS(db: Database): void {
+  db.exec(`
+    DROP TRIGGER IF EXISTS traps_ai;
+    DROP TRIGGER IF EXISTS traps_ad;
+    DROP TRIGGER IF EXISTS traps_au;
+    DROP TABLE IF EXISTS traps_fts;
+  `);
+}
+
+function createFTSTriggersV1(db: Database): void {
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS traps_ai AFTER INSERT ON traps BEGIN
+      INSERT INTO traps_fts(rowid, title, context, mistake, fix, tags)
+      VALUES (new.id, new.title, new.context, new.mistake, new.fix, new.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS traps_ad AFTER DELETE ON traps BEGIN
+      INSERT INTO traps_fts(traps_fts, rowid, title, context, mistake, fix, tags)
+      VALUES ('delete', old.id, old.title, old.context, old.mistake, old.fix, old.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS traps_au AFTER UPDATE ON traps BEGIN
+      INSERT INTO traps_fts(traps_fts, rowid, title, context, mistake, fix, tags)
+      VALUES ('delete', old.id, old.title, old.context, old.mistake, old.fix, old.tags);
+      INSERT INTO traps_fts(rowid, title, context, mistake, fix, tags)
+      VALUES (new.id, new.title, new.context, new.mistake, new.fix, new.tags);
+    END;
+  `);
+}
+
+function createFTSWithSearchText(db: Database): void {
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS traps_fts USING fts5(
+      title, context, mistake, fix, tags, search_text,
+      content='traps',
+      content_rowid='id'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS traps_ai AFTER INSERT ON traps BEGIN
+      INSERT INTO traps_fts(rowid, title, context, mistake, fix, tags, search_text)
+      VALUES (new.id, new.title, new.context, new.mistake, new.fix, new.tags, new.search_text);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS traps_ad AFTER DELETE ON traps BEGIN
+      INSERT INTO traps_fts(traps_fts, rowid, title, context, mistake, fix, tags, search_text)
+      VALUES ('delete', old.id, old.title, old.context, old.mistake, old.fix, old.tags, old.search_text);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS traps_au AFTER UPDATE ON traps BEGIN
+      INSERT INTO traps_fts(traps_fts, rowid, title, context, mistake, fix, tags, search_text)
+      VALUES ('delete', old.id, old.title, old.context, old.mistake, old.fix, old.tags, old.search_text);
+      INSERT INTO traps_fts(rowid, title, context, mistake, fix, tags, search_text)
+      VALUES (new.id, new.title, new.context, new.mistake, new.fix, new.tags, new.search_text);
+    END;
+  `);
+}

package/src/domain/trap.ts

@@ -0,0 +1,304 @@
+import {
+  CATEGORIES,
+  DEFAULT_SEVERITY,
+  EVIDENCE_SOURCE_TYPES,
+  SCOPES,
+  SEVERITIES,
+  TRAP_STATUSES,
+  type Scope,
+  type TrapStatus,
+} from "../lib/constants";
+
+export type { TrapStatus } from "../lib/constants";
+
+export interface Trap {
+  id: number;
+  title: string;
+  category: string;
+  tags: string;
+  scope: string;
+  context: string;
+  mistake: string;
+  fix: string;
+  search_text: string;
+  before_code: string | null;
+  after_code: string | null;
+  severity: string;
+  state_key: string | null;
+  status: TrapStatus;
+  supersedes_id: number | null;
+  valid_from: string;
+  valid_until: string | null;
+  project_path: string | null;
+  hit_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface TrapInput {
+  title: string;
+  category: string;
+  tags?: string[];
+  scope: string;
+  context: string;
+  mistake: string;
+  fix: string;
+  before_code?: string;
+  after_code?: string;
+  severity?: string;
+  project_path?: string | null;
+}
+
+export interface TrapSearchResult {
+  trap: Trap;
+  rank: number;
+  sources?: ("fts" | "semantic")[];
+  score?: number;
+  diagnostics?: { code: string; message: string }[];
+}
+
+export interface TrapActionCard {
+  trap_id: number;
+  scope: Scope;
+  title: string;
+  why_relevant: string;
+  avoid: string;
+  do_instead: string;
+  severity: string;
+  score: number | null;
+  sources: ("fts" | "semantic")[];
+  next_action: {
+    details_tool: "get_trap";
+    details_args: {
+      id: number;
+      scope: Scope;
+    };
+  };
+}
+
+export type TrapUpdate = Partial<Omit<TrapInput, "scope" | "project_path">>;
+
+export interface TrapEvidence {
+  id: number;
+  trap_id: number;
+  source_type: string;
+  source_ref: string | null;
+  observed_at: string;
+  related_files: string;
+  note: string | null;
+  created_at: string;
+}
+
+export interface TrapEvidenceInput {
+  source_type: string;
+  source_ref?: string | null;
+  observed_at?: string | null;
+  related_files?: string[];
+  note?: string | null;
+}
+
+export interface TrapExportEvidence extends Omit<TrapEvidence, "related_files"> {
+  related_files: string[];
+}
+
+export interface TrapExportRecord extends Trap {
+  evidence: TrapExportEvidence[];
+}
+
+export type TrapImportEvidence = Partial<Omit<TrapEvidence, "related_files">> & {
+  source_type: string;
+  related_files?: string[] | string | null;
+};
+
+export type TrapImportRecord = Omit<TrapInput, "tags" | "before_code" | "after_code" | "project_path"> & {
+  tags?: string[] | string | null;
+  before_code?: string | null;
+  after_code?: string | null;
+  project_path?: string | null;
+  evidence?: TrapImportEvidence[];
+};
+
+export interface TrapDetails {
+  trap: Trap;
+  evidence: TrapEvidence[];
+  scope: Scope;
+}
+
+export interface ArchiveTrapInput {
+  id: number;
+  scope?: string;
+}
+
+export interface SupersedeTrapInput {
+  id: number;
+  superseded_by_id: number;
+  scope?: string;
+  state_key?: string;
+}
+
+type JsonSchemaProperty = {
+  type: string;
+  enum?: string[];
+  items?: { type: string };
+  description?: string;
+};
+
+type JsonSchema = {
+  type: string;
+  properties: Record<string, JsonSchemaProperty>;
+  required?: string[];
+};
+
+export const TRAP_REQUIRED_INPUT_FIELDS = [
+  "title",
+  "category",
+  "scope",
+  "context",
+  "mistake",
+  "fix",
+] as const;
+
+export const TRAP_UPDATE_FIELDS = [
+  "title",
+  "category",
+  "context",
+  "mistake",
+  "fix",
+  "tags",
+  "before_code",
+  "after_code",
+  "severity",
+] as const;
+
+export const TRAP_INPUT_SCHEMA_PROPERTIES = {
+  title: { type: "string", description: "Short summary of the pitfall" },
+  category: { type: "string", enum: [...CATEGORIES] as string[] },
+  scope: {
+    type: "string",
+    enum: [...SCOPES] as string[],
+    description: "project = this project only, global = all projects",
+  },
+  context: { type: "string", description: "When does this pitfall typically occur?" },
+  mistake: { type: "string", description: "What the AI tends to do wrong" },
+  fix: { type: "string", description: "What should be done instead" },
+  tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" },
+  before_code: { type: "string", description: "Example of wrong code (optional)" },
+  after_code: { type: "string", description: "Example of correct code (optional)" },
+  severity: { type: "string", enum: [...SEVERITIES] as string[], description: "How severe is this pitfall?" },
+} satisfies Record<keyof Omit<TrapInput, "project_path">, JsonSchemaProperty>;
+
+export function trapInputSchema() {
+  return {
+    type: "object",
+    properties: TRAP_INPUT_SCHEMA_PROPERTIES,
+    required: [...TRAP_REQUIRED_INPUT_FIELDS],
+  };
+}
+
+export function trapUpdateSchema() {
+  const properties = Object.fromEntries(
+    TRAP_UPDATE_FIELDS.map((field) => [field, TRAP_INPUT_SCHEMA_PROPERTIES[field]])
+  );
+  return {
+    type: "object",
+    properties: {
+      id: { type: "number", description: "Trap ID to update" },
+      scope: { type: "string", enum: [...SCOPES] as string[] },
+      ...properties,
+    },
+    required: ["id"],
+  };
+}
+
+export function trapEvidenceInputSchema(): JsonSchema {
+  return {
+    type: "object",
+    properties: {
+      id: { type: "number", description: "Trap ID to attach evidence to" },
+      scope: { type: "string", enum: [...SCOPES] as string[], description: "Which scope to look in" },
+      source_type: {
+        type: "string",
+        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" },
+      observed_at: { type: "string", description: "When this was observed (ISO-like timestamp, optional)" },
+      related_files: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional related file paths",
+      },
+      note: { type: "string", description: "Optional short note about the evidence" },
+    },
+    required: ["id", "source_type"],
+  };
+}
+
+export function archiveTrapInputSchema(): JsonSchema {
+  return {
+    type: "object",
+    properties: {
+      id: { type: "number", description: "Trap ID to archive" },
+      scope: { type: "string", enum: [...SCOPES] as string[], description: "Which scope to look in" },
+    },
+    required: ["id"],
+  };
+}
+
+export function supersedeTrapInputSchema(): JsonSchema {
+  return {
+    type: "object",
+    properties: {
+      id: { type: "number", description: "Trap ID being superseded" },
+      superseded_by_id: { type: "number", description: "Trap ID that replaces the older trap" },
+      scope: { type: "string", enum: [...SCOPES] as string[], description: "Which scope to look in" },
+      state_key: { type: "string", description: "Optional lifecycle group key for this rule family" },
+    },
+    required: ["id", "superseded_by_id"],
+  };
+}
+
+export function buildTrapInput(args: Record<string, any>): TrapInput {
+  return {
+    title: args.title,
+    category: args.category,
+    scope: args.scope,
+    context: args.context,
+    mistake: args.mistake,
+    fix: args.fix,
+    tags: args.tags,
+    before_code: args.before_code,
+    after_code: args.after_code,
+    severity: args.severity ?? DEFAULT_SEVERITY,
+  };
+}
+
+export function buildTrapEvidenceInput(args: Record<string, any>): TrapEvidenceInput {
+  if (!(EVIDENCE_SOURCE_TYPES as readonly string[]).includes(args.source_type)) {
+    throw new Error(`Invalid evidence source_type: ${args.source_type}. Expected one of: ${EVIDENCE_SOURCE_TYPES.join(", ")}`);
+  }
+  return {
+    source_type: args.source_type,
+    source_ref: args.source_ref,
+    observed_at: args.observed_at,
+    related_files: Array.isArray(args.related_files) ? args.related_files.map(String) : undefined,
+    note: args.note,
+  };
+}
+
+export function parseTrapStatus(status?: string): TrapStatus | "all" | undefined {
+  if (!status) return undefined;
+  if (status === "all") return "all";
+  if ((TRAP_STATUSES as readonly string[]).includes(status)) return status as TrapStatus;
+  throw new Error(`Invalid trap status: ${status}. Expected one of: ${TRAP_STATUSES.join(", ")}, all`);
+}
+
+export function pickTrapUpdate(args: Record<string, any>): TrapUpdate {
+  const update: TrapUpdate = {};
+  for (const field of TRAP_UPDATE_FIELDS) {
+    if (args[field] !== undefined) {
+      update[field] = args[field];
+    }
+  }
+  return update;
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { findProjectRoot } from "./lib/scope";
+import { TrapStore } from "./lib/store";
+import { run } from "./commands/router";
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  showHelp();
+} else if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+  showHelp();
+} else if (args[0] === "serve") {
+  import("./mcp/server").then((m) => m.start());
+} else if (args[0] === "init") {
+  const cwd = process.cwd();
+  if (findProjectRoot(cwd)) {
+    console.log("Project already initialized.");
+  } else {
+    const dir = join(cwd, ".codetrap");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    console.log(`Initialized .codetrap/ in ${cwd}`);
+  }
+} else {
+  const store = new TrapStore(process.cwd());
+  await run(args, store);
+}
+
+function showHelp(): void {
+  console.log("codetrap — capture coding pitfalls so AI doesn't repeat mistakes");
+  console.log("");
+  console.log("Commands:");
+  console.log("  init                  Initialize .codetrap/ in current project");
+  console.log("  add                   Add a trap (use --json for structured input)");
+  console.log("  search <query>        Search traps by keyword/semantic/hybrid mode");
+  console.log("  list [--category X]   List traps");
+  console.log("  show <id>             Show trap details");
+  console.log("  edit <id> --json '{}' Edit a trap");
+  console.log("  delete <id>           Delete a trap");
+  console.log("  add_trap_evidence     Attach evidence to a trap");
+  console.log("  archive_trap          Archive a trap");
+  console.log("  supersede_trap        Mark one trap as superseded by another");
+  console.log("  embed                 Generate embeddings for semantic search");
+  console.log("  export                Export traps as JSON");
+  console.log("  import <file.json>    Import traps from JSON");
+  console.log("  stats                 Show statistics");
+  console.log("  serve                 Start MCP server (for Claude Code)");
+  console.log("");
+  console.log("Flags:");
+  console.log("  --scope project|global  Filter by scope");
+  console.log("  --category <name>       Filter by category");
+  console.log("  --mode fts|semantic|hybrid  Search mode");
+  console.log("  --status active|superseded|archived|all  Lifecycle filter");
+  console.log("  --batch-size <n>        Embedding generation batch size");
+  console.log("  --json '{}'             JSON input for add/edit");
+}

package/src/lib/constants.ts

@@ -0,0 +1,56 @@
+export const CATEGORIES = [
+  "api",
+  "database",
+  "auth",
+  "convention",
+  "security",
+  "performance",
+  "bug",
+  "other",
+] as const;
+
+export type Category = (typeof CATEGORIES)[number];
+
+export const CATEGORY_LABELS: Record<Category, string> = {
+  api: "API",
+  database: "DB",
+  auth: "Auth",
+  convention: "Conv",
+  security: "Sec",
+  performance: "Perf",
+  bug: "Bug",
+  other: "Other",
+};
+
+export const SEVERITIES = ["warning", "error", "critical"] as const;
+export type Severity = (typeof SEVERITIES)[number];
+
+export const SEVERITY_ICONS: Record<Severity, string> = {
+  warning: "WARN",
+  error: "ERR!",
+  critical: "CRIT",
+};
+
+export const SCOPES = ["project", "global"] as const;
+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 type EvidenceSourceType = (typeof EVIDENCE_SOURCE_TYPES)[number];
+
+export const SEARCH_MODES = ["fts", "semantic", "hybrid"] as const;
+export type SearchMode = (typeof SEARCH_MODES)[number];
+
+export const DEFAULT_SEVERITY: Severity = "warning";
+export const DEFAULT_CATEGORY: Category = "other";
+export const DEFAULT_TRAP_STATUS: TrapStatus = "active";
+
+// Increment this when schema changes in a breaking way.
+// Migrations are stored in src/db/migrations.ts
+export const SCHEMA_VERSION = 4;
+
+// Directory and file names
+export const CODETRAP_DIR = ".codetrap";
+export const TRAPS_DB_FILE = "traps.db";