@flyingrobots/graft 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyingrobots/graft",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Context governor and between-commit activity surface for coding agents",
   "type": "module",
   "packageManager": "pnpm@10.30.0",
@@ -21,29 +21,32 @@
     "bin/",
     "dist/",
     "src/",
+    "ADVANCED_GUIDE.md",
     "ARCHITECTURE.md",
+    "CHANGELOG.md",
     "CODE_OF_CONDUCT.md",
-    "docs/ADVANCED_GUIDE.md",
+    "GUIDE.md",
     "docs/CLI.md",
-    "docs/GUIDE.md",
     "docs/MCP.md",
+    "docs/SETUP.md",
     "LICENSE",
     "NOTICE",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "scripts": {
     "graft": "node ./bin/graft.js",
     "build": "tsc -p tsconfig.build.json",
     "prepack": "pnpm build",
-    "test": "vitest run",
+    "test": "tsx scripts/run-isolated-tests.ts",
+    "test:local": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "pack:check": "pnpm pack --dry-run",
+    "guard:agent-worktrees": "tsx scripts/check-agent-worktree-hygiene.ts",
     "security:check": "tsx scripts/check-release-security.ts",
     "release:surface-gate": "vitest run --run test/unit/release/package-library-surface.test.ts test/unit/release/three-surface-capability-posture.test.ts",
-    "release:check": "pnpm lint && pnpm typecheck && pnpm release:surface-gate && pnpm test && pnpm security:check && pnpm pack:check"
+    "release:check": "pnpm guard:agent-worktrees && pnpm lint && pnpm typecheck && pnpm release:surface-gate && pnpm test && pnpm security:check && pnpm pack:check"
   },
   "engines": {
     "node": ">=20.11.0"

package/src/adapters/json-text-decoder.ts

@@ -0,0 +1,11 @@
+import { type JsonObject, parseJsonObject } from "../contracts/json-object.js";
+
+export function parseJsonTextObject(text: string, label: string): JsonObject {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`${label} was not valid JSON`);
+  }
+  return parseJsonObject(parsed, label);
+}

package/src/adapters/node-paths.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Node PathOps adapter — implements PathOps using node:path
+// ---------------------------------------------------------------------------
+
+import * as path from "node:path";
+import type { PathOps } from "../ports/paths.js";
+
+function toForwardSlash(p: string): string {
+  return p.replaceAll("\\", "/");
+}
+
+function stripTrailingSlash(p: string): string {
+  if (p === "/") return p;
+  return p.endsWith("/") ? p.slice(0, -1) : p;
+}
+
+function normalizeImpl(p: string): string {
+  return stripTrailingSlash(toForwardSlash(path.normalize(p)));
+}
+
+export const nodePathOps: PathOps = {
+  normalize(p: string): string {
+    return normalizeImpl(p);
+  },
+
+  isWithin(filePath: string, directory: string): boolean {
+    const normFile = normalizeImpl(filePath);
+    const normDir = normalizeImpl(directory);
+    return normFile === normDir || normFile.startsWith(`${normDir}/`);
+  },
+
+  join(...segments: string[]): string {
+    return normalizeImpl(path.join(...segments));
+  },
+};

package/src/adapters/repo-paths.ts

@@ -1,13 +1,54 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 
+function pathEscapesRoot(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
+function realPathOrSelf(target: string): string {
+  try {
+    return fs.realpathSync.native(target);
+  } catch {
+    return target;
+  }
+}
+
+function nearestExistingAncestor(target: string): string {
+  let current = target;
+  while (current.length > 0) {
+    try {
+      fs.lstatSync(current);
+      return current;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) {
+        return current;
+      }
+      current = parent;
+    }
+  }
+  return target;
+}
+
 export function createRepoPathResolver(projectRoot: string): (input: string) => string {
+  const normalizedRoot = path.resolve(projectRoot);
+  const realProjectRoot = realPathOrSelf(normalizedRoot);
+
   return (input: string): string => {
-    if (path.isAbsolute(input)) return input;
-    const resolved = path.resolve(projectRoot, input);
-    const relative = path.relative(projectRoot, resolved);
-    if (relative.startsWith("..")) {
+    const resolved = path.isAbsolute(input)
+      ? path.resolve(input)
+      : path.resolve(normalizedRoot, input);
+
+    if (pathEscapesRoot(normalizedRoot, resolved)) {
       throw new Error(`Path traversal blocked: ${input}`);
     }
+
+    const realAncestor = realPathOrSelf(nearestExistingAncestor(resolved));
+    if (pathEscapesRoot(realProjectRoot, realAncestor)) {
+      throw new Error(`Path traversal blocked: ${input}`);
+    }
+
     return resolved;
   };
 }

package/src/api/tool-bridge.ts

@@ -1,5 +1,6 @@
 import type { McpToolName } from "../contracts/capabilities.js";
-import { type JsonObject, parseJsonTextObject } from "../contracts/json-object.js";
+import type { JsonObject } from "../contracts/json-object.js";
+import { parseJsonTextObject } from "../adapters/json-text-decoder.js";
 import { getMcpOutputSchema, type McpOutputFor } from "../contracts/output-schemas.js";
 import type { GraftServer, McpToolResult } from "../mcp/server.js";
 

package/src/cli/cli-error.ts

@@ -39,29 +39,50 @@ export function describeCliFailure(argv: readonly string[]): CliErrorDetails {
 
   if (group === "serve") {
     return {
-      usage: "graft serve",
-      nextSteps: ["Run `graft help` to see the explicit transport entrypoints."],
+      usage: "graft serve [--runtime <repo-local|daemon>] [--socket <path>] [--no-autostart]",
+      nextSteps: [
+        "`graft serve` is repo-local stdio. Use `graft serve --runtime daemon` for the daemon-backed stdio bridge.",
+      ],
     };
   }
 
   if (group === "daemon") {
+    if (subcommand === "status") {
+      return {
+        usage: "graft daemon status [--socket <path>]",
+        nextSteps: ["Start the daemon with `graft daemon` or target another daemon with `--socket <path>`."],
+      };
+    }
     return {
-      usage: "graft daemon [--socket <path>]",
-      nextSteps: ["Run `graft help` to see the daemon and grouped command surfaces."],
+      usage: "graft daemon [--socket <path>] | graft daemon status [--socket <path>]",
+      nextSteps: ["Run `graft daemon status` to inspect an already-running daemon without mutating daemon state."],
     };
   }
 
+  if (group === "doctor") {
+    return { usage: "graft doctor [--sludge] [--path <path>] [--json]" };
+  }
+
   if (group === "index") {
     return {
-      usage: "graft index [<from-ref>] [--json]",
-      nextSteps: ["Use `--json` for machine-readable output."],
+      usage: "graft index [--path <path>] [--json]",
+      nextSteps: ["Use `--path <path>` for lazy per-file indexing and `--json` for machine-readable output."],
+    };
+  }
+
+  if (group === "enhance") {
+    return {
+      usage: "git-graft enhance --since <ref> [--head <ref>] [--json]",
+      nextSteps: [
+        "Use `git graft enhance --since <ref>` after package install, or `git-graft enhance --since <ref>` via the direct binary.",
+      ],
     };
   }
 
   if (group === "init") {
     return {
       usage:
-        "graft init [--json] [--write-claude-mcp] [--write-claude-hooks] "
+        "graft init [--json] [--mcp-runtime <repo-local|daemon>] [--write-claude-mcp] [--write-claude-hooks] "
         + "[--write-target-git-hooks] [--write-codex-mcp] [--write-cursor-mcp] "
         + "[--write-windsurf-mcp] [--write-continue-mcp] [--write-cline-mcp]",
       nextSteps: ["Run `graft help` to confirm the repo-local bootstrap surfaces."],
@@ -97,8 +118,20 @@ export function describeCliFailure(argv: readonly string[]): CliErrorDetails {
     if (subcommand === "map") {
       return { usage: "graft struct map [<directory>] [--json]" };
     }
+    if (subcommand === "churn") {
+      return { usage: "graft struct churn [--path <path>] [--limit <n>] [--json]" };
+    }
+    if (subcommand === "exports") {
+      return { usage: "graft struct exports [<base-ref> <head-ref>] [--json]" };
+    }
+    if (subcommand === "log") {
+      return { usage: "graft struct log [--path <path>] [--limit <n>] [--json]" };
+    }
+    if (subcommand === "review") {
+      return { usage: "graft struct review [--base <ref>] [--head <ref>] [--json]" };
+    }
     return {
-      usage: "graft struct <diff|since|map> ...",
+      usage: "graft struct <diff|since|map|churn|exports|log|review> ...",
       nextSteps: ["Run `graft help` to see the available structural subcommands."],
     };
   }
@@ -110,8 +143,14 @@ export function describeCliFailure(argv: readonly string[]): CliErrorDetails {
     if (subcommand === "show") {
       return { usage: "graft symbol show <symbol> [--path <path>] [--ref <ref>] [--json]" };
     }
+    if (subcommand === "blame") {
+      return { usage: "graft symbol blame <symbol> [--path <path>] [--json]" };
+    }
+    if (subcommand === "difficulty") {
+      return { usage: "graft symbol difficulty <symbol> [--path <path>] [--limit <n>] [--json]" };
+    }
     return {
-      usage: "graft symbol <find|show> ...",
+      usage: "graft symbol <find|show|blame|difficulty> ...",
       nextSteps: ["Run `graft help` to see the available symbol subcommands."],
     };
   }
@@ -130,7 +169,7 @@ export function describeCliFailure(argv: readonly string[]): CliErrorDetails {
       return { usage: "graft diag local-history-dag [--limit <n>] [--json]" };
     }
     if (subcommand === "doctor") {
-      return { usage: "graft diag doctor [--json]" };
+      return { usage: "graft diag doctor [--sludge] [--path <path>] [--json]" };
     }
     if (subcommand === "explain") {
       return { usage: "graft diag explain <reason-code> [--json]" };

package/src/cli/command-parser.ts

@@ -12,6 +12,19 @@ export interface ParsedCommand {
   args: Record<string, unknown>;
 }
 
+export type ServeRuntime = "repo-local" | "daemon";
+
+export interface ParsedServeCommand {
+  readonly runtime: ServeRuntime;
+  readonly socketPath?: string | undefined;
+  readonly spawnIfMissing?: boolean | undefined;
+}
+
+export interface ParsedDaemonCommand {
+  readonly action: "start" | "status";
+  readonly socketPath?: string | undefined;
+}
+
 export function resolveEntrypointArgs(
   args: readonly string[],
   stdinIsTTY: boolean | undefined,
@@ -65,10 +78,50 @@ function parsePositiveInt(raw: string | undefined, flag: string): number {
   return value;
 }
 
-export function parseDaemonCommand(cwd: string, argv: string[]): { socketPath?: string } {
+export function parseDaemonCommand(cwd: string, argv: string[]): ParsedDaemonCommand {
+  const action = argv[0] === "status" ? "status" : "start";
+  if (action === "status") {
+    argv.shift();
+  }
   const socketPath = consumeOption(argv, "--socket");
   expectNoArgs(argv);
-  return socketPath !== undefined ? { socketPath: path.resolve(cwd, socketPath) } : {};
+  return {
+    action,
+    ...(socketPath !== undefined ? { socketPath: path.resolve(cwd, socketPath) } : {}),
+  };
+}
+
+function parseServeRuntime(raw: string | undefined): ServeRuntime {
+  if (raw === undefined || raw === "repo-local") {
+    return "repo-local";
+  }
+  if (raw === "daemon") {
+    return "daemon";
+  }
+  throw new Error(`--runtime must be repo-local or daemon, got ${raw}`);
+}
+
+export function parseServeCommand(cwd: string, argv: string[]): ParsedServeCommand {
+  const runtime = parseServeRuntime(consumeOption(argv, "--runtime"));
+  const socketPath = consumeOption(argv, "--socket");
+  const noAutostart = consumeFlag(argv, "--no-autostart");
+  expectNoArgs(argv);
+
+  if (runtime === "repo-local") {
+    if (socketPath !== undefined) {
+      throw new Error("--socket requires --runtime daemon");
+    }
+    if (noAutostart) {
+      throw new Error("--no-autostart requires --runtime daemon");
+    }
+    return { runtime };
+  }
+
+  return {
+    runtime,
+    ...(socketPath !== undefined ? { socketPath: path.resolve(cwd, socketPath) } : {}),
+    ...(noAutostart ? { spawnIfMissing: false } : {}),
+  };
 }
 
 export function parseGlobalOptions(
@@ -161,6 +214,62 @@ function parseStructCommand(argv: string[]): ParsedCommand {
     };
   }
 
+  if (subcommand === "churn") {
+    const filePath = consumeOption(argv, "--path");
+    const limitRaw = consumeOption(argv, "--limit");
+    expectNoArgs(argv);
+    return {
+      command: "struct_churn",
+      json,
+      args: {
+        ...(filePath !== undefined ? { path: filePath } : {}),
+        ...(limitRaw !== undefined ? { limit: parsePositiveInt(limitRaw, "--limit") } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "exports") {
+    const base = argv[0]?.startsWith("--") === false ? consumePositional(argv, "base ref") : undefined;
+    const head = argv[0]?.startsWith("--") === false ? consumePositional(argv, "head ref") : undefined;
+    expectNoArgs(argv);
+    return {
+      command: "struct_exports",
+      json,
+      args: {
+        ...(base !== undefined ? { base } : {}),
+        ...(head !== undefined ? { head } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "log") {
+    const filePath = consumeOption(argv, "--path");
+    const limitRaw = consumeOption(argv, "--limit");
+    expectNoArgs(argv);
+    return {
+      command: "struct_log",
+      json,
+      args: {
+        ...(filePath !== undefined ? { path: filePath } : {}),
+        ...(limitRaw !== undefined ? { limit: parsePositiveInt(limitRaw, "--limit") } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "review") {
+    const base = consumeOption(argv, "--base");
+    const head = consumeOption(argv, "--head");
+    expectNoArgs(argv);
+    return {
+      command: "struct_review",
+      json,
+      args: {
+        ...(base !== undefined ? { base } : {}),
+        ...(head !== undefined ? { head } : {}),
+      },
+    };
+  }
+
   throw new Error(`Unknown struct subcommand: ${subcommand}`);
 }
 
@@ -200,6 +309,36 @@ function parseSymbolCommand(argv: string[]): ParsedCommand {
     };
   }
 
+  if (subcommand === "blame") {
+    const symbol = consumePositional(argv, "symbol");
+    const filePath = consumeOption(argv, "--path");
+    expectNoArgs(argv);
+    return {
+      command: "symbol_blame",
+      json,
+      args: {
+        symbol,
+        ...(filePath !== undefined ? { path: filePath } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "difficulty") {
+    const symbol = consumePositional(argv, "symbol");
+    const filePath = consumeOption(argv, "--path");
+    const limitRaw = consumeOption(argv, "--limit");
+    expectNoArgs(argv);
+    return {
+      command: "symbol_difficulty",
+      json,
+      args: {
+        symbol,
+        ...(filePath !== undefined ? { path: filePath } : {}),
+        ...(limitRaw !== undefined ? { limit: parsePositiveInt(limitRaw, "--limit") } : {}),
+      },
+    };
+  }
+
   throw new Error(`Unknown symbol subcommand: ${subcommand}`);
 }
 
@@ -224,8 +363,17 @@ function parseDiagCommand(argv: string[]): ParsedCommand {
   const json = consumeFlag(argv, "--json");
 
   if (subcommand === "doctor") {
+    const sludge = consumeFlag(argv, "--sludge");
+    const filePath = consumeOption(argv, "--path");
     expectNoArgs(argv);
-    return { command: "diag_doctor", json, args: {} };
+    return {
+      command: "diag_doctor",
+      json,
+      args: {
+        ...(sludge ? { sludge } : {}),
+        ...(filePath !== undefined ? { path: filePath } : {}),
+      },
+    };
   }
 
   if (subcommand === "activity") {
@@ -289,14 +437,48 @@ function parseDiagCommand(argv: string[]): ParsedCommand {
   throw new Error(`Unknown diag subcommand: ${subcommand}`);
 }
 
+function parseEnhanceCommand(argv: string[]): ParsedCommand {
+  const json = consumeFlag(argv, "--json");
+  const since = consumeOption(argv, "--since");
+  const head = consumeOption(argv, "--head");
+  if (since === undefined) {
+    expectNoArgs(argv);
+    throw new Error("Missing --since");
+  }
+  expectNoArgs(argv);
+  return {
+    command: "git_graft_enhance",
+    json,
+    args: {
+      since,
+      ...(head !== undefined ? { head } : {}),
+    },
+  };
+}
+
 export function parseCommand(argv: string[]): ParsedCommand {
   const group = consumePositional(argv, "command");
 
+  if (group === "doctor") {
+    const json = consumeFlag(argv, "--json");
+    const sludge = consumeFlag(argv, "--sludge");
+    const filePath = consumeOption(argv, "--path");
+    expectNoArgs(argv);
+    return {
+      command: "diag_doctor",
+      json,
+      args: {
+        ...(sludge ? { sludge } : {}),
+        ...(filePath !== undefined ? { path: filePath } : {}),
+      },
+    };
+  }
   if (group === "read") return parseReadCommand(argv);
   if (group === "struct") return parseStructCommand(argv);
   if (group === "symbol") return parseSymbolCommand(argv);
   if (group === "migrate") return parseMigrateCommand(argv);
   if (group === "diag") return parseDiagCommand(argv);
+  if (group === "enhance") return parseEnhanceCommand(argv);
 
   throw new Error(`Unknown command: ${group}`);
 }