@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/dist/permissions.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { supportUrl } from './manifest.js';
+import { requestTimeoutMs } from './request-timeout.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. Network, response, and decoding errors
+ * resolve to `undefined` (fail-open); invalid local timeout/deadline configuration
+ * fails before the request. 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');
+    const timeoutMs = requestTimeoutMs(PERMISSIONS_FETCH_TIMEOUT_MS);
+    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(timeoutMs),
+        });
+    }
+    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));
+}
+// ── gating presentation (shared with hand-written commands) ──────────────────
+//
+// These live here, next to `missingPermission`, rather than in program.ts so that
+// hand-written commands (compute-session.ts) can present a missing permission
+// exactly the way the manifest-driven loop does without importing program.ts,
+// which imports them — a cycle.
+/** Nested resource groups — subcommands the caller can't run (separate help section). */
+export const UNAVAILABLE_HELP_GROUP = 'Unavailable (missing permission)';
+/** A leaf command's description when the caller lacks a required permission. */
+export function gatedSummary(summary, missing) {
+    return missing === undefined ? summary : `requires \`${missing}\` — ${summary}`;
+}
+/** The error printed when the caller invokes a command they lack permission for. */
+export 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. */
+export function permissionHelpNote(missing) {
+    return `\nYou don't have permission to run this command (requires \`${missing}\`).`;
+}
+/**
+ * `missingPermission` for a command that carries its requirement in code rather
+ * than in the manifest: the permission back, or `undefined` when the caller holds
+ * it or permissions are unknown (fail-open, same as the manifest path).
+ */
+export function missingRequiredPermission(granted, required) {
+    if (granted === undefined)
+        return undefined;
+    return hasPermission(granted, required) ? undefined : required;
+}

package/dist/program.d.ts

@@ -0,0 +1,129 @@
+import { type Writable } from 'node:stream';
+import { Command } from 'commander';
+import { type DispatchResponse } from './dispatch.js';
+import type { Manifest, ManifestOperation, ManifestRecipe, ShapeNode } from './manifest.js';
+import { type GrantedPermissions } from './permissions.js';
+/** camelCase → kebab-case for command + flag names (shared with `@labelbox/horizon-sdk`). */
+export declare function kebab(value: string): string;
+/**
+ * The key commander stores a parsed flag under. Commander camelCases the long
+ * flag name, so `--if-match` lands on `opts.ifMatch` — a wire header name like
+ * `If-Match` never round-trips through `kebab()` back to itself the way a
+ * camelCase path or query param name does, and reading `opts[param.name]`
+ * silently dropped the header.
+ */
+export declare function optionAttributeName(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 available sources are merged — so a
+ * missing JSON field or multipart form field fails locally rather than becoming 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 `horizon` 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 {
+    /** Byte-preserving terminal output. Absent for embedded callers, which omit binary operations. */
+    binaryStdout?: Writable;
+    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`, `skills`, `computes open`, and `computes tools` from the command tree
+     * entirely. Those are the package's only routes to `spawnSync('git', …)`, to
+     * writes under `~/.claude/`, to the `process.exit` calls in
+     * `skills.ts`/`git-host.ts` that would kill an API server mid-request, and to the
+     * direct `process.stdout` write in `compute-session.ts` that would put a
+     * bearer-equivalent cookie in the server's logs instead of the tool result. Not
+     * registering them removes the capability, which is a stronger guarantee than
+     * inspecting argv for their names — and it keeps five commands a server cannot
+     * honour out of the `--help` an agent reads. It also disables fallback to the
+     * server process's organization/environment variables, which are configuration
+     * for the server rather than authenticated scope supplied by its caller.
+     */
+    localCheckout: boolean;
+}
+/**
+ * Render a response for stdout. Normal mode preserves the HTTP result as a JSON
+ * envelope; JSON encodes a bodyless response's `undefined` data as `null` so the
+ * field remains explicit. `--quiet` is the deliberate lossy projection: it prints
+ * a manifest-declared scalar output field, or otherwise the response data's `id`
+ * (an empty line for data without one). Binary data is always written byte-for-byte.
+ * Text output includes a trailing newline.
+ */
+export declare function formatOutput(response: DispatchResponse, quiet: boolean, outputField?: string): string | ReadableStream<Uint8Array>;
+/**
+ * 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. In that mode,
+ * `--from-json` would read from the host process rather than the user's machine,
+ * so it is not registered and `--data` remains the inline alternative.
+ */
+export declare function addOptions(command: Command, entry: ManifestOperation, fileFlags?: boolean): void;
+/** Output formats `horizon recipes <id>` can render, mapped to the composed snippet field. */
+declare const RECIPE_FORMATS: {
+    readonly cli: 'cli';
+    readonly ts: 'sdk';
+    readonly curl: 'curl';
+};
+export type RecipeFormat = keyof typeof RECIPE_FORMATS;
+/** The full catalog, grouped by category, for `horizon 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 `horizon 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, allowEnvironmentFallback?: boolean): Command;
+/** Build the full `horizon` program from a fetched manifest. */
+export declare function buildProgram(manifest: Manifest, ctx: ProgramContext): Command;
+export {};