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

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

@@ -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}`;
 }
@@ -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()
 					},
@@ -4887,6 +4979,7 @@ 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);

package/package.json

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