@flyingrobots/graft 0.4.0 → 0.6.0

package/src/warp/open.ts

@@ -2,29 +2,92 @@
  * WARP graph initialization — opens the graft-ast graph backed by
  * the repo's own .git directory.
  *
- * Single entry point. Returns a WarpApp instance ready for patch
+ * Single entry point. Returns a WARP port handle ready for patch
  * writes and observer reads.
  */
 
-import WarpApp, { GitGraphAdapter } from "@git-stunts/git-warp";
+import RawWarpApp, { GitGraphAdapter } from "@git-stunts/git-warp";
 import GitPlumbing from "@git-stunts/plumbing";
+import type {
+  WarpHandle,
+  WarpMaterializeReceipt,
+  WarpObserver,
+  WarpObserverLens,
+  WarpObserverOptions,
+  WarpPatchBuilder,
+} from "../ports/warp.js";
+import { DEFAULT_WARP_WRITER_ID } from "./writer-id.js";
 
-const GRAPH_NAME = "graft-ast";
-const WRITER_ID = "graft";
+export const GRAPH_NAME = "graft-ast";
 
 export interface OpenWarpOptions {
   readonly cwd: string;
+  readonly writerId?: string;
 }
 
-export async function openWarp(options: OpenWarpOptions): Promise<WarpApp> {
+function toRawLens(lens: WarpObserverLens): {
+  match: string | string[];
+  expose?: string[];
+  redact?: string[];
+} {
+  return {
+    match: typeof lens.match === "string" ? lens.match : [...lens.match],
+    ...(lens.expose !== undefined ? { expose: [...lens.expose] } : {}),
+    ...(lens.redact !== undefined ? { redact: [...lens.redact] } : {}),
+  };
+}
+
+function toRawObserverOptions(options: WarpObserverOptions | undefined): {
+  source?: { kind: "live"; ceiling: number | null };
+} | undefined {
+  if (options === undefined) {
+    return undefined;
+  }
+  if (options.source === undefined) {
+    return {};
+  }
+  return {
+    source: {
+      kind: options.source.kind,
+      ceiling: options.source.ceiling,
+    },
+  };
+}
+
+function wrapWarpApp(app: RawWarpApp): WarpHandle {
+  return {
+    async hasNode(nodeId: string): Promise<boolean> {
+      const observer = await app.observer({ match: nodeId });
+      const nodes = await observer.getNodes();
+      return nodes.includes(nodeId);
+    },
+    observer(lens, options): Promise<WarpObserver> {
+      return app.observer(toRawLens(lens), toRawObserverOptions(options)) as Promise<WarpObserver>;
+    },
+    patch(build): Promise<string> {
+      return app.patch((patch) => build(patch as unknown as WarpPatchBuilder));
+    },
+    async materialize(): Promise<void> {
+      await app.core().materialize();
+    },
+    async materializeReceipts(): Promise<readonly WarpMaterializeReceipt[]> {
+      const { receipts } = await app.core().materialize({ receipts: true });
+      return receipts as readonly WarpMaterializeReceipt[];
+    },
+  };
+}
+
+export async function openWarp(options: OpenWarpOptions): Promise<WarpHandle> {
   // createDefault() wires the ShellRunnerFactory (required port)
   const plumbing = GitPlumbing.createDefault({ cwd: options.cwd });
   const persistence = new GitGraphAdapter({ plumbing });
 
-  return WarpApp.open({
+  const app = await RawWarpApp.open({
     persistence,
     graphName: GRAPH_NAME,
-    writerId: WRITER_ID,
+    writerId: options.writerId ?? DEFAULT_WARP_WRITER_ID,
     onDeleteWithData: "cascade",
   });
+
+  return wrapWarpApp(app);
 }

package/src/warp/plumbing.d.ts

@@ -6,6 +6,10 @@ declare module "@git-stunts/plumbing" {
     constructor(options: { runner: unknown; cwd?: string });
     static createDefault(options?: { cwd?: string; env?: string }): GitPlumbing;
     execute(options: { args: string[]; input?: string | Uint8Array }): Promise<string>;
-    executeStream(options: { args: string[] }): Promise<AsyncIterable<Uint8Array> & { collect(opts?: { asString?: boolean }): Promise<Uint8Array | string> }>;
+    executeStream(options: { args: string[] }): Promise<{
+      finished: Promise<{ code: number; stderr: string; error?: Error }>;
+      collect(opts?: { maxBytes?: number; asString?: boolean; encoding?: string }): Promise<Uint8Array | string>;
+      [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    }>;
   }
 }

package/src/warp/symbol-identity.ts

@@ -0,0 +1,100 @@
+import crypto from "node:crypto";
+import { diffOutlines } from "../parser/diff.js";
+import type { OutlineEntry } from "../parser/types.js";
+
+export type SymbolIdentityMap = ReadonlyMap<string, string>;
+
+export function buildSymbolPath(parentPath: string, name: string): string {
+  return parentPath.length > 0 ? `${parentPath}.${name}` : name;
+}
+
+function mintCanonicalSymbolIdentity(
+  commitSha: string,
+  filePath: string,
+  symbolPath: string,
+  entry: OutlineEntry,
+): string {
+  const seed = [
+    commitSha,
+    filePath,
+    symbolPath,
+    entry.kind,
+    entry.signature ?? "",
+    String(entry.exported),
+  ].join("\n");
+  return `sid:${crypto.createHash("sha256").update(seed).digest("hex").slice(0, 16)}`;
+}
+
+export function assignCanonicalSymbolIdentities(input: {
+  oldEntries: readonly OutlineEntry[];
+  newEntries: readonly OutlineEntry[];
+  oldIdentityByPath: SymbolIdentityMap;
+  commitSha: string;
+  filePath: string;
+}): Map<string, string> {
+  const assigned = new Map<string, string>();
+
+  assignLevel({
+    oldEntries: input.oldEntries,
+    newEntries: input.newEntries,
+    oldIdentityByPath: input.oldIdentityByPath,
+    commitSha: input.commitSha,
+    filePath: input.filePath,
+    oldParentPath: "",
+    newParentPath: "",
+    assigned,
+  });
+
+  return assigned;
+}
+
+function assignLevel(input: {
+  oldEntries: readonly OutlineEntry[];
+  newEntries: readonly OutlineEntry[];
+  oldIdentityByPath: SymbolIdentityMap;
+  commitSha: string;
+  filePath: string;
+  oldParentPath: string;
+  newParentPath: string;
+  assigned: Map<string, string>;
+}): void {
+  const oldByName = new Map<string, OutlineEntry>();
+  for (const entry of input.oldEntries) {
+    oldByName.set(entry.name, entry);
+  }
+
+  const continuityByNewName = new Map<string, string>();
+  const diff = diffOutlines(input.oldEntries, input.newEntries);
+  for (const continuity of diff.continuity) {
+    continuityByNewName.set(continuity.newName, continuity.oldName);
+  }
+
+  for (const newEntry of input.newEntries) {
+    const newSymbolPath = buildSymbolPath(input.newParentPath, newEntry.name);
+    const oldName = oldByName.has(newEntry.name)
+      ? newEntry.name
+      : continuityByNewName.get(newEntry.name);
+    const oldEntry = oldName !== undefined ? oldByName.get(oldName) : undefined;
+    const oldSymbolPath = oldName !== undefined
+      ? buildSymbolPath(input.oldParentPath, oldName)
+      : null;
+
+    const identityId = oldSymbolPath !== null
+      ? input.oldIdentityByPath.get(oldSymbolPath) ??
+        mintCanonicalSymbolIdentity(input.commitSha, input.filePath, newSymbolPath, newEntry)
+      : mintCanonicalSymbolIdentity(input.commitSha, input.filePath, newSymbolPath, newEntry);
+
+    input.assigned.set(newSymbolPath, identityId);
+
+    assignLevel({
+      oldEntries: oldEntry?.children ?? [],
+      newEntries: newEntry.children ?? [],
+      oldIdentityByPath: input.oldIdentityByPath,
+      commitSha: input.commitSha,
+      filePath: input.filePath,
+      oldParentPath: oldSymbolPath ?? "",
+      newParentPath: newSymbolPath,
+      assigned: input.assigned,
+    });
+  }
+}

package/src/warp/writer-id.ts

@@ -0,0 +1,30 @@
+import * as crypto from "node:crypto";
+
+export const DEFAULT_WARP_WRITER_ID = "graft";
+
+function sanitizeSegment(input: string): string {
+  const normalized = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return normalized.length > 0 ? normalized : "lane";
+}
+
+export function buildWarpWriterId(kind: string, scope?: string): string {
+  const lane = sanitizeSegment(kind);
+  if (scope === undefined || scope.trim().length === 0) {
+    return `graft_${lane}`;
+  }
+
+  const digest = crypto.createHash("sha256").update(scope).digest("hex").slice(0, 12);
+  return `graft_${lane}_${digest}`;
+}
+
+export function buildSessionWarpWriterId(sessionId: string): string {
+  return buildWarpWriterId("session", sessionId);
+}
+
+export function buildMonitorWarpWriterId(repoId: string): string {
+  return buildWarpWriterId("monitor", repoId);
+}

package/docs/GUIDE.md

@@ -1,388 +0,0 @@
-# Graft Setup Guide
-
-## Install
-
-```bash
-npm install -g @flyingrobots/graft
-```
-
-Or run without installing:
-
-```bash
-npx @flyingrobots/graft
-```
-
-## Quick setup
-
-```bash
-npx @flyingrobots/graft init
-```
-
-Scaffolds your project for graft in one command:
-- Creates `.graftignore` (template with examples)
-- Adds `.graft/` to `.gitignore`
-- Generates a `CLAUDE.md` snippet instructing agents to prefer graft tools
-- Prints Claude Code hook config for manual setup
-
-Idempotent — safe to run again without duplicating entries.
-
-## MCP Configuration
-
-Graft runs as an MCP server over stdio. Add it to your editor or
-agent's MCP configuration.
-
-### Claude Code
-
-Add to `.mcp.json` in your project root (per-project) or
-`~/.claude.json` (global):
-
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to Cursor's MCP settings (Settings → MCP Servers → Add):
-
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  }
-}
-```
-
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  }
-}
-```
-
-### VS Code + Continue
-
-Add to `.continue/config.json`:
-
-```json
-{
-  "mcpServers": [
-    {
-      "name": "graft",
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  ]
-}
-```
-
-### Cline
-
-Add via Cline's MCP settings UI, or in
-`.vscode/cline_mcp_settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  }
-}
-```
-
-### Any MCP-compatible client
-
-The pattern is the same everywhere:
-
-- **Command**: `npx`
-- **Args**: `["-y", "@flyingrobots/graft"]`
-- **Transport**: stdio (the default for most clients)
-
-If your client doesn't support `npx`, install globally and use:
-
-- **Command**: `graft`
-- **Args**: (none)
-
-## Claude Code Hooks
-
-Two hooks work together to govern agent reads:
-
-- **PreToolUse** — blocks banned files before the read happens
-- **PostToolUse** — educates the agent on context cost after large
-  file reads complete
-
-### Setup
-
-Add to `.claude/settings.json` in your project root:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-If developing graft itself, replace the `node_modules/...` paths
-with local paths:
-
-```
-src/hooks/pretooluse-read.ts    (PreToolUse)
-src/hooks/posttooluse-read.ts   (PostToolUse)
-```
-
-### PreToolUse — ban enforcement
-
-When the agent calls `Read(file_path)`, the PreToolUse hook:
-
-1. Evaluates the file against graft's policy
-2. **Banned files** (binaries, lockfiles, secrets, `.graftignore`
-   matches): exits 2 (block) with refusal reason and next steps
-3. **Everything else**: exits 0 — lets native Read proceed
-
-The PreToolUse hook does NOT block large files. It only enforces
-hard bans. Large file governance is handled by the PostToolUse hook.
-
-### PostToolUse — context cost education
-
-After a Read completes, the PostToolUse hook evaluates what
-`safe_read` would have done and tells the agent the cost:
-
-```
-[graft] You just read 450 lines (18KB) into context.
-safe_read would have returned a structural outline (2048 bytes),
-saving 16.0KB of context. Threshold: 150 lines / 12KB.
-```
-
-This feedback appears for large JS/TS files where an outline was
-available. Small files, non-JS/TS files, and nonexistent files
-produce no feedback. The hook always exits 0 — it never blocks.
-
-### Limitations
-
-Both hooks run as standalone processes — they do not share state
-with the MCP server. This means:
-
-- No session-depth dynamic caps (early/mid/late)
-- No re-read suppression or cache hits
-- No structural diffs on changed files
-- No metrics tracking or receipts
-
-For the full experience, agents should use graft's MCP tools
-(`safe_read`, `file_outline`, `read_range`) directly. The hooks
-are a safety net; the MCP server is the full governor.
-
-### Disabling
-
-To disable hooks locally without removing the project config,
-add to `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {}
-}
-```
-
-## Tool Reference
-
-| Tool | Description |
-|------|-------------|
-| `safe_read` | Policy-enforced file read. Returns full content for small files, structural outline with jump table for large files, or refusal with reason code for banned files. Detects re-reads and returns cached outlines or structural diffs. |
-| `file_outline` | Structural skeleton of a file — function signatures, class shapes, exports. Includes a jump table mapping each symbol to its line range for targeted `read_range` follow-ups. |
-| `read_range` | Read a bounded range of lines from a file. Maximum 250 lines. Use jump table entries from `file_outline` or `safe_read` to target specific symbols. |
-| `changed_since` | Check if a file changed since it was last read. Returns structural diff (added/removed/changed symbols) or "unchanged". Peek mode by default; pass `consume: true` to update the observation cache. |
-| `graft_diff` | Structural diff between two git refs. Shows added, removed, and changed symbols per file — not line hunks. Defaults to working tree vs HEAD. |
-| `run_capture` | Execute a shell command and return the last N lines of output (default 60). Full output saved to `.graft/logs/capture.log` for follow-up `read_range` calls. |
-| `state_save` | Save session working state (max 8 KB). Use for session bookmarks: current task, files modified, next planned actions. |
-| `state_load` | Load previously saved session state. Returns null if no state has been saved. |
-| `doctor` | Runtime health check. Shows project root, parser status, active thresholds, session depth, and message count. |
-| `set_budget` | Declare a session byte budget. Graft tightens read thresholds as the budget drains — no single read may consume more than 5% of remaining budget. Call once at session start. |
-| `explain` | Explain a graft reason code. Returns human-readable meaning and recommended next action for any code (e.g., `BINARY`, `BUDGET_CAP`). Case-insensitive. |
-| `stats` | Decision metrics for the current session. Total reads, outlines, refusals, cache hits, and bytes avoided. |
-
-## What the agent sees
-
-Once configured, the agent gains 12 new tools. Here's what
-happens when it uses them:
-
-### Reading files
-
-The agent calls `safe_read` instead of reading files directly.
-Graft decides what to return:
-
-- **Small files** (< 150 lines, < 12 KB): full content, as normal.
-- **Large files**: a structural outline showing function signatures,
-  class shapes, and exports — with a jump table mapping each symbol
-  to its line range. The agent can then use `read_range` to read
-  specific sections.
-- **Banned files** (binaries, lockfiles, `.env`, minified bundles,
-  build output): refused with a reason code and suggested
-  alternatives.
-- **Re-reads**: if the agent reads the same unchanged file twice,
-  graft returns the cached outline instead of the full content.
-  If the file changed, it returns a structural diff (added/removed/
-  changed symbols).
-
-### Structural navigation
-
-`file_outline` returns the structural skeleton of any file —
-function signatures, class members, exports — without the bodies.
-Each symbol has a line range so the agent can follow up with
-`read_range` for the specific code it needs.
-
-### Git diffs
-
-`graft_diff` shows what changed between git refs at the symbol
-level: "function `foo` gained a parameter" instead of line hunks.
-
-### Budget governor
-
-If the agent calls `set_budget(bytes)` at session start, graft
-tracks cumulative bytes consumed and tightens thresholds as the
-budget drains. No single read may consume more than 5% of remaining
-budget. When the budget is exhausted, all reads return outlines.
-
-Budget status appears in every receipt:
-```json
-"budget": { "total": 500000, "consumed": 14345, "remaining": 485655, "fraction": 0.029 }
-```
-
-### Session awareness
-
-Graft tracks the session and tightens policy as context pressure
-grows:
-
-| Session stage | Max read size |
-|---------------|---------------|
-| Early (< 100 messages) | 20 KB |
-| Mid (100–500 messages) | 10 KB |
-| Late (> 500 messages) | 4 KB |
-
-Tripwires warn when sessions are going off the rails (> 500
-messages, edit-bash loops, runaway tool calls).
-
-### Receipts
-
-Every response includes a `_receipt` block with session ID,
-sequence number, projection type, bytes returned, and cumulative
-counters. This is for usage analysis — you can ignore it.
-
-## Configuration
-
-### .graftignore
-
-Create a `.graftignore` file in your project root to ban
-additional file patterns:
-
-```text
-# Generated files
-*.generated.ts
-*.snap
-
-# Vendor code
-vendor/**
-
-# Large data files
-data/**/*.json
-```
-
-Patterns follow the same syntax as `.gitignore` (glob matching
-via picomatch).
-
-### Policy defaults
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| Line threshold | 150 | Files over this → outline |
-| Byte threshold | 12 KB | Files over this → outline |
-| Max range | 250 lines | read_range cap |
-| State cap | 8 KB | state_save max size |
-| Capture tail | 60 lines | run_capture default |
-
-These are not yet configurable at runtime (planned for a future
-release).
-
-## Troubleshooting
-
-### "Tool not found" or no graft tools visible
-
-- Verify graft is installed: `npx @flyingrobots/graft --help`
-  (should start the server; Ctrl+C to stop)
-- Check your MCP config syntax — JSON must be valid
-- Restart your editor/agent after adding MCP config
-- Some clients cache tool lists — try reopening the project
-
-### Agent keeps getting outlines instead of content
-
-Your files are over 150 lines or 12 KB. This is intentional.
-The agent should use the jump table from the outline to
-`read_range` the specific section it needs.
-
-### Agent can't read a file (refused)
-
-Check the reason code in the response:
-- `BINARY` — binary file, use `ls -lh` or `file` for metadata
-- `LOCKFILE` — read `package.json` instead
-- `SECRET` — `.env` files are banned for safety
-- `BUILD_OUTPUT` — read the source file, not `dist/`
-- `GRAFTIGNORE` — file matches a `.graftignore` pattern
-
-### graft is slow on first call
-
-Tree-sitter WASM grammars load on first parse (~200ms). Subsequent
-calls are fast.
-
-## Verify it works
-
-After setup, ask your agent to read a large file in your project.
-Instead of dumping the entire file, it should return an outline
-with a jump table. That's graft working.
-
-You can also ask the agent to call `doctor` to verify:
-
-```
-Use the doctor tool to check graft's health.
-```
-
-This returns the project root, parser status, active thresholds,
-and session depth.