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

package/README.md

@@ -26,37 +26,37 @@ npm install -g @hardfin/cli@dev
 
 Most commands are generated from the published API document rather than written by hand.
 
-| Piece | Holds |
-| --- | --- |
-| `hardfin api` | A call to any endpoint, written by hand, and the escape hatch when no generated command fits |
-| `src/command/surface.generated.ts` | Every endpoint as a command, rewritten by the generator |
-| `surface-overrides.json` | The operations whose generated name is wrong |
-| `spec/core.openapi.yaml` | The API document the generator reads, vendored here |
-| `scripts/generate-surface.mjs` | The generator |
+| Piece                              | Holds                                                                                        |
+| ---------------------------------- | -------------------------------------------------------------------------------------------- |
+| `hardfin api`                      | A call to any endpoint, written by hand, and the escape hatch when no generated command fits |
+| `src/command/surface.generated.ts` | Every endpoint as a command, rewritten by the generator                                      |
+| `surface-overrides.json`           | The operations whose generated name is wrong                                                 |
+| `spec/core.openapi.yaml`           | The API document the generator reads, vendored here                                          |
+| `scripts/generate-surface.mjs`     | The generator                                                                                |
 
 ### How an endpoint becomes a command
 
 The first path segment is the noun. Every later literal segment nests under it. The method
 and the shape of the last segment decide the verb.
 
-| Endpoint | Command |
-| --- | --- |
-| `GET /asset` | `hardfin asset list` |
-| `POST /asset` | `hardfin asset create` |
-| `GET /asset/{assetKey}` | `hardfin asset get <assetKey>` |
-| `PATCH /asset/{assetKey}` | `hardfin asset update <assetKey>` |
+| Endpoint                             | Command                                      |
+| ------------------------------------ | -------------------------------------------- |
+| `GET /asset`                         | `hardfin asset list`                         |
+| `POST /asset`                        | `hardfin asset create`                       |
+| `GET /asset/{assetKey}`              | `hardfin asset get <assetKey>`               |
+| `PATCH /asset/{assetKey}`            | `hardfin asset update <assetKey>`            |
 | `PATCH /asset/{assetKey}/accounting` | `hardfin asset accounting update <assetKey>` |
 
 Everything an endpoint takes becomes a flag or an argument. No command asks for JSON.
 
-| The document says | You type |
-| --- | --- |
-| A path parameter | a positional argument |
-| A query or body field | `--field-name`, in kebab case |
-| A field inside a nested object | `--address-city`, the path joined |
-| An array of values | the flag, repeated |
-| An array of objects | the flag, repeated, each carrying that element's fields as `key=value` |
-| A file upload | `--file <path>`, sent as multipart |
+| The document says              | You type                                                               |
+| ------------------------------ | ---------------------------------------------------------------------- |
+| A path parameter               | a positional argument                                                  |
+| A query or body field          | `--field-name`, in kebab case                                          |
+| A field inside a nested object | `--address-city`, the path joined                                      |
+| An array of values             | the flag, repeated                                                     |
+| An array of objects            | the flag, repeated, each carrying that element's fields as `key=value` |
+| A file upload                  | `--file <path>`, sent as multipart                                     |
 
 ```sh
 hardfin asset ownership create ast_4f9xk2mq7plr8stz \
@@ -118,10 +118,10 @@ what the api-spec bridge publishes. Commit the document and the generated comman
 
 Two checks keep the pair honest.
 
-| Check | Refuses |
-| --- | --- |
+| Check         | Refuses                                                                       |
+| ------------- | ----------------------------------------------------------------------------- |
 | The generator | a document whose `info.version` is not a date, which means an earlier release |
-| CI | a vendored document that was updated without regenerating the commands |
+| CI            | a vendored document that was updated without regenerating the commands        |
 
 The first one matters because `hardfinhq/api-spec` can sit a release behind the monorepo
 while its bridge pull request is open. Generating from that document would replace the
@@ -151,9 +151,9 @@ so CI and an agent sandbox need no browser.
 
 While it waits, the terminal takes two things.
 
-| Key | Does |
-| --- | --- |
-| `c` | Copies the URL to the clipboard |
+| Key                        | Does                                      |
+| -------------------------- | ----------------------------------------- |
+| `c`                        | Copies the URL to the clipboard           |
 | A pasted value, then enter | Finishes the sign in without the listener |
 
 Paste whichever of these you have: the whole redirect URL from the browser's address bar,
@@ -190,9 +190,9 @@ nothing about whether the credential is good.
 
 ### Where the refresh token is kept
 
-| Host | Kept in |
-| --- | --- |
-| macOS, Windows, and Linux with a secret service | the OS keyring |
+| Host                                                            | Kept in                                               |
+| --------------------------------------------------------------- | ----------------------------------------------------- |
+| macOS, Windows, and Linux with a secret service                 | the OS keyring                                        |
 | Everything else, including WSL, containers, and agent sandboxes | `$XDG_STATE_HOME/hardfin/credentials.json`, mode 0600 |
 
 `HARDFIN_NO_BROWSER=1` keeps `hardfin login` from opening a tab, which is what a script or a
@@ -210,10 +210,10 @@ production never share a sign in.
 Nothing. Hardfin registers this CLI as a first-party client, and its key is the same in every
 environment, so `hardfin login` works out of the box.
 
-| Setting | Holds | Default |
-| --- | --- | --- |
-| `clientId`, or `HARDFIN_CLIENT_ID` | the client this CLI names itself as | the seeded Hardfin CLI client |
-| `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server | the API's host root |
+| Setting                              | Holds                               | Default                       |
+| ------------------------------------ | ----------------------------------- | ----------------------------- |
+| `clientId`, or `HARDFIN_CLIENT_ID`   | the client this CLI names itself as | the seeded Hardfin CLI client |
+| `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server            | the API's host root           |
 
 ## Completing commands in your shell
 
@@ -244,11 +244,11 @@ claude mcp add hardfin -- hardfin mcp
 Every tool a server lists sits in the agent's context for the entire session, so this server
 offers one.
 
-| Offered as | Holds | Costs context |
-| --- | --- | --- |
-| The `hardfin` tool | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
-| `hardfin://guide` | Every command, its flags, and the exit codes | Only when the agent reads it |
-| `hardfin://commands` | The command tree as JSON | Only when the agent reads it |
+| Offered as           | Holds                                                            | Costs context                     |
+| -------------------- | ---------------------------------------------------------------- | --------------------------------- |
+| The `hardfin` tool   | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
+| `hardfin://guide`    | Every command, its flags, and the exit codes                     | Only when the agent reads it      |
+| `hardfin://commands` | The command tree as JSON                                         | Only when the agent reads it      |
 
 Fifty tools would describe the same surface and crowd out the work. An agent that needs the
 list reads a resource, or runs `["--help"]`.
@@ -272,14 +272,14 @@ hardfin status --json        # for a support request
 hardfin status --offline     # no network calls at all
 ```
 
-| Section | Holds |
-| --- | --- |
-| `cli` | The version, the API version it speaks, Node, and whether a terminal is attached |
-| `host` | The operating system, kernel, build, processor, memory, timezone, shell, and the distribution and WSL details on Linux |
-| `configuration` | Every setting, its value, and the layer it came from |
-| `credential` | Whether you are signed in, where the refresh token is kept, and when it was issued and last renewed |
-| `authorizationServer` | Whether discovery worked, and every endpoint it named |
-| `api` | Whether the API accepted the credential, when the access token expires, and its scopes |
+| Section               | Holds                                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `cli`                 | The version, the API version it speaks, Node, and whether a terminal is attached                                       |
+| `host`                | The operating system, kernel, build, processor, memory, timezone, shell, and the distribution and WSL details on Linux |
+| `configuration`       | Every setting, its value, and the layer it came from                                                                   |
+| `credential`          | Whether you are signed in, where the refresh token is kept, and when it was issued and last renewed                    |
+| `authorizationServer` | Whether discovery worked, and every endpoint it named                                                                  |
+| `api`                 | Whether the API accepted the credential, when the access token expires, and its scopes                                 |
 
 Nothing secret is printed. An API key and a refresh token are each reported as a
 `sha256:` fingerprint, which identifies a credential across two machines without disclosing
@@ -294,13 +294,13 @@ says which of the two you are looking at.
 A local build reaches a local server without editing code. Four layers supply the same
 settings, and the one nearest the top wins.
 
-| Layer | Where | Beats |
-| --- | --- | --- |
-| Flag | `--api-url` | everything below |
-| Environment | an exported `HARDFIN_*` variable | the files below |
-| Env file | `.env` in the working directory, or the file `HARDFIN_ENV_FILE` names | the config file |
-| Config file | `config.local.json` in the working directory | the defaults |
-| Default | the published API | nothing |
+| Layer       | Where                                                                 | Beats            |
+| ----------- | --------------------------------------------------------------------- | ---------------- |
+| Flag        | `--api-url`                                                           | everything below |
+| Environment | an exported `HARDFIN_*` variable                                      | the files below  |
+| Env file    | `.env` in the working directory, or the file `HARDFIN_ENV_FILE` names | the config file  |
+| Config file | `config.local.json` in the working directory                          | the defaults     |
+| Default     | the published API                                                     | nothing          |
 
 An exported variable beats `.env` because Node leaves a variable that is already set alone.
 
@@ -336,6 +336,24 @@ 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.
 
+## Working on the CLI
+
+```sh
+npm run check-types      # tsc
+npm run lint             # eslint, with type-aware rules
+npm run prettier:write   # formatting
+npm test                 # vitest
+npm run build            # tsdown, into dist/cli.js
+```
+
+CI runs all five on every pull request, plus a check that the generated commands still match
+the vendored API document. A pull request that fails any of them cannot merge.
+
+Two lint rules exist because of defects that reached the repository. `no-floating-promises`
+covers a promise nobody waits for, which once killed the process when a sign in was
+cancelled. `no-base-to-string` covers a value stringified as `[object Object]`, which a
+request would have carried to the API.
+
 ## Releasing
 
 This section is for anyone who merges a pull request in this repository. It tells you where
@@ -358,11 +376,11 @@ package published from a public repository, and this repository is private.
 
 ### What each merge publishes
 
-| Merge | Publishes | Version | Dist-tag |
-| --- | --- | --- | --- |
-| Pull request into `dev` | always | the next version, suffixed `-dev.<run number>` | `dev` |
-| Promotion into `main` | when `package.json` names a version that is not yet on npm | that version | `latest` |
-| Hotfix into `main` | same rule as a promotion | that version | `latest` |
+| Merge                   | Publishes                                                  | Version                                        | Dist-tag |
+| ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- | -------- |
+| Pull request into `dev` | always                                                     | the next version, suffixed `-dev.<run number>` | `dev`    |
+| Promotion into `main`   | when `package.json` names a version that is not yet on npm | that version                                   | `latest` |
+| Hotfix into `main`      | same rule as a promotion                                   | that version                                   | `latest` |
 
 A preview never moves `latest`, so `npm install @hardfin/cli` keeps returning the released
 version.
@@ -395,13 +413,13 @@ on `main` until someone brings it back.
 A required check reads `version` from `package.json` on every pull request and judges it
 against the branch the pull request targets.
 
-| Version | Into `dev` | Into `main` |
-| --- | --- | --- |
-| Plain, above what `main` holds | passes | passes |
-| Plain, equal to what `main` holds | passes | refused, because npm already serves it |
-| Plain, below what `main` holds | refused | refused |
-| Carrying a `-dev` or any other prerelease suffix | refused | refused |
-| Not a semver version | refused | refused |
+| Version                                          | Into `dev` | Into `main`                            |
+| ------------------------------------------------ | ---------- | -------------------------------------- |
+| Plain, above what `main` holds                   | passes     | passes                                 |
+| Plain, equal to what `main` holds                | passes     | refused, because npm already serves it |
+| Plain, below what `main` holds                   | refused    | refused                                |
+| Carrying a `-dev` or any other prerelease suffix | refused    | refused                                |
+| Not a semver version                             | refused    | refused                                |
 
 A prerelease suffix is refused everywhere because the release workflow appends it at publish
 time. A version equal to `main`'s is fine on `dev`, since the workflow increments the patch

package/dist/cli.js

@@ -120,6 +120,16 @@ function toOrigin(apiUrl) {
 }
 //#endregion
 //#region src/output/writer.ts
+/**
+* toText reads a value a caller supplied, which arrives typed as unknown. An object would
+* otherwise reach a request as the text "[object Object]".
+*/
+function toText(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (value === void 0 || value === null) return "";
+	return JSON.stringify(value);
+}
 /** writeData prints a command's result on stdout. */
 function writeData(value) {
 	if (typeof value === "string") {
@@ -372,7 +382,7 @@ async function toTokens(url, form) {
 		body: new URLSearchParams(form)
 	});
 	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	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 {
@@ -477,12 +487,12 @@ function forgetKeyring(issuer) {
 function forgetFile(issuer) {
 	const held = readFile();
 	if (held[issuer] === void 0) return;
-	delete held[issuer];
-	if (Object.keys(held).length === 0) {
+	const remaining = Object.fromEntries(Object.entries(held).filter(([name]) => name !== issuer));
+	if (Object.keys(remaining).length === 0) {
 		rmSync(toCredentialPath(), { force: true });
 		return;
 	}
-	writeFile(held);
+	writeFile(remaining);
 }
 /** toKeyring opens the OS keyring, or answers undefined where the platform has none. */
 function toKeyring(issuer) {
@@ -834,7 +844,7 @@ async function runApi(input) {
 		writeData((await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
-			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
 			query,
 			body
@@ -962,7 +972,7 @@ function toFlagNames(command) {
 	return [...(command?.flags ?? []).map((flag) => `--${flag.name}`), "--help"];
 }
 async function runCompletion(input) {
-	const shell = String(input.args[0] ?? "");
+	const shell = input.args[0] ?? "";
 	if (!SHELLS.includes(shell)) {
 		writeFailure(`${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
@@ -1116,7 +1126,7 @@ async function toDeviceAuthorization(endpoint, clientId, scope) {
 		})
 	});
 	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	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 = DeviceResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the device endpoint did not answer with a code");
 	return {
@@ -1192,8 +1202,12 @@ async function toListener(timeoutMs) {
 	}, timeoutMs);
 	return {
 		redirectUri: `http://${HOST}:${server.address().port}${CALLBACK_PATH}`,
-		callback: callback.finally(() => close(server, timer)),
-		close: () => close(server, timer)
+		callback: callback.finally(() => {
+			close(server, timer);
+		}),
+		close: () => {
+			close(server, timer);
+		}
 	};
 }
 function toCallback(request) {
@@ -1395,7 +1409,7 @@ async function runLogin(input) {
 	try {
 		const clientId = settings.clientId;
 		const metadata = await toMetadata(settings.issuerUrl);
-		const scope = String(input.flags["scope"] ?? DEFAULT_SCOPES);
+		const scope = toText(input.flags["scope"] ?? DEFAULT_SCOPES);
 		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
 		const listener = await toListener(WAIT_MS);
 		const pkce = toPkce();
@@ -1551,7 +1565,9 @@ async function runLogout(input) {
 	} catch {
 		revoked = false;
 	}
-	await withLock(() => forget(settings.issuerUrl));
+	await withLock(() => {
+		forget(settings.issuerUrl);
+	});
 	forgetHeldTokens();
 	writeData({
 		signedOut: true,
@@ -1613,7 +1629,7 @@ async function toResponse(request, commands, run) {
 			description: "The command tree as JSON",
 			mimeType: "application/json"
 		}] });
-		case "resources/read": return answer(toResource(String(request.params?.["uri"] ?? ""), commands));
+		case "resources/read": return answer(toResource(toText(request.params?.["uri"] ?? ""), commands));
 		case "tools/call": return answer(await toToolResult(request.params, run));
 		case "ping": return answer({});
 		default:
@@ -1691,11 +1707,13 @@ function toCliRunner() {
 		child.stderr.on("data", (chunk) => {
 			stderr += chunk.toString();
 		});
-		child.on("close", (code) => resolve({
-			stdout,
-			stderr,
-			code: code ?? 1
-		}));
+		child.on("close", (code) => {
+			resolve({
+				stdout,
+				stderr,
+				code: code ?? 1
+			});
+		});
 	});
 }
 /** serve answers requests on stdin until the client closes it. */
@@ -1861,7 +1879,7 @@ function toQuery(operation, flags) {
 		if (value === void 0) continue;
 		const parsed = flag.schema.safeParse(value);
 		const carried = parsed.success ? parsed.data : value;
-		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, String(entry));
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
 	}
 	return query;
 }
@@ -1883,7 +1901,7 @@ async function toForm(upload, flags) {
 		const value = flags[toOptionKey(field.name)];
 		if (value !== void 0) {
 			const parsed = field.schema.safeParse(value);
-			form.append(field.jsonPath[0] ?? field.name, String(parsed.success ? parsed.data : value));
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
 		}
 	}
 	return form;
@@ -1896,7 +1914,7 @@ function toBody(operation, flags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
 		if (flag.element) {
-			const elements = toElements(flag, Array.isArray(value) ? value.map(String) : [String(value)]);
+			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
 			if (elements instanceof Error) return elements;
 			set(body, flag.jsonPath, elements);
 			hasField = true;
@@ -1913,7 +1931,7 @@ function toBody(operation, flags) {
 /** toCleared sends null for each field named by --unset, which is how a field is cleared. */
 function toCleared(operation, flags, body) {
 	const named = flags["unset"];
-	const names = Array.isArray(named) ? named.map(String) : named === void 0 ? [] : [String(named)];
+	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
 	for (const name of names) {
 		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
 		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
@@ -4694,27 +4712,24 @@ function toEnvironmentReport() {
 		apiVersion: API_VERSION,
 		node: process.version,
 		platform: process.platform,
-		interactive: Boolean(process.stdin.isTTY)
+		interactive: process.stdin.isTTY
 	};
 }
 /** toConfigurationReport names every setting, its source, and never a secret's value. */
 function toConfigurationReport(resolved) {
-	const entries = Object.entries(resolved.settings).map(([key, value]) => {
+	const report = { configFile: CONFIG_FILE };
+	for (const [key, value] of Object.entries(resolved.settings)) {
 		const from = resolved.sources[key];
-		if (key === "apiKey") return [key, {
+		report[key] = key === "apiKey" ? {
 			set: value !== void 0,
 			fingerprint: toFingerprint(value),
 			from
-		}];
-		return [key, {
+		} : {
 			value: value ?? null,
 			from
-		}];
-	});
-	return {
-		...Object.fromEntries(entries),
-		configFile: CONFIG_FILE
-	};
+		};
+	}
+	return report;
 }
 function toCredentialReport(apiKey, stored) {
 	if (apiKey) return {
@@ -4810,8 +4825,7 @@ function toFlattened(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
 	const holder = value;
 	if (holder.from === void 0) return;
-	const shown = holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set");
-	return `${String(shown)}  (${holder.from})`;
+	return `${toText(holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set"))}  (${holder.from})`;
 }
 /** toLines lays the report out for a person, one indented line per value. */
 function toLines(report, depth = 0) {
@@ -4913,7 +4927,7 @@ async function toExitCode(command, args, flags) {
 }
 function toArgumentList(value) {
 	if (Array.isArray(value)) return value.map(String);
-	return value === void 0 ? [] : [String(value)];
+	return value === void 0 ? [] : [toText(value)];
 }
 function collect(value, previous) {
 	return [...previous ?? [], value];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.15",
+    "version": "0.0.2-dev.16",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -37,7 +37,12 @@
         "check-types": "tsc --noEmit",
         "test": "vitest run",
         "test:watch": "vitest",
-        "prepublishOnly": "npm run build"
+        "prepublishOnly": "npm run build",
+        "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+        "lint:fix": "eslint . --fix",
+        "prettier:check": "prettier --check .",
+        "prettier:write": "prettier --write .",
+        "test:coverage": "vitest run --coverage"
     },
     "dependencies": {
         "@napi-rs/keyring": "^2.1.0",
@@ -45,10 +50,16 @@
         "zod": "^4.6.5"
     },
     "devDependencies": {
+        "@eslint/js": "^10.0.1",
         "@types/node": "^22.15.0",
         "@vitest/coverage-v8": "^5.0.1",
+        "eslint": "^10.11.0",
+        "eslint-plugin-unused-imports": "^4.4.1",
+        "globals": "^17.12.0",
+        "prettier": "^3.9.9",
         "tsdown": "^0.23.0",
         "typescript": "^5.9.0",
+        "typescript-eslint": "^8.70.1",
         "unrun": "^0.3.1",
         "vitest": "^5.0.1",
         "yaml": "^2.9.1"