@warpgogol/forge 5.2.0 → 5.2.4

package/os/rfc/rfc-create-hint.test.ts

@@ -0,0 +1,90 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1139 AC-1: the next-steps hint printed by rfc.create must be an
+    executable command — correct binary (werkstatt, not forge), correct
+    subcommand (run), and correct flags (--id, not --file).
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runRfcCreate } from "./handlers/list-create.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+const RFC_DIR = "docs/rfcs";
+
+const TEMPLATE = `---
+id: RFC-0000
+title: "Template"
+status: draft
+kind: command
+scope: workspace
+createdAt: YYYY-MM-DD
+updatedAt: YYYY-MM-DD
+satisfies: []
+---
+
+# RFC-0000: Template
+`;
+
+function makeContext(root: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot: root,
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      success() {},
+      section() {},
+      getEvents: () => [],
+    },
+    outputFormat: "json",
+    dryRun: false,
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown>): ForgeCommandInput {
+  return { argv: [], flags } as unknown as ForgeCommandInput;
+}
+
+describe("rfc.create — RFC-1139 next-steps hint accuracy", () => {
+  let root: string;
+  let rfcDir: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-hint-"));
+    rfcDir = path.join(root, RFC_DIR);
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.writeFile(path.join(rfcDir, "rfc-0000-template.md"), TEMPLATE, "utf8");
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-1: next-steps hint is an executable werkstatt command with --id", async () => {
+    const result = await runRfcCreate(
+      makeInput({ title: "Hint Test", kind: "command", scope: "workspace" }),
+      makeContext(root),
+    );
+
+    const steps = result.nextSteps ?? [];
+    expect(steps.length).toBeGreaterThan(0);
+
+    for (const step of steps) {
+      const match = step.action.match(/pnpm exec (\S+) run ([\w.]+)/);
+      expect(match, `hint "${step.action}" must contain a runnable command`).not.toBeNull();
+      const [, binary, command] = match!;
+      // forge has no `run` subcommand — werkstatt does
+      expect(binary).toBe("werkstatt");
+      expect(command).toBe("rfc.validate");
+      // rfc.validate takes --id, not --file
+      expect(step.action).toContain("--id RFC-");
+      expect(step.action).not.toContain("--file");
+    }
+  });
+});

package/os/rfc/rfc-read-only-no-side-effects.test.ts

@@ -0,0 +1,83 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1139 AC-4: read-only commands must not write to the working tree —
+    no ambient regeneration of tracked generated files as a side effect.
+    Guards against future read-path writers.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runRfcList } from "./handlers/list-create.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+function makeContext(root: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot: root,
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      success() {},
+      section() {},
+      getEvents: () => [],
+    },
+    outputFormat: "json",
+    dryRun: false,
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { argv: [], flags } as unknown as ForgeCommandInput;
+}
+
+async function snapshotTree(root: string): Promise<Map<string, string>> {
+  const snapshot = new Map<string, string>();
+  async function walk(dir: string): Promise<void> {
+    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        snapshot.set(path.relative(root, full), await fs.readFile(full, "utf8"));
+      }
+    }
+  }
+  await walk(root);
+  return snapshot;
+}
+
+describe("read-only commands — RFC-1139 no side-effect writes", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-readonly-"));
+    const rfcDir = path.join(root, "docs", "rfcs");
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.writeFile(
+      path.join(rfcDir, "rfc-0001-test.md"),
+      `---\nid: RFC-0001\ntitle: "Test"\nstatus: draft\n---\n\n# RFC-0001\n`,
+      "utf8",
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-4: rfc.list leaves the working tree byte-identical", async () => {
+    const before = await snapshotTree(root);
+    const result = await runRfcList(makeInput(), makeContext(root));
+    expect(result.data?.status).toBe("ok");
+    const after = await snapshotTree(root);
+
+    expect([...after.keys()].sort()).toEqual([...before.keys()].sort());
+    for (const [file, content] of before) {
+      expect(after.get(file), `${file} modified by read-only command`).toBe(content);
+    }
+  });
+});

package/os/rfc/rfc.module.ts

@@ -396,7 +396,7 @@ const {
         "RFC-0476: the exclusive atomic path for accepted → implemented transitions. " +
         "Verifies preconditions (accepted status, checked+evidenced criteria, clean tree, " +
         "reachable RFC-referencing commit, passing probe evidence) then atomically sets " +
-        "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview.",
+        "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview. Required flags: `--id`.",
       scope: "workspace",
       mutatesState: true,
       writes: ["docs/rfcs/**/*.md"],

package/os/spec/spec.module.ts

@@ -103,6 +103,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         "List all living feature specs in docs/specs/live/. " +
         "Returns domain, title, lastMergedRfc, updatedAt, and historyCount for each spec.",
       scope: "workspace",
+      flags: {},
       reads: ["docs/specs/live/*.md"],
       execute: runSpecLiveList,
     },
@@ -128,6 +129,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         "V-LS-03 (lastMergedRfc is archived), V-LS-04 (history entries are archived), " +
         "V-LS-05 (no duplicate domains).",
       scope: "workspace",
+      flags: {},
       reads: ["docs/specs/live/*.md", "docs/rfcs/**/*.md"],
       execute: runSpecLiveValidate,
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.2.0",
+  "version": "5.2.4",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/forge-shell.yaml

@@ -70,6 +70,9 @@ workspace:
               - name: Install dependencies
                 run: pnpm install --frozen-lockfile
 
+              - name: Forge doctor
+                run: pnpm exec forge run forge.doctor
+
               - name: Format check
                 run: pnpm format:check
 

package/profiles/godot-game.yaml

@@ -292,6 +292,9 @@ workspace:
               - name: Install dependencies
                 run: pnpm install --frozen-lockfile
 
+              - name: Forge doctor
+                run: pnpm exec forge run forge.doctor
+
               - name: Format check
                 run: pnpm format:check
 

package/profiles/phaser-game.yaml

@@ -118,6 +118,9 @@ workspace:
               - name: Install dependencies
                 run: pnpm install --frozen-lockfile
 
+              - name: Forge doctor
+                run: pnpm exec forge run forge.doctor
+
               - name: Format check
                 run: pnpm format:check