@flyingrobots/graft 0.6.1 → 0.7.0

package/src/cli/migrate-local-history.ts

@@ -70,7 +70,8 @@ export async function runMigrateLocalHistory(options: RunMigrateLocalHistoryOpti
   const graftDir = path.join(options.cwd, ".graft");
 
   try {
-    const warp = await openWarp({ cwd: options.cwd });
+    const app = await openWarp({ cwd: options.cwd });
+    const warpCtx = { app, strandId: null };
     const payload: MigrateLocalHistoryPayload = {
       cwd: options.cwd,
       ...await migrateLegacyPersistedLocalHistoryToGraph({
@@ -78,7 +79,7 @@ export async function runMigrateLocalHistory(options: RunMigrateLocalHistoryOpti
         codec,
         graftDir,
         graph: {
-          warp,
+          warp: warpCtx,
           worktreeRoot: options.cwd,
         },
       }),

package/src/cli/peer-command.ts

@@ -1,7 +1,8 @@
 import * as path from "node:path";
 import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
 import type { CliCommandName, 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 {
   attachCliSchemaMeta,
   validateCliOutput,

package/src/contracts/capabilities.ts

@@ -1,5 +1,6 @@
 export const MCP_TOOL_NAMES = [
   "safe_read",
+  "graft_edit",
   "file_outline",
   "read_range",
   "changed_since",
@@ -16,6 +17,7 @@ export const MCP_TOOL_NAMES = [
   "monitor_start",
   "monitor_pause",
   "monitor_resume",
+  "monitor_nudge",
   "monitor_stop",
   "workspace_authorize",
   "workspace_authorizations",
@@ -33,6 +35,13 @@ export const MCP_TOOL_NAMES = [
   "explain",
   "doctor",
   "stats",
+  "graft_churn",
+  "graft_exports",
+  "graft_log",
+  "graft_blame",
+  "graft_difficulty",
+  "graft_review",
+  "knowledge_map",
 ] as const;
 
 export type McpToolName = typeof MCP_TOOL_NAMES[number];
@@ -56,6 +65,13 @@ export const CLI_COMMAND_NAMES = [
   "diag_explain",
   "diag_stats",
   "diag_capture",
+  "struct_churn",
+  "struct_exports",
+  "struct_log",
+  "symbol_blame",
+  "symbol_difficulty",
+  "struct_review",
+  "git_graft_enhance",
 ] as const;
 
 export type CliCommandName = typeof CLI_COMMAND_NAMES[number];
@@ -157,6 +173,12 @@ export const CAPABILITY_REGISTRY: readonly CapabilityDefinition[] = [
     apiExposure: "repo_workspace",
     cliMcpParity: "peer",
   }),
+  defineCapability({
+    id: "graft_edit",
+    description: "Governed exact replacement edit",
+    mcpTool: "graft_edit",
+    cliMcpParity: "mcp_only",
+  }),
   defineCapability({
     id: "file_outline",
     description: "Structural file outline",
@@ -272,6 +294,13 @@ export const CAPABILITY_REGISTRY: readonly CapabilityDefinition[] = [
     mcpTool: "monitor_resume",
     cliMcpParity: "mcp_only",
   }),
+  defineCapability({
+    id: "monitor_nudge",
+    description: "Trigger immediate re-index for a running monitor",
+    mcpTool: "monitor_nudge",
+    cliMcpParity: "mcp_only",
+  }),
+
   defineCapability({
     id: "monitor_stop",
     description: "Stop a repo-scoped persistent monitor",
@@ -391,6 +420,67 @@ export const CAPABILITY_REGISTRY: readonly CapabilityDefinition[] = [
     mcpTool: "state_load",
     cliMcpParity: "mcp_only",
   }),
+  defineCapability({
+    id: "graft_churn",
+    description: "Structural churn report — symbol change frequency hotspots",
+    mcpTool: "graft_churn",
+    cliCommand: "struct_churn",
+    cliPath: ["struct", "churn"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "graft_exports",
+    description: "Export surface diff — public API changes between refs",
+    mcpTool: "graft_exports",
+    cliCommand: "struct_exports",
+    cliPath: ["struct", "exports"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "graft_log",
+    description: "Structural git log — symbol-level changes per commit",
+    mcpTool: "graft_log",
+    cliCommand: "struct_log",
+    cliPath: ["struct", "log"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "graft_blame",
+    description: "Symbol-level blame — creation, signature history, and references",
+    mcpTool: "graft_blame",
+    cliCommand: "symbol_blame",
+    cliPath: ["symbol", "blame"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "graft_difficulty",
+    description: "Refactor difficulty score — churn curvature times reference friction",
+    mcpTool: "graft_difficulty",
+    cliCommand: "symbol_difficulty",
+    cliPath: ["symbol", "difficulty"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "graft_review",
+    description: "Zero-noise structural PR review with breaking change detection",
+    mcpTool: "graft_review",
+    cliCommand: "struct_review",
+    cliPath: ["struct", "review"],
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "git_graft_enhance",
+    description: "Git-facing structural review summary over a ref range",
+    cliCommand: "git_graft_enhance",
+    cliPath: ["enhance"],
+    cliMcpParity: "cli_only",
+  }),
+  defineCapability({
+    id: "knowledge_map",
+    description: "Session knowledge map — observed files, symbols, staleness, and coverage",
+    mcpTool: "knowledge_map",
+    cliMcpParity: "mcp_only",
+  }),
   defineCapability({
     id: "structured_buffer",
     description: "Dirty-buffer structural editor surface for in-process integrations",

package/src/contracts/json-object.ts

@@ -15,14 +15,4 @@ export function parseJsonObject(value: unknown, label: string): JsonObject {
 export function tryParseJsonObject(value: unknown): JsonObject | null {
   const parsed = jsonObjectSchema.safeParse(value);
   return parsed.success ? parsed.data : null;
-}
-
-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/contracts/output-schema-cli.ts

@@ -5,6 +5,33 @@ import { mcpOutputBodySchemas } from "./output-schema-mcp.js";
 
 const { initActionSchema, hooksConfigSchema, suggestedMcpServerSchema } = cliFragmentSchemas;
 
+const gitGraftEnhanceBodySchema = z.object({
+  range: z.object({
+    since: z.string(),
+    head: z.string(),
+  }).strict(),
+  structural: z.object({
+    changedFiles: z.number().int().nonnegative(),
+    addedSymbols: z.number().int().nonnegative(),
+    removedSymbols: z.number().int().nonnegative(),
+    changedSymbols: z.number().int().nonnegative(),
+    topFilesByChangeCount: z.array(z.object({
+      path: z.string(),
+      status: z.string(),
+      changeCount: z.number().int().nonnegative(),
+      summary: z.string(),
+    }).strict()),
+  }).strict(),
+  exports: z.object({
+    changed: z.boolean(),
+    semverImpact: z.enum(["major", "minor", "patch", "none"]),
+    addedExports: z.number().int().nonnegative(),
+    removedExports: z.number().int().nonnegative(),
+    changedExports: z.number().int().nonnegative(),
+  }).strict(),
+  warnings: z.array(z.string()),
+}).strict();
+
 export const cliOutputBodySchemas = {
   init: z.object({
     ok: z.boolean(),
@@ -17,9 +44,8 @@ export const cliOutputBodySchemas = {
   index: z.object({
     ok: z.boolean(),
     cwd: z.string(),
-    from: z.string().nullable(),
-    commitsIndexed: z.number().int().nonnegative().optional(),
-    patchesWritten: z.number().int().nonnegative().optional(),
+    filesIndexed: z.number().int().nonnegative().optional(),
+    nodesEmitted: z.number().int().nonnegative().optional(),
     error: z.string().optional(),
   }).strict(),
   migrate_local_history: z.object({
@@ -67,4 +93,11 @@ export const cliOutputBodySchemas = {
   diag_explain: mcpOutputBodySchemas.explain,
   diag_stats: mcpOutputBodySchemas.stats,
   diag_capture: mcpOutputBodySchemas.run_capture,
+  git_graft_enhance: gitGraftEnhanceBodySchema,
+  struct_churn: mcpOutputBodySchemas.graft_churn,
+  struct_exports: mcpOutputBodySchemas.graft_exports,
+  struct_log: mcpOutputBodySchemas.graft_log,
+  symbol_blame: mcpOutputBodySchemas.graft_blame,
+  symbol_difficulty: mcpOutputBodySchemas.graft_difficulty,
+  struct_review: mcpOutputBodySchemas.graft_review,
 } satisfies Record<CliCommandName, z.ZodType>;

package/src/contracts/output-schema-fragments.ts

@@ -82,6 +82,7 @@ export const diffEntrySchema: z.ZodType = z.lazy(() => z.object({
   _brand: z.literal("DiffEntry").optional(),
   name: z.string(),
   kind: z.string(),
+  exported: z.boolean().optional(),
   signature: z.string().optional(),
   oldSignature: z.string().optional(),
   childDiff: outlineDiffSchema.optional(),
@@ -102,6 +103,45 @@ export const burdenByKindSchema = z.object({
   diagnostic: burdenBucketSchema,
 }).strict();
 
+export const sludgeSignalSchema = z.object({
+  kind: z.enum([
+    "phantom_shape",
+    "cast_density",
+    "homeless_constructor",
+    "free_function_data_behavior",
+    "god_file",
+  ]),
+  severity: z.enum(["low", "medium", "high"]),
+  message: z.string(),
+  line: z.number().int().positive().optional(),
+  symbol: z.string().optional(),
+  evidence: z.string(),
+}).strict();
+
+export const sludgeFileReportSchema = z.object({
+  path: z.string(),
+  score: z.number().int().nonnegative(),
+  metrics: z.object({
+    typedefCount: z.number().int().nonnegative(),
+    typeCastCount: z.number().int().nonnegative(),
+    classCount: z.number().int().nonnegative(),
+    functionCount: z.number().int().nonnegative(),
+    symbolCount: z.number().int().nonnegative(),
+    homelessConstructorCount: z.number().int().nonnegative(),
+    freeFunctionDataBehaviorCount: z.number().int().nonnegative(),
+  }).strict(),
+  signals: z.array(sludgeSignalSchema),
+}).strict();
+
+export const sludgeReportSchema = z.object({
+  scannedFiles: z.number().int().nonnegative(),
+  filesWithSignals: z.number().int().nonnegative(),
+  totalSignals: z.number().int().nonnegative(),
+  score: z.number().int().nonnegative(),
+  files: z.array(sludgeFileReportSchema),
+  summary: z.string(),
+}).strict();
+
 export const receiptSchema = z.object({
   sessionId: z.string(),
   traceId: z.string(),
@@ -519,7 +559,7 @@ const activeCausalWorkspaceSchema = z.object({
   latestReadEvent: readEventSchema.nullable(),
   latestStageEvent: stageEventSchema.nullable(),
   latestTransitionEvent: transitionEventSchema.nullable(),
-  repoConcurrency: repoConcurrencySummarySchema,
+  repoConcurrency: repoConcurrencySummarySchema.nullable(),
   checkoutEpoch: z.number().int().nonnegative(),
   lastTransition: repoTransitionSchema.nullable(),
   semanticTransition: repoSemanticTransitionSchema.nullable(),
@@ -759,7 +799,16 @@ const suggestedMcpServerSchema = z.object({
   mcpServers: z.object({
     graft: z.object({
       command: z.literal("npx"),
-      args: z.tuple([z.literal("-y"), z.literal("@flyingrobots/graft"), z.literal("serve")]),
+      args: z.union([
+        z.tuple([z.literal("-y"), z.literal("@flyingrobots/graft"), z.literal("serve")]),
+        z.tuple([
+          z.literal("-y"),
+          z.literal("@flyingrobots/graft"),
+          z.literal("serve"),
+          z.literal("--runtime"),
+          z.literal("daemon"),
+        ]),
+      ]),
     }).strict(),
   }).strict(),
 }).strict();
@@ -797,6 +846,7 @@ export const mcpFragmentSchemas = {
   mapModeSchema,
   fileDiffSchema,
   burdenByKindSchema,
+  sludgeReportSchema,
   burdenSummarySchema,
   receiptSchema,
   runtimeObservabilitySchema,

package/src/contracts/output-schema-mcp.ts

@@ -22,6 +22,7 @@ const {
   mapModeSchema,
   fileDiffSchema,
   burdenByKindSchema,
+  sludgeReportSchema,
   burdenSummarySchema,
   runtimeObservabilitySchema,
   runtimeCausalContextSchema,
@@ -54,6 +55,34 @@ const {
   sessionDepthSchema,
 } = mcpFragmentSchemas;
 
+const graftEditReasonSchema = z.enum([
+  "NOT_FOUND",
+  "OLD_STRING_NOT_FOUND",
+  "OLD_STRING_AMBIGUOUS",
+  "BINARY",
+  "LOCKFILE",
+  "MINIFIED",
+  "BUILD_OUTPUT",
+  "SECRET",
+  "GRAFTIGNORE",
+]);
+
+const graftEditDriftWarningSchema = z.object({
+  kind: z.literal("structural_pattern_reintroduced"),
+  severity: z.literal("advisory"),
+  pattern: z.literal("jsdoc_typedef"),
+  basis: z.literal("session_local_graft_edit"),
+  message: z.string(),
+  current: z.object({
+    path: z.string(),
+    direction: z.literal("added"),
+  }).strict(),
+  previous: z.object({
+    path: z.string(),
+    direction: z.literal("removed"),
+  }).strict(),
+}).strict();
+
 export const mcpOutputBodySchemas = {
   safe_read: z.object({
     path: z.string(),
@@ -72,6 +101,20 @@ export const mcpOutputBodySchemas = {
     lastReadAt: z.string().optional(),
     diff: outlineDiffSchema.optional(),
   }).strict(),
+  graft_edit: z.object({
+    path: z.string(),
+    operation: z.literal("replace"),
+    projection: z.enum(["edited", "refused"]),
+    status: z.enum(["edited", "refused"]),
+    changed: z.boolean(),
+    matches: z.number().int().nonnegative(),
+    replacements: z.number().int().nonnegative(),
+    reason: graftEditReasonSchema.optional(),
+    reasonDetail: z.string().optional(),
+    next: z.array(z.string()).optional(),
+    actual: actualSchema.optional(),
+    driftWarnings: z.array(graftEditDriftWarningSchema).optional(),
+  }).strict(),
   file_outline: z.union([
     z.object({
       path: z.string(),
@@ -203,6 +246,7 @@ export const mcpOutputBodySchemas = {
   monitor_start: monitorActionSchema,
   monitor_pause: monitorActionSchema,
   monitor_resume: monitorActionSchema,
+  monitor_nudge: monitorActionSchema,
   monitor_stop: monitorActionSchema,
   workspace_authorize: workspaceAuthorizeSchema,
   workspace_authorizations: z.object({
@@ -268,6 +312,7 @@ export const mcpOutputBodySchemas = {
     attribution: attributionSummarySchema,
     persistedLocalHistory: persistedLocalHistorySummarySchema,
     recommendedNextAction: z.string(),
+    sludge: sludgeReportSchema.optional(),
   }).strict(),
   stats: z.object({
     totalReads: z.number().int().nonnegative(),
@@ -279,4 +324,178 @@ export const mcpOutputBodySchemas = {
     totalNonReadBytesReturned: z.number().int().nonnegative(),
     burdenByKind: burdenByKindSchema,
   }).strict(),
+  graft_churn: z.object({
+    entries: z.array(z.object({
+      symbol: z.string(),
+      filePath: z.string(),
+      kind: z.string(),
+      changeCount: z.number().int().positive(),
+      lastChangedSha: z.string(),
+      lastChangedDate: z.string(),
+    }).strict()),
+    totalSymbols: z.number().int().nonnegative(),
+    totalCommitsAnalyzed: z.number().int().nonnegative(),
+    summary: z.string(),
+  }).strict(),
+  graft_exports: z.object({
+    base: z.string(),
+    head: z.string(),
+    added: z.array(z.object({
+      symbol: z.string(),
+      filePath: z.string(),
+      kind: z.string(),
+      changeType: z.literal("added"),
+      signature: z.string().optional(),
+    }).strict()),
+    removed: z.array(z.object({
+      symbol: z.string(),
+      filePath: z.string(),
+      kind: z.string(),
+      changeType: z.literal("removed"),
+      signature: z.string().optional(),
+    }).strict()),
+    changed: z.array(z.object({
+      symbol: z.string(),
+      filePath: z.string(),
+      kind: z.string(),
+      changeType: z.literal("signature_changed"),
+      signature: z.string().optional(),
+      previousSignature: z.string().optional(),
+    }).strict()),
+    semverImpact: z.enum(["major", "minor", "patch", "none"]),
+    summary: z.string(),
+  }).strict(),
+  graft_log: z.object({
+    entries: z.array(z.object({
+      sha: z.string(),
+      message: z.string(),
+      author: z.string(),
+      date: z.string(),
+      symbols: z.object({
+        added: z.array(z.object({
+          name: z.string(),
+          kind: z.string(),
+          signature: z.string().optional(),
+          exported: z.boolean(),
+          filePath: z.string(),
+        }).strict()),
+        removed: z.array(z.object({
+          name: z.string(),
+          kind: z.string(),
+          signature: z.string().optional(),
+          exported: z.boolean(),
+          filePath: z.string(),
+        }).strict()),
+        changed: z.array(z.object({
+          name: z.string(),
+          kind: z.string(),
+          signature: z.string().optional(),
+          exported: z.boolean(),
+          filePath: z.string(),
+        }).strict()),
+      }).strict(),
+      summary: z.string(),
+    }).strict()),
+    count: z.number().int().nonnegative(),
+    layer: z.literal("commit_worldline"),
+  }).strict(),
+  graft_blame: z.object({
+    symbol: z.string(),
+    filePath: z.string().optional(),
+    currentSignature: z.string().optional(),
+    kind: z.string(),
+    exported: z.boolean(),
+    created: z.object({
+      sha: z.string(),
+      author: z.string(),
+      date: z.string(),
+      message: z.string(),
+    }).strict().optional(),
+    lastSignatureChange: z.object({
+      sha: z.string(),
+      author: z.string(),
+      date: z.string(),
+      message: z.string(),
+      previousSignature: z.string().optional(),
+    }).strict().optional(),
+    changeCount: z.number().int().nonnegative(),
+    referenceCount: z.number().int().nonnegative(),
+    referencingFiles: z.array(z.string()),
+    history: z.array(z.object({
+      sha: z.string(),
+      changeKind: z.string(),
+      date: z.string(),
+      author: z.string(),
+      signature: z.string().optional(),
+    }).strict()),
+  }).strict(),
+  graft_difficulty: z.object({
+    symbol: z.string(),
+    path: z.string().optional(),
+    entries: z.array(z.object({
+      symbol: z.string(),
+      filePath: z.string(),
+      kind: z.string(),
+      score: z.number().nonnegative(),
+      risk: z.enum(["low", "medium", "high"]),
+      recommendation: z.enum(["refactor_freely", "refactor_with_tests", "plan_before_refactor"]),
+      curvature: z.object({
+        changeCount: z.number().int().nonnegative(),
+        signatureChangeCount: z.number().int().nonnegative(),
+        score: z.number().nonnegative(),
+      }).strict(),
+      friction: z.object({
+        referenceCount: z.number().int().nonnegative(),
+        referencingFiles: z.array(z.string()),
+        score: z.number().nonnegative(),
+      }).strict(),
+    }).strict()),
+    total: z.number().int().nonnegative(),
+    summary: z.string(),
+  }).strict(),
+  graft_review: z.object({
+    base: z.string(),
+    head: z.string(),
+    totalFiles: z.number().int().nonnegative(),
+    categories: z.object({
+      structural: z.number().int().nonnegative(),
+      formatting: z.number().int().nonnegative(),
+      test: z.number().int().nonnegative(),
+      docs: z.number().int().nonnegative(),
+      config: z.number().int().nonnegative(),
+    }).strict(),
+    files: z.array(z.object({
+      path: z.string(),
+      category: z.enum(["structural", "formatting", "test", "docs", "config"]),
+      structuralChanges: z.object({
+        added: z.number().int().nonnegative(),
+        removed: z.number().int().nonnegative(),
+        changed: z.number().int().nonnegative(),
+      }).strict().optional(),
+    }).strict()),
+    breakingChanges: z.array(z.object({
+      symbol: z.string(),
+      kind: z.string(),
+      filePath: z.string(),
+      changeType: z.enum(["removed_export", "signature_changed", "type_changed"]),
+      previousSignature: z.string().optional(),
+      newSignature: z.string().optional(),
+      impactedFiles: z.number().int().nonnegative(),
+      impactedFilePaths: z.array(z.string()),
+    }).strict()),
+    summary: z.string(),
+  }).strict(),
+  knowledge_map: z.object({
+    totalFiles: z.number().int().nonnegative(),
+    totalSymbols: z.number().int().nonnegative(),
+    files: z.array(z.object({
+      path: z.string(),
+      symbols: z.array(z.string()),
+      readCount: z.number().int().positive(),
+      lastReadAt: z.string(),
+      stale: z.boolean(),
+    }).strict()),
+    staleFiles: z.array(z.string()),
+    directoryCoverage: z.record(z.string(), z.number().int().nonnegative()),
+  }).strict(),
 } satisfies Record<McpToolName, z.ZodType>;