forgeos 0.1.0-alpha.47 → 0.1.0-alpha.49

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.47 input=2bfccc8587b228260a6fa7172aa13b90311bacf5c1ddfa549d864e057cb0c6bf content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.49 input=a7c20b1d3492dcb4111d826ff8622647abd8f6be499cffb3c27e077c9b3267b1 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # forgeos
 
+## 0.1.0-alpha.49
+
+### Patch Changes
+
+- Improve release doctor visibility for npm dist-tag drift.
+
+  - `forge release doctor --json` now checks the published npm `alpha` and
+    `latest` dist-tags for public packages, reports the currently published
+    tag versions, and suggests the exact `npm dist-tag add` remediation when
+    `latest` still points at an older alpha.
+  - The npm dist-tag check is advisory rather than publish-blocking, so a
+    prepared alpha release can still ship while clearly reporting that the
+    consumer-facing `latest` tag needs promotion.
+  - GitHub Actions latest-promotion notices now include the local remediation
+    command and the `NPM_TOKEN` configuration hint when latest promotion is
+    skipped.
+
+## 0.1.0-alpha.48
+
+### Patch Changes
+
+- Complete the WorkOS FGA bridge path for production-shaped apps.
+
+  - `forge workos fga plan/sync/prove` now models the derived app resource
+    graph, hosted WorkOS resource-type setup, required membership evidence, and
+    proof scenarios as a first-class FGA manifest.
+  - `forge workos fga sync --real` and `forge workos fga prove --real` can run
+    through the authenticated WorkOS CLI/API path when `WORKOS_API_KEY` is not
+    present, preserving the no-dashboard agent flow while still using real
+    WorkOS Authorization API calls.
+  - FGA setup guidance now distinguishes what ForgeOS can automate
+    (permissions/roles through seed, resources, checks, deploy evidence) from
+    hosted WorkOS resource-type configuration, with precise remediation when
+    resource types are missing.
+  - `forge deploy check --production` now points WorkOS apps at the full FGA
+    sequence: plan, real sync, real proof, and final deploy check.
+  - WorkOS seed generation now preserves inferred FGA parent resources such as
+    `access_request -> vendor`, and regression coverage guards the generated
+    seed, CLI parser, deploy gates, and FGA setup output.
+
 ## 0.1.0-alpha.47
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,35 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.49
+
+- `forge release doctor --json` now reports npm `alpha` and `latest` dist-tag
+  versions for public packages, including exact remediation when `latest`
+  points at an older alpha.
+- The dist-tag check is advisory and non-publish-blocking, keeping alpha
+  release validation usable while making stale `latest` state explicit.
+- GitHub Actions latest-promotion notices now include the local
+  `npm dist-tag add <package>@<version> latest` fallback and `NPM_TOKEN`
+  configuration hint when promotion is skipped.
+
+## 0.1.0-alpha.48
+
+- Added the production-shaped WorkOS FGA flow:
+  `forge workos fga plan`, `sync`, `prove`, and `doctor` now derive an FGA
+  manifest from the app contract, policies, data graph, and `workos-seed.yml`.
+- `forge workos fga sync --real` and `forge workos fga prove --real` can use
+  the authenticated WorkOS CLI/API path when `WORKOS_API_KEY` is not available,
+  so agents can continue the no-dashboard flow after `workos auth login`.
+- FGA setup output now separates hosted WorkOS resource-type configuration from
+  ForgeOS-automated resource sync and authorization checks, and reports missing
+  resource types with exact next actions.
+- `forge deploy check --production` now requires matching WorkOS FGA real
+  sync/proof evidence for WorkOS-backed apps and points operators at
+  `forge workos fga plan --write`, `sync --real`, and `prove --real`.
+- WorkOS seed generation now keeps inferred parent resource relationships such
+  as `access_request -> vendor`, with regression coverage for the generated
+  seed, parser, deploy checks, and FGA plan output.
+
 ## 0.1.0-alpha.47
 
 - `forge workos setup --real` and `forge workos prove --real` now validate the

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.47 input=2bfccc8587b228260a6fa7172aa13b90311bacf5c1ddfa549d864e057cb0c6bf content=8f94368d298a28e68f6aaaf12350b8c58f890a4dc0d060299824515dce02cae6
+// @forge-generated generator=0.1.0-alpha.49 input=a7c20b1d3492dcb4111d826ff8622647abd8f6be499cffb3c27e077c9b3267b1 content=bfe9659e5f5a5d2d52e6ac7eb6c13d2bc356c8bf95724fafc6e10fe4641f2104
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.47",
-  "releaseId": "forgeos@0.1.0-alpha.47+unknown",
+  "packageVersion": "0.1.0-alpha.49",
+  "releaseId": "forgeos@0.1.0-alpha.49+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/commands.ts

@@ -6,6 +6,8 @@ import { classify } from "../compiler/classifier/classify.ts";
 import { buildRuntimeMatrix } from "../compiler/classifier/runtime-matrix.ts";
 import {
   FORGE_DB_EMPTY_TIMESTAMP_LITERAL,
+  FORGE_RELEASE_NPM_DIST_TAG_CHECK_FAILED,
+  FORGE_RELEASE_NPM_DIST_TAG_STALE,
   FORGE_RELEASE_PACKAGE_PACK_FAILED,
 } from "../compiler/diagnostics/codes.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
@@ -1149,7 +1151,7 @@ interface ReleaseDoctorCheck {
   requiredForPublish: boolean;
   requiredForProduction?: boolean;
   state?: string;
-  result: ReleaseCommandResult | SelfHostCommandResult | DocsCheckResult | DeployCommandResult | PackagePackCheckResult;
+  result: ReleaseCommandResult | SelfHostCommandResult | DocsCheckResult | DeployCommandResult | PackagePackCheckResult | NpmDistTagCheckResult;
 }
 
 interface PackagePackCheckResult {
@@ -1166,6 +1168,24 @@ interface PackagePackCheckResult {
   exitCode: 0 | 1;
 }
 
+interface NpmDistTagCheckResult {
+  ok: boolean;
+  data: {
+    command: string;
+    packageName: string | null;
+    packageVersion: string | null;
+    alphaVersion: string | null;
+    latestVersion: string | null;
+    alphaMatches: boolean;
+    latestMatches: boolean;
+    source: "npm-view" | "env-fixture" | "skipped";
+  };
+  diagnostics: ReturnType<typeof createDiagnostic>[];
+  nextActions?: string[];
+  failureKind?: string;
+  exitCode: 0 | 1;
+}
+
 interface ReleaseDoctorResult {
   schemaVersion: "0.1.0";
   ok: boolean;
@@ -1263,6 +1283,156 @@ function runPackagePackDryRun(workspaceRoot: string): PackagePackCheckResult {
   }
 }
 
+function parseNpmDistTagsJson(raw: string): Record<string, string> | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    const tags: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string") {
+        tags[key] = value;
+      }
+    }
+    return tags;
+  } catch {
+    return null;
+  }
+}
+
+function runNpmDistTagCheck(workspaceRoot: string): NpmDistTagCheckResult {
+  const pkg = readPackageJson(workspaceRoot) as {
+    name?: unknown;
+    version?: unknown;
+    private?: unknown;
+  };
+  const packageName = typeof pkg.name === "string" ? pkg.name : null;
+  const packageVersion = typeof pkg.version === "string" ? pkg.version : null;
+  const command = packageName ? `npm view ${packageName} dist-tags --json` : "npm view <package> dist-tags --json";
+  const baseData = {
+    command,
+    packageName,
+    packageVersion,
+    alphaVersion: null,
+    latestVersion: null,
+    alphaMatches: false,
+    latestMatches: false,
+    source: "skipped" as const,
+  };
+
+  if (pkg.private === true) {
+    return {
+      ok: true,
+      data: baseData,
+      diagnostics: [],
+      exitCode: 0,
+    };
+  }
+  if (!packageName || !packageVersion) {
+    return {
+      ok: false,
+      data: baseData,
+      diagnostics: [
+        createDiagnostic({
+          severity: "warning",
+          code: FORGE_RELEASE_NPM_DIST_TAG_CHECK_FAILED,
+          message: "release doctor could not check npm dist-tags because package.json is missing name or version",
+          fixHint: "Set package.json name and version before publishing, then rerun forge release doctor.",
+          suggestedCommands: ["node bin/forge.mjs release doctor --json"],
+        }),
+      ],
+      nextActions: ["node bin/forge.mjs release doctor --json"],
+      failureKind: "npm-dist-tags-package-metadata-missing",
+      exitCode: 1,
+    };
+  }
+
+  const fixture = process.env.FORGE_RELEASE_NPM_DIST_TAGS_JSON;
+  const source = fixture ? "env-fixture" as const : "npm-view" as const;
+  const stdout = fixture ?? spawnSync("npm", ["view", packageName, "dist-tags", "--json"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    timeout: 10_000,
+    windowsHide: true,
+  }).stdout;
+  const tags = parseNpmDistTagsJson(stdout || "");
+  if (!tags) {
+    return {
+      ok: false,
+      data: { ...baseData, source },
+      diagnostics: [
+        createDiagnostic({
+          severity: "warning",
+          code: FORGE_RELEASE_NPM_DIST_TAG_CHECK_FAILED,
+          message: `release doctor could not read npm dist-tags for ${packageName}`,
+          fixHint: `Run ${command}. If the package has not been published yet, publish it with the alpha tag first.`,
+          suggestedCommands: [command, "npm run release:publish-alpha"],
+        }),
+      ],
+      nextActions: [command, "npm run release:publish-alpha"],
+      failureKind: "npm-dist-tags-unavailable",
+      exitCode: 1,
+    };
+  }
+
+  const alphaVersion = tags.alpha ?? null;
+  const latestVersion = tags.latest ?? null;
+  const alphaMatches = alphaVersion === packageVersion;
+  const latestMatches = latestVersion === packageVersion;
+  const data = {
+    command,
+    packageName,
+    packageVersion,
+    alphaVersion,
+    latestVersion,
+    alphaMatches,
+    latestMatches,
+    source,
+  };
+  if (alphaMatches && latestMatches) {
+    return {
+      ok: true,
+      data,
+      diagnostics: [],
+      exitCode: 0,
+    };
+  }
+
+  const nextActions: string[] = [];
+  const diagnostics: ReturnType<typeof createDiagnostic>[] = [];
+  if (!alphaMatches) {
+    nextActions.push("npm run release:publish-alpha");
+    diagnostics.push(createDiagnostic({
+      severity: "warning",
+      code: FORGE_RELEASE_NPM_DIST_TAG_STALE,
+      message: `${packageName}@alpha points to ${alphaVersion ?? "none"}, not local version ${packageVersion}`,
+      fixHint: "Publish the current package with the alpha tag before asking users to install forgeos@alpha.",
+      suggestedCommands: ["npm run release:publish-alpha", command],
+    }));
+  }
+  if (!latestMatches) {
+    const promote = `npm dist-tag add ${packageName}@${packageVersion} latest`;
+    nextActions.push(promote);
+    nextActions.push("configure NPM_TOKEN in GitHub Actions secrets, or run npm login locally before promoting latest");
+    diagnostics.push(createDiagnostic({
+      severity: "warning",
+      code: FORGE_RELEASE_NPM_DIST_TAG_STALE,
+      message: `${packageName}@latest points to ${latestVersion ?? "none"}, not local version ${packageVersion}`,
+      fixHint: `Promote latest after the alpha package is verified: ${promote}`,
+      suggestedCommands: [promote, command],
+    }));
+  }
+  return {
+    ok: false,
+    data,
+    diagnostics,
+    nextActions,
+    failureKind: !alphaMatches ? "npm-alpha-dist-tag-stale" : "npm-latest-dist-tag-stale",
+    exitCode: 1,
+  };
+}
+
 export async function runReleaseDoctorCommand(command: Extract<ForgeCommand, { kind: "release" }>): Promise<ReleaseDoctorResult> {
   const release = await runReleaseCommand({
     ...command,
@@ -1300,6 +1470,7 @@ export async function runReleaseDoctorCommand(command: Extract<ForgeCommand, { k
     production: true,
   });
   const packagePack = runPackagePackDryRun(command.workspaceRoot);
+  const npmDistTags = runNpmDistTagCheck(command.workspaceRoot);
   const checks: ReleaseDoctorCheck[] = [
     {
       name: "release-prepared",
@@ -1340,6 +1511,13 @@ export async function runReleaseDoctorCommand(command: Extract<ForgeCommand, { k
       requiredForPublish: true,
       result: packagePack,
     },
+    {
+      name: "npm-dist-tags",
+      ok: npmDistTags.ok,
+      requiredForPublish: false,
+      state: npmDistTags.failureKind ?? (npmDistTags.data.source === "skipped" ? "skipped" : "current"),
+      result: npmDistTags,
+    },
   ];
   const failed = checks.filter((check) => !check.ok).map((check) => check.name);
   const notPrepared = checks

package/src/forge/cli/deploy.ts

@@ -853,6 +853,25 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       command: "forge workos prove --real --file workos-seed.yml --json",
       details: seedState,
     });
+    const workosFgaDoctor = runWorkOSCommand({
+      subcommand: "fga",
+      fgaAction: "doctor",
+      workspaceRoot: options.workspaceRoot,
+      json: true,
+      yes: false,
+      dryRun: true,
+      real: options.production,
+    });
+    checks.push({
+      name: "workos-fga-proof",
+      ok: !options.production || workosFgaDoctor.exitCode === 0,
+      severity: options.production ? "error" : "warning",
+      message: workosFgaDoctor.exitCode === 0
+        ? "WorkOS FGA resource graph state matches the current app contract and seed"
+        : "WorkOS production deploy requires FGA graph sync/proof evidence matching the current app",
+      command: "forge workos fga prove --real --file workos-seed.yml --json",
+      details: workosFgaDoctor.data,
+    });
   }
   const tenantProofRequired = auth.requiresTenant || hasWorkOSIntegration(options.workspaceRoot);
   const tenantProof = tenantProofRequired
@@ -928,6 +947,9 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
   });
 
   const errorFree = checks.every((check) => check.ok || check.severity === "warning");
+  const failureActions = unique(checks.flatMap((check) =>
+    !check.ok && check.command ? expandDeployFailureCommand(check.command) : []
+  ));
   return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     schemaVersion: "0.1.0",
     ok: errorFree,
@@ -938,11 +960,22 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     checks,
     nextActions: errorFree
       ? ["forge deploy verify --production --url https://app.example.com --json"]
-      : unique(checks.flatMap((check) => !check.ok && check.command ? [check.command] : [])),
+      : failureActions,
     exitCode: errorFree ? 0 : 1,
   });
 }
 
+function expandDeployFailureCommand(command: string): string[] {
+  if (command.includes("forge workos fga prove")) {
+    return [
+      "forge workos fga plan --file workos-seed.yml --write --json",
+      "forge workos fga sync --real --file workos-seed.yml --json",
+      command,
+    ];
+  }
+  return [command];
+}
+
 function renderDocker(options: DeployCommandOptions): DeployCommandResult {
   const dir = join(options.workspaceRoot, "deploy");
   nodeFileSystem.mkdirp(dir);

package/src/forge/cli/main.ts

@@ -43,6 +43,10 @@ function formatHelp(): string {
     "  forge workos seed --file workos-seed.yml --dry-run --json  Validate WorkOS seed without hosted changes",
     "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/FGA/seed readiness without dashboard changes",
     "  forge workos setup --real --file workos-seed.yml --json  Apply redirect/CORS/homepage config and seed WorkOS without dashboard",
+    "  forge workos fga plan --json  Derive the WorkOS FGA resource graph and proof scenarios from the app",
+    "  forge workos fga plan --write --json  Write .forge/workos-fga-setup.md for hosted FGA resource type setup",
+    "  forge workos fga sync --json  Record an idempotent local FGA graph state for deploy gates",
+    "  forge workos fga prove --json  Prove local FGA graph, cross-tenant denials, and state freshness",
     "  forge deploy plan --target docker --json  Explain production deploy gates and commands",
     "  forge deploy check --production --json  Gate auth, DB, metadata, generated artifacts, and liveQuery readiness",
     "  forge deploy package --target docker  Write Docker production deploy files under deploy/",

package/src/forge/cli/parse.ts

@@ -19,7 +19,7 @@ import type { AgentContractSubcommand } from "./agent-contract.ts";
 import type { AuthSubcommand } from "./auth.ts";
 import type { BaselineSubcommand } from "./baseline.ts";
 import type { AuthMdSubcommand } from "./authmd.ts";
-import type { WorkOSSubcommand } from "./workos.ts";
+import type { WorkOSFgaAction, WorkOSSubcommand } from "./workos.ts";
 import type { DeploySubcommand, DeployTarget } from "./deploy.ts";
 import type { FieldTestSubcommand } from "./field-test.ts";
 import type { SeedSubcommand } from "./seed.ts";
@@ -152,11 +152,14 @@ export type ForgeCommand =
   | {
       kind: "workos";
       subcommand: WorkOSSubcommand;
+      fgaAction?: WorkOSFgaAction;
       json: boolean;
       file?: string;
       yes: boolean;
       dryRun: boolean;
       real?: boolean;
+      write?: boolean;
+      writePath?: string;
       workspaceRoot: string;
     }
   | {
@@ -597,7 +600,8 @@ const AUTH_SUBCOMMANDS: AuthSubcommand[] = [
 ];
 const BASELINE_SUBCOMMANDS: BaselineSubcommand[] = ["create", "status"];
 const AUTHMD_SUBCOMMANDS: AuthMdSubcommand[] = ["generate", "check"];
-const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed", "setup", "prove"];
+const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed", "setup", "prove", "fga"];
+const WORKOS_FGA_ACTIONS: WorkOSFgaAction[] = ["plan", "sync", "prove", "doctor"];
 const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "check", "render", "package", "verify"];
 const FIELD_TEST_SUBCOMMANDS: FieldTestSubcommand[] = ["create", "run", "report"];
 const SECURITY_SUBCOMMANDS: SecuritySubcommand[] = ["prove"];
@@ -761,6 +765,11 @@ function parseOptionValue(args: string[], flag: string): string | undefined {
   return args[index + 1];
 }
 
+function parseOptionalOptionValue(args: string[], flag: string): string | undefined {
+  const value = parseOptionValue(args, flag);
+  return value && !value.startsWith("--") ? value : undefined;
+}
+
 function parseOptionValues(args: string[], flag: string): string[] {
   const values: string[] = [];
   for (let index = 0; index < args.length; index++) {
@@ -1444,18 +1453,27 @@ export function parseCli(argv: string[]): ParsedCli {
     case "workos": {
       const subcommand = rest[0] as WorkOSSubcommand | undefined;
       if (!subcommand || !WORKOS_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge workos requires subcommand: install, doctor, seed, setup, or prove");
+        errors.push("forge workos requires subcommand: install, doctor, seed, setup, prove, or fga");
+        return { command: null, workspaceRoot, errors };
+      }
+      const fgaAction = subcommand === "fga" ? rest[1] as WorkOSFgaAction | undefined : undefined;
+      if (subcommand === "fga" && (!fgaAction || !WORKOS_FGA_ACTIONS.includes(fgaAction))) {
+        errors.push("forge workos fga requires action: plan, sync, prove, or doctor");
         return { command: null, workspaceRoot, errors };
       }
+      const workOSWritePath = parseOptionalOptionValue(argv, "--write");
       return {
         command: {
           kind: "workos",
           subcommand,
+          ...(fgaAction ? { fgaAction } : {}),
           json: parseFlag(argv, "--json"),
           file: parseOptionValue(argv, "--file"),
           yes: parseFlag(argv, "--yes"),
           dryRun: parseFlag(argv, "--dry-run"),
           real: parseFlag(argv, "--real"),
+          write: parseFlag(argv, "--write"),
+          ...(workOSWritePath ? { writePath: workOSWritePath } : {}),
           workspaceRoot,
         },
         workspaceRoot,