@flyingrobots/graft 0.7.0 → 0.8.0

package/src/git/diff.ts

@@ -1,161 +0,0 @@
-import type { GitClient } from "../ports/git.js";
-
-export interface ChangedFilesOptions {
-  cwd: string;
-  git: GitClient;
-  base?: string | undefined;
-  head?: string | undefined;
-}
-
-export class GitError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "GitError";
-  }
-}
-
-async function git(gitClient: GitClient, args: readonly string[], cwd: string): Promise<string> {
-  const result = await gitClient.run({ args, cwd });
-  if (result.error !== undefined || result.status !== 0) {
-    throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
-  }
-  return result.stdout;
-}
-
-async function refExists(ref: string, cwd: string, gitClient: GitClient): Promise<boolean> {
-  try {
-    await git(gitClient, ["rev-parse", "--verify", ref], cwd);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function objectExists(ref: string, filePath: string, cwd: string, gitClient: GitClient): Promise<boolean> {
-  try {
-    await git(gitClient, ["cat-file", "-e", `${ref}:${filePath}`], cwd);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * List files changed between two refs, or between a ref and the working tree.
- * If head is omitted, diffs against the working tree.
- * If both base and head are omitted, diffs HEAD against the working tree.
- *
- * Throws GitError for invalid refs or non-git directories.
- * Returns empty array only when there are genuinely no changes.
- */
-
-export type ChangedFileStatus = "added" | "modified" | "deleted" | "renamed";
-
-export interface ChangedFile {
-  readonly path: string;
-  readonly status: ChangedFileStatus;
-  readonly oldPath?: string;
-}
-
-const STATUS_MAP: Record<string, ChangedFileStatus> = {
-  A: "added",
-  M: "modified",
-  D: "deleted",
-  R: "renamed",
-};
-
-function parseNameStatus(output: string): ChangedFile[] {
-  if (output === "") return [];
-  const lines = output.split("\n");
-  const result: ChangedFile[] = [];
-  for (const line of lines) {
-    const statusCode = line[0];
-    if (statusCode === undefined) continue;
-    const baseStatus = statusCode === "R" || statusCode === "C" ? statusCode : statusCode;
-    const status = STATUS_MAP[baseStatus] ?? "modified";
-    const parts = line.split("\t");
-    if (statusCode === "R" || statusCode === "C") {
-      const oldPath = parts[1];
-      const newPath = parts[2];
-      if (oldPath !== undefined && newPath !== undefined) {
-        result.push({ path: newPath, status, oldPath });
-      }
-    } else {
-      const filePath = parts[1];
-      if (filePath !== undefined) {
-        result.push({ path: filePath, status });
-      }
-    }
-  }
-  return result;
-}
-
-/**
- * List files changed between two refs with rename detection.
- * Returns structured data including status and old path for renames.
- */
-export async function getChangedFilesWithStatus(opts: ChangedFilesOptions): Promise<ChangedFile[]> {
-  const base = opts.base ?? "HEAD";
-  const args = opts.head !== undefined
-    ? ["diff-tree", "--no-commit-id", "--name-status", "-M", "-r", base, opts.head]
-    : ["diff-index", "--name-status", "-M", base, "--"];
-
-  try {
-    const output = (await git(opts.git, args, opts.cwd)).trim();
-    return parseNameStatus(output);
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new GitError(`git diff failed: ${msg}`);
-  }
-}
-
-export async function getChangedFiles(opts: ChangedFilesOptions): Promise<string[]> {
-  const base = opts.base ?? "HEAD";
-  const args = opts.head !== undefined
-    ? ["diff-tree", "--no-commit-id", "--name-only", "-r", base, opts.head]
-    : ["diff-index", "--name-only", base, "--"];
-
-  try {
-    const output = (await git(opts.git, args, opts.cwd)).trim();
-    if (output === "") return [];
-    return output.split("\n");
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new GitError(`git diff failed: ${msg}`);
-  }
-}
-
-/**
- * Get the content of a file at a specific git ref.
- * Returns null if the file doesn't exist at that ref (clean absence).
- * Throws GitError for invalid refs or git failures.
- *
- * Uses `git rev-parse --verify` and `git cat-file -e` for stable
- * detection — no error message parsing.
- */
-export async function getFileAtRef(
-  ref: string,
-  filePath: string,
-  opts: {
-    cwd: string;
-    git: GitClient;
-  },
-): Promise<string | null> {
-  // Validate the ref exists (stable probe, no message parsing)
-  if (!(await refExists(ref, opts.cwd, opts.git))) {
-    throw new GitError(`ref does not exist: ${ref}`);
-  }
-
-  // Check if the object exists at this ref (stable probe)
-  if (!(await objectExists(ref, filePath, opts.cwd, opts.git))) {
-    return null; // Clean absence — file not in this ref
-  }
-
-  // Object exists — read it
-  try {
-    return await git(opts.git, ["show", `${ref}:${filePath}`], opts.cwd);
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new GitError(`git show ${ref}:${filePath} failed: ${msg}`);
-  }
-}

package/src/git/target-git-hook-bootstrap.ts

@@ -1,56 +0,0 @@
-import * as path from "node:path";
-
-export const TARGET_GIT_TRANSITION_HOOKS = [
-  "post-checkout",
-  "post-merge",
-  "post-rewrite",
-] as const;
-
-export const TARGET_GIT_HOOK_MARKER = "graft-target-repo-git-hook";
-
-export function resolveGitHooksPath(
-  worktreeRoot: string,
-  gitCommonDir: string,
-  configuredCoreHooksPath: string | null,
-): string {
-  if (configuredCoreHooksPath === null) {
-    return path.join(gitCommonDir, "hooks");
-  }
-  return path.isAbsolute(configuredCoreHooksPath)
-    ? configuredCoreHooksPath
-    : path.resolve(worktreeRoot, configuredCoreHooksPath);
-}
-
-export function isRecognizedTargetGitHook(
-  content: string,
-  hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number],
-): boolean {
-  return content.includes(`# ${TARGET_GIT_HOOK_MARKER}:${hookName}`);
-}
-
-export function isTargetGitTransitionHookName(
-  value: string,
-): value is (typeof TARGET_GIT_TRANSITION_HOOKS)[number] {
-  return TARGET_GIT_TRANSITION_HOOKS.includes(value as (typeof TARGET_GIT_TRANSITION_HOOKS)[number]);
-}
-
-export function buildTargetGitHookScript(
-  hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number],
-): string {
-  return [
-    "#!/bin/sh",
-    `# ${TARGET_GIT_HOOK_MARKER}:${hookName}`,
-    "set -eu",
-    "GRAFT_WORKTREE_ROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"",
-    "node -e '",
-    "const fs = require(\"node:fs\");",
-    "const path = require(\"node:path\");",
-    "const [hookName, worktreeRoot, ...hookArgs] = process.argv.slice(1);",
-    "const runtimeDir = path.join(worktreeRoot, \".graft\", \"runtime\");",
-    "fs.mkdirSync(runtimeDir, { recursive: true });",
-    "const event = { hookName, hookArgs, worktreeRoot, observedAt: new Date().toISOString() };",
-    "fs.appendFileSync(path.join(runtimeDir, \"git-transitions.ndjson\"), JSON.stringify(event) + \"\\n\");",
-    `' "${hookName}" "$GRAFT_WORKTREE_ROOT" "$@"`,
-    "",
-  ].join("\n");
-}

package/src/guards/stream-boundary.ts

@@ -1,110 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,54 +0,0 @@
-// ---------------------------------------------------------------------------
-// PostToolUse hook for Read — educates the agent on context cost
-// ---------------------------------------------------------------------------
-//
-// After a Read completes, evaluates whether a large JS/TS file bypassed
-// graft's governed path and tells the agent the cost difference.
-// Does not block — just feedback.
-//
-// The agent sees messages like:
-//   "[graft] This large code read bypassed graft's governed path ...
-//    safe_read would have returned a 2KB outline, saving 16KB."
-//
-// 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 { HookInput, HookOutput, runHook } from "./shared.js";
-import { renderOversizedReadEducation } from "./read-messages.js";
-import {
-  inspectHookRead,
-} from "./read-governor.js";
-
-export { HookInput, HookOutput };
-
-export async function handlePostReadHook(input: HookInput): Promise<HookOutput> {
-  const inspection = inspectHookRead(input);
-  if (!inspection?.isGovernedCodeRead()) {
-    return new HookOutput(0, "");
-  }
-
-  const { extractOutlineForFile } = await import("../parser/outline.js");
-  const outline = extractOutlineForFile(
-    inspection.absolutePath,
-    inspection.rawContent,
-  );
-  if (outline === null) {
-    return new HookOutput(0, "");
-  }
-
-  const { CanonicalJsonCodec } = await import("../adapters/canonical-json.js");
-  const codec = new CanonicalJsonCodec();
-  const outlineBytes = Buffer.byteLength(codec.encode(outline), "utf-8");
-  return new HookOutput(
-    0,
-    renderOversizedReadEducation(inspection, outlineBytes),
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Script entry point — exit 0 on failure, never block on post-hook errors
-// ---------------------------------------------------------------------------
-
-runHook(handlePostReadHook, 0);

package/src/hooks/pretooluse-read.ts

@@ -1,52 +0,0 @@
-// ---------------------------------------------------------------------------
-// PreToolUse hook for Read — blocks banned files and redirects large code reads
-// ---------------------------------------------------------------------------
-//
-// Intercepts Claude Code's Read tool and evaluates graft policy:
-//   - Refused (banned file): exit 2 — hard block with refusal reason
-//   - Oversized JS/TS file: exit 2 — redirect to graft's bounded-read path
-//   - Everything else: exit 0 — let native Read proceed
-//
-// Banned files (.env, binaries, lockfiles, minified, build output,
-// .graftignore matches) stay hard blocks. Large JS/TS files now route
-// through graft's governed path before native Read can dump them into
-// context. PostToolUse remains a backstop if an oversized code read
-// still slips through.
-//
-// Invoked as: node --import tsx src/hooks/pretooluse-read.ts
-// Receives JSON on stdin from Claude Code hooks system.
-// ---------------------------------------------------------------------------
-import { RefusedResult } from "../policy/types.js";
-import {
-  renderGovernedReadRedirect,
-  renderRefusedReadMessage,
-} from "./read-messages.js";
-import {
-  inspectHookRead,
-} from "./read-governor.js";
-import { HookInput, HookOutput, runHook } from "./shared.js";
-
-export { HookInput, HookOutput };
-
-export function handleReadHook(input: HookInput): HookOutput {
-  const inspection = inspectHookRead(input);
-  if (inspection === null) {
-    return new HookOutput(0, "");
-  }
-
-  if (inspection.policy instanceof RefusedResult) {
-    return new HookOutput(2, renderRefusedReadMessage(inspection.policy));
-  }
-
-  if (inspection.isGovernedCodeRead()) {
-    return new HookOutput(2, renderGovernedReadRedirect(inspection));
-  }
-
-  return new HookOutput(0, "");
-}
-
-// ---------------------------------------------------------------------------
-// Script entry point — exit 2 on failure to block unsafe reads
-// ---------------------------------------------------------------------------
-
-runHook(handleReadHook, 2);

package/src/hooks/read-governor.ts

@@ -1,95 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { SupportedLang } from "../parser/lang.js";
-import { detectLang } from "../parser/lang.js";
-import { evaluatePolicy } from "../policy/evaluate.js";
-import type { PolicyResult } from "../policy/types.js";
-import { loadGraftignore } from "../policy/graftignore.js";
-import { HookInput, safeRelativePath } from "./shared.js";
-
-export class HookReadInspection {
-  readonly absolutePath: string;
-  readonly relativePath: string;
-  readonly rawContent: string;
-  readonly lines: number;
-  readonly bytes: number;
-  readonly lang: SupportedLang | null;
-  readonly policy: PolicyResult;
-
-  constructor(opts: {
-    absolutePath: string;
-    relativePath: string;
-    rawContent: string;
-    lines: number;
-    bytes: number;
-    lang: SupportedLang | null;
-    policy: PolicyResult;
-  }) {
-    if (opts.absolutePath.length === 0) {
-      throw new Error("HookReadInspection: absolutePath must be non-empty");
-    }
-    if (opts.relativePath.length === 0) {
-      throw new Error("HookReadInspection: relativePath must be non-empty");
-    }
-    if (opts.lines < 0) {
-      throw new Error("HookReadInspection: lines must be non-negative");
-    }
-    if (opts.bytes < 0) {
-      throw new Error("HookReadInspection: bytes must be non-negative");
-    }
-
-    this.absolutePath = opts.absolutePath;
-    this.relativePath = opts.relativePath;
-    this.rawContent = opts.rawContent;
-    this.lines = opts.lines;
-    this.bytes = opts.bytes;
-    this.lang = opts.lang;
-    this.policy = opts.policy;
-    Object.freeze(this);
-  }
-
-  isGovernedCodeRead(): boolean {
-    return this.lang !== null && this.policy.projection === "outline";
-  }
-}
-
-function loadGraftignorePatterns(cwd: string): string[] | undefined {
-  try {
-    const ignoreFile = fs.readFileSync(path.join(cwd, ".graftignore"), "utf-8");
-    return loadGraftignore(ignoreFile);
-  } catch {
-    return undefined;
-  }
-}
-
-export function inspectHookRead(input: HookInput): HookReadInspection | null {
-  const absolutePath = input.tool_input.file_path;
-  const relativePath = safeRelativePath(input.cwd, absolutePath);
-  if (relativePath === null) {
-    return null;
-  }
-
-  let rawContent: string;
-  try {
-    rawContent = fs.readFileSync(absolutePath, "utf-8");
-  } catch {
-    return null;
-  }
-
-  const lines = rawContent.split("\n").length;
-  const bytes = Buffer.byteLength(rawContent, "utf-8");
-  const policy = evaluatePolicy(
-    { path: relativePath, lines, bytes },
-    { graftignorePatterns: loadGraftignorePatterns(input.cwd) },
-  );
-
-  return new HookReadInspection({
-    absolutePath,
-    relativePath,
-    rawContent,
-    lines,
-    bytes,
-    lang: detectLang(absolutePath),
-    policy,
-  });
-}

package/src/hooks/read-messages.ts

@@ -1,53 +0,0 @@
-import { STATIC_THRESHOLDS } from "../policy/evaluate.js";
-import { RefusedResult } from "../policy/types.js";
-import { HookReadInspection } from "./read-governor.js";
-
-function formatKilobytes(bytes: number): string {
-  return (bytes / 1024).toFixed(1);
-}
-
-export function renderRefusedReadMessage(policy: RefusedResult): string {
-  const nextSteps = policy.next.map((step) => `  - ${step}`).join("\n");
-  return [
-    `[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");
-}
-
-export function renderGovernedReadRedirect(
-  inspection: HookReadInspection,
-): string {
-  return [
-    `[graft] Governed read: ${inspection.relativePath}`,
-    `Native Read would dump ${String(inspection.lines)} lines (${formatKilobytes(inspection.bytes)}KB) into context.`,
-    "This large JS/TS file should go through graft's bounded-read path instead.",
-    "",
-    "Next steps:",
-    `  - Call safe_read on ${inspection.relativePath}`,
-    "  - Use read_range with jump table entries for the exact region you need",
-    "  - Use file_outline if you only need symbol structure",
-    "",
-    `Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
-  ].join("\n");
-}
-
-export function renderOversizedReadEducation(
-  inspection: HookReadInspection,
-  outlineBytes: number,
-): string {
-  const savedBytes = inspection.bytes - outlineBytes;
-  return [
-    `[graft] This large code read bypassed graft's governed path for ${inspection.relativePath}.`,
-    `safe_read would have returned a structural outline (${String(outlineBytes)} bytes) instead of ${String(inspection.lines)} lines (${formatKilobytes(inspection.bytes)}KB),`,
-    `saving ${formatKilobytes(savedBytes)}KB of context. Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
-    "",
-    "If this was unexpected, verify the Claude PreToolUse hook is installed and active.",
-    "Use read_range with jump table entries after safe_read for targeted follow-up.",
-  ].join("\n");
-}