@warpgogol/forge 5.2.3 → 5.3.0

package/src/onboarding/agents-generate.ts

@@ -2,7 +2,7 @@
 <MODULE_CONTRACT>
 <purpose>forge.agents.generate — regenerates AGENTS.md deterministically from forge.yaml + skill registry. Carries the standard generated-file marker.</purpose>
 <non-goals>
-  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — refuse with exit 1.</item>
+  <item>Do not overwrite a hand-written AGENTS.md (no generated marker) — skip with warning, continue nested (RFC-1150).</item>
   <item>Do not read or modify forge.yaml — only read it via loadForgeConfig.</item>
 </non-goals>
 </MODULE_CONTRACT>
@@ -20,13 +20,14 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
+import { resolveIo } from "../utils/io.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { loadForgeConfig, resolveBinding, resolveForgePackageRoot, resolveForgeRoot } from "../config/forge-config.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 import { FORGE_SKILLS } from "../registry.ts";
-import { buildGeneratedHeader, hasGeneratedMarker, writeFileIfChanged } from "../utils/index.ts";
+import { alignMarkdownTable, buildGeneratedHeader, hasEditableGeneratedMarker, hasGeneratedMarker, mergeEditableGenerated, writeFileIfChanged } from "../utils/index.ts";
 import { generateNestedAgentsMd } from "./nested-agents-generate.ts";
 import { listStackProfiles } from "../profiles/stack-profile.ts";
 import type { StackProfile } from "../profiles/stack-profile.ts";
@@ -140,9 +141,11 @@ function readRegister(workspaceRoot: string): BehavioralRegister {
   return "business";
 }
 
-function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers: string[] }> {
+function extractTriggerPhrases(
+  workspaceRoot: string,
+): Array<{ name: string; triggerPhrases: string[] }> {
   const forgeRoot = path.join(workspaceRoot, "packages", "forge");
-  const result: Array<{ name: string; triggers: string[] }> = [];
+  const result: Array<{ name: string; triggerPhrases: string[] }> = [];
   for (const skill of FORGE_SKILLS) {
     if (skill.category !== "fo") continue;
     const skillPath = path.join(forgeRoot, skill.path);
@@ -151,10 +154,12 @@ function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers:
       const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
       if (!fmMatch) continue;
       const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
-      if (Array.isArray(fm["triggers"])) {
+      if (Array.isArray(fm["triggerPhrases"])) {
         result.push({
           name: skill.name,
-          triggers: (fm["triggers"] as unknown[]).filter((v): v is string => typeof v === "string"),
+          triggerPhrases: (fm["triggerPhrases"] as unknown[]).filter(
+            (v): v is string => typeof v === "string",
+          ),
         });
       }
     } catch {
@@ -164,21 +169,28 @@ function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers:
   return result;
 }
 
-function generateTriggersTable(triggers: Array<{ name: string; triggers: string[] }>): string {
-  const rows: string[] = [];
-  for (const { name, triggers: skillTriggers } of triggers) {
+// RFC-1154: emits the full aligned table (header + separator + rows) since
+// column widths depend on substituted trigger rows — the template carries only
+// the {{triggersTable}} placeholder, no static header lines.
+function generateTriggersTable(
+  triggerPhrases: Array<{ name: string; triggerPhrases: string[] }>,
+): string {
+  const rows: string[][] = [];
+  for (const { name, triggerPhrases: skillTriggers } of triggerPhrases) {
     if (skillTriggers.length === 0) continue;
     const display = skillTriggers.map((t) => `"${t}"`).join(", ");
-    rows.push(`| ${display} | \`${name}\` |`);
+    rows.push([display, `\`${name}\``]);
   }
-  return rows.length > 0 ? rows.join("\n") + "\n" : "";
+  // Always emit the header + separator — even with zero trigger rows the
+  // section documents the routing contract (matches pre-RFC-1154 behavior).
+  return alignMarkdownTable(["Operator says something like", "Skill"], rows) + "\n";
 }
 
 function generateBehavioralLayer(
   workspaceRoot: string,
   register: BehavioralRegister,
 ): string {
-  const triggers = extractTriggers(workspaceRoot);
+  const triggerPhrases = extractTriggerPhrases(workspaceRoot);
 
   let template: string;
   try {
@@ -187,7 +199,7 @@ function generateBehavioralLayer(
     return "";
   }
 
-  const triggersTable = generateTriggersTable(triggers);
+  const triggersTable = generateTriggersTable(triggerPhrases);
 
   let extendedLayer = "";
   if (register === "creative") {
@@ -215,6 +227,9 @@ interface AgentsGenerateResult {
   errors: string[];
   renderedFiles?: { [relPath: string]: string };
   details?: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }>;
+  // RFC-1150: set when the root AGENTS.md was skipped (hand-written, no marker)
+  rootSkipped?: boolean;
+  rootSkipReason?: string;
 }
 
 export async function runAgentsGenerate(
@@ -222,6 +237,7 @@ export async function runAgentsGenerate(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<AgentsGenerateResult>> {
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
 
   let config;
   try {
@@ -247,26 +263,18 @@ export async function runAgentsGenerate(
 
   const agentsMdPath = path.join(workspaceRoot, "AGENTS.md");
 
-  // Edit guard: refuse to overwrite a hand-written AGENTS.md (skipped in dryRun)
-  if (!dryRun && fs.existsSync(agentsMdPath)) {
-    const existing = fs.readFileSync(agentsMdPath, "utf8");
+  // Edit guard: never overwrite a hand-written AGENTS.md — skip the root file
+  // with a warning and continue to nested generation (RFC-1150, non-fatal).
+  let rootSkipped = false;
+  if (!dryRun && (await fio.exists(agentsMdPath))) {
+    const existing = await fio.readFile(agentsMdPath);
     if (!hasGeneratedMarker(existing)) {
-      const msg = `AGENTS.md exists without a generated marker — refusing to overwrite a hand-written file. Delete or rename it first, then re-run forge.agents.generate.`;
+      rootSkipped = true;
       if (outputFormat === "pretty") {
-        logger.error(msg);
+        logger.warn(
+          "AGENTS.md exists without a generated marker — skipping root file (hand-written). Nested AGENTS.md generation continues.",
+        );
       }
-      return {
-        data: {
-          command: "forge.agents.generate",
-          status: "fail",
-          configPath: "forge.yaml",
-          generated: [],
-          skipped: [],
-          errors: [msg],
-        },
-        exitCode: 1,
-        summary: `forge.agents.generate: failed — hand-written AGENTS.md`,
-      };
     }
   }
 
@@ -284,14 +292,15 @@ export async function runAgentsGenerate(
   // Build dynamic sections (skills table, capabilities, behavioral layer)
   const dynamicLines: string[] = [];
 
-  // Skills table
+  // Skills table (RFC-1154: emitted prettier-normal via alignMarkdownTable)
   dynamicLines.push("## Skills");
   dynamicLines.push("");
-  dynamicLines.push("| Name | Category | Invocation | Concerns |");
-  dynamicLines.push("| --- | --- | --- | --- |");
-  for (const skill of FORGE_SKILLS) {
-    dynamicLines.push(`| ${skill.name} | ${skill.category} | ${skill.invocation} | ${skill.concerns} |`);
-  }
+  dynamicLines.push(
+    alignMarkdownTable(
+      ["Name", "Category", "Invocation", "Concerns"],
+      FORGE_SKILLS.map((skill) => [skill.name, skill.category, skill.invocation, skill.concerns]),
+    ),
+  );
   dynamicLines.push("");
 
   // Capabilities section (RFC-0393)
@@ -300,8 +309,6 @@ export async function runAgentsGenerate(
     dynamicLines.push("");
     dynamicLines.push("Bindings resolved from `forge.yaml`:");
     dynamicLines.push("");
-    dynamicLines.push("| Key | Status | Value |");
-    dynamicLines.push("| --- | --- | --- |");
 
     const bindingKeys = [
       "commands.validateRfc",
@@ -317,21 +324,23 @@ export async function runAgentsGenerate(
       "paths.sessionsDir",
     ];
 
-    for (const key of bindingKeys) {
+    const capabilityRows: string[][] = bindingKeys.map((key) => {
       const value = resolveBinding(config, key);
       const status = value === null ? "absent" : "resolved";
       const display = value === null ? "—" : typeof value === "string" ? `\`${value}\`` : String(value);
-      dynamicLines.push(`| ${key} | ${status} | ${display} |`);
-    }
+      return [key, status, display];
+    });
 
     // compassDocs array
     const compassDocs = resolveBinding(config, "paths.compassDocs");
     if (Array.isArray(compassDocs) && compassDocs.length > 0) {
-      dynamicLines.push(`| paths.compassDocs | resolved | ${compassDocs.map((d) => `\`${d}\``).join(", ")} |`);
+      capabilityRows.push(["paths.compassDocs", "resolved", compassDocs.map((d) => `\`${d}\``).join(", ")]);
     } else {
-      dynamicLines.push(`| paths.compassDocs | absent | — |`);
+      capabilityRows.push(["paths.compassDocs", "absent", "—"]);
     }
 
+    dynamicLines.push(alignMarkdownTable(["Key", "Status", "Value"], capabilityRows));
+
     // terminology
     if (config.bindings.terminology && Object.keys(config.bindings.terminology).length > 0) {
       dynamicLines.push("");
@@ -371,7 +380,7 @@ export async function runAgentsGenerate(
   const resolvedTerminology = resolveAllTerminology(config, profile);
   content = substituteTemplate(content, resolvedTerminology);
 
-  const generated: string[] = ["AGENTS.md"];
+  const generated: string[] = [];
   const skipped: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};
   const details: Array<{ path: string; domain?: string; register?: string; workspaceType?: string }> = [];
@@ -383,10 +392,41 @@ export async function runAgentsGenerate(
 
   if (dryRun) {
     renderedFiles["AGENTS.md"] = content;
+    generated.push("AGENTS.md");
+  } else if (rootSkipped) {
+    skipped.push("AGENTS.md (hand-written)");
   } else {
-    await writeFileIfChanged(agentsMdPath, content);
-    if (outputFormat === "pretty") {
-      logger.success(`Generated ${path.relative(workspaceRoot, agentsMdPath)}`);
+    // RFC-1153: merge instead of overwrite — preserve the custom tail below
+    // the forge:custom boundary; fail-closed skip when no boundary resolves.
+    let existing: string | null = null;
+    if (await fio.exists(agentsMdPath)) {
+      try {
+        existing = await fio.readFile(agentsMdPath);
+      } catch {
+        // Unreadable — treat as absent; merge will emit a fresh file.
+      }
+    }
+    let merged = mergeEditableGenerated(content, existing, "AGENTS.md");
+    if (merged === null) {
+      if (existing !== null && !hasEditableGeneratedMarker(existing)) {
+        // RFC-0081/RFC-1153: restrictive-marker file is fully generator-owned —
+        // upgrade it to the editable boundary contract (fresh render + marker).
+        merged = mergeEditableGenerated(content, null, "AGENTS.md");
+      } else {
+        skipped.push("AGENTS.md (unmapped-customization)");
+        if (outputFormat === "pretty") {
+          logger.warn(
+            "AGENTS.md has custom content but no resolvable boundary — skipping root file (unmapped-customization). Add <!-- forge:custom --> to set the boundary.",
+          );
+        }
+      }
+    }
+    if (merged !== null) {
+      await writeFileIfChanged(agentsMdPath, merged, fio);
+      generated.push("AGENTS.md");
+      if (outputFormat === "pretty") {
+        logger.success(`Generated ${path.relative(workspaceRoot, agentsMdPath)}`);
+      }
     }
   }
 
@@ -411,7 +451,7 @@ export async function runAgentsGenerate(
       // forge root not resolvable — fallback to hardcoded detection
     }
   }
-  const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes);
+  const nestedResult = await generateNestedAgentsMd(workspaceRoot, config, dryRun, workspaceTypes, fio);
   generated.push(...nestedResult.generated);
   skipped.push(...nestedResult.skipped);
   Object.assign(renderedFiles, nestedResult.renderedFiles);
@@ -443,11 +483,12 @@ export async function runAgentsGenerate(
       skipped,
       errors: [],
       details,
+      ...(rootSkipped ? { rootSkipped: true, rootSkipReason: "hand-written" } : {}),
       ...(dryRun ? { renderedFiles } : {}),
     },
     exitCode: 0,
     summary: dryRun
       ? `forge.agents.generate: [dry-run] would generate ${generated.length} file(s), skip ${skipped.length}`
-      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped`,
+      : `forge.agents.generate: OK — ${generated.length} file(s) generated, ${skipped.length} skipped${rootSkipped ? " (root AGENTS.md hand-written — skipped)" : ""}`,
   };
 }

package/src/onboarding/create.ts

@@ -22,9 +22,8 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { resolveIo } from "../utils/io.ts";
 import { stringify as stringifyYaml } from "yaml";
 import { runScaffoldProject } from "./scaffold-project.ts";
 import { runInit, type InitResult, type InitDomainFields } from "./init.ts";
@@ -127,6 +126,7 @@ export async function runCreate(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<CreateCommandResult>> {
   const { logger, outputFormat } = context;
+  const fio = resolveIo(context.io);
   const inPlace = input.flags["in-place"] as boolean | undefined;
   const nameOverride = input.flags["name"] as string | undefined;
   const profile = input.flags["profile"] as string | undefined;
@@ -217,7 +217,7 @@ export async function runCreate(
   // If any other files or directories exist, refuse to scaffold.
   let dirEntries: string[];
   try {
-    dirEntries = fs.readdirSync(targetDir);
+    dirEntries = (await fio.readdir(targetDir)).map((e) => e.name);
   } catch {
     dirEntries = [];
   }
@@ -240,13 +240,13 @@ export async function runCreate(
   // This is a hard guard — forge.create programmatically ensures main branch,
   // so greenfield projects don't depend on the agent running git init correctly.
   const gitDir = path.join(targetDir, ".git");
-  if (!fs.existsSync(gitDir)) {
-    try {
-      execFileSync("git", ["init", "--initial-branch=main"], { cwd: targetDir, stdio: "pipe" });
+  if (!(await fio.exists(gitDir))) {
+    const gitInit = await fio.exec("git", ["init", "--initial-branch=main"], { cwd: targetDir });
+    if (gitInit.exitCode === 0) {
       if (outputFormat === "pretty") {
         logger.info("Initialized git repository with main branch");
       }
-    } catch {
+    } else {
       if (outputFormat === "pretty") {
         logger.warn("Failed to initialize git repository — run 'git init --initial-branch=main' manually");
       }
@@ -344,7 +344,7 @@ export async function runCreate(
   // 11. Post-process forge.yaml if --package-manager differs from default
   if (packageManager !== "pnpm") {
     const forgeYamlPath = path.join(targetDir, "forge.yaml");
-    if (fs.existsSync(forgeYamlPath)) {
+    if (await fio.exists(forgeYamlPath)) {
       try {
         const config = loadForgeConfig(targetDir);
         const pm = resolvePackageManager(packageManager);
@@ -354,7 +354,7 @@ export async function runCreate(
         }
         // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
         // never the resolved StackProfile object, never drops an unresolvable id.
-        fs.writeFileSync(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)), "utf8");
+        await fio.writeFile(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)));
       } catch {
         // Post-processing is best-effort — init already wrote a valid config
       }
@@ -417,7 +417,7 @@ If you already have a project elsewhere and want to move it into Forge, tell the
 
 The system will guide you through the process — it detects your project type, migrates the code (including \`.env\` and git-ignored files), optionally transfers git history, and verifies the build.
 `;
-  fs.writeFileSync(nextStepsPath, nextStepsContent, "utf8");
+  await fio.writeFile(nextStepsPath, nextStepsContent);
 
   // 14. Collect filesCreated
   const filesCreated = [