@farthershore/cli 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog — @farthershore/cli
+
+All notable changes to the `farthershore` CLI and its MCP server
+(`farthershore-mcp`) are documented here. The CLI versions independently from
+the SDKs. Pre-1.0: minor versions may include breaking changes. Releases
+before 0.35.0 are recorded only in the git history.
+
+## [0.35.0] - 2026-10-12
+
+### Added
+
+- `farthershore api <endpoint>`: an authenticated request to any platform API
+  path, like `gh api`. `-X` sets the method; `-f` / `-F` add string or typed
+  fields (query parameters for GET, a JSON body otherwise); `--input` sends a
+  JSON file; `-H` adds headers (the auth, surface and organization headers are
+  refused); `--paginate` / `--max-pages` follow offset or cursor pages; `-i`
+  prints the status and headers; `--dry-run` appends `dry_run=true`. The
+  `{business}`, `{org}` / `{organization}` and `{env}` placeholders are filled
+  from the current context. Absolute URLs and other hosts are refused.
+- `farthershore code search|describe|types|run`: code mode over the typed
+  operation surface.
+  - `code search` and `code describe` find operations and print their
+    metadata; `code types` prints `.d.ts` declarations for `fs` or one
+    namespace.
+  - `code run` runs a JavaScript/TypeScript script (a file, `-` for stdin, or
+    `-e`) with `fs`, `args`, `paginate` and `FartherShoreError` in scope. The
+    script runs in a worker with no credential and an empty environment, and
+    every call is checked by the CLI process.
+  - Read-only by default. `--allow-writes` permits non-destructive writes;
+    destructive and one-time-secret operations also need `--yes`.
+    `{ dryRun: true }` on a preview-capable write runs as a read.
+    Contract-class (managed-by-code) writes are always refused.
+  - Budgets: `--max-calls` (200), `--max-writes` (20), `--timeout` (60s), and
+    at most 4 calls in flight. A breach stops the script
+    (`CODE_MODE_BUDGET_EXCEEDED`), terminates the worker and cancels in-flight
+    requests.
+  - One-time secrets come back as `{ redacted: true, last4 }` unless
+    `--reveal-secrets` is passed; every result also goes through the secret
+    redaction backstop.
+
+### Changed
+
+- The CLI and the MCP server now run on `@farthershore/client`: the shared
+  transport, credential sources, typed errors and namespaced operation
+  surface. `--yes`, `--dry-run` and the MCP `destructiveHint` are derived from
+  each operation's spec. Requests carry
+  `x-fs-client: @farthershore/client/<version> farthershore-cli/<version>`.
+  Errors carry `param` when the server names a field.
+
+### Breaking
+
+- These commands now require `--yes`: `business rollback`,
+  `frontend rollback`, `backend tokens rotate`, `webhook rotate`,
+  `token rotate` (maker token), `persona rotate`, `persona delete`,
+  `business rbac disable`, `consumer migrate-latest`, `consumer rbac disable`
+  and `consumer rbac roles delete`. A `--dry-run` of a preview-capable
+  operation never needs `--yes`. Their MCP tools now set
+  `destructiveHint: true`.
+- Consumer RBAC writes have one operation key per verb instead of sharing
+  `consumer.roles.assign`: `consumer.roles.assign`, `consumer.rbac.enable`,
+  `consumer.rbac.disable`, `consumer.role.create`, `consumer.role.update` and
+  `consumer.role.delete`. Only `consumer.rbac.disable` and
+  `consumer.role.delete` are destructive, so `consumer rbac assign`,
+  `enable`, `roles create` and `roles update` run without `--yes`.
+  `consumer rbac roles create` is no longer retried automatically.
+- `promo-code archive` no longer requires `--yes`, and its MCP tool's
+  `destructiveHint` is now `false`.
+- `--dry-run` on an operation without a preview is refused locally with
+  `DRY_RUN_NOT_SUPPORTED`; nothing is sent.
+- The retired request-key vocabulary is gone. `operations list` no longer
+  reports an `intrinsic_replay` retry kind (`service-account approve` is a
+  `convergent_write`), and the retry contract no longer carries
+  `same_key_replay`, `keyRequired` or `liveWhenFieldPresent`. CLI and MCP
+  help describe the retry rule plainly: reads retry; writes retry only on a
+  429 or a server-marked `retryable` + `safe_to_repeat` answer; anything else
+  is `OUTCOME_UNKNOWN` (exit 5) and names the read to reconcile with.
+
+### Fixed
+
+- `workflow-control replay` and `rollback-to-config` call Core at
+  `/agent/v1/replay` and `/agent/v1/rollback-to-config`. They always returned
+  404 before.
+- A 401 on a cached exchanged token drops it, re-exchanges once and resends
+  once, so a long-lived MCP server recovers after a grant change or session
+  invalidation instead of failing for up to an hour. The refresh deadline
+  follows the token's lifetime rather than a possibly skewed local clock, and
+  concurrent first requests share one token exchange, which retries like a
+  read.
+- The MCP server uses the CLI's organization (`--organization`, the linked
+  directory, or `auth organization use`) and API URL, and sends
+  `x-fs-surface: mcp`. It could act in a different organization before.
+- POST endpoints that only read (analytics query, manifest compile, previews,
+  the builder bootstrap) and dry runs retry like reads instead of reporting
+  `OUTCOME_UNKNOWN`.
+- Transport failures have stable codes instead of `INTERNAL_ERROR`:
+  `NETWORK_ERROR` and `TIMEOUT` (retryable for reads, exit 5),
+  `REQUEST_ABORTED`, `OUTCOME_UNKNOWN` for a write with no response, and
+  `RESPONSE_UNREADABLE` for a 2xx whose body could not be read. The original
+  failure is kept as `cause`. The attempt timeout now also covers the body
+  read.
+- `farthershore api` never follows a redirect: a 3xx is reported as
+  `REDIRECT_NOT_FOLLOWED` with `details.location`, so headers never reach
+  another host.

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.34.0`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.35.0`.** Pre-1.0 — the command surface is stable but may still
 change between minor versions. Pin an exact version in CI.
 
 FartherShore lets you define a software business as code, then sells, meters,
@@ -21,19 +21,19 @@ the explicitly agent-operable subset of the CLI surface.
 ## Install
 
 ```bash
-npm install -g @farthershore/cli@0.34.0
+npm install -g @farthershore/cli@0.35.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.34.0 farthershore --help
+npx -p @farthershore/cli@0.35.0 farthershore --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-npx -p @farthershore/cli@0.34.0 farthershore-mcp
+npx -p @farthershore/cli@0.35.0 farthershore-mcp
 ```
 
 ## Authentication
@@ -274,7 +274,7 @@ farthershore business create weather-api \
   --format json
 
 farthershore business publish weather-api --format json
-farthershore business rollback weather-api wfe_previous --reason "bad release" --format json
+farthershore business rollback weather-api wfe_previous --reason "bad release" --yes --format json
 ```
 
 Deleting a business is **stage only** — the command is not registered in the
@@ -321,13 +321,13 @@ and requires the exact `business:rollback` permission.
 `rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
 `docsEnabled`, it is platform-owned and never repo-authored); once enabled,
 subscriber organizations manage roles in their portal. Both toggles are
-idempotent. Subscriber role and assignment state is kept server-side on
+safe to repeat. Subscriber role and assignment state is kept server-side on
 disable, so re-enabling is a pure flag flip.
 
 ```bash
 farthershore business rbac weather-api --format json
 farthershore business rbac enable weather-api --format json
-farthershore business rbac disable weather-api --format json
+farthershore business rbac disable weather-api --yes --format json
 ```
 
 `business rbac subjects list` lists the custom permission vocabulary: subjects
@@ -406,7 +406,7 @@ farthershore token approve <approvalId> --org \
 farthershore token deny <approvalId> --org --format json
 farthershore token update <tokenId> --org \
   --permissions '["business:read"]' --format json
-farthershore token rotate <tokenId> --org --format json
+farthershore token rotate <tokenId> --org --yes --format json
 farthershore token revoke <tokenId> --org --yes --format json
 ```
 
@@ -524,7 +524,7 @@ with placeholder data and auth bypassed.
 
 ```bash
 farthershore frontend status weather-api --format json
-farthershore frontend rollback weather-api --release-id <hash> --format json
+farthershore frontend rollback weather-api --release-id <hash> --yes --format json
 
 # Local preview (shells out to vite; needs a frontend/ project)
 farthershore frontend dev                            # hot-reloading dev server, mock mode by default
@@ -570,8 +570,8 @@ farthershore persona bootstrap weather-api --env preview --plan pro \
   --subscriber-id <subscriberId> --account-role member --role viewer \
   --format json
 
-farthershore persona rotate weather-api <personaId> --env preview --format json
-farthershore persona delete weather-api <personaId> --env preview --format json
+farthershore persona rotate weather-api <personaId> --env preview --yes --format json
+farthershore persona delete weather-api <personaId> --env preview --yes --format json
 ```
 
 Bootstrap and rotation return a key once. `login` sends the 60-second,
@@ -657,7 +657,7 @@ farthershore backend bind weather-api api \
   --origin-url https://api-pr-42.example.com \
   --format json
 farthershore backend tokens create weather-api --backend <backendId> --format json
-farthershore backend tokens rotate weather-api <tokenId> --format json
+farthershore backend tokens rotate weather-api <tokenId> --yes --format json
 farthershore backend tokens revoke weather-api <tokenId> --yes --format json
 ```
 
@@ -707,7 +707,7 @@ farthershore webhook update weather-api <webhookId> --disable --format json
 farthershore webhook test weather-api <webhookId> --format json
 farthershore webhook trigger weather-api <webhookId> --type payment.failed --format json
 farthershore webhook deliveries weather-api <webhookId> --limit 20 --format json
-farthershore webhook rotate weather-api <webhookId> --format json
+farthershore webhook rotate weather-api <webhookId> --yes --format json
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
 
@@ -763,18 +763,18 @@ Use `--all-plans` to clear plan scoping.
 Install or refresh the platform-verified skills bundle together. The platform
 pins this immutable release, and CI plus a daily repository check compare it to
 GitHub's latest stable release so the guidance cannot silently drift.
-This command requires `@farthershore/cli` 0.34.0 or newer.
+This command requires `@farthershore/cli` 0.35.0 or newer.
 
 ```bash
 set -euo pipefail
 CLI_VERSION=$(farthershore --version)
-printf '%s' "$CLI_VERSION" | node -e 'let v=""; process.stdin.on("data", c => v += c).on("end", () => { const m = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim()); if (!m || !(+m[1] > 0 || +m[2] > 34 || (+m[2] === 34 && +m[3] >= 0))) { console.error("Stop: CLI 0.34.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
+printf '%s' "$CLI_VERSION" | node -e 'let v=""; process.stdin.on("data", c => v += c).on("end", () => { const m = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim()); if (!m || !(+m[1] > 0 || +m[2] > 35 || (+m[2] === 35 && +m[3] >= 0))) { console.error("Stop: CLI 0.35.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
 farthershore skills install --help
 farthershore skills install
 ```
 
 If either prerequisite fails, stop and ask the human to run
-`npm install -g @farthershore/cli@0.34.0`, then repeat the checks.
+`npm install -g @farthershore/cli@0.35.0`, then repeat the checks.
 Do not install or upgrade global tooling autonomously.
 
 The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -789,6 +789,143 @@ Print the machine-readable action boundary: which operations are repo-authored
 farthershore operations list --format json
 ```
 
+### `farthershore api`
+
+Send a raw authenticated request to any platform API endpoint and print the
+response, like `gh api`. Use it for endpoints a typed command does not cover
+yet. Every endpoint is described in the platform's OpenAPI document
+(`farthershore api /openapi.json`).
+
+```bash
+farthershore api /businesses
+farthershore api 'businesses/{business}/environments' --paginate
+farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
+farthershore api 'management/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
+farthershore api -X POST 'businesses/{business}/promo-codes' --input promo.json
+farthershore api 'builder/organizations/{org}/members' --include
+farthershore api /businesses --format json | jq '.[].id'
+```
+
+- **Endpoint.** A path on the configured API (`--api-url` /
+  `FARTHERSHORE_API_URL`). Absolute URLs and other hosts are refused, so the
+  credential never leaves the platform, and redirects are never followed: a
+  3xx answer is an error (`REDIRECT_NOT_FOLLOWED`), so the credential and `-H`
+  headers never reach another location. Placeholders in the path and its
+  query are filled from the current context: `{business}` from
+  `--business`, `FARTHERSHORE_BUSINESS` or the linked directory; `{org}` /
+  `{organization}` from the selected organization; `{env}` from `--env`,
+  `FARTHERSHORE_ENV` or the linked environment.
+- **Method.** `-X, --method`; default `GET`, or `POST` when fields or `--input`
+  are given.
+- **Fields.** `-f key=value` sends a string; `-F key=value` converts `true`,
+  `false`, `null` and numbers, and reads `@file` (or `@-` for stdin). Nest with
+  `key[sub]=value`, append to an array with `key[]=value`. `GET` fields become
+  query parameters; otherwise they form the JSON body.
+- **`--input <file|->`** sends a JSON body as-is (not combinable with fields).
+- **`-H 'Name: value'`** adds a header. `Authorization`, `x-fs-surface`,
+  `x-fs-client` and the organization headers belong to the CLI and are refused.
+- **`--paginate`** follows offset (`pagination.hasMore`) and cursor
+  (`nextCursor`) pages and prints one object with the lists concatenated;
+  `--max-pages <n>` (default 100) bounds it.
+- **`-i, --include`** prints the HTTP status and response headers first.
+- **`--dry-run`** appends `dry_run=true`.
+
+The body is printed as-is (pretty in a terminal, compact with `--format json`),
+never wrapped in the CLI envelope; there is no `--jq`, so pipe to `jq`. Errors
+print the error envelope and use the exit codes below. Reads retry on transient
+failures; a write is never repeated: a 5xx or lost answer exits `5` and its
+error has `outcomeUnknown: true` (the `code` may be the server's own, e.g.
+`TEARDOWN_FAILED`; key on `outcomeUnknown`), so read current state before
+sending it again. `-i` also prints the status line and headers of a failed
+answer, before the error envelope.
+
+### `farthershore code` (code mode)
+
+Code mode lets you (or an agent) find platform operations and run a script
+against a typed `fs` client, instead of chaining one command per call. A
+script can loop, filter and join results, and only its return value comes
+back — the intermediate data never has to pass through a transcript.
+
+**Agent quickstart: search → describe → types → run.**
+
+```bash
+# 1. Find operations (ranked by name, path, summary and description).
+farthershore code search runtime token --format json
+
+# 2. Read one: description, TypeScript signature, safety flags, reconcile
+#    read, required permission and a runnable example.
+farthershore code describe runtimeTokens.revoke
+
+# 3. Load the types you need (or the whole API) before writing the script.
+farthershore code types runtimeTokens > fs.d.ts
+
+# 4. Run it. Reads only, unless you opt in.
+farthershore code run -e '
+  const businesses = await fs.businesses.list();
+  return businesses.filter((b) => b.status === args.status).map((b) => b.name);
+' --arg status=DRAFT
+```
+
+- **`code search <query...>`** — `--limit <n>` (default 20),
+  `--side-effect read|write`, `--namespace <ns>`. Each hit shows the path
+  (`fs.runtimeTokens.revoke`), a one-line summary and its flags (read/write,
+  destructive, one-time secret, preview, paginated).
+- **`code describe <path|opKey>`** — accepts `runtimeTokens.revoke`,
+  `fs.runtimeTokens.revoke` or the opKey `runtime_token.revoke`.
+- **`code types [namespace]`** — a self-contained `.d.ts` for `fs`, generated
+  from the same tables `code run` enforces, with JSDoc from the operation
+  specs.
+- **`code run [file|-]` / `-e '<code>'`** — the script is the body of an async
+  function: `await` freely and `return` the result (or `export default` a value
+  or an async function of `{ fs, args }`). `.ts` files (or `--ts`) have their
+  types stripped by Node; only erasable syntax is supported. `--arg key=value`
+  (repeatable) and `--args-json '{…}'` fill `args`. The return value is
+  printed as JSON on stdout; `console.*` goes to stderr, or into
+  `{ result, logs }` with `--format json`. `code run` needs Node.js 22.8 or
+  newer (`CODE_MODE_UNSUPPORTED_NODE` otherwise); TypeScript needs 22.13.
+
+In scope inside a script: `fs` (every method, plus `fs.call(opKey, input,
+options)`), `args`, `paginate(method, input)` / `collect(method, input)`,
+`refs.business(ref)` / `refs.environment(businessId, ref)`, `poll({ check,
+until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
+`FartherShoreError`. Nothing else: no `require`, `import()`, `process`,
+`fetch`, filesystem or network.
+
+**Policy** (checked in the CLI process for every call, not in the script):
+
+| Call                                                    | Needs                                                       |
+| ------------------------------------------------------- | ----------------------------------------------------------- |
+| read                                                    | nothing                                                     |
+| write                                                   | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`)       |
+| destructive or one-time-secret write                    | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
+| preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing                                |
+| managed-as-code (contract) write                        | always refused                                              |
+
+One-time secrets (minted or rotated credentials) come back to the script as
+`{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
+secret cannot be shown again, so rotate with `--reveal-secrets` when you need
+the value. Other results pass the same credential masking as the MCP server.
+
+**Budgets:** `--max-calls` (200), `--max-writes` (20), `--timeout` (60s; `60`,
+`60s`, `500ms`, `2m`) and at most 4 calls in flight. Exceeding one stops the
+script with `CODE_MODE_BUDGET_EXCEEDED` / `CODE_MODE_TIMEOUT`; Ctrl-C stops it
+too. Stopping terminates the script and cancels its in-flight requests.
+
+**Exit codes:** `0` success; `1` script error, refusal, budget or timeout; an
+uncaught operation error keeps the CLI codes below (`2` input, `3` auth, `5`
+server or `OUTCOME_UNKNOWN` — the error names the read that reconciles it).
+
+**Isolation and threat model.** The script runs in a worker thread that never
+receives the credential, the CLI config or the environment (it starts with an
+empty one); its only capability is a message channel to the CLI process,
+which applies the policy above and makes the authenticated request. Requests
+are marked `code-mode` in the client header for audit. The script itself runs
+in a fresh JavaScript context with only the language built-ins. This keeps
+credentials out of script memory and gates every side effect. It is **not** a
+sandbox for hostile code — Node's `vm` is not a security boundary — so run
+scripts you would run yourself. The hosted MCP will run scripts in an
+isolated hosted runtime instead.
+
 ## Errors and exit codes
 
 In `--format json` mode, every command prints a single canonical envelope to
@@ -802,14 +939,31 @@ bracketed code is stable across releases — quote it in support threads.
 Exit codes are a branchable taxonomy so a script can tell failure classes apart
 without parsing text:
 
-| Exit | Meaning                                                        |
-| ---- | -------------------------------------------------------------- |
-| `0`  | Success                                                        |
-| `2`  | Validation error (HTTP 400/422) — fix your input               |
-| `3`  | Auth / permission error (401/403) — re-authenticate            |
-| `4`  | Conflict / managed-by-code (409) — change it in the repo       |
-| `5`  | Server error (5xx) — retry only when `error.retryable` is true |
-| `1`  | Any other failure (local error, 402/404, argument errors, …)   |
+| Exit | Meaning                                                                                                                                            |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | Success                                                                                                                                            |
+| `2`  | Validation error (HTTP 400/422) — fix your input                                                                                                   |
+| `3`  | Auth / permission error (401/403) — re-authenticate                                                                                                |
+| `4`  | `MANAGED_BY_CODE` (409 with that code only) — the contract is managed as code; change it in the repo and push                                      |
+| `5`  | Server error (5xx), or `OUTCOME_UNKNOWN` — a write whose outcome is unknown; never repeat it blindly (see below)                                   |
+| `1`  | Any other failure: local errors, 402/404, argument errors, and every other 409 (`CONFLICT`, `RELEASE_PENDING_ACCEPTANCE`, `ROLLBACK_IN_FLIGHT`, …) |
+
+A 409 other than `MANAGED_BY_CODE` means the server refused a repeat or a
+conflicting change (an existing name, a release still being applied, a rollback
+already running). Wait or reconcile; do not edit `business/` for it.
+
+Exit `5` covers two different cases. Branch on `error.retryDisposition`:
+
+- **`reconcile_before_repeat`.** The write may or may not have run. Run the
+  read named in `error.details.reconcile` (also listed per command by
+  `farthershore operations list`) and repeat only if that read shows it did
+  not happen. The error can retain a server code such as `UPSTREAM_TIMEOUT`;
+  a lost response uses `OUTCOME_UNKNOWN`. Neither code alone decides whether
+  repeating the write is safe.
+- **`safe_to_repeat`.** Retry only when `error.retryable` is also true.
+
+The CLI retries reads automatically. It retries a write only on 429, or when
+the server marks the failure `retryable` with a `safe_to_repeat` verdict.
 
 ## CI and agent usage
 
@@ -829,6 +983,11 @@ Organization, role, member, invitation, and org MakerToken administration
 requires a live-user CLI session and is not projected into MCP; audit logs,
 notifications, and apply timelines are also CLI-only.
 
+The server resolves its target exactly as the CLI does: the stored login,
+`FARTHERSHORE_API_URL` (else the configured API URL), and the organization
+linked to its working directory, else the one chosen with
+`farthershore auth organization use`.
+
 ```bash
 farthershore-mcp
 ```