@hardfin/cli 0.0.1 → 0.0.2-dev.10

package/dist/cli.js

@@ -0,0 +1,2976 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+//#region src/command/registry.ts
+/** ExitCode is what the process returns, and what an agent branches on. */
+const ExitCode = {
+	OK: 0,
+	ERROR: 1,
+	USAGE: 2,
+	NOT_AUTHENTICATED: 4
+};
+/** defineCommand records one command so every surface reads the same declaration. */
+function defineCommand(command) {
+	return command;
+}
+//#endregion
+//#region src/config/settings.ts
+/** The API version this build was written against, sent on every request. */
+const API_VERSION = "2026-09-17";
+/** The file a local build reads its overrides from, in the working directory. */
+const CONFIG_FILE = "config.local.json";
+const DEFAULT_API_URL = "https://api.hardfin.com/v2";
+/**
+* The client Hardfin seeded for this CLI. The key is generated from a fixed identifier, so
+* it names the same first-party client in every environment.
+*/
+const DEFAULT_CLIENT_ID = "oacl_10e2etq297nhjfhb";
+const DEFAULT_ENV_FILE = ".env";
+const FileSettings = z.strictObject({
+	apiUrl: z.string().optional(),
+	apiKey: z.string().optional(),
+	clientId: z.string().optional(),
+	issuerUrl: z.string().optional()
+});
+/** ConfigFailure is a config file that cannot be read or does not match the schema. */
+var ConfigFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigFailure";
+	}
+};
+/** toSettings resolves what this invocation talks to, and where each value came from. */
+function toSettings(flags = {}, directory = process.cwd()) {
+	const fromEnvFile = loadEnvFile(directory);
+	const file = toFileSettings(directory);
+	const sources = {};
+	const pick = (key, flag, variable, fromFile, fallback) => {
+		const [value, source] = toLayer(flag, process.env[variable], fromEnvFile.has(variable), fromFile, fallback);
+		sources[key] = source;
+		return value;
+	};
+	const apiUrl = toTrimmedUrl(pick("apiUrl", flags.apiUrl, "HARDFIN_API_URL", file.apiUrl, DEFAULT_API_URL) ?? DEFAULT_API_URL);
+	return {
+		settings: {
+			apiUrl,
+			apiKey: pick("apiKey", flags.apiKey, "HARDFIN_API_KEY", file.apiKey),
+			clientId: pick("clientId", flags.clientId, "HARDFIN_CLIENT_ID", file.clientId, DEFAULT_CLIENT_ID) ?? DEFAULT_CLIENT_ID,
+			issuerUrl: pick("issuerUrl", flags.issuerUrl, "HARDFIN_ISSUER_URL", file.issuerUrl, toOrigin(apiUrl)) ?? ""
+		},
+		sources
+	};
+}
+function toLayer(flag, environment, isFromEnvFile, file, fallback) {
+	if (flag) return [flag, "flag"];
+	if (environment) return [environment, isFromEnvFile ? "env file" : "environment"];
+	if (file) return [file, "config file"];
+	return [fallback, "default"];
+}
+/** toFileSettings reads the local override file, which a local build is expected to have. */
+function toFileSettings(directory) {
+	const path = resolve(directory, CONFIG_FILE);
+	if (!existsSync(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new ConfigFailure(`${CONFIG_FILE} does not hold JSON`);
+	}
+	const result = FileSettings.safeParse(parsed);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		throw new ConfigFailure(`${CONFIG_FILE} is not valid: ${issue?.path.join(".") || "root"} ${issue?.message ?? ""}`.trim());
+	}
+	return result.data;
+}
+/**
+* loadEnvFile reads a .env beside the command, so a local build needs no exports, and
+* answers which variables it supplied. Node leaves an exported variable alone, so a
+* shell export still wins over the file.
+*/
+function loadEnvFile(directory) {
+	const path = process.env["HARDFIN_ENV_FILE"] ?? resolve(directory, DEFAULT_ENV_FILE);
+	if (!existsSync(path)) return /* @__PURE__ */ new Set();
+	const before = new Set(Object.keys(process.env));
+	try {
+		process.loadEnvFile(path);
+	} catch {
+		throw new ConfigFailure(`${path} cannot be read as an env file`);
+	}
+	return new Set(Object.keys(process.env).filter((name) => !before.has(name)));
+}
+function toTrimmedUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+/** toOrigin drops the API's path, because the authorization server sits at the host root. */
+function toOrigin(apiUrl) {
+	try {
+		return new URL(apiUrl).origin;
+	} catch {
+		return apiUrl;
+	}
+}
+//#endregion
+//#region src/output/writer.ts
+/** writeData prints a command's result on stdout. */
+function writeData(value) {
+	if (typeof value === "string") {
+		process.stdout.write(value.endsWith("\n") ? value : `${value}\n`);
+		return;
+	}
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** writeFailure prints why a command failed on stderr, as text or as JSON. */
+function writeFailure(message, isJSON, errors, requestId) {
+	if (!isJSON) {
+		process.stderr.write(`error: ${message}\n`);
+		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${entry.error} (${entry.statusCode})\n`);
+		if (requestId) process.stderr.write(`  request ${requestId}\n`);
+		return;
+	}
+	const payload = {
+		errors: errors ?? [{
+			error: message,
+			statusCode: 0
+		}],
+		requestId: requestId ?? null
+	};
+	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+/** isJSONOutput decides whether this invocation prints machine-readable output. */
+function isJSONOutput(flags) {
+	if (flags["json"] === true) return true;
+	return !process.stdout.isTTY;
+}
+/** version is what this build reports, read from the published package manifest. */
+const version$1 = createRequire(import.meta.url)("../package.json").version;
+//#endregion
+//#region src/command/agent-guide.ts
+const agentGuideCommand = defineCommand({
+	name: "agent-guide",
+	summary: "Print instructions an agent can follow to use this CLI",
+	description: "Writes Markdown describing every command, its flags, and its exit codes. Save it as a skill file, an AGENTS.md section, or paste it into a system prompt.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print the command registry as JSON instead of Markdown",
+		schema: z.boolean().optional()
+	}],
+	examples: [{
+		description: "Write a skill file",
+		command: "hardfin agent-guide > SKILL.md"
+	}, {
+		description: "Inspect the registry",
+		command: "hardfin agent-guide --json"
+	}],
+	run: runAgentGuide
+});
+/** toGuide renders the registry as the Markdown an agent reads. */
+function toGuide(commands, version) {
+	const lines = [
+		"# Hardfin CLI",
+		"",
+		`The \`hardfin\` command calls the Hardfin API. This guide describes version ${version} of the CLI, which speaks API version ${API_VERSION}.`,
+		"",
+		"## Before calling",
+		"",
+		"- Authenticate by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
+		"- Every command prints JSON on stdout and diagnostics on stderr",
+		"- Output is JSON whenever stdout is not a terminal, so no flag is needed when calling from code",
+		"",
+		"## Exit codes",
+		"",
+		"| Code | Means |",
+		"| --- | --- |",
+		"| 0 | The command succeeded |",
+		"| 1 | The command failed |",
+		"| 2 | The command was called wrongly |",
+		"| 4 | No usable credential |",
+		"",
+		"## Commands",
+		""
+	];
+	for (const command of commands) {
+		lines.push(`### \`hardfin ${command.name}\``, "", command.description ?? command.summary, "");
+		if (command.arguments.length > 0) {
+			lines.push("| Argument | Required | Holds |", "| --- | --- | --- |");
+			for (const argument of command.arguments) lines.push(`| \`${argument.name}\` | ${argument.required ? "yes" : "no"} | ${argument.description} |`);
+			lines.push("");
+		}
+		if (command.flags.length > 0) {
+			lines.push("| Flag | Takes | Does |", "| --- | --- | --- |");
+			for (const flag of command.flags) {
+				const name = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
+				lines.push(`| \`${name}\` | ${flag.valueName ?? "nothing"} | ${flag.description} |`);
+			}
+			lines.push("");
+		}
+		for (const example of command.examples) lines.push(`${example.description}:`, "", "```sh", example.command, "```", "");
+	}
+	return lines.join("\n");
+}
+async function runAgentGuide(input) {
+	if (input.flags["json"] === true) {
+		writeData(input.commands.map(toSummary));
+		return ExitCode.OK;
+	}
+	writeData(toGuide(input.commands, version$1));
+	return ExitCode.OK;
+}
+function toSummary(command) {
+	return {
+		name: command.name,
+		summary: command.summary,
+		description: command.description ?? command.summary,
+		arguments: command.arguments,
+		flags: command.flags.map((flag) => ({
+			name: flag.name,
+			short: flag.short ?? null,
+			description: flag.description,
+			valueName: flag.valueName ?? null,
+			repeatable: flag.repeatable ?? false
+		})),
+		examples: command.examples
+	};
+}
+//#endregion
+//#region src/auth/metadata.ts
+const METADATA_PATH = "/.well-known/oauth-authorization-server";
+const AuthorizationServerMetadata = z.looseObject({
+	issuer: z.string(),
+	authorization_endpoint: z.string(),
+	token_endpoint: z.string(),
+	revocation_endpoint: z.string().optional(),
+	device_authorization_endpoint: z.string().optional(),
+	scopes_supported: z.array(z.string()).optional(),
+	grant_types_supported: z.array(z.string()).optional(),
+	code_challenge_methods_supported: z.array(z.string()).optional()
+});
+/** DiscoveryFailure is an authorization server that cannot be read or does not describe itself. */
+var DiscoveryFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiscoveryFailure";
+	}
+};
+/** toMetadata reads what an authorization server says about itself. */
+async function toMetadata(issuer) {
+	const url = `${issuer.replace(/\/+$/, "")}${METADATA_PATH}`;
+	let response;
+	try {
+		response = await fetch(url, { headers: { Accept: "application/json" } });
+	} catch (error) {
+		throw new DiscoveryFailure(`${url} could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) throw new DiscoveryFailure(`${url} answered ${response.status}, so this host publishes no authorization server`);
+	const parsed = AuthorizationServerMetadata.safeParse(await response.json().catch(() => void 0));
+	if (!parsed.success) throw new DiscoveryFailure(`${url} does not describe an authorization server`);
+	if (parsed.data.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new DiscoveryFailure(`${url} names issuer ${parsed.data.issuer}, which is not the host it was read from`);
+	return parsed.data;
+}
+//#endregion
+//#region src/auth/grant.ts
+const TokenResponse = z.looseObject({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional()
+});
+/** GrantFailure is a token request the authorization server refused. */
+var GrantFailure = class extends Error {
+	code;
+	constructor(code, description) {
+		super(description ? `${code}: ${description}` : code);
+		this.name = "GrantFailure";
+		this.code = code;
+	}
+};
+/** toTokensFromCode trades an authorization code for tokens. */
+async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
+	return await toTokens(tokenUrl, {
+		grant_type: "authorization_code",
+		client_id: clientId,
+		code,
+		redirect_uri: redirectUri,
+		code_verifier: pkce.verifier
+	});
+}
+/** toTokensFromRefresh trades a refresh token for a fresh pair. */
+async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
+	return await toTokens(tokenUrl, {
+		grant_type: "refresh_token",
+		client_id: clientId,
+		refresh_token: refreshToken
+	});
+}
+/** revoke tells the server to forget a token, so signing out reaches every machine. */
+async function revoke(revocationUrl, clientId, token) {
+	await fetch(revocationUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: clientId,
+			token,
+			token_type_hint: "refresh_token"
+		})
+	});
+}
+/** toTokens asks the token endpoint, which answers a flat RFC 6749 body, not the envelope. */
+async function toTokens(url, form) {
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams(form)
+	});
+	const body = await response.json().catch(() => void 0);
+	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	const parsed = TokenResponse.safeParse(body);
+	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
+	return {
+		accessToken: parsed.data.access_token,
+		refreshToken: parsed.data.refresh_token,
+		scope: parsed.data.scope,
+		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
+	};
+}
+//#endregion
+//#region src/credential/store.ts
+const load = createRequire(import.meta.url);
+/** The service a keyring entry is filed under, alongside the issuer it belongs to. */
+const SERVICE = "hardfin-cli";
+const FILE_MODE = 384;
+const DIRECTORY_MODE$1 = 448;
+/** toCredentialPath names the file the fallback keeps refresh tokens in. */
+function toCredentialPath() {
+	const base = process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state");
+	return join(base, "hardfin", "credentials.json");
+}
+/**
+* keep writes a refresh token for one issuer. Only the refresh token is stored, so a stolen
+* entry is revocable, and access tokens live in the process that fetched them.
+*
+* A rotation keeps the date of the original sign in, because that is what the server's
+* family lifetime runs from. Callers hold the credential lock, which is what makes a write
+* from another process merge rather than disappear.
+*/
+function keep(issuer, refreshToken) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const record = {
+		refreshToken,
+		signedInAt: toCredential(issuer)?.signedInAt ?? now,
+		renewedAt: now
+	};
+	const keyring = toKeyring(issuer);
+	if (keyring) try {
+		keyring.setPassword(JSON.stringify(record));
+		return "keyring";
+	} catch {}
+	writeFile({
+		...readFile(),
+		[issuer]: record
+	});
+	return "file";
+}
+/** toCredential reads what is held for an issuer, and where it was held. */
+function toCredential(issuer) {
+	const keyring = toKeyring(issuer);
+	if (keyring) try {
+		const held = keyring.getPassword();
+		if (held) return {
+			...toRecord(held),
+			backend: "keyring"
+		};
+	} catch {}
+	const held = readFile()[issuer];
+	return held === void 0 ? void 0 : {
+		...held,
+		backend: "file",
+		path: toCredentialPath()
+	};
+}
+/** toRecord reads a stored entry, which older versions wrote as the bare token. */
+function toRecord(held) {
+	if (!held.startsWith("{")) return { refreshToken: held };
+	try {
+		return JSON.parse(held);
+	} catch {
+		return { refreshToken: held };
+	}
+}
+/** forget removes whatever is held for an issuer, in both places. */
+function forget(issuer) {
+	const keyring = toKeyring(issuer);
+	if (keyring) try {
+		keyring.deletePassword();
+	} catch {}
+	const held = readFile();
+	if (held[issuer] === void 0) return;
+	delete held[issuer];
+	if (Object.keys(held).length === 0) {
+		rmSync(toCredentialPath(), { force: true });
+		return;
+	}
+	writeFile(held);
+}
+/** toKeyring opens the OS keyring, or answers undefined where the platform has none. */
+function toKeyring(issuer) {
+	if (process.env["HARDFIN_CREDENTIAL_STORE"] === "file") return;
+	try {
+		const { Entry } = load("@napi-rs/keyring");
+		return new Entry(SERVICE, issuer);
+	} catch {
+		return;
+	}
+}
+function readFile() {
+	try {
+		const parsed = JSON.parse(readFileSync(toCredentialPath(), "utf8"));
+		if (typeof parsed !== "object" || parsed === null) return {};
+		return Object.fromEntries(Object.entries(parsed).map(([issuer, held]) => [issuer, typeof held === "string" ? { refreshToken: held } : held]));
+	} catch {
+		return {};
+	}
+}
+function writeFile(held) {
+	const path = toCredentialPath();
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: DIRECTORY_MODE$1
+	});
+	const pending = `${path}.${process.pid}.tmp`;
+	writeFileSync(pending, `${JSON.stringify(held, null, 2)}\n`, { mode: FILE_MODE });
+	chmodSync(pending, FILE_MODE);
+	renameSync(pending, path);
+}
+//#endregion
+//#region src/credential/lock.ts
+/** A lock held longer than this belongs to a process that died, so it is taken. */
+const STALE_MS = 3e4;
+const WAIT_MS$1 = 1e4;
+const RETRY_MS = 25;
+const DIRECTORY_MODE = 448;
+/** toLockPath names the lock every process coordinates credential writes through. */
+function toLockPath() {
+	return join(dirname(toCredentialPath()), "credentials.lock");
+}
+/** tryAcquire takes the lock, or reports that another process holds it. */
+function tryAcquire() {
+	const path = toLockPath();
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: DIRECTORY_MODE
+	});
+	try {
+		const handle = openSync(path, "wx");
+		writeSync(handle, String(process.pid));
+		closeSync(handle);
+		return true;
+	} catch {
+		return isStale(path) ? steal(path) : false;
+	}
+}
+/** release lets the next process in. */
+function release$1() {
+	rmSync(toLockPath(), { force: true });
+}
+/**
+* withLock runs one credential change at a time across every process. Rotation is why it
+* exists: the server kills a token family when a refresh token is presented twice, so two
+* commands refreshing at once would sign the person out.
+*/
+async function withLock(work) {
+	const deadline = Date.now() + WAIT_MS$1;
+	while (!tryAcquire()) {
+		if (Date.now() > deadline) throw new Error("another hardfin command is holding the credential lock");
+		await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+	}
+	try {
+		return await work();
+	} finally {
+		release$1();
+	}
+}
+function isStale(path) {
+	try {
+		return Date.now() - statSync(path).mtimeMs > STALE_MS;
+	} catch {
+		return true;
+	}
+}
+function steal(path) {
+	rmSync(path, { force: true });
+	return tryAcquire();
+}
+//#endregion
+//#region src/auth/session.ts
+/** A token this close to expiry is refreshed rather than used. */
+const EXPIRY_MARGIN_MS = 3e4;
+/** NoCredential is a caller with neither an API key nor a stored sign-in. */
+var NoCredential = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "NoCredential";
+	}
+};
+/** Access tokens are held for the life of the process, never written anywhere. */
+const held = /* @__PURE__ */ new Map();
+/**
+* toCredential answers what this invocation authenticates with. An API key wins, because an
+* unattended caller sets it deliberately, and otherwise the stored refresh token buys an
+* access token that lives only in memory.
+*/
+async function toRequestCredential(settings) {
+	if (settings.apiKey) return {
+		header: "X-API-Key",
+		value: settings.apiKey,
+		kind: "api key"
+	};
+	const stored = toCredential(settings.issuerUrl);
+	if (!stored) throw new NoCredential("not authenticated. Run hardfin login, or set HARDFIN_API_KEY");
+	return {
+		header: "Authorization",
+		value: `Bearer ${(await toAccessToken(settings, stored.refreshToken)).accessToken}`,
+		kind: "access token",
+		backend: stored.backend
+	};
+}
+/** toAccessToken reuses the token this process already holds until it is near expiry. */
+async function toAccessToken(settings, refreshToken) {
+	const current = held.get(settings.issuerUrl);
+	if (current && (current.expiresAt ?? 0) - EXPIRY_MARGIN_MS > Date.now()) return current;
+	const metadata = await toMetadata(settings.issuerUrl);
+	return await withLock(async () => {
+		const latest = toCredential(settings.issuerUrl)?.refreshToken ?? refreshToken;
+		try {
+			const tokens = await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest);
+			held.set(settings.issuerUrl, tokens);
+			if (tokens.refreshToken && tokens.refreshToken !== latest) keep(settings.issuerUrl, tokens.refreshToken);
+			return tokens;
+		} catch (error) {
+			if (error instanceof GrantFailure && isDead(error.code)) {
+				forget(settings.issuerUrl);
+				throw new NoCredential(`the sign in for ${settings.issuerUrl} is no longer valid, so it was removed. Run hardfin login`);
+			}
+			throw error;
+		}
+	});
+}
+/** Codes the authorization server uses when a refresh token can never work again. */
+const DEAD_GRANT_CODES = /* @__PURE__ */ new Set([
+	"invalid_grant",
+	"invalid_client",
+	"unauthorized_client"
+]);
+function isDead(code) {
+	return DEAD_GRANT_CODES.has(code);
+}
+/** forgetHeldTokens drops the access tokens this process is holding. */
+function forgetHeldTokens() {
+	held.clear();
+}
+//#endregion
+//#region src/http/client.ts
+/** RequestFailure is a call the API refused, carrying what the envelope said. */
+var RequestFailure = class extends Error {
+	status;
+	errors;
+	requestId;
+	constructor(status, errors, requestId) {
+		super(errors[0]?.error ?? `the request failed with status ${status}`);
+		this.name = "RequestFailure";
+		this.status = status;
+		this.errors = errors;
+		this.requestId = requestId;
+	}
+};
+/** request calls one /v2 endpoint and returns the envelope it answered with. */
+async function request(options) {
+	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
+	if (options.query) url.search = options.query.toString();
+	const headers = {
+		[options.credential.header]: options.credential.value,
+		"X-API-Version": API_VERSION,
+		Accept: "application/json"
+	};
+	if (options.body !== void 0) headers["Content-Type"] = "application/json";
+	const response = await fetch(url, {
+		method: options.method,
+		headers,
+		body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+	});
+	const envelope = toEnvelope(await response.text());
+	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
+		error: toStatusMessage(response.status),
+		statusCode: response.status
+	}]);
+	if (!response.ok) {
+		const errors = envelope?.metadata?.errors ?? [];
+		throw new RequestFailure(response.status, errors.length > 0 ? errors : [{
+			error: toStatusMessage(response.status),
+			statusCode: response.status
+		}], envelope?.metadata?.requestId);
+	}
+	return envelope ?? { data: null };
+}
+function toLeadingSlash(path) {
+	return path.startsWith("/") ? path : `/${path}`;
+}
+function toEnvelope(text) {
+	if (text.trim() === "") return;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function toStatusMessage(status) {
+	if (status === 401) return "the credential is missing or is not valid";
+	if (status === 403) return "the organization is deactivated, or its access has ended";
+	return `the request failed with status ${status}`;
+}
+const apiCommand = defineCommand({
+	name: "api",
+	summary: "Call a Hardfin API endpoint and print what it answers",
+	description: "Reaches every endpoint the API publishes. The path is everything after /v2, and the response envelope is printed as it arrived.",
+	arguments: [{
+		name: "path",
+		description: "The endpoint path, such as /customer or /item/item_V1StGXR8Z5jdHi6B",
+		required: true
+	}],
+	flags: [
+		{
+			name: "method",
+			short: "X",
+			description: "The HTTP method to use",
+			valueName: "method",
+			schema: z.enum([
+				"GET",
+				"POST",
+				"PATCH",
+				"PUT",
+				"DELETE"
+			]),
+			defaultValue: "GET"
+		},
+		{
+			name: "field",
+			short: "f",
+			description: "A query parameter as key=value, repeatable",
+			valueName: "key=value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "input",
+			description: "A file holding the JSON request body, or - for stdin",
+			valueName: "file",
+			schema: z.string().optional()
+		},
+		{
+			name: "json",
+			description: "Print machine-readable output, which is the default when stdout is not a terminal",
+			schema: z.boolean().optional()
+		}
+	],
+	examples: [
+		{
+			description: "List customers",
+			command: "hardfin api /customer"
+		},
+		{
+			description: "Take the second page",
+			command: "hardfin api /customer -f page=2 -f limit=50"
+		},
+		{
+			description: "Change an item",
+			command: "hardfin api -X PATCH /item/item_V1StGXR8Z5jdHi6B --input body.json"
+		}
+	],
+	run: runApi
+});
+async function runApi(input) {
+	const path = input.args[0];
+	if (!path) {
+		writeFailure("a path is required, such as /customer", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const query = toQuery$1(input.flags["field"]);
+	if (query === void 0) {
+		writeFailure("each --field is key=value, such as -f limit=50", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let body;
+	if (typeof input.flags["input"] === "string") {
+		body = toBody$1(input.flags["input"]);
+		if (body === void 0) {
+			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
+			return ExitCode.USAGE;
+		}
+	}
+	try {
+		writeData((await request({
+			apiUrl: input.resolved.settings.apiUrl,
+			credential: await toRequestCredential(input.resolved.settings),
+			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			path,
+			query,
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof NoCredential) {
+			writeFailure(error.message, input.isJSON);
+			return ExitCode.NOT_AUTHENTICATED;
+		}
+		if (error instanceof RequestFailure) {
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
+		return ExitCode.ERROR;
+	}
+}
+/** toQuery folds the repeated --field flags into query parameters. */
+function toQuery$1(fields) {
+	const query = new URLSearchParams();
+	for (const field of Array.isArray(fields) ? fields : []) {
+		const split = field.indexOf("=");
+		if (split < 1) return;
+		query.append(field.slice(0, split), field.slice(split + 1));
+	}
+	return query;
+}
+function toBody$1(source) {
+	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/command/config.ts
+const configCommand = defineCommand({
+	name: "config",
+	summary: "Print what this invocation talks to, and where each value came from",
+	description: `Resolves the API and authentication endpoints from the flags, the environment, a .env file, and ${CONFIG_FILE} in the working directory. Use it when a local build reaches the wrong server.`,
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "See what a local build is pointed at",
+		command: "hardfin config"
+	}, {
+		description: "Read one value from a script",
+		command: "hardfin config --json | jq -r .apiUrl"
+	}],
+	run: runConfig
+});
+/** toReport pairs each setting with the layer that supplied it. */
+function toReport(resolved) {
+	const report = { apiVersion: API_VERSION };
+	for (const [key, value] of Object.entries(resolved.settings)) {
+		const source = resolved.sources[key];
+		report[key] = key === "apiKey" ? {
+			set: value !== void 0,
+			from: source
+		} : {
+			value: value ?? null,
+			from: source
+		};
+	}
+	return report;
+}
+async function runConfig(input) {
+	const report = toReport(input.resolved);
+	if (input.isJSON) {
+		writeData(report);
+		return ExitCode.OK;
+	}
+	writeData(Object.entries(report).map(([key, entry]) => {
+		if (typeof entry !== "object" || entry === null) return `${key.padEnd(14)} ${String(entry)}`;
+		const holder = entry;
+		const shown = holder.value ?? (holder.set ? "set" : "not set");
+		return `${key.padEnd(14)} ${shown}  (${holder.from})`;
+	}).join("\n"));
+	return ExitCode.OK;
+}
+//#endregion
+//#region src/auth/browser.ts
+/** isWSL reports whether this Linux is running under Windows. */
+function isWSL() {
+	return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop");
+}
+/**
+* toOpeners lists the ways to open a URL here, best first. WSL needs Windows to do it,
+* because the browser the person is looking at is the Windows one, and xdg-open reaches
+* nothing outside the distribution.
+*/
+function toOpeners(url) {
+	if (process.platform === "darwin") return [["open", [url]]];
+	if (process.platform === "win32") return [["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]]];
+	if (isWSL()) return [
+		["wslview", [url]],
+		["powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"Start-Process",
+			`'${url}'`
+		]],
+		["explorer.exe", [url]]
+	];
+	return [["xdg-open", [url]]];
+}
+/** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
+function openBrowser(url) {
+	for (const [command, args] of toOpeners(url)) if (spawnSync(command, args, {
+		stdio: "ignore",
+		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
+		timeout: 1e4
+	}).error === void 0) return true;
+	return false;
+}
+//#endregion
+//#region src/auth/device.ts
+const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** The interval a server gives is in seconds, and five more are added on a slow_down. */
+const DEFAULT_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_SECONDS = 5;
+const DeviceResponse = z.looseObject({
+	device_code: z.string(),
+	user_code: z.string(),
+	verification_uri: z.string(),
+	verification_uri_complete: z.string().optional(),
+	expires_in: z.number(),
+	interval: z.number().optional()
+});
+/** toDeviceAuthorization asks for a code a person can type on another machine. */
+async function toDeviceAuthorization(endpoint, clientId, scope) {
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams({
+			client_id: clientId,
+			scope
+		})
+	});
+	const body = await response.json().catch(() => void 0);
+	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	const parsed = DeviceResponse.safeParse(body);
+	if (!parsed.success) throw new GrantFailure("invalid_response", "the device endpoint did not answer with a code");
+	return {
+		deviceCode: parsed.data.device_code,
+		userCode: parsed.data.user_code,
+		verificationUri: parsed.data.verification_uri,
+		verificationUriComplete: parsed.data.verification_uri_complete,
+		expiresAt: Date.now() + parsed.data.expires_in * 1e3,
+		intervalMs: (parsed.data.interval ?? DEFAULT_INTERVAL_SECONDS) * 1e3
+	};
+}
+/**
+* toTokensFromDevice waits for the person to approve on another machine. The server answers
+* authorization_pending until they do, and slow_down when this asked too often.
+*/
+async function toTokensFromDevice(tokenUrl, clientId, device, sleep = toSleep) {
+	let intervalMs = device.intervalMs;
+	for (;;) {
+		if (Date.now() > device.expiresAt) throw new GrantFailure("expired_token", "the code expired before it was approved");
+		await sleep(intervalMs);
+		try {
+			return await toTokens(tokenUrl, {
+				grant_type: DEVICE_GRANT,
+				client_id: clientId,
+				device_code: device.deviceCode
+			});
+		} catch (error) {
+			if (!(error instanceof GrantFailure)) throw error;
+			if (error.code === "slow_down") {
+				intervalMs += SLOW_DOWN_SECONDS * 1e3;
+				continue;
+			}
+			if (error.code !== "authorization_pending") throw error;
+		}
+	}
+}
+function toSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region src/auth/loopback.ts
+/** The path the browser is sent back to, which the client metadata document registers. */
+const CALLBACK_PATH = "/callback";
+const HOST = "127.0.0.1";
+/**
+* toListener opens a loopback server for one authorization response. The port is whatever
+* the machine hands out, which is why the server matches a loopback redirect by everything
+* except its port.
+*/
+async function toListener(timeoutMs) {
+	let settle = () => {};
+	let fail = () => {};
+	const callback = new Promise((resolve, reject) => {
+		settle = resolve;
+		fail = reject;
+	});
+	const server = createServer((request, response) => {
+		const answered = toCallback(request);
+		if (answered === void 0) {
+			response.writeHead(404).end();
+			return;
+		}
+		writePage(response, answered);
+		settle(answered);
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, HOST, resolve);
+	});
+	const timer = setTimeout(() => {
+		fail(/* @__PURE__ */ new Error("the browser did not come back in time"));
+		close(server, timer);
+	}, timeoutMs);
+	return {
+		redirectUri: `http://${HOST}:${server.address().port}${CALLBACK_PATH}`,
+		callback: callback.finally(() => close(server, timer)),
+		close: () => close(server, timer)
+	};
+}
+function toCallback(request) {
+	const url = new URL(request.url ?? "/", `http://${HOST}`);
+	if (url.pathname !== CALLBACK_PATH) return;
+	return {
+		source: "listener",
+		code: url.searchParams.get("code") ?? void 0,
+		state: url.searchParams.get("state") ?? void 0,
+		issuer: url.searchParams.get("iss") ?? void 0,
+		error: url.searchParams.get("error") ?? void 0,
+		errorDescription: url.searchParams.get("error_description") ?? void 0
+	};
+}
+function writePage(response, callback) {
+	const title = callback.error ? "Sign in refused" : "Signed in";
+	const detail = callback.error ? `${callback.error}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}` : "You can close this tab and return to your terminal.";
+	response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body style="font-family: system-ui, sans-serif; padding: 3rem; max-width: 34rem"><h1 style="font-size: 1.25rem">${title}</h1><p>${detail}</p></body></html>`);
+}
+function close(server, timer) {
+	clearTimeout(timer);
+	server.close();
+	server.closeAllConnections();
+}
+//#endregion
+//#region src/auth/pkce.ts
+/** toPkce makes a fresh verifier and the challenge derived from it. */
+function toPkce() {
+	const verifier = toUrlSafe(randomBytes(32));
+	return {
+		verifier,
+		challenge: toUrlSafe(createHash("sha256").update(verifier).digest()),
+		method: "S256"
+	};
+}
+/** toState makes the value that ties a callback to the request that started it. */
+function toState() {
+	return toUrlSafe(randomBytes(16));
+}
+function toUrlSafe(bytes) {
+	return bytes.toString("base64url");
+}
+//#endregion
+//#region src/auth/clipboard.ts
+/** toClipboardCommand names how this host takes text onto the clipboard. */
+function toClipboardCommand() {
+	if (process.platform === "darwin") return ["pbcopy", []];
+	if (process.platform === "win32") return ["clip", []];
+	if (existsSync("/proc/sys/fs/binfmt_misc/WSLInterop")) return ["clip.exe", []];
+	if (process.env["WAYLAND_DISPLAY"]) return ["wl-copy", []];
+	return ["xclip", ["-selection", "clipboard"]];
+}
+/** copyToClipboard puts text on the clipboard, and reports whether anything took it. */
+function copyToClipboard(text) {
+	const command = toClipboardCommand();
+	if (!command) return false;
+	const [name, args] = command;
+	const result = spawnSync(name, args, { input: text });
+	return result.error === void 0 && result.status === 0;
+}
+//#endregion
+//#region src/auth/prompt.ts
+const CTRL_C = "";
+const BACKSPACE = "";
+/**
+* toPastedCallback reads what a person pasted. A browser that could not reach the listener
+* leaves the whole redirect in the address bar, and a page that shows the code leaves
+* `code#state`, so both are accepted alongside a bare code.
+*/
+function toPastedCallback(pasted) {
+	const value = pasted.trim();
+	if (value.startsWith("http://") || value.startsWith("https://")) {
+		const url = new URL(value);
+		return {
+			source: "pasted",
+			code: url.searchParams.get("code") ?? void 0,
+			state: url.searchParams.get("state") ?? void 0,
+			issuer: url.searchParams.get("iss") ?? void 0,
+			error: url.searchParams.get("error") ?? void 0,
+			errorDescription: url.searchParams.get("error_description") ?? void 0
+		};
+	}
+	const [code, state] = value.split("#");
+	return {
+		source: "pasted",
+		code: code || void 0,
+		state: state || void 0
+	};
+}
+/**
+* toPrompt watches the keyboard while the browser is away. Pressing c copies the URL, and
+* pasting a code finishes the sign in on a machine whose browser cannot reach this listener.
+*/
+function toPrompt(url) {
+	let settle = () => {};
+	let fail = () => {};
+	const pasted = new Promise((resolve, reject) => {
+		settle = resolve;
+		fail = reject;
+	});
+	const input = process.stdin;
+	if (!input.isTTY) return {
+		pasted,
+		close: () => {}
+	};
+	let typed = "";
+	const onData = (chunk) => {
+		for (const character of chunk) {
+			if (character === CTRL_C) {
+				fail(/* @__PURE__ */ new Error("sign in was cancelled"));
+				return;
+			}
+			if (character === "\r" || character === "\n") {
+				if (typed.trim() === "") continue;
+				process.stderr.write("\n");
+				settle(toPastedCallback(typed));
+				return;
+			}
+			if (character === BACKSPACE) {
+				typed = typed.slice(0, -1);
+				process.stderr.write("\b \b");
+				continue;
+			}
+			if ((character === "c" || character === "C") && typed === "") {
+				process.stderr.write(copyToClipboard(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
+				continue;
+			}
+			typed += character;
+			process.stderr.write(character);
+		}
+	};
+	input.setRawMode(true);
+	input.setEncoding("utf8");
+	input.resume();
+	input.on("data", onData);
+	const close = () => {
+		input.off("data", onData);
+		input.setRawMode(false);
+		input.pause();
+	};
+	return {
+		pasted: pasted.finally(close),
+		close
+	};
+}
+//#endregion
+//#region src/command/login.ts
+/** The scopes a sign-in asks for, with offline access so a refresh token comes back. */
+const DEFAULT_SCOPES = "hardfin:read hardfin:write offline_access";
+const WAIT_MS = 3e5;
+const loginCommand = defineCommand({
+	name: "login",
+	summary: "Sign in to Hardfin through a browser",
+	description: "Opens the browser to approve this CLI, then keeps the refresh token in the OS keyring, or in a file with owner-only permissions where there is no keyring. Access tokens are never written anywhere.",
+	arguments: [],
+	flags: [
+		{
+			name: "scope",
+			description: "The scopes to ask for, separated by spaces",
+			valueName: "scopes",
+			schema: z.string(),
+			defaultValue: DEFAULT_SCOPES
+		},
+		{
+			name: "no-browser",
+			description: "Print the URL instead of opening it",
+			schema: z.boolean()
+		},
+		{
+			name: "device",
+			description: "Approve on another machine, by typing a code, with no listener on this one",
+			schema: z.boolean()
+		},
+		{
+			name: "json",
+			description: "Print machine-readable output, which is the default when stdout is not a terminal",
+			schema: z.boolean()
+		}
+	],
+	examples: [
+		{
+			description: "Sign in",
+			command: "hardfin login"
+		},
+		{
+			description: "Sign in over SSH, opening the URL yourself",
+			command: "hardfin login --no-browser"
+		},
+		{
+			description: "Approve from your phone or another machine",
+			command: "hardfin login --device"
+		}
+	],
+	run: runLogin
+});
+async function runLogin(input) {
+	const settings = input.resolved.settings;
+	try {
+		const clientId = settings.clientId;
+		const metadata = await toMetadata(settings.issuerUrl);
+		const scope = String(input.flags["scope"] ?? DEFAULT_SCOPES);
+		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
+		const listener = await toListener(WAIT_MS);
+		const pkce = toPkce();
+		const state = toState();
+		const url = toAuthorizationUrl(metadata.authorization_endpoint, {
+			clientId,
+			redirectUri: listener.redirectUri,
+			scope,
+			state,
+			challenge: pkce.challenge
+		});
+		const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
+		process.stderr.write(opened ? `Opening your browser to sign in. If it did not open:\n\n${url}\n\n` : `Open this URL to sign in:\n\n${url}\n\n`);
+		const prompt = toPrompt(url);
+		if (process.stdin.isTTY) process.stderr.write("Press c to copy the URL, or paste the code or redirect URL here: ");
+		const callback = await Promise.race([listener.callback, prompt.pasted]);
+		listener.close();
+		prompt.close();
+		process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
+		if (callback.error) {
+			writeFailure(`sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
+			return ExitCode.ERROR;
+		}
+		if (callback.source === "listener" ? callback.state !== state : callback.state !== void 0 && callback.state !== state) {
+			writeFailure("the browser came back with a state this sign in did not send", input.isJSON);
+			return ExitCode.ERROR;
+		}
+		if (callback.issuer !== void 0 && callback.issuer.replace(/\/+$/, "") !== metadata.issuer.replace(/\/+$/, "")) {
+			writeFailure(`the browser came back from ${callback.issuer}, which is not ${metadata.issuer}`, input.isJSON);
+			return ExitCode.ERROR;
+		}
+		if (!callback.code) {
+			writeFailure("the browser came back without an authorization code", input.isJSON);
+			return ExitCode.ERROR;
+		}
+		return await toSignedIn(input, metadata, await toTokensFromCode(metadata.token_endpoint, clientId, callback.code, listener.redirectUri, pkce));
+	} catch (error) {
+		if (error instanceof DiscoveryFailure || error instanceof GrantFailure) {
+			writeFailure(error.message, input.isJSON);
+			return ExitCode.ERROR;
+		}
+		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
+		return ExitCode.ERROR;
+	}
+}
+/** runDeviceLogin waits while the person approves on a machine that has a browser. */
+async function runDeviceLogin(input, metadata, scope) {
+	const settings = input.resolved.settings;
+	if (!metadata.device_authorization_endpoint) {
+		writeFailure(`${metadata.issuer} does not offer the device grant, so sign in without --device`, input.isJSON);
+		return ExitCode.ERROR;
+	}
+	const device = await toDeviceAuthorization(metadata.device_authorization_endpoint, settings.clientId, scope);
+	const url = device.verificationUriComplete ?? device.verificationUri;
+	const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
+	process.stderr.write([
+		"",
+		`  Code  ${device.userCode}`,
+		`  At    ${device.verificationUri}`,
+		"",
+		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
+	].join("\n"));
+	const prompt = toPrompt(url);
+	return await toSignedIn(input, metadata, await toTokensFromDevice(metadata.token_endpoint, settings.clientId, device).finally(() => prompt.close()));
+}
+/** toSignedIn stores what a sign in issued, whichever flow issued it. */
+async function toSignedIn(input, metadata, tokens) {
+	const refreshToken = tokens.refreshToken;
+	if (!refreshToken) {
+		writeFailure("the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
+		return ExitCode.ERROR;
+	}
+	const backend = await withLock(() => keep(input.resolved.settings.issuerUrl, refreshToken));
+	if (input.isJSON) {
+		writeData({
+			signedIn: true,
+			issuer: metadata.issuer,
+			scope: tokens.scope ?? null,
+			storedIn: backend
+		});
+		return ExitCode.OK;
+	}
+	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
+	writeData([
+		`Signed in to ${metadata.issuer}`,
+		`Scope     ${tokens.scope ?? "as granted"}`,
+		`Stored in ${stored}`,
+		"",
+		"Run hardfin status to see what this CLI is using"
+	].join("\n"));
+	return ExitCode.OK;
+}
+/** toAuthorizationUrl builds the URL the person approves this CLI at. */
+function toAuthorizationUrl(endpoint, request) {
+	const url = new URL(endpoint);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", request.clientId);
+	url.searchParams.set("redirect_uri", request.redirectUri);
+	url.searchParams.set("scope", request.scope);
+	url.searchParams.set("state", request.state);
+	url.searchParams.set("code_challenge", request.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	return url.toString();
+}
+//#endregion
+//#region src/command/logout.ts
+const logoutCommand = defineCommand({
+	name: "logout",
+	summary: "Sign out, and tell Hardfin to forget this machine",
+	description: "Removes the stored refresh token and asks the authorization server to revoke it, so a copy taken from this machine stops working.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Sign out",
+		command: "hardfin logout"
+	}],
+	run: runLogout
+});
+async function runLogout(input) {
+	const settings = input.resolved.settings;
+	const stored = toCredential(settings.issuerUrl);
+	if (!stored) {
+		writeData({
+			signedOut: false,
+			issuer: settings.issuerUrl,
+			reason: "no sign in was stored"
+		});
+		return ExitCode.OK;
+	}
+	let revoked = false;
+	try {
+		const metadata = await toMetadata(settings.issuerUrl);
+		if (metadata.revocation_endpoint) {
+			await revoke(metadata.revocation_endpoint, settings.clientId, stored.refreshToken);
+			revoked = true;
+		}
+	} catch {
+		revoked = false;
+	}
+	await withLock(() => forget(settings.issuerUrl));
+	forgetHeldTokens();
+	writeData({
+		signedOut: true,
+		issuer: settings.issuerUrl,
+		revoked
+	});
+	return ExitCode.OK;
+}
+//#endregion
+//#region src/command/operation.ts
+const INPUT_FLAG = {
+	name: "input",
+	description: "A file holding the JSON request body, or - for stdin",
+	valueName: "file",
+	schema: z.string()
+};
+const JSON_FLAG = {
+	name: "json",
+	description: "Print machine-readable output, which is the default when stdout is not a terminal",
+	schema: z.boolean()
+};
+/** defineOperation turns one endpoint into the command that calls it. */
+function defineOperation(operation) {
+	const flags = [...operation.queryFlags, JSON_FLAG];
+	if (operation.takesBody) flags.splice(flags.length - 1, 0, INPUT_FLAG);
+	return {
+		name: operation.name,
+		summary: operation.summary,
+		description: operation.description ?? operation.summary,
+		arguments: operation.pathParameters,
+		flags,
+		examples: [],
+		run: (input) => runOperation(operation, input)
+	};
+}
+async function runOperation(operation, input) {
+	const path = toPath(operation, input.args);
+	if (path === void 0) {
+		writeFailure(`this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let body;
+	if (typeof input.flags["input"] === "string") {
+		body = toBody(input.flags["input"]);
+		if (body === void 0) {
+			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
+			return ExitCode.USAGE;
+		}
+	}
+	try {
+		writeData((await request({
+			apiUrl: input.resolved.settings.apiUrl,
+			credential: await toRequestCredential(input.resolved.settings),
+			method: operation.method,
+			path,
+			query: toQuery(operation, input.flags),
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof NoCredential) {
+			writeFailure(error.message, input.isJSON);
+			return ExitCode.NOT_AUTHENTICATED;
+		}
+		if (error instanceof RequestFailure) {
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
+		return ExitCode.ERROR;
+	}
+}
+/** toPath fills the path template from the positional arguments, in order. */
+function toPath(operation, args) {
+	if (args.length !== operation.pathParameters.length) return;
+	let path = operation.path;
+	for (const [index, parameter] of operation.pathParameters.entries()) path = path.replace(`{${parameter.name}}`, encodeURIComponent(args[index] ?? ""));
+	return path;
+}
+/** toQuery carries only the flags this invocation actually set. */
+function toQuery(operation, flags) {
+	const query = new URLSearchParams();
+	for (const flag of operation.queryFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		for (const entry of Array.isArray(value) ? value : [value]) query.append(flag.queryName, String(entry));
+	}
+	return query;
+}
+/** toOptionKey names the parsed flag, which the parser reports in camel case. */
+function toOptionKey(name) {
+	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function toBody(source) {
+	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/command/surface.generated.ts
+const surfaceCommands = [
+	{
+		name: "asset",
+		summary: "Asset commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [
+			defineOperation({
+				name: "list",
+				summary: "Get asset listing",
+				method: "GET",
+				path: "/asset",
+				pathParameters: [],
+				queryFlags: [
+					{
+						name: "page",
+						queryName: "page",
+						description: "The page to return, starting at 1",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "limit",
+						queryName: "limit",
+						description: "The number of records per page, from 1 to 100",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "sort-by",
+						queryName: "sortBy",
+						description: "The field to sort by",
+						valueName: "value",
+						schema: z.enum([
+							"serial",
+							"project",
+							"item",
+							"location",
+							"owner",
+							"activity"
+						])
+					},
+					{
+						name: "sort-order",
+						queryName: "sortOrder",
+						description: "The sort direction",
+						valueName: "value",
+						schema: z.enum(["ASC", "DESC"])
+					},
+					{
+						name: "archived",
+						queryName: "archived",
+						description: "Whether to return unarchived records, archived records, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					},
+					{
+						name: "search-query",
+						queryName: "searchQuery",
+						description: "Text to match against the serial, description, item, project, owner, and location, ignored when shorter than three characters",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "for-asset-id",
+						queryName: "forAssetId",
+						description: "The IDs of the assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "for-asset-key",
+						queryName: "forAssetKey",
+						description: "The keys of the assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "for-customer",
+						queryName: "forCustomer",
+						description: "The IDs of the customers whose assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "for-item",
+						queryName: "forItem",
+						description: "The IDs of the items whose assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "at-site",
+						queryName: "atSite",
+						description: "The IDs of the locations whose assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "at-customer-sites",
+						queryName: "atCustomerSites",
+						description: "The IDs of the customers whose sites to list assets at",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "with-functional-statuses",
+						queryName: "withFunctionalStatuses",
+						description: "The functional statuses to list, where SCRAPPED lists scrapped assets",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.enum([
+							"FUNCTIONAL",
+							"NEEDS_REVIEW",
+							"NON-FUNCTIONAL",
+							"SCRAPPED"
+						]))
+					},
+					{
+						name: "with-transit-statuses",
+						queryName: "withTransitStatuses",
+						description: "The transit statuses to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.enum([
+							"IN_TRANSIT",
+							"IN_TRANSIT_TO_FIELD",
+							"IN_TRANSIT_TO_INVENTORY",
+							"NOT_IN_TRANSIT"
+						]))
+					},
+					{
+						name: "with-inventory-statuses",
+						queryName: "withInventoryStatuses",
+						description: "In_inventory, not_in_inventory, or both, which filters only when one is sent",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "with-location-company-type",
+						queryName: "withLocationCompanyType",
+						description: "Customer, manufacturer, or both, for assets at customer sites or your own, which filters only when one is sent",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "with-project-status",
+						queryName: "withProjectStatus",
+						description: "The project assignments to list: upcoming, active, past, or none",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "with-owner",
+						queryName: "withOwner",
+						description: "Manufacturer for assets your organization owns, customer for assets customers own, or both",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "for-project",
+						queryName: "forProject",
+						description: "The IDs of the projects whose assets to list",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "scrapped",
+						queryName: "scrapped",
+						description: "Whether to list unscrapped assets, scrapped assets, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					}
+				],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "create",
+				summary: "Create asset",
+				method: "POST",
+				path: "/asset",
+				pathParameters: [],
+				queryFlags: [],
+				takesBody: true
+			}),
+			{
+				name: "move",
+				summary: "Move commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [{
+					name: "execute",
+					summary: "Execute commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "create",
+						summary: "Execute asset move",
+						method: "POST",
+						path: "/asset/move/execute",
+						pathParameters: [],
+						queryFlags: [],
+						takesBody: true
+					})]
+				}, {
+					name: "plan",
+					summary: "Plan commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "create",
+						summary: "Plan asset move",
+						method: "POST",
+						path: "/asset/move/plan",
+						pathParameters: [],
+						queryFlags: [],
+						takesBody: true
+					})]
+				}]
+			},
+			defineOperation({
+				name: "get",
+				summary: "Get asset",
+				method: "GET",
+				path: "/asset/{assetKey}",
+				pathParameters: [{
+					name: "assetKey",
+					description: "The asset's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "update",
+				summary: "Patch asset",
+				method: "PATCH",
+				path: "/asset/{assetKey}",
+				pathParameters: [{
+					name: "assetKey",
+					description: "The asset's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: true
+			}),
+			{
+				name: "accounting",
+				summary: "Accounting commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "update",
+					summary: "Update asset accounting",
+					method: "PATCH",
+					path: "/asset/{assetKey}/accounting",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				}), {
+					name: "in-service-management",
+					summary: "In service management commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "update",
+						summary: "Toggle in service date management",
+						method: "PATCH",
+						path: "/asset/{assetKey}/accounting/in-service-management",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					})]
+				}]
+			},
+			{
+				name: "cost-adjustment",
+				summary: "Cost adjustment commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "create",
+					summary: "Create asset cost adjustment",
+					method: "POST",
+					path: "/asset/{assetKey}/cost-adjustment",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})]
+			},
+			{
+				name: "event",
+				summary: "Event commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get asset event list",
+					method: "GET",
+					path: "/asset/{assetKey}/event",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})]
+			},
+			{
+				name: "event-group",
+				summary: "Event group commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get asset event group listing",
+					method: "GET",
+					path: "/asset/{assetKey}/event-group",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [{
+						name: "start",
+						queryName: "start",
+						description: "The earliest an event group may have happened, or null to read from the first",
+						valueName: "value",
+						schema: z.string()
+					}, {
+						name: "end",
+						queryName: "end",
+						description: "The latest an event group may have happened, or null to read through the last",
+						valueName: "value",
+						schema: z.string()
+					}],
+					takesBody: false
+				}), defineOperation({
+					name: "get",
+					summary: "Get asset event group",
+					method: "GET",
+					path: "/asset/{assetKey}/event-group/{eventGroupKey}",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}, {
+						name: "eventGroupKey",
+						description: "The event group's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})]
+			},
+			{
+				name: "file",
+				summary: "File commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get asset files",
+					method: "GET",
+					path: "/asset/{assetKey}/file",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}), defineOperation({
+					name: "delete",
+					summary: "Delete asset file",
+					method: "DELETE",
+					path: "/asset/{assetKey}/file/{fileKey}",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}, {
+						name: "fileKey",
+						description: "The file's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})]
+			},
+			{
+				name: "functional-status",
+				summary: "Functional status commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get asset functional status history",
+					method: "GET",
+					path: "/asset/{assetKey}/functional-status",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})]
+			},
+			{
+				name: "ownership",
+				summary: "Ownership commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [
+					defineOperation({
+						name: "list",
+						summary: "Get asset ownership history",
+						method: "GET",
+						path: "/asset/{assetKey}/ownership",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					}),
+					defineOperation({
+						name: "create",
+						summary: "Create asset ownership",
+						method: "POST",
+						path: "/asset/{assetKey}/ownership",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}),
+					defineOperation({
+						name: "clear",
+						summary: "Clear the ownership an asset holds today",
+						method: "DELETE",
+						path: "/asset/{assetKey}/ownership",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}),
+					defineOperation({
+						name: "get",
+						summary: "Get asset ownership segment",
+						method: "GET",
+						path: "/asset/{assetKey}/ownership/{segmentKey}",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}, {
+							name: "segmentKey",
+							description: "The ownership segment's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					}),
+					defineOperation({
+						name: "update",
+						summary: "Patch asset ownership segment",
+						method: "PATCH",
+						path: "/asset/{assetKey}/ownership/{segmentKey}",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}, {
+							name: "segmentKey",
+							description: "The ownership segment's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}),
+					defineOperation({
+						name: "delete",
+						summary: "Delete asset ownership segment",
+						method: "DELETE",
+						path: "/asset/{assetKey}/ownership/{segmentKey}",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}, {
+							name: "segmentKey",
+							description: "The ownership segment's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					})
+				]
+			},
+			{
+				name: "scrap",
+				summary: "Scrap commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "create",
+					summary: "Scrap asset",
+					method: "POST",
+					path: "/asset/{assetKey}/scrap",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})]
+			},
+			{
+				name: "unscrap",
+				summary: "Unscrap commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "create",
+					summary: "Unscrap asset",
+					method: "POST",
+					path: "/asset/{assetKey}/unscrap",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})]
+			},
+			{
+				name: "url-link",
+				summary: "URL link commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get asset URL links",
+					method: "GET",
+					path: "/asset/{assetKey}/url-link",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}), defineOperation({
+					name: "create",
+					summary: "Create asset URL link",
+					method: "POST",
+					path: "/asset/{assetKey}/url-link",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})]
+			},
+			{
+				name: "useful-life-revision",
+				summary: "Useful life revision commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "create",
+					summary: "Create asset useful life revision",
+					method: "POST",
+					path: "/asset/{assetKey}/useful-life-revision",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})]
+			}
+		]
+	},
+	{
+		name: "customer",
+		summary: "Customer commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [
+			defineOperation({
+				name: "list",
+				summary: "Get customers",
+				method: "GET",
+				path: "/customer",
+				pathParameters: [],
+				queryFlags: [
+					{
+						name: "page",
+						queryName: "page",
+						description: "The page to return, starting at 1",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "limit",
+						queryName: "limit",
+						description: "The number of records per page, from 1 to 100",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "sort-by",
+						queryName: "sortBy",
+						description: "The field to sort by",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "sort-order",
+						queryName: "sortOrder",
+						description: "The sort direction",
+						valueName: "value",
+						schema: z.enum(["ASC", "DESC"])
+					},
+					{
+						name: "archived",
+						queryName: "archived",
+						description: "Whether to return unarchived records, archived records, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					},
+					{
+						name: "is-customer",
+						queryName: "isCustomer",
+						description: "True to return only customers, or false to return only non-customers",
+						schema: z.boolean()
+					},
+					{
+						name: "is-supplier",
+						queryName: "isSupplier",
+						description: "True to return only suppliers, or false to return only non-suppliers",
+						schema: z.boolean()
+					},
+					{
+						name: "sync-statuses",
+						queryName: "syncStatuses",
+						description: "The CRM sync statuses to return: in-sync, out-of-sync, or not-linked",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "search",
+						queryName: "search",
+						description: "Text to match against customer names",
+						valueName: "value",
+						schema: z.string()
+					}
+				],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "create",
+				summary: "Create customer",
+				method: "POST",
+				path: "/customer",
+				pathParameters: [],
+				queryFlags: [],
+				takesBody: true
+			}),
+			defineOperation({
+				name: "get",
+				summary: "Get customer",
+				method: "GET",
+				path: "/customer/{customerKey}",
+				pathParameters: [{
+					name: "customerKey",
+					description: "The customer's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "update",
+				summary: "Patch customer",
+				method: "PATCH",
+				path: "/customer/{customerKey}",
+				pathParameters: [{
+					name: "customerKey",
+					description: "The customer's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: true
+			})
+		]
+	},
+	{
+		name: "file",
+		summary: "File commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [defineOperation({
+			name: "create",
+			summary: "Upload file",
+			method: "POST",
+			path: "/file",
+			pathParameters: [],
+			queryFlags: [],
+			takesBody: true
+		}), defineOperation({
+			name: "get",
+			summary: "Get file",
+			method: "GET",
+			path: "/file/{fileKey}",
+			pathParameters: [{
+				name: "fileKey",
+				description: "The file's key, and a public file is readable with any organization's API key while any other file is readable only with its own organization's",
+				required: true
+			}],
+			queryFlags: [{
+				name: "attachment",
+				queryName: "attachment",
+				description: "True when the file downloads as an attachment rather than opening inline",
+				schema: z.boolean()
+			}],
+			takesBody: false
+		})]
+	},
+	{
+		name: "item",
+		summary: "Item commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [
+			defineOperation({
+				name: "list",
+				summary: "Get items",
+				method: "GET",
+				path: "/item",
+				pathParameters: [],
+				queryFlags: [
+					{
+						name: "type",
+						queryName: "type",
+						description: "The item type to list, SERVICE, DEVICE, or BULK, or absent for every type",
+						valueName: "value",
+						schema: z.enum([
+							"BULK",
+							"DEVICE",
+							"SERVICE"
+						])
+					},
+					{
+						name: "search",
+						queryName: "search",
+						description: "Text to match against item names, SKUs, and descriptions, in any case",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "page",
+						queryName: "page",
+						description: "The page to return, starting at 1",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "limit",
+						queryName: "limit",
+						description: "The number of records per page, from 1 to 100",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "sort-by",
+						queryName: "sortBy",
+						description: "The field to sort by",
+						valueName: "value",
+						schema: z.enum([
+							"name",
+							"sku",
+							"type",
+							"lastUpdatedAt"
+						])
+					},
+					{
+						name: "sort-order",
+						queryName: "sortOrder",
+						description: "The sort direction",
+						valueName: "value",
+						schema: z.enum(["ASC", "DESC"])
+					},
+					{
+						name: "archived",
+						queryName: "archived",
+						description: "Whether to return unarchived records, archived records, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					},
+					{
+						name: "exclude-linked-integration",
+						queryName: "excludeLinkedIntegration",
+						description: "An integration whose already-linked items to leave out",
+						valueName: "value",
+						schema: z.string()
+					}
+				],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "create",
+				summary: "Create item",
+				method: "POST",
+				path: "/item",
+				pathParameters: [],
+				queryFlags: [],
+				takesBody: true
+			}),
+			defineOperation({
+				name: "get",
+				summary: "Get item",
+				method: "GET",
+				path: "/item/{itemKey}",
+				pathParameters: [{
+					name: "itemKey",
+					description: "The item's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "update",
+				summary: "Update item",
+				method: "PATCH",
+				path: "/item/{itemKey}",
+				pathParameters: [{
+					name: "itemKey",
+					description: "The item's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: true
+			}),
+			{
+				name: "accounting",
+				summary: "Accounting commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "update",
+					summary: "Update item accounting",
+					method: "PATCH",
+					path: "/item/{itemKey}/accounting",
+					pathParameters: [{
+						name: "itemKey",
+						description: "The item's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})]
+			},
+			{
+				name: "field",
+				summary: "Field commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [
+					defineOperation({
+						name: "create",
+						summary: "Create item field",
+						method: "POST",
+						path: "/item/{itemKey}/field",
+						pathParameters: [{
+							name: "itemKey",
+							description: "The item's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}),
+					defineOperation({
+						name: "update",
+						summary: "Update item field",
+						method: "PATCH",
+						path: "/item/{itemKey}/field/{fieldKey}",
+						pathParameters: [{
+							name: "itemKey",
+							description: "The item's key",
+							required: true
+						}, {
+							name: "fieldKey",
+							description: "The field's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}),
+					defineOperation({
+						name: "delete",
+						summary: "Delete item field",
+						method: "DELETE",
+						path: "/item/{itemKey}/field/{fieldKey}",
+						pathParameters: [{
+							name: "itemKey",
+							description: "The item's key",
+							required: true
+						}, {
+							name: "fieldKey",
+							description: "The field's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					})
+				]
+			}
+		]
+	},
+	{
+		name: "location",
+		summary: "Location commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [
+			defineOperation({
+				name: "list",
+				summary: "Get location listing",
+				method: "GET",
+				path: "/location",
+				pathParameters: [],
+				queryFlags: [
+					{
+						name: "page",
+						queryName: "page",
+						description: "The page to return, starting at 1",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "limit",
+						queryName: "limit",
+						description: "The number of records per page, from 1 to 100",
+						valueName: "number",
+						schema: z.coerce.number()
+					},
+					{
+						name: "sort-by",
+						queryName: "sortBy",
+						description: "The field to sort by",
+						valueName: "value",
+						schema: z.enum([
+							"name",
+							"company",
+							"assetCount"
+						])
+					},
+					{
+						name: "sort-order",
+						queryName: "sortOrder",
+						description: "The sort direction",
+						valueName: "value",
+						schema: z.enum(["ASC", "DESC"])
+					},
+					{
+						name: "archived",
+						queryName: "archived",
+						description: "Whether to return unarchived records, archived records, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					},
+					{
+						name: "is-transient",
+						queryName: "isTransient",
+						description: "Whether to return permanent locations (false), transient locations (true), or both (all)",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					},
+					{
+						name: "search",
+						queryName: "search",
+						description: "Text to match against location and customer names",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "for-customer-ids",
+						queryName: "forCustomerIds",
+						description: "The IDs of the customers whose locations to return",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					},
+					{
+						name: "include-organization",
+						queryName: "includeOrganization",
+						description: "Whether the customer filter also matches your organization's own locations, which on its own returns only those",
+						schema: z.boolean()
+					},
+					{
+						name: "sync-statuses",
+						queryName: "syncStatuses",
+						description: "The CRM sync statuses to return: in-sync, out-of-sync, or not-linked",
+						valueName: "value",
+						repeatable: true,
+						schema: z.array(z.string())
+					}
+				],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "create",
+				summary: "Create location",
+				method: "POST",
+				path: "/location",
+				pathParameters: [],
+				queryFlags: [],
+				takesBody: true
+			}),
+			defineOperation({
+				name: "get",
+				summary: "Get location",
+				method: "GET",
+				path: "/location/{locationKey}",
+				pathParameters: [{
+					name: "locationKey",
+					description: "The location's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "update",
+				summary: "Patch location",
+				method: "PATCH",
+				path: "/location/{locationKey}",
+				pathParameters: [{
+					name: "locationKey",
+					description: "The location's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: true
+			}),
+			{
+				name: "zones",
+				summary: "Zones commands",
+				arguments: [],
+				flags: [],
+				examples: [],
+				subcommands: [defineOperation({
+					name: "list",
+					summary: "Get zones",
+					method: "GET",
+					path: "/location/{locationKey}/zones",
+					pathParameters: [{
+						name: "locationKey",
+						description: "The key of the site whose zones to list",
+						required: true
+					}],
+					queryFlags: [{
+						name: "archived",
+						queryName: "archived",
+						description: "Whether to return unarchived zones, archived zones, or all of them",
+						valueName: "value",
+						schema: z.enum([
+							"all",
+							"false",
+							"true"
+						])
+					}],
+					takesBody: false
+				})]
+			}
+		]
+	},
+	{
+		name: "url-link",
+		summary: "URL link commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [
+			defineOperation({
+				name: "get",
+				summary: "Get URL link by key",
+				method: "GET",
+				path: "/url-link/{linkKey}",
+				pathParameters: [{
+					name: "linkKey",
+					description: "The URL link's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			}),
+			defineOperation({
+				name: "update",
+				summary: "Update URL link",
+				method: "PATCH",
+				path: "/url-link/{linkKey}",
+				pathParameters: [{
+					name: "linkKey",
+					description: "The URL link's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: true
+			}),
+			defineOperation({
+				name: "delete",
+				summary: "Delete URL link",
+				method: "DELETE",
+				path: "/url-link/{linkKey}",
+				pathParameters: [{
+					name: "linkKey",
+					description: "The URL link's key",
+					required: true
+				}],
+				queryFlags: [],
+				takesBody: false
+			})
+		]
+	}
+];
+//#endregion
+//#region src/auth/jwt.ts
+/**
+* toClaims reads an access token's payload for display. Nothing here verifies the
+* signature, because the API is what decides whether a token is good.
+*/
+function toClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return {
+			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
+			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
+			scopes: toScopes(decoded),
+			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
+function toScopes(decoded) {
+	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
+	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
+}
+//#endregion
+//#region src/system/host.ts
+const BYTES_PER_GB = 1024 ** 3;
+/** toDistribution reads the name a Linux distribution gives itself. */
+function toDistribution(osRelease) {
+	const pretty = /^PRETTY_NAME="?([^"\n]+)"?$/m.exec(osRelease);
+	if (pretty?.[1]) return pretty[1];
+	const name = /^NAME="?([^"\n]+)"?$/m.exec(osRelease);
+	const version = /^VERSION_ID="?([^"\n]+)"?$/m.exec(osRelease);
+	if (!name?.[1]) return;
+	return version?.[1] ? `${name[1]} ${version[1]}` : name[1];
+}
+/** toHostReport describes the machine, which is what a support request cannot ask for twice. */
+function toHostReport() {
+	const report = {
+		type: type(),
+		kernel: release(),
+		build: version(),
+		arch: arch(),
+		cpus: cpus().length,
+		cpu: cpus()[0]?.model ?? null,
+		memoryGb: Number((totalmem() / BYTES_PER_GB).toFixed(1)),
+		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+		shell: process.env["SHELL"] ?? process.env["ComSpec"] ?? null,
+		terminal: process.env["TERM"] ?? null
+	};
+	if (process.platform !== "linux") return report;
+	report["distribution"] = toDistribution(toFile("/etc/os-release")) ?? null;
+	if (isWSL()) report["wsl"] = {
+		distribution: process.env["WSL_DISTRO_NAME"] ?? null,
+		windowsTerminal: Boolean(process.env["WT_SESSION"])
+	};
+	return report;
+}
+function toFile(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region src/command/status.ts
+/**
+* Hardfin expires an unused refresh token after this long. It is the server's rule, not the
+* CLI's, and the token endpoint reports no expiry, so what this produces is an estimate.
+*/
+const REFRESH_SLIDING_DAYS = 90;
+const statusCommand = defineCommand({
+	name: "status",
+	summary: "Report what this CLI is configured with, signed in as, and able to reach",
+	description: "Gathers everything a support request needs: the version, the configuration and where each value came from, the authorization server's endpoints, where the credential is stored, and when the tokens expire. Secrets are reported as fingerprints, never printed.",
+	arguments: [],
+	flags: [{
+		name: "offline",
+		description: "Skip every network call, and report only what is on this machine",
+		schema: z.boolean()
+	}, {
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [
+		{
+			description: "See what the CLI is using",
+			command: "hardfin status"
+		},
+		{
+			description: "Attach the whole picture to a support request",
+			command: "hardfin status --json > status.json"
+		},
+		{
+			description: "Ask nothing of the network",
+			command: "hardfin status --offline"
+		}
+	],
+	run: runStatus
+});
+async function runStatus(input) {
+	const settings = input.resolved.settings;
+	const stored = toCredential(settings.issuerUrl);
+	const report = {
+		cli: toEnvironmentReport(),
+		host: toHostReport(),
+		configuration: toConfigurationReport(input.resolved),
+		credential: toCredentialReport(settings.apiKey, stored)
+	};
+	if (input.flags["offline"] === true) {
+		report["authorizationServer"] = { checked: false };
+		report["api"] = { checked: false };
+		writeReport(report, input.isJSON);
+		return stored || settings.apiKey ? ExitCode.OK : ExitCode.NOT_AUTHENTICATED;
+	}
+	const metadata = await toMetadata(settings.issuerUrl).catch((error) => error);
+	report["authorizationServer"] = metadata instanceof Error ? {
+		reachable: false,
+		error: metadata.message
+	} : toServerReport(metadata);
+	report["api"] = await toApiReport(input);
+	writeReport(report, input.isJSON);
+	return report["api"].authenticated === false ? ExitCode.NOT_AUTHENTICATED : ExitCode.OK;
+}
+function toEnvironmentReport() {
+	return {
+		version: version$1,
+		apiVersion: API_VERSION,
+		node: process.version,
+		platform: process.platform,
+		interactive: Boolean(process.stdin.isTTY)
+	};
+}
+/** toConfigurationReport names every setting, its source, and never a secret's value. */
+function toConfigurationReport(resolved) {
+	const entries = Object.entries(resolved.settings).map(([key, value]) => {
+		const from = resolved.sources[key];
+		if (key === "apiKey") return [key, {
+			set: value !== void 0,
+			fingerprint: toFingerprint(value),
+			from
+		}];
+		return [key, {
+			value: value ?? null,
+			from
+		}];
+	});
+	return {
+		...Object.fromEntries(entries),
+		configFile: CONFIG_FILE
+	};
+}
+function toCredentialReport(apiKey, stored) {
+	if (apiKey) return {
+		kind: "api key",
+		signedIn: false,
+		note: "an API key is set, so it is used ahead of any sign in"
+	};
+	if (!stored) return {
+		kind: "none",
+		signedIn: false,
+		note: "run hardfin login, or set HARDFIN_API_KEY"
+	};
+	return {
+		kind: "browser sign in",
+		signedIn: true,
+		storedIn: stored.backend,
+		path: stored.path ?? null,
+		fingerprint: toFingerprint(stored.refreshToken),
+		signedInAt: stored.signedInAt ?? null,
+		renewedAt: stored.renewedAt ?? null,
+		refreshExpiresAt: toRefreshExpiry(stored.renewedAt),
+		refreshExpiryIsEstimated: true
+	};
+}
+function toServerReport(metadata) {
+	return {
+		reachable: true,
+		issuer: metadata.issuer,
+		authorizationEndpoint: metadata.authorization_endpoint,
+		tokenEndpoint: metadata.token_endpoint,
+		revocationEndpoint: metadata.revocation_endpoint ?? null,
+		deviceEndpoint: metadata.device_authorization_endpoint ?? null,
+		grantTypes: metadata.grant_types_supported ?? [],
+		scopes: metadata.scopes_supported ?? []
+	};
+}
+/** toApiReport asks the API who this credential is, which is the only authoritative answer. */
+async function toApiReport(input) {
+	const settings = input.resolved.settings;
+	try {
+		const credential = await toRequestCredential(settings);
+		const claims = credential.kind === "access token" ? toClaims(credential.value.replace(/^Bearer /, "")) : {};
+		const identity = await request({
+			apiUrl: settings.apiUrl,
+			credential,
+			method: "GET",
+			path: "/token"
+		}).then((envelope) => envelope.data).catch((error) => error instanceof RequestFailure ? { unavailable: error.message } : { unavailable: String(error) });
+		return {
+			reachable: true,
+			authenticated: true,
+			url: settings.apiUrl,
+			accessTokenExpiresAt: claims.expiresAt === void 0 ? null : new Date(claims.expiresAt).toISOString(),
+			accessTokenScopes: claims.scopes ?? [],
+			identity
+		};
+	} catch (error) {
+		if (error instanceof NoCredential) return {
+			reachable: null,
+			authenticated: false,
+			url: settings.apiUrl,
+			error: error.message
+		};
+		return {
+			reachable: false,
+			authenticated: false,
+			url: settings.apiUrl,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/** toRefreshExpiry applies the server's sliding rule to when the token was last renewed. */
+function toRefreshExpiry(renewedAt) {
+	if (!renewedAt) return null;
+	const renewed = new Date(renewedAt);
+	renewed.setDate(renewed.getDate() + REFRESH_SLIDING_DAYS);
+	return renewed.toISOString();
+}
+/** toFingerprint identifies a secret in a support request without disclosing it. */
+function toFingerprint(secret) {
+	if (!secret) return null;
+	return `sha256:${createHash("sha256").update(secret).digest("hex").slice(0, 12)}`;
+}
+function writeReport(report, isJSON) {
+	if (isJSON) {
+		writeData(report);
+		return;
+	}
+	writeData(toLines(report).join("\n"));
+}
+/** toFlattened reads a setting, which is a value and the layer that supplied it. */
+function toFlattened(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
+	const holder = value;
+	if (holder.from === void 0) return;
+	const shown = holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set");
+	return `${String(shown)}  (${holder.from})`;
+}
+/** toLines lays the report out for a person, one indented line per value. */
+function toLines(report, depth = 0) {
+	const lines = [];
+	const pad = "  ".repeat(depth);
+	for (const [key, value] of Object.entries(report)) {
+		const flattened = toFlattened(value);
+		if (flattened !== void 0) {
+			lines.push(`${pad}${key.padEnd(26 - depth * 2)} ${flattened}`);
+			continue;
+		}
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			lines.push(`${pad}${key}`, ...toLines(value, depth + 1));
+			continue;
+		}
+		lines.push(`${pad}${key.padEnd(26 - depth * 2)} ${Array.isArray(value) ? value.join(", ") : String(value)}`);
+	}
+	return lines;
+}
+//#endregion
+//#region src/command/commands.ts
+/** commands is every command the CLI offers, and drives help and the agent guide. */
+const commands = [
+	loginCommand,
+	logoutCommand,
+	statusCommand,
+	...surfaceCommands,
+	apiCommand,
+	configCommand,
+	agentGuideCommand
+];
+//#endregion
+//#region src/command/validate.ts
+/** toRejectedFlag names the first flag whose value its schema refuses. */
+function toRejectedFlag(command, flags) {
+	for (const flag of command.flags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		if (!flag.schema.safeParse(value).success) return `--${flag.name} does not accept ${JSON.stringify(value)}`;
+	}
+}
+//#endregion
+//#region src/cli.ts
+const program = new Command();
+program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").option("--api-url <url>", "The API to call, whose host also holds the authorization server").option("--issuer-url <url>", "The authorization server, when it does not sit at the API's host").showHelpAfterError().enablePositionalOptions();
+for (const command of commands) program.addCommand(toProgram(command));
+await program.parseAsync(process.argv);
+/** toProgram wires one registry command into the parser. */
+function toProgram(command) {
+	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
+	for (const argument of command.arguments) {
+		const name = argument.variadic ? `${argument.name}...` : argument.name;
+		program.argument(argument.required ? `<${name}>` : `[${name}]`, argument.description);
+	}
+	for (const flag of command.flags) {
+		const short = flag.short ? `-${flag.short}, ` : "";
+		const value = flag.valueName ? ` <${flag.valueName}>` : "";
+		const option = new Option(`${short}--${flag.name}${value}`, flag.description);
+		if (flag.repeatable) option.argParser(collect);
+		if (flag.defaultValue !== void 0) option.default(flag.defaultValue);
+		program.addOption(option);
+	}
+	for (const example of command.examples) program.addHelpText("after", `\n${example.description}:\n  $ ${example.command}`);
+	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(subcommand));
+	if (!command.run) return program;
+	program.action(async (...parsed) => {
+		const flags = parsed[parsed.length - 2] ?? {};
+		const args = parsed.slice(0, parsed.length - 2).flatMap(toArgumentList);
+		process.exitCode = await toExitCode(command, args, flags);
+	});
+	return program;
+}
+async function toExitCode(command, args, flags) {
+	const isJSON = isJSONOutput(flags);
+	const rejected = toRejectedFlag(command, flags);
+	if (rejected) {
+		writeFailure(rejected, isJSON);
+		return ExitCode.USAGE;
+	}
+	try {
+		const resolved = toSettings({
+			apiUrl: program.opts()["apiUrl"],
+			issuerUrl: program.opts()["issuerUrl"]
+		});
+		return await command.run?.({
+			args,
+			flags,
+			isJSON,
+			commands,
+			resolved
+		}) ?? ExitCode.OK;
+	} catch (error) {
+		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
+		return error instanceof ConfigFailure ? ExitCode.USAGE : ExitCode.ERROR;
+	}
+}
+function toArgumentList(value) {
+	if (Array.isArray(value)) return value.map(String);
+	return value === void 0 ? [] : [String(value)];
+}
+function collect(value, previous) {
+	return [...previous ?? [], value];
+}
+//#endregion
+export {};