@labelbox/recursion-cli 0.0.0 → 0.0.42

package/dist/manifest.js

@@ -0,0 +1,415 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+// The live CLI fetches its entire command surface — operations, request/response
+// shapes, and the docs browse data (resources / recipes / concepts / tutorials) —
+// from `GET /cli/manifest` on whatever server `--base-url` points at, instead of
+// baking a compiled-in `@labelbox/recursion-sdk` reference. This module owns:
+//   1. the manifest's runtime Zod schema + TS types (the validation boundary), and
+//   2. `fetchManifest` — a conditional-fetch cache (ETag / If-None-Match) that can
+//      never serve stale data and needs no manual busting.
+// The schema lives here, not in sdk-ts: the CLI no longer depends on that package
+// (see the plan's standalone-CLI decision). The backend embeds the same manifest at
+// build time (`dx manifest:generate`); this is the consumer mirror.
+/**
+ * The DEFAULT production base URL: the public API gateway origin. No path
+ * suffix — the API version lives in each operation's path (`/v1/...`), so the
+ * CLI joins this origin with the manifest's paths verbatim.
+ *
+ * Keep in sync with `DEFAULT_BASE_URL` in `packages/sdk-ts/src/index.ts`,
+ * `PUBLIC_API_BASE_URL` in `packages/sdk-ts/openapi-ts.config.ts`, and
+ * `CURL_BASE_URL` in `tools/dx/src/commands/sdk.ts`.
+ */
+export const DEFAULT_BASE_URL = 'https://api.recursion.labelbox.com';
+/**
+ * The platform's API version segment, as it appears in every canonical path.
+ *
+ * Spec-derived operations get this for free — `buildUrl` joins the manifest's
+ * `op.path`, which already carries it. The CLI's few HAND-WRITTEN support calls
+ * (`/cli/manifest`, `/me/permissions`, `/skills`) have no manifest entry to read
+ * it from, so they must supply it themselves via `supportUrl` below. Omitting it
+ * is a 404 against a bare-origin base URL, and `fetchManifest` treats a 404 as
+ * fatal (only a *network* error falls back to cache), so the CLI cannot build any
+ * command at all — the reason this is a single helper rather than three string
+ * literals.
+ */
+const API_VERSION_SEGMENT = 'v1';
+/**
+ * Join a hand-written support-endpoint path onto the base URL, under the API
+ * version segment. `path` is version-relative and must start with `/`.
+ */
+export function supportUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/$/u, '')}/${API_VERSION_SEGMENT}${path}`;
+}
+/**
+ * The manifest format the engine understands. Bumped only on a *breaking* schema
+ * change (a renamed/removed required field, a changed enum) — additive fields are
+ * backward-compatible because the schema strips unknown keys rather than rejecting
+ * them, so a newer server never breaks an older CLI by adding data. A mismatch is
+ * surfaced with an actionable upgrade message at the validation boundary.
+ */
+export const MANIFEST_FORMAT_VERSION = 1;
+const ScalarValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+// Lenient (no `.strict()`): unknown keys are stripped, never rejected — this is
+// what makes an additive backend change safe for an older CLI (see the format-version
+// note above). Recursive fields defer via `z.lazy` to the exported alias below.
+const ShapeNodeObjectSchema = z.object({
+    name: z.string().optional(),
+    type: z.string(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    itemEnum: z.array(z.string()).optional(),
+    default: ScalarValueSchema.optional(),
+    format: z.string().optional(),
+    example: ScalarValueSchema.optional(),
+    nullable: z.boolean().optional(),
+    minimum: z.number().optional(),
+    maximum: z.number().optional(),
+    exclusiveMinimum: z.number().optional(),
+    exclusiveMaximum: z.number().optional(),
+    minLength: z.number().optional(),
+    maxLength: z.number().optional(),
+    minItems: z.number().optional(),
+    maxItems: z.number().optional(),
+    pattern: z.string().optional(),
+    fields: z.array(z.lazy(() => ShapeNodeSchema)).optional(),
+    items: z.lazy(() => ShapeNodeSchema).optional(),
+    variants: z.array(z.lazy(() => ShapeNodeSchema)).optional(),
+});
+export const ShapeNodeSchema = ShapeNodeObjectSchema;
+function shapeMetaKeys(values) {
+    return values;
+}
+// Canonical render order. The helper requires every ShapeMetaKey exactly once
+// and rejects extra keys, keeping this in sync with ShapeNode and CLI_META_LABELS.
+const SHAPE_META_KEYS = shapeMetaKeys([
+    'enum',
+    'itemEnum',
+    'default',
+    'format',
+    'example',
+    'minimum',
+    'exclusiveMinimum',
+    'maximum',
+    'exclusiveMaximum',
+    'minLength',
+    'maxLength',
+    'minItems',
+    'maxItems',
+    'pattern',
+    'nullable',
+]);
+/** A node's present metadata as ordered `[key, value]` pairs (drives the CLI tags). */
+export function shapeMetaEntries(node) {
+    const entries = [];
+    for (const key of SHAPE_META_KEYS) {
+        const value = node[key];
+        if (value === undefined)
+            continue;
+        if (key === 'enum' || key === 'itemEnum') {
+            if (Array.isArray(value) && value.length > 0)
+                entries.push([key, value]);
+        }
+        else if (key === 'nullable') {
+            if (value === true)
+                entries.push([key, true]);
+        }
+        else if (key === 'exclusiveMinimum') {
+            entries.push([key, `>${value}`]);
+        }
+        else if (key === 'exclusiveMaximum') {
+            entries.push([key, `<${value}`]);
+        }
+        else {
+            entries.push([key, value]);
+        }
+    }
+    return entries;
+}
+// ── Operations — the executable command surface ──────────────────────────────
+/** A request param: a named shape node plus its HTTP location (for generic dispatch). */
+export const ManifestParamSchema = ShapeNodeObjectSchema.extend({
+    name: z.string(),
+    required: z.boolean(),
+    in: z.enum(['path', 'query', 'body']),
+});
+/**
+ * One operation, carrying everything the CLI needs to build its command and
+ * dispatch generically: the `callPath` (command tree), the `httpMethod` + `path`
+ * template + `params[].in` + `bodyKey` (dispatch), and the recursive request/response
+ * shapes (`--help`). Mirrors the relevant subset of sdk-ts's `SdkReferenceEntry`.
+ */
+export const ManifestOperationSchema = z.object({
+    operationId: z.string(),
+    callPath: z.array(z.string()).min(1),
+    summary: z.string(),
+    description: z.string().optional(),
+    httpMethod: z.enum(['get', 'post', 'put', 'patch', 'delete']),
+    path: z.string(),
+    bodyKey: z.string().optional(),
+    // Permissions the caller must hold to run this command (from the backend's
+    // `@RequirePermissions`). Absent → the command is never gated. The CLI marks
+    // commands the caller can't run and pre-empts them with a clear error, checked
+    // against the caller's `/me/permissions` set (see permissions.ts).
+    requiredPermissions: z.array(z.string()).optional(),
+    params: z.array(ManifestParamSchema),
+    response: ShapeNodeSchema.optional(),
+});
+// ── Resources — the Reference browse surface (`rl resources [<id>]`) ──────────
+const ManifestResourceObjectSchema = z.object({
+    name: z.string(),
+    fields: z.array(ShapeNodeSchema),
+});
+export const ManifestResourceSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    parent: z.string().optional(),
+    order: z.number(),
+    domain: z.string().optional(),
+    summary: z.string().optional(),
+    description: z.string().optional(),
+    object: ManifestResourceObjectSchema.optional(),
+    operationIds: z.array(z.string()),
+});
+// ── Recipes — the How-to browse surface (`rl recipes [<id>]`) ─────────────────
+const RecipeSnippetSchema = z.object({ setup: z.string(), main: z.string() });
+// Steps are read only to map a recipe to the resources it touches (via each SDK
+// step's operationId), so they're modeled loosely — just the fields the CLI uses.
+const ManifestRecipeStepSchema = z.object({ operationId: z.string().optional() });
+// A recipe's place in the relationship graph (mirrors `RecipeRelated` in
+// sdk-ts's recipes-schema). Modeled loosely here — the CLI only reads these to
+// render the "Related" / "Unblocks" block on `rl recipes <id>`; the generator
+// is the source of truth that validates them. Without these fields the manifest
+// parse would silently strip `related`, so the CLI would never see the links.
+const ManifestLinkTargetSchema = z.object({
+    type: z.enum(['recipe', 'concept', 'tutorial', 'resource']),
+    id: z.string(),
+});
+const ManifestRequiresEntrySchema = z.union([
+    z.object({ type: z.literal('recipe'), id: z.string() }),
+    z.object({
+        type: z.literal('state'),
+        explanation: z.string(),
+        predicate: z.string().optional(),
+        via: ManifestLinkTargetSchema.optional(),
+    }),
+]);
+export const ManifestRelatedSchema = z.object({
+    requires: z.array(ManifestRequiresEntrySchema).optional(),
+    variationOf: z.string().optional(),
+    learnMore: z.array(ManifestLinkTargetSchema).optional(),
+});
+export const ManifestRecipeSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    goal: z.string(),
+    category: z.string(),
+    steps: z.array(ManifestRecipeStepSchema),
+    sdk: RecipeSnippetSchema,
+    // Optional on the WIRE, though the producer always emits it. The
+    // version-mismatch check is a strict `!==` in both directions, so making this
+    // required would abort the whole command tree of every already-installed CLI
+    // the moment a newer server deployed — for a docs-only field an older CLI
+    // would otherwise just strip. `manifest.test.ts` asserts the producer emits
+    // every key this schema declares, so the field is still guaranteed present in
+    // practice without a required-field bump. See `.claude/rules/packages-cli.md`:
+    // a backend change must need no CLI release.
+    python: RecipeSnippetSchema.optional(),
+    cli: RecipeSnippetSchema,
+    curl: RecipeSnippetSchema,
+    // The recipe's relationship links (optional — absent for an island recipe).
+    related: ManifestRelatedSchema.optional(),
+});
+// ── Concepts — the Explanation browse surface (`rl explain [<concept>]`) ──────
+export const ManifestConceptSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    domain: z.string(),
+    related: z.array(z.string()),
+    // The markdown body, added by the assembler (the generated reference holds only
+    // metadata — the frontend fetches the `.md` separately; the CLI bundles it).
+    body: z.string(),
+});
+// ── Tutorials — the getting-started docs (`rl tutorials [<id>]`) ──────────────
+export const ManifestTutorialSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    // The markdown prose, or `null` for a notebook (listed as a link, never dumped).
+    body: z.string().nullable(),
+});
+// ── Domains — the product taxonomy that groups the browse surfaces ────────────
+export const ManifestDomainSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    order: z.number(),
+});
+// ── The envelope ─────────────────────────────────────────────────────────────
+export const ManifestSchema = z.object({
+    formatVersion: z.number(),
+    hash: z.string(),
+    operations: z.record(z.string(), ManifestOperationSchema),
+    resources: z.record(z.string(), ManifestResourceSchema),
+    recipes: z.record(z.string(), ManifestRecipeSchema),
+    concepts: z.record(z.string(), ManifestConceptSchema),
+    tutorials: z.array(ManifestTutorialSchema),
+    domains: z.array(ManifestDomainSchema),
+});
+/**
+ * Validate a fetched/cached manifest at the I/O boundary and check engine↔manifest
+ * format compatibility. A version mismatch is the one case worth an actionable
+ * message: the schema itself stays lenient (so additive server changes are safe),
+ * and only a deliberate format bump trips this.
+ */
+export function parseManifest(value, source) {
+    // Peek at the format version BEFORE the full-shape parse. The version bumps only
+    // on a *breaking* schema change (renamed/removed required field, changed enum) —
+    // which would also fail `ManifestSchema.safeParse`. Validating shape first would
+    // therefore shadow the actionable upgrade hint with a generic zod dump for exactly
+    // the case the version field exists to flag.
+    const versionPeek = z.object({ formatVersion: z.number() }).safeParse(value);
+    if (versionPeek.success && versionPeek.data.formatVersion !== MANIFEST_FORMAT_VERSION) {
+        const { formatVersion } = versionPeek.data;
+        const direction = formatVersion > MANIFEST_FORMAT_VERSION
+            ? // No uninstall hint here: anyone who can print this message is already
+                // running @labelbox/recursion-cli, which per the EEXIST bin collision
+                // means no pre-rename package (@labelbox/rl-cli, or the older
+                // @recursion/cli) owns the `rl` bin. A pre-rename user sees the
+                // pre-rename binary's own message instead.
+                'this `rl` CLI is out of date — upgrade it (`npm install -g @labelbox/recursion-cli`)'
+            : 'the server is older than this CLI — point --base-url at an up-to-date server';
+        throw new Error(`command-manifest format mismatch: this CLI speaks v${MANIFEST_FORMAT_VERSION}, ` +
+            `${source} served v${formatVersion}. ${direction}.`);
+    }
+    const parsed = ManifestSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`the command manifest from ${source} has an unexpected shape: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+// ── Conditional-fetch cache (no TTL, never hand-busted) ──────────────────────
+/** What we persist per base-url: the transport ETag + the last manifest payload. */
+const CacheSchema = z.object({ etag: z.string().optional(), manifest: z.unknown() });
+/**
+ * A filesystem-safe, collision-free slug for a base URL, so each server caches
+ * independently. The readable part is the sanitized URL (handy when eyeballing the
+ * cache dir); a short hash of the *full* URL is appended so two URLs that sanitize
+ * to the same string (e.g. `https://x.com:8080` vs `https://x-com-8080`) still get
+ * distinct cache files rather than silently sharing — and poisoning — one.
+ */
+function hostSlug(baseUrl) {
+    const readable = baseUrl.replace(/[^a-zA-Z0-9]+/gu, '-').replace(/^-+|-+$/gu, '') || 'default';
+    const hash = createHash('sha256').update(baseUrl, 'utf8').digest('hex').slice(0, 8);
+    return `${readable}-${hash}`;
+}
+function cachePathFor(baseUrl) {
+    return join(homedir(), '.cache', 'rl-gym', `${hostSlug(baseUrl)}.json`);
+}
+function readCache(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return undefined; // corrupt cache → treat as cold (will refetch).
+    }
+    const parsed = CacheSchema.safeParse(json);
+    if (!parsed.success)
+        return undefined;
+    // The stored manifest must still parse for the cache to be usable. A cache whose
+    // body is corrupt — or in a format this CLI rejects — must NOT seed `If-None-Match`:
+    // a 304 would reuse the bad payload and trap the CLI in a revalidation loop the
+    // server can never break (it keeps answering 304, so no fresh 200 body ever
+    // arrives). Treating it as cold lets the next fetch pull — and re-cache — a full
+    // body, so the CLI self-heals without a manual cache delete.
+    try {
+        return { etag: parsed.data.etag, manifest: parseManifest(parsed.data.manifest, 'the cache') };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(path, entry) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(entry));
+    }
+    catch {
+        // A non-writable cache dir is a bandwidth optimization lost, not a failure —
+        // the command still ran off the fetched manifest. Stay silent.
+    }
+}
+// Every `rl` invocation gates on this fetch, so it must be bounded: a server that
+// accepts the connection but never responds (a hung gateway, a stalled captive
+// portal) would otherwise hang the CLI forever. A timeout makes `fetch` reject, so
+// the catch below degrades to the cached manifest (or the clear cold-cache error).
+const MANIFEST_FETCH_TIMEOUT_MS = 30_000;
+/**
+ * Fetch the command manifest, revalidating the cache on every run:
+ *   - send `If-None-Match` with the cached ETag → `304` means the cache is provably
+ *     current (use it); `200` means the surface changed (validate + replace cache).
+ *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
+ *     with no cache it errors clearly.
+ * The cache therefore can never serve stale data and never needs manual busting — a
+ * backend redeploy is picked up automatically on the next command.
+ */
+export async function fetchManifest(baseUrl, apiKey) {
+    const url = supportUrl(baseUrl, '/cli/manifest');
+    const cachePath = cachePathFor(baseUrl);
+    const cached = readCache(cachePath);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+                Authorization: `Bearer ${apiKey}`,
+                // `If-None-Match` is a quoted string key, so it needs no naming-convention suppression.
+                ...(cached?.etag ? { 'If-None-Match': cached.etag } : {}),
+            },
+            signal: AbortSignal.timeout(MANIFEST_FETCH_TIMEOUT_MS),
+        });
+    }
+    catch {
+        if (cached) {
+            process.stderr.write(`warning: could not reach ${url} — using the cached command manifest.\n`);
+            return cached.manifest; // validated when read.
+        }
+        throw new Error(`could not reach ${url} to fetch the command manifest, and no cached copy exists ` +
+            '(check --base-url and your network).');
+    }
+    if (res.status === 304 && cached) {
+        return cached.manifest; // validated when read.
+    }
+    if (res.status === 401 || res.status === 403) {
+        throw new Error(`API key rejected fetching the command manifest (HTTP ${res.status})`);
+    }
+    if (!res.ok) {
+        throw new Error(`could not fetch the command manifest from ${url} — HTTP ${res.status}`);
+    }
+    // A 200 isn't a guarantee of JSON — a captive portal / reverse-proxy login page
+    // returns HTML, a misconfigured gateway an empty body. `res.json()` would throw a
+    // raw `SyntaxError` ("Unexpected token '<'…") that reaches the user as an
+    // unactionable `error:` line; surface a clear one instead, matching how
+    // `parseManifest` and `dispatch.ts` degrade.
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch {
+        throw new Error(`the command manifest from ${url} was not valid JSON — check that --base-url ` +
+            'points at a recursion API (not a login page or proxy).');
+    }
+    const manifest = parseManifest(json, url);
+    writeCache(cachePath, { etag: res.headers.get('etag') ?? undefined, manifest: json });
+    return manifest;
+}

package/dist/permissions.d.ts

@@ -0,0 +1,31 @@
+import { type ManifestOperation } from './manifest.js';
+/**
+ * The caller's granted permission entries, or `undefined` when they couldn't be
+ * determined (fetch failed, or the server returned an empty set). `undefined`
+ * means "unknown" → gate nothing.
+ */
+export type GrantedPermissions = ReadonlySet<string> | undefined;
+/**
+ * Fetch the caller's granted permissions. Never throws: any error (network,
+ * non-2xx, non-JSON, wrong shape) resolves to `undefined` (fail-open). An empty
+ * array also resolves to `undefined` — the backend returns `[]` for callers with
+ * no computed permissions (local/standalone/S2S), where enforcement is bypassed,
+ * so the CLI must not treat that as "deny everything". (An E2E caller with a
+ * present-but-empty `X-Permissions` also gets `[]` here; the backend would 403,
+ * but the CLI only skips local pre-emption — it does not hide or allow the call.)
+ */
+export declare function fetchPermissions(baseUrl: string, apiKey: string): Promise<GrantedPermissions>;
+/**
+ * Whether a granted set satisfies a single required permission. Mirrors
+ * `hasPermission` in `@recursion/shared` — the CLI can't depend on that private
+ * package, and (like the manifest schema) re-declares the tiny bit it needs.
+ * Wildcards: `*` grants everything; `resource:*` grants all actions on a resource.
+ */
+export declare function hasPermission(granted: ReadonlySet<string>, required: string): boolean;
+/**
+ * The first required permission the caller lacks, or `undefined` when the command
+ * is runnable — because it's ungated (no `requiredPermissions`), the caller holds
+ * all of them, or permissions are unknown (fail-open). Drives both the `--help`
+ * marker and the pre-emptive error on invocation, so they always agree.
+ */
+export declare function missingPermission(op: ManifestOperation, granted: GrantedPermissions): string | undefined;

package/dist/permissions.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { supportUrl } from './manifest.js';
+/** `/me/permissions` returns a bare JSON array of permission-entry strings. */
+const PermissionsResponseSchema = z.array(z.string());
+// Bound the fetch so a hung gateway can't stall the CLI (mirrors the manifest
+// fetch). On any failure we fall back to the fail-open "unknown" set.
+const PERMISSIONS_FETCH_TIMEOUT_MS = 30_000;
+/**
+ * Fetch the caller's granted permissions. Never throws: any error (network,
+ * non-2xx, non-JSON, wrong shape) resolves to `undefined` (fail-open). An empty
+ * array also resolves to `undefined` — the backend returns `[]` for callers with
+ * no computed permissions (local/standalone/S2S), where enforcement is bypassed,
+ * so the CLI must not treat that as "deny everything". (An E2E caller with a
+ * present-but-empty `X-Permissions` also gets `[]` here; the backend would 403,
+ * but the CLI only skips local pre-emption — it does not hide or allow the call.)
+ */
+export async function fetchPermissions(baseUrl, apiKey) {
+    const url = supportUrl(baseUrl, '/me/permissions');
+    let res;
+    try {
+        res = await fetch(url, {
+            // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(PERMISSIONS_FETCH_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (!res.ok)
+        return undefined;
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = PermissionsResponseSchema.safeParse(json);
+    if (!parsed.success || parsed.data.length === 0)
+        return undefined;
+    return new Set(parsed.data);
+}
+/**
+ * Whether a granted set satisfies a single required permission. Mirrors
+ * `hasPermission` in `@recursion/shared` — the CLI can't depend on that private
+ * package, and (like the manifest schema) re-declares the tiny bit it needs.
+ * Wildcards: `*` grants everything; `resource:*` grants all actions on a resource.
+ */
+export function hasPermission(granted, required) {
+    if (granted.has('*'))
+        return true;
+    if (granted.has(required))
+        return true;
+    const resource = required.split(':')[0];
+    if (resource === undefined || resource === '')
+        return false;
+    return granted.has(`${resource}:*`);
+}
+/**
+ * The first required permission the caller lacks, or `undefined` when the command
+ * is runnable — because it's ungated (no `requiredPermissions`), the caller holds
+ * all of them, or permissions are unknown (fail-open). Drives both the `--help`
+ * marker and the pre-emptive error on invocation, so they always agree.
+ */
+export function missingPermission(op, granted) {
+    if (granted === undefined)
+        return undefined;
+    const required = op.requiredPermissions;
+    if (!required || required.length === 0)
+        return undefined;
+    return required.find((perm) => !hasPermission(granted, perm));
+}

package/dist/program.d.ts

@@ -0,0 +1,113 @@
+import { Command } from 'commander';
+import type { Manifest, ManifestOperation, ManifestRecipe, ShapeNode } from './manifest.js';
+import { type GrantedPermissions } from './permissions.js';
+/** camelCase → kebab-case for command + flag names (was `@labelbox/recursion-sdk/nesting`). */
+export declare function kebab(value: string): string;
+/** Coerce a string flag value to its declared scalar type. */
+export declare function coerce(value: unknown, type: string): unknown;
+/**
+ * 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 declare function assembleParams(entry: ManifestOperation, opts: Record<string, unknown>, bodyBase: Record<string, unknown>): Record<string, unknown>;
+export declare function parseBodyBase(opts: Record<string, unknown>): Record<string, unknown>;
+/** The pre-resolved auth + version context bin.ts threads into the program. */
+/**
+ * Where CLI output goes, and the reason nothing here touches `process` directly.
+ *
+ * The terminal entrypoint (`bin.ts`) binds these to the real streams. The MCP
+ * endpoint binds them to string buffers so one `rl` invocation can be executed
+ * **in-process** on behalf of an agent and its output returned as a tool result.
+ * A stray `process.stdout.write` would leak an agent's output into the server's
+ * logs; a stray `process.exit` would take the whole API server down mid-request.
+ * Both are therefore banned in this module — see `buildBaseProgram`, which also
+ * routes commander's own help/error output through these sinks.
+ */
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface ProgramContext extends CliIo {
+    apiKey: string;
+    baseUrl: string;
+    version: string;
+    granted: GrantedPermissions;
+    /**
+     * Whether the process is running against a developer's own checkout.
+     *
+     * `false` when the CLI is embedded in a server (see `embed.ts`), which omits
+     * `scaffold`, `submit`, and `skills` from the command tree entirely. Those are the
+     * package's only routes to `spawnSync('git', …)`, to writes under `~/.claude/`, and
+     * to the `process.exit` calls in `skills.ts`/`git-host.ts` that would kill an API
+     * server mid-request. Not registering them removes the capability, which is a
+     * stronger guarantee than inspecting argv for their names — and it keeps three
+     * commands a server cannot honour out of the `--help` an agent reads.
+     */
+    localCheckout: boolean;
+}
+/**
+ * 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 declare function formatOutput(result: unknown, quiet: boolean): string;
+/**
+ * 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 declare function formatError(err: unknown): string;
+/**
+ * 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 declare function renderShapeTree(nodes: ShapeNode[], indent: string): string[];
+/**
+ * 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 declare function leafShapeHelp(entry: ManifestOperation): string;
+/**
+ * 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 declare function addOptions(command: Command, entry: ManifestOperation, fileFlags?: boolean): void;
+/** Output formats `rl recipes <id>` can render, mapped to the composed snippet field. */
+declare const RECIPE_FORMATS: {
+    readonly cli: "cli";
+    readonly ts: "sdk";
+    readonly py: "python";
+    readonly curl: "curl";
+};
+export type RecipeFormat = keyof typeof RECIPE_FORMATS;
+/** The full catalog, grouped by category, for `rl recipes`. */
+export declare function renderRecipeList(reference: Record<string, ManifestRecipe>): string;
+/**
+ * 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 declare function renderRelatedBlock(entry: ManifestRecipe, allRecipes: Record<string, ManifestRecipe>): string;
+/** One recipe rendered for `rl recipes <id>`: goal + composed code + related links + a docs link. */
+export declare function renderRecipeShow(entry: ManifestRecipe, format: RecipeFormat, allRecipes: Record<string, ManifestRecipe>): string;
+/** The program shell — name, description, version, and the global options. */
+export declare function buildBaseProgram(version: string, io: CliIo): Command;
+/** Build the full `rl` program from a fetched manifest. */
+export declare function buildProgram(manifest: Manifest, ctx: ProgramContext): Command;
+export {};