@xemahq/api-client-generator 0.1.5 → 0.3.0

package/src/lib/custom-fetch-template.ts

@@ -0,0 +1,200 @@
+/**
+ * Canonical `custom-fetch.ts` body, identical to the hand-maintained mutator
+ * shipped in every existing client package. Used ONLY as the fallback when a
+ * freshly scaffolded surface client has no public-surface sibling to copy from
+ * (a pure-internal/operator service). Kept byte-identical to the committed
+ * version so all clients share one fetch implementation.
+ */
+export const CANONICAL_CUSTOM_FETCH = `/**
+ * Configurable fetch wrapper for Orval-generated clients.
+ *
+ * Consumers must call \`configureClient()\` before using any endpoint function.
+ * The baseUrl is prepended to the relative paths generated by Orval.
+ */
+
+export interface ClientConfig {
+  /** Static base URL (e.g. 'http://localhost:3140') — no trailing slash. */
+  baseUrl?: string;
+  /** Per-request base-URL resolver (service-registry-safe). */
+  baseUrlResolver?: () => string | Promise<string>;
+  /** Optional async callback to get an auth token. */
+  getAuthToken?: () => Promise<string>;
+  /** Optional callback returning headers to inject on every request. */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Optional callback invoked on 401 before a single retry. */
+  onUnauthorized?: () => Promise<void>;
+  /** Maximum retry attempts for transient failures (default: 3). */
+  maxRetries?: number;
+}
+
+export class ClientError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly url: string,
+    public readonly body: unknown,
+  ) {
+    super(\`HTTP \${status} from \${url}\`);
+    this.name = 'ClientError';
+  }
+}
+
+let clientConfig: ClientConfig | null = null;
+
+export function configureClient(config: ClientConfig): void {
+  clientConfig = config;
+}
+
+export function getClientConfig(): ClientConfig {
+  if (!clientConfig) {
+    throw new Error(
+      'Client not configured. Call configureClient({ baseUrl }) before using endpoint functions.',
+    );
+  }
+  return clientConfig;
+}
+
+const RETRYABLE_STATUSES = [429, 502, 503, 504];
+
+async function buildHeaders(
+  config: ClientConfig,
+  callerHeaders: RequestInit['headers'],
+): Promise<Headers> {
+  const headers = new Headers(callerHeaders);
+  if (config.getHeaders) {
+    const globalHeaders = await Promise.resolve(config.getHeaders());
+    for (const [key, value] of Object.entries(globalHeaders)) {
+      if (!headers.has(key)) {
+        headers.set(key, value);
+      }
+    }
+  }
+  if (config.getAuthToken && !headers.has('Authorization')) {
+    const token = await config.getAuthToken();
+    headers.set('Authorization', \`Bearer \${token}\`);
+  }
+  return headers;
+}
+
+export const customFetch = async <T>(
+  url: string,
+  options: RequestInit,
+): Promise<T> => {
+  const config = getClientConfig();
+  const base = config.baseUrlResolver
+    ? await config.baseUrlResolver()
+    : config.baseUrl;
+  if (base === undefined) {
+    throw new Error(
+      'Client not configured: set baseUrl or baseUrlResolver via configureClient().',
+    );
+  }
+  const fullUrl = \`\${base}\${url}\`;
+  const maxRetries = config.maxRetries ?? 3;
+
+  const headers = await buildHeaders(config, options.headers);
+  const requestInit: RequestInit = { ...options, headers };
+
+  let delay = 1000;
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(fullUrl, requestInit);
+
+      if (response.status === 401 && config.onUnauthorized && attempt === 0) {
+        await config.onUnauthorized();
+        const refreshedHeaders = await buildHeaders(config, options.headers);
+        const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });
+        const retryBody = await parseBody(retryResponse);
+        if (retryResponse.status >= 400) {
+          throw new ClientError(retryResponse.status, fullUrl, retryBody);
+        }
+        return unwrapEnvelope(retryBody) as T;
+      }
+
+      if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {
+        const body = await parseBody(response);
+        if (response.status >= 400) {
+          throw new ClientError(response.status, fullUrl, body);
+        }
+        return unwrapEnvelope(body) as T;
+      }
+
+      const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
+      const waitMs = retryAfter ?? addJitter(delay);
+      await sleep(waitMs);
+      delay = Math.min(delay * 2, 30_000);
+    } catch (error) {
+      if (error instanceof ClientError) throw error;
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt >= maxRetries) throw lastError;
+      const waitMs = addJitter(delay);
+      await sleep(waitMs);
+      delay = Math.min(delay * 2, 30_000);
+    }
+  }
+
+  throw lastError ?? new Error(\`All retries exhausted for \${fullUrl}\`);
+};
+
+/**
+ * Xema platform services wrap every 2xx payload in a { data: T } envelope via
+ * the global ResponseEnvelopeInterceptor (platform-common). Generated types
+ * describe the INNER T (controllers declare their return type as T, not
+ * { data: T }), so the client must peel data to keep the static types and the
+ * wire shape consistent — otherwise consumers read fields off the envelope and
+ * get undefined.
+ *
+ * Only 2xx bodies reach this helper: non-2xx responses are surfaced as a thrown
+ * ClientError before unwrap, and error envelopes are emitted by the
+ * GlobalExceptionFilter, never wrapped in { data }. Paginated lists arrive as
+ * { data: T[], pagination: {...} }; consumers read both fields, so that envelope
+ * is kept intact (detected by the presence of pagination). Any body without a
+ * top-level data field is returned as-is.
+ */
+function unwrapEnvelope(body: unknown): unknown {
+  if (
+    body === null ||
+    typeof body !== 'object' ||
+    Array.isArray(body) ||
+    !('data' in body)
+  ) {
+    return body;
+  }
+  const envelope = body as { data: unknown; pagination?: unknown };
+  if ('pagination' in envelope) {
+    return envelope;
+  }
+  return envelope.data;
+}
+
+async function parseBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type');
+  if (contentType?.includes('application/json')) {
+    return response.json();
+  }
+  if (response.status === 204) {
+    return undefined;
+  }
+  return response.text();
+}
+
+function parseRetryAfter(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (!isNaN(seconds) && seconds >= 0) return seconds * 1000;
+  const date = new Date(value);
+  if (!isNaN(date.getTime())) return Math.max(0, date.getTime() - Date.now());
+  return undefined;
+}
+
+function addJitter(delay: number): number {
+  return delay + (Math.random() * 2 - 1) * delay * 0.25;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export default customFetch;
+`;

package/src/lib/default-stubs.ts

@@ -0,0 +1,422 @@
+import { dirname, join } from 'node:path';
+
+import type { TestingModuleBuilder } from '@nestjs/testing';
+
+/**
+ * Layer 2 of the DI-stub strategy: convention stubs applied to every service.
+ *
+ * Each token is resolved DYNAMICALLY from the service's own `node_modules`
+ * (or, for `PrismaService`, the conventional `src/prisma/prisma.service`
+ * path) so the generator stays decoupled — it declares no dependency on
+ * identity-client / event-hub-client / platform-common / the service's prisma
+ * module. A token that does not resolve is simply skipped (the service does
+ * not use it). A resolved token that is not actually in the DI graph yields a
+ * harmless unused override.
+ *
+ * This is NOT a heuristic: the conventional prisma path either resolves to a
+ * real module or it does not. When a service's wiring needs something beyond
+ * this baseline, it supplies an `openapi.overrides.ts` (Layer 3).
+ */
+
+/** Resolve a module export from the service's resolution root; undefined if absent. */
+function tryResolveExport(
+  fromDir: string,
+  request: string,
+  exportName: string,
+): unknown {
+  try {
+    const resolved = require.resolve(request, { paths: [fromDir] });
+
+    const mod = require(resolved) as Record<string, unknown>;
+    return mod[exportName];
+  } catch {
+    return undefined;
+  }
+}
+
+/** The service's package.json `name` (used only for dummy identity registration
+ * fields that extraction never dials); falls back to the directory basename. */
+function readServiceName(serviceDir: string): string {
+  try {
+    const pkg = require(join(serviceDir, 'package.json')) as { name?: string };
+    if (typeof pkg.name === 'string' && pkg.name.length > 0) {
+      return pkg.name;
+    }
+  } catch {
+    // no readable package.json — fall through to the basename.
+  }
+  return (
+    dirname(join(serviceDir, 'x')).split(/[\\/]/).pop() ?? 'openapi-service'
+  );
+}
+
+/**
+ * The two accessors `@xemahq/biome-database-nest` declares as returning a
+ * CLIENT rather than a query result (`prisma-service-factory.ts`:
+ * `asSystem(): TClient`, `forOrg(orgId): TClient`).
+ *
+ * They must return the stub itself. The proxy's `apply` trap answers every
+ * call with `Promise.resolve([])`, which is right for a query but wrong for
+ * an accessor — `prisma.asSystem()` yielded a Promise, so every consumer that
+ * reads a property off the returned client saw `undefined`. That is not a
+ * cosmetic mismatch: `OrgErasureModule`'s boot gate reads
+ * `client._runtimeDataModel.models` off it and refuses to start, which broke
+ * OpenAPI extraction for EVERY service using org-erasure.
+ *
+ * A closed set from a typed interface, not a growing list of guessed names.
+ */
+const CLIENT_ACCESSORS: ReadonlySet<string> = new Set(['asSystem', 'forOrg']);
+
+/**
+ * The real model list, read from the service's GENERATED Prisma client
+ * without instantiating it or touching a database.
+ *
+ * `OrgErasureModule` asserts at boot that its `orgField` matches at least one
+ * model — a participant matching none would answer every erasure
+ * `{totalDeleted: 0}` and have it recorded as success. Handing the extraction
+ * an empty or fabricated model list would either defeat that gate or trip it
+ * for the wrong reason, so the stub carries the schema the service actually
+ * generated.
+ */
+function readGeneratedModels(
+  serviceDir: string,
+): Record<string, { readonly fields: readonly { readonly name: string }[] }> {
+  const client = tryResolveExport(serviceDir, '@prisma/client', 'Prisma') as
+    | { dmmf?: { datamodel?: { models?: readonly PrismaDmmfModel[] } } }
+    | undefined;
+  const models = client?.dmmf?.datamodel?.models;
+  if (models === undefined) {
+    throw new Error(
+      `[openapi-stubs] ${serviceDir} has a PrismaService but its generated ` +
+        `Prisma client exposes no dmmf datamodel. Run \`pnpm prisma:generate\` ` +
+        `in that service before extracting — the extraction cannot fabricate a ` +
+        `schema, and a service using OrgErasureModule asserts against it at boot.`,
+    );
+  }
+  return Object.fromEntries(models.map((model) => [model.name, model]));
+}
+
+interface PrismaDmmfModel {
+  readonly name: string;
+  readonly fields: readonly { readonly name: string }[];
+}
+
+/** The defensive Prisma stub the hand-written scripts used: every access is a no-op thenable-free proxy. */
+function createPrismaStub(serviceDir: string): unknown {
+  const runtimeDataModel = { models: readGeneratedModels(serviceDir) };
+  const handler: ProxyHandler<(...args: unknown[]) => unknown> = {
+    get: (_t, prop) => {
+      if (prop === 'then') {
+        return undefined;
+      }
+      if (prop === '_runtimeDataModel') {
+        return runtimeDataModel;
+      }
+      if (prop === '$connect' || prop === '$disconnect' || prop === '$on') {
+        return () => Promise.resolve();
+      }
+      if (typeof prop === 'string' && CLIENT_ACCESSORS.has(prop)) {
+        return () => stub;
+      }
+      return new Proxy(() => Promise.resolve([]), handler);
+    },
+    apply: () => Promise.resolve([]),
+  };
+  const stub: unknown = new Proxy({} as never, handler);
+  return stub;
+}
+
+const IDENTITY_STUB = {
+  waitForReady: () => Promise.resolve(true),
+  getAccessToken: () => Promise.resolve('dummy-token'),
+  getKeycloakBaseUrl: () => 'http://localhost:8180',
+  getAllowedRealms: () => ['master'],
+  getClientId: () => 'openapi-extraction',
+};
+
+const EVENT_HUB_BOOTSTRAP_STUB = {
+  onModuleInit: async () => {},
+  onModuleDestroy: async () => {},
+  isEventHubRegistered: () => true,
+  waitForRegistration: () => Promise.resolve(true),
+};
+
+const EVENT_HUB_CLIENT_STUB = {
+  getAuthInfo: () => ({
+    jwksUrl: 'http://localhost:8180/realms/dummy/protocol/openid-connect/certs',
+    issuer: 'http://localhost:8180/realms/dummy',
+  }),
+};
+
+/**
+ * `@nestjs/core` provider CLASSES that a foreign-core dependency injects and that
+ * are only STORED (or used at a bootstrap phase extraction SKIPS), never during
+ * the metadata-only DI compile — so an inert cross-store stand-in is safe:
+ *
+ * - `ModuleRef` — `@xemahq/xema-service-nest` injects it into the
+ *   `ServiceRegistryModule` options factory to LAZILY resolve
+ *   `IdentityBootstrapService` for request-time service-token minting (a genuine
+ *   module-init value cycle forbids injecting the service directly). The closure
+ *   is never invoked during extraction.
+ * - `Reflector` — `@nestjs/schedule`'s `SchedulerMetadataAccessor` injects it;
+ *   it is read only by the scheduler's `onApplicationBootstrap` scan, which
+ *   extraction never runs. The api-surface scan reads decorator metadata through
+ *   the global `reflect-metadata` polyfill, NOT a Nest `Reflector`, so stubbing
+ *   this token does not affect classification.
+ */
+const BRIDGED_CORE_PROVIDERS = ['ModuleRef', 'Reflector'] as const;
+
+/**
+ * Dependencies that inject an `@nestjs/core` provider resolved from their OWN
+ * peer copy of `@nestjs/core`. In a multi-`@nestjs/core` checkout each resolves a
+ * copy DISTINCT from the service's, so the provider CLASS they inject mismatches
+ * the one the app's module registered under.
+ */
+const FOREIGN_CORE_INJECTORS = [
+  '@xemahq/xema-service-nest',
+  '@xemahq/service-registry-nest',
+  '@nestjs/schedule',
+];
+
+/**
+ * Apply the convention stubs to a `Test.createTestingModule(...)` builder.
+ * Returns the same builder for chaining.
+ */
+export function applyDefaultOpenApiStubs(
+  builder: TestingModuleBuilder,
+  serviceDir: string,
+): TestingModuleBuilder {
+  // PrismaService — conventional service-local path.
+  const PrismaService = tryResolveExport(
+    serviceDir,
+    join(serviceDir, 'src', 'prisma', 'prisma.service'),
+    'PrismaService',
+  );
+  if (PrismaService) {
+    builder
+      .overrideProvider(PrismaService as never)
+      .useValue(createPrismaStub(serviceDir));
+  }
+
+  // Identity bootstrap.
+  const IdentityBootstrapService = tryResolveExport(
+    serviceDir,
+    '@xemahq/identity-client',
+    'IdentityBootstrapService',
+  );
+  if (IdentityBootstrapService) {
+    builder
+      .overrideProvider(IdentityBootstrapService as never)
+      .useValue(IDENTITY_STUB);
+  }
+
+  // Identity bootstrap CONFIG. `IdentityBootstrapModule.forRootAsync`'s options
+  // factory eagerly resolves `identity-api` from the service registry
+  // (`resolveHttpUrlEagerly`) at DI-compile time — which cannot succeed in an
+  // extraction sandbox (no live registry). Overriding the resolved config token
+  // skips that factory entirely; the `IdentityBootstrapService` that consumes it
+  // is already stubbed above, so these values are never read.
+  const IDENTITY_BOOTSTRAP_CONFIG = tryResolveExport(
+    serviceDir,
+    '@xemahq/identity-client',
+    'IDENTITY_BOOTSTRAP_CONFIG',
+  );
+  if (IDENTITY_BOOTSTRAP_CONFIG) {
+    builder.overrideProvider(IDENTITY_BOOTSTRAP_CONFIG as never).useValue({
+      identityApiUrl: 'http://localhost:3053',
+      identityApiInternalToken: 'dummy-token',
+      serviceName: readServiceName(serviceDir),
+      serviceDisplayName: readServiceName(serviceDir),
+    });
+  }
+
+  // Event hub.
+  const EventHubBootstrapService = tryResolveExport(
+    serviceDir,
+    '@xemahq/event-hub-client',
+    'EventHubBootstrapService',
+  );
+  if (EventHubBootstrapService) {
+    builder
+      .overrideProvider(EventHubBootstrapService as never)
+      .useValue(EVENT_HUB_BOOTSTRAP_STUB);
+  }
+  const EventHubClient = tryResolveExport(
+    serviceDir,
+    '@xemahq/event-hub-client',
+    'EventHubClient',
+  );
+  if (EventHubClient) {
+    builder
+      .overrideProvider(EventHubClient as never)
+      .useValue(EVENT_HUB_CLIENT_STUB);
+  }
+
+  // Service-token guard (let every route through during extraction).
+  const ServiceTokenGuard = tryResolveExport(
+    serviceDir,
+    '@xemahq/platform-common',
+    'ServiceTokenGuard',
+  );
+  if (ServiceTokenGuard) {
+    builder
+      .overrideGuard(ServiceTokenGuard as never)
+      .useValue({ canActivate: () => true });
+  }
+
+  // XemaRuntimeScanner — stub so it never runs during extraction (manifest
+  // emission / capability auto-register are irrelevant to spec extraction).
+  const XemaRuntimeScanner = tryResolveExport(
+    serviceDir,
+    '@xemahq/xema-decorators',
+    'XemaRuntimeScanner',
+  );
+  if (XemaRuntimeScanner) {
+    builder.overrideProvider(XemaRuntimeScanner as never).useValue({
+      onApplicationBootstrap: async () => {},
+    });
+  }
+
+  // DiscoveryModule instantiates `DiscoveryService` EAGERLY (it is a provider,
+  // not lazy). Under local cross-repo dev the symlinked `@xemahq/xema-decorators`
+  // resolves a DIFFERENT `@nestjs/core` store than the service, so the
+  // DiscoveryService token built into the app may carry a `ModulesContainer`
+  // the service-store testing container can't resolve. Override it (from both
+  // the service's and the decorators' core stores) with an inert stub: the
+  // token actually in the graph is replaced; the other is a harmless no-op
+  // (CI's single-core per-repo install has only one). Spec extraction never
+  // needs it — the surface scan builds a fresh DiscoveryService from the app's
+  // real ModulesContainer afterwards.
+  //
+  // NOTE (local-dev only): other infra modules that eagerly inject core
+  // internals under a FOREIGN `@nestjs/core` hit the same multi-store mismatch
+  // locally — e.g. `@nestjs/schedule`'s `DiscoveryModule` provides its own
+  // `DiscoveryService` (→ `ModulesContainer`). We therefore override
+  // `DiscoveryService` in EVERY reachable core store (the service's, the
+  // decorators', and each foreign-core injector's). The exported core PROVIDER
+  // tokens those foreign modules inject (`Reflector`, `ModuleRef`) are bridged
+  // separately by {@link applyCrossStoreCoreProviderBridge}. The definitive fix
+  // remains a single `@nestjs/core` (which CI's standalone per-repo install
+  // gives); this is the aggregator/local-dev compensation.
+  const discoveryStub = { getProviders: () => [], getControllers: () => [] };
+  const coreRoots = new Set<string>([serviceDir]);
+  for (const pkg of ['@xemahq/xema-decorators', ...FOREIGN_CORE_INJECTORS]) {
+    try {
+      coreRoots.add(dirname(require.resolve(pkg, { paths: [serviceDir] })));
+    } catch {
+      // package not resolvable from this service — nothing to add for it.
+    }
+  }
+  const seenDiscovery = new Set<unknown>();
+  for (const root of coreRoots) {
+    const DiscoveryService = tryResolveExport(
+      root,
+      '@nestjs/core',
+      'DiscoveryService',
+    );
+    if (DiscoveryService && !seenDiscovery.has(DiscoveryService)) {
+      seenDiscovery.add(DiscoveryService);
+      builder
+        .overrideProvider(DiscoveryService as never)
+        .useValue(discoveryStub);
+    }
+  }
+
+  // Service registry — the permissive build-time stub.
+  const SERVICE_REGISTRY_TOKEN = tryResolveExport(
+    serviceDir,
+    '@xemahq/service-registry-nest',
+    'SERVICE_REGISTRY_TOKEN',
+  );
+  const createOpenApiStubRegistry = tryResolveExport(
+    serviceDir,
+    '@xemahq/service-registry-nest',
+    'createOpenApiStubRegistry',
+  ) as (() => unknown) | undefined;
+  if (SERVICE_REGISTRY_TOKEN && createOpenApiStubRegistry) {
+    builder
+      .overrideProvider(SERVICE_REGISTRY_TOKEN as never)
+      .useValue(createOpenApiStubRegistry());
+  }
+
+  applyCrossStoreCoreProviderBridge(builder, serviceDir);
+
+  return builder;
+}
+
+/**
+ * Bridge cross-store `@nestjs/core` provider tokens across a dual-`@nestjs/core`
+ * checkout.
+ *
+ * A core-provider inject (`ModuleRef`, `Reflector`, …) is a lookup keyed by the
+ * provider CLASS OBJECT. NestJS registers one instance per module under the class
+ * from the `@nestjs/core` that INSTANTIATED the module — the SERVICE's copy, since
+ * `Test`/`NestFactory` are resolved from `serviceDir`. In a cross-repo / workspace
+ * checkout a symlinked dependency (e.g. `@xemahq/xema-service-nest`,
+ * `@nestjs/schedule`) resolves its OWN `@nestjs/core` via realpath, so the class it
+ * bakes into an `inject` array is a DIFFERENT object than the app's →
+ * `providers.has(Token)` is false → construction fails under BOTH `Test.compile()`
+ * AND `NestFactory` (this is a token-identity fault, not a boot-method one).
+ * Production and standalone-CI are single-`@nestjs/core`, so the class objects
+ * coincide and this never bites there — hence the bridge is a no-op when the
+ * foreign copy IS the service's copy.
+ *
+ * The cross-store token is resolved to an inert stand-in that FAIL-FASTS if any of
+ * its methods are actually called (they never are during a metadata-only compile).
+ * Every OTHER unresolved token returns `undefined`, so the `TestingInjector`
+ * rethrows as normal — no broad silent mocking, no swallowed dependency error.
+ * This extends `service-nest.ts`'s dual-store strategy to the core providers that
+ * cannot be redirected by resolving Nest from the service dir (their tokens are
+ * baked into module metadata at `AppModule` import time, before the generator gets
+ * control).
+ */
+function applyCrossStoreCoreProviderBridge(
+  builder: TestingModuleBuilder,
+  serviceDir: string,
+): void {
+  const serviceProviders = BRIDGED_CORE_PROVIDERS.map((name) =>
+    tryResolveExport(serviceDir, '@nestjs/core', name),
+  );
+  const crossStore = new Set<unknown>();
+  for (const pkg of FOREIGN_CORE_INJECTORS) {
+    let pkgDir: string;
+    try {
+      pkgDir = dirname(require.resolve(pkg, { paths: [serviceDir] }));
+    } catch {
+      continue; // service does not depend on this package.
+    }
+    BRIDGED_CORE_PROVIDERS.forEach((name, i) => {
+      const foreign = tryResolveExport(pkgDir, '@nestjs/core', name);
+      // Only a copy DISTINCT from the service's own is a hazard; a single-core
+      // install resolves to the same class object → nothing to bridge.
+      if (foreign && foreign !== serviceProviders[i]) {
+        crossStore.add(foreign);
+      }
+    });
+  }
+  if (crossStore.size === 0) {
+    return; // single `@nestjs/core` end-to-end — every inject resolves natively.
+  }
+  // An inert stand-in. Property READS return a fail-fast function (so NestJS's
+  // benign resolution-time introspection — e.g. the `.then` thenable probe, which
+  // returns `undefined` — does not throw), and only CALLING a method fail-fasts.
+  const failFast = (): never => {
+    throw new Error(
+      'api-client-generator: a cross-store @nestjs/core provider stub was invoked ' +
+        'during OpenAPI extraction. It exists only so a provider can be CONSTRUCTED; ' +
+        'it must never be called (extraction skips app.init() and serves no request).',
+    );
+  };
+  const inert = new Proxy(
+    {},
+    {
+      get(_target, prop): unknown {
+        if (prop === 'then' || typeof prop === 'symbol') {
+          return undefined; // thenable / well-known-symbol probes stay benign.
+        }
+        return failFast;
+      },
+    },
+  );
+  builder.useMocker((token) => (crossStore.has(token) ? inert : undefined));
+}