@graphpilot-oss/graphpilot 0.0.1 → 1.0.0

package/examples/cline/README.md

@@ -0,0 +1,104 @@
+# Cline (VS Code extension) + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Cline.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Open Cline's MCP settings
+
+The easy way:
+
+1. Open VS Code
+2. Open the **Cline panel** (sidebar icon)
+3. Click **MCP Servers**
+4. Click the ⚙ gear icon → **Edit MCP Settings**
+
+That opens `cline_mcp_settings.json`. Direct paths if you prefer to edit it manually:
+
+| OS      | Path                                                                                                            |
+| ------- | --------------------------------------------------------------------------------------------------------------- |
+| macOS   | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+| Linux   | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`                     |
+| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`                     |
+
+## 3. Add the GraphPilot block
+
+Paste the contents of [`cline_mcp_settings.json`](./cline_mcp_settings.json) and replace `/absolute/path/to/graphpilot/` with the real path:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "disabled": false,
+      "autoApprove": [],
+    },
+  },
+}
+```
+
+Post-npm:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "npx",
+      "args": ["graphpilot", "mcp"],
+      "disabled": false,
+      "autoApprove": [],
+    },
+  },
+}
+```
+
+> The `autoApprove` array lets you list tool names that Cline will call without per-call confirmation. Add e.g. `["gp_recall"]` once you're comfortable — leave it empty until then.
+
+## 4. Verify
+
+In the Cline panel → **MCP Servers** section, `graphpilot` should appear with a **green status dot** and 5 tools listed underneath. If it doesn't, restart VS Code.
+
+## 5. Index a repo
+
+From the integrated terminal:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 6. Try it
+
+```text
+Use graphpilot to find who calls authenticate.
+
+Use gp_impact to show the blast radius of renaming parseFile.
+```
+
+Cline will surface a tool-call card with the request → response → "Approve" button. Once approved, the result appears in the chat with `file:line @ sha` evidence anchors.
+
+## 7. Keep the index fresh
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                                | Fix                                                                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Server shows red / disconnected        | Check `disabled: false`. Then try VS Code: Command Palette → "Developer: Reload Window".                                    |
+| Cline can't find tools after a restart | The settings file is JSON-strict — a trailing comma will silently disable the entire `mcpServers` block. Validate the JSON. |
+| Tool calls return "no index"           | Pass an explicit `path: "/abs/repo"`, or run `gp_index` first.                                                              |
+
+## Files in this folder
+
+| File                                                   | Purpose                                                |
+| ------------------------------------------------------ | ------------------------------------------------------ |
+| [`README.md`](./README.md)                             | This walkthrough                                       |
+| [`cline_mcp_settings.json`](./cline_mcp_settings.json) | Sample config — copy the `mcpServers` block into yours |

package/examples/cline/cline_mcp_settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}

package/examples/continue/.continuerules

@@ -0,0 +1,39 @@
+# GraphPilot routing rules for Continue
+
+This repo has a GraphPilot structural code-graph available via MCP. Use it before grep on structural questions.
+
+## When the user asks any of:
+
+- "who calls X" / "what uses X" / "where is X called from"
+- "what does X call" / "what does X depend on"
+- "rename X — what breaks" / "impact of changing X" / "what depends on X"
+- "find function X" / "where is X defined" / "list all interfaces"
+
+→ **Use the graphpilot MCP tools BEFORE grep or reading files.**
+
+| Question kind          | Tool to call                                            |
+| ---------------------- | ------------------------------------------------------- |
+| Define / locate symbol | `gp_recall({ query, substring?, path? })`               |
+| Callers / callees      | `gp_callers({ symbol, direction, path? })`              |
+| Blast radius / rename  | `gp_impact({ symbol, depth?, path? })`                  |
+| PR-scoped blast radius | `gp_impact({ symbol, since: 'main', path? })`           |
+| Index health probe     | `gp_stats({ path? })`                                   |
+| Refresh after edits    | `gp_index({ path? })`                                   |
+
+## When NOT to use GraphPilot
+
+Fall back to grep / read for:
+
+- Comments, JSDoc, string literals, error messages
+- Config files (package.json, tsconfig.json, .env)
+- Markdown / docs
+- Languages other than TypeScript / JavaScript
+- Git history (blame, log)
+
+## After heavy editing
+
+After ~10+ file edits, call `gp_index` once before further structural questions, or run `graphpilot watch` in a side terminal for sub-10 ms incremental updates.
+
+## Citing evidence
+
+Every GraphPilot response carries `file:line @ sha` anchors. When citing results to the user, **include the anchor verbatim** — it's verifiable: the user can jump to that line and the code will match.

package/examples/continue/README.md

@@ -0,0 +1,98 @@
+# Continue.dev + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Continue.
+
+> Continue's MCP support is flagged **experimental** at the time of writing. If the config key below isn't recognized, check the [Continue docs](https://docs.continue.dev) for the current schema.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Edit Continue's config
+
+Two scopes — pick one:
+
+- **Global:** `~/.continue/config.json`
+- **Per-project:** `<your-repo>/.continue/config.json`
+
+Create the file if it doesn't exist. Paste the contents of [`config.json`](./config.json) and replace `/absolute/path/to/graphpilot/` with the real path:
+
+```jsonc
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "node",
+          "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+        },
+      },
+    ],
+  },
+}
+```
+
+Post-npm:
+
+```jsonc
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["graphpilot", "mcp"],
+        },
+      },
+    ],
+  },
+}
+```
+
+## 3. Restart Continue
+
+Reload the VS Code / JetBrains window after editing the config.
+
+## 4. Verify
+
+Continue → Settings → **MCP Servers** panel. `graphpilot` should be listed with 5 tools.
+
+## 5. Index a repo
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 6. Try it
+
+```text
+Use graphpilot's gp_recall to find parseToken.
+
+Use gp_impact to compute the blast radius of renaming authenticate.
+```
+
+## 7. Keep the index fresh
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                                                 | Fix                                                                                       |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `modelContextProtocolServers` reported as "unknown key" | Your Continue version is on an older schema. Check the current docs for the new key name. |
+| Server appears but tools aren't called                  | Continue's MCP autorouting is conservative. Be explicit: _"Use graphpilot's gp_callers…"_ |
+| `pnpm install` native-module errors                     | `pnpm approve-builds --all && pnpm rebuild`. Drop to Node 22 LTS if on 23+.               |
+
+## Files in this folder
+
+| File                           | Purpose                                                      |
+| ------------------------------ | ------------------------------------------------------------ |
+| [`README.md`](./README.md)     | This walkthrough                                             |
+| [`config.json`](./config.json) | Sample `~/.continue/config.json` — copy the block into yours |

package/examples/continue/config.json

@@ -0,0 +1,13 @@
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "node",
+          "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"]
+        }
+      }
+    ]
+  }
+}

package/examples/cursor/.cursorrules

@@ -0,0 +1,39 @@
+# GraphPilot routing rules for Cursor
+
+This repo has a GraphPilot structural code-graph available via MCP. Use it before grep on structural questions.
+
+## When the user asks any of:
+
+- "who calls X" / "what uses X" / "where is X called from"
+- "what does X call" / "what does X depend on"
+- "rename X — what breaks" / "impact of changing X" / "what depends on X"
+- "find function X" / "where is X defined" / "list all interfaces"
+
+→ **Use the graphpilot MCP tools BEFORE grep or reading files.**
+
+| Question kind          | Tool to call                                            |
+| ---------------------- | ------------------------------------------------------- |
+| Define / locate symbol | `gp_recall({ query, substring?, path? })`               |
+| Callers / callees      | `gp_callers({ symbol, direction, path? })`              |
+| Blast radius / rename  | `gp_impact({ symbol, depth?, path? })`                  |
+| PR-scoped blast radius | `gp_impact({ symbol, since: 'main', path? })`           |
+| Index health probe     | `gp_stats({ path? })`                                   |
+| Refresh after edits    | `gp_index({ path? })`                                   |
+
+## When NOT to use GraphPilot
+
+Fall back to grep / read for:
+
+- Comments, JSDoc, string literals, error messages
+- Config files (package.json, tsconfig.json, .env)
+- Markdown / docs
+- Languages other than TypeScript / JavaScript
+- Git history (blame, log)
+
+## After heavy editing
+
+After ~10+ file edits, call `gp_index` once before further structural questions, or run `graphpilot watch` in a side terminal for sub-10 ms incremental updates.
+
+## Citing evidence
+
+Every GraphPilot response carries `file:line @ sha` anchors. When citing results to the user, **include the anchor verbatim** — it's verifiable: the user can jump to that line and the code will match.

package/examples/cursor/README.md

@@ -0,0 +1,98 @@
+# Cursor + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Cursor.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Open Cursor's MCP config
+
+Two ways:
+
+- **UI:** Press `Cmd/Ctrl + ,` → search "MCP" → "Edit MCP config"
+- **File:** open `~/.cursor/mcp.json` directly (create it if it doesn't exist)
+
+Paste the contents of [`mcp.json`](./mcp.json) and replace `/absolute/path/to/graphpilot/` with the real path on your machine:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "env": {
+        "GRAPHPILOT_ROOT": "${workspaceFolder}",
+      },
+    },
+  },
+}
+```
+
+`${workspaceFolder}` lets GraphPilot find the index when the agent omits `path` (MCP cwd is often your home directory, not the repo).
+
+Post-npm:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "npx",
+      "args": ["graphpilot", "mcp"],
+    },
+  },
+}
+```
+
+## 3. Verify
+
+Settings → MCP. `graphpilot` should show as **Connected** with 5 tools listed.
+
+If it shows red after the config change, click the refresh icon next to it — Cursor sometimes caches MCP server state.
+
+## 4. Index a repo
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 5. Auto-routing via `.cursorrules`
+
+Drop [`.cursorrules`](./.cursorrules) into the root of the repo you indexed. It tells Cursor's agent to reach for GraphPilot on structural questions automatically. Re-open the workspace to pick it up.
+
+Try:
+
+```text
+Who calls authenticate in this repo?
+
+What breaks if I rename parseFile?
+```
+
+You should see Cursor invoke `gp_callers` / `gp_impact` in its tool-use trace.
+
+## 6. Keep the index fresh
+
+In a side terminal:
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                            | Fix                                                                                                                                                                           |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Server shows red in Settings → MCP | Click the refresh icon. If still red, run `node dist/cli.js mcp` in a terminal — inspect stderr.                                                                              |
+| `.cursorrules` ignored             | Cursor reads it on workspace open. Close and reopen the folder.                                                                                                               |
+| Tool calls return "no index"       | Add `"env": { "GRAPHPILOT_ROOT": "${workspaceFolder}" }` to MCP config (see `mcp.json`), or copy project `.cursor/mcp.json`. Cursor also sends workspace roots automatically. |
+
+## Files in this folder
+
+| File                             | Purpose                                                              |
+| -------------------------------- | -------------------------------------------------------------------- |
+| [`README.md`](./README.md)       | This walkthrough                                                     |
+| [`mcp.json`](./mcp.json)         | Sample `~/.cursor/mcp.json` — copy the `mcpServers` block into yours |
+| [`.cursorrules`](./.cursorrules) | Routing template — copy to your indexed repo's root for auto-routing |

package/examples/cursor/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+      "env": {
+        "GRAPHPILOT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}

package/examples/windsurf/.windsurfrules

@@ -0,0 +1,39 @@
+# GraphPilot routing rules for Windsurf
+
+This repo has a GraphPilot structural code-graph available via MCP. Use it before grep on structural questions.
+
+## When the user asks any of:
+
+- "who calls X" / "what uses X" / "where is X called from"
+- "what does X call" / "what does X depend on"
+- "rename X — what breaks" / "impact of changing X" / "what depends on X"
+- "find function X" / "where is X defined" / "list all interfaces"
+
+→ **Use the graphpilot MCP tools BEFORE grep or reading files.**
+
+| Question kind          | Tool to call                                            |
+| ---------------------- | ------------------------------------------------------- |
+| Define / locate symbol | `gp_recall({ query, substring?, path? })`               |
+| Callers / callees      | `gp_callers({ symbol, direction, path? })`              |
+| Blast radius / rename  | `gp_impact({ symbol, depth?, path? })`                  |
+| PR-scoped blast radius | `gp_impact({ symbol, since: 'main', path? })`           |
+| Index health probe     | `gp_stats({ path? })`                                   |
+| Refresh after edits    | `gp_index({ path? })`                                   |
+
+## When NOT to use GraphPilot
+
+Fall back to grep / read for:
+
+- Comments, JSDoc, string literals, error messages
+- Config files (package.json, tsconfig.json, .env)
+- Markdown / docs
+- Languages other than TypeScript / JavaScript
+- Git history (blame, log)
+
+## After heavy editing
+
+After ~10+ file edits, call `gp_index` once before further structural questions, or run `graphpilot watch` in a side terminal for sub-10 ms incremental updates.
+
+## Citing evidence
+
+Every GraphPilot response carries `file:line @ sha` anchors. When citing results to the user, **include the anchor verbatim** — it's verifiable: the user can jump to that line and the code will match.

package/examples/windsurf/README.md

@@ -0,0 +1,85 @@
+# Windsurf (Codeium) + GraphPilot
+
+Step-by-step install of GraphPilot as an MCP server inside Windsurf.
+
+## 1. Build GraphPilot
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot && pnpm install && pnpm build
+```
+
+## 2. Edit Windsurf's MCP config
+
+```
+~/.codeium/windsurf/mcp_config.json
+```
+
+Create it if it doesn't exist. Paste the contents of [`mcp_config.json`](./mcp_config.json) and replace `/absolute/path/to/graphpilot/` with the real path:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
+    },
+  },
+}
+```
+
+Post-npm:
+
+```jsonc
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "npx",
+      "args": ["graphpilot", "mcp"],
+    },
+  },
+}
+```
+
+## 3. Restart Windsurf
+
+Fully quit and reopen. The Cascade panel reads MCP config on launch.
+
+## 4. Verify
+
+Open the **Cascade** panel — the MCP tools list should include the four `gp_*` tools (`gp_index`, `gp_recall`, `gp_callers`, `gp_impact`).
+
+## 5. Index a repo
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js index .
+```
+
+## 6. Try it
+
+```text
+Use graphpilot to find who calls authenticate.
+
+What breaks if I rename parseFile? Use gp_impact.
+```
+
+## 7. Keep the index fresh
+
+```bash
+node /abs/path/to/graphpilot/dist/cli.js watch .
+```
+
+## Troubleshooting
+
+| Symptom                                     | Fix                                                                                                       |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| MCP tools list is empty                     | Verify JSON syntax with `python -m json.tool ~/.codeium/windsurf/mcp_config.json`. Then restart Windsurf. |
+| Server shows but tools fail with "no index" | Pass an explicit `path: "/abs/repo"` to the tool, or `gp_index` first.                                    |
+| Native module errors on launch              | `pnpm approve-builds --all && pnpm rebuild` in the graphpilot dir. Use Node 22 LTS if on 23+.             |
+
+## Files in this folder
+
+| File                                   | Purpose                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| [`README.md`](./README.md)             | This walkthrough                                                         |
+| [`mcp_config.json`](./mcp_config.json) | Sample `~/.codeium/windsurf/mcp_config.json` — copy the block into yours |

package/examples/windsurf/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"]
+    }
+  }
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Structural memory for coding agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -15,10 +15,18 @@
     "url": "https://github.com/graphpilot-oss/graphpilot/issues"
   },
   "type": "module",
-  "main": "./dist/index.js",
   "bin": {
     "graphpilot": "./dist/cli.js"
   },
+  "files": [
+    "dist/",
+    "assets/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
   "engines": {
     "node": ">=20"
   },
@@ -39,7 +47,8 @@
     "prettier": "^3.8.3",
     "tsx": "^4.19.2",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vite": "^6.4.3",
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "build": "tsc",
@@ -51,6 +60,7 @@
     "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,mjs,cjs,json,yml,yaml,md}\"",
     "typecheck": "tsc --noEmit",
     "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm test",
-    "bench": "tsx bench/run.ts"
+    "bench": "tsx bench/run.ts",
+    "bench:scale": "tsx bench/run-scale.ts"
   }
 }

package/.editorconfig

@@ -1,15 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[Makefile]
-indent_style = tab

package/.github/CODEOWNERS

@@ -1,22 +0,0 @@
-# CODEOWNERS — auto-request review on every PR.
-#
-# Syntax: <path-glob> <reviewer> [<reviewer>...]
-# Reviewers are GitHub handles (no @) or team slugs (@org/team).
-#
-# Order matters: the LAST matching rule wins. Default rule first, then
-# overrides for paths that should pull in specific reviewers.
-#
-# Docs: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-security/customizing-your-repository/about-code-owners
-
-# Default: solo maintainer reviews everything.
-*       @codeakki
-
-# When co-maintainers join, add area-specific rules. For example:
-#
-#   /src/mcp/         @codeakki @some-mcp-expert
-#   /src/parser/      @codeakki @some-tree-sitter-expert
-#   /docs/            @codeakki @docs-lead
-#   /bench/           @codeakki @benchmark-owner
-#   /.github/         @codeakki                    # workflow changes are sensitive
-#
-# Until then, the default rule is enough.

package/.github/FUNDING.yml

@@ -1 +0,0 @@
-github: [codeakki]

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,33 +0,0 @@
----
-name: Bug report
-about: Something is broken or behaving unexpectedly
-title: 'bug: '
-labels: bug
----
-
-## Describe the bug
-
-A clear description of what's wrong.
-
-## Reproduction
-
-Steps to reproduce:
-
-1. Run `...`
-2. ...
-3. ...
-
-## Expected behavior
-
-What you expected to happen instead.
-
-## Environment
-
-- OS: [macOS / Linux / Windows + version]
-- Node version: output of `node -v`
-- GraphPilot version: output of `node dist/cli.js --version` (or commit SHA)
-- MCP client (if relevant): [Claude Code / Cursor / Windsurf / ...]
-
-## Additional context
-
-Logs, screenshots, or a minimal repo that reproduces the issue.