carto-md 1.1.0 → 1.1.2

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Carto
 
-Carto is free, open source, and community-maintained. The core team owns the merger logic, AST engine, and CLI. The community owns language and framework extractors.
+Carto is free, open source, and community-maintained. The core team owns the merger logic, MCP server, graph clustering, and CLI. The community owns language and framework extractors.
 
 ---
 
@@ -18,14 +18,15 @@ Wanted: Go, Rust, Ruby, Java, PHP, C#.
 
 Framework-specific route and model extraction lives in `src/extractors/`. Each framework is an isolated module.
 
-Currently supported: FastAPI, Express, Next.js App Router, Prisma, HTML fetch(), Plumber, Shiny.
+Currently supported: FastAPI, Express, Next.js App Router, Prisma, tRPC, HTML fetch(), Plumber, Shiny.
 
 Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
 
 ### Tier 3 — Core (review carefully before merging)
 
-- `src/agents/merger.js` — merger logic. One bad merge = developer loses manual notes = project dies. Changes here need strong justification and full test coverage.
-- `src/ast/` — AST engine. Wrong extraction = wrong AGENTS.md = AI gets confident with wrong facts. Worse than no AGENTS.md.
+- `src/agents/merger.js` — merger logic. One bad merge = developer loses manual notes = project dies.
+- `src/agents/domains.js` — graph-based domain clustering. Wrong clusters = wrong context files.
+- `src/mcp/server.js` — MCP server tools. Breaking changes affect Kiro/Cursor/Claude integration.
 - `src/detector/` — framework detection logic.
 - `src/cli/` — CLI commands.
 
@@ -34,36 +35,46 @@ Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
 ## How to add a language
 
 1. Create `src/extractors/languages/yourlanguage.js`
-2. Export a single function: `extractFromFile(filePath, fileContent)`
-3. Return:
+2. Export a plugin object:
 ```js
-{
-  routes: [{ method, path, functionName }],
-  models: [{ className, fields: [{ name, type }] }],
-  functions: [{ name, params }],
-  envVars: ['VAR_NAME']
-}
+module.exports = {
+  name: 'yourlanguage',
+  extensions: ['.ext'],
+  extract(content, relPath) {
+    return {
+      routes: [{ method, path, functionName }],
+      models: [{ className, fields: [{ name, type }] }],
+      functions: [{ name, params, returnType }],
+      envVars: ['VAR_NAME'],
+      dbTables: [{ tableName, modelName }],
+      fetches: [],
+      storageKeys: []
+    };
+  }
+};
 ```
-4. Add it to `src/extractors/loader.js` language map
-5. Test on at least 3 real open-source projects
-6. Open a PR with before/after AGENTS.md examples
+3. The loader auto-discovers it — no changes to `loader.js` needed
+4. Test on at least 3 real open-source projects
+5. Open a PR with before/after AGENTS.md examples
 
 ---
 
 ## How to add a framework extractor
 
-1. Create `src/extractors/yourframework.js`
-2. Export:
+1. Add detection to `src/detector/framework.js`
+2. Add route/model patterns to the relevant language plugin or create a new extractor in `src/extractors/`
+3. Test on at least 2 real projects using that framework
+4. Open a PR with before/after AGENTS.md examples
+
+---
+
+## How to add a domain keyword
+
+Domain clustering lives in `src/agents/domains.js`. The `DOMAIN_MAP` array maps keywords to domain names. If your framework creates a new domain category, add it:
+
 ```js
-{
-  detect(projectRoot, files) → boolean,
-  extractRoutes(filePath, fileContent) → [{ method, path, functionName }],
-  extractModels(filePath, fileContent) → [{ name, fields: [{ name, type }] }]
-}
+{ keywords: ['graphql', 'resolver', 'mutation'], domain: 'GRAPHQL' },
 ```
-3. Add detection logic to `src/detector/framework.js`
-4. Test on at least 2 real projects using that framework
-5. Open a PR with before/after AGENTS.md examples
 
 ---
 
@@ -72,7 +83,7 @@ Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
 - **Never break the merger.** Manual sections in AGENTS.md are sacred. If your change could corrupt them, it needs a full merger test suite pass.
 - **Wrong output is worse than no output.** If your extractor produces incorrect routes or models, AI gets confident with wrong facts. Only ship when accurate on real projects.
 - **Test on unknown repos.** Don't just test on projects you wrote. Find a real open-source repo using the framework and verify the output is correct.
-- **No cloud, no telemetry, no tracking.** Carto is local only. Forever. Don't add any network calls.
+- **No cloud, no telemetry, no tracking.** Carto is local only. Forever. Don't add any network calls except the existing npm update check.
 - **No paid features.** Free forever. MIT. Don't propose monetization.
 
 ---
@@ -84,6 +95,8 @@ git clone https://github.com/theanshsonkar/carto
 cd carto
 npm install
 node src/cli/index.js init   # test in any project
+node src/cli/index.js serve  # test MCP server
+npm test                     # run test suite
 ```
 
 ---
@@ -101,8 +114,9 @@ node src/cli/index.js init   # test in any project
 
 ## Issues
 
-- **Bug**: Open an issue with the project type, command run, and what AGENTS.md produced vs what you expected.
-- **Language request**: Open an issue titled "Language: [name]" — someone from the community will pick it up.
-- **Framework request**: Open an issue titled "Framework: [name]".
+- **Bug**: Open an issue with the project type, command run, and what AGENTS.md or domain files produced vs what you expected.
+- **Language request**: Open an issue titled "Language: [name]"
+- **Framework request**: Open an issue titled "Framework: [name]"
+- **Domain keyword**: Open an issue titled "Domain: [name]" if your codebase doesn't cluster correctly
 
 All issues acknowledged within 24 hours.

package/README.md

@@ -4,13 +4,13 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/carto-md)](https://www.npmjs.com/package/carto-md)
 
-**Maps your codebase so AI stops guessing. Your code changes. AGENTS.md updates. Every AI always knows.**
+**The codebase intelligence layer every AI tool queries instead of guessing.**
 
 ```bash
 npm install -g carto-md
 ```
 
-Carto auto-generates and maintains your `AGENTS.md` — the standard file every AI coding tool reads for project context. Every time you save, your routes, models, functions, and dependencies are extracted and kept current.
+Carto maps your codebase — routes, models, import graph, domain context — and exposes it as a live MCP server that Kiro, Cursor, and Claude can query mid-task. No hallucinations about your own project. No rebuilding context every session.
 
 ---
 
@@ -19,13 +19,23 @@ Carto auto-generates and maintains your `AGENTS.md` — the standard file every
 AI coding tools are blind to your actual project. Every session starts from zero.
 
 - Claude hallucinates your schema
-- Copilot suggests the wrong field names
+- Copilot suggests wrong field names
 - Kiro asks what framework you're using
 - You rebuild context manually, every time
 
-`AGENTS.md` fixes this — a file in your project root that every AI tool reads. But it's static. You write it manually. It gets stale the moment your code changes.
+`AGENTS.md` fixes this — a standard file every AI tool reads. But it's static. You write it manually. It gets stale the moment your code changes.
 
-**Carto makes it live.**
+**Carto makes it live. And queryable.**
+
+| | Without Carto | With Carto |
+|---|---|---|
+| Knows blast radius before editing | Never | Always, instantly |
+| Knows which routes break | Never | Exact list |
+| Plans multi-file changes | Guesses | Fully informed |
+| Hallucinates field names | Often | Never |
+| Understands codebase on session start | 10–20 min | 0 |
+| Works across Kiro, Cursor, Claude, Copilot | Separately | One shared graph |
+| Stays current as code changes | Goes stale | Live on every save |
 
 ---
 
@@ -33,16 +43,15 @@ AI coding tools are blind to your actual project. Every session starts from zero
 
 Same task, two Claude sessions: *"Add a `notes` field to the booking model."*
 
-**Without AGENTS.md:**
+**Without Carto:**
 - Wrong API route: suggested `POST /api/bookings` → actual is `POST /v2/bookings`
 - Wrong handler: suggested `handleNewBooking.ts` → not the creation path
-- Wrong file paths: pointed to v1 API (`apps/api/v1/...`) → v1 is legacy
+- Wrong file paths: pointed to v1 API → v1 is legacy
 - Wrong tRPC file: `bookings.tsx` → actual is `bookings/_router.tsx`
 - Field list: ~15 fields guessed → missing 20+ real fields
-- Couldn't proceed without follow-up: *"Want me to write the exact diffs once you confirm the codebase location?"*
 
-**With AGENTS.md (generated by Carto):**
-- Correct API route: `POST /v2/bookings` ✅
+**With Carto:**
+- Correct API route ✅
 - Correct controller path ✅
 - Correct tRPC file ✅
 - All 35+ booking fields returned accurately ✅
@@ -52,66 +61,146 @@ Same task, two Claude sessions: *"Add a `notes` field to the booking model."*
 
 Not smarter AI. The same AI with accurate facts.
 
-*Stress tested on cal.com (5,018 files): 87% route coverage, 100% model field accuracy, import graph with zero phantom links.*
+---
+
+## How it works
+
+```
+carto init
+      ↓
+Carto maps your codebase
+  → AGENTS.md (79 lines — lean map every AI reads)
+  → .carto/context/AUTH.md, PAYMENTS.md, TRPC.md, DATABASE.md
+  → .carto/map.json (import graph, routes, blast radius)
+  → MCP server auto-wired into Kiro, Cursor, Claude Desktop
+      ↓
+carto watch  (keeps everything live on every file save)
+carto serve  (MCP server — AI tools query graph mid-task)
+```
 
 ---
 
-## Know what breaks before you break it
+## MCP — AI queries your codebase live
 
-Most production bugs aren't logic errors. They're *"I didn't know X depended on Y."*
+`carto init` auto-wires the MCP config into Kiro, Cursor, and Claude Desktop automatically. When Kiro or Cursor is mid-task, it can call Carto directly instead of guessing:
 
-`carto impact` makes that invisible knowledge visible — before you touch anything.
+**`get_blast_radius("src/lib/payments.ts")`**
+```
+Files affected:
+  → apps/web/app/api/checkout/route.ts
+  → apps/web/app/api/webhook/route.ts
+  → packages/trpc/routers/billing.ts
+
+Routes at risk:
+  → POST /api/checkout
+  → POST /api/webhook
+  → POST /trpc/createSubscription
+```
 
-```bash
-carto impact app/models.py
+**`get_routes()`**
+```
+| Method | Path                        | Handler             |
+|--------|-----------------------------|---------------------|
+| POST   | /api/auth/signup            | POST                |
+| GET    | /api/auth/oauth/me          | GET                 |
+| POST   | /trpc/createBooking         | createBooking       |
+| GET    | /trpc/getAvailability       | getAvailability     |
+| ...    | ...                         | ...                 |
+```
 
-# Impact analysis: app/models.py
-#
-# Imported by:
-#   → app/main.py
-#   → app/rules.py
-#   → app/scoring.py
-#   → app/aws_collector.py
-#   → tests/conftest.py
-#
-# Routes affected:
-#   → POST /analyze
-#   → GET /history
-#   → POST /simulate
-#   → ... 12 more
-#
-# Risk: HIGH — 5 files depend on this
+**`get_domain("AUTH")`**
+Returns `AUTH.md` — all auth routes, session models, JWT functions, env vars.
+
+**`get_structure()`**
+Returns import graph, entry points, high impact files, tech stack.
+
+### Manual MCP config (if auto-wire didn't detect your IDE)
+
+**Kiro** — add to `~/.kiro/settings/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "carto": {
+      "command": "carto",
+      "args": ["serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
 ```
 
-No AI. No cloud. Runs in under a second. Locally, from your import graph.
+**Cursor** — add to `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "carto": {
+      "command": "carto",
+      "args": ["serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "carto": {
+      "command": "carto",
+      "args": ["serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
 
-Make it a habit: before touching any file, run `carto impact` first. 10 seconds. Could save hours.
+Then run `carto serve` in your project directory alongside `carto watch`.
 
 ---
 
-## Why not just paste your code?
+## Domain context files
 
-Context windows are large now. But pasting code means:
+Large codebases kill AI accuracy. A 2900-line AGENTS.md means AI reads 500 lines and guesses the rest.
 
-- You decide what's relevant — you're often wrong
-- AI sees a snapshot, not your live state
-- Bigger context ≠ better context
+Carto splits context by domain automatically:
 
-Carto gives AI the map. You give AI the problem. Different jobs.
+```
+AGENTS.md                  → 79 lines, always loaded
+.carto/context/
+  AUTH.md                  → auth routes, session models, JWT functions
+  PAYMENTS.md              → Stripe routes, billing models
+  TRPC.md                  → all tRPC procedures
+  DATABASE.md              → every model, schema, table
+  EVENTS.md                → webhooks, queues, cron jobs
+  CORE.md                  → shared utilities
+```
+
+AI reads AGENTS.md always. Then reads only the relevant domain file for the current task. 400 lines of exact context instead of 2900 lines of everything.
+
+Domain assignment uses your import graph — files that import each other cluster together, regardless of folder names.
 
 ---
 
-## How it works
+## Know what breaks before you break it
 
+```bash
+carto impact apps/web/app/api/auth/signup/route.ts
+
+# Impact analysis: apps/web/app/api/auth/signup/route.ts
+#
+# Imported by:
+#   → apps/web/app/api/auth/signup/handlers/calcomSignupHandler.ts
+#   → apps/web/app/api/auth/signup/handlers/selfHostedHandler.ts
+#
+# Routes at risk:
+#   → POST /api/auth/signup
+#   → ALL /api/auth/signup/handlers
+#
+# Risk: MEDIUM
 ```
-You save a file
-      ↓
-Carto extracts routes, models, functions, env vars
-      ↓
-AGENTS.md updated in 300ms
-      ↓
-Cursor, Copilot, Kiro, Codex, Claude — all read current truth
-```
+
+No AI. No cloud. Runs in under a second. From your live import graph.
 
 ---
 
@@ -121,7 +210,7 @@ Cursor, Copilot, Kiro, Codex, Claude — all read current truth
 npm install -g carto-md
 ```
 
-Or run without installing:
+Or without installing:
 
 ```bash
 npx carto-md init
@@ -132,16 +221,18 @@ npx carto-md init
 ## Usage
 
 ```bash
-# 1. Go to your project
 cd your-project
-
-# 2. Run once — like git init
 carto init
 ```
 
-That's it. Carto installs a git hook. Every `git commit` syncs AGENTS.md automatically — no watching, no manual runs, nothing to remember.
+That's it. Carto:
+- Maps your codebase
+- Generates AGENTS.md + domain context files
+- Auto-wires MCP into Kiro, Cursor, Claude Desktop
+- Installs a git hook — syncs on every commit
 
-Want live updates on every file save too? Run `carto watch` in a background terminal.
+Run `carto watch` in background for live updates on every file save.
+Run `carto serve` to start the MCP server manually if needed.
 
 ---
 
@@ -149,19 +240,14 @@ Want live updates on every file save too? Run `carto watch` in a background term
 
 | Command | What it does |
 |---------|-------------|
-| `carto init` | Detect stack, generate AGENTS.md, install git hook — auto-syncs on every commit |
-| `carto watch` | Live updates on every file save — optional, for between commits |
+| `carto init` | Map codebase, generate context files, wire MCP into IDEs |
+| `carto watch` | Live updates on every file save |
 | `carto sync` | One-time manual refresh |
+| `carto serve` | Start MCP server for Kiro/Cursor/Claude queries |
 | `carto impact <file>` | Show blast radius before touching a file |
 | `carto remove` | Remove AGENTS.md and .carto/ from this project |
 | `carto --version` | Show version |
 
-**When to use each:**
-- `init` — once per project, sets everything up
-- `watch` — optional, if you want updates between commits
-- `sync` — if you skipped watch and need a fresh snapshot
-- `impact` — before editing anything critical
-
 ---
 
 ## Works with
@@ -170,7 +256,7 @@ Want live updates on every file save too? Run `carto watch` in a background term
 |----------|------------|
 | Python | FastAPI, Pydantic |
 | JavaScript | Express, Next.js |
-| TypeScript | Express, Next.js, Prisma |
+| TypeScript | Express, Next.js, Prisma, tRPC |
 | R | Plumber, Shiny, R6, S7 |
 | HTML | fetch() calls |
 
@@ -178,22 +264,22 @@ More languages via community — open an issue or see [CONTRIBUTING.md](CONTRIBU
 
 ---
 
-## What gets extracted automatically
+## What gets extracted
 
-- API routes — FastAPI, Express, Next.js App Router
-- Data models — Pydantic, Prisma
+- API routes — FastAPI, Express, Next.js App Router, tRPC procedures
+- Data models — Pydantic, Prisma, TypeScript interfaces
 - Function signatures — across all files
-- Dependencies — from `package.json` / `requirements.txt`
-- Environment variable names — never values
-- Frontend API calls — from `fetch()` patterns
 - Import graph — which files depend on which
-- Database tables
+- Domain clusters — AUTH, PAYMENTS, TRPC, DATABASE, EVENTS
+- Blast radius — what breaks if you change a file
+- Environment variable names — never values
+- Database tables — SQLAlchemy, Django ORM, Prisma
 
 ---
 
 ## What Carto never touches
 
-Your manual sections — architecture decisions, active bugs, business rules, coding conventions — stay yours forever. Carto only rewrites between its own markers:
+Your manual sections stay yours forever. Carto only rewrites between its own markers:
 
 ```
 <!-- CARTO:AUTO:START -->
@@ -213,6 +299,7 @@ Carto fixes **factual hallucination about your own project**:
 - AI guessing wrong field names → fixed
 - AI assuming wrong framework → fixed
 - AI guessing wrong DB schema → fixed
+- AI not knowing blast radius → fixed
 
 What Carto does not fix: AI reasoning badly, wrong implementation logic, misunderstanding what you want. Carto makes AI **accurate** about your project. Not smarter. Accurate. Different thing.
 
@@ -220,11 +307,11 @@ What Carto does not fix: AI reasoning badly, wrong implementation logic, misunde
 
 ## AI tools that read AGENTS.md
 
-Drop the file in your project root. Each tool picks it up via its own context config:
-
-- **Cursor** — via context rules
+- **Cursor** — via context rules + MCP
 - **GitHub Copilot** — via workspace instructions
-- **Kiro** — natively
+- **Kiro** — natively + MCP
+- **Claude Desktop** — via MCP
+- **Claude Code** — natively
 - **Codex** — natively
 - **VS Code** — via workspace context
 - **Gemini CLI** — natively
@@ -273,4 +360,4 @@ MIT — free forever.
 
 ---
 
-*Built because AGENTS.md won. Someone had to keep it alive.*
+*Built because AGENTS.md won. Someone had to keep it alive — and make it queryable.*

package/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * carto-md — public module API
+ *
+ * Usage:
+ *   const { Carto } = require('carto-md');
+ *   const carto = new Carto();
+ *   await carto.index('/path/to/project');
+ *
+ *   // Get everything Kepler needs for a file
+ *   const ctx = carto.getContextForFile('src/auth/auth.service.ts');
+ *
+ *   // Listen for live updates
+ *   carto.on('updated', ({ file, blastRadius }) => { ... });
+ */
+
+const { Carto } = require('./src/engine/carto');
+
+module.exports = { Carto };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "carto-md",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"
   },
-  "main": "./src/sync.js",
+  "main": "./index.js",
   "scripts": {
     "test": "node test/test.js"
   },

package/src/cache/file-hash.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function getHashPath(projectRoot) {
+  return path.join(projectRoot, '.carto', 'hashes.json');
+}
+
+function loadHashes(projectRoot) {
+  try {
+    const raw = fs.readFileSync(getHashPath(projectRoot), 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function saveHashes(projectRoot, hashes) {
+  const hashPath = getHashPath(projectRoot);
+  const tmp = hashPath + '.tmp';
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(hashes, null, 2), 'utf-8');
+    fs.renameSync(tmp, hashPath);
+  } catch {}
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha1').update(content).digest('hex');
+}
+
+/**
+ * computeChangedFiles(filePaths, storedHashes, projectRoot)
+ * Returns { changed: string[], unchanged: string[], hashes: object }
+ * changed = files whose content hash differs from stored
+ * unchanged = files whose hash matches — can skip re-parsing
+ */
+function computeChangedFiles(filePaths, storedHashes, projectRoot) {
+  const changed = [];
+  const unchanged = [];
+  const newHashes = { ...storedHashes };
+
+  for (const filePath of filePaths) {
+    const relPath = path.relative(projectRoot, filePath);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+    const hash = hashContent(content);
+    if (storedHashes[relPath] === hash) {
+      unchanged.push(filePath);
+    } else {
+      changed.push(filePath);
+      newHashes[relPath] = hash;
+    }
+  }
+
+  return { changed, unchanged, hashes: newHashes };
+}
+
+/**
+ * updateFileHash(projectRoot, relPath, content)
+ * Updates the hash for a single file after incremental re-index.
+ */
+function updateFileHash(projectRoot, relPath, content) {
+  const hashes = loadHashes(projectRoot);
+  hashes[relPath] = hashContent(content);
+  saveHashes(projectRoot, hashes);
+}
+
+/**
+ * removeFileHash(projectRoot, relPath)
+ * Removes hash entry when a file is deleted.
+ */
+function removeFileHash(projectRoot, relPath) {
+  const hashes = loadHashes(projectRoot);
+  delete hashes[relPath];
+  saveHashes(projectRoot, hashes);
+}
+
+module.exports = { loadHashes, saveHashes, hashContent, computeChangedFiles, updateFileHash, removeFileHash };