@hardfin/cli 0.0.2-dev.14 → 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

@@ -4,10 +4,10 @@ import { Command, Option } from "commander";
 import { z } from "zod";
 import { chmodSync, closeSync, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
-import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
@@ -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") {
@@ -252,6 +262,32 @@ function toSummary(command) {
 	};
 }
 //#endregion
+//#region src/auth/jwt.ts
+/**
+* toClaims reads an access token's payload for display. Nothing here verifies the
+* signature, because the API is what decides whether a token is good.
+*/
+function toClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return {
+			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
+			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
+			scopes: toScopes(decoded),
+			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
+function toScopes(decoded) {
+	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
+	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({
@@ -346,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 {
@@ -388,30 +424,44 @@ function keep(issuer, refreshToken, expiresAt) {
 	const keyring = toKeyring(issuer);
 	if (keyring) try {
 		keyring.setPassword(JSON.stringify(record));
+		forgetFile(issuer);
 		return "keyring";
 	} catch {}
 	writeFile({
 		...readFile(),
 		[issuer]: record
 	});
+	forgetKeyring(issuer);
 	return "file";
 }
-/** toCredential reads what is held for an issuer, and where it was held. */
+/**
+* toCredential reads what is held for an issuer, and where it was held. Both backends are
+* read, because a host that lost its keyring for a while wrote to the file instead, and the
+* newer of the two is the one the server has not spent.
+*/
 function toCredential(issuer) {
-	const keyring = toKeyring(issuer);
-	if (keyring) try {
-		const held = keyring.getPassword();
-		if (held) return {
-			...toRecord(held),
-			backend: "keyring"
-		};
-	} catch {}
+	const fromKeyring = toKeyringCredential(issuer);
 	const held = readFile()[issuer];
-	return held === void 0 ? void 0 : {
+	const fromFile = held === void 0 ? void 0 : {
 		...held,
 		backend: "file",
 		path: toCredentialPath()
 	};
+	if (!fromKeyring || !fromFile) return fromKeyring ?? fromFile;
+	return (fromFile.renewedAt ?? "") > (fromKeyring.renewedAt ?? "") ? fromFile : fromKeyring;
+}
+function toKeyringCredential(issuer) {
+	const keyring = toKeyring(issuer);
+	if (!keyring) return;
+	try {
+		const held = keyring.getPassword();
+		return held ? {
+			...toRecord(held),
+			backend: "keyring"
+		} : void 0;
+	} catch {
+		return;
+	}
 }
 /** toRecord reads a stored entry, which older versions wrote as the bare token. */
 function toRecord(held) {
@@ -424,18 +474,25 @@ function toRecord(held) {
 }
 /** forget removes whatever is held for an issuer, in both places. */
 function forget(issuer) {
+	forgetKeyring(issuer);
+	forgetFile(issuer);
+}
+function forgetKeyring(issuer) {
 	const keyring = toKeyring(issuer);
-	if (keyring) try {
+	if (!keyring) return;
+	try {
 		keyring.deletePassword();
 	} catch {}
+}
+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) {
@@ -474,6 +531,8 @@ const STALE_MS = 3e4;
 const WAIT_MS$1 = 1e4;
 const RETRY_MS = 25;
 const DIRECTORY_MODE = 448;
+/** What this process wrote into the lock, which is how it knows the lock is still its own. */
+let heldBy;
 /** toLockPath names the lock every process coordinates credential writes through. */
 function toLockPath() {
 	return join(dirname(toCredentialPath()), "credentials.lock");
@@ -485,17 +544,23 @@ function tryAcquire() {
 		recursive: true,
 		mode: DIRECTORY_MODE
 	});
+	const mark = `${process.pid}:${randomUUID()}`;
 	try {
 		const handle = openSync(path, "wx");
-		writeSync(handle, String(process.pid));
+		writeSync(handle, mark);
 		closeSync(handle);
+		heldBy = mark;
 		return true;
 	} catch {
-		return isStale(path) ? steal(path) : false;
+		return isStale(path) ? steal(path, mark) : false;
 	}
 }
-/** release lets the next process in. */
+/** release lets the next process in, and only ever removes this process's own lock. */
 function release$1() {
+	const mark = heldBy;
+	if (mark === void 0) return;
+	heldBy = void 0;
+	if (toMark(toLockPath()) !== mark) return;
 	rmSync(toLockPath(), { force: true });
 }
 /**
@@ -522,9 +587,29 @@ function isStale(path) {
 		return true;
 	}
 }
-function steal(path) {
+/**
+* steal takes over a lock whose holder is gone. Two processes can reach this at once, so
+* the winner is whichever mark survives in the file, not whichever removed it.
+*/
+function steal(path, mark) {
 	rmSync(path, { force: true });
-	return tryAcquire();
+	try {
+		const handle = openSync(path, "wx");
+		writeSync(handle, mark);
+		closeSync(handle);
+	} catch {
+		return false;
+	}
+	if (toMark(path) !== mark) return false;
+	heldBy = mark;
+	return true;
+}
+function toMark(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
 }
 //#endregion
 //#region src/auth/session.ts
@@ -567,9 +652,9 @@ async function toAccessToken(settings, refreshToken) {
 	return await withLock(async () => {
 		const latest = toCredential(settings.issuerUrl)?.refreshToken ?? refreshToken;
 		try {
-			const tokens = await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest);
+			const tokens = toDated(await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest));
 			held.set(settings.issuerUrl, tokens);
-			if (tokens.refreshToken && tokens.refreshToken !== latest) keep(settings.issuerUrl, tokens.refreshToken, tokens.refreshExpiresAt);
+			store(settings.issuerUrl, tokens, latest);
 			return tokens;
 		} catch (error) {
 			if (error instanceof GrantFailure && isDead(error.code)) {
@@ -580,14 +665,37 @@ async function toAccessToken(settings, refreshToken) {
 		}
 	});
 }
-/** Codes the authorization server uses when a refresh token can never work again. */
-const DEAD_GRANT_CODES = /* @__PURE__ */ new Set([
-	"invalid_grant",
-	"invalid_client",
-	"unauthorized_client"
-]);
+/**
+* invalid_grant is the only refusal that says anything about the refresh token itself.
+* invalid_client and unauthorized_client describe the client registration, which is server
+* configuration and a setting a person can mistype, so a good credential survives them.
+*/
 function isDead(code) {
-	return DEAD_GRANT_CODES.has(code);
+	return code === "invalid_grant";
+}
+/**
+* toDated fills in when an access token expires. A token endpoint that states no expires_in
+* would otherwise have this process refresh on every command, and every refresh spends a
+* generation of the token family.
+*/
+function toDated(tokens) {
+	if (tokens.expiresAt !== void 0) return tokens;
+	return {
+		...tokens,
+		expiresAt: toClaims(tokens.accessToken).expiresAt
+	};
+}
+/**
+* store writes what a rotation issued. The old token is spent either way, so failing to
+* write the new one is worth saying out loud rather than failing a command that succeeded.
+*/
+function store(issuer, tokens, previous) {
+	if (!tokens.refreshToken || tokens.refreshToken === previous) return;
+	try {
+		keep(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`);
+	}
 }
 /** forgetHeldTokens drops the access tokens this process is holding. */
 function forgetHeldTokens() {
@@ -736,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
@@ -864,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;
@@ -1018,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 {
@@ -1094,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) {
@@ -1197,6 +1309,7 @@ function toPrompt(url) {
 		fail = reject;
 	});
 	const input = process.stdin;
+	pasted.catch(() => {});
 	if (!input.isTTY) return {
 		pasted,
 		close: () => {}
@@ -1296,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();
@@ -1312,9 +1425,13 @@ async function runLogin(input) {
 		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: ");
-		const callback = await Promise.race([listener.callback, prompt.pasted]);
-		listener.close();
-		prompt.close();
+		let callback;
+		try {
+			callback = await Promise.race([listener.callback, prompt.pasted]);
+		} finally {
+			listener.close();
+			prompt.close();
+		}
 		process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
 		if (callback.error) {
 			writeFailure(`sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
@@ -1360,7 +1477,15 @@ async function runDeviceLogin(input, metadata, scope) {
 		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
 	].join("\n"));
 	const prompt = toPrompt(url);
-	return await toSignedIn(input, metadata, await toTokensFromDevice(metadata.token_endpoint, settings.clientId, device).finally(() => prompt.close()));
+	try {
+		return await toSignedIn(input, metadata, await Promise.race([toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted.then(toCancelled)]));
+	} finally {
+		prompt.close();
+	}
+}
+/** toCancelled ends a device sign in that the keyboard interrupted. */
+function toCancelled() {
+	throw new Error("sign in was cancelled");
 }
 /** toSignedIn stores what a sign in issued, whichever flow issued it. */
 async function toSignedIn(input, metadata, tokens) {
@@ -1440,7 +1565,9 @@ async function runLogout(input) {
 	} catch {
 		revoked = false;
 	}
-	await withLock(() => forget(settings.issuerUrl));
+	await withLock(() => {
+		forget(settings.issuerUrl);
+	});
 	forgetHeldTokens();
 	writeData({
 		signedOut: true,
@@ -1502,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:
@@ -1580,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. */
@@ -1635,6 +1764,13 @@ async function runMcp(input) {
 }
 //#endregion
 //#region src/command/operation.ts
+/**
+* toEnum takes a value in any case, as the API does, and answers the spelling the document
+* lists, which is what a response always uses.
+*/
+function toEnum(values) {
+	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+}
 const UNSET_FLAG = {
 	name: "unset",
 	description: "A field to clear, named as its flag is, repeatable",
@@ -1741,7 +1877,9 @@ function toQuery(operation, flags) {
 	for (const flag of operation.queryFlags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
-		for (const entry of Array.isArray(value) ? value : [value]) query.append(flag.queryName, String(entry));
+		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, toText(entry));
 	}
 	return query;
 }
@@ -1761,7 +1899,10 @@ async function toForm(upload, flags) {
 	}
 	for (const field of upload.fields) {
 		const value = flags[toOptionKey(field.name)];
-		if (value !== void 0) form.append(field.jsonPath[0] ?? field.name, String(value));
+		if (value !== void 0) {
+			const parsed = field.schema.safeParse(value);
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
+		}
 	}
 	return form;
 }
@@ -1773,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;
@@ -1790,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}`);
@@ -1847,21 +1988,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"serial",
 							"project",
 							"item",
@@ -1875,14 +2016,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -1949,7 +2090,7 @@ const surfaceCommands = [
 						description: "The functional statuses to list, where SCRAPPED lists scrapped assets",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -1962,7 +2103,7 @@ const surfaceCommands = [
 						description: "The transit statuses to list",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"IN_TRANSIT",
 							"IN_TRANSIT_TO_FIELD",
 							"IN_TRANSIT_TO_INVENTORY",
@@ -2014,7 +2155,7 @@ const surfaceCommands = [
 						queryName: "scrapped",
 						description: "Whether to list unscrapped assets, scrapped assets, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2053,7 +2194,7 @@ const surfaceCommands = [
 						jsonPath: ["depreciationModel"],
 						description: "The method one unit is depreciated by, or null to clear it",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"DOUBLE_DECLINING",
 							"STRAIGHT_LINE",
 							"SUM_YEAR",
@@ -2098,7 +2239,7 @@ const surfaceCommands = [
 						description: "The asset's starting functional status, FUNCTIONAL when absent, which cannot be SCRAPPED",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -2197,7 +2338,7 @@ const surfaceCommands = [
 						description: "The number of months one unit is depreciated over, or null to clear it",
 						valueName: "number",
 						nullable: true,
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					}
 				]
 			}),
@@ -2311,7 +2452,7 @@ const surfaceCommands = [
 						description: "The asset's new functional status, which cannot be SCRAPPED because scrapping has its own endpoint",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -2393,7 +2534,7 @@ const surfaceCommands = [
 							jsonPath: ["depreciationModel"],
 							description: "The method one unit is depreciated by, or null to clear it",
 							valueName: "value",
-							schema: z.enum([
+							schema: toEnum([
 								"DOUBLE_DECLINING",
 								"STRAIGHT_LINE",
 								"SUM_YEAR",
@@ -2493,7 +2634,7 @@ const surfaceCommands = [
 							description: "The number of months one unit is depreciated over, or null to clear it",
 							valueName: "number",
 							nullable: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				}), {
@@ -2549,7 +2690,7 @@ const surfaceCommands = [
 							description: "Whether the adjustment adds to the asset's cost basis or writes it down",
 							valueName: "value",
 							required: true,
-							schema: z.enum(["CAPITALIZATION", "IMPAIRMENT"])
+							schema: toEnum(["CAPITALIZATION", "IMPAIRMENT"])
 						},
 						{
 							name: "amount",
@@ -2581,7 +2722,7 @@ const surfaceCommands = [
 							description: "Why the adjustment was made, which must be one its adjustment type allows",
 							valueName: "value",
 							required: true,
-							schema: z.enum([
+							schema: toEnum([
 								"ADDITION",
 								"BETTERMENT",
 								"DAMAGE",
@@ -3044,7 +3185,7 @@ const surfaceCommands = [
 							description: "Why the useful life was revised",
 							valueName: "value",
 							required: true,
-							schema: z.enum([
+							schema: toEnum([
 								"CHANGE_IN_USE",
 								"DAMAGE",
 								"OBSOLESCENCE",
@@ -3060,7 +3201,7 @@ const surfaceCommands = [
 							description: "The asset's revised useful life in months",
 							valueName: "number",
 							required: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				})]
@@ -3087,14 +3228,14 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
@@ -3108,14 +3249,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -3392,8 +3533,7 @@ const surfaceCommands = [
 						name: "is-public",
 						jsonPath: ["isPublic"],
 						description: "Whether any organization's API key may download the file, which is false unless sent as true",
-						valueName: "value",
-						schema: z.string()
+						schema: z.boolean()
 					}
 				]
 			}
@@ -3437,7 +3577,7 @@ const surfaceCommands = [
 						queryName: "type",
 						description: "The item type to list, SERVICE, DEVICE, or BULK, or absent for every type",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3455,21 +3595,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"sku",
 							"type",
@@ -3481,14 +3621,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -3549,7 +3689,7 @@ const surfaceCommands = [
 						description: "SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity",
 						valueName: "value",
 						required: true,
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3560,7 +3700,7 @@ const surfaceCommands = [
 						jsonPath: ["unitOfMeasure"],
 						description: "The unit a BULK item's quantities are counted in, which SERVICE and DEVICE items ignore",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"BG",
 							"BO",
 							"BX",
@@ -3706,7 +3846,7 @@ const surfaceCommands = [
 						description: "The type to convert the item to, when the item's assets and inventory history allow the conversion",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3754,7 +3894,7 @@ const surfaceCommands = [
 							jsonPath: ["depreciationModel"],
 							description: "The method one unit is depreciated by, or null to clear it",
 							valueName: "value",
-							schema: z.enum([
+							schema: toEnum([
 								"DOUBLE_DECLINING",
 								"STRAIGHT_LINE",
 								"SUM_YEAR",
@@ -3839,7 +3979,7 @@ const surfaceCommands = [
 							description: "The number of months one unit is depreciated over, or null to clear it",
 							valueName: "number",
 							nullable: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				})]
@@ -3870,7 +4010,7 @@ const surfaceCommands = [
 								description: "The kind of value the field holds",
 								valueName: "value",
 								required: true,
-								schema: z.enum([
+								schema: toEnum([
 									"BOOLEAN",
 									"DATE",
 									"DATE_TIME",
@@ -3896,7 +4036,7 @@ const surfaceCommands = [
 								valueName: "number",
 								required: true,
 								nullable: true,
-								schema: z.coerce.number()
+								schema: z.coerce.number().int()
 							},
 							{
 								name: "section",
@@ -3905,7 +4045,7 @@ const surfaceCommands = [
 								valueName: "number",
 								required: true,
 								nullable: true,
-								schema: z.coerce.number()
+								schema: z.coerce.number().int()
 							}
 						]
 					}),
@@ -3976,21 +4116,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"company",
 							"assetCount"
@@ -4001,14 +4141,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4019,7 +4159,7 @@ const surfaceCommands = [
 						queryName: "isTransient",
 						description: "Whether to return permanent locations (false), transient locations (true), or both (all)",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4184,7 +4324,7 @@ const surfaceCommands = [
 						jsonPath: ["type"],
 						description: "SITE for a site, or ZONE for a zone within a site",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"SITE",
 							"UNKNOWN",
 							"ZONE"
@@ -4340,7 +4480,7 @@ const surfaceCommands = [
 						jsonPath: ["type"],
 						description: "SITE for a site, or ZONE for a zone within a site",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"SITE",
 							"UNKNOWN",
 							"ZONE"
@@ -4370,7 +4510,7 @@ const surfaceCommands = [
 						queryName: "archived",
 						description: "Whether to return unarchived zones, archived zones, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4465,32 +4605,6 @@ const surfaceCommands = [
 	}
 ];
 //#endregion
-//#region src/auth/jwt.ts
-/**
-* toClaims reads an access token's payload for display. Nothing here verifies the
-* signature, because the API is what decides whether a token is good.
-*/
-function toClaims(token) {
-	const payload = token.split(".")[1];
-	if (!payload) return {};
-	try {
-		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		return {
-			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
-			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
-			scopes: toScopes(decoded),
-			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
-		};
-	} catch {
-		return {};
-	}
-}
-/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
-function toScopes(decoded) {
-	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
-	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
-}
-//#endregion
 //#region src/system/host.ts
 const BYTES_PER_GB = 1024 ** 3;
 /** toDistribution reads the name a Linux distribution gives itself. */
@@ -4598,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 {
@@ -4714,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) {
@@ -4817,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.14",
+    "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,9 +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"