codetrap 0.1.0

package/scripts/build-release.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+
+import { chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+type ReleaseTarget = {
+  target: string;
+  name: string;
+  windows?: boolean;
+};
+
+const releaseDir = join(process.cwd(), "dist", "release");
+
+const targets: ReleaseTarget[] = [
+  { target: "bun-darwin-arm64", name: "codetrap-darwin-arm64" },
+  { target: "bun-darwin-x64", name: "codetrap-darwin-x64" },
+  { target: "bun-linux-x64-baseline", name: "codetrap-linux-x64" },
+  { target: "bun-linux-arm64", name: "codetrap-linux-arm64" },
+  { target: "bun-windows-x64-baseline", name: "codetrap-windows-x64.exe", windows: true },
+];
+
+await rm(releaseDir, { recursive: true, force: true });
+await mkdir(releaseDir, { recursive: true });
+
+for (const item of targets) {
+  const outfile = join(releaseDir, item.name);
+  console.log(`Building ${item.name} (${item.target})`);
+  const proc = Bun.spawnSync({
+    cmd: [
+      "bun",
+      "build",
+      "--compile",
+      `--target=${item.target}`,
+      "./src/index.ts",
+      "--outfile",
+      outfile,
+    ],
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  if (!proc.success) {
+    process.exit(proc.exitCode ?? 1);
+  }
+
+  if (!item.windows) {
+    await chmod(outfile, 0o755);
+  }
+}
+
+const files = (await readdir(releaseDir)).filter((file) => file !== "sha256sums.txt").sort();
+const lines: string[] = [];
+
+for (const file of files) {
+  const path = join(releaseDir, file);
+  const bytes = await Bun.file(path).arrayBuffer();
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  const hex = [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  lines.push(`${hex}  ${file}`);
+}
+
+await writeFile(join(releaseDir, "sha256sums.txt"), `${lines.join("\n")}\n`);
+console.log(`Release assets written to ${releaseDir}`);
+

package/scripts/check-release-version.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+
+const tag = process.argv[2] ?? process.env.RELEASE_TAG ?? process.env.GITHUB_REF_NAME;
+
+if (!tag) {
+  console.error("Release tag is required. Pass v<package.version> as an argument.");
+  process.exit(1);
+}
+
+const packageJson = await Bun.file("package.json").json() as { version?: string };
+const expected = `v${packageJson.version}`;
+
+if (tag !== expected) {
+  console.error(`Release tag ${tag} does not match package version ${expected}.`);
+  process.exit(1);
+}
+
+console.log(`Release tag ${tag} matches package version ${packageJson.version}.`);
+

package/skills/codetrap-add/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codetrap-add
+description: Record a coding pitfall as a structured codetrap entry. Use when the user wants to save a lesson learned, recurring AI mistake, project convention, or runs /codetrap-add.
+---
+
+You are helping the user record a "coding pitfall" (a mistake pattern that AI coding assistants tend to make, and the correct approach). These pitfalls are stored in a local database and will be used to warn AI in future sessions.
+
+## Step 1: Gather information
+
+Ask the user to describe what went wrong. Guide them to provide:
+
+1. **What was the AI asked to do?** (the triggering context)
+2. **What did the AI do wrong?** (the mistake)
+3. **What should it have done instead?** (the fix)
+4. **How serious is this?** (warning / error / critical)
+
+If the user already provided enough detail, don't re-ask — just proceed to structuring.
+
+## Step 2: Determine scope
+
+Ask the user (or infer from context):
+- **project**: This pitfall is specific to the current project (e.g., "this project uses fetchWrapper instead of axios")
+- **global**: This pitfall applies across all projects (e.g., "never store secrets in frontend code")
+
+If a `.codetrap/` directory exists in the project, default to `project`. Otherwise default to `global`.
+
+## Step 3: Determine category
+
+Pick the best-fitting category:
+- `api` — HTTP requests, REST, GraphQL, API design
+- `database` — SQL, ORM, migrations, connections
+- `auth` — Authentication, authorization, sessions, tokens
+- `convention` — Project-specific conventions, naming, file structure
+- `security` — Vulnerabilities, secrets, input validation
+- `performance` — Bottlenecks, caching, bundle size
+- `bug` — Common logic errors, edge cases
+- `other` — Everything else
+
+## Step 4: Structure and save
+
+Convert the user's description into this JSON structure and call the CLI:
+
+```bash
+codetrap add --json '{
+  "title": "<one-line summary>",
+  "category": "<category>",
+  "scope": "<project|global>",
+  "context": "<when does this happen?>",
+  "mistake": "<what the AI does wrong>",
+  "fix": "<what should be done instead>",
+  "tags": ["<tag1>", "<tag2>"],
+  "severity": "<warning|error|critical>",
+  "before_code": "<wrong code snippet (optional)>",
+  "after_code": "<correct code snippet (optional)>"
+}'
+```
+
+If the CLI is not available, use the MCP tool `add_trap` instead.
+
+## Step 5: Confirm
+
+Tell the user:
+- The trap ID and scope
+- Suggest running `codetrap stats` to see the growing knowledge base
+- Remind them: next time AI works in this area, `/codetrap-check` will catch this pitfall

package/skills/codetrap-check/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: codetrap-check
+description: Check the codetrap pitfall database before code changes and apply relevant lessons. Use before non-trivial coding work, when touching risky areas, or when the user runs /codetrap-check.
+---
+
+Before generating any non-trivial code, pause and check the codetrap database for relevant pitfalls. This is a "pre-flight check" that prevents you from repeating known mistakes.
+
+## When to trigger
+
+Run this check when:
+1. The user asks you to write or modify code
+2. The task touches an area with recorded pitfalls (API, auth, database, security, etc.)
+3. The user explicitly runs `/codetrap-check`
+
+Do NOT run for: trivial text changes, questions about code, documentation-only changes.
+
+## Step 1: Extract key terms
+
+From the user's request, extract search keywords. Focus on:
+- Technology names: "axios", "prisma", "jwt", "react"
+- Patterns: "middleware", "endpoint", "migration", "hook"
+- Domains: "authentication", "database", "routing", "state"
+
+## Step 2: Search the database
+
+Call the MCP tool `search_traps` with the extracted keywords. Search both project and global scopes.
+
+## Step 3: Apply the lessons
+
+For each relevant trap found:
+1. Read the action card's `avoid` and `do_instead`
+2. If the card is highly relevant and you are about to edit code, call `get_trap` with `next_action.details_args.id` and `next_action.details_args.scope`
+3. Adjust your code generation to follow the correct approach
+4. If a trap matches exactly what you were about to do, explicitly tell the user: "I was about to [avoid], but the codetrap database says [do_instead]. I'll do it the right way."
+
+## Step 4: Report
+
+Briefly tell the user which traps you found and how you adjusted:
+```
+Checked codetrap: found 2 relevant pitfalls. Avoiding [X] and using [Y] instead.
+```
+
+If no traps found, say nothing — don't waste tokens.
+
+## Step 5: Record new pitfalls
+
+If while writing code you discover a NEW pitfall that isn't in the database, suggest: "This seems like a recurring pitfall. Want me to record it with `/codetrap-add`?"

package/skills/codetrap-search/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: codetrap-search
+description: Search the codetrap pitfall database for known mistakes and project lessons. Use when starting work in a new area or when the user asks whether similar issues were seen before.
+---
+
+Search the codetrap database for recorded pitfalls matching the user's query. Use the MCP tool `search_traps` or the CLI `codetrap search`.
+
+## When to use
+
+- Before writing code in a new area (e.g., "I need to write authentication middleware")
+- When the user asks "have we seen issues with X before?"
+- When starting a task that resembles something that caused problems in the past
+
+## How to search
+
+### Via MCP (preferred)
+
+Call the `search_traps` MCP tool:
+```
+search_traps(query="<keywords>", scope=<optional>, category=<optional>)
+```
+
+`search_traps` returns compact action cards. Each card includes `avoid`, `do_instead`, and `next_action.details_args` with both `id` and `scope`. Preserve that scope when calling `get_trap`.
+
+### Via CLI
+
+```bash
+codetrap search "<keywords>" [--scope project|global] [--category api|database|...]
+```
+
+## How to present results
+
+1. Show the most relevant traps first (project scope traps before global)
+2. Summarize each card's title, severity, `avoid`, and `do_instead`
+3. If a card is highly relevant and you are about to edit code, call `get_trap` with the card's `id` and `scope` before proceeding
+4. If no results, tell the user (this is a new area with no recorded pitfalls yet)
+
+## Example
+
+User: "I need to add a new API endpoint"
+→ Search: `search_traps(query="API endpoint")`
+→ Results show: "Don't use axios, use fetchWrapper" (project, error)
+→ Tell user: "I see a project convention: always use fetchWrapper instead of axios. I'll follow that."

package/src/commands/router.ts

@@ -0,0 +1,407 @@
+import { readFileSync } from "node:fs";
+import { TrapStore } from "../lib/store";
+import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
+import type { Trap } from "../domain/trap";
+import { SEARCH_MODES, type SearchMode } from "../lib/constants";
+import { TrapOperations } from "../lib/trap-operations";
+
+type ParsedArgs = {
+  opts: Record<string, string>;
+  positionals: string[];
+};
+
+export async function run(strip: string[], store: TrapStore): Promise<void> {
+  const sub = strip[0];
+  const args = strip.slice(1);
+  const operations = new TrapOperations(store);
+
+  switch (sub) {
+    case "add":
+      return cmdAdd(args, operations);
+    case "search":
+      return cmdSearch(args, operations);
+    case "list":
+      return cmdList(args, operations);
+    case "show":
+      return cmdShow(args, operations);
+    case "edit":
+      return cmdEdit(args, operations);
+    case "delete":
+    case "rm":
+      return cmdDelete(args, operations);
+    case "add_trap_evidence":
+    case "add-evidence":
+      return cmdAddTrapEvidence(args, operations);
+    case "archive_trap":
+    case "archive":
+      return cmdArchiveTrap(args, operations);
+    case "supersede_trap":
+    case "supersede":
+      return cmdSupersedeTrap(args, operations);
+    case "init":
+      return cmdInit(args, store);
+    case "export":
+      return cmdExport(args, operations);
+    case "import":
+      return cmdImport(args, operations);
+    case "stats":
+      return cmdStats(args, operations);
+    case "embed":
+      return cmdEmbed(args, store);
+    default:
+      console.log(`Unknown command: ${sub}`);
+      console.log("Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, embed");
+      process.exit(1);
+  }
+}
+
+export function parseArgs(args: string[]): ParsedArgs {
+  const opts: Record<string, string> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+      opts[key] = val;
+    } else {
+      positionals.push(args[i]);
+    }
+  }
+  return { opts, positionals };
+}
+
+// ---- commands ----
+
+function cmdInit(_args: string[], store: TrapStore): void {
+  if (store.hasProject()) {
+    console.log(`Already in a project: ${store.getProjectRoot()}`);
+    return;
+  }
+  // init is handled by index.ts before creating the store
+  console.log("Project initialized.");
+}
+
+function cmdAdd(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  // --json mode for AI/script usage
+  if (opts.json !== undefined) {
+    if (!opts.json || opts.json === "true") {
+      console.error("Error: --json requires a JSON string argument");
+      process.exit(1);
+    }
+    try {
+      const input = JSON.parse(opts.json);
+      const result = operations.addTrap(input);
+      console.log(`Trap #${result.id} added to ${result.scope} scope.`);
+    } catch (e: any) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Quick mode: codetrap add "title"
+  if (positionals.length > 0) {
+    console.log(`Use --json mode for structured input.`);
+    console.log(`Quick add: codetrap add --json '{"title":"${positionals.join(" ")}","category":"other","scope":"global","context":"...","mistake":"...","fix":"..."}'`);
+    return;
+  }
+
+  // Interactive mode
+  console.log("Interactive mode not yet implemented. Use --json for now.");
+  console.log('Example: codetrap add --json \'{"title":"...","category":"convention","scope":"project","context":"...","mistake":"...","fix":"..."}\'');
+}
+
+async function cmdSearch(args: string[], operations: TrapOperations): Promise<void> {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap search <query> [--category X] [--limit N] [--mode fts|semantic|hybrid] [--status active|superseded|archived|all]");
+    process.exit(1);
+  }
+  let cards: Awaited<ReturnType<TrapOperations["searchTrapCards"]>>;
+  try {
+    const mode = opts.mode ? parseSearchMode(opts.mode) : undefined;
+    cards = await operations.searchTrapCards({
+      query: positionals.join(" "),
+      category: opts.category,
+      scope: opts.scope,
+      limit: opts.limit ? parseInt(opts.limit) : 20,
+      mode,
+      status: opts.status,
+    });
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+
+  let count = 0;
+  for (const card of cards) {
+    console.log(formatTrapActionCard(card));
+    console.log("");
+    count++;
+  }
+  if (count === 0) console.log("No traps found.");
+}
+
+function cmdList(args: string[], operations: TrapOperations): void {
+  const { opts } = parseArgs(args);
+
+  let groups: { traps: Trap[]; scope: string }[];
+  try {
+    groups = operations.listTraps({
+      category: opts.category,
+      scope: opts.scope,
+      status: opts.status,
+      limit: opts.limit ? parseInt(opts.limit) : 50,
+    });
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+
+  let count = 0;
+  for (const group of groups) {
+    for (const t of group.traps) {
+      console.log(formatTrapShort(t, group.scope));
+      count++;
+    }
+  }
+  if (count === 0) console.log("No traps found.");
+}
+
+function cmdShow(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap show <id> [--scope project|global]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  if (isNaN(id)) {
+    console.error("Error: id must be a number");
+    process.exit(1);
+  }
+
+  const result = operations.getTrapDetails(id, opts.scope);
+  if (!result) {
+    console.error(`Trap #${id} not found.`);
+    process.exit(1);
+  }
+
+  operations.hitTrap(id, result.scope);
+  console.log(formatTrapDetails(result));
+}
+
+function cmdEdit(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap edit <id> --json '{\"title\":\"new title\"}' [--scope project|global]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  if (isNaN(id)) {
+    console.error("Error: id must be a number");
+    process.exit(1);
+  }
+
+  if (!opts.json) {
+    console.error("Error: edit requires --json for now.");
+    console.error("Example: codetrap edit 1 --json '{\"title\":\"new title\"}' [--scope project|global]");
+    process.exit(1);
+  }
+
+  try {
+    const parsed = JSON.parse(opts.json);
+    const result = operations.updateTrap(id, parsed, opts.scope);
+    if (result.success) {
+      console.log(`Trap #${id} updated in ${result.scope} scope.`);
+    } else {
+      console.error(`Trap #${id} not found or no fields changed.`);
+      process.exit(1);
+    }
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function cmdDelete(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap delete <id> [--scope project|global]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  if (isNaN(id)) {
+    console.error("Error: id must be a number");
+    process.exit(1);
+  }
+
+  const result = operations.deleteTrap(id, opts.scope);
+  if (result.success) {
+    console.log(`Trap #${id} deleted from ${result.scope} scope.`);
+  } else {
+    console.error(`Trap #${id} not found.`);
+    process.exit(1);
+  }
+}
+
+function cmdAddTrapEvidence(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap add_trap_evidence <id> --source_type manual|conversation|commit|issue|test_failure [--scope project|global] [--source_ref X] [--related_files a,b] [--note X]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  if (isNaN(id)) {
+    console.error("Error: id must be a number");
+    process.exit(1);
+  }
+
+  try {
+    const input = opts.json ? JSON.parse(opts.json) : {
+      source_type: opts.source_type ?? opts["source-type"],
+      source_ref: opts.source_ref ?? opts["source-ref"],
+      observed_at: opts.observed_at ?? opts["observed-at"],
+      related_files: parseCsv(opts.related_files ?? opts["related-files"]),
+      note: opts.note,
+    };
+    const result = operations.addTrapEvidence(id, input, opts.scope);
+    if (!result.success) {
+      console.error(`Trap #${id} not found.`);
+      process.exit(1);
+    }
+    console.log(`Evidence #${result.evidence_id} added to trap #${id} in ${result.scope} scope.`);
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function cmdArchiveTrap(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap archive_trap <id> [--scope project|global]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  if (isNaN(id)) {
+    console.error("Error: id must be a number");
+    process.exit(1);
+  }
+
+  const result = operations.archiveTrap(id, opts.scope);
+  if (result.success) {
+    console.log(`Trap #${id} archived in ${result.scope} scope.`);
+  } else {
+    console.error(`Trap #${id} not found.`);
+    process.exit(1);
+  }
+}
+
+function cmdSupersedeTrap(args: string[], operations: TrapOperations): void {
+  const { opts, positionals } = parseArgs(args);
+  if (positionals.length < 2) {
+    console.error("Usage: codetrap supersede_trap <old_id> <new_id> [--scope project|global] [--state_key key]");
+    process.exit(1);
+  }
+
+  const id = parseInt(positionals[0]);
+  const supersededById = parseInt(positionals[1]);
+  if (isNaN(id) || isNaN(supersededById)) {
+    console.error("Error: ids must be numbers");
+    process.exit(1);
+  }
+
+  const result = operations.supersedeTrap(id, supersededById, opts.scope, opts.state_key ?? opts["state-key"]);
+  if (result.success) {
+    console.log(`Trap #${id} superseded by #${supersededById} in ${result.scope} scope.`);
+  } else {
+    console.error(`Trap #${id} or #${supersededById} not found in the same scope.`);
+    process.exit(1);
+  }
+}
+
+function cmdExport(args: string[], operations: TrapOperations): void {
+  const { opts } = parseArgs(args);
+  const traps = operations.exportTraps(opts.scope);
+  console.log(JSON.stringify(traps, null, 2));
+}
+
+function cmdImport(args: string[], operations: TrapOperations): void {
+  const { positionals } = parseArgs(args);
+  if (positionals.length === 0) {
+    console.error("Usage: codetrap import <file.json>");
+    process.exit(1);
+  }
+
+  const data = readFileSync(positionals[0], "utf-8");
+  const traps = JSON.parse(data);
+  if (!Array.isArray(traps)) {
+    console.error("Error: JSON file must contain an array of traps");
+    process.exit(1);
+  }
+
+  const count = operations.importTraps(traps);
+  console.log(`Imported ${count} traps.`);
+}
+
+function cmdStats(_args: string[], operations: TrapOperations): void {
+  const stats = operations.getStats();
+
+  if (stats.project) {
+    console.log("── Project ──");
+    printStats(stats.project);
+  }
+  console.log("── Global ──");
+  printStats(stats.global);
+}
+
+async function cmdEmbed(args: string[], store: TrapStore): Promise<void> {
+  const { opts } = parseArgs(args);
+  try {
+    const result = await store.ensureEmbeddings({
+      scope: opts.scope,
+      category: opts.category,
+      limit: opts.limit ? parseInt(opts.limit) : undefined,
+      force: opts.force === "true",
+      batchSize: opts["batch-size"] ? parseInt(opts["batch-size"]) : undefined,
+    });
+    for (const scoped of result.scopes) {
+      console.log(`[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`);
+    }
+    console.log(`Total generated: ${result.generated}, skipped: ${result.skipped}, batches: ${result.batches}`);
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function printStats(s: { total: number; byCategory: Record<string, number>; bySeverity: Record<string, number> }): void {
+  console.log(`  Total: ${s.total}`);
+  console.log("  By category:");
+  for (const [cat, count] of Object.entries(s.byCategory)) {
+    console.log(`    ${cat}: ${count}`);
+  }
+  console.log("  By severity:");
+  for (const [sev, count] of Object.entries(s.bySeverity)) {
+    console.log(`    ${sev}: ${count}`);
+  }
+}
+
+function parseSearchMode(mode: string): SearchMode {
+  if ((SEARCH_MODES as readonly string[]).includes(mode)) return mode as SearchMode;
+  throw new Error(`Invalid search mode: ${mode}. Expected one of: ${SEARCH_MODES.join(", ")}`);
+}
+
+function parseCsv(value?: string): string[] | undefined {
+  if (!value) return undefined;
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}

package/src/db/connection.ts

@@ -0,0 +1,36 @@
+import { Database } from "bun:sqlite";
+import { getGlobalDB, getProjectDB } from "../lib/scope";
+import { initSchema } from "./schema";
+
+let globalDB: Database | null = null;
+const projectDBs = new Map<string, Database>();
+
+export function openDatabase(path = ":memory:"): Database {
+  const db = new Database(path);
+  configureDatabase(db);
+  return db;
+}
+
+export function openGlobal(): Database {
+  if (!globalDB) {
+    const path = getGlobalDB();
+    globalDB = openDatabase(path);
+  }
+  return globalDB;
+}
+
+export function openProject(root: string): Database {
+  const path = getProjectDB(root);
+  if (!projectDBs.has(path)) {
+    const db = openDatabase(path);
+    projectDBs.set(path, db);
+  }
+  return projectDBs.get(path)!;
+}
+
+function configureDatabase(db: Database): void {
+  db.exec("PRAGMA journal_mode=WAL");
+  db.exec("PRAGMA foreign_keys=ON");
+  db.exec("PRAGMA busy_timeout=5000");
+  initSchema(db);
+}