@warpgogol/forge 5.3.4 → 6.2.0

package/os/spec/live-spec-merge.ts

@@ -2,185 +2,51 @@
 <MODULE_CONTRACT>
 <purpose>spec.live.merge handler — extracts deltas from an RFC's ## Design section,
 classifies them as ADDED/MODIFIED/REMOVED, applies to a living spec with RFC-namespaced
-headings, and writes atomically (RFC-0711).</purpose>
+headings, and writes atomically (RFC-0711). Idempotent since RFC-1230: an RFC already
+present in spec history[] is skipped as already-merged unless --force re-merges it.</purpose>
 <non-goals>
   <item>Do not handle docs.archive integration — that is in core.module.ts.</item>
   <item>Do not validate living specs — that is spec.live.validate.</item>
+  <item>Do not repair corrupted specs — that is spec.live.rebuild.</item>
 </non-goals>
-</MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0711: initial spec.live.merge handler with delta extraction, classification, and atomic writes.</item>
   <item>RFC-0957: namespace headings by RFC ID, remove conflict detection (structurally impossible with namespacing).</item>
+  <item>RFC-1230: idempotent merge — already-merged gate keyed on spec history[], --force surgical re-merge via removeNamespacedSections, fail-fast on spec file with unparseable frontmatter; pure helpers moved to live-spec-shared.ts.</item>
+  <item>RFC-1230: review findings — scoped droppedSections to namespaced headings, warn on unreadable spec, fail-fast merge on corrupt frontmatter, CHANGE_SUMMARY dedupe</item>
 </CHANGE_SUMMARY>
 */
 
 import { ambientIo as fs } from "../../src/utils/io.ts";
 import { existsSync } from "../../src/utils/sync-fs.ts";
 import path from "node:path";
-import YAML from "yaml";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
   ForgeRuntimeContext,
 } from "../../src/types.ts";
 import { writeFileIfChanged, buildGeneratedHeader } from "../../src/utils/index.ts";
-import { parseRfcFile, listRfcFiles } from "../rfc/frontmatter-io.ts";
+import { parseRfcFile } from "../rfc/frontmatter-io.ts";
 import { RFC_DIR } from "../rfc/types.ts";
 import type {
   LivingSpec,
-  LivingSpecHistoryEntry,
   DeltaOperation,
   SpecLiveMergeResult,
 } from "./live-spec-types.ts";
-
-const LIVE_SPECS_DIR = "docs/specs/live";
-
-interface ParsedHeading {
-  level: number;
-  text: string;
-  body: string;
-}
-
-function extractDesignSection(rfcBody: string): string {
-  const designMatch = rfcBody.match(/^##\s+Design\s*$/m);
-  if (!designMatch) return "";
-  const startIndex = designMatch.index! + designMatch[0].length;
-  const nextH2Match = rfcBody.slice(startIndex).match(/^##\s+/m);
-  if (!nextH2Match) {
-    return rfcBody.slice(startIndex).trim();
-  }
-  return rfcBody.slice(startIndex, startIndex + nextH2Match.index!).trim();
-}
-
-function parseHeadings(content: string): ParsedHeading[] {
-  const lines = content.split("\n");
-  const headings: ParsedHeading[] = [];
-  let currentHeading: ParsedHeading | null = null;
-  let currentBody: string[] = [];
-
-  for (const line of lines) {
-    const headingMatch = line.match(/^(#{3,})\s+(.+)$/);
-    if (headingMatch) {
-      if (currentHeading) {
-        currentHeading.body = currentBody.join("\n").trim();
-        headings.push(currentHeading);
-      }
-      currentHeading = {
-        level: headingMatch[1].length,
-        text: headingMatch[2].trim(),
-        body: "",
-      };
-      currentBody = [];
-    } else if (currentHeading) {
-      currentBody.push(line);
-    }
-  }
-  if (currentHeading) {
-    currentHeading.body = currentBody.join("\n").trim();
-    headings.push(currentHeading);
-  }
-  return headings;
-}
-
-function deriveDomain(frontmatter: Record<string, unknown>): string | null {
-  const liveSpec = frontmatter["liveSpec"];
-  if (typeof liveSpec === "string" && liveSpec.length > 0) {
-    return liveSpec;
-  }
-  if (liveSpec === true) {
-    const packagesImpacted = frontmatter["packagesImpacted"];
-    if (Array.isArray(packagesImpacted) && packagesImpacted.length > 0) {
-      const firstPkg = String(packagesImpacted[0]);
-      return firstPkg.replace(/^packages\//, "").replace(/^@[^/]+\//, "");
-    }
-    return null;
-  }
-  return null;
-}
-
-function parseLivingSpec(content: string): LivingSpec | null {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!match) return null;
-  const fm = (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>;
-  return {
-    domain: String(fm["domain"] ?? ""),
-    title: String(fm["title"] ?? ""),
-    lastMergedRfc: String(fm["lastMergedRfc"] ?? ""),
-    updatedAt: String(fm["updatedAt"] ?? ""),
-    createdAt: String(fm["createdAt"] ?? ""),
-    history: (Array.isArray(fm["history"]) ? fm["history"] : []) as LivingSpecHistoryEntry[],
-    body: match[2] ?? "",
-  };
-}
-
-function serializeLivingSpec(spec: LivingSpec): string {
-  const fm: Record<string, unknown> = {
-    domain: spec.domain,
-    title: spec.title,
-    lastMergedRfc: spec.lastMergedRfc,
-    updatedAt: spec.updatedAt,
-    createdAt: spec.createdAt,
-    history: spec.history,
-  };
-  const fmStr = YAML.stringify(fm).trimEnd();
-  return `---\n${fmStr}\n---\n\n${spec.body}`;
-}
-
-function findHeadingInSpec(spec: LivingSpec, headingText: string): ParsedHeading | null {
-  const headings = parseHeadings(spec.body);
-  return headings.find((h) => h.text === headingText) ?? null;
-}
-
-function applyDeltasToSpecBody(
-  specBody: string,
-  deltas: ParsedHeading[],
-  operations: DeltaOperation[],
-): string {
-  let body = specBody;
-  for (const delta of deltas) {
-    const op = operations.find((o) => o.heading === delta.text);
-    if (!op) continue;
-
-    if (op.type === "added") {
-      body = `${body}\n\n${"#".repeat(delta.level)} ${delta.text}\n\n${delta.body}`;
-    } else if (op.type === "modified") {
-      const headingRegex = new RegExp(
-        `(${"#".repeat(delta.level)}\\s+${escapeRegex(delta.text)}\\s*\\n)([\\s\\S]*?)(?=#{3,}|$)`,
-      );
-      body = body.replace(headingRegex, `$1\n${delta.body}\n`);
-    } else if (op.type === "removed") {
-      const headingRegex = new RegExp(
-        `\\n*${"#".repeat(delta.level)}\\s+${escapeRegex(delta.text)}\\s*\\n[\\s\\S]*?(?=#{3,}|$)`,
-      );
-      body = body.replace(headingRegex, "\n");
-    }
-  }
-  return body.trim();
-}
-
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function namespaceHeadings(content: string, rfcId: string): string {
-  return content.replace(/^(#{3,})\s+(.+)$/gm, (_match, hashes: string, text: string) => {
-    if (/\(RFC-\d{4}\)$/.test(text)) return `${hashes} ${text}`;
-    return `${hashes} ${text} (${rfcId})`;
-  });
-}
-
-function findRfcFile(rfcDir: string, rfcId: string): Promise<string | null> {
-  return (async () => {
-    const files = await listRfcFiles(rfcDir);
-    for (const file of files) {
-      const basename = path.basename(file);
-      if (basename.toLowerCase().startsWith(rfcId.toLowerCase())) {
-        return file;
-      }
-    }
-    return null;
-  })();
-}
+import {
+  LIVE_SPECS_DIR,
+  extractDesignSection,
+  parseHeadings,
+  deriveDomain,
+  parseLivingSpec,
+  serializeLivingSpec,
+  findHeadingInSpec,
+  applyDeltasToSpecBody,
+  namespaceHeadings,
+  removeNamespacedSections,
+  findRfcFile,
+  seedSpecPrefix,
+} from "./live-spec-shared.ts";
 
 export async function runSpecLiveMerge(
   input: ForgeCommandInput,
@@ -188,6 +54,7 @@ export async function runSpecLiveMerge(
 ): Promise<ForgeCommandResult<SpecLiveMergeResult>> {
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcId = String(input.flags["id"] ?? "");
+  const force = input.flags["force"] === true;
   const dryRun = context.dryRun || input.flags["dry-run"] === true;
 
   if (!rfcId) {
@@ -284,6 +151,55 @@ export async function runSpecLiveMerge(
   if (existsSync(specFilePath)) {
     const specContent = await fs.readFile(specFilePath);
     existingSpec = parseLivingSpec(specContent);
+    // A spec file whose frontmatter cannot be parsed must not be silently
+    // overwritten by the creation path — that would discard its history[].
+    if (!existingSpec) {
+      return {
+        data: {
+          command: "spec.live.merge",
+          domain,
+          operation: "modified",
+          deltas: [],
+          conflicts: [],
+          dryRun,
+        },
+        exitCode: 1,
+        summary: `spec.live.merge: ${domain}.md exists but has no valid frontmatter — inspect or repair via spec.live.rebuild`,
+      };
+    }
+  }
+
+  // RFC-1230: idempotency gate — an RFC already in history[] is a no-op unless
+  // --force surgically re-merges (strips its namespaced sections + old entries).
+  if (existingSpec) {
+    const alreadyMerged = existingSpec.history.some((h) => h.rfc === rfcId);
+    if (alreadyMerged && !force) {
+      const result: SpecLiveMergeResult = {
+        command: "spec.live.merge",
+        domain,
+        operation: "already-merged",
+        deltas: [],
+        conflicts: [],
+        dryRun,
+      };
+      if (outputFormat === "pretty") {
+        logger.info(
+          `spec.live.merge: ${rfcId} already merged into "${domain}" — skipping (use --force to re-merge)`,
+        );
+      }
+      return {
+        data: result,
+        exitCode: 0,
+        summary: `spec.live.merge: ${rfcId} already merged into ${domain}`,
+      };
+    }
+    if (force) {
+      existingSpec = {
+        ...existingSpec,
+        body: removeNamespacedSections(existingSpec.body, rfcId),
+        history: existingSpec.history.filter((h) => h.rfc !== rfcId),
+      };
+    }
   }
 
   const operations: DeltaOperation[] = [];
@@ -307,7 +223,7 @@ export async function runSpecLiveMerge(
       updatedAt: today,
       createdAt: today,
       history: [{ rfc: rfcId, mergedAt: today, operation: "created" }],
-      body: `${header}# Living Spec: ${domain}\n\n## Overview\n\n${designSection}`,
+      body: `${seedSpecPrefix(domain, header)}${designSection}`,
     };
 
     if (!dryRun) {

package/os/spec/live-spec-rebuild.test.ts

@@ -0,0 +1,317 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for spec.live.rebuild handler — dedup-replay of history[],
+unreadable-RFC tolerance, unchanged/skipped operations, dry-run (RFC-1230).</purpose>
+<non-goals>
+  <item>Do not test spec.live.merge — covered by live-spec-merge.test.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1230: initial unit tests for spec.live.rebuild.</item>
+  <item>RFC-1230: review findings — scoped droppedSections to namespaced headings, warn on unreadable spec, fail-fast merge on corrupt frontmatter, CHANGE_SUMMARY dedupe</item>
+  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag
+
+Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
+follows the parsed selector. Guard renamed assertAllSitesAllowed ->
+assertAllFlagAccepted, message updated. 417 declaration sites + type
+surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { runSpecLiveMerge } from "./live-spec-merge.ts";
+import { runSpecLiveRebuild } from "./live-spec-rebuild.ts";
+import { removeNamespacedSections } from "./live-spec-shared.ts";
+import type { ForgeRuntimeContext } from "../../src/types.ts";
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      section: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      success: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+function rfcFixture(id: string, extraFrontmatter = "", designBody = "### Heading A\n\nBody.") {
+  return `---
+id: ${id}
+title: "Test RFC ${id}"
+status: implemented
+kind: architecture
+scope: workspace
+owners:
+  - architecture
+reviewers:
+  - human:test
+createdAt: 2026-08-06
+updatedAt: 2026-08-06
+implementedAt: 2026-08-06
+versionBump: patch
+liveSpec: true
+packagesImpacted:
+  - packages/forge${extraFrontmatter}
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# ${id}: Test RFC
+
+## Design
+
+${designBody}
+
+## Rollout
+
+Done.
+`;
+}
+
+async function setupWorkspace(): Promise<string> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-rebuild-"));
+  const rfcDir = path.join(tmpDir, "docs/rfcs");
+  await fs.mkdir(rfcDir, { recursive: true });
+  await fs.writeFile(
+    path.join(rfcDir, "rfc-9001-first.md"),
+    rfcFixture("RFC-9001", "", "### CLI surface\n\ncli body.\n\n### Types\n\ntypes body."),
+  );
+  await fs.writeFile(
+    path.join(rfcDir, "rfc-9004-second.md"),
+    rfcFixture("RFC-9004", "", "### Other\n\nother body."),
+  );
+  // RFC-9006 exists but lacks ## Design — exercises the unreadable/skip path.
+  await fs.writeFile(
+    path.join(rfcDir, "rfc-9006-no-design.md"),
+    rfcFixture("RFC-9006").replace("## Design\n\n### Heading A\n\nBody.", "## Context\n\nNo design here."),
+  );
+  return tmpDir;
+}
+
+async function cleanupWorkspace(tmpDir: string): Promise<void> {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+}
+
+const SPEC_FILE = "docs/specs/live/forge.md";
+
+async function corruptSpec(tmpDir: string): Promise<void> {
+  const specFile = path.join(tmpDir, SPEC_FILE);
+  const corrupted = (await fs.readFile(specFile, "utf-8"))
+    .replace(
+      "### CLI surface (RFC-9001)\n\ncli body.",
+      "### CLI surface (RFC-9001)\n\ncli body.\n\n### CLI surface (RFC-9001)\n\nstale duplicate.",
+    )
+    .replace(
+      "  - rfc: RFC-9004",
+      "  - rfc: RFC-9001\n    mergedAt: 2026-08-07\n    operation: modified\n  - rfc: RFC-9004",
+    );
+  await fs.writeFile(specFile, corrupted);
+}
+
+describe("spec.live.rebuild", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await setupWorkspace();
+    // Seed a clean spec via the real merge path.
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9004" } }, makeContext(tmpDir));
+  });
+
+  afterEach(async () => {
+    await cleanupWorkspace(tmpDir);
+  });
+
+  it("repairs duplicated sections and history entries by replay (AC-4)", async () => {
+    await corruptSpec(tmpDir);
+
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data).toMatchObject({
+      command: "spec.live.rebuild",
+      domain: "forge",
+      operation: "rebuilt",
+      uniqueRfcs: 2,
+      droppedHistoryEntries: 1,
+      droppedSections: 1,
+      unreadableRfcs: [],
+    });
+
+    const content = await fs.readFile(path.join(tmpDir, SPEC_FILE), "utf-8");
+    expect(content).not.toContain("stale duplicate");
+    expect(content.match(/\(RFC-9001\)/g)?.length).toBe(2);
+    expect(content.match(/\(RFC-9004\)/g)?.length).toBe(1);
+    expect(content.match(/rfc: RFC-9001/g)?.length).toBe(1);
+    expect(content.match(/rfc: RFC-9004/g)?.length).toBe(1);
+    expect(content).toContain("lastMergedRfc: RFC-9004");
+  });
+
+  it("reports unchanged when a clean spec regenerates identically", async () => {
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data).toMatchObject({ operation: "unchanged", uniqueRfcs: 2 });
+  });
+
+  it("rebuild is idempotent — a second run after repair reports unchanged", async () => {
+    await corruptSpec(tmpDir);
+    await runSpecLiveRebuild({ argv: [], flags: { domain: "forge" } }, makeContext(tmpDir));
+    const second = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge" } },
+      makeContext(tmpDir),
+    );
+    expect(second.exitCode).toBe(0);
+    expect(second.data).toMatchObject({ operation: "unchanged" });
+  });
+
+  it("warns and continues on unreadable/missing RFCs, listing unreadableRfcs (AC-8)", async () => {
+    const specFile = path.join(tmpDir, SPEC_FILE);
+    const content = await fs.readFile(specFile, "utf-8");
+    await fs.writeFile(
+      specFile,
+      content
+        .replace(
+          "### CLI surface (RFC-9001)\n\ncli body.",
+          "### CLI surface (RFC-9001)\n\ncli body.\n\n### CLI surface (RFC-9001)\n\nstale duplicate.",
+        )
+        .replace(
+          "  - rfc: RFC-9004",
+          "  - rfc: RFC-9006\n    mergedAt: 2026-08-07\n    operation: modified\n  - rfc: RFC-9999\n    mergedAt: 2026-08-08\n    operation: modified\n  - rfc: RFC-9004",
+        ),
+    );
+
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data).toMatchObject({
+      operation: "rebuilt",
+      unreadableRfcs: ["RFC-9006", "RFC-9999"],
+    });
+
+    const after = await fs.readFile(specFile, "utf-8");
+    expect(after).toContain("rfc: RFC-9006");
+    expect(after).toContain("rfc: RFC-9999");
+    expect(after).not.toContain("(RFC-9006)");
+    expect(after).toContain("lastMergedRfc: RFC-9004");
+  });
+
+  it("writes nothing under --dry-run (AC-9)", async () => {
+    await corruptSpec(tmpDir);
+    const specFile = path.join(tmpDir, SPEC_FILE);
+    const before = await fs.readFile(specFile, "utf-8");
+
+    const ctx = makeContext(tmpDir);
+    ctx.dryRun = true;
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge", "dry-run": true } },
+      ctx,
+    );
+
+    expect(result.data).toMatchObject({ operation: "rebuilt", dryRun: true });
+    expect(await fs.readFile(specFile, "utf-8")).toBe(before);
+  });
+
+  it("defaults to all specs when no selector is given; rejects --domain + --all", async () => {
+    // Under `werkstatt run` the kernel consumes --all as its site selector —
+    // "no --domain" is therefore the all-specs signal there (acceptsAllFlag).
+    const bare = await runSpecLiveRebuild({ argv: [], flags: {} }, makeContext(tmpDir));
+    expect(bare.exitCode).toBe(0);
+    expect((bare.data as { domains: unknown[] }).domains.length).toBe(1);
+
+    const both = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge", all: true } },
+      makeContext(tmpDir),
+    );
+    expect(both.exitCode).toBe(1);
+  });
+
+  it("removeNamespacedSections removes nothing when only ### matches are fence-interior (RFC-1232 AC-3)", () => {
+    const body = [
+      "## Overview",
+      "",
+      "Some prose.",
+      "",
+      "```md",
+      "### Looks like a heading (RFC-9004)",
+      "### Also looks like one (RFC-9004)",
+      "```",
+    ].join("\n");
+    expect(removeNamespacedSections(body, "RFC-9004")).toBe(body);
+  });
+
+  it("treats content after an unterminated fence as interior (RFC-1232)", () => {
+    const body = "## Overview\n\n```\n### Hidden (RFC-9004)\n### Also hidden (RFC-9004)\n";
+    expect(removeNamespacedSections(body, "RFC-9004")).toBe(body.trim());
+  });
+
+  it("replays RFC Design containing fenced ### lines without corrupting them (RFC-1232)", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/rfcs/rfc-9007-fenced-design.md"),
+      rfcFixture(
+        "RFC-9007",
+        "",
+        "### CLI surface\n\n```sh\n### a comment inside the fence\nwerkstatt run spec.live.rebuild\n```\n",
+      ),
+    );
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9007" } }, makeContext(tmpDir));
+
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "forge" } },
+      makeContext(tmpDir),
+    );
+
+    expect(result.exitCode).toBe(0);
+    const content = await fs.readFile(path.join(tmpDir, SPEC_FILE), "utf-8");
+    expect(content).toContain("### a comment inside the fence\n");
+    expect(content).not.toContain("a comment inside the fence (RFC-9007)");
+    expect(content).toContain("### CLI surface (RFC-9007)");
+  });
+
+  it("exits 1 when --domain names a nonexistent spec", async () => {
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { domain: "nonexistent" } },
+      makeContext(tmpDir),
+    );
+    expect(result.exitCode).toBe(1);
+    expect(result.summary).toContain("not found");
+  });
+
+  it("reports skipped for a spec with empty history", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/specs/live/empty.md"),
+      `---\ndomain: empty\ntitle: "Living Spec: empty"\nlastMergedRfc: ""\nupdatedAt: 2026-08-06\ncreatedAt: 2026-08-06\nhistory: []\n---\n\n# Living Spec: empty\n\n## Overview\n`,
+    );
+    const result = await runSpecLiveRebuild(
+      { argv: [], flags: { all: true } },
+      makeContext(tmpDir),
+    );
+    expect(result.exitCode).toBe(0);
+    const domains = (result.data as { domains: Array<{ domain: string; operation: string }> }).domains;
+    expect(domains.find((d) => d.domain === "empty")?.operation).toBe("skipped");
+    expect(domains.find((d) => d.domain === "forge")?.operation).toBe("unchanged");
+  });
+});