@hardfin/cli 0.1.0-dev.31 → 0.1.0-dev.33

package/README.md

@@ -77,6 +77,15 @@ hardfin file get file_7hq2mx9pkr4stz8w --output photo.jpg
 hardfin file get file_7hq2mx9pkr4stz8w --output - | wc -c
 ```
 
+Send a whole body as JSON with `--input`, from a file or from standard input. A flag given as
+well replaces its field, and a required field the body carries needs no flag. A value with a
+comma in it, which a `key=value` flag cannot carry, goes through `--input`.
+
+```sh
+hardfin location create --input location.json
+echo '{"name": "Dock 4, north side"}' | hardfin location create --input -
+```
+
 Clear a field with `--unset`, naming the flag:
 
 ```sh
@@ -199,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

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]="bb3026cb-ab06-5af0-9743-290b61ec91a3")}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]="3f5ddeb4-6ae9-5ded-b447-15c8483fc583")}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-B0vISolG.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-ByvcKNri.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-B0vISolG.js");
+		const { toReported } = await import("./program-ByvcKNri.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=bb3026cb-ab06-5af0-9743-290b61ec91a3
+//# debugId=3f5ddeb4-6ae9-5ded-b447-15c8483fc583

package/dist/completion-tree.json

@@ -351,6 +351,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -384,6 +389,11 @@
                       "valueName": "assetId=,deliverAt=,deliverAtTimezone=,destinationId=,originId=,shipAt=,shipAtTimezone=",
                       "repeatable": true
                     },
+                    {
+                      "name": "input",
+                      "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                      "valueName": "path"
+                    },
                     {
                       "name": "json",
                       "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -412,6 +422,11 @@
                       "valueName": "assetId=,deliverAt=,id=,shipAt=",
                       "repeatable": true
                     },
+                    {
+                      "name": "input",
+                      "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                      "valueName": "path"
+                    },
                     {
                       "name": "json",
                       "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -487,6 +502,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -596,6 +616,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -623,6 +648,11 @@
                       "description": "Whether Hardfin sets the asset's in-service date itself",
                       "negatable": true
                     },
+                    {
+                      "name": "input",
+                      "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                      "valueName": "path"
+                    },
                     {
                       "name": "json",
                       "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -695,6 +725,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -893,6 +928,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -913,6 +953,11 @@
                   "description": "The day your organization takes the asset back, which cannot be in the future",
                   "valueName": "value"
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -965,6 +1010,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1027,6 +1077,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1106,6 +1161,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1165,6 +1225,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1313,6 +1378,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1402,6 +1472,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1664,6 +1739,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1739,6 +1819,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1838,6 +1923,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1898,6 +1988,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -1924,6 +2019,11 @@
                   "valueName": "field",
                   "repeatable": true
                 },
+                {
+                  "name": "input",
+                  "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+                  "valueName": "path"
+                },
                 {
                   "name": "json",
                   "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -2141,6 +2241,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -2260,6 +2365,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"
@@ -2371,6 +2481,11 @@
               "valueName": "field",
               "repeatable": true
             },
+            {
+              "name": "input",
+              "description": "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+              "valueName": "path"
+            },
             {
               "name": "json",
               "description": "Print machine-readable output, which is the default when stdout is not a terminal"

package/dist/{program-B0vISolG.js → program-ByvcKNri.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]="ab584cf3-443f-569e-8167-fa0cbab9ab68")}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]="93b4bc8d-ebeb-59ca-967b-9fd10484e4a5")}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",
 		"",
@@ -1065,6 +1066,31 @@ function toSummary(command) {
 		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
 	};
 }
+//#endregion
+//#region src/command/input.ts
+/** InputFailure is a body given with --input that cannot be used, and says why. */
+var InputFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InputFailure";
+	}
+};
+/** toJSONInput reads the JSON a command was given with --input, from a file or from standard input. */
+function toJSONInput(source) {
+	const name = source === "-" ? "standard input" : source;
+	let text;
+	try {
+		text = readFileSync(source === "-" ? 0 : source, "utf8");
+	} catch {
+		return new InputFailure(`${name} cannot be read`);
+	}
+	if (text.trim() === "") return new InputFailure(`${name} is empty, and a body needs JSON`);
+	try {
+		return JSON.parse(text);
+	} catch {
+		return new InputFailure(`${name} does not hold JSON`);
+	}
+}
 const apiCommand = defineCommand({
 	name: "api",
 	summary: "Call a Hardfin API endpoint and print what it answers",
@@ -1142,9 +1168,9 @@ async function runApi(input) {
 	}
 	let body;
 	if (typeof input.flags["input"] === "string") {
-		body = toBody$1(input.flags["input"]);
-		if (body === void 0) {
-			writeFailure("invalid_input", `${input.flags["input"]} does not hold JSON`, input.isJSON);
+		body = toJSONInput(input.flags["input"]);
+		if (body instanceof InputFailure) {
+			writeFailure("invalid_input", body.message, input.isJSON);
 			return ExitCode.USAGE;
 		}
 	}
@@ -1180,14 +1206,6 @@ function toQuery$1(fields) {
 	}
 	return query;
 }
-function toBody$1(source) {
-	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
-	try {
-		return JSON.parse(text);
-	} catch {
-		return;
-	}
-}
 //#endregion
 //#region src/auth/browser.ts
 /** isWSL reports whether this Linux is running under Windows. */
@@ -2137,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;
@@ -2147,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;
@@ -2183,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}`,
@@ -2235,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);
@@ -3097,6 +3133,12 @@ const UNSET_FLAG = {
 	repeatable: true,
 	schema: z.array(z.string())
 };
+const INPUT_FLAG = {
+	name: "input",
+	description: "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+	valueName: "path",
+	schema: z.string()
+};
 const FILE_FLAG = {
 	name: "file",
 	description: "The file to upload",
@@ -3120,6 +3162,7 @@ function defineOperation(operation) {
 		...operation.queryFlags,
 		...operation.bodyFlags,
 		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
+		...operation.bodyFlags.length > 0 ? [INPUT_FLAG] : [],
 		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
 		...operation.downloads ? [OUTPUT_FLAG] : [],
 		JSON_FLAG
@@ -3147,12 +3190,17 @@ async function runOperation(operation, input) {
 		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0);
+	const given = toGivenBody(input.flags["input"]);
+	if (given instanceof InputFailure) {
+		writeFailure("invalid_input", given.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0 && !hasPath(given, flag.jsonPath));
 	if (missing.length > 0) {
 		writeFailure("missing_flag", `this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const body = toBody(operation, input.flags);
+	const body = toBody(operation, input.flags, given);
 	if (body instanceof Error) {
 		writeFailure("invalid_flag", body.message, input.isJSON);
 		return ExitCode.USAGE;
@@ -3261,10 +3309,27 @@ async function toForm(upload, flags) {
 	}
 	return form;
 }
-/** toBody builds the request body from the flags, one field at a time. */
-function toBody(operation, flags) {
-	const body = {};
-	let hasField = false;
+/** toGivenBody reads the --input body, which a generated command takes only as a JSON object. */
+function toGivenBody(source) {
+	if (typeof source !== "string") return;
+	const read = toJSONInput(source);
+	if (read instanceof InputFailure) return read;
+	if (typeof read !== "object" || read === null || Array.isArray(read)) return new InputFailure(`the body in ${source === "-" ? "standard input" : source} must be a JSON object, such as {"name": "Acme"}`);
+	return read;
+}
+/** hasPath reports whether a body already holds a value at a field's path. */
+function hasPath(body, path) {
+	let holder = body;
+	for (const name of path) {
+		if (typeof holder !== "object" || holder === null || !(name in holder)) return false;
+		holder = holder[name];
+	}
+	return true;
+}
+/** toBody builds the request body from the --input body and the flags, a flag winning over its field. */
+function toBody(operation, flags, given) {
+	const body = given ? structuredClone(given) : {};
+	let hasField = given !== void 0;
 	for (const flag of operation.bodyFlags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
@@ -6122,5 +6187,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-B0vISolG.js.map
-//# debugId=ab584cf3-443f-569e-8167-fa0cbab9ab68
+//# sourceMappingURL=program-ByvcKNri.js.map
+//# debugId=93b4bc8d-ebeb-59ca-967b-9fd10484e4a5

package/package.json

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