@xemahq/api-client-generator 0.2.0 → 0.3.0

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));
+}

package/src/lib/extract-openapi.ts

@@ -0,0 +1,240 @@
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  ALL_SURFACES,
+  type ApiSurface,
+  assertNoUnclassifiedSurfaces,
+  collectOperationIds,
+  formatRouteExtensionCoverage,
+  pruneSpecForSurface,
+  scanApiSurfaces,
+  stampRouteExtensions,
+  type OpenApiDoc,
+} from '@xemahq/xema-decorators';
+
+import { applyDefaultOpenApiStubs } from './default-stubs';
+import { loadServiceOverrides } from './overrides';
+import { seedOpenApiEnv } from './seed-openapi-env';
+import {
+  resolveServiceContext,
+  surfaceSpecPath,
+  type ResolvedServiceContext,
+} from './service-config';
+import { loadServiceNest, type ServiceNest } from './service-nest';
+
+import type { INestApplication } from '@nestjs/common';
+
+async function buildApp(
+  ctx: ResolvedServiceContext,
+  nest: ServiceNest,
+): Promise<INestApplication> {
+  // AppModule is required lazily, AFTER env seeding, so its import-time
+  // `process.env` reads see the dummies.
+
+  const appModuleMod = require(join(ctx.serviceDir, 'src', 'app.module')) as {
+    AppModule: unknown;
+  };
+  if (!appModuleMod.AppModule) {
+    throw new Error(
+      `api-client-generator: ${join(ctx.serviceDir, 'src/app.module')} does not ` +
+        `export \`AppModule\`.`,
+    );
+  }
+  let builder = nest.Test.createTestingModule({
+    imports: [appModuleMod.AppModule as never],
+  });
+  builder = applyDefaultOpenApiStubs(builder, ctx.serviceDir);
+  const overrides = loadServiceOverrides(ctx.serviceDir);
+  if (overrides?.applyOverrides) {
+    builder = overrides.applyOverrides(builder) ?? builder;
+  }
+  const moduleRef = await builder.compile();
+  // Deliberately skip app.init(): SwaggerModule only needs compiled decorator
+  // metadata, and init() would fire onModuleInit hooks that hit real DBs.
+  return moduleRef.createNestApplication();
+}
+
+/**
+ * Boot the service, build one OpenAPI document per non-empty {@link ApiSurface},
+ * and write `openapi.<surface>.json` files at the service root. Stale spec
+ * files for surfaces that became empty are deleted so `openapi:check` stays
+ * honest.
+ *
+ * Fail-fast on any route that resolves to no surface (the `api-surface:check`
+ * gate) and on any document operation the surface scan never saw (no silent
+ * drop).
+ *
+ * @returns the surfaces that were written.
+ */
+export async function extractOpenApiForService(
+  serviceDir: string = process.cwd(),
+  /**
+   * Write the specs here instead of into the service directory. Used by the
+   * code→spec drift gate so it can extract on a dirty tree without clobbering
+   * uncommitted work. Omitted everywhere else, which keeps `pnpm openapi`
+   * behaviour byte-identical.
+   */
+  outDir?: string,
+): Promise<ApiSurface[]> {
+  // Layer 1 + (Layer 3 env) BEFORE importing AppModule. `resolveServiceContext`
+  // only reads `package.json`, so it is safe to run before the env is seeded —
+  // and the serviceId it yields is what makes the scratch DB schema unique per
+  // service under parallel extraction.
+  const ctx = resolveServiceContext(serviceDir);
+  seedOpenApiEnv(ctx.api.serviceId);
+  const overrides = loadServiceOverrides(ctx.serviceDir);
+  if (overrides?.env) {
+    for (const [k, v] of Object.entries(overrides.env)) {
+      if (process.env[k] === undefined) {
+        process.env[k] = v;
+      }
+    }
+  }
+
+  const nest = loadServiceNest(ctx.serviceDir);
+  const app = await buildApp(ctx, nest);
+  try {
+    const builder = new nest.DocumentBuilder()
+      .setTitle(ctx.api.title)
+      .setVersion(ctx.version)
+      .addBearerAuth();
+    if (ctx.api.description) {
+      builder.setDescription(ctx.api.description);
+    }
+    const fullDoc = nest.SwaggerModule.createDocument(app, builder.build(), {
+      operationIdFactory: (controllerKey: string, methodKey: string) =>
+        `${controllerKey}_${methodKey}`,
+    }) as unknown as OpenApiDoc;
+
+    // Construct DiscoveryService directly from the app's ModulesContainer
+    // (always available) rather than app.get(DiscoveryService) — the latter
+    // would trigger on-demand instantiation that can't see ModulesContainer in
+    // the root context.
+    const modulesContainer = app.get(nest.ModulesContainer, { strict: false });
+    const discovery = new nest.DiscoveryService(modulesContainer);
+    const metadataScanner = new nest.MetadataScanner();
+    const scan = scanApiSurfaces(discovery, metadataScanner);
+
+    // A route needs a surface ONLY if it actually appears in the OpenAPI
+    // document. Routes excluded from the spec (`@ApiExcludeController` /
+    // `@ApiExcludeEndpoint`, e.g. health probes and event listeners) ship in
+    // no client, so they need no surface — they are not candidates.
+    const docOps = collectOperationIds(fullDoc);
+    const unclassifiedInDoc = scan.unclassified.filter((u) =>
+      docOps.has(u.operationId),
+    );
+    if (unclassifiedInDoc.length > 0) {
+      assertNoUnclassifiedSurfaces(ctx.api.serviceId, {
+        unclassified: unclassifiedInDoc,
+      });
+    }
+    // No silent drop: a doc operation the scan never saw at all (in neither
+    // surfaces, excluded, nor unclassified) means a spec-only route the
+    // runtime scan can't reach — fail fast rather than drop it.
+    const seen = new Set<string>([
+      ...scan.surfaces.keys(),
+      ...scan.excluded,
+      ...scan.unclassified.map((u) => u.operationId),
+    ]);
+    const unaccounted = [...docOps].filter((id) => !seen.has(id));
+    if (unaccounted.length > 0) {
+      throw new Error(
+        `api-client-generator: ${ctx.api.serviceId} has ${unaccounted.length} ` +
+          `OpenAPI operation(s) the surface scan never saw ` +
+          `(${unaccounted.join(', ')}). A controller is emitted into the spec ` +
+          `but unreachable from the DiscoveryService scan.`,
+      );
+    }
+
+    // Publish the route metadata the platform already computes as `x-xema-*`
+    // extensions ON THE FULL DOCUMENT, before pruning. The pruner is
+    // deletion-only, so every per-surface spec inherits the extensions without
+    // a second pass, and each spec is a faithful subset of what a live pod
+    // serves at `/api/openapi.json`.
+    //
+    // Coverage is LOGGED, not enforced: `surface` is complete by construction
+    // (see the assert above) but `resource`/`action`/`permission` depend on
+    // `@XemaResource`/`@XemaRoute` adoption, which is deliberately absent on
+    // `@XemaPublicRoute`/`@XemaInternalRoute` handlers. Failing here would red
+    // every service's build for a gap this wave does not own; omitting the key
+    // and printing the count keeps the gap visible and measurable instead.
+    const coverage = stampRouteExtensions(fullDoc, scan.projections);
+
+    const written: ApiSurface[] = [];
+    const emitted = new Set<string>();
+    for (const surface of ALL_SURFACES) {
+      const keep = new Set<string>(
+        [...scan.surfaces.entries()]
+          .filter(([, s]) => s === surface)
+          .map(([id]) => id),
+      );
+      const specPath = surfaceSpecPath(ctx, surface, outDir);
+      const { doc, pathCount } = pruneSpecForSurface(fullDoc, keep);
+      if (pathCount === 0) {
+        // Surface has no endpoints → emit nothing; clean any stale file.
+        if (existsSync(specPath)) {
+          rmSync(specPath);
+        }
+        continue;
+      }
+      for (const id of collectOperationIds(doc)) {
+        emitted.add(id);
+      }
+      writeFileSync(specPath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+      written.push(surface);
+    }
+
+    // Closing the loop on "no silent drop": the checks above prove every doc
+    // operation was CLASSIFIED; this one proves every classified operation was
+    // actually WRITTEN. Together they make the union of the per-surface specs a
+    // lossless partition of the full document, so a pruner/classifier defect
+    // can never quietly shrink a spec (and, downstream, truncate a client) —
+    // it reds the build instead.
+    const expected = [...docOps].filter(
+      (id) => scan.surfaces.has(id) && !scan.excluded.has(id),
+    );
+    const lost = expected.filter((id) => !emitted.has(id));
+    if (lost.length > 0) {
+      throw new Error(
+        `api-client-generator: ${ctx.api.serviceId} classified ` +
+          `${expected.length} OpenAPI operation(s) but only wrote ` +
+          `${emitted.size} — ${lost.length} operation(s) were lost between the ` +
+          `document and the per-surface spec(s) (${lost.join(', ')}). The ` +
+          `emitted spec would be incomplete and would truncate the generated ` +
+          `client.`,
+      );
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[xema-openapi] ${ctx.api.serviceId}: wrote ${
+        written.length
+      } surface spec(s) → ${written.join(', ') || '(none)'} ` +
+        `[${formatRouteExtensionCoverage(coverage)}]`,
+    );
+    return written;
+  } finally {
+    await app.close().catch(() => {});
+  }
+}
+
+/** CLI entry: run extraction from cwd; exit non-zero on failure. */
+export function runOpenApiCli(): void {
+  // `--out-dir <path>` redirects the specs out of the service directory. The
+  // only caller is the code→spec drift gate; without an argument the CLI is
+  // byte-for-byte what `pnpm openapi` has always done.
+  const flagIndex = process.argv.indexOf('--out-dir');
+  if (flagIndex !== -1 && process.argv[flagIndex + 1] === undefined) {
+    console.error('[xema-openapi] --out-dir requires a path');
+    process.exit(1);
+  }
+  const outDir = flagIndex === -1 ? undefined : process.argv[flagIndex + 1];
+
+  extractOpenApiForService(process.cwd(), outDir)
+    .then(() => process.exit(0))
+    .catch((err: unknown) => {
+      console.error('[xema-openapi] extraction failed:', err);
+      process.exit(1);
+    });
+}