@farthershore/cli 0.33.3 → 0.33.5

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.33.3`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.33.5`.** 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.3
+npm install -g @farthershore/cli@0.33.5
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.33.3 farthershore --help
+npx -p @farthershore/cli@0.33.5 farthershore --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-npx -p @farthershore/cli@0.33.3 farthershore-mcp
+npx -p @farthershore/cli@0.33.5 farthershore-mcp
 ```
 
 ## Authentication
@@ -140,6 +140,31 @@ write commands cover **operational** state that lives outside the manifest
 | `FARTHERSHORE_CONSUMER_TOKEN`             | Ephemeral portal consumer session for `service-account`; never persisted |
 | `FARTHERSHORE_ENVIRONMENT_ID`             | Portal environment UUID fallback for `service-account`                   |
 | `FARTHERSHORE_SUBSCRIBER_ORGANIZATION_ID` | Subscriber organization UUID fallback for `service-account`              |
+| `FS_CLI_CHANNEL`                          | `stage` enables stage-channel commands for one invocation (see below)    |
+| `FS_CLI_STAGE_HOSTS`                      | Extra hosts (comma separated) the stage-channel gate treats as stage     |
+
+## Stage-channel commands
+
+A few operations exist only to service stage. `farthershore business delete` is
+the only one today: deleting a business is unrecoverable, and there is no
+builder reason to do it from a terminal against production — the dashboard owns
+that path.
+
+They are gated twice:
+
+1. **Registration.** The command is registered only when the CLI runs in the
+   stage channel. `make cli-stage` writes `{"channel":"stage"}` into
+   `~/.farthershore/config.json` (`make cli-prod` writes `"prod"`), and
+   `FS_CLI_CHANNEL=stage` does the same for a single invocation. Without the
+   marker the command is **absent from `farthershore business --help`** and
+   invoking it is an unknown-command error — so the published CLI, as a builder
+   installs it, does not have it at all.
+2. **Target.** Even in the stage channel, the command refuses when the api-url
+   it would call is not a stage host — `--api-url https://core.farthershore.com`,
+   or `FARTHERSHORE_API_URL` pointed at production. It exits **2** with
+   `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` before any request is made.
+
+Delete a production business from the dashboard instead.
 
 ## Commands
 
@@ -253,6 +278,16 @@ farthershore business create weather-api \
 
 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>
+```
+
+Deleting a business is **stage only** — the command is not registered in the
+published CLI at all (see [Stage-channel commands](#stage-channel-commands)).
+Run `make cli-stage` first; production businesses are deleted from the
+dashboard.
+
+<!-- cli-channel: stage -->
+
+```bash
 farthershore business delete weather-api --yes --format json
 ```
 
@@ -509,7 +544,25 @@ 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`
 
@@ -534,9 +587,12 @@ farthershore persona rotate weather-api <personaId> --env preview --format json
 farthershore persona delete weather-api <personaId> --env preview --format json
 ```
 
-Bootstrap and rotation return a key once. `login` opens the hosted portal with
-a 60-second single-use handoff and never prints its bearer. Product role keys
-must already exist in that subscriber's role catalog; omit `--role` to use its
+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
@@ -718,18 +774,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.3 or newer.
+This command requires `@farthershore/cli` 0.33.5 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] >= 3))) { console.error("Stop: CLI 0.33.3 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] >= 5))) { console.error("Stop: CLI 0.33.5 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.3`, then repeat the checks.
+`npm install -g @farthershore/cli@0.33.5`, then repeat the checks.
 Do not install or upgrade global tooling autonomously.
 
 The Farther Shore CLI downloads the exact installer archive and verifies this