@warpgogol/forge 2.8.0 → 2.8.2

package/src/onboarding/nested-agents-generate.ts

@@ -0,0 +1,93 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared nested AGENTS.md generation logic (RFC-0611). Discovery + package.json
+metadata extraction + edit guard + write (or render-only in dryRun). Reused by
+runAgentsGenerate, runUpgrade, and runDoctor (staleness check via dryRun).</purpose>
+<non-goals>
+  <item>Do not generate AGENTS.md for non-workspace directories (no package.json).</item>
+  <item>Do not overwrite hand-written AGENTS.md files (no generated marker).</item>
+  <item>Do not add workspace-type detection rules — those live in workspace-discovery.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0611: initial shared nested generation function with dryRun support.</item>
+  <item>Enriched template: read package.json metadata and pass to buildNestedAgentsMd for content-rich output.</item>
+  <item>RFC-0640: accept optional workspaceTypes from profile and pass to discoverWorkspaces for profile-driven detection.</item>
+  <item>RFC-0643: return workspaceTypeMap for per-file workspace type metadata in details field.</item>
+  <item>RFC-0643: use selectNestedTemplate for profile-driven nested templates with terminology substitution.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileIfChanged } from "../utils/index.ts";
+import { discoverWorkspaces } from "./workspace-discovery.ts";
+import { buildNestedAgentsMd, selectNestedTemplate, type PackageInfo } from "./nested-agents-templates.ts";
+import type { ForgeConfig } from "../config/forge-config.ts";
+import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
+import type { StackProfile } from "../profiles/stack-profile.ts";
+import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
+
+export interface NestedGenerateResult {
+  generated: string[];
+  skipped: string[];
+  renderedFiles: { [relPath: string]: string };
+  workspaceTypeMap?: { [relPath: string]: string };
+}
+
+export function readPackageInfo(workspaceRoot: string, wsPath: string): PackageInfo | undefined {
+  const pkgJsonPath = path.join(workspaceRoot, wsPath, "package.json");
+  try {
+    const raw = fs.readFileSync(pkgJsonPath, "utf8");
+    return JSON.parse(raw) as PackageInfo;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function generateNestedAgentsMd(
+  workspaceRoot: string,
+  config: ForgeConfig,
+  dryRun: boolean,
+  workspaceTypes?: ProfileWorkspaceType[],
+): Promise<NestedGenerateResult> {
+  const workspaces = discoverWorkspaces(workspaceRoot, workspaceTypes);
+  const generated: string[] = [];
+  const skipped: string[] = [];
+  const renderedFiles: { [relPath: string]: string } = {};
+  const workspaceTypeMap: { [relPath: string]: string } = {};
+
+  // RFC-0643: resolve terminology from config + profile for nested template substitution
+  const profile = config.profile as StackProfile | undefined;
+  const terminology = resolveAllTerminology(config, profile);
+
+  for (const ws of workspaces) {
+    const agentsMdPath = path.join(workspaceRoot, ws.path, "AGENTS.md");
+    const packageInfo = readPackageInfo(workspaceRoot, ws.path);
+    const fallback = buildNestedAgentsMd(ws, config, packageInfo);
+
+    // RFC-0643: use profile-driven template when available
+    const wsType = workspaceTypes?.find((wt) => wt.id === ws.type);
+    const content = selectNestedTemplate(wsType, profile, terminology, fallback);
+    const relPath = path.join(ws.path, "AGENTS.md");
+
+    if (dryRun) {
+      renderedFiles[relPath] = content;
+      continue;
+    }
+
+    if (ws.hasAgentsMd && !ws.isGenerated) {
+      skipped.push(`${relPath} (hand-written)`);
+      continue;
+    }
+
+    await writeFileIfChanged(agentsMdPath, content);
+    generated.push(relPath);
+    workspaceTypeMap[relPath] = ws.type;
+  }
+
+  return { generated, skipped, renderedFiles, workspaceTypeMap };
+}
+
+export { discoverWorkspaces, type WorkspaceDir, type WorkspaceType } from "./workspace-discovery.ts";
+export { buildNestedAgentsMd, selectNestedTemplate, type PackageInfo } from "./nested-agents-templates.ts";

package/src/onboarding/nested-agents-templates.ts

@@ -0,0 +1,233 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Nested AGENTS.md template builder (RFC-0611). Pure function that renders
+content-rich AGENTS.md for a workspace from its package.json metadata. No I/O.</purpose>
+<non-goals>
+  <item>Do not read or write files — this is a pure render function.</item>
+  <item>Do not invent metadata not present in package.json — omit sections when data is absent.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0611: initial minimal stub template for app, package, service workspaces.</item>
+  <item>Enriched template: render package name, description, entry points, scripts, and dependencies from package.json metadata instead of a minimal stub.</item>
+  <item>RFC-0643: selectNestedTemplate() for profile-driven template selection with path traversal guard.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { buildGeneratedHeader } from "../utils/index.ts";
+import type { ForgeConfig } from "../config/forge-config.ts";
+import type { WorkspaceDir, WorkspaceType } from "./workspace-discovery.ts";
+import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
+import type { StackProfile } from "../profiles/stack-profile.ts";
+import fs from "node:fs";
+import path from "node:path";
+
+export interface PackageInfo {
+  name?: string;
+  description?: string;
+  exports?: Record<string, string | { types?: string; default?: string } | undefined>;
+  main?: string;
+  types?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+const TYPE_GUIDANCE: Record<WorkspaceType, string> = {
+  app: "This is an **app** workspace. Follow thin-route and content-driven composition rules from the root AGENTS.md.",
+  package:
+    "This is a **package** workspace. Expose stable typed APIs. Do not import from apps or services.",
+  service:
+    "This is a **service** workspace. Runtime composition only. Shared schemas and validators belong in packages.",
+};
+
+const TYPE_LABEL: Record<WorkspaceType, string> = {
+  app: "App",
+  package: "Package",
+  service: "Service",
+};
+
+interface EntryPoint {
+  name: string;
+  module: string;
+}
+
+function extractEntryPoints(
+  exports: PackageInfo["exports"],
+  main?: string,
+): EntryPoint[] {
+  if (!exports || typeof exports !== "object") {
+    if (main) return [{ name: ".", module: main }];
+    return [];
+  }
+  const result: EntryPoint[] = [];
+  for (const [key, value] of Object.entries(exports)) {
+    if (typeof value === "string") {
+      result.push({ name: key, module: value });
+    } else if (value && typeof value === "object") {
+      const module = value.types ?? value.default;
+      if (module) result.push({ name: key, module });
+    }
+  }
+  return result;
+}
+
+function formatDependencies(
+  deps: Record<string, string> | undefined,
+): { workspace: string[]; external: string[] } {
+  if (!deps) return { workspace: [], external: [] };
+  const workspace: string[] = [];
+  const external: string[] = [];
+  for (const [name, version] of Object.entries(deps)) {
+    if (version.startsWith("workspace:")) {
+      workspace.push(`\`${name}\``);
+    } else {
+      external.push(`\`${name}\` \`${version}\``);
+    }
+  }
+  return { workspace, external };
+}
+
+function buildScriptsTable(scripts: Record<string, string> | undefined): string[] {
+  if (!scripts || Object.keys(scripts).length === 0) return [];
+  const lines: string[] = [];
+  lines.push("## Scripts");
+  lines.push("");
+  lines.push("| Script | Command |");
+  lines.push("| --- | --- |");
+  for (const [name, cmd] of Object.entries(scripts)) {
+    lines.push(`| \`${name}\` | \`${cmd}\` |`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function buildDependenciesSection(deps: Record<string, string> | undefined): string[] {
+  const { workspace, external } = formatDependencies(deps);
+  if (workspace.length === 0 && external.length === 0) return [];
+  const lines: string[] = [];
+  lines.push("## Dependencies");
+  lines.push("");
+  if (workspace.length > 0) {
+    lines.push("**Workspace:**");
+    lines.push("");
+    for (const dep of workspace) lines.push(`- ${dep}`);
+    lines.push("");
+  }
+  if (external.length > 0) {
+    lines.push("**External:**");
+    lines.push("");
+    for (const dep of external) lines.push(`- ${dep}`);
+    lines.push("");
+  }
+  return lines;
+}
+
+/**
+ * RFC-0643: Select nested AGENTS.md template from profile workspace type.
+ * When agentsMdTemplate is present, resolve relative to profile directory.
+ * Reject absolute paths and parent-directory traversal (..) — fall back to hardcoded.
+ * Apply terminology substitution to the template content.
+ */
+export function selectNestedTemplate(
+  workspaceType: ProfileWorkspaceType | undefined,
+  profile: StackProfile | undefined,
+  terminology: Record<string, string>,
+  fallback: string,
+): string {
+  if (!workspaceType?.agentsMdTemplate || !profile) {
+    return fallback;
+  }
+
+  const templateRel = workspaceType.agentsMdTemplate;
+
+  // Path traversal guard: reject absolute paths and ..
+  if (path.isAbsolute(templateRel) || templateRel.includes("..")) {
+    return fallback;
+  }
+
+  // Resolve relative to profiles/ directory (where profile YAMLs live)
+  const forgeRoot = path.resolve(import.meta.dirname, "..", "..");
+  const profilesDir = path.join(forgeRoot, "profiles");
+  const templatePath = path.resolve(profilesDir, templateRel);
+
+  // Ensure resolved path is within profiles directory (no traversal escape)
+  if (!templatePath.startsWith(profilesDir + path.sep) && templatePath !== profilesDir) {
+    return fallback;
+  }
+
+  try {
+    const content = fs.readFileSync(templatePath, "utf8");
+    return substituteNestedTemplate(content, terminology);
+  } catch {
+    // Template file not found — fall back
+    return fallback;
+  }
+}
+
+function substituteNestedTemplate(
+  content: string,
+  terminology: Record<string, string>,
+): string {
+  return content.replace(
+    /\{\{terminology\.(\w+)\}\}/g,
+    (_, key: string) => terminology[key] ?? key,
+  );
+}
+
+export function buildNestedAgentsMd(
+  workspace: WorkspaceDir,
+  _config: ForgeConfig,
+  packageInfo?: PackageInfo,
+): string {
+  const header = buildGeneratedHeader({
+    filePath: "AGENTS.md",
+    ownerCommand: "forge.agents.generate",
+    commandPrefix: "forge",
+  });
+
+  const lines: string[] = [];
+  lines.push(header);
+  lines.push("");
+
+  const displayName = packageInfo?.name ?? workspace.path;
+  lines.push(`# \`${displayName}\` — Agent Guide`);
+  lines.push("");
+
+  if (packageInfo?.description) {
+    lines.push(packageInfo.description);
+    lines.push("");
+  }
+
+  lines.push(`> This file is generated by \`forge.agents.generate\`.`);
+  lines.push(`> Do not edit by hand — re-run \`forge agents generate\` to regenerate.`);
+  lines.push("");
+
+  lines.push(`**Workspace type:** ${TYPE_LABEL[workspace.type]}`);
+  lines.push("");
+  lines.push(TYPE_GUIDANCE[workspace.type]);
+  lines.push("");
+
+  if (workspace.type === "package") {
+    const entryPoints = extractEntryPoints(packageInfo?.exports, packageInfo?.main);
+    if (entryPoints.length > 0) {
+      lines.push("## Entry points");
+      lines.push("");
+      lines.push("| Entry point | Module |");
+      lines.push("| --- | --- |");
+      for (const ep of entryPoints) {
+        const suffix = ep.name === "." ? "" : ep.name.replace(/^\.\//, "/");
+        lines.push(`| \`${displayName}${suffix}\` | \`${ep.module}\` |`);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push(...buildScriptsTable(packageInfo?.scripts));
+  lines.push(...buildDependenciesSection(packageInfo?.dependencies));
+
+  lines.push("See the root `AGENTS.md` for project-wide rules, skills, and capabilities.");
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/onboarding/profile-validate.ts

@@ -0,0 +1,139 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.profile.validate — validates profile YAML files under packages/forge/profiles/ against the extended stack-profile schema (RFC-0638). Supports --id flag for single-profile validation.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not modify profile files — validation is read-only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0640: initial forge.profile.validate handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { stackProfileSchema } from "../profiles/stack-profile.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../types.ts";
+
+export interface ProfileValidateResult {
+  command: "forge.profile.validate";
+  valid: boolean;
+  profiles: Array<{
+    id: string;
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  }>;
+}
+
+export async function runProfileValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ProfileValidateResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const filterId = input.flags["id"] as string | undefined;
+
+  const forgeRoot = context.forgeRoot ?? path.join(workspaceRoot, "packages", "forge");
+  const profilesDir = path.join(forgeRoot, "profiles");
+
+  const profileResults: ProfileValidateResult["profiles"] = [];
+
+  if (!fs.existsSync(profilesDir)) {
+    const result: ProfileValidateResult = {
+      command: "forge.profile.validate",
+      valid: true,
+      profiles: [],
+    };
+    if (outputFormat === "pretty") {
+      logger.warn(`No profiles directory found at ${profilesDir}`);
+    }
+    return {
+      data: result,
+      exitCode: 0,
+      summary: "forge.profile.validate: no profiles directory — 0 profiles checked",
+    };
+  }
+
+  const entries = fs.readdirSync(profilesDir);
+  for (const entry of entries) {
+    if (!entry.endsWith(".yaml") || entry.startsWith(".")) continue;
+
+    const profilePath = path.join(profilesDir, entry);
+    const raw = fs.readFileSync(profilePath, "utf8");
+
+    let parsed: unknown;
+    let parseError: string | null = null;
+    try {
+      parsed = parseYaml(raw);
+    } catch (err) {
+      parseError = (err as Error).message;
+    }
+
+    let profileId = entry.replace(/\.yaml$/, "");
+    if (parsed && typeof parsed === "object" && "id" in parsed) {
+      profileId = (parsed as { id: string }).id;
+    }
+
+    if (filterId && profileId !== filterId) continue;
+
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (parseError) {
+      errors.push(`YAML parse error: ${parseError}`);
+    } else {
+      const result = stackProfileSchema.safeParse(parsed);
+      if (!result.success) {
+        for (const issue of result.error.issues) {
+          errors.push(`${issue.path.join(".")}: ${issue.message}`);
+        }
+      }
+    }
+
+    profileResults.push({
+      id: profileId,
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    });
+  }
+
+  const allValid = profileResults.every((p) => p.valid);
+
+  if (outputFormat === "pretty") {
+    logger.section(`Forge Profile Validate — ${profilesDir}`);
+    for (const p of profileResults) {
+      const icon = p.valid ? "✓" : "✖";
+      const fn = p.valid ? logger.success : logger.error;
+      fn(`${icon} ${p.id}: ${p.valid ? "valid" : `${p.errors.length} error(s)`}`);
+      for (const err of p.errors) {
+        logger.error(`  - ${err}`);
+      }
+    }
+    if (allValid) {
+      logger.success(`All ${profileResults.length} profile(s) valid.`);
+    } else {
+      logger.error(`${profileResults.filter((p) => !p.valid).length} profile(s) invalid.`);
+    }
+  }
+
+  const result: ProfileValidateResult = {
+    command: "forge.profile.validate",
+    valid: allValid,
+    profiles: profileResults,
+  };
+
+  return {
+    data: result,
+    exitCode: allValid ? 0 : 1,
+    summary: allValid
+      ? `forge.profile.validate: OK — ${profileResults.length} profile(s) valid`
+      : `forge.profile.validate: ${profileResults.filter((p) => !p.valid).length} invalid profile(s)`,
+  };
+}