@bongos/core 1.21.174 → 1.21.176

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

@@ -0,0 +1,576 @@
+#!/usr/bin/env node
+'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/bongos/gen-api-client.js          # (re)generate the client package
+//   node scripts/bongos/gen-api-client.js --check   # exit 2 unless a client generated from the
+//                                                   # routes builds and compiles. The client is
+//                                                   # gitignored (task 1004866), never compared.
+
+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/bongos/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/bongos/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/bongos/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/bongos/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.
+// task 1004866: docs/api/openapi.json is gitignored, so a fresh clone has none — build the
+// spec in memory from the routes (gen-api-docs.build, pure and DB-free) when it is absent.
+function readSpec() {
+  if (fs.existsSync(SPEC_PATH)) return JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
+  return require('./gen-api-docs.js').build().spec;
+}
+
+function build(injectedSpec) {
+  const spec = injectedSpec || readSpec();
+  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 check = process.argv.includes('--check');
+  if (check) {
+    // task 1004866: the client is gitignored, so there is no committed copy to call stale.
+    // The gate is now "generation succeeds and matches the routes": build the client from
+    // a spec built FROM THE ROUTES (never a possibly-stale spec on disk), then prove each
+    // runnable build compiles. Writes nothing.
+    const spec = require('./gen-api-docs.js').build().spec;
+    const { ops, files } = build(spec);
+    const vm = require('node:vm');
+    const problems = [];
+    if (ops.length === 0) problems.push('no operations generated from the routes');
+    for (const [name, content] of Object.entries(files)) if (!content) problems.push(`${name} is empty`);
+    for (const name of ['index.cjs', 'bongos-client.global.js']) {
+      try { new vm.Script(files[name], { filename: name }); } catch (e) { problems.push(`${name} does not compile: ${e.message}`); }
+    }
+    if (ops.length !== Object.values(spec.paths).reduce((n, byMethod) => n + Object.keys(byMethod).length, 0)) {
+      problems.push('client operation count does not match the spec built from the routes');
+    }
+    if (problems.length) {
+      console.error('gen-api-client --check: generation FAILED:');
+      for (const p of problems) console.error('  - ' + p);
+      process.exit(2);
+    }
+    console.log(`gen-api-client --check: generation OK (${ops.length} operations from the routes).`);
+    return;
+  }
+  const { ops, files } = build();
+  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;
+    // Compare content (task 1003844): a core.autocrlf checkout hands readFileSync back
+    // CRLF, so a byte-wise `!==` rewrote an already-correct file on every Windows clone.
+    if (!sameContent(existing, content)) { fs.mkdirSync(OUT_DIR, { recursive: true }); fs.writeFileSync(dest, content); }
+  }
+  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();