@flyingrobots/graft 0.4.0 → 0.6.0

package/src/api/repo-workspace.ts

@@ -0,0 +1,34 @@
+import * as path from "node:path";
+import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
+import { nodeFs } from "../adapters/node-fs.js";
+import { createRepoPathResolver, toRepoPolicyPath } from "../adapters/repo-paths.js";
+import { ObservationCache } from "../operations/observation-cache.js";
+import { RepoWorkspace } from "../operations/repo-workspace.js";
+import { GovernorTracker } from "../session/tracker.js";
+import type { JsonCodec } from "../ports/codec.js";
+import type { FileSystem } from "../ports/filesystem.js";
+
+export interface CreateRepoWorkspaceOptions {
+  readonly cwd?: string | undefined;
+  readonly graftignorePatterns?: readonly string[] | undefined;
+  readonly fs?: FileSystem | undefined;
+  readonly codec?: JsonCodec | undefined;
+  readonly governor?: GovernorTracker | undefined;
+  readonly cache?: ObservationCache | undefined;
+}
+
+export async function createRepoWorkspace(options: CreateRepoWorkspaceOptions = {}): Promise<RepoWorkspace> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const fs = options.fs ?? nodeFs;
+  const codec = options.codec ?? new CanonicalJsonCodec();
+  return new RepoWorkspace({
+    projectRoot: cwd,
+    fs,
+    codec,
+    graftignorePatterns: options.graftignorePatterns ?? await RepoWorkspace.loadGraftignorePatterns(fs, cwd),
+    resolvePath: createRepoPathResolver(cwd),
+    toPolicyPath: (resolvedPath) => toRepoPolicyPath(cwd, resolvedPath),
+    ...(options.governor !== undefined ? { governor: options.governor } : {}),
+    ...(options.cache !== undefined ? { cache: options.cache } : {}),
+  });
+}

package/src/api/tool-bridge.ts

@@ -0,0 +1,21 @@
+import type { McpToolName } from "../contracts/capabilities.js";
+import { type JsonObject, parseJsonTextObject } from "../contracts/json-object.js";
+import { getMcpOutputSchema, type McpOutputFor } from "../contracts/output-schemas.js";
+import type { GraftServer, McpToolResult } from "../mcp/server.js";
+
+export function parseGraftToolPayload(result: McpToolResult): JsonObject {
+  const payload = result.content.find((item) => item.type === "text");
+  if (payload === undefined) {
+    throw new Error("Graft tool result did not contain a text payload");
+  }
+  return parseJsonTextObject(payload.text, "Graft tool result");
+}
+
+export async function callGraftTool<K extends McpToolName>(
+  graft: GraftServer,
+  name: K,
+  args: JsonObject,
+): Promise<McpOutputFor<K>> {
+  const parsed = parseGraftToolPayload(await graft.callTool(name, args));
+  return getMcpOutputSchema(name).parse(parsed) as McpOutputFor<K>;
+}

package/src/cli/activity-render.ts

@@ -0,0 +1,112 @@
+import { type z } from "zod";
+import { DIAG_ACTIVITY_CLI_SCHEMA } from "../contracts/output-schemas.js";
+
+type DiagActivityOutput = z.infer<typeof DIAG_ACTIVITY_CLI_SCHEMA>;
+type ActivityGroup = DiagActivityOutput["activityWindow"]["groups"][number];
+type ActivityItem = ActivityGroup["items"][number];
+type AttributionSummary = ActivityItem["attribution"];
+type ContinuityActivityItem = Extract<ActivityItem, { itemKind: "continuity" }>;
+type ReadActivityItem = Extract<ActivityItem, { eventKind: "read" }>;
+type StageActivityItem = Extract<ActivityItem, { eventKind: "stage" }>;
+type TransitionActivityItem = Extract<ActivityItem, { eventKind: "transition" }>;
+
+function trimId(value: string | null | undefined): string {
+  if (value === null || value === undefined || value.length === 0) {
+    return "unknown";
+  }
+  const parts = value.split(":");
+  return parts.at(-1) ?? value;
+}
+
+function shortSha(value: string | null): string {
+  return value === null ? "unknown" : value.slice(0, 7);
+}
+
+function actorLabel(attribution: AttributionSummary): string {
+  const actorId = trimId(attribution.actor.actorId);
+  const actorKind = attribution.actor.actorKind;
+  return actorKind === "unknown" ? `actor:${actorId}` : `${actorKind}:${actorId}`;
+}
+
+function summarizePaths(paths: readonly string[]): string {
+  if (paths.length === 0) {
+    return "no paths";
+  }
+  if (paths.length === 1) {
+    return paths[0] ?? "no paths";
+  }
+  if (paths.length === 2) {
+    return `${paths[0] ?? ""}, ${paths[1] ?? ""}`;
+  }
+  return `${paths[0] ?? ""}, ${paths[1] ?? ""} +${String(paths.length - 2)} more`;
+}
+
+function formatContinuityItem(item: ContinuityActivityItem): string {
+  const origin = item.continuedFromCausalSessionId === null
+    ? ""
+    : ` from session:${trimId(item.continuedFromCausalSessionId)}`;
+  return `${item.occurredAt}  continuity:${item.operation}  ${actorLabel(item.attribution)}  session:${trimId(item.causalSessionId)}  strand:${trimId(item.strandId)}${origin}`;
+}
+
+function formatReadItem(item: ReadActivityItem): string {
+  return `${item.occurredAt}  read:${item.payload.surface}/${item.payload.projection}  ${actorLabel(item.attribution)}  ${summarizePaths(item.footprint.paths)}`;
+}
+
+function formatStageItem(item: StageActivityItem): string {
+  return `${item.occurredAt}  stage:${item.payload.selectionKind}  ${actorLabel(item.attribution)}  ${summarizePaths(item.footprint.paths)}`;
+}
+
+function formatTransitionItem(item: TransitionActivityItem): string {
+  return `${item.occurredAt}  transition  ${actorLabel(item.attribution)}  ${item.payload.summary}`;
+}
+
+function formatActivityItem(item: ActivityItem): string {
+  if ("itemKind" in item) {
+    return formatContinuityItem(item);
+  }
+  if (item.eventKind === "read") {
+    return formatReadItem(item);
+  }
+  if (item.eventKind === "stage") {
+    return formatStageItem(item);
+  }
+  return formatTransitionItem(item);
+}
+
+export function renderActivityView(output: unknown): string {
+  const parsed = DIAG_ACTIVITY_CLI_SCHEMA.parse(output);
+  const lines = [
+    "Activity",
+    `repo: ${parsed.repoId ?? "unknown"}`,
+    `worktree: ${parsed.worktreeId ?? "unknown"}`,
+    `anchor: ${parsed.anchor.headRef ?? parsed.anchor.posture} @ ${shortSha(parsed.anchor.headSha)}`,
+    `truth: ${parsed.truthClass}`,
+    `next: ${parsed.nextAction}`,
+    `degraded: ${parsed.degradedReasons.length === 0 ? "none" : parsed.degradedReasons.join(", ")}`,
+    "",
+    parsed.summary.headline,
+    parsed.summary.anchor,
+    parsed.summary.workspace,
+  ];
+
+  if (parsed.activityWindow.returned === 0) {
+    lines.push("", "No activity items found in the requested window.");
+    return lines.join("\n");
+  }
+
+  lines.push("");
+  lines.push(`window: ${String(parsed.activityWindow.returned)} shown / ${String(parsed.activityWindow.totalMatchingItems)} matching${parsed.activityWindow.truncated ? " (truncated)" : ""}`);
+  lines.push("");
+  lines.push("Groups");
+
+  for (const group of parsed.activityWindow.groups) {
+    lines.push("");
+    lines.push(`${group.label} (${String(group.items.length)})`);
+    lines.push(group.summary);
+    for (const item of group.items) {
+      lines.push(`  ${formatActivityItem(item)}`);
+    }
+  }
+
+  return lines.join("\n").trimEnd();
+}

package/src/cli/cli-error.ts

@@ -0,0 +1,153 @@
+import { writeLine, type Writer } from "./peer-command.js";
+
+const CLI_DOCS_PATH = "docs/CLI.md";
+
+interface CliErrorDetails {
+  readonly usage?: string | undefined;
+  readonly nextSteps?: readonly string[] | undefined;
+  readonly docsPath?: string | undefined;
+}
+
+export function writeCliError(
+  writer: Writer,
+  message: string,
+  details: CliErrorDetails = {},
+): void {
+  writeLine(writer, `Error: ${message}`);
+  if (details.usage !== undefined) {
+    writeLine(writer);
+    writeLine(writer, `Usage: ${details.usage}`);
+  }
+  const nextSteps = details.nextSteps ?? [];
+  if (nextSteps.length > 0) {
+    writeLine(writer);
+    for (const step of nextSteps) {
+      writeLine(writer, step);
+    }
+  }
+  writeLine(writer);
+  writeLine(writer, `See ${details.docsPath ?? CLI_DOCS_PATH} for grouped command help.`);
+}
+
+export function describeCliFailure(argv: readonly string[]): CliErrorDetails {
+  const [group, subcommand] = argv;
+  if (group === undefined) {
+    return {
+      nextSteps: ["Run `graft help` to see the available command groups."],
+    };
+  }
+
+  if (group === "serve") {
+    return {
+      usage: "graft serve",
+      nextSteps: ["Run `graft help` to see the explicit transport entrypoints."],
+    };
+  }
+
+  if (group === "daemon") {
+    return {
+      usage: "graft daemon [--socket <path>]",
+      nextSteps: ["Run `graft help` to see the daemon and grouped command surfaces."],
+    };
+  }
+
+  if (group === "index") {
+    return {
+      usage: "graft index [<from-ref>] [--json]",
+      nextSteps: ["Use `--json` for machine-readable output."],
+    };
+  }
+
+  if (group === "init") {
+    return {
+      usage:
+        "graft init [--json] [--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."],
+    };
+  }
+
+  if (group === "read") {
+    if (subcommand === "safe") {
+      return { usage: "graft read safe <path> [--json]" };
+    }
+    if (subcommand === "outline") {
+      return { usage: "graft read outline <path> [--json]" };
+    }
+    if (subcommand === "range") {
+      return { usage: "graft read range <path> --start <n> --end <n> [--json]" };
+    }
+    if (subcommand === "changed") {
+      return { usage: "graft read changed <path> [--consume] [--json]" };
+    }
+    return {
+      usage: "graft read <safe|outline|range|changed> ...",
+      nextSteps: ["Run `graft help` to see the available read subcommands."],
+    };
+  }
+
+  if (group === "struct") {
+    if (subcommand === "diff") {
+      return { usage: "graft struct diff [--base <ref>] [--head <ref>] [--path <path>] [--json]" };
+    }
+    if (subcommand === "since") {
+      return { usage: "graft struct since <base-ref> [--head <ref>] [--json]" };
+    }
+    if (subcommand === "map") {
+      return { usage: "graft struct map [<directory>] [--json]" };
+    }
+    return {
+      usage: "graft struct <diff|since|map> ...",
+      nextSteps: ["Run `graft help` to see the available structural subcommands."],
+    };
+  }
+
+  if (group === "symbol") {
+    if (subcommand === "find") {
+      return { usage: "graft symbol find <query> [--kind <kind>] [--path <path>] [--json]" };
+    }
+    if (subcommand === "show") {
+      return { usage: "graft symbol show <symbol> [--path <path>] [--ref <ref>] [--json]" };
+    }
+    return {
+      usage: "graft symbol <find|show> ...",
+      nextSteps: ["Run `graft help` to see the available symbol subcommands."],
+    };
+  }
+
+  if (group === "migrate") {
+    return {
+      usage: "graft migrate local-history [--json]",
+    };
+  }
+
+  if (group === "diag") {
+    if (subcommand === "activity") {
+      return { usage: "graft diag activity [--limit <n>] [--json]" };
+    }
+    if (subcommand === "local-history-dag") {
+      return { usage: "graft diag local-history-dag [--limit <n>] [--json]" };
+    }
+    if (subcommand === "doctor") {
+      return { usage: "graft diag doctor [--json]" };
+    }
+    if (subcommand === "explain") {
+      return { usage: "graft diag explain <reason-code> [--json]" };
+    }
+    if (subcommand === "stats") {
+      return { usage: "graft diag stats [--json]" };
+    }
+    if (subcommand === "capture") {
+      return { usage: "graft diag capture [--tail <n>] -- <shell command> [--json]" };
+    }
+    return {
+      usage: "graft diag <activity|local-history-dag|doctor|explain|stats|capture> ...",
+      nextSteps: ["Run `graft help` to see the available diagnostic subcommands."],
+    };
+  }
+
+  return {
+    nextSteps: ["Run `graft help` to see the available command groups."],
+  };
+}

package/src/cli/command-parser.ts

@@ -0,0 +1,302 @@
+import * as path from "node:path";
+import type { CliCommandName } from "../contracts/capabilities.js";
+
+export interface GlobalCliOptions {
+  cwd: string;
+  argv: string[];
+}
+
+export interface ParsedCommand {
+  command: CliCommandName;
+  json: boolean;
+  args: Record<string, unknown>;
+}
+
+export function resolveEntrypointArgs(
+  args: readonly string[],
+  stdinIsTTY: boolean | undefined,
+  stdoutIsTTY: boolean | undefined,
+): string[] {
+  if (args.length === 0 && stdinIsTTY !== true && stdoutIsTTY !== true) {
+    return ["serve"];
+  }
+  return [...args];
+}
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const index = args.indexOf(flag);
+  if (index === -1) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+function consumeOption(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  if (index === args.length - 1) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  const [value] = args.splice(index, 2).slice(1);
+  return value;
+}
+
+function consumePositional(args: string[], label: string): string {
+  const value = args.shift();
+  if (value === undefined) {
+    throw new Error(`Missing ${label}`);
+  }
+  return value;
+}
+
+function expectNoArgs(args: string[]): void {
+  if (args.length > 0) {
+    throw new Error(`Unexpected arguments: ${args.join(" ")}`);
+  }
+}
+
+function parsePositiveInt(raw: string | undefined, flag: string): number {
+  if (raw === undefined) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return value;
+}
+
+export function parseDaemonCommand(cwd: string, argv: string[]): { socketPath?: string } {
+  const socketPath = consumeOption(argv, "--socket");
+  expectNoArgs(argv);
+  return socketPath !== undefined ? { socketPath: path.resolve(cwd, socketPath) } : {};
+}
+
+export function parseGlobalOptions(
+  cwd: string,
+  args: readonly string[],
+): GlobalCliOptions {
+  const rest = [...args];
+  const override = consumeOption(rest, "--cwd");
+  return {
+    cwd: override !== undefined ? path.resolve(cwd, override) : cwd,
+    argv: rest,
+  };
+}
+
+function parseReadCommand(argv: string[]): ParsedCommand {
+  const subcommand = consumePositional(argv, "read subcommand");
+  const json = consumeFlag(argv, "--json");
+
+  if (subcommand === "safe") {
+    const filePath = consumePositional(argv, "path");
+    expectNoArgs(argv);
+    return { command: "read_safe", json, args: { path: filePath } };
+  }
+
+  if (subcommand === "outline") {
+    const filePath = consumePositional(argv, "path");
+    expectNoArgs(argv);
+    return { command: "read_outline", json, args: { path: filePath } };
+  }
+
+  if (subcommand === "range") {
+    const filePath = consumePositional(argv, "path");
+    const start = parsePositiveInt(consumeOption(argv, "--start"), "--start");
+    const end = parsePositiveInt(consumeOption(argv, "--end"), "--end");
+    expectNoArgs(argv);
+    return { command: "read_range", json, args: { path: filePath, start, end } };
+  }
+
+  if (subcommand === "changed") {
+    const filePath = consumePositional(argv, "path");
+    const consume = consumeFlag(argv, "--consume");
+    expectNoArgs(argv);
+    return { command: "read_changed", json, args: { path: filePath, consume } };
+  }
+
+  throw new Error(`Unknown read subcommand: ${subcommand}`);
+}
+
+function parseStructCommand(argv: string[]): ParsedCommand {
+  const subcommand = consumePositional(argv, "struct subcommand");
+  const json = consumeFlag(argv, "--json");
+
+  if (subcommand === "diff") {
+    const base = consumeOption(argv, "--base");
+    const head = consumeOption(argv, "--head");
+    const filePath = consumeOption(argv, "--path");
+    expectNoArgs(argv);
+    return {
+      command: "struct_diff",
+      json,
+      args: {
+        ...(base !== undefined ? { base } : {}),
+        ...(head !== undefined ? { head } : {}),
+        ...(filePath !== undefined ? { path: filePath } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "since") {
+    const base = consumePositional(argv, "base ref");
+    const head = consumeOption(argv, "--head");
+    expectNoArgs(argv);
+    return {
+      command: "struct_since",
+      json,
+      args: {
+        base,
+        ...(head !== undefined ? { head } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "map") {
+    const directory = argv[0]?.startsWith("--") === false ? consumePositional(argv, "directory") : undefined;
+    expectNoArgs(argv);
+    return {
+      command: "struct_map",
+      json,
+      args: directory !== undefined ? { path: directory } : {},
+    };
+  }
+
+  throw new Error(`Unknown struct subcommand: ${subcommand}`);
+}
+
+function parseSymbolCommand(argv: string[]): ParsedCommand {
+  const subcommand = consumePositional(argv, "symbol subcommand");
+  const json = consumeFlag(argv, "--json");
+
+  if (subcommand === "show") {
+    const symbol = consumePositional(argv, "symbol");
+    const filePath = consumeOption(argv, "--path");
+    const ref = consumeOption(argv, "--ref");
+    expectNoArgs(argv);
+    return {
+      command: "symbol_show",
+      json,
+      args: {
+        symbol,
+        ...(filePath !== undefined ? { path: filePath } : {}),
+        ...(ref !== undefined ? { ref } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "find") {
+    const query = consumePositional(argv, "query");
+    const kind = consumeOption(argv, "--kind");
+    const filePath = consumeOption(argv, "--path");
+    expectNoArgs(argv);
+    return {
+      command: "symbol_find",
+      json,
+      args: {
+        query,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(filePath !== undefined ? { path: filePath } : {}),
+      },
+    };
+  }
+
+  throw new Error(`Unknown symbol subcommand: ${subcommand}`);
+}
+
+function parseMigrateCommand(argv: string[]): ParsedCommand {
+  const subcommand = consumePositional(argv, "migrate subcommand");
+  const json = consumeFlag(argv, "--json");
+
+  if (subcommand === "local-history") {
+    expectNoArgs(argv);
+    return {
+      command: "migrate_local_history",
+      json,
+      args: {},
+    };
+  }
+
+  throw new Error(`Unknown migrate subcommand: ${subcommand}`);
+}
+
+function parseDiagCommand(argv: string[]): ParsedCommand {
+  const subcommand = consumePositional(argv, "diag subcommand");
+  const json = consumeFlag(argv, "--json");
+
+  if (subcommand === "doctor") {
+    expectNoArgs(argv);
+    return { command: "diag_doctor", json, args: {} };
+  }
+
+  if (subcommand === "activity") {
+    const limit = consumeOption(argv, "--limit");
+    expectNoArgs(argv);
+    return {
+      command: "diag_activity",
+      json,
+      args: {
+        ...(limit !== undefined ? { limit: parsePositiveInt(limit, "--limit") } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "local-history-dag") {
+    const limit = consumeOption(argv, "--limit");
+    expectNoArgs(argv);
+    return {
+      command: "diag_local_history_dag",
+      json,
+      args: {
+        ...(limit !== undefined ? { limit: parsePositiveInt(limit, "--limit") } : {}),
+      },
+    };
+  }
+
+  if (subcommand === "explain") {
+    const code = consumePositional(argv, "reason code");
+    expectNoArgs(argv);
+    return { command: "diag_explain", json, args: { code } };
+  }
+
+  if (subcommand === "stats") {
+    expectNoArgs(argv);
+    return { command: "diag_stats", json, args: {} };
+  }
+
+  if (subcommand === "capture") {
+    const tail = consumeOption(argv, "--tail");
+    const separator = argv.indexOf("--");
+    const commandTokens = separator === -1 ? [...argv] : argv.slice(separator + 1);
+    if (separator !== -1) {
+      argv.splice(separator);
+    } else {
+      argv.length = 0;
+    }
+    expectNoArgs(argv);
+    if (commandTokens.length === 0) {
+      throw new Error("Missing shell command");
+    }
+    return {
+      command: "diag_capture",
+      json,
+      args: {
+        command: commandTokens.join(" "),
+        ...(tail !== undefined ? { tail: parsePositiveInt(tail, "--tail") } : {}),
+      },
+    };
+  }
+
+  throw new Error(`Unknown diag subcommand: ${subcommand}`);
+}
+
+export function parseCommand(argv: string[]): ParsedCommand {
+  const group = consumePositional(argv, "command");
+
+  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);
+
+  throw new Error(`Unknown command: ${group}`);
+}

package/src/cli/entrypoint.ts

@@ -0,0 +1,18 @@
+import { resolveEntrypointArgs } from "./command-parser.js";
+import { runCli } from "./main.js";
+
+export interface CliEntrypointOptions {
+  readonly argv?: readonly string[] | undefined;
+  readonly stdinIsTTY?: boolean | undefined;
+  readonly stdoutIsTTY?: boolean | undefined;
+}
+
+export async function runCliEntrypoint(options: CliEntrypointOptions = {}): Promise<void> {
+  await runCli({
+    args: resolveEntrypointArgs(
+      options.argv ?? process.argv.slice(2),
+      options.stdinIsTTY ?? process.stdin.isTTY,
+      options.stdoutIsTTY ?? process.stdout.isTTY,
+    ),
+  });
+}