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

package/src/release-envelope/index.ts

@@ -1,6 +1,14 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import {
+  formatBackendFederationValidationErrors,
+  immutableRendererRouterBindings,
+  validateRendererIdentity,
+  validateRendererProfile,
+  validateRendererProfileCompatibility,
+  validateRendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
 import {
   canonicalSerializeMicroVerticalReleaseEnvelope,
   digestMicroVerticalReleaseEnvelopePayload,
@@ -16,8 +24,15 @@ import {
   type MicroVerticalReleaseEnvelope,
   type MicroVerticalReleaseEnvelopePayload,
   type MicroVerticalReleaseIdentity,
-  type MicroVerticalReleaseSurfaces,
   type MicroVerticalReleaseTarget,
+  type MicroVerticalReleaseUi,
+  type ReleaseEnvelope,
+  type ReleaseEnvelopeKind,
+  type ReleaseEnvelopePayload,
+  type ReleaseSurfaces,
+  SHELL_RELEASE_ENVELOPE_KIND,
+  type ShellReleaseEnvelope,
+  type ShellReleaseEnvelopePayload,
   type VerifyMicroVerticalReleaseEnvelopeOptions,
 } from './types';
 
@@ -33,6 +48,14 @@ export type {
   MicroVerticalReleaseSurfaces,
   MicroVerticalReleaseSymbolicLinkArtifact,
   MicroVerticalReleaseTarget,
+  MicroVerticalReleaseUi,
+  ReleaseEnvelope,
+  ReleaseEnvelopeKind,
+  ReleaseEnvelopePayload,
+  ReleaseSurfaces,
+  ShellReleaseEnvelope,
+  ShellReleaseEnvelopePayload,
+  ShellReleaseSurfaces,
   VerifyMicroVerticalReleaseEnvelopeOptions,
 } from './types';
 export {
@@ -40,6 +63,7 @@ export {
   MICROVERTICAL_RELEASE_ENVELOPE_KIND,
   MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
   MICROVERTICAL_RELEASE_TARGETS,
+  SHELL_RELEASE_ENVELOPE_KIND,
 };
 
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
@@ -100,6 +124,18 @@ const assertTarget = (
   return target as MicroVerticalReleaseTarget;
 };
 
+const assertEnvelopeKind = (value: unknown): ReleaseEnvelopeKind => {
+  if (
+    value !== MICROVERTICAL_RELEASE_ENVELOPE_KIND &&
+    value !== SHELL_RELEASE_ENVELOPE_KIND
+  ) {
+    throw new Error(
+      `envelope.kind must be "${MICROVERTICAL_RELEASE_ENVELOPE_KIND}" or "${SHELL_RELEASE_ENVELOPE_KIND}".`,
+    );
+  }
+  return value;
+};
+
 const assertReleaseIdentity = (
   value: unknown,
   location = 'identity',
@@ -381,8 +417,8 @@ const assertUniqueSortedArtifacts = (
 };
 
 const assertSurfacePaths = (value: unknown, location: string): string[] => {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error(`${location} must contain at least one artifact path.`);
+  if (!Array.isArray(value)) {
+    throw new Error(`${location} must be an array of artifact paths.`);
   }
   const paths = value.map((item, index) =>
     assertNormalizedLogicalPath(item, `${location}[${index}]`),
@@ -397,42 +433,97 @@ const assertSurfacePaths = (value: unknown, location: string): string[] => {
   return paths;
 };
 
-const assertSurfaces = (value: unknown): MicroVerticalReleaseSurfaces => {
+const assertSurfaces = (
+  value: unknown,
+  kind: ReleaseEnvelopeKind,
+):
+  | Pick<MicroVerticalReleaseEnvelopePayload, 'kind' | 'surfaces'>
+  | Pick<ShellReleaseEnvelopePayload, 'kind' | 'surfaces'> => {
   const surfaces = assertRecord(value, 'surfaces');
   assertExactKeys(
     surfaces,
-    ['uiClient', 'ssr', 'apiBackend', 'backendFederation'],
+    [
+      'uiClient',
+      'ssr',
+      'apiBackend',
+      // A Shell consumes remotes and never publishes a backend federation pair.
+      // A UI-only MicroVertical (cold deploy) has no backend surface to pair.
+      ...(kind !== SHELL_RELEASE_ENVELOPE_KIND &&
+      Object.hasOwn(surfaces, 'backendFederation')
+        ? ['backendFederation']
+        : []),
+    ],
     'surfaces',
   );
-  const backendFederation = assertRecord(
-    surfaces.backendFederation,
-    'surfaces.backendFederation',
-  );
-  assertExactKeys(
-    backendFederation,
-    ['manifest', 'container'],
-    'surfaces.backendFederation',
+  const backendFederation = Object.hasOwn(surfaces, 'backendFederation')
+    ? assertRecord(surfaces.backendFederation, 'surfaces.backendFederation')
+    : undefined;
+  if (backendFederation)
+    assertExactKeys(
+      backendFederation,
+      ['manifest', 'container'],
+      'surfaces.backendFederation',
+    );
+  const uiClient = assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient');
+  const ssr = assertSurfacePaths(surfaces.ssr, 'surfaces.ssr');
+  const apiBackend = assertSurfacePaths(
+    surfaces.apiBackend,
+    'surfaces.apiBackend',
   );
+  if (uiClient.length > 0 && ssr.length === 0) {
+    throw new Error(
+      'surfaces.ssr must contain at least one artifact path when UI/client is declared.',
+    );
+  }
+  if (ssr.length > 0 && uiClient.length === 0) {
+    throw new Error(
+      'surfaces.uiClient must contain at least one artifact path when SSR is declared.',
+    );
+  }
+  if (apiBackend.length === 0 && (backendFederation || uiClient.length === 0)) {
+    throw new Error(
+      'surfaces.apiBackend must contain at least one artifact path.',
+    );
+  }
+  if (kind === SHELL_RELEASE_ENVELOPE_KIND) {
+    if (uiClient.length === 0 || ssr.length === 0) {
+      throw new Error(
+        'Shell surfaces.uiClient and surfaces.ssr must each contain at least one artifact path.',
+      );
+    }
+    return { kind, surfaces: { uiClient, ssr, apiBackend } };
+  }
+  if (apiBackend.length > 0 && !backendFederation)
+    throw new Error(
+      'surfaces.backendFederation is required when API/backend is declared.',
+    );
   return {
-    uiClient: assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient'),
-    ssr: assertSurfacePaths(surfaces.ssr, 'surfaces.ssr'),
-    apiBackend: assertSurfacePaths(surfaces.apiBackend, 'surfaces.apiBackend'),
-    backendFederation: {
-      manifest: assertNormalizedLogicalPath(
-        backendFederation.manifest,
-        'surfaces.backendFederation.manifest',
-      ),
-      container: assertNormalizedLogicalPath(
-        backendFederation.container,
-        'surfaces.backendFederation.container',
-      ),
+    kind,
+    surfaces: {
+      uiClient,
+      ssr,
+      apiBackend,
+      ...(backendFederation
+        ? {
+            backendFederation: {
+              manifest: assertNormalizedLogicalPath(
+                backendFederation.manifest,
+                'surfaces.backendFederation.manifest',
+              ),
+              container: assertNormalizedLogicalPath(
+                backendFederation.container,
+                'surfaces.backendFederation.container',
+              ),
+            },
+          }
+        : {}),
     },
   };
 };
 
 const assertSurfaceReferences = (
   artifacts: readonly MicroVerticalReleaseArtifactInput[],
-  surfaces: MicroVerticalReleaseSurfaces,
+  surfaces: ReleaseSurfaces,
 ) => {
   const artifactPaths = new Set(
     artifacts.map(artifact => artifact.logicalPath),
@@ -441,8 +532,12 @@ const assertSurfaceReferences = (
     uiClient: surfaces.uiClient,
     ssr: surfaces.ssr,
     apiBackend: surfaces.apiBackend,
-    'backendFederation.manifest': [surfaces.backendFederation.manifest],
-    'backendFederation.container': [surfaces.backendFederation.container],
+    ...('backendFederation' in surfaces && surfaces.backendFederation
+      ? {
+          'backendFederation.manifest': [surfaces.backendFederation.manifest],
+          'backendFederation.container': [surfaces.backendFederation.container],
+        }
+      : {}),
   })) {
     for (const logicalPath of paths) {
       if (!artifactPaths.has(logicalPath)) {
@@ -457,7 +552,7 @@ const assertSurfaceReferences = (
 const assertTargetSurfaceContract = (
   target: MicroVerticalReleaseTarget,
   artifacts: readonly MicroVerticalReleaseArtifactInput[],
-  surfaces: MicroVerticalReleaseSurfaces,
+  surfaces: ReleaseSurfaces,
 ) => {
   const byPath = new Map(
     artifacts.map(artifact => [artifact.logicalPath, artifact]),
@@ -489,16 +584,18 @@ const assertTargetSurfaceContract = (
     target === 'node' ? 'nodejs' : 'workerd-effect',
     'API/backend',
   );
-  assertRuntime(
-    [surfaces.backendFederation.manifest],
-    'module-federation-manifest',
-    'backend federation manifest',
-  );
-  assertRuntime(
-    [surfaces.backendFederation.container],
-    target === 'node' ? 'nodejs' : 'commonjs-module',
-    'backend federation container',
-  );
+  if ('backendFederation' in surfaces && surfaces.backendFederation) {
+    assertRuntime(
+      [surfaces.backendFederation.manifest],
+      'module-federation-manifest',
+      'backend federation manifest',
+    );
+    assertRuntime(
+      [surfaces.backendFederation.container],
+      target === 'node' ? 'nodejs' : 'commonjs-module',
+      'backend federation container',
+    );
+  }
 };
 
 const deepFreeze = <T>(value: T): T => {
@@ -511,7 +608,81 @@ const deepFreeze = <T>(value: T): T => {
   return value;
 };
 
-const assertEnvelope = (value: unknown): MicroVerticalReleaseEnvelope => {
+const assertReleaseUi = (
+  value: unknown,
+  identity: MicroVerticalReleaseIdentity,
+  surfaces: ReleaseSurfaces,
+): MicroVerticalReleaseUi | undefined => {
+  if (surfaces.uiClient.length === 0) {
+    if (value !== undefined) {
+      throw new Error('envelope.ui is forbidden for an API-only release.');
+    }
+    return undefined;
+  }
+  const ui = assertRecord(value, 'envelope.ui');
+  assertExactKeys(
+    ui,
+    ['rendererIdentity', 'rendererProfile', 'routerBindings'],
+    'envelope.ui',
+  );
+  const routerBindings = assertRecord(
+    ui.routerBindings,
+    'envelope.ui.routerBindings',
+  );
+  const errors = [
+    ...validateRendererIdentity(
+      ui.rendererIdentity,
+      'envelope.ui.rendererIdentity',
+    ).errors,
+    ...validateRendererProfile(
+      ui.rendererProfile,
+      'envelope.ui.rendererProfile',
+    ).errors,
+    ...validateRendererRouterBindings(
+      routerBindings,
+      Object.keys(routerBindings),
+      'envelope.ui.routerBindings',
+    ).errors,
+  ];
+  if (errors.length > 0) {
+    throw new Error(formatBackendFederationValidationErrors(errors));
+  }
+  const rendererIdentity =
+    ui.rendererIdentity as MicroVerticalReleaseUi['rendererIdentity'];
+  const rendererProfile =
+    ui.rendererProfile as MicroVerticalReleaseUi['rendererProfile'];
+  if (!Object.hasOwn(routerBindings, rendererIdentity.entryName)) {
+    throw new Error(
+      'envelope.ui.routerBindings must include the primary rendererIdentity.entryName.',
+    );
+  }
+  if (rendererIdentity.buildId !== identity.buildMarker) {
+    throw new Error(
+      'envelope.ui.rendererIdentity.buildId must match identity.buildMarker.',
+    );
+  }
+  for (const field of ['renderer', 'protocolVersion'] as const) {
+    if (rendererIdentity[field] !== rendererProfile[field]) {
+      throw new Error(
+        `envelope.ui.rendererProfile.${field} must match rendererIdentity.${field}.`,
+      );
+    }
+  }
+  return {
+    rendererIdentity: { ...rendererIdentity },
+    rendererProfile: {
+      ...rendererProfile,
+      compiler: { ...rendererProfile.compiler },
+      hydration: { ...rendererProfile.hydration },
+      router: { ...rendererProfile.router },
+    },
+    routerBindings: immutableRendererRouterBindings(
+      routerBindings as MicroVerticalReleaseUi['routerBindings'],
+    ),
+  };
+};
+
+const assertEnvelope = (value: unknown): ReleaseEnvelope => {
   const envelope = assertRecord(value, 'envelope');
   assertExactKeys(
     envelope,
@@ -520,6 +691,7 @@ const assertEnvelope = (value: unknown): MicroVerticalReleaseEnvelope => {
       'kind',
       'target',
       'identity',
+      ...(Object.hasOwn(envelope, 'ui') ? ['ui'] : []),
       'artifacts',
       'surfaces',
       'envelopeDigest',
@@ -533,11 +705,7 @@ const assertEnvelope = (value: unknown): MicroVerticalReleaseEnvelope => {
       `envelope.schemaVersion must be ${MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION}.`,
     );
   }
-  if (envelope.kind !== MICROVERTICAL_RELEASE_ENVELOPE_KIND) {
-    throw new Error(
-      `envelope.kind must be "${MICROVERTICAL_RELEASE_ENVELOPE_KIND}".`,
-    );
-  }
+  const kind = assertEnvelopeKind(envelope.kind);
   if (!Array.isArray(envelope.artifacts) || envelope.artifacts.length === 0) {
     throw new Error('envelope.artifacts must contain at least one artifact.');
   }
@@ -546,16 +714,25 @@ const assertEnvelope = (value: unknown): MicroVerticalReleaseEnvelope => {
   );
   assertUniqueSortedArtifacts(artifacts, 'envelope.artifacts');
   const target = assertTarget(envelope.target, 'envelope.target');
-  const surfaces = assertSurfaces(envelope.surfaces);
+  const releaseSurfaces = assertSurfaces(envelope.surfaces, kind);
+  const { surfaces } = releaseSurfaces;
+  if (surfaces.uiClient.length === 0 && Object.hasOwn(envelope, 'ui')) {
+    throw new Error('envelope.ui is forbidden for an API-only release.');
+  }
   assertSurfaceReferences(artifacts, surfaces);
   assertTargetSurfaceContract(target, artifacts, surfaces);
-  const parsed: MicroVerticalReleaseEnvelope = {
+  const identity = assertReleaseIdentity(
+    envelope.identity,
+    'envelope.identity',
+  );
+  const ui = assertReleaseUi(envelope.ui, identity, surfaces);
+  const parsed: ReleaseEnvelope = {
+    ...releaseSurfaces,
     schemaVersion: MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
-    kind: MICROVERTICAL_RELEASE_ENVELOPE_KIND,
     target,
-    identity: assertReleaseIdentity(envelope.identity, 'envelope.identity'),
+    identity,
+    ...(ui ? { ui } : {}),
     artifacts,
-    surfaces,
     envelopeDigest: assertNonEmptyString(
       envelope.envelopeDigest,
       'envelope.envelopeDigest',
@@ -577,12 +754,28 @@ const assertEnvelope = (value: unknown): MicroVerticalReleaseEnvelope => {
   return parsed;
 };
 
-export const createMicroVerticalReleaseEnvelope = async (
+export function createMicroVerticalReleaseEnvelope(
+  input: CreateMicroVerticalReleaseEnvelopeInput & {
+    kind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+  },
+): Promise<ShellReleaseEnvelope>;
+export function createMicroVerticalReleaseEnvelope(
+  input: CreateMicroVerticalReleaseEnvelopeInput & {
+    kind?: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
+  },
+): Promise<MicroVerticalReleaseEnvelope>;
+export function createMicroVerticalReleaseEnvelope(
+  input: CreateMicroVerticalReleaseEnvelopeInput,
+): Promise<ReleaseEnvelope>;
+export async function createMicroVerticalReleaseEnvelope(
   input: CreateMicroVerticalReleaseEnvelopeInput,
-): Promise<MicroVerticalReleaseEnvelope> => {
+): Promise<ReleaseEnvelope> {
   const artifactRoot = await fs.realpath(path.resolve(input.artifactRoot));
   const target = assertTarget(input.target);
   const identity = assertReleaseIdentity(input.identity);
+  const kind = assertEnvelopeKind(
+    input.kind === undefined ? MICROVERTICAL_RELEASE_ENVELOPE_KIND : input.kind,
+  );
   if (!Array.isArray(input.artifacts) || input.artifacts.length === 0) {
     throw new Error('artifacts must contain at least one artifact.');
   }
@@ -593,32 +786,94 @@ export const createMicroVerticalReleaseEnvelope = async (
     left.logicalPath.localeCompare(right.logicalPath),
   );
   assertUniqueSortedArtifacts(sortedInputs, 'artifacts');
-  const surfaces = assertSurfaces(input.surfaces);
+  const releaseSurfaces = assertSurfaces(input.surfaces, kind);
+  const { surfaces } = releaseSurfaces;
+  if (surfaces.uiClient.length === 0 && Object.hasOwn(input, 'ui')) {
+    throw new Error('envelope.ui is forbidden for an API-only release.');
+  }
   assertSurfaceReferences(sortedInputs, surfaces);
   assertTargetSurfaceContract(target, sortedInputs, surfaces);
+  const ui = assertReleaseUi(input.ui, identity, surfaces);
   const artifacts = await Promise.all(
     sortedInputs.map(artifact => readFinalArtifact(artifactRoot, artifact)),
   );
   assertTargetSurfaceContract(target, artifacts, surfaces);
-  const payload: MicroVerticalReleaseEnvelopePayload = {
+  const payload: ReleaseEnvelopePayload = {
+    ...releaseSurfaces,
     schemaVersion: MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
-    kind: MICROVERTICAL_RELEASE_ENVELOPE_KIND,
     target,
     identity,
+    ...(ui ? { ui } : {}),
     artifacts,
-    surfaces,
   };
   return deepFreeze({
     ...payload,
     envelopeDigest: digestMicroVerticalReleaseEnvelopePayload(payload),
   });
-};
+}
 
-export const verifyMicroVerticalReleaseEnvelope = async (
+export function verifyMicroVerticalReleaseEnvelope(
+  value: unknown,
+  options: VerifyMicroVerticalReleaseEnvelopeOptions & {
+    expectedKind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+  },
+): Promise<ShellReleaseEnvelope>;
+export function verifyMicroVerticalReleaseEnvelope(
+  value: unknown,
+  options: VerifyMicroVerticalReleaseEnvelopeOptions & {
+    expectedKind: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
+  },
+): Promise<MicroVerticalReleaseEnvelope>;
+export function verifyMicroVerticalReleaseEnvelope(
   value: unknown,
   options: VerifyMicroVerticalReleaseEnvelopeOptions,
-): Promise<MicroVerticalReleaseEnvelope> => {
+): Promise<ReleaseEnvelope>;
+export async function verifyMicroVerticalReleaseEnvelope(
+  value: unknown,
+  options: VerifyMicroVerticalReleaseEnvelopeOptions,
+): Promise<ReleaseEnvelope> {
   const envelope = assertEnvelope(value);
+  if (options.expectedRendererProfile !== undefined) {
+    const result = validateRendererProfileCompatibility(
+      options.expectedRendererProfile,
+      envelope.ui?.rendererProfile,
+      'envelope.ui.rendererProfile',
+    );
+    if (!result.ok) {
+      throw new Error(formatBackendFederationValidationErrors(result.errors));
+    }
+  }
+  if (options.expectedRendererIdentity !== undefined) {
+    const expected = options.expectedRendererIdentity;
+    const result = validateRendererIdentity(
+      expected,
+      'expectedRendererIdentity',
+    );
+    if (!result.ok) {
+      throw new Error(formatBackendFederationValidationErrors(result.errors));
+    }
+    for (const field of [
+      'renderer',
+      'protocolVersion',
+      'appId',
+      'entryName',
+      'buildId',
+    ] as const) {
+      if (envelope.ui?.rendererIdentity[field] !== expected[field]) {
+        throw new Error(
+          `envelope.ui.rendererIdentity.${field} must match the consuming renderer identity.`,
+        );
+      }
+    }
+  }
+  if (
+    options.expectedKind !== undefined &&
+    envelope.kind !== options.expectedKind
+  ) {
+    throw new Error(
+      `envelope.kind must be "${options.expectedKind}" for this release owner; received "${envelope.kind}".`,
+    );
+  }
   if (
     options.expectedTarget !== undefined &&
     envelope.target !== options.expectedTarget
@@ -653,4 +908,4 @@ export const verifyMicroVerticalReleaseEnvelope = async (
     }
   }
   return deepFreeze(envelope);
-};
+}

package/src/release-envelope/plugin.ts

@@ -1,4 +1,15 @@
 import path from 'node:path';
+import type { RendererProfile } from '@modern-js/backend-federation-contracts';
+import type { NodePublicAssetConfig } from '../config';
+import {
+  NODE_PUBLIC_ASSET_SCOPE,
+  normalizeDeclaredPublicAssets,
+  resolveAddedDeclaredPublicAssetPaths,
+} from '../deploy-output/public-assets';
+import {
+  getDeployingTarget,
+  type ResolvedDeployTarget,
+} from '../deploy-output/target';
 import {
   emitFrameworkMicroVerticalReleaseEnvelope,
   emitNodeStagedReleaseEnvelope,
@@ -6,10 +17,11 @@ import {
   verifyNodeReleaseEnvelopeStaging,
 } from './framework-output';
 
-type ReleaseEnvelopeTarget = 'cloudflare' | 'node' | string;
-
 export interface ReleaseEnvelopeConfig {
-  deploy?: { target?: string };
+  deploy?: {
+    releaseEnvelopeRole?: 'microvertical' | 'shell';
+    node?: { publicAssets?: NodePublicAssetConfig[] };
+  };
 }
 
 export interface ReleaseEnvelopeAppContext {
@@ -17,6 +29,7 @@ export interface ReleaseEnvelopeAppContext {
   appDirectory: string;
   distDirectory: string;
   metaName: string;
+  deployTarget?: ResolvedDeployTarget;
 }
 
 export interface ReleaseEnvelopePluginApi<
@@ -38,64 +51,59 @@ export interface ReleaseEnvelopePlugin<
   setup(api: ReleaseEnvelopePluginApi<Config>): void;
 }
 
-export type ResolveDeployTarget<
-  Config extends ReleaseEnvelopeConfig = ReleaseEnvelopeConfig,
-> = (config: Config) => ReleaseEnvelopeTarget;
-
-const resolveActiveDeployTarget = <Config extends ReleaseEnvelopeConfig>(
-  api: ReleaseEnvelopePluginApi<Config>,
-  resolveDeployTarget: ResolveDeployTarget<Config>,
-) => {
-  const { metaName } = api.getAppContext();
-  const config = api.getNormalizedConfig();
-  if (
-    metaName !== 'modern-js' &&
-    !config.deploy?.target &&
-    !process.env.MODERNJS_DEPLOY
-  ) {
-    return undefined;
-  }
-  return resolveDeployTarget(config);
-};
-
 export const createUltramodernReleaseEnvelopePlugin = <
   Config extends ReleaseEnvelopeConfig,
 >({
-  resolveDeployTarget,
+  resolveRendererProfile,
 }: {
-  resolveDeployTarget: ResolveDeployTarget<Config>;
-}): ReleaseEnvelopePlugin<Config> => {
+  resolveRendererProfile?: (config: Config) => RendererProfile;
+} = {}): ReleaseEnvelopePlugin<Config> => {
   return {
     name: '@modern-js/ultramodern-release-envelope',
     pre: [
       '@modern-js/backend-federation-build',
       '@modern-js/plugin-bff',
       '@modern-js/deploy-output-aliases',
+      '@modern-js/deploy-output-public-assets',
     ],
     post: ['@modern-js/plugin-deploy'],
     setup(api) {
-      const emitBuildEnvelope = async (target: 'node' | 'cloudflare') => {
-        const { apiOnly, distDirectory } = api.getAppContext();
+      const emitBuildEnvelope = async (
+        target: 'node' | 'cloudflare',
+        requirePromotable = true,
+      ) => {
+        const { apiOnly, appDirectory, distDirectory } = api.getAppContext();
         await emitFrameworkMicroVerticalReleaseEnvelope({
           apiOnly,
+          appDirectory,
           distDirectory,
+          role: api.getNormalizedConfig().deploy?.releaseEnvelopeRole,
+          requirePromotable,
           target,
+          ...(!apiOnly && resolveRendererProfile
+            ? {
+                expectedRendererProfile: resolveRendererProfile(
+                  api.getNormalizedConfig(),
+                ),
+              }
+            : {}),
         });
       };
 
       api.onAfterBuild(async () => {
-        const configuredTarget = resolveDeployTarget(api.getNormalizedConfig());
+        const configuredTarget = api.getAppContext().deployTarget?.target;
         if (configuredTarget !== 'node' && configuredTarget !== 'cloudflare') {
           return;
         }
-        await emitBuildEnvelope(configuredTarget);
+        // A plain `modern build` is the development path: a dirty or non-Git
+        // checkout resolves to the `workspace` source revision, which is not
+        // promotable but must still build. Deploy re-emits the envelope and
+        // verifies it, so the release gate keeps its teeth there.
+        await emitBuildEnvelope(configuredTarget, false);
       });
 
       api.onBeforeDeploy(async () => {
-        const configuredTarget = resolveActiveDeployTarget(
-          api,
-          resolveDeployTarget,
-        );
+        const configuredTarget = getDeployingTarget(api.getAppContext());
         if (configuredTarget !== 'node') {
           return;
         }
@@ -105,16 +113,24 @@ export const createUltramodernReleaseEnvelopePlugin = <
       });
 
       api.onAfterDeploy(async () => {
-        const configuredTarget = resolveActiveDeployTarget(
-          api,
-          resolveDeployTarget,
-        );
+        const configuredTarget = getDeployingTarget(api.getAppContext());
         if (configuredTarget !== 'node') {
           return;
         }
         const { appDirectory, distDirectory } = api.getAppContext();
         const outputDirectory = path.join(appDirectory, '.output');
         const releaseEnvelope = await emitNodeStagedReleaseEnvelope({
+          // The Node deploy output is a copy of dist, so a declared file
+          // added output exactly when dist has no file at its path.
+          declaredPublicAssets: await resolveAddedDeclaredPublicAssetPaths({
+            appDirectory,
+            assets: normalizeDeclaredPublicAssets(
+              api.getNormalizedConfig().deploy?.node?.publicAssets,
+              NODE_PUBLIC_ASSET_SCOPE,
+            ),
+            generatedRoot: distDirectory,
+            scope: NODE_PUBLIC_ASSET_SCOPE,
+          }),
           distDirectory,
           outputDirectory,
         });