forgeos 0.1.0-alpha.34 → 0.1.0-alpha.36

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.34 input=ce9cf8b6c553d7de8113eb2a388d269cb8c90d4bb15c013a7ab907ef207619b9 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.36 input=fed0c5202e23edeb9d4d7f31d0de594194b8a898741da3c1a74b8c2d54758aa5 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # forgeos
 
+## 0.1.0-alpha.36
+
+### Patch Changes
+
+- Smooth the alpha field-test loop after the Vendor Access app exercise.
+
+  - Teach `forge deps upgrade-plan` to resolve npm alias dependencies such as `forge: npm:forgeos@alpha`, while preserving alias install specs like `forge@npm:forgeos@0.1.0-alpha.36` in generated upgrade plans.
+  - Normalize `auth.md` runtime risk rendering so Commands and Risk/Approval metadata agree that commands default to `write`.
+  - Add non-throwing command proof APIs through generated `client.commandResult(...)` and React `useCommandResult(...)`, so expected policy denials can be rendered as structured results instead of noisy unhandled browser failures.
+  - Update the basic example schema/docs to use `organizations` as the root tenant table instead of a self-referential `tenants` root.
+
+## 0.1.0-alpha.35
+
+### Patch Changes
+
+- Harden field-test regressions found while building WorkOS-style multi-tenant apps.
+
+  - Resolve camelCase `ref:` targets such as `ref:accessRequests` to canonical SQL table names like `access_requests`, and report unknown refs before invalid SQL reaches PGlite.
+  - Allow WorkOS-like local dev auth headers through dev-server CORS, including organization, membership, permissions, roles, and claims headers.
+  - Teach the generated agent contract and capability map to recognize camelCase `ctx.db` aliases for snake_case tables.
+  - Avoid printing fake `http://127.0.0.1:0` API URLs in `forge dev --port 0` startup diagnostics.
+
 ## 0.1.0-alpha.34
 
 ### 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.36
+
+- Smoothed the alpha field-test loop after the Vendor Access app exercise.
+- Taught `forge deps upgrade-plan` to resolve npm alias dependencies such as
+  `forge: npm:forgeos@alpha`, while preserving alias install specs like
+  `forge@npm:forgeos@0.1.0-alpha.36` in generated upgrade plans.
+- Normalized `auth.md` runtime risk rendering so Commands and Risk/Approval
+  metadata agree that commands default to `write`.
+- Added non-throwing command proof APIs through generated
+  `client.commandResult(...)` and React `useCommandResult(...)`, so expected
+  policy denials can be rendered as structured results instead of noisy
+  unhandled browser failures.
+- Updated the basic example schema/docs to use `organizations` as the root
+  tenant table instead of a self-referential `tenants` root.
+
+## 0.1.0-alpha.35
+
+- Hardened field-test regressions found while building WorkOS-style
+  multi-tenant apps.
+- Resolved camelCase `ref:` targets such as `ref:accessRequests` to canonical
+  SQL table names like `access_requests`, and reported unknown refs before
+  invalid SQL reaches PGlite.
+- Allowed WorkOS-like local dev auth headers through dev-server CORS,
+  including organization, membership, permissions, roles, and claims headers.
+- Taught the generated agent contract and capability map to recognize
+  camelCase `ctx.db` aliases for snake_case tables.
+- Avoided printing fake `http://127.0.0.1:0` API URLs in
+  `forge dev --port 0` startup diagnostics.
+
 ## 0.1.0-alpha.34
 
 - Hardened the ForgeOS app-building DX after the Vendor Access field test.

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.34 input=ce9cf8b6c553d7de8113eb2a388d269cb8c90d4bb15c013a7ab907ef207619b9 content=1a3f239bc322349796830461349167bb154a27e57fb1f10868c788194b3be97e
+// @forge-generated generator=0.1.0-alpha.36 input=fed0c5202e23edeb9d4d7f31d0de594194b8a898741da3c1a74b8c2d54758aa5 content=55e1e8090cce3a057473a21fe3382f8f159581327fa98ecee1a489f8de6965d0
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.34",
-  "releaseId": "forgeos@0.1.0-alpha.34+unknown",
+  "packageVersion": "0.1.0-alpha.36",
+  "releaseId": "forgeos@0.1.0-alpha.36+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/authmd.ts

@@ -64,6 +64,8 @@ interface AgentToolsLike {
   }>;
 }
 
+type RuntimeEntryKind = "command" | "query" | "liveQuery" | "action";
+
 function readGeneratedJson<T>(workspaceRoot: string, relativePath: string): T | null {
   const absolute = join(workspaceRoot, relativePath);
   if (!nodeFileSystem.exists(absolute)) {
@@ -76,11 +78,32 @@ function outputPath(options: AuthMdCommandOptions): string {
   return options.output?.trim() || "public/auth.md";
 }
 
-function listRuntimeEntries(title: string, entries: RuntimeEntry[] | undefined): string[] {
+function runtimeEntryRisk(kind: RuntimeEntryKind, entry: RuntimeEntry): string {
+  if (entry.risk) {
+    return entry.risk;
+  }
+  if (kind === "command") {
+    return "write";
+  }
+  if (kind === "action") {
+    return "external";
+  }
+  return "read";
+}
+
+function runtimeEntryNeedsApproval(kind: RuntimeEntryKind, entry: RuntimeEntry): boolean {
+  return entry.needsApproval ?? kind === "action";
+}
+
+function listRuntimeEntries(
+  title: string,
+  kind: RuntimeEntryKind,
+  entries: RuntimeEntry[] | undefined,
+): string[] {
   const rows = (entries ?? []).map((entry) =>
     `| \`${entry.name}\` | ${entry.policy ? `\`${entry.policy}\`` : "none"} | ${
       entry.requiresAuth === false ? "no" : "yes"
-    } | ${entry.risk ?? "read"} | ${String(entry.needsApproval ?? false)} |`
+    } | ${runtimeEntryRisk(kind, entry)} | ${String(runtimeEntryNeedsApproval(kind, entry))} |`
   );
   return [
     `## ${title}`,
@@ -115,16 +138,16 @@ function existingDocLinks(workspaceRoot: string): string[] {
 
 function riskMetadata(contract: AgentContractLike | null, tools: AgentToolsLike | null) {
   const runtime = [
-    ...(contract?.commands ?? []).map((entry) => ({ kind: "command", ...entry, risk: entry.risk ?? "write" })),
-    ...(contract?.queries ?? []).map((entry) => ({ kind: "query", ...entry, risk: entry.risk ?? "read" })),
-    ...(contract?.liveQueries ?? []).map((entry) => ({ kind: "liveQuery", ...entry, risk: entry.risk ?? "read" })),
-    ...(contract?.actions ?? []).map((entry) => ({ kind: "action", ...entry, risk: entry.risk ?? "external" })),
+    ...(contract?.commands ?? []).map((entry) => ({ kind: "command" as const, ...entry })),
+    ...(contract?.queries ?? []).map((entry) => ({ kind: "query" as const, ...entry })),
+    ...(contract?.liveQueries ?? []).map((entry) => ({ kind: "liveQuery" as const, ...entry })),
+    ...(contract?.actions ?? []).map((entry) => ({ kind: "action" as const, ...entry })),
   ].map((entry) => ({
     kind: entry.kind,
     name: entry.name,
     policy: entry.policy ?? null,
-    risk: entry.risk ?? "read",
-    needs_approval: entry.needsApproval ?? (entry.kind === "action"),
+    risk: runtimeEntryRisk(entry.kind, entry),
+    needs_approval: runtimeEntryNeedsApproval(entry.kind, entry),
     requires_auth: entry.requiresAuth !== false,
   }));
   const aiTools = (tools?.tools ?? []).map((tool) => ({
@@ -232,10 +255,10 @@ function renderAuthMd(workspaceRoot: string): AuthMdCommandResult & { content: s
     `- Roles: \`${auth?.claims?.roles ?? "roles"}\``,
     `- Permissions: \`${auth?.claims?.permissions ?? "permissions"}\``,
     "",
-    ...listRuntimeEntries("Commands", contract?.commands),
-    ...listRuntimeEntries("Queries", contract?.queries),
-    ...listRuntimeEntries("Live Queries", contract?.liveQueries),
-    ...listRuntimeEntries("Actions", contract?.actions),
+    ...listRuntimeEntries("Commands", "command", contract?.commands),
+    ...listRuntimeEntries("Queries", "query", contract?.queries),
+    ...listRuntimeEntries("Live Queries", "liveQuery", contract?.liveQueries),
+    ...listRuntimeEntries("Actions", "action", contract?.actions),
     "## Policies",
     "",
     "| Policy | Kind | Roles | Permissions |",

package/src/forge/cli/dev.ts

@@ -595,6 +595,17 @@ export async function resolveAvailableWebPort(input: {
   };
 }
 
+export function devStartupConsoleUrlOptions(input: {
+  host: string;
+  port: number;
+  webUrl?: string;
+}): { apiUrl?: string; webUrl?: string } {
+  return {
+    ...(input.port === 0 ? {} : { apiUrl: `http://${input.host}:${input.port}` }),
+    ...(input.webUrl ? { webUrl: input.webUrl } : {}),
+  };
+}
+
 export interface DevWatchGenerateFailureEvent {
   schemaVersion: "0.1.0";
   event: "dev.generate_failed";
@@ -1138,8 +1149,7 @@ export async function runDevCommand(
       mode: "startup",
       strictSecrets: false,
       includeImpact: true,
-      apiUrl: `http://${host}:${port}`,
-      ...(webUrl ? { webUrl } : {}),
+      ...devStartupConsoleUrlOptions({ host, port, ...(webUrl ? { webUrl } : {}) }),
     });
     if (options.json) {
       process.stdout.write(formatDevConsoleJson(startupCycle));

package/src/forge/compiler/agent-contract/build.ts

@@ -283,9 +283,33 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function toSnakeCaseName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[-\s]+/g, "_")
+    .toLowerCase();
+}
+
+function toCamelCaseName(name: string): string {
+  return name.replace(/[_-]([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase());
+}
+
+function dbTableLookup(dataGraph: AgentContractInput["dataGraph"]): Map<string, string> {
+  const lookup = new Map<string, string>();
+  for (const table of dataGraph.tables) {
+    lookup.set(table.name, table.name);
+    lookup.set(table.exportName, table.name);
+    lookup.set(toSnakeCaseName(table.name), table.name);
+    lookup.set(toSnakeCaseName(table.exportName), table.name);
+    lookup.set(toCamelCaseName(table.name), table.name);
+    lookup.set(toCamelCaseName(table.exportName), table.name);
+  }
+  return lookup;
+}
+
 function addDbAliasesForText(
   text: string,
-  tableNames: Set<string>,
+  tableLookup: Map<string, string>,
   aliases: Map<string, string>,
 ): void {
   for (const match of text.matchAll(
@@ -293,8 +317,9 @@ function addDbAliasesForText(
   )) {
     const alias = match[1] ?? "";
     const table = match[2] ?? match[3] ?? "";
-    if (alias && tableNames.has(table)) {
-      aliases.set(alias, table);
+    const canonicalTable = tableLookup.get(table);
+    if (alias && canonicalTable) {
+      aliases.set(alias, canonicalTable);
     }
   }
 
@@ -304,8 +329,9 @@ function addDbAliasesForText(
       const [rawTable, rawAlias] = part.split(":").map((value) => value.trim());
       const table = rawTable?.replace(/["'`]/g, "") ?? "";
       const alias = (rawAlias ?? rawTable ?? "").replace(/\s*=.*$/, "").trim();
-      if (tableNames.has(table) && alias) {
-        aliases.set(alias, table);
+      const canonicalTable = tableLookup.get(table);
+      if (canonicalTable && alias) {
+        aliases.set(alias, canonicalTable);
       }
     }
   }
@@ -313,26 +339,28 @@ function addDbAliasesForText(
 
 function dbTablesForText(
   text: string,
-  tableNames: Set<string>,
+  tableLookup: Map<string, string>,
   ops: Set<string>,
 ): string[] {
   const tables: string[] = [];
   for (const match of text.matchAll(/ctx\.db\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
     const table = match[1] ?? "";
     const op = match[2] ?? "";
-    if (tableNames.has(table) && ops.has(op)) {
-      tables.push(table);
+    const canonicalTable = tableLookup.get(table);
+    if (canonicalTable && ops.has(op)) {
+      tables.push(canonicalTable);
     }
   }
   for (const match of text.matchAll(/ctx\.db\s*\[\s*["'`]([^"'`]+)["'`]\s*\]\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
     const table = match[1] ?? "";
     const op = match[2] ?? "";
-    if (tableNames.has(table) && ops.has(op)) {
-      tables.push(table);
+    const canonicalTable = tableLookup.get(table);
+    if (canonicalTable && ops.has(op)) {
+      tables.push(canonicalTable);
     }
   }
   const aliases = new Map<string, string>();
-  addDbAliasesForText(text, tableNames, aliases);
+  addDbAliasesForText(text, tableLookup, aliases);
   for (const [alias, table] of aliases) {
     const aliasPattern = new RegExp(`\\b${escapeRegExp(alias)}\\s*\\.\\s*([A-Za-z_$][A-Za-z0-9_$]*)`, "g");
     for (const match of text.matchAll(aliasPattern)) {
@@ -348,10 +376,10 @@ function dbTablesForText(
 function dbTablesForFile(
   workspaceRoot: string,
   file: string | undefined,
-  tableNames: Set<string>,
+  tableLookup: Map<string, string>,
   ops: Set<string>,
 ): string[] {
-  return dbTablesForText(sourceTextWithLocalImports(workspaceRoot, file), tableNames, ops);
+  return dbTablesForText(sourceTextWithLocalImports(workspaceRoot, file), tableLookup, ops);
 }
 
 function emittedEventsForFile(workspaceRoot: string, file: string | undefined): string[] {
@@ -1222,7 +1250,7 @@ export function buildAgentContractArtifacts(
   );
 
   const runtimeEntries = new Map(input.runtimeGraph.entries.map((entry) => [entry.name, entry]));
-  const tableNames = new Set(input.dataGraph.tables.map((table) => table.name));
+  const tableLookup = dbTableLookup(input.dataGraph);
   const externalEntries = input.externalServices?.services.flatMap((service) => service.entries) ?? [];
   const localCommandInfos: AgentContract["commands"] = sorted(Object.keys(input.apiSurface.commands), (name) => name).map((name) => {
     const entry = runtimeEntries.get(name);
@@ -1232,8 +1260,8 @@ export function buildAgentContractArtifacts(
       file,
       source: "local" as const,
       policy: authPolicy(commandAuth.get(name)),
-      tablesRead: dbTablesForFile(input.workspaceRoot, file, tableNames, DB_READ_OPS),
-      tablesWritten: dbTablesForFile(input.workspaceRoot, file, tableNames, DB_WRITE_OPS),
+      tablesRead: dbTablesForFile(input.workspaceRoot, file, tableLookup, DB_READ_OPS),
+      tablesWritten: dbTablesForFile(input.workspaceRoot, file, tableLookup, DB_WRITE_OPS),
       emits: emittedEventsForFile(input.workspaceRoot, file),
       allowedPackages: entry ? packageNamesForModule(input.appGraph, entry.moduleId) : [],
       forbiddenCapabilities: forbiddenForContext(input.classified, "command"),
@@ -1268,7 +1296,7 @@ export function buildAgentContractArtifacts(
     policy: authPolicy(queryAuth.get(query.name)),
     readOnly: true,
     tenantScoped: input.tenantScope.tables.length > 0,
-    tablesRead: dbTablesForFile(input.workspaceRoot, query.file, tableNames, DB_READ_OPS),
+    tablesRead: dbTablesForFile(input.workspaceRoot, query.file, tableLookup, DB_READ_OPS),
     allowedPackages: packageNamesForModule(input.appGraph, query.moduleId),
     forbiddenCapabilities: forbiddenForContext(input.classified, "query"),
     http: httpEndpointFor("query", query.name),
@@ -1296,7 +1324,7 @@ export function buildAgentContractArtifacts(
   );
   const liveQueryInfos: AgentContract["liveQueries"] = sorted(input.liveQueryRegistry.liveQueries, (liveQuery) => liveQuery.name).map(
     (liveQuery) => {
-      const tablesRead = dbTablesForFile(input.workspaceRoot, liveQuery.file, tableNames, DB_READ_OPS);
+      const tablesRead = dbTablesForFile(input.workspaceRoot, liveQuery.file, tableLookup, DB_READ_OPS);
       return {
         name: liveQuery.name,
         file: liveQuery.file,

package/src/forge/compiler/client-sdk/render-client.ts

@@ -86,6 +86,22 @@ export type LiveSnapshot<T> = {
   traceId?: string;
 };
 
+export type ForgeCommandResult<T = unknown> =
+  | {
+      ok: true;
+      result: T;
+      status: number;
+      traceId?: string;
+      diagnostics?: { code: string; message: string }[];
+    }
+  | {
+      ok: false;
+      error: { code: string; message: string; details?: unknown };
+      status: number;
+      traceId?: string;
+      diagnostics?: { code: string; message: string }[];
+    };
+
 export type LiveQueryOptions = {
   signal?: AbortSignal;
 };
@@ -96,6 +112,7 @@ export type ForgeClient = {
   readonly lastTraceId?: string;
   query<Name extends QueryName>(name: Name, args: unknown): Promise<unknown>;
   command<Name extends CommandName>(name: Name, args: unknown): Promise<unknown>;
+  commandResult<Name extends CommandName>(name: Name, args: unknown): Promise<ForgeCommandResult<unknown>>;
   externalQuery<Name extends ExternalQueryRef>(name: Name, args: unknown): Promise<unknown>;
   externalCommand<Name extends ExternalCommandRef>(name: Name, args: unknown): Promise<unknown>;
   liveQuery<Name extends LiveQueryName>(
@@ -113,6 +130,7 @@ export function renderClientTs(): string {
   return `import { api } from "./api.ts";
 import type {
   ForgeAuthProvider,
+  ForgeCommandResult,
   ForgeClient,
   ForgeClientConfig,
   ExternalCommandRef,
@@ -128,6 +146,7 @@ export type {
   ForgeAuthProvider,
   ForgeClient,
   ForgeClientConfig,
+  ForgeCommandResult,
   ForgeStaticAuth,
   QueryName,
   CommandName,
@@ -258,6 +277,10 @@ class ForgeHttpClient implements ForgeClient {
     return this.invoke("commands", name, args);
   }
 
+  commandResult(name: string, args: unknown): Promise<ForgeCommandResult<unknown>> {
+    return this.invokeResult("commands", name, args);
+  }
+
   externalQuery(name: ExternalQueryRef, args: unknown): Promise<unknown> {
     return this.invokeExternal("queries", name, args);
   }
@@ -297,27 +320,61 @@ class ForgeHttpClient implements ForgeClient {
     name: string,
     args: unknown,
   ): Promise<unknown> {
+    const result = await this.invokeResult(kind, name, args);
+    if (!result.ok) {
+      throw new ForgeError(result.error.message, {
+        code: result.error.code,
+        traceId: result.traceId,
+        status: result.status,
+        details: result.error.details ?? result.diagnostics,
+      });
+    }
+    return result.result;
+  }
+
+  private async invokeResult(
+    kind: "queries" | "commands",
+    name: string,
+    args: unknown,
+  ): Promise<ForgeCommandResult<unknown>> {
     const baseUrl = this.config.url.replace(/\\/$/, "");
     const url = \`\${baseUrl}/\${kind}/\${encodeURIComponent(name)}\`;
     const authHeaders = await resolveAuthHeaders(this.config.auth);
 
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...authHeaders,
-      },
-      body: JSON.stringify({ args }),
-    });
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...authHeaders,
+        },
+        body: JSON.stringify({ args }),
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        status: 0,
+        error: {
+          code: "FORGE_NETWORK_ERROR",
+          message: error instanceof Error ? error.message : "network request failed",
+          details: error,
+        },
+      };
+    }
 
     let body: unknown;
     try {
       body = await response.json();
     } catch {
-      throw new ForgeError(\`HTTP \${response.status}\`, {
-        code: "FORGE_HTTP_ERROR",
+      return {
+        ok: false,
         status: response.status,
-      });
+        error: {
+          code: "FORGE_HTTP_ERROR",
+          message: \`HTTP \${response.status}\`,
+        },
+      };
     }
 
     const payload = parseJsonPayload(body);
@@ -331,15 +388,26 @@ class ForgeHttpClient implements ForgeClient {
         payload.error?.message ??
         diagnostic?.message ??
         \`Request failed with status \${response.status}\`;
-      throw new ForgeError(message, {
-        code,
-        traceId: payload.traceId,
+      return {
+        ok: false,
         status: response.status,
-        details: payload.error?.details ?? payload.diagnostics,
-      });
+        traceId: payload.traceId,
+        diagnostics: payload.diagnostics,
+        error: {
+          code,
+          message,
+          details: payload.error?.details ?? payload.diagnostics,
+        },
+      };
     }
 
-    return payload.result;
+    return {
+      ok: true,
+      result: payload.result,
+      status: response.status,
+      traceId: payload.traceId,
+      diagnostics: payload.diagnostics,
+    };
   }
 
   private async invokeExternal(
@@ -524,8 +592,11 @@ export type {
   ForgeReactAuthProvider,
   ForgeReactClient,
   ForgeReactError,
+  ForgeCommandCallResult,
   UseCommandOptions,
   UseCommandResult,
+  UseCommandResultHook,
+  UseCommandResultOptions,
   UseLiveQueryOptions,
   UseLiveQueryResult,
   UseQueryOptions,
@@ -539,6 +610,7 @@ export const useForgeClient = forgeReact.useForgeClient;
 export const useAuth = forgeReact.useAuth;
 export const useQuery = forgeReact.useQuery;
 export const useCommand = forgeReact.useCommand;
+export const useCommandResult = forgeReact.useCommandResult;
 export const useLiveQuery = forgeReact.useLiveQuery;
 `;
 }
@@ -551,8 +623,11 @@ export function renderReactDts(): string {
   ForgeReactAuthProvider,
   ForgeReactClient,
   ForgeReactError,
+  ForgeCommandCallResult,
   UseCommandOptions,
   UseCommandResult,
+  UseCommandResultHook,
+  UseCommandResultOptions,
   UseLiveQueryOptions,
   UseLiveQueryResult,
   UseQueryOptions,
@@ -564,6 +639,7 @@ export declare const useForgeClient: import("forge/react").ForgeReactBindings["u
 export declare const useAuth: import("forge/react").ForgeReactBindings["useAuth"];
 export declare const useQuery: import("forge/react").ForgeReactBindings["useQuery"];
 export declare const useCommand: import("forge/react").ForgeReactBindings["useCommand"];
+export declare const useCommandResult: import("forge/react").ForgeReactBindings["useCommandResult"];
 export declare const useLiveQuery: import("forge/react").ForgeReactBindings["useLiveQuery"];
 `;
 }

package/src/forge/compiler/data-graph/sql/ddl.ts

@@ -102,39 +102,41 @@ function parseFieldType(
   field: DataField,
   tableName: string,
   diagnostics: Diagnostic[],
+  refTables: Map<string, string>,
 ): ParsedFieldType | null {
   const declared = field.type.trim();
   const nullable = declared.endsWith("?");
-  const raw = (nullable ? declared.slice(0, -1) : declared).trim().toLowerCase();
+  const raw = (nullable ? declared.slice(0, -1) : declared).trim();
+  const lowered = raw.toLowerCase();
 
   const withNullability = (parsed: Omit<ParsedFieldType, "nullable">): ParsedFieldType => ({
     ...parsed,
     ...(nullable ? { nullable: true } : {}),
   });
 
-  if (raw === "uuid") {
+  if (lowered === "uuid") {
     return withNullability({ sqlType: "uuid" });
   }
-  if (raw === "text" || raw === "string") {
+  if (lowered === "text" || lowered === "string") {
     return withNullability({ sqlType: "text" });
   }
-  if (raw === "number") {
+  if (lowered === "number") {
     return withNullability({ sqlType: "double precision" });
   }
-  if (raw === "integer" || raw === "int") {
+  if (lowered === "integer" || lowered === "int") {
     return withNullability({ sqlType: "integer" });
   }
-  if (raw === "boolean" || raw === "bool") {
+  if (lowered === "boolean" || lowered === "bool") {
     return withNullability({ sqlType: "boolean" });
   }
-  if (raw === "timestamp" || raw === "timestamptz") {
+  if (lowered === "timestamp" || lowered === "timestamptz") {
     return withNullability({ sqlType: "timestamptz" });
   }
-  if (raw === "json") {
+  if (lowered === "json") {
     return withNullability({ sqlType: "jsonb" });
   }
 
-  if (raw.startsWith("enum:")) {
+  if (lowered.startsWith("enum:")) {
     const values = raw
       .slice("enum:".length)
       .split(",")
@@ -158,11 +160,11 @@ function parseFieldType(
     };
   }
 
-  if (raw.startsWith("enum_")) {
+  if (lowered.startsWith("enum_")) {
     return withNullability({ sqlType: "text" });
   }
 
-  if (raw.startsWith("ref:")) {
+  if (lowered.startsWith("ref:")) {
     const refTable = raw.slice("ref:".length).trim();
     if (!refTable) {
       diagnostics.push(
@@ -174,14 +176,25 @@ function parseFieldType(
       );
       return null;
     }
+    const resolvedRefTable = refTables.get(refTable) ?? refTables.get(toSnakeCase(refTable));
+    if (!resolvedRefTable) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: FORGE_DB_INVALID_SQL_PLAN,
+          message: `unknown ref target '${refTable}' on ${tableName}.${field.name}; expected one of ${[...new Set(refTables.values())].sort().join(", ")}`,
+        }),
+      );
+      return null;
+    }
     return {
       ...(nullable ? { nullable: true } : {}),
       sqlType: "uuid",
-      references: { table: toSnakeCase(refTable), column: "id" },
+      references: { table: resolvedRefTable, column: "id" },
     };
   }
 
-  if (raw === "ref") {
+  if (lowered === "ref") {
     return {
       ...(nullable ? { nullable: true } : {}),
       sqlType: "uuid",
@@ -199,6 +212,18 @@ function parseFieldType(
   return null;
 }
 
+function buildReferenceTableLookup(tables: DataTable[]): Map<string, string> {
+  const lookup = new Map<string, string>();
+  for (const table of tables) {
+    const sqlTableName = toSnakeCase(table.name);
+    lookup.set(table.name, sqlTableName);
+    lookup.set(table.exportName, sqlTableName);
+    lookup.set(sqlTableName, sqlTableName);
+    lookup.set(toSnakeCase(table.exportName), sqlTableName);
+  }
+  return lookup;
+}
+
 function defaultExprForField(field: DataField): string | undefined {
   const name = field.name;
   const type = field.type.trim().replace(/\?$/, "").toLowerCase();
@@ -217,7 +242,11 @@ function defaultExprForField(field: DataField): string | undefined {
   return undefined;
 }
 
-function buildColumns(table: DataTable, diagnostics: Diagnostic[]): ColumnDef[] {
+function buildColumns(
+  table: DataTable,
+  diagnostics: Diagnostic[],
+  refTables: Map<string, string>,
+): ColumnDef[] {
   const columns: ColumnDef[] = [];
   const fields = [...table.fields].sort((a, b) =>
     a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
@@ -236,7 +265,7 @@ function buildColumns(table: DataTable, diagnostics: Diagnostic[]): ColumnDef[]
   }
 
   for (const field of fields) {
-    const parsed = parseFieldType(field, table.name, diagnostics);
+    const parsed = parseFieldType(field, table.name, diagnostics, refTables);
     if (!parsed) {
       continue;
     }
@@ -311,9 +340,13 @@ function buildForeignKeyIndexes(tableName: string, columns: ColumnDef[]): IndexD
   return indexes;
 }
 
-function buildTableChange(table: DataTable, diagnostics: Diagnostic[]): SqlChange | null {
+function buildTableChange(
+  table: DataTable,
+  diagnostics: Diagnostic[],
+  refTables: Map<string, string>,
+): SqlChange | null {
   const tableName = toSnakeCase(table.name);
-  const columns = buildColumns(table, diagnostics);
+  const columns = buildColumns(table, diagnostics, refTables);
 
   if (columns.length === 0) {
     diagnostics.push(
@@ -351,6 +384,7 @@ export function buildSqlPlan(dataGraph: DataGraph): SqlPlan {
   const diagnostics: Diagnostic[] = [];
   const tables: SqlChange[] = [];
   const indexes: SqlChange[] = [];
+  const refTables = buildReferenceTableLookup(dataGraph.tables);
 
   const systemTables: SqlChange[] = [
     {
@@ -406,7 +440,7 @@ export function buildSqlPlan(dataGraph: DataGraph): SqlPlan {
   ];
 
   for (const table of stableSortTables(dataGraph.tables)) {
-    const change = buildTableChange(table, diagnostics);
+    const change = buildTableChange(table, diagnostics, refTables);
     if (!change) {
       continue;
     }

package/src/forge/compiler/package-upgrades/planner.ts

@@ -102,7 +102,62 @@ function readPackageJson(workspaceRoot: string): {
   };
 }
 
-function dependencyType(workspaceRoot: string, packageName: string): "dependency" | "devDependency" {
+type DependencyType = "dependency" | "devDependency";
+
+interface NpmAliasSpec {
+  packageName: string;
+  versionOrRange?: string;
+}
+
+interface PackageResolution {
+  requestedName: string;
+  packageName: string;
+  dependencyName: string;
+  dependencySpec?: string;
+  dependencyType: DependencyType;
+  isNpmAlias: boolean;
+  current: PackageApi;
+}
+
+function parseNpmAliasSpec(spec: string): NpmAliasSpec | null {
+  if (!spec.startsWith("npm:")) {
+    return null;
+  }
+  const target = spec.slice("npm:".length);
+  if (!target) {
+    return null;
+  }
+  const separator =
+    target.startsWith("@")
+      ? target.indexOf("@", target.indexOf("/") + 1)
+      : target.indexOf("@");
+  if (separator === -1) {
+    return { packageName: target };
+  }
+  return {
+    packageName: target.slice(0, separator),
+    versionOrRange: target.slice(separator + 1),
+  };
+}
+
+function dependencyEntries(
+  pkg: ReturnType<typeof readPackageJson>,
+): Array<{ type: DependencyType; name: string; spec: string }> {
+  return [
+    ...Object.entries(pkg.dependencies ?? {}).map(([name, spec]) => ({
+      type: "dependency" as const,
+      name,
+      spec,
+    })),
+    ...Object.entries(pkg.devDependencies ?? {}).map(([name, spec]) => ({
+      type: "devDependency" as const,
+      name,
+      spec,
+    })),
+  ];
+}
+
+function dependencyType(workspaceRoot: string, packageName: string): DependencyType {
   const pkg = readPackageJson(workspaceRoot);
   if (packageName in (pkg.devDependencies ?? {})) {
     return "devDependency";
@@ -110,9 +165,59 @@ function dependencyType(workspaceRoot: string, packageName: string): "dependency
   return "dependency";
 }
 
-function currentPackageApi(workspaceRoot: string, packageName: string): PackageApi | null {
+function resolvePackageForUpgrade(workspaceRoot: string, requestedName: string): PackageResolution | null {
   const graph = readGeneratedJson<PackageGraph>(workspaceRoot, `${GENERATED_DIR}/packageGraph.json`);
-  return graph?.packages.find((pkg) => pkg.name === packageName) ?? null;
+  if (!graph) {
+    return null;
+  }
+  const pkg = readPackageJson(workspaceRoot);
+  const entries = dependencyEntries(pkg);
+
+  const aliasEntry = entries.find((entry) => {
+    const alias = parseNpmAliasSpec(entry.spec);
+    return entry.name === requestedName || alias?.packageName === requestedName;
+  });
+  if (aliasEntry) {
+    const alias = parseNpmAliasSpec(aliasEntry.spec);
+    const packageName = alias?.packageName ?? aliasEntry.name;
+    const current = graph.packages.find((candidate) => candidate.name === packageName);
+    if (current) {
+      return {
+        requestedName,
+        packageName,
+        dependencyName: aliasEntry.name,
+        dependencySpec: aliasEntry.spec,
+        dependencyType: aliasEntry.type,
+        isNpmAlias: Boolean(alias),
+        current,
+      };
+    }
+  }
+
+  const current = graph.packages.find((candidate) => candidate.name === requestedName);
+  if (!current) {
+    return null;
+  }
+  const directEntry = entries.find((entry) => entry.name === requestedName);
+  return {
+    requestedName,
+    packageName: requestedName,
+    dependencyName: requestedName,
+    dependencySpec: directEntry?.spec,
+    dependencyType: directEntry?.type ?? dependencyType(workspaceRoot, requestedName),
+    isNpmAlias: false,
+    current,
+  };
+}
+
+function packageSpecForDependency(
+  resolution: Pick<PackageResolution, "packageName" | "dependencyName" | "isNpmAlias">,
+  version: string,
+): string {
+  if (resolution.isNpmAlias) {
+    return `${resolution.dependencyName}@npm:${resolution.packageName}@${version}`;
+  }
+  return `${resolution.packageName}@${version}`;
 }
 
 function fixtureMetadata(registryDir: string | undefined, packageName: string): {
@@ -348,9 +453,9 @@ export async function createUpgradePlan(
 ): Promise<UpgradePlannerResult> {
   const diagnostics: Diagnostic[] = [];
   const packageManager = detectPackageManager(options.workspaceRoot);
-  const current = currentPackageApi(options.workspaceRoot, options.packageName);
+  const resolution = resolvePackageForUpgrade(options.workspaceRoot, options.packageName);
 
-  if (!current) {
+  if (!resolution) {
     return {
       ok: false,
       diagnostics: [
@@ -363,10 +468,11 @@ export async function createUpgradePlan(
       exitCode: 1,
     };
   }
+  const current = resolution.current;
 
   const targetInfo = await resolveTargetVersion({
     workspaceRoot: options.workspaceRoot,
-    packageName: options.packageName,
+    packageName: resolution.packageName,
     currentVersion: current.version,
     target: options.target,
     registryDir: options.registryDir ?? process.env.FORGE_DEPS_REGISTRY_DIR,
@@ -388,7 +494,7 @@ export async function createUpgradePlan(
 
   const analyzed = await analyzeTargetPackage({
     workspaceRoot: options.workspaceRoot,
-    packageName: options.packageName,
+    packageName: resolution.packageName,
     versionInfo: targetInfo,
     packageManager,
     registryDir: options.registryDir ?? process.env.FORGE_DEPS_REGISTRY_DIR,
@@ -398,7 +504,7 @@ export async function createUpgradePlan(
     return { ok: false, diagnostics, exitCode: 1 };
   }
 
-  const recipe = resolveByPackageName(options.packageName) ?? undefined;
+  const recipe = resolveByPackageName(resolution.packageName) ?? undefined;
   const currentClassified = { api: current, classification: classify(current, recipe), recipe };
   const targetClassified = {
     api: analyzed.api,
@@ -425,7 +531,7 @@ export async function createUpgradePlan(
   }
 
   const affected = analyzeUpgradeImpact({
-    packageName: options.packageName,
+    packageName: resolution.packageName,
     appGraph,
     runtimeGraph,
     queryRegistry,
@@ -436,21 +542,35 @@ export async function createUpgradePlan(
   const bump = semverBump(current.version, analyzed.api.version);
   const risk = buildRiskReport({ bump, apiDiff, runtimeDiff, affected });
   const commands = recommendedCommands(affected);
+  const toInfo = {
+    ...targetInfo,
+    version: analyzed.api.version,
+    spec: packageSpecForDependency(resolution, analyzed.api.version),
+  };
   const planDir = packagePlanDir(
     options.workspaceRoot,
-    options.packageName,
+    resolution.dependencyName,
     current.version,
     analyzed.api.version,
   );
-  const id = `${packageKey(options.packageName)}-${current.version}-to-${analyzed.api.version}`;
+  const id = `${packageKey(resolution.dependencyName)}-${current.version}-to-${analyzed.api.version}`;
   const plan: PackageUpgradePlan = {
     schemaVersion: "0.1.0",
     plannerVersion: GENERATOR_VERSION,
     id,
-    packageName: options.packageName,
+    packageName: resolution.packageName,
+    ...(resolution.requestedName !== resolution.packageName
+      ? { requestedPackageName: resolution.requestedName }
+      : {}),
+    ...(resolution.isNpmAlias ? { dependencyAlias: resolution.dependencyName } : {}),
     ...(recipe?.alias ? { integrationAlias: recipe.alias } : {}),
-    from: { version: current.version, spec: `${options.packageName}@${current.version}` },
-    to: { ...targetInfo, version: analyzed.api.version },
+    from: {
+      version: current.version,
+      spec: resolution.isNpmAlias
+        ? packageSpecForDependency(resolution, current.version)
+        : `${resolution.packageName}@${current.version}`,
+    },
+    to: toInfo,
     packageManager,
     semver: {
       bump,

package/src/forge/compiler/package-upgrades/types.ts

@@ -146,6 +146,8 @@ export interface PackageUpgradePlan {
   plannerVersion: string;
   id: string;
   packageName: string;
+  requestedPackageName?: string;
+  dependencyAlias?: string;
   integrationAlias?: string;
   from: PackageVersionInfo;
   to: PackageVersionInfo;

package/src/forge/dev/server.ts

@@ -333,12 +333,27 @@ function markdownResponse(body: string, status = 200): Response {
 }
 
 function corsPreflight(): Response {
+  const allowedHeaders = [
+    "Authorization",
+    "Content-Type",
+    "WorkOS-Signature",
+    "x-forge-user-id",
+    "x-forge-tenant-id",
+    "x-forge-organization-id",
+    "x-forge-organization-membership-id",
+    "x-forge-role",
+    "x-forge-roles",
+    "x-forge-permissions",
+    "x-forge-claims",
+    "x-forge-auth-kind",
+    "x-forge-trace-id",
+  ];
   return new Response(null, {
     status: 204,
     headers: {
       "Access-Control-Allow-Origin": "*",
       "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-      "Access-Control-Allow-Headers": "Authorization, Content-Type, WorkOS-Signature, x-forge-user-id, x-forge-tenant-id, x-forge-role, x-forge-roles, x-forge-permissions",
+      "Access-Control-Allow-Headers": allowedHeaders.join(", "),
     },
   });
 }

package/src/forge/react/index.ts

@@ -45,6 +45,22 @@ export type ForgeReactError = Error & {
   details?: unknown;
 };
 
+export type ForgeCommandCallResult<T = unknown> =
+  | {
+      ok: true;
+      result: T;
+      status: number;
+      traceId?: string;
+      diagnostics?: { code: string; message: string }[];
+    }
+  | {
+      ok: false;
+      error: { code: string; message: string; details?: unknown };
+      status: number;
+      traceId?: string;
+      diagnostics?: { code: string; message: string }[];
+    };
+
 export type LiveSnapshot<T> = {
   subscriptionId: string;
   revision: number;
@@ -56,6 +72,7 @@ export type ForgeReactClient = {
   lastTraceId?: string;
   query(name: string, args: unknown): Promise<unknown>;
   command(name: string, args: unknown): Promise<unknown>;
+  commandResult?(name: string, args: unknown): Promise<ForgeCommandCallResult<unknown>>;
   liveQuery(
     name: string,
     args: unknown,
@@ -96,6 +113,22 @@ export type UseCommandResult<TArgs, TResult> = {
   reset: () => void;
 };
 
+export type UseCommandResultOptions<TResult> = {
+  onSuccess?: (result: TResult) => void;
+  onError?: (error: ForgeReactError) => void;
+  onSettled?: (result: ForgeCommandCallResult<TResult>) => void;
+};
+
+export type UseCommandResultHook<TArgs, TResult> = {
+  run: (args: TArgs) => Promise<ForgeCommandCallResult<TResult>>;
+  loading: boolean;
+  error: ForgeReactError | null;
+  result: ForgeCommandCallResult<TResult> | undefined;
+  data: TResult | undefined;
+  traceId?: string;
+  reset: () => void;
+};
+
 export type UseLiveQueryOptions = {
   enabled?: boolean;
 };
@@ -123,6 +156,10 @@ export type ForgeReactBindings<TClient extends ForgeReactClient = ForgeReactClie
     name: string,
     options?: UseCommandOptions<TResult>,
   ) => UseCommandResult<TArgs, TResult>;
+  useCommandResult: <TArgs = unknown, TResult = unknown>(
+    name: string,
+    options?: UseCommandResultOptions<TResult>,
+  ) => UseCommandResultHook<TArgs, TResult>;
   useLiveQuery: <TResult = unknown>(
     name: string,
     args: unknown,
@@ -165,6 +202,29 @@ function toForgeError(error: unknown): ForgeReactError {
   return wrapped;
 }
 
+function commandErrorToForgeError(result: Extract<ForgeCommandCallResult, { ok: false }>): ForgeReactError {
+  const error = new Error(result.error.message) as ForgeReactError;
+  error.code = result.error.code;
+  error.status = result.status;
+  error.traceId = result.traceId;
+  error.details = result.error.details ?? result.diagnostics;
+  return error;
+}
+
+function caughtErrorToCommandResult(error: unknown): ForgeCommandCallResult<never> {
+  const forgeError = toForgeError(error);
+  return {
+    ok: false,
+    status: forgeError.status ?? 0,
+    traceId: forgeError.traceId,
+    error: {
+      code: forgeError.code ?? "FORGE_REACT_COMMAND_FAILED",
+      message: forgeError.message,
+      details: forgeError.details,
+    },
+  };
+}
+
 function resolveDevAuth(devAuth: ForgeDevAuthConfig | undefined): ForgeReactAuthProvider | undefined {
   if (!devAuth) {
     return undefined;
@@ -344,6 +404,86 @@ export function createForgeReactBindings<TClient extends ForgeReactClient>(
     };
   }
 
+  function useCommandResult<TArgs = unknown, TResult = unknown>(
+    name: string,
+    options?: UseCommandResultOptions<TResult>,
+  ): UseCommandResultHook<TArgs, TResult> {
+    const client = useForgeClient();
+    const [state, setState] = React.useState<{
+      loading: boolean;
+      error: ForgeReactError | null;
+      result: ForgeCommandCallResult<TResult> | undefined;
+      data: TResult | undefined;
+      traceId?: string;
+    }>({
+      loading: false,
+      error: null,
+      result: undefined,
+      data: undefined,
+    });
+
+    const run = React.useCallback(
+      async (args: TArgs): Promise<ForgeCommandCallResult<TResult>> => {
+        setState((prev) => ({ ...prev, loading: true, error: null }));
+        let result: ForgeCommandCallResult<TResult>;
+        if (typeof client.commandResult === "function") {
+          result = (await client.commandResult(name, args)) as ForgeCommandCallResult<TResult>;
+        } else {
+          try {
+            const data = (await client.command(name, args)) as TResult;
+            result = {
+              ok: true,
+              result: data,
+              status: 200,
+              traceId: client.lastTraceId,
+            };
+          } catch (error) {
+            result = caughtErrorToCommandResult(error);
+          }
+        }
+
+        if (result.ok) {
+          setState({
+            loading: false,
+            error: null,
+            result,
+            data: result.result,
+            traceId: result.traceId ?? client.lastTraceId,
+          });
+          options?.onSuccess?.(result.result);
+        } else {
+          const forgeError = commandErrorToForgeError(result);
+          setState({
+            loading: false,
+            error: forgeError,
+            result,
+            data: undefined,
+            traceId: result.traceId,
+          });
+          options?.onError?.(forgeError);
+        }
+        options?.onSettled?.(result);
+        return result;
+      },
+      [client, name, options?.onError, options?.onSettled, options?.onSuccess],
+    );
+
+    const reset = React.useCallback(() => {
+      setState({
+        loading: false,
+        error: null,
+        result: undefined,
+        data: undefined,
+      });
+    }, []);
+
+    return {
+      ...state,
+      run,
+      reset,
+    };
+  }
+
   function useLiveQuery<TResult = unknown>(
     name: string,
     args: unknown,
@@ -430,6 +570,7 @@ export function createForgeReactBindings<TClient extends ForgeReactClient>(
     useAuth,
     useQuery,
     useCommand,
+    useCommandResult,
     useLiveQuery,
   };
 }

package/src/forge/version.ts

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