@hardfin/cli 0.0.2-dev.16 → 0.0.2-dev.18

package/README.md

@@ -71,6 +71,13 @@ A value is sent as the type the document names. `--useful-life 36` sends the num
 decimal such as `--salvage-value 1500.00` stays a string, which is how the API takes money
 without losing precision.
 
+A download is written where you name it, and a terminal is never filled with a file's bytes.
+
+```sh
+hardfin file get file_7hq2mx9pkr4stz8w --output photo.jpg
+hardfin file get file_7hq2mx9pkr4stz8w --output - | wc -c
+```
+
 Clear a field with `--unset`, naming the flag:
 
 ```sh

package/dist/cli.js

@@ -136,7 +136,7 @@ function writeData(value) {
 		process.stdout.write(value.endsWith("\n") ? value : `${value}\n`);
 		return;
 	}
-	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+	process.stdout.write(`${JSON.stringify(value ?? null, null, 2)}\n`);
 }
 /** writeFailure prints why a command failed on stderr, as text or as JSON. */
 function writeFailure(message, isJSON, errors, requestId) {
@@ -258,7 +258,8 @@ function toSummary(command) {
 			valueName: flag.valueName ?? null,
 			repeatable: flag.repeatable ?? false
 		})),
-		examples: command.examples
+		examples: command.examples,
+		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
 	};
 }
 //#endregion
@@ -719,11 +720,11 @@ var RequestFailure = class extends Error {
 /** request calls one /v2 endpoint and returns the envelope it answered with. */
 async function request(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
-	if (options.query) url.search = options.query.toString();
+	for (const [name, value] of options.query ?? []) url.searchParams.append(name, value);
 	const headers = {
 		[options.credential.header]: options.credential.value,
 		"X-API-Version": API_VERSION,
-		Accept: "application/json"
+		Accept: options.downloads ? "*/*" : "application/json"
 	};
 	if (options.body !== void 0 && options.form === void 0) headers["Content-Type"] = "application/json";
 	const response = await fetch(url, {
@@ -731,6 +732,11 @@ async function request(options) {
 		headers,
 		body: options.form ?? (options.body === void 0 ? void 0 : JSON.stringify(options.body))
 	});
+	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());
 	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
 		error: toStatusMessage(response.status),
@@ -745,6 +751,11 @@ async function request(options) {
 	}
 	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;
+}
 function toLeadingSlash(path) {
 	return path.startsWith("/") ? path : `/${path}`;
 }
@@ -1090,8 +1101,8 @@ function toOpeners(url) {
 	return [["xdg-open", [url]]];
 }
 /** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
-function openBrowser(url) {
-	for (const [command, args] of toOpeners(url)) if (spawnSync(command, args, {
+function openBrowser(url, launch = spawnSync) {
+	for (const [command, args] of toOpeners(url)) if (launch(command, args, {
 		stdio: "ignore",
 		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
 		timeout: 1e4
@@ -1261,11 +1272,11 @@ function toClipboardCommand() {
 	return ["xclip", ["-selection", "clipboard"]];
 }
 /** copyToClipboard puts text on the clipboard, and reports whether anything took it. */
-function copyToClipboard(text) {
+function copyToClipboard(text, copy = spawnSync) {
 	const command = toClipboardCommand();
 	if (!command) return false;
 	const [name, args] = command;
-	const result = spawnSync(name, args, { input: text });
+	const result = copy(name, args, { input: text });
 	return result.error === void 0 && result.status === 0;
 }
 //#endregion
@@ -1301,14 +1312,13 @@ function toPastedCallback(pasted) {
 * toPrompt watches the keyboard while the browser is away. Pressing c copies the URL, and
 * pasting a code finishes the sign in on a machine whose browser cannot reach this listener.
 */
-function toPrompt(url) {
+function toPrompt(url, input = process.stdin, copy = copyToClipboard) {
 	let settle = () => {};
 	let fail = () => {};
 	const pasted = new Promise((resolve, reject) => {
 		settle = resolve;
 		fail = reject;
 	});
-	const input = process.stdin;
 	pasted.catch(() => {});
 	if (!input.isTTY) return {
 		pasted,
@@ -1316,6 +1326,7 @@ function toPrompt(url) {
 	};
 	let typed = "";
 	const onData = (chunk) => {
+		const isKeystroke = chunk.length === 1;
 		for (const character of chunk) {
 			if (character === CTRL_C) {
 				fail(/* @__PURE__ */ new Error("sign in was cancelled"));
@@ -1332,8 +1343,8 @@ function toPrompt(url) {
 				process.stderr.write("\b \b");
 				continue;
 			}
-			if ((character === "c" || character === "C") && typed === "") {
-				process.stderr.write(copyToClipboard(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
+			if (isKeystroke && (character === "c" || character === "C") && typed === "") {
+				process.stderr.write(copy(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
 				continue;
 			}
 			typed += character;
@@ -1674,7 +1685,21 @@ 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"
+]);
 async function toToolResult(params, run) {
+	const name = params?.["name"];
+	if (name !== void 0 && name !== TOOL.name) return {
+		content: [{
+			type: "text",
+			text: `this server offers one tool, ${TOOL.name}`
+		}],
+		isError: true
+	};
 	const args = (params?.["arguments"])?.args;
 	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return {
 		content: [{
@@ -1683,7 +1708,15 @@ async function toToolResult(params, run) {
 		}],
 		isError: true
 	};
-	const outcome = await run(args);
+	const asked = args;
+	if (REFUSED_COMMANDS.has(asked[0] ?? "")) return {
+		content: [{
+			type: "text",
+			text: `${asked[0] ?? ""} is run by a person at a terminal, not through this server. Run hardfin ${asked[0] ?? ""} yourself, then call this tool again`
+		}],
+		isError: true
+	};
+	const outcome = await run(asked);
 	return {
 		content: [{
 			type: "text",
@@ -1692,6 +1725,14 @@ async function toToolResult(params, run) {
 		isError: outcome.code !== 0
 	};
 }
+/** toRequestId reads the id of a line that could not be answered, so a client is not left waiting. */
+function toRequestId(line) {
+	try {
+		return JSON.parse(line).id ?? null;
+	} catch {
+		return null;
+	}
+}
 /** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
 function toCliRunner() {
 	return (args) => new Promise((resolve) => {
@@ -1727,9 +1768,9 @@ async function serve(commands, run = toCliRunner()) {
 		} catch (error) {
 			response = {
 				jsonrpc: "2.0",
-				id: null,
+				id: toRequestId(line),
 				error: {
-					code: -32700,
+					code: -32603,
 					message: error instanceof Error ? error.message : String(error)
 				}
 			};
@@ -1784,6 +1825,12 @@ const FILE_FLAG = {
 	valueName: "path",
 	schema: z.string()
 };
+const OUTPUT_FLAG = {
+	name: "output",
+	description: "Where to write the file, or - for standard output",
+	valueName: "path",
+	schema: z.string()
+};
 const JSON_FLAG = {
 	name: "json",
 	description: "Print machine-readable output, which is the default when stdout is not a terminal",
@@ -1796,6 +1843,7 @@ function defineOperation(operation) {
 		...operation.bodyFlags,
 		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
 		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		...operation.downloads ? [OUTPUT_FLAG] : [],
 		JSON_FLAG
 	];
 	return {
@@ -1841,15 +1889,18 @@ async function runOperation(operation, input) {
 		form = built;
 	}
 	try {
-		writeData((await request({
+		const envelope = await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
 			method: operation.method,
 			path,
 			query: toQuery(operation, input.flags),
 			body,
-			form
-		})).data);
+			form,
+			downloads: operation.downloads
+		});
+		if (operation.downloads) return toWritten(envelope.data, input);
+		writeData(envelope.data);
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
@@ -1864,6 +1915,29 @@ async function runOperation(operation, input) {
 		return ExitCode.ERROR;
 	}
 }
+/**
+* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
+* because a person would otherwise have their session filled with a file's bytes.
+*/
+function toWritten(download, input) {
+	const asked = input.flags["output"];
+	const path = typeof asked === "string" ? asked : download.fileName ?? "-";
+	if (path === "-") {
+		if (process.stdout.isTTY) {
+			writeFailure("this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
+			return ExitCode.USAGE;
+		}
+		process.stdout.write(download.bytes);
+		return ExitCode.OK;
+	}
+	writeFileSync(path, download.bytes);
+	writeData({
+		written: path,
+		bytes: download.bytes.length,
+		contentType: download.contentType
+	});
+	return ExitCode.OK;
+}
 /** toPath fills the path template from the positional arguments, in order. */
 function toPath(operation, args) {
 	if (args.length !== operation.pathParameters.length) return;
@@ -2593,6 +2667,7 @@ const surfaceCommands = [
 							name: "is-in-service-date-managed-automatically",
 							jsonPath: ["isInServiceDateManagedAutomatically"],
 							description: "Whether Hardfin sets the in-service date itself, which sending an in-service date turns off",
+							negatable: true,
 							nullable: true,
 							schema: z.boolean()
 						},
@@ -2659,6 +2734,7 @@ const surfaceCommands = [
 							name: "automatic",
 							jsonPath: ["automatic"],
 							description: "Whether Hardfin sets the asset's in-service date itself",
+							negatable: true,
 							required: true,
 							schema: z.boolean()
 						}]
@@ -3361,12 +3437,14 @@ const surfaceCommands = [
 						name: "is-customer",
 						jsonPath: ["isCustomer"],
 						description: "Whether the company is a customer",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-supplier",
 						jsonPath: ["isSupplier"],
 						description: "Whether the company is a supplier",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -3466,6 +3544,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the customer is archived",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3473,6 +3552,7 @@ const surfaceCommands = [
 						name: "is-customer",
 						jsonPath: ["isCustomer"],
 						description: "Whether the company is a customer",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3480,6 +3560,7 @@ const surfaceCommands = [
 						name: "is-supplier",
 						jsonPath: ["isSupplier"],
 						description: "Whether the company is a supplier",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3554,7 +3635,8 @@ const surfaceCommands = [
 				description: "True when the file downloads as an attachment rather than opening inline",
 				schema: z.boolean()
 			}],
-			bodyFlags: []
+			bodyFlags: [],
+			downloads: true
 		})]
 	},
 	{
@@ -3657,6 +3739,7 @@ const surfaceCommands = [
 						name: "accepts-bulk-serials",
 						jsonPath: ["acceptsBulkSerials"],
 						description: "Whether a BULK item records serial numbers on its units, which SERVICE and DEVICE items ignore",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -3793,6 +3876,7 @@ const surfaceCommands = [
 						name: "accepts-bulk-serials",
 						jsonPath: ["acceptsBulkSerials"],
 						description: "Whether a BULK item records serial numbers on its units, read only beside type",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3821,6 +3905,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the item is archived, which cannot be null",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4290,18 +4375,21 @@ const surfaceCommands = [
 						name: "is-inventory",
 						jsonPath: ["isInventory"],
 						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-inventory-override",
 						jsonPath: ["isInventoryOverride"],
 						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-transient",
 						jsonPath: ["isTransient"],
 						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -4443,6 +4531,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the location is archived, and archiving a site archives its zones",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4450,6 +4539,7 @@ const surfaceCommands = [
 						name: "is-inventory",
 						jsonPath: ["isInventory"],
 						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4457,6 +4547,7 @@ const surfaceCommands = [
 						name: "is-inventory-override",
 						jsonPath: ["isInventoryOverride"],
 						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4464,6 +4555,7 @@ const surfaceCommands = [
 						name: "is-transient",
 						jsonPath: ["isTransient"],
 						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4871,13 +4963,16 @@ function toRejectedFlag(command, flags) {
 	}
 }
 //#endregion
-//#region src/cli.ts
-const program = new Command();
-program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").option("--api-url <url>", "The API to call, whose host also holds the authorization server").option("--issuer-url <url>", "The authorization server, when it does not sit at the API's host").showHelpAfterError().enablePositionalOptions();
-for (const command of commands) program.addCommand(toProgram(command), { hidden: command.hidden });
-await program.parseAsync(process.argv);
+//#region src/cli/program.ts
+/** toCli builds the parser from the registry, which is what every surface reads. */
+function toCli(entries = commands) {
+	const program = new Command();
+	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").option("--api-url <url>", "The API to call, whose host also holds the authorization server").option("--issuer-url <url>", "The authorization server, when it does not sit at the API's host").showHelpAfterError().enablePositionalOptions();
+	for (const command of entries) program.addCommand(toProgram(program, command), { hidden: command.hidden });
+	return program;
+}
 /** toProgram wires one registry command into the parser. */
-function toProgram(command) {
+function toProgram(root, command) {
 	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
 	for (const argument of command.arguments) {
 		const name = argument.variadic ? `${argument.name}...` : argument.name;
@@ -4887,21 +4982,22 @@ function toProgram(command) {
 		const short = flag.short ? `-${flag.short}, ` : "";
 		const value = flag.valueName ? ` <${flag.valueName}>` : "";
 		const option = new Option(`${short}--${flag.name}${value}`, flag.description);
+		if (flag.negatable) program.addOption(new Option(`--no-${flag.name}`, `${flag.description}, turned off`));
 		if (flag.repeatable) option.argParser(collect);
 		if (flag.defaultValue !== void 0) option.default(flag.defaultValue);
 		program.addOption(option);
 	}
 	for (const example of command.examples) program.addHelpText("after", `\n${example.description}:\n  $ ${example.command}`);
-	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(subcommand), { hidden: subcommand.hidden });
+	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(root, subcommand), { hidden: subcommand.hidden });
 	if (!command.run) return program;
 	program.action(async (...parsed) => {
 		const flags = parsed[parsed.length - 2] ?? {};
 		const args = parsed.slice(0, parsed.length - 2).flatMap(toArgumentList);
-		process.exitCode = await toExitCode(command, args, flags);
+		process.exitCode = await toExitCode(root, command, args, flags);
 	});
 	return program;
 }
-async function toExitCode(command, args, flags) {
+async function toExitCode(root, command, args, flags) {
 	const isJSON = isJSONOutput(flags);
 	const rejected = toRejectedFlag(command, flags);
 	if (rejected) {
@@ -4910,8 +5006,8 @@ async function toExitCode(command, args, flags) {
 	}
 	try {
 		const resolved = toSettings({
-			apiUrl: program.opts()["apiUrl"],
-			issuerUrl: program.opts()["issuerUrl"]
+			apiUrl: root.opts()["apiUrl"],
+			issuerUrl: root.opts()["issuerUrl"]
 		});
 		return await command.run?.({
 			args,
@@ -4933,4 +5029,7 @@ function collect(value, previous) {
 	return [...previous ?? [], value];
 }
 //#endregion
+//#region src/cli.ts
+await toCli().parseAsync(process.argv);
+//#endregion
 export {};

package/package.json

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