@xemahq/api-client-generator 0.2.0 → 0.3.0

package/src/lib/service-config.ts

@@ -0,0 +1,170 @@
+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

@@ -0,0 +1,58 @@
+/**
+ * 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 };