@redocly/cli 2.47.0 → 2.49.0

package/lib/chunks/ZOUQBK53.js

@@ -0,0 +1,14 @@
+import { createRequire as __createRequire } from 'node:module';
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __pathDirname } from 'node:path';
+const require = __createRequire(import.meta.url);
+var __filename = __fileURLToPath(import.meta.url);
+var __dirname = __pathDirname(__filename);
+import{a as S,b as f}from"./REFX2EKS.js";import{a as N}from"./UKSQ7B5H.js";import{b as E,c as U,d as j,e as K,f as J,g as z,h as Q}from"./4I2OVMBJ.js";import{a as M}from"./PFYPTG4G.js";import{b as O,c as H,d as w,e as B,g as F,h as G,i as T,j as W,k as _,n as A}from"./HJYFWIVE.js";var c=new S,y=H.go;function V(e){if(e===void 0)return"client";if(!/^[a-z_][a-z0-9_]*$/.test(e)||y.has(e))throw new M(`goPackage "${e}" is not a valid Go package name: use lowercase letters, digits, and underscores, don't start with a digit, and avoid Go keywords.`);return e}function R(e){let t=new Set,n=[];for(let r of e.services)for(let o of r.operations){let a=f(o.name),s=2;for(;t.has(a);)a=`${f(o.name)}${s++}`;t.add(a),n.push({op:o,ident:a})}return n}function oe(e){return J(e).map(n=>n.kind==="literal"?c.string(n.value):w(n.name,{style:"camel",reserved:y})).join(" + ")}function X(e,t){let n=t.servers??[];if(n.length===0)return;let r=new Set;n.forEach((o,a)=>{let s=`${f(o.description??`server${a+1}`)}URL`;r.has(s)&&(s=`${s}${a+1}`),r.add(s);let i=o.variables.map(l=>`${w(l.name,{style:"camel",reserved:y})} string`),u=o.variables.map(l=>`${w(l.name,{style:"camel",reserved:y})} default: ${c.string(l.default)}`).join(", ");e.line(`// ${s} returns the ${c.string(o.description??o.url)} base URL${u===""?".":` (${u}).`}`),e.block(`func ${s}(${i.join(", ")}) string {`,()=>{e.line(`return ${oe(o)}`)},"}"),e.blank()})}function Y(e,t){let n=z(e,t).map(r=>r.map(o=>o.kind==="apiKey"?`{Scheme: ${c.string(o.scheme)}, Kind: "apiKey", Name: ${c.string(o.name)}, In: ${c.string(o.in)}}`:`{Scheme: ${c.string(o.scheme)}, Kind: ${c.string(o.kind)}}`));if(n.length!==0)return`[][]SecuritySpec{${n.map(r=>`{${r.join(", ")}}`).join(", ")}}`}function Z(e){return`&PaginationSpec{${[`Style: ${c.string(e.style)}`,...e.param!==void 0?[`Param: ${c.string(e.param)}`]:[],...e.nextCursor!==void 0?[`NextCursor: ${c.string(e.nextCursor)}`]:[],...e.hasMore!==void 0?[`HasMore: ${c.string(e.hasMore)}`]:[],...e.limitParam!==void 0?[`LimitParam: ${c.string(e.limitParam)}`]:[],...e.items!==void 0?[`Items: ${c.string(e.items)}`]:[]].join(", ")}}`}function g(e,t="string"){if(T(e)){let n=g(W(e),t);return n.startsWith("*")||n==="any"?n:`*${n}`}switch(e.kind){case"scalar":if(t==="Date"&&e.scalar==="string"){if(e.metadata?.format==="date-time")return"time.Time";if(e.metadata?.format==="date")return"Date"}return{string:"string",integer:"int64",number:"float64",boolean:"bool"}[e.scalar];case"array":return`[]${g(e.items,t)}`;case"record":return`map[string]${g(e.value,t)}`;case"ref":return f(e.name);case"literal":return typeof e.value=="string"?"string":typeof e.value=="boolean"?"bool":"float64";case"enum":return{string:"string",integer:"int64",number:"float64",boolean:"bool"}[e.scalar];case"omit":return f(e.base);case"union":case"null":case"object":case"intersection":case"unknown":return"any"}}function ae(e,t,n,r,o){e.doc(f(t),o),e.block(`type ${f(t)} struct {`,()=>{for(let a of n){let s=f(a.name),i=g(a.schema,r),u=`\`json:"${a.name}"\``;a.required||(!i.startsWith("*")&&!i.startsWith("[]")&&!i.startsWith("map[")&&i!=="any"&&(i=`*${i}`),u=`\`json:"${a.name},omitempty"\``),e.line(`${s} ${i} ${u}`)}},"}"),e.blank()}function D(e,t="string"){let n=new S;n.line("package client"),n.blank(),e.schemas.some(({schema:a})=>G(a,e)!==void 0)&&(n.line('import "encoding/json"'),n.blank());let o=se(e,t);return t==="Date"&&o.includes("time.Time")&&(n.line('import "time"'),n.blank()),n.line(o),n.toString()}function se(e,t){let n=new S;for(let{name:r,schema:o}of e.schemas){let a=_(o);if(a!==void 0){let i=a.scalar==="string"?"string":"int64";n.doc(f(r),o.description),n.line(`type ${f(r)} ${i}`),n.blank(),n.block("const (",()=>{let u=new Set;a.values.forEach(l=>{let d=O.pascal(String(l))||"Value",m="";for(let k=2;u.has(d+m);k++)m=String(k);u.add(d+m);let p=f(r)+d+m;n.line(`${p} ${f(r)} = ${c.literal(l)}`)})},")"),n.blank();continue}if(o.kind==="object"||o.kind==="intersection"){let i=F(o,e);if(i!==void 0){ae(n,r,i.properties,t,i.description??o.description);continue}}let s=G(o,e);if(s!==void 0){let i=f(r),u=s.cases.map(l=>`${l.value} -> ${f(l.schemaName)}`).join(", ");n.line(`// ${i} is a discriminated union ("${s.property}"): ${u}.`),n.line(`type ${i} = any`),n.blank(),n.line(`// Unmarshal${i} decodes into the member selected by "${s.property}".`),n.block(`func Unmarshal${i}(data []byte) (${i}, error) {`,()=>{n.block("var probe struct {",()=>{n.line(`Discriminant string \`json:"${s.property}"\``)},"}"),n.block("if err := json.Unmarshal(data, &probe); err != nil {",()=>{n.line("return nil, err")},"}"),n.line("switch probe.Discriminant {");for(let l of s.cases)n.block(`case ${c.string(l.value)}:`,()=>{n.line(`var value ${f(l.schemaName)}`),n.line("err := json.Unmarshal(data, &value)"),n.line("return value, err")});n.line("}"),n.line("var fallback any"),n.line("err := json.Unmarshal(data, &fallback)"),n.line("return fallback, err")},"}"),n.blank();continue}n.doc(f(r),o.description),n.line(`type ${f(r)} = ${g(o,t)}`),n.blank()}return n.toString()}function q(e,t){if(t==="string")return e;let n=e.startsWith("*")?`(${e})`:e;return t==="time.Time"?`${n}.Format(time.RFC3339)`:t==="Date"?`${n}.Format("2006-01-02")`:t==="int64"?`strconv.FormatInt(${e}, 10)`:t==="float64"?`strconv.FormatFloat(${e}, 'f', -1, 64)`:t==="bool"?`strconv.FormatBool(${e})`:`fmt.Sprint(${e})`}var ie=["c","ctx","body","params","out","op"];function I(e,t){let n=B(e.pathParams.map(r=>r.name),{style:"camel",reserved:y,taken:ie});return e.pathParams.map((r,o)=>({param:r,go:n[o],type:g(r.schema,t)}))}function le(e,t){let n=new Set;return(e.successResponseHeaders??[]).map(r=>{let o=f(r.name),a=o,s=2;for(;n.has(a);)a=`${o}${s++}`;n.add(a);let i=A(r.schema,t),u={integer:{goType:"*int64",helper:"headerInt64"},number:{goType:"*float64",helper:"headerFloat64"},boolean:{goType:"*bool",helper:"headerBool"},string:{goType:"*string",helper:"headerString"}}[i];return{field:a,name:r.name,...u}})}function L(e,t,n,r,o,a=!1){let s=I(t,r),i=t.queryParams.length>0,u=U(t),l=u===void 0?void 0:g(u,r),d=a?le(t,o):[];a&&(e.line(`// ${n}Headers carries the declared response headers of ${n}WithHeaders (nil when absent or unparsable).`),e.block(`type ${n}Headers struct {`,()=>{for(let $ of d)e.line(`${$.field} ${$.goType}`)},"}"),e.blank());let m=["ctx context.Context",...s.map(({go:$,type:v})=>`${$} ${v}`),...t.requestBody?[`body ${g(t.requestBody.schema,r)}`]:[],...i?[`params *${n}Params`]:[]],p=j(t),k=a?l===void 0?`(${n}Headers, error)`:`(${l}, ${n}Headers, error)`:p!==void 0?"func(yield func(ServerSentEvent, error) bool)":l===void 0?"error":`(${l}, error)`,b=$=>a?l===void 0?`return headers, ${$}`:`return out, headers, ${$}`:l===void 0?`return ${$}`:`return out, ${$}`,P=a?`${n}WithHeaders`:n;e.doc(P,a?`Like ${n}, also returning the declared response headers.`:t.summary),e.block(`func (c *Client) ${P}(${m.join(", ")}) ${k} {`,()=>{p===void 0&&l!==void 0&&e.line(`var out ${l}`),a&&e.line(`var headers ${n}Headers`),e.line(`op := operations[${c.string(t.specName??t.name)}]`),e.line("authHeaders, query := resolveAuth(op.Security, c.config.Auth)"),i&&e.block("if params != nil {",()=>{for(let h of t.queryParams){let x=f(h.name);e.block(`if params.${x} != nil {`,()=>{if(h.schema.kind==="array"){let C=g(h.schema.items,r);e.block(`for _, item := range *params.${x} {`,()=>{e.line(`query.Add(${c.string(h.name)}, ${q("item",C)})`)},"}")}else e.line(`query.Set(${c.string(h.name)}, ${q(`*params.${x}`,g(h.schema,r))})`)},"}")}},"}");let $=s.map(({param:h,go:x,type:C})=>`${c.string(h.name)}: ${q(x,C)}`).join(", ");if(e.line(`requestURL := buildURL(c.config.ServerURL, op.Path, map[string]string{${$}})`),p!==void 0){e.block("open := func(extraHeaders map[string]string) (*http.Response, error) {",()=>{e.line("merged := map[string]string{}"),e.block("for key, value := range authHeaders {",()=>{e.line("merged[key] = value")},"}"),e.block("for key, value := range extraHeaders {",()=>{e.line("merged[key] = value")},"}"),e.line("return send(ctx, &c.config, requestSpec{OperationID: op.ID, Method: op.Method, URL: requestURL, Headers: merged, Query: query})")},"}"),e.line(`return iterSSE(open, ${p.schema!==void 0&&p.schema.kind!=="unknown"})`);return}let v=["OperationID: op.ID","Method: op.Method","URL: requestURL","Headers: authHeaders","Query: query"];if(t.requestBody&&K(t)?(e.line("contentType, reader, err := toMultipart(body)"),e.block("if err != nil {",()=>{e.line(b("err"))},"}"),v.push("Body: reader"),v.push("ContentType: contentType")):t.requestBody&&(e.line("payload, err := json.Marshal(body)"),e.block("if err != nil {",()=>{e.line(b("err"))},"}"),v.push("Body: bytes.NewReader(payload)"),v.push(`ContentType: ${c.string(t.requestBody.contentType)}`)),e.line(`resp, err := send(ctx, &c.config, requestSpec{${v.join(", ")}})`),e.block("if err != nil {",()=>{e.line(b("err"))},"}"),e.block("if resp.StatusCode >= 400 {",()=>{e.line(b("apiErrorFrom(resp, requestURL)"))},"}"),a){e.block(`if err := decodeJSON(resp, ${l===void 0?"nil":"&out"}); err != nil {`,()=>{e.line(b("err"))},"}");for(let h of d)e.line(`headers.${h.field} = ${h.helper}(resp.Header, ${c.string(h.name)})`);e.line(l===void 0?"return headers, nil":"return out, headers, nil")}else l===void 0?e.line("return decodeJSON(resp, nil)"):(e.block("if err := decodeJSON(resp, &out); err != nil {",()=>{e.line("return out, err")},"}"),e.line("return out, nil"))},"}"),e.blank()}function ee(e,t,n,r,o,a){let s=I(t,r),i=t.queryParams.length>0,u=["ctx context.Context",...s.map(({go:d,type:m})=>`${d} ${m}`),...i?[`params *${n}Params`]:[]].join(", "),l=()=>{e.line(`op := operations[${c.string(t.specName??t.name)}]`),e.line("base := url.Values{}"),i&&e.block("if params != nil {",()=>{for(let d of t.queryParams){let m=f(d.name);e.block(`if params.${m} != nil {`,()=>{e.line(`base.Set(${c.string(d.name)}, ${q(`*params.${m}`,g(d.schema,r))})`)},"}")}},"}"),e.block("call := func(pageParams url.Values) (any, *http.Response, error) {",()=>{e.line("authHeaders, query := resolveAuth(op.Security, c.config.Auth)"),e.block("for key, values := range pageParams {",()=>{e.block("for _, value := range values {",()=>{e.line("query.Set(key, value)")},"}")},"}");let d=s.map(({param:m,go:p,type:k})=>`${c.string(m.name)}: ${q(p,k)}`).join(", ");e.line(`requestURL := buildURL(c.config.ServerURL, op.Path, map[string]string{${d}})`),e.line("resp, err := send(ctx, &c.config, requestSpec{OperationID: op.ID, Method: op.Method, URL: requestURL, Headers: authHeaders, Query: query})"),e.block("if err != nil {",()=>{e.line("return nil, nil, err")},"}"),e.block("if resp.StatusCode >= 400 {",()=>{e.line("return nil, resp, apiErrorFrom(resp, requestURL)")},"}"),e.line("var raw any"),e.block("if err := decodeJSON(resp, &raw); err != nil {",()=>{e.line("return nil, resp, err")},"}"),e.line("return raw, resp, nil")},"}"),e.line("pages := iterPages(call, *op.Pagination, base)")};e.line(`// ${n}Pages iterates ${n} response pages; use with \`for page, err := range\`.`),e.block(`func (c *Client) ${n}Pages(${u}) func(yield func(${o}, error) bool) {`,()=>{l(),e.block(`return func(yield func(${o}, error) bool) {`,()=>{e.block("pages(func(raw any, err error) bool {",()=>{e.line(`var page ${o}`),e.block("if err == nil {",()=>{e.line("err = reencode(raw, &page)")},"}"),e.line("return yield(page, err)")},"})")},"}")},"}"),e.blank(),e.line(`// ${n}Items iterates the items of every ${n} page.`),e.block(`func (c *Client) ${n}Items(${u}) func(yield func(${a}, error) bool) {`,()=>{l(),e.block(`return func(yield func(${a}, error) bool) {`,()=>{e.block("pages(func(raw any, err error) bool {",()=>{e.block("if err != nil {",()=>{e.line(`var zero ${a}`),e.line("return yield(zero, err)")},"}"),e.line("pageItems, _ := resolvePointer(raw, op.Pagination.Items).([]any)"),e.block("for _, item := range pageItems {",()=>{e.line(`var typed ${a}`),e.block("if err := reencode(item, &typed); err != nil {",()=>{e.line("return yield(typed, err)")},"}"),e.block("if !yield(typed, nil) {",()=>{e.line("return false")},"}")},"}"),e.line("return true")},"})")},"}")},"}"),e.blank()}function ne(e){let t=e.split(`
+`),n=[],r=!1;for(let o of t)if(!o.startsWith("package ")){if(o.startsWith("import (")){r=!0;continue}if(r){o.startsWith(")")&&(r=!1);continue}o.startsWith("import ")||n.push(o)}return n.join(`
+`).trim()}var te=["bytes","context","encoding/base64","encoding/json","errors","fmt","io","math/rand","mime/multipart","net/http","net/url","strconv","strings","time"];function re(e,t,n,r,o,a){e.line(ne(D(t,r))),e.blank(),X(e,t),a&&(e.line("// \u2500\u2500\u2500 Embedded runtime (@redocly/client-generator go runtime) \u2500\u2500\u2500"),e.line(ne(N)),e.blank()),e.block("type operationMeta struct {",()=>{e.line("ID         string"),e.line("Method     string"),e.line("Path       string"),e.line("Security   [][]SecuritySpec"),e.line("Pagination *PaginationSpec")},"}"),e.blank(),e.block("var operations = map[string]operationMeta{",()=>{for(let{op:s,ident:i}of R(t)){let u=s.specName??s.name,l=Y(s,t),d=o.get(i),m=[`ID: ${c.string(u)}`,`Method: ${c.string(s.method.toUpperCase())}`,`Path: ${c.string(s.path)}`,...l!==void 0?[`Security: ${l}`]:[],...d!==void 0?[`Pagination: ${Z(d)}`]:[]];e.line(`${c.string(u)}: {${m.join(", ")}},`)}},"}"),e.blank();for(let{op:s,ident:i}of R(t))s.queryParams.length!==0&&(e.block(`type ${i}Params struct {`,()=>{for(let u of s.queryParams){let l=g(u.schema,r);e.line(`${f(u.name)} ${l.startsWith("*")?l:`*${l}`}`)}},"}"),e.blank());e.doc("Client",`Client for ${t.title} (${t.version}).`),e.block("type Client struct {",()=>{e.line("config Config")},"}"),e.blank(),e.block("func New(config Config) *Client {",()=>{e.block('if config.ServerURL == "" {',()=>{e.line(`config.ServerURL = ${c.string(n.serverUrl??t.serverUrl??"")}`)},"}"),e.line("return &Client{config: config}")},"}"),e.blank();for(let{op:s,ident:i}of R(t)){L(e,s,i,r),j(s)===void 0&&(s.successResponseHeaders?.length??0)>0&&L(e,s,i,r,t,!0);let u=o.get(i);if(u===void 0)continue;let l=U(s),d=l===void 0?"any":g(l,r),m=Q(l,u.items,t);ee(e,s,i,r,d,m===void 0?"any":g(m,r))}}var ze=({model:e,output:t,banner:n,emit:r,pagination:o})=>{let a=new S,s=r.dateType??"string",i=V(r.goPackage),u=new Map;for(let{op:b,ident:P}of R(e)){let $=o?.get(b.name)?.spec;$!==void 0&&u.set(P,$)}a.line(`// Code generated by @redocly/client-generator (go) from "${e.title}" ${e.version}. DO NOT EDIT.`),a.line("// Regenerate with `redocly generate-client`. Standard library only \u2014 zero dependencies."),a.line(`package ${i}`),a.blank();let l=r.runtime!=="module",d=l?te:(()=>{let b=new S;re(b,e,r,s,u,!1);let P=b.toString();return te.filter($=>new RegExp(`\\b${$.split("/").pop()}\\.`).test(P))})();a.block("import (",()=>{for(let b of d)a.line(c.string(b))},")"),a.blank(),re(a,e,r,s,u,l);let m={path:t.path.replace(/\.[^.\\/]+$/,".go"),content:a.toString()};if(l)return[m];let p=n.map(b=>`// ${b}`).join(`
+`),k=N.replace(/^package .*$/m,`package ${i}`);return[m,{path:m.path.replace(/[^\\/]+$/,"runtime.go"),content:`${p}
+${k.trimEnd()}
+`}]};function ce(e,t){let n=t.emit.dateType??"string",r=t.emit.goPackage??"client",o=R(t.model).find(u=>u.op.name===e.name)?.ident??f(e.name),a=["ctx",...e.pathParams.map(u=>`"<${w(u.name,{style:"camel",reserved:y})}>"`),...e.requestBody?[`${g(e.requestBody.schema,n)}{ /* \u2026 */ }`]:[],...e.queryParams.length>0?["nil"]:[]],s=`client.${o}(${a.join(", ")})`,i=j(e)!==void 0?`stream := ${s}`:U(e)===void 0?`err := ${s}`:`result, err := ${s}`;return{lang:"go",label:"Go SDK",source:`client := ${r}.New(${r}.Config{})
+${i}
+`}}var Qe=({model:e,output:t,emit:n,pagination:r})=>[{path:t.path.replace(/\.[^.\\/]+$/,".go.md"),content:E(e,{title:`${e.title} Go SDK reference`,frontmatter:n.docsFrontmatter===!0,language:{name:"go",label:"Go",fence:"go",requires:"The SDK needs the standard library only."},sample:o=>ce(o,{model:e,emit:n,outputPath:t.path}),paginated:new Set(r?.keys()??[])})}];export{g as a,D as b,ze as c,ce as d,Qe as e};

package/lib/chunks/ZXKOHMC6.js

@@ -0,0 +1,177 @@
+import { createRequire as __createRequire } from 'node:module';
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __pathDirname } from 'node:path';
+const require = __createRequire(import.meta.url);
+var __filename = __fileURLToPath(import.meta.url);
+var __dirname = __pathDirname(__filename);
+import"./4I2OVMBJ.js";import{a as h}from"./ZMCRMR2V.js";import"./PFYPTG4G.js";import"./HJ36YGCI.js";import"./NEWT5A6S.js";import{e as g,h as p,k as y}from"./NB54XRRU.js";import"./HJYFWIVE.js";import"./RFWIIJFG.js";import{join as M}from"node:path";var a="    ";function f(e){return`${y(e)}Schema`}var x=new Map;function u(e,r=x,t=""){return k(w(e,r,t),e)}function w(e,r,t){switch(e.kind){case"scalar":return S(e.scalar,e.metadata);case"object":return b(e.properties,r,t);case"array":return`z.array(${u(e.items,r,t)})`;case"record":return`z.record(z.string(), ${u(e.value,r,t)})`;case"ref":return`z.lazy(() => ${f(e.name)})`;case"literal":return`z.literal(${p(e.value)})`;case"enum":return z(e.values);case"union":return E(e.members,r,t);case"intersection":return e.members.map(n=>u(n,r,t)).reduce((n,o)=>`${n}.and(${o})`);case"null":return"z.null()";case"unknown":return"z.unknown()";case"omit":return q(e.base,e.keys,r,t)}}function S(e,r){switch(e){case"string":return r?.format==="binary"?"z.instanceof(Blob)":"z.string()";case"integer":return"z.number().int()";case"number":return"z.number()";case"boolean":return"z.boolean()"}}function c(e){return g(e)===e?e:JSON.stringify(e)}function b(e,r,t){if(e.length===0)return"z.object({})";let n=t+a;return`z.object({
+${e.map((s,i)=>{let d=u(s.schema,r,n),l=s.required?d:`${d}.optional()`,v=i===e.length-1?"":",";return`${n}${c(s.name)}: ${l}${v}`}).join(`
+`)}
+${t}})`}function z(e){return e.every(r=>typeof r=="string")?`z.enum([${e.map(r=>JSON.stringify(r)).join(", ")}])`:`z.union([${e.map(r=>`z.literal(${p(r)})`).join(", ")}])`}function E(e,r,t){let n=e.map(o=>u(o,r,t));return n.length===1?n[0]:`z.union([${n.join(", ")}])`}function q(e,r,t,n){let o=t.get(e);if(o&&o.kind!=="object")return u(m(o,r,t,new Set([e])),t,n);let s=r.map(i=>`${c(i)}: true`).join(", ");return`${f(e)}.omit({ ${s} })`}function m(e,r,t,n){switch(e.kind){case"object":return{...e,properties:e.properties.filter(o=>!r.includes(o.name))};case"union":case"intersection":return{...e,members:e.members.map(o=>m(o,r,t,n))};case"ref":{if(n.has(e.name))return e;let o=t.get(e.name);if(!o)return e;if(o.kind==="object"){let s=r.filter(i=>o.properties.some(d=>d.name===i));return s.length>0?{kind:"omit",base:e.name,keys:s}:e}return m(o,r,t,new Set([...n,e.name]))}default:return e}}function k(e,r){let t=r.metadata;if(!t)return e;let n=e;return r.kind==="scalar"&&r.scalar==="string"&&(t.minLength!==void 0&&(n=`${n}.min(${t.minLength})`),t.maxLength!==void 0&&(n=`${n}.max(${t.maxLength})`),t.pattern!==void 0&&(n=`${n}.regex(new RegExp(${JSON.stringify(t.pattern)}))`)),r.kind==="scalar"&&(r.scalar==="number"||r.scalar==="integer")&&(t.minimum!==void 0&&(n=`${n}.min(${t.minimum})`),t.maximum!==void 0&&(n=`${n}.max(${t.maximum})`),t.exclusiveMinimum!==void 0&&(n=`${n}.gt(${t.exclusiveMinimum})`),t.exclusiveMaximum!==void 0&&(n=`${n}.lt(${t.exclusiveMaximum})`)),r.kind==="array"&&(t.minItems!==void 0&&(n=`${n}.min(${t.minItems})`),t.maxItems!==void 0&&(n=`${n}.max(${t.maxItems})`)),n}function j(e,r){let t=[];for(let n of h(e.services)){if(n.sse!==void 0)continue;let o=n.requestBody,s=o&&o.contentType.toLowerCase().includes("json")?u(o.schema,r,a):void 0,i=n.successResponses.find(l=>l.contentType.toLowerCase().includes("json")),d=i?u(i.schema,r,a):void 0;!s&&!d||t.push({name:n.specName??n.name,request:s,response:d})}return t}function Z(e){let r=e.flatMap(n=>[`${a}${c(n.name)}: {`,...n.request?[`${a}${a}request: z.ZodType;`]:[],...n.response?[`${a}${a}response: z.ZodType;`]:[],`${a}};`]),t=e.map((n,o)=>{let s=[...n.request?[`request: ${n.request}`]:[],...n.response?[`response: ${n.response}`]:[]].join(", "),i=o===e.length-1?"":",";return`${a}${c(n.name)}: { ${s} }${i}`});return["/**"," * Request/response validators by operationId \u2014 powers `zodValidation`, or import one directly."," */","export const operationSchemas: {",...r,"} = {",...t,"};"].join(`
+`)}var I=`/** \`request\`/\`response\` validators for one operation (an absent side is not validated). */
+export type OperationSchemaSet = { request?: z.ZodType; response?: z.ZodType };
+
+const schemaIndex: Partial<Record<string, OperationSchemaSet>> = operationSchemas;
+
+/** One flattened validation problem: the full nested path and a short preview of the value. */
+export type ZodViolation = { path: string; message: string; received: string };
+
+/** A request or response payload failed validation. Requests throw it; response handling is configurable. */
+export class ZodValidationError extends Error {
+    // Declared and assigned in the body, NOT as constructor parameter properties: those
+    // need a transform, so they break \`node --experimental-strip-types\` for anything
+    // importing this module (the generated CLI runs that way).
+    readonly operationId: string;
+    readonly direction: "request" | "response";
+    readonly issues: z.ZodError["issues"];
+    readonly violations: ZodViolation[];
+
+    constructor(
+        operationId: string,
+        direction: "request" | "response",
+        issues: z.ZodError["issues"],
+        violations: ZodViolation[]
+    ) {
+        const detail = violations
+            .slice(0, 5)
+            .map((violation) => \`\${violation.path || "(root)"}: \${violation.message} (received \${violation.received})\`)
+            .join("; ");
+        const more = violations.length > 5 ? \`; \u2026and \${violations.length - 5} more\` : "";
+        super(\`\${direction === "request" ? "Request" : "Response"} validation failed for operation "\${operationId}": \${detail}\${more}\`);
+        this.operationId = operationId;
+        this.direction = direction;
+        this.issues = issues;
+        this.violations = violations;
+        this.name = "ZodValidationError";
+    }
+}
+
+// Flatten zod issues into leaf violations. Union branches (zod 3 \`unionErrors\`, zod 4
+// nested \`errors\`) are recursed into, so the message names the actual failing fields
+// instead of just the union root ("Invalid input").
+function flattenIssues(
+    issues: z.ZodError["issues"],
+    value: unknown,
+    base: PropertyKey[] = []
+): ZodViolation[] {
+    const violations: ZodViolation[] = [];
+    for (const issue of issues) {
+        const path = [...base, ...issue.path];
+        const nested = nestedIssueLists(issue);
+        if (nested.length > 0) {
+            for (const sub of nested) violations.push(...flattenIssues(sub, value, path));
+        } else {
+            violations.push({
+                path: path.map(String).join("."),
+                message: issue.message,
+                received: preview(valueAt(value, path)),
+            });
+        }
+    }
+    return violations;
+}
+
+/** The nested issue lists of a union-ish issue, across zod 3 (\`unionErrors\`) and zod 4 (\`errors\`). */
+function nestedIssueLists(issue: unknown): Array<z.ZodError["issues"]> {
+    const candidate = issue as {
+        unionErrors?: Array<{ issues: z.ZodError["issues"] }>;
+        errors?: Array<z.ZodError["issues"]>;
+    };
+    if (Array.isArray(candidate.unionErrors)) return candidate.unionErrors.map((error) => error.issues);
+    if (Array.isArray(candidate.errors)) return candidate.errors;
+    return [];
+}
+
+function valueAt(value: unknown, path: PropertyKey[]): unknown {
+    let current = value;
+    for (const key of path) {
+        if (current === null || typeof current !== "object") return undefined;
+        current = (current as Record<PropertyKey, unknown>)[key];
+    }
+    return current;
+}
+
+/** A short single-line preview of the offending value. NOTE: validation output can surface
+ *  payload data \u2014 route \`onViolation\` to a scrubbed logger when responses may carry secrets. */
+function preview(value: unknown): string {
+    let text: string;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    } catch {
+        text = String(value);
+    }
+    return text.length > 80 ? \`\${text.slice(0, 77)}\u2026\` : text;
+}
+
+export type ZodValidationOptions = {
+    /** Validate request bodies before any network call; a failure THROWS (it is the caller's own bug). Default: true. */
+    request?: boolean;
+    /** Replace the outgoing body with the parsed result, dropping keys the schema does not declare
+     *  (for strict-DTO servers that 400 on excess properties). Runs request validation. Default: false. */
+    stripRequestBodies?: boolean;
+    /** Response drift handling: \`"warn"\` (default) reports via \`onViolation\` and lets the call
+     *  succeed \u2014 a server drifting from its description should not crash the consumer;
+     *  \`"throw"\` fails the call (even on result-mode clients); \`false\` skips response validation. */
+    response?: "warn" | "throw" | false;
+    /** Sink for \`"warn"\` mode. Default: \`console.warn\` with the error message. */
+    onViolation?: (error: ZodValidationError) => void;
+};
+
+/**
+ * Schema-validation middleware for the generated client: \`use(zodValidation())\`.
+ * Request bodies are validated before any network call and throw on failure; successful
+ * JSON responses are validated against the operation's response schema and WARN by
+ * default (see \`ZodValidationOptions.response\`). Operations without a schema pass
+ * through untouched. Payloads are never mutated unless \`stripRequestBodies\` is set.
+ */
+export function zodValidation(options: ZodValidationOptions = {}) {
+    const { request = true, stripRequestBodies = false, response = "warn", onViolation } = options;
+    const report = onViolation ?? ((error: ZodValidationError) => console.warn(error.message));
+    return {
+        onRequest(context: { body?: unknown; operation: { id: string } }): void {
+            if ((!request && !stripRequestBodies) || context.body === undefined) return;
+            const schema = schemaIndex[context.operation.id]?.request;
+            if (!schema) return;
+            const result = schema.safeParse(context.body);
+            if (!result.success) {
+                throw new ZodValidationError(
+                    context.operation.id,
+                    "request",
+                    result.error.issues,
+                    flattenIssues(result.error.issues, context.body)
+                );
+            }
+            // zod object schemas drop undeclared keys during parsing, so the parsed value
+            // IS the declared shape (intersections keep their own zod semantics).
+            if (stripRequestBodies) context.body = result.data;
+        },
+        async onResponse(incoming: Response, context: { operation: { id: string } }): Promise<void> {
+            if (response === false || !incoming.ok) return;
+            const schema = schemaIndex[context.operation.id]?.response;
+            if (!schema) return;
+            const contentType = (incoming.headers.get("content-type") ?? "").toLowerCase();
+            if (!contentType.includes("json")) return;
+            const payload: unknown = await incoming.clone().json();
+            const result = schema.safeParse(payload);
+            if (!result.success) {
+                const error = new ZodValidationError(
+                    context.operation.id,
+                    "response",
+                    result.error.issues,
+                    flattenIssues(result.error.issues, payload)
+                );
+                if (response === "throw") throw error;
+                report(error);
+            }
+        },
+    };
+}`;function $(e){let r=new Map(e.schemas.map(o=>[o.name,o.schema])),t=j(e,r);if(e.schemas.length===0&&t.length===0)return"";let n=['import { z } from "zod";',...e.schemas.map(o=>`export const ${f(o.name)} = ${u(o.schema,r)};`)];return t.length===0?n.join(`
+
+`):(n.push(Z(t)),`${n.join(`
+
+`)}
+${I}
+`)}var T=({model:e,output:r,banner:t})=>{let n=$(e);if(n==="")return[];let o=t.map(s=>`// ${s}`).join(`
+`);return[{path:M(r.dir,`${r.stem}.zod.ts`),content:`${o}
+
+${n}`}]};export{T as zodGenerator};

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.1 — 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.1 — 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'];
+}