@bleedingdev/modern-js-app-tools-extensions 3.8.3-ultramodern.2

package/src/cloudflare/delivery-unit.ts

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { fs as fse } from '@modern-js/utils';
+import {
+  type DeliveryUnitIdentity,
+  isUltramodernBuildArtifact,
+  nonEmptyString,
+  toDeliveryUnitIdentity,
+  ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  ULTRAMODERN_BUILD_MODULE_PATH,
+} from '@modern-js/utils/universal';
+import { resolveUltramodernReleaseIdentity } from '../release-identity';
+import { isRecord } from './utils';
+
+const COMPACT_CONFIG_PATH = '.modernjs/ultramodern.json';
+
+export type DeliveryUnitStamp = DeliveryUnitIdentity & {
+  surfaces: {
+    ui?: DeliveryUnitIdentity & { surface: 'ui' };
+    api?: DeliveryUnitIdentity & { surface: 'api' };
+  };
+};
+
+type CompactAppResolution = {
+  app?: Record<string, unknown>;
+  workspaceRoot: string;
+};
+
+const findWorkspaceRoot = async (
+  appDirectory: string,
+): Promise<string | undefined> => {
+  let current = path.resolve(appDirectory);
+
+  for (;;) {
+    if (await fse.pathExists(path.join(current, COMPACT_CONFIG_PATH))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+
+    current = parent;
+  }
+};
+
+const stampReleaseIdentity = (
+  identity: DeliveryUnitIdentity,
+  workspaceRoot: string,
+): DeliveryUnitIdentity => {
+  if (identity.sourceRevision !== 'workspace') {
+    return identity;
+  }
+  return {
+    ...identity,
+    ...resolveUltramodernReleaseIdentity({
+      generationBuildMarker: identity.buildMarker,
+      unitId: identity.unitId,
+      workspaceRoot,
+    }),
+  };
+};
+
+const resolveCompactApp = async (
+  appDirectory: string,
+): Promise<CompactAppResolution | undefined> => {
+  const workspaceRoot = await findWorkspaceRoot(appDirectory);
+  if (!workspaceRoot) {
+    return undefined;
+  }
+
+  let compactConfig: unknown;
+  try {
+    compactConfig = await fse.readJSON(
+      path.join(workspaceRoot, COMPACT_CONFIG_PATH),
+    );
+  } catch {
+    return { workspaceRoot };
+  }
+
+  if (!isRecord(compactConfig)) {
+    return { workspaceRoot };
+  }
+
+  const topology = isRecord(compactConfig.topology)
+    ? compactConfig.topology
+    : undefined;
+  const apps = Array.isArray(topology?.apps) ? topology.apps : undefined;
+  if (!apps) {
+    return { app: compactConfig, workspaceRoot };
+  }
+
+  const resolvedAppDirectory = path.resolve(appDirectory);
+  const app = apps.find(candidate => {
+    if (!isRecord(candidate)) {
+      return false;
+    }
+    const appPath = nonEmptyString(candidate.path);
+    return (
+      appPath !== undefined &&
+      path.resolve(workspaceRoot, appPath.replace(/^\.\/+/u, '')) ===
+        resolvedAppDirectory
+    );
+  });
+  return {
+    ...(isRecord(app) ? { app } : {}),
+    workspaceRoot,
+  };
+};
+
+const createDeliveryUnitStamp = (
+  identity: DeliveryUnitIdentity,
+  app?: Record<string, unknown>,
+): DeliveryUnitStamp => {
+  const surfaceProfile = nonEmptyString(app?.surfaceProfile);
+  const emitsUi = surfaceProfile !== 'api-only';
+  const emitsApi = surfaceProfile !== 'ui-only';
+
+  return {
+    ...identity,
+    surfaces: {
+      ...(emitsUi ? { ui: { ...identity, surface: 'ui' as const } } : {}),
+      ...(emitsApi ? { api: { ...identity, surface: 'api' as const } } : {}),
+    },
+  };
+};
+
+/**
+ * Resolve the delivery-unit record declared for this app by the workspace
+ * compact config (`.modernjs/ultramodern.json`). This is the topology source
+ * of truth the Cloudflare worker snapshot is verified against.
+ */
+export const resolveTopologyDeliveryUnit = async (
+  appDirectory: string,
+): Promise<DeliveryUnitStamp | undefined> => {
+  const resolved = await resolveCompactApp(appDirectory);
+  if (!resolved?.app) {
+    return undefined;
+  }
+  const identity = toDeliveryUnitIdentity(resolved.app.deliveryUnit);
+  return identity
+    ? createDeliveryUnitStamp(
+        stampReleaseIdentity(identity, resolved.workspaceRoot),
+        resolved.app,
+      )
+    : undefined;
+};
+
+/**
+ * Resolve the delivery-unit identity actually bundled into the worker by
+ * parsing the generated `shared/ultramodern-build.ts` module. This is the
+ * worker snapshot / declared surface source that gets stamped into the manifest.
+ */
+export const resolveWorkerDeliveryUnitStamp = async (
+  appDirectory: string,
+): Promise<DeliveryUnitStamp | undefined> => {
+  const buildArtifactPath = path.join(
+    appDirectory,
+    ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  );
+  const buildModulePath = path.join(
+    appDirectory,
+    ULTRAMODERN_BUILD_MODULE_PATH,
+  );
+  let identity: DeliveryUnitIdentity | undefined;
+
+  if (await fse.pathExists(buildArtifactPath)) {
+    const artifact = await fse.readJSON(buildArtifactPath);
+    if (!isUltramodernBuildArtifact(artifact)) {
+      return undefined;
+    }
+    identity = toDeliveryUnitIdentity(artifact.deliveryUnit);
+  } else if (await fse.pathExists(buildModulePath)) {
+    console.warn(
+      `[cloudflare] ${buildArtifactPath} missing; falling back to legacy regex parsing of ${buildModulePath}. Regenerate the workspace to emit ultramodern-build.json.`,
+    );
+    const source = await fse.readFile(buildModulePath, 'utf8');
+    identity = toDeliveryUnitIdentity({
+      buildMarker: source.match(/\bbuild:\s*['"]([^'"]+)['"]/u)?.[1],
+      unitId: source.match(/\bunitId:\s*['"]([^'"]+)['"]/u)?.[1],
+      sourceRevision: source.match(
+        /\bsourceRevision:\s*['"]([^'"]+)['"]/u,
+      )?.[1],
+    });
+  }
+
+  if (!identity) {
+    return undefined;
+  }
+  const resolved = await resolveCompactApp(appDirectory);
+  if (resolved) {
+    identity = stampReleaseIdentity(identity, resolved.workspaceRoot);
+  }
+  return createDeliveryUnitStamp(identity, resolved?.app);
+};

package/src/cloudflare/i18n-worker.ts

@@ -0,0 +1,197 @@
+import type { CloudflareAppContext } from './types';
+import { isRecord } from './utils';
+
+const I18N_SERVER_PLUGIN_NAME = 'plugin-i18n/server';
+const DEFAULT_I18NEXT_DETECTION_OPTIONS = {
+  order: [
+    'querystring',
+    'cookie',
+    'localStorage',
+    'header',
+    'navigator',
+    'htmlTag',
+    'path',
+    'subdomain',
+  ],
+  lookupQuerystring: 'lng',
+  lookupCookie: 'i18next',
+  lookupHeader: 'accept-language',
+} as const;
+const SERVER_SIDE_I18N_DETECTORS = new Set(['querystring', 'cookie', 'header']);
+
+type ServerPluginConfig = NonNullable<
+  CloudflareAppContext['serverPlugins']
+>[number];
+
+type WorkerI18nDetection = {
+  order: string[];
+  lookupQuerystring: string;
+  lookupCookie: string;
+  lookupHeader: string;
+};
+
+type WorkerI18nEntry = {
+  i18nextDetector: boolean;
+  languages: string[];
+  fallbackLanguage: string;
+  detection: WorkerI18nDetection;
+  ignoreRedirectRoutes: string[];
+  staticRoutePrefixes: string[];
+  localisedUrls?: Record<string, Record<string, string>>;
+};
+
+const toStringArray = (value: unknown): string[] =>
+  Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+
+const getI18nServerPlugin = (
+  appContext: CloudflareAppContext,
+): ServerPluginConfig | undefined =>
+  appContext.serverPlugins?.find(plugin =>
+    plugin.name.includes(I18N_SERVER_PLUGIN_NAME),
+  );
+
+const removeLocaleDetectionByEntry = (config: Record<string, unknown>) => {
+  const { localeDetectionByEntry: _localeDetectionByEntry, ...rest } = config;
+  return rest;
+};
+
+const getEntryLocaleDetection = (
+  entryName: string,
+  localeDetection: Record<string, unknown>,
+) => {
+  const byEntry = isRecord(localeDetection.localeDetectionByEntry)
+    ? localeDetection.localeDetectionByEntry
+    : undefined;
+  const entryConfig = byEntry?.[entryName];
+  const globalConfig = removeLocaleDetectionByEntry(localeDetection);
+
+  return isRecord(entryConfig)
+    ? { ...globalConfig, ...entryConfig }
+    : globalConfig;
+};
+
+const normalizeI18nDetection = (detection: unknown): WorkerI18nDetection => {
+  const configured = isRecord(detection) ? detection : {};
+  const rawOrder = Array.isArray(configured.order)
+    ? configured.order
+    : DEFAULT_I18NEXT_DETECTION_OPTIONS.order;
+  const order = rawOrder.filter(
+    (entry): entry is string =>
+      typeof entry === 'string' && SERVER_SIDE_I18N_DETECTORS.has(entry),
+  );
+
+  return {
+    order: order.length > 0 ? order : ['querystring', 'cookie', 'header'],
+    lookupQuerystring:
+      typeof configured.lookupQuerystring === 'string' &&
+      configured.lookupQuerystring
+        ? configured.lookupQuerystring
+        : DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupQuerystring,
+    lookupCookie:
+      typeof configured.lookupCookie === 'string' && configured.lookupCookie
+        ? configured.lookupCookie
+        : DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupCookie,
+    lookupHeader:
+      typeof configured.lookupHeader === 'string' && configured.lookupHeader
+        ? configured.lookupHeader
+        : DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupHeader,
+  };
+};
+
+const normalizeLocalisedUrls = (
+  localisedUrls: unknown,
+): Record<string, Record<string, string>> | undefined => {
+  if (!isRecord(localisedUrls) || Object.keys(localisedUrls).length === 0) {
+    return undefined;
+  }
+
+  const normalized: Record<string, Record<string, string>> = {};
+  for (const [canonicalPath, languageMap] of Object.entries(localisedUrls)) {
+    if (!isRecord(languageMap)) {
+      continue;
+    }
+
+    const normalizedLanguageMap = Object.fromEntries(
+      Object.entries(languageMap).filter(
+        (entry): entry is [string, string] =>
+          typeof entry[1] === 'string' && entry[1].length > 0,
+      ),
+    );
+
+    if (Object.keys(normalizedLanguageMap).length > 0) {
+      normalized[canonicalPath] = normalizedLanguageMap;
+    }
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+};
+
+const normalizeWorkerI18nEntry = (
+  entryName: string,
+  localeDetection: Record<string, unknown>,
+  staticRoutePrefixes: string[],
+): WorkerI18nEntry | undefined => {
+  const entryConfig = getEntryLocaleDetection(entryName, localeDetection);
+  const languages = toStringArray(entryConfig.languages);
+
+  if (entryConfig.localePathRedirect !== true || languages.length === 0) {
+    return undefined;
+  }
+
+  const fallbackLanguage =
+    typeof entryConfig.fallbackLanguage === 'string' &&
+    entryConfig.fallbackLanguage
+      ? entryConfig.fallbackLanguage
+      : 'en';
+  const ignoreRedirectRoutes = Array.isArray(entryConfig.ignoreRedirectRoutes)
+    ? toStringArray(entryConfig.ignoreRedirectRoutes)
+    : [];
+  const localisedUrls = normalizeLocalisedUrls(entryConfig.localisedUrls);
+
+  return {
+    i18nextDetector: entryConfig.i18nextDetector !== false,
+    languages,
+    fallbackLanguage,
+    detection: normalizeI18nDetection(entryConfig.detection),
+    ignoreRedirectRoutes,
+    staticRoutePrefixes,
+    ...(localisedUrls ? { localisedUrls } : {}),
+  };
+};
+
+export const createI18nWorkerManifest = (
+  routeSpec: { routes: Array<Record<string, unknown>> },
+  appContext: CloudflareAppContext,
+) => {
+  const i18nServerPlugin = getI18nServerPlugin(appContext);
+  const localeDetection = i18nServerPlugin?.options?.localeDetection;
+
+  if (!isRecord(localeDetection)) {
+    return undefined;
+  }
+
+  const staticRoutePrefixes = toStringArray(
+    i18nServerPlugin?.options?.staticRoutePrefixes,
+  );
+  const entries: Record<string, WorkerI18nEntry> = {};
+
+  for (const route of routeSpec.routes) {
+    if (typeof route.entryName !== 'string' || entries[route.entryName]) {
+      continue;
+    }
+
+    const entry = normalizeWorkerI18nEntry(
+      route.entryName,
+      localeDetection,
+      staticRoutePrefixes,
+    );
+
+    if (entry) {
+      entries[route.entryName] = entry;
+    }
+  }
+
+  return Object.keys(entries).length > 0 ? { entries } : undefined;
+};

package/src/cloudflare/index.ts

@@ -0,0 +1,259 @@
+import path from 'node:path';
+import { fs as fse } from '@modern-js/utils';
+import { createCloudflareOutputPlan } from '../cloudflare-output-plan';
+import { assertCloudflareOutput } from '../cloudflare-output-verifier/index';
+import { readTemplate } from '../read-template';
+import {
+  emitCloudflareStagedReleaseEnvelope,
+  emitFrameworkMicroVerticalReleaseEnvelope,
+  MICROVERTICAL_RELEASE_ENVELOPE_PATH,
+  stageCloudflareReleaseEnvelope,
+  verifyBuildOutputReleaseEnvelope,
+  verifyCloudflareReleaseEnvelopeStaging,
+} from '../release-envelope/framework-output';
+import {
+  copyCloudflareArtifacts,
+  copyCloudflareD1Migrations,
+  copyCloudflarePublicAssets,
+  getCloudflareArtifacts,
+  getCloudflarePublicAssets,
+} from './artifacts';
+import {
+  ROUTE_SPEC_FILE,
+  ROUTE_SPEC_OUTPUT,
+  WORKER_BUNDLE_DIRECTORY,
+  WORKER_ENTRY,
+  WORKER_MANIFEST,
+  WRANGLER_CONFIG_FILE,
+} from './constants';
+import {
+  resolveTopologyDeliveryUnit,
+  resolveWorkerDeliveryUnitStamp,
+} from './delivery-unit';
+import type { CreateCloudflarePreset } from './types';
+import {
+  createWorkerManifest,
+  createWorkerModuleLoaders,
+  getPublicAssetExcludes,
+  shouldCopyToPublicAssets,
+  shouldCopyToWorkerBundle,
+} from './worker-manifest';
+import { createWranglerConfig } from './wrangler-config';
+
+const CLOUDFLARE_ENTRY_TEMPLATE_FRAGMENTS = [
+  'cloudflare-entry.001-bootstrap-security.mjs',
+  'cloudflare-entry.002-assets-routes.mjs',
+  'cloudflare-entry.003-i18n-locales.mjs',
+  'cloudflare-entry.004-rendering-css.mjs',
+  'cloudflare-entry.005-worker-dispatch.mjs',
+  'cloudflare-entry.006-fetch-handler.mjs',
+] as const;
+
+/**
+ * The Cloudflare entry is emitted as a raw module worker, not bundled by
+ * app-tools. Keep worker-runtime helpers inline unless the helper is emitted
+ * into `.output` or provided by a generated-worker dependency. Concatenate
+ * fragments without separators so existing generated output stays byte-identical.
+ */
+const readCloudflareEntryTemplate = async () =>
+  (
+    await Promise.all(
+      CLOUDFLARE_ENTRY_TEMPLATE_FRAGMENTS.map(fragment =>
+        readTemplate(fragment),
+      ),
+    )
+  ).join('');
+
+export const createCloudflarePreset: CreateCloudflarePreset = ({
+  api,
+  appContext,
+  modernConfig,
+}) => {
+  const { apiOnly, appDirectory, distDirectory } = appContext;
+
+  const outputDirectory = path.join(appDirectory, '.output');
+  const outputPlan = createCloudflareOutputPlan(outputDirectory);
+  const publicDirectory = outputPlan.paths.publicAssets;
+  const workerEntryPath = outputPlan.paths.workerEntry;
+  const workerManifestPath = outputPlan.paths.workerManifest;
+  const routeSpecOutputPath = path.join(outputDirectory, ROUTE_SPEC_OUTPUT);
+  const wranglerConfigPath = outputPlan.paths.wranglerConfig;
+  const cloudflareArtifacts = getCloudflareArtifacts(modernConfig);
+  const publicAssetExcludes = getPublicAssetExcludes(
+    appDirectory,
+    modernConfig,
+  );
+  const releaseEnvelopeEnabled = api.isPluginExists(
+    '@modern-js/ultramodern-release-envelope',
+  );
+  let hasReleaseEnvelope = false;
+
+  return {
+    async prepare() {
+      await fse.remove(outputDirectory);
+    },
+    async writeOutput() {
+      if (
+        releaseEnvelopeEnabled &&
+        (await fse.pathExists(
+          path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH),
+        ))
+      ) {
+        await emitFrameworkMicroVerticalReleaseEnvelope({
+          apiOnly,
+          distDirectory,
+          target: 'cloudflare',
+        });
+      }
+      if (releaseEnvelopeEnabled) {
+        await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
+      }
+      await fse.copy(distDirectory, publicDirectory, {
+        filter: src => {
+          const relativePath = path
+            .relative(distDirectory, src)
+            .replace(/\\/gu, '/');
+          return (
+            relativePath !== 'release' &&
+            !relativePath.startsWith('release/') &&
+            relativePath !== 'public' &&
+            !relativePath.startsWith('public/') &&
+            shouldCopyToPublicAssets(src, distDirectory, publicAssetExcludes)
+          );
+        },
+      });
+      const generatedPublicDirectory = path.join(distDirectory, 'public');
+      if (await fse.pathExists(generatedPublicDirectory)) {
+        await fse.copy(generatedPublicDirectory, publicDirectory, {
+          filter: src => {
+            const relativePath = path
+              .relative(generatedPublicDirectory, src)
+              .replace(/\\/gu, '/');
+            return (
+              relativePath !== 'release' &&
+              !relativePath.startsWith('release/') &&
+              shouldCopyToPublicAssets(
+                src,
+                generatedPublicDirectory,
+                publicAssetExcludes,
+              )
+            );
+          },
+        });
+      }
+      await fse.ensureDir(path.dirname(workerEntryPath));
+      await fse.ensureDir(path.dirname(workerManifestPath));
+
+      const routeSpecSourcePath = path.join(distDirectory, ROUTE_SPEC_FILE);
+      if (await fse.pathExists(routeSpecSourcePath)) {
+        await fse.copy(routeSpecSourcePath, routeSpecOutputPath);
+      }
+
+      const workerBundleSourceDirectory = path.join(
+        distDirectory,
+        WORKER_BUNDLE_DIRECTORY,
+      );
+      const workerBundleOutputDirectory = outputPlan.paths.workerBundle;
+      if (await fse.pathExists(workerBundleSourceDirectory)) {
+        await fse.copy(
+          workerBundleSourceDirectory,
+          workerBundleOutputDirectory,
+          {
+            filter: src =>
+              shouldCopyToWorkerBundle(src, workerBundleSourceDirectory),
+          },
+        );
+        await fse.writeJSON(
+          outputPlan.paths.workerPackage,
+          outputPlan.packages.worker,
+        );
+      }
+      await copyCloudflareArtifacts(
+        appDirectory,
+        outputDirectory,
+        cloudflareArtifacts,
+      );
+      await copyCloudflarePublicAssets(
+        appDirectory,
+        publicDirectory,
+        getCloudflarePublicAssets(modernConfig),
+      );
+      await copyCloudflareD1Migrations(
+        appDirectory,
+        outputDirectory,
+        modernConfig,
+      );
+
+      await fse.writeJSON(
+        wranglerConfigPath,
+        createWranglerConfig(appDirectory, modernConfig),
+        {
+          spaces: 2,
+        },
+      );
+
+      const deliveryUnitStamp =
+        await resolveWorkerDeliveryUnitStamp(appDirectory);
+      await fse.writeJSON(
+        workerManifestPath,
+        await createWorkerManifest(
+          outputDirectory,
+          modernConfig,
+          appContext,
+          deliveryUnitStamp,
+        ),
+        {
+          spaces: 2,
+        },
+      );
+      await fse.writeJSON(
+        outputPlan.paths.outputPackage,
+        outputPlan.packages.output,
+      );
+      hasReleaseEnvelope =
+        releaseEnvelopeEnabled &&
+        Boolean(
+          await stageCloudflareReleaseEnvelope({
+            distDirectory,
+            outputDirectory,
+          }),
+        );
+    },
+    async genEntry() {
+      const template = await readCloudflareEntryTemplate();
+      const manifest = await fse.readJSON(workerManifestPath);
+
+      await fse.writeFile(
+        workerEntryPath,
+        template
+          .replace('p_workerManifest', JSON.stringify(manifest, null, 2))
+          .replace(
+            'p_workerModuleLoaders',
+            createWorkerModuleLoaders(manifest),
+          ),
+      );
+      const topologyDeliveryUnit =
+        await resolveTopologyDeliveryUnit(appDirectory);
+      await assertCloudflareOutput({
+        outputDirectory,
+        importWorker: false,
+        ...(topologyDeliveryUnit ? { deliveryUnit: topologyDeliveryUnit } : {}),
+      });
+      if (hasReleaseEnvelope) {
+        await emitCloudflareStagedReleaseEnvelope({
+          distDirectory,
+          outputDirectory,
+        });
+        await verifyCloudflareReleaseEnvelopeStaging(outputDirectory);
+      } else if (
+        await fse.pathExists(
+          path.join(outputDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH),
+        )
+      ) {
+        throw new Error(
+          '[ultramodern-release-envelope] Cloudflare staging contains an envelope not selected from this MicroVertical build.',
+        );
+      }
+    },
+  };
+};