@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

package/src/release-envelope/renderer-output-stamp.ts

@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  assertUltramodernBuildArtifact,
+  formatBackendFederationValidationErrors,
+  stampUltramodernBuildArtifactIdentity,
+  ULTRAMODERN_BUILD_ARTIFACT_FILE,
+  ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  type UltramodernBuildArtifact,
+  type UltramodernBuildUiSurface,
+  validateRendererIdentity,
+  validateRendererProfile,
+  validateRendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
+
+export type RendererBuildOutputContext = {
+  appDirectory: string;
+  distDirectory: string;
+  entrypoints: readonly { entryName: string; isMainEntry?: boolean }[];
+};
+
+export type FinalizedRendererBuildOutput = {
+  buildMarker: string;
+  sourceRevision: string;
+  ui: Pick<
+    UltramodernBuildUiSurface,
+    'rendererIdentity' | 'rendererProfile' | 'routerBindings'
+  >;
+};
+
+export type RendererBuildOutputOptions = {
+  resolveRendererBuild: (
+    context: RendererBuildOutputContext,
+  ) => Promise<FinalizedRendererBuildOutput>;
+  /** Exact metadata producer selected by the owning renderer composition. */
+  rendererBuildPlugin: string;
+};
+
+export const validateFinalizedRendererBuild = (
+  output: FinalizedRendererBuildOutput,
+  context: RendererBuildOutputContext,
+  appId: string,
+) => {
+  const entryNames = context.entrypoints.map(entry => entry.entryName);
+  const primary =
+    context.entrypoints.find(entry => entry.isMainEntry) ??
+    context.entrypoints[0];
+  const errors = [
+    ...validateRendererIdentity(output.ui.rendererIdentity).errors,
+    ...validateRendererProfile(output.ui.rendererProfile).errors,
+    ...validateRendererRouterBindings(
+      output.ui.routerBindings,
+      entryNames,
+      'routerBindings',
+    ).errors,
+  ];
+  if (errors.length)
+    throw new Error(formatBackendFederationValidationErrors(errors));
+  if (
+    !primary ||
+    new Set(entryNames).size !== entryNames.length ||
+    context.entrypoints.filter(entry => entry.isMainEntry).length > 1 ||
+    output.ui.rendererIdentity.entryName !== primary.entryName ||
+    output.ui.rendererIdentity.appId !== appId ||
+    output.ui.rendererIdentity.buildId !== output.buildMarker ||
+    output.ui.rendererIdentity.renderer !== output.ui.rendererProfile.renderer
+  )
+    throw new Error(
+      'Finalized renderer output conflicts with the actual application entries and release identity.',
+    );
+};
+
+export const stampFinalizedRendererBuildArtifact = (
+  artifact: UltramodernBuildArtifact,
+  output: FinalizedRendererBuildOutput,
+  context: RendererBuildOutputContext,
+) => {
+  assertUltramodernBuildArtifact(artifact);
+  const ui = artifact.surfaces.ui;
+  if (!ui)
+    throw new Error(
+      'Finalized renderer output requires a declared UI artifact',
+    );
+  validateFinalizedRendererBuild(output, context, artifact.deliveryUnit.appId);
+  const drifted = [
+    !isDeepStrictEqual(
+      { ...ui.rendererIdentity, buildId: output.ui.rendererIdentity.buildId },
+      output.ui.rendererIdentity,
+    ) &&
+      `rendererIdentity (captured entry ${ui.rendererIdentity.entryName}, built entry ${output.ui.rendererIdentity.entryName})`,
+    !isDeepStrictEqual(ui.rendererProfile, output.ui.rendererProfile) &&
+      'rendererProfile',
+    !isDeepStrictEqual(ui.routerBindings, output.ui.routerBindings) &&
+      `routerBindings (captured entries ${Object.keys(ui.routerBindings).join(', ')}, built entries ${Object.keys(output.ui.routerBindings).join(', ')})`,
+  ].filter(Boolean);
+  if (drifted.length)
+    throw new Error(
+      `Finalized renderer output conflicts with the captured application profile or router bindings: ${drifted.join('; ')} differ from ${ULTRAMODERN_BUILD_ARTIFACT_PATH}. After changing modern.config entries, renderer or router, recapture it with \`ultramodern-create ultramodern sync-delivery-unit\`.`,
+    );
+  const identity = {
+    buildMarker: output.buildMarker,
+    sourceRevision: output.sourceRevision,
+  };
+  const stamped = stampUltramodernBuildArtifactIdentity(artifact, identity);
+  return stampUltramodernBuildArtifactIdentity(
+    {
+      ...stamped,
+      surfaces: {
+        ...stamped.surfaces,
+        ui: { ...stamped.surfaces.ui!, ...output.ui },
+      },
+    },
+    identity,
+  );
+};
+
+async function writeOwnedArtifact(file: string, bytes: string) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  let created = false;
+  try {
+    const handle = await fs.open(temporary, 'wx');
+    created = true;
+    try {
+      await handle.writeFile(bytes);
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(temporary, file);
+  } finally {
+    if (created) await fs.rm(temporary, { force: true });
+  }
+}
+
+export async function emitRendererBuildArtifact(
+  context: RendererBuildOutputContext,
+  options: RendererBuildOutputOptions,
+) {
+  const source = path.join(
+    context.appDirectory,
+    ULTRAMODERN_BUILD_ARTIFACT_PATH,
+  );
+  const bytes = await fs.readFile(source).catch(error => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!bytes) {
+    const declaration = await fs
+      .stat(source.replace(/\.json$/u, '.ts'))
+      .catch(error => {
+        if (error.code === 'ENOENT') return undefined;
+        throw error;
+      });
+    if (declaration)
+      throw new Error(
+        'Generated UI artifact declaration is missing its build carrier',
+      );
+    return undefined;
+  }
+  const artifact: unknown = JSON.parse(bytes.toString('utf8'));
+  assertUltramodernBuildArtifact(artifact);
+  const finalized = await options.resolveRendererBuild(context);
+  const stamped = stampFinalizedRendererBuildArtifact(
+    artifact,
+    finalized,
+    context,
+  );
+  const serialized = `${JSON.stringify(stamped, null, 2)}\n`;
+  for (const directory of [
+    context.distDirectory,
+    path.join(context.distDirectory, 'public'),
+  ])
+    await writeOwnedArtifact(
+      path.join(directory, ULTRAMODERN_BUILD_ARTIFACT_FILE),
+      serialized,
+    );
+  return stamped;
+}
+
+/** Stamp generated UI carriers after their actual compiler manifest is committed. */
+export function rendererBuildArtifactStampPlugin(
+  options: RendererBuildOutputOptions,
+) {
+  if (
+    typeof options.rendererBuildPlugin !== 'string' ||
+    !options.rendererBuildPlugin ||
+    options.rendererBuildPlugin.trim() !== options.rendererBuildPlugin ||
+    typeof options.resolveRendererBuild !== 'function'
+  )
+    throw new Error(
+      'Renderer artifact stamping requires its owning metadata producer',
+    );
+  return {
+    name: '@modern-js/renderer-build-artifact-stamp',
+    pre: [options.rendererBuildPlugin],
+    required: [options.rendererBuildPlugin],
+    setup(api: {
+      getAppContext(): RendererBuildOutputContext & { apiOnly?: boolean };
+      onAfterBuild(handler: () => Promise<void>): void;
+    }) {
+      api.onAfterBuild(async () => {
+        const context = api.getAppContext();
+        if (context.apiOnly) return;
+        await emitRendererBuildArtifact(context, options);
+      });
+    },
+  };
+}

package/src/release-envelope/types.ts

@@ -1,7 +1,24 @@
-export const MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION = 3 as const;
+import type {
+  RendererIdentity,
+  RendererProfile,
+  RendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
 
-export const MICROVERTICAL_RELEASE_ENVELOPE_KIND =
-  'ultramodern-target-microvertical-release-envelope' as const;
+import {
+  MICROVERTICAL_RELEASE_ENVELOPE_KIND,
+  MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
+  SHELL_RELEASE_ENVELOPE_KIND,
+} from './contract.mjs';
+
+export {
+  MICROVERTICAL_RELEASE_ENVELOPE_KIND,
+  MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
+  SHELL_RELEASE_ENVELOPE_KIND,
+};
+
+export type ReleaseEnvelopeKind =
+  | typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND
+  | typeof SHELL_RELEASE_ENVELOPE_KIND;
 
 export const MICROVERTICAL_RELEASE_TARGETS = ['node', 'cloudflare'] as const;
 
@@ -48,17 +65,35 @@ export type MicroVerticalReleaseSurfaces = {
   uiClient: string[];
   ssr: string[];
   apiBackend: string[];
-  backendFederation: {
+  backendFederation?: {
     manifest: string;
     container: string;
   };
 };
 
+export type MicroVerticalReleaseUi = {
+  rendererIdentity: RendererIdentity;
+  rendererProfile: RendererProfile;
+  routerBindings: RendererRouterBindings;
+};
+
+/** A Shell consumes remotes; it never publishes a backend federation pair. */
+export type ShellReleaseSurfaces = {
+  uiClient: string[];
+  ssr: string[];
+  apiBackend: string[];
+};
+
+export type ReleaseSurfaces =
+  | MicroVerticalReleaseSurfaces
+  | ShellReleaseSurfaces;
+
 export type MicroVerticalReleaseEnvelopePayload = {
   schemaVersion: typeof MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION;
   kind: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
   target: MicroVerticalReleaseTarget;
   identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
   artifacts: MicroVerticalReleaseArtifact[];
   surfaces: MicroVerticalReleaseSurfaces;
 };
@@ -68,16 +103,50 @@ export type MicroVerticalReleaseEnvelope =
     envelopeDigest: string;
   };
 
+export type ShellReleaseEnvelopePayload = {
+  schemaVersion: typeof MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION;
+  kind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+  target: MicroVerticalReleaseTarget;
+  identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
+  artifacts: MicroVerticalReleaseArtifact[];
+  surfaces: ShellReleaseSurfaces;
+};
+
+export type ShellReleaseEnvelope = ShellReleaseEnvelopePayload & {
+  envelopeDigest: string;
+};
+
+export type ReleaseEnvelopePayload =
+  | MicroVerticalReleaseEnvelopePayload
+  | ShellReleaseEnvelopePayload;
+
+export type ReleaseEnvelope =
+  | MicroVerticalReleaseEnvelope
+  | ShellReleaseEnvelope;
+
 export type CreateMicroVerticalReleaseEnvelopeInput = {
   artifactRoot: string;
   target: MicroVerticalReleaseTarget;
   identity: MicroVerticalReleaseIdentity;
+  ui?: MicroVerticalReleaseUi;
   artifacts: MicroVerticalReleaseArtifactInput[];
-  surfaces: MicroVerticalReleaseSurfaces;
-};
+} & (
+  | {
+      kind?: typeof MICROVERTICAL_RELEASE_ENVELOPE_KIND;
+      surfaces: MicroVerticalReleaseSurfaces;
+    }
+  | {
+      kind: typeof SHELL_RELEASE_ENVELOPE_KIND;
+      surfaces: ShellReleaseSurfaces;
+    }
+);
 
 export type VerifyMicroVerticalReleaseEnvelopeOptions = {
   artifactRoot: string;
   logicalPathForArtifact?: (artifact: MicroVerticalReleaseArtifact) => string;
   expectedTarget?: MicroVerticalReleaseTarget;
+  expectedKind?: ReleaseEnvelopeKind;
+  expectedRendererIdentity?: RendererIdentity;
+  expectedRendererProfile?: RendererProfile;
 };

package/src/release-identity.ts

@@ -1,6 +1,9 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
+// The framework initializes this fixed reader before authored config observation.
+// Its commands remain private; authored subprocess APIs keep their own guards.
+const invokeGit = execFileSync;
 const BUILD_MARKER_NAMESPACE =
   'ultramodern-delivery-unit-release-build-marker:v1';
 const PROMOTABLE_SOURCE_REVISION_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
@@ -10,14 +13,24 @@ export type UltramodernReleaseIdentity = {
   sourceRevision: string;
 };
 
+// Inherited GIT_* variables (git hooks export GIT_DIR and GIT_INDEX_FILE)
+// would make git describe some other repository than `workspaceRoot`.
+const workspaceGitEnv = (): NodeJS.ProcessEnv =>
+  Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([name]) => !name.toUpperCase().startsWith('GIT_'),
+    ),
+  );
+
 const gitOutput = (
   workspaceRoot: string,
   args: string[],
 ): string | undefined => {
   try {
-    return execFileSync('git', args, {
+    return invokeGit('git', args, {
       cwd: workspaceRoot,
       encoding: 'utf8',
+      env: workspaceGitEnv(),
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
   } catch {
@@ -44,10 +57,11 @@ export const createUltramodernReleaseBuildMarker = ({
 export const resolveUltramodernSourceRevision = (
   workspaceRoot = process.cwd(),
   configuredSourceRevision?: string,
+  environment: Readonly<NodeJS.ProcessEnv> = process.env,
 ): string => {
   const configuredArgumentValue = configuredSourceRevision?.trim();
   const configuredEnvironmentValue =
-    process.env.ULTRAMODERN_SOURCE_REVISION?.trim();
+    environment.ULTRAMODERN_SOURCE_REVISION?.trim();
   const configuredArgument =
     configuredArgumentValue && configuredArgumentValue !== 'workspace'
       ? configuredArgumentValue
@@ -110,16 +124,19 @@ export const resolveUltramodernReleaseIdentity = ({
   sourceRevision: configuredSourceRevision,
   unitId,
   workspaceRoot,
+  environment,
 }: {
   generationBuildMarker: string;
   sourceRevision?: string;
   unitId: string;
   workspaceRoot?: string;
+  environment?: Readonly<NodeJS.ProcessEnv>;
 }): UltramodernReleaseIdentity => {
   const explicitSourceRevision = configuredSourceRevision?.trim();
   const sourceRevision = resolveUltramodernSourceRevision(
     workspaceRoot,
     explicitSourceRevision,
+    environment,
   );
   return {
     buildMarker:

package/src/renderer-build-identity.ts

@@ -0,0 +1,168 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  immutableRendererRouterBindings,
+  type RendererIdentity,
+  type RendererName,
+  type RendererProfile,
+  type RendererRouterBindings,
+  type RouterFramework,
+  validateRendererProfile,
+  validateRendererRouterBindings,
+} from '@modern-js/backend-federation-contracts';
+import { resolveUltramodernSourceRevision } from './release-identity';
+
+export type RendererProfileKeyInput = RendererProfile & {
+  readonly dependencies?: Readonly<Record<string, string>>;
+};
+
+export interface RendererBuildIdentityOptions {
+  projectRoot: string;
+  renderer: RendererName;
+  profile: RendererProfileKeyInput;
+  entryNames: readonly string[];
+  mode: 'development' | 'production';
+  /** Delivery-unit app id; defaults to the application package name. */
+  appId?: string;
+  /** Externally authenticated source revision (delivery unit or CI). */
+  sourceRevision?: string;
+  /** Actual final entry ownership, supplied by the selected renderer composition. */
+  routerBindings: RendererRouterBindings;
+  /** Admitted router frameworks, supplied by the selected renderer owner. */
+  routerFrameworks?: readonly RouterFramework[];
+}
+
+export interface RendererBuildIdentities {
+  readonly identities: Readonly<Record<string, RendererIdentity>>;
+  readonly buildId: string;
+  readonly profileKey: string;
+  readonly sourceRevision: string;
+  readonly routerBindings: RendererRouterBindings;
+}
+
+const LOCKFILES = [
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+];
+
+/** Stable per process: one dev session or dirty build keeps one buildId. */
+const processNonce = randomUUID();
+
+const sha256 = (value: string | Uint8Array) =>
+  createHash('sha256').update(value).digest('hex');
+
+/** Renderer, protocol and installed renderer/framework/compiler versions. */
+export function rendererProfileKey(profile: RendererProfileKeyInput): string {
+  return sha256(
+    JSON.stringify([
+      profile.renderer,
+      profile.protocolVersion,
+      profile.compiler,
+      profile.hydration,
+      profile.router,
+      Object.entries(profile.dependencies ?? {}).sort(([left], [right]) =>
+        left < right ? -1 : left > right ? 1 : 0,
+      ),
+    ]),
+  );
+}
+
+/** Hash of the nearest lockfile, or an empty marker when there is none. */
+function lockfileHash(projectRoot: string): string {
+  let directory = path.resolve(projectRoot);
+  for (;;) {
+    for (const name of LOCKFILES) {
+      try {
+        return sha256(fs.readFileSync(path.join(directory, name)));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return '';
+    directory = parent;
+  }
+}
+
+/** Resolve once per build before emitting entries; never rehashes sources. */
+export function resolveRendererBuildIdentities(
+  options: RendererBuildIdentityOptions,
+): RendererBuildIdentities {
+  const profile: RendererProfile = {
+    renderer: options.profile.renderer,
+    protocolVersion: options.profile.protocolVersion,
+    compiler: options.profile.compiler,
+    hydration: options.profile.hydration,
+    router: options.profile.router,
+  };
+  const validation = validateRendererProfile(profile);
+  if (!validation.ok || options.renderer !== profile.renderer)
+    throw new Error(
+      `Renderer/profile identity mismatch: ${JSON.stringify(validation.errors)}.`,
+    );
+  const entries = [...options.entryNames].sort();
+  if (
+    entries.length === 0 ||
+    new Set(entries).size !== entries.length ||
+    entries.some(value => !value || value === '__proto__')
+  )
+    throw new Error(
+      'Renderer build identity requires unique nonempty entry names.',
+    );
+  const routerValidation = validateRendererRouterBindings(
+    options.routerBindings,
+    entries,
+    'routerBindings',
+    options.routerFrameworks,
+  );
+  if (!routerValidation.ok)
+    throw new Error(
+      `Invalid renderer router bindings: ${JSON.stringify(routerValidation.errors)}.`,
+    );
+  const projectRoot = path.resolve(options.projectRoot);
+  const appId =
+    options.appId ??
+    JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'))
+      .name;
+  if (typeof appId !== 'string' || !appId || appId.trim() !== appId)
+    throw new Error(
+      'Renderer application identity requires a delivery artifact appId or a package name.',
+    );
+  const profileKey = rendererProfileKey(options.profile);
+  const sourceRevision = resolveUltramodernSourceRevision(
+    projectRoot,
+    options.sourceRevision,
+  );
+  const buildId = sha256(
+    JSON.stringify([
+      profileKey,
+      lockfileHash(projectRoot),
+      options.mode === 'development' || sourceRevision === 'workspace'
+        ? processNonce
+        : sourceRevision,
+    ]),
+  );
+  const identities = Object.fromEntries(
+    entries.map(entryName => [
+      entryName,
+      Object.freeze({
+        renderer: options.renderer,
+        appId,
+        entryName,
+        protocolVersion: 1 as const,
+        buildId,
+      }),
+    ]),
+  );
+  return Object.freeze({
+    identities: Object.freeze(identities),
+    buildId,
+    profileKey,
+    sourceRevision,
+    routerBindings: immutableRendererRouterBindings(options.routerBindings),
+  });
+}

package/src/runtime-package-resolution.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { RsbuildPlugin, Rspack } from '@rsbuild/core';
+
+/**
+ * A generated `runtime-register.js` lives inside the *application*, so every
+ * runtime plugin it imports has to resolve from the application's own
+ * `node_modules`. Packages registered by a CLI plugin are dependencies of that
+ * CLI plugin, not of the application, and under an isolated (pnpm) linker the
+ * application cannot see them — the build fails with `Module not found`.
+ *
+ * Instead of freezing a single resolved file (which would lock one export
+ * condition and break the web/node split), the registering package contributes
+ * the `node_modules` directory that actually hosts the package as a *fallback*
+ * module directory. Bare specifiers keep their normal `exports` resolution, the
+ * application's own copy still wins when it declares the dependency, and both
+ * the workspace source layout and a published pnpm layout work.
+ */
+export const findHostingModuleDirectory = (
+  packageName: string,
+  fromDirectory: string,
+): string | undefined => {
+  let directory = path.resolve(fromDirectory);
+  for (;;) {
+    const candidate = path.join(directory, 'node_modules');
+    if (fs.existsSync(path.join(candidate, packageName))) {
+      return candidate;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return undefined;
+    }
+    directory = parent;
+  }
+};
+
+/**
+ * Collect the fallback module directories for the given packages, starting the
+ * search at the module that registers them.
+ */
+export const collectRuntimePackageModuleDirectories = (
+  packageNames: readonly string[],
+  registrarUrl: string,
+): string[] => {
+  const registrarDirectory = path.dirname(fileURLToPath(registrarUrl));
+  const directories: string[] = [];
+  for (const packageName of packageNames) {
+    const directory = findHostingModuleDirectory(
+      packageName,
+      registrarDirectory,
+    );
+    if (directory && !directories.includes(directory)) {
+      directories.push(directory);
+    }
+  }
+  return directories;
+};
+
+const appendModuleDirectories = (
+  config: Rspack.Configuration,
+  directories: readonly string[],
+) => {
+  if (directories.length === 0) {
+    return;
+  }
+  config.resolve ??= {};
+  const existing = config.resolve.modules ?? ['node_modules'];
+  // Appended, never prepended: the application's own upward `node_modules`
+  // search keeps priority, so a declared dependency still wins.
+  config.resolve.modules = [
+    ...existing,
+    ...directories.filter(directory => !existing.includes(directory)),
+  ];
+};
+
+/**
+ * Rsbuild plugin that adds the given directories as fallback module roots for
+ * every environment (web, node and worker bundles alike).
+ */
+export const createRuntimePackageResolutionPlugin = (
+  directories: readonly string[],
+): RsbuildPlugin => ({
+  name: 'ultramodern:runtime-package-resolution',
+  setup(api) {
+    api.modifyRspackConfig({
+      order: 'post',
+      handler(config) {
+        appendModuleDirectories(config, directories);
+      },
+    });
+    api.onBeforeCreateCompiler({
+      order: 'post',
+      handler({ bundlerConfigs }) {
+        for (const config of bundlerConfigs) {
+          appendModuleDirectories(config, directories);
+        }
+      },
+    });
+  },
+});
+
+/** `true` when the package resolves from the registering module at all. */
+export const canResolveRuntimePackage = (
+  packageName: string,
+  registrarUrl: string,
+): boolean => {
+  try {
+    createRequire(registrarUrl).resolve(packageName);
+    return true;
+  } catch {
+    return false;
+  }
+};