forgeos 0.1.0-alpha.32 → 0.1.0-alpha.34

package/src/forge/cli/dev.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
 import { createServer as createNetServer } from "node:net";
 import { run } from "../compiler/orchestrator/run.ts";
 import { basename, join } from "node:path";
@@ -56,6 +57,8 @@ export interface DevCommandOptions {
   mode?: "dev" | "serve";
   allowDevAuth?: boolean;
   skipStartupConsole?: boolean;
+  detach?: boolean;
+  lifecycle?: "status" | "stop";
 }
 
 export interface DevCommandResult {
@@ -173,6 +176,221 @@ interface DevStartFailure {
   };
 }
 
+const DEV_STATE_DIR = ".forge/dev";
+const DEV_PID_FILE = `${DEV_STATE_DIR}/dev.pid`;
+const DEV_LOG_FILE = `${DEV_STATE_DIR}/dev.log`;
+
+function devStatePaths(workspaceRoot: string): { dir: string; pidFile: string; logFile: string } {
+  return {
+    dir: join(workspaceRoot, DEV_STATE_DIR),
+    pidFile: join(workspaceRoot, DEV_PID_FILE),
+    logFile: join(workspaceRoot, DEV_LOG_FILE),
+  };
+}
+
+function readDetachedDevPid(workspaceRoot: string): number | null {
+  const text = nodeFileSystem.readText(devStatePaths(workspaceRoot).pidFile);
+  if (text === null) {
+    return null;
+  }
+  const pid = Number(text.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+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 removeDevPidFile(workspaceRoot: string): void {
+  const paths = devStatePaths(workspaceRoot);
+  if (nodeFileSystem.exists(paths.pidFile)) {
+    nodeFileSystem.remove(paths.pidFile);
+  }
+}
+
+function printDevLifecycleResult(input: {
+  options: DevCommandOptions;
+  ok: boolean;
+  action: "detach" | "status" | "stop";
+  running: boolean;
+  pid?: number;
+  logFile: string;
+  message: string;
+  exitCode: 0 | 1;
+}): DevCommandResult {
+  const payload = {
+    ok: input.ok,
+    action: input.action,
+    running: input.running,
+    ...(input.pid !== undefined ? { pid: input.pid } : {}),
+    logFile: input.logFile,
+    message: input.message,
+    nextActions: input.running
+      ? ["forge dev status --json", "forge dev stop --json", `tail -f ${input.logFile}`]
+      : ["forge dev --detach --json"],
+    exitCode: input.exitCode,
+  };
+  if (input.options.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${input.message}\n`);
+    if (input.pid !== undefined) process.stdout.write(`pid: ${input.pid}\n`);
+    process.stdout.write(`log: ${input.logFile}\n`);
+  }
+  return { exitCode: input.exitCode };
+}
+
+function buildDetachedDevArgs(options: DevCommandOptions): string[] {
+  const args = ["dev", "--skip-startup-console"];
+  if (options.host) args.push("--host", options.host);
+  if (options.port !== undefined) args.push("--port", String(options.port));
+  if (options.mock) args.push("--mock");
+  if (options.mockAi) args.push("--mock-ai");
+  if (!options.watch) args.push("--no-watch");
+  if (options.db) args.push("--db", options.db);
+  if (options.databaseUrl) args.push("--database-url", options.databaseUrl);
+  if (!options.worker) args.push("--no-worker");
+  if (options.withWeb === false) args.push("--no-web");
+  if (options.apiOnly) args.push("--api-only");
+  if (options.webOnly) args.push("--web-only");
+  if (options.open) args.push("--open");
+  if (options.webPort !== undefined) args.push("--web-port", String(options.webPort));
+  if (options.telemetry.length > 0) args.push("--telemetry", options.telemetry.join(","));
+  if (options.envFile) args.push("--env-file", options.envFile);
+  return args;
+}
+
+function runDevStatus(options: DevCommandOptions): DevCommandResult {
+  const paths = devStatePaths(options.workspaceRoot);
+  const pid = readDetachedDevPid(options.workspaceRoot);
+  const running = pid !== null && isProcessRunning(pid);
+  if (pid !== null && !running) {
+    removeDevPidFile(options.workspaceRoot);
+  }
+  return printDevLifecycleResult({
+    options,
+    ok: true,
+    action: "status",
+    running,
+    ...(pid !== null ? { pid } : {}),
+    logFile: paths.logFile,
+    message: running ? "forge dev detached server is running" : "forge dev detached server is not running",
+    exitCode: 0,
+  });
+}
+
+function runDevStop(options: DevCommandOptions): DevCommandResult {
+  const paths = devStatePaths(options.workspaceRoot);
+  const pid = readDetachedDevPid(options.workspaceRoot);
+  if (pid === null || !isProcessRunning(pid)) {
+    removeDevPidFile(options.workspaceRoot);
+    return printDevLifecycleResult({
+      options,
+      ok: true,
+      action: "stop",
+      running: false,
+      ...(pid !== null ? { pid } : {}),
+      logFile: paths.logFile,
+      message: "no detached forge dev server was running",
+      exitCode: 0,
+    });
+  }
+  process.kill(pid, "SIGTERM");
+  removeDevPidFile(options.workspaceRoot);
+  return printDevLifecycleResult({
+    options,
+    ok: true,
+    action: "stop",
+    running: false,
+    pid,
+    logFile: paths.logFile,
+    message: "stopped detached forge dev server",
+    exitCode: 0,
+  });
+}
+
+function runDevDetach(options: DevCommandOptions): DevCommandResult {
+  if (options.once) {
+    return printDevLifecycleResult({
+      options,
+      ok: false,
+      action: "detach",
+      running: false,
+      logFile: devStatePaths(options.workspaceRoot).logFile,
+      message: "forge dev --detach cannot be combined with --once",
+      exitCode: 1,
+    });
+  }
+  const existingPid = readDetachedDevPid(options.workspaceRoot);
+  const paths = devStatePaths(options.workspaceRoot);
+  nodeFileSystem.mkdirp(paths.dir);
+  if (existingPid !== null && isProcessRunning(existingPid)) {
+    return printDevLifecycleResult({
+      options,
+      ok: true,
+      action: "detach",
+      running: true,
+      pid: existingPid,
+      logFile: paths.logFile,
+      message: "forge dev detached server is already running",
+      exitCode: 0,
+    });
+  }
+
+  const cliPath = process.argv[1];
+  if (!cliPath) {
+    return printDevLifecycleResult({
+      options,
+      ok: false,
+      action: "detach",
+      running: false,
+      logFile: paths.logFile,
+      message: "could not resolve current forge CLI path for detached dev server",
+      exitCode: 1,
+    });
+  }
+
+  const fd = openSync(paths.logFile, "a");
+  try {
+    const child = spawn(process.execPath, [cliPath, ...buildDetachedDevArgs(options)], {
+      cwd: options.workspaceRoot,
+      detached: true,
+      stdio: ["ignore", fd, fd],
+      windowsHide: true,
+    });
+    if (child.pid === undefined) {
+      return printDevLifecycleResult({
+        options,
+        ok: false,
+        action: "detach",
+        running: false,
+        logFile: paths.logFile,
+        message: "detached forge dev process started without a pid",
+        exitCode: 1,
+      });
+    }
+    child.unref();
+    nodeFileSystem.writeText(paths.pidFile, `${child.pid}\n`);
+    return printDevLifecycleResult({
+      options,
+      ok: true,
+      action: "detach",
+      running: true,
+      pid: child.pid,
+      logFile: paths.logFile,
+      message: "started detached forge dev server",
+      exitCode: 0,
+    });
+  } finally {
+    closeSync(fd);
+  }
+}
+
 function nextPreviewPort(webUrl?: string): number {
   if (!webUrl) {
     return 5174;
@@ -862,6 +1080,16 @@ export async function runDevCommand(
   const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
   const startedAt = new Date();
 
+  if (options.lifecycle === "status") {
+    return runDevStatus({ ...options, workspaceRoot });
+  }
+  if (options.lifecycle === "stop") {
+    return runDevStop({ ...options, workspaceRoot });
+  }
+  if (options.detach) {
+    return runDevDetach({ ...options, workspaceRoot });
+  }
+
   if (options.once) {
     const cycle = await runDevConsoleCycle({
       workspaceRoot,

package/src/forge/cli/handoff.ts

@@ -8,10 +8,12 @@ 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";
+import { runChangedCommand } from "./changed.ts";
 
 export interface HandoffCommandOptions {
   workspaceRoot: string;
   json: boolean;
+  commitReady?: boolean;
 }
 
 export interface HandoffCommandResult {
@@ -93,6 +95,10 @@ export interface HandoffCommandResult {
     recommendedCommands: string[];
     risks: string[];
   };
+  commitReady?: {
+    count: number;
+    files: string[];
+  };
   diagnosticSummary: {
     total: number;
     sample: Diagnostic[];
@@ -205,6 +211,9 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
     includeImpact: true,
   });
   const git = buildWorkspaceGitSummary(workspaceRoot);
+  const commitReady = options.commitReady
+    ? runChangedCommand(workspaceRoot, { commitReady: true }).data.commitReady as { count: number; files: string[] } | undefined
+    : undefined;
   const recentRuns = summarizeRecentRuns(workspaceRoot);
   const agent = dev.summary.agentContext;
   const risks = [
@@ -269,6 +278,7 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
       recommendedCommands: [...new Set(nextActions)].slice(0, 10),
       risks,
     },
+    ...(commitReady ? { commitReady } : {}),
     diagnosticSummary,
     diagnostics: diagnosticSummary.sample,
     nextActions: [...new Set(nextActions)].slice(0, 10),
@@ -303,6 +313,13 @@ export function formatHandoffHuman(result: HandoffCommandResult): string {
         (result.diagnosticSummary.hidden > 0 ? ` (${result.diagnosticSummary.hidden} hidden in compact handoff)` : ""),
     );
   }
+  if (result.commitReady) {
+    lines.push("", "Commit-ready files:", `  ${result.commitReady.count}`);
+    lines.push(...result.commitReady.files.slice(0, 8).map((file) => `  ${file}`));
+    if (result.commitReady.files.length > 8) {
+      lines.push(`  ... ${result.commitReady.files.length - 8} more`);
+    }
+  }
   const changedTypes = summarizeChangeTypes(result.git.changeSummary.changed);
   if (changedTypes) {
     lines.push("", "Change types:", `  ${changedTypes}`);

package/src/forge/cli/main.ts

@@ -15,6 +15,7 @@ function formatHelp(): string {
     "  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 changed --commit-ready --json  Show files suitable for git add, excluding generated and operational 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",
@@ -75,7 +76,42 @@ function formatHelp(): string {
   ].join("\n");
 }
 
+function formatDevHelp(): string {
+  return [
+    "ForgeOS dev",
+    "",
+    "Usage:",
+    "  forge dev [status|stop] [options]",
+    "",
+    "Options:",
+    "  --db memory|pglite|postgres|none  Choose the development database adapter",
+    "  --port <port>                     API runtime port; use 0 for an ephemeral port",
+    "  --web-port <port>                 Web dev server port",
+    "  --host <host>                     Bind host, default 127.0.0.1",
+    "  --no-web                          Start API/runtime only",
+    "  --api-only                        Start API/runtime only",
+    "  --web-only                        Start web server only, expecting an API runtime",
+    "  --no-worker                       Disable local worker",
+    "  --no-watch                        Disable file watching",
+    "  --once --json                     Run one-shot diagnostics without starting servers",
+    "  --detach --json                   Start dev in the background with .forge/dev/dev.pid and .forge/dev/dev.log",
+    "",
+    "Examples:",
+    "  forge dev --db memory --port 3777 --web-port 5174",
+    "  forge dev --db pglite --once --json",
+    "  forge dev --detach --db memory --port 0 --json",
+    "  forge dev status --json",
+    "  forge dev stop --json",
+    "",
+  ].join("\n");
+}
+
 export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  if (argv[0] === "dev" && (argv.includes("--help") || argv.includes("-h"))) {
+    process.stdout.write(formatDevHelp());
+    return 0;
+  }
+
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(formatHelp());
     return 0;

package/src/forge/cli/new.ts

@@ -49,12 +49,16 @@ export interface NewCommandResult {
 const REQUIRED_GITIGNORE_PATHS = [
   "src/forge/_generated/",
   "forge.lock",
+  ".codex/",
   ".forge/cache/",
   ".forge/pglite/",
   ".forge/delta/",
+  ".forge/agent/",
   ".forge/agent/*.ndjson",
   ".forge/agent/*.history",
+  ".forge/last-run.json",
   ".forge/local/",
+  ".forge/runtime-cache/",
   ".forge/test-cache/",
   ".forge/test-runs/",
   ".forge/ui-runs/",

package/src/forge/cli/parse.ts

@@ -222,9 +222,9 @@ export type ForgeCommand =
       redacted: boolean;
     }
   | { kind: "status"; json: boolean; workspaceRoot: string }
-  | { kind: "changed"; json: boolean; authoredOnly: boolean; reviewOnly: boolean; workspaceRoot: string }
+  | { kind: "changed"; json: boolean; authoredOnly: boolean; reviewOnly: boolean; commitReady: boolean; workspaceRoot: string }
   | { kind: "diff"; target: "authored" | "generated" | "full"; json: boolean; workspaceRoot: string }
-  | { kind: "handoff"; json: boolean; workspaceRoot: string }
+  | { kind: "handoff"; json: boolean; commitReady: boolean; workspaceRoot: string }
   | {
       kind: "studio";
       subcommand: "attach" | "snapshot" | "watch" | "open" | "doctor" | "bridge" | "codex-server";
@@ -264,7 +264,7 @@ export type ForgeCommand =
     }
   | { kind: "generate"; check: boolean; dryRun: boolean; json: boolean; concurrency: number; workspaceRoot: string }
   | { kind: "add"; alias: string; options: AddOptions & { workspaceRoot: string } }
-  | { kind: "inspect"; target: InspectTarget; json: boolean; dryRun: boolean; full: boolean; brief: boolean }
+  | { kind: "inspect"; target: InspectTarget; json: boolean; dryRun: boolean; full: boolean; brief: boolean; ergonomics: boolean; workspaceRoot: string }
   | { kind: "check"; json: boolean; dryRun: boolean; strictSecrets: boolean }
   | { kind: "verify"; options: VerifyOptions }
   | { kind: "run"; name?: string; list: boolean; json: boolean; mock: boolean; userId?: string; tenantId?: string; role?: string; envFile?: string; workspaceRoot: string; queryMode?: boolean; args?: unknown }
@@ -288,6 +288,8 @@ export type ForgeCommand =
       telemetry: string[];
       envFile?: string;
       skipStartupConsole: boolean;
+      detach: boolean;
+      lifecycle?: "status" | "stop";
       workspaceRoot: string;
     }
   | {
@@ -618,7 +620,7 @@ const RENAME_TARGETS: RenameTarget[] = [
   "workflow",
   "event",
 ];
-const TEST_SUBCOMMANDS: TestSubcommand[] = ["plan", "run", "explain"];
+const TEST_SUBCOMMANDS: TestSubcommand[] = ["plan", "run", "explain", "authz"];
 const TEST_COSTS: TestCost[] = ["instant", "fast", "standard", "slow", "docker", "browser"];
 const REPAIR_SUBCOMMANDS: RepairSubcommand[] = [
   "diagnose",
@@ -1696,7 +1698,7 @@ export function parseCli(argv: string[]): ParsedCli {
     case "test": {
       const subcommand = rest[0] as TestSubcommand | undefined;
       if (!subcommand || !TEST_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge test requires subcommand: plan, run, or explain");
+        errors.push("forge test requires subcommand: plan, run, explain, or authz");
         return { command: null, workspaceRoot, errors };
       }
       const timeoutRaw = parseOptionValue(argv, "--timeout-ms");
@@ -1715,7 +1717,7 @@ export function parseCli(argv: string[]): ParsedCli {
             workspaceRoot,
             json: parseFlag(argv, "--json"),
             write: parseFlag(argv, "--write"),
-            changed: parseFlag(argv, "--changed") || (!parseFlag(argv, "--staged") && !parseOptionValue(argv, "--since") && !parseOptionValue(argv, "--feature") && !parseOptionValue(argv, "--refactor") && !parseOptionValue(argv, "--upgrade") && !parseOptionValue(argv, "--plan") && subcommand !== "explain"),
+            changed: parseFlag(argv, "--changed") || (!parseFlag(argv, "--staged") && !parseOptionValue(argv, "--since") && !parseOptionValue(argv, "--feature") && !parseOptionValue(argv, "--refactor") && !parseOptionValue(argv, "--upgrade") && !parseOptionValue(argv, "--plan") && subcommand !== "explain" && subcommand !== "authz"),
             staged: parseFlag(argv, "--staged"),
             since: parseOptionValue(argv, "--since"),
             featureId: parseOptionValue(argv, "--feature"),
@@ -1729,6 +1731,8 @@ export function parseCli(argv: string[]): ParsedCli {
             bail: parseFlag(argv, "--bail"),
             report: parseOptionValue(argv, "--report"),
             timeoutMs: timeoutMs ? Math.floor(timeoutMs) : undefined,
+            tenant: parseOptionValue(argv, "--tenant") ?? "acme",
+            otherTenant: parseOptionValue(argv, "--other-tenant") ?? "globex",
           },
         },
         workspaceRoot,
@@ -1908,6 +1912,7 @@ export function parseCli(argv: string[]): ParsedCli {
           json: parseFlag(argv, "--json"),
           authoredOnly: parseFlag(argv, "--authored"),
           reviewOnly: parseFlag(argv, "--review"),
+          commitReady: parseFlag(argv, "--commit-ready"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1935,6 +1940,7 @@ export function parseCli(argv: string[]): ParsedCli {
         command: {
           kind: "handoff",
           json: parseFlag(argv, "--json"),
+          commitReady: parseFlag(argv, "--commit-ready"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -2220,6 +2226,8 @@ export function parseCli(argv: string[]): ParsedCli {
           dryRun: parseFlag(argv, "--dry-run"),
           full: parseFlag(argv, "--full"),
           brief: parseFlag(argv, "--brief"),
+          ergonomics: parseFlag(argv, "--ergonomics"),
+          workspaceRoot,
         },
         workspaceRoot,
         errors,
@@ -2472,6 +2480,7 @@ export function parseCli(argv: string[]): ParsedCli {
       };
     }
     case "dev": {
+      const lifecycle = rest[0] === "status" || rest[0] === "stop" ? rest[0] : undefined;
       const portRaw = parseOptionValue(argv, "--port");
       const port = portRaw !== undefined ? Number(portRaw) : undefined;
       if (portRaw !== undefined && (!Number.isFinite(port) || port! < 0)) {
@@ -2509,6 +2518,8 @@ export function parseCli(argv: string[]): ParsedCli {
             .filter(Boolean),
           envFile: parseOptionValue(argv, "--env-file"),
           skipStartupConsole: parseFlag(argv, "--skip-startup-console"),
+          detach: parseFlag(argv, "--detach"),
+          lifecycle,
           workspaceRoot,
         },
         workspaceRoot,
@@ -2956,6 +2967,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--telemetry",
     "--user-id",
     "--tenant-id",
+    "--tenant",
+    "--other-tenant",
     "--role",
     "--strict-policies",
     "--strict",
@@ -2981,6 +2994,9 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--git",
     "--no-git",
     "--field-test",
+    "--commit-ready",
+    "--detach",
+    "--ergonomics",
     "--with-web",
     "--no-web",
     "--api-only",
@@ -3093,6 +3109,8 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--file" ||
         arg === "--telemetry" ||
         arg === "--user-id" ||
+        arg === "--tenant" ||
+        arg === "--other-tenant" ||
         arg === "--tenant-id" ||
         arg === "--role" ||
         arg === "--strict-policies" ||