@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/dist/manifest.js

@@ -0,0 +1,558 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+import { requestTimeoutMs } from './request-timeout.js';
+export { DEFAULT_BASE_URL } from './default-base-url.generated.js';
+export { hasJsonRequestRepresentation, isJsonOperationCallable, isMultipartRequestOperation, JSON_REQUEST_MEDIA_TYPE, MULTIPART_REQUEST_MEDIA_TYPE, } from './json-operation-callability.js';
+// 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/horizon-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 is
+//      revalidated whenever the server is reachable and remains usable offline.
+// The schema lives here, not in horizon-sdk: 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 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 = 2;
+// ── ShapeNode — the recursive request/response shape (mirrors horizon-sdk/schema.ts) ──
+//
+// Carried verbatim from the operation structs the backend assembles, so the
+// existing CLI renderers (`renderShapeTree`, `leafShapeHelp`) run on it unchanged.
+// Optionals are `?: T | undefined` so the interface matches what zod infers under
+// `exactOptionalPropertyTypes`, letting the recursion carry its `z.ZodType` type.
+export const JsonSchemaTypeSchema = z.enum([
+    'array',
+    'boolean',
+    'integer',
+    'null',
+    'number',
+    'object',
+    'string',
+]);
+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(),
+    jsonTypes: z.array(JsonSchemaTypeSchema).min(1).optional(),
+    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(),
+    maxProperties: z.number().optional(),
+    uniqueItems: z.boolean().optional(),
+    pattern: z.string().optional(),
+    fields: z.array(z.lazy(() => ShapeNodeSchema)).optional(),
+    items: z.lazy(() => ShapeNodeSchema).optional(),
+    additionalProperties: z
+        .union([z.boolean(), 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',
+    'maxProperties',
+    'uniqueItems',
+    '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', 'header', 'body']),
+});
+export const RequestBodyProjectionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('fields'), shape: ShapeNodeSchema }),
+    z.object({ kind: z.literal('whole'), shape: ShapeNodeSchema }),
+]);
+export const SuccessResponseSchema = z.object({
+    status: z.union([z.number().int().min(200).max(299), z.literal(304)]),
+    mediaTypes: z.array(z.string().min(1)),
+    headers: z.array(z.string().min(1)),
+});
+export const InvocationExamplesSchema = z.object({
+    typescript: z.string(),
+    cli: z.string(),
+    curl: z.string(),
+});
+/**
+ * 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 horizon-sdk'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(),
+    // Additive wire metadata: older manifests omit it; current generators emit it
+    // whenever a request body exists so non-CLI projections preserve body optionality.
+    requestBodyRequired: z.boolean().optional(),
+    // Deterministic, unique OpenAPI request representations. Generic clients use
+    // this to distinguish JSON-callable operations from alternate transports.
+    requestMediaTypes: z.array(z.string().min(1)).min(1).optional(),
+    // Complete body root plus how it was projected into params. Optional for
+    // backward compatibility with older servers.
+    requestBody: RequestBodyProjectionSchema.optional(),
+    // Generated from the same SDK-reference entry as the operation contract.
+    // Optional so older cached manifests remain readable.
+    examples: InvocationExamplesSchema.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(),
+    // A top-level success-response field the terminal CLI prints in quiet mode.
+    cliOutputField: z.string().min(1).optional(),
+    // Generated HTTP outcomes are the generic dispatcher's success authority.
+    successResponses: z.array(SuccessResponseSchema).min(1),
+    params: z.array(ManifestParamSchema),
+    response: ShapeNodeSchema.optional(),
+});
+// ── Resources — the Reference browse surface (`horizon 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 (`horizon 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
+// horizon-sdk's recipes-schema). Modeled loosely here — the CLI only reads these to
+// render the "Related" / "Unblocks" block on `horizon 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,
+    cli: RecipeSnippetSchema,
+    curl: RecipeSnippetSchema,
+    // The recipe's relationship links (optional — absent for an island recipe).
+    related: ManifestRelatedSchema.optional(),
+});
+// ── Concepts — the Explanation browse surface (`horizon 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 (`horizon 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(),
+});
+// ── Guides — authored product documentation exposed to MCP agents ───────────
+export const ManifestGuideSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    path: z.string(),
+    body: z.string(),
+});
+// ── 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),
+    // Additive and optional so older cached/server manifests and older CLIs remain
+    // mutually compatible. The producer emits it on every fresh generation.
+    guides: z.record(z.string(), ManifestGuideSchema).optional(),
+    domains: z.array(ManifestDomainSchema),
+})
+    .superRefine((manifest, ctx) => {
+    for (const [key, operation] of Object.entries(manifest.operations)) {
+        if (key === operation.operationId)
+            continue;
+        ctx.addIssue({
+            code: 'custom',
+            path: ['operations', key, 'operationId'],
+            message: `must match manifest key ${JSON.stringify(key)}`,
+        });
+    }
+});
+/**
+ * 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
+            ? // Only a reader already running this package can print the hint, so it names
+                // the current package and command without carrying legacy install advice.
+                'this `horizon` CLI is out of date — upgrade it (`npm install -g @labelbox/horizon-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.
+ */
+export 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 canonicalCachePathFor(baseUrl) {
+    return join(homedir(), '.cache', 'horizon', `${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;
+    }
+}
+const CACHE_TEMP_PREFIX = '.horizon-cli-';
+function uniqueCacheTempPath(directory) {
+    return join(directory, `${CACHE_TEMP_PREFIX}${process.pid.toString()}-${randomUUID()}.tmp`);
+}
+/**
+ * Create, populate, close, and publish one exclusively owned same-directory temp.
+ *
+ * Ownership begins immediately after `openSync` succeeds, so every later failure —
+ * including a partial write or close failure — triggers best-effort pathname cleanup.
+ * Descriptor ownership is cleared before the single close attempt: retrying a numeric
+ * descriptor could close an unrelated resource if the operating system reused it.
+ * Publication happens only after close succeeds and transfers the temp inode.
+ */
+function publishFromOwnedTemp(path, raw, prepare, publish) {
+    let tempPath;
+    let descriptor;
+    let ownsTemp = false;
+    try {
+        const directory = dirname(path);
+        mkdirSync(directory, { recursive: true });
+        tempPath = uniqueCacheTempPath(directory);
+        descriptor = openSync(tempPath, 'wx');
+        ownsTemp = true;
+        const bytes = Buffer.from(raw, 'utf8');
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const written = writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+            if (written === 0)
+                throw new Error('writing the cache temp made no progress');
+            offset += written;
+        }
+        prepare(descriptor);
+        const descriptorToClose = descriptor;
+        descriptor = undefined;
+        closeSync(descriptorToClose);
+        publish(tempPath);
+        ownsTemp = false;
+    }
+    catch {
+        // Cache persistence is a bandwidth optimization. The caller already has a
+        // validated in-memory manifest, so publication failures are non-fatal.
+    }
+    finally {
+        if (descriptor !== undefined) {
+            const descriptorToClose = descriptor;
+            descriptor = undefined;
+            try {
+                closeSync(descriptorToClose);
+            }
+            catch {
+                // Never retry a numeric descriptor: it may already have been reused.
+            }
+        }
+        if (ownsTemp && tempPath !== undefined) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // Pathname cleanup is best-effort; readers inspect only the final path.
+            }
+        }
+    }
+}
+/**
+ * Replace a cache with a validated HTTP 200 response via same-directory rename.
+ *
+ * Rename deliberately publishes a new inode: an existing destination's POSIX mode
+ * bits are copied to that inode, but its ACLs and xattrs are not. The operation
+ * requires write/search permission on the parent directory; it never falls back to
+ * a partial direct write when temporary-file creation or rename is unavailable.
+ */
+function replaceCacheAtomically(path, raw) {
+    publishFromOwnedTemp(path, raw, (descriptor) => {
+        // Read the mode immediately before publication. Concurrent HTTP 200 writers all
+        // preserve the established mode while rename keeps last-network-writer-wins.
+        const destination = statSync(path, { throwIfNoEntry: false });
+        if (destination !== undefined)
+            fchmodSync(descriptor, destination.mode & 0o7777);
+    }, (tempPath) => {
+        renameSync(tempPath, path);
+    });
+}
+// Every `horizon` 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;
+function manifestAfterNetworkFailure(url, cached) {
+    if (cached) {
+        process.stderr.write(`warning: could not reach ${url} — using the cached command manifest.\n`);
+        return cached.manifest;
+    }
+    throw new Error(`could not reach ${url} to fetch the command manifest, and no cached copy exists ` +
+        '(check --base-url and your network).');
+}
+/**
+ * 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.
+ * When the server is reachable, the cache is revalidated and a backend redeploy is
+ * picked up automatically. Offline, the last locally validated copy may be older
+ * than the server but keeps the CLI usable.
+ */
+export async function fetchManifest(baseUrl, apiKey) {
+    const url = supportUrl(baseUrl, '/cli/manifest');
+    const canonicalCachePath = canonicalCachePathFor(baseUrl);
+    const cached = readCache(canonicalCachePath);
+    const timeoutMs = requestTimeoutMs(MANIFEST_FETCH_TIMEOUT_MS);
+    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(timeoutMs),
+        });
+    }
+    catch {
+        return manifestAfterNetworkFailure(url, cached);
+    }
+    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 (error) {
+        // Fetch resolves once headers arrive, but the same request can still time out
+        // or fail while its body is being consumed. Only JSON syntax failures mean
+        // the server returned a malformed manifest; transport/body failures use the
+        // same validated-cache fallback as a failure before headers.
+        if (!(error instanceof SyntaxError))
+            return manifestAfterNetworkFailure(url, cached);
+        throw new Error(`the command manifest from ${url} was not valid JSON — check that --base-url ` +
+            'points at a Horizon API (not a login page or proxy).');
+    }
+    const manifest = parseManifest(json, url);
+    replaceCacheAtomically(canonicalCachePath, JSON.stringify({ etag: res.headers.get('etag') ?? undefined, manifest: json }));
+    return manifest;
+}

package/dist/permissions.d.ts

@@ -0,0 +1,46 @@
+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. 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 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;
+/** Nested resource groups — subcommands the caller can't run (separate help section). */
+export declare const UNAVAILABLE_HELP_GROUP = "Unavailable (missing permission)";
+/** A leaf command's description when the caller lacks a required permission. */
+export declare function gatedSummary(summary: string, missing: string | undefined): string;
+/** The error printed when the caller invokes a command they lack permission for. */
+export declare function permissionDeniedMessage(missing: string): string;
+/** A prominent note appended to a gated command's `--help` output. */
+export declare function permissionHelpNote(missing: string): string;
+/**
+ * `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 declare function missingRequiredPermission(granted: GrantedPermissions, required: string): string | undefined;