@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/dist/esm-node/policy-defaults.mjs

@@ -0,0 +1,46 @@
+import "node:module";
+import { collectRuntimePackageModuleDirectories, createRuntimePackageResolutionPlugin } from "./runtime-package-resolution.mjs";
+const RENDERER_EXTENSIONS_PACKAGE = '@modern-js/runtime-renderer-extensions';
+const RENDERER_EXTENSIONS_PLUGIN_NAME = 'rendererHead';
+const SERVER_EXTENSIONS_PLUGIN_NAME = '@modern-js/app-tools/server-plugin';
+const POLICY_DEFAULTS_PLUGIN_NAME = '@modern-js/ultramodern-policy-defaults';
+const applyPolicyDefaults = (api, options = {})=>{
+    if (false !== options.rendererExtensions) {
+        api._internalRuntimePlugins(({ entrypoint, plugins })=>{
+            if (!plugins.some((plugin)=>plugin.path === RENDERER_EXTENSIONS_PACKAGE)) plugins.push({
+                name: RENDERER_EXTENSIONS_PLUGIN_NAME,
+                path: RENDERER_EXTENSIONS_PACKAGE,
+                config: {}
+            });
+            return {
+                entrypoint,
+                plugins
+            };
+        });
+        const moduleDirectories = collectRuntimePackageModuleDirectories([
+            RENDERER_EXTENSIONS_PACKAGE
+        ], import.meta.url);
+        if (moduleDirectories.length > 0) api.modifyResolvedConfig((config)=>({
+                ...config,
+                builderPlugins: [
+                    ...config.builderPlugins ?? [],
+                    createRuntimePackageResolutionPlugin(moduleDirectories)
+                ]
+            }));
+    }
+    if (false !== options.serverExtensions) api._internalServerPlugins(({ plugins })=>{
+        if (!plugins.some((plugin)=>plugin.name === SERVER_EXTENSIONS_PLUGIN_NAME)) plugins.push({
+            name: SERVER_EXTENSIONS_PLUGIN_NAME
+        });
+        return {
+            plugins
+        };
+    });
+};
+const createPolicyDefaultsPlugin = (options = {})=>({
+        name: POLICY_DEFAULTS_PLUGIN_NAME,
+        setup (api) {
+            applyPolicyDefaults(api, options);
+        }
+    });
+export { POLICY_DEFAULTS_PLUGIN_NAME, RENDERER_EXTENSIONS_PACKAGE, RENDERER_EXTENSIONS_PLUGIN_NAME, SERVER_EXTENSIONS_PLUGIN_NAME, applyPolicyDefaults, createPolicyDefaultsPlugin };

package/dist/esm-node/release-envelope/framework-output.mjs

@@ -2,7 +2,7 @@ import "node:module";
 import { createHash } from "node:crypto";
 import promises from "node:fs/promises";
 import node_path from "node:path";
-import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, ULTRAMODERN_BUILD_ARTIFACT_FILE, isUltramodernBuildArtifact } from "@modern-js/utils/universal";
+import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, ULTRAMODERN_BUILD_ARTIFACT_FILE, isUltramodernBuildArtifact } from "@modern-js/backend-federation-contracts";
 import { canonicalSerializeMicroVerticalReleaseEnvelope, createMicroVerticalReleaseEnvelope, verifyMicroVerticalReleaseEnvelope } from "./index.mjs";
 const MICROVERTICAL_RELEASE_ENVELOPE_PATH = 'release/microvertical-release-envelope.json';
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_PATH = 'release/microvertical-release-identity-carriers.json';
@@ -10,6 +10,21 @@ const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_KIND = 'ultramodern-release-identi
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_SCHEMA_VERSION = 1;
 const COMPILED_MODULE_PATTERN = /\.(?:c|m)?js$/u;
 const EFFECT_BFF_WORKER_PATTERN = /^worker\/__modern_bff_effect\.(?:c|m)?js$/u;
+const EFFECT_BFF_WORKER_SUPPORT_PATTERN = /^worker\/__modern_worker_(?:runtime|shared)_*\.(?:c|m)?js$/u;
+const isEffectBffWorkerArtifact = (logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath) || EFFECT_BFF_WORKER_SUPPORT_PATTERN.test(logicalPath);
+const CRAWLER_POLICY_PATH = 'public/robots.txt';
+const isPublicMetadataPath = (logicalPath)=>'public/_headers' === logicalPath || /^public\/\.well-known\/[^/]+\.json$/u.test(logicalPath);
+const PUBLIC_BUILD_ARTIFACT_PATH = `public/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
+const DECLARED_PUBLIC_ASSET_RUNTIME = 'public-asset';
+const resolveDeclaredPublicAssets = (files, declaredPublicAssets, target)=>{
+    const staged = new Set(files);
+    const declared = new Set();
+    for (const logicalPath of declaredPublicAssets){
+        if (!logicalPath.startsWith('public/') || !staged.has(logicalPath)) throw new Error(`[ultramodern-release-envelope] final ${target} staging has no declared public asset file ${JSON.stringify(logicalPath)}.`);
+        declared.add(logicalPath);
+    }
+    return declared;
+};
 const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
 const flattenStrings = (value)=>'string' == typeof value ? [
         value
@@ -22,6 +37,46 @@ const collectNestedStrings = (value, key)=>{
             ...collectNestedStrings(entryValue, key)
         ]);
 };
+const emptyProducerRouteModules = async (distDirectory, files, manifest, manifestLogicalPath)=>{
+    if (!isRecord(manifest) || !Array.isArray(manifest.exposes) || 0 !== manifest.exposes.length || !Array.isArray(manifest.remotes) || 0 !== manifest.remotes.length || !isRecord(manifest.metaData) || !isRecord(manifest.metaData.remoteEntry) || '' !== manifest.metaData.remoteEntry.name || '' !== manifest.metaData.remoteEntry.path || 'global' !== manifest.metaData.remoteEntry.type) return [];
+    const publicPath = manifest.metaData.publicPath;
+    const safeReference = (value)=>'string' == typeof value && value.length > 0 && !/[\\\\%?#\s]/u.test(value) && !value.split('/').some((segment)=>'.' === segment || '..' === segment);
+    if (!safeReference(publicPath)) return [];
+    const absoluteBase = /^https?:\/\//u.test(publicPath);
+    if ('auto' !== publicPath && (!publicPath.endsWith('/') || !absoluteBase && (!publicPath.startsWith('/') || publicPath.startsWith('//')))) return [];
+    if (absoluteBase) {
+        const base = new URL(publicPath);
+        if (base.username || base.password || base.href !== publicPath) return [];
+    }
+    const directory = node_path.posix.dirname(manifestLogicalPath);
+    const routesManifest = await readJson(node_path.join(distDirectory, directory, 'routes-manifest.json'));
+    if (!isRecord(routesManifest) || !isRecord(routesManifest.routeAssets)) return [];
+    const modules = new Set();
+    for (const route of Object.values(routesManifest.routeAssets)){
+        if (!isRecord(route) || !Array.isArray(route.assets)) return [];
+        for (const reference of route.assets){
+            if (!safeReference(reference) || reference.startsWith('//')) return [];
+            let relative = reference;
+            if (/^https?:\/\//u.test(reference)) {
+                if (!absoluteBase || !reference.startsWith(publicPath)) return [];
+                relative = reference.slice(publicPath.length);
+            } else if (reference.startsWith('/')) {
+                const prefix = 'auto' === publicPath ? '/' : absoluteBase ? new URL(publicPath).pathname : publicPath;
+                if (!reference.startsWith(prefix)) return [];
+                relative = reference.slice(prefix.length);
+            }
+            if (!/^(?:static|html|public)\/[^:]+$/u.test(relative) || relative.includes('//')) return [];
+            const logicalPath = node_path.posix.join(directory, relative);
+            if (!files.includes(logicalPath)) return [];
+            const assetStat = await promises.lstat(node_path.join(distDirectory, logicalPath));
+            if (!assetStat.isFile()) return [];
+            if (COMPILED_MODULE_PATTERN.test(logicalPath)) modules.add(logicalPath);
+        }
+    }
+    return [
+        ...modules
+    ];
+};
 const manifestReferencedClientModules = async (distDirectory, files, manifestLogicalPath = 'mf-manifest.json')=>{
     const manifest = await readJson(node_path.join(distDirectory, manifestLogicalPath));
     const references = [
@@ -31,9 +86,10 @@ const manifestReferencedClientModules = async (distDirectory, files, manifestLog
         ...collectNestedStrings(manifest, 'async')
     ];
     const normalizedReferences = new Set(references.filter((value)=>'string' == typeof value).map((value)=>value.replace(/^https?:\/\/[^/]+/u, '')).map((value)=>value.replace(/^\/+/u, '')));
-    return files.filter((logicalPath)=>COMPILED_MODULE_PATTERN.test(logicalPath) && [
+    const modules = files.filter((logicalPath)=>COMPILED_MODULE_PATTERN.test(logicalPath) && [
             ...normalizedReferences
         ].some((reference)=>reference === logicalPath || reference.endsWith(`/${logicalPath}`) || logicalPath.endsWith(`/${reference}`)));
+    return modules.length > 0 ? modules : emptyProducerRouteModules(distDirectory, files, manifest, manifestLogicalPath);
 };
 const routeReferencedSsrModules = async (distDirectory, files, target, routeSpecLogicalPath = 'route.json')=>{
     const routeSpec = await readJson(node_path.join(distDirectory, routeSpecLogicalPath));
@@ -83,11 +139,14 @@ const writeReleaseEnvelope = async (artifactRoot, envelope)=>{
     if (!envelopePath) throw new Error('[ultramodern-release-envelope] could not resolve release envelope path.');
     await promises.writeFile(envelopePath, `${canonicalSerializeMicroVerticalReleaseEnvelope(envelope)}\n`);
 };
-const readBuildArtifact = async (distDirectory)=>{
+const readBuildArtifact = async (distDirectory, requirePromotable = true)=>{
     const artifactPath = node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE);
     const artifact = await readJson(artifactPath);
     if (!isUltramodernBuildArtifact(artifact)) throw new Error(`[ultramodern-release-envelope] ${ULTRAMODERN_BUILD_ARTIFACT_FILE} is missing or invalid.`);
-    if ('workspace' === artifact.deliveryUnit.sourceRevision) throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable full-stack envelope.');
+    if ('workspace' === artifact.deliveryUnit.sourceRevision) {
+        if (!requirePromotable) return;
+        throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.');
+    }
     return artifact;
 };
 const assertIdentityBlock = (value, identity, location, includeReleaseVersion)=>{
@@ -156,7 +215,7 @@ const releaseArtifact = (logicalPath, runtime)=>({
 const writeReleaseIdentityCarrierMetadata = async (artifactRoot, identity, carrierPaths)=>{
     const surfacesByPath = new Map();
     for (const [surface, logicalPaths] of Object.entries(carrierPaths)){
-        if (0 === logicalPaths.length) throw new Error(`[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`);
+        if (0 === logicalPaths.length && 'ssr' !== surface && 'uiClient' !== surface) throw new Error(`[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`);
         for (const logicalPath of logicalPaths){
             const surfaces = surfacesByPath.get(logicalPath) ?? new Set();
             surfaces.add(surface);
@@ -196,12 +255,12 @@ const writeReleaseIdentityCarrierMetadata = async (artifactRoot, identity, carri
     }, null, 2)}\n`);
     return releaseArtifact(MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_PATH, 'release-identity-metadata');
 };
-const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
+const createReleaseArtifactInputs = async (distDirectory, identity, target, apiOnly)=>{
     const files = await collectFiles(distDirectory);
-    if ('node' === target && files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath))) throw new Error('[ultramodern-release-envelope] Node target conflicts with a Cloudflare Effect API/BFF worker artifact; resolve the canonical deploy target instead of emitting a Node envelope for Cloudflare output.');
+    if ('node' === target && files.some(isEffectBffWorkerArtifact)) throw new Error('[ultramodern-release-envelope] Node target conflicts with a Cloudflare Effect API/BFF worker artifact; resolve the canonical deploy target instead of emitting a Node envelope for Cloudflare output.');
     const uiClientPaths = files.filter((logicalPath)=>{
         const topLevel = logicalPath.split('/')[0];
-        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -210,16 +269,17 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
             'loadable-stats.json'
         ].includes(logicalPath);
     });
-    const ssrPaths = 'node' === target ? files.filter((logicalPath)=>logicalPath.startsWith('bundles/') && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter((logicalPath)=>logicalPath.startsWith('worker/') && COMPILED_MODULE_PATTERN.test(logicalPath) && !EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
+    const ssrPaths = 'node' === target ? files.filter((logicalPath)=>logicalPath.startsWith('bundles/') && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter((logicalPath)=>logicalPath.startsWith('worker/') && COMPILED_MODULE_PATTERN.test(logicalPath) && !isEffectBffWorkerArtifact(logicalPath));
     const nodeApiEntryPaths = files.filter((logicalPath)=>logicalPath.startsWith('api/') && COMPILED_MODULE_PATTERN.test(logicalPath));
-    const apiBackendPaths = 'node' === target ? files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
-    if (0 === uiClientPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`);
-    if (0 === ssrPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${'node' === target ? 'Node' : 'workerd'} SSR artifacts.`);
-    if ('node' === target && 0 === nodeApiEntryPaths.length || 0 === apiBackendPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no actual ${'node' === target ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`);
-    const clientExecutionPaths = await manifestReferencedClientModules(distDirectory, files);
-    if (0 === clientExecutionPaths.length) throw new Error('[ultramodern-release-envelope] UI/client manifest references no compiled execution module.');
-    const ssrExecutionPaths = await routeReferencedSsrModules(distDirectory, files, target);
-    if (0 === ssrExecutionPaths.length) throw new Error(`[ultramodern-release-envelope] route manifest references no emitted ${'node' === target ? 'Node' : 'Cloudflare'} SSR execution module.`);
+    const apiBackendPaths = 'node' === target ? files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter(isEffectBffWorkerArtifact);
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.length > 0)) throw new Error('[ultramodern-release-envelope] API-only MicroVertical emitted an undeclared UI/client or SSR surface.');
+    if (!apiOnly && 0 === uiClientPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`);
+    if (!apiOnly && 0 === ssrPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${'node' === target ? 'Node' : 'workerd'} SSR artifacts.`);
+    if ('node' === target && 0 === nodeApiEntryPaths.length || 'cloudflare' === target && !files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath)) || 0 === apiBackendPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} MicroVertical has no actual ${'node' === target ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`);
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(distDirectory, files);
+    if (!apiOnly && 0 === clientExecutionPaths.length) throw new Error('[ultramodern-release-envelope] UI/client manifest references no compiled execution module.');
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(distDirectory, files, target);
+    if (!apiOnly && 0 === ssrExecutionPaths.length) throw new Error(`[ultramodern-release-envelope] route manifest references no emitted ${'node' === target ? 'Node' : 'Cloudflare'} SSR execution module.`);
     const runtimeByPath = new Map();
     const add = (paths, runtime)=>{
         for (const logicalPath of paths){
@@ -229,6 +289,8 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
         }
     };
     add(uiClientPaths, 'browser');
+    add(files.filter((logicalPath)=>logicalPath === CRAWLER_POLICY_PATH), 'crawler-policy');
+    add(files.filter(isPublicMetadataPath), 'public-metadata');
     add(ssrPaths, 'node' === target ? 'nodejs' : 'workerd');
     add(apiBackendPaths, 'node' === target ? 'nodejs' : 'workerd-effect');
     add([
@@ -285,17 +347,17 @@ const pathExists = async (filePath)=>{
         return false;
     }
 };
-const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, target })=>{
-    if (apiOnly) return;
+const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, requirePromotable = true, target })=>{
     const backendManifestPath = node_path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE);
     const backendContainerPath = node_path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE);
     const [hasBackendManifest, hasBackendContainer] = await Promise.all([
         pathExists(backendManifestPath),
         pathExists(backendContainerPath)
     ]);
-    if (!hasBackendManifest && !hasBackendContainer) return;
-    if (!hasBackendManifest || !hasBackendContainer) throw new Error('[ultramodern-release-envelope] full-stack MicroVertical backend federation manifest and container must be emitted together.');
-    const buildArtifact = await readBuildArtifact(distDirectory);
+    if (!hasBackendManifest && !hasBackendContainer && !apiOnly) return;
+    if (!hasBackendManifest || !hasBackendContainer) throw new Error('[ultramodern-release-envelope] MicroVertical backend federation manifest and container must be emitted together.');
+    const buildArtifact = await readBuildArtifact(distDirectory, requirePromotable);
+    if (!buildArtifact) return;
     const identity = {
         unitId: buildArtifact.deliveryUnit.unitId,
         buildMarker: buildArtifact.deliveryUnit.buildMarker,
@@ -303,7 +365,7 @@ const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirector
         releaseVersion: buildArtifact.deliveryUnit.version
     };
     await readBackendManifest(distDirectory, identity);
-    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target);
+    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target, apiOnly);
     const envelope = await createMicroVerticalReleaseEnvelope({
         artifactRoot: distDirectory,
         target,
@@ -334,19 +396,16 @@ const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expecte
     });
 };
 const verifyBuildOutputReleaseEnvelope = async (distDirectory, expectedTarget)=>{
-    const [hasEnvelope, hasBuildArtifact, hasBackendManifest, hasBackendEntry] = await Promise.all([
+    const [hasEnvelope, hasBuildArtifact] = await Promise.all([
         pathExists(node_path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
-        pathExists(node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
-        pathExists(node_path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE)),
-        pathExists(node_path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE))
+        pathExists(node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE))
     ]);
-    const isFullStackMicroVertical = hasBuildArtifact && (hasBackendManifest || hasBackendEntry);
     return readFrameworkMicroVerticalReleaseEnvelope({
         artifactRoot: distDirectory,
         ...expectedTarget ? {
             expectedTarget
         } : {},
-        required: hasEnvelope || isFullStackMicroVertical
+        required: hasEnvelope || hasBuildArtifact
     });
 };
 const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFrameworkMicroVerticalReleaseEnvelope({
@@ -354,8 +413,9 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly, declaredPublicAssets)=>{
     const files = await collectFiles(outputDirectory);
+    const declaredPublicAssetPaths = resolveDeclaredPublicAssets(files, declaredPublicAssets, 'Node');
     for (const requiredPath of [
         'index.js',
         'package.json',
@@ -368,7 +428,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
     ]);
     const uiClientPaths = files.filter((logicalPath)=>{
         const topLevel = logicalPath.split('/')[0];
-        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -379,6 +439,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
     });
     const ssrPaths = files.filter((logicalPath)=>'index.js' === logicalPath || logicalPath.startsWith('bundles/') && COMPILED_MODULE_PATTERN.test(logicalPath));
     const apiBackendPaths = files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath));
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.some((path)=>'index.js' !== path))) throw new Error('[ultramodern-release-envelope] final API-only Node staging contains an undeclared UI/client or SSR surface.');
     for (const [surface, paths] of [
         [
             'UI/client',
@@ -386,22 +447,25 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
         ],
         [
             'Node SSR',
-            ssrPaths
+            apiOnly ? [] : ssrPaths
         ],
         [
             'Node API/backend',
             apiBackendPaths
         ]
-    ])if (0 === paths.length) throw new Error(`[ultramodern-release-envelope] final Node staging has no ${surface} artifacts.`);
-    const clientExecutionPaths = await manifestReferencedClientModules(outputDirectory, files);
-    const ssrExecutionPaths = await routeReferencedSsrModules(outputDirectory, files, 'node');
-    if (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length) throw new Error('[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.');
+    ])if (0 === paths.length && (!apiOnly || 'Node API/backend' === surface)) throw new Error(`[ultramodern-release-envelope] final Node staging has no ${surface} artifacts.`);
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(outputDirectory, files);
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(outputDirectory, files, 'node');
+    if (!apiOnly && (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length)) throw new Error('[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.');
     const runtimeByPath = new Map(files.filter((logicalPath)=>!backendFederationPaths.has(logicalPath)).map((logicalPath)=>[
             logicalPath,
             'nodejs-deployment'
         ]));
     for (const logicalPath of uiClientPaths)runtimeByPath.set(logicalPath, 'browser');
-    for (const logicalPath of ssrPaths)runtimeByPath.set(logicalPath, 'nodejs');
+    for (const logicalPath of declaredPublicAssetPaths)runtimeByPath.set(logicalPath, DECLARED_PUBLIC_ASSET_RUNTIME);
+    if (files.includes(CRAWLER_POLICY_PATH)) runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
+    for (const logicalPath of files.filter(isPublicMetadataPath))runtimeByPath.set(logicalPath, 'public-metadata');
+    for (const logicalPath of apiOnly ? [] : ssrPaths)runtimeByPath.set(logicalPath, 'nodejs');
     for (const logicalPath of apiBackendPaths)runtimeByPath.set(logicalPath, 'nodejs');
     runtimeByPath.set(BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
     runtimeByPath.set(BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
@@ -411,7 +475,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             BACKEND_FEDERATION_MANIFEST_FILE,
             BACKEND_FEDERATION_REMOTE_ENTRY_FILE
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>'index.js' !== logicalPath)
@@ -430,7 +494,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
@@ -443,10 +507,10 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
         }
     };
 };
-const emitNodeStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+const emitNodeStagedReleaseEnvelope = async ({ declaredPublicAssets = [], distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'node');
     if (!source) return;
-    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, declaredPublicAssets);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -464,21 +528,26 @@ const stageCloudflareReleaseEnvelope = async ({ distDirectory, outputDirectory }
     if (await pathExists(stagedEnvelopePath)) throw new Error('[ultramodern-release-envelope] Cloudflare staging contains a stale envelope before final output generation.');
     return source;
 };
-const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly, declaredPublicAssets)=>{
     const files = await collectFiles(outputDirectory);
+    const declaredPublicAssetPaths = resolveDeclaredPublicAssets(files, declaredPublicAssets, 'Cloudflare');
     for (const requiredPath of [
         'server/index.mjs',
         'server/modern-worker-manifest.json',
         'wrangler.json',
         'package.json',
-        'worker/package.json'
+        ...apiOnly ? [] : [
+            'worker/package.json'
+        ]
     ])if (!files.includes(requiredPath)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging is missing ${requiredPath}.`);
     if (files.some((logicalPath)=>'public/release' === logicalPath || logicalPath.startsWith('public/release/'))) throw new Error('[ultramodern-release-envelope] final Cloudflare envelope must remain private and cannot be staged under public/release.');
     const backendManifestPath = `public/${BACKEND_FEDERATION_MANIFEST_FILE}`;
     const backendContainerPath = `public/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`;
-    const apiBackendPaths = files.filter((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
-    const ssrPaths = files.filter((logicalPath)=>(logicalPath.startsWith('server/') || logicalPath.startsWith('worker/')) && COMPILED_MODULE_PATTERN.test(logicalPath) && !EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
-    const uiClientPaths = files.filter((logicalPath)=>logicalPath.startsWith('public/') && logicalPath !== backendManifestPath && logicalPath !== backendContainerPath);
+    const apiBackendPaths = files.filter(isEffectBffWorkerArtifact);
+    if (!files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath))) throw new Error('[ultramodern-release-envelope] final Cloudflare staging has no actual Effect API/BFF worker artifact.');
+    const ssrPaths = files.filter((logicalPath)=>(logicalPath.startsWith('server/') || logicalPath.startsWith('worker/')) && COMPILED_MODULE_PATTERN.test(logicalPath) && !isEffectBffWorkerArtifact(logicalPath));
+    const uiClientPaths = files.filter((logicalPath)=>logicalPath.startsWith('public/') && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) && logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH && logicalPath !== backendManifestPath && logicalPath !== backendContainerPath);
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.some((path)=>'server/index.mjs' !== path))) throw new Error('[ultramodern-release-envelope] final API-only Cloudflare staging contains an undeclared UI/client or SSR surface.');
     for (const [surface, paths] of [
         [
             'UI/client',
@@ -486,27 +555,32 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
         ],
         [
             'Cloudflare SSR',
-            ssrPaths
+            apiOnly ? [] : ssrPaths
         ],
         [
             'Cloudflare API/backend',
             apiBackendPaths
         ]
-    ])if (0 === paths.length) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`);
+    ])if (0 === paths.length && (!apiOnly || 'Cloudflare API/backend' === surface)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`);
     for (const logicalPath of [
         backendManifestPath,
         backendContainerPath
     ])if (!files.includes(logicalPath)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging is missing ${logicalPath}.`);
-    const clientExecutionPaths = await manifestReferencedClientModules(outputDirectory, files, 'public/mf-manifest.json');
-    const ssrExecutionPaths = await routeReferencedSsrModules(outputDirectory, files, 'cloudflare', 'server/route.json');
-    if (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length) throw new Error('[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.');
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(outputDirectory, files, 'public/mf-manifest.json');
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(outputDirectory, files, 'cloudflare', 'server/route.json');
+    if (!apiOnly && (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length)) throw new Error('[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.');
     const runtimeByPath = new Map();
     for (const logicalPath of files)runtimeByPath.set(logicalPath, 'cloudflare-deployment');
     const add = (paths, runtime)=>{
         for (const logicalPath of paths)runtimeByPath.set(logicalPath, runtime);
     };
     add(uiClientPaths, 'browser');
-    add(ssrPaths, 'workerd');
+    add([
+        ...declaredPublicAssetPaths
+    ], DECLARED_PUBLIC_ASSET_RUNTIME);
+    if (files.includes(CRAWLER_POLICY_PATH)) runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
+    add(files.filter(isPublicMetadataPath), 'public-metadata');
+    add(apiOnly ? [] : ssrPaths, 'workerd');
     add(apiBackendPaths, 'workerd-effect');
     add([
         backendManifestPath
@@ -520,7 +594,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             backendManifestPath,
             backendContainerPath
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/'))
@@ -539,7 +613,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
@@ -552,10 +626,10 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
         }
     };
 };
-const emitCloudflareStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+const emitCloudflareStagedReleaseEnvelope = async ({ declaredPublicAssets = [], distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
     if (!source) return;
-    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, declaredPublicAssets);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'cloudflare',

package/dist/esm-node/release-envelope/index.mjs

@@ -185,7 +185,7 @@ const assertUniqueSortedArtifacts = (artifacts, location)=>{
     if (paths.some((logicalPath, index)=>logicalPath !== sorted[index])) throw new Error(`${location} must be sorted by logicalPath.`);
 };
 const assertSurfacePaths = (value, location)=>{
-    if (!Array.isArray(value) || 0 === value.length) 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}]`));
     const sorted = [
         ...paths
@@ -207,10 +207,16 @@ const assertSurfaces = (value)=>{
         '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 && 0 === ssr.length) throw new Error('surfaces.ssr must contain at least one artifact path when UI/client is declared.');
+    if (ssr.length > 0 && 0 === uiClient.length) throw new Error('surfaces.uiClient must contain at least one artifact path when SSR is declared.');
+    if (0 === apiBackend.length) throw new Error('surfaces.apiBackend must contain at least one artifact path.');
     return {
-        uiClient: assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient'),
-        ssr: assertSurfacePaths(surfaces.ssr, 'surfaces.ssr'),
-        apiBackend: assertSurfacePaths(surfaces.apiBackend, 'surfaces.apiBackend'),
+        uiClient,
+        ssr,
+        apiBackend,
         backendFederation: {
             manifest: assertNormalizedLogicalPath(backendFederation.manifest, 'surfaces.backendFederation.manifest'),
             container: assertNormalizedLogicalPath(backendFederation.container, 'surfaces.backendFederation.container')

package/dist/esm-node/release-envelope/plugin.mjs

@@ -1,48 +1,53 @@
 import "node:module";
 import node_path from "node:path";
+import { NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths } from "../deploy-output/public-assets.mjs";
+import { getDeployingTarget } from "../deploy-output/target.mjs";
 import { emitFrameworkMicroVerticalReleaseEnvelope, emitNodeStagedReleaseEnvelope, verifyBuildOutputReleaseEnvelope, verifyNodeReleaseEnvelopeStaging } from "./framework-output.mjs";
-const resolveActiveDeployTarget = (api, resolveDeployTarget)=>{
-    const { metaName } = api.getAppContext();
-    const config = api.getNormalizedConfig();
-    if ('modern-js' !== metaName && !config.deploy?.target && !process.env.MODERNJS_DEPLOY) return;
-    return resolveDeployTarget(config);
-};
-const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
+const createUltramodernReleaseEnvelopePlugin = ()=>({
         name: '@modern-js/ultramodern-release-envelope',
         pre: [
             '@modern-js/backend-federation-build',
-            '@modern-js/plugin-bff'
+            '@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)=>{
+            const emitBuildEnvelope = async (target, requirePromotable = true)=>{
                 const { apiOnly, distDirectory } = api.getAppContext();
                 await emitFrameworkMicroVerticalReleaseEnvelope({
                     apiOnly,
                     distDirectory,
+                    requirePromotable,
                     target
                 });
             };
             api.onAfterBuild(async ()=>{
-                const configuredTarget = resolveDeployTarget(api.getNormalizedConfig());
+                const configuredTarget = api.getAppContext().deployTarget?.target;
                 if ('node' !== configuredTarget && 'cloudflare' !== configuredTarget) return;
-                await emitBuildEnvelope(configuredTarget);
+                await emitBuildEnvelope(configuredTarget, false);
             });
             api.onBeforeDeploy(async ()=>{
-                const configuredTarget = resolveActiveDeployTarget(api, resolveDeployTarget);
+                const configuredTarget = getDeployingTarget(api.getAppContext());
                 if ('node' !== configuredTarget) return;
                 await emitBuildEnvelope(configuredTarget);
                 const { distDirectory } = api.getAppContext();
                 await verifyBuildOutputReleaseEnvelope(distDirectory, configuredTarget);
             });
             api.onAfterDeploy(async ()=>{
-                const configuredTarget = resolveActiveDeployTarget(api, resolveDeployTarget);
+                const configuredTarget = getDeployingTarget(api.getAppContext());
                 if ('node' !== configuredTarget) return;
                 const { appDirectory, distDirectory } = api.getAppContext();
                 const outputDirectory = node_path.join(appDirectory, '.output');
                 const releaseEnvelope = await emitNodeStagedReleaseEnvelope({
+                    declaredPublicAssets: await resolveAddedDeclaredPublicAssetPaths({
+                        appDirectory,
+                        assets: normalizeDeclaredPublicAssets(api.getNormalizedConfig().deploy?.node?.publicAssets, NODE_PUBLIC_ASSET_SCOPE),
+                        generatedRoot: distDirectory,
+                        scope: NODE_PUBLIC_ASSET_SCOPE
+                    }),
                     distDirectory,
                     outputDirectory
                 });

package/dist/esm-node/release-identity.mjs

@@ -3,14 +3,13 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 const BUILD_MARKER_NAMESPACE = 'ultramodern-delivery-unit-release-build-marker:v1';
 const PROMOTABLE_SOURCE_REVISION_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const workspaceGitEnv = ()=>Object.fromEntries(Object.entries(process.env).filter(([name])=>!name.toUpperCase().startsWith('GIT_')));
 const gitOutput = (workspaceRoot, args)=>{
     try {
-        return execFileSync('git', [
-            '-C',
-            workspaceRoot,
-            ...args
-        ], {
+        return execFileSync('git', args, {
+            cwd: workspaceRoot,
             encoding: 'utf8',
+            env: workspaceGitEnv(),
             stdio: [
                 'ignore',
                 'pipe',
@@ -44,7 +43,7 @@ const resolveUltramodernSourceRevision = (workspaceRoot = process.cwd(), configu
     ]);
     const status = gitOutput(gitRoot, [
         'status',
-        '--porcelain=v1',
+        '--porcelain',
         '--untracked-files=all'
     ]);
     if (!revision || void 0 === status || status.length > 0) return 'workspace';