@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/gen-api-client.js

@@ -1,557 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/gen-api-client.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/gen-api-client.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// gen-api-client.js — generate a typed JS client from the OpenAPI spec (task 1995,
-// R08 / goal 36 api-client-sdk). Per ADR 0118 (code-first, schema-as-data): the
-// client is GENERATED from docs/api/openapi.json — never hand-written — so it can
-// never drift from the routes. Emits into clients/bongos-client/:
-//   index.mjs   — createClient({ baseUrl, token, fetch }) → methods grouped by tag
-//   index.d.ts  — TypeScript types (method signatures + the error envelope)
-//   package.json, README.md
-//
-// Design (mirrors gen-api-docs.js / ADR 0063): deterministic (stable sort, no
-// clock), zero runtime deps, --check gate. The client itself has ZERO deps — it
-// uses the platform `fetch` (Node 18+ / browsers), so vendoring it pulls nothing
-// transitive. It is NOT published to npm (task 1003742) — consumers copy the build
-// they need; see the generated README.
-//
-// Usage:
-//   node scripts/gds/gen-api-client.js          # (re)generate the client package
-//   node scripts/gds/gen-api-client.js --check   # exit 2 if the committed client is stale
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { resolveDocsRoot } = require('../../src/instance-config');
-const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
-
-// The client is generated FROM the spec and lives beside it as a per-instance
-// artifact: both resolve to the DOCS root — the instance repo when a consumer
-// points at it (`bongos upgrade`), the same coreRoot in a single checkout (ADR
-// 0108, task 2051). So an upgrade regenerates the CONSUMER's client, not node_modules.
-const DOCS_ROOT = resolveDocsRoot();
-const SPEC_PATH = path.join(DOCS_ROOT, 'docs', 'api', 'openapi.json');
-const OUT_DIR = path.join(DOCS_ROOT, 'clients', 'bongos-client');
-
-const camel = (s) => String(s).replace(/[_\-/{}]+(.)?/g, (_, c) => (c ? c.toUpperCase() : '')).replace(/^(.)/, (m) => m.toLowerCase());
-const pascal = (s) => { const c = camel(s); return c.charAt(0).toUpperCase() + c.slice(1); };
-
-// Build the method model from the spec: [{ tag, name, method, path, pathParams,
-// queryParams, hasBody, bodyProps, rank, summary }]
-function buildModel(spec) {
-  const schemas = (spec.components && spec.components.schemas) || {};
-  const ops = [];
-  for (const [p, byMethod] of Object.entries(spec.paths)) {
-    for (const [method, op] of Object.entries(byMethod)) {
-      const tag = (op.tags && op.tags[0]) || 'default';
-      const params = op.parameters || [];
-      const pathParams = params.filter((x) => x.in === 'path').map((x) => x.name);
-      const queryParams = params.filter((x) => x.in === 'query').map((x) => x.name);
-      const bodySchema = op.requestBody && op.requestBody.content
-        && op.requestBody.content['application/json'] && op.requestBody.content['application/json'].schema;
-      // task 2050: the enriched spec references a NAMED request schema by $ref; resolve
-      // it so we can (a) type the method's body and (b) show real fields in the README.
-      const bodyRef = bodySchema && bodySchema.$ref ? bodySchema.$ref.split('/').pop() : null;
-      const refSchema = bodyRef ? schemas[bodyRef] : (bodySchema && bodySchema.properties ? bodySchema : null);
-      const bodyProps = refSchema && refSchema.properties ? Object.keys(refSchema.properties) : [];
-      const requiredBody = (refSchema && Array.isArray(refSchema.required)) ? refSchema.required : [];
-      // task 2061: the enriched spec attaches a named RESPONSE schema to the success
-      // (2xx) response when the route's res.json({…}) shape is statically provable.
-      // Resolve it so the method return types as `Promise<ThatShape>` instead of the
-      // `ApiResponse` (any) alias. Absent → keep ApiResponse (the shape wasn't provable).
-      const okResp = op.responses && (op.responses['200'] || op.responses['201'] || op.responses['202']);
-      const okSchema = okResp && okResp.content && okResp.content['application/json'] && okResp.content['application/json'].schema;
-      const responseRef = okSchema && okSchema.$ref ? okSchema.$ref.split('/').pop() : null;
-      ops.push({
-        tag,
-        methodName: camel(op.operationId || `${method}_${p}`),
-        httpMethod: method.toUpperCase(),
-        path: p,
-        pathParams,
-        queryParams,
-        hasBody: !!bodySchema || ['post', 'put', 'patch'].includes(method),
-        bodyRef,                                          // the components.schemas key, if any
-        bodyRequired: !!(op.requestBody && op.requestBody.required),
-        bodyProps,
-        requiredBody,
-        responseRef,
-        rank: op['x-rank'] || 'unknown',
-        summary: (op.summary || op.description || '').split('\n')[0].slice(0, 120),
-      });
-    }
-  }
-  // stable sort by tag then path then method
-  ops.sort((a, b) => a.tag.localeCompare(b.tag) || a.path.localeCompare(b.path) || a.httpMethod.localeCompare(b.httpMethod));
-  return ops;
-}
-
-function groupByTag(ops) {
-  const groups = {};
-  for (const op of ops) (groups[camel(op.tag)] ||= []).push(op);
-  return groups;
-}
-
-// --- emit index.mjs ---------------------------------------------------------
-function renderClientJs(spec, ops) {
-  const groups = groupByTag(ops);
-  const defaultBase = (spec.servers && spec.servers[0] && spec.servers[0].url) || '/api/bongos/v1';
-  const L = [];
-  L.push(`// @bongos/client — GENERATED from the OpenAPI spec by`);
-  L.push(`// scripts/gds/gen-api-client.js (task 1995 / ADR 0118). DO NOT EDIT BY HAND —`);
-  L.push(`// regenerate on spec change. Zero deps; uses the platform fetch.`);
-  L.push(`'use strict';`);
-  L.push('');
-  L.push(`export const API_VERSION = ${JSON.stringify(spec['x-api-version'] || 'v1')};`);
-  L.push(`export const DEFAULT_BASE_URL = ${JSON.stringify(defaultBase)};`);
-  L.push('');
-  L.push(`// The one error shape (ADR 0116). A non-2xx response rejects with this.`);
-  L.push(`export class ApiError extends Error {`);
-  L.push(`  constructor(status, body) {`);
-  L.push(`    const env = body && body.error;`);
-  L.push(`    super((env && (env.message || env.code)) || ('HTTP ' + status));`);
-  L.push(`    this.name = 'ApiError';`);
-  L.push(`    this.status = status;`);
-  L.push(`    this.code = env && env.code;`);
-  L.push(`    this.details = env && env.details;`);
-  L.push(`  }`);
-  L.push(`}`);
-  L.push('');
-  L.push(`function buildPath(template, args) {`);
-  L.push(`  return template.replace(/\\{(\\w+)\\}/g, (_, k) => {`);
-  L.push(`    if (args[k] == null) throw new Error('missing path param: ' + k);`);
-  L.push(`    return encodeURIComponent(args[k]);`);
-  L.push(`  });`);
-  L.push(`}`);
-  L.push('');
-  L.push(`function qs(query) {`);
-  L.push(`  if (!query) return '';`);
-  L.push(`  const parts = [];`);
-  L.push(`  for (const [k, v] of Object.entries(query)) {`);
-  L.push(`    if (v == null) continue;`);
-  L.push(`    parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(v));`);
-  L.push(`  }`);
-  L.push(`  return parts.length ? '?' + parts.join('&') : '';`);
-  L.push(`}`);
-  L.push('');
-  L.push(`// createClient({ baseUrl, token, fetch, throwOnError }) — baseUrl defaults to the`);
-  L.push(`// versioned same-origin base (${defaultBase}). Pass an absolute baseUrl for an`);
-  L.push(`// external caller. token → Authorization: Bearer. fetch defaults to the platform`);
-  L.push(`// fetch. throwOnError (default true): a non-2xx rejects with ApiError and a 2xx`);
-  L.push(`// resolves to the parsed body. Set throwOnError:false for the internal-CLI`);
-  L.push(`// contract — every call resolves to { status, ok, data } and never throws on HTTP`);
-  L.push(`// status (network errors still reject), so status-inspecting callers port 1:1.`);
-  L.push(`// credentials: forwarded to fetch as \`credentials\` (e.g. 'same-origin' / 'include')`);
-  L.push(`// so a same-origin BROWSER page can authenticate by session COOKIE instead of a`);
-  L.push(`// Bearer token — the hall/status web pages use this (task 1996 / R09).`);
-  L.push(`export function createClient(opts = {}) {`);
-  L.push(`  // An explicit baseUrl:'' means "paths are already absolute" — honored (not`);
-  L.push(`  // treated as unset), so a caller that passes full same-origin paths (e.g. the`);
-  L.push(`  // hall's fetch wrappers, task 1996) routes them through unchanged.`);
-  L.push(`  const baseUrl = (opts.baseUrl != null ? opts.baseUrl : DEFAULT_BASE_URL).replace(/\\/$/, '');`);
-  L.push(`  const token = opts.token || null;`);
-  L.push(`  const credentials = opts.credentials || null;`);
-  L.push(`  const cache = opts.cache || null; // forwarded to fetch (e.g. 'no-store' for the public status page)`);
-  L.push(`  const doFetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);`);
-  L.push(`  const throwOnError = opts.throwOnError !== false;`);
-  L.push(`  if (!doFetch) throw new Error('no fetch available — pass opts.fetch');`);
-  L.push(`  async function request(method, template, spec, args) {`);
-  L.push(`    args = args || {};`);
-  L.push(`    const url = baseUrl + buildPath(template, args) + qs(args.query);`);
-  L.push(`    const headers = Object.assign({}, args.headers);`);
-  L.push(`    if (token) headers['Authorization'] = 'Bearer ' + token;`);
-  L.push(`    const init = { method, headers };`);
-  L.push(`    if (credentials) init.credentials = credentials;`);
-  L.push(`    if (args.cache || cache) init.cache = args.cache || cache;`);
-  L.push(`    if (spec.hasBody && args.body !== undefined) {`);
-  L.push(`      headers['Content-Type'] = 'application/json';`);
-  L.push(`      init.body = JSON.stringify(args.body);`);
-  L.push(`    }`);
-  L.push(`    const res = await doFetch(url, init);`);
-  L.push(`    const text = await res.text();`);
-  L.push(`    let data = null;`);
-  L.push(`    try { data = text ? JSON.parse(text) : null; } catch { data = null; }`);
-  L.push(`    if (!res.ok && throwOnError) throw new ApiError(res.status, data);`);
-  L.push(`    return throwOnError ? data : { status: res.status, ok: res.ok, data };`);
-  L.push(`  }`);
-  L.push(`  return {`);
-  L.push(`    // Generic escape hatch for a path with no generated method (an undocumented`);
-  L.push(`    // route or a non-API URL). request(method, path, { query, body, headers }).`);
-  L.push(`    // Honors the same throwOnError mode. \`path\` is relative to baseUrl.`);
-  L.push(`    request: (method, path, o) => { o = o || {}; return request(method, path, { hasBody: o.hasBody != null ? o.hasBody : o.body !== undefined }, o); },`);
-  for (const [tag, list] of Object.entries(groups).sort()) {
-    L.push(`    ${JSON.stringify(tag)}: {`);
-    for (const op of list) {
-      const specObj = `{ hasBody: ${op.hasBody} }`;
-      L.push(`      // ${op.httpMethod} ${op.path} — rank: ${op.rank}${op.summary ? ' — ' + op.summary.replace(/\*\//g, '') : ''}`);
-      L.push(`      ${op.methodName}: (args) => request(${JSON.stringify(op.httpMethod)}, ${JSON.stringify(pathParamsTemplate(op.path))}, ${specObj}, args),`);
-    }
-    L.push(`    },`);
-  }
-  L.push(`  };`);
-  L.push(`}`);
-  L.push('');
-  L.push(`export default createClient;`);
-  return L.join('\n') + '\n';
-}
-
-// convert /tasks/:id → /tasks/{id} (spec paths already use {id}; keep as-is)
-function pathParamsTemplate(p) { return p; }
-
-// --- derive alternate module formats from the emitted ESM --------------------
-// The body of createClient() is universal JS — only the top-level `export`
-// bindings make index.mjs ESM. So the CJS and browser-global builds are pure
-// syntactic transforms of the SAME emitted ESM source: they can never diverge
-// in behavior from the module the tests exercise. The generator owns the export
-// surface, so the binding names are fixed (API_VERSION, DEFAULT_BASE_URL,
-// ApiError, createClient).
-function stripEsmExports(esm) {
-  return esm
-    .replace(/^export (const|class|function) /gm, '$1 ')
-    .replace(/^export default createClient;\n?/m, '');
-}
-
-// index.cjs — for Node consumers that use require() (e.g. a zero-dep CJS subproject
-// that vendors this file at package time).
-function renderClientCjs(esm) {
-  const header =
-    '// @bongos/client (CommonJS build) — GENERATED from index.mjs by\n' +
-    '// scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Same behavior as the ESM\n' +
-    '// build; only the module bindings differ. For require()-based consumers.\n';
-  const body = stripEsmExports(esm)
-    .replace(/^\/\/ @cloudbongos\/client — GENERATED[^\n]*\n(?:\/\/[^\n]*\n)*/m, '');
-  return header + body +
-    '\nmodule.exports = createClient;\n' +
-    'module.exports.createClient = createClient;\n' +
-    'module.exports.ApiError = ApiError;\n' +
-    'module.exports.API_VERSION = API_VERSION;\n' +
-    'module.exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;\n';
-}
-
-// bongos-client.global.js — a browser-global (IIFE) build for classic <script>
-// pages that are not ES modules. Exposes window.BongosClient = { createClient,
-// ApiError, API_VERSION, DEFAULT_BASE_URL }. Served publicly by the app so pages
-// can consume the generated client without a module/bundler step.
-function renderClientBrowserGlobal(esm) {
-  const body = stripEsmExports(esm)
-    .replace(/^'use strict';\n/m, '')
-    .replace(/^\/\/ @cloudbongos\/client — GENERATED[^\n]*\n(?:\/\/[^\n]*\n)*/m, '');
-  return (
-    '// @bongos/client (browser-global build) — GENERATED from index.mjs by\n' +
-    '// scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Exposes window.BongosClient\n' +
-    '// for classic <script> pages. Same behavior as the ESM build.\n' +
-    '(function (global) {\n' +
-    "'use strict';\n" +
-    body +
-    '\nglobal.BongosClient = { createClient: createClient, ApiError: ApiError, ' +
-    'API_VERSION: API_VERSION, DEFAULT_BASE_URL: DEFAULT_BASE_URL };\n' +
-    "})(typeof globalThis !== 'undefined' ? globalThis : (typeof self !== 'undefined' ? self : this));\n"
-  );
-}
-
-// --- emit index.d.ts --------------------------------------------------------
-// task 2050 (ADR 0118 "one schema, three consumers"): the enriched spec carries
-// field-level request schemas in components.schemas. We render each as a TS type
-// and give every write method a TYPED `body`, so the client stops typing request
-// bodies as `unknown`. task 2061 (ADR 0124) extends this to SUCCESS responses: a
-// route whose res.json({…}) shape is statically provable gets a `<OperationId>Response`
-// component (rendered here as an interface, same as request schemas), and its method
-// returns `Promise<ThatShape>`. A route whose shape can't be proven keeps `ApiResponse`.
-
-const TS_RESERVED_KEY = /^[A-Za-z_$][\w$]*$/;
-function tsLiteral(v) { return typeof v === 'string' ? JSON.stringify(v) : String(v); }
-function tsScalarType(t) { return t === 'string' ? 'string' : (t === 'integer' || t === 'number') ? 'number' : t === 'boolean' ? 'boolean' : 'unknown'; }
-function tsPropKey(k) { return TS_RESERVED_KEY.test(k) ? k : JSON.stringify(k); }
-
-// A JSON Schema fragment → a TS type string. Handles the shapes gen-api-docs emits:
-// $ref, type-union (['integer','string']), scalars, enum unions, arrays, and objects.
-function tsForSchema(schema) {
-  if (!schema || typeof schema !== 'object') return 'unknown';
-  if (schema.$ref) return schema.$ref.split('/').pop();
-  if (Array.isArray(schema.enum) && schema.enum.length && schema.type === undefined) return schema.enum.map(tsLiteral).join(' | ');
-  const t = schema.type;
-  if (Array.isArray(t)) return t.map(tsScalarType).join(' | ');
-  if (t === 'string' || t === 'integer' || t === 'number' || t === 'boolean') {
-    if (Array.isArray(schema.enum) && schema.enum.length) return schema.enum.map(tsLiteral).join(' | ');
-    return tsScalarType(t);
-  }
-  if (t === 'array') {
-    const item = schema.items ? tsForSchema(schema.items) : 'unknown';
-    return /[ |&]/.test(item) ? `(${item})[]` : `${item}[]`;
-  }
-  if (t === 'object') return schema.properties ? tsObjectBody(schema) : 'Record<string, unknown>';
-  if (Array.isArray(schema.enum) && schema.enum.length) return schema.enum.map(tsLiteral).join(' | ');
-  return 'unknown';
-}
-
-function tsObjectBody(schema) {
-  const req = new Set(schema.required || []);
-  const props = Object.entries(schema.properties || {})
-    .map(([k, v]) => `${tsPropKey(k)}${req.has(k) ? '' : '?'}: ${tsForSchema(v)}`);
-  return `{ ${props.join('; ')} }`;
-}
-
-// Emit `export interface|type Name …` for every component schema (sorted, stable).
-function renderSchemaDecls(spec) {
-  const schemas = (spec.components && spec.components.schemas) || {};
-  const L = [];
-  for (const name of Object.keys(schemas).sort()) {
-    const s = schemas[name];
-    if (s && s.type === 'object' && s.properties) {
-      L.push(`export interface ${name} ${tsObjectBody(s)}`);
-    } else {
-      L.push(`export type ${name} = ${tsForSchema(s)};`);
-    }
-  }
-  return L;
-}
-
-function methodSignature(op) {
-  // task 2061: type the resolved return as the route's proven response shape when
-  // the spec carries one; otherwise the `ApiResponse` (any) alias, as before.
-  const ret = `Promise<${op.responseRef || 'ApiResponse'}>`;
-  if (op.bodyRef) {
-    return op.bodyRequired
-      ? `${op.methodName}(args: RequestArgs & { body: ${op.bodyRef} }): ${ret};`
-      : `${op.methodName}(args?: RequestArgs & { body?: ${op.bodyRef} }): ${ret};`;
-  }
-  return `${op.methodName}(args?: RequestArgs): ${ret};`;
-}
-
-function renderTypes(spec, ops) {
-  const groups = groupByTag(ops);
-  const L = [];
-  L.push(`// GENERATED — TypeScript types for @bongos/client (task 1995; field-level`);
-  L.push(`// request typing added in task 2050 / ADR 0118). DO NOT EDIT BY HAND.`);
-  L.push(`export declare const API_VERSION: string;`);
-  L.push(`export declare const DEFAULT_BASE_URL: string;`);
-  L.push(``);
-  L.push(`// Request-body + shared types, generated from the OpenAPI components.schemas.`);
-  for (const line of renderSchemaDecls(spec)) L.push(line);
-  L.push(``);
-  L.push(`// The fallback response type: a route whose res.json({…}) shape could not be`);
-  L.push(`// statically proven (a bare value, a spread, a computed key) returns this instead`);
-  L.push(`// of a named <OperationId>Response interface. Assignable both ways; cast at the call site.`);
-  L.push(`export type ApiResponse = any;`);
-  L.push(`export declare class ApiError extends Error { status: number; code?: string; details?: unknown }`);
-  L.push(`export interface ClientOptions { baseUrl?: string; token?: string; credentials?: RequestCredentials; cache?: RequestCache; fetch?: typeof fetch; throwOnError?: boolean }`);
-  L.push(`export interface RequestArgs { query?: Record<string, string | number | boolean | null | undefined>; body?: unknown; headers?: Record<string, string>; cache?: RequestCache; [pathParam: string]: unknown }`);
-  L.push(`// With throwOnError:false every method resolves to this instead of throwing on non-2xx.`);
-  L.push(`export interface Result<T = ApiResponse> { status: number; ok: boolean; data: T }`);
-  L.push(`export interface BongosClient {`);
-  L.push(`  /** Generic escape hatch for a path with no generated method. */`);
-  L.push(`  request(method: string, path: string, opts?: { query?: RequestArgs['query']; body?: unknown; headers?: Record<string, string>; cache?: RequestCache; hasBody?: boolean }): Promise<ApiResponse>;`);
-  for (const [tag, list] of Object.entries(groups).sort()) {
-    L.push(`  ${JSON.stringify(tag)}: {`);
-    for (const op of list) {
-      L.push(`    /** ${op.httpMethod} ${op.path} — rank: ${op.rank} */`);
-      L.push(`    ${methodSignature(op)}`);
-    }
-    L.push(`  };`);
-  }
-  L.push(`}`);
-  L.push(`export declare function createClient(opts?: ClientOptions): BongosClient;`);
-  L.push(`export default createClient;`);
-  return L.join('\n') + '\n';
-}
-
-function renderPackageJson(spec) {
-  return JSON.stringify({
-    name: '@bongos/client',
-    version: spec.info && spec.info.version ? spec.info.version : '0.0.0',
-    description: 'Generated typed client for the Bongos API (ADR 0118). Do not edit by hand.',
-    type: 'module',
-    main: 'index.mjs',
-    types: 'index.d.ts',
-    browser: './bongos-client.global.js',
-    unpkg: './bongos-client.global.js',
-    jsdelivr: './bongos-client.global.js',
-    exports: {
-      '.': {
-        types: './index.d.ts',
-        browser: './bongos-client.global.js',
-        import: './index.mjs',
-        require: './index.cjs',
-        default: './index.mjs',
-      },
-    },
-    files: ['index.mjs', 'index.cjs', 'index.d.ts', 'bongos-client.global.js', 'README.md'],
-    license: 'AGPL-3.0-or-later',
-    // `private: true` is the ENFORCEMENT of the paragraph below (task 1004143). Task
-    // 1003742 removed the publishConfig, which stopped the repo CLAIMING this was a
-    // published package — but nothing stopped it BECOMING one again: `npm publish` in
-    // clients/bongos-client/ succeeded and would have recreated @bongos/client@0.0.2,
-    // the exact package the owner deleted from the registry on 2026-09-09. npm now
-    // refuses with EPRIVATE, so that removal cannot be silently undone by anyone who
-    // runs publish in the wrong directory.
-    //
-    // This is not the publish posture the note below calls fiction. That was declaring
-    // HOW it publishes (access: restricted) for something never published; this
-    // declares that it does not publish, which is the same fact the note states in
-    // prose. It does not affect `main`/`types`/`exports`, so the vendored copy and a
-    // workspace link resolve exactly as before.
-    private: true,
-    // NO publishConfig — this client is NOT an npm package (task 1003742).
-    //
-    // It was published once, 2026-07-07 at 0.0.2, under ADR 0134's private-first plan, and never
-    // updated while the API it is generated FROM moved 500+ core versions. It had zero consumers
-    // the whole time: nothing across the core or any instance repo ever declared it as a
-    // dependency — every consumer VENDORS a copy instead. That was two places when this was
-    // written; both have since been deleted or retired (ADR 0324 retired
-    // @cloudbongos/cli), so there is now no vendoring consumer left at all. The
-    // owner removed it from the registry on 2026-09-09.
-    //
-    // The manifest itself stays: `main`/`types`/`exports` are what make the vendored copy and a
-    // workspace link resolve. Declaring a publish posture is the part that was fiction.
-    sideEffects: false,
-  }, null, 2) + '\n';
-}
-
-// Pick representative ops for the README's usage block, straight from the model —
-// so the example only ever names methods the generator actually emits (it used to
-// hardcode getTask/createTask, which the operationId-derived namer never produces).
-// Prefer the `tasks` group for a familiar narrative; fall back to whatever exists.
-function pickExamples(ops) {
-  const pref = (list) => list.find((o) => o.tag === 'tasks') || list[0] || null;
-  return {
-    simple: ops.find((o) => o.tag === 'me' && o.methodName === 'getMe')
-      || pref(ops.filter((o) => o.httpMethod === 'GET' && !o.pathParams.length && !o.queryParams.length)),
-    getOne: pref(ops.filter((o) => o.httpMethod === 'GET' && o.pathParams.length === 1)),
-    create: pref(ops.filter((o) => o.httpMethod === 'POST' && o.hasBody && !o.pathParams.length)),
-    // A plain collection GET for the `query` example. The spec declares no query
-    // params (gen-api-docs doesn't extract them yet), but the client forwards any
-    // `query` object generically — so we illustrate it on a real collection route.
-    list: pref(ops.filter((o) => o.httpMethod === 'GET' && !o.pathParams.length && o.methodName !== 'getMe')),
-  };
-}
-
-// The lines inside the README's `try { … }`, built from real ops. Each carries an
-// inline comment with the actual route so the mapping method→endpoint is visible.
-function exampleLines(ops) {
-  const g = (o) => camel(o.tag);
-  const L = [];
-  const ex = pickExamples(ops);
-  if (ex.simple) L.push(`  const first = await api.${g(ex.simple)}.${ex.simple.methodName}();               // GET ${ex.simple.path}`);
-  if (ex.getOne) L.push(`  const item = await api.${g(ex.getOne)}.${ex.getOne.methodName}({ ${ex.getOne.pathParams[0]}: 1988 });   // GET ${ex.getOne.path}`);
-  if (ex.create) {
-    const props = (ex.create.requiredBody.length ? ex.create.requiredBody : ex.create.bodyProps).slice(0, 2);
-    const body = props.length ? props.map((p) => `${p}: '…'`).join(', ') : '/* … */';
-    L.push(`  const created = await api.${g(ex.create)}.${ex.create.methodName}({ body: { ${body} } }); // ${ex.create.httpMethod} ${ex.create.path}`);
-  }
-  if (ex.list) L.push(`  const page = await api.${g(ex.list)}.${ex.list.methodName}({ query: { limit: 25, offset: 0 } }); // GET ${ex.list.path}`);
-  return L;
-}
-
-function renderReadme(spec, ops) {
-  const base = (spec.servers && spec.servers[0] && spec.servers[0].url) || '/api/bongos/v1';
-  return [
-    `# @bongos/client`,
-    ``,
-    `A **generated**, zero-dependency typed client for the Bongos API — produced from`,
-    `\`docs/api/openapi.json\` by \`scripts/gds/gen-api-client.js\` (ADR 0118). Do not edit`,
-    `by hand; it regenerates when the spec changes, so it can never drift from the routes.`,
-    ``,
-    `- API version: **${spec['x-api-version'] || 'v1'}** (served at \`${base}\`)`,
-    `- ${ops.length} operations across ${new Set(ops.map((o) => o.tag)).size} resource groups`,
-    ``,
-    `## Use it from your project`,
-    ``,
-    `**This is not an npm package** — it is not published, and nothing depends on it as one`,
-    `(task 1003742). Consume it by VENDORING the build you need, which is what every consumer`,
-    `in this repo already does:`,
-    ``,
-    '```bash',
-    `# ESM / bundler:  cp clients/bongos-client/index.mjs  <your project>/vendor/`,
-    `# CommonJS:       cp clients/bongos-client/index.cjs  <your project>/vendor/`,
-    `# Browser global: cp clients/bongos-client/bongos-client.global.js <your project>/public/`,
-    '```',
-    ``,
-    `Copy \`index.d.ts\` alongside it for types. Re-copy after \`gen-api-client.js\` runs, so the`,
-    `client cannot drift from the routes.`,
-    ``,
-    `## Use`,
-    ``,
-    `The examples import by package name, which resolves in a workspace. A VENDORED copy is`,
-    `imported by its path instead — \`from './vendor/index.mjs'\` — everything below is identical.`,
-    ``,
-    '```js',
-    `import { createClient, ApiError } from '@bongos/client';`,
-    ``,
-    `const api = createClient({`,
-    `  baseUrl: 'https://example.com${base}', // your instance origin — or omit for same-origin (browser)`,
-    `  token: process.env.BONGOS_TOKEN,             // Authorization: Bearer <token>`,
-    `});`,
-    ``,
-    `try {`,
-    ...exampleLines(ops),
-    `} catch (e) {`,
-    `  if (e instanceof ApiError) console.error(e.code, e.status, e.details); // the ADR-0116 envelope`,
-    `}`,
-    '```',
-    ``,
-    `Every method takes one \`args\` object: path params by name (e.g. \`{ id }\`), plus`,
-    `optional \`query\`, \`body\`, and \`headers\`. A non-2xx response throws \`ApiError\``,
-    `carrying the envelope's \`code\` / \`message\` / \`details\` and the HTTP \`status\`.`,
-    ``,
-    `## Authenticate + a runnable hello-world`,
-    ``,
-    `How to get a \`token\` (Device Flow for a headless program, or a portal-issued`,
-    `bearer) and a copy-paste-runnable proof are in the on-ramp guide:`,
-    `**\`docs/api-onramp.md\`**. The example lives next to this client:`,
-    ``,
-    '```bash',
-    `node clients/bongos-client/examples/hello-world.mjs   # public read — no token needed`,
-    '```',
-    ``,
-  ].join('\n');
-}
-
-// injectedSpec (task 1003537): the otb-regen merge driver regenerates this client
-// DURING a merge, when docs/api/openapi.json on disk may be the conflicted file git has
-// just written markers into — JSON.parse would throw on it. Passing a spec built in
-// memory keeps the heal working and keeps the client consistent with the api-reference.md
-// the same merge resolves. Omitted everywhere else, so the CLI path is unchanged.
-function build(injectedSpec) {
-  const spec = injectedSpec || JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
-  const ops = buildModel(spec);
-  const esm = renderClientJs(spec, ops);
-  return {
-    ops,
-    files: {
-      'index.mjs': esm,
-      'index.cjs': renderClientCjs(esm),
-      'bongos-client.global.js': renderClientBrowserGlobal(esm),
-      'index.d.ts': renderTypes(spec, ops),
-      'package.json': renderPackageJson(spec),
-      'README.md': renderReadme(spec, ops),
-    },
-  };
-}
-
-function main() {
-  const { ops, files } = build();
-  const check = process.argv.includes('--check');
-  let stale = false;
-  for (const [name, content] of Object.entries(files)) {
-    const dest = path.join(OUT_DIR, name);
-    const existing = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
-    // Freshness is a question about CONTENT, so compare content (task 1003844 — the
-    // same defect as 1003619). We render with join('\n') = LF, but a core.autocrlf
-    // checkout hands readFileSync back CRLF, so a byte-wise `!==` called the already
-    // -correct client STALE on every Windows clone, forever: regenerating writes LF,
-    // git restores CRLF, gate red again. Comparing via sameContent cures it for every
-    // file here at once, so a seventh generated file can't reintroduce it by missing
-    // an eol pin. A missing file reads as null, which never matches a non-empty
-    // render — still stale, as before.
-    if (!sameContent(existing, content)) {
-      stale = true;
-      if (!check) { fs.mkdirSync(OUT_DIR, { recursive: true }); fs.writeFileSync(dest, content); }
-    }
-  }
-  if (check) {
-    if (stale) { console.error('clients/bongos-client is STALE — run `node scripts/gds/gen-api-client.js`'); process.exit(2); }
-    console.log('clients/bongos-client is fresh.');
-  } else {
-    console.log(`gen-api-client: wrote clients/bongos-client (${ops.length} operations, ${Object.keys(files).length} files).`);
-  }
-}
-
-module.exports = { build, buildModel, groupByTag, renderClientJs, renderTypes, camel, pascal };
-if (require.main === module) main();
+require('../bongos/forwarder.js').forward(module, 'gen-api-client.js');