@hardfin/cli 0.0.2-dev.3 → 0.0.2-dev.6

package/dist/cli.js

@@ -0,0 +1,1552 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+//#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";
+const DEFAULT_API_URL = "https://api.hardfin.com/v2";
+/** toApiUrl picks the API this invocation talks to. */
+function toApiUrl(override) {
+	return (override ?? process.env["HARDFIN_API_URL"] ?? DEFAULT_API_URL).replace(/\/+$/, "");
+}
+/** toApiKey reads the API key an unattended caller set. */
+function toApiKey() {
+	return process.env["HARDFIN_API_KEY"] || void 0;
+}
+//#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 = 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));
+	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/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 = {
+		"X-API-Key": options.apiKey,
+		"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 apiKey = toApiKey();
+	if (!apiKey) {
+		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
+		return ExitCode.NOT_AUTHENTICATED;
+	}
+	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: toApiUrl(),
+			apiKey,
+			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			path,
+			query,
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		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/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 apiKey = toApiKey();
+	if (!apiKey) {
+		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
+		return ExitCode.NOT_AUTHENTICATED;
+	}
+	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: toApiUrl(),
+			apiKey,
+			method: operation.method,
+			path,
+			query: toQuery(operation, input.flags),
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		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/commands.ts
+/** commands is every command the CLI offers, and drives help and the agent guide. */
+const commands = [
+	...[
+		{
+			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
+				}),
+				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: "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: "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: "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: "Present, with any value or none, when the file should download as an attachment rather than open inline",
+					valueName: "value",
+					schema: z.string()
+				}],
+				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
+				})
+			]
+		}
+	],
+	apiCommand,
+	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, "-v, --version").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 {
+		return await command.run?.({
+			args,
+			flags,
+			isJSON,
+			commands
+		}) ?? ExitCode.OK;
+	} catch (error) {
+		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
+		return 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 {};