@zudojs/api 1.1.1 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/api
 
-Higher-level API layer — operation definitions, execution context, interceptors, and a transport-agnostic executor. Sits above `@zudojs/http` and `@zudojs/cqrs`.
+Higher-level API layer — operation definitions, execution context, interceptors, a transport-agnostic executor, and bindings that expose one operation over HTTP, RPC, queues and the CLI. `@zudojs/http` mounts it; it never imports `@zudojs/http`.
 
 <!-- zudo-docs:start -->
 
@@ -12,7 +12,7 @@ Higher-level API layer — operation definitions, execution context, interceptor
 
 Import this when you need:
 
-- define an operation once and call it from HTTP, RPC, queue, or CLI
+- define an operation once and serve it over HTTP (`createApiFetchHandler`), RPC (`registerApiRpcProcedures`), a queue (`bindApiQueue`), and the CLI (`runApiCli`)
 - apply the same interceptors (auth, logging, retry) regardless of transport
 - typed `APIContext` flowing through every handler
 
@@ -68,6 +68,8 @@ import {
 } from "@zudojs/api";
 ```
 
+The bindings add `createApiFetchHandler`, `describeApiRoutes`, `resolveApiRoute`, `registerApiRpcProcedures`, `createApiRpcProcedure`, `apiErrorToRPCError`, `bindApiQueue`, `createApiQueueProcessor`, `runApiCli`, `parseApiCliArgs`, `APICliExitCode`, `toApiWireResult`, `toApiWireError`, `TransportContextKey` and the types `APIOperationRoute`, `APIOperationHttpOptions`, `APIWireResult`, `APIWireError` and each binding's options — see [Bindings](#bindings-one-operation-many-transports).
+
 Every API error class from `@zudojs/errors` (`APIError`, `APIValidationError`, `APIInternalError`, `APIOperationNotFoundError`, …) plus `createAPIError`, `isAPIError` and `ErrorCode` are re-exported for convenience.
 
 ## Usage
@@ -120,6 +122,147 @@ if (result.ok) {
 
 Results are frozen `{ ok: true, data }` / `{ ok: false, error }` objects — `execute` never throws for an operation failure.
 
+## Bindings: one operation, many transports
+
+Every binding runs calls through an `APIExecutor` you pass as `executor` (so its interceptors apply everywhere), validates input with the operation's schema (after the interceptors), sets `TransportContextKey` (`"http" | "rpc" | "queue" | "cli"`) on the context, and reports each non-exposed failure to `onInternalError(error, requestId)`. The `state` option builds `context.state` from what the transport hands over (the `Request`, the `RPCContext`, the `Job`, the CLI invocation); throw an `APIError` there, such as `APIAuthenticationError`, to refuse the call.
+
+Failures take one client-safe shape everywhere, `APIWireError`: `{ code, message, statusCode, requestId, issues? }`. `message` is the error's own only when it is `expose: true`, otherwise `"An internal error occurred."`. Stack traces, causes and metadata never leave the process.
+
+```typescript
+import { schema } from "@zudojs/schema";
+import { APIExecutor, APIOperationRegistry, defineOperation } from "@zudojs/api";
+
+const getUser = defineOperation({
+  name: "users.get",
+  input: schema.object({ id: schema.string() }),
+  metadata: { http: { method: "GET", path: "/users/:id" } }, // default: POST /users.get
+  handler: async (input) => db.findUser(input.id),
+});
+
+const registry = new APIOperationRegistry();
+registry.register(getUser);
+registry.freeze();
+const executor = new APIExecutor({ interceptors: [logging] });
+```
+
+### HTTP: a web-standard fetch handler
+
+```typescript
+import { createApiFetchHandler } from "@zudojs/api";
+
+const handle = createApiFetchHandler(registry, {
+  executor,
+  basePath: "/api",
+  state: (request) => ({ user: verify(request.headers.get("authorization")) }),
+});
+
+// Any Fetch API server: @zudojs/http, Bun.serve, Deno.serve, an edge runtime.
+const response = await handle(new Request("https://app.test/api/users/u1"));
+// 200 { "ok": true, "data": { ... } }
+```
+
+On `@zudojs/http`, mount it with no glue code. `mountFetchHandler` strips the mount prefix by default, so leave `basePath` unset:
+
+```typescript
+import { mountFetchHandler } from "@zudojs/http";
+
+mountFetchHandler(router, "/api", createApiFetchHandler(registry, { executor }));
+```
+
+`GET` and `DELETE` routes read input from the query string (values are strings, so use coercing schemas); `POST`, `PUT` and `PATCH` read a JSON body (at most `maxBodyBytes`, 1 MiB by default). Path parameters are merged over either and win. A `__proto__`, `constructor` or `prototype` key anywhere in the query or body is refused with 400, and a body route answers 415 to any declared content type other than JSON, even with an empty body, so a cross-site HTML form cannot trigger it. Every binding (RPC, queue, CLI) refuses such keys in its input too, with a validation error. Errors use their status: 422 validation, 404 unknown route, 405 wrong method (with `Allow`), 413/415/400 for a bad body, 500 internal. The request id comes from a safe `x-request-id` header and is echoed back; the call runs under `request.signal`.
+
+### Route contract for `@zudojs/http` and OpenAPI
+
+`describeApiRoutes(operations, { basePath })` returns one frozen `APIOperationRoute` per operation and throws on invalid or conflicting routes:
+
+```typescript
+interface APIOperationRoute {
+  readonly operationId: string; // operation name
+  readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  readonly path: string; // "/api/users/:id"
+  readonly pathParams: readonly string[]; // ["id"]
+  readonly inputSource: "query" | "body";
+  readonly input?: unknown; // the operation's input schema
+  readonly output?: unknown; // the operation's output schema
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly deprecated?: boolean;
+  readonly version?: string;
+  readonly successStatus: 200;
+}
+```
+
+### OpenAPI
+
+`toOpenAPIRouteDescriptors(operations, { basePath })` turns the same routes into `@zudojs/openapi` descriptors, so one call documents what the fetch handler serves:
+
+```typescript
+import { createOpenAPIDocumentFromRoutes } from "@zudojs/openapi";
+import { toOpenAPIRouteDescriptors } from "@zudojs/api";
+
+const document = createOpenAPIDocumentFromRoutes(
+  toOpenAPIRouteDescriptors(registry, { basePath: "/api" }),
+  { info: { title: "Users", version: "1.0.0" } },
+);
+```
+
+Each descriptor carries `operationId`, method, path, description, tags and `deprecated`. The input schema becomes `query` (`GET` / `DELETE`) or `body`, with path-bound fields moved to `params`. `responses` documents 200 with the `{ ok: true, data }` envelope around the output schema, and 422, 404, 409, 500 and 504 with the `{ ok: false, error }` body. Only `@zudojs/schema` schemas are converted; with another schema library, input stays undocumented and `data` is `unknown`.
+
+### RPC
+
+```typescript
+import { RPCClient, RPCServer, createRPCMemoryTransport } from "@zudojs/rpc";
+import { registerApiRpcProcedures } from "@zudojs/api";
+
+const server = new RPCServer();
+registerApiRpcProcedures(server, registry, {
+  executor,
+  state: (rpc) => ({ user: rpc.auth?.userId }), // transport-verified, never frame metadata
+});
+
+const client = new RPCClient(createRPCMemoryTransport(server));
+await client.call("users.get", { id: "u1" });
+```
+
+Procedure names default to the operation name, which must then be a valid RPC name (`"users.get"`); pass `procedureName` to map others. API errors become their RPC equivalents (`RPC_VALIDATION_ERROR` with issues, `RPC_UNAUTHENTICATED`, `RPC_FORBIDDEN`, `RPC_RATE_LIMITED`, `RPC_TIMEOUT`, …); any other keeps its code, such as `ERR_API_CONFLICT`. Serve the same server over HTTP with `createRPCFetchHandler(server)`, for example `mountFetchHandler(router, "/rpc", createRPCFetchHandler(server))` on `@zudojs/http`.
+
+### Queues
+
+```typescript
+import { createInMemoryQueue, createQueueName } from "@zudojs/queue";
+import { bindApiQueue } from "@zudojs/api";
+
+const queue = createInMemoryQueue(createQueueName("operations"));
+bindApiQueue(queue, registry, { executor });
+
+await queue.add("users.get", { id: "u1" }, { attempts: 1 });
+```
+
+The job name is the operation name and `job.data` is the input. Success completes the job with the output. A failure throws an `APIError` carrying the client-safe message, so the queue retries and dead-letters it as usual. Validation failures are retried too, so enqueue unchecked input with `attempts: 1`.
+
+### CLI
+
+```typescript
+#!/usr/bin/env node
+import { runApiCli } from "@zudojs/api";
+
+const controller = new AbortController();
+process.once("SIGINT", () => controller.abort());
+process.exitCode = await runApiCli(registry, process.argv.slice(2), {
+  executor,
+  programName: "app",
+  signal: controller.signal,
+});
+```
+
+```bash
+app users.get --id u1                      # prints the output as JSON, exit 0
+app users.create --json '{"name":"Ann"}' --address.city Paris --admin
+app --help                                 # lists operations
+```
+
+The operation name comes first (or pass `operation` for a single-purpose binary). `--field value` and `--field=value` set fields; kebab-case becomes camelCase, dots nest, repeats collect arrays, `--flag` is `true` and `--no-flag` is `false`. JSON-looking values (numbers, `true`, `false`, `null`, `{…}`, `[…]`) are parsed; anything else stays a string. On failure the `{ ok: false, error }` body goes to stderr and the exit code follows `APICliExitCode`: 64 usage, 65 invalid input, 69 unavailable, 70 internal, 75 timeout, 77 permission, 130 cancelled, 1 otherwise.
+
 ## Input validation
 
 The executor accepts two kinds of schema for `input` and `output`, recognised structurally so the package depends on no validation library:
@@ -143,7 +286,9 @@ const charge = defineOperation({
 });
 ```
 
-The executor validates the input before the handler runs and passes the schema's _transformed_ value to the handler. Failures return an `APIValidationError` (422).
+The executor validates the input immediately before the handler runs, after every interceptor, and passes the schema's _transformed_ value to the handler. Failures return an `APIValidationError` (422). Because the interceptors run first, an authentication interceptor refuses an anonymous call with its own error (401) before the input is inspected, so a 422 describing the schema never reaches an unauthenticated caller; logging, metrics and rate-limit interceptors see invalid calls (`context.result` is the 422); and an interceptor that replaces `context.input` cannot bypass the schema, since the replacement is what gets validated.
+
+Without type arguments, `defineOperation` infers the handler's `input` from the `input` schema: a Standard Schema's declared output type, or the `data` of a `safeParse` schema's success result. That works inline too, as in `registry.register(defineOperation({ input: TodoInput, handler: async (input) => input.title }))` or an operation list passed to a binding. Explicit type arguments (`defineOperation<TInput, TOutput>(...)`) are still honoured as given. `InferAPISchemaOutput<typeof schema>` names the inferred type.
 
 Schema issue messages routinely interpolate the value that failed, so by default the executor does **not** copy them into the client-facing error: each issue becomes `"<path>: invalid"` (e.g. `"user.email: invalid"`), naming where validation failed without echoing what was submitted. The list is capped at `MAX_VALIDATION_ISSUES` entries with a trailing `"… and N more issue(s) omitted."` marker.
 
@@ -161,14 +306,25 @@ When `operation.output` is set, the handler's return value is validated too, and
 
 Every operation has a deadline. `timeout` must be a positive, finite integer of at most `MAX_OPERATION_TIMEOUT` milliseconds; `defineOperation` rejects `0`, negatives, `NaN` and non-integers rather than silently running unbounded. Precedence is `timeout` → `metadata.timeout` → `DEFAULT_OPERATION_TIMEOUT`, resolved by `resolveOperationTimeout`.
 
-The handler itself is not cancellable — pass `context.signal` into anything that supports it. An execution cancelled through the signal fails with `ErrorCode.OPERATION_CANCELLED`; branch on that code rather than on the (nginx-convention) 499 status.
+The handler always receives a `context.signal`, even when the caller supplied none. It aborts when the deadline elapses (its `reason` is the `APITimeoutError` the call fails with, 504) or when the caller's signal aborts (its `reason` is the `ErrorCode.OPERATION_CANCELLED` error the call fails with), so pass it into anything that supports it (`fetch`, a driver query, a loop check) and the work stops instead of running on and repeating side effects after the caller has given up. The signal is not aborted when the handler completes normally. Everything else on the handler's context (`requestId`, `state`, `get`/`set`, `metadata`) is the caller's context. Branch on `ErrorCode.OPERATION_CANCELLED` rather than on the (nginx-convention) 499 status.
+
+```typescript
+const exportReport = defineOperation({
+  name: "reports.export",
+  timeout: 10_000,
+  handler: async (input, context) => {
+    const rows = await fetch(reportUrl, { signal: context.signal }); // stops at the deadline
+    return rows.json();
+  },
+});
+```
 
 ## Interceptors
 
 ```typescript
 const timing: APIInterceptor = {
   async intercept(context, next) {
-    context.input = sanitize(context.input); // reaches the handler
+    context.input = sanitize(context.input); // validated, then reaches the handler
     const started = Date.now();
     const result = await next();
     // context.result === result, including when a downstream interceptor
@@ -181,7 +337,7 @@ const timing: APIInterceptor = {
 new APIExecutor([timing]); // or new APIExecutor({ interceptors: [timing] })
 ```
 
-At most `MAX_INTERCEPTORS` interceptors per executor, and each `next()` may be awaited once.
+At most `MAX_INTERCEPTORS` interceptors per executor, and each `next()` may be awaited once. Interceptors run outermost first and wrap input validation: `context.input` is the input as the caller sent it (not yet validated or transformed), and whatever an interceptor leaves there is validated before the handler sees it.
 
 ## Context
 

package/dist/api/bindings/cli/apiCli.argv.d.ts

@@ -0,0 +1,36 @@
+import type { Serializer } from "@zudojs/serialization";
+/**
+ * Parsed command line: the operation named on it (when the CLI serves
+ * several), the input object built from flags, and whether help was asked
+ * for. A malformed command line is reported as `{ ok: false, message }`.
+ */
+export type APICliParseResult = {
+    readonly ok: true;
+    readonly operation?: string;
+    readonly input: unknown;
+    readonly help: boolean;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Parses CLI arguments into operation input.
+ *
+ * - `--name value`, `--name=value`: sets `input.name`. Kebab-case becomes
+ *   camelCase (`--first-name` → `firstName`); dots nest
+ *   (`--address.city Paris`).
+ * - A value that is a JSON number, `true`, `false` or `null`, or starts
+ *   with `{`, `[` or `"`, is parsed as JSON; anything else stays a string.
+ * - `--flag` with no value is `true`; `--no-flag` is `false`.
+ * - A repeated flag collects an array.
+ * - `--json '<object>'` supplies a base input object the flags merge over,
+ *   or any JSON input when no other flags are given.
+ * - `--help` / `-h` requests help.
+ *
+ * @param expectOperation Whether the first positional argument names the
+ * operation.
+ * @param serializer JSON parser for values. Defaults to a size- and
+ * depth-limited `@zudojs/serialization` JSON serializer.
+ */
+export declare function parseApiCliArgs(argv: readonly string[], expectOperation: boolean, serializer?: Serializer<unknown, string>): APICliParseResult;
+//# sourceMappingURL=apiCli.argv.d.ts.map

package/dist/api/bindings/cli/apiCli.argv.js

@@ -0,0 +1,78 @@
+import { createSerializer } from "@zudojs/serialization";
+import { isPlainObject } from "@zudojs/types";
+import { assignOption, camelCase, coerceOptionValue, parseJson } from "./apiCli.values.js";
+const DEFAULT_SERIALIZER = createSerializer("json", { maxSize: 1024 * 1024, maxDepth: 64 });
+const KEY_SEGMENT = /^[A-Za-z_$][\w$-]*$/;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Parses CLI arguments into operation input.
+ *
+ * - `--name value`, `--name=value`: sets `input.name`. Kebab-case becomes
+ *   camelCase (`--first-name` → `firstName`); dots nest
+ *   (`--address.city Paris`).
+ * - A value that is a JSON number, `true`, `false` or `null`, or starts
+ *   with `{`, `[` or `"`, is parsed as JSON; anything else stays a string.
+ * - `--flag` with no value is `true`; `--no-flag` is `false`.
+ * - A repeated flag collects an array.
+ * - `--json '<object>'` supplies a base input object the flags merge over,
+ *   or any JSON input when no other flags are given.
+ * - `--help` / `-h` requests help.
+ *
+ * @param expectOperation Whether the first positional argument names the
+ * operation.
+ * @param serializer JSON parser for values. Defaults to a size- and
+ * depth-limited `@zudojs/serialization` JSON serializer.
+ */
+export function parseApiCliArgs(argv, expectOperation, serializer = DEFAULT_SERIALIZER) {
+    const fields = {};
+    let base;
+    let operation;
+    let help = false;
+    let flagCount = 0;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--help" || token === "-h") {
+            help = true;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            if (expectOperation && operation === undefined) {
+                operation = token;
+                continue;
+            }
+            return { ok: false, message: `Unexpected argument "${token}".` };
+        }
+        const eq = token.indexOf("=");
+        const rawKey = eq === -1 ? token.slice(2) : token.slice(2, eq);
+        const next = argv[i + 1];
+        let raw = eq === -1 ? undefined : token.slice(eq + 1);
+        if (raw === undefined && next !== undefined && !next.startsWith("--")) {
+            raw = next;
+            i += 1;
+        }
+        if (rawKey === "json") {
+            const parsed = parseJson(raw, serializer);
+            if (!parsed.ok) {
+                return { ok: false, message: "--json must be followed by valid JSON." };
+            }
+            base = parsed.value;
+            continue;
+        }
+        const negated = raw === undefined && rawKey.startsWith("no-");
+        const path = (negated ? rawKey.slice(3) : rawKey).split(".").map(camelCase);
+        if (path.some((segment) => !KEY_SEGMENT.test(segment) || UNSAFE_KEYS.has(segment))) {
+            return { ok: false, message: `Invalid option "--${rawKey}".` };
+        }
+        const value = raw === undefined ? !negated : coerceOptionValue(raw, serializer);
+        if (!assignOption(fields, path, value)) {
+            return { ok: false, message: `Option "--${rawKey}" conflicts with another option.` };
+        }
+        flagCount += 1;
+    }
+    if (flagCount > 0 && base !== undefined && !isPlainObject(base)) {
+        return { ok: false, message: "--json must be an object when combined with other options." };
+    }
+    const input = flagCount === 0 ? (base ?? {}) : { ...(isPlainObject(base) ? base : {}), ...fields };
+    return { ok: true, ...(operation !== undefined ? { operation } : {}), input, help };
+}
+//# sourceMappingURL=apiCli.argv.js.map

package/dist/api/bindings/cli/apiCli.binding.d.ts

@@ -0,0 +1,45 @@
+import type { APIBindingOptions, APIOperationSource } from "../shared/apiBinding.type.js";
+import type { APICliExitCodeValue } from "./apiCli.exitCode.js";
+/**
+ * One CLI call as the `state` hook sees it.
+ */
+export interface APICliInvocation {
+    readonly argv: readonly string[];
+    readonly input: unknown;
+}
+/**
+ * Where the CLI writes. Defaults to `process.stdout` / `process.stderr`.
+ */
+export interface APICliIO {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+/**
+ * Options for {@link runApiCli}. `state` receives the invocation.
+ */
+export interface APICliOptions extends APIBindingOptions<APICliInvocation> {
+    readonly io?: APICliIO;
+    /** Cancels the running operation (wire it to SIGINT). */
+    readonly signal?: AbortSignal;
+    /**
+     * Run this operation instead of reading its name from `argv[0]` — for a
+     * single-purpose binary.
+     */
+    readonly operation?: string;
+    /** Program name shown in help. Defaults to `"cli"`. */
+    readonly programName?: string;
+}
+/**
+ * Runs an operation from command-line arguments and returns the exit code.
+ *
+ * `argv` is `process.argv.slice(2)`: the operation name first (unless
+ * `options.operation` fixes it), then `--field value` options and/or
+ * `--json '{...}'` (see `parseApiCliArgs`). On success the output is
+ * printed to stdout as JSON and the exit code is 0. On failure the same
+ * client-safe `{ ok: false, error }` body the HTTP binding sends is
+ * printed to stderr, and the exit code reflects the failure (see
+ * {@link APICliExitCode}). Never calls `process.exit`, and never throws
+ * for a failed call — only for an invalid operation list.
+ */
+export declare function runApiCli(operations: APIOperationSource, argv: readonly string[], options?: APICliOptions): Promise<APICliExitCodeValue>;
+//# sourceMappingURL=apiCli.binding.d.ts.map

package/dist/api/bindings/cli/apiCli.binding.js

@@ -0,0 +1,77 @@
+import { createSerializer } from "@zudojs/serialization";
+import { createOperationRunner, listOperations } from "../shared/apiBinding.helper.js";
+import { toApiWireResult } from "../shared/apiWireResult.helper.js";
+import { normalizeAPIError } from "../../executor/executor.core.js";
+import { parseApiCliArgs } from "./apiCli.argv.js";
+import { APICliExitCode, apiCliExitCodeForStatus } from "./apiCli.exitCode.js";
+const PRETTY = createSerializer("json", { pretty: true });
+/**
+ * Runs an operation from command-line arguments and returns the exit code.
+ *
+ * `argv` is `process.argv.slice(2)`: the operation name first (unless
+ * `options.operation` fixes it), then `--field value` options and/or
+ * `--json '{...}'` (see `parseApiCliArgs`). On success the output is
+ * printed to stdout as JSON and the exit code is 0. On failure the same
+ * client-safe `{ ok: false, error }` body the HTTP binding sends is
+ * printed to stderr, and the exit code reflects the failure (see
+ * {@link APICliExitCode}). Never calls `process.exit`, and never throws
+ * for a failed call — only for an invalid operation list.
+ */
+export async function runApiCli(operations, argv, options = {}) {
+    const io = options.io ?? defaultIO();
+    const known = listOperations(operations);
+    const fixed = options.operation;
+    const parsed = parseApiCliArgs(argv, fixed === undefined);
+    if (!parsed.ok) {
+        io.stderr(`${parsed.message}\n`);
+        return APICliExitCode.USAGE;
+    }
+    const name = fixed ?? parsed.operation;
+    if (parsed.help || name === undefined) {
+        (parsed.help ? io.stdout : io.stderr)(usage(known, options.programName ?? "cli", fixed));
+        return parsed.help ? APICliExitCode.OK : APICliExitCode.USAGE;
+    }
+    const operation = known.find((candidate) => candidate.name === name);
+    if (operation === undefined) {
+        io.stderr(`Unknown operation "${name}". Run with --help to list operations.\n`);
+        return APICliExitCode.USAGE;
+    }
+    const run = createOperationRunner(options);
+    const { result, requestId } = await run({
+        operation,
+        input: parsed.input,
+        source: { argv, input: parsed.input },
+        transport: "cli",
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    const wire = toApiWireResult(result, requestId);
+    if (!wire.ok) {
+        io.stderr(`${PRETTY.serialize(wire)}\n`);
+        return apiCliExitCodeForStatus(wire.error.statusCode);
+    }
+    try {
+        if (wire.data !== undefined) {
+            io.stdout(`${PRETTY.serialize(wire.data)}\n`);
+        }
+        return APICliExitCode.OK;
+    }
+    catch (error) {
+        const failure = normalizeAPIError(error, operation.name);
+        options.onInternalError?.(failure, requestId);
+        io.stderr(`${PRETTY.serialize(toApiWireResult({ ok: false, error: failure }, requestId))}\n`);
+        return APICliExitCode.INTERNAL;
+    }
+}
+function usage(operations, program, fixed) {
+    const shown = fixed === undefined ? operations : operations.filter((op) => op.name === fixed);
+    const lines = shown.map((op) => `  ${op.name}${op.metadata?.description !== undefined ? `  ${op.metadata.description}` : ""}`);
+    const call = fixed === undefined ? `${program} <operation>` : program;
+    return `Usage: ${call} [--field value ...] [--json '<input>']\n\nOperations:\n${lines.join("\n")}\n`;
+}
+function defaultIO() {
+    return {
+        stdout: (text) => void process.stdout.write(text),
+        stderr: (text) => void process.stderr.write(text),
+    };
+}
+//# sourceMappingURL=apiCli.binding.js.map

package/dist/api/bindings/cli/apiCli.exitCode.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Exit codes returned by `runApiCli`, following BSD `sysexits.h` where a
+ * code fits so shell scripts can branch on the kind of failure.
+ */
+export declare const APICliExitCode: Readonly<{
+    /** The operation succeeded. */
+    OK: 0;
+    /** The operation failed with a client error that has no closer code. */
+    FAILURE: 1;
+    /** Bad command line: unknown operation, malformed option (EX_USAGE). */
+    USAGE: 64;
+    /** Input failed validation (EX_DATAERR). */
+    INVALID_INPUT: 65;
+    /** Rate limited or unavailable; try again later (EX_UNAVAILABLE). */
+    UNAVAILABLE: 69;
+    /** Internal error (EX_SOFTWARE). */
+    INTERNAL: 70;
+    /** Timed out (EX_TEMPFAIL). */
+    TIMEOUT: 75;
+    /** Not authenticated or not permitted (EX_NOPERM). */
+    PERMISSION: 77;
+    /** Cancelled through the abort signal (128 + SIGINT). */
+    CANCELLED: 130;
+}>;
+/** One of the {@link APICliExitCode} values. */
+export type APICliExitCodeValue = (typeof APICliExitCode)[keyof typeof APICliExitCode];
+/**
+ * Maps a failed result's HTTP-style status to an exit code.
+ */
+export declare function apiCliExitCodeForStatus(status: number): APICliExitCodeValue;
+//# sourceMappingURL=apiCli.exitCode.d.ts.map

package/dist/api/bindings/cli/apiCli.exitCode.js

@@ -0,0 +1,43 @@
+/**
+ * Exit codes returned by `runApiCli`, following BSD `sysexits.h` where a
+ * code fits so shell scripts can branch on the kind of failure.
+ */
+export const APICliExitCode = Object.freeze({
+    /** The operation succeeded. */
+    OK: 0,
+    /** The operation failed with a client error that has no closer code. */
+    FAILURE: 1,
+    /** Bad command line: unknown operation, malformed option (EX_USAGE). */
+    USAGE: 64,
+    /** Input failed validation (EX_DATAERR). */
+    INVALID_INPUT: 65,
+    /** Rate limited or unavailable; try again later (EX_UNAVAILABLE). */
+    UNAVAILABLE: 69,
+    /** Internal error (EX_SOFTWARE). */
+    INTERNAL: 70,
+    /** Timed out (EX_TEMPFAIL). */
+    TIMEOUT: 75,
+    /** Not authenticated or not permitted (EX_NOPERM). */
+    PERMISSION: 77,
+    /** Cancelled through the abort signal (128 + SIGINT). */
+    CANCELLED: 130,
+});
+/**
+ * Maps a failed result's HTTP-style status to an exit code.
+ */
+export function apiCliExitCodeForStatus(status) {
+    if (status === 400 || status === 422)
+        return APICliExitCode.INVALID_INPUT;
+    if (status === 401 || status === 403)
+        return APICliExitCode.PERMISSION;
+    if (status === 408 || status === 504)
+        return APICliExitCode.TIMEOUT;
+    if (status === 429 || status === 503)
+        return APICliExitCode.UNAVAILABLE;
+    if (status === 499)
+        return APICliExitCode.CANCELLED;
+    if (status >= 500)
+        return APICliExitCode.INTERNAL;
+    return APICliExitCode.FAILURE;
+}
+//# sourceMappingURL=apiCli.exitCode.js.map

package/dist/api/bindings/cli/apiCli.values.d.ts

@@ -0,0 +1,24 @@
+import type { Serializer } from "@zudojs/serialization";
+/** Converts a kebab-case option segment to camelCase. */
+export declare function camelCase(segment: string): string;
+/** Parses JSON text, reporting failure instead of throwing. */
+export declare function parseJson(raw: string | undefined, serializer: Serializer<unknown, string>): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+};
+/**
+ * Parses an option value that looks like JSON (a number, `true`, `false`,
+ * `null`, or text starting with `{`, `[` or `"`); keeps anything else, and
+ * any number JSON would round, as the string typed.
+ */
+export declare function coerceOptionValue(raw: string, serializer: Serializer<unknown, string>): unknown;
+/**
+ * Sets `value` at a dotted `path`, collecting repeats into an array.
+ * Returns `false` when the path collides with an existing scalar or
+ * object. Only own properties count, so `--to-string` cannot collide
+ * with `Object.prototype`.
+ */
+export declare function assignOption(target: Record<string, unknown>, path: readonly string[], value: unknown): boolean;
+//# sourceMappingURL=apiCli.values.d.ts.map

package/dist/api/bindings/cli/apiCli.values.js

@@ -0,0 +1,71 @@
+import { isPlainObject } from "@zudojs/types";
+const JSON_LITERAL = /^(?:-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)$/;
+/** Converts a kebab-case option segment to camelCase. */
+export function camelCase(segment) {
+    return segment.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+/** Parses JSON text, reporting failure instead of throwing. */
+export function parseJson(raw, serializer) {
+    if (raw === undefined) {
+        return { ok: false };
+    }
+    try {
+        return { ok: true, value: serializer.deserialize(raw) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Parses an option value that looks like JSON (a number, `true`, `false`,
+ * `null`, or text starting with `{`, `[` or `"`); keeps anything else, and
+ * any number JSON would round, as the string typed.
+ */
+export function coerceOptionValue(raw, serializer) {
+    const looksJson = JSON_LITERAL.test(raw) || /^[[{"]/.test(raw);
+    if (!looksJson) {
+        return raw;
+    }
+    const parsed = parseJson(raw, serializer);
+    return parsed.ok && !isLossyNumber(parsed.value) ? parsed.value : raw;
+}
+/**
+ * A number JSON cannot hand back faithfully — an integer beyond 2^53 or
+ * an overflow to Infinity — is kept as the string the user typed.
+ */
+function isLossyNumber(value) {
+    return (typeof value === "number" &&
+        (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))));
+}
+/**
+ * Sets `value` at a dotted `path`, collecting repeats into an array.
+ * Returns `false` when the path collides with an existing scalar or
+ * object. Only own properties count, so `--to-string` cannot collide
+ * with `Object.prototype`.
+ */
+export function assignOption(target, path, value) {
+    let node = target;
+    for (const segment of path.slice(0, -1)) {
+        const child = Object.hasOwn(node, segment) ? node[segment] : undefined;
+        if (child === undefined) {
+            node[segment] = {};
+        }
+        else if (!isPlainObject(child)) {
+            return false;
+        }
+        node = node[segment];
+    }
+    const leaf = path[path.length - 1];
+    const existing = Object.hasOwn(node, leaf) ? node[leaf] : undefined;
+    if (existing === undefined) {
+        node[leaf] = value;
+    }
+    else if (isPlainObject(existing)) {
+        return false;
+    }
+    else {
+        node[leaf] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+    }
+    return true;
+}
+//# sourceMappingURL=apiCli.values.js.map

package/dist/api/bindings/cli/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI binding: parses command-line arguments into operation input, runs
+ * the operation, prints the result as JSON, and returns an exit code. No
+ * dependency on any CLI framework.
+ */
+export type { APICliInvocation, APICliIO, APICliOptions } from "./apiCli.binding.js";
+export { runApiCli } from "./apiCli.binding.js";
+export type { APICliParseResult } from "./apiCli.argv.js";
+export { parseApiCliArgs } from "./apiCli.argv.js";
+export type { APICliExitCodeValue } from "./apiCli.exitCode.js";
+export { APICliExitCode, apiCliExitCodeForStatus } from "./apiCli.exitCode.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/bindings/cli/index.js

@@ -0,0 +1,9 @@
+/**
+ * CLI binding: parses command-line arguments into operation input, runs
+ * the operation, prints the result as JSON, and returns an exit code. No
+ * dependency on any CLI framework.
+ */
+export { runApiCli } from "./apiCli.binding.js";
+export { parseApiCliArgs } from "./apiCli.argv.js";
+export { APICliExitCode, apiCliExitCodeForStatus } from "./apiCli.exitCode.js";
+//# sourceMappingURL=index.js.map