@hardfin/cli 0.1.0-dev.32 → 0.1.0-dev.34

package/README.md

@@ -208,6 +208,21 @@ On WSL the browser is opened through Windows, by `wslview`, then PowerShell, the
 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.
 
+### When an agent signs you in
+
+An agent that runs `hardfin login` reads its stderr, and you only see what the agent passes
+on. So when output is JSON, which it is whenever stdout is not a terminal, the command writes
+one line of JSON on stderr before it starts waiting.
+
+| `event`       | Also carries                                                         | The agent should                                    |
+| ------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `sign_in_url` | `url`, `browserOpened`, `waitSeconds`                                | Show you `url`, saying whether a browser tab opened |
+| `device_code` | `userCode`, `verificationUri`, `url`, `browserOpened`, `waitSeconds` | Show you the code and where to enter it             |
+
+The command then waits up to `waitSeconds` for you to approve, so the agent has to let it run
+that long. An agent with no way to open your browser, such as one in a cloud sandbox, signs
+in with `--device`.
+
 ### Signing in from a machine with no browser
 
 `hardfin login --device` prints a short code and a page to enter it on, and waits. Approve
@@ -305,22 +320,33 @@ other client can run Hardfin commands.
 claude mcp add hardfin -- hardfin mcp
 ```
 
-### One tool, and resources for the rest
+### Two tools, and resources for the rest
 
 Every tool a server lists sits in the agent's context for the entire session, so this server
-offers one.
+offers two. They differ only in what they may run, which lets a client run a read without
+asking and ask before anything changes.
 
-| Offered as           | Holds                                                            | Costs context                     |
-| -------------------- | ---------------------------------------------------------------- | --------------------------------- |
-| The `hardfin` tool   | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
-| `hardfin://guide`    | Every command, its flags, and the exit codes                     | Only when the agent reads it      |
-| `hardfin://commands` | The command tree as JSON                                         | Only when the agent reads it      |
+| Offered as           | Holds                                                                  | Costs context                |
+| -------------------- | ---------------------------------------------------------------------- | ---------------------------- |
+| `hardfin_read`       | A command that only reads, such as `["asset", "list", "--limit", "5"]` | Always, about 800 bytes      |
+| `hardfin_write`      | A command that creates, changes or deletes, with an optional JSON body | Always, about 800 bytes      |
+| `hardfin://guide`    | Every command, its flags, the exit codes and the error codes           | Only when the agent reads it |
+| `hardfin://commands` | The command tree as JSON                                               | Only when the agent reads it |
 
-Fifty tools would describe the same surface and crowd out the work. An agent that needs the
-list reads a resource, or runs `["--help"]`.
+A command is a read when its endpoint's method is GET, or for `hardfin api` when no other
+`--method` is given. Anything else is a write, and `hardfin_read` refuses it by naming
+`hardfin_write`. Both tools carry a title, the read-only or destructive hint, and a link to
+the API reference, which Claude's connector directory requires.
 
 A tool call runs the CLI itself, so an agent and a person get identical parsing, output and
-exit codes.
+exit codes. Each call has these limits:
+
+| Limit            | Value                                   | Past it                                    |
+| ---------------- | --------------------------------------- | ------------------------------------------ |
+| Time             | 120 seconds                             | The command is stopped, and the call fails |
+| 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  |
 
 ### What it signs in as
 

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]="62437fed-ab84-53c5-9984-9bbadc0f2e15")}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]="f2529e6e-d7d4-5fe2-b460-7e86ca865c25")}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-B02z-kNH.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-DTsxnjRj.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-B02z-kNH.js");
+		const { toReported } = await import("./program-DTsxnjRj.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=62437fed-ab84-53c5-9984-9bbadc0f2e15
+//# debugId=f2529e6e-d7d4-5fe2-b460-7e86ca865c25

package/dist/{program-B02z-kNH.js → program-DTsxnjRj.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]="b1928379-e7e3-5a7e-9ade-d45695e05814")}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]="c7f8ce05-d638-5d0f-a088-655ddade6f45")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.js";
 import { n as toCompletion, t as toAnswer$1 } from "./completion-tree-rR_Rmeij.js";
 import { createRequire } from "node:module";
@@ -987,6 +987,7 @@ function toGuide(commands, version) {
 		"## Before calling",
 		"",
 		"- Authenticate with `--api-key`, by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
+		"- `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",
 		"",
@@ -2154,7 +2155,13 @@ async function runLogin(input) {
 			challenge: pkce.challenge
 		});
 		const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
-		process.stderr.write(opened ? `Opening your browser to sign in. If it did not open:\n\n${url}\n\n` : `Open this URL to sign in:\n\n${url}\n\n`);
+		if (input.isJSON) writeEvent({
+			event: "sign_in_url",
+			url,
+			browserOpened: opened,
+			waitSeconds: WAIT_MS / 1e3
+		});
+		else process.stderr.write(opened ? `Opening your browser to sign in. If it did not open:\n\n${url}\n\n` : `Open this URL to sign in:\n\n${url}\n\n`);
 		const prompt = toPrompt(url);
 		if (process.stdin.isTTY) process.stderr.write("Press c to copy the URL, or paste the code or redirect URL here: ");
 		let callback;
@@ -2164,7 +2171,7 @@ async function runLogin(input) {
 			listener.close();
 			prompt.close();
 		}
-		process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
+		if (!input.isJSON) process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
 		if (callback.error) {
 			writeFailure("sign_in_failed", `sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
 			return ExitCode.ERROR;
@@ -2200,7 +2207,15 @@ async function runDeviceLogin(input, metadata, scope) {
 	const device = await toDeviceAuthorization(metadata.device_authorization_endpoint, settings.clientId, scope);
 	const url = device.verificationUriComplete ?? device.verificationUri;
 	const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
-	process.stderr.write([
+	if (input.isJSON) writeEvent({
+		event: "device_code",
+		userCode: device.userCode,
+		verificationUri: device.verificationUri,
+		url,
+		browserOpened: opened,
+		waitSeconds: Math.max(0, Math.round((device.expiresAt - Date.now()) / 1e3))
+	});
+	else process.stderr.write([
 		"",
 		`  Code  ${device.userCode}`,
 		`  At    ${device.verificationUri}`,
@@ -2252,6 +2267,10 @@ async function toSignedIn(input, metadata, tokens) {
 	].join("\n"));
 	return ExitCode.OK;
 }
+/** writeEvent tells a program what a sign in is waiting on, as one line of JSON on stderr. */
+function writeEvent(event) {
+	process.stderr.write(`${JSON.stringify(event)}\n`);
+}
 /** toAuthorizationUrl builds the URL the person approves this CLI at. */
 function toAuthorizationUrl(endpoint, request) {
 	const url = new URL(endpoint);
@@ -2778,23 +2797,52 @@ function wasReportAttempted() {
 const PROTOCOL_VERSION = "2025-06-18";
 const GUIDE_URI = "hardfin://guide";
 const COMMANDS_URI = "hardfin://commands";
-/**
-* One tool, because every tool a server lists sits in the agent's context for the whole
-* session. The commands themselves are resources, which cost nothing until one is read.
-*/
-const TOOL = {
-	name: "hardfin",
-	description: "Run a Hardfin CLI command against the Hardfin API. Pass the arguments as a list, such as [\"asset\", \"list\", \"--limit\", \"5\"]. Run [\"--help\"] for the commands, or read the hardfin://guide resource.",
-	inputSchema: {
-		type: "object",
-		properties: { args: {
+/** The public reference for the API every command calls. */
+const API_REFERENCE = "https://docs.hardfin.com";
+const ARGUMENTS_SCHEMA = {
+	type: "object",
+	properties: {
+		args: {
 			type: "array",
 			items: { type: "string" },
 			description: "The arguments to hardfin, without the program name"
-		} },
-		required: ["args"]
+		},
+		input: {
+			type: "string",
+			description: "JSON sent to the command on standard input, which it reads when given --input -"
+		}
+	},
+	required: ["args"]
+};
+/**
+* Two tools, so a client can let a read run without asking and ask before anything changes.
+* The commands themselves are resources, which cost nothing until one is read.
+*/
+const READ_TOOL = {
+	name: "hardfin_read",
+	title: "Read Hardfin data",
+	description: `Runs a Hardfin CLI command that only reads, against the Hardfin API (${API_REFERENCE}). Takes the arguments as a list, such as ["asset", "list", "--limit", "5"]. ["--help"] lists the commands, and the hardfin://guide resource describes each one.`,
+	inputSchema: ARGUMENTS_SCHEMA,
+	annotations: {
+		title: "Read Hardfin data",
+		readOnlyHint: true,
+		destructiveHint: false,
+		openWorldHint: true
+	}
+};
+const WRITE_TOOL = {
+	name: "hardfin_write",
+	title: "Change Hardfin data",
+	description: `Runs a Hardfin CLI command that creates, changes or deletes records through the Hardfin API (${API_REFERENCE}). Takes the arguments as a list, such as ["customer", "create", "--name", "Acme"]. A JSON body goes in the input argument, with --input - in the list.`,
+	inputSchema: ARGUMENTS_SCHEMA,
+	annotations: {
+		title: "Change Hardfin data",
+		readOnlyHint: false,
+		destructiveHint: true,
+		openWorldHint: true
 	}
 };
+const INSTRUCTIONS = "hardfin_read looks records up and hardfin_write changes them. Both run Hardfin CLI commands, so the arguments are what a person would type after hardfin. The hardfin://guide resource lists every command, flag and error code.";
 /** ProtocolFailure is a line this server answers with a JSON-RPC error rather than a result. */
 var ProtocolFailure = class extends Error {
 	code;
@@ -2822,10 +2870,12 @@ async function toResponse(request, commands, run) {
 			},
 			serverInfo: {
 				name: "hardfin",
+				title: "Hardfin",
 				version: version$1
-			}
+			},
+			instructions: INSTRUCTIONS
 		});
-		case "tools/list": return answer({ tools: [TOOL] });
+		case "tools/list": return answer({ tools: [READ_TOOL, WRITE_TOOL] });
 		case "resources/list": return answer({ resources: [{
 			uri: GUIDE_URI,
 			name: "Hardfin CLI guide",
@@ -2838,7 +2888,8 @@ async function toResponse(request, commands, run) {
 			mimeType: "application/json"
 		}] });
 		case "resources/read": {
-			const uri = toText(request.params?.["uri"] ?? "");
+			const uri = request.params?.["uri"];
+			if (typeof uri !== "string" || uri === "") throw new ProtocolFailure(-32602, "resources/read needs a uri, such as hardfin://guide", request.id ?? null);
 			const resource = toResource(uri, commands);
 			if (!resource) return {
 				jsonrpc: "2.0",
@@ -2850,7 +2901,7 @@ async function toResponse(request, commands, run) {
 			};
 			return answer(resource);
 		}
-		case "tools/call": return answer(await toToolResult(request.params, run));
+		case "tools/call": return answer(await toToolResult(request, commands, run));
 		case "ping": return answer({});
 		default:
 			if (request.id === void 0 || request.id === null) return;
@@ -2924,80 +2975,170 @@ function toCommandName(args) {
 function toIsAskingForHelp(args) {
 	return args.includes("--help") || args.includes("-h") || args[0] === "help";
 }
-async function toToolResult(params, run) {
-	if (params?.["name"] !== TOOL.name) return {
-		content: [{
-			type: "text",
-			text: `a call names its tool, and this server offers one, ${TOOL.name}`
-		}],
-		isError: true
-	};
-	const args = (params?.["arguments"])?.args;
-	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return {
-		content: [{
-			type: "text",
-			text: "args must be a list of strings, such as [\"asset\", \"list\"]"
-		}],
-		isError: true
-	};
+async function toToolResult(request, commands, run) {
+	const params = request.params;
+	const name = params?.["name"];
+	if (name !== READ_TOOL.name && name !== WRITE_TOOL.name) throw new ProtocolFailure(-32602, `a call names its tool, and this server offers ${READ_TOOL.name} and ${WRITE_TOOL.name}`, request.id ?? null);
+	const called = params?.["arguments"];
+	const args = called?.args;
+	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return toError("args must be a list of strings, such as [\"asset\", \"list\"]");
+	if (called?.input !== void 0 && typeof called.input !== "string") return toError("input must be a string holding JSON, such as {\"name\": \"Acme\"}");
 	const refused = toRefusedArgument(args);
-	if (refused) return {
-		content: [{
-			type: "text",
-			text: refused
-		}],
-		isError: true
-	};
+	if (refused) return toError(refused);
 	const asked = args;
 	const command = toCommandName(asked) ?? "";
-	if (REFUSED_COMMANDS.has(command) && !toIsAskingForHelp(asked)) return {
+	if (REFUSED_COMMANDS.has(command) && !toIsAskingForHelp(asked)) 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 && toAccess(asked, commands) === "write") return toError(`this command changes data, so it runs through ${WRITE_TOOL.name}`);
+	const outcome = await run(asked, called?.input);
+	return {
 		content: [{
 			type: "text",
-			text: `${command} is run by a person at a terminal, not through this server. Run hardfin ${command} yourself, then call this tool again`
+			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
 		}],
-		isError: true
+		isError: outcome.code !== 0
 	};
-	const outcome = await run(asked);
+}
+function toError(text) {
 	return {
 		content: [{
 			type: "text",
-			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
+			text
 		}],
-		isError: outcome.code !== 0
+		isError: true
 	};
 }
-/** The most a command line can carry, below what the operating system refuses outright. */
-const ARGUMENT_LIMIT = 1e5;
+/** Commands with no endpoint that only show something, which a read may run. */
+const LOCAL_READS = /* @__PURE__ */ new Set([
+	"status",
+	"config",
+	"agent-guide",
+	"help"
+]);
+/**
+* toAccess decides whether a call reads or changes data. A generated command answers by its
+* endpoint's method, hardfin api by the method it was given, and anything it cannot place is
+* treated as a change, so it is asked about.
+*/
+function toAccess(args, commands) {
+	if (toIsAskingForHelp(args)) return "read";
+	let level = commands;
+	let found;
+	for (let index = 0; index < args.length; index += 1) {
+		const word = args[index] ?? "";
+		if (GLOBAL_OPTIONS_WITH_VALUES.has(word)) {
+			index += 1;
+			continue;
+		}
+		if (word.startsWith("-")) continue;
+		const next = level.find((entry) => entry.name === word);
+		if (!next) break;
+		found = next;
+		level = next.subcommands ?? [];
+		if (level.length === 0) break;
+	}
+	if (!found) return "read";
+	if (found.endpoint) return found.endpoint.method === "GET" ? "read" : "write";
+	if (found.name === "api") return toApiMethod(args) === "GET" ? "read" : "write";
+	if (LOCAL_READS.has(found.name) || (found.subcommands?.length ?? 0) > 0) return "read";
+	return "write";
+}
+/** toApiMethod reads the method hardfin api was given, which is GET when none was. */
+function toApiMethod(args) {
+	for (let index = 0; index < args.length; index += 1) {
+		const word = args[index] ?? "";
+		if (word === "-X" || word === "--method") return (args[index + 1] ?? "GET").toUpperCase();
+		if (word.startsWith("--method=")) return word.slice(9).toUpperCase();
+		if (word.startsWith("-X") && word.length > 2) return word.slice(2).toUpperCase();
+	}
+	return "GET";
+}
+/** The most one argument can hold, which Linux refuses past 128 KiB. */
+const ARGUMENT_BYTES = 131071;
+/** The most a whole command line can carry, below what the operating system refuses outright. */
+const COMMAND_LINE_BYTES = 1e6;
 /** toRefusedArgument names an argument a command line cannot carry, rather than failing later. */
 function toRefusedArgument(args) {
 	const withNul = args.findIndex((argument) => argument.includes("\0"));
 	if (withNul >= 0) return `args[${withNul}] holds a NUL byte, which a command line cannot carry`;
-	const total = args.reduce((carried, argument) => carried + argument.length, 0);
-	if (total > ARGUMENT_LIMIT) return `these arguments are ${total} characters, and a command line carries at most ${ARGUMENT_LIMIT}`;
-}
+	const oversized = args.findIndex((argument) => Buffer.byteLength(argument) > ARGUMENT_BYTES);
+	if (oversized >= 0) return `args[${oversized}] is ${Buffer.byteLength(args[oversized] ?? "")} bytes, and one argument carries at most ${ARGUMENT_BYTES}. Send a large body in the input argument instead`;
+	const total = args.reduce((carried, argument) => carried + Buffer.byteLength(argument), 0);
+	if (total > COMMAND_LINE_BYTES) return `these arguments are ${total} bytes, and a command line carries at most ${COMMAND_LINE_BYTES}`;
+}
+/** How long one command may run before it is stopped, so a hung call cannot hold its client. */
+const CALL_TIMEOUT_MS = 12e4;
+/** How many commands run at once, so a burst of calls cannot start a process each. */
+const MAX_RUNNING = 4;
 /** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
-function toCliRunner() {
-	return (args) => new Promise((resolve) => {
-		const child = spawn(process.execPath, [process.argv[1] ?? "", ...args], { env: {
-			...process.env,
-			HARDFIN_NO_BROWSER: "1",
-			HARDFIN_MCP: "1"
-		} });
+function toCliRunner(timeoutMs = CALL_TIMEOUT_MS, entry = process.argv[1] ?? "") {
+	const waiting = [];
+	let running = 0;
+	const acquire = async () => {
+		if (running < MAX_RUNNING) {
+			running += 1;
+			return;
+		}
+		await new Promise((resolve) => waiting.push(resolve));
+	};
+	const release = () => {
+		const next = waiting.shift();
+		if (next) next();
+		else running -= 1;
+	};
+	return async (args, input) => {
+		await acquire();
+		try {
+			return await toRun(entry, args, input, timeoutMs);
+		} finally {
+			release();
+		}
+	};
+}
+/** toRun runs one command, feeding it input on stdin and stopping it at the deadline. */
+function toRun(entry, args, input, timeoutMs) {
+	return new Promise((resolve) => {
+		let child;
+		try {
+			child = spawn(process.execPath, [entry, ...args], { env: {
+				...process.env,
+				HARDFIN_NO_BROWSER: "1",
+				HARDFIN_MCP: "1"
+			} });
+		} catch (error) {
+			resolve({
+				stdout: "",
+				stderr: `the command could not start: ${error instanceof Error ? error.message : String(error)}`,
+				code: 1
+			});
+			return;
+		}
 		let stdout = "";
 		let stderr = "";
+		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.on("error", (error) => {
+			stderr += `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`;
 			resolve({
 				stdout,
 				stderr,
-				code: code ?? 1
+				code: isTimedOut ? 1 : code ?? 1
 			});
 		});
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(input ?? "");
 	});
 }
 /** serve answers requests on stdin until the client closes it. */
@@ -6168,5 +6309,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-B02z-kNH.js.map
-//# debugId=b1928379-e7e3-5a7e-9ade-d45695e05814
+//# sourceMappingURL=program-DTsxnjRj.js.map
+//# debugId=c7f8ce05-d638-5d0f-a088-655ddade6f45

package/package.json

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