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

package/README.md

@@ -85,6 +85,7 @@ Most commands are generated from the published API document rather than written
 | `src/command/surface.generated.ts` | Every endpoint as a command, rewritten by the generator                                      |
 | `surface-overrides.json`           | The operations whose generated name is wrong                                                 |
 | `spec/core.openapi.yaml`           | The API document the generator reads, vendored here                                          |
+| `spec/source.json`                 | Where the vendored document came from, and whether it is a preview                           |
 | `scripts/generate-surface.mjs`     | The generator                                                                                |
 
 ### How an endpoint becomes a command
@@ -199,9 +200,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 +279,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.
@@ -322,24 +325,61 @@ reads it. Nothing fetches a document during a build, a release, or CI.
 Refresh it with the script, which then rewrites the generated commands:
 
 ```sh
-scripts/update-spec.sh              # reads hardfinhq/api-spec over your own git access
+scripts/update-spec.sh              # the newer of api-spec's main and active-preview
+scripts/update-spec.sh --main       # api-spec's main, the published contract
+scripts/update-spec.sh --preview    # api-spec's active-preview, and fails when there is none
 scripts/update-spec.sh ../hardfin   # bundles the fragmented source in a monorepo checkout
 ```
 
-The monorepo form runs the same bundler at the same version CI uses, so the result matches
-what the api-spec bridge publishes. Commit the document and the generated commands together.
+The first three read `hardfinhq/api-spec` over your own git access. The monorepo form runs the
+same bundler at the same version CI uses, so the result matches what the api-spec bridge
+publishes. Commit the document, `spec/source.json` and the generated files together.
 
-Two checks keep the pair honest.
+#### Previews
 
-| Check         | Refuses                                                                       |
-| ------------- | ----------------------------------------------------------------------------- |
-| The generator | a document whose `info.version` is not a date, which means an earlier release |
-| CI            | a vendored document that was updated without regenerating the commands        |
+`hardfinhq/api-spec` has two branches the script reads.
+
+| Branch           | Holds                                                   | Exists                                        |
+| ---------------- | ------------------------------------------------------- | --------------------------------------------- |
+| `main`           | The published contract, which the production API serves | always                                        |
+| `active-preview` | The next contract, before it publishes                  | while the monorepo's `api-preview` tag exists |
+
+Pushing or moving the monorepo's `api-preview` tag rebuilds `active-preview` from `main` with
+the tagged commit's document. Deleting the tag deletes the branch. With no option, the script
+reads `active-preview` while it exists and its last commit is newer than `main`'s. Once `main`
+publishes past it, `main` holds everything the preview did, and the script reads `main`.
+
+A preview lets a dev build carry the next contract before it publishes. Merging a preview
+document to `dev` publishes it as a `-dev` build like any other change.
+
+The script records where the document came from in `spec/source.json`, including whether it is
+a preview. A preview names an API version the production API does not serve yet, so it never
+reaches a release.
+
+| Check                                            | Refuses                                                 |
+| ------------------------------------------------ | ------------------------------------------------------- |
+| The version check, on a pull request into `main` | a `spec/source.json` that names a preview               |
+| The release workflow, on a push to `main`        | the same, for a preview that reached `main` another way |
+
+Run `scripts/update-spec.sh --main` and commit the result before releasing a `dev` that carries a preview.
+
+#### Checks on the document
+
+Three checks keep the document and the generated files honest.
+
+| Check         | Refuses                                                                                                                    |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| The generator | a document whose `info.version` is not a date, which means an earlier release                                              |
+| CI            | a vendored document that was updated without regenerating the commands                                                     |
+| CI            | an API version that differs from the document's, because the generator writes it to `src/command/api-version.generated.ts` |
 
 The first one matters because `hardfinhq/api-spec` can sit a release behind the monorepo
 while its bridge pull request is open. Generating from that document would replace the
 current commands with an earlier API's.
 
+The API version every request sends is the document's `info.version`. Nothing sets it by hand,
+so a new document cannot leave requests naming the version before it.
+
 ## Signing in
 
 ```sh

package/dist/{check-CDkHR_Qt.js → check-CvjTUx-K.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]="4a31fc43-cc3a-59be-a501-eb86f4115b3f")}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",
@@ -184,9 +113,11 @@ function toRelease(of) {
 	return `hardfin-cli@${of}`;
 }
 //#endregion
+//#region src/command/api-version.generated.ts
+/** API_VERSION is the version of the API document the commands were generated from. */
+const API_VERSION = "2026-10-22";
+//#endregion
 //#region src/config/settings.ts
-/** The API version this build was written against, sent on every request. */
-const API_VERSION = "2026-10-21";
 /** The file a local build reads its overrides from, in the working directory. */
 const CONFIG_FILE = "config.local.json";
 const DEFAULT_API_URL = "https://api.hardfin.com/v2";
@@ -304,6 +235,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 +496,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, CONFIG_FILE as _, isShipped as a, API_VERSION 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, ConfigFailure as v, Interrupted as w, toTelemetry as x, toSettings as y };
 
-//# sourceMappingURL=check-CDkHR_Qt.js.map
-//# debugId=e9a5da76-6485-5cc1-9d09-55076e5c9b22
+//# sourceMappingURL=check-CvjTUx-K.js.map
+//# debugId=4a31fc43-cc3a-59be-a501-eb86f4115b3f

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]="3bf6cdf0-d851-549b-9a43-bb3c8520e8ff")}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-CC8Iqb14.js");
+		const { startUpdateCheck, writeUpdateNotice } = await import("./notice-D6mbHF9O.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-CC8Iqb14.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=3bf6cdf0-d851-549b-9a43-bb3c8520e8ff