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

package/dist/cjs/policy-defaults.js

@@ -0,0 +1,101 @@
+"use strict";
+const __rslib_import_meta_url__ = /*#__PURE__*/ function() {
+    return "u" < typeof document ? new (require('url'.replace('', ''))).URL('file:' + __filename).href : document.currentScript && document.currentScript.src || new URL('main.js', document.baseURI).href;
+}();
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    POLICY_DEFAULTS_PLUGIN_NAME: ()=>POLICY_DEFAULTS_PLUGIN_NAME,
+    RENDERER_EXTENSIONS_PACKAGE: ()=>RENDERER_EXTENSIONS_PACKAGE,
+    RENDERER_EXTENSIONS_PLUGIN_NAME: ()=>RENDERER_EXTENSIONS_PLUGIN_NAME,
+    SERVER_EXTENSIONS_PLUGIN_NAME: ()=>SERVER_EXTENSIONS_PLUGIN_NAME,
+    applyPolicyDefaults: ()=>applyPolicyDefaults,
+    createPolicyDefaultsPlugin: ()=>createPolicyDefaultsPlugin
+});
+const external_runtime_package_resolution_js_namespaceObject = require("./runtime-package-resolution.js");
+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 = (0, external_runtime_package_resolution_js_namespaceObject.collectRuntimePackageModuleDirectories)([
+            RENDERER_EXTENSIONS_PACKAGE
+        ], __rslib_import_meta_url__);
+        if (moduleDirectories.length > 0) api.modifyResolvedConfig((config)=>({
+                ...config,
+                builderPlugins: [
+                    ...config.builderPlugins ?? [],
+                    (0, external_runtime_package_resolution_js_namespaceObject.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);
+        }
+    });
+exports.POLICY_DEFAULTS_PLUGIN_NAME = __webpack_exports__.POLICY_DEFAULTS_PLUGIN_NAME;
+exports.RENDERER_EXTENSIONS_PACKAGE = __webpack_exports__.RENDERER_EXTENSIONS_PACKAGE;
+exports.RENDERER_EXTENSIONS_PLUGIN_NAME = __webpack_exports__.RENDERER_EXTENSIONS_PLUGIN_NAME;
+exports.SERVER_EXTENSIONS_PLUGIN_NAME = __webpack_exports__.SERVER_EXTENSIONS_PLUGIN_NAME;
+exports.applyPolicyDefaults = __webpack_exports__.applyPolicyDefaults;
+exports.createPolicyDefaultsPlugin = __webpack_exports__.createPolicyDefaultsPlugin;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "POLICY_DEFAULTS_PLUGIN_NAME",
+    "RENDERER_EXTENSIONS_PACKAGE",
+    "RENDERER_EXTENSIONS_PLUGIN_NAME",
+    "SERVER_EXTENSIONS_PLUGIN_NAME",
+    "applyPolicyDefaults",
+    "createPolicyDefaultsPlugin"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/release-envelope/framework-output.js

@@ -53,7 +53,7 @@ const promises_namespaceObject = require("node:fs/promises");
 var promises_default = /*#__PURE__*/ __webpack_require__.n(promises_namespaceObject);
 const external_node_path_namespaceObject = require("node:path");
 var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
-const universal_namespaceObject = require("@modern-js/utils/universal");
+const backend_federation_contracts_namespaceObject = require("@modern-js/backend-federation-contracts");
 const external_index_js_namespaceObject = require("./index.js");
 const MICROVERTICAL_RELEASE_ENVELOPE_PATH = 'release/microvertical-release-envelope.json';
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_PATH = 'release/microvertical-release-identity-carriers.json';
@@ -61,6 +61,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/${backend_federation_contracts_namespaceObject.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
@@ -73,6 +88,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 = external_node_path_default().posix.dirname(manifestLogicalPath);
+    const routesManifest = await readJson(external_node_path_default().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 = external_node_path_default().posix.join(directory, relative);
+            if (!files.includes(logicalPath)) return [];
+            const assetStat = await promises_default().lstat(external_node_path_default().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(external_node_path_default().join(distDirectory, manifestLogicalPath));
     const references = [
@@ -82,9 +137,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(external_node_path_default().join(distDirectory, routeSpecLogicalPath));
@@ -134,11 +190,14 @@ const writeReleaseEnvelope = async (artifactRoot, envelope)=>{
     if (!envelopePath) throw new Error('[ultramodern-release-envelope] could not resolve release envelope path.');
     await promises_default().writeFile(envelopePath, `${(0, external_index_js_namespaceObject.canonicalSerializeMicroVerticalReleaseEnvelope)(envelope)}\n`);
 };
-const readBuildArtifact = async (distDirectory)=>{
-    const artifactPath = external_node_path_default().join(distDirectory, universal_namespaceObject.ULTRAMODERN_BUILD_ARTIFACT_FILE);
+const readBuildArtifact = async (distDirectory, requirePromotable = true)=>{
+    const artifactPath = external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.ULTRAMODERN_BUILD_ARTIFACT_FILE);
     const artifact = await readJson(artifactPath);
-    if (!(0, universal_namespaceObject.isUltramodernBuildArtifact)(artifact)) throw new Error(`[ultramodern-release-envelope] ${universal_namespaceObject.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 (!(0, backend_federation_contracts_namespaceObject.isUltramodernBuildArtifact)(artifact)) throw new Error(`[ultramodern-release-envelope] ${backend_federation_contracts_namespaceObject.ULTRAMODERN_BUILD_ARTIFACT_FILE} is missing or invalid.`);
+    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)=>{
@@ -154,7 +213,7 @@ const assertIdentityBlock = (value, identity, location, includeReleaseVersion)=>
     for (const [field, expectedValue] of Object.entries(expected))if (value[field] !== expectedValue) throw new Error(`[ultramodern-release-envelope] ${location}.${field} must match ${expectedValue}; received ${String(value[field])}.`);
 };
 const readBackendManifest = async (distDirectory, identity)=>{
-    const manifest = await readJson(external_node_path_default().join(distDirectory, universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE));
+    const manifest = await readJson(external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE));
     if (!isRecord(manifest) || !isRecord(manifest.backendFederation)) throw new Error('[ultramodern-release-envelope] backend federation manifest is missing backendFederation metadata.');
     assertIdentityBlock(manifest.backendFederation.deliveryUnit, identity, 'backendFederation.deliveryUnit', true);
     const versionBoundary = manifest.backendFederation.versionBoundary;
@@ -207,7 +266,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);
@@ -247,12 +306,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',
@@ -261,16 +320,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){
@@ -280,13 +340,15 @@ 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([
-        universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE
     ], 'module-federation-manifest');
     add([
-        universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
     ], 'node' === target ? 'nodejs' : 'commonjs-module');
     const surfaces = {
         uiClient: [
@@ -299,8 +361,8 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
             ...apiBackendPaths
         ].sort((left, right)=>left.localeCompare(right)),
         backendFederation: {
-            manifest: universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-            container: universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            manifest: backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+            container: backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
         }
     };
     const artifacts = [
@@ -309,8 +371,8 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
     const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(distDirectory, identity, {
         apiBackend: apiBackendPaths,
         backendFederation: [
-            universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-            universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+            backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
         ],
         ssr: [
             ...new Set([
@@ -336,17 +398,17 @@ const pathExists = async (filePath)=>{
         return false;
     }
 };
-const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, target })=>{
-    if (apiOnly) return;
-    const backendManifestPath = external_node_path_default().join(distDirectory, universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE);
-    const backendContainerPath = external_node_path_default().join(distDirectory, universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE);
+const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, requirePromotable = true, target })=>{
+    const backendManifestPath = external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE);
+    const backendContainerPath = external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.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,
@@ -354,7 +416,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 (0, external_index_js_namespaceObject.createMicroVerticalReleaseEnvelope)({
         artifactRoot: distDirectory,
         target,
@@ -385,19 +447,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(external_node_path_default().join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
-        pathExists(external_node_path_default().join(distDirectory, universal_namespaceObject.ULTRAMODERN_BUILD_ARTIFACT_FILE)),
-        pathExists(external_node_path_default().join(distDirectory, universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE)),
-        pathExists(external_node_path_default().join(distDirectory, universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE))
+        pathExists(external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.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({
@@ -405,21 +464,22 @@ 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',
-        universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-        universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
     ])if (!files.includes(requiredPath)) throw new Error(`[ultramodern-release-envelope] final Node staging is missing ${requiredPath}.`);
     const backendFederationPaths = new Set([
-        universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-        universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+        backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
     ]);
     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',
@@ -430,6 +490,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',
@@ -437,32 +498,35 @@ 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(universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
-    runtimeByPath.set(universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
+    runtimeByPath.set(backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
+    runtimeByPath.set(backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
     const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(outputDirectory, identity, {
         apiBackend: apiBackendPaths,
         backendFederation: [
-            universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-            universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+            backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>'index.js' !== logicalPath)
@@ -481,23 +545,23 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
                 ...apiBackendPaths
             ].sort((left, right)=>left.localeCompare(right)),
             backendFederation: {
-                manifest: universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
-                container: universal_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+                manifest: backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE,
+                container: backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE
             }
         }
     };
 };
-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 (0, external_index_js_namespaceObject.createMicroVerticalReleaseEnvelope)({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -515,21 +579,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/${universal_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE}`;
-    const backendContainerPath = `public/${universal_namespaceObject.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 backendManifestPath = `public/${backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE}`;
+    const backendContainerPath = `public/${backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`;
+    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',
@@ -537,27 +606,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
@@ -571,7 +645,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             backendManifestPath,
             backendContainerPath
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/'))
@@ -590,7 +664,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: [
@@ -603,10 +677,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 (0, external_index_js_namespaceObject.createMicroVerticalReleaseEnvelope)({
         artifactRoot: outputDirectory,
         target: 'cloudflare',

package/dist/cjs/release-envelope/index.js

@@ -232,7 +232,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
@@ -254,10 +254,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')