@labelbox/recursion-cli 0.0.0 → 0.0.41

package/dist/program.js

@@ -0,0 +1,875 @@
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { dispatchOperation } from './dispatch.js';
+import { addGitHostCommands } from './git-host.js';
+import { shapeMetaEntries } from './manifest.js';
+import { missingPermission } from './permissions.js';
+import { addSkillsCommands } from './skills.js';
+// The CLI is a thin, generic driver. It builds its whole command tree + docs at
+// runtime from a manifest **fetched live** from the target server (see
+// `manifest.ts`), keyed by each operation's `callPath` — the exact path used as
+// `rl.<noun>.<verb>(...)` in the TS SDK. Adding/changing a backend endpoint → the
+// command appears (or changes) after the backend deploys, with NO CLI release.
+// Dispatch is generic (`dispatch.ts`): there is no per-operation code and no baked
+// client.
+/** camelCase → kebab-case for command + flag names (was `@labelbox/recursion-sdk/nesting`). */
+export function kebab(value) {
+    return value.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase();
+}
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+// Flag names the CLI reserves for its own meta-options. If a generated operation
+// ever declares a param whose kebab name collides with one of these, commander
+// would silently register the flag twice (last-registration-wins), so we fail
+// fast at build time instead. `from-json`/`data` are body meta-flags; the rest
+// are program-level globals.
+const RESERVED_FLAGS = new Set([
+    'from-json',
+    'data',
+    'api-key',
+    'base-url',
+    'quiet',
+    'help',
+    'version',
+]);
+// Top-level command names the CLI registers itself (the docs browse groups + the
+// bespoke `skills` action group, added after the operation loop). An operation
+// whose top-level `callPath` segment kebabs onto one of these would be silently
+// shadowed — commander resolves duplicates to the first registration — so we
+// reserve them and fail fast, mirroring RESERVED_FLAGS for flags.
+const RESERVED_COMMANDS = new Set([
+    'resources',
+    'recipes',
+    'explain',
+    'tutorials',
+    'skills',
+    'scaffold',
+    'submit',
+]);
+const TRUE_VALUES = new Set(['true', '1', 'yes']);
+const FALSE_VALUES = new Set(['false', '0', 'no']);
+/** Coerce a string flag value to its declared scalar type. */
+export function coerce(value, type) {
+    if (typeof value !== 'string')
+        return value;
+    if (type === 'number' || type === 'integer') {
+        const n = Number(value);
+        // Reject NaN and non-finite values (e.g. Infinity, 1e999): the latter
+        // JSON-serialize to null, which the API would silently misinterpret.
+        if (!Number.isFinite(n)) {
+            throw new Error(`invalid ${type} value ${JSON.stringify(value)} (expected a number)`);
+        }
+        if (type === 'integer' && !Number.isInteger(n)) {
+            throw new Error(`invalid integer value ${JSON.stringify(value)} (expected a whole number)`);
+        }
+        return n;
+    }
+    if (type === 'boolean') {
+        const lower = value.toLowerCase();
+        if (TRUE_VALUES.has(lower))
+            return true;
+        if (FALSE_VALUES.has(lower))
+            return false;
+        throw new Error(`invalid boolean value ${JSON.stringify(value)} (expected true or false)`);
+    }
+    return value;
+}
+/**
+ * Build the flat options object from parsed CLI flags + a pre-parsed body base
+ * (from `--from-json` / `--data`). Path and query params and scalar body fields
+ * come from individual flags; scalar flags override the JSON base. Required scalar
+ * body fields are enforced here — after the flag and JSON sources are merged — so a
+ * value supplied via `--from-json`/`--data` satisfies the requirement just as its
+ * own flag would (a clear CLI error rather than a server-side 4xx).
+ */
+export function assembleParams(entry, opts, bodyBase) {
+    const params = {};
+    for (const param of entry.params) {
+        if (param.in === 'path' || param.in === 'query') {
+            const value = opts[param.name];
+            if (value === undefined)
+                continue;
+            // A non-scalar query param (array/object) must reach dispatch as a real
+            // array/object — the query serializer dispatches on JS type, so a raw string
+            // would be mis-serialized. Parse those flag values as JSON; scalars use
+            // `coerce`. (Path params are always plain string segments.)
+            params[param.name] =
+                param.in === 'query' && !SCALAR_TYPES.has(param.type)
+                    ? parseJson(typeof value === 'string' ? value : '', `--${kebab(param.name)}`)
+                    : coerce(value, param.type);
+        }
+    }
+    if (entry.bodyKey) {
+        const body = { ...bodyBase };
+        const missing = [];
+        for (const param of entry.params) {
+            if (param.in === 'body' && SCALAR_TYPES.has(param.type)) {
+                const value = opts[param.name];
+                if (value !== undefined)
+                    body[param.name] = coerce(value, param.type);
+                if (param.required && body[param.name] === undefined)
+                    missing.push(kebab(param.name));
+            }
+        }
+        if (missing.length > 0) {
+            throw new Error(`missing required field(s): ${missing.map((m) => `--${m}`).join(', ')} ` +
+                // Names only --data: it is the one body source present in every
+                // program, whereas --from-json is absent from the embedded one, and a
+                // message naming a flag that does not exist sends the reader hunting.
+                '(pass the flag or include it in the --data JSON body)');
+        }
+        params[entry.bodyKey] = body;
+    }
+    return params;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse JSON, surfacing a clean `error:`-friendly message tagged by source. */
+function parseJson(text, source) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`invalid JSON in ${source}: ${detail}`);
+    }
+}
+export function parseBodyBase(opts) {
+    const { fromJson, data } = opts;
+    if (typeof fromJson === 'string' && typeof data === 'string') {
+        throw new Error('--from-json and --data are mutually exclusive; pass only one');
+    }
+    let parsed;
+    // Tracked so the failure below can name the flag the caller actually passed.
+    // Naming both would send a reader of the embedded program — where `--from-json`
+    // is not registered — hunting for a flag that does not exist there.
+    let source;
+    if (typeof fromJson === 'string') {
+        let contents;
+        try {
+            contents = readFileSync(fromJson, 'utf8');
+        }
+        catch {
+            throw new Error(`could not read --from-json file ${JSON.stringify(fromJson)}`);
+        }
+        source = '--from-json';
+        parsed = parseJson(contents, source);
+    }
+    else if (typeof data === 'string') {
+        source = '--data';
+        parsed = parseJson(data, source);
+    }
+    else {
+        return {};
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`${source} must contain a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * Render a result for stdout. In `--quiet` mode, prints the result's `id` (an
+ * empty line for results without one). Otherwise pretty-prints the JSON, or `OK`
+ * for a void response. The trailing newline is part of the returned string.
+ */
+export function formatOutput(result, quiet) {
+    if (quiet) {
+        const id = typeof result === 'object' && result !== null && 'id' in result ? result.id : undefined;
+        return `${id === undefined ? '' : String(id)}\n`;
+    }
+    return `${result === undefined ? 'OK' : JSON.stringify(result, null, 2)}\n`;
+}
+/**
+ * Render a caught error for stderr. Generic dispatch throws the server's JSON error
+ * body (printed as-is) or an `Error` (its message). A raw, detail-less object (or a
+ * thrown empty value) maps to a message that points at the likely cause.
+ */
+export function formatError(err) {
+    if (err instanceof Error)
+        return err.message;
+    const json = JSON.stringify(err, null, 2);
+    if (json === undefined || json === '{}') {
+        return 'request failed — the server could not be reached (check --base-url and your network)';
+    }
+    return json;
+}
+// Per-key CLI tag labels. Driven by `shapeMetaEntries` (the shared spine in
+// `manifest.ts`); `satisfies Record<ShapeMetaKey, string>` makes a new `ShapeNode`
+// constraint a compile error here until it gets a label.
+const CLI_META_LABELS = {
+    enum: 'enum',
+    itemEnum: 'values',
+    default: 'default',
+    format: 'format',
+    example: 'example',
+    minimum: 'min',
+    exclusiveMinimum: 'min',
+    maximum: 'max',
+    exclusiveMaximum: 'max',
+    minLength: 'minLength',
+    maxLength: 'maxLength',
+    minItems: 'minItems',
+    maxItems: 'maxItems',
+    pattern: 'pattern',
+    nullable: 'nullable',
+};
+/**
+ * Bracketed spec-metadata tags for a node — allowed values, default, format,
+ * example, the numeric/length/size constraints, and nullability. Shared by the
+ * per-flag help and the request-body / returns shape trees so both surface the
+ * same facts. (Required-ness is conveyed separately: commander marks required
+ * path/query flags, and the tree marks optional fields with a `?`.)
+ */
+function metaTags(node) {
+    return shapeMetaEntries(node).map(([key, value]) => {
+        if (key === 'nullable')
+            return `[${CLI_META_LABELS[key]}]`;
+        const rendered = Array.isArray(value) ? value.join('|') : value;
+        return `[${CLI_META_LABELS[key]}: ${rendered}]`;
+    });
+}
+/** Help text for a flag: its description plus any spec metadata, bracketed. */
+function helpText(param) {
+    const parts = [];
+    if (param.description)
+        parts.push(param.description);
+    parts.push(...metaTags(param));
+    // Body scalar fields are non-mandatory at the commander level (so --from-json
+    // can satisfy them) — commander's help won't mark them required, so surface it.
+    if (param.in === 'body' && param.required)
+        parts.push('[required]');
+    return parts.join(' ');
+}
+/**
+ * Render a request-body / response shape as an indented tree of lines. Each node
+ * shows `name` (or `name?` when optional), its type label, and its metadata tags,
+ * then recurses into whatever sub-shape it has.
+ */
+export function renderShapeTree(nodes, indent) {
+    return nodes.flatMap((node) => {
+        const label = node.name;
+        if (!label)
+            return [];
+        return renderShapeNode(node, label, indent);
+    });
+}
+/** One node as `<label>: <type> <tags> — <desc>`, followed by its nested sub-shape. */
+function renderShapeNode(node, label, indent) {
+    const optional = node.required === false ? '?' : '';
+    const tags = metaTags(node);
+    const desc = node.description ? ` — ${node.description}` : '';
+    const head = `${indent}${label}${optional}: ${node.type}${tags.length ? ` ${tags.join(' ')}` : ''}${desc}`;
+    return [head, ...renderShapeChildren(node, `${indent}  `)];
+}
+/**
+ * A node's nested sub-shape, recursed generically: a union lists each variant under
+ * `one of:`; an object renders its `fields`; an array descends into its `items`.
+ */
+function renderShapeChildren(node, indent) {
+    if (node.variants?.length) {
+        return [
+            `${indent}one of:`,
+            ...node.variants.flatMap((variant, index) => renderShapeNode(variant, variant.name ?? `variant ${index + 1}`, `${indent}  `)),
+        ];
+    }
+    if (node.fields?.length) {
+        return renderShapeTree(node.fields, indent);
+    }
+    if (node.items) {
+        return renderShapeNode(node.items, 'items', indent);
+    }
+    return [];
+}
+/**
+ * The "Request body" + "Returns" help sections appended after a leaf command's
+ * built-in help. The body section renders the body params' full nested shape; the
+ * returns section renders the success response's full shape — an object's fields,
+ * an `array of <element>` with the element's shape, or a scalar's type — or a note
+ * when the op returns no body.
+ */
+export function leafShapeHelp(entry) {
+    const sections = [];
+    const bodyParams = entry.params.filter((p) => p.in === 'body');
+    if (entry.bodyKey && bodyParams.length > 0) {
+        sections.push('Request body:', ...renderShapeTree(bodyParams, '  '), '');
+    }
+    const response = entry.response;
+    if (!response) {
+        sections.push('Returns: (no documented response body)');
+    }
+    else if (response.fields && response.fields.length > 0) {
+        const tags = metaTags(response);
+        const desc = response.description ? ` — ${response.description}` : '';
+        sections.push(`Returns: ${response.type}${tags.length ? ` ${tags.join(' ')}` : ''}${desc}`, ...renderShapeTree(response.fields, '  '));
+    }
+    else if (response.items) {
+        const item = response.items;
+        const tags = metaTags(response);
+        const desc = response.description ? ` — ${response.description}` : '';
+        sections.push(`Returns: array of ${item.type}${tags.length ? ` ${tags.join(' ')}` : ''}${desc}`, ...renderShapeNode(item, 'items', '  '));
+    }
+    else if (response.variants?.length) {
+        const tags = metaTags(response);
+        const desc = response.description ? ` — ${response.description}` : '';
+        sections.push(`Returns: ${response.type}${tags.length ? ` ${tags.join(' ')}` : ''}${desc}`, ...renderShapeChildren(response, '  '));
+    }
+    else {
+        const tags = metaTags(response);
+        const desc = response.description ? ` — ${response.description}` : '';
+        sections.push(`Returns: ${response.type}${tags.length ? ` ${tags.join(' ')}` : ''}${desc}`);
+    }
+    return `\n${sections.join('\n')}`;
+}
+/**
+ * Register an operation's flags.
+ *
+ * `fileFlags` is false when the program has no developer checkout — the embedded
+ * server case. `--from-json` reads a file from the *server's* filesystem there, so
+ * `assertAllowedArgv` refuses it; advertising a flag in `--help` that is then
+ * refused on use sends a caller looking for a permission or configuration problem
+ * that does not exist. Not registered at all, so `--help` shows only what works
+ * and `--data` is the single documented way to pass a body.
+ */
+export function addOptions(command, entry, fileFlags = true) {
+    // Flags already claimed on this command. A body field can legitimately repeat
+    // a path parameter's name — several upstream PATCH operations take the full
+    // resource type as their request body, so `agent_id` is both the path
+    // parameter and a property of the body schema. Commander throws when the same
+    // flag is added twice, and that throw happens while the whole program is
+    // being built, so one such operation takes down `rl` entirely rather than
+    // just itself. Path and query win: they address the resource and are what the
+    // URL is built from. The shadowed body field is still settable through
+    // `--from-json` / `--data`.
+    const claimed = new Set();
+    const ordered = [
+        ...entry.params.filter((p) => p.in === 'path' || p.in === 'query'),
+        ...entry.params.filter((p) => p.in !== 'path' && p.in !== 'query'),
+    ];
+    for (const param of ordered) {
+        const registersFlag = param.in === 'path' ||
+            param.in === 'query' ||
+            (param.in === 'body' && SCALAR_TYPES.has(param.type));
+        if (!registersFlag)
+            continue;
+        const name = kebab(param.name);
+        if (claimed.has(name))
+            continue;
+        claimed.add(name);
+        if (RESERVED_FLAGS.has(name)) {
+            throw new Error(`operation "${entry.operationId}" declares param "${param.name}" whose flag ` +
+                `--${name} collides with a reserved CLI flag; rename it in the backend spec.`);
+        }
+        const flag = `--${name} <${name}>`;
+        const nonScalarQuery = param.in === 'query' && !SCALAR_TYPES.has(param.type);
+        const description = nonScalarQuery
+            ? [helpText(param), '[pass as JSON]'].filter(Boolean).join(' ')
+            : helpText(param);
+        if (param.in === 'path') {
+            command.requiredOption(flag, description);
+        }
+        else if (param.in === 'query') {
+            if (param.required)
+                command.requiredOption(flag, description);
+            else
+                command.option(flag, description);
+        }
+        else {
+            // Scalar body field — always a plain option (requiredness enforced in
+            // assembleParams once flag + JSON sources are merged).
+            command.option(flag, description);
+        }
+    }
+    if (entry.bodyKey) {
+        if (fileFlags) {
+            command.option('--from-json <file>', 'Read the request body from a JSON file');
+        }
+        command.option('--data <json>', 'Inline JSON request body');
+    }
+}
+// ── docs browse surfaces — one consistent shape: `rl <group> [<id>]` ─────────
+//
+// All four read-only browse groups (resources / recipes / explain / tutorials)
+// take one positional shape: bare lists, an id shows that one. No `show`/`list`
+// verbs (those are the action layer's, `rl <noun> <verb>`). All data is the live
+// manifest; these commands are pure presentation (no further network).
+// The Labelbox app host (not the recursion API base) — recipes/docs render in-app.
+const RECIPE_DOCS_BASE_URL = 'https://app.labelbox.com';
+/** Output formats `rl recipes <id>` can render, mapped to the composed snippet field. */
+const RECIPE_FORMATS = { cli: 'cli', ts: 'sdk', curl: 'curl' };
+function isRecipeFormat(value) {
+    return Object.hasOwn(RECIPE_FORMATS, value);
+}
+/** Group entries under their domain (in nav order), with anything domainless last. */
+function groupByDomain(entries, domainOf, domains) {
+    const order = new Map(domains.map((d, i) => [d.id, { title: d.title, index: i }]));
+    const buckets = new Map();
+    for (const entry of entries) {
+        const key = domainOf(entry) ?? '';
+        const bucket = buckets.get(key) ?? [];
+        bucket.push(entry);
+        buckets.set(key, bucket);
+    }
+    const groups = [...buckets.entries()].map(([id, items]) => ({
+        id,
+        title: order.get(id)?.title ?? 'Other',
+        index: order.get(id)?.index ?? Number.MAX_SAFE_INTEGER,
+        entries: items,
+    }));
+    groups.sort((a, b) => a.index - b.index || a.title.localeCompare(b.title, 'en'));
+    return groups.map(({ title, entries: items }) => ({ title, entries: items }));
+}
+const ACTIONS_HELP_GROUP = 'Actions:';
+const DOCS_HELP_GROUP = 'Documentation:';
+const GIT_HOST_HELP_GROUP = 'Coding tasks:';
+/** Nested resource groups (`rl problems --help`, etc.) — allowed subcommands. */
+const COMMANDS_HELP_GROUP = 'Commands';
+/** Nested resource groups — subcommands the caller can't run (separate help section). */
+const UNAVAILABLE_HELP_GROUP = 'Unavailable (missing permission)';
+// ── permission gating (per-caller) ───────────────────────────────────────────
+//
+// A command the caller can't run stays *visible* (nothing is hidden) but is
+// grouped under "Unavailable (missing permission)", marked in its description,
+// and pre-empted on invoke. The listing marker, the leaf `--help` note, and the
+// invocation error all derive from the same missing-permission slug, so they
+// can't disagree. When permissions are unknown (fail-open) `missing` is undefined
+// everywhere and none of this fires.
+/** A leaf command's description when the caller lacks a required permission. */
+function gatedSummary(summary, missing) {
+    return missing === undefined ? summary : `requires \`${missing}\` — ${summary}`;
+}
+/** Banner above a resource group's `--help` when it lists unavailable subcommands. */
+function permissionGroupBanner(gatedCount) {
+    const noun = gatedCount === 1 ? 'command requires a permission' : 'commands require permissions';
+    return `\n${gatedCount} ${noun} you do not have (listed under "${UNAVAILABLE_HELP_GROUP}").\n`;
+}
+/** The error printed when the caller invokes a command they lack permission for. */
+function permissionDeniedMessage(missing) {
+    return `you don't have permission to run this command (requires \`${missing}\`)`;
+}
+/** A prominent note appended to a gated command's `--help` output. */
+function permissionHelpNote(missing) {
+    return `\nYou don't have permission to run this command (requires \`${missing}\`).`;
+}
+/** A resource's domain: its own, else the nearest ancestor's (walking `parent`). */
+function resolveResourceDomain(resource, byId) {
+    let current = resource;
+    const seen = new Set();
+    while (current && !seen.has(current.id)) {
+        if (current.domain)
+            return current.domain;
+        seen.add(current.id);
+        current =
+            current.parent && Object.hasOwn(byId, current.parent) ? byId[current.parent] : undefined;
+    }
+    return undefined;
+}
+/** The `rl <callPath>` invocation for an operation, with its required-flag hints. */
+function operationInvocation(op) {
+    const flags = [];
+    for (const param of op.params) {
+        if (param.in === 'path' || (param.in === 'query' && param.required)) {
+            const name = kebab(param.name);
+            flags.push(`--${name} <${name}>`);
+        }
+    }
+    if (op.bodyKey)
+        flags.push('--data <json>');
+    // kebab each segment so the printed command matches the real one (the tree is
+    // built from `kebab(segment)`) — `rl environments attach-external-id`, not the
+    // camelCase callPath.
+    const command = op.callPath.map(kebab).join(' ');
+    return `rl ${command}${flags.length ? ` ${flags.join(' ')}` : ''}`;
+}
+/** `rl resources [<id>]` — the Reference hub (grouped browse, or one resource). */
+function addResourcesCommand(program, manifest, io) {
+    const byId = manifest.resources;
+    program
+        .command('resources [id]')
+        .helpGroup(DOCS_HELP_GROUP)
+        .description('Browse resource reference hubs (run without an argument to list all)')
+        .action((id) => {
+        if (id === undefined) {
+            io.stdout(renderResourceList(manifest));
+            return;
+        }
+        // `Object.hasOwn`, not `byId[id]`: a Zod `z.record` is a plain object, so a bare
+        // read walks the prototype chain — `rl resources constructor` would resolve to a
+        // truthy inherited member, bypass the not-found guard, and crash in the renderer.
+        const entry = Object.hasOwn(byId, id) ? byId[id] : undefined;
+        if (!entry) {
+            throw new Error(`unknown resource "${id}". Run \`rl resources\` to list resources.`);
+        }
+        io.stdout(renderResourceShow(entry, manifest));
+    });
+}
+function renderResourceList(manifest) {
+    const byId = manifest.resources;
+    const all = Object.values(byId);
+    const groups = groupByDomain(all, (r) => resolveResourceDomain(r, byId), manifest.domains);
+    const lines = ['Resources — run `rl resources <id>` for the full overview.', ''];
+    for (const group of groups) {
+        lines.push(group.title);
+        const sorted = group.entries.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id, 'en'));
+        for (const r of sorted) {
+            lines.push(r.summary ? `  ${r.id} — ${r.summary}` : `  ${r.id}`);
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderResourceShow(resource, manifest) {
+    const parts = [resource.title];
+    if (resource.summary)
+        parts.push(resource.summary);
+    if (resource.description)
+        parts.push('', resource.description);
+    if (resource.object && resource.object.fields.length > 0) {
+        parts.push('', `Object: ${resource.object.name}`, ...renderShapeTree(resource.object.fields, '  '));
+    }
+    const ops = resource.operationIds
+        // Object.hasOwn guards the prototype chain (matching the argv-driven lookups):
+        // `manifest.operations` is a Zod `z.record` plain object, so a stray operationId
+        // that's a JS prototype key (constructor/valueOf/…) would otherwise resolve to a
+        // truthy inherited member, survive the filter, and render as garbage.
+        .map((opId) => Object.hasOwn(manifest.operations, opId) ? manifest.operations[opId] : undefined)
+        .filter((op) => op !== undefined)
+        .sort((a, b) => a.callPath.join(' ').localeCompare(b.callPath.join(' '), 'en'));
+    if (ops.length > 0) {
+        parts.push('', 'Operations:');
+        for (const op of ops)
+            parts.push(`  ${operationInvocation(op)} — ${op.summary}`);
+    }
+    const opIds = new Set(resource.operationIds);
+    const recipes = Object.values(manifest.recipes)
+        .filter((r) => r.steps.some((s) => s.operationId !== undefined && opIds.has(s.operationId)))
+        .sort((a, b) => a.id.localeCompare(b.id, 'en'));
+    if (recipes.length > 0) {
+        parts.push('', 'Recipes that use this:');
+        for (const r of recipes)
+            parts.push(`  ${r.id} — ${r.title}`);
+    }
+    return `${parts.join('\n')}\n`;
+}
+/** `rl recipes [<id>]` — How-to (list grouped by category, or one recipe). */
+function addRecipesCommand(program, manifest, io) {
+    program
+        .command('recipes [id]')
+        .helpGroup(DOCS_HELP_GROUP)
+        .description('Browse documented recipes — multi-step, user-goal guides for the app')
+        .option('--format <format>', `Output format: ${Object.keys(RECIPE_FORMATS).join(' | ')}`, 'cli')
+        .action((id, opts) => {
+        if (id === undefined) {
+            io.stdout(renderRecipeList(manifest.recipes));
+            return;
+        }
+        // Object.hasOwn guards the prototype chain (see the resources hub above).
+        const entry = Object.hasOwn(manifest.recipes, id) ? manifest.recipes[id] : undefined;
+        if (!entry) {
+            throw new Error(`unknown recipe "${id}". Run \`rl recipes\` to see all recipes.`);
+        }
+        const format = opts.format ?? 'cli';
+        // `Object.hasOwn`, not `format in RECIPE_FORMATS`: `in` walks the prototype
+        // chain, so `--format toString` (or valueOf/constructor/__proto__/…) would
+        // pass and then crash in renderRecipeShow with an unactionable TypeError.
+        // Mirrors `resolveSkill`'s own-key check in skills.controller.ts.
+        if (!isRecipeFormat(format)) {
+            throw new Error(`invalid --format "${format}" (expected: ${Object.keys(RECIPE_FORMATS).join(', ')})`);
+        }
+        io.stdout(renderRecipeShow(entry, format, manifest.recipes));
+    });
+}
+/** The full catalog, grouped by category, for `rl recipes`. */
+export function renderRecipeList(reference) {
+    const entries = Object.values(reference);
+    if (entries.length === 0)
+        return 'No recipes are available.\n';
+    const byCategory = new Map();
+    for (const entry of entries) {
+        const group = byCategory.get(entry.category) ?? [];
+        group.push(entry);
+        byCategory.set(entry.category, group);
+    }
+    const lines = ['Recipes — run `rl recipes <id>` for the full walkthrough.', ''];
+    for (const category of [...byCategory.keys()].sort()) {
+        lines.push(category);
+        const group = byCategory.get(category) ?? [];
+        for (const entry of group.sort((a, b) => a.id.localeCompare(b.id, 'en'))) {
+            lines.push(`  ${entry.id} — ${entry.title}`);
+            lines.push(`    ${entry.goal}`);
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+/**
+ * The "Related" + "Unblocks" block for a recipe — its place in the graph. The
+ * stored links (`requires` / `variationOf` / `learnMore`) come off the recipe;
+ * **Unblocks** is *derived* (never stored): the recipes that name THIS one as a
+ * `requires` recipe, so an agent reading one recipe sees both what to do first
+ * and where it can go next. Returns `''` when the recipe is an island.
+ */
+export function renderRelatedBlock(entry, allRecipes) {
+    const related = entry.related;
+    const lines = [];
+    const requires = related?.requires ?? [];
+    if (requires.length > 0) {
+        lines.push('  Requires');
+        for (const req of requires) {
+            if (req.type === 'recipe') {
+                lines.push(`    • ${req.id}`);
+            }
+            else {
+                const via = req.via ? `   (via ${req.via.id})` : '';
+                lines.push(`    • state: ${req.explanation}${via}`);
+            }
+        }
+    }
+    if (related?.variationOf) {
+        lines.push('  Variation of');
+        lines.push(`    • ${related.variationOf}`);
+    }
+    const learnMore = related?.learnMore ?? [];
+    if (learnMore.length > 0) {
+        lines.push('  Learn more');
+        for (const target of learnMore)
+            lines.push(`    • ${target.type}: ${target.id}`);
+    }
+    // Unblocks — the inverse of `requires` (this recipe is a prerequisite of …).
+    // Matches the same edge set the cycle gate walks + the skill traverses: a
+    // direct `recipe` requirement AND a `state` requirement reached `via` this
+    // recipe, so the three surfaces agree on what counts as a prerequisite edge.
+    const unblocks = Object.values(allRecipes)
+        .filter((r) => (r.related?.requires ?? []).some((q) => (q.type === 'recipe' && q.id === entry.id) ||
+        (q.type === 'state' && q.via?.type === 'recipe' && q.via.id === entry.id)))
+        .map((r) => r.id)
+        .sort((a, b) => a.localeCompare(b, 'en'));
+    if (unblocks.length > 0) {
+        lines.push('  Unblocks');
+        for (const id of unblocks)
+            lines.push(`    • ${id}`);
+    }
+    return lines.length > 0 ? `Related\n${lines.join('\n')}\n` : '';
+}
+/** One recipe rendered for `rl recipes <id>`: goal + composed code + related links + a docs link. */
+export function renderRecipeShow(entry, format, allRecipes) {
+    const { setup, main } = entry[RECIPE_FORMATS[format]];
+    const snippet = [setup, main].filter(Boolean).join('\n\n');
+    const relatedBlock = renderRelatedBlock(entry, allRecipes);
+    return [
+        entry.title,
+        entry.goal,
+        '',
+        snippet,
+        '',
+        ...(relatedBlock ? [relatedBlock] : []),
+        // "Full docs", not "Learn more": the Related block above already has a
+        // "Learn more" subsection (related concepts/tutorials), and two same-named
+        // labels in agent-facing output is confusing. This is the recipe's own page.
+        `Full docs: ${RECIPE_DOCS_BASE_URL}/admin/docs?page=recipe:${entry.id}`,
+        '',
+    ].join('\n');
+}
+/** `rl explain [<concept>]` — Explanation (list grouped by domain, or one page). */
+function addExplainCommand(program, manifest, io) {
+    program
+        .command('explain [concept]')
+        .helpGroup(DOCS_HELP_GROUP)
+        .description('Browse explanation concept pages (run without an argument to list all)')
+        .action((concept) => {
+        if (concept === undefined) {
+            io.stdout(renderConceptList(manifest));
+            return;
+        }
+        // Object.hasOwn guards the prototype chain (see the resources hub above).
+        const entry = Object.hasOwn(manifest.concepts, concept)
+            ? manifest.concepts[concept]
+            : undefined;
+        if (!entry) {
+            throw new Error(`unknown concept "${concept}". Run \`rl explain\` to list concepts.`);
+        }
+        io.stdout(renderConceptShow(entry));
+    });
+}
+function renderConceptList(manifest) {
+    const groups = groupByDomain(Object.values(manifest.concepts), (c) => c.domain, manifest.domains);
+    const lines = ['Explanations — run `rl explain <concept>` for the full page.', ''];
+    for (const group of groups) {
+        lines.push(group.title);
+        for (const c of group.entries.sort((a, b) => a.id.localeCompare(b.id, 'en'))) {
+            lines.push(`  ${c.id} — ${c.title}`);
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderConceptShow(concept) {
+    const parts = [concept.body];
+    if (concept.related.length > 0) {
+        // Strip the `resource:` / `recipe:` / `concept:` kind prefix for a clean footer.
+        const related = concept.related.map((slug) => slug.replace(/^[a-z]+:/u, ''));
+        parts.push('', `Related: ${related.join(' · ')}`);
+    }
+    return `${parts.join('\n')}\n`;
+}
+/** `rl tutorials [<id>]` — Tutorials (the existing getting-started docs). */
+function addTutorialsCommand(program, manifest, io) {
+    program
+        .command('tutorials [id]')
+        .helpGroup(DOCS_HELP_GROUP)
+        .description('Browse getting-started tutorials (run without an argument to list all)')
+        .action((id) => {
+        if (id === undefined) {
+            const lines = ['Tutorials — run `rl tutorials <id>` for the full text.', ''];
+            for (const t of manifest.tutorials)
+                lines.push(`  ${t.id} — ${t.title}`);
+            io.stdout(`${lines.join('\n')}\n`);
+            return;
+        }
+        const entry = manifest.tutorials.find((t) => t.id === id);
+        if (!entry) {
+            throw new Error(`unknown tutorial "${id}". Run \`rl tutorials\` to list tutorials.`);
+        }
+        if (entry.body === null) {
+            io.stdout(`${entry.title}\n\nThis tutorial is a notebook — open it in the app: ` +
+                `${RECIPE_DOCS_BASE_URL}/admin/docs?page=${entry.id}\n`);
+            return;
+        }
+        io.stdout(`${entry.body}\n`);
+    });
+}
+/** The program shell — name, description, version, and the global options. */
+export function buildBaseProgram(version, io) {
+    return (new Command('rl')
+        // Route commander's own output (help text, unknown-command errors, invalid
+        // option values) through the caller's sinks, and turn its `process.exit`
+        // calls into thrown `CommanderError`s.
+        //
+        // Both settings MUST be applied here, on the root, *before* any `.command()`
+        // call: commander copies `_outputConfiguration` and `_exitCallback` onto a
+        // subcommand at creation time (`copyInheritedSettings`), so applying them
+        // after the tree is built would leave every subcommand still writing to the
+        // process streams and still calling `process.exit`.
+        .configureOutput({ writeOut: io.stdout, writeErr: io.stderr })
+        .exitOverride()
+        .description('Command-line interface for the Recursion RL platform')
+        .version(version)
+        .option('--api-key <key>', 'API key (defaults to the LABELBOX_API_KEY env var)')
+        .option('--base-url <url>', 'Recursion API base URL (defaults to the RECURSION_BASE_URL env var, then the production host)')
+        .option('--quiet', 'Output only the resulting resource id (JSON otherwise)'));
+}
+/** Build the full `rl` program from a fetched manifest. */
+export function buildProgram(manifest, ctx) {
+    // `ctx` structurally satisfies CliIo, so the root program — and by inheritance
+    // every command built below — writes to the caller's sinks and never exits.
+    const program = buildBaseProgram(ctx.version, ctx);
+    // Cache of group (non-leaf) commands by their joined path prefix so siblings
+    // share intermediate nodes (and each gets its own `--help`).
+    const groups = new Map();
+    // Parents whose `--help` should carry the unavailable-command banner.
+    const gatedCountByParent = new Map();
+    // Register a child command, failing fast if its name already exists under this
+    // parent (or shadows a reserved top-level group). `kebab()` is non-injective and
+    // commander registers duplicates silently — resolving `.find()` to the first — so
+    // a colliding op would otherwise become an unreachable command with no error.
+    const claim = (parent, name, source) => {
+        const clashesReserved = parent === program && RESERVED_COMMANDS.has(name);
+        if (clashesReserved || parent.commands.some((c) => c.name() === name)) {
+            throw new Error(`${source} maps to command "${name}"${parent === program ? '' : ` under "${parent.name()}"`}, ` +
+                'which is already taken — two operations’ call paths collide (or one hits a reserved ' +
+                'top-level command). Rename one in the backend spec.');
+        }
+        return parent.command(name);
+    };
+    const entries = Object.values(manifest.operations).sort((a, b) => {
+        const aDenied = missingPermission(a, ctx.granted) !== undefined ? 1 : 0;
+        const bDenied = missingPermission(b, ctx.granted) !== undefined ? 1 : 0;
+        if (aDenied !== bDenied)
+            return aDenied - bDenied;
+        return a.callPath.join(' ').localeCompare(b.callPath.join(' '), 'en');
+    });
+    for (const entry of entries) {
+        const parents = entry.callPath.slice(0, -1);
+        const leaf = entry.callPath[entry.callPath.length - 1];
+        if (leaf === undefined)
+            continue;
+        let parent = program;
+        let prefix = '';
+        for (const segment of parents) {
+            const key = prefix === '' ? segment : `${prefix}.${segment}`;
+            let group = groups.get(key);
+            if (!group) {
+                // Label the group with its resource's one-line summary. The synthesizer's
+                // tag is singular while its namespace is plural, so fall back to the
+                // singular form; sub-namespaces match no resource and keep a generic label.
+                const groupName = kebab(segment);
+                const resourceFor = (key) => Object.hasOwn(manifest.resources, key) ? manifest.resources[key] : undefined;
+                const resource = resourceFor(groupName) ?? resourceFor(groupName.replace(/s$/u, ''));
+                group = claim(parent, groupName, `operation "${entry.operationId}"`).description(resource?.summary ?? `${groupName} commands`);
+                if (parent === program)
+                    group.helpGroup(ACTIONS_HELP_GROUP);
+                groups.set(key, group);
+            }
+            parent = group;
+            prefix = key;
+        }
+        // The first required permission the caller lacks (undefined → runnable /
+        // ungated / fail-open). Drives the listing marker, the help note, and the
+        // pre-emptive invocation error from one source so they always agree.
+        const missing = missingPermission(entry, ctx.granted);
+        const leafCommand = claim(parent, kebab(leaf), `operation "${entry.operationId}"`).description(gatedSummary(entry.summary, missing));
+        if (parent === program) {
+            leafCommand.helpGroup(missing === undefined ? ACTIONS_HELP_GROUP : UNAVAILABLE_HELP_GROUP);
+        }
+        else if (missing === undefined) {
+            leafCommand.helpGroup(COMMANDS_HELP_GROUP);
+        }
+        else {
+            leafCommand.helpGroup(UNAVAILABLE_HELP_GROUP);
+            gatedCountByParent.set(parent, (gatedCountByParent.get(parent) ?? 0) + 1);
+        }
+        addOptions(leafCommand, entry, ctx.localCheckout);
+        leafCommand.addHelpText('after', leafShapeHelp(entry));
+        if (missing !== undefined)
+            leafCommand.addHelpText('after', permissionHelpNote(missing));
+        leafCommand.action(async (localOpts) => {
+            try {
+                // Pre-empt a doomed request with a clear local error, instead of letting
+                // it round-trip to a server 403.
+                if (missing !== undefined)
+                    throw new Error(permissionDeniedMessage(missing));
+                const params = assembleParams(entry, localOpts, parseBodyBase(localOpts));
+                const result = await dispatchOperation(entry, params, {
+                    apiKey: ctx.apiKey,
+                    baseUrl: ctx.baseUrl,
+                });
+                const global = program.opts();
+                ctx.stdout(formatOutput(result, global.quiet === true));
+            }
+            catch (err) {
+                // Normalize to an Error carrying the rendered text, then rethrow: commander
+                // rejects `parseAsync`, and `run()` is the single place that renders
+                // `error: <message>`. Dispatch throws the server's raw JSON error body (not
+                // an Error), so formatting has to happen here, while that shape is intact.
+                throw new Error(formatError(err));
+            }
+        });
+    }
+    for (const [parent, gatedCount] of gatedCountByParent) {
+        parent.addHelpText('before', permissionGroupBanner(gatedCount));
+    }
+    // The docs browse groups + the bespoke `rl skills` action group.
+    addResourcesCommand(program, manifest, ctx);
+    addRecipesCommand(program, manifest, ctx);
+    addExplainCommand(program, manifest, ctx);
+    addTutorialsCommand(program, manifest, ctx);
+    if (ctx.localCheckout) {
+        addSkillsCommands(program, DOCS_HELP_GROUP);
+        addGitHostCommands(program, GIT_HOST_HELP_GROUP);
+    }
+    program.configureHelp({ sortSubcommands: true });
+    program.commandsGroup(DOCS_HELP_GROUP);
+    // Lazy implicit help skips _initCommandGroup unless created via helpCommand(true).
+    program.helpCommand(true);
+    program.addHelpText('after', `
+Run \`rl <command> --help\` for details and flags on any command.
+Browse the full reference with \`rl resources\`, or guided walkthroughs with \`rl recipes\`.`);
+    return program;
+}