@warpgogol/forge 5.2.3 → 5.3.0

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";

package/src/onboarding/skill-markers.ts

@@ -0,0 +1,162 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1154: .forge-managed marker manifests for synced skill dirs and the
+stale-dir prune for forge upgrade. Every skill-sync site records the files it
+wrote into .agents/skills/<name>/ so a later upgrade can distinguish
+forge-owned leftover dirs from consumer-authored skills — ownership is proven
+by the marker, not inferred from the name.
+</purpose>
+<non-goals>
+  <item>Do not prune unmarked dirs — no marker means consumer-owned (pre-RFC-1154 syncs, hand-authored skills).</item>
+  <item>Do not delete dirs containing files outside the manifest — consumer additions keep the dir.</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>Marker is a per-dir JSON manifest ({ files: string[] }) — fail-safe: missing marker means no right to delete.</item>
+  <item>Prune only when on-disk contents ⊆ manifest files + marker; extras keep the dir and warn.</item>
+</KEY_DECISIONS>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial implementation — SKILL_MARKER_FILE, writeSkillMarker, pruneStaleSkillDirs.</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 * as sfs from "../utils/sync-fs.ts";
+
+/** Marker file name written into every forge-synced skill dir. */
+export const SKILL_MARKER_FILE = ".forge-managed";
+
+export interface SkillMarkerManifest {
+  files: string[]; // paths forge wrote into the skill dir, relative to it
+}
+
+export interface PruneResult {
+  /** Stale marked dirs that were deleted (contents ⊆ manifest + marker). */
+  pruned: string[];
+  /** Marked stale dirs kept because extra consumer files exist or the marker is corrupt. */
+  keptWithConsumerFiles: string[];
+}
+
+/** Canonical marker bytes — deterministic, sorted file list. */
+export function buildSkillMarkerContent(files: string[]): string {
+  const manifest: SkillMarkerManifest = { files: [...files].sort() };
+  return JSON.stringify(manifest) + "\n";
+}
+
+/** Write the .forge-managed manifest into a synced skill dir (async/io path). */
+export async function writeSkillMarker(
+  skillDir: string,
+  files: string[],
+  io?: WorkspaceIO,
+): Promise<void> {
+  const fio = resolveIo(io);
+  await writeFileIfChanged(
+    path.join(skillDir, SKILL_MARKER_FILE),
+    buildSkillMarkerContent(files),
+    fio,
+  );
+}
+
+/** Sync twin for runInit (sync call path — no WorkspaceIO). */
+export function writeSkillMarkerSync(skillDir: string, files: string[]): void {
+  const markerPath = path.join(skillDir, SKILL_MARKER_FILE);
+  const next = buildSkillMarkerContent(files);
+  try {
+    if (sfs.readFileSync(markerPath, "utf8") === next) return;
+  } catch {
+    // Marker absent or unreadable — write below
+  }
+  sfs.writeFileSync(markerPath, next, "utf8");
+}
+
+function parseMarker(raw: string): SkillMarkerManifest | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      Array.isArray((parsed as SkillMarkerManifest).files) &&
+      (parsed as SkillMarkerManifest).files.every((f) => typeof f === "string")
+    ) {
+      return parsed as SkillMarkerManifest;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prune stale synced skill dirs under `agentsSkillsDir`: a dir is stale when it
+ * carries `.forge-managed` and its name is not in `currentSyncSet`. Deletion is
+ * allowed only when every file in the dir is listed in the manifest (or is the
+ * marker itself). Corrupt markers and dirs with extra files are kept and
+ * reported in `keptWithConsumerFiles`.
+ */
+export async function pruneStaleSkillDirs(
+  agentsSkillsDir: string,
+  currentSyncSet: Set<string>,
+  io?: WorkspaceIO,
+): Promise<PruneResult> {
+  const fio = resolveIo(io);
+  const result: PruneResult = { pruned: [], keptWithConsumerFiles: [] };
+
+  let entries;
+  try {
+    entries = await fio.readdir(agentsSkillsDir);
+  } catch {
+    return result; // No skills dir — nothing to prune
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    const name = entry.name;
+    if (currentSyncSet.has(name)) continue;
+
+    const dir = path.join(agentsSkillsDir, name);
+    const markerPath = path.join(dir, SKILL_MARKER_FILE);
+    if (!(await fio.exists(markerPath))) continue; // consumer-owned — never touch
+
+    let manifest: SkillMarkerManifest | null = null;
+    try {
+      manifest = parseMarker(await fio.readFile(markerPath));
+    } catch {
+      manifest = null;
+    }
+    if (!manifest) {
+      result.keptWithConsumerFiles.push(`${name} (corrupt marker)`);
+      continue;
+    }
+
+    const allowed = new Set([...manifest.files, SKILL_MARKER_FILE]);
+    const onDisk = await listFilesRecursive(dir, fio);
+    const extra = onDisk.filter((f) => !allowed.has(f));
+    if (extra.length > 0) {
+      result.keptWithConsumerFiles.push(`${name} (consumer files: ${extra.join(", ")})`);
+      continue;
+    }
+
+    await fio.rm(dir, { recursive: true });
+    result.pruned.push(name);
+  }
+
+  return result;
+}
+
+async function listFilesRecursive(dir: string, io: WorkspaceIO, prefix = ""): Promise<string[]> {
+  const out: string[] = [];
+  const entries = await io.readdir(dir);
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory) {
+      out.push(...(await listFilesRecursive(path.join(dir, entry.name), io, rel)));
+    } else {
+      out.push(rel);
+    }
+  }
+  return out;
+}

package/src/onboarding/templates/behavioral-layer-core.md

@@ -2,14 +2,12 @@
 
 ## Behavioral layer
 
-This section defines the agent's core behavioral contract. It is generated from skill `triggers` and fixed policy text. The agent MUST follow these behaviors in every session.
+This section defines the agent's core behavioral contract. It is generated from skill `triggerPhrases` and fixed policy text. The agent MUST follow these behaviors in every session.
 
 ### Intent-to-skill routing
 
-When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggers` fields in skill frontmatter.
+When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggerPhrases` fields in skill frontmatter.
 
-| Operator says something like | Skill |
-| --- | --- |
 {{triggersTable}}
 The agent uses judgment to calibrate routing — minor edits (typo fixes, small CSS changes) do not require skill invocation, while significant changes (new features, architectural decisions) do.