@homenshum/convex-mcp-nodebench 0.9.1 → 0.9.3

package/README.md

@@ -1,195 +1,233 @@
-# convex-mcp-nodebench
-
-Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, HTTP endpoint analysis, deployment gates, persistent gotcha DB, and methodology guidance.
-
-**Complements** Context7 (raw library docs) and the official Convex MCP (deployment introspection) with structured verification workflows and persistent Convex knowledge.
-
-## 17 Tools across 8 Categories
-
-### Schema Tools
-| Tool | Description |
-|------|-------------|
-| `convex_audit_schema` | Scan schema.ts for anti-patterns: deprecated validators (`v.bigint()`), `v.any()` usage, reserved field names, missing indexes, naming conventions |
-| `convex_suggest_indexes` | Analyze query patterns across all functions and suggest missing indexes |
-| `convex_check_validator_coverage` | Check all exported functions have args + returns validators |
-
-### Function Tools
-| Tool | Description |
-|------|-------------|
-| `convex_audit_functions` | Audit function registration, missing validators, public/internal misuse, action anti-patterns, **cross-call violations** (query calling runMutation/runAction) |
-| `convex_check_function_refs` | Validate api.x.y / internal.x.y references, detect direct function passing |
-
-### HTTP Tools
-| Tool | Description |
-|------|-------------|
-| `convex_analyze_http` | Analyze convex/http.ts for duplicate routes, missing CORS headers, missing OPTIONS preflight handlers, missing httpRouter/httpAction imports |
-
-### Deployment Tools
-| Tool | Description |
-|------|-------------|
-| `convex_pre_deploy_gate` | Pre-deployment quality gate: schema, auth, validators, recent audit results (only blocks on truly critical issues) |
-| `convex_check_env_vars` | Check Convex-specific env vars referenced in code exist in .env files (filters out NODE_ENV, PATH, etc.) |
-
-### Learning Tools
-| Tool | Description |
-|------|-------------|
-| `convex_record_gotcha` | Persist a Convex gotcha/edge case for future reference |
-| `convex_search_gotchas` | Full-text search across known Convex gotchas (BM25 + FTS5) |
-
-### Methodology Tools
-| Tool | Description |
-|------|-------------|
-| `convex_get_methodology` | Step-by-step guides: schema audit, function compliance, deploy verification, knowledge management |
-| `convex_discover_tools` | BM25-scored tool discovery with optional embedding-enhanced semantic search |
-
-### Integration Bridge Tools
-| Tool | Description |
-|------|-------------|
-| `convex_generate_rules_md` | Generate a Convex rules markdown file from gotcha DB, recent audits, and project stats |
-| `convex_snapshot_schema` | Capture schema snapshot for diffing (tracks tables, indexes per table, size). Auto-diffs against previous snapshot |
-| `convex_bootstrap_project` | Comprehensive project health scan: schema, auth, _generated, file count, improvement plan |
-
-### Infrastructure Tools
-| Tool | Description |
-|------|-------------|
-| `convex_check_crons` | Validate crons.ts: duplicate names, public handlers, interval issues |
-| `convex_analyze_components` | Parse convex.config.ts: active/conditional components, unused imports |
-
-## Self-Instruct QuickRefs
-
-Every tool response includes a `quickRef` block telling the agent what to do next:
-
-```json
-{
-  "nextAction": "Run convex_check_validator_coverage to ensure all functions have validators",
-  "nextTools": ["convex_check_validator_coverage", "convex_audit_functions"],
-  "methodology": "convex_schema_audit",
-  "relatedGotchas": ["returns_validator_required", "new_function_syntax"],
-  "confidence": "high"
-}
-```
-
-## Pre-Seeded Gotcha Database
-
-Ships with 32 gotchas extracted from Convex best practices, auto-upserted on upgrade:
-
-### Critical
-- `pagination_cursor_null_first` -- First paginate() call must pass cursor: null
-- `query_no_side_effects` -- Queries CANNOT call runMutation or runAction (runtime error)
-- `use_node_for_external_api` -- Actions calling external APIs need `"use node"` directive
-- `validator_bigint_deprecated` -- Use v.int64() not v.bigint()
-
-### Warnings
-- `ctx_auth_returns_null` -- getUserIdentity() returns null when unauthenticated
-- `http_cors_manual` -- CORS headers must be added manually to HTTP endpoints
-- `http_route_no_wildcard` -- HTTP routes use exact path matching, no wildcards
-- `avoid_v_any` -- v.any() defeats the purpose of validators
-- `mutation_transaction_atomicity` -- Each mutation is a separate transaction
-- `db_get_returns_null` -- ctx.db.get() returns null if document missing
-- `storage_get_returns_null` -- ctx.storage.get() returns null if file missing
-- `convex_1mb_document_limit` -- Documents cannot exceed 1MB
-- `scheduled_function_must_be_internal` -- Scheduled functions should be internal
-- And 19 more covering index ordering, undefined handling, field naming, action patterns...
-
-## Quick Start
-
-### Install
-```bash
-npm install @homenshum/convex-mcp-nodebench
-```
-
-Or from source:
-```bash
-cd packages/convex-mcp-nodebench
-npm install
-npm run build
-```
-
-### Run (stdio)
-```bash
-npx convex-mcp-nodebench
-```
-
-### Dev mode
-```bash
-npx tsx src/index.ts
-```
-
-### Add to MCP config
-```json
-{
-  "mcpServers": {
-    "convex-mcp-nodebench": {
-      "command": "npx",
-      "args": ["@homenshum/convex-mcp-nodebench"]
-    }
-  }
-}
-```
-
-### First prompt
-```
-Search convex gotchas for "pagination" then audit the schema at /path/to/my-project
-```
-
-## Data Storage
-
-Persistent SQLite database at `~/.convex-mcp-nodebench/convex.db`:
-
-- **convex_gotchas** -- Gotcha knowledge base with FTS5 full-text search
-- **schema_snapshots** -- Schema history for table + index diffing
-- **deploy_checks** -- Deployment gate audit trail
-- **audit_results** -- Per-file analysis cache
-
-## Testing
-
-```bash
-npm test
-```
-
-30 tests verify all 17 tools work against the real nodebench-ai codebase (3,147 Convex functions, 323 tables, 82 crons, 8 HTTP routes).
-
-## Architecture
-
-```
-packages/convex-mcp-nodebench/
-  src/
-    index.ts                    -- MCP server entry, tool assembly (17 tools)
-    db.ts                       -- SQLite schema + upsert seed logic
-    types.ts                    -- Tool types, QuickRef interface
-    gotchaSeed.ts               -- 32 pre-seeded Convex gotchas
-    tools/
-      schemaTools.ts            -- Schema audit, index suggestions, validator coverage
-      functionTools.ts          -- Function audit, cross-call detection, reference checking
-      httpTools.ts              -- HTTP endpoint analysis (routes, CORS, duplicates)
-      deploymentTools.ts        -- Pre-deploy gate, env var checking (Convex-filtered)
-      learningTools.ts          -- Gotcha recording + FTS5 search
-      methodologyTools.ts       -- Methodology guides, BM25 tool discovery
-      integrationBridgeTools.ts -- Rules generation, schema snapshots with index diffing, project bootstrap
-      cronTools.ts              -- Cron job validation
-      componentTools.ts         -- Component config analysis
-      toolRegistry.ts           -- Central catalog with quickRef metadata + BM25 scoring
-      embeddingProvider.ts      -- Optional semantic search (Google/OpenAI embeddings)
-    __tests__/
-      tools.test.ts             -- 30 integration tests
-```
-
-## Changelog
-
-### v0.3.0
-- **New tool**: `convex_analyze_http` -- HTTP endpoint analysis (duplicate routes, CORS, OPTIONS handlers)
-- **Cross-call detection**: queries calling `ctx.runMutation`/`ctx.runAction` flagged as critical
-- **12 new gotchas**: pagination, ctx.auth, scheduled functions, HTTP routes, CORS, v.any(), storage, transactions, document limits, "use node"
-- **Schema snapshot diffs** now track index additions/removals per table
-- **env_vars** filtered to Convex-specific patterns (excludes NODE_ENV, PATH, HOME, etc.)
-- **Gotcha seeding** upgraded to upsert -- existing users get new gotchas on upgrade
-- **Bug fixes**: fnv1aHash missing in embeddingProvider, collectTsFilesFlat ESM compat
-
-### v0.2.0
-- Schema audit noise reduced (836 -> 163 issues): index naming aggregated, v.any() detection added
-- Function audit severity corrected: missing returns downgraded from critical to warning
-- Deploy gate threshold: only blocks on >10 criticals
-- npm tarball reduced from 45.9kB to 31.5kB
-
-### v0.1.0
-- Initial release: 16 tools, 20 gotchas, BM25 discovery, embedding-enhanced search
+# convex-mcp-nodebench
+
+Convex-specific MCP server that audits, verifies, and guides Convex development. 36 tools across schema audit, function compliance, security, performance, deployment gates, SARIF reporting, persistent gotcha DB, and adaptive architecture planning.
+
+**Complements** Context7 (raw library docs) and the official Convex MCP (deployment introspection) with structured verification workflows and persistent Convex knowledge.
+
+## 36 Tools
+
+### Core Audit (10 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_audit_schema` | Scan schema.ts for anti-patterns: deprecated validators, `v.any()`, reserved fields, missing indexes |
+| `convex_suggest_indexes` | Analyze query patterns across all functions and suggest missing indexes |
+| `convex_check_validator_coverage` | Check all exported functions have args + returns validators |
+| `convex_audit_functions` | Audit function registration, validators, public/internal misuse, cross-call violations |
+| `convex_check_function_refs` | Validate `api.x.y` / `internal.x.y` references, detect direct function passing |
+| `convex_check_type_safety` | Find `as any` casts, undefined returns, loose ID types across all files |
+| `convex_audit_authorization` | Audit auth guard coverage: which public functions check `getUserIdentity()` |
+| `convex_audit_actions` | Audit actions for direct DB access, missing error handling, external API patterns |
+| `convex_audit_transaction_safety` | Find read-modify-write races, multiple `runMutation` in single functions |
+| `convex_audit_query_efficiency` | Detect unbounded `.collect()`, `.filter()` without index, mutation-as-read |
+
+### Infrastructure Audit (9 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_analyze_http` | Analyze http.ts: duplicate routes, missing CORS, OPTIONS preflight handlers |
+| `convex_check_crons` | Validate crons.ts: duplicate names, public handlers, interval issues |
+| `convex_analyze_components` | Parse convex.config.ts: active/conditional components, unused imports |
+| `convex_audit_storage_usage` | Audit storage: stores, deletes, missing null checks on `getUrl()` |
+| `convex_audit_pagination` | Find paginate calls missing validators or without proper cursor handling |
+| `convex_audit_vector_search` | Audit vector indexes, search calls, dimension mismatches |
+| `convex_audit_schedulers` | Find `runAfter`/`runAt` usage, self-scheduling loops, missing termination |
+| `convex_audit_data_modeling` | Audit tables: deep nesting, dangling refs, `v.any()`, arrays-of-arrays |
+| `convex_audit_dev_setup` | Check project hygiene: _generated dir, tsconfig, package deps, env files |
+
+### Deployment & Quality Gate (4 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_pre_deploy_gate` | Pre-deployment gate: schema, auth, validators, recent audits (blocks on critical) |
+| `convex_check_env_vars` | Check env vars referenced in code exist in .env files (Convex-filtered) |
+| `convex_quality_gate` | Composite quality score (A-F grade) with configurable thresholds |
+| `convex_schema_migration_plan` | Diff schema snapshots and generate migration steps with risk assessment |
+
+### Reporting (2 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_export_sarif` | Export all audit results as SARIF 2.1.0 (GitHub Code Scanning compatible) |
+| `convex_audit_diff` | Compare current audit against baseline: new issues, fixed issues, trend |
+
+### Adaptive Architect (3 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_scan_capabilities` | Regex scan of project structure: function types, data access, auth, storage, schema patterns |
+| `convex_verify_concept` | Verify if a concept (e.g. "Vector Search RAG") is implemented via regex signatures |
+| `convex_generate_plan` | Generate Convex-specific implementation steps for missing signatures |
+
+**Self-discovery loop**: `scan_capabilities` → `verify_concept` → `generate_plan` → implement → re-verify
+
+### Knowledge & Discovery (5 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_record_gotcha` | Persist a Convex gotcha/edge case for future reference |
+| `convex_search_gotchas` | Full-text search across known Convex gotchas (BM25 + FTS5) |
+| `convex_get_methodology` | Step-by-step guides: schema audit, function compliance, deploy verification |
+| `convex_discover_tools` | BM25 + optional embedding-enhanced semantic tool discovery |
+| `convex_critter_check` | Accountability check: scores task intent (why/who/what) before starting work |
+
+### Integration Bridge (3 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `convex_generate_rules_md` | Generate Convex rules markdown from gotcha DB, recent audits, project stats |
+| `convex_snapshot_schema` | Capture schema snapshot for diffing (tables, indexes, size). Auto-diffs against previous |
+| `convex_bootstrap_project` | Comprehensive project health scan with improvement plan |
+
+## Quick Start
+
+### Install
+```bash
+npm install @homenshum/convex-mcp-nodebench
+```
+
+### Add to MCP config (Claude Code, Cursor, Windsurf)
+```json
+{
+  "mcpServers": {
+    "convex-mcp-nodebench": {
+      "command": "npx",
+      "args": ["@homenshum/convex-mcp-nodebench"]
+    }
+  }
+}
+```
+
+### First prompt
+```
+Audit the schema at /path/to/my-project, then run the quality gate
+```
+
+### Optional: Enable semantic search
+Set `GOOGLE_API_KEY` or `OPENAI_API_KEY` env var. The `convex_discover_tools` tool will automatically use embedding-enhanced search when available (Google `text-embedding-004` or OpenAI `text-embedding-3-small`).
+
+## Self-Instruct QuickRefs
+
+Every tool response includes a `quickRef` block guiding the agent to the next step:
+
+```json
+{
+  "nextAction": "Run convex_check_validator_coverage to ensure all functions have validators",
+  "nextTools": ["convex_check_validator_coverage", "convex_audit_functions"],
+  "methodology": "convex_schema_audit",
+  "relatedGotchas": ["returns_validator_required", "new_function_syntax"],
+  "confidence": "high"
+}
+```
+
+## Pre-Seeded Gotcha Database
+
+Ships with 32 gotchas extracted from Convex best practices, auto-upserted on upgrade:
+
+**Critical**: `pagination_cursor_null_first`, `query_no_side_effects`, `use_node_for_external_api`, `validator_bigint_deprecated`
+
+**Warnings**: `ctx_auth_returns_null`, `http_cors_manual`, `http_route_no_wildcard`, `avoid_v_any`, `mutation_transaction_atomicity`, `db_get_returns_null`, `storage_get_returns_null`, `convex_1mb_document_limit`, `scheduled_function_must_be_internal`, and 19 more covering index ordering, undefined handling, field naming, action patterns...
+
+## Data Storage
+
+Persistent SQLite at `~/.convex-mcp-nodebench/convex.db`:
+
+| Table | Purpose |
+|-------|---------|
+| `convex_gotchas` | Knowledge base with FTS5 full-text search |
+| `schema_snapshots` | Schema history for table + index diffing |
+| `deploy_checks` | Deployment gate audit trail |
+| `audit_results` | Per-file analysis cache |
+| `concept_verifications` | Architect concept verification history |
+| `critter_checks` | Task accountability records |
+
+## Testing
+
+```bash
+npm test
+```
+
+63 tests (53 unit + 10 E2E) verify all 36 tools against the real nodebench-ai codebase (3,158 Convex functions, 328 tables, 82 crons, 44 HTTP routes).
+
+## Architecture
+
+```
+packages/convex-mcp-nodebench/
+  src/
+    index.ts                    -- MCP server, tool assembly (36 tools)
+    db.ts                       -- SQLite schema + upsert seed logic
+    types.ts                    -- Tool types, QuickRef interface
+    gotchaSeed.ts               -- 32 pre-seeded Convex gotchas
+    tools/
+      schemaTools.ts            -- Schema audit, index suggestions, validator coverage
+      functionTools.ts          -- Function audit, cross-call detection, ref checking
+      httpTools.ts              -- HTTP endpoint analysis
+      deploymentTools.ts        -- Pre-deploy gate, env var checking
+      learningTools.ts          -- Gotcha recording + FTS5 search
+      methodologyTools.ts       -- Methodology guides, BM25 tool discovery
+      integrationBridgeTools.ts -- Rules generation, schema snapshots, project bootstrap
+      cronTools.ts              -- Cron job validation
+      componentTools.ts         -- Component config analysis
+      critterTools.ts           -- Task accountability checking
+      authorizationTools.ts     -- Auth guard audit
+      queryEfficiencyTools.ts   -- Query performance audit
+      actionAuditTools.ts       -- Action anti-pattern detection
+      typeSafetyTools.ts        -- Type safety audit
+      transactionSafetyTools.ts -- Transaction race detection
+      storageAuditTools.ts      -- Storage usage audit
+      paginationTools.ts        -- Pagination pattern audit
+      dataModelingTools.ts      -- Data modeling audit
+      devSetupTools.ts          -- Dev environment audit
+      migrationTools.ts         -- Schema migration planning
+      reportingTools.ts         -- SARIF export, baseline diff
+      vectorSearchTools.ts      -- Vector search audit
+      schedulerTools.ts         -- Scheduler audit
+      qualityGateTools.ts       -- Composite quality gate
+      architectTools.ts         -- Capability scan, concept verify, plan generation
+      toolRegistry.ts           -- Central catalog with quickRef + BM25 scoring
+      embeddingProvider.ts      -- Optional semantic search (Google/OpenAI embeddings)
+    __tests__/
+      tools.test.ts             -- 53 unit/integration tests
+      architectE2E.test.ts      -- 10 E2E tests (industry-latest concept verification)
+```
+
+## Changelog
+
+### v0.9.1
+- **Fix**: Strategy matching order in architect tools -- specific patterns (`ctx.db.query`, `ctx.runMutation`) now matched before generic keywords (`query`, `mutation`)
+
+### v0.9.0
+- **3 new tools**: `convex_scan_capabilities`, `convex_verify_concept`, `convex_generate_plan` -- adaptive architect with Convex-specific regex patterns, strategies, and file hints
+- **Self-discovery loop**: scan → verify → plan → implement → re-verify
+- **7 Convex pattern categories**: function types, schema, data access, auth, storage, client-side, cross-function calls
+- **~40 Convex-specific strategies** in `inferConvexStrategy()` with correct priority ordering
+- **10 new E2E tests** validating architect tools against industry-latest concepts (Vector Search RAG, Real-Time Collaboration, File Upload Pipeline, Scheduled Retry Queue, Row-Level Security)
+
+### v0.8.0
+- **14 new tools**: authorization audit, query efficiency, action audit, type safety, transaction safety, storage audit, pagination audit, data modeling audit, dev setup audit, schema migration planning, SARIF 2.1.0 export, baseline diff, vector search audit, scheduler audit
+- **Quality gate**: Composite A-F scoring with configurable thresholds
+- **SARIF 2.1.0**: GitHub Code Scanning compatible export aggregating all audit types
+- **Baseline diff**: Track audit trends (improving/stable/degrading) over time
+- **MCP Resources**: `project-health`, `recent-audits`, `gotcha-db`
+- **MCP Prompts**: `full-audit`, `pre-deploy-checklist`, `security-review`
+
+### v0.4.0
+- **New tool**: `convex_critter_check` -- task accountability with 10 calibrated checks
+- **Cross-call fix**: improved detection of query→mutation violations
+- **v.any() aggregation**: grouped by table for cleaner output
+
+### v0.3.0
+- **New tool**: `convex_analyze_http` -- HTTP endpoint analysis
+- **Cross-call detection**: queries calling `ctx.runMutation`/`ctx.runAction` flagged as critical
+- **12 new gotchas**: pagination, ctx.auth, scheduled functions, HTTP routes, CORS, storage, transactions
+- **Schema snapshot diffs** track index additions/removals per table
+- **Gotcha seeding** upgraded to upsert
+
+### v0.2.0
+- Schema audit noise reduced (836 -> 163 issues)
+- Function audit severity corrected
+- Deploy gate threshold: only blocks on >10 criticals
+- npm tarball reduced from 45.9kB to 31.5kB
+
+### v0.1.0
+- Initial release: 16 tools, 20 gotchas, BM25 discovery, embedding-enhanced search

package/dist/db.js

@@ -3,99 +3,99 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
 let _db = null;
-const SCHEMA_SQL = `
-PRAGMA journal_mode = WAL;
-PRAGMA busy_timeout = 5000;
-PRAGMA foreign_keys = ON;
-
--- ═══════════════════════════════════════════
--- CONVEX GOTCHAS (Persistent knowledge base)
--- ═══════════════════════════════════════════
-
-CREATE TABLE IF NOT EXISTS convex_gotchas (
-  id            INTEGER PRIMARY KEY AUTOINCREMENT,
-  key           TEXT NOT NULL UNIQUE,
-  content       TEXT NOT NULL,
-  category      TEXT NOT NULL DEFAULT 'general',
-  severity      TEXT NOT NULL DEFAULT 'warning',
-  convex_version TEXT,
-  tags          TEXT,
-  source        TEXT NOT NULL DEFAULT 'seed',
-  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
-  updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE VIRTUAL TABLE IF NOT EXISTS convex_gotchas_fts USING fts5(
-  key,
-  content,
-  category,
-  tags,
-  content='convex_gotchas',
-  content_rowid='id'
-);
-
-CREATE TRIGGER IF NOT EXISTS gotchas_fts_insert AFTER INSERT ON convex_gotchas BEGIN
-  INSERT INTO convex_gotchas_fts(rowid, key, content, category, tags)
-  VALUES (new.id, new.key, new.content, new.category, COALESCE(new.tags, ''));
-END;
-
-CREATE TRIGGER IF NOT EXISTS gotchas_fts_delete AFTER DELETE ON convex_gotchas BEGIN
-  INSERT INTO convex_gotchas_fts(convex_gotchas_fts, rowid, key, content, category, tags)
-  VALUES ('delete', old.id, old.key, old.content, old.category, COALESCE(old.tags, ''));
-END;
-
-CREATE TRIGGER IF NOT EXISTS gotchas_fts_update AFTER UPDATE ON convex_gotchas BEGIN
-  INSERT INTO convex_gotchas_fts(convex_gotchas_fts, rowid, key, content, category, tags)
-  VALUES ('delete', old.id, old.key, old.content, old.category, COALESCE(old.tags, ''));
-  INSERT INTO convex_gotchas_fts(rowid, key, content, category, tags)
-  VALUES (new.id, new.key, new.content, new.category, COALESCE(new.tags, ''));
-END;
-
--- ═══════════════════════════════════════════
--- SCHEMA SNAPSHOTS (for diff/audit history)
--- ═══════════════════════════════════════════
-
-CREATE TABLE IF NOT EXISTS schema_snapshots (
-  id            TEXT PRIMARY KEY,
-  project_dir   TEXT NOT NULL,
-  schema_json   TEXT NOT NULL,
-  function_spec TEXT,
-  snapshot_at   TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_schema_snapshots_project ON schema_snapshots(project_dir);
-
--- ═══════════════════════════════════════════
--- DEPLOYMENT CHECKS (audit trail)
--- ═══════════════════════════════════════════
-
-CREATE TABLE IF NOT EXISTS deploy_checks (
-  id            TEXT PRIMARY KEY,
-  project_dir   TEXT NOT NULL,
-  check_type    TEXT NOT NULL,
-  passed        INTEGER NOT NULL DEFAULT 0,
-  findings      TEXT,
-  checked_at    TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_deploy_checks_project ON deploy_checks(project_dir);
-
--- ═══════════════════════════════════════════
--- AUDIT RESULTS (per-file analysis cache)
--- ═══════════════════════════════════════════
-
-CREATE TABLE IF NOT EXISTS audit_results (
-  id            TEXT PRIMARY KEY,
-  project_dir   TEXT NOT NULL,
-  audit_type    TEXT NOT NULL,
-  file_path     TEXT,
-  issues_json   TEXT NOT NULL,
-  issue_count   INTEGER NOT NULL DEFAULT 0,
-  audited_at    TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_audit_results_project ON audit_results(project_dir);
-CREATE INDEX IF NOT EXISTS idx_audit_results_type ON audit_results(audit_type);
+const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA busy_timeout = 5000;
+PRAGMA foreign_keys = ON;
+
+-- ═══════════════════════════════════════════
+-- CONVEX GOTCHAS (Persistent knowledge base)
+-- ═══════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS convex_gotchas (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  key           TEXT NOT NULL UNIQUE,
+  content       TEXT NOT NULL,
+  category      TEXT NOT NULL DEFAULT 'general',
+  severity      TEXT NOT NULL DEFAULT 'warning',
+  convex_version TEXT,
+  tags          TEXT,
+  source        TEXT NOT NULL DEFAULT 'seed',
+  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS convex_gotchas_fts USING fts5(
+  key,
+  content,
+  category,
+  tags,
+  content='convex_gotchas',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS gotchas_fts_insert AFTER INSERT ON convex_gotchas BEGIN
+  INSERT INTO convex_gotchas_fts(rowid, key, content, category, tags)
+  VALUES (new.id, new.key, new.content, new.category, COALESCE(new.tags, ''));
+END;
+
+CREATE TRIGGER IF NOT EXISTS gotchas_fts_delete AFTER DELETE ON convex_gotchas BEGIN
+  INSERT INTO convex_gotchas_fts(convex_gotchas_fts, rowid, key, content, category, tags)
+  VALUES ('delete', old.id, old.key, old.content, old.category, COALESCE(old.tags, ''));
+END;
+
+CREATE TRIGGER IF NOT EXISTS gotchas_fts_update AFTER UPDATE ON convex_gotchas BEGIN
+  INSERT INTO convex_gotchas_fts(convex_gotchas_fts, rowid, key, content, category, tags)
+  VALUES ('delete', old.id, old.key, old.content, old.category, COALESCE(old.tags, ''));
+  INSERT INTO convex_gotchas_fts(rowid, key, content, category, tags)
+  VALUES (new.id, new.key, new.content, new.category, COALESCE(new.tags, ''));
+END;
+
+-- ═══════════════════════════════════════════
+-- SCHEMA SNAPSHOTS (for diff/audit history)
+-- ═══════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS schema_snapshots (
+  id            TEXT PRIMARY KEY,
+  project_dir   TEXT NOT NULL,
+  schema_json   TEXT NOT NULL,
+  function_spec TEXT,
+  snapshot_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_schema_snapshots_project ON schema_snapshots(project_dir);
+
+-- ═══════════════════════════════════════════
+-- DEPLOYMENT CHECKS (audit trail)
+-- ═══════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS deploy_checks (
+  id            TEXT PRIMARY KEY,
+  project_dir   TEXT NOT NULL,
+  check_type    TEXT NOT NULL,
+  passed        INTEGER NOT NULL DEFAULT 0,
+  findings      TEXT,
+  checked_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_deploy_checks_project ON deploy_checks(project_dir);
+
+-- ═══════════════════════════════════════════
+-- AUDIT RESULTS (per-file analysis cache)
+-- ═══════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS audit_results (
+  id            TEXT PRIMARY KEY,
+  project_dir   TEXT NOT NULL,
+  audit_type    TEXT NOT NULL,
+  file_path     TEXT,
+  issues_json   TEXT NOT NULL,
+  issue_count   INTEGER NOT NULL DEFAULT 0,
+  audited_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_results_project ON audit_results(project_dir);
+CREATE INDEX IF NOT EXISTS idx_audit_results_type ON audit_results(audit_type);
 `;
 export function getDb() {
     if (_db)
@@ -112,14 +112,14 @@ export function genId(prefix) {
 export function seedGotchasIfEmpty(gotchas) {
     const db = getDb();
     // Upsert: insert new seed gotchas, skip user-created ones (source != 'seed')
-    const upsert = db.prepare(`INSERT INTO convex_gotchas (key, content, category, severity, tags, source)
-     VALUES (?, ?, ?, ?, ?, 'seed')
-     ON CONFLICT(key) DO UPDATE SET
-       content = excluded.content,
-       category = excluded.category,
-       severity = excluded.severity,
-       tags = excluded.tags,
-       updated_at = datetime('now')
+    const upsert = db.prepare(`INSERT INTO convex_gotchas (key, content, category, severity, tags, source)
+     VALUES (?, ?, ?, ?, ?, 'seed')
+     ON CONFLICT(key) DO UPDATE SET
+       content = excluded.content,
+       category = excluded.category,
+       severity = excluded.severity,
+       tags = excluded.tags,
+       updated_at = datetime('now')
      WHERE source = 'seed'`);
     const tx = db.transaction(() => {
         for (const g of gotchas) {

package/dist/index.js

@@ -79,7 +79,7 @@ for (const tool of ALL_TOOLS) {
 // ── Server setup ────────────────────────────────────────────────────
 const server = new Server({
     name: "convex-mcp-nodebench",
-    version: "0.9.1",
+    version: "0.9.3",
 }, {
     capabilities: {
         tools: {},
@@ -328,27 +328,27 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
                     role: "user",
                     content: {
                         type: "text",
-                        text: `Run a complete audit of the Convex project at "${projectDir}". Execute these tools in order:
-
-1. convex_audit_schema — Check schema.ts for anti-patterns
-2. convex_audit_functions — Audit function registration and compliance
-3. convex_audit_authorization — Check auth coverage on public endpoints
-4. convex_audit_query_efficiency — Find unbounded queries and missing indexes
-5. convex_audit_actions — Validate action safety (no ctx.db, error handling)
-6. convex_check_type_safety — Find as-any casts and type issues
-7. convex_audit_transaction_safety — Detect race conditions
-8. convex_audit_storage_usage — Check file storage patterns
-9. convex_audit_pagination — Validate pagination implementations
-10. convex_audit_data_modeling — Check schema design quality
-11. convex_audit_vector_search — Validate vector search setup
-12. convex_audit_schedulers — Check scheduled function safety
-13. convex_audit_dev_setup — Verify project setup
-14. convex_quality_gate — Run configurable quality gate across all results
-
-After running all audits, summarize:
-- Total issues by severity (critical/warning/info)
-- Top 5 most impactful issues to fix first
-- Quality gate score and grade
+                        text: `Run a complete audit of the Convex project at "${projectDir}". Execute these tools in order:
+
+1. convex_audit_schema — Check schema.ts for anti-patterns
+2. convex_audit_functions — Audit function registration and compliance
+3. convex_audit_authorization — Check auth coverage on public endpoints
+4. convex_audit_query_efficiency — Find unbounded queries and missing indexes
+5. convex_audit_actions — Validate action safety (no ctx.db, error handling)
+6. convex_check_type_safety — Find as-any casts and type issues
+7. convex_audit_transaction_safety — Detect race conditions
+8. convex_audit_storage_usage — Check file storage patterns
+9. convex_audit_pagination — Validate pagination implementations
+10. convex_audit_data_modeling — Check schema design quality
+11. convex_audit_vector_search — Validate vector search setup
+12. convex_audit_schedulers — Check scheduled function safety
+13. convex_audit_dev_setup — Verify project setup
+14. convex_quality_gate — Run configurable quality gate across all results
+
+After running all audits, summarize:
+- Total issues by severity (critical/warning/info)
+- Top 5 most impactful issues to fix first
+- Quality gate score and grade
 - Trend direction if previous audits exist (use convex_audit_diff)`,
                     },
                 },
@@ -363,16 +363,16 @@ After running all audits, summarize:
                     role: "user",
                     content: {
                         type: "text",
-                        text: `Run pre-deployment checks for the Convex project at "${projectDir}":
-
-1. convex_pre_deploy_gate — Structural checks (schema, auth config, initialization)
-2. convex_check_env_vars — Verify all required env vars are set
-3. convex_audit_authorization — Ensure auth coverage is adequate
-4. convex_audit_actions — No ctx.db access in actions
-5. convex_snapshot_schema — Capture current schema state
-6. convex_schema_migration_plan — Compare against previous snapshot for breaking changes
-7. convex_quality_gate — Final quality check with thresholds
-
+                        text: `Run pre-deployment checks for the Convex project at "${projectDir}":
+
+1. convex_pre_deploy_gate — Structural checks (schema, auth config, initialization)
+2. convex_check_env_vars — Verify all required env vars are set
+3. convex_audit_authorization — Ensure auth coverage is adequate
+4. convex_audit_actions — No ctx.db access in actions
+5. convex_snapshot_schema — Capture current schema state
+6. convex_schema_migration_plan — Compare against previous snapshot for breaking changes
+7. convex_quality_gate — Final quality check with thresholds
+
 Report: DEPLOY or DO NOT DEPLOY with specific blockers to fix.`,
                     },
                 },
@@ -387,15 +387,15 @@ Report: DEPLOY or DO NOT DEPLOY with specific blockers to fix.`,
                     role: "user",
                     content: {
                         type: "text",
-                        text: `Run a security review of the Convex project at "${projectDir}":
-
-1. convex_audit_authorization — Auth coverage on all public endpoints
-2. convex_check_type_safety — Type safety bypasses (as any)
-3. convex_audit_actions — Action safety (ctx.db, error handling, "use node")
-4. convex_audit_storage_usage — Storage permission patterns
-5. convex_audit_pagination — Unbounded numItems (DoS risk)
-6. convex_audit_transaction_safety — Race condition risks
-
+                        text: `Run a security review of the Convex project at "${projectDir}":
+
+1. convex_audit_authorization — Auth coverage on all public endpoints
+2. convex_check_type_safety — Type safety bypasses (as any)
+3. convex_audit_actions — Action safety (ctx.db, error handling, "use node")
+4. convex_audit_storage_usage — Storage permission patterns
+5. convex_audit_pagination — Unbounded numItems (DoS risk)
+6. convex_audit_transaction_safety — Race condition risks
+
 Focus on: unauthorized data access, unvalidated inputs, missing error boundaries, and potential data corruption vectors.`,
                     },
                 },

package/dist/tools/authorizationTools.js

@@ -97,16 +97,17 @@ function auditAuthorization(convexDir) {
                     withoutAuth++;
                     // Critical: public mutation/action with DB writes but no auth
                     if ((ft === "mutation" || ft === "action") && hasDbWrite) {
+                        const sensitiveHint = isSensitiveName ? ` Name "${funcName}" suggests a destructive operation.` : "";
                         issues.push({
                             severity: "critical",
                             location: `${relativePath}:${i + 1}`,
                             functionName: funcName,
-                            message: `Public ${ft} "${funcName}" writes to DB without auth check. Any client can call this.`,
+                            message: `Public ${ft} "${funcName}" writes to DB without auth check. Any client can call this.${sensitiveHint}`,
                             fix: `Add: const identity = await ctx.auth.getUserIdentity(); if (!identity) throw new Error("Not authenticated");`,
                         });
                     }
-                    // Critical: sensitive-named function without auth
-                    if (isSensitiveName) {
+                    else if (isSensitiveName) {
+                        // Only flag sensitive name separately if not already caught by DB-write check
                         issues.push({
                             severity: "critical",
                             location: `${relativePath}:${i + 1}`,

package/dist/tools/critterTools.js

@@ -12,18 +12,18 @@ import { getDb } from "../db.js";
 // ── DB setup ────────────────────────────────────────────────────────────────
 function ensureCritterTable() {
     const db = getDb();
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS critter_checks (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      task TEXT NOT NULL,
-      why TEXT NOT NULL,
-      who TEXT NOT NULL,
-      success_looks_like TEXT,
-      score INTEGER NOT NULL,
-      verdict TEXT NOT NULL,
-      feedback TEXT NOT NULL,
-      created_at TEXT NOT NULL DEFAULT (datetime('now'))
-    )
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS critter_checks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task TEXT NOT NULL,
+      why TEXT NOT NULL,
+      who TEXT NOT NULL,
+      success_looks_like TEXT,
+      score INTEGER NOT NULL,
+      verdict TEXT NOT NULL,
+      feedback TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
   `);
 }
 function scoreCritterCheck(input) {
@@ -188,7 +188,7 @@ export const critterTools = [
             ensureCritterTable();
             const result = scoreCritterCheck(args);
             const db = getDb();
-            db.prepare(`INSERT INTO critter_checks (task, why, who, success_looks_like, score, verdict, feedback)
+            db.prepare(`INSERT INTO critter_checks (task, why, who, success_looks_like, score, verdict, feedback)
          VALUES (?, ?, ?, ?, ?, ?, ?)`).run(args.task, args.why, args.who, args.success_looks_like ?? null, result.score, result.verdict, JSON.stringify(result.feedback));
             return {
                 score: result.score,

package/dist/tools/dataModelingTools.js

@@ -35,6 +35,46 @@ function auditDataModeling(convexDir) {
         tableNames.add(m[1]);
         totalTables++;
     }
+    // Detect spread-imported table providers (e.g. ...authTables adds "users", "sessions")
+    // Strategy 1: Known spreads from popular Convex packages
+    const knownSpreads = {
+        authTables: ["users", "authSessions", "authAccounts", "authRefreshTokens", "authVerificationCodes", "authRateLimits", "authVerifiers"],
+    };
+    // Strategy 2: Parse inline comments next to spreads for table name hints
+    // e.g. ...authTables, // `users`, `sessions`
+    const spreadCommentPattern = /\.\.\.(\w+)\s*,?\s*\/\/\s*(.+)/g;
+    let sm;
+    while ((sm = spreadCommentPattern.exec(content)) !== null) {
+        const spreadName = sm[1];
+        const comment = sm[2];
+        // Extract backtick-quoted or quoted table names from comment
+        const commentTables = [...comment.matchAll(/[`"'](\w+)[`"']/g)].map(m => m[1]);
+        // Merge known + comment-discovered tables
+        const tables = new Set([
+            ...(knownSpreads[spreadName] ?? []),
+            ...commentTables,
+        ]);
+        for (const t of tables) {
+            if (!tableNames.has(t)) {
+                tableNames.add(t);
+                totalTables++;
+            }
+        }
+    }
+    // Strategy 3: If no comment matched, still apply known spreads
+    const simpleSpreadPattern = /\.\.\.(\w+)/g;
+    let sm2;
+    while ((sm2 = simpleSpreadPattern.exec(content)) !== null) {
+        const tables = knownSpreads[sm2[1]];
+        if (tables) {
+            for (const t of tables) {
+                if (!tableNames.has(t)) {
+                    tableNames.add(t);
+                    totalTables++;
+                }
+            }
+        }
+    }
     // Per-table analysis
     let currentTable = "";
     let tableStartLine = 0;

package/dist/tools/learningTools.js

@@ -80,11 +80,11 @@ export const learningTools = [
             let results;
             try {
                 // FTS5 search
-                let sql = `
-          SELECT g.*, rank
-          FROM convex_gotchas g
-          JOIN convex_gotchas_fts fts ON g.id = fts.rowid
-          WHERE convex_gotchas_fts MATCH ?
+                let sql = `
+          SELECT g.*, rank
+          FROM convex_gotchas g
+          JOIN convex_gotchas_fts fts ON g.id = fts.rowid
+          WHERE convex_gotchas_fts MATCH ?
         `;
                 const params = [args.query];
                 if (args.category) {

package/dist/tools/reportingTools.js

@@ -75,7 +75,7 @@ function buildSarif(projectDir, auditTypes, limit) {
                 tool: {
                     driver: {
                         name: "convex-mcp-nodebench",
-                        version: "0.9.1",
+                        version: "0.9.3",
                         informationUri: "https://www.npmjs.com/package/@homenshum/convex-mcp-nodebench",
                         rules: [...rulesMap.values()],
                     },

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@homenshum/convex-mcp-nodebench",
-  "version": "0.9.1",
-  "description": "Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, deployment gates, persistent gotcha DB, and methodology guidance. Complements Context7 (raw docs) and official Convex MCP (deployment introspection) with structured verification workflows.",
-  "type": "module",
-  "bin": {
-    "convex-mcp-nodebench": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "!dist/__tests__",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm run test"
-  },
-  "keywords": [
-    "mcp",
-    "convex",
-    "model-context-protocol",
-    "schema-audit",
-    "function-compliance",
-    "deploy-gates",
-    "gotcha-db",
-    "self-instruct",
-    "ai-agents",
-    "verification"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/HomenShum/nodebench-ai.git",
-    "directory": "packages/convex-mcp-nodebench"
-  },
-  "license": "MIT",
-  "author": "HomenShum",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "better-sqlite3": "^11.0.0"
-  },
-  "optionalDependencies": {
-    "@google/genai": "^1.10.0",
-    "openai": "^5.8.2"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^20.11.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3",
-    "vitest": "^3.2.4"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@homenshum/convex-mcp-nodebench",
+  "version": "0.9.3",
+  "description": "Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, deployment gates, persistent gotcha DB, and methodology guidance. Complements Context7 (raw docs) and official Convex MCP (deployment introspection) with structured verification workflows.",
+  "type": "module",
+  "bin": {
+    "convex-mcp-nodebench": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/__tests__",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "mcp",
+    "convex",
+    "model-context-protocol",
+    "schema-audit",
+    "function-compliance",
+    "deploy-gates",
+    "gotcha-db",
+    "self-instruct",
+    "ai-agents",
+    "verification"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HomenShum/nodebench-ai.git",
+    "directory": "packages/convex-mcp-nodebench"
+  },
+  "license": "MIT",
+  "author": "HomenShum",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "better-sqlite3": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "@google/genai": "^1.10.0",
+    "openai": "^5.8.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}