@hardfin/cli 0.0.2-dev.8 → 0.1.0-dev.19

package/README.md

@@ -7,8 +7,8 @@ It is built for people at a terminal and for agents that call Hardfin on their b
 
 ## Status
 
-The CLI is early. `hardfin api` and the generated commands work against an API key, and
-`hardfin login` is not built yet.
+The CLI is early. Signing in works against a Hardfin that publishes an authorization
+server, and every command also accepts an API key.
 
 ## Install
 
@@ -26,30 +26,67 @@ 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>` |
 
-A path parameter becomes a positional argument. A query parameter becomes a flag, named in
-kebab case, and an array parameter becomes a flag you repeat. An enum parameter carries its
-values, so a wrong value fails locally with exit code 2 rather than at the API.
+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                                     |
+
+```sh
+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
+```
+
+A value is sent as the type the document names. `--useful-life 36` sends the number 36. A
+decimal such as `--salvage-value 1500.00` stays a string, which is how the API takes money
+without losing precision.
+
+A download is written where you name it, and a terminal is never filled with a file's bytes.
+
+```sh
+hardfin file get file_7hq2mx9pkr4stz8w --output photo.jpg
+hardfin file get file_7hq2mx9pkr4stz8w --output - | wc -c
+```
+
+Clear a field with `--unset`, naming the flag:
+
+```sh
+hardfin asset accounting update ast_4f9xk2mq7plr8stz --unset useful-life
+```
+
+Three things fail locally with exit code 2, before any request is made: a value outside an
+enum, a required field that is missing, and `--unset` on a field the API will not take null
+for.
 
 ### Overrides
 
@@ -88,27 +125,189 @@ 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
 current commands with an earlier API's.
 
+## Signing in
+
+```sh
+hardfin login            # approve this CLI in a browser
+hardfin login --device   # approve on another machine, by typing a code
+hardfin status           # what the CLI is configured with and signed in as
+hardfin logout           # forget this machine, and ask Hardfin to revoke it
+```
+
+An API key is still the way to run unattended. `HARDFIN_API_KEY` wins over a stored sign in,
+so CI and an agent sandbox need no browser.
+
+### What login does
+
+1. Reads `/.well-known/oauth-authorization-server` at the API's host, which names every
+   endpoint, including the authorize endpoint on the app host
+2. Opens a loopback listener on `127.0.0.1`, over IPv4, on whatever port the machine hands out
+3. Opens the browser to approve this CLI, with a PKCE challenge and a state value
+4. Prints the URL, and waits at the keyboard as well as on the listener
+5. Checks the state and the `iss` it came back with, then trades the code for tokens
+6. Keeps the refresh token, and nothing else
+
+While it waits, the terminal takes two things.
+
+| 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,
+`code#state`, or the code alone. A browser on another machine never reaches this listener,
+and the redirect it failed to follow is still in the address bar.
+
+On WSL the browser is opened through Windows, by `wslview`, then PowerShell, then
+`explorer.exe`, because `xdg-open` reaches nothing outside the distribution.
+
+The port changes every time, so Hardfin matches a loopback redirect by everything except its
+port, which is what RFC 8252 asks of an authorization server.
+
+### Signing in from a machine with no browser
+
+`hardfin login --device` prints a short code and a page to enter it on, and waits. Approve
+on your phone or any other machine, and the terminal finishes on its own.
+
+```
+  Code  WDJB-MJHT
+  At    https://app.hardfin.com/device
+```
+
+The CLI refuses `--device` when the authorization server does not offer that grant, rather
+than waiting for an endpoint that is not there.
+
+### When a sign in stops working
+
+A refresh token can die: someone signed out on another machine, the token was presented
+twice, or it aged out. The server answers `invalid_grant`, and the CLI removes the dead
+credential and tells you to run `hardfin login` again.
+
+A server that merely cannot be reached does not count, because a failed connection says
+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                                        |
+| 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
+headless host wants. `HARDFIN_CREDENTIAL_STORE=file` forces the file. `hardfin status` reports which one holds
+the credential, and where.
+
+Access tokens are never written anywhere. One is fetched when a command needs it and lives
+in that process only, so what sits at rest is revocable with `hardfin logout`.
+
+A credential is filed under the authorization server it came from, so a local build and
+production never share a sign in.
+
+### What it needs configured
+
+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           |
+
+## Completing commands in your shell
+
+```sh
+source <(hardfin completion zsh)     # this shell, now
+hardfin completion zsh >> ~/.zshrc   # every shell after this one
+```
+
+`bash`, `zsh`, `fish` and `powershell` each get a script. The script asks the CLI what may
+follow what you have typed, so completions never fall behind the commands, including the ones
+generated from the API document.
+
+## Serving an agent
+
+```sh
+hardfin mcp
+```
+
+It speaks the Model Context Protocol on standard input and output, so Claude, Codex or any
+other client can run Hardfin commands.
+
+```sh
+claude mcp add hardfin -- hardfin mcp
+```
+
+### One tool, and resources for the rest
+
+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      |
+
+Fifty tools would describe the same surface and crowd out the work. An agent that needs the
+list reads a resource, or runs `["--help"]`.
+
+A tool call runs the CLI itself, so an agent and a person get identical parsing, output and
+exit codes.
+
+### What it signs in as
+
+The server uses whatever credential this machine holds, so an agent acts as the person who
+ran `hardfin login`. Give an agent an API key through `HARDFIN_API_KEY` when it should act
+as an integration instead.
+
+## Diagnosing a problem
+
+`hardfin status` prints everything a support request needs, and is the first thing to send.
+
+```sh
+hardfin status               # for you
+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                                 |
+
+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
+it.
+
+`refreshExpiresAt` is what the server said when it issued the token. A sign in stored before
+the server reported one falls back to Hardfin's 90-day rule, and `refreshExpiryIsEstimated`
+says which of the two you are looking at.
+
 ## Local configuration
 
 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.
 
@@ -117,13 +316,12 @@ An exported variable beats `.env` because Node leaves a variable that is already
 ```json
 {
     "apiUrl": "http://localhost:8080/v2",
-    "auth": { "tokenUrl": "http://localhost:9000/oauth/token" }
+    "clientId": "https://hardfin.com/cli/client.json"
 }
 ```
 
-The authentication endpoints follow `apiUrl`, so pointing at a local server moves the whole
-flow. Name one under `auth` to move only that one. The keys are `apiUrl`, `apiKey`,
-`clientId`, and `auth` holding `authorizeUrl`, `tokenUrl`, `deviceUrl`, and `revokeUrl`.
+The authorization server sits at the API's host, so pointing at a local server moves signing
+in with it. The keys are `apiUrl`, `apiKey`, `clientId`, and `issuerUrl`.
 
 A key the file does not define fails the command with exit code 2. A typo that was silently
 ignored would look like a setting that never applied.
@@ -145,6 +343,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
@@ -167,11 +383,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.
@@ -204,13 +420,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