@graphpilot-oss/graphpilot 0.0.1 → 0.1.0

package/docs/mcp-setup.md

@@ -1,231 +0,0 @@
-# MCP Setup per Client
-
-GraphPilot is an [MCP](https://modelcontextprotocol.io) server that
-speaks JSON-RPC over **stdio**. Any MCP-compatible client can use it.
-
-This doc covers the five most common clients. The pattern is the same
-everywhere: tell the client to launch `graphpilot mcp` (or
-`node /path/to/dist/cli.js mcp`) when it starts.
-
-## Two ways to invoke GraphPilot
-
-| Mode        | Command + args                                 | When to use                          |
-| ----------- | ---------------------------------------------- | ------------------------------------ |
-| Local build | `node /abs/path/to/graphpilot/dist/cli.js mcp` | Pre-v0.1.0, contributors, dev mode   |
-| `npx`       | `npx graphpilot mcp`                           | Once v0.1.0 ships to npm (preferred) |
-
-Examples below show both. Pick whichever matches your install.
-
----
-
-## Claude Code (Anthropic)
-
-**Config file:** `~/.claude.json` (macOS, Linux) or
-`%USERPROFILE%\.claude.json` (Windows).
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "node",
-      "args": ["/Users/you/code/graphpilot/dist/cli.js", "mcp"],
-    },
-  },
-}
-```
-
-Or post-v0.1.0:
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "npx",
-      "args": ["graphpilot", "mcp"],
-    },
-  },
-}
-```
-
-**Verify:** fully restart Claude Code (quit, don't just close the
-window). Type `/mcp` — you should see:
-
-```
-graphpilot
-  5 tools: gp_index, gp_recall, gp_callers, gp_impact, gp_stats
-```
-
-**Common gotcha:** `~/.claude.json` is read only on launch. Edits don't
-hot-reload — you must relaunch.
-
----
-
-## Cursor
-
-**Settings UI:** `Cmd/Ctrl + ,` → search "MCP" → "Edit MCP config".
-
-**File path:** `~/.cursor/mcp.json`.
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "node",
-      "args": ["/Users/you/code/graphpilot/dist/cli.js", "mcp"],
-    },
-  },
-}
-```
-
-**Verify:** Settings → MCP — `graphpilot` should show as **Connected**
-with 5 tools listed underneath.
-
-**Common gotcha:** Cursor sometimes caches MCP server state. If the
-server shows red after a config change, click the refresh icon next to
-it.
-
----
-
-## Cline (VS Code extension)
-
-Cline reads MCP config from a per-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`
-
-Easier: open the Cline panel in VS Code → "MCP Servers" → click the gear
-icon → "Edit MCP Settings". Then add:
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "node",
-      "args": ["/Users/you/code/graphpilot/dist/cli.js", "mcp"],
-      "disabled": false,
-      "autoApprove": [],
-    },
-  },
-}
-```
-
-**Verify:** the Cline panel's "MCP Servers" section lists `graphpilot`
-with a green status dot.
-
----
-
-## Windsurf (Codeium)
-
-**Config file:** `~/.codeium/windsurf/mcp_config.json`.
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "node",
-      "args": ["/Users/you/code/graphpilot/dist/cli.js", "mcp"],
-    },
-  },
-}
-```
-
-**Verify:** restart Windsurf → open the Cascade panel → MCP tools list
-should include the four `gp_*` tools.
-
----
-
-## Continue.dev
-
-Continue uses `~/.continue/config.json` (global) or
-`<repo>/.continue/config.json` (per-project).
-
-```jsonc
-{
-  "experimental": {
-    "modelContextProtocolServers": [
-      {
-        "transport": {
-          "type": "stdio",
-          "command": "node",
-          "args": ["/Users/you/code/graphpilot/dist/cli.js", "mcp"],
-        },
-      },
-    ],
-  },
-}
-```
-
-**Verify:** Continue → Settings → "MCP Servers" panel should list
-graphpilot.
-
-**Common gotcha:** Continue's MCP support is still flagged as
-experimental — versions vary. If `modelContextProtocolServers` is
-unrecognized, check the Continue version + their docs for the current
-config key.
-
----
-
-## Any other MCP-capable client
-
-Generic pattern works anywhere the client supports stdio MCP:
-
-- **Transport:** `stdio`
-- **Command:** `node` (or `npx`)
-- **Args:** `["/abs/path/to/graphpilot/dist/cli.js", "mcp"]`
-  (or `["graphpilot", "mcp"]` once on npm)
-- **Protocol version:** `2024-11-05` (matches
-  `@modelcontextprotocol/sdk@1.29.x`)
-
-### Use the MCP Inspector to verify the wire
-
-```bash
-npx @modelcontextprotocol/inspector node dist/cli.js mcp
-```
-
-Opens a browser-based UI listing the 5 tools with their schemas. Lets
-you fire a test call and see the JSON-RPC frames.
-
----
-
-## Environment variables
-
-| Variable              | Effect                                                                |
-| --------------------- | --------------------------------------------------------------------- |
-| `GRAPHPILOT_NO_LOG=1` | Disable the interaction log (`~/.graphpilot/<id>/interactions.jsonl`) |
-
-There are intentionally **no other env vars**. No API keys, no telemetry
-endpoints, no remote URLs. If a future feature needs one, it'll be
-opt-in and documented.
-
----
-
-## End-to-end smoke test
-
-```bash
-# In your project's terminal
-node /abs/path/to/graphpilot/dist/cli.js index .
-
-# Then in your agent:
-# "Use graphpilot's gp_stats tool to show the index for this repo."
-```
-
-If the response includes repo id, file/symbol/edge counts, and an
-`indexedAt` timestamp — the wire is healthy.
-
----
-
-## Troubleshooting
-
-| Symptom                                            | Likely cause                                                                     | Fix                                                                                           |
-| -------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Server connects then immediately disconnects       | Server crashing on startup, or you're on a build older than the Day-10 stdio fix | Run `node dist/cli.js mcp` in a terminal — inspect stderr for the error. Rebuild from `main`. |
-| Client shows no servers                            | Config file has a JSON syntax error                                              | Validate JSON; clients often silently ignore broken configs                                   |
-| Tools list but every call returns "No index found" | Path mismatch — Claude's `cwd` ≠ the path you indexed                            | Pass an explicit `path: "/abs/path"` argument to each tool call                               |
-| Some `gp_*` tools missing from the catalog         | Stale build cached by the client                                                 | `pnpm build` then fully restart the client                                                    |
-| stderr says "Failed to load native bindings"       | `tree-sitter` native module didn't compile                                       | `pnpm approve-builds --all && pnpm rebuild`. If on Node 23+, drop to Node 22 LTS.             |
-| Tool returns "Invalid input: Unknown field(s)"     | Caller passed an unrecognized argument                                           | Schemas are strict — only the documented fields are allowed                                   |
-
-Anything not in this table → please file an
-[issue](https://github.com/graphpilot-oss/graphpilot/issues) with the agent's
-stderr + the failing JSON-RPC payload.

package/docs/quickstart.md

@@ -1,202 +0,0 @@
-# Quickstart
-
-Five-minute path from a fresh clone to Claude Code answering structural
-questions about your codebase using GraphPilot.
-
-## Prerequisites
-
-- Node.js **≥ 20** — check with `node --version`
-- **pnpm 9+** (or use `npm` if you prefer — examples below default to pnpm)
-- An MCP-compatible coding agent: Claude Code, Cursor, Cline, Windsurf,
-  or Continue.dev
-
-## 1. Install
-
-Until v0.1.0 is published to npm, build from source:
-
-```bash
-git clone https://github.com/graphpilot-oss/graphpilot.git
-cd graphpilot
-pnpm install
-pnpm build
-```
-
-The compiled CLI lives at `dist/cli.js`. Verify:
-
-```bash
-node dist/cli.js help
-```
-
-Once v0.1.0 publishes:
-
-```bash
-npx graphpilot --help    # zero-install
-# or
-npm install -g @graphpilot-oss/graphpilot
-```
-
-## 2. Index your first repo
-
-Pick a TypeScript or JavaScript project — preferably a real one with
-several hundred files so you can feel the value.
-
-```bash
-node dist/cli.js index /path/to/your/repo
-```
-
-Expected output:
-
-```
-Indexing /path/to/your/repo ...
-
-✓ Remembered 412 symbols, 1138 calls (387 resolved) across 87 files in 320ms.
-  Repo id:    a1b2c3d4e5f6abcd
-  Graph file: /Users/you/.graphpilot/a1b2c3d4e5f6abcd/graph.json
-```
-
-What just happened:
-
-- Every `.ts/.tsx/.js/.jsx/.mjs/.cjs` file got parsed by tree-sitter
-- Functions, classes, methods, interfaces, types, enums were extracted
-- Every call site inside every function body was captured
-- The resolver matched in-repo callees back to their definitions
-- Result saved to `~/.graphpilot/<repo-id>/graph.json` (mode 0600)
-
-## 3. Sanity-check the index
-
-```bash
-# Re-read what was saved
-node dist/cli.js status /path/to/your/repo
-```
-
-Or peek at the raw JSON:
-
-```bash
-jq '{filesIndexed, symbolCount, edgeCount, indexedAt}' \
-  ~/.graphpilot/<repo-id>/graph.json
-```
-
-## 4. Wire to Claude Code
-
-Edit `~/.claude.json` (create the file if it doesn't exist):
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "node",
-      "args": ["/absolute/path/to/graphpilot/dist/cli.js", "mcp"],
-    },
-  },
-}
-```
-
-Once v0.1.0 ships to npm, you can simplify to:
-
-```jsonc
-{
-  "mcpServers": {
-    "graphpilot": {
-      "command": "npx",
-      "args": ["graphpilot", "mcp"],
-    },
-  },
-}
-```
-
-**Restart Claude Code fully** (quit, don't just close the window). Then
-type `/mcp` — `graphpilot` should appear with **5 tools** (gp_index,
-gp_recall, gp_callers, gp_impact, gp_stats).
-
-For Cursor / Cline / Windsurf / Continue, see
-[mcp-setup.md](mcp-setup.md).
-
-## 5. Ask Claude a structural question
-
-In a project where you've already run `gp_index`, try these in Claude
-Code. Pick real symbol names from your indexed repo:
-
-```text
-"Use graphpilot to find where parseToken is defined."
-
-"Who calls authenticate in this repo? Use graphpilot."
-
-"What does indexDirectory call? Use graphpilot's callees."
-
-"Re-index this repo with graphpilot."
-
-"Use graphpilot to show the current index stats."
-```
-
-Watch the response for a `Calling graphpilot/gp_*` line — that's the
-tool firing. If you see it, you're done.
-
-## 6. Keep the index fresh while you edit (optional)
-
-By default the index is a snapshot — it grows stale as you edit. Either
-re-run `graphpilot index .` after big changes, or just leave watch mode
-running in a side terminal:
-
-```bash
-node dist/cli.js watch /path/to/your/repo
-# [graphpilot:watch] Watching ... (412 symbols, 1138 calls, 87 files).
-# [graphpilot:watch] src/auth.ts: 32 (+1) symbols, 89 (+3) calls (4ms).
-# [graphpilot:watch] src/auth.ts deleted: 30 (-2) symbols, 84 (-5) calls (3ms).
-# Ctrl+C to stop.
-```
-
-Each save triggers a sub-10ms incremental update. The on-disk
-`graph.json` is rewritten atomically — Claude always sees a consistent
-view, even mid-edit.
-
-## 7. Make Claude reach for GraphPilot automatically
-
-You shouldn't have to type "use graphpilot to..." every time. Add a
-`CLAUDE.md` to the root of the indexed repo:
-
-```markdown
-When asked 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"
-- "find function X" / "where is X defined"
-
-→ Use graphpilot MCP tools (`gp_recall`, `gp_callers`) BEFORE grep or
-reading files. Graphpilot is a pre-built code-graph for this repo.
-
-Fall back to grep/read for: comments, string literals, config files,
-languages other than TS/JS, git history.
-
-After 10+ file edits, call `gp_index` once before further structural
-questions.
-```
-
-Restart Claude Code one more time. From here, structural questions route
-to GraphPilot automatically.
-
-When `gp_impact` is part of the routing, add this line so it's used too:
-
-```
-- "rename X — what breaks" / "impact of changing X" / "what depends on X"
-  → use gp_impact (returns direct + transitive callers + tests + public-API flag)
-```
-
-## What to do next
-
-- [mcp-setup.md](mcp-setup.md) — per-client configuration
-- [architecture.md](architecture.md) — how the pipeline works
-- [limitations.md](limitations.md) — what GraphPilot deliberately doesn't do
-
-## Troubleshooting
-
-| Symptom                                               | Fix                                                                                 |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `/mcp` doesn't list graphpilot                        | Run `pnpm build` again, then **fully** quit and reopen Claude Code                  |
-| Every tool call returns "No GraphPilot index found"   | Run `node dist/cli.js index /path` first, and pass an absolute `path` to tool calls |
-| Tool errors with "Invalid input: Unknown field(s)..." | Schemas are strict — remove extra fields from the tool call                         |
-| `pnpm install` fails on native modules                | `pnpm approve-builds --all && pnpm rebuild`                                         |
-| Server starts but never responds                      | You're on a build older than the Day-10 stdio fix; rebuild from `main`              |
-| The server keeps showing the same stale data          | Call `gp_index` from the agent (or re-run `node dist/cli.js index .`)               |
-
-Issues not in this table → [open an issue](https://github.com/graphpilot-oss/graphpilot/issues).

package/eslint.config.js

@@ -1,148 +0,0 @@
-// ESLint flat config (ESLint v9+).
-//
-// Primary purpose: enforce the "local-first, no network" promise at the
-// build gate. Until this rule was added the promise was a convention,
-// not an enforced contract — see SECURITY.md for the user-facing
-// guarantee this protects.
-//
-// Secondary purpose: catch the small set of rules where tsc isn't enough
-// (no unused variables, no console.log left in production code).
-
-import tseslint from '@typescript-eslint/eslint-plugin';
-import tsparser from '@typescript-eslint/parser';
-
-const NETWORK_MSG =
-  'No network code in src/. GraphPilot is local-first; runtime must not ' +
-  'open sockets. If you genuinely need an outbound call, it belongs in ' +
-  'a separate opt-in path — open an issue first.';
-
-const SHELL_MSG =
-  'No child_process in src/. Shelling out from runtime code creates ' +
-  'injection surface against user-supplied symbol names / paths. Tests ' +
-  'and scripts (subprocess MCP test, bench harness) are exempt — those ' +
-  'live under tests/ and scripts/.';
-
-/**
- * Modules banned from `src/`. The product promise is that nothing leaves
- * the user's machine — that's only true if there's no networking code
- * anywhere in the runtime path.
- */
-const BANNED_NETWORK_IMPORTS = [
-  { name: 'http', message: NETWORK_MSG },
-  { name: 'https', message: NETWORK_MSG },
-  { name: 'node:http', message: NETWORK_MSG },
-  { name: 'node:https', message: NETWORK_MSG },
-  { name: 'undici', message: NETWORK_MSG },
-  { name: 'axios', message: NETWORK_MSG },
-  { name: 'node-fetch', message: NETWORK_MSG },
-  { name: 'cross-fetch', message: NETWORK_MSG },
-  { name: 'got', message: NETWORK_MSG },
-  { name: 'request', message: NETWORK_MSG },
-  { name: 'superagent', message: NETWORK_MSG },
-];
-
-/**
- * Modules where shelling out to a child process would create injection
- * surface; enforced at the build gate.
- */
-const BANNED_SHELL_IMPORTS = [
-  { name: 'child_process', message: SHELL_MSG },
-  { name: 'node:child_process', message: SHELL_MSG },
-];
-
-export default [
-  // ---------------------------------------------------------------------
-  // src/ — production code
-  // ---------------------------------------------------------------------
-  {
-    files: ['src/**/*.ts'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        sourceType: 'module',
-        ecmaVersion: 2022,
-      },
-      globals: {
-        process: 'readonly',
-        console: 'readonly',
-        Buffer: 'readonly',
-        setTimeout: 'readonly',
-        clearTimeout: 'readonly',
-        setInterval: 'readonly',
-        clearInterval: 'readonly',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
-    rules: {
-      'no-restricted-imports': [
-        'error',
-        {
-          paths: [...BANNED_NETWORK_IMPORTS, ...BANNED_SHELL_IMPORTS],
-        },
-      ],
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
-      ],
-      'no-console': ['warn', { allow: ['error', 'warn'] }],
-    },
-  },
-
-  // ---------------------------------------------------------------------
-  // tests/ and scripts/ — looser rules
-  // ---------------------------------------------------------------------
-  {
-    files: ['tests/**/*.ts', 'scripts/**/*.{ts,mjs}'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        sourceType: 'module',
-        ecmaVersion: 2022,
-      },
-      globals: {
-        process: 'readonly',
-        console: 'readonly',
-        Buffer: 'readonly',
-        setTimeout: 'readonly',
-        clearTimeout: 'readonly',
-        setInterval: 'readonly',
-        clearInterval: 'readonly',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
-    rules: {
-      // Tests + scripts ARE allowed to use child_process (subprocess test,
-      // smoke runner, future bench harness).
-      'no-console': 'off',
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
-      ],
-    },
-  },
-
-  // ---------------------------------------------------------------------
-  // tests/fixtures — these files deliberately contain "unused" symbols
-  // because they exist for parser tests to detect. This block must come
-  // AFTER the broader tests/ block so its override wins (ESLint flat
-  // configs cascade — later matches override earlier ones).
-  // ---------------------------------------------------------------------
-  {
-    files: ['tests/fixtures/**/*.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-      'no-unused-vars': 'off',
-    },
-  },
-
-  // ---------------------------------------------------------------------
-  // Things to ignore
-  // ---------------------------------------------------------------------
-  {
-    ignores: ['dist/**', 'node_modules/**', 'coverage/**', '.notes/**', 'pnpm-lock.yaml'],
-  },
-];

package/lefthook.yml

@@ -1,81 +0,0 @@
-# lefthook — git hooks for GraphPilot
-#
-# Why:
-#   - Catch lint / type errors BEFORE they land in main.
-#   - Enforce Conventional Commits so the changelog stays clean and
-#     release automation can parse history (when we add release-please
-#     later).
-#   - Cheap to bypass intentionally (LEFTHOOK=0 git commit) but the
-#     default makes the right thing the easy thing.
-#
-# Install path:
-#   `pnpm install` runs lefthook's postinstall hook which wires this
-#   file into .git/hooks/. No manual `lefthook install` step required.
-#
-# Bypass:
-#   LEFTHOOK=0 git commit              # skip all hooks
-#   LEFTHOOK_EXCLUDE=lint git commit   # skip the lint job only
-
-pre-commit:
-  parallel: true
-  jobs:
-    - name: typecheck
-      run: pnpm typecheck
-      glob:
-        - 'src/**/*.ts'
-        - 'tests/**/*.ts'
-        - 'bench/**/*.ts'
-
-    - name: lint
-      # Only lint files actually staged — fast, accurate.
-      run: pnpm exec eslint {staged_files}
-      glob:
-        - 'src/**/*.ts'
-        - 'tests/**/*.ts'
-        - 'scripts/**/*.{ts,mjs}'
-
-    - name: format
-      # Format-check staged files. If drift, the dev runs `pnpm format`
-      # to fix and re-stages. No auto-write here — explicit is safer
-      # (auto-write on commit can clobber a stash or rebase mid-edit).
-      run: pnpm exec prettier --check {staged_files}
-      glob:
-        - '**/*.{ts,tsx,js,jsx,mjs,cjs,json,yml,yaml,md}'
-
-commit-msg:
-  jobs:
-    - name: conventional-commits
-      # Conventional Commits regex. Allows:
-      #   feat: ...      feat(scope): ...
-      #   fix: ...       fix(scope)!: ...      (! marks breaking change)
-      #   chore: ...     docs: ...     refactor: ...     test: ...
-      #   perf: ...      build: ...    ci: ...           revert: ...
-      # Plus the standard merge-commit / fixup / WIP forms.
-      run: |
-        first=$(head -1 "{1}")
-        if echo "$first" | grep -qE '^(Merge |Revert |fixup!|squash!|amend!)'; then
-          exit 0
-        fi
-        if echo "$first" | grep -qE '^(feat|fix|chore|docs|test|refactor|perf|build|ci|revert)(\([^)]+\))?!?: .+'; then
-          exit 0
-        fi
-        echo ""
-        echo "❌ Commit message does not follow Conventional Commits."
-        echo ""
-        echo "   Got: $first"
-        echo ""
-        echo "   Format: <type>(<scope>)?: <subject>"
-        echo "   Types : feat, fix, chore, docs, test, refactor, perf, build, ci, revert"
-        echo ""
-        echo "   Examples:"
-        echo "     feat(mcp): add gp_impact tool"
-        echo "     fix: handle empty TS files gracefully"
-        echo "     docs(quickstart): clarify Claude Code setup"
-        echo ""
-        echo "   To bypass once:  LEFTHOOK=0 git commit ..."
-        exit 1
-
-pre-push:
-  jobs:
-    - name: test
-      run: pnpm test

package/pnpm-workspace.yaml

@@ -1,6 +0,0 @@
-allowBuilds:
-  esbuild: true
-  lefthook: true
-  tree-sitter: true
-  tree-sitter-javascript: true
-  tree-sitter-typescript: true