@labelbox/recursion-cli 0.0.0 → 0.0.42

package/README.md

@@ -1 +1,113 @@
-Placeholder. Do not install. Real package ships from Recursion CI.
+# @labelbox/recursion-cli
+
+`rl` — the rl-gym command-line interface. It mirrors the TypeScript SDK
+(`@labelbox/recursion-sdk`) exactly: where the SDK is `rl.synthesizers.create(...)`, the
+CLI is `rl synthesizers create …`. Dots become spaces; you get `--help` at every
+level.
+
+```sh
+rl --help                     # list nouns (synthesizers, synthesizer-runs)
+rl synthesizers --help        # list verbs (create, get, list, …)
+rl synthesizers create --help # list flags
+```
+
+## How it works (fully live, zero per-operation code)
+
+The CLI ships **no** baked API reference and has **no** `@labelbox/recursion-sdk` dependency.
+On each run it **fetches a manifest** from `GET /cli/manifest` on whatever server
+`--base-url` points at (production by default, or staging, or `localhost`), validates
+it (`src/manifest.ts`), and builds its entire command tree, `--help`, request/response
+shapes, and docs browse surfaces from it. Dispatch is generic (`src/dispatch.ts`):
+each request is built straight from the manifest operation's HTTP method + path
+template + params + body — there is no hand-written command per operation and no
+baked client.
+
+The result: **adding or changing a backend endpoint needs zero CLI release** — the
+live CLI reflects it as soon as the backend deploys. The CLI is re-released only when
+its own engine code changes. The manifest is revalidated on every run via a
+conditional fetch (ETag / `If-None-Match`), cached per base-url under
+`~/.cache/rl-gym/`, so it can never serve stale data and never needs manual busting.
+
+### Docs browse surfaces
+
+Beyond the executable `rl <noun> <verb>` operations, the manifest carries the docs,
+exposed as one consistent positional shape — `rl <group> [<id>]` (bare lists, an id
+shows that one):
+
+```sh
+rl resources [<id>]    # Reference — resource hubs: object shape, operations, recipes
+rl recipes  [<id>]     # How-to — multi-step user-goal guides (--format cli|ts|curl)
+rl explain  [<concept>] # Explanation — concept pages
+rl tutorials [<id>]    # Tutorials — getting-started docs
+```
+
+## Install / run
+
+Published to **public npm** as `@labelbox/recursion-cli` — no token, no repo access, no
+setup beyond Node itself.
+
+```sh
+npm uninstall -g @recursion/cli @labelbox/rl-cli   # no-op unless a pre-rename package is installed
+npm install -g @labelbox/recursion-cli   # they all own the global `rl` bin — EEXIST otherwise
+# or, zero-install:
+npx @labelbox/recursion-cli --help
+```
+
+The CLI is standalone, so this pulls in no `@labelbox/recursion-sdk`.
+**Full setup steps and install-failure triage live in
+`apps/recursion/web/public/docs/cli-getting-started.md`** — that page owns them; don't
+restate them here.
+
+The CLI is released independently of the SDK (it no longer depends on it): a
+`packages/cli/**` change cuts a CLI release via the **Release / CLI** GitHub
+Action — see `yarn dx help release`.
+
+From a monorepo checkout, run the bin directly without installing:
+
+```sh
+yarn workspace @labelbox/recursion-cli build
+node ./packages/cli/dist/bin.js --help
+```
+
+## Auth
+
+Set `LABELBOX_API_KEY` in the environment, or pass `--api-key <key>`. Override the
+host with `--base-url <url>` (defaults to the public Recursion API gateway, see
+`DEFAULT_BASE_URL` in `src/manifest.ts`).
+
+## Flags
+
+- **Path / query params** are individual flags: `--environment-id`, `--limit`, …
+  Required path and query params must be passed as flags. A query param whose type
+  is an array or object (e.g. `--models`, `--enrichment-filters`) takes a JSON value
+  (`--models '["a","b"]'`); its help text is tagged `[pass as JSON]`.
+- **Request body**: scalar top-level fields are individual flags (`--name`,
+  `--system-prompt`, …); pass the full body — including complex fields like
+  `contextInputs` / `targetFields` — with `--from-json <file>` or `--data <json>`
+  (mutually exclusive — pass only one). Scalar flags override values from
+  `--from-json`/`--data`. A required scalar body field can be supplied by either
+  its flag or the JSON body.
+- **Output**: prints the result as JSON by default; `--quiet` prints only the
+  resulting resource's `id` (a blank line for results without one, e.g. list or
+  no-content operations).
+
+```sh
+rl synthesizers get --synthesizer-job-id sj_01HX...
+rl synthesizers create --environment-id env_01HX... --from-json ./body.json
+rl synthesizer-runs trigger --problem-version-id pv_01HX... --from-json ./run.json
+```
+
+## The command surface is the live server
+
+There is **nothing to regenerate or commit** for the CLI — the command surface is
+fetched fresh from the target server's `GET /cli/manifest` on every run, so a backend
+change flows through automatically after deploy with no CLI step. The manifest itself
+is assembled by `yarn dx manifest:generate` (wired into `dx codegen`) from the
+spec-derived reference files and embedded into the backend; to add or change a
+command, change the backend `@SdkRoute` — not this package.
+
+The *engine* (manifest fetch + cache + validation, generic dispatch, flag mapping,
+help formatting, the request-body / returns shape trees, and the docs browse
+renderers) is verified by `src/*.test.ts`, which build the program from a fixture
+manifest in-memory and assert the realized flags + `--help` + browse output — no
+committed golden snapshot to maintain.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { fetchManifest } from './manifest.js';
+import { fetchPermissions } from './permissions.js';
+import { run } from './run.js';
+import { readCliVersion } from './version.js';
+// The orchestration lives in run.ts (testable); this entrypoint only binds the real
+// dependencies and turns the returned code into a process exit. Runs on import —
+// kept logic-free so it never needs its own test.
+//
+// `run()` never throws and never exits: it renders every failure (including a
+// missing key, a manifest fetch/validation error, and synchronous throws from
+// buildProgram() such as a reserved-flag collision) to the `stderr` sink as
+// `error: <message>`, then returns the exit code. The `.catch()` below is a
+// backstop for a defect in that contract, not a routine path.
+run({
+    argv: process.argv,
+    // Pass the reader, not its result — run() invokes it so a throw (corrupt install)
+    // is rendered as `error: <message>` rather than a raw stack trace.
+    version: readCliVersion,
+    fetchManifest,
+    fetchPermissions,
+    // The terminal entrypoint: `scaffold`, `submit`, and `skills` act on the
+    // developer's own checkout, so this is the one caller that registers them.
+    localCheckout: true,
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+})
+    .then((code) => {
+    // Only exit non-zero. Calling process.exit(0) here could truncate a large
+    // pending stdout write; letting node drain and exit naturally cannot.
+    if (code !== 0)
+        process.exit(code);
+})
+    .catch((err) => {
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { ManifestOperation } from './manifest.js';
+export interface DispatchContext {
+    baseUrl: string;
+    apiKey: string;
+}
+/** Build the full request URL: base + path (params substituted) + query string. */
+export declare function buildUrl(op: ManifestOperation, params: Record<string, unknown>, baseUrl: string): string;
+/**
+ * Build and send the request for one operation, returning the parsed success body
+ * (or `undefined` for a 204 / empty response). On a non-2xx response the parsed
+ * error body is thrown (so `formatError` prints the server's JSON detail);
+ * `fetch` rejecting for an unreachable server propagates and is mapped to the
+ * standard "could not be reached" message by `formatError`.
+ */
+export declare function dispatchOperation(op: ManifestOperation, params: Record<string, unknown>, ctx: DispatchContext): Promise<unknown>;

package/dist/dispatch.js

@@ -0,0 +1,122 @@
+// Bound every request so a server that accepts the connection but never responds
+// can't hang the CLI indefinitely. Generous — recursion operations are quick REST
+// calls (long work is async + polled), so this only trips on a genuine hang.
+const REQUEST_TIMEOUT_MS = 120_000;
+/** Serialize one query param value the way the generated client did. */
+function serializeQueryParam(name, value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value)) {
+        // form + explode: repeat the key per element. A non-scalar element (object/array)
+        // is JSON-encoded so it survives rather than becoming `[object Object]` —
+        // consistent with the object branch below. No shipped query param is `object[]`
+        // today; this keeps the two branches from diverging.
+        return value
+            .filter((v) => v !== undefined && v !== null)
+            .map((v) => {
+            const encoded = typeof v === 'object' ? JSON.stringify(v) : String(v);
+            return `${name}=${encodeURIComponent(encoded)}`;
+        });
+    }
+    if (typeof value === 'object') {
+        // Object-valued query params (the `deepObject` `enrichmentFilters`, a
+        // record(string, string[])) go on the wire as a single JSON-encoded string. The
+        // backend does NOT bracket-parse (`name[key]=v` lands as a stray key and the
+        // param reads as absent — verified against the live API); its schema preprocess
+        // JSON.parses the value, and the frontend serializes it identically
+        // (apps/recursion/web/src/api/problems.ts). JSON also preserves the nested arrays a
+        // bracket + `String()` encoding silently corrupted.
+        return [`${name}=${encodeURIComponent(JSON.stringify(value))}`];
+    }
+    return [`${name}=${encodeURIComponent(String(value))}`];
+}
+/** Build the full request URL: base + path (params substituted) + query string. */
+export function buildUrl(op, params, baseUrl) {
+    const path = op.path.replace(/\{([^}]+)\}/gu, (_match, name) => {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            throw new Error(`missing required path parameter "${name}"`);
+        }
+        return encodeURIComponent(String(value));
+    });
+    const search = [];
+    for (const param of op.params) {
+        if (param.in === 'query')
+            search.push(...serializeQueryParam(param.name, params[param.name]));
+    }
+    const base = baseUrl.replace(/\/$/u, '');
+    const withPath = `${base}${path.startsWith('/') ? path : `/${path}`}`;
+    return search.length > 0 ? `${withPath}?${search.join('&')}` : withPath;
+}
+/** Parse a response body, dispatching on content type (JSON vs. raw text). */
+async function parseBody(res) {
+    if (res.status === 204)
+        return undefined;
+    const text = await res.text();
+    if (text === '')
+        return undefined;
+    const contentType = res.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json') || contentType.includes('+json')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/**
+ * Build and send the request for one operation, returning the parsed success body
+ * (or `undefined` for a 204 / empty response). On a non-2xx response the parsed
+ * error body is thrown (so `formatError` prints the server's JSON detail);
+ * `fetch` rejecting for an unreachable server propagates and is mapped to the
+ * standard "could not be reached" message by `formatError`.
+ */
+export async function dispatchOperation(op, params, ctx) {
+    const url = buildUrl(op, params, ctx.baseUrl);
+    const headers = {
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        Authorization: `Bearer ${ctx.apiKey}`,
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        Accept: 'application/json',
+    };
+    let body;
+    if (op.bodyKey && params[op.bodyKey] !== undefined) {
+        body = JSON.stringify(params[op.bodyKey]);
+        headers['Content-Type'] = 'application/json';
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method: op.httpMethod.toUpperCase(),
+            headers,
+            // Spread rather than `body` — `RequestInit.body` is not optional-undefined,
+            // so passing `undefined` explicitly is a type error under
+            // exactOptionalPropertyTypes (and a bodyless GET is the common case).
+            ...(body === undefined ? {} : { body }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        // AbortSignal.timeout rejects with a TimeoutError — turn the hang into a clear,
+        // actionable message; other fetch failures (refused/reset) propagate unchanged.
+        if (err instanceof Error && err.name === 'TimeoutError') {
+            throw new Error(`request to ${url} timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);
+        }
+        throw err;
+    }
+    const parsed = await parseBody(res);
+    if (!res.ok) {
+        // Prefer the server's structured error body (formatError renders it as JSON);
+        // fall back to a status-coded Error when there's no usable body. `!== null` (not
+        // `!== undefined`) because `typeof null === 'object'` — a literal `null` body
+        // would otherwise be thrown and surface as an unactionable `error: null`.
+        if (parsed !== null && typeof parsed === 'object')
+            throw parsed;
+        throw new Error(typeof parsed === 'string' && parsed !== ''
+            ? `request failed (HTTP ${res.status}): ${parsed}`
+            : `request failed — HTTP ${res.status}`);
+    }
+    return parsed;
+}

package/dist/embed.d.ts

@@ -0,0 +1,41 @@
+import type { Manifest } from './manifest.js';
+import type { GrantedPermissions } from './permissions.js';
+export type { Manifest, GrantedPermissions };
+export interface ExecuteCliOptions {
+    /** CLI arguments as the caller would type them, e.g. `['environments', 'list']`. */
+    args: readonly string[];
+    /** The caller's own API key, from the request. Never the server's environment. */
+    apiKey: string;
+    /** The API the CLI dispatches against. Server configuration, not caller input. */
+    baseUrl: string;
+    /** Reported by `rl --version`. */
+    version: string;
+    /** The pre-assembled manifest — served from memory, never re-fetched over HTTP. */
+    manifest: Manifest;
+    /** The caller's granted permissions, so `--help` and gating match who is asking. */
+    granted: GrantedPermissions;
+}
+export interface CliResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /** True when the invocation failed — becomes the tool result's `isError`. */
+    failed: boolean;
+}
+/**
+ * Reject argv that would exfiltrate the caller's key, reach the filesystem, or
+ * spawn a process. Messages are written for the model, naming the alternative so
+ * it can correct itself rather than retrying the same call.
+ *
+ * @throws Error when the invocation is not permitted here.
+ */
+export declare function assertAllowedArgv(args: readonly string[]): void;
+/**
+ * Run one `rl` invocation in-process and capture its output.
+ *
+ * Resolves for both success and failure — a non-zero exit is a normal outcome the
+ * model should see and correct from, not an exception. It rejects only on a
+ * refused argv (see `assertAllowedArgv`), or if `run()` breaks its no-throw
+ * contract.
+ */
+export declare function executeCli(options: ExecuteCliOptions): Promise<CliResult>;

package/dist/embed.js

@@ -0,0 +1,153 @@
+import { run } from './run.js';
+// Running `rl` inside a server process, on behalf of an agent, without a shell.
+//
+// The MCP endpoint exposes one tool whose argument is an argv array. This module
+// is the whole surface it needs: `executeCli` builds the argv, runs the same
+// `run()` the terminal entrypoint uses, and returns the captured output instead of
+// writing to the process streams.
+//
+// Three things make this safe rather than merely convenient:
+//
+//   1. **No process is spawned.** There is no shell, so there is no quoting,
+//      escaping, or metacharacter surface — argv is passed as an array and reaches
+//      commander verbatim. An agent cannot reach the container's shell through it.
+//   2. **Credentials and target are server-controlled**, never caller-supplied.
+//      See RESERVED_FLAGS — this is the difference between running the CLI for the
+//      caller and letting the caller point the CLI wherever it likes.
+//   3. **Laptop-shaped commands are refused.** BLOCKED_COMMANDS covers the CLI's
+//      only routes to the host filesystem and to `spawnSync`.
+//
+// Everything else — the command tree, `--help`, permission gating, dispatch — is
+// the real CLI, unchanged.
+/**
+ * Command groups that never make sense server-side, and that are the CLI's only
+ * routes to the host filesystem or a child process.
+ *
+ * - `scaffold` / `submit` (`git-host.ts`) run `spawnSync('git', …)` and write an
+ *   executable credential helper, handing it the parent's full environment.
+ * - `skills` (`skills.ts`) writes into `~/.claude/skills/` — on a server that is
+ *   the container's home directory, not the caller's machine.
+ *
+ * **This set is not what makes them unreachable.** `run({ localCheckout: false })`
+ * below never registers them, so the capability is absent from the command tree
+ * rather than filtered out of argv. This check exists only so a model that asks for
+ * one gets an explanation instead of commander's bare `unknown command`.
+ */
+const BLOCKED_COMMANDS = new Set(['scaffold', 'submit', 'skills']);
+/**
+ * Flags the caller may not set, each because the server must decide it.
+ *
+ * `--base-url` is the security-critical one. `dispatchOperation` sends
+ * `Authorization: Bearer <apiKey>` to whatever base URL resolves, so a caller-set
+ * `--base-url` would send the *caller's own API key* to a host of the caller's
+ * choosing. Refusing it is what keeps this from being a credential-exfiltration
+ * primitive wrapped in a tool call.
+ *
+ * `--api-key` is refused for the same reason in reverse: the identity a request
+ * runs under is established by the request, not by an argument a model can write.
+ *
+ * Rejecting is not merely belt-and-braces over appending our own values.
+ * `resolveApiKey`/`resolveBaseUrl` read argv via `flagValue`, which prefers the
+ * `--name=value` form found *anywhere* in argv over the space form — so a
+ * caller-supplied `--base-url=…` would beat a server value appended afterwards.
+ * The only correct handling is to refuse the argv outright.
+ */
+const RESERVED_FLAGS = ['--api-key', '--base-url'];
+/**
+ * `--from-json <path>` reads an arbitrary file and folds it into the request body
+ * (`program.ts` → `parseBodyBase`). In a server process that is a file-read
+ * primitive handed to a model: the contents reach the API, and a parse failure
+ * echoes the path back in the error. `--data` accepts the same JSON inline and is
+ * always available, so nothing is lost by refusing the file form.
+ */
+const BLOCKED_FLAG = '--from-json';
+/** Does argv set this flag, in either the space form or the `=` form? */
+function hasFlag(args, flag) {
+    return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+}
+/**
+ * Reject argv that would exfiltrate the caller's key, reach the filesystem, or
+ * spawn a process. Messages are written for the model, naming the alternative so
+ * it can correct itself rather than retrying the same call.
+ *
+ * @throws Error when the invocation is not permitted here.
+ */
+export function assertAllowedArgv(args) {
+    for (const flag of RESERVED_FLAGS) {
+        if (hasFlag(args, flag)) {
+            throw new Error(`${flag} cannot be set here — it is determined by your authenticated session. ` +
+                'Remove it and retry.');
+        }
+    }
+    if (hasFlag(args, BLOCKED_FLAG)) {
+        throw new Error(`${BLOCKED_FLAG} is not available here because it reads a file from the server. ` +
+            'Pass the same JSON inline with --data instead.');
+    }
+    // Only the command position, which is the first non-flag token — where commander
+    // resolves it from. Scanning every token instead would permanently refuse valid
+    // data that happens to spell one of these names (`--name submit`), and because it
+    // is the caller's own data the model could not retry its way out of it. The
+    // security property does not rest on this check anyway; see BLOCKED_COMMANDS.
+    const command = args.find((arg) => !arg.startsWith('-'));
+    if (command !== undefined && BLOCKED_COMMANDS.has(command)) {
+        throw new Error(`"${command}" is not available here: it acts on a local developer checkout, ` +
+            'which this server does not have. Run it from your own terminal with the rl CLI.');
+    }
+}
+/**
+ * Run one `rl` invocation in-process and capture its output.
+ *
+ * Resolves for both success and failure — a non-zero exit is a normal outcome the
+ * model should see and correct from, not an exception. It rejects only on a
+ * refused argv (see `assertAllowedArgv`), or if `run()` breaks its no-throw
+ * contract.
+ */
+export async function executeCli(options) {
+    if (options.apiKey === '') {
+        throw new Error('cannot run the CLI without an API key for the calling user');
+    }
+    assertAllowedArgv(options.args);
+    const stdout = [];
+    const stderr = [];
+    const exitCode = await run({
+        // Server-controlled flags go first, before anything the caller sent — global
+        // flags precede the command, which is the form `resolveApiKey`/`resolveBaseUrl`
+        // scan for. `assertAllowedArgv` has already guaranteed the caller set neither.
+        // `run()` slices off the leading two entries as it would a real `process.argv`,
+        // so the placeholders have to be present.
+        //
+        // The `=` form, not the space form: `flagValue` refuses to read a space-form
+        // value that itself starts with `-`, so a key or URL beginning with a dash would
+        // read as unset and `resolveApiKey` would fall through to
+        // `process.env.LABELBOX_API_KEY` — turning a key in the container into the acting
+        // identity, the exact substitution this path exists to prevent. The `=` form
+        // binds any value, and is also the form `flagValue` prefers, so nothing later in
+        // argv can outrank it.
+        argv: [
+            'node',
+            'rl',
+            `--api-key=${options.apiKey}`,
+            `--base-url=${options.baseUrl}`,
+            ...options.args,
+        ],
+        version: () => options.version,
+        // Both fetches are satisfied from what the caller already resolved: the
+        // manifest is embedded in the server, and the permissions came in on the
+        // request. No HTTP, no ETag cache directory, and no way for a slow or
+        // unreachable network to stall a tool call.
+        fetchManifest: () => Promise.resolve(options.manifest),
+        fetchPermissions: () => Promise.resolve(options.granted),
+        // No developer checkout here, so `scaffold`, `submit`, and `skills` are never
+        // registered — the CLI's only `spawnSync`, `~/.claude/` writes, and
+        // `process.exit` calls are absent from this program, not merely refused.
+        localCheckout: false,
+        stdout: (text) => stdout.push(text),
+        stderr: (text) => stderr.push(text),
+    });
+    return {
+        stdout: stdout.join(''),
+        stderr: stderr.join(''),
+        exitCode,
+        failed: exitCode !== 0,
+    };
+}

package/dist/git-host.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+/** `POST /v1/organizations/:organizationId/git-repo-claims` — mints a per-Aligner
+ *  repo + push token for `problemId`. The claiming Aligner is the
+ *  authenticated caller (the API key), never a client-supplied field. */
+export declare function claimGitRepo(args: {
+    apiKey: string;
+    baseUrl: string;
+    organizationId: string;
+    problemId: string;
+}): Promise<{
+    cloneUrl: string;
+    defaultBranch: string;
+    pushToken: string;
+}>;
+/** Register the `scaffold` / `submit` commands on `program`. */
+export declare function addGitHostCommands(program: Command, helpGroup: string): void;