forgeos 0.1.0-alpha.52 → 0.1.0-alpha.54

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.52 input=9a95853ed8e82db41be0b0cc4fc809e0b1c0c12fd1ac024d386bc651a70d965b content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.54 input=7577a1a1a717ae3776c6725b005a98a36c149041f62ef4e28e098baad0bd1fcc content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # forgeos
 
+## 0.1.0-alpha.54
+
+### Patch Changes
+
+- Add a machine-readable WorkOS FGA hosted setup artifact.
+
+  - `forge workos fga plan --write --json` and real sync failures that write
+    `.forge/workos-fga-setup.md` now also write
+    `.forge/workos-fga-setup.json`.
+  - The JSON artifact includes the derived resource types, hosted setup
+    boundary, rerun commands, docs, unsupported automation notes, and paired
+    Markdown/JSON paths so agents and CI can consume the FGA handoff without
+    parsing Markdown.
+  - Human output now prints both the Markdown guide and JSON setup artifact
+    paths when they are written.
+
+## 0.1.0-alpha.53
+
+### Patch Changes
+
+- Keep WorkOS FGA proof messaging honest across local and real modes.
+
+  - `forge workos fga doctor --json` now reports local proof timestamps as
+    local proof instead of using real-production wording when the state file was
+    produced by local FGA proof commands.
+  - This prevents local/mock FGA evidence from being mistaken for hosted WorkOS
+    Authorization API proof during production-readiness handoff.
+
 ## 0.1.0-alpha.52
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,20 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.54
+
+- WorkOS FGA setup writes now produce a paired machine-readable
+  `.forge/workos-fga-setup.json` artifact alongside the Markdown guide.
+- The JSON artifact includes derived resource types, hosted setup boundary,
+  rerun commands, docs, unsupported automation notes, and paired artifact paths
+  for agents and CI.
+
+## 0.1.0-alpha.53
+
+- `forge workos fga doctor --json` now distinguishes local FGA proof timestamps
+  from real WorkOS Authorization API proof timestamps, avoiding production
+  readiness confusion in agent handoffs.
+
 ## 0.1.0-alpha.52
 
 - Generated WorkOS FGA setup guides now include an explicit automation boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.52",
+  "version": "0.1.0-alpha.54",
   "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.52","releaseId":"forgeos@0.1.0-alpha.52+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.54","releaseId":"forgeos@0.1.0-alpha.54+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.52 input=9a95853ed8e82db41be0b0cc4fc809e0b1c0c12fd1ac024d386bc651a70d965b content=d4d4c9fd5f2fe5a5d3fa127d43487901cf1e68875b7ac99abdfe9a9cc90265ee
+// @forge-generated generator=0.1.0-alpha.54 input=7577a1a1a717ae3776c6725b005a98a36c149041f62ef4e28e098baad0bd1fcc content=7078de03fb1c3ae829b803fdfd1e9320fa10b8c128e51d374d8afab09cdc3df5
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.52",
-  "releaseId": "forgeos@0.1.0-alpha.52+unknown",
+  "packageVersion": "0.1.0-alpha.54",
+  "releaseId": "forgeos@0.1.0-alpha.54+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/workos.ts

@@ -57,6 +57,7 @@ const GENERATED_SEED_FILE = `${GENERATED_DIR}/integrations/workos/workos-seed.ym
 const WORKOS_SEED_STATE_FILE = ".workos-seed-state.json";
 const WORKOS_FGA_STATE_FILE = ".workos-fga-state.json";
 const WORKOS_FGA_SETUP_GUIDE_FILE = ".forge/workos-fga-setup.md";
+const WORKOS_FGA_SETUP_PLAN_FILE = ".forge/workos-fga-setup.json";
 
 function runExternalCommand(
   command: string[],
@@ -714,7 +715,16 @@ export interface WorkOSFgaResourceTypeSetup {
 }
 
 export interface WorkOSFgaSetupGuide {
+  schemaVersion: "0.1.0";
+  kind: "workos-fga-setup";
   resourceTypes: WorkOSFgaResourceTypeSetup[];
+  hostedSetup: WorkOSFgaHostedSetup;
+  commands: {
+    plan: string;
+    syncReal: string;
+    proveReal: string;
+    deployCheck: string;
+  };
   markdown: string;
   docs: string[];
   unsupportedAutomation: string[];
@@ -1196,7 +1206,16 @@ function workOSFgaSetupGuide(manifest: WorkOSFgaManifest, hostedSetup: WorkOSFga
     "",
   ].join("\n");
   return {
+    schemaVersion: "0.1.0",
+    kind: "workos-fga-setup",
     resourceTypes,
+    hostedSetup,
+    commands: {
+      plan: "forge workos fga plan --file workos-seed.yml --write --json",
+      syncReal: "forge workos fga sync --real --file workos-seed.yml --json",
+      proveReal: "forge workos fga prove --real --file workos-seed.yml --json",
+      deployCheck: "forge deploy check --production --json",
+    },
     markdown,
     docs: hostedSetup.docs,
     unsupportedAutomation: [
@@ -1214,16 +1233,34 @@ function resolveWorkOSFgaSetupGuidePath(options: WorkOSCommandOptions): string |
   return candidate && candidate !== "true" && !candidate.startsWith("--") ? candidate : WORKOS_FGA_SETUP_GUIDE_FILE;
 }
 
+function workOSFgaSetupPlanPath(markdownPath: string): string {
+  if (markdownPath === WORKOS_FGA_SETUP_GUIDE_FILE) {
+    return WORKOS_FGA_SETUP_PLAN_FILE;
+  }
+  return markdownPath.endsWith(".md")
+    ? `${markdownPath.slice(0, -3)}.json`
+    : `${markdownPath}.json`;
+}
+
 function writeWorkOSFgaSetupGuide(
   workspaceRoot: string,
   guide: WorkOSFgaSetupGuide,
   preferredPath = WORKOS_FGA_SETUP_GUIDE_FILE,
-): string {
+): { markdownPath: string; jsonPath: string } {
   const relativePath = preferredPath.startsWith("/") ? preferredPath.slice(1) : preferredPath;
   const absolutePath = join(workspaceRoot, relativePath);
   mkdirSync(dirname(absolutePath), { recursive: true });
   writeFileSync(absolutePath, guide.markdown, "utf8");
-  return relativePath;
+  const jsonPath = workOSFgaSetupPlanPath(relativePath);
+  const absoluteJsonPath = join(workspaceRoot, jsonPath);
+  mkdirSync(dirname(absoluteJsonPath), { recursive: true });
+  const { markdown: _markdown, ...jsonGuide } = guide;
+  writeFileSync(absoluteJsonPath, `${JSON.stringify({
+    ...jsonGuide,
+    markdownPath: relativePath,
+    jsonPath,
+  }, null, 2)}\n`, "utf8");
+  return { markdownPath: relativePath, jsonPath };
 }
 
 function fgaData(input: {
@@ -1240,6 +1277,7 @@ function fgaData(input: {
   nextCommand?: string;
   nextActions?: string[];
   setupGuidePath?: string;
+  setupGuideJsonPath?: string;
 }): Record<string, unknown> {
   const hostedSetup = workOSFgaHostedSetup(input.manifest, input.workosSdk);
   const setupGuide = workOSFgaSetupGuide(input.manifest, hostedSetup);
@@ -1259,6 +1297,7 @@ function fgaData(input: {
     ...(input.workosSdk ? { workosSdk: input.workosSdk } : {}),
     ...(input.stateFile ? { stateFile: input.stateFile } : {}),
     ...(input.setupGuidePath ? { setupGuidePath: input.setupGuidePath } : {}),
+    ...(input.setupGuideJsonPath ? { setupGuideJsonPath: input.setupGuideJsonPath } : {}),
     nextCommand: input.nextCommand,
     nextActions: input.nextActions ?? hostedSetup.nextActions,
     notes: [
@@ -2621,7 +2660,9 @@ function collectWorkOSFgaChecks(input: {
       name: "fga-proof-state",
       ok: !input.requireProof || Boolean(input.state.provedAt),
       detail: input.state.provedAt
-        ? `${WORKOS_FGA_STATE_FILE} records real proof at ${input.state.provedAt}`
+        ? input.state.mode === "real"
+          ? `${WORKOS_FGA_STATE_FILE} records real proof at ${input.state.provedAt}`
+          : `${WORKOS_FGA_STATE_FILE} records local proof at ${input.state.provedAt}`
         : input.requireProof
           ? `${WORKOS_FGA_STATE_FILE} must be produced by forge workos fga prove --real --json`
           : `${WORKOS_FGA_STATE_FILE} proof timestamp not required for this command`,
@@ -2762,9 +2803,12 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
   const manifest = collectWorkOSFgaManifest(options.workspaceRoot, file);
   const initialHostedSetup = workOSFgaHostedSetup(manifest);
   const setupGuidePath = resolveWorkOSFgaSetupGuidePath(options);
-  const writtenSetupGuidePath = setupGuidePath
+  const writtenSetupGuide = setupGuidePath
     ? writeWorkOSFgaSetupGuide(options.workspaceRoot, workOSFgaSetupGuide(manifest, initialHostedSetup), setupGuidePath)
     : undefined;
+  const writtenSetupGuideData = writtenSetupGuide
+    ? { setupGuidePath: writtenSetupGuide.markdownPath, setupGuideJsonPath: writtenSetupGuide.jsonPath }
+    : {};
   let state = readWorkOSFgaState(options.workspaceRoot, manifest);
   const command = ["forge", "workos", "fga", action, "--file", file];
   const real = options.real ?? false;
@@ -2796,7 +2840,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         state,
         seedState,
         real,
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: `forge workos fga sync --file ${file} --json`,
       }),
       exitCode: ok ? 0 : 1,
@@ -2833,7 +2877,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga plan --file ${file} --json`,
         }),
         exitCode: 1,
@@ -2854,7 +2898,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga sync --file ${file} --json`,
         }),
         exitCode: 0,
@@ -2884,7 +2928,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           real,
           ...(cliAuth ? { cliAuth } : {}),
           workosSdk: sdk.data,
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: `forge workos fga sync --real --file ${file} --json`,
           nextActions: workOSFgaHostedSetup(manifest, sdk.data).nextActions,
         }),
@@ -2917,7 +2961,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
         stateFile,
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: real ? `forge workos fga prove --real --file ${file} --json` : `forge workos fga prove --file ${file} --json`,
       }),
       exitCode: 0,
@@ -2990,7 +3034,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
         ...(stateFile ? { stateFile } : {}),
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: ok ? "forge deploy check --production --json" : `forge workos fga sync${real ? " --real" : ""} --file ${file} --json`,
       }),
       stdout: sdk?.stdout,
@@ -3030,7 +3074,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
       seedState,
       readiness,
       real,
-      ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+      ...writtenSetupGuideData,
       nextCommand: readiness.nextCommand,
       nextActions: readiness.nextActions,
     }),
@@ -3157,11 +3201,14 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
   }
   if (result.kind === "workos-fga") {
     const data = result.data && typeof result.data === "object"
-      ? result.data as { action?: string; real?: boolean; nextCommand?: string; stateFile?: string; setupGuidePath?: string; nextActions?: string[] }
+      ? result.data as { action?: string; real?: boolean; nextCommand?: string; stateFile?: string; setupGuidePath?: string; setupGuideJsonPath?: string; nextActions?: string[] }
       : {};
     if (data.setupGuidePath) {
       lines.push(`FGA setup guide: ${data.setupGuidePath}`);
     }
+    if (data.setupGuideJsonPath) {
+      lines.push(`FGA setup JSON: ${data.setupGuideJsonPath}`);
+    }
     if (result.ok && data.action === "plan") {
       lines.push(`WorkOS FGA plan passed; run ${data.nextCommand ?? "forge workos fga sync --json"}.`);
     } else if (result.ok && data.action === "sync") {

package/src/forge/version.ts

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