@redocly/cli 2.47.0 → 2.48.0

package/lib/eject-assets/AGENTS.md

@@ -0,0 +1,137 @@
+# Writing custom client generators
+
+A generator is a plain module: `(input) => GeneratedFile[]`. It receives the
+language-agnostic API model and returns files — in ANY output language. It runs
+in the same pass as the built-ins; select it by path in `redocly.yaml`:
+
+```yaml
+client:
+  generators: [typescript, ./generators/my-generator.mjs]
+```
+
+## The contract
+
+```js
+/** @type {import('@redocly/client-generator').CustomGenerator} */
+export default {
+  name: 'my-generator',
+  run({ model, output, outputMode, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.txt'), content: '…' }];
+  },
+  // Optional: one idiomatic call snippet per operation for docs (x-codeSamples),
+  // collected into an overlay file when `client.codeSamples: true` is set.
+  sample(operation, { model, emit }) {
+    return { lang: 'python', source: '…' };
+  },
+  // Optional: the reference page for what `run` emits, written when `client.docs` (or
+  // --docs) is on. Same `{ path, content }` shape as `run`; `renderReferencePage` gives
+  // the standard layout and takes `sample` for its snippets. A generator documents itself.
+  docs({ model, output, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.md'), content: '…' }];
+  },
+};
+```
+
+## Declaring options
+
+A generator that needs configuration declares it as a schema; `run` then receives
+`options` already validated, with defaults applied:
+
+```js
+export default {
+  name: 'permissions-matrix',
+  options: {
+    type: 'object',
+    properties: { groupBy: { enum: ['tag', 'path'], default: 'tag' } },
+    additionalProperties: false,
+  },
+  run({ model, output, options }) {
+    return [
+      { path: output.path.replace(/\.ts$/, '.permissions.md'), content: render(options.groupBy) },
+    ];
+  },
+};
+```
+
+Users set them per generator name:
+
+```yaml
+client:
+  generators: [typescript, ./generators/permissions-matrix.mjs]
+  options:
+    permissions-matrix:
+      groupBy: path
+```
+
+The supported subset is a top-level `type: 'object'` with `properties`, `required`, and
+`additionalProperties`; each property is a scalar (`string`/`number`/`boolean`), an
+`enum`, or an array of scalars, and may carry a `default` and a `description`. Don't
+validate options inside `run` — an unknown key, a wrong type, a value outside an `enum`,
+or a missing `required` key already fails generation before `run` is called.
+
+Rules: output is deterministic (same description → same bytes); never add
+dependencies to the generated client; **never hand-edit generated output** —
+edit this generator and regenerate. Emitted file paths must stay inside the
+`--output` directory (subdirectories are fine) — escapes are rejected.
+Optionally declare `requiresGenerator` — the `@redocly/client-generator` version
+range you wrote this against (`'^1.2.0'`, `'~1.2.0'`, `'>=1.2.0'`, or an exact
+version). A CLI outside the range then fails with the fix path instead of feeding
+your generator an unexpected model shape. Ejected generators carry it
+automatically; hand-written ones without it are taken as current.
+
+## The model (IR)
+
+`model.services[].operations[]` — each operation carries `name`, `specName`,
+`method`, `path`, `tags`, `pathParams`/`queryParams`/`headerParams`/`cookieParams`,
+`requestBody`, `successResponses`/`errorResponses` (each with a `schema`), and
+`security`. `model.schemas` holds the named schemas. Every schema is a
+discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
+`literal`, `enum`, `union` (optionally with a discriminator), `intersection`
+(allOf), `null`, `unknown`, `omit`.
+
+## Helpers (import from '@redocly/client-generator')
+
+| Helper                                                  | Use                                                                                                                              |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `flattenAllOf(schema, model)`                           | The merged property view of allOf compositions — languages without intersection types render this.                               |
+| `deref(schema, model)`                                  | Follow a `ref` chain to the schema it names (cycle-guarded).                                                                     |
+| `jsonSuccessSchema(op)` / `sseResponse(op)`             | The primary JSON success schema; the `text/event-stream` response when the operation streams.                                    |
+| `isMultipartBody(op)`                                   | Whether the request body is multipart.                                                                                           |
+| `serverUrlParts(server)`                                | A server-URL template as literal/variable parts, ready for any concatenation syntax.                                             |
+| `securityRequirements(op, model)`                       | The operation's security as OR-alternatives of AND-sets, denormalized against the declared schemes.                              |
+| `paginationItemSchema(pageSchema, itemsPointer, model)` | The raw element schema behind a pagination rule's `items` pointer — a `ref` element keeps its name.                              |
+| `discriminatorCases(schema, model)`                     | `{ property, cases }` dispatch table for discriminated unions.                                                                   |
+| `isNullable(schema)` / `unwrapNullable(schema)`         | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                    |
+| `enumValues(schema)`                                    | Values plus SCREAMING_SNAKE member-name suggestions.                                                                             |
+| `headerCoerceType(schema, model)`                       | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                 |
+| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                          |
+| `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter. |
+| `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                               |
+| `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                             |
+| `schemaAtPointer(schema, pointer, model)`               | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type. |
+| `paginationRuleFor(op, config)`                         | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                   |
+| `renderReferencePage(model, options)`                   | The Markdown reference page a generator's `docs` hook returns — your `sample` hook supplies its call snippets.                   |
+| `NotSupportedError`                                     | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                |
+| `AUTHORING_HELPER_NAMES`                                | The list of the above (introspection).                                                                                           |
+
+Worked example: the built-in `python` generator
+(`packages/client-generator/src/generators/python/index.ts` in the Redocly CLI repo) is
+authored with exactly this toolkit and nothing else — models via `flattenAllOf`/
+`enumValues`/`discriminatorCases`, all code through `Printer`, every name through
+`identifierFor(..., RESERVED_WORDS.python)`.
+
+A generator that emits TypeScript may additionally use the source-text renderers from
+`@redocly/client-generator/generate` — `tsType` (schema → type), `tsJsdoc`, `codeLiteral`,
+`operationSignature`, `pascalCase`, `safeIdent`. There is no AST toolkit and no
+`typescript` dependency: every generator prints text through `Printer`.
+
+## The loop
+
+1. Edit the generator.
+2. Run `redocly generate-client`.
+3. Inspect `git diff` of the generated output.
+4. Repeat. Generated files are never hand-edited.
+
+If you had to work around a **missing helper** or a wrong default, tell the user
+and suggest filing an issue at https://github.com/Redocly/redocly-cli/issues —
+include the generator snippet and the helper you expected to exist.

package/lib/eject-assets/generators/cli/docs.ts

@@ -0,0 +1,224 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+// The cli-docs emitter: renders the Markdown reference for the generated CLI from the
+// SAME command table `runCli` dispatches on, and the same `groupSlug`/`constantCase` the
+// runtime addresses groups and reads credentials with. A second model would drift from
+// the tool the first time either side changed.
+
+import {
+  type CliCommand,
+  type CliFlag,
+  constantCase,
+  groupSlug,
+  Printer,
+} from '@redocly/client-generator';
+
+export type CliDocsOptions = {
+  /** Page heading. */
+  title: string;
+  /** Emit YAML front matter carrying the title, for docs sites that expect it. */
+  frontmatter: boolean;
+  /** The generated file's stem: what the page calls the command, and what its credential
+   * variables derive from. A reader who installs it under another bin name renames only
+   * the command — the variables are fixed at generation. */
+  name: string;
+  /** Auth schemes the description declares, in the order the CLI resolves them. */
+  schemes: Array<{ key: string; kind: 'bearer' | 'basic' | 'apiKey' }>;
+};
+
+/** Table-cell-safe text: one line, and pipes/backslashes escaped so they don't alter columns/escaping. */
+function cell(text: string | undefined): string {
+  return (text ?? '').replace(/\s+/g, ' ').trim().replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+/** How a command is typed at the prompt: `<group-slug> <name>`, or just `<name>`. */
+function address(command: CliCommand): string {
+  return [command.group === undefined ? undefined : groupSlug(command.group), command.name]
+    .filter(Boolean)
+    .join(' ');
+}
+
+function usageLine(name: string, command: CliCommand): string {
+  const words = [
+    name,
+    address(command),
+    ...command.positionals.map((positional) => `<${positional.name}>`),
+    ...command.flags.filter((flag) => flag.required).map((flag) => `--${flag.name} <${flag.type}>`),
+    ...(command.body ? [command.body.required ? "--json '<json>'" : "[--json '<json>']"] : []),
+  ];
+  return words.filter((word) => word !== '').join(' ');
+}
+
+function writeFlagTable(printer: Printer, flags: CliFlag[]): void {
+  printer.line('| Flag | Type | Required | Description |');
+  printer.line('| ---- | ---- | -------- | ----------- |');
+  for (const flag of flags) {
+    const description = [
+      cell(flag.description),
+      flag.enum === undefined
+        ? ''
+        : `One of ${flag.enum.map((value) => `\`${value}\``).join(', ')}.`,
+      flag.type === 'array' ? 'Repeat the flag for multiple values.' : '',
+    ]
+      .filter((part) => part !== '')
+      .join(' ');
+    printer.line(
+      `| \`--${flag.name}\` | ${flag.type} | ${flag.required ? 'yes' : 'no'} | ${description} |`
+    );
+  }
+  printer.blank();
+}
+
+function writeCommand(printer: Printer, command: CliCommand, options: CliDocsOptions): void {
+  printer.line(`### \`${address(command)}\``);
+  printer.blank();
+  if (command.summary !== undefined) {
+    printer.line(cell(command.summary));
+    printer.blank();
+  }
+  printer.line(`\`${command.method} ${command.path}\``);
+  printer.blank();
+  printer.line('```sh');
+  printer.line(usageLine(options.name, command));
+  printer.line('```');
+  printer.blank();
+  if (command.positionals.length > 0) {
+    printer.line('| Argument | Description |');
+    printer.line('| -------- | ----------- |');
+    for (const positional of command.positionals) {
+      printer.line(`| \`<${positional.name}>\` | ${cell(positional.description)} |`);
+    }
+    printer.blank();
+  }
+  if (command.flags.length > 0) writeFlagTable(printer, command.flags);
+  const notes = [
+    command.body === undefined
+      ? ''
+      : `Takes a JSON body${command.body.required ? ' (required)' : ''}: \`--json '<json>'\`, \`--json @file.json\`, or \`--json @-\` for stdin.`,
+    command.unsupportedBody === undefined
+      ? ''
+      : `Takes a \`${command.unsupportedBody}\` body, which the CLI cannot build — call this operation through the generated client instead.`,
+    command.paginated === true
+      ? 'Paginated: `--page-all` follows every page, printing one JSON page per line.'
+      : '',
+    command.sse === true ? 'Streams server-sent events as one JSON object per line.' : '',
+    command.blob === true ? 'Returns binary content, so `--output <path>` is required.' : '',
+  ].filter((note) => note !== '');
+  for (const note of notes) printer.line(note);
+  if (notes.length > 0) printer.blank();
+}
+
+/** The whole page: heading, global flags, credentials, exit codes, then every command. */
+export function renderCliDocs(commands: CliCommand[], options: CliDocsOptions): string {
+  const printer = new Printer();
+  if (options.frontmatter) {
+    printer.line('---');
+    printer.line(`title: ${options.title}`);
+    printer.line('---');
+    printer.blank();
+  }
+  printer.line(`# ${options.title}`);
+  printer.blank();
+  printer.line(
+    `Generated command-line reference for \`${options.name}\`, produced from the API description by \`redocly generate-client\`.`
+  );
+  printer.line('Re-run generation to update it — this file is not hand-edited.');
+  printer.blank();
+
+  printer.line('## Usage');
+  printer.blank();
+  printer.line('```sh');
+  printer.line(`${options.name} <command> [flags]`);
+  printer.line(`${options.name} --help`);
+  printer.line(`${options.name} schema <command>   # request/response schemas`);
+  printer.line('```');
+  printer.blank();
+  printer.line(
+    'Install the file under any `bin` name: the command takes that name, and the credential variables below do not change.'
+  );
+  printer.blank();
+
+  printer.line('## Global flags');
+  printer.blank();
+  printer.line('| Flag | Description |');
+  printer.line('| ---- | ----------- |');
+  // `--token` mirrors the CLI itself: without a bearer scheme the tool rejects the flag,
+  // so the reference must not list it.
+  const hasBearer = options.schemes.some((scheme) => scheme.kind === 'bearer');
+  for (const [flag, description] of [
+    ['--server-url <url>', 'Override the server URL included in the client.'],
+    ['--format <json\\|ndjson>', 'Output format.'],
+    ['--dry-run', 'Print the prepared request, credentials redacted, without sending it.'],
+    ['--page-all', 'Follow pagination, printing one JSON page per line.'],
+    ['--output <path>', 'Write the response body to a file. Required for binary responses.'],
+    ...(hasBearer ? [['--token <token>', 'Bearer token, overriding the environment.']] : []),
+    ['--json <json\\|@file\\|@->', 'Request body, inline or from a file or stdin.'],
+  ] as const) {
+    printer.line(`| \`${flag}\` | ${description} |`);
+  }
+  printer.blank();
+
+  const prefix = constantCase(options.name);
+  printer.line('## Credentials');
+  printer.blank();
+  if (options.schemes.length === 0) {
+    printer.line('The description declares no security schemes, so no credentials are read.');
+  } else {
+    printer.line('Credentials come from the environment:');
+    printer.blank();
+    printer.line('| Scheme | Variable |');
+    printer.line('| ------ | -------- |');
+    for (const scheme of options.schemes) {
+      const variable =
+        scheme.kind === 'bearer'
+          ? `\`${prefix}_TOKEN\` (or \`--token\`)`
+          : scheme.kind === 'basic'
+            ? `\`${prefix}_USERNAME\` and \`${prefix}_PASSWORD\``
+            : `\`${prefix}_API_KEY_${constantCase(scheme.key)}\``;
+      printer.line(`| ${scheme.kind} (\`${scheme.key}\`) | ${variable} |`);
+    }
+  }
+  printer.blank();
+
+  printer.line('## Exit codes');
+  printer.blank();
+  printer.line('| Code | Meaning |');
+  printer.line('| ---- | ------- |');
+  for (const [code, meaning] of [
+    [0, 'success'],
+    [1, 'API error (status other than 401 or 403)'],
+    [2, 'auth error (401 or 403)'],
+    [3, 'validation error'],
+    [4, 'usage error (unknown command or flag, bad `--json`)'],
+  ] as const) {
+    printer.line(`| ${code} | ${meaning} |`);
+  }
+  printer.blank();
+  printer.line('Errors print one JSON object to stderr, so stdout stays clean for piping.');
+  printer.blank();
+
+  // One section per tag, in the order the description declares them, then the untagged
+  // commands — the same order `--help` lists them in.
+  const groups = [...new Set(commands.map((command) => command.group))];
+  for (const group of groups) {
+    const inGroup = commands.filter((command) => command.group === group);
+    if (group === undefined) {
+      printer.line('## Commands');
+      printer.blank();
+    } else {
+      printer.line(`## ${group}`);
+      printer.blank();
+      printer.line(`Addressed as \`${options.name} ${groupSlug(group)} <command>\`.`);
+      printer.blank();
+    }
+    for (const command of inGroup) writeCommand(printer, command, options);
+  }
+  return (
+    printer
+      .toString()
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd() + '\n'
+  );
+}

package/lib/eject-assets/generators/cli/engine-source.ts

@@ -0,0 +1,21 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+// The cli engine's embeddable source, snapshotted at prepare time (see
+// scripts/generate-runtime-sources.mjs).
+
+import {
+  RUNTIME_SOURCES,
+  RUNTIME_SOURCES_STRIPPED,
+} from '@redocly/client-generator/runtime-sources';
+
+/** The cli engine (`runCli` + types) stripped for embedding into `<stem>.cli.ts`. */
+export function embedCliRuntime(): string {
+  return RUNTIME_SOURCES_STRIPPED['cli.ts'];
+}
+
+/** The cli engine RAW, for `runtime: 'module'` (written as `runtime/cli.ts`). */
+export function cliRuntimeSource(): string {
+  return RUNTIME_SOURCES['cli.ts'];
+}

package/lib/eject-assets/generators/cli/index.ts

@@ -0,0 +1,90 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+import {
+  type CodeSample,
+  type Generator,
+  groupSlug,
+  type OperationModel,
+  type SampleContext,
+} from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderCliDocs } from './docs.ts';
+import { cliRuntimeSource } from './engine-source.ts';
+import { cliAuthSchemes, commandData, renderCliModule } from './render.ts';
+
+/**
+ * The cli generator: a bin-ready `<stem>.cli.ts` — a zero-dependency, typed
+ * command-line interface over the sibling client (typed flags, `--json`
+ * bodies, env auth, `--page-all`, SSE/blob output, a documented exit-code
+ * contract). Requires `typescript` (throw mode); wires zod validation when co-selected.
+ */
+export const cliGenerator: Generator = ({ model, output, banner, emit, selected, pagination }) => {
+  const content = renderCliModule(model, {
+    stem: output.stem,
+    importExt: emit.importExt ?? 'js',
+    zodSelected: selected?.includes('zod') ?? false,
+    pagination,
+    argsStyle: emit.argsStyle ?? 'grouped',
+    runtime: emit.runtime ?? 'inline',
+  });
+  const entry = { path: join(output.dir, `${output.stem}.cli.ts`), content };
+  if (emit.runtime !== 'module') return [entry];
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  return [
+    entry,
+    {
+      path: join(output.dir, 'runtime', 'cli.ts'),
+      content: `${header}\n\n${cliRuntimeSource().trim()}\n`,
+    },
+  ];
+};
+
+/**
+ * The CLI's own reference page, written when `client.docs` is on: the usage line, the
+ * global flags, the credential variables, the exit codes, and one section per command.
+ * It renders from `commandData` — the same table `runCli` dispatches on — so the page
+ * cannot describe a tool other than the one beside it.
+ */
+export const cliDocs: Generator = ({ model, output, emit, pagination }) => {
+  const content = renderCliDocs(commandData(model, { pagination }), {
+    title: `${model.title} command-line reference`,
+    frontmatter: emit.docsFrontmatter === true,
+    name: output.stem,
+    schemes: cliAuthSchemes(model),
+  });
+  return [{ path: join(output.dir, `${output.stem}.cli.md`), content }];
+};
+
+/** One shell invocation per operation — feeds `x-codeSamples` for docs. */
+export function cliSample(op: OperationModel, ctx: SampleContext): CodeSample | undefined {
+  const command = commandData(ctx.model, { pagination: ctx.pagination }).find(
+    (candidate) => candidate.name === op.name
+  );
+  if (command === undefined) return undefined;
+  const words = [
+    'client',
+    ...(command.group ? [groupSlug(command.group)] : []),
+    command.name,
+    ...command.positionals.map((positional) => `<${positional.name}>`),
+    ...command.flags.filter((flag) => flag.required).map((flag) => `--${flag.name} <${flag.type}>`),
+    ...(command.body ? ["--json '<json>'"] : []),
+  ];
+  return {
+    lang: 'shell',
+    label: 'CLI',
+    source: `npx tsx client.cli.ts ${words.slice(1).join(' ')}\n`,
+  };
+}
+
+export default {
+  name: 'cli',
+  run: cliGenerator,
+  sample: cliSample,
+  docs: cliDocs,
+  requires: ["typescript","zod"],
+  errorModes: ["throw"],
+  requiresGenerator: '^0.4.0',
+};