forgeos 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/forge/cli/docs.ts

@@ -0,0 +1,265 @@
+import { spawnSync } from "node:child_process";
+import { dirname, join, normalize } from "node:path";
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { docsReadyNextActions } from "./next-actions.ts";
+
+export type DocsSubcommand = "check";
+
+export interface DocsCheckOptions {
+  workspaceRoot: string;
+  json: boolean;
+  build?: boolean;
+  installVenv?: boolean;
+}
+
+export interface DocsCheck {
+  name: string;
+  ok: boolean;
+  status: "pass" | "fail" | "warning";
+  details?: unknown;
+}
+
+export interface DocsCheckResult {
+  ok: boolean;
+  checks: DocsCheck[];
+  diagnostics: Diagnostic[];
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+const REQUIRED_DOCS = [
+  "index.md",
+  "getting-started.md",
+  "agent-workflow.md",
+  "cli-reference.md",
+  "troubleshooting.md",
+  "production-readiness.md",
+  "self-host.md",
+  "release.md",
+] as const;
+
+const CONTENT_CHECKS: Array<{ file: string; contains: string[] }> = [
+  { file: ".readthedocs.yaml", contains: ["version: 2", "configuration: mkdocs.yml", "fail_on_warning: true", "requirements: docs/requirements.txt"] },
+  { file: "mkdocs.yml", contains: ["name: material", "markdown_extensions:", "extra_css:", "javascripts/mermaid-init.js"] },
+  { file: "docs/getting-started.md", contains: ["npm create forgeos-app@alpha", "Open the web URL"] },
+  { file: "docs/agent-workflow.md", contains: ["forge do", "forge status --json", "forge handoff --json"] },
+  { file: "docs/troubleshooting.md", contains: ["FORGE_DELTA_BUSY", "waiting-for-user-trust", "Studio target preview issues"] },
+  { file: "docs/release.md", contains: ["release:verify-public-alpha", "Documentation checklist"] },
+  { file: "docs/self-host.md", contains: ["forge deploy check --production --json"] },
+];
+
+function read(workspaceRoot: string, relative: string): string | null {
+  const path = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(path)) {
+    return null;
+  }
+  return nodeFileSystem.readText(path) ?? "";
+}
+
+function checkFileExists(workspaceRoot: string, relative: string): DocsCheck {
+  return nodeFileSystem.exists(join(workspaceRoot, relative))
+    ? { name: relative, ok: true, status: "pass" }
+    : { name: relative, ok: false, status: "fail", details: { missing: true } };
+}
+
+function checkContains(workspaceRoot: string, file: string, contains: string[]): DocsCheck {
+  const content = read(workspaceRoot, file);
+  if (content === null) {
+    return { name: `${file}:content`, ok: false, status: "fail", details: { missing: true } };
+  }
+  const missing = contains.filter((needle) => !content.includes(needle));
+  return missing.length === 0
+    ? { name: `${file}:content`, ok: true, status: "pass" }
+    : { name: `${file}:content`, ok: false, status: "fail", details: { missing } };
+}
+
+function slugifyHeading(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_]/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-");
+}
+
+function anchorsFor(content: string): Set<string> {
+  const anchors = new Set<string>();
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^(#{1,6})\s+(.+)$/.exec(line);
+    if (match) {
+      anchors.add(slugifyHeading(match[2] ?? ""));
+    }
+  }
+  return anchors;
+}
+
+function checkYamlShape(workspaceRoot: string, relative: string, requiredKeys: string[]): DocsCheck {
+  const content = read(workspaceRoot, relative);
+  if (content === null) {
+    return { name: `${relative}:yaml`, ok: false, status: "fail", details: { missing: true } };
+  }
+  const malformed = content
+    .split(/\r?\n/)
+    .filter((line) => line.trim() && !line.trimStart().startsWith("#"))
+    .filter((line) => !/^\s*-\s+/.test(line))
+    .filter((line) => !line.includes(":"));
+  const missingKeys = requiredKeys.filter((key) => !new RegExp(`^${key}:`, "m").test(content));
+  const ok = malformed.length === 0 && missingKeys.length === 0;
+  return ok
+    ? { name: `${relative}:yaml`, ok: true, status: "pass" }
+    : { name: `${relative}:yaml`, ok: false, status: "fail", details: { malformed, missingKeys } };
+}
+
+function checkInternalLinks(workspaceRoot: string): DocsCheck {
+  const missing: Array<{ file: string; target: string }> = [];
+  const docs = nodeFileSystem.exists(join(workspaceRoot, "docs"))
+    ? nodeFileSystem.readDir(join(workspaceRoot, "docs"))
+      .filter((entry) => entry.name.endsWith(".md"))
+      .map((entry) => `docs/${entry.name}`)
+    : [];
+  for (const file of docs) {
+    const content = read(workspaceRoot, file) ?? "";
+    const links = [...content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)]
+      .map((match) => match[1] ?? "")
+      .filter((target) =>
+        target &&
+        !target.startsWith("http://") &&
+        !target.startsWith("https://") &&
+        !target.startsWith("mailto:") &&
+        !target.startsWith("#") &&
+        !target.startsWith("`")
+      );
+    for (const target of links) {
+      const [pathPart, anchor] = target.split("#");
+      const resolved = normalize(join(dirname(file), decodeURIComponent(pathPart ?? ""))).replace(/\\/g, "/");
+      if (!nodeFileSystem.exists(join(workspaceRoot, resolved))) {
+        missing.push({ file, target });
+        continue;
+      }
+      if (anchor) {
+        const targetContent = read(workspaceRoot, resolved) ?? "";
+        if (!anchorsFor(targetContent).has(anchor)) {
+          missing.push({ file, target });
+        }
+      }
+    }
+  }
+  return missing.length === 0
+    ? { name: "docs-internal-links", ok: true, status: "pass" }
+    : { name: "docs-internal-links", ok: false, status: "fail", details: { missing } };
+}
+
+function checkMkdocsTooling(workspaceRoot: string): DocsCheck {
+  const result = spawnSync("python3", ["-m", "mkdocs", "--version"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status === 0) {
+    return {
+      name: "mkdocs-tooling",
+      ok: true,
+      status: "pass",
+      details: { version: (result.stdout ?? "").trim() },
+    };
+  }
+  return {
+    name: "mkdocs-tooling",
+    ok: true,
+    status: "warning",
+    details: {
+      message: "mkdocs is not importable in the current Python environment; install docs/requirements.txt before building docs locally",
+    },
+  };
+}
+
+function runOptionalDocsBuild(options: DocsCheckOptions): DocsCheck[] {
+  const checks: DocsCheck[] = [];
+  const python = process.platform === "win32"
+    ? join(options.workspaceRoot, ".venv-rtd", "Scripts", "python.exe")
+    : join(options.workspaceRoot, ".venv-rtd", "bin", "python");
+  if (options.installVenv) {
+    const venv = spawnSync("python3", ["-m", "venv", ".venv-rtd"], {
+      cwd: options.workspaceRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    checks.push(venv.status === 0
+      ? { name: "mkdocs-venv-create", ok: true, status: "pass" }
+      : { name: "mkdocs-venv-create", ok: false, status: "fail", details: { stderr: venv.stderr } });
+    if (venv.status === 0) {
+      const install = spawnSync(python, ["-m", "pip", "install", "-r", "docs/requirements.txt"], {
+        cwd: options.workspaceRoot,
+        encoding: "utf8",
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      checks.push(install.status === 0
+        ? { name: "mkdocs-venv-install", ok: true, status: "pass" }
+        : { name: "mkdocs-venv-install", ok: false, status: "fail", details: { stderr: install.stderr } });
+    }
+  }
+  if (options.build) {
+    const command = options.installVenv ? python : "python3";
+    const args = ["-m", "mkdocs", "build", "--strict"];
+    const build = spawnSync(command, args, {
+      cwd: options.workspaceRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    checks.push(build.status === 0
+      ? { name: "mkdocs-build-strict", ok: true, status: "pass", details: { stdout: build.stdout?.trim() } }
+      : { name: "mkdocs-build-strict", ok: false, status: "fail", details: { stderr: build.stderr } });
+  }
+  return checks;
+}
+
+export function runDocsCheckCommand(options: DocsCheckOptions): DocsCheckResult {
+  const checks: DocsCheck[] = [
+    checkFileExists(options.workspaceRoot, ".readthedocs.yaml"),
+    checkFileExists(options.workspaceRoot, "mkdocs.yml"),
+    checkFileExists(options.workspaceRoot, "docs/requirements.txt"),
+    checkFileExists(options.workspaceRoot, "docs/stylesheets/forge.css"),
+    checkFileExists(options.workspaceRoot, "docs/javascripts/mermaid-init.js"),
+    ...REQUIRED_DOCS.map((file) => checkFileExists(options.workspaceRoot, `docs/${file}`)),
+    checkYamlShape(options.workspaceRoot, ".readthedocs.yaml", ["version", "build", "mkdocs"]),
+    checkYamlShape(options.workspaceRoot, "mkdocs.yml", ["site_name", "theme", "nav"]),
+    ...CONTENT_CHECKS.map((check) => checkContains(options.workspaceRoot, check.file, check.contains)),
+    checkInternalLinks(options.workspaceRoot),
+    checkMkdocsTooling(options.workspaceRoot),
+    ...runOptionalDocsBuild(options),
+  ];
+  const failed = checks.filter((check) => !check.ok);
+  const diagnostics = failed.map((check) => createDiagnostic({
+    severity: "error",
+    code: "FORGE_DOCS_CHECK_FAILED",
+    message: `documentation check failed: ${check.name}`,
+    suggestedCommands: ["forge docs check --json", "bun test tests/docs/readthedocs.test.ts"],
+  }));
+  const ok = failed.length === 0;
+  return {
+    ok,
+    checks,
+    diagnostics,
+    nextActions: ok
+      ? docsReadyNextActions()
+      : ["forge docs check --json", "bun test tests/docs/readthedocs.test.ts"],
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export function formatDocsCheckHuman(result: DocsCheckResult): string {
+  const lines = [
+    `docs check ${result.ok ? "ok" : "failed"}`,
+    ...result.checks.map((check) => `${check.status} ${check.name}`),
+  ];
+  if (result.nextActions.length > 0) {
+    lines.push("", "Next:", ...result.nextActions.map((action) => `  ${action}`));
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/doctor.ts

@@ -6,6 +6,12 @@ import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
 import type { TableMapEntry } from "../compiler/data-graph/sql/serialize.ts";
 import type { FrontendGraph } from "../compiler/types/frontend-graph.ts";
 import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import {
+  DEFAULT_PGLITE_DIR,
+  inspectPgliteStore,
+  type PgliteStoreInspection,
+} from "../runtime/db/pglite-adapter.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
 export interface DoctorCheck {
   name: string;
@@ -20,6 +26,49 @@ export interface DoctorResult {
   exitCode: 0 | 1;
 }
 
+export interface PgliteDoctorResult {
+  ok: boolean;
+  inspection: PgliteStoreInspection;
+  checks: DoctorCheck[];
+  dbGuide: LocalDbModeGuide;
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+export interface LocalDbModeGuide {
+  recommendedForCurrentState: "pglite" | "memory" | "stop-active-process" | "repair-pglite";
+  memory: {
+    command: string;
+    useWhen: string[];
+    tradeoff: string;
+  };
+  pglite: {
+    command: string;
+    useWhen: string[];
+    tradeoff: string;
+  };
+  repair?: {
+    command: string;
+    safeWhen: string;
+    preservesDataByArchiving: boolean;
+  };
+}
+
+export interface RuntimeDoctorResult {
+  ok: boolean;
+  checks: DoctorCheck[];
+  dev: {
+    pidFile: string;
+    logFile: string;
+    running: boolean;
+    pid?: number;
+  };
+  pglite: PgliteStoreInspection;
+  dbGuide: LocalDbModeGuide;
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
 function present(workspaceRoot: string, name: string, relative: string): DoctorCheck {
   const ok = nodeFileSystem.exists(join(workspaceRoot, relative));
   return {
@@ -92,6 +141,50 @@ function frontendDevAuthChecks(
     }));
 }
 
+function buildLocalDbModeGuide(workspaceRoot: string, pglite: PgliteStoreInspection): LocalDbModeGuide {
+  const memoryCommand = "forge dev --db memory --json";
+  const pgliteCommand = "forge dev --db pglite --json";
+  const repairCommand = "forge db repair --local --adapter pglite --json";
+  const recommendedForCurrentState: LocalDbModeGuide["recommendedForCurrentState"] =
+    pglite.state === "active"
+      ? "stop-active-process"
+      : pglite.state === "aborted" || pglite.state === "unhealthy"
+        ? "repair-pglite"
+        : pglite.openable
+          ? "pglite"
+          : "memory";
+  return normalizeForgeCliCommandsInValue(workspaceRoot, {
+    recommendedForCurrentState,
+    memory: {
+      command: memoryCommand,
+      useWhen: [
+        "you need a clean isolated smoke test",
+        "PGlite is active, aborted, or suspected corrupt",
+        "you do not need local data to persist after the process exits",
+      ],
+      tradeoff: "Fast and isolated, but data disappears when the dev process exits.",
+    },
+    pglite: {
+      command: pgliteCommand,
+      useWhen: [
+        "you want local data to persist between dev runs",
+        "you are reproducing real database behavior more closely than memory",
+        "doctor pglite reports the store is missing or healthy",
+      ],
+      tradeoff: "Persists local state, but a stale/corrupt .forge/pglite store can require repair.",
+    },
+    ...(pglite.state === "aborted" || pglite.state === "unhealthy"
+      ? {
+          repair: {
+            command: repairCommand,
+            safeWhen: "PGlite is not owned by a live forge dev process and doctor reports aborted/unhealthy.",
+            preservesDataByArchiving: true,
+          },
+        }
+      : {}),
+  }) as LocalDbModeGuide;
+}
+
 export async function runDoctorCommand(options: {
   workspaceRoot: string;
 }): Promise<DoctorResult> {
@@ -193,6 +286,151 @@ export async function runDoctorCommand(options: {
   };
 }
 
+export async function runPgliteDoctorCommand(options: {
+  workspaceRoot: string;
+}): Promise<PgliteDoctorResult> {
+  const dataDir = join(options.workspaceRoot, DEFAULT_PGLITE_DIR);
+  const inspection = await inspectPgliteStore(dataDir);
+  const ok = inspection.state === "missing" || inspection.state === "healthy";
+  const checks: DoctorCheck[] = [
+    {
+      name: "pglite-store",
+      ok,
+      severity: inspection.state === "active" ? "warning" : "error",
+      message: ok
+        ? `PGlite store is ${inspection.state}`
+        : inspection.error ?? `PGlite store is ${inspection.state}`,
+    },
+    {
+      name: "pglite-openable",
+      ok: inspection.openable,
+      severity: inspection.state === "active" ? "warning" : "error",
+      message: inspection.openable
+        ? undefined
+        : "local PGlite store cannot be opened by Forge dev",
+    },
+  ];
+
+  if (inspection.lockFiles.length > 0) {
+    checks.push({
+      name: "pglite-lock-files",
+      ok: inspection.state === "healthy",
+      severity: inspection.state === "active" ? "warning" : "error",
+      message: `lock files present: ${inspection.lockFiles.join(", ")}`,
+    });
+  }
+
+  const exitOk = checks.every((check) => check.ok || check.severity === "warning");
+  const dbGuide = buildLocalDbModeGuide(options.workspaceRoot, inspection);
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    ok: exitOk,
+    inspection,
+    checks,
+    dbGuide,
+    nextActions: inspection.nextActions,
+    exitCode: exitOk ? 0 : 1,
+  });
+}
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+}
+
+function readPid(path: string): number | undefined {
+  const text = nodeFileSystem.readText(path);
+  if (text === null) return undefined;
+  const pid = Number(text.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+export async function runRuntimeDoctorCommand(options: {
+  workspaceRoot: string;
+}): Promise<RuntimeDoctorResult> {
+  const checks: DoctorCheck[] = [];
+  const generated = await runGenerate({
+    workspaceRoot: options.workspaceRoot,
+    check: true,
+    dryRun: false,
+    json: false,
+    concurrency: 4,
+  });
+  checks.push({
+    name: "generated",
+    ok: generated.exitCode === 0,
+    severity: "error",
+    message: generated.exitCode === 0 ? "generated artifacts are fresh" : "generated artifacts are stale; run forge generate",
+  });
+
+  const devDir = join(options.workspaceRoot, ".forge", "dev");
+  const pidFile = join(devDir, "dev.pid");
+  const logFile = join(devDir, "dev.log");
+  const pid = readPid(pidFile);
+  const running = pid !== undefined && isProcessRunning(pid);
+  checks.push({
+    name: "dev-lifecycle",
+    ok: true,
+    severity: "warning",
+    message: running
+      ? `detached forge dev is running with pid ${pid}`
+      : "no detached forge dev server is running",
+  });
+
+  const pglite = await inspectPgliteStore(join(options.workspaceRoot, DEFAULT_PGLITE_DIR));
+  const pgliteOk = pglite.state === "missing" || pglite.state === "healthy" || pglite.state === "active";
+  checks.push({
+    name: "pglite-store",
+    ok: pgliteOk,
+    severity: pglite.state === "active" ? "warning" : "error",
+    message: pglite.error ?? `PGlite store is ${pglite.state}`,
+  });
+  checks.push({
+    name: "pglite-openable",
+    ok: pglite.openable || pglite.state === "active",
+    severity: pglite.state === "active" ? "warning" : "error",
+    message: pglite.openable
+      ? "PGlite store is openable"
+      : pglite.state === "active"
+        ? "PGlite store is owned by a live process"
+        : "PGlite store cannot be opened",
+  });
+
+  const ok = checks.every((check) => check.ok || check.severity === "warning");
+  const dbGuide = buildLocalDbModeGuide(options.workspaceRoot, pglite);
+  const nextActions = ok
+    ? ["forge dev --once --json", "forge dev status --json"]
+    : [
+        ...(generated.exitCode === 0 ? [] : ["forge generate"]),
+        ...(pglite.state === "active"
+          ? ["stop the running forge dev process that owns .forge/pglite", "forge doctor pglite --json"]
+          : []),
+        ...(pglite.state === "aborted" || pglite.state === "unhealthy"
+          ? ["forge doctor pglite --json", "forge db repair --local --adapter pglite --json", "forge dev --db memory --json"]
+          : []),
+        ...(!pglite.openable && pglite.state !== "active" && pglite.state !== "aborted" && pglite.state !== "unhealthy"
+          ? ["forge doctor pglite --json", "forge dev --db memory --json"]
+          : []),
+      ];
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    ok,
+    checks,
+    dev: {
+      pidFile,
+      logFile,
+      running,
+      ...(pid !== undefined ? { pid } : {}),
+    },
+    pglite,
+    dbGuide,
+    nextActions: [...new Set(nextActions)],
+    exitCode: ok ? 0 : 1,
+  });
+}
+
 export function formatDoctorJson(result: DoctorResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
@@ -207,3 +445,62 @@ export function formatDoctorHuman(result: DoctorResult): string {
   lines.push(result.ok ? "Project is coherent." : "Project needs attention.");
   return `${lines.join("\n")}\n`;
 }
+
+export function formatPgliteDoctorJson(result: PgliteDoctorResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatPgliteDoctorHuman(result: PgliteDoctorResult): string {
+  const lines = ["Forge PGlite Doctor", ""];
+  for (const check of result.checks) {
+    const marker = check.ok ? "OK" : check.severity === "warning" ? "WARN" : "FAIL";
+    lines.push(`${marker} ${check.name}${check.message ? ` - ${check.message}` : ""}`);
+  }
+  lines.push("");
+  lines.push(`Store: ${result.inspection.dataDir}`);
+  lines.push(`State: ${result.inspection.state}`);
+  lines.push(`Recommended DB mode: ${result.dbGuide.recommendedForCurrentState}`);
+  lines.push(`Memory: ${result.dbGuide.memory.command} - ${result.dbGuide.memory.tradeoff}`);
+  lines.push(`PGlite: ${result.dbGuide.pglite.command} - ${result.dbGuide.pglite.tradeoff}`);
+  if (result.dbGuide.repair) {
+    lines.push(`Repair: ${result.dbGuide.repair.command}`);
+  }
+  if (result.nextActions.length > 0) {
+    lines.push("");
+    lines.push("Next actions:");
+    for (const action of result.nextActions) {
+      lines.push(`  ${action}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatRuntimeDoctorJson(result: RuntimeDoctorResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatRuntimeDoctorHuman(result: RuntimeDoctorResult): string {
+  const lines = ["Forge Runtime Doctor", ""];
+  for (const check of result.checks) {
+    const marker = check.ok ? "OK" : check.severity === "warning" ? "WARN" : "FAIL";
+    lines.push(`${marker} ${check.name}${check.message ? ` - ${check.message}` : ""}`);
+  }
+  lines.push("");
+  lines.push(`Dev pid file: ${result.dev.pidFile}`);
+  lines.push(`Dev log file: ${result.dev.logFile}`);
+  lines.push(`PGlite state: ${result.pglite.state}`);
+  lines.push(`Recommended DB mode: ${result.dbGuide.recommendedForCurrentState}`);
+  lines.push(`Memory: ${result.dbGuide.memory.command} - ${result.dbGuide.memory.tradeoff}`);
+  lines.push(`PGlite: ${result.dbGuide.pglite.command} - ${result.dbGuide.pglite.tradeoff}`);
+  if (result.dbGuide.repair) {
+    lines.push(`Repair: ${result.dbGuide.repair.command}`);
+  }
+  if (result.nextActions.length > 0) {
+    lines.push("");
+    lines.push("Next actions:");
+    for (const action of result.nextActions) {
+      lines.push(`  ${action}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/env-placeholders.ts

@@ -0,0 +1,62 @@
+export interface PlaceholderEnvProblem {
+  key: string;
+  reason: string;
+}
+
+const GENERIC_PLACEHOLDER_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
+  { pattern: /\bexample\.(com|test|org|net)\b/, reason: "example domain" },
+  { pattern: /\bdummy\b/, reason: "dummy marker" },
+  { pattern: /\bplaceholder\b/, reason: "placeholder marker" },
+  { pattern: /\bchange[-_]?me\b/, reason: "change-me marker" },
+  { pattern: /\bdo[-_]?not[-_]?use\b/, reason: "do-not-use marker" },
+  { pattern: /^<.*>$/, reason: "angle-bracket placeholder" },
+  { pattern: /^your[-_]/, reason: "your-value placeholder" },
+];
+
+const KEY_PLACEHOLDER_PATTERNS: Record<string, Array<{ pattern: RegExp; reason: string }>> = {
+  DATABASE_URL: [
+    { pattern: /^postgres:\/\/forge:forge@postgres:5432\/forge_app$/i, reason: "generated Docker example database URL" },
+    { pattern: /^postgres:\/\/forge:forge@db:5432\/forge$/i, reason: "local dummy database URL" },
+    { pattern: /^postgres:\/\/local-only\b/i, reason: "local-only database URL" },
+  ],
+  WORKOS_API_KEY: [
+    { pattern: /^sk_test_dummy/i, reason: "dummy WorkOS API key" },
+    { pattern: /^sk_test_?\.\.\.$/i, reason: "placeholder WorkOS API key" },
+  ],
+  WORKOS_CLIENT_ID: [
+    { pattern: /^client_?\.\.\.$/i, reason: "placeholder WorkOS client id" },
+    { pattern: /^client_test_local$/i, reason: "local fake WorkOS client id" },
+  ],
+  WORKOS_COOKIE_PASSWORD: [
+    { pattern: /dummy/i, reason: "dummy cookie password" },
+    { pattern: /change[-_]?me/i, reason: "change-me cookie password" },
+  ],
+  FORGE_AUTH_AUDIENCE: [
+    { pattern: /^client_test_local$/i, reason: "local fake auth audience" },
+  ],
+  FORGE_AUTH_JWKS_URI: [
+    { pattern: /\/client_test_local$/i, reason: "local fake JWKS client id" },
+  ],
+};
+
+export function placeholderEnvProblem(key: string, value: string | undefined): PlaceholderEnvProblem | null {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed) return null;
+  const normalized = trimmed.toLowerCase();
+  for (const { pattern, reason } of KEY_PLACEHOLDER_PATTERNS[key] ?? []) {
+    if (pattern.test(trimmed)) return { key, reason };
+  }
+  for (const { pattern, reason } of GENERIC_PLACEHOLDER_PATTERNS) {
+    if (pattern.test(normalized)) return { key, reason };
+  }
+  return null;
+}
+
+export function productionPlaceholderEnvProblems(
+  values: Record<string, string>,
+  keys = Object.keys(values),
+): PlaceholderEnvProblem[] {
+  return keys
+    .map((key) => placeholderEnvProblem(key, values[key]))
+    .filter((problem): problem is PlaceholderEnvProblem => Boolean(problem));
+}

package/src/forge/cli/evolution.ts

@@ -0,0 +1,40 @@
+import { realpathSync } from "node:fs";
+import { LocalEvolutionService } from "../agent-fabric/local-evolution-service.ts";
+import type { EvolutionChannel, EvolutionDecisionAction } from "../agent-fabric/local-evolution-registry.ts";
+
+export interface EvolutionCliOptions {
+  subcommand: "register" | "evaluate" | "status" | "review" | "load";
+  workspaceRoot: string;
+  json: boolean;
+  manifest?: string;
+  versionId?: string;
+  action?: EvolutionDecisionAction;
+  extensionKey?: string;
+  channel?: EvolutionChannel;
+}
+
+export async function runEvolutionCommand(options: EvolutionCliOptions): Promise<number> {
+  let service: LocalEvolutionService | undefined;
+  try {
+    service = await LocalEvolutionService.open(realpathSync(options.workspaceRoot));
+    const result = options.subcommand === "register"
+      ? await service.register(options.manifest!)
+      : options.subcommand === "evaluate"
+        ? await service.evaluate(options.versionId!)
+        : options.subcommand === "status"
+          ? await service.status(options.versionId!)
+          : options.subcommand === "review"
+            ? await service.decide(options.action!, options.versionId!)
+            : await service.loadSelected(options.extensionKey!, options.channel!);
+    // The CLI loader reports verified metadata. Library callers can consume the verified bytes.
+    const output = "artifact" in result ? { versionId: result.versionId,
+      extensionKey: result.manifest.extensionKey, artifactBytes: result.artifact.length } : result;
+    process.stdout.write(options.json ? `${JSON.stringify({ ok: true, result: output }, null, 2)}\n` :
+      `${JSON.stringify(output, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(options.json ? `${JSON.stringify({ ok: false, error: message }, null, 2)}\n` : `error: ${message}\n`);
+    return 1;
+  } finally { await service?.close(); }
+}