@lovrozagar/honey-clients 0.0.0 → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovro Žagar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @lovrozagar/honey-clients
+
+Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a Go command-line client and an MCP server from an OpenAPI
+3.x document, or straight from a [`@lovrozagar/honey`](https://www.npmjs.com/package/@lovrozagar/honey) app.
+
+## Install
+
+```sh
+npm install --save-dev @lovrozagar/honey-clients
+```
+
+Node 22.12 or later, or Bun 1.3 or later.
+
+## Start
+
+From a document:
+
+```sh
+npx honey-clients generate --spec openapi.json --target ts --target python --out generated
+```
+
+From a honey app module, with no document written first:
+
+```sh
+npx honey-clients generate --app src/app.ts --target ts --target go --go-module-path github.com/acme/shop/sdk \
+  --out generated
+```
+
+The targets are `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` and `mcp`.
+
+## honey-clients generate
+
+```sh
+honey-clients generate --spec openapi.json --target ts --target cli --out generated \
+  --cli-binary-name shop --cli-module-path github.com/acme/shop --cli-repo acme/shop
+```
+
+- `--spec <file>`: the OpenAPI document, as JSON.
+- `--app <module>[#export]`: a honey app module instead of `--spec` (give one, never both). Its named export, else
+  `app`, else `default`, is the app; its document is made by the app's own `@lovrozagar/honey/openapi`, resolved from
+  the app as at run time, and the module's `openApi` export, if any, is that document's options (`info`,
+  `securitySchemes`, `invalidate`, …, as `generateOpenApi` takes them). Started by `bun run`, the bin hands the load to
+  that Bun, so a module needing Bun's loaders works; a run ends once it has written, whatever the module left open.
+  The module exports the app and serves nothing: one that calls `serve()` as it loads is outside `--app`'s contract,
+  since honey never serves implicitly and has no switch to stop it.
+- `--target <name>`: `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` or `mcp`; repeat it for more than one. Each
+  target's files go under `<out>/<target>`.
+- `--<target>-<option>`: a target's options are its generator's, passed through as given (`--go-module-path`,
+  `--rust-crate-name`, `--cli-binary-name`). Each takes a value. `honey-clients --help` lists them all.
+- `--watch`: generate again on each change of the spec (or the `--app` module), each run in a fresh process.
+
+The `go` and `cli` targets format every Go file they write with gofmt, so they need Go installed. gofmt is found by
+`$GOFMT`, then `$GOROOT/bin/gofmt`, then `gofmt` on `PATH`, then beside the `go` on `PATH`. Without one they refuse.
+
+The `ts` target formats every file it writes with oxfmt, an optional peer: install `oxfmt` beside honey-clients. Without
+it the files go out as emitted, valid TypeScript that is not formatted.
+
+**Stale files are deleted, edited ones kept.** Each `<out>/<target>` keeps `.honey-generated.json`: every file the run
+wrote, with its sha256. A file is rewritten only when its bytes change, through a temp file renamed over it. A
+regeneration deletes a file the last run wrote and this one does not (a `cli` target's old `<name>_cmds.go`, say), unless
+it was edited since: that one is kept and named on stderr. A file the manifest never listed is never deleted, nothing
+outside `<out>/<target>` is touched, and no symlink is followed. Without a manifest, nothing is deleted.
+
+## Documentation
+
+- [Code generation](https://github.com/lovrozagar/honey/blob/main/docs/codegen.md): every target and its options.
+- [Generated clients](https://github.com/lovrozagar/honey/blob/main/docs/client.md) and their
+  [per-language recipes](https://github.com/lovrozagar/honey/blob/main/docs/sdk-recipes.md).
+- [The generated CLI](https://github.com/lovrozagar/honey/blob/main/docs/cli.md),
+  [releasing it](https://github.com/lovrozagar/honey/blob/main/docs/cli-release.md), and
+  [the MCP server](https://github.com/lovrozagar/honey/blob/main/docs/mcp.md).
+
+## License
+
+MIT

package/bin/honey-clients.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// The honey-clients bin (bit 17 phase h). A repository checkout (marked by tsconfig.json, which is not published)
+// runs the TypeScript source, natively on Bun (under the honey-source condition) and through jiti on Node, so a stale
+// dist/ never runs; an installed package runs the compiled JavaScript on any runtime (the tarball ships dist/, not src/).
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { basename } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const isBun = typeof globalThis.Bun !== "undefined"
+const checkout = existsSync(new URL("../tsconfig.json", import.meta.url))
+
+// `bun run` and `bunx` start this file through its node shebang, while what they run is meant for Bun: hand over to
+// the Bun that started us, which they name in npm_execpath. Once, never again in the child.
+function invokingBun() {
+	if (isBun || process.env.HONEY_NO_BUN_HANDOFF === "1") return null
+	if (!process.env.npm_config_user_agent?.startsWith("bun/")) return null
+	const bun = process.env.npm_execpath
+	if (!bun || !/^bunx?(\.exe)?$/.test(basename(bun)) || !existsSync(bun)) return null
+	return bun
+}
+
+// The handoff: Bun runs this file with our arguments and `env` over ours; a signal we get is passed on to it, and we
+// end as it ended, its exit code or the same signal.
+function handOff(bun, env) {
+	// Forwarders first: a signal landing as spawn returns would otherwise end this process by its default action,
+	// orphaning the child. A handler runs from the event loop, after this block, so `child` is set by then.
+	let child
+	const forward = (signal) => child.kill(signal)
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, forward)
+	child = spawn(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+		env: { ...process.env, ...env, HONEY_NO_BUN_HANDOFF: "1" },
+		stdio: "inherit",
+	})
+	child.on("error", (error) => {
+		console.error(`honey-clients: could not start ${bun}: ${error.message}`)
+		process.exit(1)
+	})
+	child.on("exit", (code, signal) => {
+		if (signal) {
+			for (const each of ["SIGINT", "SIGTERM", "SIGHUP"]) process.off(each, forward)
+			process.kill(process.pid, signal)
+			return
+		}
+		process.exit(code ?? 1)
+	})
+}
+
+// A checkout on Bun runs under the honey-source condition: an --app module's checkout core then resolves to its
+// source, never to an unbuilt or stale dist/ (bit 20). Set through BUN_OPTIONS when the caller did not, in the one
+// handoff, so a watch's generation children inherit it; Bun reports BUN_OPTIONS' flags in execArgv, so a Bun started
+// with it never hands off again.
+const SOURCE_CONDITION = "--conditions=honey-source"
+const unconditioned = isBun && checkout && !process.execArgv.includes(SOURCE_CONDITION)
+// The hand-off's backstop: its child carries HONEY_BUN_HANDOFF, the depth of hand-offs before it. A child that would
+// hand off again (the condition set but not in its execArgv) refuses instead of re-running itself without end.
+const handOffDepth = Number(process.env.HONEY_BUN_HANDOFF ?? 0)
+const sourceEnv = checkout
+	? {
+			BUN_OPTIONS: `${process.env.BUN_OPTIONS ?? ""} ${SOURCE_CONDITION}`.trim(),
+			HONEY_BUN_HANDOFF: String(handOffDepth + 1),
+		}
+	: {}
+
+async function entry() {
+	if (checkout) {
+		if (isBun) return import("../src/cli.ts")
+		const { createJiti } = await import("jiti")
+		return createJiti(import.meta.url).import("../src/cli.ts")
+	}
+	try {
+		return await import("../dist/cli.js")
+	} catch (error) {
+		if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.url).endsWith("/dist/cli.js")) {
+			console.error("honey-clients: dist/ is missing from this install. Reinstall it, or run it with Bun.")
+			process.exit(1)
+		}
+		throw error
+	}
+}
+
+const bun = invokingBun()
+if (bun) handOff(bun, sourceEnv)
+else if (unconditioned && handOffDepth >= 1) {
+	console.error("honey-clients: Bun hand-off loop: --conditions=honey-source not visible after re-exec")
+	process.exit(1)
+} else if (unconditioned) handOff(process.execPath, sourceEnv)
+else {
+	const { main } = await entry()
+	const code = await main(process.argv.slice(2))
+	/* an --app module may leave a timer or a socket open: the run is over once main returns, its output flushed */
+	for (const stream of [process.stdout, process.stderr]) await new Promise((done) => stream.write("", done))
+	process.exit(code)
+}

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+import { type Formatter } from "./emit/shared/format.ts";
+import { type Generate } from "./gen/args.ts";
+/**
+ * The gofmt the go and cli targets are formatted with: `$GOFMT`, else `$GOROOT/bin/gofmt`, else gofmt on PATH, else
+ * the gofmt beside the real `go` on PATH (where every Go install keeps it); none when no Go is installed. Found by
+ * looking, never by running Go.
+ */
+export declare function findGofmt(env?: NodeJS.ProcessEnv): string | undefined;
+/** oxfmt's `format`, the optional peer, when installed; else undefined (TS then goes out as emitted). */
+export declare function loadOxfmt(specifier?: string): Promise<Formatter | undefined>;
+/** What a generation reads beside its run: the environment, where skips are reported, the oxfmt module to load. */
+export type GenerateContext = {
+    readonly env: NodeJS.ProcessEnv;
+    readonly report: (line: string) => void;
+    /** oxfmt's specifier, "oxfmt" by default: a leg names a missing one to run without it */
+    readonly oxfmt?: string;
+};
+/** Every file a run writes, by target and its path under the target's directory, Go's through gofmt, TS's through oxfmt. */
+export declare function generated(run: Pick<Generate, "options" | "targets">, document: Record<string, unknown>, { env, oxfmt, report }: GenerateContext): Promise<Partial<Record<"cli" | "csharp" | "go" | "java" | "mcp" | "python" | "rust" | "ts", Readonly<Record<string, string>>>>>;
+/** Where the CLI writes: standard output and standard error, by default the process's. */
+export type Io = {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+};
+/** `document`'s targets generated and written under `<out>/<target>`, stale files deleted. */
+export declare function writeGenerated(run: Pick<Generate, "options" | "out" | "targets">, document: Record<string, unknown>, io: Io, env: NodeJS.ProcessEnv): Promise<number>;
+/** What a run takes beside its arguments: the environment, the directory paths resolve from, a watch's stop signal. */
+export type RunOptions = {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+};
+/** Runs `honey-clients <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
+export declare function main(argv: readonly string[], io?: Io, options?: RunOptions): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,204 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The honey-clients generate CLI (bit 17 phase h): `honey-clients generate --spec <openapi.json> --target <name>...
+ * --out <dir>` writes each target's generated files under `<out>/<target>`. A target's options are its generate
+ * function's, spelled `--<target>-<option>` and passed through untouched: each generator validates its own. The go and
+ * cli targets' whole trees go through gofmt (the post-pass), so a missing gofmt is a refusal, never unformatted Go; the
+ * ts target's files go through oxfmt, the optional peer, imported lazily, and go out as emitted without it (00-rules).
+ * `--watch` regenerates in a fresh child on each change of the spec. Parsing is strict: an unknown flag, a missing
+ * value, a stray argument or an option for a target not asked for is a usage error. Each target is written through
+ * write.ts: only changed files, a hashed manifest, a removed operation's unedited files deleted (bit 19 h1). `--app`
+ * generates from a honey app module instead of a spec, its document made by the app's own core (ir/load.ts, bit 19 h2).
+ */
+import { existsSync, readFileSync, realpathSync, statSync, watch } from "node:fs";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { generateGoCli } from "./emit/cli/module.js";
+import { generateCSharpSdk } from "./emit/csharp/sdk.js";
+import { generateGoSdk } from "./emit/go/sdk.js";
+import { generateJavaSdk } from "./emit/java/sdk.js";
+import { generateMcpServer } from "./emit/mcp/server.js";
+import { generatePythonSdk } from "./emit/python/sdk.js";
+import { generateRustSdk } from "./emit/rust/sdk.js";
+import { formatFiles } from "./emit/shared/format.js";
+import { gofmtFormatter } from "./emit/shared/gofmt.js";
+import { generateSdk } from "./emit/ts/sdk.js";
+import { parseGenerate, usage, UsageError } from "./gen/args.js";
+import { runCli } from "./gen/process.js";
+import { appRef, loadAppDocument } from "./ir/load.js";
+import { writeTarget } from "./gen/write.js";
+/** An executable named `name` on PATH, or none. */
+function onPath(name, env) {
+    return (env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .map((dir) => join(dir, name))
+        .find((path) => existsSync(path) && statSync(path).isFile());
+}
+/**
+ * The gofmt the go and cli targets are formatted with: `$GOFMT`, else `$GOROOT/bin/gofmt`, else gofmt on PATH, else
+ * the gofmt beside the real `go` on PATH (where every Go install keeps it); none when no Go is installed. Found by
+ * looking, never by running Go.
+ */
+export function findGofmt(env = process.env) {
+    if (env.GOFMT)
+        return env.GOFMT;
+    const fromRoot = env.GOROOT ? join(env.GOROOT, "bin", "gofmt") : undefined;
+    if (fromRoot !== undefined && existsSync(fromRoot))
+        return fromRoot;
+    const go = onPath("go", env);
+    const beside = go === undefined ? undefined : join(dirname(realpathSync(go)), "gofmt");
+    return onPath("gofmt", env) ?? (beside !== undefined && existsSync(beside) ? beside : undefined);
+}
+/** One SDK target's generation: its files and what it reports (a name it renamed). */
+function sdkOf(target, document, options) {
+    switch (target) {
+        case "ts":
+            return generateSdk(document, { name: "SDK", ...options });
+        case "go":
+            return generateGoSdk(document, options);
+        case "rust":
+            return generateRustSdk(document, options);
+        case "python":
+            return generatePythonSdk(document, options);
+        case "csharp":
+            return generateCSharpSdk(document, options);
+        case "java":
+            return generateJavaSdk(document, options);
+    }
+}
+/** One target's files for `document`, by their path under the target's directory; what it leaves out to `report`. */
+function filesOf(target, document, options, report) {
+    if (target === "cli")
+        return generateGoCli(document, options).files;
+    if (target === "mcp") {
+        const server = generateMcpServer(document, options);
+        for (const op of server.skipped)
+            report(`honey-clients: mcp: no tool serves ${op} yet: skipped\n`);
+        return server.files;
+    }
+    const sdk = sdkOf(target, document, options);
+    for (const notice of sdk.notices)
+        report(`honey-clients: ${notice}\n`);
+    return sdk.files;
+}
+/** oxfmt's `format`, the optional peer, when installed; else undefined (TS then goes out as emitted). */
+export async function loadOxfmt(specifier = "oxfmt") {
+    try {
+        return (await import(__rewriteRelativeImportExtension(specifier))).format;
+    }
+    catch (error) {
+        if (error.code === "ERR_MODULE_NOT_FOUND")
+            return undefined;
+        throw error;
+    }
+}
+/** Every file a run writes, by target and its path under the target's directory, Go's through gofmt, TS's through oxfmt. */
+export async function generated(run, document, { env, oxfmt, report }) {
+    const out = {};
+    for (const target of run.targets) {
+        let files = filesOf(target, document, run.options[target], report);
+        if (target === "go" || target === "cli") {
+            const gofmt = findGofmt(env);
+            if (gofmt === undefined)
+                throw new Error("gofmt is required for the go and cli targets (install Go, or set GOFMT)");
+            files = await formatFiles(files, { go: gofmtFormatter(gofmt) });
+        }
+        if (target === "ts") {
+            const format = await loadOxfmt(oxfmt);
+            if (format !== undefined)
+                files = await formatFiles(files, { ts: format });
+        }
+        out[target] = files;
+    }
+    return out;
+}
+/** The spec at `path`, parsed. */
+function readSpec(path) {
+    const text = readFileSync(path, "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${path}: not a JSON document (${error.message})`, { cause: error });
+    }
+}
+const PROCESS_IO = {
+    err: (text) => void process.stderr.write(text),
+    out: (text) => void process.stdout.write(text),
+};
+/** `document`'s targets generated and written under `<out>/<target>`, stale files deleted. */
+export async function writeGenerated(run, document, io, env) {
+    let count = 0;
+    for (const [target, files] of Object.entries(await generated(run, document, { env, report: io.err }))) {
+        for (const rel of writeTarget(join(run.out, target), files).kept)
+            io.err(`honey-clients: ${join(target, rel)} is stale but edited since it was generated, or not its to delete: kept\n`);
+        count += Object.keys(files).length;
+    }
+    io.out(`honey-clients: generated ${count} files into ${run.out}\n`);
+    return 0;
+}
+/** One generation: the spec read, or the app's document made (the module resolved from `cwd`), then written. */
+async function generateOnce(run, io, env, cwd) {
+    const document = run.app === "" ? readSpec(resolve(cwd, run.spec)) : await loadAppDocument(run.app, cwd);
+    return writeGenerated({ ...run, out: resolve(cwd, run.out) }, document, io, env);
+}
+/**
+ * Generates now and on each change of the spec, each run a fresh child after the one before it (a change during a run
+ * is one more run, never two at once); `signal` stops the watch, which then ends 0 once the last run is done. A
+ * generation child (HONEY_CODEGEN_CHILD) never watches: were `--watch` ever passed down, each child would start another.
+ */
+function watchSpec(run, argv, io, options) {
+    if (options.env.HONEY_CODEGEN_CHILD === "1")
+        throw new Error("--watch is not allowed in a generation child");
+    const args = ["generate", ...argv.filter((arg) => arg !== "--watch" && !arg.startsWith("--watch="))];
+    const spec = resolve(options.cwd, run.app === "" ? run.spec : appRef(run.app).module);
+    let queue = Promise.resolve();
+    const generate = () => {
+        queue = queue.then(() => runCli(args, { cwd: options.cwd, env: options.env }).catch((error) => io.err(`honey-clients: ${error.message}\n`)));
+    };
+    let timer;
+    const watcher = watch(dirname(spec), (_event, name) => {
+        if (name !== basename(spec))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(generate, 100);
+    });
+    io.out(`honey-clients: watching ${spec}\n`);
+    generate();
+    return new Promise((settle) => options.signal?.addEventListener("abort", () => {
+        watcher.close();
+        clearTimeout(timer);
+        void queue.then(() => settle(0));
+    }, { once: true }));
+}
+/** Runs `honey-clients <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
+export async function main(argv, io = PROCESS_IO, options = {}) {
+    try {
+        if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help" || argv.includes("--help")) {
+            io.out(`${usage()}\n`);
+            return argv.length === 0 ? 1 : 0;
+        }
+        if (argv[0] !== "generate")
+            throw new UsageError(`unknown command ${JSON.stringify(argv[0])}`);
+        const run = parseGenerate(argv.slice(1));
+        const [env, cwd] = [options.env ?? process.env, options.cwd ?? process.cwd()];
+        return run.watch
+            ? await watchSpec(run, argv.slice(1), io, { cwd, env, signal: options.signal })
+            : await generateOnce(run, io, env, cwd);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            io.err(`honey-clients: ${error.message}\n\n${usage()}\n`);
+            return 1;
+        }
+        io.err(`honey-clients: ${error.message}\n`);
+        return 1;
+    }
+}

package/dist/emit/cli/commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One command per operation (bit 17), by its dotted id: `items.get` is `items get`, `a.b.c` is `a b c`, a flat id
+ * (`getRoot`) a top-level `get-root`. The verb is the id's last segment as authored, never renamed. In a group a
+ * subgroup claims its name before a command, and at the root every built-in (completion, commands, config, help,
+ * schema, skill, version) is taken first, so a clash is suffixed as the IR suffixes ids (`version2`). Each command calls
+ * the embedded SDK's own method by the emitter's call plan, its body read from its flags (a multipart one part by
+ * part), and prints the answer with the response it came on, or a stream's events one line each (phase d).
+ */
+import type { IR } from "../../ir/model.ts";
+import type { SdkOp } from "../../ir/sdk-model.ts";
+import type { GoCallPlan } from "../go/sdk-client.ts";
+/** The root's own commands, each taken before an operation's. */
+export declare const BUILT_INS: string[];
+/** A command node: a group of others, or one operation's command. */
+export type CommandNode = {
+    readonly name: string;
+    readonly fn: string;
+    readonly children: readonly CommandNode[];
+    readonly op?: {
+        readonly op: SdkOp;
+        readonly plan: GoCallPlan;
+    };
+};
+/** The command tree under the root, by the ids of every operation `ops` holds a command for. */
+export declare function commandTree(ops: readonly SdkOp[], plans: Readonly<Record<string, GoCallPlan>>): CommandNode[];
+/** A group's command function, then each of its children's. */
+export declare function groupFuncs(node: CommandNode, path: readonly string[], ir: IR): string[][];

package/dist/emit/cli/commands.js

@@ -0,0 +1,187 @@
+import { goString, lineComment } from "../shared/escape.js";
+import { compareCodeUnits, NameScope, pascalWords } from "../shared/lang.js";
+import { commandFlags, helpText, kebab } from "./flags.js";
+/** The root's own commands, each taken before an operation's. */
+export const BUILT_INS = ["commands", "completion", "config", "help", "schema", "skill", "version"];
+function rawTree(ops, plans) {
+    const root = { groups: new Map(), leaves: new Map() };
+    for (const op of [...ops].sort((a, b) => compareCodeUnits(a.id, b.id))) {
+        let at = root;
+        for (const segment of op.segments.slice(0, -1)) {
+            if (!at.groups.has(segment))
+                at.groups.set(segment, { groups: new Map(), leaves: new Map() });
+            at = at.groups.get(segment);
+        }
+        at.leaves.set(op.segments.at(-1), { op, plan: plans[op.id] });
+    }
+    return root;
+}
+/** `raw` named: its groups first, then its commands, each claimed in its parent's scope; funcs claimed in `funcs`. */
+function named(raw, path, scope, funcs) {
+    const groups = [...raw.groups].sort(([a], [b]) => compareCodeUnits(a, b));
+    const leaves = [...raw.leaves].sort(([a], [b]) => compareCodeUnits(a, b));
+    return [
+        ...groups.map(([segment, child]) => {
+            const name = scope.claim(kebab(segment));
+            const at = [...path, name];
+            return {
+                children: named(child, at, new NameScope(), funcs),
+                fn: funcs.claim(`new${pascalWords(at.join(" "))}Cmd`),
+                name,
+            };
+        }),
+        ...leaves.map(([segment, leaf]) => {
+            const name = scope.claim(kebab(segment));
+            return { children: [], fn: funcs.claim(`new${pascalWords([...path, name].join(" "))}Cmd`), name, op: leaf };
+        }),
+    ];
+}
+/** The command tree under the root, by the ids of every operation `ops` holds a command for. */
+export function commandTree(ops, plans) {
+    return named(rawTree(ops, plans), [], new NameScope(BUILT_INS), new NameScope(["Root", "newClient", "failed"]));
+}
+/** A named type of the SDK's, as package cmd spells it: `sdk.` before each exported name. */
+const qualified = (type) => type.replace(/(?<![\w.])([A-Z]\w*)/g, "sdk.$1");
+/** A multipart body's statements: each file part from its opened files, each text part from its flag. */
+function multipartLines(type, parts) {
+    const lines = [`\tvar body ${type}`];
+    for (const [i, part] of parts.entries()) {
+        if (!part.file) {
+            lines.push(`\tif err := cli.Set(&body.${part.field}, p.Values(${goString(part.flag)})); err != nil {`, "\t\treturn err", "\t}");
+            continue;
+        }
+        const file = "sdk.FilePart{Filename: upload.Filename, Data: upload.Data}";
+        const set = part.list ? `body.${part.field} = append(body.${part.field}, ${file})` : `body.${part.field} = ${file}`;
+        lines.push(`\tuploads${i}, err := p.Files(${goString(part.flag)})`, "\tif err != nil {", "\t\treturn err", "\t}", `\tfor _, upload := range uploads${i} {`, `\t\t${set}`, "\t}");
+    }
+    return lines;
+}
+/** The statements reading the body, and the argument passing it. */
+function bodyLines(op, plan, flags) {
+    const { fields } = flags;
+    const body = op.body;
+    if (body === undefined)
+        return [[], ""];
+    const required = String(body.required);
+    const map = `map[string]string{${fields.map(([flag, key]) => `${goString(flag)}: ${goString(key)}`).join(", ")}}`;
+    const fail = ["\tif err != nil {", "\t\treturn err", "\t}"];
+    switch (body.kind) {
+        case "json": {
+            /* a pointer type decodes as well: json.Unmarshal allocates it, and an absent optional body stays nil */
+            const read = `\tif err := p.JSON(&body, ${required}, ${map}); err != nil {`;
+            return [[`\tvar body ${qualified(plan.bodyType)}`, read, "\t\treturn err", "\t}"], ", body"];
+        }
+        case "form":
+            return [[`\tbody, err := p.Form(${required}, ${map})`, ...fail], ", body"];
+        case "text":
+            return [[`\tbody, err := p.Text(${required})`, ...fail], ", body"];
+        case "multipart":
+            return [multipartLines(qualified(plan.bodyType), flags.parts), ", body"];
+        default:
+            return [[`\tbody, err := p.Reader(${required})`, ...fail], ", body"];
+    }
+}
+/** A stream's call: its stream opened first (its output flags checked), then each event printed as it comes. */
+function streamLines(call, stream) {
+    const open = ["\tout, err := cli.OpenStream(c)", "\tif err != nil {", "\t\treturn err", "\t}", "\tdefer out.Close()"];
+    if (stream === "sse")
+        return [
+            ...open,
+            `\tfor event, err := range ${call} {`,
+            "\t\tif err != nil {",
+            "\t\t\treturn failed(err)",
+            "\t\t}",
+            "\t\tif !out.Event(event.Event, event.ID, event.Data) {",
+            "\t\t\tbreak",
+            "\t\t}",
+            "\t}",
+            "\treturn out.Err()",
+        ];
+    return [
+        ...open,
+        `\tconn, err := ${call}`,
+        "\tif err != nil {",
+        "\t\treturn failed(err)",
+        "\t}",
+        stream === "realtime" ? "\treturn failed(out.Resume(conn))" : "\treturn out.Converse(conn)",
+    ];
+}
+/** The call and what follows it, by what the method returns: the answer printed with the response it came on. */
+function callLines(call, plan) {
+    const declared = Object.keys(plan.responseHeaders?.fields ?? {})
+        .map(goString)
+        .join(", ");
+    const answer = (data) => `\treturn cli.Print(c, cli.Answer{${data}Response: resp, Declared: []string{${declared}}})`;
+    if (plan.returns === "error")
+        return [
+            "\tvar resp *http.Response",
+            `\tif err := ${call}; err != nil {`,
+            "\t\treturn failed(err)",
+            "\t}",
+            answer(""),
+        ];
+    return [
+        "\tvar resp *http.Response",
+        `\tanswer, err := ${call}`,
+        "\tif err != nil {",
+        "\t\treturn failed(err)",
+        "\t}",
+        answer("Data: answer, "),
+    ];
+}
+/** An operation's command function: its flags, then the RunE that checks them, calls the SDK and prints. */
+function opFunc(node, path, ir) {
+    const { op, plan } = node.op;
+    const flags = commandFlags(op, plan, ir.schemas);
+    const use = [node.name, ...plan.pathParams.map((name) => `<${kebab(name)}>`)].join(" ");
+    const [read, bodyArg] = bodyLines(op, plan, flags);
+    const args = plan.pathParams.map((_, i) => `, path[${i}]`).join("");
+    const method = ["client", ...plan.members, plan.method].join(".");
+    const cobra = [`Use: ${goString(use)}`, `Short: ${goString(helpText(op.summary))}`];
+    if (op.description !== "")
+        cobra.push(`Long: ${goString(helpText(op.description))}`);
+    const run = [
+        "\tif err := p.Check(); err != nil {",
+        "\t\treturn err",
+        "\t}",
+        ...(plan.pathParams.length > 0 ? ["\tpath := p.PathValues(args)"] : []),
+        `\topts := &sdk.${plan.opts}{}`,
+        ...flags.opts,
+        ...read,
+        "\tclient, err := newClient(c)",
+        "\tif err != nil {",
+        "\t\treturn err",
+        "\t}",
+        ...(plan.stream === null
+            ? callLines(`${method}(c.Context()${args}${bodyArg}, opts, sdk.WithResponseInto(&resp))`, plan)
+            : streamLines(`${method}(c.Context()${args}${bodyArg}, opts)`, plan.stream)),
+    ];
+    return [
+        ...lineComment(`${node.fn} is \`${[...path, node.name].join(" ")}\`: ${op.method} ${op.path}.`, "//"),
+        `func ${node.fn}() *cobra.Command {`,
+        `\tcmd := &cobra.Command{${cobra.join(", ")}}`,
+        "\tp := cli.NewParams(cmd)",
+        ...flags.declare,
+        `\tcmd.RunE = func(c *cobra.Command, ${plan.pathParams.length > 0 ? "args" : "_"} []string) error {`,
+        ...run.map((line) => `\t${line}`),
+        "\t}",
+        "\treturn cmd",
+        "}",
+    ];
+}
+/** A group's command function, then each of its children's. */
+export function groupFuncs(node, path, ir) {
+    if (node.op !== undefined)
+        return [opFunc(node, path, ir)];
+    const at = [...path, node.name];
+    const children = node.children.map((child) => `${child.fn}()`).join(", ");
+    const own = [
+        ...lineComment(`${node.fn} is \`${at.join(" ")}\`, a group of commands.`, "//"),
+        `func ${node.fn}() *cobra.Command {`,
+        `\tcmd := cli.Group(&cobra.Command{Use: ${goString(node.name)}})`,
+        `\tcmd.AddCommand(${children})`,
+        "\treturn cmd",
+        "}",
+    ];
+    return [own, ...node.children.flatMap((child) => groupFuncs(child, at, ir))];
+}