@hardfin/cli 0.1.1-dev.54 → 0.1.1-dev.56

package/README.md

@@ -72,6 +72,19 @@ 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.
 
+Inside a `key=value` flag, `=` gives a value as you typed it and `:=` gives it as JSON.
+
+| You type                | Is sent as                                                         |
+| ----------------------- | ------------------------------------------------------------------ |
+| `value=36`              | the text "36", because a custom field may hold a serial number     |
+| `value:=36`             | the number 36                                                      |
+| `value:=true`           | the boolean true                                                   |
+| `deliverAt:=null`       | null                                                               |
+| `order=2` or `order:=2` | the number 2, because the document types `order` as a whole number |
+
+A value the field does not take fails locally with exit code 2, such as `order=two`, or
+`id:=42` for a field that takes text alone.
+
 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
@@ -411,7 +424,8 @@ projects come ready. Running it again updates only what it wrote.
 | `.vscode/mcp.json`                    | The `hardfin` server, for VS Code                                   |
 
 The server is the hosted one at the authorization server's host, `https://api.hardfin.com/mcp`
-by default. Every other server in an MCP config, and everything in `AGENTS.md` outside the
+by default. [Serving an agent](#serving-an-agent) says how it differs from the local server
+this CLI runs. Every other server in an MCP config, and everything in `AGENTS.md` outside the
 markers, is left as it was. A config that does not hold JSON is skipped, never overwritten.
 
 `init` refuses an address that `config.local.json` or `.env` in the folder chose, because the
@@ -423,17 +437,46 @@ package, so `init` writes the copy that matches the installed CLI.
 
 ## Serving an agent
 
+Hardfin has two MCP servers, and an agent needs only one of them. Hardfin hosts one. The
+other is this CLI, run on your machine. Read this section to choose between them.
+
+|                       | The hosted server                                                    | The local server                                       |
+| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
+| Runs                  | At Hardfin, at `https://api.hardfin.com/mcp`                         | On your machine, started by the agent's client         |
+| Needs installed       | Nothing                                                              | This CLI, and Node 20.12 or later                      |
+| Set up by             | `hardfin init`                                                       | `claude mcp add hardfin -- hardfin mcp`                |
+| Signs in as           | Whoever signs in to Hardfin from the client                          | Whoever ran `hardfin login` here, or `HARDFIN_API_KEY` |
+| Tools                 | `hardfin_read`, `hardfin_create`, `hardfin_update`, `hardfin_delete` | `hardfin_read`, `hardfin_write`, `hardfin_delete`      |
+| A call names          | An operation from the API reference, with its parameters and body    | A command, as the words typed after `hardfin`          |
+| Read-only when        | The sign in was not granted `hardfin:write`                          | The same, or it was started with `--read-only`         |
+| Files on your machine | Out of reach                                                         | Uploaded and downloaded, inside the folder it runs in  |
+
+Choose the hosted server unless one of these holds.
+
+- The agent has to upload a file from your machine, or download one to it
+- The agent runs where your browser cannot sign in to Hardfin, and you have a stored sign in or an API key on the machine
+- You want a local build of the API, which `hardfin mcp` reaches through `config.local.json`
+
+The two servers place one command differently. Scrapping an asset goes through
+`hardfin_delete` on the local server and through `hardfin_update` on the hosted one. Both ask
+before it by default, because both tools carry the destructive hint.
+
+Both set-ups name the server `hardfin`, so adding one to a project replaces the other. To run
+both, give the local one another name:
+
 ```sh
-hardfin mcp
+claude mcp add hardfin-local -- hardfin mcp
 ```
 
-It speaks the Model Context Protocol on standard input and output, so Claude, Codex or any
-other client can run Hardfin commands.
+The rest of this section is about the local server.
 
 ```sh
-claude mcp add hardfin -- hardfin mcp
+hardfin mcp
 ```
 
+It speaks the Model Context Protocol on standard input and output, so Claude, Codex or any
+other client can run Hardfin commands.
+
 ### Three tools, and resources for the rest
 
 Every tool a server lists sits in the agent's context for the entire session, so this server

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]="c6243d33-fcd1-5df5-9405-f1e6448344d6")}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]="ec88336e-026f-5a04-9acd-43c5410c3229")}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-BhH7Zc0y.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CI4W2agw.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported, writeCrash } = await import("./program-BhH7Zc0y.js");
+		const { toReported, writeCrash } = await import("./program-CI4W2agw.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -54,4 +54,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=c6243d33-fcd1-5df5-9405-f1e6448344d6
+//# debugId=ec88336e-026f-5a04-9acd-43c5410c3229

package/dist/{program-BhH7Zc0y.js → program-CI4W2agw.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]="91a42949-4ebc-5767-bd2f-75c98f7b5603")}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]="cb5319cf-733c-5f06-b5d8-f8f154bf4267")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
@@ -1477,7 +1477,8 @@ function toDescribed(flag) {
 		default: flag.defaultValue,
 		schema: toFlagSchema(flag),
 		sends: sent.queryName !== void 0 ? { query: sent.queryName } : sent.jsonPath !== void 0 ? { body: sent.jsonPath } : void 0,
-		element: sent.element
+		element: sent.element,
+		elementTypes: sent.elementTypes
 	};
 	return Object.fromEntries(Object.entries(described).filter(([, value]) => value !== void 0 && value !== false));
 }
@@ -3356,17 +3357,64 @@ function toElements(flag, values) {
 		for (const pair of value.split(",")) {
 			const split = pair.indexOf("=");
 			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ") ?? ""}=, such as --${flag.name} ${flag.element?.[0] ?? "field"}=value. A value cannot contain a comma`);
-			const key = pair.slice(0, split).trim();
+			const isJSON = pair[split - 1] === ":";
+			const key = pair.slice(0, isJSON ? split - 1 : split).trim();
 			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
 			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
 			const value = pair.slice(split + 1).trim();
 			if (flag.elementUuids?.includes(key) && !z.uuid().safeParse(value).success) return /* @__PURE__ */ new Error(`--${flag.name} needs a UUID for ${key}, such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90, and ${value || "nothing"} is not one`);
-			element[key] = value;
+			const types = flag.elementTypes?.[key];
+			const typed = isJSON ? toJSONValue(value, types ?? ["string"]) : toTyped(value, types);
+			if (typed === NOT_TAKEN) return /* @__PURE__ */ new Error(`--${flag.name} needs ${toNamedTypes(types ?? ["string"])} for ${key}, and ${value || "nothing"} is not one`);
+			element[key] = typed;
 		}
 		elements.push(element);
 	}
 	return elements;
 }
+/** Marks text that is none of the types a field takes. */
+const NOT_TAKEN = Symbol("not taken");
+const NUMBER = /^-?\d+(\.\d+)?$/;
+/**
+* toTyped reads the text after key= as the type the document gives the field. A field that
+* takes text is sent as typed, whatever it looks like, because 36 may be a serial number. A
+* field that takes no text has only one reading, so order=2 is sent as the number.
+*/
+function toTyped(text, types) {
+	if (types === void 0 || types.includes("string")) return text;
+	if (types.includes("null") && text === "null") return null;
+	if ((types.includes("integer") || types.includes("number")) && NUMBER.test(text)) {
+		const value = Number(text);
+		if (types.includes("number") || Number.isInteger(value)) return value;
+	}
+	if (types.includes("boolean") && (text === "true" || text === "false")) return text === "true";
+	return NOT_TAKEN;
+}
+/**
+* toJSONValue reads the text after key:= as JSON, and takes it when the field takes its type.
+* It is how a custom field is given the number 36 or true, where key= would send the text.
+*/
+function toJSONValue(text, types) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return NOT_TAKEN;
+	}
+	const type = value === null ? "null" : typeof value;
+	return (types.includes(type) || type === "number" && types.includes("integer") && Number.isInteger(value)) && type !== "object" ? value : NOT_TAKEN;
+}
+/** toNamedTypes says in words what a field takes, for the message that refuses a value. */
+function toNamedTypes(types) {
+	const named = {
+		integer: "a whole number",
+		number: "a number",
+		boolean: "true or false",
+		string: "text in quotes",
+		null: "null"
+	};
+	return types.filter((type) => type in named).map((type) => named[type]).join(" or ");
+}
 /** set writes a value at its path, building the objects a nested field needs. */
 function set(body, path, value) {
 	let holder = body;
@@ -4826,6 +4874,12 @@ const commands = [
 									"destinationId",
 									"originId"
 								],
+								elementTypes: {
+									"deliverAt": ["string", "null"],
+									"deliverAtTimezone": ["string", "null"],
+									"shipAt": ["string", "null"],
+									"shipAtTimezone": ["string", "null"]
+								},
 								schema: z.array(z.string())
 							}]
 						})]
@@ -4856,6 +4910,10 @@ const commands = [
 									"shipAt"
 								],
 								elementUuids: ["assetId"],
+								elementTypes: {
+									"deliverAt": ["string", "null"],
+									"shipAt": ["string", "null"]
+								},
 								schema: z.array(z.string())
 							}]
 						})]
@@ -4933,6 +4991,14 @@ const commands = [
 							repeatable: true,
 							element: ["fieldId", "value"],
 							elementUuids: ["fieldId"],
+							elementTypes: { "value": [
+								"array",
+								"boolean",
+								"number",
+								"object",
+								"string",
+								"null"
+							] },
 							schema: z.array(z.string())
 						},
 						{
@@ -6277,6 +6343,10 @@ const commands = [
 								"section"
 							],
 							elementUuids: ["fieldId"],
+							elementTypes: {
+								"order": ["integer"],
+								"section": ["integer"]
+							},
 							schema: z.array(z.string())
 						},
 						{
@@ -7177,5 +7247,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-BhH7Zc0y.js.map
-//# debugId=91a42949-4ebc-5767-bd2f-75c98f7b5603
+//# sourceMappingURL=program-CI4W2agw.js.map
+//# debugId=cb5319cf-733c-5f06-b5d8-f8f154bf4267

package/package.json

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