forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/forge/compiler/orchestrator/run.ts

@@ -5,6 +5,12 @@ import {
 import type { GenerateOptions, GenerateResult } from "../types/cli.ts";
 import type { Diagnostic } from "../types/diagnostic.ts";
 import { classify } from "../classifier/classify.ts";
+import { getAppGraphProfile } from "../app-graph/profile.ts";
+import {
+  clearSignalProfile,
+  getSignalProfile,
+  resetSignalProfile,
+} from "../classifier/signals.ts";
 import type { ClassifiedPackage } from "../classifier/runtime-matrix.ts";
 import { buildRuntimeMatrix } from "../classifier/runtime-matrix.ts";
 import { emit } from "../emitter/emit.ts";
@@ -25,8 +31,10 @@ import {
   formatCompileTimings,
   isCompileProfileEnabled,
   recordCompileTimings,
+  shouldPrintCompileProfile,
 } from "./profile.ts";
 import { plan } from "./plan.ts";
+import { getPlanProfile } from "./plan-profile.ts";
 import {
   buildAppGraphForSession,
   discoverForSession,
@@ -100,6 +108,7 @@ export async function run(options: GenerateOptions): Promise<GenerateResult> {
 async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
   const profileEnabled = isCompileProfileEnabled();
   const runStarted = profileEnabled ? performance.now() : 0;
+  let fastCheckMs = 0;
   let generateCheckCache: GenerateResult["cache"] =
     options.check && !options.dryRun
       ? {
@@ -110,7 +119,9 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
       : undefined;
 
   if (options.check && !options.dryRun) {
+    const fastCheckStarted = profileEnabled ? performance.now() : 0;
     const fastCheck = runFastGenerateCheck(options.workspaceRoot);
+    fastCheckMs = profileEnabled ? performance.now() - fastCheckStarted : 0;
     if (fastCheck.kind === "hit") {
       return fastCheck.result;
     }
@@ -121,7 +132,9 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
     };
   }
 
+  const sessionStarted = profileEnabled ? performance.now() : 0;
   const session = getCompileSession(options.workspaceRoot);
+  const sessionMs = profileEnabled ? performance.now() - sessionStarted : 0;
 
   const discoverStarted = profileEnabled ? performance.now() : 0;
   const ctx = discoverForSession(session);
@@ -130,20 +143,40 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
 
   const pkgCompiler = new PackageGraphCompiler();
 
-  const graphStarted = profileEnabled ? performance.now() : 0;
-  const [appGraph, pkgResult] = await Promise.all([
-    buildAppGraphForSession(session),
-    pkgCompiler.build(ctx.dependencies, {
+  let appGraphMs = 0;
+  let packageGraphMs = 0;
+  const graphBuildStarted = profileEnabled ? performance.now() : 0;
+  const appGraphPromise = (async () => {
+    const started = profileEnabled ? performance.now() : 0;
+    const graph = await buildAppGraphForSession(session);
+    appGraphMs = profileEnabled ? performance.now() - started : 0;
+    return graph;
+  })();
+  const packageGraphPromise = (async () => {
+    const started = profileEnabled ? performance.now() : 0;
+    const result = await pkgCompiler.build(ctx.dependencies, {
       runtimeInspect: false,
       resolutionMode: "nodenext",
       cacheDir: ctx.cacheDir,
       concurrency: options.concurrency,
       lockfileHash: ctx.lockfileHash,
-    }),
-  ]);
-  const graphMs = profileEnabled ? performance.now() - graphStarted : 0;
+    });
+    packageGraphMs = profileEnabled ? performance.now() - started : 0;
+    return result;
+  })();
+  const [appGraph, pkgResult] = await Promise.all([appGraphPromise, packageGraphPromise]);
+  const graphBuildMs = profileEnabled ? performance.now() - graphBuildStarted : 0;
 
+  const classifyStarted = profileEnabled ? performance.now() : 0;
+  if (profileEnabled) {
+    resetSignalProfile();
+  }
   const classified = classifyPackages(pkgResult.graph);
+  const classifierSignals = profileEnabled ? getSignalProfile() : undefined;
+  if (profileEnabled) {
+    clearSignalProfile();
+  }
+  const classifyMs = profileEnabled ? performance.now() - classifyStarted : 0;
 
   const planStarted = profileEnabled ? performance.now() : 0;
   const emitPlan = plan({
@@ -160,8 +193,13 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
       ? "dry-run"
       : "write";
 
+  const runtimeMatrixStarted = profileEnabled ? performance.now() : 0;
   const matrix = buildRuntimeMatrix(classified);
+  const runtimeMatrixMs = profileEnabled ? performance.now() - runtimeMatrixStarted : 0;
+  const importGuardsStarted = profileEnabled ? performance.now() : 0;
   const guardDiagnostics = checkImportGuards(appGraph.moduleGraph, matrix);
+  const importGuardsMs = profileEnabled ? performance.now() - importGuardsStarted : 0;
+  const qualityGateStarted = profileEnabled ? performance.now() : 0;
   // Import guards fail `forge check`; generate/drift only surface them as warnings.
   const guardDiagnosticsForGate =
     mode === "check"
@@ -176,6 +214,7 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
     pkgResult.diagnostics,
     [...guardDiagnosticsForGate, ...(emitPlan.diagnostics ?? [])],
   );
+  const qualityGateMs = profileEnabled ? performance.now() - qualityGateStarted : 0;
 
   const emitStarted = profileEnabled ? performance.now() : 0;
   const emitResult = await emit(emitPlan, {
@@ -184,6 +223,7 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
   });
   const emitMs = profileEnabled ? performance.now() - emitStarted : 0;
 
+  const postEmitStarted = profileEnabled ? performance.now() : 0;
   const warnings: Diagnostic[] = [
     ...qualityDiagnostics.filter((d) => d.severity === "warning"),
     ...emitResult.warnings,
@@ -214,30 +254,6 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
     }
   }
 
-  if (profileEnabled) {
-    const totalMs = performance.now() - runStarted;
-    recordCompileTimings({
-      discoverMs,
-      appGraphMs: graphMs,
-      packageGraphMs: 0,
-      planMs,
-      emitMs,
-      totalMs,
-    });
-    const fsProfile = getFileSystemProfile();
-    process.stderr.write(`${formatCompileTimings({
-      discoverMs,
-      appGraphMs: graphMs,
-      packageGraphMs: 0,
-      planMs,
-      emitMs,
-      totalMs,
-    })}\n`);
-    if (fsProfile) {
-      process.stderr.write(`${formatFileSystemProfile(fsProfile)}\n`);
-    }
-  }
-
   const driftFailure =
     options.check &&
     (emitResult.changed.length > 0 ||
@@ -257,6 +273,56 @@ async function runUnlocked(options: GenerateOptions): Promise<GenerateResult> {
   const unchanged = emitResult.unchanged.filter((path) =>
     plannedPaths.has(path),
   );
+  const postEmitMs = profileEnabled ? performance.now() - postEmitStarted : 0;
+
+  if (profileEnabled) {
+    const totalMs = performance.now() - runStarted;
+    const appGraphProfile = getAppGraphProfile(appGraph);
+    const planProfile = getPlanProfile(emitPlan);
+    const unaccountedMs = Math.max(
+      0,
+      totalMs -
+        fastCheckMs -
+        sessionMs -
+        discoverMs -
+        graphBuildMs -
+        classifyMs -
+        planMs -
+        runtimeMatrixMs -
+        importGuardsMs -
+        qualityGateMs -
+        emitMs -
+        postEmitMs,
+    );
+    const timings = {
+      fastCheckMs,
+      sessionMs,
+      discoverMs,
+      graphBuildMs,
+      appGraphMs,
+      ...(appGraphProfile ? { appGraph: appGraphProfile } : {}),
+      packageGraphMs,
+      classifyMs,
+      ...(classifierSignals ? { classifierSignals } : {}),
+      planMs,
+      ...(planProfile ? { planDetail: planProfile } : {}),
+      runtimeMatrixMs,
+      importGuardsMs,
+      qualityGateMs,
+      emitMs,
+      postEmitMs,
+      unaccountedMs,
+      totalMs,
+    };
+    recordCompileTimings(timings);
+    const fsProfile = getFileSystemProfile();
+    if (shouldPrintCompileProfile()) {
+      process.stderr.write(`${formatCompileTimings(timings)}\n`);
+      if (fsProfile) {
+        process.stderr.write(`${formatFileSystemProfile(fsProfile)}\n`);
+      }
+    }
+  }
 
   return {
     changed,

package/src/forge/compiler/orchestrator/serialize.ts

@@ -86,6 +86,14 @@ function moduleGraphForAppGraphSnapshot(graph: AppGraph): AppGraph["moduleGraph"
   };
 }
 
+export function serializeConstFromJson(
+  exportName: string,
+  serializedJson: string,
+): string {
+  const parsed: unknown = JSON.parse(serializedJson.trimEnd());
+  return `export const ${exportName} = ${JSON.stringify(parsed, null, 2)} as const;\n`;
+}
+
 export function serializeAppGraphJson(graph: AppGraph): string {
   const payload = {
     schemaVersion: graph.schemaVersion,
@@ -100,26 +108,35 @@ export function serializeAppGraphJson(graph: AppGraph): string {
 }
 
 export function serializeAppGraphTs(graph: AppGraph): string {
-  const parsed: unknown = JSON.parse(serializeAppGraphJson(graph).trimEnd());
-  return `export const appGraph = ${JSON.stringify(parsed, null, 2)} as const;\n`;
+  return serializeConstFromJson("appGraph", serializeAppGraphJson(graph));
 }
 
 export function serializePackageGraphJson(graph: PackageGraph): string {
   return serializeCanonical(graph);
 }
 
-export function serializePackageGraphTs(graph: PackageGraph): string {
-  const parsed: unknown = JSON.parse(serializePackageGraphJson(graph).trimEnd());
-  return `export const packageGraph = ${JSON.stringify(parsed, null, 2)} as const;\n`;
+export function serializePackageGraphTs(_graph: PackageGraph): string {
+  return [
+    "import packageGraphJson from \"./packageGraph.json\" with { type: \"json\" };",
+    "",
+    "export type PackageGraph = typeof packageGraphJson;",
+    "export const packageGraph = packageGraphJson;",
+    "",
+  ].join("\n");
 }
 
 export function serializeRuntimeMatrixJson(matrix: RuntimeMatrix): string {
   return serializeCanonical(matrix);
 }
 
-export function serializeRuntimeMatrixTs(matrix: RuntimeMatrix): string {
-  const parsed: unknown = JSON.parse(serializeRuntimeMatrixJson(matrix).trimEnd());
-  return `export const runtimeMatrix = ${JSON.stringify(parsed, null, 2)} as const;\n`;
+export function serializeRuntimeMatrixTs(_matrix: RuntimeMatrix): string {
+  return [
+    "import runtimeMatrixJson from \"./runtimeMatrix.json\" with { type: \"json\" };",
+    "",
+    "export type RuntimeMatrix = typeof runtimeMatrixJson;",
+    "export const runtimeMatrix = runtimeMatrixJson;",
+    "",
+  ].join("\n");
 }
 
 export function serializeImportGuardsJson(
@@ -890,6 +907,7 @@ export function serializeSubscriptionManifestTs(
 }
 
 export function serializeApiJson(surface: ApiSurface): string {
+  const external = surface.external ?? { services: {}, commands: {}, queries: {} };
   return serializeCanonical({
     schemaVersion: surface.schemaVersion,
     generatorVersion: surface.generatorVersion,
@@ -899,6 +917,7 @@ export function serializeApiJson(surface: ApiSurface): string {
     liveQueries: surface.liveQueries,
     actions: surface.actions,
     workflows: surface.workflows,
+    external,
   });
 }
 
@@ -933,6 +952,12 @@ export function serializeReactManifestJson(
   return serializeCanonical(manifest);
 }
 
+export function serializeVueManifestJson(
+  manifest: import("../client-sdk/build-manifest.ts").VueManifest,
+): string {
+  return serializeCanonical(manifest);
+}
+
 export function serializeTestGraphJson(graph: TestGraph): string {
   return serializeCanonical(graph);
 }

package/src/forge/compiler/orchestrator/types.ts

@@ -3,7 +3,7 @@ import type { Dependency } from "../types/package-graph.ts";
 import type { PackageManager } from "../types/runtime.ts";
 import type { SourceFileIndex } from "./workspace-index.ts";
 
-export const ORCHESTRATOR_MANIFEST_VERSION = "1";
+export const ORCHESTRATOR_MANIFEST_VERSION = "2";
 
 export interface DiscoverContext {
   workspaceRoot: string;

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-manager/adapter.ts

@@ -83,7 +83,10 @@ async function runInstall(
   executor: CommandExecutor,
 ): Promise<PmAddResult> {
   const ignoreScripts = opts.ignoreScripts ?? true;
-  const argv = buildAddCommand(pm, spec, { ignoreScripts });
+  const argv = buildAddCommand(pm, spec, {
+    ignoreScripts,
+    workspace: opts.workspace,
+  });
   const lockBefore = hashLockfiles(opts.cwd, pm);
 
   const result = await executor.run(argv, { cwd: opts.cwd });

package/src/forge/compiler/package-manager/commands.ts

@@ -2,6 +2,7 @@ import type { PackageManager } from "../types/runtime.ts";
 
 export interface BuildAddCommandOptions {
   ignoreScripts: boolean;
+  workspace?: string;
 }
 
 /**
@@ -27,6 +28,9 @@ export function buildAddCommand(
       if (ignoreScripts) {
         args.push("--ignore-scripts");
       }
+      if (options.workspace) {
+        args.push("--workspace", options.workspace);
+      }
       return args;
     }
     case "pnpm": {

package/src/forge/compiler/package-manager/executor.ts

@@ -88,11 +88,40 @@ export class PackageManagerCommandError extends Error {
   }
 }
 
+function quoteWindowsShellArg(arg: string): string {
+  if (/^[a-zA-Z0-9@._/:=-]+$/.test(arg)) {
+    return arg;
+  }
+  return `"${arg.replace(/(["^&|<>])/g, "^$1")}"`;
+}
+
+function spawnArgvForWindowsScript(originalArgv: string[], resolvedArgv: string[]): string[] {
+  const originalCommand = originalArgv[0] ?? resolvedArgv[0]!;
+  const command =
+    originalCommand.includes("\\") ||
+    originalCommand.includes("/") ||
+    isAbsolute(originalCommand)
+      ? resolvedArgv[0]!
+      : originalCommand;
+  const commandPart = command === originalCommand ? command : quoteWindowsShellArg(command);
+  const args = originalArgv.slice(1).map(quoteWindowsShellArg).join(" ");
+  return [
+    process.env.ComSpec ?? "cmd.exe",
+    "/d",
+    "/c",
+    `${commandPart}${args ? ` ${args}` : ""}`,
+  ];
+}
+
 export const defaultCommandExecutor: CommandExecutor = {
   async run(argv, options) {
     const resolvedArgv = resolvePackageManagerArgv(argv);
+    const spawnArgv =
+      process.platform === "win32" && /\.(?:cmd|bat)$/i.test(resolvedArgv[0] ?? "")
+        ? spawnArgvForWindowsScript(argv, resolvedArgv)
+        : resolvedArgv;
     return new Promise<CommandRunResult>((resolve, reject) => {
-      const child = spawn(resolvedArgv[0]!, resolvedArgv.slice(1), {
+      const child = spawn(spawnArgv[0]!, spawnArgv.slice(1), {
         cwd: options.cwd,
         env: options.env ?? process.env,
         windowsHide: true,

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;