@hardfin/cli 0.1.1-dev.56 → 0.1.1-dev.58

package/dist/{program-CI4W2agw.js → program-C2DP0mVy.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cb5319cf-733c-5f06-b5d8-f8f154bf4267")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b26e6779-10c9-5732-b40c-04e75265338c")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
@@ -1127,6 +1127,7 @@ async function request$1(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
 	for (const [name, value] of options.query ?? []) url.searchParams.append(name, value);
 	const headers = {
+		...options.headers,
 		[options.credential.header]: options.credential.value,
 		"X-API-Version": API_VERSION,
 		Accept: options.downloads ? "*/*" : "application/json"
@@ -1558,98 +1559,130 @@ function toJSONInput(source) {
 		return new InputFailure(`${name} does not hold JSON`);
 	}
 }
-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"
+//#endregion
+//#region src/command/operation.ts
+/**
+* toEnum takes a value in any case, as the API does, and answers the spelling the document
+* lists, which is what a response always uses.
+*/
+function toEnum(values) {
+	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+}
+/** The word that clears a field the API takes null for, and the way to send that word as text. */
+const NULL_WORD = "null";
+/**
+* toNullOrText reads the word null before anything else. A field the API takes null for is
+* cleared by it, and "null" in quotes is the text. Any other value comes back as it was.
+*/
+function toNullOrText(value, isNullable) {
+	if (value === "\"null\"") return NULL_WORD;
+	return isNullable && value === "null" ? null : value;
+}
+const UNSET_FLAG = {
+	name: "unset",
+	description: "A field to clear, named as its flag is, repeatable",
+	valueName: "field",
+	repeatable: true,
+	schema: z.array(z.string())
+};
+const INPUT_FLAG = {
+	name: "input",
+	description: "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+	valueName: "path",
+	schema: z.string()
+};
+const FILE_FLAG = {
+	name: "file",
+	description: "The file to upload",
+	valueName: "path",
+	schema: z.string()
+};
+const OUTPUT_FLAG = {
+	name: "output",
+	description: "Where to write the file, or - for standard output",
+	valueName: "path",
+	schema: z.string()
+};
+const JSON_FLAG$1 = {
+	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,
+		...operation.bodyFlags,
+		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
+		...operation.bodyFlags.length > 0 ? [INPUT_FLAG] : [],
+		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		...operation.downloads ? [OUTPUT_FLAG] : [],
+		JSON_FLAG$1
+	];
+	return {
+		name: operation.name,
+		summary: operation.summary,
+		description: operation.description ?? operation.summary,
+		arguments: operation.pathParameters,
+		flags,
+		examples: operation.example ? [{
+			description: operation.summary,
+			command: operation.example
+		}] : [],
+		endpoint: {
+			method: operation.method,
+			path: operation.path
 		},
-		{
-			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("invalid_arguments", "a path is required, such as /customer", input.isJSON);
+		run: (input) => runOperation(operation, input)
+	};
+}
+async function runOperation(operation, input) {
+	const path = toPath(operation, input.args);
+	if (path === void 0) {
+		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s), each the key of a record`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	if (!isInsideApi(input.resolved.settings.apiUrl, path)) {
-		writeFailure("invalid_arguments", "a path stays inside the API, so it cannot climb out of it with ..", input.isJSON);
+	const given = toGivenBody$1(input.flags["input"]);
+	if (given instanceof InputFailure) {
+		writeFailure("invalid_input", given.message, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const query = toQuery$1(input.flags["field"]);
-	if (query === void 0) {
-		writeFailure("invalid_flag", "each --field is key=value, such as -f limit=50", input.isJSON);
+	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0 && !hasPath(given, flag.jsonPath));
+	if (missing.length > 0) {
+		writeFailure("missing_flag", `this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	let body;
-	if (typeof input.flags["input"] === "string") {
-		body = toJSONInput(input.flags["input"]);
-		if (body instanceof InputFailure) {
-			writeFailure("invalid_input", body.message, input.isJSON);
+	const body = toBody(operation, input.flags, given);
+	if (body instanceof Error) {
+		writeFailure("invalid_flag", body.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (operation.bodyFlags.length > 0 && body === void 0) {
+		writeFailure("empty_request", `this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let form;
+	if (operation.upload) {
+		const built = await toForm$1(operation.upload, input.flags);
+		if (built instanceof Error) {
+			writeFailure("invalid_input", built.message, input.isJSON);
 			return ExitCode.USAGE;
 		}
+		form = built;
 	}
 	try {
-		writeData((await request$1({
+		const envelope = await request$1({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
-			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
+			method: operation.method,
 			path,
-			query,
-			body
-		})).data);
+			query: toQuery$1(operation, input.flags),
+			body,
+			form,
+			downloads: operation.downloads
+		});
+		if (operation.downloads) return toWritten(envelope.data, input);
+		writeData(envelope.data);
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
@@ -1663,48 +1696,476 @@ async function runApi(input) {
 		throw error;
 	}
 }
-/** isInsideApi reports whether a path, once parsed, still lands under the API's own path. */
-function isInsideApi(apiUrl, path) {
-	try {
-		const base = new URL(apiUrl);
-		const target = new URL(`${apiUrl}${path.startsWith("/") ? "" : "/"}${path}`);
-		const root = base.pathname.replace(/\/+$/, "");
-		return target.origin === base.origin && (target.pathname === root || target.pathname.startsWith(`${root}/`));
-	} catch {
-		return false;
+/**
+* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
+* because a person would otherwise have their session filled with a file's bytes.
+*/
+function toWritten(download, input) {
+	const asked = input.flags["output"];
+	const offered = typeof asked === "string" ? void 0 : download.fileName;
+	const path = typeof asked === "string" ? asked : offered === void 0 ? "-" : toLocalName(offered);
+	if (path === void 0 || offered !== void 0 && existsSync(path)) {
+		writeFailure("output_required", path === void 0 ? `this file is offered as ${JSON.stringify(offered)}, which is not a name to write here, so name where to write it with --output` : `${path} already exists, so name where to write this file with --output`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (path === "-") {
+		if (process.stdout.isTTY) {
+			writeFailure("output_required", "this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
+			return ExitCode.USAGE;
+		}
+		process.stdout.write(download.bytes);
+		return ExitCode.OK;
 	}
+	writeFileSync(path, download.bytes);
+	writeData({
+		written: path,
+		bytes: download.bytes.length,
+		contentType: download.contentType
+	});
+	return ExitCode.OK;
 }
-/** toQuery folds the repeated --field flags into query parameters. */
-function toQuery$1(fields) {
+/** toLocalName reduces a name the API offered to one file in the working directory, or to nothing. */
+function toLocalName(offered) {
+	const name = offered.split(/[\\/]/).pop() ?? "";
+	return name === "" || name.startsWith(".") ? void 0 : name;
+}
+/** The arguments a URL reads as "this folder" and "the one above", and one that names nothing. */
+const NOT_A_KEY = /* @__PURE__ */ new Set([
+	"",
+	".",
+	".."
+]);
+/** toPath fills the path template from the positional arguments, in order. */
+function toPath(operation, args) {
+	if (args.length !== operation.pathParameters.length || args.some((argument) => NOT_A_KEY.has(argument))) 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$1(operation, flags) {
 	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));
+	for (const flag of operation.queryFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		const parsed = flag.schema.safeParse(value);
+		const carried = parsed.success ? parsed.data : value;
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
 	}
 	return query;
 }
-//#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");
+/** toOptionKey names the parsed flag, which the parser reports in camel case. */
+function toOptionKey(name) {
+	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
-/**
-* toOpenable answers the address a browser may be sent to, and nothing for anything else. The
-* address comes from the authorization server, which a file in the working directory can
-* name, so it is parsed and written out again before any program is handed it.
-*/
-function toOpenable(url) {
-	let parsed;
+/** toForm builds the file part and its fields, which an upload endpoint takes. */
+async function toForm$1(upload, flags) {
+	const path = flags["file"];
+	if (typeof path !== "string") return /* @__PURE__ */ new Error("this command needs --file, the file to upload");
+	const form = new FormData();
 	try {
-		parsed = new URL(url);
+		form.append(upload.filePart, await openAsBlob(path), basename(path));
 	} catch {
-		return;
+		return /* @__PURE__ */ new Error(`${path} cannot be read`);
 	}
-	const isLocal = parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
-	return parsed.protocol === "https:" || isLocal ? parsed.href : void 0;
-}
+	for (const field of upload.fields) {
+		const value = flags[toOptionKey(field.name)];
+		if (value !== void 0) {
+			const parsed = field.schema.safeParse(value);
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
+		}
+	}
+	return form;
+}
+/** toGivenBody reads the --input body, which a generated command takes only as a JSON object. */
+function toGivenBody$1(source) {
+	if (typeof source !== "string") return;
+	const read = toJSONInput(source);
+	if (read instanceof InputFailure) return read;
+	if (typeof read !== "object" || read === null || Array.isArray(read)) return new InputFailure(`the body in ${source === "-" ? "standard input" : source} must be a JSON object, such as {"name": "Acme"}`);
+	return read;
+}
+/** hasPath reports whether a body already holds a value at a field's path. */
+function hasPath(body, path) {
+	let holder = body;
+	for (const name of path) {
+		if (typeof holder !== "object" || holder === null || !(name in holder)) return false;
+		holder = holder[name];
+	}
+	return true;
+}
+/** toBody builds the request body from the --input body and the flags, a flag winning over its field. */
+function toBody(operation, flags, given) {
+	const body = given ? structuredClone(given) : {};
+	let hasField = given !== void 0;
+	for (const flag of operation.bodyFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		if (flag.element) {
+			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
+			if (elements instanceof Error) return elements;
+			set(body, flag.jsonPath, elements);
+			hasField = true;
+			continue;
+		}
+		const given = toNullOrText(value, flag.nullable === true);
+		if (given === null) {
+			set(body, flag.jsonPath, null);
+			hasField = true;
+			continue;
+		}
+		const parsed = flag.schema.safeParse(given);
+		set(body, flag.jsonPath, parsed.success ? parsed.data : given);
+		hasField = true;
+	}
+	const cleared = toCleared(operation, flags, body);
+	if (cleared instanceof Error) return cleared;
+	return hasField || cleared ? body : void 0;
+}
+/** toCleared sends null for each field named by --unset, which is how a field is cleared. */
+function toCleared(operation, flags, body) {
+	const named = flags["unset"];
+	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
+	for (const name of names) {
+		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
+		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
+		if (!flag.nullable) return /* @__PURE__ */ new Error(`--${flag.name} cannot be cleared, because the API does not accept null for it`);
+		set(body, flag.jsonPath, null);
+	}
+	return names.length > 0;
+}
+/** toElements reads the key=value pairs a repeated flag carries for one array element. */
+function toElements(flag, values) {
+	const elements = [];
+	for (const value of values) {
+		const element = {};
+		for (const pair of value.split(",")) {
+			const split = pair.indexOf("=");
+			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ") ?? ""}=, such as --${flag.name} ${flag.element?.[0] ?? "field"}=value. A value cannot contain a comma`);
+			const isJSON = pair[split - 1] === ":";
+			const key = pair.slice(0, isJSON ? split - 1 : split).trim();
+			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
+			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
+			const value = pair.slice(split + 1).trim();
+			if (flag.elementUuids?.includes(key) && !z.uuid().safeParse(value).success) return /* @__PURE__ */ new Error(`--${flag.name} needs a UUID for ${key}, such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90, and ${value || "nothing"} is not one`);
+			const types = flag.elementTypes?.[key];
+			const typed = isJSON ? toJSONValue(value, types ?? ["string"]) : toTyped(value, types);
+			if (typed === NOT_TAKEN) return /* @__PURE__ */ new Error(`--${flag.name} needs ${toNamedTypes(types ?? ["string"])} for ${key}, and ${value || "nothing"} is not one`);
+			element[key] = typed;
+		}
+		elements.push(element);
+	}
+	return elements;
+}
+/** Marks text that is none of the types a field takes. */
+const NOT_TAKEN = Symbol("not taken");
+const NUMBER = /^-?\d+(\.\d+)?$/;
+/**
+* toTyped reads the text after key= as the type the document gives the field. A field that
+* takes text is sent as typed, whatever it looks like, because 36 may be a serial number. A
+* field that takes no text has only one reading, so order=2 is sent as the number.
+*/
+function toTyped(text, types) {
+	const given = toNullOrText(text, types?.includes("null") === true);
+	if (given === null || given !== text) return given;
+	if (types === void 0 || types.includes("string")) return text;
+	if ((types.includes("integer") || types.includes("number")) && NUMBER.test(text)) {
+		const value = Number(text);
+		if (types.includes("number") || Number.isInteger(value)) return value;
+	}
+	if (types.includes("boolean") && (text === "true" || text === "false")) return text === "true";
+	return NOT_TAKEN;
+}
+/**
+* toJSONValue reads the text after key:= as JSON, and takes it when the field takes its type.
+* It is how a custom field is given the number 36 or true, where key= would send the text.
+*/
+function toJSONValue(text, types) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return NOT_TAKEN;
+	}
+	const type = value === null ? "null" : typeof value;
+	return (types.includes(type) || type === "number" && types.includes("integer") && Number.isInteger(value)) && type !== "object" ? value : NOT_TAKEN;
+}
+/** toNamedTypes says in words what a field takes, for the message that refuses a value. */
+function toNamedTypes(types) {
+	const named = {
+		integer: "a whole number",
+		number: "a number",
+		boolean: "true or false",
+		string: "text in quotes",
+		null: "null"
+	};
+	return types.filter((type) => type in named).map((type) => named[type]).join(" or ");
+}
+/** set writes a value at its path, building the objects a nested field needs. */
+function set(body, path, value) {
+	let holder = body;
+	for (const name of path.slice(0, -1)) {
+		holder[name] = holder[name] ?? {};
+		holder = holder[name];
+	}
+	holder[path[path.length - 1] ?? ""] = value;
+}
+//#endregion
+//#region src/command/api.ts
+const METHODS = [
+	"GET",
+	"POST",
+	"PATCH",
+	"PUT",
+	"DELETE"
+];
+/** The part name the API's upload endpoints take a file under. */
+const DEFAULT_FILE_PART = "data";
+/** The headers that carry the credential and the version, which the CLI sets and a caller does not. */
+const KEPT_HEADERS = /* @__PURE__ */ new Set([
+	"authorization",
+	"x-api-key",
+	"x-api-version",
+	"host",
+	"content-length"
+]);
+const apiCommand = defineCommand({
+	name: "api",
+	summary: "Call a Hardfin API endpoint and print what it answers",
+	description: "Reaches every endpoint the API publishes, for when no generated command fits. The path is everything after /v2, and what the endpoint answered with is printed. A file is uploaded with --file and downloaded with --output.",
+	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(METHODS),
+			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: "file",
+			description: "A file to upload as multipart, in place of a JSON body",
+			valueName: "path",
+			schema: z.string().optional()
+		},
+		{
+			name: "file-part",
+			description: `The name of the part the file is sent as, which is ${DEFAULT_FILE_PART} when not given`,
+			valueName: "name",
+			schema: z.string().optional()
+		},
+		{
+			name: "form",
+			short: "F",
+			description: "A field sent beside the file as key=value, repeatable",
+			valueName: "key=value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "header",
+			short: "H",
+			description: "A request header as Name: value, repeatable",
+			valueName: "name: value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "output",
+			description: "Where to write a file the endpoint answers with, or - for standard output",
+			valueName: "path",
+			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"
+		},
+		{
+			description: "Download a file",
+			command: "hardfin api /file/file_7hq2mx9pkr4stz8w --output photo.jpg"
+		},
+		{
+			description: "Upload a file, with the fields the endpoint takes beside it",
+			command: "hardfin api -X POST /file --file photo.jpg -F fileType=ASSET_FILE -F forEntity=0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d70"
+		},
+		{
+			description: "Send a header",
+			command: "hardfin api /file/file_7hq2mx9pkr4stz8w -H \"If-None-Match: \\\"abc\\\"\" --output photo.jpg"
+		}
+	],
+	run: runApi
+});
+async function runApi(input) {
+	const path = input.args[0];
+	if (!path) {
+		writeFailure("invalid_arguments", "a path is required, such as /customer", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (!isInsideApi(input.resolved.settings.apiUrl, path)) {
+		writeFailure("invalid_arguments", "a path stays inside the API, so it cannot climb out of it with ..", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const query = toQuery(input.flags["field"]);
+	if (query === void 0) {
+		writeFailure("invalid_flag", "each --field is key=value, such as -f limit=50", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const headers = toHeaders(input.flags["header"]);
+	if (headers instanceof Error) {
+		writeFailure("invalid_flag", headers.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const method = toText(input.flags["method"] ?? "GET").toUpperCase();
+	const isUpload = typeof input.flags["file"] === "string";
+	if (isUpload && (typeof input.flags["input"] === "string" || method === "GET")) {
+		writeFailure("invalid_flag", method === "GET" ? "--file uploads a file, so give the method with -X, such as -X POST" : "--file and --input both give the body, so give one of them", input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let body;
+	if (typeof input.flags["input"] === "string") {
+		body = toJSONInput(input.flags["input"]);
+		if (body instanceof InputFailure) {
+			writeFailure("invalid_input", body.message, input.isJSON);
+			return ExitCode.USAGE;
+		}
+	}
+	const form = isUpload ? await toForm(input.flags) : void 0;
+	if (form instanceof Error) {
+		writeFailure("invalid_input", form.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const isDownload = typeof input.flags["output"] === "string";
+	try {
+		const envelope = await request$1({
+			apiUrl: input.resolved.settings.apiUrl,
+			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
+			method,
+			path,
+			query,
+			body,
+			form,
+			headers,
+			downloads: isDownload
+		});
+		if (isDownload) return toWritten(envelope.data, input);
+		writeData(envelope.data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof NoCredential) {
+			writeFailure("not_signed_in", error.message, input.isJSON);
+			return ExitCode.NOT_AUTHENTICATED;
+		}
+		if (error instanceof RequestFailure) {
+			writeFailure(toRequestCode(error), error.message, input.isJSON, error.errors, error.requestId, error.status);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		throw error;
+	}
+}
+/** isInsideApi reports whether a path, once parsed, still lands under the API's own path. */
+function isInsideApi(apiUrl, path) {
+	try {
+		const base = new URL(apiUrl);
+		const target = new URL(`${apiUrl}${path.startsWith("/") ? "" : "/"}${path}`);
+		const root = base.pathname.replace(/\/+$/, "");
+		return target.origin === base.origin && (target.pathname === root || target.pathname.startsWith(`${root}/`));
+	} catch {
+		return false;
+	}
+}
+/** toHeaders reads the repeated --header flags, and refuses one the CLI sets itself. */
+function toHeaders(given) {
+	const headers = {};
+	for (const header of Array.isArray(given) ? given : []) {
+		const split = header.indexOf(":");
+		const name = header.slice(0, Math.max(split, 0)).trim();
+		if (split < 1 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) return /* @__PURE__ */ new Error(`--header is Name: value, such as -H "If-None-Match: abc", and ${JSON.stringify(header)} is not`);
+		if (KEPT_HEADERS.has(name.toLowerCase())) return /* @__PURE__ */ new Error(`--header cannot set ${name}, because the CLI sets it from your sign in and settings`);
+		headers[name] = header.slice(split + 1).trim();
+	}
+	return headers;
+}
+/** toForm builds the multipart body an upload sends: the file, and the fields given beside it. */
+async function toForm(flags) {
+	const path = toText(flags["file"]);
+	const form = new FormData();
+	try {
+		form.append(toText(flags["filePart"] ?? DEFAULT_FILE_PART), await openAsBlob(path), basename(path));
+	} catch {
+		return /* @__PURE__ */ new Error(`${path} cannot be read`);
+	}
+	for (const field of Array.isArray(flags["form"]) ? flags["form"] : []) {
+		const split = field.indexOf("=");
+		if (split < 1) return /* @__PURE__ */ new Error(`each --form is key=value, such as -F fileType=ASSET_FILE, and ${JSON.stringify(field)} is not`);
+		form.append(field.slice(0, split), field.slice(split + 1));
+	}
+	return form;
+}
+/** toQuery folds the repeated --field flags into query parameters. */
+function toQuery(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;
+}
+//#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");
+}
+/**
+* toOpenable answers the address a browser may be sent to, and nothing for anything else. The
+* address comes from the authorization server, which a file in the working directory can
+* name, so it is parsed and written out again before any program is handed it.
+*/
+function toOpenable(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	const isLocal = parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+	return parsed.protocol === "https:" || isLocal ? parsed.href : void 0;
+}
 const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
 	"127.0.0.1",
 	"[::1]",
@@ -1933,7 +2394,7 @@ const YES_FLAG = {
 	description: "Make the change without asking",
 	schema: z.boolean()
 };
-const JSON_FLAG$1 = {
+const JSON_FLAG = {
 	name: "json",
 	description: "Print machine-readable output, which is the default when stdout is not a terminal",
 	schema: z.boolean()
@@ -1943,7 +2404,7 @@ const installCommand = defineCommand({
 	summary: "Set up completion in your shell",
 	description: "Writes the completion script under your data directory and loads it from your shell's startup file, between two marked lines. Fish loads it from its completions directory, so no startup file changes. Run it again after upgrading, so the script matches the CLI.",
 	arguments: [SHELL_ARGUMENT],
-	flags: [YES_FLAG, JSON_FLAG$1],
+	flags: [YES_FLAG, JSON_FLAG],
 	examples: [{
 		description: "Install for the shell you are using",
 		command: "hardfin completion install"
@@ -1958,7 +2419,7 @@ const uninstallCommand = defineCommand({
 	summary: "Remove completion from your shell",
 	description: "Removes the script install wrote, and the marked lines it added to your shell's startup file.",
 	arguments: [SHELL_ARGUMENT],
-	flags: [YES_FLAG, JSON_FLAG$1],
+	flags: [YES_FLAG, JSON_FLAG],
 	examples: [{
 		description: "Remove completion from zsh",
 		command: "hardfin completion uninstall zsh"
@@ -2592,837 +3053,503 @@ async function toTokensFromDevice(tokenUrl, clientId, device, sleep = toSleep) {
 		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, state) {
-	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;
-		}
-		if (!isOurs(answered, state)) {
-			writePage(response, 400, "Not this sign in", "This page did not come from the sign in your terminal started.");
-			return;
-		}
-		writeOutcome(response, answered);
-		settle(answered);
-	});
-	await new Promise((resolve, reject) => {
-		server.once("error", reject);
-		server.listen(0, HOST, resolve);
-	});
-	const timer = setTimeout(() => {
-		fail(new TimedOut("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
-	};
-}
-/**
-* isOurs answers whether a response belongs to this sign in. A refusal with no state at all
-* is still taken, because not every authorization server sends the state back with one.
-*/
-function isOurs(callback, state) {
-	if (callback.state !== void 0) return callback.state === state;
-	return callback.code === void 0 && callback.error !== void 0;
-}
-function writeOutcome(response, callback) {
-	if (!callback.error) {
-		writePage(response, 200, "Signed in", "You can close this tab and return to your terminal.");
-		return;
-	}
-	writePage(response, 200, "Sign in refused", `${callback.error}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}`);
-}
-/** toEscaped makes text safe to put in a page, because the words of a refusal come from the URL. */
-function toEscaped(text) {
-	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
-}
-function writePage(response, status, heading, words) {
-	const title = toEscaped(heading);
-	const detail = toEscaped(words);
-	response.writeHead(status, {
-		"Content-Type": "text/html; charset=utf-8",
-		"Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
-		"X-Content-Type-Options": "nosniff"
-	}).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, copy = spawnSync) {
-	const command = toClipboardCommand();
-	if (!command) return false;
-	const [name, args] = command;
-	const result = copy(name, args, { input: text });
-	return result.error === void 0 && result.status === 0;
-}
-//#endregion
-//#region src/auth/prompt.ts
-const CTRL_C = "";
-const CTRL_BACKSLASH = "";
-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, input = process.stdin, copy = copyToClipboard) {
-	let settle = () => {};
-	let fail = () => {};
-	const pasted = new Promise((resolve, reject) => {
-		settle = resolve;
-		fail = reject;
-	});
-	pasted.catch(() => {});
-	if (!input.isTTY) return {
-		pasted,
-		close: () => {}
-	};
-	let typed = "";
-	const onData = (chunk) => {
-		const isKeystroke = chunk.length === 1;
-		for (const character of chunk) {
-			if (character === CTRL_C || character === CTRL_BACKSLASH) {
-				fail(new Interrupted());
-				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 (isKeystroke && (character === "c" || character === "C") && typed === "") {
-				process.stderr.write(copy(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
+				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 (character < " ") continue;
-			typed += character;
-			process.stderr.write(character);
+			if (error.code !== "authorization_pending") throw error;
 		}
-	};
-	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
-	};
+	}
+}
+function toSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 //#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";
-/** The scopes a sign in asks for when it must not be able to change anything. */
-const READ_ONLY_SCOPES = "hardfin:read 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: "read-only",
-			description: "Ask for read access alone, so nothing run with this sign in can change a record",
-			schema: z.boolean()
-		},
-		{
-			name: "scope",
-			description: `The scopes to ask for, separated by spaces, which are ${DEFAULT_SCOPES} when not given`,
-			valueName: "scopes",
-			schema: z.string()
-		},
-		{
-			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 so that nothing can be changed",
-			command: "hardfin login --read-only"
-		},
-		{
-			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;
-	const isReadOnly = input.flags["readOnly"] === true;
-	if (isReadOnly && input.flags["scope"] !== void 0) {
-		writeFailure("invalid_flag", "--read-only and --scope both name the scopes to ask for, so give one of them", input.isJSON);
-		return ExitCode.USAGE;
-	}
-	try {
-		const clientId = settings.clientId;
-		const metadata = await toMetadata(settings.issuerUrl);
-		const scope = isReadOnly ? READ_ONLY_SCOPES : toText(input.flags["scope"] ?? DEFAULT_SCOPES);
-		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
-		const state = toState();
-		const listener = await toListener(WAIT_MS, state);
-		const pkce = toPkce();
-		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);
-		if (input.isJSON) writeEvent({
-			event: "sign_in_url",
-			url,
-			browserOpened: opened,
-			waitSeconds: WAIT_MS / 1e3
-		});
-		else 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: ");
-		let callback;
-		try {
-			callback = await Promise.race([listener.callback, prompt.pasted]);
-		} finally {
-			listener.close();
-			prompt.close();
-		}
-		if (!input.isJSON) process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
-		if (callback.error) {
-			writeFailure("sign_in_failed", `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("sign_in_failed", "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("sign_in_failed", `the browser came back from ${callback.issuer}, which is not ${metadata.issuer}`, input.isJSON);
-			return ExitCode.ERROR;
+//#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, state) {
+	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;
 		}
-		if (!callback.code) {
-			writeFailure("sign_in_failed", "the browser came back without an authorization code", input.isJSON);
-			return ExitCode.ERROR;
+		if (!isOurs(answered, state)) {
+			writePage(response, 400, "Not this sign in", "This page did not come from the sign in your terminal started.");
+			return;
 		}
-		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 || error instanceof SignInStopped) {
-			writeFailure("sign_in_failed", error.message, input.isJSON);
-			return ExitCode.ERROR;
+		writeOutcome(response, answered);
+		settle(answered);
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, HOST, resolve);
+	});
+	const timer = setTimeout(() => {
+		fail(new TimedOut("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);
 		}
-		throw 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("sign_in_failed", `${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);
-	if (input.isJSON) writeEvent({
-		event: "device_code",
-		userCode: device.userCode,
-		verificationUri: device.verificationUri,
-		url,
-		browserOpened: opened,
-		waitSeconds: Math.max(0, Math.round((device.expiresAt - Date.now()) / 1e3))
-	});
-	else process.stderr.write([
-		"",
-		`  Code  ${toPrintable(device.userCode)}`,
-		`  At    ${toPrintable(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);
-	try {
-		return await toSignedIn(input, metadata, await toDeviceTokens(toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted));
-	} finally {
-		prompt.close();
+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
+	};
+}
+/**
+* isOurs answers whether a response belongs to this sign in. A refusal with no state at all
+* is still taken, because not every authorization server sends the state back with one.
+*/
+function isOurs(callback, state) {
+	if (callback.state !== void 0) return callback.state === state;
+	return callback.code === void 0 && callback.error !== void 0;
+}
+function writeOutcome(response, callback) {
+	if (!callback.error) {
+		writePage(response, 200, "Signed in", "You can close this tab and return to your terminal.");
+		return;
 	}
+	writePage(response, 200, "Sign in refused", `${callback.error}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}`);
+}
+/** toEscaped makes text safe to put in a page, because the words of a refusal come from the URL. */
+function toEscaped(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+}
+function writePage(response, status, heading, words) {
+	const title = toEscaped(heading);
+	const detail = toEscaped(words);
+	response.writeHead(status, {
+		"Content-Type": "text/html; charset=utf-8",
+		"Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+		"X-Content-Type-Options": "nosniff"
+	}).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>`);
 }
-/**
-* toDeviceTokens waits for the approval, or for the keyboard. Ctrl-C arrives as an Interrupted
-* and stops quietly. Text followed by Enter means the person typed the code here, where it
-* does nothing, so they are told where it goes instead.
-*/
-async function toDeviceTokens(approved, typed) {
-	return await Promise.race([approved, typed.then(() => {
-		throw new SignInStopped("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
-	})]);
+function close(server, timer) {
+	clearTimeout(timer);
+	server.close();
+	server.closeAllConnections();
 }
-/** toSignedIn stores what a sign in issued, whichever flow issued it. */
-async function toSignedIn(input, metadata, tokens) {
-	const refreshToken = tokens.refreshToken;
-	if (!refreshToken) {
-		writeFailure("sign_in_failed", "the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
-		return ExitCode.ERROR;
-	}
-	const scopes = toGrantedScopes(tokens);
-	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt, scopes));
-	if (input.isJSON) {
-		writeData({
-			signedIn: true,
-			issuer: metadata.issuer,
-			scope: tokens.scope ?? null,
-			scopes: scopes ?? null,
-			canWrite: toCanWrite(scopes),
-			storedIn: backend
-		});
-		return ExitCode.OK;
-	}
-	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
-	writeData([
-		`Signed in to ${metadata.issuer}`,
-		`Scope     ${scopes?.join(" ") ?? tokens.scope ?? "as granted"}`,
-		...toCanWrite(scopes) === false ? ["Access    read-only, so a command that changes a record will be refused"] : [],
-		`Stored in ${stored}`,
-		"",
-		"Run hardfin status to see what this CLI is using",
-		...isInstalled() ? [] : ["Run hardfin completion install to complete commands with Tab"]
-	].join("\n"));
-	return ExitCode.OK;
+//#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"
+	};
 }
-/** writeEvent tells a program what a sign in is waiting on, as one line of JSON on stderr. */
-function writeEvent(event) {
-	process.stderr.write(`${JSON.stringify(event)}\n`);
+/** toState makes the value that ties a callback to the request that started it. */
+function toState() {
+	return toUrlSafe(randomBytes(16));
 }
-/** 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();
+function toUrlSafe(bytes) {
+	return bytes.toString("base64url");
 }
 //#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;
+//#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, copy = spawnSync) {
+	const command = toClipboardCommand();
+	if (!command) return false;
+	const [name, args] = command;
+	const result = copy(name, args, { input: text });
+	return result.error === void 0 && result.status === 0;
 }
 //#endregion
-//#region src/command/operation.ts
+//#region src/auth/prompt.ts
+const CTRL_C = "";
+const CTRL_BACKSLASH = "";
+const BACKSPACE = "";
 /**
-* toEnum takes a value in any case, as the API does, and answers the spelling the document
-* lists, which is what a response always uses.
+* 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 toEnum(values) {
-	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+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
+	};
 }
-const UNSET_FLAG = {
-	name: "unset",
-	description: "A field to clear, named as its flag is, repeatable",
-	valueName: "field",
-	repeatable: true,
-	schema: z.array(z.string())
-};
-const INPUT_FLAG = {
-	name: "input",
-	description: "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
-	valueName: "path",
-	schema: z.string()
-};
-const FILE_FLAG = {
-	name: "file",
-	description: "The file to upload",
-	valueName: "path",
-	schema: z.string()
-};
-const OUTPUT_FLAG = {
-	name: "output",
-	description: "Where to write the file, or - for standard output",
-	valueName: "path",
-	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,
-		...operation.bodyFlags,
-		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
-		...operation.bodyFlags.length > 0 ? [INPUT_FLAG] : [],
-		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
-		...operation.downloads ? [OUTPUT_FLAG] : [],
-		JSON_FLAG
-	];
+/**
+* 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, input = process.stdin, copy = copyToClipboard) {
+	let settle = () => {};
+	let fail = () => {};
+	const pasted = new Promise((resolve, reject) => {
+		settle = resolve;
+		fail = reject;
+	});
+	pasted.catch(() => {});
+	if (!input.isTTY) return {
+		pasted,
+		close: () => {}
+	};
+	let typed = "";
+	const onData = (chunk) => {
+		const isKeystroke = chunk.length === 1;
+		for (const character of chunk) {
+			if (character === CTRL_C || character === CTRL_BACKSLASH) {
+				fail(new Interrupted());
+				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 (isKeystroke && (character === "c" || character === "C") && typed === "") {
+				process.stderr.write(copy(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
+				continue;
+			}
+			if (character < " ") 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 {
-		name: operation.name,
-		summary: operation.summary,
-		description: operation.description ?? operation.summary,
-		arguments: operation.pathParameters,
-		flags,
-		examples: operation.example ? [{
-			description: operation.summary,
-			command: operation.example
-		}] : [],
-		endpoint: {
-			method: operation.method,
-			path: operation.path
-		},
-		run: (input) => runOperation(operation, input)
+		pasted: pasted.finally(close),
+		close
 	};
 }
-async function runOperation(operation, input) {
-	const path = toPath(operation, input.args);
-	if (path === void 0) {
-		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s), each the key of a record`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const given = toGivenBody$1(input.flags["input"]);
-	if (given instanceof InputFailure) {
-		writeFailure("invalid_input", given.message, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0 && !hasPath(given, flag.jsonPath));
-	if (missing.length > 0) {
-		writeFailure("missing_flag", `this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const body = toBody(operation, input.flags, given);
-	if (body instanceof Error) {
-		writeFailure("invalid_flag", body.message, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	if (operation.bodyFlags.length > 0 && body === void 0) {
-		writeFailure("empty_request", `this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	let form;
-	if (operation.upload) {
-		const built = await toForm(operation.upload, input.flags);
-		if (built instanceof Error) {
-			writeFailure("invalid_input", built.message, input.isJSON);
-			return ExitCode.USAGE;
+//#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";
+/** The scopes a sign in asks for when it must not be able to change anything. */
+const READ_ONLY_SCOPES = "hardfin:read 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: "read-only",
+			description: "Ask for read access alone, so nothing run with this sign in can change a record",
+			schema: z.boolean()
+		},
+		{
+			name: "scope",
+			description: `The scopes to ask for, separated by spaces, which are ${DEFAULT_SCOPES} when not given`,
+			valueName: "scopes",
+			schema: z.string()
+		},
+		{
+			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()
 		}
-		form = built;
+	],
+	examples: [
+		{
+			description: "Sign in",
+			command: "hardfin login"
+		},
+		{
+			description: "Sign in so that nothing can be changed",
+			command: "hardfin login --read-only"
+		},
+		{
+			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;
+	const isReadOnly = input.flags["readOnly"] === true;
+	if (isReadOnly && input.flags["scope"] !== void 0) {
+		writeFailure("invalid_flag", "--read-only and --scope both name the scopes to ask for, so give one of them", input.isJSON);
+		return ExitCode.USAGE;
 	}
 	try {
-		const envelope = await request$1({
-			apiUrl: input.resolved.settings.apiUrl,
-			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
-			method: operation.method,
-			path,
-			query: toQuery(operation, input.flags),
-			body,
-			form,
-			downloads: operation.downloads
+		const clientId = settings.clientId;
+		const metadata = await toMetadata(settings.issuerUrl);
+		const scope = isReadOnly ? READ_ONLY_SCOPES : toText(input.flags["scope"] ?? DEFAULT_SCOPES);
+		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
+		const state = toState();
+		const listener = await toListener(WAIT_MS, state);
+		const pkce = toPkce();
+		const url = toAuthorizationUrl(metadata.authorization_endpoint, {
+			clientId,
+			redirectUri: listener.redirectUri,
+			scope,
+			state,
+			challenge: pkce.challenge
 		});
-		if (operation.downloads) return toWritten(envelope.data, input);
-		writeData(envelope.data);
-		return ExitCode.OK;
-	} catch (error) {
-		if (error instanceof NoCredential) {
-			writeFailure("not_signed_in", error.message, input.isJSON);
-			return ExitCode.NOT_AUTHENTICATED;
+		const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
+		if (input.isJSON) writeEvent({
+			event: "sign_in_url",
+			url,
+			browserOpened: opened,
+			waitSeconds: WAIT_MS / 1e3
+		});
+		else 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: ");
+		let callback;
+		try {
+			callback = await Promise.race([listener.callback, prompt.pasted]);
+		} finally {
+			listener.close();
+			prompt.close();
 		}
-		if (error instanceof RequestFailure) {
-			writeFailure(toRequestCode(error), error.message, input.isJSON, error.errors, error.requestId, error.status);
-			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		if (!input.isJSON) process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
+		if (callback.error) {
+			writeFailure("sign_in_failed", `sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
+			return ExitCode.ERROR;
 		}
-		throw error;
-	}
-}
-/**
-* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
-* because a person would otherwise have their session filled with a file's bytes.
-*/
-function toWritten(download, input) {
-	const asked = input.flags["output"];
-	const offered = typeof asked === "string" ? void 0 : download.fileName;
-	const path = typeof asked === "string" ? asked : offered === void 0 ? "-" : toLocalName(offered);
-	if (path === void 0 || offered !== void 0 && existsSync(path)) {
-		writeFailure("output_required", path === void 0 ? `this file is offered as ${JSON.stringify(offered)}, which is not a name to write here, so name where to write it with --output` : `${path} already exists, so name where to write this file with --output`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	if (path === "-") {
-		if (process.stdout.isTTY) {
-			writeFailure("output_required", "this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
-			return ExitCode.USAGE;
+		if (callback.source === "listener" ? callback.state !== state : callback.state !== void 0 && callback.state !== state) {
+			writeFailure("sign_in_failed", "the browser came back with a state this sign in did not send", input.isJSON);
+			return ExitCode.ERROR;
 		}
-		process.stdout.write(download.bytes);
-		return ExitCode.OK;
-	}
-	writeFileSync(path, download.bytes);
-	writeData({
-		written: path,
-		bytes: download.bytes.length,
-		contentType: download.contentType
-	});
-	return ExitCode.OK;
-}
-/** toLocalName reduces a name the API offered to one file in the working directory, or to nothing. */
-function toLocalName(offered) {
-	const name = offered.split(/[\\/]/).pop() ?? "";
-	return name === "" || name.startsWith(".") ? void 0 : name;
-}
-/** The arguments a URL reads as "this folder" and "the one above", and one that names nothing. */
-const NOT_A_KEY = /* @__PURE__ */ new Set([
-	"",
-	".",
-	".."
-]);
-/** toPath fills the path template from the positional arguments, in order. */
-function toPath(operation, args) {
-	if (args.length !== operation.pathParameters.length || args.some((argument) => NOT_A_KEY.has(argument))) 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;
-		const parsed = flag.schema.safeParse(value);
-		const carried = parsed.success ? parsed.data : value;
-		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(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());
-}
-/** toForm builds the file part and its fields, which an upload endpoint takes. */
-async function toForm(upload, flags) {
-	const path = flags["file"];
-	if (typeof path !== "string") return /* @__PURE__ */ new Error("this command needs --file, the file to upload");
-	const form = new FormData();
-	try {
-		form.append(upload.filePart, await openAsBlob(path), basename(path));
-	} catch {
-		return /* @__PURE__ */ new Error(`${path} cannot be read`);
-	}
-	for (const field of upload.fields) {
-		const value = flags[toOptionKey(field.name)];
-		if (value !== void 0) {
-			const parsed = field.schema.safeParse(value);
-			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
+		if (callback.issuer !== void 0 && callback.issuer.replace(/\/+$/, "") !== metadata.issuer.replace(/\/+$/, "")) {
+			writeFailure("sign_in_failed", `the browser came back from ${callback.issuer}, which is not ${metadata.issuer}`, input.isJSON);
+			return ExitCode.ERROR;
+		}
+		if (!callback.code) {
+			writeFailure("sign_in_failed", "the browser came back without an authorization code", input.isJSON);
+			return ExitCode.ERROR;
 		}
-	}
-	return form;
-}
-/** toGivenBody reads the --input body, which a generated command takes only as a JSON object. */
-function toGivenBody$1(source) {
-	if (typeof source !== "string") return;
-	const read = toJSONInput(source);
-	if (read instanceof InputFailure) return read;
-	if (typeof read !== "object" || read === null || Array.isArray(read)) return new InputFailure(`the body in ${source === "-" ? "standard input" : source} must be a JSON object, such as {"name": "Acme"}`);
-	return read;
-}
-/** hasPath reports whether a body already holds a value at a field's path. */
-function hasPath(body, path) {
-	let holder = body;
-	for (const name of path) {
-		if (typeof holder !== "object" || holder === null || !(name in holder)) return false;
-		holder = holder[name];
-	}
-	return true;
-}
-/** toBody builds the request body from the --input body and the flags, a flag winning over its field. */
-function toBody(operation, flags, given) {
-	const body = given ? structuredClone(given) : {};
-	let hasField = given !== void 0;
-	for (const flag of operation.bodyFlags) {
-		const value = flags[toOptionKey(flag.name)];
-		if (value === void 0) continue;
-		if (flag.element) {
-			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
-			if (elements instanceof Error) return elements;
-			set(body, flag.jsonPath, elements);
-			hasField = true;
-			continue;
+		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 || error instanceof SignInStopped) {
+			writeFailure("sign_in_failed", error.message, input.isJSON);
+			return ExitCode.ERROR;
 		}
-		const parsed = flag.schema.safeParse(value);
-		set(body, flag.jsonPath, parsed.success ? parsed.data : value);
-		hasField = true;
+		throw error;
 	}
-	const cleared = toCleared(operation, flags, body);
-	if (cleared instanceof Error) return cleared;
-	return hasField || cleared ? body : void 0;
 }
-/** toCleared sends null for each field named by --unset, which is how a field is cleared. */
-function toCleared(operation, flags, body) {
-	const named = flags["unset"];
-	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
-	for (const name of names) {
-		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
-		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
-		if (!flag.nullable) return /* @__PURE__ */ new Error(`--${flag.name} cannot be cleared, because the API does not accept null for it`);
-		set(body, flag.jsonPath, null);
+/** 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("sign_in_failed", `${metadata.issuer} does not offer the device grant, so sign in without --device`, input.isJSON);
+		return ExitCode.ERROR;
 	}
-	return names.length > 0;
-}
-/** toElements reads the key=value pairs a repeated flag carries for one array element. */
-function toElements(flag, values) {
-	const elements = [];
-	for (const value of values) {
-		const element = {};
-		for (const pair of value.split(",")) {
-			const split = pair.indexOf("=");
-			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ") ?? ""}=, such as --${flag.name} ${flag.element?.[0] ?? "field"}=value. A value cannot contain a comma`);
-			const isJSON = pair[split - 1] === ":";
-			const key = pair.slice(0, isJSON ? split - 1 : split).trim();
-			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
-			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
-			const value = pair.slice(split + 1).trim();
-			if (flag.elementUuids?.includes(key) && !z.uuid().safeParse(value).success) return /* @__PURE__ */ new Error(`--${flag.name} needs a UUID for ${key}, such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90, and ${value || "nothing"} is not one`);
-			const types = flag.elementTypes?.[key];
-			const typed = isJSON ? toJSONValue(value, types ?? ["string"]) : toTyped(value, types);
-			if (typed === NOT_TAKEN) return /* @__PURE__ */ new Error(`--${flag.name} needs ${toNamedTypes(types ?? ["string"])} for ${key}, and ${value || "nothing"} is not one`);
-			element[key] = typed;
-		}
-		elements.push(element);
+	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);
+	if (input.isJSON) writeEvent({
+		event: "device_code",
+		userCode: device.userCode,
+		verificationUri: device.verificationUri,
+		url,
+		browserOpened: opened,
+		waitSeconds: Math.max(0, Math.round((device.expiresAt - Date.now()) / 1e3))
+	});
+	else process.stderr.write([
+		"",
+		`  Code  ${toPrintable(device.userCode)}`,
+		`  At    ${toPrintable(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);
+	try {
+		return await toSignedIn(input, metadata, await toDeviceTokens(toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted));
+	} finally {
+		prompt.close();
 	}
-	return elements;
 }
-/** Marks text that is none of the types a field takes. */
-const NOT_TAKEN = Symbol("not taken");
-const NUMBER = /^-?\d+(\.\d+)?$/;
 /**
-* toTyped reads the text after key= as the type the document gives the field. A field that
-* takes text is sent as typed, whatever it looks like, because 36 may be a serial number. A
-* field that takes no text has only one reading, so order=2 is sent as the number.
+* toDeviceTokens waits for the approval, or for the keyboard. Ctrl-C arrives as an Interrupted
+* and stops quietly. Text followed by Enter means the person typed the code here, where it
+* does nothing, so they are told where it goes instead.
 */
-function toTyped(text, types) {
-	if (types === void 0 || types.includes("string")) return text;
-	if (types.includes("null") && text === "null") return null;
-	if ((types.includes("integer") || types.includes("number")) && NUMBER.test(text)) {
-		const value = Number(text);
-		if (types.includes("number") || Number.isInteger(value)) return value;
-	}
-	if (types.includes("boolean") && (text === "true" || text === "false")) return text === "true";
-	return NOT_TAKEN;
+async function toDeviceTokens(approved, typed) {
+	return await Promise.race([approved, typed.then(() => {
+		throw new SignInStopped("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
+	})]);
 }
-/**
-* toJSONValue reads the text after key:= as JSON, and takes it when the field takes its type.
-* It is how a custom field is given the number 36 or true, where key= would send the text.
-*/
-function toJSONValue(text, types) {
-	let value;
-	try {
-		value = JSON.parse(text);
-	} catch {
-		return NOT_TAKEN;
+/** toSignedIn stores what a sign in issued, whichever flow issued it. */
+async function toSignedIn(input, metadata, tokens) {
+	const refreshToken = tokens.refreshToken;
+	if (!refreshToken) {
+		writeFailure("sign_in_failed", "the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
+		return ExitCode.ERROR;
 	}
-	const type = value === null ? "null" : typeof value;
-	return (types.includes(type) || type === "number" && types.includes("integer") && Number.isInteger(value)) && type !== "object" ? value : NOT_TAKEN;
+	const scopes = toGrantedScopes(tokens);
+	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt, scopes));
+	if (input.isJSON) {
+		writeData({
+			signedIn: true,
+			issuer: metadata.issuer,
+			scope: tokens.scope ?? null,
+			scopes: scopes ?? null,
+			canWrite: toCanWrite(scopes),
+			storedIn: backend
+		});
+		return ExitCode.OK;
+	}
+	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
+	writeData([
+		`Signed in to ${metadata.issuer}`,
+		`Scope     ${scopes?.join(" ") ?? tokens.scope ?? "as granted"}`,
+		...toCanWrite(scopes) === false ? ["Access    read-only, so a command that changes a record will be refused"] : [],
+		`Stored in ${stored}`,
+		"",
+		"Run hardfin status to see what this CLI is using",
+		...isInstalled() ? [] : ["Run hardfin completion install to complete commands with Tab"]
+	].join("\n"));
+	return ExitCode.OK;
 }
-/** toNamedTypes says in words what a field takes, for the message that refuses a value. */
-function toNamedTypes(types) {
-	const named = {
-		integer: "a whole number",
-		number: "a number",
-		boolean: "true or false",
-		string: "text in quotes",
-		null: "null"
-	};
-	return types.filter((type) => type in named).map((type) => named[type]).join(" or ");
+/** writeEvent tells a program what a sign in is waiting on, as one line of JSON on stderr. */
+function writeEvent(event) {
+	process.stderr.write(`${JSON.stringify(event)}\n`);
 }
-/** set writes a value at its path, building the objects a nested field needs. */
-function set(body, path, value) {
-	let holder = body;
-	for (const name of path.slice(0, -1)) {
-		holder[name] = holder[name] ?? {};
-		holder = holder[name];
+/** 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;
 	}
-	holder[path[path.length - 1] ?? ""] = value;
+	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/mcp/confine.ts
@@ -4686,6 +4813,7 @@ const commands = [
 							jsonPath: ["depreciationModel"],
 							description: "The method one unit is depreciated by, or null to clear it",
 							valueName: "value",
+							nullable: true,
 							schema: toEnum([
 								"DOUBLE_DECLINING",
 								"STRAIGHT_LINE",
@@ -5051,6 +5179,7 @@ const commands = [
 								jsonPath: ["depreciationModel"],
 								description: "The method one unit is depreciated by, or null to clear it",
 								valueName: "value",
+								nullable: true,
 								schema: toEnum([
 									"DOUBLE_DECLINING",
 									"STRAIGHT_LINE",
@@ -6427,6 +6556,7 @@ const commands = [
 								jsonPath: ["depreciationModel"],
 								description: "The method one unit is depreciated by, or null to clear it",
 								valueName: "value",
+								nullable: true,
 								schema: toEnum([
 									"DOUBLE_DECLINING",
 									"STRAIGHT_LINE",
@@ -6860,6 +6990,7 @@ const commands = [
 							jsonPath: ["type"],
 							description: "SITE for a site, or ZONE for a zone within a site",
 							valueName: "value",
+							nullable: true,
 							schema: toEnum([
 								"SITE",
 								"UNKNOWN",
@@ -7020,6 +7151,7 @@ const commands = [
 							jsonPath: ["type"],
 							description: "SITE for a site, or ZONE for a zone within a site",
 							valueName: "value",
+							nullable: true,
 							schema: toEnum([
 								"SITE",
 								"UNKNOWN",
@@ -7160,7 +7292,9 @@ 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)}`;
+		const given = toNullOrText(value, flag.nullable === true);
+		if (given === null) continue;
+		if (!flag.schema.safeParse(given).success) return `--${flag.name} does not accept ${JSON.stringify(value)}`;
 	}
 }
 //#endregion
@@ -7247,5 +7381,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-CI4W2agw.js.map
-//# debugId=cb5319cf-733c-5f06-b5d8-f8f154bf4267
+//# sourceMappingURL=program-C2DP0mVy.js.map
+//# debugId=b26e6779-10c9-5732-b40c-04e75265338c