@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/dist/request-timeout.d.ts

@@ -0,0 +1,8 @@
+export interface RequestBudget {
+    readonly requestTimeoutMs: number;
+    readonly invocationTimeoutMs?: number;
+}
+/** Resolve the local request cap and optional whole-invocation recipe deadline. */
+export declare function requestBudget(defaultTimeoutMs: number): RequestBudget;
+/** Bound one finite fetch by its local cap and any whole-invocation deadline. */
+export declare function requestTimeoutMs(defaultTimeoutMs: number): number;

package/dist/request-timeout.js

@@ -0,0 +1,33 @@
+const REQUEST_TIMEOUT_ENV = 'HORIZON_REQUEST_TIMEOUT_MS';
+const REQUEST_DEADLINE_ENV = 'HORIZON_REQUEST_DEADLINE_MS';
+const MAX_NODE_TIMER_DURATION_MS = 2_147_483_647;
+function positiveIntegerEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive safe integer (received ${raw})`);
+    }
+    return parsed;
+}
+/** Resolve the local request cap and optional whole-invocation recipe deadline. */
+export function requestBudget(defaultTimeoutMs) {
+    const configuredTimeoutMs = positiveIntegerEnv(REQUEST_TIMEOUT_ENV) ?? defaultTimeoutMs;
+    const deadlineMs = positiveIntegerEnv(REQUEST_DEADLINE_ENV);
+    const invocationTimeoutMs = deadlineMs === undefined ? undefined : deadlineMs - Date.now();
+    if (invocationTimeoutMs !== undefined && invocationTimeoutMs <= 0) {
+        throw new Error(`${REQUEST_DEADLINE_ENV} elapsed before the request could start`);
+    }
+    const boundedInvocationTimeoutMs = Math.min(invocationTimeoutMs ?? MAX_NODE_TIMER_DURATION_MS, MAX_NODE_TIMER_DURATION_MS);
+    return {
+        requestTimeoutMs: Math.min(defaultTimeoutMs, configuredTimeoutMs, boundedInvocationTimeoutMs),
+        ...(invocationTimeoutMs === undefined
+            ? {}
+            : { invocationTimeoutMs: boundedInvocationTimeoutMs }),
+    };
+}
+/** Bound one finite fetch by its local cap and any whole-invocation deadline. */
+export function requestTimeoutMs(defaultTimeoutMs) {
+    return requestBudget(defaultTimeoutMs).requestTimeoutMs;
+}

package/dist/resolve.d.ts

@@ -0,0 +1,53 @@
+import type { Command } from 'commander';
+import type { DispatchContext as DispatchScope } from './dispatch.js';
+/** Read a global flag's value from argv (`--name value` or `--name=value`). */
+export declare function flagValue(argv: string[], name: string): string | undefined;
+/** `--api-key` wins over `LABELBOX_API_KEY`; undefined when neither is set. */
+export declare function resolveApiKey(argv: string[]): string | undefined;
+/** The canonical Horizon API base URL from the environment. */
+export declare function envBaseUrl(): string | undefined;
+/** `--base-url` wins over `HORIZON_BASE_URL`, falling back to the production host. */
+export declare function resolveBaseUrl(argv: string[]): string;
+/**
+ * The options declared on the root `horizon` command, as seen by anything that
+ * reads `program.opts()`. The single definition for the whole package — program.ts,
+ * git-host.ts, skills.ts and compute-session.ts all read the same five flags, and
+ * four copies of this shape could disagree about which ones exist.
+ */
+export interface GlobalOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Only the manifest-driven dispatch loop renders differently for it. */
+    quiet?: boolean;
+    /** Scope headers for operations whose authorization is not derivable from the
+     *  body — see `DispatchContext` in dispatch.ts. */
+    scopeOrganizationExternalId?: string;
+    scopeEnvironmentExternalId?: string;
+}
+/** Program-scoped equivalent of `resolveBaseUrl`, for commands registered outside
+ *  the manifest-driven dispatch loop. Never throws — some of them (the `skills`
+ *  reads) hit public endpoints and need a base URL without a key. */
+export declare function commandBaseUrl(program: Command): string;
+/** Program-scoped equivalent of `resolveApiKey`; undefined when neither
+ *  `--api-key` nor `LABELBOX_API_KEY` is set. */
+export declare function commandApiKey(program: Command): string | undefined;
+/**
+ * The scope headers to attach to a dispatched request, omitting either when it is
+ * not configured.
+ *
+ * Returned as a partial object so the caller can spread it: `exactOptionalPropertyTypes`
+ * makes an explicit `undefined` a type error where the field is `?:`, and an absent
+ * key is also what `dispatchOperation` tests for.
+ *
+ * Environment fallback belongs only to the terminal CLI. Embedded callers run
+ * inside a server process whose environment is not part of the authenticated
+ * caller's request context, so `buildProgram` disables it for that mode.
+ */
+export declare function commandScope(program: Command, allowEnvironmentFallback?: boolean): Pick<DispatchScope, 'organizationExternalId' | 'environmentExternalId'>;
+/** Program-scoped equivalent of `resolveApiKey` + `resolveBaseUrl`, for commands
+ *  registered outside the manifest-driven dispatch loop. Throws when no key is
+ *  configured, since every such command authenticates as the caller. */
+export declare function resolveCommandAuth(program: Command): {
+    apiKey: string;
+    baseUrl: string;
+};

package/dist/resolve.js

@@ -0,0 +1,111 @@
+import process from 'node:process';
+import { DEFAULT_BASE_URL } from './manifest.js';
+// Resolving the API key + base URL from argv + env, before commander parses — the
+// live CLI needs both up front to fetch the command manifest the rest of the tree
+// is built from. Global flags precede the command (documented), so a flat argv scan
+// is sufficient and matches commander's later parse. Extracted from bin.ts so the
+// precedence is unit-testable (bin.ts runs `main()` on import).
+/** Read a global flag's value from argv (`--name value` or `--name=value`). */
+export function flagValue(argv, name) {
+    const eq = argv.find((arg) => arg.startsWith(`--${name}=`));
+    if (eq)
+        return eq.slice(name.length + 3);
+    const index = argv.indexOf(`--${name}`);
+    if (index >= 0) {
+        // The space-form value is the next token — but only if it isn't itself an
+        // option (`horizon --api-key --quiet`): a dangling `--api-key` has no value, so we
+        // return undefined and let the env fallback apply rather than silently
+        // consuming `--quiet` as a bogus (non-empty) key. Values that legitimately
+        // start with `-` use the `--name=value` form above.
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith('-'))
+            return next;
+    }
+    return undefined;
+}
+/** `--api-key` wins over `LABELBOX_API_KEY`; undefined when neither is set. */
+export function resolveApiKey(argv) {
+    const { LABELBOX_API_KEY: envApiKey } = process.env;
+    return flagValue(argv, 'api-key') ?? envApiKey;
+}
+/** The canonical Horizon API base URL from the environment. */
+export function envBaseUrl() {
+    return process.env['HORIZON_BASE_URL'];
+}
+/** `--base-url` wins over `HORIZON_BASE_URL`, falling back to the production host. */
+export function resolveBaseUrl(argv) {
+    return flagValue(argv, 'base-url') ?? envBaseUrl() ?? DEFAULT_BASE_URL;
+}
+/** Program-scoped equivalent of `resolveBaseUrl`, for commands registered outside
+ *  the manifest-driven dispatch loop. Never throws — some of them (the `skills`
+ *  reads) hit public endpoints and need a base URL without a key. */
+export function commandBaseUrl(program) {
+    const { baseUrl } = program.opts();
+    return baseUrl ?? envBaseUrl() ?? DEFAULT_BASE_URL;
+}
+/** Program-scoped equivalent of `resolveApiKey`; undefined when neither
+ *  `--api-key` nor `LABELBOX_API_KEY` is set. */
+export function commandApiKey(program) {
+    const { apiKey } = program.opts();
+    const { LABELBOX_API_KEY: envApiKey } = process.env;
+    return apiKey ?? envApiKey;
+}
+/**
+ * The scope headers to attach to a dispatched request, omitting either when it is
+ * not configured.
+ *
+ * Returned as a partial object so the caller can spread it: `exactOptionalPropertyTypes`
+ * makes an explicit `undefined` a type error where the field is `?:`, and an absent
+ * key is also what `dispatchOperation` tests for.
+ *
+ * Environment fallback belongs only to the terminal CLI. Embedded callers run
+ * inside a server process whose environment is not part of the authenticated
+ * caller's request context, so `buildProgram` disables it for that mode.
+ */
+export function commandScope(program, allowEnvironmentFallback = true) {
+    const { scopeOrganizationExternalId, scopeEnvironmentExternalId } = program.opts();
+    const envOrg = allowEnvironmentFallback
+        ? process.env['LABELBOX_ORGANIZATION_EXTERNAL_ID']
+        : undefined;
+    const envEnvironment = allowEnvironmentFallback
+        ? process.env['HORIZON_ENVIRONMENT_EXTERNAL_ID']
+        : undefined;
+    const org = scopeOrganizationExternalId ?? envOrg;
+    const environment = scopeEnvironmentExternalId ?? envEnvironment;
+    if (org !== undefined && org.trim() === '') {
+        throw new Error('organization scope must not be empty — set --scope-organization-external-id' +
+            (allowEnvironmentFallback ? ' or LABELBOX_ORGANIZATION_EXTERNAL_ID' : '') +
+            ' to a non-empty value');
+    }
+    if (environment !== undefined && environment.trim() === '') {
+        throw new Error('environment scope must not be empty — set --scope-environment-external-id' +
+            (allowEnvironmentFallback ? ' or HORIZON_ENVIRONMENT_EXTERNAL_ID' : '') +
+            ' to a non-empty value');
+    }
+    // Env structurally requires org — the guard's own hierarchy, enforced before any
+    // lookup. Sending env alone earns a bare `ForbiddenException()` with no body,
+    // which surfaces as an opaque `Forbidden` that names neither the missing header
+    // nor the unset env var. Unlike the guard's other 403s, this one is a
+    // well-formedness violation rather than an authorization answer, so pre-empting
+    // it locally costs no oracle-resistance and matches how every other doomed
+    // request in this CLI is caught before it leaves.
+    if (environment !== undefined && org === undefined) {
+        throw new Error('an environment scope implies an organization scope — set --scope-organization-external-id' +
+            (allowEnvironmentFallback ? ' or LABELBOX_ORGANIZATION_EXTERNAL_ID' : '') +
+            ' alongside the environment');
+    }
+    return {
+        ...(org === undefined ? {} : { organizationExternalId: org }),
+        ...(environment === undefined ? {} : { environmentExternalId: environment }),
+    };
+}
+/** Program-scoped equivalent of `resolveApiKey` + `resolveBaseUrl`, for commands
+ *  registered outside the manifest-driven dispatch loop. Throws when no key is
+ *  configured, since every such command authenticates as the caller. */
+export function resolveCommandAuth(program) {
+    const apiKey = commandApiKey(program);
+    if (!apiKey) {
+        throw new Error('missing API key — set LABELBOX_API_KEY or pass --api-key');
+    }
+    return { apiKey, baseUrl: commandBaseUrl(program) };
+}

package/dist/run.d.ts

@@ -0,0 +1,44 @@
+import type { Writable } from 'node:stream';
+import type { Manifest } from './manifest.js';
+import type { GrantedPermissions } from './permissions.js';
+export interface RunDeps {
+    /** Full argv including the node + script entries, as `parseAsync` expects. */
+    argv: string[];
+    /**
+     * Resolves the CLI version lazily. A thunk (not a plain string) so a throw from
+     * reading package.json happens *inside* `run()` — surfacing as a rejected promise
+     * bin.ts renders via `fail()`, not a raw stack trace before the promise exists.
+     */
+    version: () => string;
+    fetchManifest: (baseUrl: string, apiKey: string) => Promise<Manifest>;
+    /**
+     * Resolves the caller's granted permissions for the per-command gate. Never
+     * rejects — it resolves to `undefined` (fail-open) on any failure, so a
+     * permissions outage degrades to "gate nothing", never to a broken CLI.
+     */
+    fetchPermissions: (baseUrl: string, apiKey: string) => Promise<GrantedPermissions>;
+    stdout: (text: string) => void;
+    /** Byte-preserving terminal output. Omitted by filesystem-less embedded callers. */
+    binaryStdout?: Writable;
+    stderr: (text: string) => void;
+    /**
+     * Whether `scaffold`, `submit`, `skills`, `computes open`, and `computes tools`
+     * are registered at all, and whether request scope may fall back to the process
+     * environment. See `ProgramContext.localCheckout` — the terminal entrypoint
+     * passes `true`, an embedding server passes `false` so server configuration
+     * cannot become caller request scope.
+     */
+    localCheckout: boolean;
+}
+/**
+ * Resolve `--version` and the no-key branches with no network, then fetch the
+ * manifest and build + run the command tree.
+ *
+ * **Never throws and never exits.** It returns the exit code the caller should
+ * use, having already rendered any failure to `deps.stderr`. That contract is
+ * what lets the MCP endpoint run one `horizon` invocation in-process on behalf of an
+ * agent: a thrown error would become a 500 instead of a tool result, and a
+ * `process.exit` would take the API server down mid-request. `bin.ts` is the only
+ * caller that turns the returned code back into a real exit.
+ */
+export declare function run(deps: RunDeps): Promise<number>;

package/dist/run.js

@@ -0,0 +1,81 @@
+import { CommanderError } from 'commander';
+import { buildBaseProgram, buildProgram, formatError } from './program.js';
+import { resolveApiKey, resolveBaseUrl } from './resolve.js';
+// The CLI orchestration, extracted from bin.ts (which runs it on import) so it has a
+// seam for unit tests: the `--version` short-circuit and the no-key branches all
+// resolve *before* any network, and that "works offline / with no key" guarantee
+// lives only here. Dependencies (the manifest fetch + the output sink) are injected.
+const MISSING_KEY_MESSAGE = 'missing API key — set LABELBOX_API_KEY or pass --api-key (the CLI fetches its commands from the server)';
+/**
+ * Resolve `--version` and the no-key branches with no network, then fetch the
+ * manifest and build + run the command tree.
+ *
+ * **Never throws and never exits.** It returns the exit code the caller should
+ * use, having already rendered any failure to `deps.stderr`. That contract is
+ * what lets the MCP endpoint run one `horizon` invocation in-process on behalf of an
+ * agent: a thrown error would become a 500 instead of a tool result, and a
+ * `process.exit` would take the API server down mid-request. `bin.ts` is the only
+ * caller that turns the returned code back into a real exit.
+ */
+export async function run(deps) {
+    try {
+        return await execute(deps);
+    }
+    catch (err) {
+        // Commander signals help and `--version` by throwing with exitCode 0 — the text
+        // has already gone to the sinks, so that is a success, not a failure. Its real
+        // errors (unknown command, bad option value) have likewise already been written
+        // by `writeErr`, so re-rendering them here would duplicate the message.
+        if (err instanceof CommanderError)
+            return err.exitCode;
+        deps.stderr(`error: ${formatError(err)}\n`);
+        return 1;
+    }
+}
+async function execute(deps) {
+    const args = deps.argv.slice(2);
+    // Resolve inside execute() (not in bin.ts at the call site) so a throw is caught
+    // by run()'s handler and rendered, not an uncaught synchronous crash.
+    const version = deps.version();
+    // `--version` is the one thing that works with no key and no network — resolve it
+    // before fetching the manifest the rest of the CLI is built from.
+    if (args.includes('--version') || args.includes('-V')) {
+        deps.stdout(`${version}\n`);
+        return 0;
+    }
+    // Pre-resolve auth (before commander parses) — threaded into the program so the
+    // manifest fetch and per-op dispatch use exactly one source.
+    const apiKey = resolveApiKey(args);
+    const baseUrl = resolveBaseUrl(args);
+    if (!apiKey) {
+        // Top-level help still prints (global flags + a hint); everything else needs the
+        // key, since the command tree itself comes from the gated manifest.
+        if (args.includes('--help') || args.includes('-h')) {
+            buildBaseProgram(version, deps, deps.localCheckout)
+                .addHelpText('after', '\nSet LABELBOX_API_KEY (or pass --api-key) — the CLI fetches its commands from the server.')
+                .outputHelp();
+            return 0;
+        }
+        throw new Error(MISSING_KEY_MESSAGE);
+    }
+    // The manifest (command surface) and the caller's permissions (the per-command
+    // gate) are independent fetches — run them together. The permissions fetch
+    // never rejects (fail-open), so this can't turn a permissions outage into a
+    // CLI failure.
+    const [manifest, granted] = await Promise.all([
+        deps.fetchManifest(baseUrl, apiKey),
+        deps.fetchPermissions(baseUrl, apiKey),
+    ]);
+    const program = buildProgram(manifest, {
+        apiKey,
+        baseUrl,
+        version,
+        granted,
+        localCheckout: deps.localCheckout,
+        stdout: deps.stdout,
+        ...(deps.binaryStdout === undefined ? {} : { binaryStdout: deps.binaryStdout }),
+        stderr: deps.stderr,
+    });
+    await program.parseAsync(deps.argv);
+    return 0;
+}

package/dist/skills.d.ts

@@ -0,0 +1,73 @@
+import type { Command } from 'commander';
+import { z } from 'zod';
+/**
+ * The canonical Horizon skill installed when no name is given.
+ */
+export declare const DEFAULT_SKILL_NAME = "horizon";
+/** sha256 (hex) of the markdown with any injected `skill-version:` line removed. */
+export declare function skillVersionHash(text: string): string;
+/** The `skill-version` value stamped into a file's frontmatter, if present. */
+export declare function stampedVersion(content: string): string | undefined;
+export type SkillStatus = 'missing' | 'up-to-date' | 'out-of-date';
+/** Compare an installed file (or its absence) against the latest published version. */
+export declare function skillStatus(installed: string | undefined, latestVersion: string): SkillStatus;
+/**
+ * True if the installed file looks locally modified: its recomputed body hash
+ * doesn't match its own `skill-version` stamp, or it carries no stamp at all
+ * (unknown provenance). Such a file is never overwritten without `--force`.
+ */
+export declare function isHandEdited(installed: string): boolean;
+declare const SkillPayloadSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+type SkillPayload = z.infer<typeof SkillPayloadSchema>;
+declare const SkillSummarySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+type SkillSummary = z.infer<typeof SkillSummarySchema>;
+/**
+ * Fetch `{ name, version, content }` for a skill from `GET /v1/skills/<name>`.
+ *
+ * Exported only so `support-urls.test.ts` can assert its hand-written URL join
+ * against the committed spec, alongside the other support endpoints.
+ */
+export declare function fetchSkill(name: string, apiKey: string, baseUrl: string): Promise<SkillPayload>;
+/**
+ * Fetch the catalog of installable skills from `GET /skills`. The endpoint is now
+ * gated (the CLI always has a key — `bin.ts` requires one before any command), so
+ * the key is sent when present; it stays optional here only so the function is
+ * reusable in contexts that legitimately have none.
+ */
+export declare function listSkills(opts: {
+    apiKey?: string | undefined;
+    baseUrl: string;
+}): Promise<SkillSummary[]>;
+/** Programmatic core of `horizon skills check` — fetch latest, read installed, compare. */
+export declare function checkSkill(name: string, opts: {
+    apiKey: string;
+    baseUrl: string;
+    skillFile?: string | undefined;
+}): Promise<{
+    status: SkillStatus;
+    latestVersion: string;
+}>;
+/** Raised when `install` refuses to clobber a locally-modified file (no `--force`). */
+export declare class HandEditedError extends Error {
+}
+/** Programmatic core of `horizon skills install` — fetch latest and write it (guarded). */
+export declare function installSkill(name: string, opts: {
+    apiKey: string;
+    baseUrl: string;
+    skillFile?: string | undefined;
+    force?: boolean | undefined;
+}): Promise<{
+    path: string;
+    action: 'installed' | 'updated' | 'unchanged';
+    version: string;
+}>;
+/** Register the `skills check` / `skills install` command group on `program`. */
+export declare function addSkillsCommands(program: Command, docsHelpGroup: string): void;
+export {};

package/dist/skills.js

@@ -0,0 +1,235 @@
+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';
+import { supportUrl } from './manifest.js';
+import { commandApiKey, commandBaseUrl, resolveCommandAuth } from './resolve.js';
+// ── bespoke `horizon skills` group (hand-written, not spec-derived) ────────────────
+//
+// Keeps a downloaded Claude skill current. The platform serves each skill from
+// `GET /skills/:skillName` with a content-hash version; this group fetches that,
+// compares it to the installed `~/.claude/skills/<name>/SKILL.md`, and refreshes
+// it. The package defaults to the canonical `horizon` skill. Deliberately NOT an
+// `@SdkRoute` endpoint — that would auto-generate a colliding `horizon skills` command.
+/**
+ * The canonical Horizon skill installed when no name is given.
+ */
+export const DEFAULT_SKILL_NAME = 'horizon';
+// ── hash contract — MUST stay byte-identical to apps/horizon/api/src/skills/skill-hash.ts ──
+// (the two packages share no published runtime dependency). A committed fixture
+// pins the same hash in both test suites so the duplication can't drift.
+/** A single `skill-version:` line (with its trailing newline), anywhere in the text. */
+const SKILL_VERSION_LINE = /^skill-version:.*\r?\n/m;
+/** sha256 (hex) of the markdown with any injected `skill-version:` line removed. */
+export function skillVersionHash(text) {
+    return createHash('sha256').update(text.replace(SKILL_VERSION_LINE, ''), 'utf8').digest('hex');
+}
+/** The `skill-version` value stamped into a file's frontmatter, if present. */
+export function stampedVersion(content) {
+    return /^skill-version:[ \t]*(\S+)[ \t]*\r?$/m.exec(content)?.[1];
+}
+/** Compare an installed file (or its absence) against the latest published version. */
+export function skillStatus(installed, latestVersion) {
+    if (installed === undefined)
+        return 'missing';
+    return stampedVersion(installed) === latestVersion ? 'up-to-date' : 'out-of-date';
+}
+/**
+ * True if the installed file looks locally modified: its recomputed body hash
+ * doesn't match its own `skill-version` stamp, or it carries no stamp at all
+ * (unknown provenance). Such a file is never overwritten without `--force`.
+ */
+export function isHandEdited(installed) {
+    const stamped = stampedVersion(installed);
+    if (stamped === undefined)
+        return true;
+    return skillVersionHash(installed) !== stamped;
+}
+// Validate every API response at the I/O boundary with Zod. The backend owns the
+// authoritative schemas in skills.dto.ts; these are the minimal CLI-side mirrors.
+const SkillPayloadSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+    content: z.string(),
+});
+const SkillSummarySchema = z.object({
+    name: z.string(),
+    description: z.string(),
+});
+// Each `horizon skills` fetch is bounded for the same reason as the manifest fetch
+// (see manifest.ts): a server that accepts the connection but never responds would
+// otherwise hang `horizon skills check`/`install`/`list` indefinitely. The timeout makes
+// `fetch` reject so the caller surfaces a clear error rather than blocking forever.
+const SKILLS_FETCH_TIMEOUT_MS = 30_000;
+/**
+ * Fetch `{ name, version, content }` for a skill from `GET /v1/skills/<name>`.
+ *
+ * Exported only so `support-urls.test.ts` can assert its hand-written URL join
+ * against the committed spec, alongside the other support endpoints.
+ */
+export async function fetchSkill(name, apiKey, baseUrl) {
+    const url = supportUrl(baseUrl, `/skills/${encodeURIComponent(name)}`);
+    const res = await fetch(url, {
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(SKILLS_FETCH_TIMEOUT_MS),
+    });
+    if (res.status === 404) {
+        throw new Error(`unknown skill "${name}" (the platform has no skill by that name)`);
+    }
+    if (!res.ok) {
+        throw new Error(`could not fetch skill "${name}" — HTTP ${res.status}`);
+    }
+    const parsed = SkillPayloadSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected response shape from ${url}`);
+    }
+    return parsed.data;
+}
+/**
+ * Fetch the catalog of installable skills from `GET /skills`. The endpoint is now
+ * gated (the CLI always has a key — `bin.ts` requires one before any command), so
+ * the key is sent when present; it stays optional here only so the function is
+ * reusable in contexts that legitimately have none.
+ */
+export async function listSkills(opts) {
+    const url = supportUrl(opts.baseUrl, '/skills');
+    const res = await fetch(url, {
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        headers: opts.apiKey === undefined ? {} : { Authorization: `Bearer ${opts.apiKey}` },
+        signal: AbortSignal.timeout(SKILLS_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`could not list skills — HTTP ${res.status}`);
+    }
+    const parsed = z.array(SkillSummarySchema).safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected response shape from ${url}`);
+    }
+    return parsed.data;
+}
+/** Global install path for a skill, unless `--skill-file` overrides it. */
+function installedPath(name, skillFile) {
+    return skillFile ?? join(homedir(), '.claude', 'skills', name, 'SKILL.md');
+}
+function readInstalled(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Programmatic core of `horizon skills check` — fetch latest, read installed, compare. */
+export async function checkSkill(name, opts) {
+    const latest = await fetchSkill(name, opts.apiKey, opts.baseUrl);
+    const installed = readInstalled(installedPath(name, opts.skillFile));
+    return { status: skillStatus(installed, latest.version), latestVersion: latest.version };
+}
+/** Raised when `install` refuses to clobber a locally-modified file (no `--force`). */
+export class HandEditedError extends Error {
+}
+/** Programmatic core of `horizon skills install` — fetch latest and write it (guarded). */
+export async function installSkill(name, opts) {
+    const latest = await fetchSkill(name, opts.apiKey, opts.baseUrl);
+    const path = installedPath(name, opts.skillFile);
+    const existing = readInstalled(path);
+    if (existing !== undefined && opts.force !== true && isHandEdited(existing)) {
+        throw new HandEditedError(`${path} looks hand-edited (its content no longer matches its skill-version stamp). ` +
+            'Refusing to overwrite — re-run with --force to replace it with the published version.');
+    }
+    // Already the published version — don't rewrite the file (no mtime churn) or
+    // claim a change happened; `install` run directly is then honest that nothing
+    // needs to take effect.
+    if (existing === latest.content) {
+        return { path, action: 'unchanged', version: latest.version };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, latest.content);
+    return {
+        path,
+        action: existing === undefined ? 'installed' : 'updated',
+        version: latest.version,
+    };
+}
+/** Register the `skills check` / `skills install` command group on `program`. */
+export function addSkillsCommands(program, docsHelpGroup) {
+    const skills = program
+        .command('skills')
+        .helpGroup(docsHelpGroup)
+        .description('Install and update the downloadable Claude skills for this platform');
+    skills
+        .command('list')
+        .description('List the skills available to install')
+        .action(async () => {
+        try {
+            // The CLI always has a key by the time any command runs (bin.ts requires
+            // one), so pass it through; the endpoint is gated like everything else.
+            const available = await listSkills({
+                apiKey: commandApiKey(program),
+                baseUrl: commandBaseUrl(program),
+            });
+            if (available.length === 0) {
+                process.stdout.write('No skills are available.\n');
+                return;
+            }
+            const lines = available.map((s) => s.description ? `  ${s.name} — ${s.description}` : `  ${s.name}`);
+            process.stdout.write(`Installable skills (run \`horizon skills install <name>\`):\n${lines.join('\n')}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    skills
+        .command('check [name]')
+        .description('Report whether the installed skill matches the latest published version')
+        .option('--skill-file <path>', 'Check this file instead of the global ~/.claude/skills path')
+        .action(async (name, opts) => {
+        const skill = name ?? DEFAULT_SKILL_NAME;
+        try {
+            const { apiKey, baseUrl } = resolveCommandAuth(program);
+            const { status } = await checkSkill(skill, { apiKey, baseUrl, skillFile: opts.skillFile });
+            if (status === 'up-to-date') {
+                process.stdout.write(`${skill} is up to date.\n`);
+                return;
+            }
+            const lead = status === 'missing' ? 'is not installed' : 'is out of date';
+            process.stdout.write(`${skill} ${lead} — run \`horizon skills install ${skill}\`.\n`);
+            process.exit(1);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    skills
+        .command('install [name]')
+        .description('Install or update a skill to the latest published version')
+        .option('--force', 'Overwrite even if the installed file looks hand-edited')
+        .option('--skill-file <path>', 'Write to this file instead of the global ~/.claude/skills path')
+        .action(async (name, opts) => {
+        const skill = name ?? DEFAULT_SKILL_NAME;
+        try {
+            const { apiKey, baseUrl } = resolveCommandAuth(program);
+            const { path, action, version } = await installSkill(skill, {
+                apiKey,
+                baseUrl,
+                skillFile: opts.skillFile,
+                force: opts.force,
+            });
+            if (action === 'unchanged') {
+                process.stdout.write(`${skill} is already up to date (version ${version.slice(0, 12)}).\n`);
+                return;
+            }
+            process.stdout.write(`${action === 'installed' ? 'Installed' : 'Updated'} ${skill} → ${path} ` +
+                `(version ${version.slice(0, 12)}). Takes effect on the next /${skill}.\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read at runtime so the tag-only publish flow's stamped version is reported;
+ * local/dev builds will report the committed placeholder (0.0.0).
+ */
+export declare function readCliVersion(): string;