@hardfin/cli 0.1.0-dev.19 → 0.1.0-dev.21

package/README.md

@@ -63,8 +63,7 @@ hardfin asset ownership create ast_4f9xk2mq7plr8stz \
   --customer-id cst_a1 --date 2026-09-23 --sale-price 1500.00
 
 hardfin asset move execute create \
-  --move assetId=ast_a1,locationId=loc_x \
-  --move assetId=ast_b2,locationId=loc_y
+  --move assetId=0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d70,originId=0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d71,destinationId=0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d72,shipAt=2026-09-24T10:00:00Z
 ```
 
 A value is sent as the type the document names. `--useful-life 36` sends the number 36. A
@@ -343,6 +342,11 @@ The CLI reads whatever `config.local.json` and `.env` sit in the directory you r
 A directory you do not control can therefore point the CLI at a server you do not expect, so
 run `hardfin config` when a command reaches somewhere surprising.
 
+A sign in is not carried there. An access token is sent only to the host that issued it, and
+only over https unless that host is this machine. Pointing `apiUrl` elsewhere gets a refusal
+naming both hosts, rather than a token sent to a stranger. An API key is sent wherever you
+point it, because setting one is a deliberate act.
+
 ## Working on the CLI
 
 ```sh

package/dist/cli.js

@@ -139,9 +139,9 @@ function writeData(value) {
 	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) {
+function writeFailure(message, isJSON, errors, requestId, status) {
 	if (!isJSON) {
-		process.stderr.write(`error: ${message}\n`);
+		process.stderr.write(`error: ${message}${status === void 0 ? "" : ` (HTTP ${status})`}\n`);
 		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${entry.error} (${entry.statusCode})\n`);
 		if (requestId) process.stderr.write(`  request ${requestId}\n`);
 		return;
@@ -151,7 +151,8 @@ function writeFailure(message, isJSON, errors, requestId) {
 			error: message,
 			statusCode: 0
 		}],
-		requestId: requestId ?? null
+		requestId: requestId ?? null,
+		status: status ?? null
 	};
 	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
@@ -289,112 +290,6 @@ function toScopes(decoded) {
 	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
 }
 //#endregion
-//#region src/auth/metadata.ts
-const METADATA_PATH = "/.well-known/oauth-authorization-server";
-const AuthorizationServerMetadata = z.looseObject({
-	issuer: z.string(),
-	authorization_endpoint: z.string(),
-	token_endpoint: z.string(),
-	revocation_endpoint: z.string().optional(),
-	device_authorization_endpoint: z.string().optional(),
-	scopes_supported: z.array(z.string()).optional(),
-	grant_types_supported: z.array(z.string()).optional(),
-	code_challenge_methods_supported: z.array(z.string()).optional()
-});
-/** DiscoveryFailure is an authorization server that cannot be read or does not describe itself. */
-var DiscoveryFailure = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "DiscoveryFailure";
-	}
-};
-/** toMetadata reads what an authorization server says about itself. */
-async function toMetadata(issuer) {
-	const url = `${issuer.replace(/\/+$/, "")}${METADATA_PATH}`;
-	let response;
-	try {
-		response = await fetch(url, { headers: { Accept: "application/json" } });
-	} catch (error) {
-		throw new DiscoveryFailure(`${url} could not be reached: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (!response.ok) throw new DiscoveryFailure(`${url} answered ${response.status}, so this host publishes no authorization server`);
-	const parsed = AuthorizationServerMetadata.safeParse(await response.json().catch(() => void 0));
-	if (!parsed.success) throw new DiscoveryFailure(`${url} does not describe an authorization server`);
-	if (parsed.data.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new DiscoveryFailure(`${url} names issuer ${parsed.data.issuer}, which is not the host it was read from`);
-	return parsed.data;
-}
-//#endregion
-//#region src/auth/grant.ts
-const TokenResponse = z.looseObject({
-	access_token: z.string(),
-	token_type: z.string(),
-	expires_in: z.number().optional(),
-	refresh_token: z.string().optional(),
-	refresh_token_expires_in: z.number().optional(),
-	scope: z.string().optional()
-});
-/** GrantFailure is a token request the authorization server refused. */
-var GrantFailure = class extends Error {
-	code;
-	constructor(code, description) {
-		super(description ? `${code}: ${description}` : code);
-		this.name = "GrantFailure";
-		this.code = code;
-	}
-};
-/** toTokensFromCode trades an authorization code for tokens. */
-async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
-	return await toTokens(tokenUrl, {
-		grant_type: "authorization_code",
-		client_id: clientId,
-		code,
-		redirect_uri: redirectUri,
-		code_verifier: pkce.verifier
-	});
-}
-/** toTokensFromRefresh trades a refresh token for a fresh pair. */
-async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
-	return await toTokens(tokenUrl, {
-		grant_type: "refresh_token",
-		client_id: clientId,
-		refresh_token: refreshToken
-	});
-}
-/** revoke tells the server to forget a token, so signing out reaches every machine. */
-async function revoke(revocationUrl, clientId, token) {
-	await fetch(revocationUrl, {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: new URLSearchParams({
-			client_id: clientId,
-			token,
-			token_type_hint: "refresh_token"
-		})
-	});
-}
-/** toTokens asks the token endpoint, which answers a flat RFC 6749 body, not the envelope. */
-async function toTokens(url, form) {
-	const response = await fetch(url, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/x-www-form-urlencoded",
-			Accept: "application/json"
-		},
-		body: new URLSearchParams(form)
-	});
-	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
-	const parsed = TokenResponse.safeParse(body);
-	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
-	return {
-		accessToken: parsed.data.access_token,
-		refreshToken: parsed.data.refresh_token,
-		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
-		scope: parsed.data.scope,
-		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
-	};
-}
-//#endregion
 //#region src/credential/store.ts
 const load = createRequire(import.meta.url);
 /** The service a keyring entry is filed under, alongside the issuer it belongs to. */
@@ -414,7 +309,7 @@ function toCredentialPath() {
 * family lifetime runs from. Callers hold the credential lock, which is what makes a write
 * from another process merge rather than disappear.
 */
-function keep(issuer, refreshToken, expiresAt) {
+function keep$1(issuer, refreshToken, expiresAt) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const record = {
 		refreshToken,
@@ -526,6 +421,147 @@ function writeFile(held) {
 	renameSync(pending, path);
 }
 //#endregion
+//#region src/auth/metadata.ts
+const METADATA_PATH = "/.well-known/oauth-authorization-server";
+const AuthorizationServerMetadata = z.looseObject({
+	issuer: z.string(),
+	authorization_endpoint: z.string(),
+	token_endpoint: z.string(),
+	revocation_endpoint: z.string().optional(),
+	device_authorization_endpoint: z.string().optional(),
+	scopes_supported: z.array(z.string()).optional(),
+	grant_types_supported: z.array(z.string()).optional(),
+	code_challenge_methods_supported: z.array(z.string()).optional()
+});
+/** DiscoveryFailure is an authorization server that cannot be read or does not describe itself. */
+var DiscoveryFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiscoveryFailure";
+	}
+};
+/** How long a discovery document is reused, which is the hour the server asks for. */
+const CACHE_MS = 36e5;
+/** toMetadata reads what an authorization server says about itself. */
+async function toMetadata(issuer) {
+	const cached = toCached(issuer);
+	if (cached) return cached;
+	const url = `${issuer.replace(/\/+$/, "")}${METADATA_PATH}`;
+	let response;
+	try {
+		response = await fetch(url, { headers: { Accept: "application/json" } });
+	} catch (error) {
+		throw new DiscoveryFailure(`${url} could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) throw new DiscoveryFailure(`${url} answered ${response.status}, so this host publishes no authorization server`);
+	const parsed = AuthorizationServerMetadata.safeParse(await response.json().catch(() => void 0));
+	if (!parsed.success) throw new DiscoveryFailure(`${url} does not describe an authorization server`);
+	if (parsed.data.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new DiscoveryFailure(`${url} names issuer ${parsed.data.issuer}, which is not the host it was read from`);
+	keep(issuer, parsed.data);
+	return parsed.data;
+}
+/** toCachePath names where one server's document is kept, beside the credentials. */
+function toCachePath(issuer) {
+	const name = createHash("sha256").update(issuer).digest("hex").slice(0, 16);
+	return join(dirname(toCredentialPath()), `metadata-${name}.json`);
+}
+function toCached(issuer) {
+	const path = toCachePath(issuer);
+	if (!existsSync(path)) return;
+	try {
+		const held = JSON.parse(readFileSync(path, "utf8"));
+		if ((held.readAt ?? 0) + CACHE_MS < Date.now()) return;
+		const parsed = AuthorizationServerMetadata.safeParse(held.document);
+		return parsed.success ? parsed.data : void 0;
+	} catch {
+		return;
+	}
+}
+function keep(issuer, document) {
+	const path = toCachePath(issuer);
+	try {
+		mkdirSync(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(path, JSON.stringify({
+			readAt: Date.now(),
+			document
+		}), { mode: 384 });
+	} catch {}
+}
+//#endregion
+//#region src/auth/grant.ts
+const TokenResponse = z.looseObject({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	refresh_token_expires_in: z.number().optional(),
+	scope: z.string().optional()
+});
+/** GrantFailure is a token request the authorization server refused. */
+var GrantFailure = class extends Error {
+	code;
+	constructor(code, description) {
+		super(description ? `${code}: ${description}` : code);
+		this.name = "GrantFailure";
+		this.code = code;
+	}
+};
+/** toTokensFromCode trades an authorization code for tokens. */
+async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
+	return await toTokens(tokenUrl, {
+		grant_type: "authorization_code",
+		client_id: clientId,
+		code,
+		redirect_uri: redirectUri,
+		code_verifier: pkce.verifier
+	});
+}
+/** toTokensFromRefresh trades a refresh token for a fresh pair. */
+async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
+	return await toTokens(tokenUrl, {
+		grant_type: "refresh_token",
+		client_id: clientId,
+		refresh_token: refreshToken
+	});
+}
+/** revoke tells the server to forget a token, so signing out reaches every machine. */
+async function revoke(revocationUrl, clientId, token) {
+	await fetch(revocationUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: clientId,
+			token,
+			token_type_hint: "refresh_token"
+		})
+	});
+}
+/** toTokens asks the token endpoint, which answers a flat RFC 6749 body, not the envelope. */
+async function toTokens(url, form) {
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams(form)
+	});
+	const body = await response.json().catch(() => void 0);
+	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
+	const parsed = TokenResponse.safeParse(body);
+	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
+	return {
+		accessToken: parsed.data.access_token,
+		refreshToken: parsed.data.refresh_token,
+		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
+		scope: parsed.data.scope,
+		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
+	};
+}
+//#endregion
 //#region src/credential/lock.ts
 /** A lock held longer than this belongs to a process that died, so it is taken. */
 const STALE_MS = 3e4;
@@ -636,6 +672,7 @@ async function toRequestCredential(settings) {
 		value: settings.apiKey,
 		kind: "api key"
 	};
+	refuseForeignHost(settings);
 	const stored = toCredential(settings.issuerUrl);
 	if (!stored) throw new NoCredential("not authenticated. Run hardfin login, or set HARDFIN_API_KEY");
 	return {
@@ -693,11 +730,33 @@ function toDated(tokens) {
 function store(issuer, tokens, previous) {
 	if (!tokens.refreshToken || tokens.refreshToken === previous) return;
 	try {
-		keep(issuer, tokens.refreshToken, tokens.refreshExpiresAt);
+		keep$1(issuer, tokens.refreshToken, tokens.refreshExpiresAt);
 	} catch (error) {
 		process.stderr.write(`warning: this sign in was renewed but could not be stored, so the next command will ask you to sign in again: ${error instanceof Error ? error.message : String(error)}\n`);
 	}
 }
+/**
+* refuseForeignHost keeps an access token on the host that issued it. The API URL and the
+* authorization server are configured separately, and a directory's config file can set
+* either, so nothing else stops a token minted for Hardfin being sent somewhere else.
+*/
+function refuseForeignHost(settings) {
+	const api = toHost(settings.apiUrl);
+	const issuer = toHost(settings.issuerUrl);
+	if (api === void 0 || issuer === void 0) throw new NoCredential(`${settings.apiUrl} is not a URL this CLI can call`);
+	if (api.host !== issuer.host) throw new NoCredential(`this sign in belongs to ${issuer.host}, so it is not sent to ${api.host}. Set HARDFIN_API_KEY to call another host, or point --issuer-url at the server that signs you in`);
+	if (api.protocol !== "https:" && !isLoopback(api.hostname)) throw new NoCredential(`${settings.apiUrl} is not https, so a sign in is not sent to it`);
+}
+function toHost(url) {
+	try {
+		return new URL(url);
+	} catch {
+		return;
+	}
+}
+function isLoopback(hostname) {
+	return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
+}
 /** forgetHeldTokens drops the access tokens this process is holding. */
 function forgetHeldTokens() {
 	held.clear();
@@ -838,6 +897,10 @@ async function runApi(input) {
 		writeFailure("a path is required, such as /customer", input.isJSON);
 		return ExitCode.USAGE;
 	}
+	if (path.split("/").includes("..")) {
+		writeFailure("a path stays inside the API, so it cannot contain ..", input.isJSON);
+		return ExitCode.USAGE;
+	}
 	const query = toQuery$1(input.flags["field"]);
 	if (query === void 0) {
 		writeFailure("each --field is key=value, such as -f limit=50", input.isJSON);
@@ -867,7 +930,7 @@ async function runApi(input) {
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
@@ -993,31 +1056,100 @@ async function runCompletion(input) {
 }
 /** toScript writes a shell's completion, each one asking __complete for the candidates. */
 function toScript(shell) {
-	if (shell === "bash") return `# hardfin completion for bash
+	return SCRIPTS[shell];
+}
+const SCRIPTS = {
+	bash: `# hardfin completion for bash
+_hardfin_words() {
+  # Bash splits a word at = and :, so the pieces are joined again wherever no space
+  # separates them in the line, and the word under the cursor ends at the cursor.
+  local line=\${COMP_LINE:0:COMP_POINT} offset=0 i word rest gap
+  _hardfin_line_words=()
+
+  for ((i = 0; i <= COMP_CWORD; i++)); do
+    rest=\${line:offset}
+
+    if ((i < COMP_CWORD)); then
+      word=\${COMP_WORDS[i]}
+      gap=\${rest%%"$word"*}
+      offset=$((offset + \${#gap} + \${#word}))
+    else
+      word=\${rest#"\${rest%%[![:space:]]*}"}
+      gap=\${rest%"$word"}
+    fi
+
+    if ((i > 0)) && [[ -z $gap ]]; then
+      _hardfin_line_words[\${#_hardfin_line_words[@]} - 1]+=$word
+    else
+      _hardfin_line_words+=("$word")
+    fi
+  done
+}
+
 _hardfin_complete() {
-  local words
-  words=("\${COMP_WORDS[@]:1}")
-  COMPREPLY=($(hardfin __complete -- "\${words[@]}" 2>/dev/null))
+  local _hardfin_line_words candidate current prefix breaks
+  _hardfin_words
+  COMPREPLY=()
+
+  while IFS= read -r candidate; do
+    COMPREPLY+=("$candidate")
+  done < <(hardfin __complete -- "\${_hardfin_line_words[@]:1}" 2>/dev/null)
+
+  # Readline replaces only the text after the last = or : in the word, so a candidate
+  # loses what comes before it or the line would repeat that part.
+  current=\${_hardfin_line_words[\${#_hardfin_line_words[@]} - 1]}
+  breaks=\${COMP_WORDBREAKS//[^=:]/}
+
+  if [[ -n $breaks && $current == *["$breaks"]* ]]; then
+    prefix=\${current%"\${current##*["$breaks"]}"}
+    COMPREPLY=("\${COMPREPLY[@]#"$prefix"}")
+  fi
 }
-complete -F _hardfin_complete hardfin`;
-	if (shell === "zsh") return `# hardfin completion for zsh
+
+complete -F _hardfin_complete hardfin`,
+	zsh: `# hardfin completion for zsh
 _hardfin_complete() {
   local -a candidates
-  candidates=(\${(f)"$(hardfin __complete -- \${words[2,-1]} 2>/dev/null)"})
+  candidates=(\${(f)"$(hardfin __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)"})
   compadd -a candidates
 }
-compdef _hardfin_complete hardfin`;
-	if (shell === "fish") return `# hardfin completion for fish
-complete -c hardfin -f -a "(hardfin __complete -- (commandline -opc)[2..-1] 2>/dev/null)"`;
-	return `# hardfin completion for PowerShell
+
+compdef _hardfin_complete hardfin`,
+	fish: `# hardfin completion for fish
+function __hardfin_complete
+    # Older fish lacks -x, which replaced -o, so it falls back to the older option.
+    set -l words (commandline -xpc 2>/dev/null; or commandline -opc)
+    set -l current (commandline -ct)
+    hardfin __complete -- $words[2..-1] "$current" 2>/dev/null
+end
+
+complete -c hardfin -f -a "(__hardfin_complete)"`,
+	powershell: `# hardfin completion for PowerShell
 Register-ArgumentCompleter -Native -CommandName hardfin -ScriptBlock {
   param($wordToComplete, $commandAst, $cursorPosition)
-  $words = $commandAst.CommandElements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() }
+
+  # Only the words before the cursor decide what is offered, and PowerShell leaves out the
+  # empty word after a trailing space, so it is added back.
+  $words = @($commandAst.CommandElements | Select-Object -Skip 1 | Where-Object { $_.Extent.StartOffset -lt $cursorPosition } | ForEach-Object { $_.Extent.Text })
+
+  if ($wordToComplete -eq '') {
+    # Before 7.3, and in Legacy mode, an empty argument never reaches the program unless
+    # it is written as a pair of quotes.
+    $isLegacy = $PSVersionTable.PSVersion -lt [version]'7.3' -or $PSNativeCommandArgumentPassing -eq 'Legacy'
+    $words += if ($isLegacy) { '""' } else { '' }
+  }
+
   hardfin __complete -- @words 2>$null | ForEach-Object {
-    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    $text = $_
+
+    if ($text -match '[\\s#@$;,''{}()"\`|<>&]') {
+      $text = "'" + ($text -replace "'", "''") + "'"
+    }
+
+    [System.Management.Automation.CompletionResult]::new($text, $_, 'ParameterValue', $_)
   }
-}`;
-}
+}`
+};
 //#endregion
 //#region src/command/config.ts
 const configCommand = defineCommand({
@@ -1505,7 +1637,7 @@ async function toSignedIn(input, metadata, tokens) {
 		writeFailure("the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
 		return ExitCode.ERROR;
 	}
-	const backend = await withLock(() => keep(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt));
+	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt));
 	if (input.isJSON) {
 		writeData({
 			signedIn: true,
@@ -1609,6 +1741,17 @@ const TOOL = {
 		required: ["args"]
 	}
 };
+/** ProtocolFailure is a line this server answers with a JSON-RPC error rather than a result. */
+var ProtocolFailure = class extends Error {
+	code;
+	id;
+	constructor(code, message, id) {
+		super(message);
+		this.name = "ProtocolFailure";
+		this.code = code;
+		this.id = id;
+	}
+};
 /** toResponse answers one request, and answers nothing to a notification. */
 async function toResponse(request, commands, run) {
 	const answer = (result) => ({
@@ -1640,7 +1783,19 @@ async function toResponse(request, commands, run) {
 			description: "The command tree as JSON",
 			mimeType: "application/json"
 		}] });
-		case "resources/read": return answer(toResource(toText(request.params?.["uri"] ?? ""), commands));
+		case "resources/read": {
+			const uri = toText(request.params?.["uri"] ?? "");
+			const resource = toResource(uri, commands);
+			if (!resource) return {
+				jsonrpc: "2.0",
+				id: request.id ?? null,
+				error: {
+					code: -32002,
+					message: `${uri} is not a resource this server offers`
+				}
+			};
+			return answer(resource);
+		}
 		case "tools/call": return answer(await toToolResult(request.params, run));
 		case "ping": return answer({});
 		default:
@@ -1655,9 +1810,16 @@ async function toResponse(request, commands, run) {
 			};
 	}
 }
+/** The revisions this server speaks, newest first, which is what it may answer with. */
+const PROTOCOL_VERSIONS = [
+	PROTOCOL_VERSION,
+	"2025-03-26",
+	"2024-11-05"
+];
+/** toProtocolVersion answers a version this server implements, never one it was told. */
 function toProtocolVersion(params) {
 	const asked = params?.["protocolVersion"];
-	return typeof asked === "string" ? asked : PROTOCOL_VERSION;
+	return typeof asked === "string" && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSION;
 }
 function toResource(uri, commands) {
 	if (uri === GUIDE_URI) return { contents: [{
@@ -1670,10 +1832,6 @@ function toResource(uri, commands) {
 		mimeType: "application/json",
 		text: JSON.stringify(toTree(commands), null, 2)
 	}] };
-	return {
-		contents: [],
-		isError: true
-	};
 }
 /** toTree names every command and what it takes, without the schemas a tool list would carry. */
 function toTree(commands) {
@@ -1691,12 +1849,32 @@ const REFUSED_COMMANDS = /* @__PURE__ */ new Set([
 	"logout",
 	"mcp"
 ]);
+/** The global options, which sit before a command and take a value of their own. */
+const GLOBAL_OPTIONS_WITH_VALUES = /* @__PURE__ */ new Set(["--api-url", "--issuer-url"]);
+/**
+* toCommandName reads which command a call names. A global option sits before it, so
+* reading the first argument alone would let --issuer-url x logout through.
+*/
+function toCommandName(args) {
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index] ?? "";
+		if (GLOBAL_OPTIONS_WITH_VALUES.has(argument)) {
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith("-")) continue;
+		return argument;
+	}
+}
+/** toIsAskingForHelp reports whether a call only wants to read about a command. */
+function toIsAskingForHelp(args) {
+	return args.includes("--help") || args.includes("-h") || args[0] === "help";
+}
 async function toToolResult(params, run) {
-	const name = params?.["name"];
-	if (name !== void 0 && name !== TOOL.name) return {
+	if (params?.["name"] !== TOOL.name) return {
 		content: [{
 			type: "text",
-			text: `this server offers one tool, ${TOOL.name}`
+			text: `a call names its tool, and this server offers one, ${TOOL.name}`
 		}],
 		isError: true
 	};
@@ -1708,11 +1886,20 @@ async function toToolResult(params, run) {
 		}],
 		isError: true
 	};
+	const refused = toRefusedArgument(args);
+	if (refused) return {
+		content: [{
+			type: "text",
+			text: refused
+		}],
+		isError: true
+	};
 	const asked = args;
-	if (REFUSED_COMMANDS.has(asked[0] ?? "")) return {
+	const command = toCommandName(asked) ?? "";
+	if (REFUSED_COMMANDS.has(command) && !toIsAskingForHelp(asked)) 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`
+			text: `${command} is run by a person at a terminal, not through this server. Run hardfin ${command} yourself, then call this tool again`
 		}],
 		isError: true
 	};
@@ -1725,13 +1912,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;
-	}
+/** The most a command line can carry, below what the operating system refuses outright. */
+const ARGUMENT_LIMIT = 1e5;
+/** 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}`;
 }
 /** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
 function toCliRunner() {
@@ -1760,24 +1948,65 @@ function toCliRunner() {
 /** serve answers requests on stdin until the client closes it. */
 async function serve(commands, run = toCliRunner()) {
 	const lines = createInterface({ input: process.stdin });
+	const answering = /* @__PURE__ */ new Set();
 	for await (const line of lines) {
 		if (line.trim() === "") continue;
-		let response;
-		try {
-			response = await toResponse(JSON.parse(line), commands, run);
-		} catch (error) {
-			response = {
-				jsonrpc: "2.0",
-				id: toRequestId(line),
-				error: {
-					code: -32603,
-					message: error instanceof Error ? error.message : String(error)
-				}
-			};
+		const answered = toAnswer(line, commands, run).finally(() => answering.delete(answered));
+		answering.add(answered);
+	}
+	await Promise.all(answering);
+}
+/** toAnswer replies to one line, and never rejects, because a rejection ends the server. */
+async function toAnswer(line, commands, run) {
+	let response;
+	try {
+		response = await toResponse(toRequest(line), commands, run);
+	} catch (error) {
+		response = error instanceof ProtocolFailure ? toErrorResponse(error.id, error.code, error.message) : toErrorResponse(toRequestId(line), -32603, error instanceof Error ? error.message : String(error));
+	}
+	if (response) write(`${JSON.stringify(response)}\n`);
+}
+/** toRequest reads one line, refusing what the protocol does not allow to be a request. */
+function toRequest(line) {
+	let parsed;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		throw new ProtocolFailure(-32700, "this line is not JSON", null);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new ProtocolFailure(-32600, "a request is a JSON object, and this server takes one per line", null);
+	const request = parsed;
+	if (typeof request.method !== "string") throw new ProtocolFailure(-32600, "a request names a method", toAllowedId(request.id));
+	if (request.id !== void 0 && request.id !== null && typeof request.id !== "string" && typeof request.id !== "number") throw new ProtocolFailure(-32600, "an id is a string, a number, or null", null);
+	return request;
+}
+function toAllowedId(id) {
+	return typeof id === "string" || typeof id === "number" ? id : null;
+}
+function toErrorResponse(id, code, message) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message
 		}
-		if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+	};
+}
+/** toRequestId reads the id of a line that could not be answered, so a client is not left waiting. */
+function toRequestId(line) {
+	try {
+		return toAllowedId(JSON.parse(line).id);
+	} catch {
+		return null;
 	}
 }
+/** write puts a reply on stdout, and stops quietly when the client has gone. */
+function write(text) {
+	try {
+		process.stdout.write(text);
+	} catch {}
+}
 //#endregion
 //#region src/command/mcp.ts
 const mcpCommand = defineCommand({
@@ -1879,6 +2108,10 @@ async function runOperation(operation, input) {
 		writeFailure(body.message, input.isJSON);
 		return ExitCode.USAGE;
 	}
+	if (operation.bodyFlags.length > 0 && body === void 0) {
+		writeFailure(`this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, input.isJSON);
+		return ExitCode.USAGE;
+	}
 	let form;
 	if (operation.upload) {
 		const built = await toForm(operation.upload, input.flags);
@@ -1908,7 +2141,7 @@ async function runOperation(operation, input) {
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
@@ -2021,10 +2254,11 @@ function toElements(flag, values) {
 		const element = {};
 		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]}=value`);
-			const key = pair.slice(0, split);
+			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();
 			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
-			element[key] = pair.slice(split + 1);
+			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
+			element[key] = pair.slice(split + 1).trim();
 		}
 		elements.push(element);
 	}
@@ -2114,9 +2348,9 @@ const surfaceCommands = [
 						name: "for-asset-id",
 						queryName: "forAssetId",
 						description: "The IDs of the assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "for-asset-key",
@@ -2130,33 +2364,33 @@ const surfaceCommands = [
 						name: "for-customer",
 						queryName: "forCustomer",
 						description: "The IDs of the customers whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "for-item",
 						queryName: "forItem",
 						description: "The IDs of the items whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "at-site",
 						queryName: "atSite",
 						description: "The IDs of the locations whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "at-customer-sites",
 						queryName: "atCustomerSites",
 						description: "The IDs of the customers whose sites to list assets at",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "with-functional-statuses",
@@ -2220,9 +2454,9 @@ const surfaceCommands = [
 						name: "for-project",
 						queryName: "forProject",
 						description: "The IDs of the projects whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "scrapped",
@@ -2241,7 +2475,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "create",
 				summary: "Create asset",
-				example: "hardfin asset create --item-id <value> --serial <value>",
+				example: "hardfin asset create --item-id <uuid> --serial <value>",
 				method: "POST",
 				path: "/asset",
 				pathParameters: [],
@@ -2355,16 +2589,16 @@ const surfaceCommands = [
 						name: "item-id",
 						jsonPath: ["itemId"],
 						description: "The ID of the catalog item the asset is a unit of",
-						valueName: "value",
+						valueName: "uuid",
 						required: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "location-id",
 						jsonPath: ["locationId"],
 						description: "The ID of the location the asset enters inventory at",
-						valueName: "value",
-						schema: z.string()
+						valueName: "uuid",
+						schema: z.uuid()
 					},
 					{
 						name: "salvage-value",
@@ -2431,7 +2665,7 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Execute asset move",
-						example: "hardfin asset move execute create",
+						example: "hardfin asset move execute create --move assetId=<value>,deliverAt=<value>,deliverAtTimezone=<value>,destinationId=<value>,originId=<value>,shipAt=<value>,shipAtTimezone=<value>",
 						method: "POST",
 						path: "/asset/move/execute",
 						pathParameters: [],
@@ -2440,7 +2674,7 @@ const surfaceCommands = [
 							name: "move",
 							jsonPath: ["moves"],
 							description: "The moves to carry out",
-							valueName: "assetId=,deliverAt=",
+							valueName: "assetId=,deliverAt=,deliverAtTimezone=,destinationId=,originId=,shipAt=,shipAtTimezone=",
 							repeatable: true,
 							element: [
 								"assetId",
@@ -2463,7 +2697,7 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Plan asset move",
-						example: "hardfin asset move plan create",
+						example: "hardfin asset move plan create --move assetId=<value>,deliverAt=<value>,id=<value>,shipAt=<value>",
 						method: "POST",
 						path: "/asset/move/plan",
 						pathParameters: [],
@@ -2472,7 +2706,7 @@ const surfaceCommands = [
 							name: "move",
 							jsonPath: ["moves"],
 							description: "The moves to plan",
-							valueName: "assetId=,deliverAt=",
+							valueName: "assetId=,deliverAt=,id=,shipAt=",
 							repeatable: true,
 							element: [
 								"assetId",
@@ -2502,7 +2736,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "update",
 				summary: "Patch asset",
-				example: "hardfin asset update ast_4f9xk2mq7plr8stz",
+				example: "hardfin asset update ast_4f9xk2mq7plr8stz --metadata fieldId=<value>,value=<value>",
 				method: "PATCH",
 				path: "/asset/{assetKey}",
 				pathParameters: [{
@@ -2545,9 +2779,9 @@ const surfaceCommands = [
 						name: "initial-location-id",
 						jsonPath: ["initialLocationId"],
 						description: "The ID of the location the asset entered inventory at",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "metadata",
@@ -2967,7 +3201,7 @@ const surfaceCommands = [
 					defineOperation({
 						name: "create",
 						summary: "Create asset ownership",
-						example: "hardfin asset ownership create ast_4f9xk2mq7plr8stz --customer-id <value> --date <value>",
+						example: "hardfin asset ownership create ast_4f9xk2mq7plr8stz --customer-id <uuid> --date <value>",
 						method: "POST",
 						path: "/asset/{assetKey}/ownership",
 						pathParameters: [{
@@ -2981,9 +3215,9 @@ const surfaceCommands = [
 								name: "customer-id",
 								jsonPath: ["customerId"],
 								description: "The ID of the customer that takes ownership of the asset",
-								valueName: "value",
+								valueName: "uuid",
 								required: true,
-								schema: z.string()
+								schema: z.uuid()
 							},
 							{
 								name: "date",
@@ -3063,9 +3297,9 @@ const surfaceCommands = [
 								name: "customer-id",
 								jsonPath: ["customerId"],
 								description: "The ID of the customer that owned the asset during the segment",
-								valueName: "value",
+								valueName: "uuid",
 								nullable: true,
-								schema: z.string()
+								schema: z.uuid()
 							},
 							{
 								name: "date",
@@ -3585,7 +3819,7 @@ const surfaceCommands = [
 		subcommands: [defineOperation({
 			name: "create",
 			summary: "Upload file",
-			example: "hardfin file create --file-type <value> --for-entity <value> --file photo.jpg",
+			example: "hardfin file create --file-type <value> --for-entity <uuid> --file photo.jpg",
 			method: "POST",
 			path: "/file",
 			pathParameters: [],
@@ -3606,9 +3840,9 @@ const surfaceCommands = [
 						name: "for-entity",
 						jsonPath: ["forEntity"],
 						description: "The ID of the asset the file is attached to",
-						valueName: "value",
+						valueName: "uuid",
 						required: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "is-public",
@@ -3862,7 +4096,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "update",
 				summary: "Update item",
-				example: "hardfin item update item_7Hq2Lm9XcR4tWz8K",
+				example: "hardfin item update item_7Hq2Lm9XcR4tWz8K --field fieldId=<value>,order=<value>,section=<value>",
 				method: "PATCH",
 				path: "/item/{itemKey}",
 				pathParameters: [{
@@ -3892,7 +4126,7 @@ const surfaceCommands = [
 						name: "field",
 						jsonPath: ["fields"],
 						description: "New positions for a DEVICE item's fields",
-						valueName: "fieldId=,order=",
+						valueName: "fieldId=,order=,section=",
 						repeatable: true,
 						element: [
 							"fieldId",
@@ -4351,17 +4585,17 @@ const surfaceCommands = [
 						name: "consignee",
 						jsonPath: ["consignee"],
 						description: "The ID of the customer a zone is designated for, such as for reservations, provisioning or a 3PL",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "customer-id",
 						jsonPath: ["customerId"],
 						description: "The ID of the customer to assign a site to, or null for your organization's own site",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "description",
@@ -4403,9 +4637,9 @@ const surfaceCommands = [
 						name: "parent-location-id",
 						jsonPath: ["parentLocationId"],
 						description: "The ID of the site a zone belongs to, required for a zone and refused for a site",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "type",
@@ -4507,17 +4741,17 @@ const surfaceCommands = [
 						name: "consignee",
 						jsonPath: ["consignee"],
 						description: "The ID of the customer a zone is designated for, such as for reservations, provisioning or a 3PL",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "customer-id",
 						jsonPath: ["customerId"],
 						description: "The ID of the customer to assign a site to, or null for your organization's own site",
-						valueName: "value",
+						valueName: "uuid",
 						nullable: true,
-						schema: z.string()
+						schema: z.uuid()
 					},
 					{
 						name: "description",
@@ -5030,6 +5264,10 @@ function collect(value, previous) {
 }
 //#endregion
 //#region src/cli.ts
+process.stdout.on("error", (error) => {
+	if (error.code === "EPIPE") process.exit(0);
+	throw error;
+});
 await toCli().parseAsync(process.argv);
 //#endregion
 export {};

package/package.json

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