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

package/README.md

@@ -24,6 +24,57 @@ Previews of unreleased work are published from the `dev` branch.
 npm install -g @hardfin/cli@dev
 ```
 
+### Staying up to date
+
+Hardfin changes its API from time to time in ways an older CLI cannot follow. The CLI checks
+npm for a newer version, and `hardfin update` installs it.
+
+```sh
+hardfin update --check   # say whether a newer version is published
+hardfin update           # install it, asking first
+hardfin update --yes     # install it without asking, as an agent does
+```
+
+The check asks npm's registry once a day, beside the command rather than before it. It asks
+again at once when a command fails in a way a newer CLI may fix:
+
+- The API refused the version this CLI speaks, which is `cli_outdated`
+- The API refused the request, which is `bad_request` or `invalid_request`
+- The CLI did not know a command, flag or body field, which is `unknown_command`, `invalid_flag` or `invalid_input`
+- An answer carried the API's `API_VERSION_OUTDATED` notice
+
+A newer version is announced on stderr after the command's own output. A person reads a
+sentence. Anything else reads one JSON line, which carries `event` where a failure carries `code`.
+
+| `event`                | Fields                                   | Means                                                   |
+| ---------------------- | ---------------------------------------- | ------------------------------------------------------- |
+| `update_available`     | `version`, `latest`, `reason`, `command` | A newer CLI is published. `command` installs it         |
+| `api_version_outdated` | `apiVersion`, `latestVersion`, `command` | The API has moved on, and no newer CLI is published yet |
+
+`reason` is `reminder` for the daily notice, which is printed once a day for each version.
+It is `failure` or `api_version_outdated` when the notice follows a failure or the API's
+notice, and those are printed every time. Set `HARDFIN_NO_UPDATE_CHECK=1` to turn the check
+off. A run with `CI` set never checks, and neither does `hardfin mcp`.
+
+`hardfin update` installs only where it owns the install. It never runs `sudo`.
+
+| Installed with                                       | `hardfin update`                                                     |
+| ---------------------------------------------------- | -------------------------------------------------------------------- |
+| `npm install -g`, in a folder this account can write | Runs `npm install -g` with the same prefix, then refreshes the skill |
+| `npm install -g`, in a folder another account owns   | Prints `npm install -g @hardfin/cli@latest`, and fails               |
+| `npx`                                                | Prints `npx -y @hardfin/cli@latest`, and fails                       |
+| Volta, pnpm, Yarn or Bun                             | Prints that tool's install command, and fails                        |
+| A project's `package.json`                           | Prints `npm install @hardfin/cli@latest` for that project, and fails |
+| A clone of this repository                           | Prints the git and build commands, and fails                         |
+
+A failure here has the code `update_unavailable`, and its message ends with the command to
+run. A preview updates to the newer of the next preview and the next release.
+
+After installing, `hardfin update` runs `hardfin init --skills-only` with the new version when
+the working directory holds the skill `hardfin init` wrote. That brings the skill up to date
+and leaves `AGENTS.md` and the MCP configs alone. Run `hardfin init --skills-only` in any
+other project you set up.
+
 ## The command surface
 
 Most commands are generated from the published API document rather than written by hand.
@@ -148,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
 
@@ -169,7 +221,7 @@ otherwise have to read. Pipe a result through `jq .` to read it indented.
 | `requestId` | The API's request ID, or null when the request never reached it          |
 | `status`    | The HTTP status, or null for a failure caught before any request is made |
 
-Four codes cover failures that are easy to mistake for something else.
+Five codes cover failures that are easy to mistake for something else.
 
 | `code`                | Happens when                                                                                         |
 | --------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -177,6 +229,7 @@ Four codes cover failures that are easy to mistake for something else.
 | `unexpected_response` | A 200 whose body is not the API's JSON, such as a proxy's page. It is never an empty result          |
 | `timed_out`           | The server did not begin to answer within 60 seconds, or 300 for an upload                           |
 | `file_error`          | This machine refused a path the command was given                                                    |
+| `cli_outdated`        | The API no longer serves the version of the endpoint this CLI speaks. Only `hardfin update` fixes it |
 
 A change that timed out may still have been made, and the message says so. Read the record
 before sending the change again.
@@ -225,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-wgnggJ45.js

@@ -0,0 +1,500 @@
+#!/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){}}();
+import { createRequire } from "node:module";
+import { z } from "zod";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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/report/expected.ts
+/**
+* ExpectedFailure is a failure the CLI anticipated: the person's input, their network, their
+* machine, or an answer from the API. It is shown to the person and never reported, and every
+* error that does not extend it is reported as a defect.
+*/
+var ExpectedFailure = class extends Error {};
+/** LockHeld is another hardfin command holding the credential lock for too long. */
+var LockHeld = class extends ExpectedFailure {
+	constructor() {
+		super("another hardfin command is holding the credential lock");
+		this.name = "LockHeld";
+	}
+};
+/**
+* Interrupted is a person stopping the CLI with Ctrl-C. It is something they chose to do,
+* not a failure, so the CLI stops quietly with the exit code a shell gives an interrupt.
+*/
+var Interrupted = class extends ExpectedFailure {
+	constructor() {
+		super("interrupted");
+		this.name = "Interrupted";
+	}
+};
+/** TimedOut is something the CLI waited on for longer than it allows, such as the browser. */
+var TimedOut = class extends ExpectedFailure {
+	constructor(message) {
+		super(message);
+		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",
+	"false",
+	"off",
+	"no"
+]);
+/**
+* toTelemetry decides whether defects are reported. A person's opt out wins over everything,
+* and a CLI run from a checkout reports only when its developer asks it to.
+*/
+function toTelemetry(env = process.env, isCheckout = isRunFromCheckout()) {
+	const dsn = env["HARDFIN_SENTRY_DSN"] || "https://a4819e652e9fa63c0ab67e9febe44565@o1388102.ingest.us.sentry.io/4512176532684800";
+	const base = {
+		dsn,
+		environment: isCheckout ? "local" : version$1.includes("-dev.") ? "preview" : "production",
+		release: toRelease(version$1)
+	};
+	if (env["DO_NOT_TRACK"] && !OFF.has(env["DO_NOT_TRACK"].toLowerCase())) return {
+		...base,
+		enabled: false,
+		from: "DO_NOT_TRACK"
+	};
+	const asked = env["HARDFIN_TELEMETRY"]?.toLowerCase();
+	if (asked !== void 0 && OFF.has(asked)) return {
+		...base,
+		enabled: false,
+		from: "HARDFIN_TELEMETRY"
+	};
+	if (!isDsn(dsn)) return {
+		...base,
+		enabled: false,
+		from: "HARDFIN_SENTRY_DSN is not a valid DSN"
+	};
+	if (asked !== void 0) return {
+		...base,
+		enabled: true,
+		from: "HARDFIN_TELEMETRY"
+	};
+	return isCheckout ? {
+		...base,
+		enabled: false,
+		from: "run from a checkout"
+	} : {
+		...base,
+		enabled: true,
+		from: "default"
+	};
+}
+/**
+* isRunFromCheckout answers whether this CLI runs from a clone of its repository, as npm link
+* and node dist/cli.js do. The published package holds dist and nothing beside it.
+*/
+function isRunFromCheckout() {
+	return existsSync(fileURLToPath(new URL("../src", import.meta.url)));
+}
+/** isDsn answers whether a DSN can be read as the URL of a Sentry project. */
+function isDsn(dsn) {
+	try {
+		return new URL(dsn).host !== "";
+	} catch {
+		return false;
+	}
+}
+/**
+* toRelease names a version as Sentry knows it. Sentry refuses a slash in a release name, so
+* the scoped package name @hardfin/cli cannot be used, and hardfin-cli stands in for it.
+*/
+function toRelease(of) {
+	return `hardfin-cli@${of}`;
+}
+//#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";
+/**
+* The client Hardfin seeded for this CLI. The key is generated from a fixed identifier, so
+* it names the same first-party client in every environment.
+*/
+const DEFAULT_CLIENT_ID = "oacl_10e2etq297nhjfhb";
+const DEFAULT_ENV_FILE = ".env";
+const FileSettings = z.strictObject({
+	apiUrl: z.string().optional(),
+	apiKey: z.string().optional(),
+	clientId: z.string().optional(),
+	issuerUrl: z.string().optional()
+});
+/** ConfigFailure is a config file that cannot be read or does not match the schema. */
+var ConfigFailure = class extends ExpectedFailure {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigFailure";
+	}
+};
+/** toSettings resolves what this invocation talks to, and where each value came from. */
+function toSettings(flags = {}, directory = process.cwd()) {
+	const fromEnvFile = loadEnvFile(directory);
+	const file = toFileSettings(directory);
+	const sources = {};
+	const pick = (key, flag, variable, fromFile, fallback) => {
+		const [value, source] = toLayer(flag, process.env[variable], fromEnvFile.has(variable), fromFile, fallback);
+		sources[key] = source;
+		return value;
+	};
+	const apiUrl = toTrimmedUrl(pick("apiUrl", flags.apiUrl, "HARDFIN_API_URL", file.apiUrl, DEFAULT_API_URL) ?? DEFAULT_API_URL);
+	return {
+		settings: {
+			apiUrl,
+			apiKey: pick("apiKey", flags.apiKey, "HARDFIN_API_KEY", file.apiKey),
+			clientId: pick("clientId", flags.clientId, "HARDFIN_CLIENT_ID", file.clientId, DEFAULT_CLIENT_ID) ?? DEFAULT_CLIENT_ID,
+			issuerUrl: pick("issuerUrl", flags.issuerUrl, "HARDFIN_ISSUER_URL", file.issuerUrl, toOrigin(apiUrl)) ?? ""
+		},
+		sources
+	};
+}
+function toLayer(flag, environment, isFromEnvFile, file, fallback) {
+	if (flag) return [flag, "flag"];
+	if (environment) return [environment, isFromEnvFile ? "env file" : "environment"];
+	if (file) return [file, "config file"];
+	return [fallback, "default"];
+}
+/** toFileSettings reads the local override file, which a local build is expected to have. */
+function toFileSettings(directory) {
+	const path = resolve(directory, CONFIG_FILE);
+	if (!existsSync(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new ConfigFailure(`${CONFIG_FILE} does not hold JSON`);
+	}
+	const result = FileSettings.safeParse(parsed);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		throw new ConfigFailure(`${CONFIG_FILE} is not valid: ${issue?.path.join(".") || "root"} ${issue?.message ?? ""}`.trim());
+	}
+	return result.data;
+}
+/** The variables an env file may set, which are the settings and nothing else the CLI reads. */
+const SETTING_VARIABLES = /* @__PURE__ */ new Set([
+	"HARDFIN_API_URL",
+	"HARDFIN_API_KEY",
+	"HARDFIN_CLIENT_ID",
+	"HARDFIN_ISSUER_URL"
+]);
+/**
+* isTakenFromFile answers whether an env file may set a variable. A file in a folder supplies
+* the settings, and may turn error reports off. Where reports go, where a sign in is kept,
+* and anything a started program reads are for the person to set themselves.
+*/
+function isTakenFromFile(name, value) {
+	if (SETTING_VARIABLES.has(name)) return true;
+	if (name === "DO_NOT_TRACK") return !OFF.has(value.toLowerCase());
+	return name === "HARDFIN_TELEMETRY" && OFF.has(value.toLowerCase());
+}
+/**
+* loadEnvFile reads a .env beside the command, so a local build needs no exports, and
+* answers which variables it supplied. An exported variable is left alone, so a shell
+* export still wins over the file.
+*/
+function loadEnvFile(directory) {
+	const path = process.env["HARDFIN_ENV_FILE"] ?? resolve(directory, DEFAULT_ENV_FILE);
+	if (!existsSync(path)) return /* @__PURE__ */ new Set();
+	let held;
+	try {
+		held = parseEnv(readFileSync(path, "utf8"));
+	} catch {
+		throw new ConfigFailure(`${path} cannot be read as an env file`);
+	}
+	const supplied = /* @__PURE__ */ new Set();
+	for (const [name, value] of Object.entries(held)) {
+		if (value === void 0 || process.env[name] !== void 0 || !isTakenFromFile(name, value)) continue;
+		process.env[name] = value;
+		supplied.add(name);
+	}
+	return supplied;
+}
+function toTrimmedUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+/** toOrigin drops the API's path, because the authorization server sits at the host root. */
+function toOrigin(apiUrl) {
+	try {
+		return new URL(apiUrl).origin;
+	} catch {
+		return 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() {
+	const base = process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state");
+	return join(base, "hardfin");
+}
+/** The newest API version any answer in this run asked the CLI to move to. */
+let outdatedTo;
+/** noteNotices keeps what an answer's notices say about the version this CLI speaks. */
+function noteNotices(notices) {
+	if (!Array.isArray(notices)) return;
+	for (const notice of notices) {
+		const { code, latestVersion } = typeof notice === "object" && notice !== null ? notice : {};
+		if (code !== "API_VERSION_OUTDATED" || typeof latestVersion !== "string") continue;
+		if (outdatedTo === void 0 || latestVersion > outdatedTo) outdatedTo = latestVersion;
+	}
+}
+/** toOutdatedTo answers the API version an answer said to move to, or nothing when none did. */
+function toOutdatedTo() {
+	return outdatedTo;
+}
+//#endregion
+//#region src/system/package.ts
+/** The folders this package ships, beside its manifest. */
+const SHIPPED = [
+	"dist",
+	"skills",
+	"templates"
+];
+/** toPackageDirectory finds this package's own folder, which holds the skills and templates it ships. */
+function toPackageDirectory(from = dirname(fileURLToPath(import.meta.url))) {
+	for (let directory = from;; directory = dirname(directory)) {
+		const manifest = join(directory, "package.json");
+		if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@hardfin/cli") return directory;
+		if (dirname(directory) === directory) throw new Error("the @hardfin/cli package folder could not be found, so its skills cannot be copied");
+	}
+}
+/**
+* isShipped answers whether a path is one of the files this package installs. A file of the
+* CLI's own that cannot be read is a broken install, not the person's machine refusing them.
+*/
+function isShipped(path, packageDirectory) {
+	let directory;
+	try {
+		directory = packageDirectory ?? toPackageDirectory();
+	} catch {
+		return false;
+	}
+	return path === join(directory, "package.json") || SHIPPED.some((folder) => path === join(directory, folder) || path.startsWith(join(directory, folder) + sep));
+}
+//#endregion
+//#region src/update/check.ts
+/** The package the CLI is published as, which an update installs. */
+const PACKAGE = "@hardfin/cli";
+/** How long a registry request may take, which is short because no command waits on it for long. */
+const REGISTRY_TIMEOUT_MS = 3e3;
+/** A version as npm publishes this package, a release or a dev preview. */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+/**
+* toUpdateCheckRefusal says why the CLI should not ask the registry, or nothing when it may.
+* A person turns it off with HARDFIN_NO_UPDATE_CHECK, and a CI run never asks.
+*/
+function toUpdateCheckRefusal(env = process.env) {
+	const asked = env["HARDFIN_NO_UPDATE_CHECK"];
+	if (asked !== void 0 && asked !== "" && !OFF.has(asked.toLowerCase())) return "HARDFIN_NO_UPDATE_CHECK is set";
+	if (env["CI"] && !OFF.has(env["CI"].toLowerCase())) return "CI is set";
+}
+/**
+* toCheck answers whether a newer version is published. It reads the cache while it is less
+* than a day old, unless isFresh asks the registry regardless.
+*/
+async function toCheck(options = {}) {
+	const cache = toCache();
+	const isCurrent = cache !== void 0 && Date.now() - Date.parse(cache.checkedAt) < 864e5;
+	if (cache && (options.isCachedOnly || isCurrent && !options.isFresh)) return toUpdateCheck(cache.tags, cache.checkedAt, true);
+	if (options.isCachedOnly) return;
+	const tags = await toRegistryTags(options.signal);
+	if (!tags) return;
+	const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+	writeCache({
+		...cache,
+		checkedAt,
+		tags
+	});
+	return toUpdateCheck(tags, checkedAt, false);
+}
+/** toUpdateCheck compares the installed version with the newest one on its channel. */
+function toUpdateCheck(tags, checkedAt, isCached, version = version$1) {
+	const tag = toChannel(version);
+	const latest = (tag === "dev" ? [tags.dev, tags.latest] : [tags.latest]).filter((entry) => entry !== void 0).reduce((newest, entry) => newest === void 0 || toCompared(entry, newest) > 0 ? entry : newest, void 0);
+	if (latest === void 0 || !VERSION.test(version)) return;
+	return {
+		version,
+		latest,
+		tag,
+		isOutdated: toCompared(latest, version) > 0,
+		checkedAt,
+		isCached
+	};
+}
+/** toChannel names the npm tag a version was published under. */
+function toChannel(version) {
+	return /-dev\./.test(version) ? "dev" : "latest";
+}
+/**
+* toCompared orders two versions by semver precedence. A release sorts after its own
+* previews, and dev.10 after dev.9, because a numeric part compares as a number.
+*/
+function toCompared(a, b) {
+	const [left, right] = [VERSION.exec(a), VERSION.exec(b)];
+	if (!left || !right) return 0;
+	for (let index = 1; index <= 3; index++) {
+		const difference = Number(left[index]) - Number(right[index]);
+		if (difference !== 0) return Math.sign(difference);
+	}
+	const [leftPre, rightPre] = [left[4], right[4]];
+	if (leftPre === void 0 || rightPre === void 0) return leftPre === rightPre ? 0 : leftPre === void 0 ? 1 : -1;
+	const [leftParts, rightParts] = [leftPre.split("."), rightPre.split(".")];
+	for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index++) {
+		const [l, r] = [leftParts[index], rightParts[index]];
+		if (l === void 0 || r === void 0) return l === void 0 ? -1 : 1;
+		const difference = /^\d+$/.test(l) && /^\d+$/.test(r) ? Number(l) - Number(r) : l.localeCompare(r);
+		if (difference !== 0) return Math.sign(difference);
+	}
+	return 0;
+}
+/** toRegistryTags asks npm which versions the package's tags name, or nothing when it cannot answer. */
+async function toRegistryTags(signal) {
+	const registry = (process.env["npm_config_registry"] || "https://registry.npmjs.org").replace(/\/+$/, "");
+	const timeout = AbortSignal.timeout(REGISTRY_TIMEOUT_MS);
+	try {
+		const response = await fetch(`${registry}/-/package/${PACKAGE}/dist-tags`, {
+			headers: { Accept: "application/json" },
+			signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+		});
+		if (!response.ok) return;
+		return toTags(await response.json());
+	} catch {
+		return;
+	}
+}
+/** toTags keeps the tags that name a version, since a tag's value reaches an npm command line. */
+function toTags(answer) {
+	if (typeof answer !== "object" || answer === null) return;
+	const tags = {};
+	for (const name of ["latest", "dev"]) {
+		const value = answer[name];
+		if (typeof value === "string" && VERSION.test(value)) tags[name] = value;
+	}
+	return tags.latest === void 0 && tags.dev === void 0 ? void 0 : tags;
+}
+/**
+* isReminderDue answers whether a daily reminder of this version may be printed, and marks it
+* printed. A person told once a day is told enough, and an agent running many commands is not
+* told on every one.
+*/
+function isReminderDue(latest) {
+	const cache = toCache();
+	if (!cache) return true;
+	if (cache.remindedOf === latest && Date.now() - Date.parse(cache.remindedAt ?? "") < 864e5) return false;
+	writeCache({
+		...cache,
+		remindedOf: latest,
+		remindedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	return true;
+}
+function toCachePath() {
+	return join(toStateDirectory(), "update-check.json");
+}
+function toCache() {
+	try {
+		const parsed = JSON.parse(readFileSync(toCachePath(), "utf8"));
+		const tags = toTags(parsed.tags);
+		return typeof parsed.checkedAt === "string" && tags ? {
+			...parsed,
+			checkedAt: parsed.checkedAt,
+			tags
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+function writeCache(cache) {
+	try {
+		mkdirSync(dirname(toCachePath()), { recursive: true });
+		writeFileSync(toCachePath(), `${JSON.stringify(cache)}\n`);
+	} 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 };
+
+//# 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]="aae61fcd-2c4e-5e7c-9063-5e90072d5171")}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,7 +14,9 @@ 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-DgQuzFjb.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);
 		} catch (error) {
@@ -22,6 +24,7 @@ try {
 			if (code === void 0) throw error;
 			process.exitCode = code;
 		}
+		await writeUpdateNotice(pending, process.argv.slice(2));
 		if (wasReportAttempted()) process.exit();
 	} else process.stdout.write(`${answer}\n`);
 } catch (error) {
@@ -33,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-DgQuzFjb.js");
+		const { toReported, writeCrash } = await import("./program-CYp6XF8D.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -54,4 +57,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=aae61fcd-2c4e-5e7c-9063-5e90072d5171
+//# debugId=e43cc9b0-2707-553a-973d-9a707e329000