@warpgogol/forge 2.8.0 → 2.8.2

package/src/onboarding/scaffold-project.ts

@@ -0,0 +1,299 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.scaffold — creates a working pnpm + Turborepo monorepo from a stack profile in the current directory.</purpose>
+<non-goals>
+  <item>Do not add a --force flag — ever.</item>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0392: initial forge.scaffold handler.</item>
+  <item>RFC-0542: populate nextSteps in forge.scaffold result.</item>
+  <item>Add __PROJECT_NAME__ placeholder replacement for workspace files; profiles now include root package.json with scripts (clean, format, test, upgrade-packages) and scripts/clean.mjs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
+import { resolveForgeRoot } from "../config/forge-config.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeNextStep,
+  ForgeRuntimeContext,
+} from "../types.ts";
+
+interface ScaffoldProjectResult {
+  command: string;
+  status: "pass" | "fail";
+  profile: string;
+  created: string[];
+  installLog: string[];
+  errors: string[];
+}
+
+export async function runScaffoldProject(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ScaffoldProjectResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const profileId = input.flags["profile"] as string | undefined;
+  const projectName = input.flags["name"] as string | undefined;
+  const templateId = input.flags["template"] as string | undefined;
+
+  const created: string[] = [];
+  const installLog: string[] = [];
+  const errors: string[] = [];
+
+  // Validate required flags
+  if (!profileId) {
+    return fail("forge.scaffold", "", "Missing required flag: --profile", errors, outputFormat, logger);
+  }
+  // Derive project name from folder name if not provided (consistent with forge.create)
+  const effectiveProjectName = projectName ?? path.basename(workspaceRoot);
+
+  // Validate kebab-case project name
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(effectiveProjectName)) {
+    return fail("forge.scaffold", profileId, `Project name "${effectiveProjectName}" is not kebab-case`, errors, outputFormat, logger);
+  }
+
+  // RFC-0877: The target directory must be empty (only .git/ tolerated).
+  // The empty-directory check is handled by forge.create.
+  // forge.scaffold is called from forge.create which already verified the directory is empty.
+
+  // Load profiles and find the requested one
+  let forgeRoot: string;
+  if (context.forgeRoot) {
+    forgeRoot = context.forgeRoot;
+  } else {
+    try {
+      forgeRoot = resolveForgeRoot(workspaceRoot);
+    } catch {
+      // In autonomous mode, forgeRoot may be the cwd itself
+      forgeRoot = workspaceRoot;
+    }
+  }
+
+  let profiles: StackProfile[];
+  try {
+    profiles = listStackProfiles(forgeRoot);
+  } catch (err) {
+    return fail("forge.scaffold", profileId, `Failed to load profiles: ${(err as Error).message}`, errors, outputFormat, logger);
+  }
+
+  const profile = profiles.find((p) => p.id === profileId);
+  if (!profile) {
+    const available = profiles.map((p) => p.id).join(", ");
+    return fail("forge.scaffold", profileId, `Unknown profile "${profileId}". Available: ${available}`, errors, outputFormat, logger);
+  }
+
+  // Create workspace directories
+  for (const dir of profile.workspace.dirs) {
+    const dirPath = path.join(workspaceRoot, dir);
+    fs.mkdirSync(dirPath, { recursive: true });
+    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 });
+    const content = file.content.replace(/__PROJECT_NAME__/g, effectiveProjectName);
+    fs.writeFileSync(filePath, content, "utf8");
+    created.push(file.path);
+  }
+
+  // Ensure .npmrc has ignore-workspace-root-check=true before running install commands to avoid:
+  // - ERR_PNPM_ADDING_TO_ROOT (pnpm v10/v11 blocks `pnpm add` in workspace root without -w)
+  // - ERR_PNPM_IGNORED_BUILDS (pnpm exits non-zero for ignored build scripts)
+  // 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 (!existing.includes("ignore-workspace-root-check=true")) {
+        fs.appendFileSync(npmrcPath, "ignore-workspace-root-check=true\n", "utf8");
+      }
+    } else {
+      fs.writeFileSync(npmrcPath, "ignore-workspace-root-check=true\n", "utf8");
+      created.push(".npmrc");
+    }
+  }
+
+  // Create first workspace if defined (use template override if --template is provided)
+  let templateError: string | null = null;
+  const effectiveFirstWorkspace = (() => {
+    if (templateId && profile.templates) {
+      const template = profile.templates.find((t) => t.id === templateId);
+      if (template) return template.firstWorkspace;
+      templateError = `Unknown template "${templateId}". Available: ${profile.templates.map((t) => t.id).join(", ")}`;
+      return undefined;
+    }
+    // Use default template if no --template specified and templates exist
+    if (profile.templates && profile.templates.length > 0) {
+      const defaultTemplate = profile.templates.find((t) => t.default) ?? profile.templates[0];
+      return defaultTemplate.firstWorkspace;
+    }
+    return profile.firstWorkspace;
+  })();
+
+  if (templateError) {
+    return fail("forge.scaffold", profileId, templateError, errors, outputFormat, logger);
+  }
+
+  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 });
+    created.push(`${wsPath}/`);
+
+    for (const file of effectiveFirstWorkspace.files) {
+      const filePath = path.join(wsDir, file.path);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      // 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");
+      created.push(`${wsPath}/${file.path}`);
+    }
+  }
+
+  // Run ALL install commands AFTER all files are created (atomicity: no partial state if install fails)
+  // Root workspace install commands
+  if (outputFormat === "pretty" && profile.install.length > 0) {
+    logger.info(`Installing ${profile.install.length} root workspace package(s)...`);
+  }
+  for (const cmd of profile.install) {
+    if (outputFormat === "pretty") {
+      logger.info(`Running: ${cmd}`);
+    }
+    try {
+      execSync(cmd, { cwd: workspaceRoot, stdio: "pipe", timeout: 60000 });
+      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");
+      // 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)`);
+        if (outputFormat === "pretty") {
+          logger.success(`Finished: ${cmd} (build scripts ignored — run 'pnpm approve-builds' later)`);
+        }
+      } else {
+        installLog.push(`${cmd} — FAILED: ${details || (err as Error).message}`);
+        if (outputFormat === "pretty") {
+          logger.warn(`Install failed (non-fatal): ${cmd}`);
+          if (details) logger.warn(details);
+          logger.warn("Run this command manually after fixing the issue (e.g. configuring .npmrc).");
+        }
+      }
+    }
+  }
+
+  // First workspace install commands
+  if (effectiveFirstWorkspace) {
+    const wsPath = effectiveFirstWorkspace.path.replace("my-site", effectiveProjectName).replace("my-game", effectiveProjectName);
+    const wsDir = path.join(workspaceRoot, wsPath);
+    if (outputFormat === "pretty" && effectiveFirstWorkspace.install.length > 0) {
+      logger.info(`Installing first workspace packages in ${effectiveFirstWorkspace.path}...`);
+    }
+    for (const cmd of effectiveFirstWorkspace.install) {
+      if (outputFormat === "pretty") {
+        logger.info(`Running: ${cmd}`);
+      }
+      try {
+        execSync(cmd, { cwd: wsDir, stdio: "pipe", timeout: 60000 });
+        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");
+        // 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)`);
+          if (outputFormat === "pretty") {
+            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}`);
+          if (outputFormat === "pretty") {
+            logger.error(`Install failed: ${cmd}`);
+            if (details) logger.error(details);
+          }
+          return {
+            data: { command: "forge.scaffold", status: "fail", profile: profileId, created, installLog, errors },
+            nextSteps: [{ action: "Fix the errors above and re-run forge.scaffold", kind: "required" }],
+            exitCode: 1,
+            summary: `forge.scaffold: failed — install step "${cmd}" failed`,
+          };
+        }
+      }
+    }
+  }
+
+  // Format generated files with prettier if it's available
+  try {
+    if (outputFormat === "pretty") {
+      logger.info("Formatting generated files with prettier...");
+    }
+    execSync("npx prettier --write .", { cwd: workspaceRoot, stdio: "pipe", timeout: 30000 });
+    installLog.push("prettier --write . — ok");
+    if (outputFormat === "pretty") {
+      logger.success("Formatting complete.");
+    }
+  } catch {
+    // Prettier is optional — don't fail the scaffold if it's not available
+    if (outputFormat === "pretty") {
+      logger.info("Skipping prettier formatting (not available yet).");
+    }
+  }
+
+  if (outputFormat === "pretty") {
+    logger.success(`Scaffolded ${profile.displayName} in ${workspaceRoot}`);
+    for (const f of created) {
+      logger.info(`  created: ${f}`);
+    }
+  }
+
+  const nextSteps: ForgeNextStep[] =
+    [
+      { action: "Open the project in Windsurf", kind: "required" },
+      { action: "Run forge.create to deploy skills and docs dirs", kind: "required" },
+    ];
+  return {
+    data: { command: "forge.scaffold", status: "pass", profile: profileId, created, installLog, errors },
+    nextSteps,
+    exitCode: 0,
+    summary: `forge.scaffold: OK — scaffolded ${profileId} with ${created.length} files`,
+  };
+}
+
+function fail(
+  command: string,
+  profile: string,
+  message: string,
+  errors: string[],
+  outputFormat: string,
+  logger: ForgeRuntimeContext["logger"],
+): ForgeCommandResult<ScaffoldProjectResult> {
+  errors.push(message);
+  if (outputFormat === "pretty") {
+    logger.error(message);
+  }
+  return {
+    data: { command, status: "fail", profile, created: [], installLog: [], errors },
+    nextSteps: [{ action: "Fix the errors above and re-run forge.scaffold", kind: "required" }],
+    exitCode: 1,
+    summary: `${command}: failed — ${message}`,
+  };
+}

package/src/onboarding/scaffold.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.port.scaffold — generates a skeleton for a new skill or command in forge.</purpose>
+<non-goals>
+  <item>Do not validate the scaffolded content — that is forge.port.validate's job.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial forge.port.scaffold handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { FORGE_SKILLS } from "../registry.ts";
+import { resolveForgeRoot } from "../config/forge-config.ts";
+
+interface ScaffoldResult {
+  command: string;
+  status: "pass" | "fail";
+  created: string[];
+  errors: string[];
+}
+
+export function runScaffold(
+  input: { flags: { name?: string; type?: string; category?: string } },
+  context: unknown,
+): ScaffoldResult {
+  const ctx = context as { workspaceRoot?: string };
+  const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
+  let forgeRoot: string;
+  try {
+    forgeRoot = resolveForgeRoot(workspaceRoot);
+  } catch {
+    forgeRoot = path.join(workspaceRoot, "packages", "forge");
+  }
+
+  const name = input.flags?.name;
+  const type = input.flags?.type ?? "skill";
+  const category = input.flags?.category ?? "shared";
+
+  const errors: string[] = [];
+  const created: string[] = [];
+
+  if (!name) {
+    errors.push("--name flag is required");
+    return { command: "forge.port.scaffold", status: "fail", created, errors };
+  }
+
+  // Check for existing skill with same name
+  if (FORGE_SKILLS.some((s) => s.name === name)) {
+    errors.push(`Skill "${name}" already exists in the forge registry`);
+    return { command: "forge.port.scaffold", status: "fail", created, errors };
+  }
+
+  if (type === "skill") {
+    const skillDir = path.join(forgeRoot, "skills", category, name);
+    const skillPath = path.join(skillDir, "SKILL.md");
+
+    if (fs.existsSync(skillPath)) {
+      errors.push(`SKILL.md already exists at ${path.relative(workspaceRoot, skillPath)}`);
+      return { command: "forge.port.scaffold", status: "fail", created, errors };
+    }
+
+    fs.mkdirSync(skillDir, { recursive: true });
+
+    const content = `---
+name: ${name}
+description: TODO — one-line description (max 200 chars)
+invocation: user
+category: ${category}
+concerns: document-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+# ${name}
+
+Before starting, read \`PREFERENCES.md\` at the repository root. If the file is missing or \`aiLanguage\` is unset, ask the operator once and create the file using the \`my-preferences\` skill semantics.
+
+TODO: Write the skill's behavioral instructions here.
+`;
+
+    fs.writeFileSync(skillPath, content, "utf8");
+    created.push(path.relative(workspaceRoot, skillPath));
+  } else if (type === "command") {
+    const cmdDir = path.join(forgeRoot, "os", name);
+    const cmdPath = path.join(cmdDir, `${name}.module.ts`);
+
+    if (fs.existsSync(cmdPath)) {
+      errors.push(`Command module already exists at ${path.relative(workspaceRoot, cmdPath)}`);
+      return { command: "forge.port.scaffold", status: "fail", created, errors };
+    }
+
+    fs.mkdirSync(cmdDir, { recursive: true });
+
+    const content = `/*
+<MODULE_CONTRACT>
+<purpose>TODO — purpose of the ${name} command module.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/site-kernel.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial ${name} command module.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule, ForgeCommandDefinition } from "../../src/forge-module.ts";
+
+export const forge${capitalize(name)}Module: ForgeModule = {
+  name: "forge-${name}",
+  version: "0.1.0",
+  register(registry) {
+    registry.registerCommand({
+      name: "${name}",
+      description: "TODO — one-line description",
+      scope: "workspace",
+      execute() {
+        // TODO: implement
+      },
+    } satisfies ForgeCommandDefinition);
+  },
+};
+`;
+
+    fs.writeFileSync(cmdPath, content, "utf8");
+    created.push(path.relative(workspaceRoot, cmdPath));
+  } else {
+    errors.push(`--type must be "skill" or "command", got "${type}"`);
+  }
+
+  return {
+    command: "forge.port.scaffold",
+    status: errors.length === 0 ? "pass" : "fail",
+    created,
+    errors,
+  };
+}
+
+function capitalize(s: string): string {
+  return s.split("-").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}