@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.15 → 3.9.0-ultramodern.16

package/dist/esm/deploy-output/public-assets.mjs

@@ -0,0 +1,82 @@
+import promises from "node:fs/promises";
+import node_path from "node:path";
+import { normalizeRelativePath } from "../cloudflare/utils.mjs";
+const DECLARED_PUBLIC_ASSET_DIRECTORY = 'public';
+const CLOUDFLARE_PUBLIC_ASSET_SCOPE = {
+    label: 'deploy.worker.publicAssets',
+    output: 'Cloudflare public output'
+};
+const NODE_PUBLIC_ASSET_SCOPE = {
+    label: 'deploy.node.publicAssets',
+    output: 'Node public output'
+};
+const normalizeDeclaredPublicAssets = (assets, scope)=>(assets ?? []).map((asset, index)=>({
+            from: normalizeRelativePath(asset?.from, `${scope.label}[${index}].from`, 'app root'),
+            to: normalizeRelativePath(asset?.to, `${scope.label}[${index}].to`, scope.output, {
+                allowRoot: true
+            }),
+            index
+        }));
+const isMissingPathError = (error)=>error instanceof Error && 'code' in error && 'ENOENT' === error.code;
+const pathExists = async (filePath)=>{
+    try {
+        await promises.lstat(filePath);
+        return true;
+    } catch (error) {
+        if (isMissingPathError(error)) return false;
+        throw error;
+    }
+};
+const listDeclaredPublicAssetFiles = async (appDirectory, assets, scope)=>{
+    const files = [];
+    const owners = new Map();
+    const add = (index, logicalPath)=>{
+        const owner = owners.get(logicalPath);
+        if (void 0 !== owner) throw new Error(`${scope.label}[${index}] and ${scope.label}[${owner}] both stage ${JSON.stringify(logicalPath)}.`);
+        owners.set(logicalPath, index);
+        files.push({
+            index,
+            logicalPath
+        });
+    };
+    const visit = async (asset, sourcePath, destination)=>{
+        const stat = await promises.lstat(sourcePath);
+        if (stat.isSymbolicLink()) throw new Error(`${scope.label}[${asset.index}].from must not contain symbolic links: ${node_path.relative(appDirectory, sourcePath).replace(/\\/gu, '/')}`);
+        if (stat.isFile()) {
+            if (destination === DECLARED_PUBLIC_ASSET_DIRECTORY) throw new Error(`${scope.label}[${asset.index}].to must name a file when ${scope.label}[${asset.index}].from is a file.`);
+            add(asset.index, destination);
+            return;
+        }
+        if (!stat.isDirectory()) throw new Error(`${scope.label}[${asset.index}].from must contain only files and directories: ${node_path.relative(appDirectory, sourcePath).replace(/\\/gu, '/')}`);
+        const entries = (await promises.readdir(sourcePath)).sort();
+        for (const entry of entries)await visit(asset, node_path.join(sourcePath, entry), node_path.posix.join(destination, entry));
+    };
+    for (const asset of assets){
+        const sourcePath = node_path.join(appDirectory, asset.from);
+        if (!await pathExists(sourcePath)) throw new Error(`${scope.label}[${asset.index}].from does not exist: ${asset.from}`);
+        await visit(asset, sourcePath, node_path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to));
+    }
+    return files;
+};
+const resolveAddedDeclaredPublicAssetPaths = async ({ appDirectory, assets, generatedRoot, scope })=>{
+    const added = [];
+    for (const file of (await listDeclaredPublicAssetFiles(appDirectory, assets, scope)))if (!await pathExists(node_path.join(generatedRoot, file.logicalPath))) added.push(file.logicalPath);
+    return added.sort();
+};
+const stageDeclaredPublicAssets = async ({ appDirectory, outputDirectory, assets, scope })=>{
+    const files = await listDeclaredPublicAssetFiles(appDirectory, assets, scope);
+    const added = [];
+    for (const file of files){
+        const asset = assets.find((candidate)=>candidate.index === file.index);
+        const relativePath = node_path.posix.relative(node_path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to), file.logicalPath);
+        const destination = node_path.join(outputDirectory, file.logicalPath);
+        const replacesGeneratedFile = await pathExists(destination);
+        await promises.mkdir(node_path.dirname(destination), {
+            recursive: true
+        });
+        await promises.copyFile(node_path.join(appDirectory, asset.from, relativePath), destination);
+        if (!replacesGeneratedFile) added.push(file.logicalPath);
+    }
+    return added.sort();
+};
+export { CLOUDFLARE_PUBLIC_ASSET_SCOPE, DECLARED_PUBLIC_ASSET_DIRECTORY, NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths, stageDeclaredPublicAssets };

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

@@ -14,6 +14,16 @@ const isEffectBffWorkerArtifact = (logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(
 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
@@ -402,8 +412,9 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly)=>{
+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',
@@ -416,7 +427,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity,
     ]);
     const uiClientPaths = files.filter((logicalPath)=>{
         const topLevel = logicalPath.split('/')[0];
-        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -450,6 +461,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity,
             'nodejs-deployment'
         ]));
     for (const logicalPath of uiClientPaths)runtimeByPath.set(logicalPath, 'browser');
+    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');
@@ -494,10 +506,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, 0 === source.surfaces.uiClient.length);
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, declaredPublicAssets);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -515,8 +527,9 @@ 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, apiOnly)=>{
+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',
@@ -532,7 +545,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
     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);
+    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 [
         [
@@ -561,6 +574,9 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
         for (const logicalPath of paths)runtimeByPath.set(logicalPath, runtime);
     };
     add(uiClientPaths, 'browser');
+    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');
@@ -609,10 +625,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, 0 === source.surfaces.uiClient.length);
+    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/release-envelope/plugin.mjs

@@ -1,4 +1,5 @@
 import node_path from "node:path";
+import { NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths } from "../deploy-output/public-assets.mjs";
 import { emitFrameworkMicroVerticalReleaseEnvelope, emitNodeStagedReleaseEnvelope, verifyBuildOutputReleaseEnvelope, verifyNodeReleaseEnvelopeStaging } from "./framework-output.mjs";
 const resolveActiveDeployTarget = (api, resolveDeployTarget)=>{
     const { metaName } = api.getAppContext();
@@ -11,7 +12,8 @@ const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
         pre: [
             '@modern-js/backend-federation-build',
             '@modern-js/plugin-bff',
-            '@modern-js/deploy-output-aliases'
+            '@modern-js/deploy-output-aliases',
+            '@modern-js/deploy-output-public-assets'
         ],
         post: [
             '@modern-js/plugin-deploy'
@@ -44,6 +46,12 @@ const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
                 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/templates/cloudflare-entry.005-worker-dispatch.mjs

@@ -160,14 +160,46 @@ async function dispatchRouteWorker(route, request, env, ctx) {
   );
 }
 
-function matchesPrefix(pathname, prefix) {
+// Worker Static Assets decode percent-encoded paths, so an encoded spelling
+// of a mounted prefix (`/%70refix/...`, `/prefix%2F...`) would otherwise skip
+// the BFF or service binding that owns the prefix and reach ASSETS directly.
+// Resolve such spellings to the canonical pathname the owner sees; a
+// backslash or undecodable spelling becomes a path the owner rejects.
+function resolvePrefixPathname(pathname, prefix) {
   if (!prefix || prefix === '/') {
-    return true;
+    return pathname;
   }
 
   const normalized = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  let candidate = pathname;
+
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    if (candidate === normalized || candidate.startsWith(`${normalized}/`)) {
+      return candidate;
+    }
+    if (candidate.startsWith(`${normalized}\\`)) {
+      return `${normalized}/__invalid_encoded_path__`;
+    }
+
+    let decoded;
+    try {
+      decoded = decodeURIComponent(candidate);
+    } catch {
+      return candidate.toLowerCase().startsWith(normalized.toLowerCase())
+        ? `${normalized}/__invalid_encoded_path__`
+        : null;
+    }
+    if (decoded === candidate) {
+      return null;
+    }
+    candidate = decoded;
+  }
 
-  return pathname === normalized || pathname.startsWith(`${normalized}/`);
+  return null;
+}
+
+function matchesPrefix(pathname, prefix) {
+  return resolvePrefixPathname(pathname, prefix) !== null;
 }
 
 function createRequestForMountedPrefix(request, prefix) {
@@ -177,12 +209,13 @@ function createRequestForMountedPrefix(request, prefix) {
 
   const url = new URL(request.url);
   const normalized = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  const matchedPathname = resolvePrefixPathname(url.pathname, normalized);
 
-  if (!matchesPrefix(url.pathname, normalized)) {
+  if (matchedPathname === null) {
     return request;
   }
 
-  const nextPath = url.pathname.slice(normalized.length) || '/';
+  const nextPath = matchedPathname.slice(normalized.length) || '/';
   url.pathname = nextPath.startsWith('/') ? nextPath : `/${nextPath}`;
 
   return new Request(url, request);
@@ -309,12 +342,21 @@ function getEffectBffDispatcher(bff, runtime) {
 async function dispatchBffRequest(request, env) {
   const bff = MODERN_WORKER_MANIFEST.bff;
 
-  if (
-    !bff?.worker ||
-    !matchesPrefix(new URL(request.url).pathname, bff.prefix)
-  ) {
+  const requestUrl = new URL(request.url);
+  const matchedPathname = resolvePrefixPathname(
+    requestUrl.pathname,
+    bff?.prefix,
+  );
+  if (!bff?.worker || matchedPathname === null) {
     return null;
   }
+  const canonicalRequest =
+    matchedPathname === requestUrl.pathname
+      ? request
+      : new Request(
+          Object.assign(requestUrl, { pathname: matchedPathname }),
+          request,
+        );
   if (bff.runtimeFramework !== 'effect') {
     return createEffectBffDispatcherErrorResponse(
       bff,
@@ -347,7 +389,7 @@ async function dispatchBffRequest(request, env) {
       return createEffectBffDispatcherErrorResponse(bff, error);
     }
 
-    return effectDispatcher.dispatch(request, { env });
+    return effectDispatcher.dispatch(canonicalRequest, { env });
   }
 
   const directHandler =

package/dist/esm-node/cloudflare/artifacts.mjs

@@ -1,6 +1,7 @@
 import "node:module";
 import node_path from "node:path";
 import { fs } from "@modern-js/utils";
+import { CLOUDFLARE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, stageDeclaredPublicAssets } from "../deploy-output/public-assets.mjs";
 import { RESERVED_ARTIFACT_DESTINATION_DIRECTORIES, RESERVED_ARTIFACT_DESTINATION_FILES, ROUTE_SPEC_OUTPUT } from "./constants.mjs";
 import { normalizeRelativePath } from "./utils.mjs";
 const normalizeCloudflareArtifact = (artifact, index)=>{
@@ -16,18 +17,7 @@ const normalizeCloudflareArtifact = (artifact, index)=>{
     };
 };
 const getCloudflareArtifacts = (modernConfig)=>(modernConfig.deploy?.worker?.artifacts ?? []).map(normalizeCloudflareArtifact);
-const normalizeCloudflarePublicAsset = (asset, index)=>{
-    const from = normalizeRelativePath(asset.from, `deploy.worker.publicAssets[${index}].from`, 'app root');
-    const to = normalizeRelativePath(asset.to, `deploy.worker.publicAssets[${index}].to`, 'Cloudflare public output', {
-        allowRoot: true
-    });
-    return {
-        from,
-        to,
-        index
-    };
-};
-const getCloudflarePublicAssets = (modernConfig)=>(modernConfig.deploy?.worker?.publicAssets ?? []).map(normalizeCloudflarePublicAsset);
+const getCloudflarePublicAssets = (modernConfig)=>normalizeDeclaredPublicAssets(modernConfig.deploy?.worker?.publicAssets, CLOUDFLARE_PUBLIC_ASSET_SCOPE);
 const copyCloudflareArtifacts = async (appDirectory, outputDirectory, artifacts)=>{
     for (const artifact of artifacts){
         const sourcePath = node_path.join(appDirectory, artifact.from);
@@ -35,13 +25,12 @@ const copyCloudflareArtifacts = async (appDirectory, outputDirectory, artifacts)
         await fs.copy(sourcePath, node_path.join(outputDirectory, artifact.to));
     }
 };
-const copyCloudflarePublicAssets = async (appDirectory, publicDirectory, publicAssets)=>{
-    for (const asset of publicAssets){
-        const sourcePath = node_path.join(appDirectory, asset.from);
-        if (!await fs.pathExists(sourcePath)) throw new Error(`deploy.worker.publicAssets[${asset.index}].from does not exist: ${asset.from}`);
-        await fs.copy(sourcePath, node_path.join(publicDirectory, asset.to));
-    }
-};
+const copyCloudflarePublicAssets = async (appDirectory, outputDirectory, publicAssets)=>stageDeclaredPublicAssets({
+        appDirectory,
+        outputDirectory,
+        assets: publicAssets,
+        scope: CLOUDFLARE_PUBLIC_ASSET_SCOPE
+    });
 const copyCloudflareD1Migrations = async (appDirectory, outputDirectory, modernConfig)=>{
     for (const [index, database] of (modernConfig.deploy?.worker?.d1Databases ?? []).entries()){
         if (!database.migrationsDir) continue;

package/dist/esm-node/cloudflare/index.mjs

@@ -33,6 +33,7 @@ const createCloudflarePreset = ({ api, appContext, modernConfig })=>{
     const publicAssetExcludes = getPublicAssetExcludes(appDirectory, modernConfig);
     const releaseEnvelopeEnabled = api.isPluginExists('@modern-js/ultramodern-release-envelope');
     let hasReleaseEnvelope = false;
+    let declaredPublicAssets = [];
     return {
         async prepare () {
             await fs.remove(outputDirectory);
@@ -75,7 +76,7 @@ const createCloudflarePreset = ({ api, appContext, modernConfig })=>{
                 await fs.writeJSON(outputPlan.paths.workerPackage, outputPlan.packages.worker);
             }
             await copyCloudflareArtifacts(appDirectory, outputDirectory, cloudflareArtifacts);
-            await copyCloudflarePublicAssets(appDirectory, publicDirectory, getCloudflarePublicAssets(modernConfig));
+            declaredPublicAssets = await copyCloudflarePublicAssets(appDirectory, outputDirectory, getCloudflarePublicAssets(modernConfig));
             await copyCloudflareD1Migrations(appDirectory, outputDirectory, modernConfig);
             await fs.writeJSON(wranglerConfigPath, createWranglerConfig(appDirectory, modernConfig), {
                 spaces: 2
@@ -104,6 +105,7 @@ const createCloudflarePreset = ({ api, appContext, modernConfig })=>{
             });
             if (hasReleaseEnvelope) {
                 await emitCloudflareStagedReleaseEnvelope({
+                    declaredPublicAssets,
                     distDirectory,
                     outputDirectory
                 });

package/dist/esm-node/deploy-output/plugin.mjs

@@ -2,6 +2,7 @@ import "node:module";
 import { createRequire } from "node:module";
 import node_path from "node:path";
 import { preserveNpmAliases, readPackageIdentity } from "./npmAliases.mjs";
+import { NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, stageDeclaredPublicAssets } from "./public-assets.mjs";
 import { resolveDeployTarget as external_target_mjs_resolveDeployTarget } from "./target.mjs";
 import { fileURLToPath as __rspack_fileURLToPath } from "node:url";
 var __rspack_import_meta_filename__ = __rspack_fileURLToPath(import.meta.url);
@@ -28,4 +29,20 @@ const createDeployOutputAliasesPlugin = ({ resolveDeployTarget = external_target
             });
         }
     });
-export { createDeployOutputAliasesPlugin };
+const createDeployOutputPublicAssetsPlugin = ({ resolveDeployTarget = external_target_mjs_resolveDeployTarget } = {})=>({
+        name: '@modern-js/deploy-output-public-assets',
+        setup (api) {
+            api.onAfterDeploy(async ()=>{
+                const { appDirectory, metaName } = api.getAppContext();
+                const config = api.getNormalizedConfig();
+                if ('modern-js' !== metaName && !config.deploy?.target && !process.env.MODERNJS_DEPLOY || 'node' !== resolveDeployTarget(config)) return;
+                await stageDeclaredPublicAssets({
+                    appDirectory,
+                    outputDirectory: node_path.join(appDirectory, '.output'),
+                    assets: normalizeDeclaredPublicAssets(config.deploy?.node?.publicAssets, NODE_PUBLIC_ASSET_SCOPE),
+                    scope: NODE_PUBLIC_ASSET_SCOPE
+                });
+            });
+        }
+    });
+export { createDeployOutputAliasesPlugin, createDeployOutputPublicAssetsPlugin };

package/dist/esm-node/deploy-output/public-assets.mjs

@@ -0,0 +1,83 @@
+import "node:module";
+import promises from "node:fs/promises";
+import node_path from "node:path";
+import { normalizeRelativePath } from "../cloudflare/utils.mjs";
+const DECLARED_PUBLIC_ASSET_DIRECTORY = 'public';
+const CLOUDFLARE_PUBLIC_ASSET_SCOPE = {
+    label: 'deploy.worker.publicAssets',
+    output: 'Cloudflare public output'
+};
+const NODE_PUBLIC_ASSET_SCOPE = {
+    label: 'deploy.node.publicAssets',
+    output: 'Node public output'
+};
+const normalizeDeclaredPublicAssets = (assets, scope)=>(assets ?? []).map((asset, index)=>({
+            from: normalizeRelativePath(asset?.from, `${scope.label}[${index}].from`, 'app root'),
+            to: normalizeRelativePath(asset?.to, `${scope.label}[${index}].to`, scope.output, {
+                allowRoot: true
+            }),
+            index
+        }));
+const isMissingPathError = (error)=>error instanceof Error && 'code' in error && 'ENOENT' === error.code;
+const pathExists = async (filePath)=>{
+    try {
+        await promises.lstat(filePath);
+        return true;
+    } catch (error) {
+        if (isMissingPathError(error)) return false;
+        throw error;
+    }
+};
+const listDeclaredPublicAssetFiles = async (appDirectory, assets, scope)=>{
+    const files = [];
+    const owners = new Map();
+    const add = (index, logicalPath)=>{
+        const owner = owners.get(logicalPath);
+        if (void 0 !== owner) throw new Error(`${scope.label}[${index}] and ${scope.label}[${owner}] both stage ${JSON.stringify(logicalPath)}.`);
+        owners.set(logicalPath, index);
+        files.push({
+            index,
+            logicalPath
+        });
+    };
+    const visit = async (asset, sourcePath, destination)=>{
+        const stat = await promises.lstat(sourcePath);
+        if (stat.isSymbolicLink()) throw new Error(`${scope.label}[${asset.index}].from must not contain symbolic links: ${node_path.relative(appDirectory, sourcePath).replace(/\\/gu, '/')}`);
+        if (stat.isFile()) {
+            if (destination === DECLARED_PUBLIC_ASSET_DIRECTORY) throw new Error(`${scope.label}[${asset.index}].to must name a file when ${scope.label}[${asset.index}].from is a file.`);
+            add(asset.index, destination);
+            return;
+        }
+        if (!stat.isDirectory()) throw new Error(`${scope.label}[${asset.index}].from must contain only files and directories: ${node_path.relative(appDirectory, sourcePath).replace(/\\/gu, '/')}`);
+        const entries = (await promises.readdir(sourcePath)).sort();
+        for (const entry of entries)await visit(asset, node_path.join(sourcePath, entry), node_path.posix.join(destination, entry));
+    };
+    for (const asset of assets){
+        const sourcePath = node_path.join(appDirectory, asset.from);
+        if (!await pathExists(sourcePath)) throw new Error(`${scope.label}[${asset.index}].from does not exist: ${asset.from}`);
+        await visit(asset, sourcePath, node_path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to));
+    }
+    return files;
+};
+const resolveAddedDeclaredPublicAssetPaths = async ({ appDirectory, assets, generatedRoot, scope })=>{
+    const added = [];
+    for (const file of (await listDeclaredPublicAssetFiles(appDirectory, assets, scope)))if (!await pathExists(node_path.join(generatedRoot, file.logicalPath))) added.push(file.logicalPath);
+    return added.sort();
+};
+const stageDeclaredPublicAssets = async ({ appDirectory, outputDirectory, assets, scope })=>{
+    const files = await listDeclaredPublicAssetFiles(appDirectory, assets, scope);
+    const added = [];
+    for (const file of files){
+        const asset = assets.find((candidate)=>candidate.index === file.index);
+        const relativePath = node_path.posix.relative(node_path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to), file.logicalPath);
+        const destination = node_path.join(outputDirectory, file.logicalPath);
+        const replacesGeneratedFile = await pathExists(destination);
+        await promises.mkdir(node_path.dirname(destination), {
+            recursive: true
+        });
+        await promises.copyFile(node_path.join(appDirectory, asset.from, relativePath), destination);
+        if (!replacesGeneratedFile) added.push(file.logicalPath);
+    }
+    return added.sort();
+};
+export { CLOUDFLARE_PUBLIC_ASSET_SCOPE, DECLARED_PUBLIC_ASSET_DIRECTORY, NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths, stageDeclaredPublicAssets };

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

@@ -15,6 +15,16 @@ const isEffectBffWorkerArtifact = (logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(
 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
@@ -403,8 +413,9 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly)=>{
+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',
@@ -417,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 && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -451,6 +462,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity,
             'nodejs-deployment'
         ]));
     for (const logicalPath of uiClientPaths)runtimeByPath.set(logicalPath, 'browser');
+    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');
@@ -495,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, 0 === source.surfaces.uiClient.length);
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, declaredPublicAssets);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -516,8 +528,9 @@ 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, apiOnly)=>{
+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',
@@ -533,7 +546,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
     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);
+    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 [
         [
@@ -562,6 +575,9 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
         for (const logicalPath of paths)runtimeByPath.set(logicalPath, runtime);
     };
     add(uiClientPaths, 'browser');
+    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');
@@ -610,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, 0 === source.surfaces.uiClient.length);
+    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/plugin.mjs

@@ -1,5 +1,6 @@
 import "node:module";
 import node_path from "node:path";
+import { NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths } from "../deploy-output/public-assets.mjs";
 import { emitFrameworkMicroVerticalReleaseEnvelope, emitNodeStagedReleaseEnvelope, verifyBuildOutputReleaseEnvelope, verifyNodeReleaseEnvelopeStaging } from "./framework-output.mjs";
 const resolveActiveDeployTarget = (api, resolveDeployTarget)=>{
     const { metaName } = api.getAppContext();
@@ -12,7 +13,8 @@ const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
         pre: [
             '@modern-js/backend-federation-build',
             '@modern-js/plugin-bff',
-            '@modern-js/deploy-output-aliases'
+            '@modern-js/deploy-output-aliases',
+            '@modern-js/deploy-output-public-assets'
         ],
         post: [
             '@modern-js/plugin-deploy'
@@ -45,6 +47,12 @@ const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
                 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
                 });