@farthershore/cli 0.33.2 → 0.33.4

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.33.2`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.33.4`.** 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.33.2
+npm install -g @farthershore/cli@0.33.4
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.33.2 farthershore --help
+npx -p @farthershore/cli@0.33.4 farthershore --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-npx -p @farthershore/cli@0.33.2 farthershore-mcp
+npx -p @farthershore/cli@0.33.4 farthershore-mcp
 ```
 
 ## Authentication
@@ -88,7 +88,8 @@ Create a managed business repo, author the business, validate it, and push:
 
 ```bash
 # 1. Create the managed repo. Human output is exactly its URL.
-REPO_URL=$(farthershore business create weather-api)
+REPO_URL=$(farthershore business create weather-api \
+  --idempotency-key <persisted-business-create-attempt-key>)
 
 # 2. Clone it and author business/ from scratch.
 git clone "$REPO_URL"
@@ -219,12 +220,14 @@ farthershore build --format json
 Run the same verdict the GitHub `farthershore/validate` PR check produces, before
 you push. It builds the manifest twice and compares the IR hash (the determinism
 check the build runner enforces), then — when you pass `--business` — submits the
-IR for a server dry-run that returns compile diagnostics, the semantic diff, and
-an economic-change verdict.
+IR for a server verdict that returns compile diagnostics, the semantic diff, and
+an economic-change verdict. The server may retain a diagnostic compilation
+record, but validation never accepts or publishes business state, so it is safe
+to repeat and does not take an idempotency key.
 
 ```bash
 farthershore validate                       # local build + determinism only
-farthershore validate --business weather-api # + full server verdict
+farthershore validate --business weather-api
 farthershore validate --local-only --format json
 ```
 
@@ -245,10 +248,11 @@ farthershore business subdomain-check weather-api --format json
 
 farthershore business create weather-api \
   --display-name "Weather API" \
+  --idempotency-key <persisted-business-create-attempt-key> \
   --format json
 
-farthershore business publish weather-api --format json
-farthershore business rollback weather-api wfe_previous --reason "bad release" --format json
+farthershore business publish weather-api --format json --idempotency-key <persisted-business-publish-attempt-key>
+farthershore business rollback weather-api wfe_previous --reason "bad release" --format json --idempotency-key <persisted-business-rollback-attempt-key>
 farthershore business delete weather-api --yes --format json
 ```
 
@@ -338,7 +342,7 @@ farthershore organization role list <organizationId> --filter builtIn=true --sor
 farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
 
 # Primary owner only; hands ultimate authority to another existing member.
-farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
+farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json --idempotency-key <persisted-organization-ownership-transfer-attempt-key>
 ```
 
 Selecting the default organization is a local credential concern, not an API
@@ -365,14 +369,15 @@ farthershore token create deploy-bot --org \
 
 farthershore token list --org --format json
 farthershore token approvals --org --format json
-farthershore token approve <approvalId> --org --format json
+farthershore token approve <approvalId> --org --format json --idempotency-key <persisted-token-approve-attempt-key>
 farthershore token approve <approvalId> --org \
+  --idempotency-key <persisted-token-approve-attempt-key> \
   --permissions '["business:read"]' --format json # trim on approval
 farthershore token deny <approvalId> --org --format json
 farthershore token update <tokenId> --org \
   --permissions '["business:read"]' \
   --idempotency-key org-token-update-2026-08-11 --format json
-farthershore token rotate <tokenId> --org --format json
+farthershore token rotate <tokenId> --org --format json --idempotency-key <persisted-token-rotate-attempt-key>
 farthershore token revoke <tokenId> --org --yes --format json
 ```
 
@@ -383,9 +388,10 @@ exactly once; store it immediately. Human output follows the same rule: it
 prints plaintext only for an ACTIVE one-time-secret response and says explicitly
 when a PENDING request minted nothing.
 
-Create and update accept `--idempotency-key`. Reuse the same key when repeating
-the same logical request after an interrupted invocation. If omitted, the CLI
-generates a key and keeps it stable across its automatic transient retries.
+Create and update require `--idempotency-key`. Persist the key before the first
+dispatch and reuse it only when repeating that exact logical request after an
+interrupted invocation. The CLI never generates a key: a process-local key
+would be lost across the restart where retry safety matters most.
 
 ### `farthershore stripe`
 
@@ -430,15 +436,17 @@ farthershore service-account approvals <businessId> --format json
 farthershore service-account approve <businessId> <approvalId> \
   --permissions '["route:read"]' --format json # optional trim
 farthershore service-account deny <businessId> <approvalId> --format json
-farthershore service-account rotate <businessId> <serviceAccountId> --format json
+farthershore service-account rotate <businessId> <serviceAccountId> --format json --idempotency-key <persisted-service-account-rotate-attempt-key>
 farthershore service-account revoke <businessId> <serviceAccountId> --yes --format json
 ```
 
 Pass `--environment-id` and `--subscriber-organization` to override the two
 context environment variables for one command. PENDING create/update responses
 never print `plaintext`. ACTIVE creates
-and rotations print the one-time key once. Create/update idempotency follows the
-same explicit-key or generated stable in-flight retry behavior as org tokens.
+and rotations print the one-time key once. Create, update, and rotate require a
+caller-persisted key, just like one-time-secret org-token operations. A replayed
+success includes `meta.idempotency.replayed: true`; follow it with a list read
+before reporting current state.
 
 This group is direct CLI-only and deliberately has no MCP projection: the MCP
 operation registry carries builder principals, not portal consumer sessions.
@@ -484,8 +492,9 @@ farthershore plan list weather-api --format json
 
 ### `farthershore frontend`
 
-Managed Frontend Hosting operations plus a local preview. `deploy`, `status`,
-and `rollback` operate the hosted build; `preview` runs the generated
+Managed Frontend Hosting status, rollback, and a local preview. Builds are
+Git-triggered: production builds on a GitHub Release and preview environments
+build on pushes to their environment branch. `preview` runs the generated
 `frontend/`'s `vite dev` with an injected `window.__FS_CONFIG__` shim so the
 portal renders locally exactly as it serves in production. Pass `--mock` to
 inject `{ mock: true }` instead of Core/Clerk config for local page inspection
@@ -493,7 +502,6 @@ with placeholder data and auth bypassed.
 
 ```bash
 farthershore frontend status weather-api --format json
-farthershore frontend deploy weather-api --format json
 farthershore frontend rollback weather-api --release-id <hash> --format json
 
 # Local preview (shells out to vite; needs a frontend/ project)
@@ -501,18 +509,63 @@ farthershore frontend dev                            # hot-reloading dev server,
 farthershore frontend preview                        # production build served as-is, mock mode by default
 farthershore frontend dev --live                     # against the real platform
 farthershore frontend preview --core-url http://localhost:8787
-```
+
+# Local preview signed in as a test persona (hot reload against the real platform)
+farthershore frontend dev --live --business acme --env preview --persona alice
+farthershore frontend dev --live --business acme --env preview --persona persona_123 --port 4321
+```
+
+`--live --business --env --persona` (all three required, not combinable with
+`--mock` or `--core-url`) opens `http://localhost:<port>` (default 5173)
+already signed in as that test persona, exactly as the hosted portal would
+be. The CLI issues a short-lived, origin-bound preview lease from Core and
+holds it only in its own process memory; Vite runs on a private random
+loopback port behind a CLI-owned proxy that attaches the lease to portal
+requests and serves the secret-free sign-in bridge. Nothing secret ever
+reaches the browser URL, DOM, storage, or logs — the browser only ever holds
+the same HttpOnly session cookie the hosted portal uses. The lease renews
+automatically while the command runs and is revoked when it exits (Ctrl-C
+included); a lease that cannot be revoked expires within five minutes. Core
+is always the one selected for the authenticated CLI (`--api-url` /
+`FARTHERSHORE_API_URL`).
 
 ### `farthershore persona`
 
-Mint fresh `fsk_test_*` API keys in a test-strategy environment so you can
-exercise the gateway end-to-end.
+Create temporary subscriber users in a test-strategy environment so an agent
+can exercise the same customer RBAC, browser session, and gateway paths as a
+human. The Business SDK contributes raw permissions; the subscribing
+organization composes those permissions into its own product roles.
 
 ```bash
-farthershore persona bootstrap weather-api --env preview --plan pro --format json
+# First persona creates and owns a temporary subscriber workspace.
+farthershore persona bootstrap weather-api --env preview --plan pro --format json --idempotency-key <persisted-persona-bootstrap-attempt-key>
 farthershore persona list weather-api --env preview --format json
-farthershore persona revoke weather-api <personaId> --env preview --format json
-```
+farthershore persona login weather-api <ownerPersonaId> --env preview --format json
+
+# Join the same subscriber after its owner has enabled subscriber RBAC and
+# created roles/defaults through the normal customer RBAC surface.
+farthershore persona bootstrap weather-api --env preview --plan pro \
+  --subscriber-id <subscriberId> --account-role member --role viewer \
+  --format json --idempotency-key <persisted-member-bootstrap-attempt-key>
+
+farthershore persona rotate weather-api <personaId> --env preview --format json --idempotency-key <persisted-persona-rotate-attempt-key>
+farthershore persona delete weather-api <personaId> --env preview --format json
+```
+
+Bootstrap and rotation return a key once. `login` sends the 60-second,
+single-use handoff only in the browser URL fragment to the platform-owned
+`/persona-sign-in` bridge. The bridge establishes an HttpOnly browser session
+and returns to the exact original portal path, query, and fragment. CLI output
+contains portal metadata but never the handoff or a session bearer. Product
+role keys must already exist in that subscriber's role catalog; omit `--role` to use its
+configured default. Deletion tears down the temporary user and credential, and
+deleting the environment also removes the remaining persona-owned workspace.
+After an environment-branch apply, existing personas remain available but are
+detached from the superseded subscription. Use `persona login` with the same
+persona id and select a plan from the new branch contract; the CLI does not
+fall back to a production plan. The old raw test key stays invalid. After the
+persona is reattached, run `persona rotate` to mint a replacement key for
+gateway testing; its product roles and explicit scope ceiling are preserved.
 
 ### `farthershore usage`
 
@@ -548,11 +601,11 @@ compiled integration that references it.
 ```bash
 farthershore variables list weather-api --format json
 printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
-  SENTRY_AUTH_TOKEN --format json
+  SENTRY_AUTH_TOKEN --format json --idempotency-key <persisted-sentry-variable-attempt-key>
 printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
-  FS_PUBLIC_POSTHOG_KEY --format json
-farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
-farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
+  FS_PUBLIC_POSTHOG_KEY --format json --idempotency-key <persisted-posthog-variable-attempt-key>
+farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json --idempotency-key <persisted-variables-revoke-attempt-key>
+farthershore variables rm weather-api POSTHOG_SECRET --yes --format json --idempotency-key <persisted-variables-rm-attempt-key>
 ```
 
 There is no builder-managed public-variable surface and values are never
@@ -570,13 +623,14 @@ farthershore backend list weather-api --format json
 farthershore backend create weather-api \
   --name "Production API" \
   --origin-url https://api.example.com \
+  --idempotency-key <persisted-backend-create-attempt-key> \
   --format json
 farthershore backend bind weather-api api \
   --env preview-42 \
   --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 create weather-api --backend <backendId> --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>
+farthershore backend tokens rotate weather-api <tokenId> --format json --idempotency-key <persisted-backend-tokens-rotate-attempt-key>
 farthershore backend tokens revoke weather-api <tokenId> --yes --format json
 ```
 
@@ -621,12 +675,13 @@ farthershore webhook list weather-api --format json
 farthershore webhook create weather-api \
   --url https://hooks.example.com/farthershore \
   --events subscription.created,payment.failed \
+  --idempotency-key <persisted-webhook-create-attempt-key> \
   --format json
 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 test weather-api <webhookId> --idempotency-key <persisted-test-attempt-key> --format json
+farthershore webhook trigger weather-api <webhookId> --type payment.failed --idempotency-key <persisted-trigger-attempt-key> --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> --format json --idempotency-key <persisted-webhook-rotate-attempt-key>
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
 
@@ -665,8 +720,10 @@ Manage checkout promo codes (operational state, not part of the manifest).
 farthershore promo-code list weather-api --format json
 farthershore promo-code create weather-api \
   --code LAUNCH25 --kind percent_off --percent 25 --duration-months 3 \
+  --idempotency-key <persisted-promo-code-create-attempt-key> \
   --plan <planId> --format json
 farthershore promo-code create weather-api \
+  --idempotency-key <persisted-promo-code-create-attempt-key> \
   --code SAVE500 --kind amount_off --amount-cents 500 --duration-months 1 --format json
 farthershore promo-code archive weather-api <promoCodeId> --format json
 farthershore promo-code reactivate weather-api <promoCodeId> --format json
@@ -682,18 +739,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.33.2 or newer.
+This command requires `@farthershore/cli` 0.33.4 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] > 33 || (+m[2] === 33 && +m[3] >= 2))) { console.error("Stop: CLI 0.33.2 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] > 33 || (+m[2] === 33 && +m[3] >= 4))) { console.error("Stop: CLI 0.33.4 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.33.2`, then repeat the checks.
+`npm install -g @farthershore/cli@0.33.4`, then repeat the checks.
 Do not install or upgrade global tooling autonomously.
 
 The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -721,14 +778,14 @@ 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                                   |
-| `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`  | 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, …)   |
 
 ## CI and agent usage