@warpgogol/forge 5.2.3 → 5.3.0

package/src/onboarding/memory-compact.ts

@@ -0,0 +1,189 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge memory.compact — mechanically enforce the MEMORY.md character budget
+(RFC-0664) by removing oldest Environment notes bullets until the file fits.
+Invoked standalone and by forge doctor --fix for the memory-layer check (RFC-1151).</purpose>
+<non-goals>
+  <item>Never touch "## Current focus" or "## Decisions in flight" — those need editorial judgment.</item>
+  <item>No semantic rewriting — bullets are removed whole, never edited or merged.</item>
+  <item>No archiving into daily/ logs — removed content is recoverable via git history.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial memory.compact — oldest-first Environment notes truncation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { resolveIo } from "../utils/io.ts";
+import path from "node:path";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
+import { resolveMemoryBudget } from "./memory-scaffold.ts";
+
+const MEMORY_MD_PATH = path.join(".agents", "memory", "MEMORY.md");
+const COMPACT_SECTION = "## Environment notes";
+const PROTECTED_SECTIONS = new Set(["## Current focus", "## Decisions in flight"]);
+
+export interface MemoryCompactResult {
+  command: "forge.memory.compact";
+  status: "pass" | "fail";
+  removed: number;
+  remainingChars: number;
+  budget: number;
+  removedLines?: string[];
+  errors: string[];
+}
+
+interface Section {
+  header: string;
+  start: number; // line index of the "## ..." header
+  end: number; // line index one past the section's last line
+}
+
+function parseSections(lines: string[]): Section[] {
+  const sections: Section[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      if (sections.length > 0) sections[sections.length - 1].end = i;
+      sections.push({ header: lines[i].trim(), start: i, end: lines.length });
+    }
+  }
+  return sections;
+}
+
+function isBullet(line: string): boolean {
+  return /^\s*-\s+/.test(line);
+}
+
+/**
+ * Remove oldest bullets from `## Environment notes` until the file fits the
+ * budget. Returns the new line list and the removed bullet lines.
+ * Exported for reuse by `forge doctor --fix` (RFC-1151).
+ */
+export function compactMemoryMd(
+  content: string,
+  budget: number,
+): { lines: string[]; removedLines: string[]; fitsBudget: boolean } {
+  if (content.length <= budget) {
+    return { lines: content.split("\n"), removedLines: [], fitsBudget: true };
+  }
+
+  const lines = content.split("\n");
+  const sections = parseSections(lines);
+  const target = sections.find((s) => s.header === COMPACT_SECTION);
+
+  const removedLines: string[] = [];
+  if (target) {
+    // Sanity: never remove from protected sections even if headers drift.
+    if (PROTECTED_SECTIONS.has(target.header)) {
+      return { lines, removedLines, fitsBudget: false };
+    }
+    // Remove bullet lines oldest-first (document order) within the section.
+    let i = target.start + 1;
+    while (i < target.end && lines.join("\n").length > budget) {
+      if (isBullet(lines[i])) {
+        removedLines.push(lines[i]);
+        lines.splice(i, 1);
+        target.end--;
+        // Recompute section ends after splice — only the target shrinks.
+      } else {
+        i++;
+      }
+    }
+  }
+
+  const fitsBudget = lines.join("\n").length <= budget;
+  return { lines, removedLines, fitsBudget };
+}
+
+export async function runMemoryCompact(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MemoryCompactResult>> {
+  const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const fio = resolveIo(context.io);
+  const memoryPath = path.join(workspaceRoot, MEMORY_MD_PATH);
+  const budget = resolveMemoryBudget(workspaceRoot);
+
+  const fail = (msg: string): ForgeCommandResult<MemoryCompactResult> => ({
+    data: {
+      command: "forge.memory.compact",
+      status: "fail",
+      removed: 0,
+      remainingChars: 0,
+      budget,
+      errors: [msg],
+    },
+    exitCode: 1,
+    summary: `forge.memory.compact: failed — ${msg}`,
+  });
+
+  if (!(await fio.exists(memoryPath))) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: 0,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: "forge.memory.compact: OK — MEMORY.md absent, nothing to compact",
+    };
+  }
+
+  const content = await fio.readFile(memoryPath);
+  if (content.length <= budget) {
+    return {
+      data: {
+        command: "forge.memory.compact",
+        status: "pass",
+        removed: 0,
+        remainingChars: content.length,
+        budget,
+        errors: [],
+      },
+      exitCode: 0,
+      summary: `forge.memory.compact: OK — already within budget (${content.length}/${budget} chars)`,
+    };
+  }
+
+  const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+  const remainingChars = lines.join("\n").length;
+
+  if (!fitsBudget) {
+    return fail(
+      `still over budget after removing ${removedLines.length} Environment notes bullet(s) ` +
+        `(${remainingChars}/${budget} chars) — manual editorial compaction required`,
+    );
+  }
+
+  if (!dryRun) {
+    await fio.writeFile(memoryPath, lines.join("\n"));
+  }
+
+  if (outputFormat === "pretty") {
+    for (const line of removedLines) {
+      logger.info(`removed: ${line.slice(0, 80)}`);
+    }
+    logger.success(
+      `${dryRun ? "[dry-run] would remove" : "removed"} ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`,
+    );
+  }
+
+  return {
+    data: {
+      command: "forge.memory.compact",
+      status: "pass",
+      removed: removedLines.length,
+      remainingChars,
+      budget,
+      removedLines: dryRun ? removedLines : undefined,
+      errors: [],
+    },
+    exitCode: 0,
+    summary: dryRun
+      ? `forge.memory.compact: [dry-run] would remove ${removedLines.length} bullet(s) — ${remainingChars}/${budget} chars`
+      : `forge.memory.compact: OK — removed ${removedLines.length} bullet(s), ${remainingChars}/${budget} chars`,
+  };
+}

package/src/onboarding/memory-scaffold.ts

@@ -12,7 +12,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { loadForgeConfig } from "../config/forge-config.ts";
 
@@ -138,7 +138,7 @@ export function scaffoldMemoryLayer(workspaceRoot: string): MemoryScaffoldResult
 // Health check
 // ---------------------------------------------------------------------------
 
-function resolveMemoryBudget(workspaceRoot: string): number {
+export function resolveMemoryBudget(workspaceRoot: string): number {
   try {
     const config = loadForgeConfig(workspaceRoot);
     if (config.bindings?.memory?.budget !== undefined && config.bindings?.memory?.budget !== null) {

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

@@ -23,19 +23,29 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { writeFileIfChanged } from "../utils/index.ts";
+import {
+  canonicalFooterOf,
+  hasEditableGeneratedMarker,
+  mergeEditableGenerated,
+  splitEditableGenerated,
+  writeFileIfChanged,
+} from "../utils/index.ts";
+import { resolveIo } from "../utils/io.ts";
 import { discoverWorkspaces } from "./workspace-discovery.ts";
 import { buildNestedAgentsMd, selectNestedTemplate, type PackageInfo } from "./nested-agents-templates.ts";
 import type { ForgeConfig } from "../config/forge-config.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
 import type { StackProfile } from "../profiles/stack-profile.ts";
+import type { WorkspaceIO } from "../types.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 
 export interface NestedGenerateResult {
   generated: string[];
   skipped: string[];
+  /** RFC-1153: files merged with a carried custom tail below the boundary. */
+  preserved: string[];
   renderedFiles: { [relPath: string]: string };
   workspaceTypeMap?: { [relPath: string]: string };
 }
@@ -55,11 +65,18 @@ export async function generateNestedAgentsMd(
   config: ForgeConfig,
   dryRun: boolean,
   workspaceTypes?: ProfileWorkspaceType[],
+  io?: WorkspaceIO,
 ): Promise<NestedGenerateResult> {
-  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const workspaces = discoverWorkspaces(
+    workspaceRoot,
+    workspaceTypes,
+    config.bindings?.workspaces?.skipDirs,
+  );
   const generated: string[] = [];
   const skipped: string[] = [];
+  const preserved: string[] = [];
   const renderedFiles: { [relPath: string]: string } = {};
+  const fio = resolveIo(io);
   const workspaceTypeMap: { [relPath: string]: string } = {};
 
   // RFC-0643: resolve terminology from config + profile for nested template substitution
@@ -86,12 +103,40 @@ export async function generateNestedAgentsMd(
       continue;
     }
 
-    await writeFileIfChanged(agentsMdPath, content);
+    // RFC-1153: merge instead of overwrite — the `forge:custom` boundary marks
+    // the split between the generator-owned head and the preserved custom tail.
+    let existing: string | null = null;
+    if (ws.hasAgentsMd) {
+      try {
+        existing = await fio.readFile(agentsMdPath);
+      } catch {
+        // Unreadable — treat as absent; merge will emit a fresh file.
+      }
+    }
+    let merged = mergeEditableGenerated(content, existing, relPath);
+    if (merged === null && 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, relPath);
+    }
+    if (merged === null) {
+      skipped.push(`${relPath} (unmapped-customization)`);
+      continue;
+    }
+
+    await writeFileIfChanged(agentsMdPath, merged, fio);
     generated.push(relPath);
     workspaceTypeMap[relPath] = ws.type;
+    const footer = canonicalFooterOf(content);
+    if (
+      existing !== null &&
+      splitEditableGenerated(existing, relPath, footer ?? undefined).customTail !== null
+    ) {
+      preserved.push(relPath);
+    }
   }
 
-  return { generated, skipped, renderedFiles, workspaceTypeMap };
+  return { generated, skipped, preserved, renderedFiles, workspaceTypeMap };
 }
 
 export { discoverWorkspaces, type WorkspaceDir, type WorkspaceType } from "./workspace-discovery.ts";

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;