@xemahq/api-client-generator 0.4.2 → 0.4.4

package/src/lib/seed-openapi-env.ts

@@ -1,136 +0,0 @@
-/**
- * Layer 1 of the DI-stub strategy: seed deterministic dummy env vars BEFORE
- * the service's `AppModule` is imported. NestJS modules read `process.env` at
- * import time, so this MUST run first.
- *
- * Every value is a throwaway placeholder. `app.init()` is deliberately skipped
- * during extraction, so nothing here is ever dialed — the values only need to
- * exist so import-time `getOrThrow`/`new URL(...)` calls don't crash.
- *
- * This is the union of the seeds the 41 hand-written `extract-openapi.ts`
- * scripts set. A service that reads an env var not covered here adds it via the
- * optional per-service `openapi.overrides.ts` `env` field (Layer 3) — the
- * generator never silently invents a value it wasn't told about beyond this
- * shared baseline.
- */
-
-const DUMMY_ENCRYPTION_KEY_HEX =
-  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
-const DUMMY_BASE64_KEY = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
-
-/** Set a default only if the var is unset (`??=` semantics). */
-function seed(vars: Record<string, string>): void {
-  for (const [key, value] of Object.entries(vars)) {
-    if (process.env[key] === undefined) {
-      process.env[key] = value;
-    }
-  }
-}
-
-/** The throwaway database every extraction points at. Never dialed. */
-const SCRATCH_DB_NAME = 'dummy_openapi';
-
-/**
- * Per-service scratch Postgres schema.
- *
- * Extraction is run in PARALLEL by turbo across ~40 services. If they all point
- * at one database AND one `public` schema they share a single
- * `_prisma_migrations` table, so any code path that migrates at DI-construction
- * time interleaves foreign migration histories and wedges its neighbours. Giving
- * each service its own schema makes the scratch surfaces disjoint by
- * construction. Postgres identifiers are lower-cased and capped at 63 bytes.
- */
-export function openApiScratchSchema(serviceId: string): string {
-  return `extract_${serviceId.replace(/[^a-zA-Z0-9]+/g, '_')}`
-    .toLowerCase()
-    .slice(0, 63);
-}
-
-/**
- * @param serviceId the `xema.api.serviceId` of the service being extracted —
- *   used to derive a scratch schema unique to this extraction process.
- */
-export function seedOpenApiEnv(serviceId: string): void {
-  const schema = openApiScratchSchema(serviceId);
-  seed({
-    NODE_ENV: 'development',
-
-    // Extraction-mode flag. `XemaServiceModule` eagerly resolves peer URLs from
-    // the KernelState/etcd registry at DI-construction time; with no live cluster
-    // that throws and the module can't even be constructed for scanning. Setting
-    // this makes the SDK's construction-time resolvers (`resolveHttpUrlEagerly`)
-    // short-circuit to a non-routable `.invalid` stub. The var NAME is the
-    // service-registry-nest `OPENAPI_EXTRACTION_ENV_VAR` contract; the SDK is a
-    // higher layer, so we set the env by name rather than import it here.
-    XEMA_OPENAPI_EXTRACTION: '1',
-
-    // Database (Prisma + raw pools). The scratch schema is per-service — see
-    // `openApiScratchSchema`. `DB_SCHEMA` is NOT redundant with the URL's
-    // `?schema=`: `createBiomePrismaAdapterFromEnv` passes it as the adapter's
-    // second-arg `{ schema }`, while `?schema=` is what a Prisma CLI/migrate
-    // invocation reads.
-    DATABASE_URL: `postgresql://dummy:dummy@localhost:5432/${SCRATCH_DB_NAME}?schema=${schema}`,
-    DB_HOST: 'localhost',
-    DB_PORT: '5432',
-    DB_NAME: SCRATCH_DB_NAME,
-    DB_SCHEMA: schema,
-    DB_USER: 'dummy',
-    DB_PASSWORD: 'dummy',
-    REDIS_URL: 'redis://localhost:6379',
-    OPENSEARCH_URL: 'http://localhost:9200',
-
-    // Identity / auth.
-    IDENTITY_API_URL: 'http://localhost:3053',
-    IDENTITY_API_INTERNAL_TOKEN: 'dummy-token',
-    JWT_PUBLIC_KEY_URL:
-      'http://localhost:8180/realms/dummy/protocol/openid-connect/certs',
-    JWT_ISSUER: 'http://localhost:8180/realms/dummy',
-    GATEWAY_JWT_SECRET: 'dummy-gateway-jwt-secret-for-openapi-extraction',
-    OPENCODE_WORKER_PASSWORD: 'dummy-worker-password',
-
-    // Service registry (etcd-only autodiscovery). `createKernelState` fail-fasts
-    // without this; the etcd3 client is lazy (no dial until first call) and
-    // extraction skips `app.init()`, so the dummy endpoint is never contacted.
-    XEMA_ETCD_ENDPOINTS: 'localhost:2379',
-
-    // Event hub. `WEBHOOK_URL` is the delivery callback every service that
-    // SUBSCRIBES declares to `EventHubModule.forRootAsync` — it is boot-REQUIRED
-    // (`getOrThrow`) in ~20 services, so it belongs in the shared baseline
-    // rather than being re-declared in ~20 `openapi.overrides.ts` files.
-    EVENT_HUB_URL: 'http://localhost:3128',
-    WEBHOOK_URL: 'http://localhost:3000/webhooks/events',
-
-    // Cross-service HTTP URLs (resolved via the registry in prod; dummy here).
-    BACKLOG_API_URL: 'http://localhost:3100',
-    MEMORY_API_URL: 'http://localhost:3060',
-    LLM_REGISTRY_API_URL: 'http://localhost:3112',
-    LLM_GATEWAY_API_URL: 'http://localhost:3110',
-    ARTIFACT_STORE_API_URL: 'http://localhost:3130',
-    KNOWLEDGE_BASE_API_URL: 'http://localhost:3200',
-    PROJECT_REGISTRY_API_URL: 'http://localhost:3300',
-    CONNECTOR_GATEWAY_API_URL: 'http://localhost:3900',
-    DESIGN_SYSTEM_BUILDER_API_URL: 'http://localhost:3210',
-    SEARCH_API_URL: 'http://localhost:3220',
-    BILLING_API_URL: 'http://localhost:3140',
-    CAPABILITY_REGISTRY_API_URL: 'http://localhost:3700',
-
-    // SCM / git.
-    SCM_WEBHOOK_SECRET: 'dummy-webhook-secret',
-    SCM_WEBHOOK_BASE_URL: 'http://localhost:3500/webhooks',
-    GITEA_URL: 'http://localhost:3000',
-    GITEA_ADMIN_USER: 'gitea_admin',
-    GITEA_ADMIN_PASS: 'gitea_admin_pass',
-
-    // Encryption keys (hex 32-byte + base64 variants used across services).
-    MASTER_ENCRYPTION_KEY: DUMMY_ENCRYPTION_KEY_HEX,
-    ENCRYPTION_MASTER_KEY: DUMMY_BASE64_KEY,
-    LLM_REGISTRY_ENCRYPTION_KEY:
-      'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789',
-    VARIABLE_ENCRYPTION_KEY:
-      'fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210',
-
-    // Platform observability endpoints.
-    PLATFORM_METRICS_ENDPOINT: 'http://localhost:9090/metrics',
-    PLATFORM_AUDIT_ENDPOINT: 'http://localhost:3601/audit',
-  });
-}

package/src/lib/service-config.ts

@@ -1,170 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-
-import { ApiSurface } from '@xemahq/xema-decorators';
-
-/**
- * The per-service residue of the central generator: a `xema.api` block in the
- * service's own `package.json`. Everything else (spec paths, client dirs,
- * client package names, mutator path, orval mode) is derived from this plus
- * the repo layout — there is no `orval.config.ts`, no extract script.
- *
- * ```jsonc
- * // <service>/package.json
- * { "name": "backlog-api", "version": "0.1.0",
- *   "xema": { "api": { "serviceId": "backlog-api", "biomeId": "backlog",
- *                      "title": "Backlog API", "description": "…" } } }
- * ```
- */
-export interface XemaApiConfig {
-  readonly serviceId: string;
-  readonly biomeId: string;
-  readonly title: string;
-  readonly description?: string;
-}
-
-export interface ResolvedServiceContext {
-  /** Absolute path to the service directory (process cwd). */
-  readonly serviceDir: string;
-  /** Absolute path to the repository root (holds pnpm-workspace.yaml). */
-  readonly repoRoot: string;
-  /** The declared `xema.api` block. */
-  readonly api: XemaApiConfig;
-  /** The service `package.json` version — stamped into every surface client. */
-  readonly version: string;
-}
-
-/** Walk up from `start` to the directory holding `pnpm-workspace.yaml`. */
-export function findRepoRoot(start: string): string {
-  let dir = resolve(start);
-  while (dir !== dirname(dir)) {
-    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
-      return dir;
-    }
-    dir = dirname(dir);
-  }
-  throw new Error(
-    `api-client-generator: could not locate a repo root (pnpm-workspace.yaml) ` +
-      `walking up from ${start}.`,
-  );
-}
-
-/**
- * Read and validate the service's `package.json#xema.api` block + version.
- * Fail-fast on a missing/malformed block — the generator never guesses a
- * serviceId or biomeId.
- */
-export function resolveServiceContext(serviceDir: string): ResolvedServiceContext {
-  const pkgPath = join(serviceDir, 'package.json');
-  if (!existsSync(pkgPath)) {
-    throw new Error(
-      `api-client-generator: no package.json found at ${pkgPath}. Run the ` +
-        `generator from a service directory.`,
-    );
-  }
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
-    version?: unknown;
-    xema?: { api?: Partial<XemaApiConfig> } | null;
-  };
-  const api = pkg.xema?.api;
-  if (!api || typeof api !== 'object') {
-    throw new Error(
-      `api-client-generator: ${pkgPath} is missing the required \`xema.api\` ` +
-        `block. Add: { "xema": { "api": { "serviceId": "<id>", "biomeId": ` +
-        `"<biome>", "title": "<title>" } } }.`,
-    );
-  }
-  const { serviceId, biomeId, title, description } = api;
-  for (const [field, value] of Object.entries({ serviceId, biomeId, title })) {
-    if (typeof value !== 'string' || value.trim() === '') {
-      throw new Error(
-        `api-client-generator: \`xema.api.${field}\` is required and must be a ` +
-          `non-empty string in ${pkgPath}.`,
-      );
-    }
-  }
-  if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
-    throw new Error(
-      `api-client-generator: ${pkgPath} is missing a \`version\` — every ` +
-        `generated surface client shares the service version.`,
-    );
-  }
-  return {
-    serviceDir: resolve(serviceDir),
-    repoRoot: findRepoRoot(serviceDir),
-    api: {
-      serviceId: serviceId as string,
-      biomeId: biomeId as string,
-      title: title as string,
-      ...(typeof description === 'string' ? { description } : {}),
-    },
-    version: pkg.version,
-  };
-}
-
-/**
- * Short package name (without the `@xemahq/` scope) for a surface client.
- *
- * - public:   `<serviceId>-client`                  (unchanged from today, e.g.
- *             `backlog-api` → `backlog-api-client`)
- * - internal: surface segment inserted before a trailing `-api`, matching the
- *             agreed shape `llm-registry-api` → `llm-registry-internal-api-client`;
- *             services without a `-api` suffix fall back to
- *             `<serviceId>-internal-client`.
- * - operator: same rule with `operator`.
- *
- * Deterministic for every serviceId — no name guessing, pure string rule.
- */
-export function surfaceClientShortName(
-  serviceId: string,
-  surface: ApiSurface,
-): string {
-  if (surface === ApiSurface.Public) {
-    return `${serviceId}-client`;
-  }
-  const segment = surface; // 'internal' | 'operator'
-  if (serviceId.endsWith('-api')) {
-    const base = serviceId.slice(0, -'-api'.length);
-    return `${base}-${segment}-api-client`;
-  }
-  return `${serviceId}-${segment}-client`;
-}
-
-/** Scoped npm package name for a surface client. */
-export function surfaceClientPackageName(
-  serviceId: string,
-  surface: ApiSurface,
-): string {
-  return `@xemahq/${surfaceClientShortName(serviceId, surface)}`;
-}
-
-/** Absolute client package directory under `<repoRoot>/packages/clients/`. */
-export function surfaceClientDir(
-  ctx: ResolvedServiceContext,
-  surface: ApiSurface,
-): string {
-  const dirName = surfaceClientShortName(ctx.api.serviceId, surface).replace(
-    /-client$/,
-    '',
-  );
-  return join(ctx.repoRoot, 'packages', 'clients', dirName);
-}
-
-/** Absolute path of a surface's OpenAPI document at the service root. */
-export function surfaceSpecPath(
-  ctx: ResolvedServiceContext,
-  surface: ApiSurface,
-  /**
-   * Where to write instead of the service directory.
-   *
-   * Exists so a drift GATE can extract without touching the working tree. Its
-   * sibling `check-client-spec-drift.mjs` states the requirement plainly: a
-   * check that regenerates in place and reads `git status` cannot be run by an
-   * author mid-change without destroying their work, so nobody runs it. The
-   * same has to be true of code→spec drift, and that is only possible if the
-   * extractor can be pointed elsewhere.
-   */
-  outDir?: string,
-): string {
-  return join(outDir ?? ctx.serviceDir, `openapi.${surface}.json`);
-}

package/src/lib/service-nest.ts

@@ -1,58 +0,0 @@
-/**
- * Resolve the NestJS runtime classes from the SERVICE's own `node_modules`,
- * not the generator's.
- *
- * The generator is symlinked into each service as a workspace package; a static
- * `import … from '@nestjs/core'` would resolve to the generator's own copy of
- * Nest, producing a dual-package hazard — the `DiscoveryService` token built
- * into the app (service's Nest) would differ from the token we pass to
- * `app.get(...)` (generator's Nest), and DI resolution fails. Resolving these
- * from `serviceDir` guarantees one Nest instance end-to-end.
- *
- * (The decorator-metadata scan in `@xemahq/xema-decorators` is NOT subject to
- * this: it reads via the global `Reflect` polyfill and compares string keys,
- * so the generator's copy reads metadata stamped by the service's copy fine.)
- */
-
-import type { INestApplication, Type } from '@nestjs/common';
-import type {
-  DiscoveryService,
-  MetadataScanner,
-  ModulesContainer,
-} from '@nestjs/core';
-import type { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
-import type { Test } from '@nestjs/testing';
-
-export interface ServiceNest {
-  readonly Test: typeof Test;
-  readonly DocumentBuilder: typeof DocumentBuilder;
-  readonly SwaggerModule: typeof SwaggerModule;
-  readonly DiscoveryService: Type<DiscoveryService>;
-  readonly MetadataScanner: Type<MetadataScanner>;
-  readonly ModulesContainer: Type<ModulesContainer>;
-}
-
-function requireFrom(
-  serviceDir: string,
-  request: string,
-): Record<string, unknown> {
-  const resolved = require.resolve(request, { paths: [serviceDir] });
-
-  return require(resolved) as Record<string, unknown>;
-}
-
-export function loadServiceNest(serviceDir: string): ServiceNest {
-  const core = requireFrom(serviceDir, '@nestjs/core');
-  const testing = requireFrom(serviceDir, '@nestjs/testing');
-  const swagger = requireFrom(serviceDir, '@nestjs/swagger');
-  return {
-    Test: testing.Test as typeof Test,
-    DocumentBuilder: swagger.DocumentBuilder as typeof DocumentBuilder,
-    SwaggerModule: swagger.SwaggerModule as typeof SwaggerModule,
-    DiscoveryService: core.DiscoveryService as Type<DiscoveryService>,
-    MetadataScanner: core.MetadataScanner as Type<MetadataScanner>,
-    ModulesContainer: core.ModulesContainer as Type<ModulesContainer>,
-  };
-}
-
-export type { INestApplication };