@warpgogol/forge 5.2.4 → 5.3.0

package/os/core/handlers/pinned-validate.ts

@@ -21,8 +21,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { exec } from "node:child_process";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { exec } from "../../../src/utils/sync-fs.ts";
 import { promisify } from "node:util";
 import path from "node:path";
 import type {
@@ -141,7 +141,7 @@ async function appendAuditLog(
 ): Promise<void> {
   const logPath = path.join(repoRoot, AUDIT_LOG_PATH);
   const line = JSON.stringify(entry) + "\n";
-  await fs.appendFile(logPath, line, "utf8");
+  await fs.appendFile(logPath, line);
 }
 
 export async function runPinnedValidate(

package/os/core/handlers/profile-resolve.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { resolveForgeRoot } from "../../../src/config/forge-config.ts";

package/os/core/handlers/public-surface.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import type {
   ForgeCommandInput,

package/os/core/handlers/release-prepare.ts

@@ -14,8 +14,8 @@
 </CHANGE_SUMMARY>
 */
 
-import { readFile, copyFile, mkdir, stat } from "node:fs/promises";
 import { join, basename } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 import { createHash } from "node:crypto";
 import type {
   ForgeCommandInput,
@@ -27,6 +27,10 @@ import { loadWorkspaceDeps } from "../../werkstatt/handlers/workspace-deps.ts";
 import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
 import type { ProfileRelease } from "../../../src/profiles/profile-schema.ts";
 
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
+
 export interface ReleaseManifest {
   schemaVersion: string;
   releaseId: string;
@@ -58,7 +62,7 @@ function generateReleaseId(profileId: string, shortHash: string): string {
 
 async function readVersionFromPackageJson(workspaceRoot: string): Promise<string> {
   try {
-    const raw = await readFile(join(workspaceRoot, "package.json"), "utf8");
+    const raw = await io.readFile(join(workspaceRoot, "package.json"));
     const pkg = JSON.parse(raw) as { version?: string };
     return pkg.version ?? "0.0.0";
   } catch {
@@ -79,7 +83,7 @@ async function findBuiltArtifacts(
     if (!isGlob) {
       const fullPath = join(workspaceRoot, produceOutput);
       try {
-        const _s = await stat(fullPath);
+        const _s = await io.stat(fullPath);
         return [fullPath];
       } catch {
         return [];
@@ -110,6 +114,7 @@ export async function runReleasePrepare(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeReleasePrepareResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
 
@@ -212,7 +217,7 @@ export async function runReleasePrepare(
       if (!dryRun) {
         const { byteHashFile } = await loadWorkspaceDeps();
         hash = await byteHashFile(builtFile);
-        const stats = await stat(builtFile);
+        const stats = await io.stat(builtFile);
         size = stats.size;
         allHashes += hash;
       }
@@ -268,12 +273,12 @@ export async function runReleasePrepare(
     };
   }
 
-  await mkdir(releaseDir, { recursive: true });
+  await io.mkdir(releaseDir);
 
   for (const a of manifestArtifacts) {
     const srcPath = join(workspaceRoot, a.path);
     const dstPath = join(releaseDir, basename(a.path));
-    await copyFile(srcPath, dstPath);
+    await io.copyFile(srcPath, dstPath);
   }
 
   const manifestPath = join(releaseDir, releaseConfig.manifestName);

package/os/core/handlers/release-publish.ts

@@ -14,8 +14,8 @@
 </CHANGE_SUMMARY>
 */
 
-import { readFile, copyFile, mkdir } from "node:fs/promises";
 import { join, basename } from "node:path";
+import { resolveIo } from "../../../src/utils/io.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -46,6 +46,7 @@ export async function runReleasePublish(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeReleasePublishResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
 
@@ -87,7 +88,7 @@ export async function runReleasePublish(
 
   let manifest: ReleaseManifest;
   try {
-    const raw = await readFile(manifestPath, "utf8");
+    const raw = await io.readFile(manifestPath);
     manifest = JSON.parse(raw) as ReleaseManifest;
   } catch {
     return {
@@ -155,15 +156,14 @@ export async function runReleasePublish(
 
   if (target === "local") {
     const publishedDir = join(releaseDir, "published");
-    await mkdir(publishedDir, { recursive: true });
+    await io.mkdir(publishedDir);
     for (const f of filesToPublish) {
       const dst = join(publishedDir, basename(f));
-      await copyFile(f, dst);
+      await io.copyFile(f, dst);
       publishedFiles.push({ path: f, targetPath: dst });
     }
   } else if (target === "r2" || target === "s3") {
     const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
-    const { readFile: fsReadFile } = await import("node:fs/promises");
 
     const endpoint =
       target === "r2"
@@ -185,7 +185,7 @@ export async function runReleasePublish(
 
     for (const f of filesToPublish) {
       const key = prefix ? `${prefix}/${basename(f)}` : basename(f);
-      const body = await fsReadFile(f);
+      const body = await io.readFile(f);
       await client.send(
         new PutObjectCommand({
           Bucket: bucket,

package/os/core/handlers/validate.ts

@@ -18,7 +18,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { exec } from "node:child_process";
+import { exec } from "../../../src/utils/sync-fs.ts";
 import { promisify } from "node:util";
 import type {
   ForgeCommandInput,

package/os/exploration/exploration.module.ts

@@ -74,6 +74,7 @@ export async function createForgeExplorationModule(): Promise<ForgeModule> {
         scope: "workspace",
         mutatesState: true,
         writes: ["docs/explorations/*.md"],
+        generates: [],
         reads: ["docs/explorations/*.md"],
         cacheable: false,
         flags: {

package/os/exploration/frontmatter-io.ts

@@ -13,7 +13,7 @@ their YAML frontmatter without validating the shape.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../src/utils/io.ts";
 import path from "node:path";
 import YAML from "yaml";
 import { EXPLORATION_DIR } from "./types.ts";
@@ -38,9 +38,9 @@ export async function listExplorationFiles(explorationsDirPath: string): Promise
   const results: string[] = [];
 
   try {
-    const entries = await fs.readdir(explorationsDirPath, { withFileTypes: true });
+    const entries = await fs.readdir(explorationsDirPath);
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+      if (entry.isFile && entry.name.endsWith(".md") && entry.name !== "README.md") {
         results.push(entry.name);
       }
     }
@@ -57,7 +57,7 @@ export async function readAndParseExplorationNote(
 ): Promise<{ fileName: string; parsed: ParsedExplorationNote } | undefined> {
   try {
     const filePath = path.join(explorationsDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseExplorationFile(content) };
   } catch {
     return undefined;

package/os/exploration/handlers/archive.ts

@@ -10,7 +10,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import type {
   ForgeCommandInput,
@@ -110,7 +110,7 @@ export async function runExplorationArchive(
         related,
       };
       const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
-      await fs.writeFile(filePath, updatedContent, "utf-8");
+      await fs.writeFile(filePath, updatedContent);
     }
     if (outputFormat === "pretty") {
       logger.info(`Exploration note ${slug} is already archived (no-op).`);
@@ -136,7 +136,7 @@ export async function runExplorationArchive(
   };
 
   const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
-  await fs.writeFile(filePath, updatedContent, "utf-8");
+  await fs.writeFile(filePath, updatedContent);
 
   if (outputFormat === "pretty") {
     logger.success(`Archived exploration note: ${slug} (${previousStatus} → archived)`);

package/os/mission/handlers/archive.ts

@@ -26,10 +26,10 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { existsSync, lstatSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execSync } from "../../../src/utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import type {
   ForgeCommandInput,
@@ -61,7 +61,7 @@ async function cleanServiceFolders(workpieceDir: string): Promise<string[]> {
   for (const folder of SERVICE_FOLDERS) {
     const target = path.join(workpieceDir, folder);
     if (existsSync(target)) {
-      await fs.rm(target, { recursive: true, force: true });
+      await fs.rm(target);
       removed.push(folder);
     }
   }
@@ -76,7 +76,7 @@ function isCacheEntry(name: string): boolean {
 async function readMissionReleaseId(missionDir: string): Promise<string | null> {
   const manifestPath = path.join(missionDir, "mission.yaml");
   try {
-    const raw = await fs.readFile(manifestPath, "utf8");
+    const raw = await fs.readFile(manifestPath);
     const parsed = parseYaml(raw) as Record<string, unknown>;
     const releaseId = parsed?.releaseId;
     if (typeof releaseId === "string" && releaseId.trim()) return releaseId.trim();
@@ -89,7 +89,7 @@ async function readMissionReleaseId(missionDir: string): Promise<string | null>
 async function readMissionState(missionDir: string): Promise<string | null> {
   const manifestPath = path.join(missionDir, "mission.yaml");
   try {
-    const raw = await fs.readFile(manifestPath, "utf8");
+    const raw = await fs.readFile(manifestPath);
     const parsed = parseYaml(raw) as Record<string, unknown>;
     const state = parsed?.state;
     if (typeof state === "string") return state.trim();
@@ -106,7 +106,7 @@ async function readMissionState(missionDir: string): Promise<string | null> {
   const workpieceDir = path.join(missionDir, "workpiece");
   if (existsSync(workpieceDir)) {
     const entries = await fs.readdir(workpieceDir);
-    const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+    const nonCacheEntries = entries.filter((e) => !isCacheEntry(e.name));
     if (nonCacheEntries.length === 0) {
       return "closed";
     }
@@ -125,17 +125,17 @@ async function isOrphanedRemnant(missionDir: string): Promise<boolean> {
   if (!existsSync(workpieceDir)) return true;
 
   const entries = await fs.readdir(workpieceDir);
-  const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+  const nonCacheEntries = entries.filter((e) => !isCacheEntry(e.name));
   return nonCacheEntries.length === 0;
 }
 
 // RFC-0982: Check if a mission directory has non-cache content (source files,
 // configs, etc.) that warrants manual inspection rather than auto-cleanup.
 async function hasNonCacheContent(missionDir: string): Promise<boolean> {
-  const entries = await fs.readdir(missionDir, { withFileTypes: true });
+  const entries = await fs.readdir(missionDir);
   for (const entry of entries) {
     if (entry.name === "workpiece") continue;
-    if (entry.isDirectory() && isCacheEntry(entry.name)) {
+    if (entry.isDirectory && isCacheEntry(entry.name)) {
       continue;
     }
     // Any file or non-cache directory at mission root is content
@@ -146,7 +146,7 @@ async function hasNonCacheContent(missionDir: string): Promise<boolean> {
   const workpieceDir = path.join(missionDir, "workpiece");
   if (existsSync(workpieceDir)) {
     const wpEntries = await fs.readdir(workpieceDir);
-    const nonCacheEntries = wpEntries.filter((e) => !isCacheEntry(e));
+    const nonCacheEntries = wpEntries.filter((e) => !isCacheEntry(e.name));
     if (nonCacheEntries.length > 0) return true;
   }
 
@@ -176,7 +176,7 @@ async function moveMissionDir(
 
   if (!dryRun) {
     if (targetParentDir) {
-      await fs.mkdir(targetParentDir, { recursive: true });
+      await fs.mkdir(targetParentDir);
     }
 
     // RFC-0801: Clean service folders from workpiece before move.
@@ -271,14 +271,17 @@ export async function runMissionArchive(
   }
 
   // Phase 1: Scan missions/ for terminal-state missions to move into archive
-  const rootEntries = await fs.readdir(missionsPath, { withFileTypes: true });
+  const rootEntries = await fs.readdir(missionsPath);
 
   // Stale symlink cleanup: IDEs or file watchers may recreate symlinks to
   // archived mission directories after mission.archive has moved them.
   // These symlinks break pnpm workspace resolution and mission number derivation.
   // Trash them before they can cause downstream issues.
   for (const e of rootEntries) {
-    if (e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME) {
+    if (
+      lstatSync(path.join(missionsPath, e.name)).isSymbolicLink() &&
+      e.name !== ARCHIVE_DIR_NAME
+    ) {
       const symlinkPath = path.join(missionsPath, e.name);
       const sourceRel = `${MISSIONS_DIR}/${e.name}`;
       if (!dryRun) {
@@ -296,7 +299,12 @@ export async function runMissionArchive(
   }
 
   const rootDirs = rootEntries
-    .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME)
+    .filter(
+      (e) =>
+        e.isDirectory &&
+        !lstatSync(path.join(missionsPath, e.name)).isSymbolicLink() &&
+        e.name !== ARCHIVE_DIR_NAME,
+    )
     .map((e) => e.name);
 
   for (const missionId of rootDirs) {
@@ -410,13 +418,13 @@ export async function runMissionArchive(
   // Phase 2: Scan missions/archive/<state>/ for non-terminal missions to move back
   const archivePath = path.join(missionsPath, ARCHIVE_DIR_NAME);
   if (existsSync(archivePath)) {
-    const stateDirs = await fs.readdir(archivePath, { withFileTypes: true });
-    const stateDirNames = stateDirs.filter((e) => e.isDirectory()).map((e) => e.name);
+    const stateDirs = await fs.readdir(archivePath);
+    const stateDirNames = stateDirs.filter((e) => e.isDirectory).map((e) => e.name);
 
     for (const stateDirName of stateDirNames) {
       const stateDirPath = path.join(archivePath, stateDirName);
-      const archivedMissions = await fs.readdir(stateDirPath, { withFileTypes: true });
-      const archivedDirNames = archivedMissions.filter((e) => e.isDirectory()).map((e) => e.name);
+      const archivedMissions = await fs.readdir(stateDirPath);
+      const archivedDirNames = archivedMissions.filter((e) => e.isDirectory).map((e) => e.name);
 
       for (const missionId of archivedDirNames) {
         const archivedMissionDir = path.join(stateDirPath, missionId);

package/os/mission/mission.module.ts

@@ -14,47 +14,46 @@
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeMissionModule(): Promise<ForgeModule> {
-const { runMissionArchive } = await import("./handlers/archive.ts");
+  const { runMissionArchive } = await import("./handlers/archive.ts");
   return {
-  name: "forge-mission",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-mission",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "mission.archive",
-      description:
-        "Move terminal-state mission directories (state: closed or aborted in " +
-        "mission.yaml) into missions/archive/<state>/<missionId>/ subdirectories. " +
-        "Bidirectional: moves open missions found in archive subdirectories back " +
-        "to missions/. Use --dry-run to preview. Use --status to filter to a " +
-        "single terminal status (closed, aborted). " +
-        "Prefer the docs.archive umbrella command unless you need to archive only missions.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["missions/*", "missions/archive/**"],
-      reads: ["missions/**"],
-      cacheable: false,
-      flags: {
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview what would be moved without touching the filesystem.",
-        },
-        status: {
-          kind: "string",
-          description: "Filter to a single terminal status (closed, aborted).",
-        },
-        "clean-orphans": {
-          kind: "boolean",
-          description:
-            "Trash orphaned directories (no mission.yaml, only cache files) instead of archiving them.",
+    commands: [
+      {
+        name: "mission.archive",
+        description:
+          "Move terminal-state mission directories (state: closed or aborted in " +
+          "mission.yaml) into missions/archive/<state>/<missionId>/ subdirectories. " +
+          "Bidirectional: moves open missions found in archive subdirectories back " +
+          "to missions/. Use --dry-run to preview. Use --status to filter to a " +
+          "single terminal status (closed, aborted). " +
+          "Prefer the docs.archive umbrella command unless you need to archive only missions.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["missions/*", "missions/archive/**"],
+        generates: [],
+        reads: ["missions/**"],
+        cacheable: false,
+        flags: {
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview what would be moved without touching the filesystem.",
+          },
+          status: {
+            kind: "string",
+            description: "Filter to a single terminal status (closed, aborted).",
+          },
+          "clean-orphans": {
+            kind: "boolean",
+            description:
+              "Trash orphaned directories (no mission.yaml, only cache files) instead of archiving them.",
+          },
         },
+        execute: runMissionArchive,
       },
-      execute: runMissionArchive,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/naming/naming-convention.ts

@@ -13,9 +13,14 @@ uses kebab-case (lowercase letters, digits, hyphens only), with documented exemp
 */
 
 import { basename, join, relative } from "node:path";
-import { readFile } from "node:fs/promises";
-import { readdirSync, type Dirent } from "node:fs";
+import { ambientIo, resolveIo } from "../../src/utils/io.ts";
+
+import { readdirSync, type Dirent } from "../../src/utils/sync-fs.ts";
 import { collectFiles } from "../../src/utils/fs.ts";
+
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -168,7 +173,7 @@ function hasNamingViolation(fileName: string): boolean {
 async function readSimpleIgnorePatterns(filePath: string): Promise<Set<string>> {
   const patterns = new Set<string>();
   try {
-    const content = await readFile(filePath, "utf8");
+    const content = await io.readFile(filePath);
     for (const rawLine of content.split("\n")) {
       const line = rawLine.trim();
       if (!line || line.startsWith("#")) continue;
@@ -270,6 +275,7 @@ export async function runNamingConventionLint(
     unknownTopLevelDirs?: string[];
   }>
 > {
+  const _io = resolveIo(context.io);
   const workspaceRoot = context.workspaceRoot;
   const includeIgnored = input.flags["include-ignored"] === true;
 

package/os/naming/naming.module.ts

@@ -7,39 +7,39 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial forgeNamingModule registering naming.convention.lint.</item>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
 </CHANGE_SUMMARY>
 */
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeNamingModule(): Promise<ForgeModule> {
-const { runNamingConventionLint } = await import("./naming-convention.ts");
+  const { runNamingConventionLint } = await import("./naming-convention.ts");
   return {
-  name: "forge-naming",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-naming",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "naming.convention.lint",
-      contract: "naming",
-      rules: [],
-      description:
-        "Validate all filenames use kebab-case (no underscores) across registered workspace roots.",
-      scope: "workspace",
-      supportsAllSites: true,
-      flags: {
-        "include-ignored": {
-          kind: "boolean",
-          description: "Also scan files ignored by .gitignore or .windsurfignore.",
+    commands: [
+      {
+        name: "naming.convention.lint",
+        mutatesState: false,
+        contract: "naming",
+        rules: [],
+        description:
+          "Validate all filenames use kebab-case (no underscores) across registered workspace roots.",
+        scope: "workspace",
+        supportsAllSites: true,
+        flags: {
+          "include-ignored": {
+            kind: "boolean",
+            description: "Also scan files ignored by .gitignore or .windsurfignore.",
+          },
         },
+        reads: ["packages/**/*.{ts,tsx}", "apps/**/*.{ts,tsx}", "services/**/*.{ts,tsx}"],
+        execute: runNamingConventionLint,
       },
-      reads: ["packages/**/*.{ts,tsx}", "apps/**/*.{ts,tsx}", "services/**/*.{ts,tsx}"],
-      execute: runNamingConventionLint,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;