supipowers 1.5.3 → 2.0.1

package/src/ultraplan/authoring/synth-gate.ts

@@ -0,0 +1,165 @@
+/**
+ * SYNTHESIZE-stage `$EDITOR` round-trip helper.
+ *
+ * After the synthesize stage produces `drafts/iteration-N/authored.json`, the user gate
+ * lets the user hand-edit a markdown rendering of the draft. The flow:
+ *
+ *   1. Render the planner's authored.json to authored.md.
+ *   2. Open the markdown in `$EDITOR` (blocking) via `openInEditor`.
+ *   3. Read the file back, strip any prior parse-error annotations, parse, validate.
+ *   4. On clean parse: overlay the patch onto the planner's draft and re-save authored.json.
+ *   5. On parse failure: prepend a structured error annotation, re-open. Two consecutive
+ *      failures bubble up to a user gate ("keep editing | discard edits | abandon").
+ *
+ * The helper is a pure orchestrator: it takes a `Platform` for `exec` and otherwise reads
+ * and writes through the storage helpers. Tests pass a mock platform whose `exec` fakes the
+ * editor by mutating the file in place.
+ */
+
+import * as fs from "node:fs";
+
+import type { Platform } from "../../platform/types.js";
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  UltraPlanAuthoredArtifact,
+} from "../../types.js";
+import { openInEditor } from "../../utils/editor.js";
+import {
+  applyAuthoredPatch,
+  annotateParseErrors,
+  parseAuthoredFromMarkdown,
+  serializeAuthoredToMarkdown,
+  stripParseErrorAnnotations,
+  type AuthoredMarkdownParseError,
+} from "./markdown.js";
+import {
+  loadDraftAuthoredJson,
+  saveDraftAuthoredJson,
+  saveDraftAuthoredMarkdown,
+  loadDraftAuthoredMarkdown,
+} from "./storage.js";
+import { validateUltraPlanAuthoredArtifact } from "../contracts.js";
+
+export interface SynthGateInput {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  sessionId: string;
+  iteration: number;
+  /**
+   * Maximum number of editor re-opens after parse errors before yielding control to the
+   * caller for a manual recovery decision. Default 2 \u2014 matches the plan's two-strikes rule.
+   */
+  maxParseRetries?: number;
+}
+
+export type SynthGateResult =
+  | { status: "saved"; authored: UltraPlanAuthoredArtifact }
+  | { status: "parse-failed"; errors: AuthoredMarkdownParseError[] }
+  | { status: "no-changes"; authored: UltraPlanAuthoredArtifact }
+  | { status: "io-error"; message: string };
+
+/**
+ * Run the editor round-trip exactly once: render markdown, open editor, parse on save.
+ * Does not loop; the caller decides what to do with parse errors.
+ */
+export async function runEditorRoundTripOnce(input: SynthGateInput): Promise<SynthGateResult> {
+  const { platform, paths, cwd, sessionId, iteration } = input;
+
+  const draftJsonResult = loadDraftAuthoredJson(paths, cwd, sessionId, iteration);
+  if (!draftJsonResult.ok) {
+    return { status: "io-error", message: `Could not read draft authored.json: ${draftJsonResult.error.message}` };
+  }
+  const draftValidation = validateUltraPlanAuthoredArtifact(draftJsonResult.value);
+  if (!draftValidation.ok) {
+    return {
+      status: "io-error",
+      message: `Draft authored.json failed schema validation before editing: ${draftValidation.errors.join("; ")}`,
+    };
+  }
+  const draft = draftValidation.value;
+
+  // Step 1: render the markdown. If a markdown file already exists for this iteration (e.g.
+  // a prior round-trip left annotations), strip them so the user sees a clean file unless we
+  // are intentionally re-opening with new errors.
+  let markdown = serializeAuthoredToMarkdown(draft);
+  const previousMd = loadDraftAuthoredMarkdown(paths, cwd, sessionId, iteration);
+  if (previousMd.ok) {
+    // Use whatever content the user left in place last time, stripped of annotations.
+    markdown = stripParseErrorAnnotations(previousMd.value);
+  }
+
+  // Step 2: persist the rendered markdown so the editor opens an existing file.
+  const writeResult = saveDraftAuthoredMarkdown(paths, cwd, sessionId, iteration, markdown);
+  if (!writeResult.ok) {
+    return { status: "io-error", message: `Could not write draft markdown for editor: ${writeResult.error.message}` };
+  }
+
+  // Step 3: open in editor. openInEditor awaits the spawned process.
+  const filePath = writeResult.value;
+  await openInEditor(platform, filePath);
+
+  // Step 4: read the file back. If it didn't change, surface a no-changes result.
+  let edited: string;
+  try {
+    edited = fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    return {
+      status: "io-error",
+      message: `Could not re-read edited markdown: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const cleaned = stripParseErrorAnnotations(edited);
+  if (cleaned === markdown) {
+    return { status: "no-changes", authored: draft };
+  }
+
+  // Step 5: parse + validate.
+  const parsed = parseAuthoredFromMarkdown(cleaned);
+  if (!parsed.ok) {
+    // Re-write with annotation for the next attempt; the caller decides whether to loop.
+    const annotated = annotateParseErrors(cleaned, parsed.errors);
+    saveDraftAuthoredMarkdown(paths, cwd, sessionId, iteration, annotated);
+    return { status: "parse-failed", errors: parsed.errors };
+  }
+
+  const applied = applyAuthoredPatch(draft, parsed.patch);
+  if (!applied.ok) {
+    const errors: AuthoredMarkdownParseError[] = applied.errors.map((message) => ({ line: null, message }));
+    const annotated = annotateParseErrors(cleaned, errors);
+    saveDraftAuthoredMarkdown(paths, cwd, sessionId, iteration, annotated);
+    return { status: "parse-failed", errors };
+  }
+
+  // Step 6: persist the merged authored.json. The planner-original snapshot at
+  // `authored.planner.json` is preserved (the synth-stage tool wrote it before this gate
+  // ran) so we can always compare what shipped vs. what the planner emitted.
+  const persisted = saveDraftAuthoredJson(paths, cwd, sessionId, iteration, applied.value);
+  if (!persisted.ok) {
+    return { status: "io-error", message: `Could not save merged authored.json: ${persisted.error.message}` };
+  }
+
+  // Re-write the markdown without annotations so the next opening is clean.
+  saveDraftAuthoredMarkdown(paths, cwd, sessionId, iteration, cleaned);
+
+  return { status: "saved", authored: applied.value };
+}
+
+/**
+ * Run the editor round-trip in a bounded retry loop. After `maxParseRetries` consecutive
+ * parse failures, returns the most recent failure for the caller to decide on a manual
+ * recovery path.
+ */
+export async function runSynthGateLoop(input: SynthGateInput): Promise<SynthGateResult> {
+  const maxRetries = input.maxParseRetries ?? 2;
+  let lastFailure: SynthGateResult | null = null;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    const result = await runEditorRoundTripOnce(input);
+    if (result.status === "saved" || result.status === "no-changes" || result.status === "io-error") {
+      return result;
+    }
+    // parse-failed
+    lastFailure = result;
+  }
+  return lastFailure ?? { status: "io-error", message: "synth gate exhausted retries without producing a result" };
+}