@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# @labelbox/horizon-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`horizon` — the Horizon CLI. It mirrors the TypeScript SDK
+(`@labelbox/horizon-sdk`) exactly: where the SDK is `horizon.synthesizers.create(...)`, the
+CLI is `horizon synthesizers create …`. Dots become spaces; you get `--help` at every
+level. `horizon` is the only executable name.
+
+```sh
+horizon --help                     # list nouns (synthesizers, synthesizer-runs)
+horizon synthesizers --help        # list verbs (create, get, list, …)
+horizon 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/horizon-sdk` dependency.
+On each run it **revalidates the manifest** from `GET /v1/cli/manifest` when the server
+selected by `--base-url` is reachable (production by default, or staging, or
+`localhost`). If the server is unavailable, it falls back only to a locally cached
+manifest that was previously validated. From that manifest it builds its entire
+command tree, `--help`, request/response shapes, and docs browse surfaces
+(`src/manifest.ts`). 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. When the server is reachable, the manifest is
+revalidated on every run via a conditional fetch (ETag / `If-None-Match`) and cached
+per base-url under `~/.cache/horizon/`. When the server is unreachable, the CLI may
+use the last locally validated copy so commands remain available offline. Validated
+fresh HTTP `200` responses use atomic same-directory rename and therefore retain
+last-network-writer behavior. Replacement preserves an existing file's POSIX mode
+bits, but deliberately publishes a new inode and does not preserve its ACLs or
+extended attributes. Publication requires parent-directory write/search permission;
+if unavailable, the CLI keeps using the validated in-memory result and never falls
+back to a partial direct write.
+
+### Docs browse surfaces
+
+Beyond the executable `horizon <noun> <verb>` operations, the manifest carries the docs,
+exposed as one consistent positional shape — `horizon <group> [<id>]` (bare lists, an id
+shows that one):
+
+```sh
+horizon resources [<id>]     # Reference — resource hubs: object shape, operations, recipes
+horizon recipes [<id>]       # How-to — multi-step user-goal guides (--format cli|ts|curl)
+horizon explain [<concept>]  # Explanation — concept pages
+horizon tutorials [<id>]     # Tutorials — getting-started docs
+```
+
+## Install / run
+
+The package is not published yet, so no npm install command is valid today.
+The manual **Release / CLI** workflow builds and externally consumes an
+immutable `0.0.1` bootstrap archive, but executable release authority refuses
+npm and GitHub mutation until a Labelbox npm owner reserves the package and
+registers its Trusted Publisher.
+
+When activated, the CLI remains standalone and pulls in no
+`@labelbox/horizon-sdk`. It is versioned independently of the SDK, remains below
+`1.0.0`, and may include breaking changes.
+
+From a monorepo checkout, run the bin directly without installing:
+
+```sh
+yarn workspace @labelbox/horizon-cli build
+node ./packages/horizon-cli/dist/bin.js --help
+```
+
+## Auth
+
+Set `LABELBOX_API_KEY` in the environment without printing it or putting it on a
+command line. Override the host with `--base-url <url>` (defaults to the public
+Horizon 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]`.
+- **Operation headers** declared by the API are individual flags too. Required
+  concurrency and replay controls therefore appear as `--if-match` and
+  `--idempotency-key` and are forwarded under their declared HTTP names.
+- **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.
+- **Multipart request body**: binary fields are local-path flags such as
+  `--file ./skill.zip`; scalar form fields remain ordinary flags. The CLI reads
+  the file only in its terminal process and lets the HTTP runtime set the
+  multipart boundary. Filesystem-less embedded callers expose JSON operations
+  only.
+- **Output**: prints every non-binary result as the JSON HTTP envelope
+  `{ data, status, headers }` by default. A bodyless `204` or `304` is encoded as
+  `data: null` because JSON has no `undefined`. `--quiet` deliberately discards
+  that HTTP metadata and prints only the resulting resource's `id`; an operation
+  may instead declare one scalar response field for quiet output (for example,
+  the handoff-access command's ephemeral URL). Results without either value print
+  a blank line in quiet mode. Binary downloads are written to stdout byte-for-byte
+  with no encoding or trailing newline, so redirect them to a file.
+
+The embedded dispatcher exposes JSON/text operations and returns each success as
+`{ data, status, headers }`. `headers` contains the response headers declared for
+that status in OpenAPI (including `ETag`, `Location`, and
+`Idempotency-Replayed`). Bodyless `data` is `undefined`. Operations with a binary
+success representation are excluded from embedded and MCP callers; use the
+terminal CLI, which streams their bytes directly to stdout.
+
+```sh
+horizon environments get --environment-id 784e2386-e297-4f9d-a886-838422383b65
+horizon synthesizers get --synthesizer-job-id b45c081d-3069-4e32-98d4-aa5ec3d442c6
+```
+
+## The command surface is the live server
+
+There is **nothing to regenerate or commit** for the CLI — the command surface is
+revalidated against the target server's `GET /v1/cli/manifest` on every run when the
+server is reachable, with a validated local-cache fallback when it is offline. A
+backend change therefore flows through automatically after deploy with no CLI step.
+The manifest itself is assembled by `yarn generate cli:manifest` (included in
+`yarn generate prerequisites`) 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,39 @@
+#!/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),
+    binaryStdout: process.stdout,
+    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/compute-session.d.ts

@@ -0,0 +1,135 @@
+import type { Command } from 'commander';
+import { z } from 'zod';
+import { type GrantedPermissions } from './permissions.js';
+/** Mirrors `ComputeAccessSessionDto`; `mintAccessSession`'s 201 body. */
+declare const AccessSessionSchema: z.ZodObject<{
+    redemptionUrl: z.ZodURL;
+    redemptionUrlExpiresAt: z.ZodString;
+}, z.core.$strip>;
+export interface ComputeSession {
+    /** `https://c-<compute-id>.<subdomain-root>`, taken from the redemption URL —
+     *  the edge's domain is the server's to choose, never assembled client-side. */
+    origin: string;
+    /** Streamable-HTTP MCP endpoint on that origin.
+     *
+     *  The trailing slash is load-bearing: the world's nginx routes MCP with
+     *  `location /mcp/ { proxy_pass http://mcp:8000; }`, an nginx *prefix* match, so
+     *  a request to `/mcp` does not match it and never reaches the MCP server. */
+    mcpEndpoint: string;
+    /** Plain-JSON enumeration of every tool the world serves, on the same origin
+     *  and behind the same cookie — nginx rewrites `/mcp-health/` to the MCP
+     *  server's `/health/`, so this is its `/health/tools`. Answers "what is in
+     *  this world?" without an MCP handshake or a JSON-RPC client. */
+    toolsEndpoint: string;
+    /** `name=value`, ready to send verbatim as a `Cookie` request header. */
+    cookie: string;
+}
+export declare const SESSION_FORMATS: readonly ['header-file', 'claude-code', 'json', 'cookie'];
+export type SessionFormat = (typeof SESSION_FORMATS)[number];
+/** The default, and the reason it is the default: every other format puts a
+ *  bearer-equivalent credential somewhere durable. */
+export declare const DEFAULT_SESSION_FORMAT: SessionFormat;
+/**
+ * Bind the redemption origin **before** anything is sent to it.
+ *
+ * The redemption URL comes back over the wire, and the next thing the CLI does is
+ * make a request to it — so it is untrusted input on the way in and a request
+ * target on the way out. Everything downstream (the MCP endpoint, the cookie's
+ * eventual destination) is derived from this origin, which makes a bad one a
+ * credential-exfiltration primitive rather than a cosmetic error.
+ *
+ * Port of `proxyUrlFromRedemption` (devbox.ts): TLS only, no userinfo (which would
+ * let `https://c-<id>@attacker.example/` read as the expected host), a hostname
+ * that *starts with* `c-<computeId>.` and is strictly longer than that prefix (so
+ * the compute the caller named is the compute the session is for, and a bare
+ * `c-<id>.` with no domain is refused), and the exact redemption pathname.
+ */
+export declare function redemptionOrigin(redemptionUrl: string, computeId: string): string;
+/** `POST /v1/computes/:computeId/access/sessions` — mints a short-lived,
+ *  single-use redemption URL for a running compute the caller owns. */
+export declare function mintAccessSession(args: {
+    apiKey: string;
+    baseUrl: string;
+    computeId: string;
+}): Promise<z.infer<typeof AccessSessionSchema>>;
+/** Redeem a minted URL into the edge session cookie.
+ *
+ *  `computeId` is not decoration: the URL is validated against it *before* the
+ *  request goes out (see `redemptionOrigin`), because sending it is the act that
+ *  would leak.
+ *
+ *  `redirect: 'manual'` is load-bearing: the cookie rides on the 302 itself, and
+ *  following the redirect would consume the only header this request exists to
+ *  read. The URL is single-use and TTL-bounded (60s upstream), so a failure here
+ *  is not retryable with the same URL — mint a fresh one. */
+export declare function redeemSession(redemptionUrl: string, computeId: string): Promise<string>;
+/** Mint and redeem in one step, returning everything an MCP client needs. */
+export declare function openComputeSession(args: {
+    apiKey: string;
+    baseUrl: string;
+    computeId: string;
+}): Promise<ComputeSession>;
+/** One tool as the world's MCP server reports it on `/health/tools`.
+ *
+ *  Mirrors `MCPToolHealth` in `worldsim_platform/mcp/server.py`. Only the fields the
+ *  grouped view reads are modelled, and the object is *loose* on purpose: the world
+ *  ships on its own cadence, so a tool gaining a field must neither break enumeration
+ *  nor silently vanish. A stripping object would drop `method`, `path` and
+ *  `example_arguments` — exactly the call-shape fields `--json` exists to carry. */
+declare const WorldToolSchema: z.ZodObject<{
+    service: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type WorldTool = z.infer<typeof WorldToolSchema>;
+/** Every tool the world currently serves.
+ *
+ *  This is the post-allowlist set: the MCP server filters by `WORLDSIM_MCP_TOOLS_FILE`
+ *  before registering, so it answers what an agent in this world can actually call,
+ *  not what the bake could expose. The bake's full catalogue is a different question,
+ *  answered by `run-config-versions discover-mcp-tools`.
+ *
+ *  Plain JSON over the same session cookie as `/mcp/` — no MCP handshake, so no
+ *  `initialize` round-trip and no JSON-RPC pagination to unroll. */
+export declare function fetchWorldTools(session: ComputeSession): Promise<WorldTool[]>;
+/** Group by service, because a world's tools are namespaced by the service that
+ *  backs them (`gitea.create_user`) and a flat list of 200 hides that structure. */
+export declare function formatWorldTools(tools: WorldTool[]): string;
+/**
+ * The MCP server name a compute registers under when `--name` isn't given.
+ *
+ * A compute is a generic remote machine — `tools/dx devbox` runs devboxes on the
+ * same primitive — so the name is derived from the compute rather than from any
+ * one workload that happens to run on it. Derived rather than fixed so two open
+ * computes don't collide under one name in the client's config.
+ */
+export declare function defaultServerName(computeId: string): string;
+export declare function parseServerName(value: string): string;
+/**
+ * Write the `Cookie:` request header to a file only the current user can read,
+ * and return its path.
+ *
+ * In its own `mkdtempSync` directory (mode 0700) rather than a fixed, guessable
+ * path under `tmpdir()`, and with the `wx` flag, which refuses to follow or
+ * overwrite an existing path — the same shape `git-host.ts` uses for its askpass
+ * helper, and for the same local-attacker-pre-plants-a-symlink reason. Unlike that
+ * one, this file *is* the secret, hence 0600.
+ */
+export declare function writeSessionHeaderFile(session: ComputeSession): string;
+export declare function formatSession(session: ComputeSession, format: SessionFormat, serverName: string): string;
+/** Attach `open` and `tools` to the manifest-built `computes` group.
+ *
+ *  Registered after the operation loop, so the group already exists — unless the
+ *  backend serves no compute operations at all, in which case there is nothing to
+ *  attach to and nothing to offer. A name collision means the backend grew its own
+ *  `computes open` or `computes tools`; fail loudly rather than let commander silently shadow one,
+ *  mirroring `claim()` in program.ts.
+ *
+ *  Returns the `computes` group and number of gated commands when they were
+ *  registered in their gated form, so the caller can fold them into that group's
+ *  "N commands require permissions" banner; `undefined` otherwise. */
+export declare function addComputeSessionCommands(program: Command, helpGroup: string, granted: GrantedPermissions): {
+    parent: Command;
+    gatedCount: number;
+} | undefined;
+export {};