@flyingrobots/graft 0.3.1

package/src/guards/stream-boundary.ts

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// Stream/Port boundary guards — enforce the Two-Case Rule at runtime
+// ---------------------------------------------------------------------------
+//
+// Law: Streams explore. Ports decide.
+//
+// Ports return bounded artifacts (Promise<T>). Streams return
+// unbounded traversals (AsyncIterable<T>). These two shapes MUST
+// NOT cross. A port that returns a stream is a lie. A stream that
+// returns a single value is a waste.
+//
+// These guards make violations throw, not silently misbehave.
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the value implements the async iterable protocol.
+ */
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as Record<symbol, unknown>)[Symbol.asyncIterator] === "function"
+  );
+}
+
+/**
+ * Throws if the value is an AsyncIterable. Use at port return boundaries
+ * to prevent streams from leaking into persistence layers.
+ *
+ * @param value - The value to check
+ * @param context - Description of where the check is (e.g. "FileSystem.readFile()")
+ */
+export function assertNotStream(value: unknown, context: string): void {
+  if (isAsyncIterable(value)) {
+    throw new TypeError(
+      `${context} produced a stream where a bounded value was required. ` +
+      `Ports return artifacts, not traversals.`,
+    );
+  }
+}
+
+/**
+ * Throws if the value is NOT an AsyncIterable. Use at stream transform
+ * entry points to prevent bounded values from entering traversal pipelines.
+ *
+ * @param value - The value to check
+ * @param context - Description of where the check is (e.g. "BlobWriteTransform.apply()")
+ */
+export function assertStream(value: unknown, context: string): asserts value is AsyncIterable<unknown> {
+  if (!isAsyncIterable(value)) {
+    const actual = value === null ? "null"
+      : Array.isArray(value) ? "Array"
+      : typeof value;
+    throw new TypeError(
+      `${context} expected AsyncIterable but received ${actual}. ` +
+      `Streams traverse, they do not materialize.`,
+    );
+  }
+}
+
+/**
+ * Wraps a port method to guard its return value against accidental streams.
+ * Use this to retrofit existing ports without modifying their interfaces.
+ *
+ * @param portName - Name of the port class (for error messages)
+ * @param methodName - Name of the method being guarded
+ * @param fn - The original method
+ */
+export function guardPortReturn<TArgs extends unknown[], TReturn>(
+  portName: string,
+  methodName: string,
+  fn: (...args: TArgs) => Promise<TReturn>,
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    const result = await fn(...args);
+    assertNotStream(result, `${portName}.${methodName}()`);
+    return result;
+  };
+}
+
+/**
+ * Wraps an entire port interface via Proxy. Every method call is
+ * intercepted: if the return is a Promise, it's awaited and checked
+ * with assertNotStream. Synchronous returns are checked directly.
+ *
+ * One line to guard a whole port instead of per-method wiring.
+ *
+ * @param portName - Name of the port (for error messages)
+ * @param port - The port instance to guard
+ */
+export function guardedPort<T extends object>(portName: string, port: T): T {
+  return new Proxy(port, {
+    get(target: T, prop: string | symbol, receiver: unknown): unknown {
+      const value = Reflect.get(target, prop, receiver) as unknown;
+      if (typeof value !== "function") return value;
+      const methodName = typeof prop === "symbol" ? prop.toString() : prop;
+      return function (this: unknown, ...args: unknown[]): unknown {
+        const result = (value as (...a: unknown[]) => unknown).apply(target, args);
+        if (result instanceof Promise) {
+          return result.then((resolved: unknown) => {
+            assertNotStream(resolved, `${portName}.${methodName}()`);
+            return resolved;
+          });
+        }
+        assertNotStream(result, `${portName}.${methodName}()`);
+        return result;
+      };
+    },
+  });
+}

package/src/hooks/posttooluse-read.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// PostToolUse hook for Read — educates the agent on context cost
+// ---------------------------------------------------------------------------
+//
+// After a Read completes, evaluates what safe_read would have done and
+// tells the agent the cost difference. Does not block — just feedback.
+//
+// The agent sees messages like:
+//   "[graft] You just read 450 lines (18KB). safe_read would have
+//    returned a 2KB outline, saving 16KB of context."
+//
+// This teaches the agent to prefer graft's MCP tools voluntarily.
+//
+// Invoked as: node --import tsx src/hooks/posttooluse-read.ts
+// Receives JSON on stdin from Claude Code hooks system.
+// ---------------------------------------------------------------------------
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { evaluatePolicy, STATIC_THRESHOLDS } from "../policy/evaluate.js";
+import { ContentResult, RefusedResult } from "../policy/types.js";
+import { loadGraftignore } from "../policy/graftignore.js";
+import { HookInput, HookOutput, safeRelativePath, runHook } from "./shared.js";
+
+export { HookInput, HookOutput };
+
+export async function handlePostReadHook(input: HookInput): Promise<HookOutput> {
+  const filePath = input.tool_input.file_path;
+
+  // Path outside project — no feedback
+  const relPath = safeRelativePath(input.cwd, filePath);
+  if (relPath === null) {
+    return new HookOutput(0, "");
+  }
+
+  // Read file to get dimensions
+  let rawContent: string;
+  try {
+    rawContent = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return new HookOutput(0, "");
+  }
+
+  const lines = rawContent.split("\n");
+  const bytes = Buffer.byteLength(rawContent, "utf-8");
+
+  // Load .graftignore patterns
+  let graftignorePatterns: string[] | undefined;
+  try {
+    const ignoreFile = fs.readFileSync(
+      path.join(input.cwd, ".graftignore"),
+      "utf-8",
+    );
+    graftignorePatterns = loadGraftignore(ignoreFile);
+  } catch {
+    // No .graftignore
+  }
+
+  // Evaluate what safe_read would have done
+  const policy = evaluatePolicy(
+    { path: relPath, lines: lines.length, bytes },
+    { graftignorePatterns },
+  );
+
+  // Small file — no feedback needed, Read was the right call
+  if (policy instanceof ContentResult) {
+    return new HookOutput(0, "");
+  }
+
+  // Refused — PreToolUse should have caught this, but just in case
+  if (policy instanceof RefusedResult) {
+    return new HookOutput(0, "");
+  }
+
+  // Outline projection — the agent just dumped a large file into context
+  // when safe_read would have returned a compact outline
+  const { detectLang } = await import("../parser/lang.js");
+  const lang = detectLang(filePath);
+  if (lang === null) {
+    // Non-JS/TS — no outline available, Read was reasonable
+    return new HookOutput(0, "");
+  }
+
+  const { CanonicalJsonCodec } = await import("../adapters/canonical-json.js");
+  const { extractOutline } = await import("../parser/outline.js");
+  const codec = new CanonicalJsonCodec();
+  const outline = extractOutline(rawContent, lang);
+  const outlineBytes = Buffer.byteLength(codec.encode(outline), "utf-8");
+  const saved = bytes - outlineBytes;
+  const savedKb = (saved / 1024).toFixed(1);
+  const bytesKb = (bytes / 1024).toFixed(1);
+
+  return new HookOutput(0, [
+    `[graft] You just read ${String(lines.length)} lines (${bytesKb}KB) into context.`,
+    `safe_read would have returned a structural outline (${String(outlineBytes)} bytes),`,
+    `saving ${savedKb}KB of context. Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
+    "",
+    "Consider using graft's safe_read tool for large files —",
+    "it returns outlines with jump tables for targeted read_range.",
+  ].join("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// Script entry point — exit 0 on failure, never block on post-hook errors
+// ---------------------------------------------------------------------------
+
+runHook(handlePostReadHook, 0);

package/src/hooks/pretooluse-read.ts

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// PreToolUse hook for Read — blocks banned files only
+// ---------------------------------------------------------------------------
+//
+// Intercepts Claude Code's Read tool and evaluates graft policy:
+//   - Refused (banned file): exit 2 — hard block with refusal reason
+//   - Everything else: exit 0 — let native Read proceed
+//
+// Banned files (.env, binaries, lockfiles, minified, build output,
+// .graftignore matches) are the only hard enforcement. Large file
+// governance is handled by the PostToolUse hook via education.
+//
+// Invoked as: node --import tsx src/hooks/pretooluse-read.ts
+// Receives JSON on stdin from Claude Code hooks system.
+// ---------------------------------------------------------------------------
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { evaluatePolicy } from "../policy/evaluate.js";
+import { RefusedResult } from "../policy/types.js";
+import { loadGraftignore } from "../policy/graftignore.js";
+import { HookInput, HookOutput, safeRelativePath, runHook } from "./shared.js";
+
+export { HookInput, HookOutput };
+
+export function handleReadHook(input: HookInput): HookOutput {
+  const filePath = input.tool_input.file_path;
+
+  // Path outside project — let Read handle it, not our concern
+  const relPath = safeRelativePath(input.cwd, filePath);
+  if (relPath === null) {
+    return new HookOutput(0, "");
+  }
+
+  // Read file to get dimensions for policy
+  let rawContent: string;
+  try {
+    rawContent = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    // File errors (ENOENT, EACCES, EISDIR) — let Read handle natively
+    return new HookOutput(0, "");
+  }
+
+  const lines = rawContent.split("\n");
+  const bytes = Buffer.byteLength(rawContent, "utf-8");
+
+  // Load .graftignore patterns
+  let graftignorePatterns: string[] | undefined;
+  try {
+    const ignoreFile = fs.readFileSync(
+      path.join(input.cwd, ".graftignore"),
+      "utf-8",
+    );
+    graftignorePatterns = loadGraftignore(ignoreFile);
+  } catch {
+    // No .graftignore — that's fine
+  }
+
+  // Evaluate policy
+  const policy = evaluatePolicy(
+    { path: relPath, lines: lines.length, bytes },
+    { graftignorePatterns },
+  );
+
+  // Only block refused files — everything else passes through
+  if (policy instanceof RefusedResult) {
+    const nextSteps = policy.next.map((n) => `  - ${n}`).join("\n");
+    return new HookOutput(2, [
+      `[graft] Refused: ${policy.reason}`,
+      policy.reasonDetail,
+      "",
+      "Next steps:",
+      nextSteps,
+      "",
+      "Graft tools: use file_outline to see the file's structure,",
+      "or safe_read for a policy-aware read with caching.",
+    ].join("\n"));
+  }
+
+  // Content or outline — let Read proceed. PostToolUse will educate.
+  return new HookOutput(0, "");
+}
+
+// ---------------------------------------------------------------------------
+// Script entry point — exit 2 on failure to block unsafe reads
+// ---------------------------------------------------------------------------
+
+runHook(handleReadHook, 2);

package/src/hooks/shared.ts

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// Shared utilities for Claude Code hooks
+// ---------------------------------------------------------------------------
+
+import * as path from "node:path";
+
+/** Maximum stdin bytes before rejecting (1 MB — generous for JSON). */
+const MAX_STDIN_BYTES = 1_048_576;
+
+export class HookInput {
+  readonly session_id: string;
+  readonly cwd: string;
+  readonly hook_event_name: string;
+  readonly tool_name: string;
+  readonly tool_input: {
+    readonly file_path: string;
+    readonly offset?: number;
+    readonly limit?: number;
+  };
+  readonly tool_result?: string;
+
+  constructor(opts: {
+    session_id: string;
+    cwd: string;
+    hook_event_name: string;
+    tool_name: string;
+    tool_input: { file_path: string; offset?: number; limit?: number };
+    tool_result?: string;
+  }) {
+    if (opts.session_id.length === 0) {
+      throw new Error("HookInput: session_id must be non-empty");
+    }
+    if (opts.cwd.length === 0) {
+      throw new Error("HookInput: cwd must be non-empty");
+    }
+    if (opts.tool_input.file_path.length === 0) {
+      throw new Error("HookInput: tool_input.file_path must be non-empty");
+    }
+    this.session_id = opts.session_id;
+    this.cwd = opts.cwd;
+    this.hook_event_name = opts.hook_event_name;
+    this.tool_name = opts.tool_name;
+    this.tool_input = Object.freeze({ ...opts.tool_input });
+    if (opts.tool_result !== undefined) this.tool_result = opts.tool_result;
+    Object.freeze(this);
+  }
+}
+
+export class HookOutput {
+  readonly exitCode: number;
+  readonly stderr: string;
+
+  constructor(exitCode: number, stderr: string) {
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Reads stdin with a size guard. Throws if input exceeds MAX_STDIN_BYTES.
+ * Accumulates raw buffers to avoid corrupting multi-byte UTF-8 characters
+ * that may be split across chunk boundaries.
+ */
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  let totalBytes = 0;
+  for await (const chunk of process.stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf-8");
+    totalBytes += buf.length;
+    if (totalBytes > MAX_STDIN_BYTES) {
+      throw new Error(
+        `stdin exceeded ${String(MAX_STDIN_BYTES)} bytes — aborting`,
+      );
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/**
+ * Parses and validates hook input from a raw JSON string.
+ * Returns a frozen HookInput instance.
+ */
+export function parseHookInput(raw: string): HookInput {
+  const parsed: unknown = JSON.parse(raw);
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("Hook input must be a JSON object");
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  const sessionId = obj["session_id"];
+  if (typeof sessionId !== "string") {
+    throw new Error("Hook input missing session_id");
+  }
+
+  const cwd = obj["cwd"];
+  if (typeof cwd !== "string") {
+    throw new Error("Hook input missing cwd");
+  }
+
+  const rawToolInput = obj["tool_input"];
+  if (typeof rawToolInput !== "object" || rawToolInput === null) {
+    throw new Error("Hook input missing tool_input");
+  }
+  const toolInput = rawToolInput as Record<string, unknown>;
+
+  const filePath = toolInput["file_path"];
+  if (typeof filePath !== "string") {
+    throw new Error("Hook input missing tool_input.file_path");
+  }
+
+  const hookEventName = obj["hook_event_name"];
+  const toolName = obj["tool_name"];
+  const toolResult = obj["tool_result"];
+  const offset = toolInput["offset"];
+  const limit = toolInput["limit"];
+
+  return new HookInput({
+    session_id: sessionId,
+    cwd,
+    hook_event_name: typeof hookEventName === "string" ? hookEventName : "",
+    tool_name: typeof toolName === "string" ? toolName : "",
+    tool_input: {
+      file_path: filePath,
+      ...(typeof offset === "number" ? { offset } : {}),
+      ...(typeof limit === "number" ? { limit } : {}),
+    },
+    ...(typeof toolResult === "string" ? { tool_result: toolResult } : {}),
+  });
+}
+
+/**
+ * Returns a cwd-relative path, or null if the path is outside the cwd.
+ * Prevents path traversal attacks and handles the path.relative() edge case
+ * where paths outside cwd produce absolute or '../' prefixed results.
+ */
+export function safeRelativePath(cwd: string, filePath: string): string | null {
+  const rel = path.relative(cwd, filePath);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    return null;
+  }
+  return rel;
+}
+
+/**
+ * Wraps a hook's main function with stdin reading, input parsing,
+ * and error handling. Logs full stack traces on failure.
+ */
+export function runHook(
+  handler: (input: HookInput) => HookOutput | Promise<HookOutput>,
+  failExitCode: number,
+): void {
+  const run = async (): Promise<void> => {
+    const raw = await readStdin();
+    const input = parseHookInput(raw);
+    const output = await handler(input);
+    if (output.stderr.length > 0) process.stderr.write(output.stderr);
+    process.exit(output.exitCode);
+  };
+
+  run().catch((err: unknown) => {
+    const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    process.stderr.write(`[graft] Hook error: ${detail}`);
+    process.exit(failExitCode);
+  });
+}

package/src/mcp/cache.ts

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// Observation cache — tracks file content seen by the agent
+// ---------------------------------------------------------------------------
+
+import * as crypto from "node:crypto";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+
+export function hashContent(content: string): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+export class Observation {
+  readonly contentHash: string;
+  readonly outline: readonly OutlineEntry[];
+  readonly jumpTable: readonly JumpEntry[];
+  readonly actual: Readonly<{ lines: number; bytes: number }>;
+  readonly firstReadAt: string;
+  private _readCount: number;
+  private _lastReadAt: string;
+
+  constructor(opts: {
+    contentHash: string;
+    outline: readonly OutlineEntry[];
+    jumpTable: readonly JumpEntry[];
+    actual: Readonly<{ lines: number; bytes: number }>;
+    readCount: number;
+    firstReadAt: string;
+    lastReadAt: string;
+  }) {
+    this.contentHash = opts.contentHash;
+    this.outline = opts.outline;
+    this.jumpTable = opts.jumpTable;
+    this.actual = opts.actual;
+    this._readCount = opts.readCount;
+    this.firstReadAt = opts.firstReadAt;
+    this._lastReadAt = opts.lastReadAt;
+  }
+
+  get readCount(): number {
+    return this._readCount;
+  }
+
+  get lastReadAt(): string {
+    return this._lastReadAt;
+  }
+
+  isStale(currentContentHash: string): boolean {
+    return this.contentHash !== currentContentHash;
+  }
+
+  touch(): void {
+    this._readCount++;
+    this._lastReadAt = new Date().toISOString();
+  }
+}
+
+export type CacheResult =
+  | { hit: true; obs: Observation }
+  | { hit: false; stale: Observation | null };
+
+export class ObservationCache {
+  private readonly entries = new Map<string, Observation>();
+
+  record(
+    filePath: string,
+    contentHash: string,
+    outline: readonly OutlineEntry[],
+    jumpTable: readonly JumpEntry[],
+    actual: Readonly<{ lines: number; bytes: number }>,
+  ): void {
+    const existing = this.entries.get(filePath);
+    const now = new Date().toISOString();
+    this.entries.set(filePath, new Observation({
+      contentHash,
+      outline,
+      jumpTable,
+      actual,
+      readCount: (existing?.readCount ?? 0) + 1,
+      firstReadAt: existing?.firstReadAt ?? now,
+      lastReadAt: now,
+    }));
+  }
+
+  check(filePath: string, currentContent: string): CacheResult {
+    const obs = this.entries.get(filePath);
+    if (obs === undefined) return { hit: false, stale: null };
+    if (!obs.isStale(hashContent(currentContent))) return { hit: true, obs };
+    return { hit: false, stale: obs };
+  }
+
+  get(filePath: string): Observation | undefined {
+    return this.entries.get(filePath);
+  }
+}

package/src/mcp/cached-file.ts

@@ -0,0 +1,38 @@
+import { extractOutline } from "../parser/outline.js";
+import { detectLang } from "../parser/lang.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import { hashContent } from "./cache.js";
+
+/**
+ * Immutable snapshot of a file read. Built once from a single readFileSync,
+ * shared by all consumers (cache, policy, outline extraction) to eliminate
+ * TOCTOU races where the file changes between reads.
+ */
+export class CachedFile {
+  /** @internal */
+  private readonly _brand = "CachedFile" as const;
+  readonly path: string;
+  readonly rawContent: string;
+  readonly hash: string;
+  readonly outline: readonly OutlineEntry[];
+  readonly jumpTable: readonly JumpEntry[];
+  readonly actual: { readonly lines: number; readonly bytes: number };
+
+  constructor(filePath: string, rawContent: string) {
+    this.path = filePath;
+    this.rawContent = rawContent;
+    this.hash = hashContent(rawContent);
+    this.actual = {
+      lines: rawContent.split("\n").length,
+      bytes: Buffer.byteLength(rawContent),
+    };
+    // Fallback to "ts" parser for unknown extensions — TS/JS parser handles
+    // .mjs, .cjs, and other JS-family files that detectLang doesn't cover.
+    const lang = detectLang(filePath) ?? "ts";
+    const result = extractOutline(rawContent, lang);
+    this.outline = result.entries;
+    this.jumpTable = result.jumpTable ?? [];
+    Object.freeze(this.actual);
+    Object.freeze(this);
+  }
+}

package/src/mcp/context.ts

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// ToolContext — shared dependencies injected into every tool handler
+// ---------------------------------------------------------------------------
+
+import * as path from "node:path";
+import type { ObservationCache } from "./cache.js";
+import type { Metrics } from "./metrics.js";
+import type { SessionTracker } from "../session/tracker.js";
+import type { McpToolResult } from "./receipt.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { JsonCodec } from "../ports/codec.js";
+
+import type { z } from "zod";
+
+export type ToolHandler = (args: Record<string, unknown>) => McpToolResult | Promise<McpToolResult>;
+
+export interface ToolDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly schema?: Record<string, z.ZodType>;
+  readonly policyCheck?: boolean;
+  readonly createHandler: (ctx: ToolContext) => ToolHandler;
+}
+
+export interface ToolContext {
+  readonly projectRoot: string;
+  readonly graftDir: string;
+  readonly session: SessionTracker;
+  readonly cache: ObservationCache;
+  readonly metrics: Metrics;
+  readonly fs: FileSystem;
+  readonly codec: JsonCodec;
+  respond(tool: string, data: Record<string, unknown>): McpToolResult;
+  resolvePath(relative: string): string;
+}
+
+/**
+ * Resolve a user-provided path against projectRoot with traversal guard.
+ * Absolute paths pass through unchanged. Relative paths that escape the
+ * project root via ".." are rejected.
+ */
+export function createPathResolver(projectRoot: string): (input: string) => string {
+  return (input: string): string => {
+    if (path.isAbsolute(input)) return input;
+    const resolved = path.resolve(projectRoot, input);
+    const rel = path.relative(projectRoot, resolved);
+    if (rel.startsWith("..")) {
+      throw new Error(`Path traversal blocked: ${input}`);
+    }
+    return resolved;
+  };
+}