@graphpilot-oss/graphpilot 0.0.1 → 0.1.0

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 five `gp_*` tools (`gp_index`, `gp_recall`, `gp_callers`, `gp_impact`, `gp_stats`).
+
+## 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": "0.1.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"
   },
@@ -51,6 +59,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.

package/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: Discussion / Question
-    url: https://github.com/graphpilot-oss/graphpilot/discussions
-    about: Ask questions or share ideas in Discussions instead of opening an issue.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,23 +0,0 @@
----
-name: Feature request
-about: Suggest a new feature or improvement
-title: 'feat: '
-labels: enhancement
----
-
-## What problem does this solve?
-
-Describe the real-world task or pain point that motivates this feature.
-"My coding agent struggles with X" is more useful than "GraphPilot should support X."
-
-## Proposed solution
-
-What you'd like to see. Rough sketch is fine.
-
-## Alternatives considered
-
-What workarounds have you tried? Any other tools that solve this well?
-
-## Additional context
-
-Links, screenshots, examples.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +0,0 @@
-## What
-
-Brief description of the change.
-
-## Why
-
-What problem does this solve? Link to issue: closes #...
-
-## How
-
-Brief explanation of the approach. Anything reviewers should look at carefully?
-
-## Checklist
-
-- [ ] Tests added/updated
-- [ ] Documentation updated if user-facing behavior changed
-- [ ] `CHANGELOG.md` updated under `[Unreleased]`
-- [ ] CI passes (`pnpm build && pnpm test`)
-- [ ] Commit message follows [Conventional Commits](https://www.conventionalcommits.org)

package/.github/dependabot.yml

@@ -1,15 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: '/'
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-    groups:
-      dev-dependencies:
-        dependency-type: development
-
-  - package-ecosystem: github-actions
-    directory: '/'
-    schedule:
-      interval: monthly

package/.github/workflows/ci.yml

@@ -1,62 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  lint:
-    name: lint (ESLint — enforces no-network in src/, T12)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: pnpm/action-setup@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm typecheck
-      - run: pnpm lint
-
-  test:
-    name: test (${{ matrix.os }}, node ${{ matrix.node }})
-    needs: lint
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        node: [20, 22]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: pnpm/action-setup@v6
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node }}
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm build
-
-      - name: Test
-        run: pnpm test
-
-  audit:
-    name: audit
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: pnpm/action-setup@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm audit --audit-level=high

package/.github/workflows/release.yml

@@ -1,50 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  contents: write
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: pnpm/action-setup@v6
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: pnpm
-          registry-url: 'https://registry.npmjs.org'
-
-      - run: pnpm install --frozen-lockfile
-
-      - run: pnpm run check
-
-      - run: pnpm build
-
-      # Test tags (e.g. v0.0.1-test) publish under --tag test, not latest
-      - name: Publish (test tag)
-        if: contains(github.ref_name, '-test')
-        run: pnpm publish --no-git-checks --tag test
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      # Real releases publish normally with provenance
-      - name: Publish (release)
-        if: "!contains(github.ref_name, '-test')"
-        run: pnpm publish --no-git-checks --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      # Only create a GitHub Release for real tags, not test ones
-      - uses: softprops/action-gh-release@v3
-        if: "!contains(github.ref_name, '-test')"
-        with:
-          generate_release_notes: true

package/.prettierignore

@@ -1,19 +0,0 @@
-# Don't reformat:
-node_modules/
-dist/
-coverage/
-
-# Lockfiles + generated data are not human-edited.
-pnpm-lock.yaml
-package-lock.json
-yarn.lock
-
-# Benchmark output is generated by `pnpm bench` — prettier would
-# pointlessly reformat the JSON every run.
-bench/results/
-
-# Private notes are not part of the project, don't touch.
-.notes/
-
-# CLAUDE.md is per-developer + gitignored, leave alone.
-CLAUDE.md

package/.prettierrc.json

@@ -1,20 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "arrowParens": "always",
-  "endOfLine": "lf",
-  "bracketSpacing": true,
-  "overrides": [
-    {
-      "files": "*.md",
-      "options": {
-        "proseWrap": "preserve",
-        "printWidth": 80
-      }
-    }
-  ]
-}