@hardfin/cli 0.1.1-dev.69 → 0.1.1-dev.70

package/README.md

@@ -199,9 +199,10 @@ A field the API does not take null for is sent the word as text. The same holds
 hardfin asset accounting update ast_4f9xk2mq7plr8stz --unset useful-life
 ```
 
-Three things fail locally with exit code 2, before any request is made: a value outside an
-enum, a required field that is missing, and `--unset` on a field the API will not take null
-for.
+Four things fail locally with exit code 2, before any request is made: a value outside an
+enum, a required field that is missing, a list element missing a field every element needs,
+and `--unset` on a field the API will not take null for. `--help` starts a required flag's
+description with `Required.`, and names the fields every element of a repeated flag needs.
 
 ### When a command fails
 
@@ -277,16 +278,17 @@ hardfin agent-guide --json customer create | jq -r '.commands[0].flags[] | selec
 The JSON holds `cli`, `apiVersion`, `exitCodes`, `errorCodes`, `globalFlags` and `commands`.
 Each command names its `path`, its `endpoint`, whether it `runs`, and its flags.
 
-| A flag's     | Holds                                                                       |
-| ------------ | --------------------------------------------------------------------------- |
-| `required`   | Present when the command fails without it                                   |
-| `schema`     | The `type`, and the `enum`, `format`, `minimum` or `maximum` that narrow it |
-| `sends`      | The query parameter, or the path of the body field, the value goes to       |
-| `clearable`  | Present when `--unset` can clear the field                                  |
-| `repeatable` | Present when the flag is given once per value                               |
-| `negatable`  | Present when a boolean also takes a `--no-` form                            |
-| `element`    | The fields one value carries as `key=value`, for an array of objects        |
-| `default`    | The value used when the flag is not given                                   |
+| A flag's          | Holds                                                                       |
+| ----------------- | --------------------------------------------------------------------------- |
+| `required`        | Present when the command fails without it                                   |
+| `schema`          | The `type`, and the `enum`, `format`, `minimum` or `maximum` that narrow it |
+| `sends`           | The query parameter, or the path of the body field, the value goes to       |
+| `clearable`       | Present when `--unset` can clear the field                                  |
+| `repeatable`      | Present when the flag is given once per value                               |
+| `negatable`       | Present when a boolean also takes a `--no-` form                            |
+| `element`         | The fields one value carries as `key=value`, for an array of objects        |
+| `elementRequired` | The fields of `element` every value must carry                              |
+| `default`         | The value used when the flag is not given                                   |
 
 A part that is absent means no. The description is read from the same declarations the parser
 enforces, so it cannot say one thing while the command does another.

package/dist/{check-CDkHR_Qt.js → check-wgnggJ45.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]="e9a5da76-6485-5cc1-9d09-55076e5c9b22")}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]="9d637f5e-0cda-5582-80ff-432edc41bf8c")}catch(e){}}();
 import { createRequire } from "node:module";
 import { z } from "zod";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -8,79 +8,6 @@ import { dirname, join, resolve, sep } from "node:path";
 import { parseEnv } from "node:util";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
-//#region src/output/writer.ts
-/**
-* toText reads a value a caller supplied, which arrives typed as unknown. An object would
-* otherwise reach a request as the text "[object Object]".
-*/
-function toText(value) {
-	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
-	if (value === void 0 || value === null) return "";
-	return JSON.stringify(value);
-}
-/** Every control character but a newline and a tab, which are the two a line of text needs. */
-const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
-/**
-* toPrintable makes text safe to show at a terminal. A name or a message from the API can
-* hold an escape sequence, which a terminal would act on. Each such character is written
-* as its code, so the text reads as what it holds.
-*/
-function toPrintable(text) {
-	return text.replace(CONTROL, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
-}
-/**
-* toJSON writes a value for whoever is reading the stream. A person at a terminal gets it
-* indented. A program gets it on one line, because the indentation of a page of records is
-* close to half of what an agent would otherwise have to read.
-*/
-function toJSON(value, stream) {
-	return stream.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value);
-}
-/** writeData prints a command's result on stdout. */
-function writeData(value) {
-	if (typeof value === "string") {
-		const text = toPrintable(value);
-		process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
-		return;
-	}
-	process.stdout.write(`${toJSON(value ?? null, process.stdout)}\n`);
-}
-/** The code of the last failure written, which decides whether the CLI checks for an update. */
-let lastFailureCode;
-/** toLastFailureCode answers the code of the last failure this run wrote. */
-function toLastFailureCode() {
-	return lastFailureCode;
-}
-/** writeFailure prints why a command failed on stderr, with a code only a machine reading JSON sees. */
-function writeFailure(code, message, isJSON, errors, requestId, status) {
-	lastFailureCode = code;
-	if (!isJSON) {
-		process.stderr.write(`error: ${toPrintable(message)}${status === void 0 ? "" : ` (HTTP ${status})`}\n`);
-		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${toPrintable(entry.error)} (${entry.statusCode})\n`);
-		if (requestId) process.stderr.write(`  request ${toPrintable(requestId)}\n`);
-		return;
-	}
-	const payload = {
-		code,
-		message,
-		errors: errors ?? [{
-			error: message,
-			statusCode: 0
-		}],
-		requestId: requestId ?? null,
-		status: status ?? null
-	};
-	process.stderr.write(`${toJSON(payload, process.stderr)}\n`);
-}
-/** isJSONOutput decides whether this invocation prints machine-readable output. */
-function isJSONOutput(flags) {
-	if (flags["json"] === true) return true;
-	return !process.stdout.isTTY;
-}
-/** version is what this build reports, read from the published package manifest. */
-const version$1 = createRequire(import.meta.url)("../package.json").version;
-//#endregion
 //#region src/report/expected.ts
 /**
 * ExpectedFailure is a failure the CLI anticipated: the person's input, their network, their
@@ -112,6 +39,8 @@ var TimedOut = class extends ExpectedFailure {
 		this.name = "TimedOut";
 	}
 };
+/** version is what this build reports, read from the published package manifest. */
+const version$1 = createRequire(import.meta.url)("../package.json").version;
 /** The values that mean no, for a variable that turns something on or off. */
 const OFF = /* @__PURE__ */ new Set([
 	"0",
@@ -304,6 +233,77 @@ function toOrigin(apiUrl) {
 	}
 }
 //#endregion
+//#region src/output/writer.ts
+/**
+* toText reads a value a caller supplied, which arrives typed as unknown. An object would
+* otherwise reach a request as the text "[object Object]".
+*/
+function toText(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (value === void 0 || value === null) return "";
+	return JSON.stringify(value);
+}
+/** Every control character but a newline and a tab, which are the two a line of text needs. */
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+/**
+* toPrintable makes text safe to show at a terminal. A name or a message from the API can
+* hold an escape sequence, which a terminal would act on. Each such character is written
+* as its code, so the text reads as what it holds.
+*/
+function toPrintable(text) {
+	return text.replace(CONTROL, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/**
+* toJSON writes a value for whoever is reading the stream. A person at a terminal gets it
+* indented. A program gets it on one line, because the indentation of a page of records is
+* close to half of what an agent would otherwise have to read.
+*/
+function toJSON(value, stream) {
+	return stream.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+/** writeData prints a command's result on stdout. */
+function writeData(value) {
+	if (typeof value === "string") {
+		const text = toPrintable(value);
+		process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+		return;
+	}
+	process.stdout.write(`${toJSON(value ?? null, process.stdout)}\n`);
+}
+/** The code of the last failure written, which decides whether the CLI checks for an update. */
+let lastFailureCode;
+/** toLastFailureCode answers the code of the last failure this run wrote. */
+function toLastFailureCode() {
+	return lastFailureCode;
+}
+/** writeFailure prints why a command failed on stderr, with a code only a machine reading JSON sees. */
+function writeFailure(code, message, isJSON, errors, requestId, status) {
+	lastFailureCode = code;
+	if (!isJSON) {
+		process.stderr.write(`error: ${toPrintable(message)}${status === void 0 ? "" : ` (HTTP ${status})`}\n`);
+		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${toPrintable(entry.error)} (${entry.statusCode})\n`);
+		if (requestId) process.stderr.write(`  request ${toPrintable(requestId)}\n`);
+		return;
+	}
+	const payload = {
+		code,
+		message,
+		errors: errors ?? [{
+			error: message,
+			statusCode: 0
+		}],
+		requestId: requestId ?? null,
+		status: status ?? null
+	};
+	process.stderr.write(`${toJSON(payload, process.stderr)}\n`);
+}
+/** isJSONOutput decides whether this invocation prints machine-readable output. */
+function isJSONOutput(flags) {
+	if (flags["json"] === true) return true;
+	return !process.stdout.isTTY;
+}
+//#endregion
 //#region src/system/state.ts
 /** toStateDirectory names the folder the CLI keeps what it remembers between runs in. */
 function toStateDirectory() {
@@ -494,7 +494,7 @@ function writeCache(cache) {
 	} catch {}
 }
 //#endregion
-export { toPrintable as C, writeFailure as E, toLastFailureCode as S, writeData as T, LockHeld as _, isShipped as a, isJSONOutput as b, toOutdatedTo as c, CONFIG_FILE as d, ConfigFailure as f, Interrupted as g, ExpectedFailure as h, toUpdateCheckRefusal as i, toStateDirectory as l, toTelemetry as m, isReminderDue as n, toPackageDirectory as o, toSettings as p, toCheck as r, noteNotices as s, PACKAGE as t, API_VERSION as u, TimedOut as v, toText as w, toJSON as x, version$1 as y };
+export { ExpectedFailure as C, TimedOut as E, version$1 as S, LockHeld as T, API_VERSION as _, isShipped as a, toSettings as b, toOutdatedTo as c, toJSON as d, toLastFailureCode as f, writeFailure as g, writeData as h, toUpdateCheckRefusal as i, toStateDirectory as l, toText as m, isReminderDue as n, toPackageDirectory as o, toPrintable as p, toCheck as r, noteNotices as s, PACKAGE as t, isJSONOutput as u, CONFIG_FILE as v, Interrupted as w, toTelemetry as x, ConfigFailure as y };
 
-//# sourceMappingURL=check-CDkHR_Qt.js.map
-//# debugId=e9a5da76-6485-5cc1-9d09-55076e5c9b22
+//# sourceMappingURL=check-wgnggJ45.js.map
+//# debugId=9d637f5e-0cda-5582-80ff-432edc41bf8c

package/dist/cli.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]="6ad4927e-4221-5401-ac3e-392b1fcb2a19")}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]="e43cc9b0-2707-553a-973d-9a707e329000")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,8 +14,8 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-eT-hgKX0.js");
-		const { startUpdateCheck, writeUpdateNotice } = await import("./notice-Bq9ifPV6.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CYp6XF8D.js");
+		const { startUpdateCheck, writeUpdateNotice } = await import("./notice-CQ5Nlp80.js");
 		const pending = startUpdateCheck(process.argv.slice(2));
 		try {
 			await toCli().parseAsync(process.argv);
@@ -36,7 +36,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported, writeCrash } = await import("./program-eT-hgKX0.js");
+		const { toReported, writeCrash } = await import("./program-CYp6XF8D.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -57,4 +57,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=6ad4927e-4221-5401-ac3e-392b1fcb2a19
+//# debugId=e43cc9b0-2707-553a-973d-9a707e329000

package/dist/{notice-Bq9ifPV6.js → notice-CQ5Nlp80.js}

@@ -1,7 +1,7 @@
 #!/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]="85e43a08-810a-5f4e-9d70-a869c9a65ee1")}catch(e){}}();
-import { S as toLastFailureCode, c as toOutdatedTo, i as toUpdateCheckRefusal, n as isReminderDue, o as toPackageDirectory, r as toCheck, t as PACKAGE, u as API_VERSION, x as toJSON } from "./check-CDkHR_Qt.js";
+!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]="46b26b33-c4ba-5ddd-9436-b5f91120d1da")}catch(e){}}();
+import { _ as API_VERSION, c as toOutdatedTo, d as toJSON, f as toLastFailureCode, i as toUpdateCheckRefusal, n as isReminderDue, o as toPackageDirectory, r as toCheck, t as PACKAGE } from "./check-wgnggJ45.js";
 //#region src/update/notice.ts
 /**
 * The failures a newer CLI may not have, because each can mean the API changed under this one:
@@ -130,5 +130,5 @@ function toCommandName(args) {
 //#endregion
 export { startUpdateCheck, writeUpdateNotice };
 
-//# sourceMappingURL=notice-Bq9ifPV6.js.map
-//# debugId=85e43a08-810a-5f4e-9d70-a869c9a65ee1
+//# sourceMappingURL=notice-CQ5Nlp80.js.map
+//# debugId=46b26b33-c4ba-5ddd-9436-b5f91120d1da

package/dist/{program-eT-hgKX0.js → program-CYp6XF8D.js}

@@ -1,8 +1,8 @@
 #!/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]="ef42eac6-02c0-5ed0-ad0b-c3d60bfb51f8")}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]="2061590a-8bec-56a7-864d-cb1435ccb994")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.js";
-import { C as toPrintable, E as writeFailure, T as writeData, _ as LockHeld, a as isShipped, b as isJSONOutput, d as CONFIG_FILE, f as ConfigFailure, g as Interrupted, h as ExpectedFailure, i as toUpdateCheckRefusal, l as toStateDirectory, m as toTelemetry, o as toPackageDirectory, p as toSettings, r as toCheck, s as noteNotices, t as PACKAGE, u as API_VERSION, v as TimedOut, w as toText, y as version$1 } from "./check-CDkHR_Qt.js";
+import { C as ExpectedFailure, E as TimedOut, S as version$1, T as LockHeld, _ as API_VERSION, a as isShipped, b as toSettings, g as writeFailure, h as writeData, i as toUpdateCheckRefusal, l as toStateDirectory, m as toText, o as toPackageDirectory, p as toPrintable, r as toCheck, s as noteNotices, t as PACKAGE, u as isJSONOutput, v as CONFIG_FILE, w as Interrupted, x as toTelemetry, y as ConfigFailure } from "./check-wgnggJ45.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
 import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
@@ -15,77 +15,6 @@ import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
 import { createInterface as createInterface$1 } from "node:readline";
-//#region src/cli/parser.ts
-/** toParser builds the parser from the registry, and hands whatever it parses to onRun. */
-function toParser(entries, onRun, isSilent = false) {
-	const program = new Command();
-	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").enablePositionalOptions();
-	toQuietParser(program, isSilent);
-	for (const flag of GLOBAL_FLAGS) program.option(`--${flag.name} <${flag.valueName}>`, flag.description);
-	for (const command of entries) program.addCommand(toProgram(program, command, onRun, isSilent), { hidden: command.hidden });
-	return program;
-}
-/** toProgram wires one registry command into the parser. */
-function toProgram(root, command, onRun, isSilent) {
-	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
-	toQuietParser(program, isSilent);
-	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.negatable) program.addOption(new Option(`--no-${flag.name}`, `${flag.description}, turned off`));
-		if (flag.repeatable) option.argParser(collect);
-		if (!flag.repeatable && flag.valueName) option.argParser(toOnce(flag.name));
-		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(root, subcommand, onRun, isSilent), { hidden: subcommand.hidden });
-	if (!command.run) return program;
-	program.action((...parsed) => {
-		const flags = parsed[parsed.length - 2] ?? {};
-		return onRun({
-			command,
-			args: parsed.slice(0, parsed.length - 2).flatMap(toArgumentList),
-			flags,
-			globals: root.opts()
-		});
-	});
-	return program;
-}
-/**
-* toQuietParser has the parser hand back its mistakes, so they are answered like any other
-* failure. A silent parser also keeps its help and version to itself, for a caller that only
-* wants to know what a command line means.
-*/
-function toQuietParser(program, isSilent) {
-	program.exitOverride().configureOutput({ outputError: () => void 0 });
-	if (isSilent) program.configureOutput({
-		writeOut: () => void 0,
-		writeErr: () => void 0
-	});
-}
-function toArgumentList(value) {
-	if (Array.isArray(value)) return value.map(String);
-	return value === void 0 ? [] : [toText(value)];
-}
-/** toOnce refuses a flag given a second time. */
-function toOnce(name) {
-	let isGiven = false;
-	return (value) => {
-		if (isGiven) throw new InvalidArgumentError(`--${name} takes one value and is given more than once`);
-		isGiven = true;
-		return value;
-	};
-}
-function collect(value, previous) {
-	return [...previous ?? [], value];
-}
-//#endregion
 //#region src/auth/jwt.ts
 /**
 * toClaims reads an access token's payload for display. Nothing here verifies the
@@ -1137,7 +1066,10 @@ function toCommandLines(command, parents) {
 function toTaken(flag) {
 	const values = flag.schema.enum ?? flag.schema.items?.enum;
 	if (values) return `one of ${values.map((value) => `\`${value}\``).join(", ")}`;
-	if (flag.element) return flag.element.map((field) => `${field}=`).join(",");
+	if (flag.element) {
+		const taken = flag.element.map((field) => `${field}=`).join(",");
+		return flag.elementRequired ? `${taken}, each needing ${flag.elementRequired.map((field) => `${field}=`).join(",")}` : taken;
+	}
 	return flag.valueName ?? "nothing";
 }
 async function runAgentGuide(input) {
@@ -1191,6 +1123,7 @@ function toDescribed(flag) {
 		elementMoney: sent.elementMoney,
 		elementEnums: sent.elementEnums,
 		elementPatterns: sent.elementPatterns,
+		elementRequired: sent.elementRequired,
 		together: sent.together
 	};
 	return Object.fromEntries(Object.entries(described).filter(([, value]) => value !== void 0 && value !== false));
@@ -1247,6 +1180,84 @@ function toSummary(command, parents) {
 	};
 }
 //#endregion
+//#region src/cli/parser.ts
+/** toParser builds the parser from the registry, and hands whatever it parses to onRun. */
+function toParser(entries, onRun, isSilent = false) {
+	const program = new Command();
+	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").enablePositionalOptions();
+	toQuietParser(program, isSilent);
+	for (const flag of GLOBAL_FLAGS) program.option(`--${flag.name} <${flag.valueName}>`, flag.description);
+	for (const command of entries) program.addCommand(toProgram(program, command, onRun, isSilent), { hidden: command.hidden });
+	return program;
+}
+/** toHelpDescription says in help whether a flag, or each element it carries, must be given. */
+function toHelpDescription(flag) {
+	const described = toDescribed(flag);
+	const required = described.required ? `Required. ${flag.description}` : flag.description;
+	if (!described.elementRequired) return required;
+	return `${required}. Each one needs ${described.elementRequired.map((field) => `${field}=`).join(", ")}`;
+}
+/** toProgram wires one registry command into the parser. */
+function toProgram(root, command, onRun, isSilent) {
+	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
+	toQuietParser(program, isSilent);
+	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}`, toHelpDescription(flag));
+		if (flag.negatable) program.addOption(new Option(`--no-${flag.name}`, `${flag.description}, turned off`));
+		if (flag.repeatable) option.argParser(collect);
+		if (!flag.repeatable && flag.valueName) option.argParser(toOnce(flag.name));
+		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(root, subcommand, onRun, isSilent), { hidden: subcommand.hidden });
+	if (!command.run) return program;
+	program.action((...parsed) => {
+		const flags = parsed[parsed.length - 2] ?? {};
+		return onRun({
+			command,
+			args: parsed.slice(0, parsed.length - 2).flatMap(toArgumentList),
+			flags,
+			globals: root.opts()
+		});
+	});
+	return program;
+}
+/**
+* toQuietParser has the parser hand back its mistakes, so they are answered like any other
+* failure. A silent parser also keeps its help and version to itself, for a caller that only
+* wants to know what a command line means.
+*/
+function toQuietParser(program, isSilent) {
+	program.exitOverride().configureOutput({ outputError: () => void 0 });
+	if (isSilent) program.configureOutput({
+		writeOut: () => void 0,
+		writeErr: () => void 0
+	});
+}
+function toArgumentList(value) {
+	if (Array.isArray(value)) return value.map(String);
+	return value === void 0 ? [] : [toText(value)];
+}
+/** toOnce refuses a flag given a second time. */
+function toOnce(name) {
+	let isGiven = false;
+	return (value) => {
+		if (isGiven) throw new InvalidArgumentError(`--${name} takes one value and is given more than once`);
+		isGiven = true;
+		return value;
+	};
+}
+function collect(value, previous) {
+	return [...previous ?? [], value];
+}
+//#endregion
 //#region src/command/input.ts
 /** InputFailure is a body given with --input that cannot be used, and says why. */
 var InputFailure = class extends Error {
@@ -1421,6 +1432,11 @@ async function runOperation(operation, input) {
 		writeFailure("invalid_flag", built.message, input.isJSON);
 		return ExitCode.USAGE;
 	}
+	const missingElementField = toMissingElementField(operation, built);
+	if (missingElementField) {
+		writeFailure("missing_flag", missingElementField, input.isJSON);
+		return ExitCode.USAGE;
+	}
 	const isBareAction = operation.method === "POST" && operation.pathParameters.length > 0 && !operation.upload;
 	const body = built === void 0 && isBareAction && operation.bodyFlags.length > 0 ? {} : built;
 	if (operation.bodyFlags.length > 0 && body === void 0) {
@@ -1581,6 +1597,29 @@ function toUnknownField(shape, value, path) {
 		if (unknown) return unknown;
 	}
 }
+/**
+* toMissingElementField names the first element that lacks a field every element must carry,
+* whether the element came from its flag or from the --input body.
+*/
+function toMissingElementField(operation, body) {
+	for (const flag of operation.bodyFlags) {
+		const elements = toValueAt(body, flag.jsonPath);
+		if (!flag.elementRequired || !Array.isArray(elements)) continue;
+		for (const [index, element] of elements.entries()) {
+			const missing = flag.elementRequired.filter((field) => !hasPath(element, [field]));
+			if (missing.length > 0) return `${flag.jsonPath.join(".")}[${index}] needs ${missing.join(", ")}. Every --${flag.name} needs ${flag.elementRequired.map((field) => `${field}=`).join(", ")}`;
+		}
+	}
+}
+/** toValueAt reads the value a body holds at a field's path. */
+function toValueAt(body, path) {
+	let holder = body;
+	for (const name of path) {
+		if (typeof holder !== "object" || holder === null) return;
+		holder = holder[name];
+	}
+	return holder;
+}
 /** hasPath reports whether a body already holds a value at a field's path. */
 function hasPath(body, path) {
 	let holder = body;
@@ -4784,7 +4823,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "create",
 				summary: "Create asset",
-				example: "hardfin asset create --in-inventory-date <value> --item-id <uuid> --location-id <uuid>",
+				example: "hardfin asset create --in-inventory-date <value> --item-id <uuid> --location-id <uuid> --serial <value>",
 				method: "POST",
 				path: "/asset",
 				pathParameters: [],
@@ -5307,6 +5346,11 @@ const surfaceCommands = [
 								"shipAt": ["string", "null"],
 								"shipAtTimezone": ["string", "null"]
 							},
+							elementRequired: [
+								"assetId",
+								"destinationId",
+								"originId"
+							],
 							schema: z.array(z.string())
 						}],
 						body: { "fields": { "moves": { "items": { "fields": {
@@ -5350,6 +5394,7 @@ const surfaceCommands = [
 								"deliverAt": ["string", "null"],
 								"shipAt": ["string", "null"]
 							},
+							elementRequired: ["assetId", "id"],
 							schema: z.array(z.string())
 						}],
 						body: { "fields": { "moves": { "items": { "fields": {
@@ -5441,6 +5486,7 @@ const surfaceCommands = [
 							"string",
 							"null"
 						] },
+						elementRequired: ["fieldId"],
 						schema: z.array(z.string())
 					},
 					{
@@ -5941,7 +5987,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Create asset cost adjustment",
-					example: "hardfin asset cost-adjustment create ast_4f9xk2mq7plr8stz --adjustment-type <value> --amount-value <value> --amount-iso-code <value>",
+					example: "hardfin asset cost-adjustment create ast_4f9xk2mq7plr8stz --adjustment-type <value> --amount-value <value> --amount-iso-code <value> --effective-date <value> --reason <value>",
 					method: "POST",
 					path: "/asset/{assetKey}/cost-adjustment",
 					pathParameters: [{
@@ -7509,6 +7555,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -7619,6 +7666,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -8111,6 +8159,7 @@ const surfaceCommands = [
 							"order": ["integer"],
 							"section": ["integer"]
 						},
+						elementRequired: ["fieldId"],
 						schema: z.array(z.string())
 					},
 					{
@@ -8594,7 +8643,7 @@ const surfaceCommands = [
 					defineOperation({
 						name: "create",
 						summary: "Create item field",
-						example: "hardfin item field create item_7Hq2Lm9XcR4tWz8K --field-type <value> --label <value> --order <number>",
+						example: "hardfin item field create item_7Hq2Lm9XcR4tWz8K --field-type <value> --label <value> --order <number> --section <number>",
 						method: "POST",
 						path: "/item/{itemKey}/field",
 						pathParameters: [{
@@ -9344,7 +9393,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "create",
 				summary: "Create project",
-				example: "hardfin project create --line-item aggregationKey=<value>,itemId=<value>,quantity=<value>,transactionType=<value> --name <value>",
+				example: "hardfin project create --line-item itemId=<value>,transactionType=<value>,aggregationKey=<value>,quantity=<value> --name <value>",
 				method: "POST",
 				path: "/project",
 				pathParameters: [],
@@ -9557,6 +9606,7 @@ const surfaceCommands = [
 							"totalOverride.amount": "^[^-]",
 							"unitPrice.amount": "^[^-]"
 						},
+						elementRequired: ["itemId", "transactionType"],
 						schema: z.array(z.string())
 					},
 					{
@@ -9695,7 +9745,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "update",
 				summary: "Patch project",
-				example: "hardfin project update proj_7hq2lm9xcr4twz8k --line-item aggregationKey=<value>,itemId=<value>,quantity=<value>,transactionType=<value>",
+				example: "hardfin project update proj_7hq2lm9xcr4twz8k --line-item itemId=<value>,transactionType=<value>,aggregationKey=<value>,quantity=<value>",
 				method: "PATCH",
 				path: "/project/{projectKey}",
 				pathParameters: [{
@@ -9973,6 +10023,7 @@ const surfaceCommands = [
 							"totalOverride.amount": "^[^-]",
 							"unitPrice.amount": "^[^-]"
 						},
+						elementRequired: ["itemId", "transactionType"],
 						schema: z.array(z.string())
 					},
 					{
@@ -10896,6 +10947,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -11112,6 +11164,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -11510,7 +11563,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "create",
 				summary: "Create return order",
-				example: "hardfin return-order create --from-location-id <uuid> --item itemId=<value>,requestedQuantity=<value> --return-type <value>",
+				example: "hardfin return-order create --from-location-id <uuid> --item itemId=<value>,requestedQuantity=<value> --return-type <value> --to-location-id <uuid>",
 				method: "POST",
 				path: "/return-order",
 				pathParameters: [],
@@ -11636,6 +11689,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -11863,6 +11917,7 @@ const surfaceCommands = [
 						element: ["itemId", "requestedQuantity"],
 						elementUuids: ["itemId"],
 						elementTypes: { "requestedQuantity": ["integer"] },
+						elementRequired: ["itemId", "requestedQuantity"],
 						schema: z.array(z.string())
 					},
 					{
@@ -13679,5 +13734,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-eT-hgKX0.js.map
-//# debugId=ef42eac6-02c0-5ed0-ad0b-c3d60bfb51f8
+//# sourceMappingURL=program-CYp6XF8D.js.map
+//# debugId=2061590a-8bec-56a7-864d-cb1435ccb994

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.1-dev.69",
+    "version": "0.1.1-dev.70",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",