@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.1

package/src/cloudflare/artifacts.ts

@@ -1,9 +1,11 @@
 import path from 'node:path';
 import { fs as fse } from '@modern-js/utils';
-import type {
-  CloudflareWorkerArtifactConfig,
-  CloudflareWorkerPublicAssetConfig,
-} from '../config';
+import type { CloudflareWorkerArtifactConfig } from '../config';
+import {
+  CLOUDFLARE_PUBLIC_ASSET_SCOPE,
+  normalizeDeclaredPublicAssets,
+  stageDeclaredPublicAssets,
+} from '../deploy-output/public-assets';
 import {
   RESERVED_ARTIFACT_DESTINATION_DIRECTORIES,
   RESERVED_ARTIFACT_DESTINATION_FILES,
@@ -54,34 +56,12 @@ export const getCloudflareArtifacts = (modernConfig: CloudflareModernConfig) =>
     normalizeCloudflareArtifact,
   );
 
-const normalizeCloudflarePublicAsset = (
-  asset: CloudflareWorkerPublicAssetConfig,
-  index: number,
-) => {
-  const from = normalizeRelativePath(
-    asset.from,
-    `deploy.worker.publicAssets[${index}].from`,
-    'app root',
-  );
-  const to = normalizeRelativePath(
-    asset.to,
-    `deploy.worker.publicAssets[${index}].to`,
-    'Cloudflare public output',
-    { allowRoot: true },
-  );
-
-  return {
-    from,
-    to,
-    index,
-  };
-};
-
 export const getCloudflarePublicAssets = (
   modernConfig: CloudflareModernConfig,
 ) =>
-  (modernConfig.deploy?.worker?.publicAssets ?? []).map(
-    normalizeCloudflarePublicAsset,
+  normalizeDeclaredPublicAssets(
+    modernConfig.deploy?.worker?.publicAssets,
+    CLOUDFLARE_PUBLIC_ASSET_SCOPE,
   );
 
 export const copyCloudflareArtifacts = async (
@@ -102,23 +82,22 @@ export const copyCloudflareArtifacts = async (
   }
 };
 
+/**
+ * Stage `deploy.worker.publicAssets` into Worker Static Assets.
+ *
+ * @returns the staged files relative to the Cloudflare output root.
+ */
 export const copyCloudflarePublicAssets = async (
   appDirectory: string,
-  publicDirectory: string,
+  outputDirectory: string,
   publicAssets: ReturnType<typeof getCloudflarePublicAssets>,
-) => {
-  for (const asset of publicAssets) {
-    const sourcePath = path.join(appDirectory, asset.from);
-
-    if (!(await fse.pathExists(sourcePath))) {
-      throw new Error(
-        `deploy.worker.publicAssets[${asset.index}].from does not exist: ${asset.from}`,
-      );
-    }
-
-    await fse.copy(sourcePath, path.join(publicDirectory, asset.to));
-  }
-};
+) =>
+  stageDeclaredPublicAssets({
+    appDirectory,
+    outputDirectory,
+    assets: publicAssets,
+    scope: CLOUDFLARE_PUBLIC_ASSET_SCOPE,
+  });
 
 export const copyCloudflareD1Migrations = async (
   appDirectory: string,

package/src/cloudflare/delivery-unit.ts

@@ -1,26 +1,79 @@
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import {
+  assertRendererProfileCompatibility,
+  assertUltramodernBuildArtifact,
   type DeliveryUnitIdentity,
-  isUltramodernBuildArtifact,
+  formatBackendFederationValidationErrors,
+  immutableRendererRouterBindings,
   nonEmptyString,
+  type RendererIdentity,
+  type RendererProfile,
+  type RendererRouterBindings,
   toDeliveryUnitIdentity,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
   ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  validateRendererIdentity,
+  validateRendererProfile,
+  validateRendererRouterBindings,
 } from '@modern-js/backend-federation-contracts';
 import { fs as fse } from '@modern-js/utils';
 import { resolveUltramodernReleaseIdentity } from '../release-identity';
 import { isRecord } from './utils';
 
-const COMPACT_CONFIG_PATH = '.modernjs/ultramodern.json';
+const TOPOLOGY_PATH = 'topology/reference-topology.json';
 
 export type DeliveryUnitStamp = DeliveryUnitIdentity & {
   surfaces: {
-    ui?: DeliveryUnitIdentity & { surface: 'ui' };
+    ui?: DeliveryUnitIdentity & {
+      surface: 'ui';
+      rendererIdentity: RendererIdentity;
+      rendererProfile: RendererProfile;
+      routerBindings: RendererRouterBindings;
+    };
     api?: DeliveryUnitIdentity & { surface: 'api' };
   };
 };
 
-type CompactAppResolution = {
+/**
+ * The topology's declaration of one delivery unit. A UI surface may omit the
+ * renderer projection entirely (a React workspace authored before renderer
+ * selection); the build then resolves its renderer identity from the app
+ * config alone, and there is no declared projection to verify it against.
+ */
+export type TopologyUiSurface = DeliveryUnitIdentity & { surface: 'ui' } & (
+    | {
+        rendererIdentity: RendererIdentity;
+        rendererProfile: RendererProfile;
+        routerBindings: RendererRouterBindings;
+      }
+    | {
+        rendererIdentity?: undefined;
+        rendererProfile?: undefined;
+        routerBindings?: undefined;
+      }
+  );
+
+export type TopologyDeliveryUnit = DeliveryUnitIdentity & {
+  /** The declaring topology app. */
+  appId: string;
+  surfaces: {
+    ui?: TopologyUiSurface;
+    api?: DeliveryUnitIdentity & { surface: 'api' };
+  };
+};
+
+const RENDERER_PROJECTION_FIELDS = [
+  'renderer',
+  'rendererIdentity',
+  'rendererIdentities',
+  'rendererProfile',
+  'routerBindings',
+] as const;
+
+type TopologyAppResolution = {
   app?: Record<string, unknown>;
+  role: 'microvertical' | 'shell';
   workspaceRoot: string;
 };
 
@@ -30,7 +83,7 @@ const findWorkspaceRoot = async (
   let current = path.resolve(appDirectory);
 
   for (;;) {
-    if (await fse.pathExists(path.join(current, COMPACT_CONFIG_PATH))) {
+    if (await fse.pathExists(path.join(current, TOPOLOGY_PATH))) {
       return current;
     }
 
@@ -60,34 +113,32 @@ const stampReleaseIdentity = (
   };
 };
 
-const resolveCompactApp = async (
+const resolveTopologyApp = async (
   appDirectory: string,
-): Promise<CompactAppResolution | undefined> => {
+): Promise<TopologyAppResolution | undefined> => {
   const workspaceRoot = await findWorkspaceRoot(appDirectory);
   if (!workspaceRoot) {
     return undefined;
   }
 
-  let compactConfig: unknown;
-  try {
-    compactConfig = await fse.readJSON(
-      path.join(workspaceRoot, COMPACT_CONFIG_PATH),
+  const topology: unknown = await fse.readJSON(
+    path.join(workspaceRoot, TOPOLOGY_PATH),
+  );
+  if (
+    !isRecord(topology) ||
+    !isRecord(topology.shell) ||
+    !Array.isArray(topology.verticals) ||
+    (topology.shells !== undefined && !Array.isArray(topology.shells))
+  ) {
+    throw new Error(
+      '[cloudflare-delivery-unit] Invalid declared reference topology.',
     );
-  } catch {
-    return { workspaceRoot };
-  }
-
-  if (!isRecord(compactConfig)) {
-    return { workspaceRoot };
-  }
-
-  const topology = isRecord(compactConfig.topology)
-    ? compactConfig.topology
-    : undefined;
-  const apps = Array.isArray(topology?.apps) ? topology.apps : undefined;
-  if (!apps) {
-    return { app: compactConfig, workspaceRoot };
   }
+  const apps = [
+    topology.shell,
+    ...topology.verticals,
+    ...(Array.isArray(topology.shells) ? topology.shells : []),
+  ];
 
   const resolvedAppDirectory = path.resolve(appDirectory);
   const app = apps.find(candidate => {
@@ -101,24 +152,122 @@ const resolveCompactApp = async (
         resolvedAppDirectory
     );
   });
+  if (!isRecord(app)) {
+    throw new Error(
+      `[cloudflare-delivery-unit] ${appDirectory} is missing from the declared reference topology.`,
+    );
+  }
   return {
-    ...(isRecord(app) ? { app } : {}),
+    app,
+    role:
+      app === topology.shell ||
+      (Array.isArray(topology.shells) && topology.shells.includes(app))
+        ? 'shell'
+        : 'microvertical',
     workspaceRoot,
   };
 };
 
-const createDeliveryUnitStamp = (
+/** Resolve the producer role from this app's authoritative topology membership. */
+export const resolveTopologyReleaseRole = async (
+  appDirectory: string,
+): Promise<'microvertical' | 'shell' | undefined> => {
+  const resolved = await resolveTopologyApp(appDirectory);
+  if (!resolved?.app) return undefined;
+  const kind = resolved.role === 'shell' ? 'shell' : 'vertical';
+  if (resolved.app.kind !== kind) {
+    throw new Error(
+      '[cloudflare-delivery-unit] Declared app kind disagrees with its topology membership.',
+    );
+  }
+  return resolved.role;
+};
+
+const createTopologyDeliveryUnitStamp = (
   identity: DeliveryUnitIdentity,
-  app?: Record<string, unknown>,
-): DeliveryUnitStamp => {
-  const surfaceProfile = nonEmptyString(app?.surfaceProfile);
+  app: Record<string, unknown>,
+): TopologyDeliveryUnit => {
+  const surfaceProfile = nonEmptyString(app.surfaceProfile);
+  if (
+    surfaceProfile !== undefined &&
+    !['api-only', 'ui-only', 'full-stack'].includes(surfaceProfile)
+  ) {
+    throw new Error(
+      '[cloudflare-delivery-unit] Declared app has an invalid surface profile.',
+    );
+  }
   const emitsUi = surfaceProfile !== 'api-only';
   const emitsApi = surfaceProfile !== 'ui-only';
+  const appId = nonEmptyString(app.id);
+  if (!appId)
+    throw new Error('[cloudflare-delivery-unit] Declared app requires an id.');
+  let ui: TopologyUiSurface | undefined;
+  if (emitsUi) {
+    if (RENDERER_PROJECTION_FIELDS.every(field => !Object.hasOwn(app, field))) {
+      ui = { ...identity, surface: 'ui' };
+    } else {
+      const routerBindings = isRecord(app.routerBindings)
+        ? app.routerBindings
+        : {};
+      const errors = [
+        ...validateRendererIdentity(app.rendererIdentity).errors,
+        ...validateRendererProfile(app.rendererProfile).errors,
+        ...validateRendererRouterBindings(
+          app.routerBindings,
+          Object.keys(routerBindings),
+          'routerBindings',
+        ).errors,
+      ];
+      if (errors.length) {
+        throw new Error(
+          `[cloudflare-delivery-unit] ${formatBackendFederationValidationErrors(errors)}`,
+        );
+      }
+      const rendererIdentity = app.rendererIdentity as RendererIdentity;
+      const rendererProfile = app.rendererProfile as RendererProfile;
+      if (!Object.hasOwn(routerBindings, rendererIdentity.entryName))
+        throw new Error(
+          '[cloudflare-delivery-unit] Topology routerBindings must include the primary renderer identity entry.',
+        );
+      const declaredIdentity = toDeliveryUnitIdentity(app.deliveryUnit);
+      if (
+        rendererIdentity.renderer !== app.renderer ||
+        rendererIdentity.renderer !== rendererProfile.renderer ||
+        rendererIdentity.appId !== app.id ||
+        rendererIdentity.buildId !== declaredIdentity?.buildMarker
+      ) {
+        throw new Error(
+          '[cloudflare-delivery-unit] Topology UI renderer metadata must match its app and delivery-unit identity.',
+        );
+      }
+      ui = {
+        ...identity,
+        surface: 'ui',
+        rendererIdentity: {
+          ...rendererIdentity,
+          buildId: identity.buildMarker,
+        },
+        rendererProfile,
+        routerBindings: immutableRendererRouterBindings(
+          routerBindings as RendererRouterBindings,
+        ),
+      };
+    }
+  } else if (
+    app.rendererIdentity !== undefined ||
+    app.rendererProfile !== undefined ||
+    app.routerBindings !== undefined
+  ) {
+    throw new Error(
+      '[cloudflare-delivery-unit] API-only topology must not declare a UI renderer identity or profile.',
+    );
+  }
 
   return {
     ...identity,
+    appId,
     surfaces: {
-      ...(emitsUi ? { ui: { ...identity, surface: 'ui' as const } } : {}),
+      ...(ui ? { ui } : {}),
       ...(emitsApi ? { api: { ...identity, surface: 'api' as const } } : {}),
     },
   };
@@ -126,53 +275,127 @@ const createDeliveryUnitStamp = (
 
 /**
  * Resolve the delivery-unit record declared for this app by the workspace
- * compact config (`.modernjs/ultramodern.json`). This is the topology source
+ * reference topology. This is the topology source
  * of truth the Cloudflare worker snapshot is verified against.
  */
 export const resolveTopologyDeliveryUnit = async (
   appDirectory: string,
-): Promise<DeliveryUnitStamp | undefined> => {
-  const resolved = await resolveCompactApp(appDirectory);
+): Promise<TopologyDeliveryUnit | undefined> => {
+  const resolved = await resolveTopologyApp(appDirectory);
   if (!resolved?.app) {
     return undefined;
   }
   const identity = toDeliveryUnitIdentity(resolved.app.deliveryUnit);
-  return identity
-    ? createDeliveryUnitStamp(
-        stampReleaseIdentity(identity, resolved.workspaceRoot),
-        resolved.app,
-      )
-    : undefined;
+  if (!identity) {
+    throw new Error(
+      '[cloudflare-delivery-unit] Declared app is missing a valid delivery-unit identity.',
+    );
+  }
+  return createTopologyDeliveryUnitStamp(
+    stampReleaseIdentity(identity, resolved.workspaceRoot),
+    resolved.app,
+  );
 };
 
 /**
- * Resolve the delivery-unit identity actually bundled into the worker by
- * reading the generated `shared/ultramodern-build.json` artifact. This is the
- * worker snapshot / declared surface source that gets stamped into the manifest.
+ * Preserve the finalized build artifact already stamped from renderer-build.json.
+ * The generation artifact cannot attest the compiled application.
  */
 export const resolveWorkerDeliveryUnitStamp = async (
   appDirectory: string,
+  distDirectory: string,
 ): Promise<DeliveryUnitStamp | undefined> => {
   const buildArtifactPath = path.join(
-    appDirectory,
-    ULTRAMODERN_BUILD_ARTIFACT_PATH,
+    distDirectory,
+    ULTRAMODERN_BUILD_ARTIFACT_FILE,
   );
-  let identity: DeliveryUnitIdentity | undefined;
-
-  if (await fse.pathExists(buildArtifactPath)) {
-    const artifact = await fse.readJSON(buildArtifactPath);
-    if (!isUltramodernBuildArtifact(artifact)) {
-      return undefined;
-    }
-    identity = toDeliveryUnitIdentity(artifact.deliveryUnit);
-  }
-
-  if (!identity) {
+  if (!(await fse.pathExists(buildArtifactPath))) {
+    if (
+      await fse.pathExists(
+        path.join(appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH),
+      )
+    )
+      throw new Error(
+        '[cloudflare-delivery-unit] Finalized build artifact is required before worker output stamping.',
+      );
     return undefined;
   }
-  const resolved = await resolveCompactApp(appDirectory);
-  if (resolved) {
-    identity = stampReleaseIdentity(identity, resolved.workspaceRoot);
+  const artifact: unknown = await fse.readJSON(buildArtifactPath);
+  assertUltramodernBuildArtifact(artifact);
+  const identity: DeliveryUnitIdentity = {
+    unitId: artifact.deliveryUnit.unitId,
+    buildMarker: artifact.deliveryUnit.buildMarker,
+    sourceRevision: artifact.deliveryUnit.sourceRevision,
+  };
+  const resolved = await resolveTopologyApp(appDirectory);
+  const stampedArtifact = artifact;
+  let emitsApi = true;
+  if (resolved?.app) {
+    if (stampedArtifact.deliveryUnit.appId !== resolved.app.id) {
+      throw new Error(
+        '[cloudflare-delivery-unit] Build artifact appId must match the declared topology app.',
+      );
+    }
+    const declaredIdentity = toDeliveryUnitIdentity(resolved.app.deliveryUnit);
+    if (!declaredIdentity) {
+      throw new Error(
+        '[cloudflare-delivery-unit] Declared app is missing a valid delivery-unit identity.',
+      );
+    }
+    const expected = createTopologyDeliveryUnitStamp(identity, resolved.app);
+    for (const field of ['unitId'] as const) {
+      if (declaredIdentity[field] !== identity[field]) {
+        throw new Error(
+          `[cloudflare-delivery-unit] Build artifact ${field} must match the declared topology delivery-unit identity.`,
+        );
+      }
+    }
+    const ui = stampedArtifact.surfaces.ui;
+    if (Boolean(expected.surfaces.ui) !== Boolean(ui)) {
+      throw new Error(
+        '[cloudflare-delivery-unit] Build artifact UI surface must match the declared topology surface profile.',
+      );
+    }
+    if (expected.surfaces.ui?.rendererIdentity && ui) {
+      if (
+        !isDeepStrictEqual(
+          expected.surfaces.ui.routerBindings,
+          ui.routerBindings,
+        )
+      )
+        throw new Error(
+          '[cloudflare-delivery-unit] Finalized build routerBindings must match the declared topology router bindings.',
+        );
+      for (const field of [
+        'renderer',
+        'appId',
+        'entryName',
+        'protocolVersion',
+        'buildId',
+      ] as const) {
+        if (
+          expected.surfaces.ui.rendererIdentity[field] !==
+          ui.rendererIdentity[field]
+        ) {
+          throw new Error(
+            `[cloudflare-delivery-unit] Build artifact UI rendererIdentity.${field} must match the declared topology renderer identity.`,
+          );
+        }
+      }
+      assertRendererProfileCompatibility(
+        expected.surfaces.ui.rendererProfile,
+        ui.rendererProfile,
+      );
+    }
+    emitsApi = expected.surfaces.api !== undefined;
   }
-  return createDeliveryUnitStamp(identity, resolved?.app);
+  return {
+    ...stampedArtifact.deliveryUnit,
+    surfaces: {
+      ...(emitsApi ? { api: stampedArtifact.surfaces.api } : {}),
+      ...(stampedArtifact.surfaces.ui
+        ? { ui: stampedArtifact.surfaces.ui }
+        : {}),
+    },
+  };
 };

package/src/cloudflare/index.ts

@@ -1,4 +1,9 @@
 import path from 'node:path';
+import {
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_REMOTE_ENTRY_FILE,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
+} from '@modern-js/backend-federation-contracts';
 import { fs as fse } from '@modern-js/utils';
 import { createCloudflareOutputPlan } from '../cloudflare-output-plan';
 import { assertCloudflareOutput } from '../cloudflare-output-verifier/index';
@@ -22,14 +27,8 @@ import {
   ROUTE_SPEC_FILE,
   ROUTE_SPEC_OUTPUT,
   WORKER_BUNDLE_DIRECTORY,
-  WORKER_ENTRY,
-  WORKER_MANIFEST,
-  WRANGLER_CONFIG_FILE,
 } from './constants';
-import {
-  resolveTopologyDeliveryUnit,
-  resolveWorkerDeliveryUnitStamp,
-} from './delivery-unit';
+import { resolveWorkerDeliveryUnitStamp } from './delivery-unit';
 import type { CreateCloudflarePreset } from './types';
 import {
   createWorkerManifest,
@@ -87,21 +86,19 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
     '@modern-js/ultramodern-release-envelope',
   );
   let hasReleaseEnvelope = false;
+  let declaredPublicAssets: string[] = [];
 
   return {
     async prepare() {
       await fse.remove(outputDirectory);
     },
     async writeOutput() {
-      if (
-        releaseEnvelopeEnabled &&
-        (await fse.pathExists(
-          path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH),
-        ))
-      ) {
+      if (releaseEnvelopeEnabled) {
         await emitFrameworkMicroVerticalReleaseEnvelope({
           apiOnly,
+          appDirectory,
           distDirectory,
+          role: modernConfig.deploy?.releaseEnvelopeRole,
           target: 'cloudflare',
         });
       }
@@ -113,6 +110,20 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
           const relativePath = path
             .relative(distDirectory, src)
             .replace(/\\/gu, '/');
+          // API-only builds emit server modules at arbitrary paths under dist,
+          // including transitive imports outside api/. Only the framework's
+          // published backend contract belongs beside the explicit public tree.
+          if (
+            apiOnly &&
+            relativePath !== '' &&
+            ![
+              BACKEND_FEDERATION_MANIFEST_FILE,
+              BACKEND_FEDERATION_REMOTE_ENTRY_FILE,
+              ULTRAMODERN_BUILD_ARTIFACT_FILE,
+            ].includes(relativePath)
+          ) {
+            return false;
+          }
           return (
             relativePath !== 'release' &&
             !relativePath.startsWith('release/') &&
@@ -173,9 +184,9 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
         outputDirectory,
         cloudflareArtifacts,
       );
-      await copyCloudflarePublicAssets(
+      declaredPublicAssets = await copyCloudflarePublicAssets(
         appDirectory,
-        publicDirectory,
+        outputDirectory,
         getCloudflarePublicAssets(modernConfig),
       );
       await copyCloudflareD1Migrations(
@@ -192,8 +203,10 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
         },
       );
 
-      const deliveryUnitStamp =
-        await resolveWorkerDeliveryUnitStamp(appDirectory);
+      const deliveryUnitStamp = await resolveWorkerDeliveryUnitStamp(
+        appDirectory,
+        distDirectory,
+      );
       await fse.writeJSON(
         workerManifestPath,
         await createWorkerManifest(
@@ -232,8 +245,10 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
             createWorkerModuleLoaders(manifest),
           ),
       );
-      const topologyDeliveryUnit =
-        await resolveTopologyDeliveryUnit(appDirectory);
+      const topologyDeliveryUnit = await resolveWorkerDeliveryUnitStamp(
+        appDirectory,
+        distDirectory,
+      );
       await assertCloudflareOutput({
         outputDirectory,
         importWorker: false,
@@ -241,6 +256,7 @@ export const createCloudflarePreset: CreateCloudflarePreset = ({
       });
       if (hasReleaseEnvelope) {
         await emitCloudflareStagedReleaseEnvelope({
+          declaredPublicAssets,
           distDirectory,
           outputDirectory,
         });