forgeos 0.1.0-alpha.44 → 0.1.0-alpha.46

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.44 input=3c44e5f9f6fd4afe42accec6d73bca4f36f188ed9de5fb11f4a890d3020fe2bc content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.46 input=fa019b5420e754f08100c96852edfc9ea0b39a6b050cbd9bc99106b88775c207 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # forgeos
 
+## 0.1.0-alpha.46
+
+### Patch Changes
+
+- Smooth the package upgrade apply path used by real ForgeOS apps.
+
+  - `forge deps upgrade-apply` and `forge deps upgrade-rollback` now accept the
+    `planDir` returned by `forge deps upgrade-plan`, automatically resolving it
+    to `plan.json`.
+  - Passing a directory without `plan.json` now returns a targeted
+    `FORGE_DEPS_TARGET_NOT_FOUND` diagnostic with the exact suggested command
+    instead of falling through to a generic JSON parse failure.
+  - Add regression coverage for applying upgrade plans through the returned
+    directory path and for invalid plan directories.
+
+## 0.1.0-alpha.45
+
+### Patch Changes
+
+- Smooth the WorkOS, field-test, and deploy-readiness DX discovered during real
+  app field testing.
+
+  - Accept `--real` through the top-level unknown-option guard so documented
+    commands like `forge workos setup --real --file workos-seed.yml --json` and
+    `forge workos prove --real --file workos-seed.yml --json` run instead of
+    being rejected before parsing.
+  - Treat known WorkOS CLI duplicate-resource seed responses as explicit clean
+    idempotency: Forge now records `seedAlreadyAppliedReason`, suppresses the
+    scary duplicate stderr from the successful JSON result, and writes seed
+    state with the already-applied status.
+  - Run `forge field-test run` through an async harness process and emit
+    periodic stderr heartbeats so long realistic probes no longer look frozen
+    while preserving machine-readable JSON output.
+  - Add a `deploy-env-sources` check to `forge deploy check --production` that
+    reports which env sources were inspected, which keys were present, and which
+    production keys are still missing without printing secret values; `.env` and
+    `.env.local` are shown as local guidance, not production deploy evidence.
+
 ## 0.1.0-alpha.44
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,32 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.46
+
+- `forge deps upgrade-apply` and `forge deps upgrade-rollback` now accept the
+  `planDir` returned by `forge deps upgrade-plan`, resolving it to the nested
+  `plan.json` automatically.
+- Invalid upgrade plan directories now return a precise
+  `FORGE_DEPS_TARGET_NOT_FOUND` diagnostic with suggested commands instead of a
+  generic JSON parse failure.
+- Added regression coverage for plan-directory apply behavior and missing
+  `plan.json` diagnostics.
+
+## 0.1.0-alpha.45
+
+- `forge workos setup/prove --real` now passes the top-level unknown-option
+  guard, matching the documented no-dashboard WorkOS apply flow.
+- `forge workos seed --file workos-seed.yml --json` now treats known WorkOS
+  duplicate-resource responses as explicit idempotency, suppressing duplicate
+  stderr in successful JSON output while recording `seedAlreadyAppliedReason`
+  and seed state.
+- `forge field-test run` now uses an async harness process with periodic
+  progress heartbeats on stderr so realistic probes do not appear stuck.
+- `forge deploy check --production` now reports sanitized env-source evidence,
+  including which production keys were found or missing, while keeping `.env`
+  and `.env.local` clearly marked as local guidance rather than production
+  deploy evidence.
+
 ## 0.1.0-alpha.44
 
 - `forge inspect ui --ergonomics` now treats helper-based seed recovery inside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.44",
+  "version": "0.1.0-alpha.46",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "license": "MIT",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.44","releaseId":"forgeos@0.1.0-alpha.44+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.46","releaseId":"forgeos@0.1.0-alpha.46+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.44 input=3c44e5f9f6fd4afe42accec6d73bca4f36f188ed9de5fb11f4a890d3020fe2bc content=3d89cc8170a2affb58421e25ec58882655d6ea2399efe65a822d99e1afa1ddb5
+// @forge-generated generator=0.1.0-alpha.46 input=fa019b5420e754f08100c96852edfc9ea0b39a6b050cbd9bc99106b88775c207 content=715d49dd9abed8465a5cf5e82713973aab97cc178fda3b1e8b1647b93683ee58
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.44",
-  "releaseId": "forgeos@0.1.0-alpha.44+unknown",
+  "packageVersion": "0.1.0-alpha.46",
+  "releaseId": "forgeos@0.1.0-alpha.46+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/deploy.ts

@@ -120,6 +120,23 @@ function fieldTestReportCandidates(workspaceRoot: string): Array<{ path: string;
 }
 
 const FIELD_TEST_PRODUCTION_COMMAND = "forge field-test run --realistic --json";
+const DEPLOY_ENV_FILE = "deploy/.env.production";
+const LOCAL_ENV_FILES = [".env", ".env.local"];
+const DEPLOY_ENV_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",
+];
 
 function summarizeFieldTestReport(data: Record<string, unknown>) {
   const results = Array.isArray(data.results) ? data.results as Array<Record<string, unknown>> : [];
@@ -428,7 +445,7 @@ function renderEnvExample(workspaceRoot: string): string {
 }
 
 function hasProductionEnvFile(workspaceRoot: string): boolean {
-  return nodeFileSystem.exists(join(workspaceRoot, "deploy/.env.production"));
+  return nodeFileSystem.exists(join(workspaceRoot, DEPLOY_ENV_FILE));
 }
 
 function parseEnvValue(value: string): string {
@@ -442,8 +459,8 @@ function parseEnvValue(value: string): string {
   return trimmed;
 }
 
-function readDeployEnvFile(workspaceRoot: string): Record<string, string> {
-  const absolute = join(workspaceRoot, "deploy/.env.production");
+function readEnvFile(workspaceRoot: string, relative: string): Record<string, string> {
+  const absolute = join(workspaceRoot, relative);
   if (!nodeFileSystem.exists(absolute)) return {};
   const text = nodeFileSystem.readText(absolute) ?? "";
   const values: Record<string, string> = {};
@@ -457,6 +474,63 @@ function readDeployEnvFile(workspaceRoot: string): Record<string, string> {
   return values;
 }
 
+function readDeployEnvFile(workspaceRoot: string): Record<string, string> {
+  return readEnvFile(workspaceRoot, DEPLOY_ENV_FILE);
+}
+
+function envKeys(values: Record<string, string>): string[] {
+  return DEPLOY_ENV_KEYS.filter((key) => Boolean(values[key])).sort();
+}
+
+function processDeployEnv(): Record<string, string> {
+  return Object.fromEntries(
+    DEPLOY_ENV_KEYS
+      .filter((key) => Boolean(process.env[key]))
+      .map((key) => [key, process.env[key]!]),
+  );
+}
+
+function deployEnvSources(workspaceRoot: string): Record<string, unknown> {
+  const processEnv = processDeployEnv();
+  const deployEnv = readDeployEnvFile(workspaceRoot);
+  const localSources = LOCAL_ENV_FILES.map((path) => {
+    const values = readEnvFile(workspaceRoot, path);
+    return {
+      path,
+      present: nodeFileSystem.exists(join(workspaceRoot, path)),
+      role: "local-guidance",
+      readForProduction: false,
+      keys: envKeys(values),
+    };
+  });
+  const productionEvidence = {
+    ...deployEnv,
+    ...processEnv,
+  };
+  return {
+    readOrder: ["process.env", DEPLOY_ENV_FILE],
+    note: `${DEPLOY_ENV_FILE} and current process env are production deploy evidence; .env/.env.local are reported only as local guidance and are not used to pass production gates.`,
+    sources: [
+      {
+        path: "process.env",
+        present: envKeys(processEnv).length > 0,
+        role: "production-evidence",
+        readForProduction: true,
+        keys: envKeys(processEnv),
+      },
+      {
+        path: DEPLOY_ENV_FILE,
+        present: hasProductionEnvFile(workspaceRoot),
+        role: "production-evidence",
+        readForProduction: true,
+        keys: envKeys(deployEnv),
+      },
+      ...localSources,
+    ],
+    missingProductionKeys: DEPLOY_ENV_KEYS.filter((key) => !productionEvidence[key]),
+  };
+}
+
 function deployEnvValue(workspaceRoot: string, name: string): string | undefined {
   return process.env[name] || readDeployEnvFile(workspaceRoot)[name];
 }
@@ -494,15 +568,15 @@ function databaseReady(options: DeployCommandOptions): boolean {
 
 function databaseReadyMessage(options: DeployCommandOptions): string {
   if (process.env.DATABASE_URL) return "DATABASE_URL is set in the current environment";
-  if (readDeployEnvFile(options.workspaceRoot).DATABASE_URL) return "DATABASE_URL is set in deploy/.env.production";
-  if (hasProductionEnvFile(options.workspaceRoot)) return "deploy/.env.production is present but does not set DATABASE_URL";
+  if (readDeployEnvFile(options.workspaceRoot).DATABASE_URL) return `DATABASE_URL is set in ${DEPLOY_ENV_FILE}`;
+  if (hasProductionEnvFile(options.workspaceRoot)) return `${DEPLOY_ENV_FILE} is present but does not set DATABASE_URL`;
   if (hasRenderedProductionEnvExample(options.workspaceRoot)) {
     return options.production
-      ? "deploy/.env.production.example is only a template; copy it to deploy/.env.production with DATABASE_URL or set DATABASE_URL"
+      ? `deploy/.env.production.example is only a template; copy it to ${DEPLOY_ENV_FILE} with DATABASE_URL or set DATABASE_URL`
       : "deploy/.env.production.example is present";
   }
   return options.production
-    ? "production deploy requires DATABASE_URL or deploy/.env.production"
+    ? `production deploy requires DATABASE_URL or ${DEPLOY_ENV_FILE}`
     : "deploy readiness requires DATABASE_URL or rendered deploy/.env.production.example";
 }
 
@@ -650,6 +724,13 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       found: lockfiles,
     },
   });
+  checks.push({
+    name: "deploy-env-sources",
+    ok: true,
+    severity: "warning",
+    message: `${DEPLOY_ENV_FILE} and process.env are production deploy evidence; .env/.env.local are local guidance only`,
+    details: deployEnvSources(options.workspaceRoot),
+  });
 
   const auth = await withDeployEnv(options.workspaceRoot, async () => loadAuthConfigFromEnv(options.workspaceRoot));
   const productionAuth = auth.mode === "jwt" || auth.mode === "oidc";

package/src/forge/cli/deps.ts

@@ -73,15 +73,55 @@ function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null
   return JSON.parse(raw) as T;
 }
 
-function planPathFor(workspaceRoot: string, planIdOrPath: string): string {
-  if (nodeFileSystem.exists(planIdOrPath)) {
-    return planIdOrPath;
-  }
-  const direct = join(workspaceRoot, planIdOrPath);
-  if (nodeFileSystem.exists(direct)) {
-    return direct;
+function resolvePlanPathFor(
+  workspaceRoot: string,
+  planIdOrPath: string,
+): { ok: true; path: string } | { ok: false; diagnostics: Diagnostic[] } {
+  const candidates = [
+    planIdOrPath,
+    join(workspaceRoot, planIdOrPath),
+    join(workspaceRoot, ".forge", "upgrades", planIdOrPath, "plan.json"),
+  ];
+
+  for (const candidate of candidates) {
+    if (!nodeFileSystem.exists(candidate)) {
+      continue;
+    }
+    if (!nodeFileSystem.isDirectory(candidate)) {
+      return { ok: true, path: candidate };
+    }
+    const nestedPlan = join(candidate, "plan.json");
+    if (nodeFileSystem.exists(nestedPlan) && !nodeFileSystem.isDirectory(nestedPlan)) {
+      return { ok: true, path: nestedPlan };
+    }
+    return {
+      ok: false,
+      diagnostics: [{
+        severity: "error",
+        code: "FORGE_DEPS_TARGET_NOT_FOUND",
+        message: `upgrade plan directory '${planIdOrPath}' does not contain plan.json`,
+        fixHint: "Pass the plan.json file returned by forge deps upgrade-plan, or rerun upgrade-plan.",
+        suggestedCommands: [
+          `forge deps upgrade-apply ${nestedPlan} --json`,
+          "forge deps upgrade-plan <package> --to latest --json",
+        ],
+      }],
+    };
   }
-  return join(workspaceRoot, ".forge", "upgrades", planIdOrPath, "plan.json");
+
+  return {
+    ok: false,
+    diagnostics: [{
+      severity: "error",
+      code: "FORGE_DEPS_TARGET_NOT_FOUND",
+      message: `upgrade plan '${planIdOrPath}' was not found`,
+      fixHint: "Use the planDir or plan.json path returned by forge deps upgrade-plan.",
+      suggestedCommands: [
+        `forge deps upgrade-apply .forge/upgrades/${planIdOrPath}/plan.json --json`,
+        "forge deps upgrade-plan <package> --to latest --json",
+      ],
+    }],
+  };
 }
 
 function findPackage(workspaceRoot: string, packageName: string): {
@@ -395,9 +435,17 @@ export async function runDepsCommand(options: DepsCommandOptions): Promise<DepsC
     if (!options.planPath) {
       return missingPlan();
     }
+    const resolvedPlan = resolvePlanPathFor(options.workspaceRoot, options.planPath);
+    if (!resolvedPlan.ok) {
+      return {
+        ok: false,
+        diagnostics: resolvedPlan.diagnostics,
+        exitCode: 1,
+      };
+    }
     const applied = await applyUpgradePlan({
       workspaceRoot: options.workspaceRoot,
-      planPath: planPathFor(options.workspaceRoot, options.planPath),
+      planPath: resolvedPlan.path,
       yes: options.yes,
       allowScripts: options.allowScripts,
       skipTests: options.skipTests,
@@ -409,6 +457,7 @@ export async function runDepsCommand(options: DepsCommandOptions): Promise<DepsC
         applied: applied.applied,
         rolledBack: applied.rolledBack,
         reinstallCommand: applied.plan?.rollback.reinstallCommand,
+        planPath: resolvedPlan.path,
       },
       diagnostics: applied.diagnostics,
       exitCode: applied.exitCode,
@@ -419,15 +468,24 @@ export async function runDepsCommand(options: DepsCommandOptions): Promise<DepsC
     if (!options.planPath) {
       return missingPlan();
     }
+    const resolvedPlan = resolvePlanPathFor(options.workspaceRoot, options.planPath);
+    if (!resolvedPlan.ok) {
+      return {
+        ok: false,
+        diagnostics: resolvedPlan.diagnostics,
+        exitCode: 1,
+      };
+    }
     const rolledBack = rollbackUpgradePlan({
       workspaceRoot: options.workspaceRoot,
-      planPath: planPathFor(options.workspaceRoot, options.planPath),
+      planPath: resolvedPlan.path,
     });
     return {
       ok: rolledBack.ok,
       data: {
         rolledBack: rolledBack.rolledBack,
         reinstallCommand: rolledBack.plan?.rollback.reinstallCommand,
+        planPath: resolvedPlan.path,
       },
       diagnostics: rolledBack.diagnostics,
       exitCode: rolledBack.exitCode,

package/src/forge/cli/field-test.ts

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -400,7 +400,56 @@ async function createFieldTestApp(options: FieldTestCommandOptions): Promise<Fie
   });
 }
 
-function runHarness(options: FieldTestCommandOptions): FieldTestCommandResult {
+function shouldEmitProgress(): boolean {
+  return process.env.FORGE_FIELD_TEST_PROGRESS !== "0";
+}
+
+function runHarnessProcess(
+  options: FieldTestCommandOptions,
+  args: string[],
+): Promise<{ status: number | null; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const emitProgress = shouldEmitProgress();
+    const child = spawn(process.execPath, args, {
+      cwd: options.workspaceRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const heartbeat = emitProgress
+      ? setInterval(() => {
+          const elapsed = Math.round((Date.now() - startedAt) / 1000);
+          process.stderr.write(`[forge] field-test still running after ${elapsed}s; timeout=${options.timeoutMs}ms\n`);
+        }, 30_000)
+      : undefined;
+    const finish = (status: number | null, extraStderr = "") => {
+      if (settled) return;
+      settled = true;
+      if (heartbeat) clearInterval(heartbeat);
+      if (extraStderr) stderr += extraStderr;
+      resolve({ status, stdout, stderr });
+    };
+    child.on("error", (error) => {
+      finish(1, `${error.message}\n`);
+    });
+    child.on("close", (status) => {
+      finish(status);
+    });
+  });
+}
+
+async function runHarness(options: FieldTestCommandOptions): Promise<FieldTestCommandResult> {
   const script = scriptPath(options.workspaceRoot);
   if (!script) {
     return {
@@ -433,11 +482,7 @@ function runHarness(options: FieldTestCommandOptions): FieldTestCommandResult {
   if (options.forgeSpec) args.push("--forge-spec", options.forgeSpec);
   if (reportPath) args.push("--write-report", reportPath);
   if (options.json) args.push("--json");
-  const result = spawnSync(process.execPath, args, {
-    cwd: options.workspaceRoot,
-    encoding: "utf8",
-    windowsHide: true,
-  });
+  const result = await runHarnessProcess(options, args);
   const reportAbsolute = reportPath ? resolveReportPath(options.workspaceRoot, reportPath) : null;
   const reportData = reportAbsolute && existsSync(reportAbsolute)
     ? JSON.parse(readFileSync(reportAbsolute, "utf8")) as unknown

package/src/forge/cli/parse.ts

@@ -3069,6 +3069,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--auth-probes",
     "--ui-probes",
     "--realistic",
+    "--real",
     "--write-report",
     "--tenant-scoped",
     "--field",

package/src/forge/cli/workos.ts

@@ -703,7 +703,9 @@ function seedData(input: {
   dryRun?: boolean;
   seedFileSanitized?: boolean;
   seedAlreadyApplied?: boolean;
+  seedAlreadyAppliedReason?: string;
   seedStateFile?: string;
+  workosCli?: Record<string, unknown>;
   configActions?: WorkOSConfigActionResult[];
   nextCommand?: string;
 }): Record<string, unknown> {
@@ -716,7 +718,9 @@ function seedData(input: {
     dryRun: input.dryRun ?? false,
     seedFileSanitized: input.seedFileSanitized ?? false,
     seedAlreadyApplied: input.seedAlreadyApplied ?? false,
+    ...(input.seedAlreadyAppliedReason ? { seedAlreadyAppliedReason: input.seedAlreadyAppliedReason } : {}),
     ...(input.seedStateFile ? { seedStateFile: input.seedStateFile } : {}),
+    ...(input.workosCli ? { workosCli: input.workosCli } : {}),
     configActions: input.configActions ?? [],
     ...(input.nextCommand ? { nextCommand: input.nextCommand } : {}),
   };
@@ -1087,6 +1091,9 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     const child = runExternalCommand(delegatedCommand, options);
     const seedAlreadyApplied =
       child.status !== 0 && isWorkOSSeedAlreadyApplied(child.stdout, child.stderr);
+    const seedAlreadyAppliedReason = seedAlreadyApplied
+      ? "workos-cli-existing-resource"
+      : undefined;
     const seedStateFile = child.status === 0 || seedAlreadyApplied
       ? writeWorkOSSeedState({
         workspaceRoot: options.workspaceRoot,
@@ -1113,11 +1120,17 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
         seedState: latestSeedState,
         seedFileSanitized: preparedSeed.sanitized,
         seedAlreadyApplied,
+        seedAlreadyAppliedReason,
         seedStateFile,
+        workosCli: {
+          status: child.status,
+          idempotentConflict: seedAlreadyApplied,
+          stderrSuppressed: seedAlreadyApplied && Boolean(child.stderr.trim()),
+        },
         configActions,
       }),
       stdout: child.stdout,
-      stderr: child.stderr,
+      stderr: seedAlreadyApplied ? undefined : child.stderr,
       exitCode: child.status === 0 || seedAlreadyApplied ? 0 : 1,
     };
   } finally {

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.44";
+export const FORGEOS_VERSION = "0.1.0-alpha.46";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;