forgeos 0.1.0-alpha.35 → 0.1.0-alpha.37

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.35 input=a41a4935f71e0376ad8546906f6e5bd7c01f6e033fc3aba669f636ad528e9881 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.37 input=055c7d65fca3d6d8b05af2899c233ff69d377edf0f46f719e2d164ee0574309a content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # forgeos
 
+## 0.1.0-alpha.37
+
+### Patch Changes
+
+- Fix `forge deps upgrade-plan` for npm alias installs used by ForgeOS apps.
+
+  - Record the real package name from package metadata in the generated package graph when a dependency is installed through an alias such as `forge: npm:forgeos@...`.
+  - Resolve upgrade plans by either the real package name (`forgeos`) or the dependency alias (`forge`) while preserving install specs like `forge@npm:forgeos@0.1.0-alpha.37`.
+  - Avoid attempting to resolve the unrelated public `forge@alpha` package when an app asks to upgrade its ForgeOS alias dependency.
+  - Add regression coverage for aliased package graph entries where the import name and real npm package name differ.
+
+## 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

package/docs/changelog.md

@@ -6,6 +6,35 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.37
+
+- Fixed `forge deps upgrade-plan` for npm alias installs used by ForgeOS apps.
+- Recorded the real package name from package metadata in generated package
+  graph entries when a dependency is installed through an alias such as
+  `forge: npm:forgeos@...`.
+- Resolved upgrade plans by either the real package name (`forgeos`) or the
+  dependency alias (`forge`) while preserving install specs like
+  `forge@npm:forgeos@0.1.0-alpha.37`.
+- Avoided attempting to resolve the unrelated public `forge@alpha` package when
+  an app asks to upgrade its ForgeOS alias dependency.
+- Added regression coverage for aliased package graph entries where the import
+  name and real npm package name differ.
+
+## 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

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.35 input=a41a4935f71e0376ad8546906f6e5bd7c01f6e033fc3aba669f636ad528e9881 content=55c7152fe779387c1acecdd5901f3a8affd1cfc9de8ef40b1c8883e083ebfa8a
+// @forge-generated generator=0.1.0-alpha.37 input=055c7d65fca3d6d8b05af2899c233ff69d377edf0f46f719e2d164ee0574309a content=1e26c5249853569091c1b295aab06bd2b9546462328fe8126eda099222430b61
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.35",
-  "releaseId": "forgeos@0.1.0-alpha.35+unknown",
+  "packageVersion": "0.1.0-alpha.37",
+  "releaseId": "forgeos@0.1.0-alpha.37+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/deps.ts

@@ -93,7 +93,9 @@ function findPackage(workspaceRoot: string, packageName: string): {
   const lock = nodeFileSystem.exists(join(workspaceRoot, "forge.lock"))
     ? (JSON.parse((nodeFileSystem.readText(join(workspaceRoot, "forge.lock")) ?? "")) as ForgeLock)
     : null;
-  const pkg = graph?.packages.find((candidate) => candidate.name === packageName);
+  const pkg = graph?.packages.find((candidate) =>
+    candidate.name === packageName || candidate.packageName === packageName
+  );
   return { graph, pkg, lock };
 }
 

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/package-graph/compiler.ts

@@ -271,6 +271,7 @@ export class PackageGraphCompiler {
 
     const partialApi = {
       name: dep.name,
+      ...(packageJson.name && packageJson.name !== dep.name ? { packageName: packageJson.name } : {}),
       version: dep.version,
       packageManager: dep.packageManager,
       resolutionMode: opts.resolutionMode,
@@ -454,10 +455,11 @@ function portableDtsPath(dtsPath: string, dep: Pick<Dependency, "installPath" |
 }
 
 function readPackageJson(installPath: string): {
+  name?: string;
   exports?: unknown;
 } {
   const raw = readTextFile(join(installPath, "package.json"));
-  return JSON.parse(raw) as { exports?: unknown };
+  return JSON.parse(raw) as { name?: string; exports?: unknown };
 }
 
 function resolveSandboxBackend(

package/src/forge/compiler/package-graph/constants.ts

@@ -1,4 +1,4 @@
 export const PACKAGE_GRAPH_SCHEMA_VERSION = "1.0.0";
-export const PACKAGE_ANALYZER_VERSION = "0.2.0";
+export const PACKAGE_ANALYZER_VERSION = "0.2.1";
 export { GENERATOR_VERSION } from "../../version.ts";
 export const DEFAULT_PATTERN_EXPANSION_LIMIT = 50;

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

@@ -102,17 +102,138 @@ 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 matchesPackageName(candidate: PackageApi, packageName: string): boolean {
+  return candidate.name === packageName || candidate.packageName === packageName;
+}
+
+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";
   }
+  for (const entry of dependencyEntries(pkg)) {
+    const alias = parseNpmAliasSpec(entry.spec);
+    if (alias?.packageName === packageName) {
+      return entry.type;
+    }
+  }
   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) => matchesPackageName(candidate, packageName)) ??
+      graph.packages.find((candidate) => candidate.name === aliasEntry.name);
+    if (current) {
+      return {
+        requestedName,
+        packageName,
+        dependencyName: aliasEntry.name,
+        dependencySpec: aliasEntry.spec,
+        dependencyType: aliasEntry.type,
+        isNpmAlias: Boolean(alias),
+        current,
+      };
+    }
+  }
+
+  const current = graph.packages.find((candidate) => matchesPackageName(candidate, requestedName));
+  if (!current) {
+    return null;
+  }
+  const directEntry = entries.find((entry) => {
+    const alias = parseNpmAliasSpec(entry.spec);
+    return entry.name === requestedName || alias?.packageName === requestedName;
+  });
+  const alias = directEntry ? parseNpmAliasSpec(directEntry.spec) : null;
+  const packageName = alias?.packageName ?? current.packageName ?? requestedName;
+  return {
+    requestedName,
+    packageName,
+    dependencyName: directEntry?.name ?? requestedName,
+    dependencySpec: directEntry?.spec,
+    dependencyType: directEntry?.type ?? dependencyType(workspaceRoot, requestedName),
+    isNpmAlias: Boolean(alias),
+    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 +469,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 +484,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 +510,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 +520,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 +547,7 @@ export async function createUpgradePlan(
   }
 
   const affected = analyzeUpgradeImpact({
-    packageName: options.packageName,
+    packageName: resolution.packageName,
     appGraph,
     runtimeGraph,
     queryRegistry,
@@ -436,21 +558,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,
@@ -512,18 +648,19 @@ export function listOutdatedFromFixture(options: {
 
   return graph.packages
     .flatMap((pkg) => {
-      const metadata = fixtureMetadata(registryDir, pkg.name);
+      const packageName = pkg.packageName ?? pkg.name;
+      const metadata = fixtureMetadata(registryDir, packageName);
       const latest = metadata?.["dist-tags"]?.latest;
       if (!latest || latest === pkg.version) {
         return [];
       }
-      const recipe = resolveByPackageName(pkg.name);
+      const recipe = resolveByPackageName(packageName);
       return [{
-        name: pkg.name,
+        name: packageName,
         current: pkg.version,
         wanted: latest,
         latest,
-        type: dependencyType(options.workspaceRoot, pkg.name),
+        type: dependencyType(options.workspaceRoot, packageName),
         managedByRecipe: Boolean(recipe),
         ...(recipe?.alias ? { recipe: recipe.alias } : {}),
       }];

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/compiler/types/package-graph.ts

@@ -92,7 +92,13 @@ export interface Entrypoint {
 }
 
 export interface PackageApi {
+  /**
+   * Import/dependency name used by the app, which may be an npm alias such as
+   * "forge" for "npm:forgeos@...".
+   */
   name: string;
+  /** Real package.json name when it differs from the dependency/import name. */
+  packageName?: string;
   version: string;
   packageManager: PackageManager;
   resolutionMode: ResolutionMode;

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.35";
+export const FORGEOS_VERSION = "0.1.0-alpha.37";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;