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

package/src/release-envelope/framework-output.ts

@@ -33,6 +33,16 @@ 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: string) =>
+  EFFECT_BFF_WORKER_PATTERN.test(logicalPath) ||
+  EFFECT_BFF_WORKER_SUPPORT_PATTERN.test(logicalPath);
+const CRAWLER_POLICY_PATH = 'public/robots.txt';
+const isPublicMetadataPath = (logicalPath: string) =>
+  logicalPath === 'public/_headers' ||
+  /^public\/\.well-known\/[^/]+\.json$/u.test(logicalPath);
+const PUBLIC_BUILD_ARTIFACT_PATH = `public/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -345,7 +355,7 @@ const readBuildArtifact = async (
       return undefined;
     }
     throw new Error(
-      '[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable full-stack envelope.',
+      '[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.',
     );
   }
   return artifact;
@@ -516,7 +526,11 @@ const writeReleaseIdentityCarrierMetadata = async (
     ReleaseIdentityCarrierSurface,
     string[],
   ][]) {
-    if (logicalPaths.length === 0) {
+    if (
+      logicalPaths.length === 0 &&
+      surface !== 'ssr' &&
+      surface !== 'uiClient'
+    ) {
       throw new Error(
         `[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`,
       );
@@ -591,12 +605,10 @@ const createReleaseArtifactInputs = async (
   distDirectory: string,
   identity: MicroVerticalReleaseIdentity,
   target: MicroVerticalReleaseTarget,
+  apiOnly: boolean,
 ) => {
   const files = await collectFiles(distDirectory);
-  if (
-    target === 'node' &&
-    files.some(logicalPath => EFFECT_BFF_WORKER_PATTERN.test(logicalPath))
-  ) {
+  if (target === 'node' && 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.',
     );
@@ -606,7 +618,9 @@ const createReleaseArtifactInputs = async (
     return (
       topLevel === 'static' ||
       topLevel === 'html' ||
-      topLevel === 'public' ||
+      (topLevel === 'public' &&
+        logicalPath !== CRAWLER_POLICY_PATH &&
+        !isPublicMetadataPath(logicalPath)) ||
       [
         'index.html',
         'mf-manifest.json',
@@ -628,7 +642,7 @@ const createReleaseArtifactInputs = async (
           logicalPath =>
             logicalPath.startsWith('worker/') &&
             COMPILED_MODULE_PATTERN.test(logicalPath) &&
-            !EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
+            !isEffectBffWorkerArtifact(logicalPath),
         );
   const nodeApiEntryPaths = files.filter(
     logicalPath =>
@@ -643,44 +657,48 @@ const createReleaseArtifactInputs = async (
               logicalPath.startsWith('shared/')) &&
             COMPILED_MODULE_PATTERN.test(logicalPath),
         )
-      : files.filter(logicalPath =>
-          EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
-        );
+      : files.filter(isEffectBffWorkerArtifact);
 
-  if (uiClientPaths.length === 0) {
+  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 && uiClientPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`,
     );
   }
-  if (ssrPaths.length === 0) {
+  if (!apiOnly && ssrPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${target === 'node' ? 'Node' : 'workerd'} SSR artifacts.`,
     );
   }
   if (
     (target === 'node' && nodeApiEntryPaths.length === 0) ||
+    (target === 'cloudflare' &&
+      !files.some(logicalPath =>
+        EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
+      )) ||
     apiBackendPaths.length === 0
   ) {
     throw new Error(
-      `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no actual ${target === 'node' ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`,
+      `[ultramodern-release-envelope] ${target} MicroVertical has no actual ${target === 'node' ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`,
     );
   }
 
-  const clientExecutionPaths = await manifestReferencedClientModules(
-    distDirectory,
-    files,
-  );
-  if (clientExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(distDirectory, files);
+  if (!apiOnly && clientExecutionPaths.length === 0) {
     throw new Error(
       '[ultramodern-release-envelope] UI/client manifest references no compiled execution module.',
     );
   }
-  const ssrExecutionPaths = await routeReferencedSsrModules(
-    distDirectory,
-    files,
-    target,
-  );
-  if (ssrExecutionPaths.length === 0) {
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(distDirectory, files, target);
+  if (!apiOnly && ssrExecutionPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] route manifest references no emitted ${target === 'node' ? 'Node' : 'Cloudflare'} SSR execution module.`,
     );
@@ -699,6 +717,11 @@ const createReleaseArtifactInputs = async (
     }
   };
   add(uiClientPaths, 'browser');
+  add(
+    files.filter(logicalPath => logicalPath === CRAWLER_POLICY_PATH),
+    'crawler-policy',
+  );
+  add(files.filter(isPublicMetadataPath), 'public-metadata');
   add(ssrPaths, target === 'node' ? 'nodejs' : 'workerd');
   add(apiBackendPaths, target === 'node' ? 'nodejs' : 'workerd-effect');
   add([BACKEND_FEDERATION_MANIFEST_FILE], 'module-federation-manifest');
@@ -766,9 +789,6 @@ export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
   requirePromotable?: boolean;
   target: MicroVerticalReleaseTarget;
 }): Promise<MicroVerticalReleaseEnvelope | undefined> => {
-  if (apiOnly) {
-    return undefined;
-  }
   const backendManifestPath = path.join(
     distDirectory,
     BACKEND_FEDERATION_MANIFEST_FILE,
@@ -781,12 +801,12 @@ export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
     pathExists(backendManifestPath),
     pathExists(backendContainerPath),
   ]);
-  if (!hasBackendManifest && !hasBackendContainer) {
+  if (!hasBackendManifest && !hasBackendContainer && !apiOnly) {
     return undefined;
   }
   if (!hasBackendManifest || !hasBackendContainer) {
     throw new Error(
-      '[ultramodern-release-envelope] full-stack MicroVertical backend federation manifest and container must be emitted together.',
+      '[ultramodern-release-envelope] MicroVertical backend federation manifest and container must be emitted together.',
     );
   }
 
@@ -808,6 +828,7 @@ export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
     distDirectory,
     identity,
     target,
+    apiOnly,
   );
   const envelope = await createMicroVerticalReleaseEnvelope({
     artifactRoot: distDirectory,
@@ -854,21 +875,14 @@ export const verifyBuildOutputReleaseEnvelope = async (
   distDirectory: string,
   expectedTarget?: MicroVerticalReleaseTarget,
 ) => {
-  const [hasEnvelope, hasBuildArtifact, hasBackendManifest, hasBackendEntry] =
-    await Promise.all([
-      pathExists(path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
-      pathExists(path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
-      pathExists(path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE)),
-      pathExists(
-        path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE),
-      ),
-    ]);
-  const isFullStackMicroVertical =
-    hasBuildArtifact && (hasBackendManifest || hasBackendEntry);
+  const [hasEnvelope, hasBuildArtifact] = await Promise.all([
+    pathExists(path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
+    pathExists(path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
+  ]);
   return readFrameworkMicroVerticalReleaseEnvelope({
     artifactRoot: distDirectory,
     ...(expectedTarget ? { expectedTarget } : {}),
-    required: hasEnvelope || isFullStackMicroVertical,
+    required: hasEnvelope || hasBuildArtifact,
   });
 };
 
@@ -887,6 +901,7 @@ export const verifyNodeReleaseEnvelopeStaging = async ({
 const createNodeStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
+  apiOnly: boolean,
 ) => {
   const files = await collectFiles(outputDirectory);
   for (const requiredPath of [
@@ -911,7 +926,9 @@ const createNodeStagedReleaseArtifactInputs = async (
     return (
       topLevel === 'static' ||
       topLevel === 'html' ||
-      topLevel === 'public' ||
+      (topLevel === 'public' &&
+        logicalPath !== CRAWLER_POLICY_PATH &&
+        !isPublicMetadataPath(logicalPath)) ||
       [
         'index.html',
         'mf-manifest.json',
@@ -933,27 +950,35 @@ const createNodeStagedReleaseArtifactInputs = async (
       (logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) &&
       COMPILED_MODULE_PATTERN.test(logicalPath),
   );
+  if (
+    apiOnly &&
+    (uiClientPaths.length > 0 || ssrPaths.some(path => path !== 'index.js'))
+  ) {
+    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', uiClientPaths],
-    ['Node SSR', ssrPaths],
+    ['Node SSR', apiOnly ? [] : ssrPaths],
     ['Node API/backend', apiBackendPaths],
   ] as const) {
-    if (paths.length === 0) {
+    if (paths.length === 0 && (!apiOnly || surface === 'Node API/backend')) {
       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 (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(outputDirectory, files);
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(outputDirectory, files, 'node');
+  if (
+    !apiOnly &&
+    (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0)
+  ) {
     throw new Error(
       '[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.',
     );
@@ -967,7 +992,13 @@ const createNodeStagedReleaseArtifactInputs = async (
   for (const logicalPath of uiClientPaths) {
     runtimeByPath.set(logicalPath, 'browser');
   }
-  for (const logicalPath of ssrPaths) {
+  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) {
@@ -988,12 +1019,14 @@ const createNodeStagedReleaseArtifactInputs = async (
         BACKEND_FEDERATION_MANIFEST_FILE,
         BACKEND_FEDERATION_REMOTE_ENTRY_FILE,
       ],
-      ssr: [
-        ...new Set([
-          ...ssrExecutionPaths,
-          ...ssrPaths.filter(logicalPath => logicalPath !== 'index.js'),
-        ]),
-      ],
+      ssr: apiOnly
+        ? []
+        : [
+            ...new Set([
+              ...ssrExecutionPaths,
+              ...ssrPaths.filter(logicalPath => logicalPath !== 'index.js'),
+            ]),
+          ],
       uiClient: uiClientPaths.filter(logicalPath =>
         COMPILED_MODULE_PATTERN.test(logicalPath),
       ),
@@ -1010,7 +1043,9 @@ const createNodeStagedReleaseArtifactInputs = async (
       uiClient: [...uiClientPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
-      ssr: [...ssrPaths].sort((left, right) => left.localeCompare(right)),
+      ssr: apiOnly
+        ? []
+        : [...ssrPaths].sort((left, right) => left.localeCompare(right)),
       apiBackend: [...apiBackendPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
@@ -1036,6 +1071,7 @@ export const emitNodeStagedReleaseEnvelope = async ({
   const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(
     outputDirectory,
     source.identity,
+    source.surfaces.uiClient.length === 0,
   );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,
@@ -1077,6 +1113,7 @@ export const stageCloudflareReleaseEnvelope = async ({
 const createCloudflareStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
+  apiOnly: boolean,
 ) => {
   const files = await collectFiles(outputDirectory);
   for (const requiredPath of [
@@ -1084,7 +1121,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     'server/modern-worker-manifest.json',
     'wrangler.json',
     'package.json',
-    'worker/package.json',
+    ...(apiOnly ? [] : ['worker/package.json']),
   ]) {
     if (!files.includes(requiredPath)) {
       throw new Error(
@@ -1105,28 +1142,46 @@ const createCloudflareStagedReleaseArtifactInputs = async (
   }
   const backendManifestPath = `public/${BACKEND_FEDERATION_MANIFEST_FILE}`;
   const backendContainerPath = `public/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`;
-  const apiBackendPaths = files.filter(logicalPath =>
-    EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
-  );
+  const 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) &&
-      !EFFECT_BFF_WORKER_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 => path !== 'server/index.mjs'))
+  ) {
+    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', uiClientPaths],
-    ['Cloudflare SSR', ssrPaths],
+    ['Cloudflare SSR', apiOnly ? [] : ssrPaths],
     ['Cloudflare API/backend', apiBackendPaths],
   ] as const) {
-    if (paths.length === 0) {
+    if (
+      paths.length === 0 &&
+      (!apiOnly || surface === 'Cloudflare API/backend')
+    ) {
       throw new Error(
         `[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`,
       );
@@ -1140,18 +1195,25 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     }
   }
 
-  const clientExecutionPaths = await manifestReferencedClientModules(
-    outputDirectory,
-    files,
-    'public/mf-manifest.json',
-  );
-  const ssrExecutionPaths = await routeReferencedSsrModules(
-    outputDirectory,
-    files,
-    'cloudflare',
-    'server/route.json',
-  );
-  if (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(
+        outputDirectory,
+        files,
+        'public/mf-manifest.json',
+      );
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(
+        outputDirectory,
+        files,
+        'cloudflare',
+        'server/route.json',
+      );
+  if (
+    !apiOnly &&
+    (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0)
+  ) {
     throw new Error(
       '[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.',
     );
@@ -1167,7 +1229,11 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     }
   };
   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], 'module-federation-manifest');
   add([backendContainerPath], 'commonjs-module');
@@ -1178,12 +1244,16 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     {
       apiBackend: apiBackendPaths,
       backendFederation: [backendManifestPath, backendContainerPath],
-      ssr: [
-        ...new Set([
-          ...ssrExecutionPaths,
-          ...ssrPaths.filter(logicalPath => logicalPath.startsWith('worker/')),
-        ]),
-      ],
+      ssr: apiOnly
+        ? []
+        : [
+            ...new Set([
+              ...ssrExecutionPaths,
+              ...ssrPaths.filter(logicalPath =>
+                logicalPath.startsWith('worker/'),
+              ),
+            ]),
+          ],
       uiClient: uiClientPaths.filter(logicalPath =>
         COMPILED_MODULE_PATTERN.test(logicalPath),
       ),
@@ -1200,7 +1270,9 @@ const createCloudflareStagedReleaseArtifactInputs = async (
       uiClient: [...uiClientPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
-      ssr: [...ssrPaths].sort((left, right) => left.localeCompare(right)),
+      ssr: apiOnly
+        ? []
+        : [...ssrPaths].sort((left, right) => left.localeCompare(right)),
       apiBackend: [...apiBackendPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
@@ -1230,6 +1302,7 @@ export const emitCloudflareStagedReleaseEnvelope = async ({
     await createCloudflareStagedReleaseArtifactInputs(
       outputDirectory,
       source.identity,
+      source.surfaces.uiClient.length === 0,
     );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,

package/src/release-envelope/index.ts

@@ -381,8 +381,8 @@ const assertUniqueSortedArtifacts = (
 };
 
 const assertSurfacePaths = (value: unknown, location: string): string[] => {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error(`${location} must contain at least one artifact path.`);
+  if (!Array.isArray(value)) {
+    throw new Error(`${location} must be an array of artifact paths.`);
   }
   const paths = value.map((item, index) =>
     assertNormalizedLogicalPath(item, `${location}[${index}]`),
@@ -413,10 +413,31 @@ const assertSurfaces = (value: unknown): MicroVerticalReleaseSurfaces => {
     ['manifest', 'container'],
     'surfaces.backendFederation',
   );
+  const uiClient = assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient');
+  const ssr = assertSurfacePaths(surfaces.ssr, 'surfaces.ssr');
+  const apiBackend = assertSurfacePaths(
+    surfaces.apiBackend,
+    'surfaces.apiBackend',
+  );
+  if (uiClient.length > 0 && ssr.length === 0) {
+    throw new Error(
+      'surfaces.ssr must contain at least one artifact path when UI/client is declared.',
+    );
+  }
+  if (ssr.length > 0 && uiClient.length === 0) {
+    throw new Error(
+      'surfaces.uiClient must contain at least one artifact path when SSR is declared.',
+    );
+  }
+  if (apiBackend.length === 0) {
+    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,