@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.3 → 3.9.0-ultramodern.5

package/src/build-config/build-environment.ts

@@ -0,0 +1,404 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import type { URL } from 'node:url';
+import type { Rspack } from '@rsbuild/core';
+
+const EFFECT_TSGO_PACKAGE = '@effect/tsgo';
+const EFFECT_TSGO_BIN = 'effect-tsgo';
+const EFFECT_TSGO_RESOLUTION_ERROR =
+  'Unable to resolve the Effect TS-Go compiler. Install "@effect/tsgo" and a native TypeScript backend for this build config, or set EFFECT_TSGO_BIN.';
+const executableEffectTsgoCompilers = new Map<string, string>();
+const BUILD_CONFIG_ENVIRONMENT_PLUGIN =
+  'ModernJsBuildConfigEnvironmentLeasePlugin';
+const ENVIRONMENT_LEASE_REGISTRY_KEY = Symbol.for(
+  '@modern-js/app-tools/build-config-environment-lease-registry/v1',
+);
+const ENVIRONMENT_LEASE_REGISTRY_BRAND = Symbol.for(
+  '@modern-js/app-tools/build-config-environment-lease-registry-brand/v1',
+);
+const LIFECYCLE_HOOK_NAMES = [
+  'run',
+  'watchRun',
+  'afterDone',
+  'failed',
+  'shutdown',
+  'watchClose',
+] as const;
+
+type PackageJson = {
+  bin?: Record<string, string> | string;
+};
+
+type EnvironmentLease = {
+  originalValue: string | undefined;
+  owners: Set<symbol>;
+  value: string;
+};
+
+type EnvironmentLeaseRegistry = Readonly<{
+  acquire: (name: string, value: string) => () => void;
+  brand: symbol;
+}>;
+
+type LifecycleHookName = (typeof LIFECYCLE_HOOK_NAMES)[number];
+
+type LifecycleHook = {
+  tap: (options: { name: string; stage: number }, handler: () => void) => void;
+};
+
+function restoreEnvironment(name: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[name];
+  } else {
+    process.env[name] = value;
+  }
+}
+
+function createEnvironmentLeaseRegistry(): EnvironmentLeaseRegistry {
+  const environmentLeases = new Map<string, EnvironmentLease>();
+
+  return Object.freeze({
+    acquire(name: string, value: string): () => void {
+      let lease = environmentLeases.get(name);
+
+      if (lease) {
+        if (lease.value !== value) {
+          throw new Error(
+            `Build config environment "${name}" already has an active lease for a different value.`,
+          );
+        }
+        if (process.env[name] !== lease.value) {
+          throw new Error(
+            `Build config environment lease for "${name}" lost ownership before another lease was acquired.`,
+          );
+        }
+      } else {
+        lease = {
+          originalValue: process.env[name],
+          owners: new Set(),
+          value,
+        };
+        process.env[name] = value;
+        environmentLeases.set(name, lease);
+      }
+
+      const owner = Symbol(name);
+      lease.owners.add(owner);
+      let released = false;
+
+      return () => {
+        if (released) {
+          return;
+        }
+
+        if (environmentLeases.get(name) !== lease || !lease.owners.has(owner)) {
+          throw new Error(
+            `Build config environment lease for "${name}" cannot be restored because its ownership record was lost.`,
+          );
+        }
+
+        released = true;
+        const lostOwnership = process.env[name] !== lease.value;
+        lease.owners.delete(owner);
+
+        if (lease.owners.size === 0) {
+          environmentLeases.delete(name);
+          restoreEnvironment(name, lease.originalValue);
+        } else if (lostOwnership) {
+          process.env[name] = lease.value;
+        }
+
+        if (lostOwnership) {
+          throw new Error(
+            `Build config environment lease for "${name}" lost ownership before restoration.`,
+          );
+        }
+      };
+    },
+    brand: ENVIRONMENT_LEASE_REGISTRY_BRAND,
+  });
+}
+
+function getEnvironmentLeaseRegistry(): EnvironmentLeaseRegistry {
+  const descriptor = Object.getOwnPropertyDescriptor(
+    process,
+    ENVIRONMENT_LEASE_REGISTRY_KEY,
+  );
+
+  if (descriptor) {
+    const registry = descriptor.value as
+      | Partial<EnvironmentLeaseRegistry>
+      | undefined;
+    if (
+      descriptor.configurable ||
+      descriptor.enumerable ||
+      descriptor.writable ||
+      registry?.brand !== ENVIRONMENT_LEASE_REGISTRY_BRAND ||
+      typeof registry.acquire !== 'function'
+    ) {
+      throw new Error(
+        'The process-global build config environment lease registry is occupied by an incompatible value.',
+      );
+    }
+    return registry as EnvironmentLeaseRegistry;
+  }
+
+  const registry = createEnvironmentLeaseRegistry();
+  Object.defineProperty(process, ENVIRONMENT_LEASE_REGISTRY_KEY, {
+    configurable: false,
+    enumerable: false,
+    value: registry,
+    writable: false,
+  });
+  return registry;
+}
+
+function acquireEnvironmentLease(name: string, value: string): () => void {
+  return getEnvironmentLeaseRegistry().acquire(name, value);
+}
+
+function releaseAfterFailure(
+  release: () => void,
+  originalError: unknown,
+): never {
+  try {
+    release();
+  } catch (restorationError) {
+    throw new AggregateError(
+      [originalError, restorationError],
+      'Build config environment setup and restoration both failed.',
+    );
+  }
+
+  throw originalError;
+}
+
+class BuildConfigEnvironmentLeasePlugin {
+  constructor(private readonly release: () => void) {}
+
+  apply(compiler: Rspack.Compiler): void {
+    const hooks = compiler.hooks as unknown as Record<
+      string,
+      LifecycleHook | undefined
+    >;
+
+    try {
+      const lifecycleHooks = {} as Record<LifecycleHookName, LifecycleHook>;
+      for (const hookName of LIFECYCLE_HOOK_NAMES) {
+        const hook = hooks[hookName];
+        if (!hook || typeof hook.tap !== 'function') {
+          throw new Error(
+            `Rspack does not expose the "${hookName}" lifecycle hook required to restore build config environment leases.`,
+          );
+        }
+        lifecycleHooks[hookName] = hook;
+      }
+
+      let mode: 'pending' | 'run' | 'watch' = 'pending';
+      const modeTap = {
+        name: BUILD_CONFIG_ENVIRONMENT_PLUGIN,
+        stage: Number.MIN_SAFE_INTEGER,
+      };
+      const releaseTap = {
+        name: BUILD_CONFIG_ENVIRONMENT_PLUGIN,
+        stage: Number.MAX_SAFE_INTEGER,
+      };
+      const releaseAfterOneShot = () => {
+        if (mode !== 'watch' && compiler.watchMode !== true) {
+          this.release();
+        }
+      };
+
+      lifecycleHooks.run.tap(modeTap, () => {
+        mode = 'run';
+      });
+      lifecycleHooks.watchRun.tap(modeTap, () => {
+        mode = 'watch';
+      });
+      lifecycleHooks.afterDone.tap(releaseTap, releaseAfterOneShot);
+      lifecycleHooks.failed.tap(releaseTap, releaseAfterOneShot);
+      lifecycleHooks.shutdown.tap(releaseTap, this.release);
+      lifecycleHooks.watchClose.tap(releaseTap, this.release);
+    } catch (error) {
+      releaseAfterFailure(this.release, error);
+    }
+  }
+}
+
+function resolveEffectTsgoCli(from: string | URL): string {
+  const projectRequire = createRequire(from);
+  const packageJsonPath = projectRequire.resolve(
+    `${EFFECT_TSGO_PACKAGE}/package.json`,
+  );
+  const packageJson = JSON.parse(
+    readFileSync(packageJsonPath, 'utf-8'),
+  ) as PackageJson;
+  const bin =
+    typeof packageJson.bin === 'string'
+      ? packageJson.bin
+      : packageJson.bin?.[EFFECT_TSGO_BIN];
+
+  if (!bin) {
+    throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+  }
+
+  return resolve(dirname(packageJsonPath), bin);
+}
+
+function resolveExecutableEffectTsgoCompiler(compilerPath: string): string {
+  if (process.platform === 'win32') {
+    return compilerPath;
+  }
+
+  const sourcePath = realpathSync(compilerPath);
+  const source = lstatSync(sourcePath);
+  if (!source.isFile()) {
+    throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+  }
+
+  try {
+    accessSync(sourcePath, constants.X_OK);
+    return compilerPath;
+  } catch {
+    // npm currently publishes Effect TS-Go's native Unix files without an
+    // execute bit. Keep node_modules immutable and materialize a private copy.
+  }
+
+  const cachedCompiler = executableEffectTsgoCompilers.get(sourcePath);
+  if (cachedCompiler) {
+    try {
+      accessSync(cachedCompiler, constants.X_OK);
+      return cachedCompiler;
+    } catch {
+      executableEffectTsgoCompilers.delete(sourcePath);
+    }
+  }
+
+  const compilerBytes = readFileSync(sourcePath);
+  const compilerDigest = createHash('sha256')
+    .update(compilerBytes)
+    .digest('hex');
+  const compilerDirectory = join(
+    tmpdir(),
+    'modern-js',
+    'effect-tsgo',
+    compilerDigest,
+  );
+  mkdirSync(compilerDirectory, { recursive: true, mode: 0o700 });
+  const executableCompiler = join(compilerDirectory, basename(sourcePath));
+  try {
+    accessSync(executableCompiler, constants.X_OK);
+  } catch {
+    const temporaryCompiler = join(
+      compilerDirectory,
+      `.${basename(sourcePath)}.${process.pid}.tmp`,
+    );
+    rmSync(temporaryCompiler, { force: true });
+    try {
+      writeFileSync(temporaryCompiler, compilerBytes, {
+        flag: 'wx',
+        mode: 0o700,
+      });
+      chmodSync(temporaryCompiler, 0o700);
+      renameSync(temporaryCompiler, executableCompiler);
+    } finally {
+      rmSync(temporaryCompiler, { force: true });
+    }
+  }
+  accessSync(executableCompiler, constants.X_OK);
+  executableEffectTsgoCompilers.set(sourcePath, executableCompiler);
+  return executableCompiler;
+}
+
+/**
+ * Reads an environment variable while keeping generated build configs free of
+ * direct process access.
+ */
+export function getBuildConfigEnvironment(name: string): string | undefined {
+  return process.env[name];
+}
+
+/**
+ * Runs a Rspack config setup under a leased environment value. The lease is
+ * restored when that compiler reaches any supported terminal hook.
+ */
+export function withBuildConfigEnvironment<
+  Config extends { plugins?: Rspack.Plugin[] },
+  SetupArguments extends unknown[],
+>(
+  name: string,
+  value: string,
+  setup: (
+    config: Config,
+    ...args: SetupArguments
+  ) => Config | void | Promise<Config | void>,
+): (config: Config, ...args: SetupArguments) => Promise<Config> {
+  return async (config, ...args) => {
+    const release = acquireEnvironmentLease(name, value);
+
+    try {
+      const configured = (await setup(config, ...args)) ?? config;
+      configured.plugins = [
+        ...(configured.plugins ?? []),
+        new BuildConfigEnvironmentLeasePlugin(release),
+      ];
+      return configured;
+    } catch (error) {
+      releaseAfterFailure(release, error);
+    }
+  };
+}
+
+export type ResolveEffectTsgoCompilerOptions = {
+  /** Module URL or absolute filename used to resolve the consumer's compiler. */
+  from: string | URL;
+};
+
+/**
+ * Resolves the Effect TS-Go executable used by Module Federation DTS builds.
+ */
+export function resolveEffectTsgoCompiler(
+  options: ResolveEffectTsgoCompilerOptions,
+): string {
+  const configuredCompiler =
+    getBuildConfigEnvironment('EFFECT_TSGO_BIN')?.trim();
+
+  if (configuredCompiler) {
+    try {
+      return resolveExecutableEffectTsgoCompiler(configuredCompiler);
+    } catch {
+      throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+    }
+  }
+
+  try {
+    const compiler = execFileSync(
+      process.execPath,
+      [resolveEffectTsgoCli(options.from), 'get-exe-path'],
+      { encoding: 'utf-8' },
+    ).trim();
+
+    if (compiler) {
+      return resolveExecutableEffectTsgoCompiler(compiler);
+    }
+  } catch {
+    // Use one stable error for package, platform-binary, and CLI failures.
+  }
+
+  throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+}

package/src/build-config/precompress/plugin.ts

@@ -0,0 +1,140 @@
+import { constants as zlibConstants } from 'node:zlib';
+import type { RsbuildPlugin } from '@rsbuild/core';
+import CompressionPlugin from 'compression-webpack-plugin';
+import type { PrecompressConfig } from './types';
+
+export type { PrecompressCodecOptions, PrecompressConfig } from './types';
+
+type CompressionPluginOptions = NonNullable<
+  ConstructorParameters<typeof CompressionPlugin>[0]
+>;
+
+const DEFAULT_PRECOMPRESS_TEST = /\.(js|mjs|cjs|css|html|svg|json|map)$/i;
+const DEFAULT_PRECOMPRESS_THRESHOLD = 10 * 1024;
+const DEFAULT_PRECOMPRESS_MIN_RATIO = 0.8;
+
+const createDefaultGzipOptions = (): CompressionPluginOptions => ({
+  algorithm: 'gzip',
+  filename: '[path][base].gz',
+  test: DEFAULT_PRECOMPRESS_TEST,
+  threshold: DEFAULT_PRECOMPRESS_THRESHOLD,
+  minRatio: DEFAULT_PRECOMPRESS_MIN_RATIO,
+  compressionOptions: {
+    level: 6,
+  },
+});
+
+const createDefaultBrotliOptions = (): CompressionPluginOptions => ({
+  algorithm: 'brotliCompress',
+  filename: '[path][base].br',
+  test: DEFAULT_PRECOMPRESS_TEST,
+  threshold: DEFAULT_PRECOMPRESS_THRESHOLD,
+  minRatio: DEFAULT_PRECOMPRESS_MIN_RATIO,
+  compressionOptions: {
+    params: {
+      [zlibConstants.BROTLI_PARAM_QUALITY]: 9,
+    },
+  },
+});
+
+const mergeCompressionOptions = (
+  base: CompressionPluginOptions,
+  next: Partial<CompressionPluginOptions>,
+): CompressionPluginOptions => {
+  const merged = {
+    ...base,
+    ...next,
+  };
+
+  if (base.compressionOptions || next.compressionOptions) {
+    const baseCompressionOptions = base.compressionOptions as
+      | Record<string, unknown>
+      | undefined;
+    const nextCompressionOptions = next.compressionOptions as
+      | Record<string, unknown>
+      | undefined;
+    const mergedCompressionOptions = {
+      ...baseCompressionOptions,
+      ...nextCompressionOptions,
+    };
+
+    if (baseCompressionOptions?.params || nextCompressionOptions?.params) {
+      mergedCompressionOptions.params = {
+        ...(baseCompressionOptions?.params as Record<string, unknown>),
+        ...(nextCompressionOptions?.params as Record<string, unknown>),
+      };
+    }
+
+    merged.compressionOptions = mergedCompressionOptions;
+  }
+
+  return merged;
+};
+
+const resolveCodecOptions = (
+  codecConfig: PrecompressConfig['gzip'] | PrecompressConfig['brotli'],
+  createDefaultOptions: () => CompressionPluginOptions,
+): CompressionPluginOptions | null => {
+  if (codecConfig === false) {
+    return null;
+  }
+
+  if (codecConfig === undefined || codecConfig === true) {
+    return createDefaultOptions();
+  }
+
+  return mergeCompressionOptions(createDefaultOptions(), codecConfig);
+};
+
+const resolvePrecompressConfig = (
+  precompress: boolean | PrecompressConfig | undefined,
+): PrecompressConfig | false => {
+  if (precompress === false || precompress === undefined) {
+    return false;
+  }
+
+  if (precompress === true) {
+    return {};
+  }
+
+  return precompress;
+};
+
+export const builderPluginAdapterPrecompress = (
+  precompress: boolean | PrecompressConfig | undefined,
+): RsbuildPlugin => ({
+  name: 'builder-plugin-adapter-modern-precompress',
+
+  setup(api) {
+    api.modifyBundlerChain((chain, { isProd, target }) => {
+      if (!isProd || target !== 'web') {
+        return;
+      }
+
+      const precompressConfig = resolvePrecompressConfig(precompress);
+      if (precompressConfig === false) {
+        return;
+      }
+
+      const gzipOptions = resolveCodecOptions(
+        precompressConfig.gzip,
+        createDefaultGzipOptions,
+      );
+      if (gzipOptions) {
+        chain
+          .plugin('modern-precompress-gzip')
+          .use(CompressionPlugin, [gzipOptions]);
+      }
+
+      const brotliOptions = resolveCodecOptions(
+        precompressConfig.brotli,
+        createDefaultBrotliOptions,
+      );
+      if (brotliOptions) {
+        chain
+          .plugin('modern-precompress-brotli')
+          .use(CompressionPlugin, [brotliOptions]);
+      }
+    });
+  },
+});

package/src/build-config/precompress/types.ts

@@ -0,0 +1,26 @@
+import type CompressionPlugin from 'compression-webpack-plugin';
+
+type CompressionPluginOptions = NonNullable<
+  ConstructorParameters<typeof CompressionPlugin>[0]
+>;
+
+export type PrecompressCodecOptions =
+  | boolean
+  | Partial<CompressionPluginOptions>;
+
+export interface PrecompressConfig {
+  /**
+   * Configure gzip precompression options.
+   * `true` means using default options.
+   * `false` means disabling gzip precompression.
+   * @default true
+   */
+  gzip?: PrecompressCodecOptions;
+  /**
+   * Configure brotli precompression options.
+   * `true` means using default options.
+   * `false` means disabling brotli precompression.
+   * @default true
+   */
+  brotli?: PrecompressCodecOptions;
+}

package/src/build-config/public.ts

@@ -0,0 +1,6 @@
+export type { ResolveEffectTsgoCompilerOptions } from './build-environment';
+export {
+  getBuildConfigEnvironment,
+  resolveEffectTsgoCompiler,
+  withBuildConfigEnvironment,
+} from './build-environment';

package/src/cloudflare/constants.ts

@@ -34,7 +34,7 @@ export const BFF_EFFECT_WORKER_ENTRY = `${WORKER_BUNDLE_DIRECTORY}/__modern_bff_
 export const BFF_EFFECT_WORKER_DISPATCHER_EXPORT =
   '__modern_create_effect_bff_dispatcher';
 export const EFFECT_BFF_CLOUDFLARE_IMPORT_GUIDANCE =
-  'Ensure the Effect API entry exists at api/index.ts or bff.effect.entry, and import Cloudflare edge handlers from @modern-js/plugin-bff/effect-edge instead of lambda/Hono server helpers.';
+  'Ensure the Effect API entry exists at api/index.ts or bff.effect.entry, and import Cloudflare edge handlers from @modern-js/bff-effect/effect-edge instead of lambda/Hono server helpers.';
 export const DEFAULT_COMPATIBILITY_DATE = '2026-06-02';
 export const COMPATIBILITY_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
 export const REQUIRED_COMPATIBILITY_FLAGS =

package/src/cloudflare/delivery-unit.ts

@@ -1,5 +1,4 @@
 import path from 'node:path';
-import { fs as fse } from '@modern-js/utils';
 import {
   type DeliveryUnitIdentity,
   isUltramodernBuildArtifact,
@@ -7,7 +6,8 @@ import {
   toDeliveryUnitIdentity,
   ULTRAMODERN_BUILD_ARTIFACT_PATH,
   ULTRAMODERN_BUILD_MODULE_PATH,
-} from '@modern-js/utils/universal';
+} from '@modern-js/backend-federation-contracts';
+import { fs as fse } from '@modern-js/utils';
 import { resolveUltramodernReleaseIdentity } from '../release-identity';
 import { isRecord } from './utils';
 

package/src/cloudflare/worker-manifest.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import type {} from '@modern-js/server-runtime-extensions/server-config';
 import { fs as fse } from '@modern-js/utils';
 import { readRouteSpec } from './artifacts';
 import {

package/src/cloudflare-builder.ts

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { SERVICE_WORKER_ENVIRONMENT_NAME } from '@modern-js/builder';
 import type { BffUserConfig } from '@modern-js/server-core';
+import type {} from '@modern-js/server-runtime-extensions/server-config';
 import { isProd } from '@modern-js/utils';
 import type {
   EnvironmentConfig,

package/src/cloudflare-output-contract.ts

@@ -10,19 +10,56 @@ export const CLOUDFLARE_RUNTIME_TYPE = 'cloudflare-module-worker';
 export const CLOUDFLARE_OUTPUT_PACKAGE_TYPE = 'module';
 export const CLOUDFLARE_WORKER_PACKAGE_TYPE = 'commonjs';
 export const CLOUDFLARE_WORKER_BUNDLE_FORMAT = 'commonjs';
+// Import availability for the default 2026-06-02 nodejs_compat target.
+// Some modules are runtime-provided stubs whose unsupported operations throw.
 export const CLOUDFLARE_WORKER_NODE_BUILTINS = [
+  'assert',
+  'assert/strict',
   'async_hooks',
   'buffer',
+  'child_process',
   'crypto',
+  'dgram',
+  'dns',
+  'domain',
   'events',
+  'fs',
   'fs/promises',
+  'http',
+  'http2',
+  'inspector',
   'module',
+  'net',
+  'os',
   'path',
   'process',
+  'readline',
+  'readline/promises',
+  'repl',
+  'sqlite',
   'stream',
+  'stream/consumers',
+  'stream/promises',
+  'stream/web',
   'string_decoder',
+  'timers',
+  'timers/promises',
+  'tls',
+  'trace_events',
+  'tty',
   'url',
   'util',
+  'util/types',
+  'v8',
+  'vm',
+  'wasi',
+  'worker_threads',
+  'zlib',
+] as const;
+// Platform imports available with the default 2026-06-02 nodejs_compat target.
+// Import availability does not imply support for every Node API operation.
+export const CLOUDFLARE_WORKER_PLATFORM_MODULES = [
+  'cloudflare:sockets',
 ] as const;
 export const CLOUDFLARE_REQUIRED_COMPATIBILITY_FLAGS = [
   'nodejs_compat',

package/src/cloudflare-output-verifier/identity.ts

@@ -2,7 +2,7 @@ import {
   DELIVERY_UNIT_IDENTITY_FIELDS,
   type DeliveryUnitIdentity,
   deliveryUnitIdentityFieldValue,
-} from '@modern-js/utils/universal';
+} from '@modern-js/backend-federation-contracts';
 import type { CloudflareOutputVerifierIssue, JsonObject } from './issues';
 import { addIssue, assertEqual } from './issues';