@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.11 → 3.9.0-ultramodern.13

package/dist/cjs/config.js

@@ -28,15 +28,19 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    createRemoteManifestUrl: ()=>remote_address_js_namespaceObject.createRemoteManifestUrl,
     getBuildConfigEnvironment: ()=>public_js_namespaceObject.getBuildConfigEnvironment,
     resolveEffectTsgoCompiler: ()=>public_js_namespaceObject.resolveEffectTsgoCompiler,
     withBuildConfigEnvironment: ()=>public_js_namespaceObject.withBuildConfigEnvironment
 });
 const public_js_namespaceObject = require("./build-config/public.js");
+const remote_address_js_namespaceObject = require("./build-config/remote-address.js");
+exports.createRemoteManifestUrl = __webpack_exports__.createRemoteManifestUrl;
 exports.getBuildConfigEnvironment = __webpack_exports__.getBuildConfigEnvironment;
 exports.resolveEffectTsgoCompiler = __webpack_exports__.resolveEffectTsgoCompiler;
 exports.withBuildConfigEnvironment = __webpack_exports__.withBuildConfigEnvironment;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createRemoteManifestUrl",
     "getBuildConfigEnvironment",
     "resolveEffectTsgoCompiler",
     "withBuildConfigEnvironment"

package/dist/cjs/deploy-output/npmAliases.js

@@ -48,6 +48,10 @@ const dependencyKeys = [
     'dependencies',
     'optionalDependencies'
 ];
+const rootDependencyKeys = [
+    ...dependencyKeys,
+    'devDependencies'
+];
 const exactVersionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
 async function readPackageJson(filePath) {
     return JSON.parse(await promises_default().readFile(filePath, 'utf8'));
@@ -63,14 +67,34 @@ function parseNpmAlias(aliasName, specifier) {
         targetVersion: target.slice(versionSeparator + 1)
     };
 }
-function aliasesFromPackageJson(packageJson) {
+function aliasesFromPackageJson(packageJson, keys = dependencyKeys) {
     const aliases = [];
-    for (const dependencyKey of dependencyKeys)for (const [aliasName, specifier] of Object.entries(packageJson[dependencyKey] ?? {})){
+    for (const dependencyKey of keys)for (const [aliasName, specifier] of Object.entries(packageJson[dependencyKey] ?? {})){
         const alias = parseNpmAlias(aliasName, specifier);
         if (alias) aliases.push(alias);
     }
     return aliases;
 }
+async function catalogAliasesFromInstalledPackages(appDirectory, packageJson) {
+    const aliases = [];
+    for (const dependencyKey of rootDependencyKeys)for (const [aliasName, specifier] of Object.entries(packageJson[dependencyKey] ?? {})){
+        if (!specifier.startsWith('catalog:')) continue;
+        let installedPackage;
+        try {
+            installedPackage = await readPackageJson(external_node_path_default().join(appDirectory, 'node_modules', aliasName, 'package.json'));
+        } catch (error) {
+            if ('ENOENT' === error.code) continue;
+            throw error;
+        }
+        if (!installedPackage.name || !installedPackage.version) throw new Error(`Installed catalog package ${aliasName} has no identity`);
+        if (installedPackage.name !== aliasName) aliases.push({
+            aliasName,
+            targetName: installedPackage.name,
+            targetVersion: installedPackage.version
+        });
+    }
+    return aliases;
+}
 async function collectPackageRecords(nodeModulesDirectory) {
     const records = [];
     const visitedNodeModules = new Set();
@@ -192,7 +216,8 @@ async function preserveNpmAliases({ appDirectory, outputDirectory, implicitAlias
     const records = await collectPackageRecords(external_node_path_default().join(outputDirectory, 'node_modules'));
     const appPackageJson = await readPackageJson(external_node_path_default().join(appDirectory, 'package.json'));
     const rootAliases = [
-        ...aliasesFromPackageJson(appPackageJson),
+        ...aliasesFromPackageJson(appPackageJson, rootDependencyKeys),
+        ...await catalogAliasesFromInstalledPackages(appDirectory, appPackageJson),
         ...implicitAliases
     ].filter((alias)=>alias.aliasName !== alias.targetName);
     const emittedRootAliases = [];

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

@@ -61,6 +61,11 @@ 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 isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
 const flattenStrings = (value)=>'string' == typeof value ? [
         value
@@ -181,7 +186,7 @@ const readBuildArtifact = async (distDirectory, requirePromotable = true)=>{
     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 full-stack envelope.');
+        throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.');
     }
     return artifact;
 };
@@ -251,7 +256,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);
@@ -291,12 +296,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',
@@ -305,16 +310,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){
@@ -324,6 +330,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([
@@ -381,15 +389,14 @@ const pathExists = async (filePath)=>{
     }
 };
 const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, requirePromotable = true, target })=>{
-    if (apiOnly) return;
     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.');
+    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 = {
@@ -399,7 +406,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,
@@ -430,19 +437,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, backend_federation_contracts_namespaceObject.ULTRAMODERN_BUILD_ARTIFACT_FILE)),
-        pathExists(external_node_path_default().join(distDirectory, backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE)),
-        pathExists(external_node_path_default().join(distDirectory, backend_federation_contracts_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({
@@ -450,7 +454,7 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly)=>{
     const files = await collectFiles(outputDirectory);
     for (const requiredPath of [
         'index.js',
@@ -464,7 +468,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) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -475,6 +479,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',
@@ -482,22 +487,24 @@ 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');
+    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_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
     runtimeByPath.set(backend_federation_contracts_namespaceObject.BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
@@ -507,7 +514,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             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)
@@ -526,7 +533,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: [
@@ -542,7 +549,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
 const emitNodeStagedReleaseEnvelope = async ({ 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);
     const staged = await (0, external_index_js_namespaceObject.createMicroVerticalReleaseEnvelope)({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -560,21 +567,25 @@ 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)=>{
     const files = await collectFiles(outputDirectory);
     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_contracts_namespaceObject.BACKEND_FEDERATION_MANIFEST_FILE}`;
     const backendContainerPath = `public/${backend_federation_contracts_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 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) && 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',
@@ -582,27 +593,29 @@ 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');
+    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
@@ -616,7 +629,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             backendManifestPath,
             backendContainerPath
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/'))
@@ -635,7 +648,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: [
@@ -651,7 +664,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
 const emitCloudflareStagedReleaseEnvelope = async ({ 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);
     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')

package/dist/esm/backend-federation-build/codegen.mjs

@@ -170,8 +170,13 @@ const createBackendManifest = (workspaceRoot, distDirectory, app, entryIntegrity
             source: {
                 module: sourceModule
             },
-            readinessPath: `${app.apiPrefix}/${app.apiStem}/readiness`,
-            openapiPath: `${app.apiPrefix}/openapi.json`,
+            ...'rpc' === app.apiProtocol ? {
+                rpcPath: app.rpcPath,
+                rpcSerialization: 'json'
+            } : {
+                readinessPath: `${app.apiPrefix}/${app.apiStem}/readiness`,
+                openapiPath: `${app.apiPrefix}/openapi.json`
+            },
             ...app.deliveryUnit ? {
                 deliveryUnit: app.deliveryUnit
             } : {},

package/dist/esm/backend-federation-build/config.mjs

@@ -3,7 +3,8 @@ import promises from "node:fs/promises";
 import node_path from "node:path";
 import { resolveUltramodernSourceRevision } from "@modern-js/app-tools-extensions/release-identity";
 import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, DELIVERY_UNIT_DEPLOY_PROFILE, DELIVERY_UNIT_KIND, DELIVERY_UNIT_SCHEMA_VERSION, ULTRAMODERN_BUILD_ARTIFACT_PATH, deliveryUnitContractBlock, isUltramodernBuildArtifact, validateDeliveryUnitRecord, validateUltramodernBuildArtifact } from "@modern-js/backend-federation-contracts";
-const COMPACT_CONFIG_PATH = '.modernjs/ultramodern.json';
+const REFERENCE_TOPOLOGY_PATH = 'topology/reference-topology.json';
+const DEVELOPMENT_OVERLAY_PATH = 'topology/local-overlays/development.json';
 const normalizeRelativePath = (value)=>value.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
 const isRecord = (value)=>'object' == typeof value && null !== value;
 const readJsonFile = async (filePath)=>JSON.parse(await promises.readFile(filePath, 'utf8'));
@@ -31,15 +32,25 @@ const readBuildIdentity = async (appDirectory)=>{
 const toPascalCase = (value)=>value.split(/[^a-zA-Z0-9]+/u).filter(Boolean).map((part)=>part.charAt(0).toUpperCase() + part.slice(1)).join('');
 const stringValue = (value)=>'string' == typeof value && value.length > 0 ? value : void 0;
 const createBackendName = (app, id)=>{
-    const configuredName = stringValue(app.backendFederation?.name) ?? stringValue(app.backendFederation?.executionSurfaces?.node?.remoteName) ?? stringValue(app.serverExecution?.node?.remoteName);
+    const configuredName = stringValue(app.backendFederation?.name) ?? stringValue(app.backendFederation?.executionSurfaces?.node?.remoteName);
     if (configuredName) return configuredName;
     const mfName = stringValue(app.moduleFederation?.name);
     return mfName ? `${mfName}Backend` : `vertical${toPascalCase(id)}Backend`;
 };
+const rebaseDefaultLocalUrl = (value, defaultPort, publicOrigin)=>{
+    let url;
+    try {
+        url = new URL(value);
+    } catch  {
+        return value;
+    }
+    if ('http:' !== url.protocol || 'localhost' !== url.hostname || Number(url.port) !== defaultPort || url.username || url.password) return value;
+    return `${publicOrigin}${url.pathname}${url.search}${url.hash}`;
+};
 const findWorkspaceRoot = (appDirectory)=>{
     let current = appDirectory;
     while(true){
-        if (existsSync(node_path.join(current, COMPACT_CONFIG_PATH))) return current;
+        if (existsSync(node_path.join(current, REFERENCE_TOPOLOGY_PATH))) return current;
         const parent = node_path.dirname(current);
         if (parent === current) return;
         current = parent;
@@ -63,54 +74,90 @@ const createStampedDeliveryUnit = (input)=>{
     if (!validation.ok) return;
     return deliveryUnitContractBlock(record);
 };
-const createAppFromCompactMetadata = (workspaceRoot, appDirectory, compactApp)=>{
-    const id = stringValue(compactApp.id);
-    const appPath = stringValue(compactApp.path);
-    if (!id || 'vertical' !== compactApp.kind || !isRecord(compactApp.api)) return;
-    const directory = appPath ? normalizeRelativePath(appPath) : `verticals/${id}`;
+const createAppFromTopology = (workspaceRoot, appDirectory, topologyApp, overlay, packageManifest)=>{
+    const id = stringValue(topologyApp.id);
+    const appPath = stringValue(topologyApp.path);
+    if (!id || !appPath || 'vertical' !== topologyApp.kind || !isRecord(topologyApp.api) || !isRecord(topologyApp.backendFederation)) return;
+    const directory = normalizeRelativePath(appPath);
     if (node_path.resolve(workspaceRoot, directory) !== node_path.resolve(appDirectory)) return;
-    const port = 'number' == typeof compactApp.port ? compactApp.port : void 0;
-    if (void 0 === port) return;
-    const apiPrefix = stringValue(compactApp.api.prefix) ?? `/${id}-api`;
-    const apiStem = stringValue(compactApp.api.stem) ?? id;
-    const backendName = createBackendName(compactApp, id);
-    const manifestUrl = stringValue(compactApp.backendFederation?.executionSurfaces?.node?.manifestUrl) ?? stringValue(compactApp.serverExecution?.node?.manifestUrl) ?? `http://localhost:${port}/${BACKEND_FEDERATION_MANIFEST_FILE}`;
-    const containerEntry = stringValue(compactApp.backendFederation?.executionSurfaces?.node?.containerEntry) ?? stringValue(compactApp.serverExecution?.node?.containerEntry) ?? `http://localhost:${port}/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`;
-    const configuredRemoteType = stringValue(compactApp.backendFederation?.executionSurfaces?.node?.remoteType) ?? stringValue(compactApp.serverExecution?.node?.remoteType);
+    const defaultPort = overlay.ports?.[id];
+    if ('number' != typeof defaultPort || !Number.isInteger(defaultPort) || defaultPort < 1 || defaultPort > 65535) throw new Error(`[backend-federation-build] Invalid development port for ${id}.`);
+    const portEnv = stringValue(topologyApp.portEnv) ?? `VERTICAL_${(stringValue(topologyApp.domain) ?? id).replace(/[^a-zA-Z0-9]/gu, '_').toUpperCase()}_PORT`;
+    const port = Number(process.env[portEnv] ?? defaultPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`[backend-federation-build] Invalid ${portEnv} development port for ${id}.`);
+    const publicUrlEnv = stringValue(topologyApp.cloudflare?.publicUrlEnv);
+    const configuredPublicUrl = publicUrlEnv ? process.env[publicUrlEnv]?.trim() : void 0;
+    let publicOrigin = `http://localhost:${port}`;
+    if (configuredPublicUrl) {
+        let url;
+        try {
+            url = new URL(configuredPublicUrl);
+        } catch  {
+            throw new Error(`[backend-federation-build] Invalid ${publicUrlEnv} public URL for ${id}.`);
+        }
+        if (![
+            'http:',
+            'https:'
+        ].includes(url.protocol) || url.username || url.password) throw new Error(`[backend-federation-build] Invalid ${publicUrlEnv} public URL for ${id}.`);
+        publicOrigin = url.origin;
+    }
+    const apiPrefix = stringValue(topologyApp.api.bff?.prefix) ?? `/${id}-api`;
+    const apiProtocol = topologyApp.api.protocol ?? 'rest';
+    if ('rest' !== apiProtocol && 'rpc' !== apiProtocol) throw new Error(`[backend-federation-build] Unsupported API protocol for ${id}.`);
+    const rpcPath = 'rpc' === apiProtocol ? stringValue(topologyApp.api.rpcPath) : void 0;
+    if ('rpc' === apiProtocol && (!rpcPath || 'json' !== topologyApp.api.rpcSerialization)) throw new Error(`[backend-federation-build] Missing JSON RPC route metadata for ${id}.`);
+    const apiStem = stringValue(topologyApp.api.stem) ?? id;
+    const backendName = createBackendName(topologyApp, id);
+    const nodeOverlay = overlay.serverExecution?.[id]?.node;
+    if (!isRecord(nodeOverlay)) throw new Error(`[backend-federation-build] Missing declared Node server execution for ${id}.`);
+    const manifestUrl = rebaseDefaultLocalUrl(stringValue(nodeOverlay?.manifestUrl) ?? `http://localhost:${defaultPort}/${BACKEND_FEDERATION_MANIFEST_FILE}`, defaultPort, publicOrigin);
+    const containerEntry = rebaseDefaultLocalUrl(stringValue(nodeOverlay?.containerEntry) ?? `http://localhost:${defaultPort}/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`, defaultPort, publicOrigin);
+    const configuredRemoteType = stringValue(nodeOverlay?.remoteType) ?? stringValue(topologyApp.backendFederation?.executionSurfaces?.node?.remoteType);
     if (void 0 !== configuredRemoteType && 'commonjs-module' !== configuredRemoteType) throw new Error(`[backend-federation-build] Node backend federation remoteType must be "commonjs-module"; received "${configuredRemoteType}" for ${id}.`);
     if (!new URL(containerEntry).pathname.endsWith(`/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`)) throw new Error(`[backend-federation-build] Node backend federation containerEntry must end with "/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}"; received "${containerEntry}" for ${id}.`);
     const remoteType = 'commonjs-module';
-    const packageName = stringValue(compactApp.package);
-    const uiManifestUrl = stringValue(compactApp.backendFederation?.versionBoundary?.ui?.manifestUrl) ?? stringValue(compactApp.moduleFederation?.manifestUrl);
-    const compactDeliveryUnit = isRecord(compactApp.deliveryUnit) ? {
-        unitId: stringValue(compactApp.deliveryUnit.unitId),
-        buildMarker: stringValue(compactApp.deliveryUnit.buildMarker),
-        sourceRevision: stringValue(compactApp.deliveryUnit.sourceRevision),
-        packageName: stringValue(compactApp.deliveryUnit.packageName),
-        version: stringValue(compactApp.deliveryUnit.version)
+    const packageName = stringValue(packageManifest.name);
+    const version = stringValue(packageManifest.version);
+    if (stringValue(topologyApp.package) !== packageName || !version) throw new Error(`[backend-federation-build] Topology package identity must match package.json for ${id}.`);
+    const declaredUiManifestUrl = stringValue(overlay.manifests?.[id]);
+    const uiManifestUrl = declaredUiManifestUrl ? rebaseDefaultLocalUrl(declaredUiManifestUrl, defaultPort, publicOrigin) : void 0;
+    const topologyDeliveryUnit = isRecord(topologyApp.deliveryUnit) ? {
+        unitId: stringValue(topologyApp.deliveryUnit.unitId),
+        buildMarker: stringValue(topologyApp.deliveryUnit.buildMarker),
+        sourceRevision: stringValue(topologyApp.deliveryUnit.sourceRevision),
+        packageName: stringValue(topologyApp.deliveryUnit.packageName),
+        version: stringValue(topologyApp.deliveryUnit.version)
     } : void 0;
     return {
         id,
         directory,
         packageName,
+        version,
         port,
         apiPrefix,
+        apiProtocol,
+        rpcPath,
         apiStem,
         backendName,
         manifestUrl,
         containerEntry,
         remoteType,
         uiManifestUrl,
-        compactDeliveryUnit
+        topologyDeliveryUnit
     };
 };
 const findBackendFederationApp = async (workspaceRoot, appDirectory)=>{
-    const compactConfigPath = node_path.join(workspaceRoot, COMPACT_CONFIG_PATH);
-    const compactConfig = await readJsonFile(compactConfigPath);
-    const apps = Array.isArray(compactConfig.topology?.apps) ? compactConfig.topology.apps : [];
-    for (const app of apps){
-        const resolved = createAppFromCompactMetadata(workspaceRoot, appDirectory, app);
+    const topologyPath = node_path.join(workspaceRoot, REFERENCE_TOPOLOGY_PATH);
+    const topology = await readJsonFile(topologyPath);
+    if (!isRecord(topology) || !Array.isArray(topology.verticals)) throw new Error(`[backend-federation-build] Invalid declared topology at ${topologyPath}.`);
+    const overlayPath = node_path.join(workspaceRoot, DEVELOPMENT_OVERLAY_PATH);
+    const overlay = await readJsonFile(overlayPath);
+    if (!isRecord(overlay) || !isRecord(overlay.ports)) throw new Error(`[backend-federation-build] Invalid development overlay at ${overlayPath}.`);
+    const packageManifest = await readJsonFile(node_path.join(appDirectory, 'package.json'));
+    for (const app of topology.verticals){
+        const resolved = createAppFromTopology(workspaceRoot, appDirectory, app, overlay, packageManifest);
         if (resolved) return resolved;
     }
+    throw new Error(`[backend-federation-build] ${appDirectory} is missing from the declared reference topology.`);
 };
-export { COMPACT_CONFIG_PATH, buildArtifactPathFor, createAppFromCompactMetadata, createStampedDeliveryUnit, findBackendFederationApp, findWorkspaceRoot, normalizeRelativePath, readBuildIdentity, resolveWorkspaceSourceRevision };
+export { DEVELOPMENT_OVERLAY_PATH, REFERENCE_TOPOLOGY_PATH, buildArtifactPathFor, createAppFromTopology, createStampedDeliveryUnit, findBackendFederationApp, findWorkspaceRoot, normalizeRelativePath, readBuildIdentity, resolveWorkspaceSourceRevision };