@hardfin/cli 0.0.1 → 0.0.2-dev.11

package/README.md

@@ -7,7 +7,8 @@ It is built for people at a terminal and for agents that call Hardfin on their b
 
 ## Status
 
-This package is a placeholder that reserves the name. No commands work 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
 
@@ -15,6 +16,367 @@ This package is a placeholder that reserves the name. No commands work yet.
 npm install -g @hardfin/cli
 ```
 
+Previews of unreleased work are published from the `dev` branch.
+
+```sh
+npm install -g @hardfin/cli@dev
+```
+
+## The command surface
+
+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 |
+
+### 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>` |
+| `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.
+
+### Overrides
+
+Two endpoints sometimes want one name. `DELETE /asset/{assetKey}/ownership` and
+`DELETE /asset/{assetKey}/ownership/{segmentKey}` both generate `asset ownership delete`, so
+the generator stops and names the pair.
+
+Settle it in `surface-overrides.json`, keyed by `operationId`:
+
+```json
+{
+    "assetClearAssetActiveOwnership": {
+        "command": ["asset", "ownership", "clear"],
+        "summary": "Clear the ownership an asset holds today"
+    }
+}
+```
+
+An override for an `operationId` the document no longer publishes fails the generator. That
+is deliberate, because a silently dropped override renames a command nobody meant to rename.
+
+### The vendored document
+
+`spec/core.openapi.yaml` is the API document this repository carries, and the generator
+reads it. Nothing fetches a document during a build, a release, or CI.
+
+Refresh it with the script, which then rewrites the generated commands:
+
+```sh
+scripts/update-spec.sh              # reads hardfinhq/api-spec over your own git access
+scripts/update-spec.sh ../hardfin   # bundles the fragmented source in a monorepo checkout
+```
+
+The monorepo form runs the same bundler at the same version CI uses, so the result matches
+what the api-spec bridge publishes. Commit the document and the generated commands together.
+
+Two checks keep the pair honest.
+
+| 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 |
+
+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 |
+
+## 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 an estimate. Hardfin expires an unused refresh token after 90 days,
+but the token endpoint reports no expiry, so the CLI applies that rule to the date it last
+renewed. The flag `refreshExpiryIsEstimated` says so in the output.
+
+## 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 |
+
+An exported variable beats `.env` because Node leaves a variable that is already set alone.
+
+### What a local build writes
+
+```json
+{
+    "apiUrl": "http://localhost:8080/v2",
+    "clientId": "https://hardfin.com/cli/client.json"
+}
+```
+
+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.
+
+`config.local.json` and `.env` are both gitignored.
+
+### Seeing what won
+
+```sh
+hardfin config
+```
+
+It prints each setting, its value, and the layer that supplied it. The API key is reported
+as set or not set, never printed.
+
+### Both files are read from the working directory
+
+The CLI reads whatever `config.local.json` and `.env` sit in the directory you run it from.
+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.
+
+## Releasing
+
+This section is for anyone who merges a pull request in this repository. It tells you where
+your branch goes and what reaches npm when it lands.
+
+Nobody publishes from a laptop. Every version on npm is published by
+`.github/workflows/release.yaml`, which npm trusts through OIDC. No npm token exists.
+
+A published version carries no provenance attestation, because npm only builds one for a
+package published from a public repository, and this repository is private.
+
+### Where a branch goes
+
+- `dev` is the integration branch, and every pull request targets it
+- `main` holds what is released, and the only pull requests it takes are promotions and
+  hotfixes
+- A promotion is a pull request from `dev` to `main`, and merging it is how a release is cut
+- A hotfix is a pull request straight to `main`, for a fix that cannot wait for the next
+  promotion
+
+### 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` |
+
+A preview never moves `latest`, so `npm install @hardfin/cli` keeps returning the released
+version.
+
+The workflow picks the preview version itself. It reads `version` from `package.json`, and
+if that version is already on npm it increments the patch, so a preview always sorts after
+the last release.
+
+### Cut a release
+
+1. Open a pull request against `dev` that sets `version` in `package.json` to the version
+   you are releasing. Change nothing else in it
+2. Merge it, which publishes one more preview
+3. Open a promotion pull request from `dev` to `main`
+4. Merge it. The workflow publishes to npm under `latest` and opens a GitHub release tagged
+   `v<version>`
+
+### Ship a hotfix
+
+1. Branch from `main`
+2. Commit the fix, and in the same pull request raise the patch version in `package.json`
+3. Target `main`, and merge. The workflow publishes it
+4. Open a pull request merging `main` back into `dev` the same day
+
+Step 4 is what keeps the fix from being reverted by the next promotion. A hotfix lives only
+on `main` until someone brings it back.
+
+### What CI refuses
+
+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 |
+
+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
+when it builds a preview.
+
+### Rules
+
+- Never run `npm publish` by hand. The package requires two-factor authentication and
+  disallows tokens, and a hand publish skips the version check that guards the branch
+- Never reuse a version. npm refuses to serve a version's contents twice, even after an
+  unpublish, so a bad release is fixed by publishing the next patch
+- Never rename `release.yaml`. npm's trusted publisher names this file, and a rename stops
+  every publish until someone updates the package settings on npm
+- A merge into `main` that does not raise the version publishes nothing. The workflow finds
+  the version already on npm and stops
+
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE)