@xemahq/repo-build-tooling 0.9.2 → 0.10.0

package/src/service-bootstrap.mjs

@@ -0,0 +1,491 @@
+#!/usr/bin/env node
+/**
+ * Generate the per-service `BiomeServiceDescriptor` bootstrap constant that
+ * `XemaServiceModule.forBiome(...)` consumes — from the AUTHORITATIVE source,
+ * each biome's `xema-biome.json`.
+ *
+ * Why: today a service's identity (name / version / dependencies) is declared
+ * in `xema-biome.json` AND re-typed as string literals inside `app.module.ts`
+ * (`ServiceRegistryModule` descriptor + `IdentityBootstrapModule`). That
+ * duplication drifts. This codegen makes the manifest the single source of
+ * truth: it emits `src/generated/<service>.bootstrap.generated.ts` next to each
+ * shipped API, and `app.module.ts` imports the constant instead of repeating
+ * the strings. A developer changes name/version/deps in ONE place — the manifest.
+ *
+ * Manifest fields read — the v5 COMPONENT contract (`xema.components[]`). The
+ * v4 `xema.ships.apis[]` spelling this used to read is RETIRED and matches
+ * nothing in the fleet.
+ *
+ *   - top-level `version`                      → descriptor.semver / biomeVersion (required)
+ *   - `components[].kind === 'service'`        → the components this emits for
+ *   - `components[].protocol.serviceName`      → descriptor.name (falls back to `key`)
+ *   - `components[].artifact.path`             → where the file is written (required)
+ *   - `components[].protocol.displayName`      → descriptor.displayName
+ *                                       (optional; falls back to `<xema.displayName> API`)
+ *   - `components[].protocol.description`      → descriptor.description (optional)
+ *                                       — the ONE authored copy `main.ts` reads for
+ *                                       the OpenAPI `info.description`
+ *   - `components[].protocol.requiresServices` → descriptor.requiresServices
+ *                                       (optional; default ['identity-api'])
+ *   - `components[].protocol.capabilities`     → descriptor.protocols (optional)
+ *   - `components[].protocol.exposesCapabilities` → descriptor.exposesCapabilities
+ *                                       (optional; falls back to `xema.exposesCapabilities`)
+ *   - `components[].requirements.scaling.concurrency.maximumPerInstance`
+ *                                       → descriptor.maximumConcurrentRequests (required positive
+ *                                       integer; a service without one is refused)
+ *   - `components[].kind === 'worker'`          → a `XemaWorkerDescriptor` constant in
+ *                                       `<package>/src/generated/<key>.worker-descriptor.generated.ts`
+ *                                       (name = key, requiresServices = protocol.requiresServices,
+ *                                       maximumConcurrentActivities = maximumPerInstance, and for a
+ *                                       Nexus provider maximumConcurrentNexusOperations =
+ *                                       maximumNexusOperationsPerInstance, required, no default). The package is
+ *                                       the worker's `artifact.path`, or — for a `shared-oci-image`
+ *                                       worker — the path of the component whose image it shares.
+ *                                       Like services, only emitted into a package that depends on
+ *                                       `@xemahq/xema-service-nest`.
+ *   - `xema.id`                                → descriptor.biomeId       (required)
+ *   - `xema.capabilityDomain`                  → descriptor.capabilityDomain (optional)
+ *
+ * v4 also carried a per-API `serviceKind`; v5 carries none and needs none —
+ * every generated descriptor in the fleet is `ServiceKind.BiomeApi`, the
+ * default. `displayName` is the opposite case and is why this port needed a
+ * kernel change first: it is REGISTERED WITH identity-api, and 20 of the 50
+ * services declare one that differs from `<biome displayName> API`. Deriving it
+ * would have renamed them in the identity plane.
+ *
+ * `biomeId` + `biomeVersion` are NOT decoration: `isHttpCapabilityProjectionEnabled`
+ * in `@xemahq/xema-service-nest` gates HTTP capability projection on BOTH being
+ * present (a projected capability is stamped with `biome.id`/`biome.version`, and
+ * provenance cannot be guessed). A descriptor emitted without them silently
+ * projects nothing — so they are emitted unconditionally, and a manifest with no
+ * `xema.id` is a hard error rather than a descriptor that boots into a no-op.
+ * `capabilityDomain` is the `<domain>` segment of every projected ref; it is
+ * emitted only when the manifest declares it (the runtime defaults it to the
+ * biome id, so emitting the default would be redundant duplication).
+ *
+ * It runs in ONE repository: it walks every `xema-biome.json` under the
+ * repository root (the working directory, or `--root <dir>`) and writes next to
+ * the packages those manifests name. Every repository runs the same published
+ * copy, so no repository hand-writes a generated value.
+ *
+ *   xema-service-bootstrap                         # write
+ *   xema-service-bootstrap --check                 # CI: fail on drift
+ *   xema-service-bootstrap --filter mailops-api    # one component
+ *   xema-service-bootstrap --root <repo-dir>       # a repository other than cwd
+ */
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+} from 'node:fs';
+import { join, relative, dirname, resolve } from 'node:path';
+import { renderServiceProtocols } from './service-bootstrap-protocols.mjs';
+import { readMaximumPerInstance } from './service-bootstrap-concurrency.mjs';
+import {
+  WORKER_DESCRIPTOR_FILE_SUFFIX,
+  renderWorkerDescriptorFile,
+  workerPackagePath,
+  workerRecord,
+} from './worker-descriptor-generation.mjs';
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.turbo', 'coverage']);
+
+const argv = process.argv.slice(2);
+const CHECK = argv.includes('--check');
+const optionValue = (flag) => {
+  const index = argv.indexOf(flag);
+  if (index < 0) return null;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    console.error(`[xema-service-bootstrap] ${flag} needs a value.`);
+    process.exit(2);
+  }
+  return value;
+};
+const FILTER = optionValue('--filter');
+const ROOT = resolve(optionValue('--root') ?? process.cwd());
+
+/** Recursively collect files named `target` under `dir`. */
+function walk(dir, target, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      walk(join(dir, e.name), target, out);
+    } else if (e.name === target) {
+      out.push(join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+const CONST_KEY = (name) => name.toUpperCase().replace(/-/g, '_') + '_BOOTSTRAP';
+
+const titleCase = (slug) =>
+  slug
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+/** Map a manifest into 0..n descriptor records (one per shipped API). */
+function descriptorsFromManifest(manifestPath) {
+  const manifestDir = dirname(manifestPath);
+  let m;
+  try {
+    m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `[xema-service-bootstrap] cannot parse ${relative(ROOT, manifestPath)}: ${error.message}`,
+      { cause: error },
+    );
+  }
+  const xema = m?.xema ?? m;
+  const version = m?.version ?? xema?.version;
+  // v5: a service is a COMPONENT whose kind says so. `protocol.serviceName` is
+  // the wire name; `key` is its fallback, and the two agree fleet-wide today.
+  const apis = (xema?.components ?? [])
+    .filter((component) => component?.kind === 'service')
+    .map((component) => ({
+      name: component?.protocol?.serviceName ?? component?.key,
+      path: component?.artifact?.path,
+      displayName: component?.protocol?.displayName,
+      description: component?.protocol?.description,
+      requiresServices: component?.protocol?.requiresServices,
+      exposesCapabilities: component?.protocol?.exposesCapabilities,
+      protocols: component?.protocol?.capabilities,
+      component,
+    }));
+  const out = [];
+  for (const api of apis) {
+    if (!api?.name || !api?.path) continue;
+    if (FILTER && api.name !== FILTER) continue;
+    // Only emit for services that OPT IN by declaring the dependency. A biome
+    // may ship a worker / non-migrated API in the same manifest; generating a
+    // descriptor that imports `@xemahq/xema-service-nest` into a service that
+    // doesn't depend on it would break that service's build. The dep is the
+    // single signal that a service consumes `XemaServiceModule.forBiome`.
+    if (!packageOptsIn(join(manifestDir, api.path, 'package.json'))) continue;
+    if (!version) {
+      throw new Error(
+        `[xema-service-bootstrap] ${relative(ROOT, manifestPath)} ships api "${api.name}" but has no top-level "version".`,
+      );
+    }
+    const displayName =
+      api.displayName ??
+      (xema?.displayName ? `${xema.displayName} API` : `${titleCase(api.name)}`);
+    // v5 carries no per-component serviceKind, and needs none: every generated
+    // descriptor in the fleet is a biome API.
+    const serviceKind = 'biome-api';
+    const requiresServices =
+      Array.isArray(api.requiresServices) && api.requiresServices.length > 0
+        ? api.requiresServices
+        : ['identity-api'];
+    // SORTED, so the generated file is a function of the declaration SET rather
+    // than of the order someone happened to type it in. Without this, moving a
+    // ref inside the manifest churns a generated file for no semantic reason —
+    // and `--check` would fail on a diff that means nothing.
+    const exposesCapabilities = [
+      ...(Array.isArray(api.exposesCapabilities)
+        ? api.exposesCapabilities
+        : Array.isArray(xema?.exposesCapabilities)
+          ? xema.exposesCapabilities
+          : []),
+    ].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    const protocols = api.protocols;
+    const biomeId = xema?.id;
+    if (typeof biomeId !== 'string' || biomeId.trim() === '') {
+      throw new Error(
+        `[xema-service-bootstrap] ${relative(ROOT, manifestPath)} ships api "${api.name}" but has no "xema.id". ` +
+          'The biome id is the provenance stamped on every projected capability — ' +
+          'without it `XemaServiceModule.forBiome` disables HTTP capability projection entirely.',
+      );
+    }
+    const capabilityDomain =
+      typeof xema?.capabilityDomain === 'string' &&
+      xema.capabilityDomain.trim() !== ''
+        ? xema.capabilityDomain
+        : null;
+    const maximumConcurrentRequests = readMaximumPerInstance(
+      api.component,
+      relative(ROOT, manifestPath),
+    );
+    const apiSrcDir = join(manifestDir, api.path, 'src');
+    out.push({
+      name: api.name,
+      maximumConcurrentRequests,
+      semver: String(version),
+      serviceKind,
+      displayName,
+      description: api.description,
+      requiresServices,
+      exposesCapabilities,
+      protocols,
+      biomeId,
+      biomeVersion: String(version),
+      capabilityDomain,
+      outFile: join(
+        apiSrcDir,
+        'generated',
+        `${api.name}.bootstrap.generated.ts`,
+      ),
+      manifestRel: relative(ROOT, manifestPath),
+      apiSrcExists: existsSync(apiSrcDir),
+      packageJsonPath: join(manifestDir, api.path, 'package.json'),
+    });
+  }
+  return out;
+}
+
+/** The package.json dependency that opts a package in to generation. */
+function packageOptsIn(packageJsonPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return Boolean((pkg.dependencies ?? {})[SERVICE_NEST_PACKAGE]);
+  } catch {
+    return false;
+  }
+}
+
+/** Map a manifest into 0..n worker descriptor records (one per worker component). */
+function workerDescriptorsFromManifest(manifestPath) {
+  const manifestDir = dirname(manifestPath);
+  let m;
+  try {
+    m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `[xema-service-bootstrap] cannot parse ${relative(ROOT, manifestPath)}: ${error.message}`,
+      { cause: error },
+    );
+  }
+  const components = (m?.xema ?? m)?.components ?? [];
+  const manifestRel = relative(ROOT, manifestPath);
+  const out = [];
+  for (const component of components) {
+    if (component?.kind !== 'worker' || !component?.key) continue;
+    if (FILTER && component.key !== FILTER) continue;
+    const packageDir = join(manifestDir, workerPackagePath(component, components, manifestRel));
+    // Same opt-in as services: no dependency on the SDK, no generated import. Checked
+    // BEFORE the record, so a worker that is not opted in never has to declare a limit.
+    if (!packageOptsIn(join(packageDir, 'package.json'))) continue;
+    const record = workerRecord(component, components, manifestRel);
+    const srcDir = join(packageDir, 'src');
+    out.push({
+      ...record,
+      manifestRel,
+      srcExists: existsSync(srcDir),
+      outFile: join(srcDir, 'generated', `${record.name}.${WORKER_DESCRIPTOR_FILE_SUFFIX}`),
+      render: () =>
+        renderWorkerDescriptorFile(record, {
+          manifestRel,
+          serviceNestPackage: SERVICE_NEST_PACKAGE,
+        }),
+    });
+  }
+  return out;
+}
+
+// THE TWO PACKAGES THIS GENERATOR EMITS AN IMPORT FOR, named once.
+//
+// The protocol import was hardcoded as `@xemahq/kernel-contracts/service-registry`
+// and went stale when the kernel package was renamed to `@xemahq/contracts`.
+// It stayed invisible because that import is emitted ONLY for a service that
+// declares protocols, and for a long time none did.
+//
+// What it did when it finally fired is worse than emitting a dead import: the
+// generator OVERWROTE resource-governance-api's committed, CORRECT file with
+// the retired name, and `--check` therefore reported that correct file as
+// "out of date" and told the reader to regenerate it. The gate was demanding a
+// regression, and obeying it broke xema-base's build.
+const SERVICE_NEST_PACKAGE = '@xemahq/xema-service-nest';
+const KERNEL_CONTRACTS_PACKAGE = '@xemahq/contracts';
+const SERVICE_REGISTRY_SUBPATH = `${KERNEL_CONTRACTS_PACKAGE}/service-registry`;
+
+const SERVICE_KIND_ENUM = {
+  'platform-service': 'ServiceKind.PlatformService',
+  'biome-api': 'ServiceKind.BiomeApi',
+  cli: 'ServiceKind.Cli',
+};
+
+// A generator that emits an import nobody declares produces a file that does not
+// compile, in a repository the generator does not build. This makes that a
+// GENERATION-time failure instead, naming the service and the package.
+//
+// It grades ONLY the kernel-contracts import, and deliberately not the
+// `@xemahq/xema-service-nest` one: a service reaches this function only by
+// DECLARING that exact package — that is the opt-in signal above — so asserting
+// it here could never fail, and a check that cannot fail is worse than no check
+// because it reads as protection in review.
+//
+// It grades DECLARATIONS, not resolution: the constitution already requires that
+// every package list every `@xemahq/*` it imports, so a declared dependency is
+// the right thing to check and it needs no install to check it. Measured when
+// this landed: all 53 generated services declare `@xemahq/xema-service-nest`,
+// and the one service with a protocol import declares the kernel package — so
+// this reddens nothing that was already correct.
+function assertKernelContractsDeclared(d) {
+  if (!existsSync(d.packageJsonPath)) {
+    throw new Error(
+      `[xema-service-bootstrap] ${d.name}: no package.json at ${relative(ROOT, d.packageJsonPath)}, so the protocol import this generator emits cannot be checked against what the service declares.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(d.packageJsonPath, 'utf8'));
+  const declared = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+  ]);
+  if (!declared.has(KERNEL_CONTRACTS_PACKAGE)) {
+    throw new Error(
+      `[xema-service-bootstrap] ${d.name} (${relative(ROOT, d.packageJsonPath)}) declares service protocols, so this generator emits an import from ` +
+        `'${SERVICE_REGISTRY_SUBPATH}' — but the service does not declare ${KERNEL_CONTRACTS_PACKAGE}. ` +
+        'Either the kernel package was renamed and the constants at the top of this file are stale, or the service is missing a dependency. ' +
+        'Both produce the same symptom — a generated file that will not compile — and both are fixed here, never in the generated file.',
+    );
+  }
+}
+
+function renderFile(d) {
+  const kindExpr = SERVICE_KIND_ENUM[d.serviceKind];
+  if (!kindExpr) {
+    throw new Error(
+      `[xema-service-bootstrap] ${d.manifestRel} api "${d.name}" has unknown serviceKind "${d.serviceKind}" (expected platform-service | biome-api | cli).`,
+    );
+  }
+  const arr = (xs) =>
+    xs.length === 0 ? '[]' : `[${xs.map((x) => `'${x}'`).join(', ')}]`;
+  const renderedProtocols = renderServiceProtocols(d.protocols);
+  if (renderedProtocols.imports.length > 0) {
+    assertKernelContractsDeclared(d);
+  }
+  const protocolImports =
+    renderedProtocols.imports.length === 0
+      ? ''
+      : `import {\n${renderedProtocols.imports.map((name) => `  ${name},`).join('\n')}\n} from '${SERVICE_REGISTRY_SUBPATH}';\n`;
+  return `// AUTO-GENERATED by xema-service-bootstrap (@xemahq/repo-build-tooling) — DO NOT EDIT.
+// Source of truth: ${d.manifestRel} (xema.components[] + top-level version).
+// Regenerate: \`pnpm exec xema-service-bootstrap\`.
+${protocolImports}import {
+  ServiceKind,
+  type BiomeServiceDescriptor,
+} from '${SERVICE_NEST_PACKAGE}';
+
+/**
+ * Bootstrap identity for ${d.name}, consumed by
+ * \`XemaServiceModule.forBiome(${CONST_KEY(d.name)})\`. Edit the biome manifest,
+ * not this file.
+ */
+export const ${CONST_KEY(d.name)}: BiomeServiceDescriptor = {
+  name: '${d.name}',
+  semver: '${d.semver}',
+  serviceKind: ${kindExpr},
+  displayName: '${d.displayName.replace(/'/g, "\\'")}',
+${d.description ? `  // JSON.stringify, not a quoted literal: a lifted description carries real\n  // newlines, and single quotes produced an unterminated string.\n  description: ${JSON.stringify(d.description)},\n` : ''}\
+  maximumConcurrentRequests: ${d.maximumConcurrentRequests},
+  requiresServices: ${arr(d.requiresServices)},
+  exposesCapabilities: ${arr(d.exposesCapabilities)},${renderedProtocols.field}
+  biomeId: '${d.biomeId}',
+  biomeVersion: '${d.biomeVersion}',${
+    d.capabilityDomain === null
+      ? ''
+      : `\n  capabilityDomain: '${d.capabilityDomain}',`
+  }
+};
+`;
+}
+
+const manifests = walk(ROOT, 'xema-biome.json', []);
+const records = manifests.flatMap(descriptorsFromManifest);
+const workerRecords = manifests.flatMap(workerDescriptorsFromManifest);
+
+// A SCAN THAT FINDS NOTHING IS A FAILURE, NEVER AN "OK".
+//
+// This generator once read a retired manifest spelling, matched nothing in a
+// fleet it walked, and reported "OK — 0 file(s) up to date": `--check` was a
+// gate that could not fail. So an empty result exits non-zero: no manifest
+// under the root means it ran in the wrong directory, and manifests with no
+// opted-in service or worker mean the reader and the manifests disagree (or the
+// repository has nothing to generate and must not run this).
+if (manifests.length === 0) {
+  console.error(
+    `[xema-service-bootstrap] found no xema-biome.json under ${ROOT}. ` +
+      'Run it from the repository root, or pass --root <repo-dir>.',
+  );
+  process.exit(1);
+}
+if (records.length === 0 && workerRecords.length === 0 && FILTER === null) {
+  console.error(
+    `[xema-service-bootstrap] walked ${manifests.length} xema-biome.json manifest(s) under ${ROOT} ` +
+      'and produced ZERO service or worker descriptors. A descriptor is emitted for each ' +
+      '`xema.components[]` entry of kind `service` or `worker` whose package declares ' +
+      `${SERVICE_NEST_PACKAGE}; none here does, so this run would verify nothing.`,
+  );
+  process.exit(1);
+}
+if (FILTER !== null && records.length === 0 && workerRecords.length === 0) {
+  console.error(`[xema-service-bootstrap] --filter ${FILTER} matched no opted-in service or worker component.`);
+  process.exit(1);
+}
+
+let drift = 0;
+let written = 0;
+let skipped = 0;
+let compared = 0;
+const outputs = [
+  ...records.map((d) => ({
+    outFile: d.outFile,
+    srcExists: d.apiSrcExists,
+    render: () => renderFile(d),
+  })),
+  ...workerRecords,
+];
+for (const d of outputs) {
+  if (!d.srcExists) {
+    // The manifest declares an api whose source isn't present in this
+    // checkout (carved-repo skew). Skip rather than emit into a phantom dir.
+    skipped++;
+    continue;
+  }
+  compared++;
+  const next = d.render();
+  const prev = existsSync(d.outFile) ? readFileSync(d.outFile, 'utf8') : null;
+  if (prev === next) continue;
+  if (CHECK) {
+    console.error(
+      `DRIFT: ${relative(ROOT, d.outFile)} is out of date (regenerate with \`pnpm exec xema-service-bootstrap\`).`,
+    );
+    drift++;
+    continue;
+  }
+  mkdirSync(dirname(d.outFile), { recursive: true });
+  writeFileSync(d.outFile, next, 'utf8');
+  console.log(`wrote ${relative(ROOT, d.outFile)}`);
+  written++;
+}
+
+// A RUN THAT COMPARES OR WRITES NOTHING IS A FAILURE: every record skipped because
+// its source is missing would otherwise report OK (check) or "Done" (generate).
+if (compared === 0) {
+  console.error(
+    `[xema-service-bootstrap] ${outputs.length} descriptor(s) found, but every one was skipped because its package has no src/ in this checkout; ` +
+      `${CHECK ? 'nothing was compared' : 'nothing was written'}. Run it in a checkout that contains the sources.`,
+  );
+  process.exit(1);
+}
+
+if (CHECK) {
+  if (drift > 0) {
+    console.error(`\n${drift} generated file(s) out of date.`);
+    process.exit(1);
+  }
+  console.log(`OK — ${records.length} service bootstrap and ${workerRecords.length} worker descriptor file(s) up to date.`);
+} else {
+  console.log(
+    `Done — ${written} written, ${skipped} skipped (source not in checkout), ${outputs.length} total.`,
+  );
+}