@warpgogol/forge 5.2.4 → 5.3.1

package/src/onboarding/nested-agents-templates.ts

@@ -19,13 +19,13 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { buildGeneratedHeader } from "../utils/index.ts";
+import { alignMarkdownTable, buildGeneratedHeader } from "../utils/index.ts";
 import { resolveForgePackageRoot } from "../config/forge-config.ts";
 import type { ForgeConfig } from "../config/forge-config.ts";
 import type { WorkspaceDir, WorkspaceType } from "./workspace-discovery.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
 import type { StackProfile } from "../profiles/stack-profile.ts";
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 
 export interface PackageInfo {
@@ -99,11 +99,13 @@ function buildScriptsTable(scripts: Record<string, string> | undefined): string[
   const lines: string[] = [];
   lines.push("## Scripts");
   lines.push("");
-  lines.push("| Script | Command |");
-  lines.push("| --- | --- |");
-  for (const [name, cmd] of Object.entries(scripts)) {
-    lines.push(`| \`${name}\` | \`${cmd}\` |`);
-  }
+  // RFC-1154: emitted prettier-normal via alignMarkdownTable
+  lines.push(
+    alignMarkdownTable(
+      ["Script", "Command"],
+      Object.entries(scripts).map(([name, cmd]) => [`\`${name}\``, `\`${cmd}\``]),
+    ),
+  );
   lines.push("");
   return lines;
 }
@@ -222,12 +224,16 @@ export function buildNestedAgentsMd(
     if (entryPoints.length > 0) {
       lines.push("## Entry points");
       lines.push("");
-      lines.push("| Entry point | Module |");
-      lines.push("| --- | --- |");
-      for (const ep of entryPoints) {
-        const suffix = ep.name === "." ? "" : ep.name.replace(/^\.\//, "/");
-        lines.push(`| \`${displayName}${suffix}\` | \`${ep.module}\` |`);
-      }
+      // RFC-1154: emitted prettier-normal via alignMarkdownTable
+      lines.push(
+        alignMarkdownTable(
+          ["Entry point", "Module"],
+          entryPoints.map((ep) => {
+            const suffix = ep.name === "." ? "" : ep.name.replace(/^\.\//, "/");
+            return [`\`${displayName}${suffix}\``, `\`${ep.module}\``];
+          }),
+        ),
+      );
       lines.push("");
     }
   }

package/src/onboarding/npm-token-check.ts

@@ -11,8 +11,8 @@
 </CHANGE_SUMMARY>
 */
 
-import { execSync } from "node:child_process";
-import fs from "node:fs";
+import { execSync } from "../utils/sync-fs.ts";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 
 /** Result of the npm-token probe (RFC-1125). */

package/src/onboarding/prettierignore.ts

@@ -0,0 +1,263 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1154: managed `.prettierignore` block for forge-owned generated paths.
+planPrettierignore detects whether a consumer project uses prettier (root
+config file, package.json key, or existing .prettierignore) and computes the
+delimited block entries — forge-synced skill dirs plus generated-artifact
+globs. applyPrettierignore reconciles the block idempotently via
+writeFileIfChanged; everything outside the delimited markers stays
+operator-owned.
+</purpose>
+<non-goals>
+  <item>Do not detect prettier outside the project root — nested-only configs are out of scope (documented limitation).</item>
+  <item>Do not touch consumer entries outside the delimited block — the rest of the file is operator-owned.</item>
+  <item>Do not list unmarked skill dirs — .agents/skills entries come from .forge-managed markers only (AC-9).</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>Skill entries enumerate dirs carrying a .forge-managed marker — block membership equals the forge-owned set.</item>
+  <item>Unbalanced markers treat the file as operator-owned; a fresh block is appended, never merged.</item>
+</KEY_DECISIONS>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial implementation — plan/apply + delimited-block reconcile.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import type { WorkspaceIO } from "../types.ts";
+import { resolveIo } from "../utils/io.ts";
+import { writeFileIfChanged } from "../utils/fs-idempotent.ts";
+import { fileExists } from "../utils/fs.ts";
+import * as sfs from "../utils/sync-fs.ts";
+import { SKILL_MARKER_FILE } from "./skill-markers.ts";
+
+export const PRETTIERIGNORE_BLOCK_BEGIN = "# forge-managed generated paths (RFC-1154)";
+export const PRETTIERIGNORE_BLOCK_END = "# end forge-managed";
+
+/** Prettier config files probed at the project root (root-only detection). */
+const PRETTIER_CONFIG_NAMES = [
+  ".prettierrc",
+  ".prettierrc.json",
+  ".prettierrc.yml",
+  ".prettierrc.yaml",
+  ".prettierrc.js",
+  ".prettierrc.cjs",
+  ".prettierrc.mjs",
+  ".prettierrc.toml",
+  "prettier.config.js",
+  "prettier.config.cjs",
+  "prettier.config.mjs",
+  "prettier.config.ts",
+];
+
+/** Non-skill generated-artifact entries, in stable order. */
+const FIXED_ENTRIES = [
+  "**/*.generated.yaml",
+  "docs/sessions/",
+  "docs/metrics/",
+  "docs/queues/session-*.yaml",
+];
+
+export interface PrettierignorePlan {
+  applies: boolean; // consumer uses prettier
+  entries: string[]; // resolved ignore entries for this workspace
+  fileExists: boolean;
+}
+
+export type PrettierignoreResult = "written" | "updated" | "unchanged" | "skipped";
+
+function packageJsonUsesPrettier(pkg: Record<string, unknown>): boolean {
+  if (typeof pkg["prettier"] !== "undefined") return true;
+  for (const depKey of ["dependencies", "devDependencies"]) {
+    const deps = pkg[depKey];
+    if (deps && typeof deps === "object" && "prettier" in deps) return true;
+  }
+  return false;
+}
+
+async function detectPrettier(workspaceRoot: string, io: WorkspaceIO): Promise<boolean> {
+  for (const name of PRETTIER_CONFIG_NAMES) {
+    if (await io.exists(path.join(workspaceRoot, name))) return true;
+  }
+  const pkgPath = path.join(workspaceRoot, "package.json");
+  if (await io.exists(pkgPath)) {
+    try {
+      if (packageJsonUsesPrettier(JSON.parse(await io.readFile(pkgPath)))) return true;
+    } catch {
+      // Unreadable package.json — other probes still apply
+    }
+  }
+  return fileExists(path.join(workspaceRoot, ".prettierignore"));
+}
+
+// Sync twin for runInit (sync call path — no WorkspaceIO).
+function detectPrettierSync(workspaceRoot: string): boolean {
+  for (const name of PRETTIER_CONFIG_NAMES) {
+    if (sfs.existsSync(path.join(workspaceRoot, name))) return true;
+  }
+  const pkgPath = path.join(workspaceRoot, "package.json");
+  if (sfs.existsSync(pkgPath)) {
+    try {
+      if (packageJsonUsesPrettier(JSON.parse(sfs.readFileSync(pkgPath, "utf8")))) return true;
+    } catch {
+      // Unreadable package.json — other probes still apply
+    }
+  }
+  return sfs.existsSync(path.join(workspaceRoot, ".prettierignore"));
+}
+
+/**
+ * Skill-dir entries derive from `.forge-managed` markers under
+ * `agentsSkillsDir` — marker presence is the forge-ownership proof (AC-9:
+ * unmarked dirs are consumer-owned and never listed).
+ */
+async function listManagedSkillEntries(
+  workspaceRoot: string,
+  skillsDirRel: string,
+  io: WorkspaceIO,
+): Promise<string[]> {
+  const entries: string[] = [];
+  const absDir = path.join(workspaceRoot, skillsDirRel);
+  let children;
+  try {
+    children = await io.readdir(absDir);
+  } catch {
+    return entries;
+  }
+  for (const child of children) {
+    if (!child.isDirectory) continue;
+    if (await io.exists(path.join(absDir, child.name, SKILL_MARKER_FILE))) {
+      entries.push(`${skillsDirRel.replace(/\/+$/, "")}/${child.name}/`);
+    }
+  }
+  return entries.sort();
+}
+
+// Sync twin for runInit.
+function listManagedSkillEntriesSync(workspaceRoot: string, skillsDirRel: string): string[] {
+  const entries: string[] = [];
+  const absDir = path.join(workspaceRoot, skillsDirRel);
+  let children;
+  try {
+    children = sfs.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+  for (const child of children) {
+    if (!child.isDirectory()) continue;
+    if (sfs.existsSync(path.join(absDir, child.name, SKILL_MARKER_FILE))) {
+      entries.push(`${skillsDirRel.replace(/\/+$/, "")}/${child.name}/`);
+    }
+  }
+  return entries.sort();
+}
+
+export async function planPrettierignore(
+  workspaceRoot: string,
+  skillsDirRel = ".agents/skills",
+  io?: WorkspaceIO,
+): Promise<PrettierignorePlan> {
+  const fio = resolveIo(io);
+  const applies = await detectPrettier(workspaceRoot, fio);
+  const skillEntries = applies
+    ? await listManagedSkillEntries(workspaceRoot, skillsDirRel, fio)
+    : [];
+  return {
+    applies,
+    entries: [...skillEntries, ...FIXED_ENTRIES],
+    fileExists: await fileExists(path.join(workspaceRoot, ".prettierignore")),
+  };
+}
+
+// Sync twin for runInit.
+export function planPrettierignoreSync(
+  workspaceRoot: string,
+  skillsDirRel = ".agents/skills",
+): PrettierignorePlan {
+  const applies = detectPrettierSync(workspaceRoot);
+  const skillEntries = applies ? listManagedSkillEntriesSync(workspaceRoot, skillsDirRel) : [];
+  return {
+    applies,
+    entries: [...skillEntries, ...FIXED_ENTRIES],
+    fileExists: sfs.existsSync(path.join(workspaceRoot, ".prettierignore")),
+  };
+}
+
+function renderBlock(entries: string[]): string {
+  return [PRETTIERIGNORE_BLOCK_BEGIN, ...entries, PRETTIERIGNORE_BLOCK_END].join("\n");
+}
+
+/**
+ * Pure reconcile: compute the next `.prettierignore` content from existing
+ * content + managed entries. Content outside the delimited block is preserved
+ * verbatim; unbalanced markers cause the whole file to be treated as
+ * operator-owned (fresh block appended).
+ */
+export function reconcilePrettierignoreContent(
+  existing: string,
+  entries: string[],
+): { next: string; changed: Exclude<PrettierignoreResult, "skipped"> } {
+  const block = renderBlock(entries);
+  if (existing === "") {
+    return { next: block + "\n", changed: "written" };
+  }
+
+  const beginIdx = existing.indexOf(PRETTIERIGNORE_BLOCK_BEGIN);
+  const endIdx = existing.indexOf(PRETTIERIGNORE_BLOCK_END);
+  const balanced = beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx;
+  if (balanced) {
+    const before = existing.slice(0, beginIdx);
+    const after = existing.slice(endIdx + PRETTIERIGNORE_BLOCK_END.length).replace(/^\r?\n/, "");
+    let next = before + block + (after ? "\n" + after : "");
+    if (!next.endsWith("\n")) next += "\n";
+    return { next, changed: next === existing ? "unchanged" : "updated" };
+  }
+
+  const next = existing.endsWith("\n")
+    ? existing + "\n" + block + "\n"
+    : existing + "\n\n" + block + "\n";
+  return { next, changed: "updated" };
+}
+
+/**
+ * Reconcile the managed block in `.prettierignore` (async/io path — used by
+ * forge upgrade and kernel-driven callers).
+ */
+export async function applyPrettierignore(
+  workspaceRoot: string,
+  plan: PrettierignorePlan,
+  io?: WorkspaceIO,
+): Promise<PrettierignoreResult> {
+  if (!plan.applies) return "skipped";
+
+  const fio = resolveIo(io);
+  const filePath = path.join(workspaceRoot, ".prettierignore");
+
+  let existing = "";
+  try {
+    existing = await fio.readFile(filePath);
+  } catch {
+    // File absent — create containing only the managed block
+  }
+
+  const { next, changed } = reconcilePrettierignoreContent(existing, plan.entries);
+  if (changed === "unchanged") return "unchanged";
+  const writeResult = await writeFileIfChanged(filePath, next, fio);
+  return writeResult === "unchanged" ? "unchanged" : changed;
+}
+
+/** Sync twin for runInit — same contract via sync-fs. */
+export function applyPrettierignoreSync(
+  workspaceRoot: string,
+  plan: PrettierignorePlan,
+): PrettierignoreResult {
+  if (!plan.applies) return "skipped";
+
+  const filePath = path.join(workspaceRoot, ".prettierignore");
+  const existing = sfs.existsSync(filePath) ? sfs.readFileSync(filePath, "utf8") : "";
+  const { next, changed } = reconcilePrettierignoreContent(existing, plan.entries);
+  if (changed === "unchanged") return "unchanged";
+  sfs.writeFileSync(filePath, next, "utf8");
+  return changed;
+}

package/src/onboarding/profile-validate.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import { resolveIo } from "../utils/io.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { stackProfileSchema } from "../profiles/stack-profile.ts";
@@ -37,6 +37,7 @@ export async function runProfileValidate(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ProfileValidateResult>> {
   const { workspaceRoot, logger, outputFormat } = context;
+  const fio = resolveIo(context.io);
   const filterId = input.flags["id"] as string | undefined;
 
   const forgeRoot = context.forgeRoot ?? path.join(workspaceRoot, "packages", "forge");
@@ -44,7 +45,7 @@ export async function runProfileValidate(
 
   const profileResults: ProfileValidateResult["profiles"] = [];
 
-  if (!fs.existsSync(profilesDir)) {
+  if (!(await fio.exists(profilesDir))) {
     const result: ProfileValidateResult = {
       command: "forge.profile.validate",
       valid: true,
@@ -60,12 +61,12 @@ export async function runProfileValidate(
     };
   }
 
-  const entries = fs.readdirSync(profilesDir);
+  const entries = (await fio.readdir(profilesDir)).map((e) => e.name);
   for (const entry of entries) {
     if (!entry.endsWith(".yaml") || entry.startsWith(".")) continue;
 
     const profilePath = path.join(profilesDir, entry);
-    const raw = fs.readFileSync(profilePath, "utf8");
+    const raw = await fio.readFile(profilePath);
 
     let parsed: unknown;
     let parseError: string | null = null;

package/src/onboarding/scaffold-project.ts

@@ -18,9 +18,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { resolveIo } from "../utils/io.ts";
 import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
 import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
 import { resolveForgeRoot } from "../config/forge-config.ts";
@@ -45,6 +44,18 @@ export async function runScaffoldProject(
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ScaffoldProjectResult>> {
   const { workspaceRoot, logger, outputFormat } = context;
+  const fio = resolveIo(context.io);
+  const execCommand = async (
+    cmd: string,
+    cwd: string,
+    timeoutMs: number,
+  ): Promise<{ ok: boolean; stdout: string; stderr: string }> => {
+    const parts = cmd.split(/\s+/).filter(Boolean);
+    const res = await fio
+      .exec(parts[0]!, parts.slice(1), { cwd, timeoutMs })
+      .catch((err: Error) => ({ exitCode: null, stdout: "", stderr: String(err) }));
+    return { ok: res.exitCode === 0, stdout: res.stdout, stderr: res.stderr };
+  };
   const profileId = input.flags["profile"] as string | undefined;
   const projectName = input.flags["name"] as string | undefined;
   const templateId = input.flags["template"] as string | undefined;
@@ -98,16 +109,16 @@ export async function runScaffoldProject(
   // Create workspace directories
   for (const dir of profile.workspace.dirs) {
     const dirPath = path.join(workspaceRoot, dir);
-    fs.mkdirSync(dirPath, { recursive: true });
+    await fio.mkdir(dirPath);
     created.push(`${dir}/`);
   }
 
   // Create workspace files (with __PROJECT_NAME__ placeholder replacement)
   for (const file of profile.workspace.files) {
     const filePath = path.join(workspaceRoot, file.path);
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    await fio.mkdir(path.dirname(filePath));
     const content = file.content.replace(/__PROJECT_NAME__/g, effectiveProjectName);
-    fs.writeFileSync(filePath, content, "utf8");
+    await fio.writeFile(filePath, content);
     created.push(file.path);
   }
 
@@ -117,13 +128,13 @@ export async function runScaffoldProject(
   // Profiles may already include .npmrc in workspace.files — append the setting if missing.
   const npmrcPath = path.join(workspaceRoot, ".npmrc");
   if (profile.install.length > 0) {
-    if (fs.existsSync(npmrcPath)) {
-      const existing = fs.readFileSync(npmrcPath, "utf8");
+    if (await fio.exists(npmrcPath)) {
+      const existing = await fio.readFile(npmrcPath);
       if (!existing.includes("ignore-workspace-root-check=true")) {
-        fs.appendFileSync(npmrcPath, "ignore-workspace-root-check=true\n", "utf8");
+        await fio.appendFile(npmrcPath, "ignore-workspace-root-check=true\n");
       }
     } else {
-      fs.writeFileSync(npmrcPath, "ignore-workspace-root-check=true\n", "utf8");
+      await fio.writeFile(npmrcPath, "ignore-workspace-root-check=true\n");
       created.push(".npmrc");
     }
   }
@@ -152,17 +163,17 @@ export async function runScaffoldProject(
   if (effectiveFirstWorkspace) {
     const wsPath = effectiveFirstWorkspace.path.replace("my-site", effectiveProjectName).replace("my-game", effectiveProjectName);
     const wsDir = path.join(workspaceRoot, wsPath);
-    fs.mkdirSync(wsDir, { recursive: true });
+    await fio.mkdir(wsDir);
     created.push(`${wsPath}/`);
 
     for (const file of effectiveFirstWorkspace.files) {
       const filePath = path.join(wsDir, file.path);
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      await fio.mkdir(path.dirname(filePath));
       // Replace placeholder names (quoted and bare)
       const content = file.content
         .replace(/my-site/g, effectiveProjectName)
         .replace(/my-game/g, effectiveProjectName);
-      fs.writeFileSync(filePath, content, "utf8");
+      await fio.writeFile(filePath, content);
       created.push(`${wsPath}/${file.path}`);
     }
   }
@@ -186,16 +197,17 @@ export async function runScaffoldProject(
     if (outputFormat === "pretty") {
       logger.info(`Running: ${cmd}`);
     }
-    try {
-      execSync(cmd, { cwd: workspaceRoot, stdio: "pipe", timeout: 60000 });
+    const res = await execCommand(cmd, workspaceRoot, 60000);
+    if (res.ok) {
       installLog.push(`${cmd} — ok`);
       if (outputFormat === "pretty") {
         logger.success(`Finished: ${cmd}`);
       }
-    } catch (err) {
-      const stderr = String((err as { stderr?: Buffer }).stderr ?? "").trim();
-      const stdout = String((err as { stdout?: Buffer }).stdout ?? "").trim();
-      const details = [stderr, stdout].filter(Boolean).join("\n");
+      if (outputFormat === "pretty") {
+        logger.success(`Finished: ${cmd}`);
+      }
+    } else {
+      const details = [res.stderr.trim(), res.stdout.trim()].filter(Boolean).join("\n");
       // pnpm v10 exits non-zero for ERR_PNPM_IGNORED_BUILDS even when install succeeded
       if (details.includes("ERR_PNPM_IGNORED_BUILDS")) {
         installLog.push(`${cmd} — ok (build scripts ignored)`);
@@ -203,7 +215,7 @@ export async function runScaffoldProject(
           logger.success(`Finished: ${cmd} (build scripts ignored — run 'pnpm approve-builds' later)`);
         }
       } else {
-        installLog.push(`${cmd} — FAILED: ${details || (err as Error).message}`);
+        installLog.push(`${cmd} — FAILED: ${details || "non-zero exit"}`);
         if (outputFormat === "pretty") {
           logger.warn(`Install failed (non-fatal): ${cmd}`);
           if (details) logger.warn(details);
@@ -224,16 +236,14 @@ export async function runScaffoldProject(
       if (outputFormat === "pretty") {
         logger.info(`Running: ${cmd}`);
       }
-      try {
-        execSync(cmd, { cwd: wsDir, stdio: "pipe", timeout: 60000 });
+      const res2 = await execCommand(cmd, wsDir, 60000);
+      if (res2.ok) {
         installLog.push(`${cmd} — ok`);
         if (outputFormat === "pretty") {
           logger.success(`Finished: ${cmd}`);
         }
-      } catch (err) {
-        const stderr = String((err as { stderr?: Buffer }).stderr ?? "").trim();
-        const stdout = String((err as { stdout?: Buffer }).stdout ?? "").trim();
-        const details = [stderr, stdout].filter(Boolean).join("\n");
+      } else {
+        const details = [res2.stderr.trim(), res2.stdout.trim()].filter(Boolean).join("\n");
         // pnpm v10 exits non-zero for ERR_PNPM_IGNORED_BUILDS even when install succeeded
         if (details.includes("ERR_PNPM_IGNORED_BUILDS")) {
           installLog.push(`${cmd} — ok (build scripts ignored)`);
@@ -241,7 +251,7 @@ export async function runScaffoldProject(
             logger.success(`Finished: ${cmd} (build scripts ignored — run 'pnpm approve-builds' later)`);
           }
         } else {
-          errors.push(`Install step failed: ${cmd}\n${details || (err as Error).message}`);
+          errors.push(`Install step failed: ${cmd}\n${details || "non-zero exit"}`);
           if (outputFormat === "pretty") {
             logger.error(`Install failed: ${cmd}`);
             if (details) logger.error(details);
@@ -262,7 +272,8 @@ export async function runScaffoldProject(
     if (outputFormat === "pretty") {
       logger.info("Formatting generated files with prettier...");
     }
-    execSync("npx prettier --write .", { cwd: workspaceRoot, stdio: "pipe", timeout: 30000 });
+    const res3 = await execCommand("npx prettier --write .", workspaceRoot, 30000);
+    if (!res3.ok) throw new Error(res3.stderr || "prettier failed");
     installLog.push("prettier --write . — ok");
     if (outputFormat === "pretty") {
       logger.success("Formatting complete.");

package/src/onboarding/scaffold.ts

@@ -10,7 +10,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { FORGE_SKILLS } from "../registry.ts";
 import { resolveForgeRoot } from "../config/forge-config.ts";