@warpgogol/forge 5.2.4 → 5.3.1

package/src/onboarding/agents-generate.ts

@@ -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,23 @@ function readRegister(workspaceRoot: string): BehavioralRegister {
   return "business";
 }
 
-function extractTriggers(workspaceRoot: string): Array<{ name: string; triggers: string[] }> {
-  const forgeRoot = path.join(workspaceRoot, "packages", "forge");
-  const result: Array<{ name: string; triggers: string[] }> = [];
+/** resolveForgeRoot throws when neither layout exists — routing-table
+ *  extraction is best-effort, so an unresolvable root yields an empty table. */
+function safeResolveForgeRoot(workspaceRoot: string): string | undefined {
+  try {
+    return resolveForgeRoot(workspaceRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+function extractTriggerPhrases(
+  forgeRoot: string | undefined,
+): Array<{ name: string; triggerPhrases: string[] }> {
+  // Consumer packages have no packages/forge — the root must come from the
+  // runtime context (or the installed package), never a hardcoded monorepo path.
+  if (!forgeRoot) return [];
+  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 +166,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 +181,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,
+  forgeRoot: string | undefined,
 ): string {
-  const triggers = extractTriggers(workspaceRoot);
+  const triggerPhrases = extractTriggerPhrases(forgeRoot);
 
   let template: string;
   try {
@@ -187,7 +211,7 @@ function generateBehavioralLayer(
     return "";
   }
 
-  const triggersTable = generateTriggersTable(triggers);
+  const triggersTable = generateTriggersTable(triggerPhrases);
 
   let extendedLayer = "";
   if (register === "creative") {
@@ -225,6 +249,7 @@ export async function runAgentsGenerate(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<AgentsGenerateResult>> {
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
 
   let config;
   try {
@@ -253,8 +278,8 @@ export async function runAgentsGenerate(
   // 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 && fs.existsSync(agentsMdPath)) {
-    const existing = fs.readFileSync(agentsMdPath, "utf8");
+  if (!dryRun && (await fio.exists(agentsMdPath))) {
+    const existing = await fio.readFile(agentsMdPath);
     if (!hasGeneratedMarker(existing)) {
       rootSkipped = true;
       if (outputFormat === "pretty") {
@@ -279,14 +304,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)
@@ -295,8 +321,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",
@@ -312,21 +336,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("");
@@ -341,7 +367,10 @@ export async function runAgentsGenerate(
   }
 
   // Behavioral layer section (RFC-0548)
-  const behavioralLayer = generateBehavioralLayer(workspaceRoot, register);
+  const behavioralLayer = generateBehavioralLayer(
+    register,
+    context.forgeRoot ?? safeResolveForgeRoot(workspaceRoot),
+  );
   dynamicLines.push(behavioralLayer);
   dynamicLines.push("");
 
@@ -382,10 +411,37 @@ export async function runAgentsGenerate(
   } else if (rootSkipped) {
     skipped.push("AGENTS.md (hand-written)");
   } else {
-    await writeFileIfChanged(agentsMdPath, content);
-    generated.push("AGENTS.md");
-    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)}`);
+      }
     }
   }
 
@@ -410,7 +466,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);

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 = [