@labelbox/horizon-cli 0.0.0-stage → 0.0.1

package/dist/dispatch.js

@@ -0,0 +1,265 @@
+import { openAsBlob } from 'node:fs';
+import { basename } from 'node:path';
+import { baseMediaType, responseBodyKind } from './json-operation-callability.js';
+import { isMultipartRequestOperation, } from './manifest.js';
+import { requestBudget } from './request-timeout.js';
+// Every header the API trusts as caller identity or scope belongs here, not
+// just the ones a manifest happens to expose today: the denylist exists so a
+// future header parameter cannot become a flag that a caller pointed at a
+// standalone stack could set to impersonate or self-escalate.
+const RESERVED_OPERATION_HEADERS = new Set([
+    'accept',
+    'authorization',
+    'content-length',
+    'content-type',
+    'cookie',
+    'host',
+    'x-api-key',
+    'x-environment-external-id',
+    'x-labelbox-rl-data-principal-id',
+    'x-lb-auth-token',
+    'x-organization-id',
+    'x-organization-external-id',
+    'x-permissions',
+    'x-problem-external-id',
+    'x-user-external-id',
+    'x-user-id',
+]);
+// Bound every request through response headers, and through the complete body for
+// buffered JSON/text responses. Binary bodies stream after that handoff, so a
+// valid large/slow download is not killed by an unrelated request-start budget.
+const REQUEST_TIMEOUT_MS = 120_000;
+const MULTIPART_SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+async function buildMultipartBody(op, params, allowFileInputs) {
+    if (!allowFileInputs) {
+        throw new Error('multipart file inputs are unavailable in an embedded CLI');
+    }
+    const body = new FormData();
+    for (const param of op.params) {
+        if (param.in !== 'body')
+            continue;
+        const value = params[param.name];
+        if (value === undefined || value === null) {
+            if (param.required)
+                throw new Error(`missing required multipart field "${param.name}"`);
+            continue;
+        }
+        if (param.format === 'binary') {
+            if (typeof value !== 'string') {
+                throw new Error(`multipart file field "${param.name}" must be a local path`);
+            }
+            let blob;
+            try {
+                blob = await openAsBlob(value);
+            }
+            catch {
+                throw new Error(`could not read multipart file for --${param.name.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase()}: ${JSON.stringify(value)}`);
+            }
+            body.append(param.name, blob, basename(value));
+            continue;
+        }
+        if (!MULTIPART_SCALAR_TYPES.has(param.type) || typeof value === 'object') {
+            throw new Error(`multipart field "${param.name}" has unsupported type "${param.type}"`);
+        }
+        body.append(param.name, String(value));
+    }
+    return body;
+}
+/** 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/horizon/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 without coercing binary bytes through UTF-8 text. */
+async function parseBody(res, declaredMediaTypes) {
+    if (res.status === 204 || res.status === 304) {
+        await res.body?.cancel().catch(() => undefined);
+        return undefined;
+    }
+    const actualMediaType = res.headers.get('content-type');
+    if (actualMediaType !== null &&
+        declaredMediaTypes !== undefined &&
+        !declaredMediaTypes.some((declaredMediaType) => baseMediaType(declaredMediaType) === baseMediaType(actualMediaType))) {
+        throw new Error(`response for HTTP ${res.status} used undeclared Content-Type ${JSON.stringify(actualMediaType)}`);
+    }
+    if (declaredMediaTypes?.length === 0) {
+        await res.body?.cancel().catch(() => undefined);
+        return undefined;
+    }
+    if (actualMediaType === null &&
+        declaredMediaTypes !== undefined &&
+        declaredMediaTypes.length > 1) {
+        throw new Error(`response for HTTP ${res.status} omitted Content-Type; expected one of ${declaredMediaTypes.join(', ')}`);
+    }
+    const kind = responseBodyKind(actualMediaType ?? declaredMediaTypes?.[0] ?? '');
+    if (kind === 'binary') {
+        if (res.body === null)
+            throw new Error(`response for HTTP ${res.status} omitted its binary body`);
+        return res.body;
+    }
+    const text = await res.text();
+    if (text === '')
+        return kind === 'json' ? undefined : text;
+    if (kind === 'json') {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function declaredResponseHeaders(response, headers) {
+    return Object.fromEntries(response.headers.flatMap((name) => {
+        const value = headers.get(name);
+        return value === null ? [] : [[name, value]];
+    }));
+}
+/**
+ * Build and send the request for one operation, returning its status, declared
+ * headers, and parsed data without collapsing HTTP semantics. Conditional 304 is
+ * successful only when the generated contract declares it. Binary bodies remain
+ * bytes; empty non-JSON text remains an empty string. On an undeclared 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}`,
+    };
+    const acceptedMediaTypes = [
+        ...new Set(op.successResponses.flatMap(({ mediaTypes }) => mediaTypes)),
+    ];
+    if (acceptedMediaTypes.length > 0) {
+        headers['Accept'] = acceptedMediaTypes.join(', ');
+    }
+    // The guard requires org whenever env is present (env-without-org is a 403 with
+    // no body), so passing only `--scope-environment-external-id` fails upstream of the
+    // operation. Both are forwarded verbatim; the server resolves and authorizes them.
+    if (ctx.organizationExternalId !== undefined) {
+        headers['X-Organization-External-Id'] = ctx.organizationExternalId;
+    }
+    if (ctx.environmentExternalId !== undefined) {
+        headers['X-Environment-External-Id'] = ctx.environmentExternalId;
+    }
+    for (const param of op.params) {
+        if (param.in !== 'header')
+            continue;
+        if (RESERVED_OPERATION_HEADERS.has(param.name.toLowerCase())) {
+            throw new Error(`operation declares reserved request header "${param.name}"`);
+        }
+        const value = params[param.name];
+        if (value !== undefined && value !== null) {
+            // Mirrors the query path: a non-scalar survives as JSON rather than
+            // collapsing to "[object Object]".
+            headers[param.name] = typeof value === 'object' ? JSON.stringify(value) : String(value);
+        }
+    }
+    let body;
+    if (isMultipartRequestOperation(op)) {
+        body = await buildMultipartBody(op, params, ctx.allowFileInputs === true);
+    }
+    else if (op.bodyKey && params[op.bodyKey] !== undefined) {
+        body = JSON.stringify(params[op.bodyKey]);
+        headers['Content-Type'] = 'application/json';
+    }
+    const { requestTimeoutMs: timeoutMs, invocationTimeoutMs } = requestBudget(REQUEST_TIMEOUT_MS);
+    const requestController = new AbortController();
+    const requestTimeout = setTimeout(() => requestController.abort(), timeoutMs);
+    const requestSignal = invocationTimeoutMs === undefined
+        ? requestController.signal
+        : AbortSignal.any([requestController.signal, AbortSignal.timeout(invocationTimeoutMs)]);
+    let res;
+    try {
+        const response = 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: requestSignal,
+        });
+        res = response;
+        const declaredResponse = op.successResponses.find(({ status }) => status === response.status);
+        if (declaredResponse === undefined) {
+            // Horizon errors are one JSON envelope. Reject any other media type before
+            // reading it so an upstream binary body cannot be buffered or mistaken for
+            // a network failure.
+            const parsed = await parseBody(response, ['application/json']);
+            // 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 ${response.status}): ${parsed}`
+                : `request failed — HTTP ${response.status}`);
+        }
+        return {
+            data: await parseBody(response, declaredResponse.mediaTypes),
+            status: response.status,
+            headers: declaredResponseHeaders(declaredResponse, response.headers),
+        };
+    }
+    catch (err) {
+        // Only this deadline can abort the private controller. Turn that abort into a
+        // clear error; other fetch failures (refused/reset) propagate unchanged.
+        if (requestSignal.aborted) {
+            throw new Error(`request to ${url} timed out after ${timeoutMs / 1000}s`);
+        }
+        await res?.body?.cancel().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        // `parseBody` returns a binary body's native stream without consuming it.
+        // Detach that stream from the request-start timeout before handing it to stdout.
+        clearTimeout(requestTimeout);
+    }
+}

package/dist/embed.d.ts

@@ -0,0 +1,39 @@
+import { type DispatchResponse } from './dispatch.js';
+import { type Manifest, type ManifestOperation, parseManifest } from './manifest.js';
+export { isJsonOperationCallable, JSON_REQUEST_MEDIA_TYPE } from './manifest.js';
+import { type GrantedPermissions } from './permissions.js';
+export { parseManifest };
+export type { Manifest, ManifestOperation, GrantedPermissions };
+export type ManifestOperationResult = {
+    readonly failed: false;
+    readonly value: DispatchResponse;
+} | {
+    readonly failed: true;
+    readonly error: string;
+};
+export interface ExecuteManifestOperationOptions {
+    /** The generated manifest operation to dispatch. */
+    operation: ManifestOperation;
+    /** SDK-shaped input: path/query fields at top level and JSON under `bodyKey`. */
+    arguments: Record<string, unknown>;
+    /** The caller's own API key, from the request. Never the server's environment. */
+    apiKey: string;
+    /** The API to dispatch against. Server configuration, not tool input. */
+    baseUrl: string;
+    /** The caller's granted permissions, resolved by the embedding server. */
+    granted: GrantedPermissions;
+    /** Trusted organization scope resolved by the embedding server. */
+    organizationExternalId?: string;
+    /** Trusted environment scope resolved by the embedding server. */
+    environmentExternalId?: string;
+}
+/**
+ * Dispatch one generated manifest operation without routing through commander.
+ *
+ * The operation, API target, credentials, and permissions are separate from the
+ * tool arguments so caller input can only populate the operation's path, query,
+ * and JSON body. This path has no argv, shell, child-process, or filesystem
+ * behavior. Expected invocation failures resolve as a discriminated result; a
+ * missing caller API key is an embedding invariant and rejects.
+ */
+export declare function executeManifestOperation(options: ExecuteManifestOperationOptions): Promise<ManifestOperationResult>;

package/dist/embed.js

@@ -0,0 +1,51 @@
+import { dispatchOperation } from './dispatch.js';
+import { isJsonOperationCallable, parseManifest, } from './manifest.js';
+export { isJsonOperationCallable, JSON_REQUEST_MEDIA_TYPE } from './manifest.js';
+import { missingPermission } from './permissions.js';
+import { formatError } from './program.js';
+// Re-exported so an embedding server can validate and type the manifest it hands
+// in without reaching past this module's entrypoint.
+export { parseManifest };
+/**
+ * Dispatch one generated manifest operation without routing through commander.
+ *
+ * The operation, API target, credentials, and permissions are separate from the
+ * tool arguments so caller input can only populate the operation's path, query,
+ * and JSON body. This path has no argv, shell, child-process, or filesystem
+ * behavior. Expected invocation failures resolve as a discriminated result; a
+ * missing caller API key is an embedding invariant and rejects.
+ */
+export async function executeManifestOperation(options) {
+    if (options.apiKey === '') {
+        throw new Error('cannot run a manifest operation without an API key for the calling user');
+    }
+    if (!isJsonOperationCallable(options.operation)) {
+        return {
+            failed: true,
+            error: `${options.operation.operationId} has no JSON-compatible request and response representation`,
+        };
+    }
+    const missing = missingPermission(options.operation, options.granted);
+    if (missing !== undefined) {
+        return {
+            failed: true,
+            error: formatError(new Error(`you don't have permission to run this operation (requires \`${missing}\`)`)),
+        };
+    }
+    try {
+        const response = await dispatchOperation(options.operation, options.arguments, {
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            ...(options.organizationExternalId === undefined
+                ? {}
+                : { organizationExternalId: options.organizationExternalId }),
+            ...(options.environmentExternalId === undefined
+                ? {}
+                : { environmentExternalId: options.environmentExternalId }),
+        });
+        return { failed: false, value: response };
+    }
+    catch (err) {
+        return { failed: true, error: formatError(err) };
+    }
+}

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;

package/dist/git-host.js

@@ -0,0 +1,184 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+import { supportUrl } from './manifest.js';
+import { resolveCommandAuth } from './resolve.js';
+// ── bespoke `horizon scaffold` / `horizon submit` group (hand-written, not spec-derived) ──
+//
+// Claims a per-Aligner Forgejo repo for a coding-task problem, clones it locally
+// (`scaffold`), and pushes local changes back to it (`submit`). Deliberately
+// NOT `@SdkRoute`-derived commands: local `git` subprocess invocation and
+// credential injection have no place in the generic manifest-driven dispatch
+// loop, so this group is registered directly on `program`, same as `skills`.
+const GitRepoClaimSchema = z.object({
+    cloneUrl: z.string(),
+    defaultBranch: z.string(),
+    pushToken: z.string(),
+});
+/** Filename (under `.git/`) the claim's identity is stashed in after
+ *  `scaffold`, so `submit` can re-claim before every push. `submit` MUST
+ *  re-claim rather than reuse a token stashed at scaffold time: the backend
+ *  mints one push token per Aligner under a fixed name and deletes any
+ *  prior token of that name on every claim (`GitHostClient.mintPushToken`),
+ *  since the Forgejo username derives from the Aligner alone, not the
+ *  problem. Without re-claiming, scaffolding a second problem would
+ *  invalidate the first problem's stashed token and its `submit` would
+ *  401/403. */
+const CLAIM_FILE = 'horizon-forgejo-claim.json';
+const StashedClaimSchema = z.object({
+    organizationId: z.string(),
+    problemId: z.string(),
+});
+/** `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 async function claimGitRepo(args) {
+    const url = supportUrl(args.baseUrl, `/organizations/${encodeURIComponent(args.organizationId)}/git-repo-claims`);
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+            Authorization: `Bearer ${args.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ problemId: args.problemId }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`could not claim a git repo for problem ${args.problemId} — HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    const parsed = GitRepoClaimSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected response shape from ${url}`);
+    }
+    return parsed.data;
+}
+/** Writes a `GIT_ASKPASS` helper that answers "Username" prompts with a
+ *  placeholder and "Password" prompts with `token`, via an env var — never
+ *  the URL or argv, so the token never lands in shell history or `ps`
+ *  listings. Returns the env overrides to pass to the `git` subprocess and
+ *  the script's containing directory, for the caller to clean up.
+ *
+ *  `GIT_ASKPASS` must be a single executable file, not a "command args"
+ *  string — verified live: git silently never invokes a two-word value like
+ *  `"<node> <script>"` (no error, no fallback prompt — it just doesn't run),
+ *  so the script needs a `#!/usr/bin/env node` shebang and the exec bit.
+ *
+ *  The script lives in its own `mkdtempSync` directory (not a fixed,
+ *  guessable path directly under `tmpdir()`) and is written with the `wx`
+ *  flag, which refuses to follow or overwrite an existing path — closing
+ *  the local-attacker-pre-plants-a-symlink hardening gap a fixed name would
+ *  leave open, even though the script itself carries no secret (the token
+ *  rides in `HORIZON_FORGEJO_TOKEN`, not the script body). */
+function gitCredentialEnv(token) {
+    const dir = mkdtempSync(join(tmpdir(), 'horizon-forgejo-'));
+    const scriptPath = join(dir, 'askpass.cjs');
+    writeFileSync(scriptPath, '#!/usr/bin/env node\n' +
+        "const p = process.argv[2] || '';\n" +
+        "process.stdout.write(/username/i.test(p) ? 'x-access-token' : (process.env.HORIZON_FORGEJO_TOKEN || ''));\n", { flag: 'wx' });
+    chmodSync(scriptPath, 0o700);
+    return {
+        env: {
+            ...process.env,
+            // biome-ignore lint/style/useNamingConvention: environment variable names, not ours to rename
+            GIT_ASKPASS: scriptPath,
+            // biome-ignore lint/style/useNamingConvention: environment variable names, not ours to rename
+            HORIZON_FORGEJO_TOKEN: token,
+        },
+        cleanupDir: dir,
+    };
+}
+function runGit(args, cwd, token) {
+    const { env, cleanupDir } = gitCredentialEnv(token);
+    try {
+        // `-c credential.helper=` (empty) disables any configured credential
+        // helper (e.g. macOS's osxkeychain, on by default with git-for-mac) for
+        // just this invocation — found live: without it, a helper transparently
+        // caches/replays a *previous* claim's credential for the same host,
+        // silently shadowing GIT_ASKPASS and authenticating as the wrong claim
+        // (or failing on an expired one) instead of using the fresh token below.
+        const result = spawnSync('git', ['-c', 'credential.helper=', ...args], {
+            cwd,
+            env,
+            stdio: 'inherit',
+        });
+        if (result.status !== 0) {
+            throw new Error(`git ${args.join(' ')} failed (exit ${result.status ?? 'unknown'})`);
+        }
+    }
+    finally {
+        rmSync(cleanupDir, { recursive: true, force: true });
+    }
+}
+function claimFilePath(repoDir) {
+    return join(repoDir, '.git', CLAIM_FILE);
+}
+function stashClaim(repoDir, claim) {
+    writeFileSync(claimFilePath(repoDir), JSON.stringify(claim), { mode: 0o600 });
+}
+function readStashedClaim(repoDir) {
+    const path = claimFilePath(repoDir);
+    if (!existsSync(path)) {
+        throw new Error(`no claim found at ${path} — run \`horizon scaffold\` in this directory first, or pass --path to point at a scaffolded repo`);
+    }
+    const parsed = StashedClaimSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+    if (!parsed.success) {
+        throw new Error(`stashed claim at ${path} has an unexpected shape`);
+    }
+    return parsed.data;
+}
+/** Register the `scaffold` / `submit` commands on `program`. */
+export function addGitHostCommands(program, helpGroup) {
+    program
+        .command('scaffold <problemId>')
+        .helpGroup(helpGroup)
+        .description('Claim a per-Aligner git repo for a coding-task problem and clone it locally')
+        .requiredOption('--organization-id <id>', 'Organization the problem belongs to')
+        .option('--out <dir>', 'Directory to clone into (default: derived from the repo name)')
+        .action(async (problemId, opts) => {
+        try {
+            const { apiKey, baseUrl } = resolveCommandAuth(program);
+            const claim = await claimGitRepo({
+                apiKey,
+                baseUrl,
+                organizationId: opts.organizationId,
+                problemId,
+            });
+            const dir = opts.out ?? basename(claim.cloneUrl).replace(/\.git$/u, '');
+            mkdirSync(dir, { recursive: true });
+            runGit(['clone', claim.cloneUrl, dir], process.cwd(), claim.pushToken);
+            stashClaim(dir, { organizationId: opts.organizationId, problemId });
+            process.stdout.write(`Cloned into ${dir} (branch ${claim.defaultBranch}). Ready to work.\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    program
+        .command('submit')
+        .helpGroup(helpGroup)
+        .description('Push local changes in a scaffolded repo back to its claimed remote')
+        .option('--path <dir>', 'Path to the scaffolded repo (default: current directory)')
+        .action(async (opts) => {
+        const dir = opts.path ?? process.cwd();
+        try {
+            // Re-claims rather than reusing a token stashed at `scaffold` time —
+            // see `CLAIM_FILE`'s doc comment: the backend's push token is a
+            // single fixed-name credential per Aligner, so scaffolding any other
+            // problem since would have invalidated a stashed one.
+            const stashed = readStashedClaim(dir);
+            const { apiKey, baseUrl } = resolveCommandAuth(program);
+            const claim = await claimGitRepo({ apiKey, baseUrl, ...stashed });
+            runGit(['push'], dir, claim.pushToken);
+            process.stdout.write('Pushed.\n');
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+}

package/dist/json-operation-callability.d.ts

@@ -0,0 +1,31 @@
+/** The manifest fields needed to decide whether a generic JSON caller can invoke an operation. */
+export interface JsonOperationCallabilityInput {
+    readonly requestMediaTypes?: readonly string[] | undefined;
+    readonly successResponses: readonly {
+        readonly mediaTypes: readonly string[];
+    }[];
+}
+export declare const JSON_REQUEST_MEDIA_TYPE = "application/json";
+export declare const MULTIPART_REQUEST_MEDIA_TYPE = "multipart/form-data";
+export type ResponseBodyKind = 'json' | 'text' | 'binary';
+export declare function baseMediaType(mediaType: string): string;
+/** How a generic HTTP client must consume a successful response representation. */
+export declare function responseBodyKind(mediaType: string): ResponseBodyKind;
+/** The distinct body transports declared across every generated success response. */
+export declare function successResponseBodyKinds(operation: JsonOperationCallabilityInput): readonly ResponseBodyKind[];
+/** Whether any generated success representation requires a byte-stream transport. */
+export declare function hasBinarySuccessRepresentation(operation: JsonOperationCallabilityInput): boolean;
+/** The first generated success representation when it is not JSON. */
+export declare function nonJsonSuccessMediaType(operation: JsonOperationCallabilityInput): string | undefined;
+/** A bodyless operation has no request representation and remains JSON-callable. */
+export declare function hasJsonRequestRepresentation(operation: JsonOperationCallabilityInput): boolean;
+/**
+ * Whether a generic JSON caller can invoke this manifest operation without a
+ * filesystem or binary response transport.
+ *
+ * Keep this module dependency-free: DX loads it from source during cold
+ * bootstrap, before the CLI package has a dist directory.
+ */
+export declare function isJsonOperationCallable(operation: JsonOperationCallabilityInput): boolean;
+/** Whether the operation's usable non-JSON representation is multipart form data. */
+export declare function isMultipartRequestOperation(operation: JsonOperationCallabilityInput): boolean;

package/dist/json-operation-callability.js

@@ -0,0 +1,57 @@
+export const JSON_REQUEST_MEDIA_TYPE = 'application/json';
+export const MULTIPART_REQUEST_MEDIA_TYPE = 'multipart/form-data';
+export function baseMediaType(mediaType) {
+    return (mediaType.split(';')[0] ?? '').trim().toLowerCase();
+}
+/** How a generic HTTP client must consume a successful response representation. */
+export function responseBodyKind(mediaType) {
+    const base = baseMediaType(mediaType);
+    if (base === JSON_REQUEST_MEDIA_TYPE || base.endsWith('+json'))
+        return 'json';
+    if (base === '' ||
+        base.startsWith('text/') ||
+        base === 'application/xml' ||
+        base.endsWith('+xml') ||
+        base === 'application/yaml' ||
+        base.endsWith('+yaml') ||
+        base === 'application/javascript') {
+        return 'text';
+    }
+    return 'binary';
+}
+/** The distinct body transports declared across every generated success response. */
+export function successResponseBodyKinds(operation) {
+    return [
+        ...new Set(operation.successResponses.flatMap(({ mediaTypes }) => mediaTypes.map(responseBodyKind))),
+    ];
+}
+/** Whether any generated success representation requires a byte-stream transport. */
+export function hasBinarySuccessRepresentation(operation) {
+    return successResponseBodyKinds(operation).includes('binary');
+}
+/** The first generated success representation when it is not JSON. */
+export function nonJsonSuccessMediaType(operation) {
+    return operation.successResponses
+        .flatMap(({ mediaTypes }) => mediaTypes)
+        .find((mediaType) => responseBodyKind(mediaType) !== 'json');
+}
+/** A bodyless operation has no request representation and remains JSON-callable. */
+export function hasJsonRequestRepresentation(operation) {
+    return (operation.requestMediaTypes === undefined ||
+        operation.requestMediaTypes.includes(JSON_REQUEST_MEDIA_TYPE));
+}
+/**
+ * Whether a generic JSON caller can invoke this manifest operation without a
+ * filesystem or binary response transport.
+ *
+ * Keep this module dependency-free: DX loads it from source during cold
+ * bootstrap, before the CLI package has a dist directory.
+ */
+export function isJsonOperationCallable(operation) {
+    return hasJsonRequestRepresentation(operation) && !hasBinarySuccessRepresentation(operation);
+}
+/** Whether the operation's usable non-JSON representation is multipart form data. */
+export function isMultipartRequestOperation(operation) {
+    return (operation.requestMediaTypes?.includes(MULTIPART_REQUEST_MEDIA_TYPE) === true &&
+        !operation.requestMediaTypes.includes(JSON_REQUEST_MEDIA_TYPE));
+}