@farthershore/cli 0.39.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,73 @@ All notable changes to the `farthershore` CLI are documented here. The CLI
4
4
  versions independently from the SDKs. Pre-1.0: minor versions may include
5
5
  breaking changes. Releases before 0.35.0 are recorded only in the git history.
6
6
 
7
+ ## [0.41.0] - 2026-11-09
8
+
9
+ - **Breaking:** `business rollback` now sends `publishId` and reads
10
+ `rollbackPublishId` from the response; the publish receipt names the same
11
+ id `publishId`. Requires the matching platform release.
12
+
13
+ ## [0.40.0] - 2026-11-06
14
+
15
+ - **Breaking:** Organization deletion, ownership transfer and Stripe disconnection now direct callers to the dashboard. Business deletion is available only to the stage CLI; human-only methods are removed from code mode and the API client.
16
+
17
+ ### Added
18
+
19
+ - `code search` returns docs guides alongside matching methods. JSON guides
20
+ include the catalog methods named by each matching docs chunk (with an
21
+ excerpt fallback for older docs hosts). `--no-guides` or `--namespace`
22
+ searches methods only; `--stage` selects stage docs. If docs search is
23
+ unavailable, method search still works and JSON reports
24
+ `guidesUnavailable: true`. Guide search requires the matching platform release.
25
+ - `code search --code <js>` and `--code-file <file>` run a JavaScript filter
26
+ over a frozen `catalog`, with no platform access. Query words are optional
27
+ when using either flag; combining query words with a script, or both script
28
+ flags, fails with `INVALID_ARGUMENT`.
29
+ - `code describe` accepts 1–25 method paths, operation keys or `docs:<page>`
30
+ refs, and `--stage` selects stage docs. Docs refs return the full page's
31
+ Markdown. JSON for a single method is unchanged; multiple refs or a docs
32
+ ref return `{ methods, docs }`. Invalid page paths fail with
33
+ `DOCS_INVALID_PAGE`; more than 25 refs fail with `INVALID_ARGUMENT`.
34
+ Reading docs pages requires the matching platform release.
35
+ - `webhook event-types`, endpoint subscriptions, `webhook listen` and sample
36
+ sends support `customer.created`, `customer.deleted`,
37
+ `customer.member.added`, `customer.member.updated` and
38
+ `customer.member.removed`. Customer deletion includes test-persona cleanup
39
+ when it deletes the customer; starting a free subscription now emits
40
+ `subscription.created`. Requires the matching platform release.
41
+
42
+ ### Changed
43
+
44
+ - **Breaking:** `docs search` uses semantic docs search by default, returning
45
+ page paths, titles, URLs and snippets. Use `--literal` for the previous
46
+ literal search; `--collection` implies literal search. If semantic search is
47
+ unavailable, it falls back to literal search with a notice and
48
+ `searchUnavailable: true` in JSON. Semantic search requires the matching
49
+ platform release.
50
+ - **Breaking:** `stripe disconnect` no longer accepts `--delete-account`.
51
+ It only removes a business's Stripe override. Close Stripe accounts from
52
+ the dashboard after a fresh sign-in check. Requires the matching platform
53
+ release.
54
+ - **Breaking:** customer context tokens are always enabled; remove
55
+ `customerContext.contextTokens` from Business SDK programs. Contract output
56
+ no longer includes `customer_context.context_tokens`. Requires the matching
57
+ platform release.
58
+
59
+ ### Fixed
60
+
61
+ - **Breaking:** `webhook listen` uses only the bundled tunnel helper and no
62
+ longer runs an executable from `PATH`. A missing or unsupported helper
63
+ fails with `TUNNEL_BINARY_UNAVAILABLE`; reinstall the CLI with optional
64
+ dependencies enabled on a supported platform.
65
+ - **Breaking:** `backend scaffold` refuses a root `.gitignore` that is a
66
+ symbolic link, a hard-linked file or a special file
67
+ (`BACKEND_SCAFFOLD_GITIGNORE_UNSAFE`), and keeps its write bound to the
68
+ validated file.
69
+ - `frontend dev` / `frontend preview` with `--live --persona` wait for lease
70
+ renewal scheduling before reporting readiness. Shutdown waits for pending
71
+ renewal work and attempts to revoke the current lease even if cancelling
72
+ renewal fails; cancellation failures are reported after cleanup.
73
+
7
74
  ## [0.39.0] - 2026-10-28
8
75
 
9
76
  ### Changed
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Create and operate [FartherShore](https://farthershore.com) software businesses
4
4
  from the terminal.
5
5
 
6
- **Status: `0.39.0`.** Pre-1.0 — the command surface is stable but may still
6
+ **Status: `0.41.0`.** Pre-1.0 — the command surface is stable but may still
7
7
  change between minor versions. Pin an exact version in CI.
8
8
 
9
9
  FartherShore lets you define a software business as code, then sells, meters,
@@ -20,13 +20,13 @@ takes `--format json` for non-interactive scripting.
20
20
  ## Install
21
21
 
22
22
  ```bash
23
- npm install -g @farthershore/cli@0.39.0
23
+ npm install -g @farthershore/cli@0.41.0
24
24
  ```
25
25
 
26
26
  Or run it directly with npx:
27
27
 
28
28
  ```bash
29
- npx -p @farthershore/cli@0.39.0 farthershore --help
29
+ npx -p @farthershore/cli@0.41.0 farthershore --help
30
30
  ```
31
31
 
32
32
  ## Authentication
@@ -142,7 +142,9 @@ the only one today: deleting a business is unrecoverable, and there is no
142
142
  builder reason to do it from a terminal against production — the dashboard owns
143
143
  that path.
144
144
 
145
- They are gated twice:
145
+ The published production build excludes this command and its raw deletion request.
146
+ Build the internal stage CLI with `FS_CLI_BUILD_CHANNEL=stage pnpm --filter @farthershore/cli build`.
147
+ The stage build is gated twice:
146
148
 
147
149
  1. **Registration.** The command is registered only when the CLI runs in the
148
150
  stage channel. `make cli-stage` writes `{"channel":"stage"}` into
@@ -156,12 +158,8 @@ They are gated twice:
156
158
  or `FARTHERSHORE_API_URL` pointed at production. It exits **2** with
157
159
  `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` before any request is made.
158
160
 
159
- Code mode applies both gates to the same operation: outside the stage channel
160
- `fs.businesses.delete` does not exist (absent from `code search`, `describe`,
161
- `types` and the script's `fs`), and in the stage channel a call against a
162
- non-stage api-url is refused with `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` before
163
- any request, whatever `--allow-writes` / `--yes` say. Code mode never gets a
164
- weaker guard than the command for the same operation.
161
+ Human-only actions have no client or code-mode method in any channel, including stage.
162
+ Business deletion for teardown uses only the stage command’s raw request.
165
163
 
166
164
  The raw `api` command applies both gates too: a request that the platform
167
165
  serves as `business delete` (`-X DELETE /businesses/<id>`, or its
@@ -351,8 +349,11 @@ farthershore business update weather-api \
351
349
 
352
350
  `business publish` enforces the same go-live gates as the dashboard and returns
353
351
  stable remediation errors when a prerequisite is missing.
354
- `business rollback` enqueues a rollback of the specified prior publish workflow
355
- and requires the exact `business:rollback` permission.
352
+ `business rollback` takes a `publishId` and enqueues a rollback of that prior publish
353
+ and requires the exact `business:rollback` permission. The async management publish receipt returns
354
+ `publishId`; its publish-status response returns the same value as
355
+ `execution.id`. Pass that value unchanged. The rollback receipt returns
356
+ `rollbackPublishId` for the newly queued rollback.
356
357
 
357
358
  `business rbac` reads a business's Managed-RBAC state — the platform-owned
358
359
  `rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
@@ -404,14 +405,14 @@ farthershore env delete weather-api preview --yes --format json
404
405
  ### `farthershore organization`
405
406
 
406
407
  Manage organization members and the exact platform-permission roles assigned
407
- to them. Built-in and custom roles use the same list contract.
408
+ to them. Built-in and custom roles use the same list contract. Deletion, ownership
409
+ transfer, and removing or demoting an owner require a person in the dashboard
410
+ after fresh sign-in and typed-name confirmation.
408
411
 
409
412
  ```bash
410
413
  farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
411
414
  farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
412
415
 
413
- # Primary owner only; hands ultimate authority to another existing member.
414
- farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
415
416
  ```
416
417
 
417
418
  Selecting the default organization is a local credential concern, not an API
@@ -457,21 +458,15 @@ If a create or update times out, run `token list --org` before trying again.
457
458
 
458
459
  ### `farthershore stripe`
459
460
 
460
- Read the Stripe Connect account a business bills through (a per-business
461
- override when one exists, otherwise the organization default) and remove a
462
- per-business override. Both require a signed-in owner session; a MakerToken is
463
- rejected. Connecting Stripe is a browser-only onboarding handshake with Stripe,
464
- so there is deliberately no `stripe connect` command — do it from the
465
- dashboard and confirm with `stripe status`.
461
+ Read the Stripe account a business bills through. Reading status requires a
462
+ signed-in owner session. Connecting, disconnecting, closing or changing payout
463
+ settings requires a person in the dashboard after fresh sign-in and typed-name
464
+ confirmation. The CLI does not perform these actions.
466
465
 
467
466
  ```bash
468
467
  farthershore stripe status weather-api --format json
469
- farthershore stripe disconnect weather-api --yes --format json
470
468
  ```
471
469
 
472
- `stripe disconnect` is refused while any subscription on the business is still
473
- money-bearing.
474
-
475
470
  ### `farthershore service-account`
476
471
 
477
472
  Manage service accounts owned by a subscriber organization. This is a separate
@@ -800,8 +795,10 @@ farthershore webhook listen weather-api --forward-to localhost:3000/webhooks \
800
795
  --events subscription.created,payment.failed --format json
801
796
  ```
802
797
 
803
- `listen` needs `cloudflared` — bundled as an optional
804
- `@farthershore/cloudflared-<platform>` dependency, or on your PATH. A listener
798
+ `listen` needs the bundled tunnel helper, installed as an optional CLI
799
+ dependency. If it is missing, reinstall
800
+ the CLI with optional dependencies enabled; the listener does not search your
801
+ repository or PATH for an executable. A listener
805
802
  killed hard leaves an
806
803
  endpoint with a `*.trycloudflare.com` URL; `webhook delete --yes` removes it.
807
804
 
@@ -830,18 +827,18 @@ Use `--all-plans` to clear plan scoping.
830
827
  Install or refresh the platform-verified skills bundle together. The platform
831
828
  pins this immutable release, and CI plus a daily repository check compare it to
832
829
  GitHub's latest stable release so the guidance cannot silently drift.
833
- This command requires `@farthershore/cli` 0.39.0 or newer.
830
+ This command requires `@farthershore/cli` 0.41.0 or newer.
834
831
 
835
832
  ```bash
836
833
  set -euo pipefail
837
834
  CLI_VERSION=$(farthershore --version)
838
- 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] > 39 || (+m[2] === 39 && +m[3] >= 0))) { console.error("Stop: CLI 0.39.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
835
+ 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] > 41 || (+m[2] === 41 && +m[3] >= 0))) { console.error("Stop: CLI 0.41.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
839
836
  farthershore skills install --help
840
837
  farthershore skills install
841
838
  ```
842
839
 
843
840
  If either prerequisite fails, stop and ask the human to run
844
- `npm install -g @farthershore/cli@0.39.0`, then repeat the checks.
841
+ `npm install -g @farthershore/cli@0.41.0`, then repeat the checks.
845
842
  Do not install or upgrade global tooling autonomously.
846
843
 
847
844
  The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -954,8 +951,8 @@ farthershore code run -e '
954
951
  `--side-effect read|write`, `--namespace <ns>`. Each hit shows the path
955
952
  (`fs.runtimeTokens.revoke`), a one-line summary and its flags (read/write,
956
953
  destructive, one-time secret, preview, paginated).
957
- - **`code describe <path|opKey>`** — accepts `runtimeTokens.revoke`,
958
- `fs.runtimeTokens.revoke` or the opKey `runtime_token.revoke`.
954
+ - **`code describe <refs...>`** — accepts `runtimeTokens.revoke`,
955
+ `fs.runtimeTokens.revoke`, the opKey `runtime_token.revoke`, or `docs:<page>` (1–25 refs).
959
956
  - **`code types [namespace]`** — a self-contained `.d.ts` for `fs`, generated
960
957
  from the same tables `code run` enforces, with JSDoc from the operation
961
958
  specs.
@@ -977,14 +974,14 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
977
974
 
978
975
  **Policy** (checked in the CLI process for every call, not in the script):
979
976
 
980
- | Call | Needs |
981
- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
982
- | read | nothing |
983
- | write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
984
- | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
985
- | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
986
- | managed-as-code (contract) write | always refused |
987
- | stage-only (business delete) | also the stage channel and a stage api-url (else `COMMAND_NOT_AVAILABLE_IN_PRODUCTION`) |
977
+ | Call | Needs |
978
+ | ------------------------------------------------------- | ----------------------------------------------------------- |
979
+ | read | nothing |
980
+ | write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
981
+ | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
982
+ | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
983
+ | managed-as-code (contract) write | always refused |
984
+ | human-only action | no client or code-mode method; use the dashboard |
988
985
 
989
986
  One-time secrets (minted or rotated credentials) come back to the script as
990
987
  `{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
@@ -1072,3 +1069,12 @@ run in CI.
1072
1069
  ## License
1073
1070
 
1074
1071
  MIT
1072
+
1073
+ Code discovery includes docs guides: `farthershore code search runtime token`.
1074
+ Read one with `farthershore code describe docs:agents/overview`; describe accepts
1075
+ 1–25 method paths, opKeys, or docs refs. Use `--no-guides` or `--namespace` to
1076
+ search methods only. Use `--stage` to select stage docs; production is the default.
1077
+ For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.sideEffect === "read").map(m => m.method)'`
1078
+ or `--code-file script.js`. Filters have a frozen catalog and no platform access.
1079
+ `farthershore docs search "runtime token"` uses docs search and falls back to
1080
+ literal text when unavailable. `--literal` or `--collection` forces literal search.