@warpgogol/forge 5.2.4 → 5.3.1

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: [],
+  };
 }
-;

package/os/notes/notes.module.ts

@@ -7,6 +7,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0808: initial forgeNotesModule registering 3 note validation commands.</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>
 */
 
@@ -18,100 +19,101 @@ import type {
 } from "../../src/types.ts";
 
 export async function createForgeNotesModule(): Promise<ForgeModule> {
-const { runNoteLinkValidate } = await import("../../src/validators/note-link-validate.ts");
-    const { runNoteFrontmatterValidate } =
-      await import("../../src/validators/note-frontmatter-validate.ts");
-    const { runNoteOrphanDetect } = await import("../../src/validators/note-orphan-detect.ts");
+  const { runNoteLinkValidate } = await import("../../src/validators/note-link-validate.ts");
+  const { runNoteFrontmatterValidate } =
+    await import("../../src/validators/note-frontmatter-validate.ts");
+  const { runNoteOrphanDetect } = await import("../../src/validators/note-orphan-detect.ts");
 
-    const noteLinkValidateWrapper = async (
-      input: ForgeCommandInput,
-      context: ForgeRuntimeContext,
-    ): Promise<ForgeCommandResult> => {
-      return runNoteLinkValidate(input, context);
-    };
+  const noteLinkValidateWrapper = async (
+    input: ForgeCommandInput,
+    context: ForgeRuntimeContext,
+  ): Promise<ForgeCommandResult> => {
+    return runNoteLinkValidate(input, context);
+  };
 
-    const noteFrontmatterValidateWrapper = async (
-      input: ForgeCommandInput,
-      context: ForgeRuntimeContext,
-    ): Promise<ForgeCommandResult> => {
-      return runNoteFrontmatterValidate(input, context);
-    };
+  const noteFrontmatterValidateWrapper = async (
+    input: ForgeCommandInput,
+    context: ForgeRuntimeContext,
+  ): Promise<ForgeCommandResult> => {
+    return runNoteFrontmatterValidate(input, context);
+  };
 
-    const noteOrphanDetectWrapper = async (
-      input: ForgeCommandInput,
-      context: ForgeRuntimeContext,
-    ): Promise<ForgeCommandResult> => {
-      return runNoteOrphanDetect(input, context);
-    };
+  const noteOrphanDetectWrapper = async (
+    input: ForgeCommandInput,
+    context: ForgeRuntimeContext,
+  ): Promise<ForgeCommandResult> => {
+    return runNoteOrphanDetect(input, context);
+  };
   return {
-  name: "forge-notes",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-notes",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "note.link.validate",
-      contract: "note",
-      rules: [],
-      description:
-        "Validate wikilink integrity across a markdown note vault. Scans [[wikilinks]] and resolves each against the note graph.",
-      scope: "workspace",
-      supportsAllSites: false,
-      flags: {
-        "vault-dir": {
-          kind: "string",
-          description: "Vault directory relative to workspace root (default: vault).",
-        },
-        path: {
-          kind: "string",
-          description: "Subdirectory within the vault to scope the scan to.",
+    commands: [
+      {
+        name: "note.link.validate",
+        mutatesState: false,
+        contract: "note",
+        rules: [],
+        description:
+          "Validate wikilink integrity across a markdown note vault. Scans [[wikilinks]] and resolves each against the note graph.",
+        scope: "workspace",
+        supportsAllSites: false,
+        flags: {
+          "vault-dir": {
+            kind: "string",
+            description: "Vault directory relative to workspace root (default: vault).",
+          },
+          path: {
+            kind: "string",
+            description: "Subdirectory within the vault to scope the scan to.",
+          },
         },
+        reads: ["vault/**/*.md"],
+        cacheable: false,
+        execute: noteLinkValidateWrapper,
       },
-      reads: ["vault/**/*.md"],
-      cacheable: false,
-      execute: noteLinkValidateWrapper,
-    },
-    {
-      name: "note.frontmatter.validate",
-      contract: "note",
-      rules: [],
-      description:
-        "Validate frontmatter consistency across a markdown note vault. Checks for required fields in YAML frontmatter.",
-      scope: "workspace",
-      supportsAllSites: false,
-      flags: {
-        "vault-dir": {
-          kind: "string",
-          description: "Vault directory relative to workspace root (default: vault).",
-        },
-        fields: {
-          kind: "string",
-          description: "Comma-separated list of required fields (default: title).",
+      {
+        name: "note.frontmatter.validate",
+        mutatesState: false,
+        contract: "note",
+        rules: [],
+        description:
+          "Validate frontmatter consistency across a markdown note vault. Checks for required fields in YAML frontmatter.",
+        scope: "workspace",
+        supportsAllSites: false,
+        flags: {
+          "vault-dir": {
+            kind: "string",
+            description: "Vault directory relative to workspace root (default: vault).",
+          },
+          fields: {
+            kind: "string",
+            description: "Comma-separated list of required fields (default: title).",
+          },
         },
+        reads: ["vault/**/*.md"],
+        cacheable: false,
+        execute: noteFrontmatterValidateWrapper,
       },
-      reads: ["vault/**/*.md"],
-      cacheable: false,
-      execute: noteFrontmatterValidateWrapper,
-    },
-    {
-      name: "note.orphan.detect",
-      description:
-        "Detect orphan notes in a markdown note vault — notes with zero inbound wikilinks. Always exits zero (warnings, not errors).",
-      scope: "workspace",
-      supportsAllSites: false,
-      flags: {
-        "vault-dir": {
-          kind: "string",
-          description: "Vault directory relative to workspace root (default: vault).",
+      {
+        name: "note.orphan.detect",
+        mutatesState: false,
+        description:
+          "Detect orphan notes in a markdown note vault — notes with zero inbound wikilinks. Always exits zero (warnings, not errors).",
+        scope: "workspace",
+        supportsAllSites: false,
+        flags: {
+          "vault-dir": {
+            kind: "string",
+            description: "Vault directory relative to workspace root (default: vault).",
+          },
         },
+        reads: ["vault/**/*.md"],
+        cacheable: false,
+        execute: noteOrphanDetectWrapper,
       },
-      reads: ["vault/**/*.md"],
-      cacheable: false,
-      execute: noteOrphanDetectWrapper,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/plan/frontmatter-io.ts

@@ -13,7 +13,7 @@ parsing for plan files under docs/plans/.
 </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 { PLAN_FILE_PATTERN } from "./types.ts";
@@ -39,13 +39,13 @@ export async function listPlanFiles(planDirPath: string): Promise<string[]> {
 
   async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
     try {
-      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const entries = await fs.readdir(dirPath);
       for (const entry of entries) {
         const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
+        if (entry.isDirectory) {
           await scanDir(path.join(dirPath, entry.name), relativePath);
         } else if (
-          entry.isFile() &&
+          entry.isFile &&
           entry.name.endsWith(".md") &&
           !entry.name.startsWith("plan-0000") &&
           entry.name !== "README.md" &&
@@ -69,7 +69,7 @@ export async function readAndParsePlan(
 ): Promise<{ fileName: string; parsed: ParsedPlan } | undefined> {
   try {
     const filePath = path.join(planDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parsePlanFile(content) };
   } catch {
     return undefined;

package/os/plan/handlers/archive.ts

@@ -16,7 +16,7 @@ non-terminal files found in subdirectories back to the root.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import { listPlanFiles, extractRfcIdFromPlanFile } from "../frontmatter-io.ts";
 import { loadRfcStatusMap } from "../../rfc/frontmatter-io.ts";
@@ -115,7 +115,9 @@ export async function runPlanArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
         continue;
       } catch {
@@ -123,7 +125,7 @@ export async function runPlanArchive(
       }
 
       if (!dryRun) {
-        await fs.mkdir(targetDir, { recursive: true });
+        await fs.mkdir(targetDir);
         try {
           await fs.rename(path.join(planDirPath, fileName), targetPath);
         } catch (err) {
@@ -166,7 +168,9 @@ export async function runPlanArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
         continue;
       } catch {

package/os/plan/plan.module.ts

@@ -13,42 +13,41 @@
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgePlanModule(): Promise<ForgeModule> {
-const { runPlanArchive } = await import("./handlers/archive.ts");
+  const { runPlanArchive } = await import("./handlers/archive.ts");
   return {
-  name: "forge-plan",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-plan",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "plan.archive",
-      description:
-        "Move plan files whose parent RFC has terminal status " +
-        "(implemented, rejected, superseded) into docs/plans/archive/<status>/ " +
-        "subdirectories. Bidirectional: moves non-terminal files found in " +
-        "subdirectories back to root. Use --dry-run to preview. " +
-        "Use --status to filter to a single terminal status. " +
-        "Prefer the docs.archive umbrella command unless you need to archive only plans.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/plans/*.md", "docs/plans/archive/**"],
-      reads: ["docs/plans/**/*.md", "docs/rfcs/**/*.md"],
-      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 (implemented, rejected, superseded).",
+    commands: [
+      {
+        name: "plan.archive",
+        description:
+          "Move plan files whose parent RFC has terminal status " +
+          "(implemented, rejected, superseded) into docs/plans/archive/<status>/ " +
+          "subdirectories. Bidirectional: moves non-terminal files found in " +
+          "subdirectories back to root. Use --dry-run to preview. " +
+          "Use --status to filter to a single terminal status. " +
+          "Prefer the docs.archive umbrella command unless you need to archive only plans.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/plans/*.md", "docs/plans/archive/**"],
+        generates: [],
+        reads: ["docs/plans/**/*.md", "docs/rfcs/**/*.md"],
+        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 (implemented, rejected, superseded).",
+          },
         },
+        execute: runPlanArchive,
       },
-      execute: runPlanArchive,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/plugin/plugin.module.ts

@@ -8,11 +8,12 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0941: initial forgePluginModule with forge.plugin.validate and forge.plugin.discover commands.</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 path from "node:path";
-import fs from "node:fs";
+import * as fs from "../../src/utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import type { ForgeModule } from "../../src/forge-module.ts";
 import type {
@@ -233,10 +234,11 @@ export const forgePluginModule: ForgeModule = {
   name: "forge-plugin",
   version: "0.1.0",
   runtime: "autonomous",
-    declarations: [],
+  declarations: [],
   commands: [
     {
       name: "forge.plugin.validate",
+      mutatesState: false,
       contract: "forge",
       rules: [],
       description:
@@ -250,6 +252,7 @@ export const forgePluginModule: ForgeModule = {
     },
     {
       name: "forge.plugin.discover",
+      mutatesState: false,
       description:
         "Enumerate all project-declared skill packs with valid forge.plugin.yaml manifests (RFC-0941). Returns pack id, version, prefix, and directory.",
       scope: "workspace",
@@ -258,8 +261,7 @@ export const forgePluginModule: ForgeModule = {
       reads: ["forge.yaml", "**/forge.plugin.yaml"],
       cacheable: false,
       execute: runPluginDiscover,
-    }
+    },
   ],
-  pipelines: [
-
-  ]};
+  pipelines: [],
+};

package/os/program/discovery.ts

@@ -13,10 +13,10 @@ against schemas, and computes normative source hashes.</purpose>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { execSync } from "node:child_process";
+import { execSync } from "../../src/utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import {
   programManifestSchema,

package/os/program/handlers/complete.ts

@@ -13,7 +13,7 @@ manifest. Supports --bootstrap for packet 000 (RFC-0856).</purpose>
 </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, stringify as stringifyYaml } from "yaml";
 import type {

package/os/program/handlers/lease.ts

@@ -14,7 +14,7 @@ and recover actions (RFC-0856).</purpose>
 </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, stringify as stringifyYaml } from "yaml";
 import type {

package/os/program/handlers/seal.ts

@@ -14,7 +14,7 @@ to sealed, and records the seal in the program manifest (RFC-0856).</purpose>
 </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, stringify as stringifyYaml } from "yaml";
 import type {

package/os/program/lease.ts

@@ -13,7 +13,7 @@ Raw tokens are never persisted to disk.</purpose>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { programPacketLeaseSchema, type ProgramPacketLease } from "./schemas.ts";