@hardfin/cli 0.1.1-dev.70 → 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
@@ -324,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-wgnggJ45.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]="9d637f5e-0cda-5582-80ff-432edc41bf8c")}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";
@@ -113,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";
@@ -494,7 +496,7 @@ function writeCache(cache) {
 	} catch {}
 }
 //#endregion
-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 };
+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-wgnggJ45.js.map
-//# debugId=9d637f5e-0cda-5582-80ff-432edc41bf8c
+//# 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]="e43cc9b0-2707-553a-973d-9a707e329000")}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-CYp6XF8D.js");
-		const { startUpdateCheck, writeUpdateNotice } = await import("./notice-CQ5Nlp80.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-CYp6XF8D.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=e43cc9b0-2707-553a-973d-9a707e329000
+//# debugId=3bf6cdf0-d851-549b-9a43-bb3c8520e8ff