@hardfin/cli 0.0.2-dev.5 → 0.0.2-dev.7

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. `hardfin api` and the generated commands work against an API key, and
+`hardfin login` is not built yet.
 
 ## Install
 
@@ -21,6 +22,117 @@ Previews of unreleased work are published from the `dev` branch.
 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 |
+| `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.
+
+### Regenerating
+
+The Surface workflow runs each weekday, reads `reference/core.openapi.yaml` from the
+`hardfinhq/api-spec` repository through a read-only deploy key, and opens a pull request when
+the generated file changes. It needs the `API_SPEC_READ_DEPLOY_KEY` secret.
+
+Run it by hand against a local document:
+
+```sh
+npm run generate-surface -- ../api-spec/reference/core.openapi.yaml
+```
+
+The document is bundled, meaning its external files are inlined, but `$ref` pointers within
+it remain. The generator follows those pointers itself.
+
+## 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",
+    "auth": { "tokenUrl": "http://localhost:9000/oauth/token" }
+}
+```
+
+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`.
+
+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