@xemahq/api-client-generator 0.1.5 → 0.3.0

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

package/src/lib/generate-clients.ts

@@ -0,0 +1,240 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { ALL_SURFACES, type ApiSurface } from '@xemahq/xema-decorators';
+
+import { ensureClientPackage } from './client-package';
+import { ensureClientReadme } from './client-readme';
+import { postProcessClient } from './repo-post-process';
+import {
+  resolveServiceContext,
+  surfaceClientDir,
+  surfaceClientPackageName,
+  surfaceSpecPath,
+  type ResolvedServiceContext,
+} from './service-config';
+
+/**
+ * Native dynamic import of a module resolved from the SERVICE's node_modules
+ * (so we use the service's orval, not the generator's). `new Function` keeps
+ * the `import()` from being downleveled to `require()` by the CJS transpile,
+ * so an ESM-only orval still loads.
+ */
+async function importFromService(
+  serviceDir: string,
+  request: string,
+): Promise<Record<string, unknown>> {
+  const resolved = require.resolve(request, { paths: [serviceDir] });
+  const dynamicImport = new Function('u', 'return import(u)') as (
+    u: string,
+  ) => Promise<Record<string, unknown>>;
+  return dynamicImport(pathToFileURL(resolved).href);
+}
+
+type OrvalGenerate = (config: unknown) => Promise<unknown>;
+
+async function resolveOrvalGenerate(
+  serviceDir: string,
+): Promise<OrvalGenerate> {
+  const mod = await importFromService(serviceDir, 'orval');
+  const generate =
+    (mod.generate as OrvalGenerate | undefined) ??
+    (mod.default as { generate?: OrvalGenerate } | undefined)?.generate;
+  if (typeof generate !== 'function') {
+    throw new Error(
+      'api-client-generator: could not resolve orval `generate` from the service.',
+    );
+  }
+  return generate;
+}
+
+/**
+ * In-memory orval config equivalent to the legacy per-service orval.config.ts.
+ * orval's programmatic `generate()` expects a SINGLE normalized project config
+ * (`{ input, output }`), not the named-project map the CLI reads from a file.
+ */
+function orvalConfigFor(specPath: string, clientSrc: string): unknown {
+  return {
+    input: { target: specPath },
+    output: {
+      mode: 'tags-split',
+      target: `${clientSrc}/endpoints`,
+      schemas: `${clientSrc}/models`,
+      client: 'fetch',
+      override: {
+        fetch: { includeHttpResponseReturnType: false },
+        mutator: {
+          path: `${clientSrc}/custom-fetch.ts`,
+          name: 'customFetch',
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Orphan backlog, keyed `<serviceId>:<surface>` → why it is not fixable from
+ * the generator. **Currently EMPTY, and it must stay that way.**
+ *
+ * It briefly carried five entries: services that capability auto-projection had
+ * reclassified fully-internal without retiring their PUBLIC-surface client
+ * package. All five are resolved — `audit-log-api` regained a genuine Public
+ * surface (two `platform_admin` browser reads); `biome-fetcher-api`,
+ * `policy-distributor-api`, `workspace-git-api` and
+ * `workspace-storage-pool-api` are service-to-service only and their public
+ * client packages were deleted.
+ *
+ * An entry here is a tracked backlog item, never a silent pass — the same
+ * contract as `tooling/boundaries/stack-confidentiality-baseline.json`. Adding
+ * one buys time for a condition the generator genuinely cannot resolve; it is
+ * NOT a place to park a newly-orphaned client. Resolve the orphan instead:
+ * either the service emits the surface (fix the classification at the route,
+ * and give it a real guard) or it does not (delete the package and migrate
+ * consumers to the internal client).
+ */
+const KNOWN_ORPHANED_SURFACE_CLIENTS: Readonly<Record<string, string>> =
+  Object.freeze({});
+
+/**
+ * Fail fast when a surface lost its spec (it has no endpoints any more) while a
+ * previously generated client package for that surface is still on disk with
+ * generated endpoints in it.
+ *
+ * Skipping such a surface silently — which is what the plain
+ * `if (!existsSync(specPath)) continue` did — leaves a package that still
+ * builds, still publishes and still exports operations the service no longer
+ * classifies into that surface. That is dead code the generator can neither
+ * refresh nor prune, so it must be an error the operator resolves (delete or
+ * deprecate the package), not a warning.
+ *
+ * Guarded by `surfacesWithSpec.length > 0`: when the service has NO spec at all
+ * the caller simply has not run `xema-openapi` yet, which is a different (and
+ * not-an-orphan) situation.
+ *
+ * {@link KNOWN_ORPHANED_SURFACE_CLIENTS} is the escape hatch for an orphan the
+ * generator genuinely cannot resolve. It is EMPTY — the backlog this guard
+ * originally uncovered has been worked off — so today every orphan is a hard
+ * error. See that constant before adding to it.
+ */
+function assertNoOrphanedSurfaceClients(
+  ctx: ResolvedServiceContext,
+  surfacesWithSpec: readonly ApiSurface[],
+): void {
+  if (surfacesWithSpec.length === 0) {
+    return;
+  }
+  const orphans = ALL_SURFACES.filter(
+    (surface) =>
+      !surfacesWithSpec.includes(surface) &&
+      existsSync(join(surfaceClientDir(ctx, surface), 'src', 'endpoints')),
+  );
+  if (orphans.length === 0) {
+    return;
+  }
+
+  const baselined = orphans.filter((surface) =>
+    Object.hasOwn(
+      KNOWN_ORPHANED_SURFACE_CLIENTS,
+      `${ctx.api.serviceId}:${surface}`,
+    ),
+  );
+  const blocking = orphans.filter((surface) => !baselined.includes(surface));
+
+  for (const surface of baselined) {
+    const key = `${ctx.api.serviceId}:${surface}`;
+
+    console.warn(
+      `[xema-client-generate] KNOWN ORPHAN ${key} — ${surfaceClientDir(ctx, surface)} ` +
+        `is stale and will not be regenerated. ${KNOWN_ORPHANED_SURFACE_CLIENTS[key]}`,
+    );
+  }
+
+  if (blocking.length === 0) {
+    return;
+  }
+  throw new Error(
+    `api-client-generator: ${ctx.api.serviceId} emits no spec for surface(s) ` +
+      `${blocking.join(', ')}, but a generated client package still exists at ` +
+      `${blocking.map((s) => surfaceClientDir(ctx, s)).join(', ')}. That client ` +
+      `is orphaned — it would keep exporting operations the surface no longer ` +
+      `has. Delete the package (and its workspace consumers) or restore the ` +
+      `surface classification.`,
+  );
+}
+
+/**
+ * Generate (and compile) one ORVAL client package per surface that has an
+ * emitted spec. Surfaces without a spec are skipped — no empty packages. All
+ * generated clients share the service version (stamped by
+ * {@link ensureClientPackage}).
+ *
+ * @returns the surfaces that were generated.
+ */
+export async function generateClientsForService(
+  serviceDir: string = process.cwd(),
+): Promise<ApiSurface[]> {
+  const ctx: ResolvedServiceContext = resolveServiceContext(serviceDir);
+  const generate = await resolveOrvalGenerate(ctx.serviceDir);
+
+  const surfacesWithSpec = ALL_SURFACES.filter((s) =>
+    existsSync(surfaceSpecPath(ctx, s)),
+  );
+  assertNoOrphanedSurfaceClients(ctx, surfacesWithSpec);
+
+  const generated: ApiSurface[] = [];
+  for (const surface of surfacesWithSpec) {
+    const specPath = surfaceSpecPath(ctx, surface);
+    const { clientDir, clientSrc } = ensureClientPackage(ctx, surface);
+    ensureClientReadme({
+      clientDir,
+      packageName: surfaceClientPackageName(ctx.api.serviceId, surface),
+      serviceTitle: ctx.api.title,
+      surface,
+      repoRoot: ctx.repoRoot,
+    });
+    // Clean prior generated output so endpoints/models removed from this
+    // surface's spec (e.g. routes reclassified to another surface) don't linger
+    // as stale files — orval does not prune removed operations.
+    rmSync(join(clientSrc, 'endpoints'), { recursive: true, force: true });
+    rmSync(join(clientSrc, 'models'), { recursive: true, force: true });
+    await generate(orvalConfigFor(specPath, clientSrc));
+    postProcessClient(ctx.repoRoot, ctx.serviceDir, clientSrc);
+    // `tsc` is additive: it emits for the sources it sees and NEVER deletes an
+    // output whose source disappeared. Without this, every operation ever
+    // generated into this surface survives in `dist/` forever — so a route
+    // reclassified to another surface keeps a stale `.js` + `.d.ts` in the old
+    // client. Consumers then type-check GREEN against a symbol the surface no
+    // longer has, the published tarball (`files: ["dist"]`) ships endpoints the
+    // spec does not contain, and the breakage only appears on a clean
+    // checkout/CI where `dist` starts empty. Pruning `dist` alongside
+    // `src/endpoints` + `src/models` keeps the compiled output a faithful image
+    // of the spec.
+    rmSync(join(clientDir, 'dist'), { recursive: true, force: true });
+    // Compile to dist using the client package's own tsconfig.
+    execFileSync('pnpm', ['exec', 'tsc', '-p', 'tsconfig.json'], {
+      cwd: clientDir,
+      stdio: 'inherit',
+    });
+    generated.push(surface);
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `[xema-client-generate] ${ctx.api.serviceId}: generated ${
+      generated.length
+    } client(s) → ${generated.join(', ') || '(none)'}`,
+  );
+  return generated;
+}
+
+/** CLI entry: generate clients from cwd; exit non-zero on failure. */
+export function runClientGenerateCli(): void {
+  generateClientsForService()
+    .then(() => process.exit(0))
+    .catch((err: unknown) => {
+      console.error('[xema-client-generate] generation failed:', err);
+      process.exit(1);
+    });
+}

package/src/lib/overrides.ts

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { TestingModuleBuilder } from '@nestjs/testing';
+
+/**
+ * Layer 3 of the DI-stub strategy: the optional per-service escape hatch. Most
+ * services need none of this — the universal env seed (Layer 1) + convention
+ * stubs (Layer 2) cover them. A service with a bespoke provider that boots at
+ * import/compile time ships an `openapi.overrides.ts` at its root:
+ *
+ * ```ts
+ * // <service>/openapi.overrides.ts
+ * import type { OpenApiOverrides } from '@xemahq/api-client-generator';
+ * export default {
+ *   env: { SOME_CUSTOM_VAR: 'dummy' },
+ *   applyOverrides: (builder) => builder.overrideProvider(WeirdSvc).useValue({ … }),
+ * } satisfies OpenApiOverrides;
+ * ```
+ */
+export interface OpenApiOverrides {
+  /** Extra dummy env vars seeded before `AppModule` is imported. */
+  readonly env?: Record<string, string>;
+  /**
+   * Hook applied to the `Test.createTestingModule(...)` builder AFTER the
+   * default convention stubs, so a service can override a default or stub an
+   * extra provider. Return the builder (or void — it is mutated in place).
+   */
+  readonly applyOverrides?: (
+    builder: TestingModuleBuilder,
+  ) => TestingModuleBuilder | void;
+}
+
+const OVERRIDES_BASENAME = 'openapi.overrides';
+
+/**
+ * Load `<serviceDir>/openapi.overrides.ts` (or `.js`) if present. Returns
+ * `undefined` when absent — the common case. Throws if the file exists but
+ * exports a malformed shape (fail-fast; no silent ignore).
+ */
+export function loadServiceOverrides(
+  serviceDir: string,
+): OpenApiOverrides | undefined {
+  const candidate = [`${OVERRIDES_BASENAME}.ts`, `${OVERRIDES_BASENAME}.js`]
+    .map((f) => join(serviceDir, f))
+    .find((p) => existsSync(p));
+  if (!candidate) {
+    return undefined;
+  }
+
+  const loaded: unknown = require(candidate);
+  if (loaded === null || typeof loaded !== 'object') {
+    throw new Error(
+      `api-client-generator: ${candidate} must export an overrides object.`,
+    );
+  }
+  const selected =
+    'default' in loaded &&
+    loaded.default !== null &&
+    typeof loaded.default === 'object'
+      ? loaded.default
+      : loaded;
+  const overrides = Object.fromEntries(Object.entries(selected));
+  if (
+    overrides.env !== undefined &&
+    (typeof overrides.env !== 'object' || overrides.env === null)
+  ) {
+    throw new Error(
+      `api-client-generator: ${candidate} \`env\` must be a Record<string,string>.`,
+    );
+  }
+  if (
+    overrides.applyOverrides !== undefined &&
+    typeof overrides.applyOverrides !== 'function'
+  ) {
+    throw new Error(
+      `api-client-generator: ${candidate} \`applyOverrides\` must be a function.`,
+    );
+  }
+  return overrides;
+}

package/src/lib/repo-post-process.ts

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Bridge to the repository's existing `tooling/codegen` ORVAL post-processors.
+ * The generator reuses them (rather than re-implementing) so the generated
+ * client is byte-identical to what `scripts/build-client-index.js` produced
+ * today — same barrel, same fixers, same arguments.
+ */
+
+interface PostProcessors {
+  regenerateModelsBarrel: (clientSrc: string) => number;
+  fixOrvalResponseTypes: (serviceRoot: string) => number;
+  fixOrvalArrayParams: (clientSrc: string) => number;
+}
+
+function requireRepoTool(repoRoot: string, file: string): unknown {
+  const path = join(repoRoot, 'tooling', 'codegen', file);
+  if (!existsSync(path)) {
+    throw new Error(
+      `api-client-generator: required post-processor ${path} not found. The ` +
+        `repo must ship tooling/codegen/${file}.`,
+    );
+  }
+
+  return require(path);
+}
+
+export function loadRepoPostProcessors(repoRoot: string): PostProcessors {
+  const { regenerateModelsBarrel } = requireRepoTool(
+    repoRoot,
+    'regenerate-models-barrel.js',
+  ) as { regenerateModelsBarrel: (c: string) => number };
+  const { fixOrvalResponseTypes } = requireRepoTool(
+    repoRoot,
+    'fix-orval-response-types.js',
+  ) as { fixOrvalResponseTypes: (r: string) => number };
+  const { fixOrvalArrayParams } = requireRepoTool(
+    repoRoot,
+    'fix-orval-array-params.js',
+  ) as { fixOrvalArrayParams: (c: string) => number };
+  return { regenerateModelsBarrel, fixOrvalResponseTypes, fixOrvalArrayParams };
+}
+
+/**
+ * Rebuild `<clientSrc>/index.ts` — the barrel re-exporting custom-fetch +
+ * models + every tags-split endpoint file. Identical to the loop in the legacy
+ * per-service `build-client-index.js`.
+ */
+function rebuildIndexBarrel(clientSrc: string): number {
+  const lines = [
+    '// Auto-generated by @xemahq/api-client-generator — do not edit manually.',
+    "export { configureClient, getClientConfig, ClientError, customFetch, type ClientConfig } from './custom-fetch';",
+  ];
+
+  const modelsIndex = join(clientSrc, 'models', 'index.ts');
+  if (existsSync(modelsIndex)) {
+    const content = readFileSync(modelsIndex, 'utf8');
+    if (/^export /m.test(content)) {
+      lines.push("export * from './models';");
+    }
+  }
+
+  const endpointsDir = join(clientSrc, 'endpoints');
+  if (existsSync(endpointsDir)) {
+    for (const entry of readdirSync(endpointsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const files = readdirSync(join(endpointsDir, entry.name));
+      const tsFile = files.find(
+        (f) => f.endsWith('.ts') && !f.endsWith('.d.ts'),
+      );
+      if (tsFile) {
+        lines.push(
+          `export * from './endpoints/${entry.name}/${tsFile.replace('.ts', '')}';`,
+        );
+      }
+    }
+  }
+
+  lines.push('');
+  writeFileSync(join(clientSrc, 'index.ts'), lines.join('\n'));
+  return lines.length - 2;
+}
+
+/**
+ * Run the full post-ORVAL pipeline for one generated client, mirroring the
+ * legacy `build-client-index.js` ordering exactly: models barrel → index
+ * barrel → response-type fix → array-param fix.
+ *
+ * `serviceRoot` is passed to `fixOrvalResponseTypes` unchanged from the legacy
+ * call site (it resolves its own models path internally), so the output is
+ * identical to today's pipeline.
+ */
+export function postProcessClient(
+  repoRoot: string,
+  serviceRoot: string,
+  clientSrc: string,
+): void {
+  const tools = loadRepoPostProcessors(repoRoot);
+  tools.regenerateModelsBarrel(clientSrc);
+  rebuildIndexBarrel(clientSrc);
+  tools.fixOrvalResponseTypes(serviceRoot);
+  tools.fixOrvalArrayParams(clientSrc);
+}