@flyingrobots/graft 0.4.0 → 0.6.0

package/src/cli/init-model.ts

@@ -0,0 +1,229 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArrayValue = JsonValue[];
+export type JsonValue = JsonPrimitive | JsonArrayValue | JsonObjectValue;
+
+export interface JsonObjectValue {
+  [key: string]: JsonValue | undefined;
+}
+
+type InitActionKind = "exists" | "create" | "append";
+
+export class InitAction {
+  constructor(
+    readonly action: InitActionKind,
+    readonly label: string,
+    readonly detail?: string,
+  ) {}
+
+  static create(label: string, detail?: string): InitAction {
+    return new InitAction("create", label, detail);
+  }
+
+  static append(label: string, detail?: string): InitAction {
+    return new InitAction("append", label, detail);
+  }
+
+  static exists(label: string, detail?: string): InitAction {
+    return new InitAction("exists", label, detail);
+  }
+}
+
+export class InitFailure {
+  readonly ok = false;
+
+  constructor(
+    readonly cwd: string,
+    readonly error: string,
+  ) {}
+
+  toJSON(): JsonObjectValue {
+    return {
+      ok: this.ok,
+      cwd: this.cwd,
+      error: this.error,
+    };
+  }
+}
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const index = args.indexOf(flag);
+  if (index === -1) {
+    return false;
+  }
+  args.splice(index, 1);
+  return true;
+}
+
+export class ParsedInitArgs {
+  constructor(
+    readonly json: boolean,
+    readonly writeClaudeMcp: boolean,
+    readonly writeClaudeHooks: boolean,
+    readonly writeTargetGitHooks: boolean,
+    readonly writeCodexMcp: boolean,
+    readonly writeCursorMcp: boolean,
+    readonly writeWindsurfMcp: boolean,
+    readonly writeContinueMcp: boolean,
+    readonly writeClineMcp: boolean,
+  ) {}
+
+  static parse(rawArgs: readonly string[]): ParsedInitArgs {
+    const args = [...rawArgs];
+    const parsed = new ParsedInitArgs(
+      consumeFlag(args, "--json"),
+      consumeFlag(args, "--write-claude-mcp"),
+      consumeFlag(args, "--write-claude-hooks"),
+      consumeFlag(args, "--write-target-git-hooks"),
+      consumeFlag(args, "--write-codex-mcp"),
+      consumeFlag(args, "--write-cursor-mcp"),
+      consumeFlag(args, "--write-windsurf-mcp"),
+      consumeFlag(args, "--write-continue-mcp"),
+      consumeFlag(args, "--write-cline-mcp"),
+    );
+
+    if (args.length > 0) {
+      throw new Error(`Unknown init arguments: ${args.join(" ")}`);
+    }
+
+    return parsed;
+  }
+
+  get writesAnyMcpConfig(): boolean {
+    return this.writeClaudeMcp
+      || this.writeCodexMcp
+      || this.writeCursorMcp
+      || this.writeWindsurfMcp
+      || this.writeContinueMcp
+      || this.writeClineMcp;
+  }
+}
+
+export class GraftMcpServer {
+  readonly name = "graft";
+  readonly command = "npx";
+  readonly args = ["-y", "@flyingrobots/graft", "serve"] as const;
+  readonly codexStartupTimeoutSec = 120;
+
+  toJsonServerEntry(): JsonObjectValue {
+    return {
+      command: this.command,
+      args: [...this.args],
+    };
+  }
+
+  toJsonMcpConfig(): JsonObjectValue {
+    return {
+      mcpServers: {
+        [this.name]: this.toJsonServerEntry(),
+      },
+    };
+  }
+
+  toContinueServerEntry(): JsonObjectValue {
+    return {
+      name: this.name,
+      command: this.command,
+      args: [...this.args],
+    };
+  }
+
+  toContinueConfig(): JsonObjectValue {
+    return {
+      mcpServers: [this.toContinueServerEntry()],
+    };
+  }
+
+  toCodexTomlBlock(): string {
+    return [
+      "[mcp_servers.graft]",
+      "command = \"npx\"",
+      "args = [\"-y\", \"@flyingrobots/graft\", \"serve\"]",
+      `startup_timeout_sec = ${String(this.codexStartupTimeoutSec)}`,
+      "",
+    ].join("\n");
+  }
+}
+
+export class GraftHookCommand {
+  constructor(readonly command: string) {}
+
+  toJsonValue(): JsonObjectValue {
+    return {
+      type: "command",
+      command: this.command,
+    };
+  }
+}
+
+export class GraftHookMatcher {
+  constructor(
+    readonly matcher: "Read",
+    readonly hooks: readonly GraftHookCommand[],
+  ) {}
+
+  toJsonValue(): JsonObjectValue {
+    return {
+      matcher: this.matcher,
+      hooks: this.hooks.map((hook) => hook.toJsonValue()),
+    };
+  }
+}
+
+export class GraftHooksConfig {
+  constructor(
+    readonly preToolUse: GraftHookMatcher,
+    readonly postToolUse: GraftHookMatcher,
+  ) {}
+
+  toJsonValue(): JsonObjectValue {
+    return {
+      hooks: {
+        PreToolUse: [this.preToolUse.toJsonValue()],
+        PostToolUse: [this.postToolUse.toJsonValue()],
+      },
+    };
+  }
+}
+
+export const GRAFT_MCP_SERVER = new GraftMcpServer();
+export const GRAFT_HOOKS_CONFIG = new GraftHooksConfig(
+  new GraftHookMatcher("Read", [
+    new GraftHookCommand("node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"),
+  ]),
+  new GraftHookMatcher("Read", [
+    new GraftHookCommand("node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"),
+  ]),
+);
+
+export class InitResult {
+  readonly ok = true;
+
+  constructor(
+    readonly cwd: string,
+    readonly actions: readonly InitAction[],
+    readonly hooksConfig: GraftHooksConfig,
+    readonly suggestedMcpServer: GraftMcpServer,
+  ) {}
+
+  toJSON(): JsonObjectValue {
+    return {
+      ok: this.ok,
+      cwd: this.cwd,
+      actions: this.actions.map((action) => ({
+        action: action.action,
+        label: action.label,
+        ...(action.detail !== undefined ? { detail: action.detail } : {}),
+      })),
+      hooksConfig: this.hooksConfig.toJsonValue(),
+      suggestedMcpServer: this.suggestedMcpServer.toJsonMcpConfig(),
+    };
+  }
+}
+
+export function isJsonObjectValue(value: unknown): value is JsonObjectValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function cloneJsonValue<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/cli/init-render.ts

@@ -0,0 +1,54 @@
+import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
+import { attachCliSchemaMeta, validateCliOutput } from "../contracts/output-schemas.js";
+import { GRAFT_HOOKS_CONFIG, GRAFT_MCP_SERVER, InitFailure, InitResult, ParsedInitArgs, type JsonObjectValue } from "./init-model.js";
+
+const codec = new CanonicalJsonCodec();
+
+interface Writer {
+  write(chunk: string): unknown;
+}
+
+function writeLine(writer: Writer, line = ""): void {
+  writer.write(`${line}\n`);
+}
+
+function indentJson(value: unknown, spaces = 2): string {
+  const json = JSON.stringify(value, null, spaces);
+  return json.split("\n").map((line) => `  ${line}`).join("\n");
+}
+
+export function renderInitText(result: InitResult, args: ParsedInitArgs, writer: Writer): void {
+  writeLine(writer);
+  writeLine(writer, `Initializing graft in ${result.cwd}`);
+  writeLine(writer);
+  for (const action of result.actions) {
+    const detail = action.detail !== undefined ? ` (${action.detail})` : "";
+    writeLine(writer, `  ${action.action.padEnd(6)} ${action.label}${detail}`);
+  }
+  writeLine(writer);
+
+  if (!args.writeClaudeHooks) {
+    writeLine(writer, "Add to .claude/settings.json for Claude Code hook integration:");
+    writeLine(writer);
+    writeLine(writer, JSON.stringify(GRAFT_HOOKS_CONFIG.toJsonValue(), null, 2));
+    writeLine(writer);
+  }
+
+  if (!args.writesAnyMcpConfig) {
+    writeLine(writer, "Done. Add graft to your MCP config:");
+    writeLine(writer);
+    writeLine(writer, indentJson(GRAFT_MCP_SERVER.toJsonMcpConfig()));
+    writeLine(writer);
+    writeLine(writer, "Use explicit --write-*-mcp flags or --write-claude-hooks");
+    writeLine(writer, "or --write-target-git-hooks for one-step bootstrap into project-local config files.");
+  }
+
+  writeLine(writer);
+}
+
+export function emitInitJson(result: JsonObjectValue | InitFailure, writer: Writer): void {
+  const payload = result instanceof InitFailure
+    ? result.toJSON()
+    : result;
+  writer.write(`${codec.encode(validateCliOutput("init", attachCliSchemaMeta("init", payload)))}\n`);
+}

package/src/cli/init-target-hooks.ts

@@ -0,0 +1,93 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  buildTargetGitHookScript,
+  isRecognizedTargetGitHook,
+  resolveGitHooksPath,
+  TARGET_GIT_TRANSITION_HOOKS,
+} from "../git/target-git-hook-bootstrap.js";
+import { InitAction } from "./init-model.js";
+
+function readGitValue(cwd: string, args: readonly string[]): string | null {
+  try {
+    const value = execFileSync("git", [...args], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function relativeLabel(cwd: string, filePath: string): string {
+  const relative = path.relative(cwd, filePath);
+  if (relative.length === 0 || relative.startsWith("..")) {
+    return filePath;
+  }
+  return relative;
+}
+
+function resolveTargetGitHooksDirectory(cwd: string): {
+  configuredCoreHooksPath: string | null;
+  resolvedHooksPath: string;
+} {
+  const worktreeRoot = readGitValue(cwd, [
+    "rev-parse",
+    "--path-format=absolute",
+    "--show-toplevel",
+  ]);
+  const gitCommonDir = readGitValue(cwd, [
+    "rev-parse",
+    "--path-format=absolute",
+    "--git-common-dir",
+  ]);
+  if (worktreeRoot === null || gitCommonDir === null) {
+    throw new Error("--write-target-git-hooks requires a git worktree");
+  }
+
+  const configuredCoreHooksPath = readGitValue(cwd, ["config", "--get", "core.hooksPath"]);
+  return {
+    configuredCoreHooksPath,
+    resolvedHooksPath: resolveGitHooksPath(
+      worktreeRoot,
+      gitCommonDir,
+      configuredCoreHooksPath,
+    ),
+  };
+}
+
+export function ensureTargetGitHooks(cwd: string): InitAction[] {
+  const { resolvedHooksPath } = resolveTargetGitHooksDirectory(cwd);
+  const actions: InitAction[] = [];
+  fs.mkdirSync(resolvedHooksPath, { recursive: true });
+
+  for (const hookName of TARGET_GIT_TRANSITION_HOOKS) {
+    const hookPath = path.join(resolvedHooksPath, hookName);
+    const label = relativeLabel(cwd, hookPath);
+    const nextContent = buildTargetGitHookScript(hookName);
+    if (!fs.existsSync(hookPath)) {
+      fs.writeFileSync(hookPath, nextContent);
+      fs.chmodSync(hookPath, 0o755);
+      actions.push(InitAction.create(label, "wrote graft target git hook"));
+      continue;
+    }
+
+    const existing = fs.readFileSync(hookPath, "utf-8");
+    if (existing === nextContent) {
+      actions.push(InitAction.exists(label, "already has graft target git hook"));
+      continue;
+    }
+    if (isRecognizedTargetGitHook(existing, hookName)) {
+      fs.writeFileSync(hookPath, nextContent);
+      fs.chmodSync(hookPath, 0o755);
+      actions.push(InitAction.append(label, "updated graft target git hook"));
+      continue;
+    }
+    actions.push(InitAction.exists(label, "external hook preserved"));
+  }
+
+  return actions;
+}

package/src/cli/init.ts

@@ -1,5 +1,8 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
+import { appendIfMissing, ensureTargetGitHooks, mergeClaudeHooksConfig, mergeClaudeMcpConfig, mergeClineMcpConfig, mergeCodexMcpConfig, mergeContinueMcpConfig, mergeCursorMcpConfig, mergeWindsurfMcpConfig, writeIfMissing } from "./init-bootstrap.js";
+import { writeCliError } from "./cli-error.js";
+import { GRAFT_HOOKS_CONFIG, GRAFT_MCP_SERVER, InitFailure, InitResult, ParsedInitArgs } from "./init-model.js";
+import { emitInitJson, renderInitText } from "./init-render.js";
 
 const GRAFTIGNORE_TEMPLATE = `# Graft ignore patterns — files matching these are refused by safe_read.
 # Syntax: same as .gitignore (glob matching via picomatch).
@@ -10,6 +13,8 @@ const GRAFTIGNORE_TEMPLATE = `# Graft ignore patterns — files matching these a
 # data/**/*.json
 `;
 
+const READ_GUIDANCE_MARKER = "## File reads";
+
 const AGENT_SNIPPET = `## File reads
 
 This project uses [graft](https://github.com/flyingrobots/graft) as
@@ -28,85 +33,90 @@ session metrics. Native reads bypass all of that.
 
 const GITIGNORE_ENTRY = "\n# Graft runtime data\n.graft/\n";
 
-const HOOKS_CONFIG = `
-Add to .claude/settings.json for Claude Code hook integration:
+interface Writer {
+  write(chunk: string): unknown;
+}
 
-{
-  "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"
-          }
-        ]
-      }
-    ]
-  }
+export interface RunInitOptions {
+  cwd?: string | undefined;
+  args?: readonly string[] | undefined;
+  stdout?: Writer | undefined;
+  stderr?: Writer | undefined;
 }
-`;
 
-function writeIfMissing(filePath: string, content: string, label: string): void {
-  if (fs.existsSync(filePath)) {
-    console.log(`  exists  ${label}`);
-  } else {
-    fs.writeFileSync(filePath, content);
-    console.log(`  create  ${label}`);
+function initProject(cwd: string, args: ParsedInitArgs): InitResult {
+  const actions = [
+    writeIfMissing(path.join(cwd, ".graftignore"), GRAFTIGNORE_TEMPLATE, ".graftignore"),
+    appendIfMissing(path.join(cwd, ".gitignore"), ".graft/", GITIGNORE_ENTRY, ".gitignore"),
+    appendIfMissing(path.join(cwd, "CLAUDE.md"), READ_GUIDANCE_MARKER, `\n${AGENT_SNIPPET}`, "CLAUDE.md"),
+  ];
+
+  if (args.writeClaudeMcp) {
+    actions.push(mergeClaudeMcpConfig(cwd));
+  }
+  if (args.writeClaudeHooks) {
+    actions.push(mergeClaudeHooksConfig(cwd));
+  }
+  if (args.writeTargetGitHooks) {
+    actions.push(...ensureTargetGitHooks(cwd));
+  }
+  if (args.writeCodexMcp) {
+    actions.push(mergeCodexMcpConfig(cwd));
+    actions.push(
+      appendIfMissing(
+        path.join(cwd, "AGENTS.md"),
+        READ_GUIDANCE_MARKER,
+        `\n${AGENT_SNIPPET}`,
+        "AGENTS.md",
+      ),
+    );
+  }
+  if (args.writeCursorMcp) {
+    actions.push(mergeCursorMcpConfig(cwd));
+  }
+  if (args.writeWindsurfMcp) {
+    actions.push(mergeWindsurfMcpConfig(cwd));
+  }
+  if (args.writeContinueMcp) {
+    actions.push(mergeContinueMcpConfig(cwd));
   }
+  if (args.writeClineMcp) {
+    actions.push(mergeClineMcpConfig(cwd));
+  }
+
+  return new InitResult(cwd, actions, GRAFT_HOOKS_CONFIG, GRAFT_MCP_SERVER);
 }
 
-function appendIfMissing(filePath: string, marker: string, content: string, label: string): void {
-  if (fs.existsSync(filePath)) {
-    const existing = fs.readFileSync(filePath, "utf-8");
-    if (existing.includes(marker)) {
-      console.log(`  exists  ${label} (already has graft entry)`);
+export function runInit(options: RunInitOptions = {}): void {
+  const cwd = options.cwd ?? process.cwd();
+  const args = options.args ?? process.argv.slice(3);
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+
+  try {
+    const parsed = ParsedInitArgs.parse(args);
+    const result = initProject(cwd, parsed);
+    if (parsed.json) {
+      emitInitJson(result.toJSON(), stdout);
       return;
     }
-    fs.appendFileSync(filePath, content);
-    console.log(`  append  ${label}`);
-  } else {
-    fs.writeFileSync(filePath, content.trimStart());
-    console.log(`  create  ${label}`);
-  }
-}
-
-export function runInit(): void {
-  const cwd = process.cwd();
-  console.log(`\nInitializing graft in ${cwd}\n`);
-
-  // 1. .graftignore
-  writeIfMissing(path.join(cwd, ".graftignore"), GRAFTIGNORE_TEMPLATE, ".graftignore");
-
-  // 2. .gitignore — append .graft/
-  appendIfMissing(path.join(cwd, ".gitignore"), ".graft/", GITIGNORE_ENTRY, ".gitignore");
-
-  // 3. CLAUDE.md — append agent instructions snippet
-  appendIfMissing(path.join(cwd, "CLAUDE.md"), "safe_read", "\n" + AGENT_SNIPPET, "CLAUDE.md");
-
-  // 4. Print hooks config for manual setup
-  console.log(HOOKS_CONFIG);
-
-  console.log("Done. Add graft to your MCP config:\n");
-  console.log(`  {
-    "mcpServers": {
-      "graft": {
-        "command": "npx",
-        "args": ["-y", "@flyingrobots/graft"]
-      }
+    renderInitText(result, parsed, stdout);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.exitCode = 1;
+    if (args.includes("--json")) {
+      emitInitJson(new InitFailure(cwd, message), stdout);
+      return;
     }
+    writeCliError(stderr, message, {
+      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: [
+        "Use explicit --write-*-mcp flags to bootstrap project-local client config files.",
+        "Use --write-target-git-hooks only inside a git worktree.",
+      ],
+    });
   }
-`);
 }

package/src/cli/json-document.ts

@@ -0,0 +1,144 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  cloneJsonValue,
+  isJsonObjectValue,
+  type JsonArrayValue,
+  type JsonObjectValue,
+  type JsonValue,
+} from "./init-model.js";
+
+function formatJsonField(pointer: readonly string[]): string {
+  return pointer.length === 0 ? "document root" : pointer.join(".");
+}
+
+export class JsonArrayNode {
+  constructor(
+    private readonly value: JsonArrayValue,
+    private readonly label: string,
+    private readonly pointer: readonly string[] = [],
+  ) {}
+
+  static fromUnknown(
+    value: unknown,
+    label: string,
+    pointer: readonly string[] = [],
+  ): JsonArrayNode {
+    if (!Array.isArray(value)) {
+      throw new Error(`${label}: expected ${formatJsonField(pointer)} to be an array`);
+    }
+    return new JsonArrayNode(value as JsonArrayValue, label, pointer);
+  }
+
+  objectItems(): JsonObjectNode[] {
+    return this.value.map((item, index) =>
+      JsonObjectNode.fromUnknown(item, this.label, [...this.pointer, `[${String(index)}]`]),
+    );
+  }
+
+  push(value: JsonValue): void {
+    this.value.push(cloneJsonValue(value));
+  }
+}
+
+export class JsonObjectNode {
+  constructor(
+    private readonly value: JsonObjectValue,
+    private readonly label: string,
+    private readonly pointer: readonly string[] = [],
+  ) {}
+
+  static fromUnknown(
+    value: unknown,
+    label: string,
+    pointer: readonly string[] = [],
+  ): JsonObjectNode {
+    if (!isJsonObjectValue(value)) {
+      throw new Error(`${label}: expected ${formatJsonField(pointer)} to be an object`);
+    }
+    return new JsonObjectNode(value, label, pointer);
+  }
+
+  has(key: string): boolean {
+    return this.value[key] !== undefined;
+  }
+
+  set(key: string, value: JsonValue): void {
+    this.value[key] = cloneJsonValue(value);
+  }
+
+  ensureObject(key: string): JsonObjectNode {
+    const current = this.value[key];
+    if (current === undefined) {
+      const created: JsonObjectValue = {};
+      this.value[key] = created;
+      return new JsonObjectNode(created, this.label, [...this.pointer, key]);
+    }
+    return JsonObjectNode.fromUnknown(current, this.label, [...this.pointer, key]);
+  }
+
+  ensureArray(key: string): JsonArrayNode {
+    const current = this.value[key];
+    if (current === undefined) {
+      const created: JsonArrayValue = [];
+      this.value[key] = created;
+      return new JsonArrayNode(created, this.label, [...this.pointer, key]);
+    }
+    return JsonArrayNode.fromUnknown(current, this.label, [...this.pointer, key]);
+  }
+
+  requireArray(key: string): JsonArrayNode {
+    const current = this.value[key];
+    if (current === undefined) {
+      throw new Error(`${this.label}: expected ${formatJsonField([...this.pointer, key])} to exist`);
+    }
+    return JsonArrayNode.fromUnknown(current, this.label, [...this.pointer, key]);
+  }
+
+  stringValue(key: string): string | undefined {
+    const current = this.value[key];
+    return typeof current === "string" ? current : undefined;
+  }
+
+  toJsonValue(): JsonObjectValue {
+    return this.value;
+  }
+}
+
+export class JsonObjectDocument {
+  constructor(
+    readonly label: string,
+    readonly filePath: string,
+    private readonly rootNode: JsonObjectNode,
+  ) {}
+
+  static create(
+    filePath: string,
+    label: string,
+    root: JsonObjectValue,
+  ): JsonObjectDocument {
+    return new JsonObjectDocument(
+      label,
+      filePath,
+      new JsonObjectNode(cloneJsonValue(root), label),
+    );
+  }
+
+  static open(filePath: string, label: string): JsonObjectDocument {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+    return new JsonObjectDocument(
+      label,
+      filePath,
+      JsonObjectNode.fromUnknown(parsed, label),
+    );
+  }
+
+  root(): JsonObjectNode {
+    return this.rootNode;
+  }
+
+  write(): void {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    fs.writeFileSync(this.filePath, JSON.stringify(this.rootNode.toJsonValue(), null, 2));
+  }
+}