forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/cli/progress.ts

@@ -0,0 +1,51 @@
+export interface CommandHeartbeat {
+  setPhase: (phase: string) => void;
+  stop: () => void;
+}
+
+export function startCommandHeartbeat(input: {
+  label: string;
+  enabled?: boolean;
+  initialPhase?: string;
+  intervalMs?: number;
+  stallMs?: number;
+}): CommandHeartbeat {
+  if (input.enabled === false || process.env.FORGE_PROGRESS === "0") {
+    return {
+      setPhase: () => {},
+      stop: () => {},
+    };
+  }
+
+  const startedAt = Date.now();
+  const intervalMs = input.intervalMs ?? 10_000;
+  const stallMs = input.stallMs ?? 30_000;
+  let phase = input.initialPhase ?? "running";
+  let ticks = 0;
+
+  const timer = setInterval(() => {
+    ticks += 1;
+    const elapsedMs = Date.now() - startedAt;
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const stalled = elapsedMs >= stallMs;
+    const prefix = stalled ? "still waiting" : "working";
+    process.stderr.write(
+      `[forge] ${input.label}: ${prefix}; phase=${phase}; elapsed=${elapsedSeconds}s\n`,
+    );
+    if (stalled && ticks === Math.ceil(stallMs / intervalMs)) {
+      process.stderr.write(
+        `[forge] ${input.label}: run with --json for structured status; for dev startup failures, use forge last --json.\n`,
+      );
+    }
+  }, intervalMs);
+  timer.unref?.();
+
+  return {
+    setPhase: (nextPhase: string) => {
+      phase = nextPhase;
+    },
+    stop: () => {
+      clearInterval(timer);
+    },
+  };
+}

package/src/forge/cli/query.ts

@@ -1,6 +1,10 @@
 import { listQueries, runQuery, type ListQueriesResult, type RunQueryResult } from "../runtime/query/run-query.ts";
 import { resolveAuthFromCli } from "../runtime/auth/resolve.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import {
+  resolveExternalQualifiedName,
+  runExternalEntry,
+} from "../runtime/external/bridge.ts";
 
 export type QuerySubcommand = "list" | "run";
 
@@ -52,6 +56,34 @@ export async function runQueryCommand(
     role: options.role,
   });
 
+  const external = resolveExternalQualifiedName(options.workspaceRoot, options.name, "query");
+  if (external) {
+    const run = await runExternalEntry(options.workspaceRoot, {
+      kind: "query",
+      serviceName: external.serviceName,
+      entryName: external.entryName,
+      args: options.args,
+      auth,
+    });
+    return {
+      run: {
+        ok: run.ok,
+        result: run.result,
+        query: {
+          name: `${external.serviceName}.${external.entryName}`,
+          qualifiedName: `${external.serviceName}.${external.entryName}`,
+          file: `external:${external.serviceName}`,
+          symbolId: `external:${external.serviceName}:query:${external.entryName}`,
+          moduleId: `external:${external.serviceName}`,
+        },
+        diagnostics: run.diagnostics,
+        exitCode: run.exitCode,
+        traceId: run.traceId,
+      },
+      exitCode: run.exitCode,
+    };
+  }
+
   const run = await runQuery(options.workspaceRoot, options.name, {
     args: options.args,
     auth,

package/src/forge/cli/release.ts

@@ -18,12 +18,14 @@ import {
   providerConfigDiagnostics,
 } from "../runtime/release/runtime.ts";
 import { symbolicateStacktrace } from "../runtime/release/symbolicate.ts";
+import { releasePrepareNextActions, releaseReadyNextActions } from "./next-actions.ts";
 
 export type ReleaseArea = "release" | "artifacts" | "sourcemaps";
 export type ReleaseAction =
   | "prepare"
   | "inspect"
   | "check"
+  | "doctor"
   | "finalize"
   | "collect"
   | "list"
@@ -44,12 +46,15 @@ export interface ReleaseCommandOptions {
   target?: ReleaseExportProvider;
   allowDirty: boolean;
   allowPublicSourcemaps: boolean;
+  allowMissingLocalRelease?: boolean;
 }
 
 export interface ReleaseCommandResult {
   ok: boolean;
   data?: unknown;
   diagnostics: Diagnostic[];
+  nextActions?: string[];
+  failureKind?: string;
   exitCode: 0 | 1;
 }
 
@@ -125,19 +130,34 @@ export async function runReleaseCommand(
     const dir = latestReleaseDir(options.workspaceRoot);
     const diagnostics: Diagnostic[] = [];
     if (!dir || !nodeFileSystem.exists(join(dir, "release.json"))) {
-      diagnostics.push(
-        createDiagnostic({
-          severity: "error",
+      if (options.allowMissingLocalRelease) {
+        diagnostics.push(createDiagnostic({
+          severity: "warning",
           code: FORGE_RELEASE_ID_MISSING,
-          message: "no prepared local release found",
-        }),
-      );
+          message: "no prepared local release found; treating this as not-prepared because --allow-missing-local-release was provided",
+          fixHint: "Run forge release prepare when you want to validate a concrete release bundle.",
+          suggestedCommands: releasePrepareNextActions(),
+        }));
+      } else {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "error",
+            code: FORGE_RELEASE_ID_MISSING,
+            message: "no prepared local release found; run forge release prepare before release check/finalize",
+            fixHint: "Prepare a local release first, then re-run the release gate.",
+            suggestedCommands: releasePrepareNextActions(),
+          }),
+        );
+      }
     }
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     return {
-      ok: diagnostics.length === 0,
-      data: { releaseDir: dir },
+      ok: errors.length === 0,
+      data: { releaseDir: dir, state: diagnostics.length === 0 ? "prepared" : "missing-prepared-release" },
       diagnostics,
-      exitCode: diagnostics.length === 0 ? 0 : 1,
+      nextActions: diagnostics.length === 0 ? releaseReadyNextActions() : releasePrepareNextActions(),
+      failureKind: errors.length === 0 ? undefined : "missing-prepared-release",
+      exitCode: errors.length === 0 ? 0 : 1,
     };
   }
 
@@ -256,7 +276,7 @@ export async function runReleaseCommand(
     };
   }
 
-  return { ok: false, diagnostics: [], exitCode: 1 };
+  return { ok: false, diagnostics: [], failureKind: "unsupported-release-command", exitCode: 1 };
 }
 
 function missingRelease(): ReleaseCommandResult {
@@ -266,9 +286,13 @@ function missingRelease(): ReleaseCommandResult {
       createDiagnostic({
         severity: "error",
         code: FORGE_RELEASE_ID_MISSING,
-        message: "release not found",
+        message: "release not found; pass --release <id> or run forge release prepare first",
+        fixHint: "Inspect the prepared releases directory or create a new local release.",
+        suggestedCommands: ["forge release prepare --env production", "forge release inspect --json"],
       }),
     ],
+    nextActions: ["forge release prepare --env production", "forge release inspect --json"],
+    failureKind: "missing-prepared-release",
     exitCode: 1,
   };
 }

package/src/forge/cli/repository.ts

@@ -0,0 +1,151 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { readRepositoryManifest, resolveRepositoryRoot, validateRepositoryManifest } from "../repository-manifest/index.ts";
+import { discoverRepository } from "../repository-analysis/scanner.ts";
+import { analyzeRepository } from "../repository-analysis/analyze.ts";
+import { readRepositorySnapshot, repositoryContext } from "../repository-analysis/context.ts";
+import { evaluateRepositoryQuality } from "../repository-analysis/quality.ts";
+import { isSensitiveRepositoryPath } from "../repository-analysis/scanner.ts";
+import { collectRepositoryCache } from "../repository-analysis/cache-gc.ts";
+import { createRepositoryAgentBenchmarkPlan, evaluateRepositoryAgentBenchmark, repositoryAgentBenchmarkBinding } from "../repository-analysis/benchmark.ts";
+import { selectRepositoryChecks } from "../repository-analysis/check-selection.ts";
+import { isDeepStrictEqual } from "node:util";
+import { planRepositoryRuntime, observeRepositoryRuntime, readRuntimeObservation, selectRuntimeObservation, runtimeSourceDigest } from "../repository-analysis/runtime-observation.ts";
+
+function readBenchmarkJson(cwd: string, input: string, maximum: number): any {
+  const path = resolve(cwd, input);
+  for (let current = path; ; current = dirname(current)) { if (existsSync(current) && lstatSync(current).isSymbolicLink()) throw new Error("Benchmark inputs cannot traverse symlinks"); if (dirname(current) === current) break; }
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.size > maximum || isSensitiveRepositoryPath(path)) throw new Error("Benchmark input must be a bounded regular JSON file");
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { throw new Error("Benchmark input must contain valid JSON"); }
+}
+
+export interface RepositoryCliOptions {
+  action: "discover" | "analyze" | "context" | "quality" | "cache-gc" | "benchmark-plan" | "benchmark-report" | "runtime-plan" | "runtime-observe" | "runtime-context";
+  cwd: string;
+  root?: string;
+  projectId?: string;
+  manifestPath?: string;
+  cacheRoot?: string;
+  write: boolean;
+  json: boolean;
+  query?: string;
+  snapshotId?: string;
+  limit?: number;
+  maxChars?: number;
+  cursor?: string;
+  output?: string;
+  cases?: string;
+  modelConfig?: string;
+  repetitions?: number;
+  plan?: string;
+  observations?: string;
+  graceHours?: number;
+  execute?: boolean;
+  environmentId?: string;
+  observationId?: string;
+}
+
+export async function runRepositoryCommand(options: RepositoryCliOptions): Promise<{ exitCode: number; [key: string]: unknown }> {
+  try {
+    if (!["discover", "analyze", "context", "quality", "cache-gc", "benchmark-plan", "benchmark-report", "runtime-plan", "runtime-observe", "runtime-context"].includes(options.action)) throw new Error("Unsupported repository action");
+    const runtime = options.action.startsWith("runtime-");
+    if (!runtime && (options.execute || options.environmentId !== undefined || options.observationId !== undefined)) throw new Error("Runtime options require a runtime action");
+    if (options.execute && options.action !== "runtime-observe") throw new Error("--execute requires runtime-observe");
+    if (["runtime-plan", "runtime-observe"].includes(options.action) && !options.environmentId) throw new Error("Runtime planning/observation requires --environment-id <label>");
+    if (options.action === "runtime-observe" && !options.execute) throw new Error("Runtime observation executes declared commands; review runtime-plan then supply --execute");
+    if (["runtime-plan", "runtime-context"].includes(options.action) && options.write) throw new Error("Runtime plans/context are read-only");
+    if (runtime && options.cacheRoot) throw new Error("Runtime reports use the repository-owned cache; --cache-root is unsupported");
+    if (runtime && options.cursor) throw new Error("Runtime context does not support --cursor");
+    if (runtime && options.maxChars !== undefined && options.maxChars > 16000) throw new Error("Runtime context is bounded to 16000 characters");
+    if (runtime && options.limit !== undefined) throw new Error("Runtime actions do not support --limit");
+    if (options.action !== "runtime-context" && runtime && options.query !== undefined) throw new Error("--query requires runtime-context for runtime actions");
+    if (options.action === "runtime-context" && options.observationId) throw new Error("--observation-id requires runtime-plan or runtime-observe");
+    if (["context", "quality", "benchmark-plan", "benchmark-report"].includes(options.action) && options.write) throw new Error("Repository context/quality/benchmark is read-only");
+    if (["quality", "benchmark-plan"].includes(options.action) && !options.cases) throw new Error("Repository quality/benchmark-plan requires --cases <reviewed-cases.json>");
+    if (!["quality", "benchmark-plan"].includes(options.action) && options.cases) throw new Error("--cases is only supported for quality/benchmark-plan");
+    if (options.action === "benchmark-plan" && !options.modelConfig) throw new Error("Benchmark planning requires --model-config <file>");
+    if (options.action !== "benchmark-plan" && (options.modelConfig || options.repetitions !== undefined)) throw new Error("Model options require benchmark-plan");
+    if (options.action === "benchmark-report" && (!options.plan || !options.observations)) throw new Error("Benchmark reporting requires --plan and --observations");
+    if (options.action !== "benchmark-report" && (options.plan || options.observations)) throw new Error("--plan/--observations require benchmark-report");
+    if (options.action !== "cache-gc" && options.graceHours !== undefined) throw new Error("--grace-hours requires cache-gc");
+    if (options.action === "cache-gc" && [options.query, options.snapshotId, options.limit, options.maxChars, options.cursor].some(value => value !== undefined)) throw new Error("cache-gc does not support context or snapshot guard options");
+    if (options.output && (options.action !== "discover" || !options.write)) throw new Error("--output requires discovery with --write");
+    const root = await resolveRepositoryRoot(options);
+    if (options.action === "cache-gc") return { exitCode: 0, ok: true, ...collectRepositoryCache(root, { cacheRoot: options.cacheRoot, apply: options.write, graceMs: options.graceHours === undefined ? undefined : options.graceHours * 3600000 }) };
+    if (options.action === "discover") {
+      const manifest = discoverRepository(root);
+      const checked = validateRepositoryManifest(manifest);
+      if (!checked.manifest) throw new Error(`No valid supported repository proposal: ${checked.diagnostics.join("; ")}`);
+      if (options.write) {
+        const file = resolve(options.output ?? resolve(root, "forge.manifest.json"));
+        if (existsSync(file)) throw new Error("Discovery never overwrites an existing manifest; choose a new --output");
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+      }
+      return { exitCode: 0, ok: true, root, manifest, wroteManifest: options.write };
+    }
+    const loaded = readRepositoryManifest(root, { manifestPath: options.manifestPath });
+    if (!loaded.manifest || loaded.diagnostics.length) throw new Error(loaded.diagnostics.join("; ") || "Repository manifest missing. Run forge manifest discover, review and save the proposal first.");
+    if (options.action === "runtime-observe") {
+      if (options.snapshotId) {
+        const input = await analyzeRepository(root, loaded.manifest, { write: false });
+        if (input.snapshotId !== options.snapshotId) throw new Error("Runtime snapshot guard differs from current source");
+      }
+      const report = await observeRepositoryRuntime(root, loaded.manifest, { environmentId: options.environmentId!, observationId: options.observationId, write: options.write });
+      const ok = report.observations.every(item => item.status === "completed");
+      return { ok, exitCode: ok ? 0 : 1, wroteArtifacts: options.write, report };
+    }
+    if (options.action === "runtime-plan") {
+      const input = await analyzeRepository(root, loaded.manifest, { write: false });
+      if (options.snapshotId && input.snapshotId !== options.snapshotId) throw new Error("Runtime snapshot guard differs from current source");
+      return { ok: true, exitCode: 0, plan: { ...planRepositoryRuntime(input, options.environmentId!, options.observationId), inputDigest: runtimeSourceDigest(root, loaded.manifest) } };
+    }
+    if (options.action === "analyze") {
+      const snapshot = await analyzeRepository(root, loaded.manifest, { write: options.write, cacheRoot: options.cacheRoot });
+      const ok = snapshot.coverage.errors === 0;
+      return { exitCode: ok ? 0 : 1, ok, root, wroteArtifacts: options.write, snapshotId: snapshot.snapshotId, coverage: snapshot.coverage, snapshot };
+    }
+    const snapshot = readRepositorySnapshot(root, { cacheRoot: options.cacheRoot });
+    if (!snapshot) throw new Error("Repository snapshot missing; run forge repository analyze --write first");
+    if (options.action === "runtime-context") {
+      const current = repositoryContext(root, snapshot, "overview", { manifest: loaded.manifest, snapshotId: options.snapshotId });
+      if (!current.ok) throw new Error(current.diagnostics.join("; "));
+      const report = readRuntimeObservation(root, snapshot, { environmentId: options.environmentId });
+      if (!report) throw new Error("Runtime report missing, stale or invalid; review runtime-plan and run runtime-observe explicitly");
+      return { ok: true, exitCode: 0, context: selectRuntimeObservation(report, { query: options.query, maxChars: options.maxChars }) };
+    }
+    if (["quality", "benchmark-plan", "benchmark-report"].includes(options.action)) {
+      const current = repositoryContext(root, snapshot, "overview", { manifest: loaded.manifest, snapshotId: options.snapshotId });
+      if (!current.ok) throw new Error(current.diagnostics.join("; "));
+      if (options.action === "benchmark-report") {
+        const input = readBenchmarkJson(options.cwd, options.plan!, 128 * 1024 * 1024), plan = input.plan ?? input;
+        const report = evaluateRepositoryAgentBenchmark(plan, readBenchmarkJson(options.cwd, options.observations!, 16 * 1024 * 1024));
+        const expectedBinding = repositoryAgentBenchmarkBinding(snapshot);
+        if (!isDeepStrictEqual(plan.binding, expectedBinding)) throw new Error("Benchmark plan belongs to a different repository input");
+        const checksByScope = new Map<string, unknown>();
+        for (const run of plan.runs) {
+          const key = JSON.stringify(run.workerInput.scope);
+          if (!checksByScope.has(key)) checksByScope.set(key, JSON.parse(JSON.stringify(selectRepositoryChecks(snapshot, { scope: run.workerInput.scope }).checks)));
+          if (!isDeepStrictEqual(run.workerInput.checks, checksByScope.get(key))) throw new Error("Benchmark checks differ from current repository declarations");
+        }
+        return { ...report, ok: true, exitCode: 0 };
+      }
+      if (options.action === "benchmark-plan") {
+        const plan = createRepositoryAgentBenchmarkPlan(snapshot, readBenchmarkJson(options.cwd, options.cases!, 128 * 1024), { model: readBenchmarkJson(options.cwd, options.modelConfig!, 128 * 1024), repetitions: options.repetitions, maxChars: options.maxChars });
+        return { plan, ok: true, exitCode: 0 };
+      }
+      const casesPath = resolve(options.cwd, options.cases!);
+      const stat = lstatSync(casesPath);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024 || isSensitiveRepositoryPath(casesPath)) throw new Error("Quality cases must be a bounded regular JSON file");
+      let cases: unknown;
+      try { cases = JSON.parse(readFileSync(casesPath, "utf8")); } catch { throw new Error("Quality cases must contain valid JSON"); }
+      const report = evaluateRepositoryQuality(snapshot, cases as Parameters<typeof evaluateRepositoryQuality>[1], { maxChars: options.maxChars });
+      return { ...report, ok: report.passed, exitCode: report.passed ? 0 : 1 };
+    }
+    const result = repositoryContext(root, snapshot, options.query ?? "overview", {
+      snapshotId: options.snapshotId, limit: options.limit, maxChars: options.maxChars, cursor: options.cursor, manifest: loaded.manifest,
+    });
+    return { ...result, exitCode: result.ok ? 0 : 1 };
+  } catch (error) { return { exitCode: 1, ok: false, diagnostics: [{ severity: "error", code: "FORGE_REPOSITORY", message: (error instanceof Error ? error.message : "Repository operation failed").slice(0, 512) }] }; }
+}

package/src/forge/cli/run.ts

@@ -1,6 +1,11 @@
 import { listEntries, runEntry } from "../runtime/executor.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import type { RunEntryResult, ListEntriesResult } from "../runtime/executor.ts";
+import {
+  resolveExternalQualifiedName,
+  runExternalEntry,
+} from "../runtime/external/bridge.ts";
+import { resolveAuthFromCli } from "../runtime/auth/resolve.ts";
 
 export interface RunCommandOptions {
   name?: string;
@@ -10,6 +15,7 @@ export interface RunCommandOptions {
   userId?: string;
   tenantId?: string;
   role?: string;
+  args?: unknown;
   workspaceRoot: string;
 }
 
@@ -29,9 +35,45 @@ export async function runRunCommand(
     return { list, exitCode: list.exitCode };
   }
 
+  const external = resolveExternalQualifiedName(options.workspaceRoot, options.name!, "command");
+  if (external) {
+    const run = await runExternalEntry(options.workspaceRoot, {
+      kind: "command",
+      serviceName: external.serviceName,
+      entryName: external.entryName,
+      args: options.args,
+      auth: resolveAuthFromCli({
+        userId: options.userId,
+        tenantId: options.tenantId,
+        role: options.role,
+      }),
+    });
+    return {
+      run: {
+        ok: run.ok,
+        result: run.result,
+        diagnostics: run.diagnostics,
+        exitCode: run.exitCode,
+        traceId: run.traceId,
+        entry: {
+          id: `external:${external.serviceName}:command:${external.entryName}`,
+          kind: "command",
+          name: `${external.serviceName}.${external.entryName}`,
+          qualifiedName: `${external.serviceName}.${external.entryName}`,
+          file: `external:${external.serviceName}`,
+          moduleId: `external:${external.serviceName}`,
+          runtimeContext: "command",
+          dependencies: [],
+        },
+      },
+      exitCode: run.exitCode,
+    };
+  }
+
   const run = await runEntry(options.workspaceRoot, options.name!, {
     json: options.json,
     mock: options.mock,
+    args: options.args,
     userId: options.userId,
     tenantId: options.tenantId,
     role: options.role,

package/src/forge/cli/secrets.ts

@@ -8,6 +8,7 @@ import {
 } from "../runtime/secrets/check.ts";
 import { getRuntimeEnvStore, initializeRuntimeEnv } from "../runtime/context/create-context.ts";
 import { redactSecretValue } from "../runtime/secrets/env-loader.ts";
+import { productionPlaceholderEnvProblems } from "./env-placeholders.ts";
 
 export type SecretsSubcommand = "list" | "check" | "print" | "set" | "unset" | "prove";
 
@@ -219,13 +220,146 @@ export function formatSecretsJson(result: SecretsCommandResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
 
-export type EnvSubcommand = "list" | "check" | "print";
+export type EnvSubcommand = "list" | "check" | "print" | "doctor";
+export type EnvDoctorTarget = "local" | "staging" | "production";
 
 export interface EnvCommandOptions {
   subcommand: EnvSubcommand;
   workspaceRoot: string;
   json: boolean;
   redacted?: boolean;
+  target?: EnvDoctorTarget;
+}
+
+const ENV_DOCTOR_KEYS = [
+  "DATABASE_URL",
+  "FORGE_AUTH_MODE",
+  "FORGE_AUTH_ISSUER",
+  "FORGE_AUTH_AUDIENCE",
+  "FORGE_AUTH_JWKS_URI",
+  "FORGE_AUTH_DISCOVERY_URL",
+  "WORKOS_API_KEY",
+  "WORKOS_CLIENT_ID",
+  "WORKOS_COOKIE_PASSWORD",
+  "WORKOS_REDIRECT_URI",
+  "WORKOS_POST_LOGIN_REDIRECT_URI",
+  "WORKOS_POST_LOGOUT_REDIRECT_URI",
+  "WORKOS_WEBHOOK_SECRET",
+] as const;
+
+function parseEnvFile(workspaceRoot: string, relative: string): Record<string, string> {
+  const path = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(path)) return {};
+  const values: Record<string, string> = {};
+  for (const rawLine of (nodeFileSystem.readText(path) ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const rawValue = line.slice(eq + 1).trim();
+    values[line.slice(0, eq).trim()] = rawValue.replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function envDoctorFiles(target: EnvDoctorTarget): string[] {
+  if (target === "production") return ["deploy/.env.production"];
+  if (target === "staging") return ["deploy/.env.staging", ".env.staging"];
+  return [".env", ".env.local"];
+}
+
+function hasWorkOSAppArtifacts(workspaceRoot: string): boolean {
+  return nodeFileSystem.exists(join(workspaceRoot, "workos-seed.yml")) ||
+    nodeFileSystem.exists(join(workspaceRoot, "src/policies.workos.ts")) ||
+    nodeFileSystem.exists(join(workspaceRoot, "src/forge/_generated/integrations/workos/auth-routes.ts"));
+}
+
+function envDoctor(options: EnvCommandOptions): SecretsCommandResult {
+  const target = options.target ?? "local";
+  const files = envDoctorFiles(target).map((path) => {
+    const values = parseEnvFile(options.workspaceRoot, path);
+    return {
+      path,
+      present: nodeFileSystem.exists(join(options.workspaceRoot, path)),
+      keys: Object.keys(values).filter((key) => ENV_DOCTOR_KEYS.includes(key as (typeof ENV_DOCTOR_KEYS)[number])).sort(),
+      values,
+    };
+  });
+  const processValues = Object.fromEntries(
+    ENV_DOCTOR_KEYS.filter((key) => Boolean(process.env[key])).map((key) => [key, process.env[key]!]),
+  );
+  const effective = {
+    ...Object.assign({}, ...files.map((file) => file.values)),
+    ...processValues,
+  } as Record<string, string>;
+  const required = target === "production"
+    ? ["DATABASE_URL", "FORGE_AUTH_MODE", "FORGE_AUTH_ISSUER", "FORGE_AUTH_AUDIENCE"]
+    : ["FORGE_AUTH_MODE"];
+  const missing = required.filter((key) => !effective[key]);
+  const authMode = effective.FORGE_AUTH_MODE ?? "dev-headers";
+  const productionAuth = authMode === "jwt" || authMode === "oidc";
+  const database = effective.DATABASE_URL
+    ? "postgres"
+    : target === "production"
+      ? "missing"
+      : "local-dev";
+  const workosDetected = hasWorkOSAppArtifacts(options.workspaceRoot) ||
+    Boolean(effective.WORKOS_CLIENT_ID || effective.WORKOS_API_KEY);
+  const provider = workosDetected ? "workos" : "none";
+  const hasJwtSource = Boolean(effective.FORGE_AUTH_JWKS_URI || effective.FORGE_AUTH_DISCOVERY_URL);
+  const placeholderProblems = target === "production"
+    ? productionPlaceholderEnvProblems(effective, ENV_DOCTOR_KEYS as unknown as string[])
+    : [];
+  const blockers = [
+    ...missing.filter((key) => key !== "DATABASE_URL").map((key) => `${key} missing`),
+    ...(target === "production" && !productionAuth ? [`FORGE_AUTH_MODE=${authMode} is not production auth`] : []),
+    ...(target === "production" && database === "missing" ? ["DATABASE_URL missing"] : []),
+    ...(target === "production" && productionAuth && !hasJwtSource
+      ? ["FORGE_AUTH_JWKS_URI or FORGE_AUTH_DISCOVERY_URL missing"]
+      : []),
+    ...(target === "production" && workosDetected && !effective.WORKOS_CLIENT_ID ? ["WORKOS_CLIENT_ID missing"] : []),
+    ...(target === "production" && workosDetected && !effective.WORKOS_API_KEY ? ["WORKOS_API_KEY missing"] : []),
+    ...placeholderProblems.map((problem) => `${problem.key} uses placeholder value (${problem.reason})`),
+  ];
+  const warnings = [
+    ...(target === "production" && files.every((file) => !file.present)
+      ? ["deploy/.env.production not found; process.env alone may be fine in CI but is easy for agents to miss"]
+      : []),
+    ...(workosDetected && !effective.WORKOS_COOKIE_PASSWORD ? ["WORKOS_COOKIE_PASSWORD missing"] : []),
+    ...(workosDetected && !effective.WORKOS_REDIRECT_URI ? ["WORKOS_REDIRECT_URI missing"] : []),
+  ];
+  return {
+    exitCode: blockers.length === 0 ? 0 : 1,
+    data: {
+      schemaVersion: "0.1.0",
+      kind: "env-doctor",
+      ok: blockers.length === 0,
+      target,
+      authMode,
+      productionAuth,
+      database,
+      provider,
+      sources: [
+        {
+          path: "process.env",
+          present: Object.keys(processValues).length > 0,
+          keys: Object.keys(processValues).sort(),
+          values: undefined,
+        },
+        ...files.map(({ path, present, keys }) => ({ path, present, keys })),
+      ],
+      present: ENV_DOCTOR_KEYS.filter((key) => Boolean(effective[key])).sort(),
+      missing,
+      placeholderProblems,
+      blockers,
+      warnings,
+      nextActions: blockers.length === 0
+        ? ["forge deploy readiness --production --json"]
+        : target === "production"
+          ? ["cp deploy/.env.production.example deploy/.env.production", "forge env doctor --target production --json"]
+          : ["forge env doctor --target local --json"],
+    },
+  };
 }
 
 export async function runEnvCommand(options: EnvCommandOptions): Promise<SecretsCommandResult> {
@@ -233,6 +367,8 @@ export async function runEnvCommand(options: EnvCommandOptions): Promise<Secrets
   const schema = loadEnvSchema(options.workspaceRoot);
 
   switch (options.subcommand) {
+    case "doctor":
+      return envDoctor(options);
     case "list":
       if (!schema) {
         return {