@hardfin/cli 0.1.1-dev.42 → 0.1.1-dev.45

package/README.md

@@ -16,6 +16,8 @@ server, and every command also accepts an API key.
 npm install -g @hardfin/cli
 ```
 
+It needs Node 20.12 or later.
+
 Previews of unreleased work are published from the `dev` branch.
 
 ```sh
@@ -71,6 +73,9 @@ decimal such as `--salvage-value 1500.00` stays a string, which is how the API t
 without losing precision.
 
 A download is written where you name it, and a terminal is never filled with a file's bytes.
+With no `--output`, the file takes the name it was uploaded under, in the working directory.
+That name never chooses a folder, a hidden file, or a file that is already there. The command
+asks for `--output` in those cases.
 
 ```sh
 hardfin file get file_7hq2mx9pkr4stz8w --output photo.jpg
@@ -180,7 +185,9 @@ hardfin logout           # forget this machine, and ask Hardfin to revoke it
 ```
 
 An API key is still the way to run unattended. `--api-key`, or `HARDFIN_API_KEY`, wins over
-a stored sign in, so CI and an agent sandbox need no browser. The flag beats the variable.
+a stored sign in, so CI and an agent sandbox need no browser. The flag beats the variable. Prefer the
+variable, because a command line is visible to other programs on the machine and is kept in
+an agent's transcript.
 
 An API key is held to two rules before it is sent:
 
@@ -199,7 +206,8 @@ how a local build is set up. Pass `--api-url` to send a key you set to that fold
 2. Opens a loopback listener on `127.0.0.1`, over IPv4, on whatever port the machine hands out
 3. Opens the browser to approve this CLI, with a PKCE challenge and a state value
 4. Prints the URL, and waits at the keyboard as well as on the listener
-5. Checks the state and the `iss` it came back with, then trades the code for tokens
+5. Checks the state and the `iss` it came back with, then trades the code for tokens. Every
+   endpoint the authorization server named must be https, or this machine
 6. Keeps the refresh token, and nothing else
 
 While it waits, the terminal takes two things.
@@ -216,6 +224,11 @@ and the redirect it failed to follow is still in the address bar.
 On WSL the browser is opened through Windows, by `wslview`, then PowerShell, then
 `explorer.exe`, because `xdg-open` reaches nothing outside the distribution.
 
+The browser is only ever sent to an https address, or to this machine. The address comes from
+the authorization server, so one with any other scheme is printed for you to read and never
+opened. The listener takes only a response that carries the state this sign in sent, and
+turns any other request away without ending the sign in.
+
 The port changes every time, so Hardfin matches a loopback redirect by everything except its
 port, which is what RFC 8252 asks of an authorization server.
 
@@ -401,6 +414,17 @@ exit codes. Each call has these limits:
 | Commands running | 4 at once                               | The next call waits for one to finish      |
 | One argument     | 128 KiB                                 | Refused, pointing at the `input` argument  |
 | Standard input   | The call's `input` argument, or nothing | Always closed, so `--input -` never waits  |
+| One result       | 200,000 characters                      | Cut, with a line saying it is not complete |
+
+A failed call also carries the failure as `structuredContent`, with the same `code`,
+`message`, `errors`, `requestId` and `status` the CLI prints, plus `exitCode`. A file that is
+not text is refused through `--output -`, because handing it over as text would change its
+bytes.
+
+Renewing a sign in gives the authorization server 15 seconds for its whole answer. That keeps
+a renewal well inside the 120 seconds a call has, so a slow renewal fails as `timed_out` and
+is not stopped partway. A refresh token the server rotated and never finished sending is
+still lost, which no client can prevent.
 
 ### What a call may touch on this machine
 
@@ -416,6 +440,9 @@ held to rules a person at a terminal is not.
 | Downloads with `--output <path>`                               | A write, so it runs through `hardfin_write`            |
 | Downloads with no `--output`                                   | Refused, naming `--output -` to read the file in place |
 
+`hardfin init` is held to the same folder. `hardfin completion install` and `uninstall` are
+refused, along with `login`, `logout` and `mcp`, because a person runs those themselves.
+
 The rules cover every flag that takes a path: `--input`, `--file` and `--output`. A person
 runs the command themselves for a file the server will not reach.
 
@@ -472,7 +499,8 @@ Only defects are reported. None of these are:
 - a network failure, or a server that cannot be reached
 - a mistake on the command line or in a settings file
 - being signed out, or a sign in that was cancelled or refused
-- the machine refusing a file, such as a full disk or a missing permission
+- the machine refusing a file, such as a full disk or a missing permission, unless the file
+  is one the CLI installs, which makes it a broken package
 - anything from a run with no API key and no stored sign in, except a defect in `hardfin login`
 
 The last rule is there because package scanners install the CLI and run it in sandboxes. They
@@ -510,9 +538,11 @@ settings, and the one nearest the top wins.
 
 An exported variable beats `.env`, because the CLI leaves a variable that is already set alone.
 
-An env file sets only variables that begin with `HARDFIN_`. Anything else in it is ignored,
-so a `.env` in a folder you cloned cannot set a variable such as `NODE_OPTIONS` for the
-programs the CLI starts.
+An env file sets the four settings: `HARDFIN_API_URL`, `HARDFIN_API_KEY`, `HARDFIN_CLIENT_ID`
+and `HARDFIN_ISSUER_URL`. It may also turn error reports off, with `DO_NOT_TRACK=1` or
+`HARDFIN_TELEMETRY=0`. Anything else in it is ignored, so a `.env` in a folder you cloned
+cannot set `NODE_OPTIONS` for the programs the CLI starts, or send error reports elsewhere
+with `HARDFIN_SENTRY_DSN`. Export a variable yourself to set it.
 
 ### What a local build writes
 

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]="c2c38fd6-1925-561f-baf9-51faf8c4c4b8")}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]="7a26fe4e-1a9f-538e-af63-a17134f6e803")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,7 +14,7 @@ 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-CqO1St9H.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-Bz-DwZDJ.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -31,10 +31,13 @@ try {
 async function toCrash(error) {
 	if (isCrashing) return;
 	isCrashing = true;
-	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported } = await import("./program-CqO1St9H.js");
-		await toReported(error, false, void 0, "fatal");
+		const { toReported, writeCrash } = await import("./program-Bz-DwZDJ.js");
+		writeCrash(error, isJSON);
+		await toReported(error, isJSON, void 0, "fatal");
+	} catch {
+		process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
 	} finally {
 		process.exit(1);
 	}
@@ -51,4 +54,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=c2c38fd6-1925-561f-baf9-51faf8c4c4b8
+//# debugId=7a26fe4e-1a9f-538e-af63-a17134f6e803

package/dist/completion-tree.json

@@ -7,7 +7,7 @@
     },
     {
       "name": "api-key",
-      "description": "An API key to call with, in place of HARDFIN_API_KEY or a sign in",
+      "description": "An API key to call with. Prefer HARDFIN_API_KEY, because a command line is visible to other programs",
       "valueName": "key"
     },
     {

package/dist/{program-CqO1St9H.js → program-Bz-DwZDJ.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]="0a793a7f-2311-5aaf-b27d-0877574e2d18")}catch(e){}}();
-import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.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]="8bcae06e-d313-56ed-bc3e-49b505487fa3")}catch(e){}}();
+import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.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, Option } from "commander";
@@ -9,11 +9,11 @@ import { z } from "zod";
 import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseEnv } from "node:util";
+import { fileURLToPath } from "node:url";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
 import { createInterface as createInterface$1 } from "node:readline";
 //#region src/output/writer.ts
@@ -27,10 +27,21 @@ function toText(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")}`);
+}
 /** writeData prints a command's result on stdout. */
 function writeData(value) {
 	if (typeof value === "string") {
-		process.stdout.write(value.endsWith("\n") ? value : `${value}\n`);
+		const text = toPrintable(value);
+		process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
 		return;
 	}
 	process.stdout.write(`${JSON.stringify(value ?? null, null, 2)}\n`);
@@ -38,9 +49,9 @@ function writeData(value) {
 /** 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) {
 	if (!isJSON) {
-		process.stderr.write(`error: ${message}${status === void 0 ? "" : ` (HTTP ${status})`}\n`);
-		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${entry.error} (${entry.statusCode})\n`);
-		if (requestId) process.stderr.write(`  request ${requestId}\n`);
+		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 = {
@@ -155,6 +166,77 @@ var TimedOut = class extends ExpectedFailure {
 		this.name = "TimedOut";
 	}
 };
+/** 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. */
@@ -225,8 +307,23 @@ function toFileSettings(directory) {
 	}
 	return result.data;
 }
-/** The prefix of every variable this CLI reads, which is all an env file may set. */
-const VARIABLE_PREFIX = "HARDFIN_";
+/** 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
@@ -243,7 +340,7 @@ function loadEnvFile(directory) {
 	}
 	const supplied = /* @__PURE__ */ new Set();
 	for (const [name, value] of Object.entries(held)) {
-		if (!name.startsWith(VARIABLE_PREFIX) || value === void 0 || process.env[name] !== void 0) continue;
+		if (value === void 0 || process.env[name] !== void 0 || !isTakenFromFile(name, value)) continue;
 		process.env[name] = value;
 		supplied.add(name);
 	}
@@ -269,6 +366,19 @@ var Unreachable = class extends ExpectedFailure {
 		this.name = "Unreachable";
 	}
 };
+/** isLoopback reports whether a host is this machine. */
+function isLoopback(hostname) {
+	return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
+}
+/** isSecure answers whether a URL is https, or is this machine, where nothing sits in between. */
+function isSecure(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" || parsed.protocol === "http:" && isLoopback(parsed.hostname);
+	} catch {
+		return false;
+	}
+}
 const OFFLINE = "Couldn't connect to Hardfin. Check your internet connection and try again.";
 const INSECURE = "Couldn't connect to Hardfin securely, so nothing was sent. A work network or security software may be blocking the connection. If this keeps happening, contact your IT team.";
 /** The reasons Node gives, by the code on the error behind fetch's own. */
@@ -342,6 +452,12 @@ const REASONS = {
 		detail: "not an HTTPS server"
 	}
 };
+/**
+* How long the authorization server may take over its whole answer. Renewing a sign in comes
+* before the request a command was asked to make, so a slow renewal has to end, and say so,
+* well before a caller's own limit stops the command without a word.
+*/
+const SIGN_IN_TIMEOUT_MS = 15e3;
 /** How long a server may take to begin its answer, before the request is given up on. */
 const ANSWER_TIMEOUT_MS = 6e4;
 /**
@@ -350,15 +466,34 @@ const ANSWER_TIMEOUT_MS = 6e4;
 * would otherwise wait on a stalled connection for as long as it stayed open.
 */
 async function send(url, init, timeoutMs = ANSWER_TIMEOUT_MS) {
+	return await withDeadline(url, init, timeoutMs, (response) => Promise.resolve(response));
+}
+/**
+* sendForJSON asks the authorization server, and holds its whole answer to one short deadline.
+* A server that sends its headers and then stalls would otherwise keep a command waiting on
+* the body for as long as the connection stayed open.
+*/
+async function sendForJSON(url, init, timeoutMs = SIGN_IN_TIMEOUT_MS) {
+	return await withDeadline(url, init, timeoutMs, async (response, isOver) => {
+		return {
+			response,
+			body: await response.json().catch((error) => {
+				if (isOver()) throw error;
+			})
+		};
+	});
+}
+/** withDeadline makes one request, and gives up on it unless the work on its response ends in time. */
+async function withDeadline(url, init, timeoutMs, work) {
 	const deadline = new AbortController();
 	const timer = setTimeout(() => {
 		deadline.abort();
 	}, timeoutMs);
 	try {
-		return await fetch(url, {
+		return await work(await fetch(url, {
 			...init,
 			signal: init?.signal ? AbortSignal.any([init.signal, deadline.signal]) : deadline.signal
-		});
+		}), () => deadline.signal.aborted);
 	} catch (error) {
 		if (deadline.signal.aborted) throw toTimedOut(url, init?.method ?? "GET", timeoutMs);
 		throw toUnreachable(url, error);
@@ -440,11 +575,11 @@ async function revoke(revocationUrl, clientId, token) {
 			token,
 			token_type_hint: "refresh_token"
 		})
-	});
+	}, SIGN_IN_TIMEOUT_MS);
 }
 /** toTokens asks the token endpoint, which answers a flat RFC 6749 body, not the envelope. */
 async function toTokens(url, form) {
-	const response = await send(url, {
+	const answered = await sendForJSON(url, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/x-www-form-urlencoded",
@@ -452,7 +587,8 @@ async function toTokens(url, form) {
 		},
 		body: new URLSearchParams(form)
 	});
-	const body = await response.json().catch(() => void 0);
+	const response = answered.response;
+	const body = toRecord$1(answered.body);
 	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
 	const parsed = TokenResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
@@ -464,6 +600,10 @@ async function toTokens(url, form) {
 		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
 	};
 }
+/** toRecord reads a body as the object an OAuth answer is, and nothing for any other JSON. */
+function toRecord$1(body) {
+	return typeof body === "object" && body !== null && !Array.isArray(body) ? body : void 0;
+}
 //#endregion
 //#region src/credential/store.ts
 const load = createRequire(import.meta.url);
@@ -622,17 +762,31 @@ async function toMetadata(issuer, signal) {
 	const cached = toCached(issuer);
 	if (cached) return cached;
 	const url = `${issuer.replace(/\/+$/, "")}${METADATA_PATH}`;
-	const response = await send(url, {
+	const { response, body } = await sendForJSON(url, {
 		headers: { Accept: "application/json" },
 		signal
 	});
 	if (!response.ok) throw new DiscoveryFailure(`${url} answered ${response.status}, so this host publishes no authorization server`);
-	const parsed = AuthorizationServerMetadata.safeParse(await response.json().catch(() => void 0));
+	const parsed = AuthorizationServerMetadata.safeParse(body);
 	if (!parsed.success) throw new DiscoveryFailure(`${url} does not describe an authorization server`);
 	if (parsed.data.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new DiscoveryFailure(`${url} names issuer ${parsed.data.issuer}, which is not the host it was read from`);
+	const plain = toPlainEndpoint(parsed.data);
+	if (plain) throw new DiscoveryFailure(`${url} names ${plain}, which is not https, so nothing is sent to it`);
 	keep(issuer, parsed.data);
 	return parsed.data;
 }
+/**
+* toPlainEndpoint names an endpoint that would carry a code or a refresh token over a plain
+* connection. The document chooses every endpoint, so each is checked before any is used.
+*/
+function toPlainEndpoint(metadata) {
+	return [
+		metadata.authorization_endpoint,
+		metadata.token_endpoint,
+		metadata.revocation_endpoint,
+		metadata.device_authorization_endpoint
+	].find((endpoint) => endpoint !== void 0 && !isSecure(endpoint));
+}
 /** toCachePath names where one server's document is kept, beside the credentials. */
 function toCachePath(issuer) {
 	const name = createHash("sha256").update(issuer).digest("hex").slice(0, 16);
@@ -645,7 +799,7 @@ function toCached(issuer) {
 		const held = JSON.parse(readFileSync(path, "utf8"));
 		if ((held.readAt ?? 0) + CACHE_MS < Date.now()) return;
 		const parsed = AuthorizationServerMetadata.safeParse(held.document);
-		return parsed.success ? parsed.data : void 0;
+		return parsed.success && !toPlainEndpoint(parsed.data) ? parsed.data : void 0;
 	} catch {
 		return;
 	}
@@ -899,10 +1053,6 @@ function toHost$1(url) {
 		return;
 	}
 }
-/** isLoopback reports whether a host is this machine. */
-function isLoopback(hostname) {
-	return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
-}
 /**
 * toHeldCredential answers a credential without asking the server for one: the API key, or
 * an access token this process already holds. An error report uses it, because a refresh
@@ -996,7 +1146,12 @@ async function request$1(options) {
 /** toFileName reads the name a download was offered under, when the server names one. */
 function toFileName(disposition) {
 	const matched = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition ?? "");
-	return matched?.[1] ? decodeURIComponent(matched[1]) : void 0;
+	if (!matched?.[1]) return;
+	try {
+		return decodeURIComponent(matched[1]);
+	} catch {
+		return;
+	}
 }
 function toLeadingSlash(path) {
 	return path.startsWith("/") ? path : `/${path}`;
@@ -1016,6 +1171,35 @@ function toStatusMessage(status) {
 	return `the request failed with status ${status}`;
 }
 //#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/report/classify.ts
 /**
 * The codes Node gives when the machine refuses something: permissions, a full or read-only
@@ -1042,8 +1226,9 @@ function isReportable(error) {
 }
 /** isMachineRefusal answers whether an error is the machine refusing a file or a folder. */
 function isMachineRefusal(error) {
-	const code = error instanceof Error ? error.code : void 0;
-	return typeof code === "string" && ENVIRONMENT_CODES.has(code);
+	const { code, path } = error instanceof Error ? error : {};
+	if (typeof code !== "string" || !ENVIRONMENT_CODES.has(code)) return false;
+	return !(typeof path === "string" && isShipped(path));
 }
 //#endregion
 //#region src/output/failure.ts
@@ -1135,7 +1320,7 @@ function toGuide(commands, version) {
 		"",
 		"## Before calling",
 		"",
-		"- Authenticate with `--api-key`, by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
+		"- Authenticate by running `hardfin login`, or by setting `HARDFIN_API_KEY` in the environment. Do not pass a key as `--api-key`, because a command line is kept in transcripts and shown to other programs",
 		"- `hardfin login` writes one JSON line on stderr before it waits. Show the person its `url`, or its `userCode` and `verificationUri`, and let the command run for `waitSeconds`",
 		"- Every command prints JSON on stdout and diagnostics on stderr",
 		"- Output is JSON whenever stdout is not a terminal, so no flag is needed when calling from code",
@@ -1193,7 +1378,7 @@ function toCommandLines(command, parents) {
 }
 async function runAgentGuide(input) {
 	if (input.flags["json"] === true) {
-		writeData(input.commands.map(toSummary));
+		writeData(input.commands.filter((command) => !command.hidden).map(toSummary));
 		return ExitCode.OK;
 	}
 	writeData(toGuide(input.commands, version$1));
@@ -1374,26 +1559,41 @@ function isWSL() {
 	return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop");
 }
 /**
-* toOpeners lists the ways to open a URL here, best first. WSL needs Windows to do it,
+* toOpenable answers the address a browser may be sent to, and nothing for anything else. The
+* address comes from the authorization server, which a file in the working directory can
+* name, so it is parsed and written out again before any program is handed it.
+*/
+function toOpenable(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	const isLocal = parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+	return parsed.protocol === "https:" || isLocal ? parsed.href : void 0;
+}
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"[::1]",
+	"localhost"
+]);
+/**
+* toOpenerList lists the ways to open a URL here, best first. WSL needs Windows to do it,
 * because the browser the person is looking at is the Windows one, and xdg-open reaches
 * nothing outside the distribution.
 */
-function toOpeners(url) {
-	if (process.platform === "darwin") return [["open", [url]]];
-	if (process.platform === "win32") return [["cmd", [
-		"/c",
-		"start",
-		"",
-		url
-	]]];
-	if (isWSL()) return [
+function toOpenerList(url, platform = process.platform, isInsideWSL = isWSL()) {
+	if (platform === "darwin") return [["open", [url]]];
+	if (platform === "win32") return [["rundll32.exe", ["url.dll,FileProtocolHandler", url]]];
+	if (isInsideWSL) return [
 		["wslview", [url]],
 		["powershell.exe", [
 			"-NoProfile",
 			"-NonInteractive",
 			"-Command",
 			"Start-Process",
-			`'${url}'`
+			`'${url.replaceAll("'", "''")}'`
 		]],
 		["explorer.exe", [url]]
 	];
@@ -1401,7 +1601,9 @@ function toOpeners(url) {
 }
 /** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
 function openBrowser(url, launch = spawnSync) {
-	for (const [command, args] of toOpeners(url)) if (launch(command, args, {
+	const openable = toOpenable(url);
+	if (openable === void 0) return false;
+	for (const [command, args] of toOpenerList(openable)) if (launch(command, args, {
 		stdio: "ignore",
 		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
 		timeout: 1e4
@@ -2161,14 +2363,6 @@ function toFiles(directory) {
 		return statSync(path).isDirectory() ? toFiles(path) : [path];
 	});
 }
-/** 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");
-	}
-}
 //#endregion
 //#region src/command/types.generated.ts
 /** API_TYPES is the TypeScript hardfin types prints. */
@@ -2229,7 +2423,7 @@ const DeviceResponse = z.looseObject({
 });
 /** toDeviceAuthorization asks for a code a person can type on another machine. */
 async function toDeviceAuthorization(endpoint, clientId, scope) {
-	const response = await send(endpoint, {
+	const answered = await sendForJSON(endpoint, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/x-www-form-urlencoded",
@@ -2240,7 +2434,8 @@ async function toDeviceAuthorization(endpoint, clientId, scope) {
 			scope
 		})
 	});
-	const body = await response.json().catch(() => void 0);
+	const response = answered.response;
+	const body = toRecord$1(answered.body);
 	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
 	const parsed = DeviceResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the device endpoint did not answer with a code");
@@ -2291,7 +2486,7 @@ const HOST = "127.0.0.1";
 * the machine hands out, which is why the server matches a loopback redirect by everything
 * except its port.
 */
-async function toListener(timeoutMs) {
+async function toListener(timeoutMs, state) {
 	let settle = () => {};
 	let fail = () => {};
 	const callback = new Promise((resolve, reject) => {
@@ -2304,7 +2499,11 @@ async function toListener(timeoutMs) {
 			response.writeHead(404).end();
 			return;
 		}
-		writePage(response, answered);
+		if (!isOurs(answered, state)) {
+			writePage(response, 400, "Not this sign in", "This page did not come from the sign in your terminal started.");
+			return;
+		}
+		writeOutcome(response, answered);
 		settle(answered);
 	});
 	await new Promise((resolve, reject) => {
@@ -2337,10 +2536,33 @@ function toCallback(request) {
 		errorDescription: url.searchParams.get("error_description") ?? void 0
 	};
 }
-function writePage(response, callback) {
-	const title = callback.error ? "Sign in refused" : "Signed in";
-	const detail = callback.error ? `${callback.error}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}` : "You can close this tab and return to your terminal.";
-	response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body style="font-family: system-ui, sans-serif; padding: 3rem; max-width: 34rem"><h1 style="font-size: 1.25rem">${title}</h1><p>${detail}</p></body></html>`);
+/**
+* isOurs answers whether a response belongs to this sign in. A refusal with no state at all
+* is still taken, because not every authorization server sends the state back with one.
+*/
+function isOurs(callback, state) {
+	if (callback.state !== void 0) return callback.state === state;
+	return callback.code === void 0 && callback.error !== void 0;
+}
+function writeOutcome(response, callback) {
+	if (!callback.error) {
+		writePage(response, 200, "Signed in", "You can close this tab and return to your terminal.");
+		return;
+	}
+	writePage(response, 200, "Sign in refused", `${callback.error}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}`);
+}
+/** toEscaped makes text safe to put in a page, because the words of a refusal come from the URL. */
+function toEscaped(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+}
+function writePage(response, status, heading, words) {
+	const title = toEscaped(heading);
+	const detail = toEscaped(words);
+	response.writeHead(status, {
+		"Content-Type": "text/html; charset=utf-8",
+		"Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+		"X-Content-Type-Options": "nosniff"
+	}).end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body style="font-family: system-ui, sans-serif; padding: 3rem; max-width: 34rem"><h1 style="font-size: 1.25rem">${title}</h1><p>${detail}</p></body></html>`);
 }
 function close(server, timer) {
 	clearTimeout(timer);
@@ -2528,9 +2750,9 @@ async function runLogin(input) {
 		const metadata = await toMetadata(settings.issuerUrl);
 		const scope = toText(input.flags["scope"] ?? DEFAULT_SCOPES);
 		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
-		const listener = await toListener(WAIT_MS);
-		const pkce = toPkce();
 		const state = toState();
+		const listener = await toListener(WAIT_MS, state);
+		const pkce = toPkce();
 		const url = toAuthorizationUrl(metadata.authorization_endpoint, {
 			clientId,
 			redirectUri: listener.redirectUri,
@@ -2601,8 +2823,8 @@ async function runDeviceLogin(input, metadata, scope) {
 	});
 	else process.stderr.write([
 		"",
-		`  Code  ${device.userCode}`,
-		`  At    ${device.verificationUri}`,
+		`  Code  ${toPrintable(device.userCode)}`,
+		`  At    ${toPrintable(device.verificationUri)}`,
 		"",
 		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
 	].join("\n"));
@@ -2787,7 +3009,7 @@ function defineOperation(operation) {
 async function runOperation(operation, input) {
 	const path = toPath(operation, input.args);
 	if (path === void 0) {
-		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
+		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s), each the key of a record`, input.isJSON);
 		return ExitCode.USAGE;
 	}
 	const given = toGivenBody(input.flags["input"]);
@@ -2850,7 +3072,12 @@ async function runOperation(operation, input) {
 */
 function toWritten(download, input) {
 	const asked = input.flags["output"];
-	const path = typeof asked === "string" ? asked : download.fileName ?? "-";
+	const offered = typeof asked === "string" ? void 0 : download.fileName;
+	const path = typeof asked === "string" ? asked : offered === void 0 ? "-" : toLocalName(offered);
+	if (path === void 0 || offered !== void 0 && existsSync(path)) {
+		writeFailure("output_required", path === void 0 ? `this file is offered as ${JSON.stringify(offered)}, which is not a name to write here, so name where to write it with --output` : `${path} already exists, so name where to write this file with --output`, input.isJSON);
+		return ExitCode.USAGE;
+	}
 	if (path === "-") {
 		if (process.stdout.isTTY) {
 			writeFailure("output_required", "this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
@@ -2867,9 +3094,20 @@ function toWritten(download, input) {
 	});
 	return ExitCode.OK;
 }
+/** toLocalName reduces a name the API offered to one file in the working directory, or to nothing. */
+function toLocalName(offered) {
+	const name = offered.split(/[\\/]/).pop() ?? "";
+	return name === "" || name.startsWith(".") ? void 0 : name;
+}
+/** The arguments a URL reads as "this folder" and "the one above", and one that names nothing. */
+const NOT_A_KEY = /* @__PURE__ */ new Set([
+	"",
+	".",
+	".."
+]);
 /** toPath fills the path template from the positional arguments, in order. */
 function toPath(operation, args) {
-	if (args.length !== operation.pathParameters.length) return;
+	if (args.length !== operation.pathParameters.length || args.some((argument) => NOT_A_KEY.has(argument))) return;
 	let path = operation.path;
 	for (const [index, parameter] of operation.pathParameters.entries()) path = path.replace(`{${parameter.name}}`, encodeURIComponent(args[index] ?? ""));
 	return path;
@@ -3007,6 +3245,10 @@ function toRefusedPath(flag, path, isWritten, root = process.cwd()) {
 	if (isWithin(toReal(dirname(toCredentialPath())), target)) return refuse("it is where the sign in is kept");
 	if (isWritten && existsSync(target)) return refuse("it already exists, and a call does not overwrite a file");
 }
+/** isInsideFolder answers whether a path is the folder the server runs in, or sits inside it. */
+function isInsideFolder(path, root = process.cwd()) {
+	return isWithin(toReal(root), toReal(resolve(root, path)));
+}
 /** toEnvFile names the env file a person pointed the CLI at, when they did. */
 function toEnvFile(root) {
 	const named = process.env["HARDFIN_ENV_FILE"];
@@ -3026,76 +3268,6 @@ function toReal(path) {
 	const parent = dirname(path);
 	return parent === path ? path : join(toReal(parent), basename(path));
 }
-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/system/host.ts
 const BYTES_PER_GB = 1024 ** 3;
@@ -3402,7 +3574,7 @@ async function report(error, occasion, resolved) {
 	try {
 		const status = settings ? await toStatus(settings) : void 0;
 		const secrets = [settings?.settings.apiKey, settings ? toCredential(settings.settings.issuerUrl)?.refreshToken : void 0];
-		return await (await import("./sentry-BM9Rvhhy.js")).send({
+		return await (await import("./sentry-e3Tum2kz.js")).send({
 			error,
 			occasion,
 			telemetry,
@@ -3621,7 +3793,7 @@ function toResource(uri, commands) {
 }
 /** toTree names every command and what it takes, without the schemas a tool list would carry. */
 function toTree(commands) {
-	return commands.map((command) => ({
+	return commands.filter((command) => !command.hidden).map((command) => ({
 		name: command.name,
 		summary: command.summary,
 		arguments: command.arguments.map((argument) => argument.name),
@@ -3629,11 +3801,16 @@ function toTree(commands) {
 		subcommands: command.subcommands ? toTree(command.subcommands) : void 0
 	}));
 }
-/** Signing in needs a browser and a person, neither of which an agent's session has. */
-const REFUSED_COMMANDS = /* @__PURE__ */ new Set([
-	"login",
-	"logout",
-	"mcp"
+/**
+* The commands a person runs themselves, each by the words that run it. Signing in needs a
+* browser and a person, and installing completion changes the startup file of their shell.
+*/
+const REFUSED_COMMANDS = /* @__PURE__ */ new Map([
+	["login", "login"],
+	["logout", "logout"],
+	["mcp", "mcp"],
+	["install", "completion install"],
+	["uninstall", "completion uninstall"]
 ]);
 /**
 * toParsed asks the CLI's own parser what a call would run, without running it. The server
@@ -3672,7 +3849,8 @@ function toFixedOption(parsed) {
 */
 function toRefusedFile(parsed) {
 	if (!parsed.ran) return;
-	const { command, flags } = parsed.ran;
+	const { command, args, flags } = parsed.ran;
+	if (command.name === "init" && args[0] !== void 0 && !isInsideFolder(args[0])) return `init cannot set up ${args[0]}, because it is outside the folder this server runs in. A person can run hardfin init there themselves`;
 	for (const flag of command.flags.filter((entry) => PATH_VALUES.has(entry.valueName ?? ""))) {
 		const path = flags[toOptionKey(flag.name)];
 		const isWritten = flag.name === "output";
@@ -3697,18 +3875,44 @@ async function toToolResult(request, commands, run) {
 	if (fixed) return toError(fixed);
 	const confined = toRefusedFile(parsed);
 	if (confined) return toError(confined);
-	const command = parsed.ran?.command.name ?? "";
-	if (REFUSED_COMMANDS.has(command)) return toError(`${command} is run by a person at a terminal, not through this server. Run hardfin ${command} yourself, then call this tool again`);
+	const command = REFUSED_COMMANDS.get(parsed.ran?.command.name ?? "");
+	if (command !== void 0) return toError(`${command} is run by a person at a terminal, not through this server. Run hardfin ${command} yourself, then call this tool again`);
 	if (name === READ_TOOL.name && toAccessOf(parsed) === "write") return toError(`this command changes data, so it runs through ${WRITE_TOOL.name}`);
 	const outcome = await run(asked, called?.input);
+	const text = toBounded([outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n"));
+	const failure = outcome.code === 0 ? void 0 : toFailure(outcome);
 	return {
 		content: [{
 			type: "text",
-			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
+			text: text || `hardfin exited ${outcome.code}`
 		}],
-		isError: outcome.code !== 0
+		isError: outcome.code !== 0,
+		...failure ? { structuredContent: failure } : {}
 	};
 }
+/** The most text one result carries, because every character of it sits in the agent's context. */
+const RESULT_CHARACTERS = 2e5;
+/** toBounded cuts a result that is too long to be useful, and says that it did. */
+function toBounded(text, limit = RESULT_CHARACTERS) {
+	if (text.length <= limit) return text;
+	return `${text.slice(0, limit)}\n\n[This result was cut at ${limit} of ${text.length} characters, so it is not complete and may not parse. Ask for less, with --limit, --page or a filter]`;
+}
+/**
+* toFailure reads the failure a command printed, so a client can branch on its code without
+* parsing text. A command that printed anything else beside it answers with the text alone.
+*/
+function toFailure(outcome) {
+	try {
+		const parsed = JSON.parse(outcome.stderr);
+		if (typeof parsed !== "object" || parsed === null || typeof parsed.code !== "string") return;
+		return {
+			...parsed,
+			exitCode: outcome.code
+		};
+	} catch {
+		return;
+	}
+}
 function toError(text) {
 	return {
 		content: [{
@@ -3792,35 +3996,72 @@ function toRun(entry, args, input, timeoutMs) {
 			});
 			return;
 		}
-		let stdout = "";
-		let stderr = "";
+		const stdout = toCollector();
+		const stderr = toCollector();
 		let isTimedOut = false;
 		const timer = setTimeout(() => {
 			isTimedOut = true;
 			child.kill("SIGKILL");
 		}, timeoutMs);
-		child.stdout.on("data", (chunk) => {
-			stdout += chunk.toString();
-		});
-		child.stderr.on("data", (chunk) => {
-			stderr += chunk.toString();
-		});
+		child.stdout.on("data", stdout.take);
+		child.stderr.on("data", stderr.take);
 		child.on("error", (error) => {
-			stderr += `the command could not start: ${error.message}\n`;
+			stderr.take(Buffer.from(`the command could not start: ${error.message}\n`));
 		});
 		child.on("close", (code) => {
 			clearTimeout(timer);
-			if (isTimedOut) stderr += `this command took longer than ${timeoutMs / 1e3} seconds, so it was stopped\n`;
+			if (isTimedOut) stderr.take(Buffer.from(`this command took longer than ${timeoutMs / 1e3} seconds, so it was stopped\n`));
+			const printed = stdout.toText();
+			const said = stderr.toText() ?? "";
+			const ended = isTimedOut ? 1 : code ?? 1;
+			if (printed !== void 0) {
+				resolve({
+					stdout: printed,
+					stderr: said,
+					code: ended
+				});
+				return;
+			}
 			resolve({
-				stdout,
-				stderr,
-				code: isTimedOut ? 1 : code ?? 1
+				stdout: "",
+				stderr: ended === 0 ? `${said}this answer is ${stdout.bytes()} bytes that are not text, so it cannot be read here. Keep it with --output and a new file name, through ${WRITE_TOOL.name}\n` : said,
+				code: ended || 1
 			});
 		});
 		child.stdin.on("error", () => void 0);
 		child.stdin.end(input ?? "");
 	});
 }
+/** The most output kept from one command, well past what a result carries, so memory stays bounded. */
+const KEPT_BYTES = 4 * RESULT_CHARACTERS;
+/**
+* toCollector gathers what a command prints as bytes. Decoding each chunk on its own would
+* split a character that straddles two chunks, and would hide that a file is not text.
+*/
+function toCollector() {
+	const chunks = [];
+	let kept = 0;
+	let seen = 0;
+	return {
+		take: (chunk) => {
+			seen += chunk.length;
+			if (kept < KEPT_BYTES) {
+				chunks.push(chunk);
+				kept += chunk.length;
+			}
+		},
+		bytes: () => seen,
+		toText: () => {
+			let text;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks), { stream: true });
+			} catch {
+				return;
+			}
+			return seen > kept ? `${text}\n[${seen - kept} more bytes were not kept]` : text;
+		}
+	};
+}
 /** serve answers requests on stdin until the client closes it. */
 async function serve(commands, run = toCliRunner()) {
 	const lines = createInterface$1({ input: process.stdin });
@@ -6674,6 +6915,10 @@ async function toExitCode(globals, command, args, flags) {
 		return error instanceof ConfigFailure ? ExitCode.USAGE : ExitCode.ERROR;
 	}
 }
+/** writeCrash answers an error nothing caught, in the form the caller reads. */
+function writeCrash(error, isJSON) {
+	writeFailure(toErrorCode(error), error instanceof Error ? error.message : String(error), isJSON);
+}
 /** toReported reports a defect, and tells a person at a terminal that it was reported. */
 async function toReported(error, isJSON, resolved, level = "error") {
 	const invocation = toInvocation(commands, process.argv.slice(2));
@@ -6687,7 +6932,7 @@ async function toReported(error, isJSON, resolved, level = "error") {
 	if (id && !isJSON) process.stderr.write(`This looks like a problem in hardfin itself, and it has been reported to the Hardfin team. Reference: ${id}\n`);
 }
 //#endregion
-export { toCli, toParseExitCode, toReported, wasReportAttempted };
+export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-CqO1St9H.js.map
-//# debugId=0a793a7f-2311-5aaf-b27d-0877574e2d18
+//# sourceMappingURL=program-Bz-DwZDJ.js.map
+//# debugId=8bcae06e-d313-56ed-bc3e-49b505487fa3

package/dist/{scrub-BN3gyBpR.js → scrub-BZ0egWxC.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]="3af5060a-b6fe-5f2e-9661-01f4460a7b04")}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]="76640861-61e5-5004-ae78-dee93e00338f")}catch(e){}}();
 import { z } from "zod";
 import { homedir } from "node:os";
 //#region src/command/registry.ts
@@ -26,7 +26,7 @@ const GLOBAL_FLAGS = [
 	},
 	{
 		name: "api-key",
-		description: "An API key to call with, in place of HARDFIN_API_KEY or a sign in",
+		description: "An API key to call with. Prefer HARDFIN_API_KEY, because a command line is visible to other programs",
 		valueName: "key",
 		schema: z.string()
 	},
@@ -118,5 +118,5 @@ function toFlag(flags, word) {
 //#endregion
 export { defineCommand as a, GLOBAL_FLAGS as i, toScrubbed as n, ExitCode as r, toInvocation as t };
 
-//# sourceMappingURL=scrub-BN3gyBpR.js.map
-//# debugId=3af5060a-b6fe-5f2e-9661-01f4460a7b04
+//# sourceMappingURL=scrub-BZ0egWxC.js.map
+//# debugId=76640861-61e5-5004-ae78-dee93e00338f

package/dist/{sentry-BM9Rvhhy.js → sentry-e3Tum2kz.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]="35c80804-dcd8-5662-9f00-9c8ff04f286a")}catch(e){}}();
-import { n as toScrubbed } from "./scrub-BN3gyBpR.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]="12bc3b97-183e-5e0e-84a2-4353d0ade50b")}catch(e){}}();
+import { n as toScrubbed } from "./scrub-BZ0egWxC.js";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { request } from "node:http";
@@ -4385,5 +4385,5 @@ function toTags(delivery) {
 //#endregion
 export { send };
 
-//# sourceMappingURL=sentry-BM9Rvhhy.js.map
-//# debugId=35c80804-dcd8-5662-9f00-9c8ff04f286a
+//# sourceMappingURL=sentry-e3Tum2kz.js.map
+//# debugId=12bc3b97-183e-5e0e-84a2-4353d0ade50b

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.1-dev.42",
+    "version": "0.1.1-dev.45",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -29,7 +29,7 @@
         "templates"
     ],
     "engines": {
-        "node": ">=20"
+        "node": ">=20.12"
     },
     "publishConfig": {
         "access": "public"

package/skills/hardfin-cli/SKILL.md

@@ -17,7 +17,7 @@ flags, so check `--help` before relying on a flag this skill does not show.
 hardfin --version || npm install -g @hardfin/cli
 ```
 
-It needs Node 20 or later. If `npm install -g` is refused, run commands as
+It needs Node 20.12 or later. If `npm install -g` is refused, run commands as
 `npx -y @hardfin/cli <command>` instead.
 
 ## 2. Make sure it is signed in
@@ -28,11 +28,11 @@ hardfin status --offline --json
 
 `credential.kind` is `none` when nobody is signed in. Then sign in one of three ways.
 
-| Situation                                                  | Do this                                          |
-| ---------------------------------------------------------- | ------------------------------------------------ |
-| You run on the person's own machine                        | Run `hardfin login` in the foreground            |
-| You run in a cloud sandbox, away from the person's browser | Run `hardfin login --device`                     |
-| The person gave you an API key                             | Pass `--api-key <key>`, or set `HARDFIN_API_KEY` |
+| Situation                                                  | Do this                                  |
+| ---------------------------------------------------------- | ---------------------------------------- |
+| You run on the person's own machine                        | Run `hardfin login` in the foreground    |
+| You run in a cloud sandbox, away from the person's browser | Run `hardfin login --device`             |
+| The person gave you an API key                             | Set `HARDFIN_API_KEY` in the environment |
 
 `hardfin login` writes one JSON line on stderr before it waits:
 
@@ -44,7 +44,9 @@ hardfin status --offline --json
 It then waits up to `waitSeconds` (300) for the person to approve. Give the command that
 long to finish. Do not run it in the background and move on.
 
-Never write an API key into a file in the repository, and never echo it back.
+Never write an API key into a file in the repository, and never echo it back. Never pass it
+as `--api-key` either, because a command line is kept in transcripts and shown to other
+programs on the machine.
 
 ## 3. Find the command
 

package/templates/AGENTS.md

@@ -4,7 +4,7 @@ This project works with Hardfin data through the Hardfin CLI, `hardfin`.
 
 | Task                               | Command                                                                      |
 | ---------------------------------- | ---------------------------------------------------------------------------- |
-| Install                            | `npm install -g @hardfin/cli`, with Node 20 or later                         |
+| Install                            | `npm install -g @hardfin/cli`, with Node 20.12 or later                      |
 | Sign in                            | `hardfin login`, or `--device` away from a browser, or set `HARDFIN_API_KEY` |
 | Check what it is connected to      | `hardfin status`                                                             |
 | Find a command                     | `hardfin --help`, then `hardfin <noun> --help`                               |