forgeos 0.1.0-alpha.6 → 0.1.0-alpha.60

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/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

@@ -219,13 +219,141 @@ 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 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"] : []),
+  ];
+  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,
+      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 +361,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 {