codetrap 0.1.0

package/.env.example

@@ -0,0 +1,3 @@
+# Jina AI API key for semantic/hybrid search embeddings.
+# Create one at https://jina.ai/api-dashboard/
+JINA_API_KEY=

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 codetrap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,305 @@
+# codetrap
+
+> A local-first coding pitfall memory bank — record mistakes once, never repeat them twice.
+
+**codetrap** records structured coding pitfalls ("traps") and provides search across them before you write code. It serves both human developers via CLI and AI coding agents via MCP (Model Context Protocol).
+
+## Why?
+
+AI coding agents make the same mistakes repeatedly across sessions and projects. codetrap gives them a shared memory of "what not to do" — so when an agent is about to write code, it can check the trap database first and avoid known pitfalls.
+
+## Quick Start
+
+For detailed setup options, see [Installation](docs/installation.md).
+
+```bash
+# Prerequisites: Bun >= 1.x (https://bun.sh)
+
+# Source install
+git clone <repo-url> && cd codetrap
+bun install
+bun run install:cli
+codetrap --help
+
+# Initialize codetrap data in a project
+codetrap init
+
+# Record your first trap
+codetrap add --json '{
+  "title": "Dont use fetch() without timeout",
+  "category": "api",
+  "scope": "global",
+  "context": "Any external HTTP call in Node/Bun",
+  "mistake": "Using bare fetch() which has no default timeout",
+  "fix": "Always wrap fetch with AbortSignal.timeout(n)",
+  "severity": "critical",
+  "tags": ["fetch", "timeout", "http"]
+}'
+
+# Search for relevant traps
+codetrap search "HTTP request timeout" --mode hybrid
+
+# List all traps
+codetrap list
+
+# Show trap details
+codetrap show 1
+```
+
+## Features
+
+- **Structured trap recording** — title, category, context, mistake, fix, severity, tags, before/after code
+- **Dual scope** — project-scoped (`.codetrap/traps.db`) and global (`~/.codetrap/traps.db`)
+- **Three search modes** — FTS (SQLite FTS5), semantic (Jina embeddings), hybrid (RRF fusion)
+- **Chinese + mixed-language search** — CJK bigram tokenizer, synonym map for Chinese-English terms
+- **MCP server** — 10 tools + 4 resources for AI agent integration
+- **Embedding cache** with freshness tracking — embeddings are rebuildable, stale ones auto-invalidated
+- **Schema migrations** — in-code migration system from v0 through current v3
+- **Single-binary builds** — `bun build --compile` produces standalone binaries in `dist/`
+
+## Directory Structure
+
+```
+codetrap/
+├── src/
+│   ├── index.ts              CLI entry point
+│   ├── mcp-server.ts         MCP server entry point
+│   ├── commands/router.ts    CLI command dispatch
+│   ├── mcp/
+│   │   ├── server.ts         MCP stdio transport + handlers
+│   │   ├── tools.ts          7 MCP tool definitions
+│   │   └── resources.ts      4 MCP resource URIs
+│   ├── domain/trap.ts        Trap types, builders, schemas
+│   ├── lib/
+│   │   ├── store.ts          Project/global scope orchestration
+│   │   ├── search-service.ts FTS/semantic/hybrid search, RRF fusion
+│   │   ├── search-normalizer.ts  CJK bigram, synonyms, search_text
+│   │   ├── fts-query.ts      Safe FTS5 literal query compiler
+│   │   ├── embedder.ts       Jina Embeddings adapter
+│   │   ├── embedding-job.ts  Batch embedding generation
+│   │   ├── format.ts         CLI output formatting
+│   │   ├── scope.ts          Project root detection
+│   │   └── constants.ts      Categories, severities, defaults
+│   ├── db/
+│   │   ├── connection.ts     SQLite connection + PRAGMAs
+│   │   ├── schema.ts         Schema init + migrations
+│   │   ├── queries.ts        CRUD, search, stats, import/export
+│   │   ├── embedding-queries.ts  Embedding storage SQL
+│   │   └── repository.ts     Single-DB facade
+│   └── tests/
+│       ├── search-safety.test.ts
+│       ├── search-normalizer.test.ts
+│       ├── search-chinese.test.ts
+│       ├── search-semantic.test.ts
+│       ├── search-eval.test.ts
+│       └── fixtures/search-eval.json
+├── skills/                   Agent skill definitions
+├── docs/                     Architecture + reference docs
+├── package.json
+├── tsconfig.json
+└── CONTEXT.md                Full project context for AI agents
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `init` | Initialize `.codetrap/` in current project |
+| `add` | Record a new trap (JSON or interactive) |
+| `search <query>` | Search traps (--mode fts\|semantic\|hybrid) |
+| `list` | List traps (--category, --severity, --scope, --limit) |
+| `show <id>` | Show full trap details |
+| `edit <id>` | Edit a trap |
+| `delete <id>` | Delete a trap |
+| `export` | Export traps to JSON |
+| `import` | Import traps from JSON |
+| `stats` | Show database statistics |
+| `embed` | Generate embeddings (requires JINA_API_KEY) |
+| `serve` | Start MCP server |
+
+## Agent Integration
+
+For AI coding agents, use three layers:
+
+- **MCP** gives the agent structured tools like `search_traps` and `add_trap`.
+- **AGENTS.md / CLAUDE.md** tells the agent when to use codetrap.
+- **CLI** is the fallback that works even when MCP is unavailable.
+
+MCP and project guidance are complementary. MCP tells the agent what it can call; `AGENTS.md` or `CLAUDE.md` tells it when to call it.
+
+### MCP Setup
+
+Codex:
+
+```bash
+codex mcp add codetrap -- codetrap serve
+```
+
+Generic MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "codetrap": {
+      "command": "codetrap",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Project Guidance
+
+Add this to `AGENTS.md` for Codex, or to `CLAUDE.md` for Claude Code:
+
+````md
+## Codetrap
+
+Before non-trivial code edits, check codetrap for relevant pitfalls.
+
+Prefer MCP tools when available:
+- `search_traps`
+- `get_trap`
+- `add_trap`
+
+Fallback to CLI:
+
+```bash
+codetrap search "<keywords>" --mode hybrid
+```
+
+When a new recurring mistake or project convention is discovered, ask whether to record it with codetrap.
+````
+
+Recommended behavior:
+
+- Use `search_traps` or `codetrap search` before risky edits in APIs, auth, database, security, migrations, or project conventions.
+- Call `get_trap` for highly relevant results before editing code.
+- Apply the recorded `avoid` and `do_instead` guidance while making changes.
+- Ask before recording a new trap unless the user explicitly requested it.
+
+### Codex Skills
+
+Codex users can optionally install the bundled skills from `skills/`:
+
+- `codetrap-check` — pre-flight check before code changes.
+- `codetrap-search` — search existing lessons.
+- `codetrap-add` — record a new pitfall.
+
+Skills are a convenience layer for Codex users. They do not replace MCP or `AGENTS.md`; they make manual triggers like "run codetrap-check" easier.
+
+### MCP Tools
+
+| Tool | Description |
+|---|---|
+| `search_traps` | Compact action-card search across active traps |
+| `add_trap` | Record a new trap |
+| `get_trap` | Drill down into full trap details and evidence |
+| `list_traps` | List traps with filters |
+| `update_trap` | Edit an existing trap |
+| `delete_trap` | Delete a trap |
+| `add_trap_evidence` | Attach source/evidence metadata |
+| `archive_trap` | Archive a trap so default search skips it |
+| `supersede_trap` | Mark a trap as replaced by another |
+| `get_stats` | Database statistics |
+
+### Resources
+
+- `codetrap://project/recent` — Recently added project traps
+- `codetrap://global/recent` — Recently added global traps
+- `codetrap://project/top` — Most-hit project traps
+- `codetrap://global/top` — Most-hit global traps
+- `codetrap://{scope}/trap/{id}` — Individual trap by ID
+
+## Configuration
+
+| Env Variable | Required | Description |
+|---|---|---|
+| `JINA_API_KEY` | No | Jina AI API key for semantic/hybrid search. Without it, hybrid falls back to FTS. Get one at [jina.ai](https://jina.ai/api-dashboard/) |
+
+All other behavior is configured via sensible defaults — see `src/lib/constants.ts`.
+
+### Jina Embeddings Setup
+
+codetrap works without a Jina API key. In that mode, search uses SQLite FTS keyword matching. If you want semantic search or stronger hybrid search, configure `JINA_API_KEY`.
+
+1. Create a Jina API key from the [Jina AI dashboard](https://jina.ai/api-dashboard/).
+
+2. Add it to your shell environment.
+
+macOS or Linux with zsh:
+
+```bash
+echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+macOS or Linux with bash:
+
+```bash
+echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Windows PowerShell:
+
+```powershell
+setx JINA_API_KEY "your-jina-api-key"
+```
+
+After `setx`, open a new PowerShell window.
+
+3. Verify that the key is visible without printing the secret:
+
+```bash
+bun -e 'console.log(process.env.JINA_API_KEY ? "has-key" : "no-key")'
+```
+
+4. Generate embeddings for the traps you want semantic search to use:
+
+```bash
+cd /path/to/your/project
+codetrap embed --scope project
+codetrap embed --scope global
+```
+
+5. Search with hybrid mode:
+
+```bash
+codetrap search "HTTP request timeout" --mode hybrid
+```
+
+If `JINA_API_KEY` is not set:
+
+- `codetrap search "<query>" --mode fts` works normally.
+- `codetrap search "<query>" --mode hybrid` works, but falls back to FTS.
+- `codetrap search "<query>" --mode semantic` and `codetrap embed` require `JINA_API_KEY`.
+
+## Build
+
+```bash
+bun run build          # Build CLI + MCP server binaries → dist/
+bun run build:cli      # dist/codetrap
+bun run build:serve    # dist/codetrap-serve
+```
+
+## Test
+
+```bash
+bun test src/tests/                    # All tests
+bun test src/tests/search-eval.test.ts # Recall@5 evaluation
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Runtime | Bun + TypeScript |
+| Database | SQLite (bun:sqlite) + FTS5 |
+| Embeddings | Jina AI (`jina-embeddings-v5-text-small`) |
+| MCP | `@modelcontextprotocol/sdk` |
+| Search | FTS5 + cosine similarity + RRF fusion |
+
+## License
+
+MIT

package/docs/installation.md

@@ -0,0 +1,306 @@
+# Installation
+
+codetrap supports three installation paths. Use source installation while developing the tool, binary installation for users who do not want a Bun toolchain, and package-manager installation after publishing the package.
+
+## Method 1: Source Install
+
+Best for developers who want to inspect or modify codetrap.
+
+Requirements:
+
+- Bun 1.x or newer
+- Git
+
+```bash
+git clone <repo-url>
+cd codetrap
+bun install
+bun run install:cli
+codetrap --help
+```
+
+`bun run install:cli` creates a `codetrap` symlink in Bun's global bin directory. On macOS and Linux this is usually:
+
+```bash
+$(bun pm bin -g)/codetrap
+```
+
+After installation, initialize codetrap inside any project:
+
+```bash
+cd /path/to/your/project
+codetrap init
+codetrap stats
+```
+
+Use the CLI from any directory:
+
+```bash
+codetrap search "HTTP request timeout" --mode hybrid
+codetrap add --json '{
+  "title": "Dont use fetch() without timeout",
+  "category": "api",
+  "scope": "project",
+  "context": "Any external HTTP call in Node/Bun",
+  "mistake": "Using bare fetch() which has no default timeout",
+  "fix": "Always wrap fetch with AbortSignal.timeout(n)",
+  "severity": "critical",
+  "tags": ["fetch", "timeout", "http"]
+}'
+```
+
+If you move the codetrap repository after source installation, run this again from the new path:
+
+```bash
+bun run install:cli
+```
+
+## Method 2: Binary Install
+
+Best for ordinary users who only want the `codetrap` command.
+
+This method does not require Bun at runtime once release binaries are published.
+
+### For maintainers
+
+Release binaries are built by `.github/workflows/release.yml` when a version tag is pushed.
+
+1. Make sure `package.json` has the version you want to release.
+
+2. Commit all release changes.
+
+3. Create and push a matching tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release tag must match `package.json` exactly. For example, package version `0.1.0` must use tag `v0.1.0`.
+
+The workflow runs:
+
+```bash
+bun test src/tests
+bun run build:release
+```
+
+It uploads these release assets:
+
+```text
+codetrap-darwin-arm64
+codetrap-darwin-x64
+codetrap-linux-x64
+codetrap-linux-arm64
+codetrap-windows-x64.exe
+sha256sums.txt
+```
+
+You can build the same files locally:
+
+```bash
+bun run build:release
+ls dist/release
+```
+
+### For users
+
+Download the binary for your platform from GitHub Releases, then install it into a directory on your `PATH`.
+
+macOS Apple Silicon:
+
+```bash
+curl -L https://github.com/woertedetiankong/codetrap/releases/latest/download/codetrap-darwin-arm64 -o codetrap
+mkdir -p ~/.local/bin
+mv codetrap ~/.local/bin/codetrap
+chmod +x ~/.local/bin/codetrap
+codetrap --help
+```
+
+macOS Intel:
+
+```bash
+curl -L https://github.com/woertedetiankong/codetrap/releases/latest/download/codetrap-darwin-x64 -o codetrap
+mkdir -p ~/.local/bin
+mv codetrap ~/.local/bin/codetrap
+chmod +x ~/.local/bin/codetrap
+codetrap --help
+```
+
+Linux x64:
+
+```bash
+curl -L https://github.com/woertedetiankong/codetrap/releases/latest/download/codetrap-linux-x64 -o codetrap
+mkdir -p ~/.local/bin
+mv codetrap ~/.local/bin/codetrap
+chmod +x ~/.local/bin/codetrap
+codetrap --help
+```
+
+Make sure `~/.local/bin` is on your `PATH`. For zsh:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Windows PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force "$HOME\bin"
+Invoke-WebRequest `
+  -Uri "https://github.com/woertedetiankong/codetrap/releases/latest/download/codetrap-windows-x64.exe" `
+  -OutFile "$HOME\bin\codetrap.exe"
+codetrap --help
+```
+
+Then add `%USERPROFILE%\bin` to your user `Path`.
+
+## Method 3: Package-Manager Install
+
+Best for long-term use after codetrap is published as a package.
+
+### For maintainers
+
+Package publishing is handled by `.github/workflows/npm-publish.yml` when a GitHub Release is published.
+
+Before automated publishing, configure npm trusted publishing:
+
+1. Create or log into your npm account.
+2. Make sure the package name `codetrap` is available, or rename the package in `package.json`.
+3. On npmjs.com, open the package settings and add a trusted publisher:
+   - Publisher: GitHub Actions
+   - Organization/user: `woertedetiankong`
+   - Repository: `codetrap`
+   - Workflow filename: `npm-publish.yml`
+4. Publish a GitHub Release from the matching version tag.
+
+If npm does not let you configure trusted publishing before the first version exists, do the first publish manually after checking the package contents:
+
+```bash
+npm pack --dry-run
+npm publish --access public
+```
+
+Then configure trusted publishing for future releases.
+
+The workflow runs:
+
+```bash
+bun test src/tests
+npm pack --dry-run
+npm publish --access public
+```
+
+The package is source-based: the npm package installs the `codetrap` command from `src/index.ts`, so users still need Bun installed.
+
+You can preview the npm package locally:
+
+```bash
+npm pack --dry-run
+```
+
+### For users
+
+Bun users can install it globally after publishing:
+
+```bash
+bun add -g codetrap
+codetrap --help
+```
+
+npm users can install it globally if Bun is also installed, because the CLI entrypoint runs with Bun:
+
+```bash
+npm install -g codetrap
+codetrap --help
+```
+
+Until the package is published, use the source install method:
+
+```bash
+git clone <repo-url>
+cd codetrap
+bun install
+bun run install:cli
+```
+
+## Optional: Jina Embeddings
+
+`JINA_API_KEY` is optional. Without it, codetrap still works with SQLite FTS keyword search, and hybrid search falls back to FTS.
+
+Create a key from the [Jina AI dashboard](https://jina.ai/api-dashboard/), then set it globally if you want semantic or hybrid search to work from every directory.
+
+macOS or Linux with zsh:
+
+```bash
+echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+macOS or Linux with bash:
+
+```bash
+echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Windows PowerShell:
+
+```powershell
+setx JINA_API_KEY "your-jina-api-key"
+```
+
+After `setx`, open a new PowerShell window.
+
+Verify that the key is visible without printing the secret:
+
+```bash
+bun -e 'console.log(process.env.JINA_API_KEY ? "has-key" : "no-key")'
+```
+
+Generate embeddings for the traps you want semantic search to use:
+
+```bash
+cd /path/to/your/project
+codetrap embed --scope project
+codetrap embed --scope global
+```
+
+Then search:
+
+```bash
+codetrap search "HTTP request timeout" --mode hybrid
+```
+
+If `JINA_API_KEY` is not set:
+
+- `codetrap search "<query>" --mode fts` works normally.
+- `codetrap search "<query>" --mode hybrid` works, but falls back to FTS.
+- `codetrap search "<query>" --mode semantic` and `codetrap embed` require `JINA_API_KEY`.
+
+## Optional: Codex MCP
+
+If the `codetrap` command is on your `PATH`, add it to Codex as an MCP server:
+
+```bash
+codex mcp add codetrap -- codetrap serve
+```
+
+If your MCP client does not inherit your shell `PATH`, use the absolute path:
+
+```bash
+codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
+```
+
+Agents can also use the CLI directly from `AGENTS.md`:
+
+```md
+Before non-trivial code edits, check codetrap:
+
+codetrap search "<keywords>" --mode hybrid
+
+To add a lesson:
+
+codetrap add --json '{...}'
+```

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "codetrap",
+  "version": "0.1.0",
+  "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woertedetiankong/codetrap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/woertedetiankong/codetrap/issues"
+  },
+  "homepage": "https://github.com/woertedetiankong/codetrap#readme",
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "mcp",
+    "memory",
+    "sqlite"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "src/commands",
+    "src/db",
+    "src/domain",
+    "src/lib",
+    "src/mcp",
+    "src/index.ts",
+    "src/mcp-server.ts",
+    "skills",
+    "scripts",
+    "docs/installation.md",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "codetrap": "./src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "install:cli": "ln -sf \"$PWD/src/index.ts\" \"$(bun pm bin -g)/codetrap\"",
+    "build:release": "bun run scripts/build-release.ts",
+    "check:release-version": "bun run scripts/check-release-version.ts",
+    "build": "bun build ./src/index.ts --compile --outfile dist/codetrap && bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve",
+    "build:cli": "bun build ./src/index.ts --compile --outfile dist/codetrap",
+    "build:serve": "bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}