@crustjs/openapi 0.0.0 → 0.1.1

package/README.md

@@ -1,3 +1,15 @@
 # @crustjs/openapi
 
-This `0.0.0` version is an empty placeholder, published once so the package can use npm trusted publishing. Do not install it. The first real release will be `0.1.0`. See https://crustjs.com.
+Call a CLI's HTTP API and browse its OpenAPI spec from an api command
+
+`apiCommand({ spec, baseUrl, auth, paginate })` adds `<cli> api`, a `gh api`-style escape hatch: `--list` and `--spec` read the bundled OpenAPI document offline, and `api <path>` sends an authenticated request and prints the response body, byte for byte to a pipe or file. With the `json()` Extension, `--json` prints each mode's data as JSON on stdout. It also provides the `apiClient` Context, so your own commands share the same base URL and auth.
+
+## Install
+
+```sh
+npm install @crustjs/openapi
+```
+
+## Documentation
+
+Full docs: [crustjs.com/docs/modules/openapi](https://crustjs.com/docs/modules/openapi)

package/dist/index.d.ts

@@ -0,0 +1,134 @@
+import { CommandDefinition, CommandShape, ContextFactory, ContextInstance, ContextSetup, ExtensionFactory } from "@crustjs/core";
+import { JsonValue } from "@crustjs/utils/json";
+interface ApiClientOptions {
+  /** URL request paths resolve against, e.g. `https://api.example.com/v1`. */
+  readonly baseUrl: string;
+  /**
+   * Headers added to requests to the base URL's origin, e.g. an `Authorization` header, or any
+   * default header such as `User-Agent` or an API-version header. All of them are treated as
+   * credentials: they are never sent off the base URL's origin.
+   * Called at most once per invocation, on the first request that sends credentials: never
+   * for a command that only reads the Context, nor for requests with `auth: false`.
+   */
+  readonly auth?: (input: ContextSetup) => Readonly<Record<string, string>> | undefined | Promise<Readonly<Record<string, string>> | undefined>;
+}
+/** The `api` Context value: `fetch()` bound to the API's base URL and auth. */
+interface ApiClient {
+  readonly baseUrl: string;
+  /**
+   * `fetch()` for `path` below {@link ApiClient.baseUrl} (an absolute URL is used as is, but
+   * must be on the base URL's origin: otherwise it rejects with a `TypeError` before any request),
+   * with the `auth` headers the request does not set itself, and the invocation's signal
+   * unless `init.signal` is given. Redirects are followed here
+   * (up to 20 per request, http: and https: only); one to another origin than the base URL's
+   * continues without `Authorization`, `Cookie`, `Proxy-Authorization`, or any header named like an `auth` header.
+   * With `auth: false` (e.g. a public operation), neither the request nor its redirects
+   * call `auth` or carry its headers.
+   */
+  fetch(path: string, init?: RequestInit & {
+    readonly auth?: false;
+  }): Promise<Response>;
+}
+/**
+ * The shared API client Context. {@link apiCommand} provides it, so app commands
+ * declare `.use(apiClient)` and call `(await ctx.api).fetch("/users")`.
+ */
+export declare const apiClient: ContextFactory<"api", ApiClientOptions, ApiClient>;
+/**
+ * An OpenAPI document; only `paths` and local `$ref` targets are read. Keys of `paths`
+ * not starting with `/`, such as `x-*` extensions, are skipped.
+ */
+interface OpenApiSpec {
+  readonly paths?: Readonly<Record<string, unknown>>;
+  readonly [key: string]: unknown;
+}
+/** A request for {@link ApiClient.fetch}; without `init`, the previous request's is reused. */
+interface ApiRequest {
+  readonly path: string;
+  readonly init?: RequestInit;
+}
+interface ApiCommandOptions extends ApiClientOptions {
+  /**
+   * The OpenAPI document, e.g. an imported JSON file bundled with the CLI and read offline;
+   * or a loader for it, called with the invocation's signal only when `api --list` or
+   * `api --spec` runs, e.g. a lazy `import()` of the JSON file that keeps it out of startup.
+   */
+  readonly spec: OpenApiSpec | ((input: {
+    signal: AbortSignal;
+  }) => OpenApiSpec | Promise<OpenApiSpec>);
+  /**
+   * The next page's request for `--paginate`, or `undefined` after the last page.
+   * Receives a copy of each successful response, so it may read the body. The next page
+   * must be http(s); off the base URL's origin it is requested without credential headers.
+   * Returning the previous request again (same URL and method, `init` reused) fails instead of looping.
+   */
+  readonly paginate?: (response: Response) => ApiRequest | undefined | Promise<ApiRequest | undefined>;
+}
+/**
+ * A non-2xx response to `api <path>`; its body was already printed (to stderr under `--json`).
+ * The `json()` Extension prints its `status` as the error's `details`.
+ */
+export declare class ApiResponseError extends Error {
+  override name: string;
+  /** The HTTP status code. */
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+declare const pathArg: {
+  readonly name: "path";
+  readonly type: "string";
+  readonly description: "Request path below the API base URL, e.g. /users";
+};
+declare const apiFlags: {
+  readonly list: {
+    readonly type: "boolean";
+    readonly noNegate: true;
+    readonly description: "List the API's operations";
+  };
+  readonly spec: {
+    readonly type: "string";
+    readonly description: "Print the OpenAPI definition of an operationId or path";
+  };
+  readonly method: {
+    readonly type: "string";
+    readonly short: "X";
+    readonly description: "HTTP method; default GET, or POST with fields or a body";
+  };
+  readonly header: {
+    readonly type: "string";
+    readonly short: "H";
+    readonly multiple: true;
+    readonly description: "Request header, 'Key: Value'";
+  };
+  readonly field: {
+    readonly type: "string";
+    readonly short: "F";
+    readonly multiple: true;
+    readonly description: "key=value; true, false, null, and numbers are sent as JSON";
+  };
+  readonly body: {
+    readonly type: "string";
+    readonly description: "Request body: inline, @file, or - for stdin";
+  };
+  readonly paginate: {
+    readonly type: "boolean";
+    readonly noNegate: true;
+    readonly description: "Fetch every page, printing each response body as one JSON line";
+  };
+};
+/** The contributed `api` command, spelled out because the exported factory needs a declared type. */
+type ApiCommandDefinition = CommandDefinition<"api", readonly [], CommandShape<readonly [typeof pathArg], typeof apiFlags, {}, JsonValue | undefined, {}, readonly JsonValue[] | undefined>, {
+  api: ApiClient;
+}>;
+/**
+ * Provides the {@link apiClient} Context and contributes `api`: `api --list` and
+ * `api --spec <operationId|path>` read the spec (calling its loader, if any); `api <path>` sends
+ * a request through the client, prints the response body to stdout (its exact bytes to a pipe or
+ * file; as text to a terminal, failing instead for a binary body), and fails with {@link ApiResponseError} on a non-2xx
+ * status. Under the `json()` Extension's `--json`, `api` returns its data as the command result instead: the operations, the
+ * definition, or the parsed response body; `--paginate` yields each page body as an event.
+ */
+export declare const apiCommand: ExtensionFactory<[options: ApiCommandOptions], {
+  api: ApiClient;
+}, readonly [ContextInstance<"api", ApiClient, {}, {}>], {}, readonly [ApiCommandDefinition], never, {}>;
+export type { ApiClient, ApiClientOptions, ApiCommandOptions, ApiRequest, OpenApiSpec };

package/dist/index.js

@@ -0,0 +1,588 @@
+import { CrustError, defineCommand, defineContext, defineExtension, defineExtensionId } from "@crustjs/core";
+import { jsonErrorDetails } from "@crustjs/utils/json";
+// src/client.ts
+/** `path` joined below `baseUrl`, keeping the base's own path; absolute URLs pass through. */
+function resolveUrl(baseUrl, path) {
+	return URL.canParse(path) ? new URL(path) : new URL(`${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`);
+}
+/**
+* `path` resolved like {@link ApiClient.fetch} does for a first request, which must stay on
+* `baseUrl`'s origin, so credentials set for the API never go to a host the caller named;
+* only redirects and next pages may leave it. Throws a `TypeError` for any other origin.
+*/
+function baseOriginUrl(baseUrl, path) {
+	const url = resolveUrl(baseUrl, path);
+	const { origin } = new URL(baseUrl);
+	if (url.origin !== origin) throw new TypeError(`Cannot request ${url.href}: only URLs on ${origin} are allowed`);
+	return url;
+}
+const REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+const MAX_REDIRECTS = 20;
+const BODY_HEADERS = [
+	"content-encoding",
+	"content-language",
+	"content-location",
+	"content-type"
+];
+/** `response` reporting `redirected`, as `fetch()` does after following a redirect, on its clones too. */
+function markRedirected(response) {
+	const clone = response.clone.bind(response);
+	return Object.defineProperties(response, {
+		redirected: { value: true },
+		clone: { value: () => markRedirected(clone()) }
+	});
+}
+const nextPageFetchers = /* @__PURE__ */ new WeakMap();
+/**
+* `client.fetch()` for a next page a response named: like a redirect target, it must be
+* http(s) and gets no credential headers off the base URL's origin, even ones the request set.
+*/
+function fetchNextPage(client, path, init) {
+	const fetchNext = nextPageFetchers.get(client);
+	if (fetchNext === void 0) throw new TypeError("fetchNextPage: not an apiClient Context value");
+	return fetchNext(path, init);
+}
+/**
+* The shared API client Context. {@link apiCommand} provides it, so app commands
+* declare `.use(apiClient)` and call `(await ctx.api).fetch("/users")`.
+*/
+const apiClient = /* @__PURE__ */ defineContext("api").setup(async (input, options) => {
+	const origin = new URL(options.baseUrl).origin;
+	const credentialHeaders = [
+		"authorization",
+		"cookie",
+		"proxy-authorization"
+	];
+	let authHeaders;
+	async function loadAuthHeaders() {
+		const headers = new Headers(await options.auth?.(input));
+		credentialHeaders.push(...headers.keys());
+		return headers;
+	}
+	const firstHop = (url, { auth, ...init } = {}) => ({
+		url,
+		init: {
+			...init,
+			headers: new Headers(init.headers),
+			signal: init.signal ?? input.signal
+		},
+		auth: auth !== false,
+		redirects: 0
+	});
+	/**
+	* The request for `target` after `from`, for a redirect with `status` or, without one,
+	* a next page. Every move to a URL a response named goes through here, so the protocol,
+	* redirect limit, and credential rules cannot be bypassed.
+	*/
+	function step(from, target, status) {
+		from.init.signal?.throwIfAborted();
+		if (target.protocol !== "http:" && target.protocol !== "https:") throw new TypeError(`Cannot request ${target.href}: only http: and https: URLs`);
+		const headers = new Headers(from.init.headers);
+		let { method = "GET", body } = from.init;
+		if (status !== void 0) {
+			if (from.redirects === MAX_REDIRECTS) throw new TypeError(`fetch ${from.url.href}: too many redirects`);
+			const upper = method.toUpperCase();
+			if (status === 303 ? upper !== "GET" && upper !== "HEAD" : status <= 302 && upper === "POST") {
+				method = "GET";
+				body = null;
+				for (const name of BODY_HEADERS) headers.delete(name);
+			}
+		}
+		if (target.origin !== origin) for (const name of credentialHeaders) headers.delete(name);
+		const redirects = from.redirects + (status === void 0 ? 0 : 1);
+		return {
+			...from,
+			url: target,
+			init: {
+				...from.init,
+				method,
+				body,
+				headers
+			},
+			redirects
+		};
+	}
+	async function send(hop) {
+		const redirect = hop.init.redirect ?? "follow";
+		for (;;) {
+			const headers = new Headers(hop.init.headers);
+			if (hop.auth && hop.url.origin === origin) {
+				for (const [name, value] of await (authHeaders ??= loadAuthHeaders())) if (!headers.has(name)) headers.set(name, value);
+			}
+			const response = await fetch(hop.url, {
+				...hop.init,
+				headers,
+				redirect: redirect === "follow" ? "manual" : redirect
+			});
+			const location = response.headers.get("location");
+			if (redirect !== "follow" || !REDIRECT_STATUSES.has(response.status) || location === null) return hop.redirects > 0 ? markRedirected(response) : response;
+			await response.body?.cancel();
+			hop = step(hop, new URL(location, hop.url), response.status);
+		}
+	}
+	const client = {
+		baseUrl: options.baseUrl,
+		fetch: async (path, init) => send(firstHop(baseOriginUrl(options.baseUrl, path), init))
+	};
+	nextPageFetchers.set(client, (path, init) => {
+		const target = resolveUrl(options.baseUrl, path);
+		return send(step(firstHop(target, init), target));
+	});
+	return client;
+});
+// src/api-command.ts
+const API = /* @__PURE__ */ defineExtensionId("crust:openapi");
+/**
+* A non-2xx response to `api <path>`; its body was already printed (to stderr under `--json`).
+* The `json()` Extension prints its `status` as the error's `details`.
+*/
+var ApiResponseError = class extends Error {
+	name = "ApiResponseError";
+	/** The HTTP status code. */
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		Object.defineProperty(this, jsonErrorDetails, { value: { status } });
+	}
+};
+const METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+/**
+* The value a local `$ref`'s JSON Pointer fragment (`#/...`, URI-encoded or not) points to
+* in `spec`, or `undefined`, also for other fragments such as `#anchor`.
+*/
+function refTarget(spec, ref) {
+	let pointer;
+	try {
+		pointer = decodeURIComponent(ref.slice(1));
+	} catch {
+		return;
+	}
+	if (pointer !== "" && !pointer.startsWith("/")) return void 0;
+	let target = spec;
+	for (const token of pointer.split("/").slice(1)) {
+		const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
+		target = typeof target === "object" && target !== null && Object.hasOwn(target, key) ? target[key] : void 0;
+	}
+	return target;
+}
+/** A Path Item with its own local `$ref`s (e.g. to `components.pathItems`) followed; sibling keys win. */
+function pathItem(spec, item) {
+	let current = item;
+	const seen = /* @__PURE__ */ new Set();
+	for (let ref = current.$ref; typeof ref === "string" && ref.startsWith("#") && !seen.has(ref); ref = current.$ref) {
+		seen.add(ref);
+		const target = refTarget(spec, ref);
+		if (typeof target !== "object" || target === null || Array.isArray(target)) break;
+		const { $ref: _ref, ...siblings } = current;
+		current = {
+			...target,
+			...siblings
+		};
+	}
+	return current;
+}
+function operations(spec) {
+	return Object.entries(spec.paths ?? {}).flatMap(([path, item]) => {
+		if (!path.startsWith("/") || typeof item !== "object" || item === null) return [];
+		const resolved = pathItem(spec, item);
+		return METHODS.flatMap((method) => {
+			const operation = resolved[method];
+			return typeof operation === "object" && operation !== null ? [{
+				method,
+				path,
+				operation,
+				shared: resolved.parameters
+			}] : [];
+		});
+	});
+}
+/** `spec`, or what its loader returns; a failure other than cancellation becomes a plain `Error`. */
+async function loadSpec(spec, signal) {
+	if (typeof spec !== "function") return spec;
+	let loaded;
+	try {
+		loaded = await spec({ signal });
+	} catch (cause) {
+		if (signal.aborted && cause === signal.reason || cause instanceof Error && cause.name === "AbortError") throw cause;
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		throw new Error(`api: cannot load the OpenAPI document (${reason})`, { cause });
+	}
+	const tag = Object.prototype.toString.call(loaded).slice(8, -1);
+	const prototype = tag === "Object" ? Object.getPrototypeOf(loaded) : void 0;
+	if (tag !== "Object" || prototype !== Object.prototype && prototype !== null) {
+		const kind = tag === "Object" ? "class instance" : tag.toLowerCase();
+		throw new Error(`api: cannot load the OpenAPI document (expected a plain object, got ${kind})`);
+	}
+	return loaded;
+}
+/** Each operation's method, path, and the `operationId` and `summary` the spec has. */
+function listOperations(spec) {
+	return operations(spec).map(({ method, path, operation }) => {
+		const { operationId, summary } = operation;
+		return {
+			method: method.toUpperCase(),
+			path,
+			...typeof operationId === "string" && operationId !== "" ? { operationId } : {},
+			...typeof summary === "string" && summary !== "" ? { summary } : {}
+		};
+	});
+}
+function isLocalRef(ref) {
+	return typeof ref === "string" && ref.startsWith("#");
+}
+/** `value` with its local `$ref` chain followed, stopping at a cycle or a dangling `$ref`. */
+function deref(spec, value) {
+	const seen = /* @__PURE__ */ new Set();
+	for (;;) {
+		const ref = typeof value === "object" && value !== null ? value.$ref : void 0;
+		if (!isLocalRef(ref) || seen.has(ref)) return value;
+		seen.add(ref);
+		const target = refTarget(spec, ref);
+		if (target === void 0) return value;
+		value = target;
+	}
+}
+/** The path item's `parameters`, minus those the operation redefines (same `name` and `in`), then the operation's. */
+function mergeParameters(spec, shared, own) {
+	const list = (parameters) => Array.isArray(parameters) ? parameters : [];
+	const key = (parameter) => {
+		const { name, in: location } = deref(spec, parameter) ?? {};
+		return typeof name === "string" && typeof location === "string" ? JSON.stringify([location, name]) : void 0;
+	};
+	const redefined = new Set(list(own).map(key));
+	return [...list(shared).filter((parameter) => {
+		const id = key(parameter);
+		return id === void 0 || !redefined.has(id);
+	}), ...list(own)];
+}
+/**
+* `value` with local `$ref`s (`#/...`) followed, each target written once: a target used once is
+* inlined, keeping sibling keys; one used more often, or recursively, keeps its `$ref`s and is
+* written once under `$refs`, keyed by the `$ref` text. Inlining every use instead grows
+* exponentially with shared schemas, as in large public specs.
+*/
+function resolveRefs(value, spec) {
+	const targets = /* @__PURE__ */ new Map();
+	const target = (ref) => {
+		if (!targets.has(ref)) targets.set(ref, refTarget(spec, ref));
+		return targets.get(ref);
+	};
+	const uses = /* @__PURE__ */ new Map();
+	const count = (node) => {
+		if (typeof node !== "object" || node === null) return;
+		for (const item of Object.values(node)) count(item);
+		const { $ref } = node;
+		if (!isLocalRef($ref) || target($ref) === void 0) return;
+		const seen = uses.get($ref) ?? 0;
+		uses.set($ref, seen + 1);
+		if (seen === 0) count(target($ref));
+	};
+	count(value);
+	const refs = {};
+	const write = (node) => {
+		if (Array.isArray(node)) return node.map(write);
+		if (typeof node !== "object" || node === null) return node;
+		const { $ref, ...siblings } = node;
+		const used = isLocalRef($ref) ? uses.get($ref) ?? 0 : 0;
+		if (used === 1) {
+			const resolved = write(target($ref));
+			return typeof resolved === "object" && resolved !== null && !Array.isArray(resolved) ? {
+				...resolved,
+				...write(siblings)
+			} : resolved;
+		}
+		if (used > 1 && !Object.hasOwn(refs, $ref)) {
+			refs[$ref] = void 0;
+			refs[$ref] = write(target($ref));
+		}
+		return Object.fromEntries(Object.entries(node).map(([key, item]) => [key, key === "$ref" ? item : write(item)]));
+	};
+	const written = write(value);
+	return Object.keys(refs).length > 0 ? {
+		...written,
+		$refs: refs
+	} : written;
+}
+/**
+* The path item for a spec path, or the operation with that `operationId` with its method, path,
+* and the path item's shared `parameters`; local `$ref`s resolved by {@link resolveRefs}.
+*/
+function specFor(spec, target) {
+	const paths = spec.paths ?? {};
+	if (target.startsWith("/") && Object.hasOwn(paths, target)) return resolveRefs(paths[target], spec);
+	const matches = operations(spec).filter(({ operation }) => operation.operationId === target);
+	const [match] = matches;
+	if (match === void 0) throw new Error(`No operation or path "${target}" in the OpenAPI spec`);
+	if (matches.length > 1) {
+		const candidates = matches.map(({ method, path }) => `${method.toUpperCase()} ${path}`);
+		throw new Error(`The operationId "${target}" is ambiguous in the OpenAPI spec (${candidates.join(", ")}): pass a path instead`);
+	}
+	const { method, path, operation, shared } = match;
+	const parameters = mergeParameters(spec, shared, operation.parameters);
+	return resolveRefs({
+		method: method.toUpperCase(),
+		path,
+		...operation,
+		...parameters.length > 0 ? { parameters } : {}
+	}, spec);
+}
+const JSON_NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+/** `key=value`; `true`, `false`, `null`, and JSON numbers become JSON values, like `gh api -F`. */
+function parseField(field) {
+	const at = field.indexOf("=");
+	if (at <= 0) throw new CrustError("PARSE", "Invalid -F value: expected key=value.", { flag: "field" });
+	const value = field.slice(at + 1);
+	const literals = {
+		true: true,
+		false: false,
+		null: null
+	};
+	if (Object.hasOwn(literals, value)) return [field.slice(0, at), literals[value]];
+	if (!JSON_NUMBER.test(value)) return [field.slice(0, at), value];
+	const number = Number(value);
+	if (!Number.isFinite(number)) throw new CrustError("PARSE", `Invalid -F value for "${field.slice(0, at)}": the number is out of range.`, { flag: "field" });
+	return [field.slice(0, at), number];
+}
+/** RFC 9110 `token`, the grammar of a method. */
+const METHOD_TOKEN = /^[!#$%&'*+.^_`|~\w-]+$/;
+/** The method to send for `-X`, upper-cased, failing before any request for one fetch() would not send. */
+function parseMethod(method) {
+	if (!METHOD_TOKEN.test(method)) throw new CrustError("PARSE", "Invalid -X value: expected an HTTP method such as GET or PATCH, without spaces.", { flag: "method" });
+	const normalized = method.toUpperCase();
+	let sent;
+	try {
+		sent = new Request("http://localhost/", { method: normalized }).method;
+	} catch {}
+	if (sent !== normalized) {
+		const problem = sent === void 0 ? "cannot send it" : `would send it as ${sent}`;
+		throw new CrustError("PARSE", `-X ${normalized}: this runtime's fetch() ${problem}.`, { flag: "method" });
+	}
+	return normalized;
+}
+function parseHeader(header) {
+	const at = header.indexOf(":");
+	if (at <= 0) throw new CrustError("PARSE", "Invalid -H value: expected \"Name: value\".", { flag: "header" });
+	const entry = [header.slice(0, at).trim(), header.slice(at + 1).trim()];
+	try {
+		new Headers().append(...entry);
+	} catch {
+		throw new CrustError("PARSE", "Invalid -H value: the header name or value has characters HTTP does not allow.", { flag: "header" });
+	}
+	return entry;
+}
+/** Inline text, `@path` (relative to the working directory), or `-` (all of stdin). */
+async function readBody(value, signal) {
+	if (value !== "-" && !value.startsWith("@")) return value;
+	try {
+		return value === "-" ? await (await import("@crustjs/utils/process")).readStdin(signal) : process.getBuiltinModule("node:fs").readFileSync(value.slice(1), "utf8");
+	} catch (cause) {
+		if (signal.aborted && cause === signal.reason) throw cause;
+		const name = value === "-" ? "stdin" : `"${value.slice(1)}"`;
+		const reason = cause instanceof Error ? ` (${cause.message})` : "";
+		throw new CrustError("PARSE", `--body: cannot read ${name}${reason}`, { flag: "body" }).withCause(cause);
+	}
+}
+const pathArg = {
+	name: "path",
+	type: "string",
+	description: "Request path below the API base URL, e.g. /users"
+};
+const apiFlags = {
+	list: {
+		type: "boolean",
+		noNegate: true,
+		description: "List the API's operations"
+	},
+	spec: {
+		type: "string",
+		description: "Print the OpenAPI definition of an operationId or path"
+	},
+	method: {
+		type: "string",
+		short: "X",
+		description: "HTTP method; default GET, or POST with fields or a body"
+	},
+	header: {
+		type: "string",
+		short: "H",
+		multiple: true,
+		description: "Request header, 'Key: Value'"
+	},
+	field: {
+		type: "string",
+		short: "F",
+		multiple: true,
+		description: "key=value; true, false, null, and numbers are sent as JSON"
+	},
+	body: {
+		type: "string",
+		description: "Request body: inline, @file, or - for stdin"
+	},
+	paginate: {
+		type: "boolean",
+		noNegate: true,
+		description: "Fetch every page, printing each response body as one JSON line"
+	}
+};
+/**
+* Provides the {@link apiClient} Context and contributes `api`: `api --list` and
+* `api --spec <operationId|path>` read the spec (calling its loader, if any); `api <path>` sends
+* a request through the client, prints the response body to stdout (its exact bytes to a pipe or
+* file; as text to a terminal, failing instead for a binary body), and fails with {@link ApiResponseError} on a non-2xx
+* status. Under the `json()` Extension's `--json`, `api` returns its data as the command result instead: the operations, the
+* definition, or the parsed response body; `--paginate` yields each page body as an event.
+*/
+const apiCommand = /* @__PURE__ */ defineExtension(API).factory((extension, { spec, paginate, ...client }) => extension.provide(apiClient(client)).add(defineCommand("api", { description: "Call the HTTP API, or browse its OpenAPI spec" }, (command) => command.use(apiClient).args(pathArg).flags(apiFlags).action(async ({ args, flags, ctx, signal, stdout, stderr }) => {
+	const json = flags.json === true;
+	if (flags.list) {
+		const listed = listOperations(await loadSpec(spec, signal));
+		if (json) return listed;
+		for (const entry of listed) stdout(Object.values(entry).join(" "));
+		return;
+	}
+	if (flags.spec !== void 0) {
+		const found = specFor(await loadSpec(spec, signal), flags.spec);
+		if (json) return found;
+		stdout(JSON.stringify(found));
+		return;
+	}
+	if (args.path === void 0) throw new CrustError("VALIDATION", "Missing required argument \"<path>\" (or pass --list or --spec)");
+	if (flags.paginate && paginate === void 0) throw new Error("--paginate: this CLI does not configure pagination");
+	let url;
+	try {
+		url = baseOriginUrl(client.baseUrl, args.path);
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		throw new CrustError("PARSE", message, { argument: "path" }).withCause(cause);
+	}
+	const fields = (flags.field ?? []).map(parseField);
+	const body = flags.body === void 0 ? void 0 : await readBody(flags.body, signal);
+	const method = parseMethod(flags.method ?? (fields.length > 0 || body !== void 0 ? "POST" : "GET"));
+	const headers = new Headers((flags.header ?? []).map(parseHeader));
+	let path = args.path;
+	let requestBody = body;
+	if (fields.length > 0) {
+		if (body !== void 0 || method === "GET" || method === "HEAD") {
+			const query = new URLSearchParams(fields.map(([key, value]) => [key, String(value)])).toString();
+			url.search = url.search === "" ? query : `${url.search.slice(1)}&${query}`;
+			path = url.href;
+		} else requestBody = JSON.stringify(Object.fromEntries(fields));
+	}
+	if (requestBody !== void 0 && !headers.has("content-type")) headers.set("content-type", "application/json");
+	const api = await ctx.api;
+	/** The response and body of each page: just one without --paginate. Fails after a non-2xx page. */
+	async function* pages() {
+		let request = {
+			path,
+			init: {
+				method,
+				headers,
+				body: requestBody
+			}
+		};
+		let shown = args.path;
+		let sentMethod = method;
+		let response = await api.fetch(request.path, request.init);
+		for (let pageNumber = 2;; pageNumber++) {
+			const page = flags.paginate ? response.clone() : void 0;
+			yield {
+				response,
+				bytes: new Uint8Array(await response.arrayBuffer())
+			};
+			if (!response.ok) throw new ApiResponseError(response.status, `${sentMethod} ${withoutQuery(shown)}: HTTP ${response.status} ${response.statusText}`.trimEnd());
+			const next = page && paginate ? await paginate(page) : void 0;
+			if (next === void 0) return;
+			const nextInit = next.init ?? request.init;
+			const nextUrl = resolveUrl(client.baseUrl, next.path).href;
+			const nextMethod = nextInit?.method ?? "GET";
+			if (nextInit === request.init && nextMethod === sentMethod && nextUrl === resolveUrl(client.baseUrl, request.path).href) throw new Error(`--paginate: page ${pageNumber} repeats the previous request (${nextMethod} ${withoutQuery(nextUrl)})`);
+			request = {
+				path: next.path,
+				init: nextInit
+			};
+			shown = next.path;
+			sentMethod = nextMethod;
+			response = await fetchNextPage(api, request.path, request.init);
+		}
+	}
+	/** Prints each page's body; under --json, yields a successful page's body as JSON data instead. */
+	async function* bodies() {
+		const { getAmbientTerminalIO, writeProcessOutput } = await import("@crustjs/utils/terminal");
+		let refusal;
+		if (flags.paginate) refusal = "--paginate prints only text and JSON bodies";
+		else if (json) refusal = "--json prints only text and JSON bodies, so run without it to write the bytes to stdout";
+		else if (getAmbientTerminalIO() !== void 0) refusal = "its bytes go only to the process's stdout, not to captured output";
+		else if (process.getBuiltinModule("node:tty").isatty(1)) refusal = "redirect or pipe stdout to save it instead of printing it to the terminal";
+		for await (const { response, bytes } of pages()) {
+			if (refusal === void 0) {
+				writeProcessOutput(1, bytes);
+				continue;
+			}
+			const text = bodyText(bytes);
+			if (text === void 0) {
+				if (response.ok) {
+					const type = response.headers.get("content-type") ?? "no Content-Type";
+					throw new Error(`api: ${flags.paginate ? "a --paginate page" : "the response"} body is binary (${type}); ${refusal}`);
+				}
+				continue;
+			}
+			if (!json) {
+				if (flags.paginate) stdout(compactJson(text));
+				else if (text !== "") stdout(text.replace(/\r?\n$/, ""));
+			} else if (!response.ok) {
+				if (text !== "") stderr(text.replace(/\r?\n$/, ""));
+			} else if (flags.paginate || text !== "") yield bodyValue(text);
+		}
+		return void 0;
+	}
+	if (flags.paginate && json) return bodies();
+	let result;
+	for await (const value of bodies()) result = value;
+	return result;
+}))));
+/** `path` up to its query or fragment, which may hold a credential such as an `-F` field. */
+function withoutQuery(path) {
+	return path.replace(/[?#][\s\S]*$/, "");
+}
+/** The body as text, or `undefined` when it is not valid UTF-8. */
+function bodyText(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+/** A body as JSON data: parsed when it is JSON (numbers as doubles), the text itself otherwise. */
+function bodyValue(text) {
+	try {
+		return JSON.parse(text, (_key, value) => Object.is(value, -0) ? 0 : value);
+	} catch {
+		return text;
+	}
+}
+/** A page body as one NDJSON line: JSON compacted, any other text (even empty) as a JSON string. */
+function compactJson(text) {
+	try {
+		JSON.parse(text);
+	} catch {
+		return JSON.stringify(text);
+	}
+	return text.replace(/"(?:[^"\\]|\\.)*"|\s+/g, (token) => token[0] === "\"" ? token : "");
+}
+export { ApiResponseError, apiClient, apiCommand };

package/package.json

@@ -1,17 +1,67 @@
 {
-	"name": "@crustjs/openapi",
-	"version": "0.0.0",
-	"description": "Placeholder for the first release of @crustjs/openapi. Do not install this version.",
-	"license": "MIT",
-	"author": "chenxin-yan",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/chenxin-yan/crust.git",
-		"directory": "packages/openapi"
-	},
-	"homepage": "https://crustjs.com",
-	"files": [],
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "@crustjs/openapi",
+  "version": "0.1.1",
+  "description": "Call a CLI's HTTP API and browse its OpenAPI spec from an api command",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "chenxin-yan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenxin-yan/crust.git",
+    "directory": "packages/openapi"
+  },
+  "homepage": "https://crustjs.com",
+  "bugs": {
+    "url": "https://github.com/chenxin-yan/crust/issues"
+  },
+  "keywords": [
+    "cli",
+    "crust",
+    "openapi",
+    "api",
+    "http",
+    "bun"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crustjs/utils": "^0.3.1"
+  },
+  "devDependencies": {
+    "@crustjs/config": "0.0.0",
+    "@crustjs/core": "0.6.1",
+    "@crustjs/extensions": "0.6.1",
+    "@crustjs/testing": "0.1.8",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependencies": {
+    "@crustjs/core": "^0.6.1",
+    "typescript": ">=5.9.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "vp run build:task",
+    "dev": "vp pack --watch",
+    "check:types": "vp run check:types:task",
+    "test": "vp run test:task"
+  }
+}