@flyingrobots/graft 0.4.0 → 0.5.0

package/src/mcp/runtime-staged-target.ts

@@ -0,0 +1,161 @@
+import * as crypto from "node:crypto";
+import type { AttributionSummary, StagedTarget } from "../contracts/causal-ontology.js";
+import type { RepoObservation } from "./repo-state.js";
+import type { RuntimeCausalContext } from "./runtime-causal-context.js";
+import type { WorkspaceStatus } from "./workspace-router.js";
+
+const FULL_FILE_SAFE_STATUSES = new Set(["A", "D", "R", "C", "T"]);
+
+export interface RuntimeStagedTargetNone {
+  readonly availability: "none";
+  readonly stability: "runtime_local";
+  readonly provenanceLevel: "artifact_history";
+}
+
+export interface RuntimeStagedTargetFullFile {
+  readonly availability: "full_file";
+  readonly stability: "runtime_local";
+  readonly provenanceLevel: "artifact_history";
+  readonly attribution: AttributionSummary;
+  readonly target: StagedTarget;
+}
+
+export interface RuntimeStagedTargetAmbiguous {
+  readonly availability: "ambiguous";
+  readonly stability: "runtime_local";
+  readonly provenanceLevel: "artifact_history";
+  readonly attribution: AttributionSummary;
+  readonly reason:
+    | "missing_head_commit"
+    | "missing_workspace_overlay"
+    | "modified_path_selection_requires_deeper_evidence";
+  readonly observedStagedPaths: number;
+  readonly ambiguousPaths: readonly string[];
+}
+
+export type RuntimeStagedTarget =
+  | RuntimeStagedTargetNone
+  | RuntimeStagedTargetFullFile
+  | RuntimeStagedTargetAmbiguous;
+
+interface MergedStatusEntry {
+  readonly path: string;
+  readonly stagedStatus: string;
+  readonly worktreeStatus: string;
+}
+
+function stableId(prefix: string, input: string): string {
+  return `${prefix}:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 16)}`;
+}
+
+function parseMergedStatusLine(line: string): MergedStatusEntry | null {
+  if (line.length < 4) return null;
+  return {
+    stagedStatus: line[0] ?? " ",
+    worktreeStatus: line[1] ?? " ",
+    path: line.slice(3),
+  };
+}
+
+function stagedEntries(statusLines: readonly string[]): readonly MergedStatusEntry[] {
+  return statusLines
+    .map(parseMergedStatusLine)
+    .filter((entry): entry is MergedStatusEntry => entry !== null && entry.stagedStatus !== " " && entry.stagedStatus !== "?");
+}
+
+function isFullFileSafe(entry: MergedStatusEntry): boolean {
+  return entry.worktreeStatus === " " && FULL_FILE_SAFE_STATUSES.has(entry.stagedStatus);
+}
+
+export function buildRuntimeStagedTarget(
+  status: WorkspaceStatus,
+  causalContext: RuntimeCausalContext,
+  repoState: RepoObservation,
+  attribution: AttributionSummary,
+): RuntimeStagedTarget {
+  const observedEntries = stagedEntries(repoState.statusLines);
+  if (observedEntries.length === 0) {
+    return {
+      availability: "none",
+      stability: "runtime_local",
+      provenanceLevel: "artifact_history",
+    };
+  }
+
+  if (repoState.headSha === null) {
+    return {
+      availability: "ambiguous",
+      stability: "runtime_local",
+      provenanceLevel: "artifact_history",
+      attribution,
+      reason: "missing_head_commit",
+      observedStagedPaths: observedEntries.length,
+      ambiguousPaths: observedEntries.map((entry) => entry.path),
+    };
+  }
+
+  if (repoState.workspaceOverlayId === null || status.repoId === null || status.worktreeId === null) {
+    return {
+      availability: "ambiguous",
+      stability: "runtime_local",
+      provenanceLevel: "artifact_history",
+      attribution,
+      reason: "missing_workspace_overlay",
+      observedStagedPaths: observedEntries.length,
+      ambiguousPaths: observedEntries.map((entry) => entry.path),
+    };
+  }
+
+  const ambiguousEntries = observedEntries.filter((entry) => !isFullFileSafe(entry));
+  if (ambiguousEntries.length > 0) {
+    return {
+      availability: "ambiguous",
+      stability: "runtime_local",
+      provenanceLevel: "artifact_history",
+      attribution,
+      reason: "modified_path_selection_requires_deeper_evidence",
+      observedStagedPaths: observedEntries.length,
+      ambiguousPaths: ambiguousEntries.map((entry) => entry.path),
+    };
+  }
+
+  const selectionEntries = observedEntries.map((entry) => ({
+    path: entry.path,
+    symbols: [],
+    regions: [],
+  }));
+
+  const target: StagedTarget = {
+    targetId: stableId(
+      "target",
+      JSON.stringify({
+        repoId: status.repoId,
+        worktreeId: status.worktreeId,
+        checkoutEpochId: causalContext.checkoutEpochId,
+        workspaceOverlayId: repoState.workspaceOverlayId,
+        headSha: repoState.headSha,
+        paths: selectionEntries.map((entry) => entry.path),
+      }),
+    ),
+    targetKind: "staged_target",
+    repoId: status.repoId,
+    worktreeId: status.worktreeId,
+    checkoutEpochId: causalContext.checkoutEpochId,
+    workspaceOverlayId: repoState.workspaceOverlayId,
+    selectedAt: repoState.observedAt,
+    selectionKind: "full_file",
+    selectionEntries,
+    base: {
+      headCommitSha: repoState.headSha,
+      indexTreeSha: null,
+    },
+  };
+
+  return {
+    availability: "full_file",
+    stability: "runtime_local",
+    provenanceLevel: "artifact_history",
+    attribution,
+    target,
+  };
+}

package/src/mcp/runtime-workspace-overlay.ts

@@ -0,0 +1,255 @@
+import * as path from "node:path";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { GitClient } from "../ports/git.js";
+import {
+  isRecognizedTargetGitHook,
+  isTargetGitTransitionHookName,
+  resolveGitHooksPath,
+  TARGET_GIT_TRANSITION_HOOKS,
+} from "../git/target-git-hook-bootstrap.js";
+import type {
+  RepoTransition,
+  WorkspaceOverlaySummary,
+} from "./repo-state.js";
+
+export type GitHookBootstrapPosture = "absent" | "external_unknown" | "installed";
+export type WorkspaceOverlayObservationMode =
+  | "inferred_between_tool_calls"
+  | "hook_observed_checkout_boundaries";
+export type WorkspaceOverlayLineagePosture =
+  | "stable"
+  | "forked_after_transition";
+export type WorkspaceOverlayBoundaryAuthority =
+  | "none"
+  | "repo_snapshot"
+  | "hook_observed";
+export type WorkspaceOverlayDegradedReason =
+  | "target_repo_hooks_absent"
+  | "target_repo_hooks_unrecognized"
+  | "local_edit_watchers_absent";
+
+export interface GitTransitionHookEvent {
+  readonly hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number];
+  readonly hookArgs: readonly string[];
+  readonly worktreeRoot: string;
+  readonly observedAt: string;
+}
+
+export interface GitHookBootstrapStatus {
+  readonly posture: GitHookBootstrapPosture;
+  readonly configuredCoreHooksPath: string | null;
+  readonly resolvedHooksPath: string;
+  readonly requiredHooks: readonly string[];
+  readonly presentHooks: readonly string[];
+  readonly missingHooks: readonly string[];
+  readonly supportsCheckoutBoundaries: boolean;
+}
+
+export interface RuntimeWorkspaceOverlayFooting {
+  readonly observationMode: WorkspaceOverlayObservationMode;
+  readonly lineagePosture: WorkspaceOverlayLineagePosture;
+  readonly boundaryAuthority: WorkspaceOverlayBoundaryAuthority;
+  readonly degraded: true;
+  readonly degradedReason: WorkspaceOverlayDegradedReason;
+  readonly checkoutEpoch: number;
+  readonly lastTransition: RepoTransition | null;
+  readonly workspaceOverlayId: string | null;
+  readonly workspaceOverlay: WorkspaceOverlaySummary | null;
+  readonly hookBootstrap: GitHookBootstrapStatus;
+  readonly latestHookEvent: GitTransitionHookEvent | null;
+}
+
+async function readGitConfig(
+  gitClient: GitClient,
+  cwd: string,
+  key: string,
+): Promise<string | null> {
+  const result = await gitClient.run({
+    args: ["config", "--get", key],
+    cwd,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const value = result.stdout.trim();
+  return value.length > 0 ? value : null;
+}
+
+async function fileExists(fs: FileSystem, targetPath: string): Promise<boolean> {
+  try {
+    await fs.readFile(targetPath, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function equivalentWorktreeRoots(left: string, right: string): boolean {
+  const leftResolved = path.resolve(left);
+  const rightResolved = path.resolve(right);
+  if (leftResolved === rightResolved) {
+    return true;
+  }
+  return (
+    leftResolved === `/private${rightResolved}`
+    || rightResolved === `/private${leftResolved}`
+  );
+}
+
+function parseHookEventLine(
+  line: string,
+  worktreeRoot: string,
+): GitTransitionHookEvent | null {
+  try {
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    const hookName = parsed["hookName"];
+    const hookArgs = parsed["hookArgs"];
+    const observedAt = parsed["observedAt"];
+    const observedWorktreeRoot = parsed["worktreeRoot"];
+    if (
+      typeof hookName !== "string"
+      || !isTargetGitTransitionHookName(hookName)
+      || !Array.isArray(hookArgs)
+      || !hookArgs.every((value) => typeof value === "string")
+      || typeof observedAt !== "string"
+      || typeof observedWorktreeRoot !== "string"
+      || !equivalentWorktreeRoots(observedWorktreeRoot, worktreeRoot)
+    ) {
+      return null;
+    }
+    return {
+      hookName,
+      hookArgs,
+      worktreeRoot: observedWorktreeRoot,
+      observedAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function readLatestHookEvent(
+  fs: FileSystem,
+  worktreeRoot: string,
+): Promise<GitTransitionHookEvent | null> {
+  const logPath = path.join(worktreeRoot, ".graft", "runtime", "git-transitions.ndjson");
+  try {
+    const content = await fs.readFile(logPath, "utf-8");
+    const lines = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const line = lines[index];
+      if (line === undefined) continue;
+      const parsed = parseHookEventLine(line, worktreeRoot);
+      if (parsed !== null) {
+        return parsed;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function inspectGitHookBootstrap(
+  fs: FileSystem,
+  gitClient: GitClient,
+  worktreeRoot: string,
+  gitCommonDir: string,
+): Promise<GitHookBootstrapStatus> {
+  const configuredCoreHooksPath = await readGitConfig(
+    gitClient,
+    worktreeRoot,
+    "core.hooksPath",
+  );
+  const resolvedHooksPath = resolveGitHooksPath(
+    worktreeRoot,
+    gitCommonDir,
+    configuredCoreHooksPath,
+  );
+
+  const presentHooks: string[] = [];
+  const missingHooks: string[] = [];
+  let recognizedHooks = 0;
+  let externalHooks = 0;
+  for (const hookName of TARGET_GIT_TRANSITION_HOOKS) {
+    const hookPath = path.join(resolvedHooksPath, hookName);
+    if (await fileExists(fs, hookPath)) {
+      presentHooks.push(hookName);
+      try {
+        const content = await fs.readFile(hookPath, "utf-8");
+        if (isRecognizedTargetGitHook(content, hookName)) {
+          recognizedHooks += 1;
+        } else {
+          externalHooks += 1;
+        }
+      } catch {
+        externalHooks += 1;
+      }
+    } else {
+      missingHooks.push(hookName);
+    }
+  }
+
+  const allHooksInstalled = recognizedHooks === TARGET_GIT_TRANSITION_HOOKS.length;
+  return {
+    posture: allHooksInstalled
+      ? "installed"
+      : (presentHooks.length === 0 ? "absent" : "external_unknown"),
+    configuredCoreHooksPath,
+    resolvedHooksPath,
+    requiredHooks: [...TARGET_GIT_TRANSITION_HOOKS],
+    presentHooks,
+    missingHooks,
+    supportsCheckoutBoundaries: allHooksInstalled && externalHooks === 0,
+  };
+}
+
+export async function buildRuntimeWorkspaceOverlayFooting(
+  fs: FileSystem,
+  gitClient: GitClient,
+  worktreeRoot: string,
+  gitCommonDir: string,
+  repoState: {
+    readonly checkoutEpoch: number;
+    readonly lastTransition: RepoTransition | null;
+    readonly workspaceOverlayId: string | null;
+    readonly workspaceOverlay: WorkspaceOverlaySummary | null;
+  },
+): Promise<RuntimeWorkspaceOverlayFooting> {
+  const hookBootstrap = await inspectGitHookBootstrap(
+    fs,
+    gitClient,
+    worktreeRoot,
+    gitCommonDir,
+  );
+  const latestHookEvent = hookBootstrap.supportsCheckoutBoundaries
+    ? await readLatestHookEvent(fs, worktreeRoot)
+    : null;
+  const lineagePosture = repoState.checkoutEpoch > 0 || latestHookEvent !== null || repoState.lastTransition !== null
+    ? "forked_after_transition"
+    : "stable";
+  const boundaryAuthority = latestHookEvent !== null
+    ? "hook_observed"
+    : (repoState.lastTransition !== null || repoState.checkoutEpoch > 0
+        ? "repo_snapshot"
+        : "none");
+  return {
+    observationMode: latestHookEvent === null
+      ? "inferred_between_tool_calls"
+      : "hook_observed_checkout_boundaries",
+    lineagePosture,
+    boundaryAuthority,
+    degraded: true,
+    degradedReason: hookBootstrap.supportsCheckoutBoundaries
+      ? "local_edit_watchers_absent"
+      : (hookBootstrap.posture === "absent"
+          ? "target_repo_hooks_absent"
+          : "target_repo_hooks_unrecognized"),
+    checkoutEpoch: repoState.checkoutEpoch,
+    lastTransition: repoState.lastTransition,
+    workspaceOverlayId: repoState.workspaceOverlayId,
+    workspaceOverlay: repoState.workspaceOverlay,
+    hookBootstrap,
+    latestHookEvent,
+  };
+}

package/src/mcp/semantic-transition-guidance.ts

@@ -0,0 +1,60 @@
+import type { CausalSurfaceNextAction } from "../contracts/causal-surface-next-action.js";
+import type { PersistedLocalHistorySummary } from "./persisted-local-history.js";
+import type { RepoConcurrencySummary } from "./repo-concurrency.js";
+import type { RepoObservation } from "./repo-state.js";
+
+export function deriveCausalSurfaceNextAction(
+  summaryNextAction: PersistedLocalHistorySummary["nextAction"],
+  semanticTransition: RepoObservation["semanticTransition"],
+  repoConcurrency: RepoConcurrencySummary | null,
+): CausalSurfaceNextAction {
+  if (
+    summaryNextAction === "bind_workspace_to_begin_local_history"
+    || summaryNextAction === "inspect_or_resume_local_history"
+  ) {
+    return summaryNextAction;
+  }
+
+  if (semanticTransition !== null) {
+    switch (semanticTransition.kind) {
+      case "conflict_resolution":
+        return "resolve_conflicts_before_continuing";
+      case "merge_phase":
+        return semanticTransition.phase === "completed_or_cleared"
+          ? summaryNextAction
+          : "complete_merge_phase_before_continuing";
+      case "rebase_phase":
+        return semanticTransition.phase === "completed_or_cleared"
+          ? summaryNextAction
+          : "continue_rebase_phase_before_continuing";
+      case "bulk_transition":
+        return "inspect_bulk_transition_scope_before_continuing";
+      case "index_update":
+      case "unknown":
+        break;
+    }
+  }
+
+  if (repoConcurrency === null) {
+    return summaryNextAction;
+  }
+
+  switch (repoConcurrency.posture) {
+    case "divergent_checkout":
+      return "review_divergent_checkout_before_continuing";
+    case "shared_worktree":
+      if (summaryNextAction === "review_transition_boundary_before_continuing") {
+        return summaryNextAction;
+      }
+      return "coordinate_shared_worktree_before_continuing";
+    case "overlapping_actors":
+      if (summaryNextAction === "review_transition_boundary_before_continuing") {
+        return summaryNextAction;
+      }
+      return "inspect_overlapping_actor_activity_before_continuing";
+    case "exclusive":
+    case "shared_repo_only":
+    case "unknown":
+      return summaryNextAction;
+  }
+}

package/src/mcp/semantic-transition-summary.ts

@@ -0,0 +1,130 @@
+interface SemanticTransitionSummaryEvidence {
+  readonly totalPaths: number;
+  readonly stagedPaths: number;
+  readonly changedPaths: number;
+  readonly untrackedPaths: number;
+  readonly unmergedPaths: number;
+  readonly mergeInProgress: boolean;
+  readonly rebaseInProgress: boolean;
+  readonly rebaseStep: number | null;
+  readonly rebaseTotalSteps: number | null;
+  readonly lastTransitionKind: "checkout" | "reset" | "merge" | "rebase" | null;
+  readonly reflogSubject: string | null;
+}
+
+type SemanticTransitionKind =
+  | "index_update"
+  | "conflict_resolution"
+  | "merge_phase"
+  | "rebase_phase"
+  | "bulk_transition"
+  | "unknown";
+
+type SemanticTransitionPhase =
+  | "started"
+  | "conflicted"
+  | "resolved_waiting_commit"
+  | "continued"
+  | "completed_or_cleared"
+  | null;
+
+function buildConflictResolutionSummary(
+  evidence: SemanticTransitionSummaryEvidence,
+  previousUnmergedPaths: number | null,
+): string {
+  if (evidence.unmergedPaths === 0) {
+    if (previousUnmergedPaths !== null && previousUnmergedPaths > 0) {
+      return `Conflict posture cleared from ${String(previousUnmergedPaths)} conflicted path(s).`;
+    }
+    return "Conflict posture cleared after an explicit conflict-resolution movement.";
+  }
+
+  if (previousUnmergedPaths === null) {
+    return `Conflict posture is active across ${String(evidence.unmergedPaths)} path(s).`;
+  }
+
+  if (previousUnmergedPaths === 0) {
+    return `Conflict posture emerged across ${String(evidence.unmergedPaths)} path(s).`;
+  }
+
+  if (evidence.unmergedPaths < previousUnmergedPaths) {
+    return `Conflict posture is shrinking from ${String(previousUnmergedPaths)} to ${String(evidence.unmergedPaths)} path(s).`;
+  }
+
+  if (evidence.unmergedPaths > previousUnmergedPaths) {
+    return `Conflict posture widened from ${String(previousUnmergedPaths)} to ${String(evidence.unmergedPaths)} path(s).`;
+  }
+
+  return `Conflict posture remains active across ${String(evidence.unmergedPaths)} path(s).`;
+}
+
+function buildBulkTransitionSummary(evidence: SemanticTransitionSummaryEvidence): string {
+  if (
+    evidence.stagedPaths === evidence.totalPaths
+    && evidence.changedPaths === 0
+    && evidence.untrackedPaths === 0
+  ) {
+    return `Bulk staging spans ${String(evidence.totalPaths)} path(s) at the index boundary.`;
+  }
+  if (
+    evidence.changedPaths === evidence.totalPaths
+    && evidence.stagedPaths === 0
+    && evidence.untrackedPaths === 0
+  ) {
+    return `Bulk edit sweep spans ${String(evidence.totalPaths)} unstaged path(s).`;
+  }
+  return `Bulk transition movement spans ${String(evidence.totalPaths)} path(s) with ${String(evidence.stagedPaths)} staged and ${String(evidence.changedPaths)} unstaged changes.`;
+}
+
+export function buildSemanticTransitionSummary(input: {
+  readonly kind: SemanticTransitionKind;
+  readonly evidence: SemanticTransitionSummaryEvidence;
+  readonly phase: SemanticTransitionPhase;
+  readonly previousUnmergedPaths?: number | null;
+}): string {
+  const { kind, evidence, phase, previousUnmergedPaths = null } = input;
+  switch (kind) {
+    case "merge_phase":
+      switch (phase) {
+        case "conflicted":
+          return `Merge is in conflict across ${String(evidence.unmergedPaths)} path(s).`;
+        case "resolved_waiting_commit":
+          return "Merge conflicts are cleared and the merge is waiting for commit/admission.";
+        case "completed_or_cleared":
+          return "Merge transition completed or merge state has cleared.";
+        case "started":
+          return "Merge started and is now inspectable as active repo state.";
+        case "continued":
+          return "Merge progressed and remains active.";
+        default:
+          return "Merge state is active.";
+      }
+    case "rebase_phase":
+      switch (phase) {
+        case "conflicted":
+          return `Rebase is in conflict across ${String(evidence.unmergedPaths)} path(s).`;
+        case "continued":
+          return evidence.rebaseStep !== null && evidence.rebaseTotalSteps !== null
+            ? `Rebase continued at step ${String(evidence.rebaseStep)} of ${String(evidence.rebaseTotalSteps)}.`
+            : "Rebase continued and remains active.";
+        case "completed_or_cleared":
+          return "Rebase transition completed or rebase state has cleared.";
+        case "started":
+          return "Rebase started and is now inspectable as active repo state.";
+        case "resolved_waiting_commit":
+          return "Rebase conflicts are cleared and the rebase is waiting for the next step.";
+        default:
+          return "Rebase state is active.";
+      }
+    case "conflict_resolution":
+      return buildConflictResolutionSummary(evidence, previousUnmergedPaths);
+    case "index_update":
+      return evidence.totalPaths > 1
+        ? `Index/staging boundary changed across ${String(evidence.totalPaths)} path(s).`
+        : "Index/staging boundary changed.";
+    case "bulk_transition":
+      return buildBulkTransitionSummary(evidence);
+    case "unknown":
+      return "Repo/workspace movement is inspectable, but the semantic transition meaning remains unknown.";
+  }
+}