@hardfin/cli 0.1.1-dev.41 → 0.1.1-dev.44

package/README.md

@@ -71,6 +71,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
@@ -109,6 +112,17 @@ stderr, so a pipe still carries only the result.
 | `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 |
 
+Three codes cover failures that are easy to mistake for something else.
+
+| `code`                | Happens when                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| `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                                           |
+
+A change that timed out may still have been made, and the message says so. Read the record
+before sending the change again.
+
 An agent branches on `code`. A code is never renamed and never changes meaning, while the
 message may be reworded at any time. `hardfin agent-guide` lists every code with what it
 means, and `src/output/failure.ts` defines them.
@@ -205,6 +219,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.
 
@@ -390,6 +409,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
 
@@ -405,6 +435,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.
 
@@ -442,6 +475,10 @@ Nothing secret is printed. An API key and a refresh token are each reported as a
 `sha256:` fingerprint, which identifies a credential across two machines without disclosing
 it.
 
+`api.authenticated` is `true` only when the API answered who the credential is. A 401 or a
+403 makes it `false`, and `hardfin status` then exits with code 4. It is `null` when the API
+could not be asked, because no answer says nothing about the credential.
+
 `refreshExpiresAt` is what the server said when it issued the token. A sign in stored before
 the server reported one falls back to Hardfin's 90-day rule, and `refreshExpiryIsEstimated`
 says which of the two you are looking at.

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]="12877cfa-09aa-5239-8a24-ecc77a951641")}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]="641b3aa6-1d59-5f9c-b2f3-0bf132c35831")}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-C1-jZp6K.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CgT1Kr8L.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
 	try {
-		const { toReported } = await import("./program-C1-jZp6K.js");
+		const { toReported } = await import("./program-CgT1Kr8L.js");
 		await toReported(error, false, void 0, "fatal");
 	} finally {
 		process.exit(1);
@@ -51,4 +51,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=12877cfa-09aa-5239-8a24-ecc77a951641
+//# debugId=641b3aa6-1d59-5f9c-b2f3-0bf132c35831

package/dist/{program-C1-jZp6K.js → program-CgT1Kr8L.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]="8cef3750-26c4-5378-89b9-1b3b5b7aaaa7")}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]="2c607b02-61ea-5376-957f-d434d5692ac5")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
@@ -261,30 +261,238 @@ function toOrigin(apiUrl) {
 	}
 }
 //#endregion
-//#region src/auth/jwt.ts
+//#region src/http/reach.ts
+/** Unreachable is a request that never reached a server, so there is no answer to report. */
+var Unreachable = class extends ExpectedFailure {
+	constructor(message) {
+		super(message);
+		this.name = "Unreachable";
+	}
+};
+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. */
+const REASONS = {
+	ECONNREFUSED: {
+		message: OFFLINE,
+		detail: "connection refused"
+	},
+	ENOTFOUND: {
+		message: OFFLINE,
+		detail: "address not found"
+	},
+	EAI_AGAIN: {
+		message: OFFLINE,
+		detail: "address lookup failed"
+	},
+	ETIMEDOUT: {
+		message: OFFLINE,
+		detail: "timed out"
+	},
+	UND_ERR_CONNECT_TIMEOUT: {
+		message: OFFLINE,
+		detail: "timed out"
+	},
+	EHOSTUNREACH: {
+		message: OFFLINE,
+		detail: "no route to host"
+	},
+	ENETUNREACH: {
+		message: OFFLINE,
+		detail: "network unreachable"
+	},
+	ECONNRESET: {
+		message: OFFLINE,
+		detail: "connection closed"
+	},
+	UND_ERR_SOCKET: {
+		message: OFFLINE,
+		detail: "connection closed"
+	},
+	DEPTH_ZERO_SELF_SIGNED_CERT: {
+		message: INSECURE,
+		detail: "certificate not trusted"
+	},
+	SELF_SIGNED_CERT_IN_CHAIN: {
+		message: INSECURE,
+		detail: "certificate not trusted"
+	},
+	UNABLE_TO_VERIFY_LEAF_SIGNATURE: {
+		message: INSECURE,
+		detail: "certificate not trusted"
+	},
+	UNABLE_TO_GET_ISSUER_CERT_LOCALLY: {
+		message: INSECURE,
+		detail: "certificate not trusted"
+	},
+	CERT_HAS_EXPIRED: {
+		message: INSECURE,
+		detail: "certificate expired"
+	},
+	ERR_TLS_CERT_ALTNAME_INVALID: {
+		message: INSECURE,
+		detail: "certificate is for another host"
+	},
+	ERR_SSL_WRONG_VERSION_NUMBER: {
+		message: OFFLINE,
+		detail: "not an HTTPS server"
+	},
+	EPROTO: {
+		message: OFFLINE,
+		detail: "not an HTTPS server"
+	}
+};
 /**
-* toClaims reads an access token's payload for display. Nothing here verifies the
-* signature, because the API is what decides whether a token is good.
+* 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.
 */
-function toClaims(token) {
-	const payload = token.split(".")[1];
-	if (!payload) return {};
-	try {
-		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+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;
+/**
+* send is fetch, with a failure to connect reported in words anyone can act on. It gives up
+* on a server that has not begun to answer in time, because a caller with no person watching
+* 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 {
-			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
-			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
-			scopes: toScopes(decoded),
-			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+			response,
+			body: await response.json().catch((error) => {
+				if (isOver()) throw error;
+			})
 		};
-	} catch {
-		return {};
+	});
+}
+/** 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 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);
+	} finally {
+		clearTimeout(timer);
 	}
 }
-/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
-function toScopes(decoded) {
-	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
-	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
+/** toTimedOut describes a request given up on, and says when it may have gone through anyway. */
+function toTimedOut(url, method, timeoutMs) {
+	const waited = `${new URL(url).host} did not answer within ${timeoutMs / 1e3} seconds`;
+	return new TimedOut(["GET", "HEAD"].includes(method.toUpperCase()) ? waited : `${waited}. The change may still have been made, so read the record before sending it again`);
+}
+/**
+* toUnreachable describes a request that could not connect. Fetch reports every such failure
+* as "fetch failed", and the reason is on the error it wraps. The person reads a plain
+* message, and the line after it names the reason and host for whoever helps them.
+*/
+function toUnreachable(url, error) {
+	const host = new URL(url).host;
+	const cause = error instanceof Error ? error.cause : void 0;
+	const code = cause instanceof Error ? cause.code : void 0;
+	const reason = (error instanceof Error && error.name === "TimeoutError" ? REASONS["ETIMEDOUT"] : code === void 0 ? void 0 : REASONS[code]) ?? {
+		message: OFFLINE,
+		detail: cause instanceof Error ? cause.message : error instanceof Error ? error.message : String(error)
+	};
+	return new Unreachable(`${reason.message}\nDetails: ${reason.detail} (${host})`);
+}
+//#endregion
+//#region src/auth/grant.ts
+const TokenResponse = z.looseObject({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	refresh_token_expires_in: z.number().optional(),
+	scope: z.string().optional()
+});
+/** GrantFailure is a token request the authorization server refused. */
+var GrantFailure = class extends ExpectedFailure {
+	code;
+	constructor(code, description) {
+		super(description ? `${code}: ${description}` : code);
+		this.name = "GrantFailure";
+		this.code = code;
+	}
+};
+/** SignInStopped is a sign in the person ended themselves, in a way other than Ctrl-C. */
+var SignInStopped = class extends ExpectedFailure {
+	constructor(message) {
+		super(message);
+		this.name = "SignInStopped";
+	}
+};
+/** toTokensFromCode trades an authorization code for tokens. */
+async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
+	return await toTokens(tokenUrl, {
+		grant_type: "authorization_code",
+		client_id: clientId,
+		code,
+		redirect_uri: redirectUri,
+		code_verifier: pkce.verifier
+	});
+}
+/** toTokensFromRefresh trades a refresh token for a fresh pair. */
+async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
+	return await toTokens(tokenUrl, {
+		grant_type: "refresh_token",
+		client_id: clientId,
+		refresh_token: refreshToken
+	});
+}
+/** revoke tells the server to forget a token, so signing out reaches every machine. */
+async function revoke(revocationUrl, clientId, token) {
+	await send(revocationUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: clientId,
+			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 answered = await sendForJSON(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams(form)
+	});
+	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");
+	return {
+		accessToken: parsed.data.access_token,
+		refreshToken: parsed.data.refresh_token,
+		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
+		scope: parsed.data.scope,
+		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
@@ -418,111 +626,6 @@ function writeFile(held) {
 	renameSync(pending, path);
 }
 //#endregion
-//#region src/http/reach.ts
-/** Unreachable is a request that never reached a server, so there is no answer to report. */
-var Unreachable = class extends ExpectedFailure {
-	constructor(message) {
-		super(message);
-		this.name = "Unreachable";
-	}
-};
-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. */
-const REASONS = {
-	ECONNREFUSED: {
-		message: OFFLINE,
-		detail: "connection refused"
-	},
-	ENOTFOUND: {
-		message: OFFLINE,
-		detail: "address not found"
-	},
-	EAI_AGAIN: {
-		message: OFFLINE,
-		detail: "address lookup failed"
-	},
-	ETIMEDOUT: {
-		message: OFFLINE,
-		detail: "timed out"
-	},
-	UND_ERR_CONNECT_TIMEOUT: {
-		message: OFFLINE,
-		detail: "timed out"
-	},
-	EHOSTUNREACH: {
-		message: OFFLINE,
-		detail: "no route to host"
-	},
-	ENETUNREACH: {
-		message: OFFLINE,
-		detail: "network unreachable"
-	},
-	ECONNRESET: {
-		message: OFFLINE,
-		detail: "connection closed"
-	},
-	UND_ERR_SOCKET: {
-		message: OFFLINE,
-		detail: "connection closed"
-	},
-	DEPTH_ZERO_SELF_SIGNED_CERT: {
-		message: INSECURE,
-		detail: "certificate not trusted"
-	},
-	SELF_SIGNED_CERT_IN_CHAIN: {
-		message: INSECURE,
-		detail: "certificate not trusted"
-	},
-	UNABLE_TO_VERIFY_LEAF_SIGNATURE: {
-		message: INSECURE,
-		detail: "certificate not trusted"
-	},
-	UNABLE_TO_GET_ISSUER_CERT_LOCALLY: {
-		message: INSECURE,
-		detail: "certificate not trusted"
-	},
-	CERT_HAS_EXPIRED: {
-		message: INSECURE,
-		detail: "certificate expired"
-	},
-	ERR_TLS_CERT_ALTNAME_INVALID: {
-		message: INSECURE,
-		detail: "certificate is for another host"
-	},
-	ERR_SSL_WRONG_VERSION_NUMBER: {
-		message: OFFLINE,
-		detail: "not an HTTPS server"
-	},
-	EPROTO: {
-		message: OFFLINE,
-		detail: "not an HTTPS server"
-	}
-};
-/** send is fetch, with a failure to connect reported in words anyone can act on. */
-async function send(url, init) {
-	try {
-		return await fetch(url, init);
-	} catch (error) {
-		throw toUnreachable(url, error);
-	}
-}
-/**
-* toUnreachable describes a request that could not connect. Fetch reports every such failure
-* as "fetch failed", and the reason is on the error it wraps. The person reads a plain
-* message, and the line after it names the reason and host for whoever helps them.
-*/
-function toUnreachable(url, error) {
-	const host = new URL(url).host;
-	const cause = error instanceof Error ? error.cause : void 0;
-	const code = cause instanceof Error ? cause.code : void 0;
-	const reason = (error instanceof Error && error.name === "TimeoutError" ? REASONS["ETIMEDOUT"] : code === void 0 ? void 0 : REASONS[code]) ?? {
-		message: OFFLINE,
-		detail: cause instanceof Error ? cause.message : error instanceof Error ? error.message : String(error)
-	};
-	return new Unreachable(`${reason.message}\nDetails: ${reason.detail} (${host})`);
-}
-//#endregion
 //#region src/auth/metadata.ts
 const METADATA_PATH = "/.well-known/oauth-authorization-server";
 const AuthorizationServerMetadata = z.looseObject({
@@ -549,12 +652,12 @@ 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`);
 	keep(issuer, parsed.data);
@@ -591,75 +694,30 @@ function keep(issuer, document) {
 	} catch {}
 }
 //#endregion
-//#region src/auth/grant.ts
-const TokenResponse = z.looseObject({
-	access_token: z.string(),
-	token_type: z.string(),
-	expires_in: z.number().optional(),
-	refresh_token: z.string().optional(),
-	refresh_token_expires_in: z.number().optional(),
-	scope: z.string().optional()
-});
-/** GrantFailure is a token request the authorization server refused. */
-var GrantFailure = class extends ExpectedFailure {
-	code;
-	constructor(code, description) {
-		super(description ? `${code}: ${description}` : code);
-		this.name = "GrantFailure";
-		this.code = code;
+//#region src/auth/jwt.ts
+/**
+* toClaims reads an access token's payload for display. Nothing here verifies the
+* signature, because the API is what decides whether a token is good.
+*/
+function toClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return {
+			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
+			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
+			scopes: toScopes(decoded),
+			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+		};
+	} catch {
+		return {};
 	}
-};
-/** toTokensFromCode trades an authorization code for tokens. */
-async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
-	return await toTokens(tokenUrl, {
-		grant_type: "authorization_code",
-		client_id: clientId,
-		code,
-		redirect_uri: redirectUri,
-		code_verifier: pkce.verifier
-	});
 }
-/** toTokensFromRefresh trades a refresh token for a fresh pair. */
-async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
-	return await toTokens(tokenUrl, {
-		grant_type: "refresh_token",
-		client_id: clientId,
-		refresh_token: refreshToken
-	});
-}
-/** revoke tells the server to forget a token, so signing out reaches every machine. */
-async function revoke(revocationUrl, clientId, token) {
-	await send(revocationUrl, {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: new URLSearchParams({
-			client_id: clientId,
-			token,
-			token_type_hint: "refresh_token"
-		})
-	});
-}
-/** 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, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/x-www-form-urlencoded",
-			Accept: "application/json"
-		},
-		body: new URLSearchParams(form)
-	});
-	const body = await response.json().catch(() => void 0);
-	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");
-	return {
-		accessToken: parsed.data.access_token,
-		refreshToken: parsed.data.refresh_token,
-		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
-		scope: parsed.data.scope,
-		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
-	};
+/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
+function toScopes(decoded) {
+	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
+	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
 }
 //#endregion
 //#region src/credential/lock.ts
@@ -916,6 +974,18 @@ var RequestFailure = class extends ExpectedFailure {
 		this.requestId = requestId;
 	}
 };
+/**
+* UnexpectedAnswer is a successful response that is not the API's envelope. A captive portal
+* or a proxy answers 200 with a page of its own, which must not pass for an empty result.
+*/
+var UnexpectedAnswer = class extends ExpectedFailure {
+	constructor(host, contentType) {
+		super(`${host} answered with ${contentType ?? "something"} that is not the API's JSON, so nothing can be read from it. A proxy, a firewall or a network sign-in page may be answering in its place`);
+		this.name = "UnexpectedAnswer";
+	}
+};
+/** How long an upload may take to be answered, which is longer than any other request. */
+const UPLOAD_TIMEOUT_MS = 3e5;
 /** request calls one /v2 endpoint and returns the envelope it answered with. */
 async function request$1(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
@@ -931,13 +1001,14 @@ async function request$1(options) {
 		signal: options.signal,
 		headers,
 		body: options.form ?? (options.body === void 0 ? void 0 : JSON.stringify(options.body))
-	});
+	}, options.form ? UPLOAD_TIMEOUT_MS : void 0);
 	if (options.downloads && response.ok) return { data: {
 		bytes: Buffer.from(await response.arrayBuffer()),
 		contentType: response.headers.get("content-type"),
 		fileName: toFileName(response.headers.get("content-disposition"))
 	} };
-	const envelope = toEnvelope(await response.text());
+	const text = await response.text();
+	const envelope = toEnvelope(text);
 	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
 		error: toStatusMessage(response.status),
 		statusCode: response.status
@@ -949,12 +1020,18 @@ async function request$1(options) {
 			statusCode: response.status
 		}], envelope?.metadata?.requestId);
 	}
+	if (envelope === void 0 && text.trim() !== "") throw new UnexpectedAnswer(url.host, response.headers.get("content-type"));
 	return envelope ?? { data: null };
 }
 /** 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}`;
@@ -962,7 +1039,8 @@ function toLeadingSlash(path) {
 function toEnvelope(text) {
 	if (text.trim() === "") return;
 	try {
-		return JSON.parse(text);
+		const parsed = JSON.parse(text);
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
 	} catch {
 		return;
 	}
@@ -973,6 +1051,36 @@ function toStatusMessage(status) {
 	return `the request failed with status ${status}`;
 }
 //#endregion
+//#region src/report/classify.ts
+/**
+* The codes Node gives when the machine refuses something: permissions, a full or read-only
+* disk, a path that is missing or of the wrong kind, and a reader that closed the pipe.
+*/
+const ENVIRONMENT_CODES = /* @__PURE__ */ new Set([
+	"EACCES",
+	"EPERM",
+	"ENOSPC",
+	"EROFS",
+	"ENOENT",
+	"EISDIR",
+	"ENOTDIR",
+	"EEXIST",
+	"EPIPE"
+]);
+/**
+* isReportable answers whether an error is a defect in the CLI. Everything the CLI anticipated
+* extends ExpectedFailure, so a failure nobody has classified yet is reported until someone
+* decides it is expected.
+*/
+function isReportable(error) {
+	return !(error instanceof ExpectedFailure) && !isMachineRefusal(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);
+}
+//#endregion
 //#region src/output/failure.ts
 /** FAILURE_CODES is every code a failure can carry, and none is ever renamed or given a new meaning. */
 const FAILURE_CODES = {
@@ -986,6 +1094,7 @@ const FAILURE_CODES = {
 	not_confirmed: "The change was not confirmed. Pass --yes to confirm it without a terminal",
 	shell_unavailable: "The shell did not say where its startup file is",
 	invalid_config: "A config file or setting cannot be read",
+	file_error: "This machine refused a file or folder the command needed, such as a path that does not exist",
 	not_signed_in: "No usable credential. Run hardfin login, or set HARDFIN_API_KEY",
 	sign_in_failed: "Signing in did not finish",
 	unreachable: "The CLI could not connect to the server",
@@ -1001,6 +1110,7 @@ const FAILURE_CODES = {
 	rate_limited: "Too many requests. Wait, then try again (HTTP 429)",
 	server_error: "The API failed to answer (HTTP 5xx)",
 	api_error: "The API refused the request with another status",
+	unexpected_response: "The answer was not the API's JSON, as when a proxy or a sign-in page answers in its place",
 	internal_error: "A problem in hardfin itself, which has been reported"
 };
 /** toStatusCode names a refusal by the HTTP status the API answered with. */
@@ -1025,6 +1135,9 @@ function toErrorCode(error) {
 	if (error instanceof Unreachable) return "unreachable";
 	if (error instanceof TimedOut) return "timed_out";
 	if (error instanceof LockHeld) return "busy";
+	if (error instanceof UnexpectedAnswer) return "unexpected_response";
+	if (error instanceof GrantFailure || error instanceof DiscoveryFailure || error instanceof SignInStopped) return "sign_in_failed";
+	if (isMachineRefusal(error)) return "file_error";
 	return "internal_error";
 }
 //#endregion
@@ -1115,7 +1228,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));
@@ -1296,26 +1409,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]]
 	];
@@ -1323,7 +1451,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
@@ -2151,7 +2281,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",
@@ -2162,7 +2292,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");
@@ -2213,7 +2344,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) => {
@@ -2226,7 +2357,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) => {
@@ -2259,10 +2394,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);
@@ -2450,9 +2608,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,
@@ -2496,7 +2654,7 @@ async function runLogin(input) {
 		}
 		return await toSignedIn(input, metadata, await toTokensFromCode(metadata.token_endpoint, clientId, callback.code, listener.redirectUri, pkce));
 	} catch (error) {
-		if (error instanceof DiscoveryFailure || error instanceof GrantFailure) {
+		if (error instanceof DiscoveryFailure || error instanceof GrantFailure || error instanceof SignInStopped) {
 			writeFailure("sign_in_failed", error.message, input.isJSON);
 			return ExitCode.ERROR;
 		}
@@ -2542,7 +2700,7 @@ async function runDeviceLogin(input, metadata, scope) {
 */
 async function toDeviceTokens(approved, typed) {
 	return await Promise.race([approved, typed.then(() => {
-		throw new ExpectedFailure("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
+		throw new SignInStopped("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
 	})]);
 }
 /** toSignedIn stores what a sign in issued, whichever flow issued it. */
@@ -2709,7 +2867,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"]);
@@ -2772,7 +2930,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);
@@ -2789,9 +2952,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;
@@ -2929,6 +3103,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"];
@@ -3210,6 +3388,8 @@ function toServerReport(metadata) {
 		scopes: metadata.scopes_supported ?? []
 	};
 }
+/** The statuses the API answers when it will not take the credential. */
+const REFUSED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
 /** toApiReport asks the API who this credential is, which is the only authoritative answer. */
 async function toApiReport(resolved, options) {
 	const settings = resolved.settings;
@@ -3222,6 +3402,7 @@ async function toApiReport(resolved, options) {
 		};
 		const claims = credential.kind === "access token" ? toClaims(credential.value.replace(/^Bearer /, "")) : {};
 		let isReachable = true;
+		let isAuthenticated = true;
 		const identity = await request$1({
 			apiUrl: settings.apiUrl,
 			credential,
@@ -3229,12 +3410,13 @@ async function toApiReport(resolved, options) {
 			path: "/token",
 			signal: options.signal
 		}).then((envelope) => envelope.data).catch((error) => {
-			isReachable = !(error instanceof Unreachable);
+			isReachable = !(error instanceof Unreachable || error instanceof TimedOut);
+			isAuthenticated = error instanceof RequestFailure && REFUSED_STATUSES.has(error.status) ? false : null;
 			return { unavailable: error instanceof Error ? error.message : String(error) };
 		});
 		return {
 			reachable: isReachable,
-			authenticated: true,
+			authenticated: isAuthenticated,
 			url: settings.apiUrl,
 			accessTokenExpiresAt: claims.expiresAt === void 0 ? null : new Date(claims.expiresAt).toISOString(),
 			accessTokenScopes: claims.scopes ?? [],
@@ -3300,33 +3482,6 @@ function toLines(report, depth = 0) {
 	return lines;
 }
 //#endregion
-//#region src/report/classify.ts
-/**
-* The codes Node gives when the machine refuses something: permissions, a full or read-only
-* disk, a path that is missing or of the wrong kind, and a reader that closed the pipe.
-*/
-const ENVIRONMENT_CODES = /* @__PURE__ */ new Set([
-	"EACCES",
-	"EPERM",
-	"ENOSPC",
-	"EROFS",
-	"ENOENT",
-	"EISDIR",
-	"ENOTDIR",
-	"EEXIST",
-	"EPIPE"
-]);
-/**
-* isReportable answers whether an error is a defect in the CLI. Everything the CLI anticipated
-* extends ExpectedFailure, so a failure nobody has classified yet is reported until someone
-* decides it is expected.
-*/
-function isReportable(error) {
-	if (error instanceof ExpectedFailure) return false;
-	const code = error instanceof Error ? error.code : void 0;
-	return !(typeof code === "string" && ENVIRONMENT_CODES.has(code));
-}
-//#endregion
 //#region src/report/report.ts
 /** True once a report has been sent or tried, which the entry point reads before it exits. */
 let isAttempted = false;
@@ -3566,7 +3721,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),
@@ -3574,11 +3729,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
@@ -3617,7 +3777,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";
@@ -3642,18 +3803,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: [{
@@ -3737,35 +3924,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 });
@@ -6634,5 +6858,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-C1-jZp6K.js.map
-//# debugId=8cef3750-26c4-5378-89b9-1b3b5b7aaaa7
+//# sourceMappingURL=program-CgT1Kr8L.js.map
+//# debugId=2c607b02-61ea-5376-957f-d434d5692ac5

package/package.json

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

package/skills/hardfin-cli/SKILL.md

@@ -124,13 +124,17 @@ The exit code says what kind of failure it was.
 
 The error is JSON on stderr. Branch on its `code`, never on the message.
 
-| `code`                                              | Do this                                                          |
-| --------------------------------------------------- | ---------------------------------------------------------------- |
-| `not_signed_in`, `unauthorized`                     | Sign in again                                                    |
-| `invalid_flag`, `missing_flag`, `invalid_arguments` | Read `--help` for that command                                   |
-| `not_found`                                         | Check you passed a key, not an ID, where the command wants a key |
-| `bad_request`, `invalid_request`, `conflict`        | Read `errors`, which names the field                             |
-| `rate_limited`                                      | Wait a minute, then retry once                                   |
-| `unreachable`, `server_error`                       | Tell the person, and include `requestId` if there is one         |
+| `code`                                              | Do this                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------ |
+| `not_signed_in`, `unauthorized`                     | Sign in again                                                      |
+| `invalid_flag`, `missing_flag`, `invalid_arguments` | Read `--help` for that command                                     |
+| `not_found`                                         | Check you passed a key, not an ID, where the command wants a key   |
+| `bad_request`, `invalid_request`, `conflict`        | Read `errors`, which names the field                               |
+| `rate_limited`                                      | Wait a minute, then retry once                                     |
+| `unreachable`, `server_error`                       | Tell the person, and include `requestId` if there is one           |
+| `timed_out`                                         | For a change, read the record first, because it may have been made |
+| `unexpected_response`                               | Tell the person a proxy or network page answered, not Hardfin      |
+| `file_error`                                        | Check the path you gave exists and can be read or written          |
+| `sign_in_failed`                                    | Tell the person, and have them run `hardfin login`                 |
 
 `hardfin agent-guide` lists every code.