forgeos 0.1.0-alpha.31 → 0.1.0-alpha.32

package/src/forge/cli/db.ts

@@ -30,6 +30,7 @@ import {
   DEFAULT_PGLITE_DIR,
   repairLocalPgliteStore,
 } from "../runtime/db/pglite-adapter.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
 export type DbSubcommand = "diff" | "migrate" | "reset" | "status" | "doctor" | "repair" | "rls-check";
 
@@ -258,7 +259,7 @@ async function runDbDoctor(
       .sort();
     const ok = inspected.diagnostics.length === 0 && missingTables.length === 0 && missingColumns.length === 0;
 
-    return {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
       ok,
       data: {
         schemaVersion: "0.1.0",
@@ -287,7 +288,7 @@ async function runDbDoctor(
         ...inspected.diagnostics,
       ],
       exitCode: ok ? 0 : 1,
-    };
+    });
   } finally {
     await adapter.close();
   }
@@ -295,7 +296,7 @@ async function runDbDoctor(
 
 async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult> {
   if (!options.local) {
-    return {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
       ok: false,
       data: {
         schemaVersion: "0.1.0",
@@ -314,11 +315,11 @@ async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult>
         }),
       ],
       exitCode: 1,
-    };
+    });
   }
 
   if (options.db !== "pglite") {
-    return {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
       ok: false,
       data: {
         schemaVersion: "0.1.0",
@@ -336,7 +337,7 @@ async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult>
         }),
       ],
       exitCode: 1,
-    };
+    });
   }
 
   const dataDir = join(options.workspaceRoot, DEFAULT_PGLITE_DIR);
@@ -355,7 +356,7 @@ async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult>
         }),
       ];
 
-  return {
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     ok: result.ok,
     data: {
       schemaVersion: "0.1.0",
@@ -365,7 +366,7 @@ async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult>
     },
     diagnostics,
     exitCode: result.ok ? 0 : 1,
-  };
+  });
 }
 
 export async function runDbCommand(options: DbCommandOptions): Promise<DbCommandResult> {

package/src/forge/cli/dev.ts

@@ -31,6 +31,7 @@ import { createAmbientDeltaRecorder } from "../delta/index.ts";
 import { resetCompileSessions } from "../compiler/orchestrator/session.ts";
 import { FORGE_PGLITE_STORE_ABORTED } from "../compiler/diagnostics/codes.ts";
 import { isPgliteAbortMessage } from "../runtime/db/pglite-adapter.ts";
+import { forgeCliCommandForWorkspace, forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
 import { writeLastRunRecord } from "./last-run.ts";
 
 export interface DevCommandOptions {
@@ -95,6 +96,7 @@ interface DevStartupSummary {
   schemaVersion: "0.1.0";
   ok: true;
   mode: "dev";
+  warnings: Array<{ code: string; message: string; nextAction?: string }>;
   api: {
     url: string;
     host: string;
@@ -289,6 +291,63 @@ function classifyDevStartFailure(input: {
   };
 }
 
+function writeDevStartFailure(input: {
+  workspaceRoot: string;
+  startedAt: Date;
+  finishedAt: Date;
+  options: DevCommandOptions;
+  host: string;
+  port: number;
+  failure: DevStartFailure;
+}): DevCommandResult {
+  const nextActions = forgeCliCommandsForWorkspace(input.workspaceRoot, input.failure.nextActions);
+  const busy = input.failure.busy
+    ? {
+        ...input.failure.busy,
+        suggestedCommands: forgeCliCommandsForWorkspace(input.workspaceRoot, input.failure.busy.suggestedCommands),
+      }
+    : undefined;
+  writeLastRunRecord(input.workspaceRoot, {
+    schemaVersion: "0.1.0",
+    command: forgeCliCommandForWorkspace(input.workspaceRoot, "forge dev"),
+    ok: false,
+    startedAt: input.startedAt.toISOString(),
+    finishedAt: input.finishedAt.toISOString(),
+    durationMs: input.finishedAt.getTime() - input.startedAt.getTime(),
+    ...(input.failure.code ? { code: input.failure.code } : {}),
+    failureKind: input.failure.failureKind,
+    message: input.failure.message,
+    nextActions,
+    details: {
+      db: input.options.db,
+      host: input.host,
+      port: input.port,
+    },
+  });
+  if (input.options.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        error: input.failure.message,
+        code: input.failure.code,
+        failureKind: input.failure.failureKind,
+        busy,
+        nextActions,
+        exitCode: 1,
+      })}\n`,
+    );
+  } else {
+    console.error(`error${input.failure.code ? ` ${input.failure.code}` : ""}: ${input.failure.message}`);
+    if (nextActions.length > 0) {
+      console.error("next:");
+      for (const action of nextActions) {
+        console.error(`  ${action}`);
+      }
+    }
+  }
+  return { exitCode: 1 };
+}
+
 export async function resolveAvailableWebPort(input: {
   host: string;
   preferredPort: number;
@@ -493,6 +552,16 @@ function buildStartupSummary(input: {
     ? [...new Set(frontend.clientBindings.map((binding) => `${binding.kind}:${binding.name}`))].sort()
     : [];
   const browserUrl = input.web?.url ?? input.handle.url;
+  const warnings = input.handle.state.db.kind === "memory"
+    ? [
+        {
+          code: "FORGE_DEV_MEMORY_DB_FIDELITY",
+          message:
+            "Memory DB is fast and non-persistent; PGlite/Postgres remain the authoritative checks for full SQL constraints and adapter fidelity.",
+          nextAction: `rerun with ${forgeCliCommandForWorkspace(input.workspaceRoot, "forge dev --db pglite --once --json")} before treating the result as database-realistic`,
+        },
+      ]
+    : [];
   const preview = previewSummaryFor({
     workspaceRoot: input.workspaceRoot,
     host: input.handle.host,
@@ -502,6 +571,7 @@ function buildStartupSummary(input: {
     schemaVersion: "0.1.0",
     ok: true,
     mode: "dev",
+    warnings,
     api: {
       url: input.handle.url,
       host: input.handle.host,
@@ -553,15 +623,15 @@ function buildStartupSummary(input: {
       changedFiles: input.generated?.changedFiles ?? 0,
       sampleChanged: input.generated?.sampleChanged ?? [],
       hiddenChanged: input.generated?.hiddenChanged ?? 0,
-      command: input.generated?.command ?? "forge generate",
-      checkCommand: input.generated?.checkCommand ?? "forge generate --check --json",
+      command: input.generated?.command ?? forgeCliCommandForWorkspace(input.workspaceRoot, "forge generate"),
+      checkCommand: input.generated?.checkCommand ?? forgeCliCommandForWorkspace(input.workspaceRoot, "forge generate --check --json"),
       message: input.generated?.message ?? (buildInfoRaw ? "generated artifacts are loaded" : "generated build info is missing"),
     },
     next: {
       browserUrl,
       apiIndex: input.handle.url,
-      inspect: "forge inspect summary --json",
-      verify: "forge dev --once --json",
+      inspect: forgeCliCommandForWorkspace(input.workspaceRoot, "forge inspect summary --json"),
+      verify: forgeCliCommandForWorkspace(input.workspaceRoot, "forge dev --once --json"),
     },
     pid: process.pid,
   };
@@ -582,6 +652,12 @@ function printStartupHuman(summary: DevStartupSummary): void {
   lines.push(`  Generated: ${summary.generated.state}${summary.generated.changedFiles > 0 ? ` (${summary.generated.changedFiles} changed)` : ""}${summary.generated.runtimeStaleRisk ? " (stale risk)" : ""}`);
   lines.push(`  Generated note: ${summary.generated.message}`);
   lines.push(`  Generated check: ${summary.generated.checkCommand}`);
+  for (const warning of summary.warnings) {
+    lines.push(`  Warning ${warning.code}: ${warning.message}`);
+    if (warning.nextAction) {
+      lines.push(`  Next: ${warning.nextAction}`);
+    }
+  }
   lines.push("");
 
   lines.push("Web app");
@@ -683,12 +759,15 @@ export function generatedEvidenceFromCycle(cycle: DevConsoleCycle): DevStartupGe
     sampleChanged,
     hiddenChanged,
     message: phase?.message ?? "generated phase did not report a message",
-    command: "forge generate",
-    checkCommand: "forge generate --check --json",
+    command: cycle.summary.generated.command,
+    checkCommand: cycle.summary.generated.checkCommand,
   };
 }
 
-export function generatedEvidenceFromGenerateResult(result: DevGenerateResult): DevStartupGeneratedEvidence {
+export function generatedEvidenceFromGenerateResult(
+  result: DevGenerateResult,
+  options: { workspaceRoot?: string } = {},
+): DevStartupGeneratedEvidence {
   return {
     ok: result.ok,
     state: result.ok ? result.changed.length > 0 ? "regenerated" : "fresh" : "stale-risk",
@@ -700,8 +779,12 @@ export function generatedEvidenceFromGenerateResult(result: DevGenerateResult):
         ? `regenerated ${result.changed.length} generated artifacts`
         : "generated artifacts are up to date"
       : "generated artifacts could not be regenerated",
-    command: "forge generate",
-    checkCommand: "forge generate --check --json",
+    command: options.workspaceRoot
+      ? forgeCliCommandForWorkspace(options.workspaceRoot, "forge generate")
+      : "forge generate",
+    checkCommand: options.workspaceRoot
+      ? forgeCliCommandForWorkspace(options.workspaceRoot, "forge generate --check --json")
+      : "forge generate --check --json",
   };
 }
 
@@ -725,16 +808,20 @@ export function buildDevWatchGenerateFailureEvent(input: {
   changedCount: number;
   changedPaths: string[];
   result: DevGenerateResult;
+  workspaceRoot?: string;
 }): DevWatchGenerateFailureEvent {
+  const nextActions = input.workspaceRoot
+    ? forgeCliCommandsForWorkspace(input.workspaceRoot, ["forge dev --once --json", "forge check --json"])
+    : ["forge dev --once --json", "forge check --json"];
   return {
     schemaVersion: "0.1.0",
     event: "dev.generate_failed",
     ok: false,
     changedFiles: input.changedCount,
     changedPaths: input.changedPaths,
-    generated: generatedEvidenceFromGenerateResult(input.result),
+    generated: generatedEvidenceFromGenerateResult(input.result, { workspaceRoot: input.workspaceRoot }),
     diagnostics: input.result.diagnostics,
-    nextActions: ["forge dev --once --json", "forge check --json"],
+    nextActions,
   };
 }
 
@@ -744,7 +831,11 @@ export function buildDevWatchReloadEvent(input: {
   generated: DevGenerateResult;
   reload: Awaited<ReturnType<DevServerHandle["reload"]>>;
   cycle: DevConsoleCycle;
+  workspaceRoot?: string;
 }): DevWatchReloadEvent {
+  const failureNextActions = input.workspaceRoot
+    ? forgeCliCommandsForWorkspace(input.workspaceRoot, ["forge dev --once --json", "forge check --json"])
+    : ["forge dev --once --json", "forge check --json"];
   return {
     schemaVersion: "0.1.0",
     event: "dev.reload",
@@ -756,12 +847,12 @@ export function buildDevWatchReloadEvent(input: {
     runtimeEntries: input.reload.runtimeEntries,
     worker: input.reload.worker,
     diagnostics: input.reload.diagnostics,
-    generated: generatedEvidenceFromGenerateResult(input.generated),
+    generated: generatedEvidenceFromGenerateResult(input.generated, { workspaceRoot: input.workspaceRoot }),
     preview: input.cycle.summary.preview,
     agentContext: input.cycle.summary.agentContext,
     nextActions: input.reload.ok
       ? input.cycle.summary.agentContext.recommendedCommands
-      : ["forge dev --once --json", "forge check --json"],
+      : failureNextActions,
   };
 }
 
@@ -784,6 +875,24 @@ export async function runDevCommand(
 
   const host = resolveDevHost(options.host);
   const port = resolveDevPort(options.port);
+  if (!options.webOnly && !(await isPortAvailable(host, port))) {
+    const failure = classifyDevStartFailure({
+      rawMessage: `listen EADDRINUSE: address already in use ${host}:${port}`,
+      host,
+      port,
+      webPort: options.webPort,
+      db: options.db,
+    });
+    return writeDevStartFailure({
+      workspaceRoot,
+      startedAt,
+      finishedAt: new Date(),
+      options,
+      host,
+      port,
+      failure,
+    });
+  }
   const requestedWebPort = options.webPort ?? detectDefaultWebPort(workspaceRoot);
   const shouldStartWeb =
     options.webOnly === true ||
@@ -913,45 +1022,15 @@ export async function runDevCommand(
       webPort: options.webPort,
       db: options.db,
     });
-    writeLastRunRecord(workspaceRoot, {
-      schemaVersion: "0.1.0",
-      command: "forge dev",
-      ok: false,
-      startedAt: startedAt.toISOString(),
-      finishedAt: finishedAt.toISOString(),
-      durationMs: finishedAt.getTime() - startedAt.getTime(),
-      ...(failure.code ? { code: failure.code } : {}),
-      failureKind: failure.failureKind,
-      message: failure.message,
-      nextActions: failure.nextActions,
-      details: {
-        db: options.db,
-        host,
-        port,
-      },
+    return writeDevStartFailure({
+      workspaceRoot,
+      startedAt,
+      finishedAt,
+      options,
+      host,
+      port,
+      failure,
     });
-    if (options.json) {
-      process.stdout.write(
-        `${JSON.stringify({
-          ok: false,
-          error: failure.message,
-          code: failure.code,
-          failureKind: failure.failureKind,
-          busy: failure.busy,
-          nextActions: failure.nextActions,
-          exitCode: 1,
-        })}\n`,
-      );
-    } else {
-      console.error(`error${failure.code ? ` ${failure.code}` : ""}: ${failure.message}`);
-      if (failure.nextActions.length > 0) {
-        console.error("next:");
-        for (const action of failure.nextActions) {
-          console.error(`  ${action}`);
-        }
-      }
-    }
-    return { exitCode: 1 };
   }
 
   const webHandle = !shouldStartWeb
@@ -990,11 +1069,11 @@ export async function runDevCommand(
       ok: true,
       startedAt: startedAt.toISOString(),
       finishedAt: finishedAt.toISOString(),
-      durationMs: finishedAt.getTime() - startedAt.getTime(),
-      nextActions: [
-        webHandle?.url ?? handle.url,
-        "forge last --json",
-      ],
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+    nextActions: [
+      webHandle?.url ?? handle.url,
+      forgeCliCommandForWorkspace(workspaceRoot, "forge last --json"),
+    ],
       details: {
         db: handle.state.db.kind,
         apiUrl: handle.url,
@@ -1059,6 +1138,7 @@ export async function runDevCommand(
             },
             reload,
             cycle,
+            workspaceRoot,
           }))}\n`);
         }
         if (!reload.ok && !options.json) {
@@ -1083,6 +1163,7 @@ export async function runDevCommand(
               diagnostics: [...result.errors, ...result.warnings],
               exitCode: 1,
             },
+            workspaceRoot,
           }))}\n`);
         } else {
           console.error(`[forge dev] regeneration failed after ${changedCount} changed files; runtime was not reloaded`);

package/src/forge/cli/doctor.ts

@@ -11,6 +11,7 @@ import {
   inspectPgliteStore,
   type PgliteStoreInspection,
 } from "../runtime/db/pglite-adapter.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
 export interface DoctorCheck {
   name: string;
@@ -241,13 +242,13 @@ export async function runPgliteDoctorCommand(options: {
   }
 
   const exitOk = checks.every((check) => check.ok || check.severity === "warning");
-  return {
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     ok: exitOk,
     inspection,
     checks,
     nextActions: inspection.nextActions,
     exitCode: exitOk ? 0 : 1,
-  };
+  });
 }
 
 export function formatDoctorJson(result: DoctorResult): string {

package/src/forge/cli/handoff.ts

@@ -6,6 +6,7 @@ import type { DevConsoleCycle, DevConsolePhase } from "../dev-console/types.ts";
 import type { TestRunRecord } from "../impact/types.ts";
 import type { UiRunReport } from "../ui/types.ts";
 import { summarizeChangeTypes, type CategorizedFileSummary } from "../workspace/change-summary.ts";
+import { forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
 import { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
 
 export interface HandoffCommandOptions {
@@ -92,6 +93,14 @@ export interface HandoffCommandResult {
     recommendedCommands: string[];
     risks: string[];
   };
+  diagnosticSummary: {
+    total: number;
+    sample: Diagnostic[];
+    hidden: number;
+    bySeverity: Record<string, number>;
+    byCode: Record<string, number>;
+    fullDiagnosticsCommands: string[];
+  };
   diagnostics: Diagnostic[];
   nextActions: string[];
   exitCode: 0 | 1;
@@ -162,11 +171,37 @@ function buildOpeningBrief(input: {
   ].join(" ");
 }
 
+function compactDiagnostics(
+  workspaceRoot: string,
+  diagnostics: Diagnostic[],
+  sampleSize = 8,
+): HandoffCommandResult["diagnosticSummary"] {
+  const bySeverity: Record<string, number> = {};
+  const byCode: Record<string, number> = {};
+  for (const diagnostic of diagnostics) {
+    bySeverity[diagnostic.severity] = (bySeverity[diagnostic.severity] ?? 0) + 1;
+    byCode[diagnostic.code] = (byCode[diagnostic.code] ?? 0) + 1;
+  }
+  return {
+    total: diagnostics.length,
+    sample: diagnostics.slice(0, sampleSize),
+    hidden: Math.max(0, diagnostics.length - sampleSize),
+    bySeverity,
+    byCode,
+    fullDiagnosticsCommands: forgeCliCommandsForWorkspace(workspaceRoot, [
+      "forge dev --once --json",
+      "forge inspect all --full --json",
+      "forge generate --check --json",
+    ]),
+  };
+}
+
 export async function runHandoffCommand(options: HandoffCommandOptions): Promise<HandoffCommandResult> {
   const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
   const dev = await runDevConsoleCycle({
     workspaceRoot,
     mode: "once",
+    generatedMode: "check",
     includeImpact: true,
   });
   const git = buildWorkspaceGitSummary(workspaceRoot);
@@ -185,14 +220,17 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
   ];
   const nextActions = [
     ...agent.recommendedCommands,
-    ...(git.changed.count > 0 ? ["forge review run --changed --json"] : []),
-    "forge handoff --json",
+    ...forgeCliCommandsForWorkspace(workspaceRoot, [
+      ...(git.changed.count > 0 ? ["forge review run --changed --json"] : []),
+      "forge handoff --json",
+    ]),
   ];
   const ok = dev.ok &&
     agent.blockingIssues.length === 0 &&
     (!recentRuns.test || recentRuns.test.ok) &&
     (!recentRuns.ui || recentRuns.ui.ok);
   const changedFiles = Math.max(agent.changedFiles, git.changed.count);
+  const diagnosticSummary = compactDiagnostics(workspaceRoot, dev.diagnostics);
 
   return {
     schemaVersion: "0.1.0",
@@ -231,7 +269,8 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
       recommendedCommands: [...new Set(nextActions)].slice(0, 10),
       risks,
     },
-    diagnostics: dev.diagnostics,
+    diagnosticSummary,
+    diagnostics: diagnosticSummary.sample,
     nextActions: [...new Set(nextActions)].slice(0, 10),
     exitCode: ok ? 0 : 1,
   };
@@ -256,6 +295,14 @@ export function formatHandoffHuman(result: HandoffCommandResult): string {
     lines.push("", "Risks:");
     lines.push(...result.nextAgent.risks.slice(0, 6).map((risk) => `  ${risk}`));
   }
+  if (result.diagnosticSummary.total > 0) {
+    lines.push(
+      "",
+      "Diagnostics:",
+      `  ${result.diagnosticSummary.total} total` +
+        (result.diagnosticSummary.hidden > 0 ? ` (${result.diagnosticSummary.hidden} hidden in compact handoff)` : ""),
+    );
+  }
   const changedTypes = summarizeChangeTypes(result.git.changeSummary.changed);
   if (changedTypes) {
     lines.push("", "Change types:", `  ${changedTypes}`);

package/src/forge/cli/main.ts

@@ -14,6 +14,8 @@ function formatHelp(): string {
     "  forge status --json       Compact project health, handoff state, and next actions",
     "  forge changed --json      Group changed files into human, generated, and risk buckets",
     "  forge changed --authored --json  Show only authored changed files, excluding generated artifacts",
+    "  forge changed --review --json  Show review-focused app/config/docs changes, excluding local agent/browser artifacts",
+    "  forge new my-app --template minimal-web --field-test  Create an installed WorkOS/auth.md field-test app",
     "  forge diff authored       Run the authored-only git diff pathspec",
     "  forge handoff --json      Compact work handoff for the next external code agent",
     "  forge agent onboard --target codex --json  Prepare adapter, hooks, memory, and dev snapshot",
@@ -28,7 +30,7 @@ function formatHelp(): string {
     "  forge workos install --yes --json  Delegate AuthKit setup to npx --yes workos@latest install",
     "  forge workos doctor --json  Check WorkOS AuthKit/FGA files, claims, seed, webhook, and tenant guards",
     "  forge workos doctor --yes --json  Run local checks, then delegate to npx --yes workos@latest doctor",
-    "  forge workos seed --file src/forge/_generated/integrations/workos/workos-seed.yml --json  Plan WorkOS CLI seed",
+    "  forge workos seed --file workos-seed.yml --json  Plan WorkOS CLI seed",
     "  forge release check --allow-missing-local-release --json  Gate release readiness without failing on unprepared local artifacts",
     "  forge self-host check --prepared-only --json  Report compose readiness without creating deploy files",
     "  forge delta status --verbose --json  Include Delta schema, lock, and aggregate count details",