@farthershore/cli 0.39.0 → 0.40.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,67 @@ 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.40.0] - 2026-11-06
8
+
9
+ - **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.
10
+
11
+ ### Added
12
+
13
+ - `code search` returns docs guides alongside matching methods. JSON guides
14
+ include the catalog methods named by each matching docs chunk (with an
15
+ excerpt fallback for older docs hosts). `--no-guides` or `--namespace`
16
+ searches methods only; `--stage` selects stage docs. If docs search is
17
+ unavailable, method search still works and JSON reports
18
+ `guidesUnavailable: true`. Guide search requires the matching platform release.
19
+ - `code search --code <js>` and `--code-file <file>` run a JavaScript filter
20
+ over a frozen `catalog`, with no platform access. Query words are optional
21
+ when using either flag; combining query words with a script, or both script
22
+ flags, fails with `INVALID_ARGUMENT`.
23
+ - `code describe` accepts 1–25 method paths, operation keys or `docs:<page>`
24
+ refs, and `--stage` selects stage docs. Docs refs return the full page's
25
+ Markdown. JSON for a single method is unchanged; multiple refs or a docs
26
+ ref return `{ methods, docs }`. Invalid page paths fail with
27
+ `DOCS_INVALID_PAGE`; more than 25 refs fail with `INVALID_ARGUMENT`.
28
+ Reading docs pages requires the matching platform release.
29
+ - `webhook event-types`, endpoint subscriptions, `webhook listen` and sample
30
+ sends support `customer.created`, `customer.deleted`,
31
+ `customer.member.added`, `customer.member.updated` and
32
+ `customer.member.removed`. Customer deletion includes test-persona cleanup
33
+ when it deletes the customer; starting a free subscription now emits
34
+ `subscription.created`. Requires the matching platform release.
35
+
36
+ ### Changed
37
+
38
+ - **Breaking:** `docs search` uses semantic docs search by default, returning
39
+ page paths, titles, URLs and snippets. Use `--literal` for the previous
40
+ literal search; `--collection` implies literal search. If semantic search is
41
+ unavailable, it falls back to literal search with a notice and
42
+ `searchUnavailable: true` in JSON. Semantic search requires the matching
43
+ platform release.
44
+ - **Breaking:** `stripe disconnect` no longer accepts `--delete-account`.
45
+ It only removes a business's Stripe override. Close Stripe accounts from
46
+ the dashboard after a fresh sign-in check. Requires the matching platform
47
+ release.
48
+ - **Breaking:** customer context tokens are always enabled; remove
49
+ `customerContext.contextTokens` from Business SDK programs. Contract output
50
+ no longer includes `customer_context.context_tokens`. Requires the matching
51
+ platform release.
52
+
53
+ ### Fixed
54
+
55
+ - **Breaking:** `webhook listen` uses only the bundled tunnel helper and no
56
+ longer runs an executable from `PATH`. A missing or unsupported helper
57
+ fails with `TUNNEL_BINARY_UNAVAILABLE`; reinstall the CLI with optional
58
+ dependencies enabled on a supported platform.
59
+ - **Breaking:** `backend scaffold` refuses a root `.gitignore` that is a
60
+ symbolic link, a hard-linked file or a special file
61
+ (`BACKEND_SCAFFOLD_GITIGNORE_UNSAFE`), and keeps its write bound to the
62
+ validated file.
63
+ - `frontend dev` / `frontend preview` with `--live --persona` wait for lease
64
+ renewal scheduling before reporting readiness. Shutdown waits for pending
65
+ renewal work and attempts to revoke the current lease even if cancelling
66
+ renewal fails; cancellation failures are reported after cleanup.
67
+
7
68
  ## [0.39.0] - 2026-10-28
8
69
 
9
70
  ### 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.40.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.40.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.40.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
@@ -404,14 +402,14 @@ farthershore env delete weather-api preview --yes --format json
404
402
  ### `farthershore organization`
405
403
 
406
404
  Manage organization members and the exact platform-permission roles assigned
407
- to them. Built-in and custom roles use the same list contract.
405
+ to them. Built-in and custom roles use the same list contract. Deletion, ownership
406
+ transfer, and removing or demoting an owner require a person in the dashboard
407
+ after fresh sign-in and typed-name confirmation.
408
408
 
409
409
  ```bash
410
410
  farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
411
411
  farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
412
412
 
413
- # Primary owner only; hands ultimate authority to another existing member.
414
- farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
415
413
  ```
416
414
 
417
415
  Selecting the default organization is a local credential concern, not an API
@@ -457,21 +455,15 @@ If a create or update times out, run `token list --org` before trying again.
457
455
 
458
456
  ### `farthershore stripe`
459
457
 
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`.
458
+ Read the Stripe account a business bills through. Reading status requires a
459
+ signed-in owner session. Connecting, disconnecting, closing or changing payout
460
+ settings requires a person in the dashboard after fresh sign-in and typed-name
461
+ confirmation. The CLI does not perform these actions.
466
462
 
467
463
  ```bash
468
464
  farthershore stripe status weather-api --format json
469
- farthershore stripe disconnect weather-api --yes --format json
470
465
  ```
471
466
 
472
- `stripe disconnect` is refused while any subscription on the business is still
473
- money-bearing.
474
-
475
467
  ### `farthershore service-account`
476
468
 
477
469
  Manage service accounts owned by a subscriber organization. This is a separate
@@ -800,8 +792,10 @@ farthershore webhook listen weather-api --forward-to localhost:3000/webhooks \
800
792
  --events subscription.created,payment.failed --format json
801
793
  ```
802
794
 
803
- `listen` needs `cloudflared` — bundled as an optional
804
- `@farthershore/cloudflared-<platform>` dependency, or on your PATH. A listener
795
+ `listen` needs the bundled tunnel helper, installed as an optional CLI
796
+ dependency. If it is missing, reinstall
797
+ the CLI with optional dependencies enabled; the listener does not search your
798
+ repository or PATH for an executable. A listener
805
799
  killed hard leaves an
806
800
  endpoint with a `*.trycloudflare.com` URL; `webhook delete --yes` removes it.
807
801
 
@@ -830,18 +824,18 @@ Use `--all-plans` to clear plan scoping.
830
824
  Install or refresh the platform-verified skills bundle together. The platform
831
825
  pins this immutable release, and CI plus a daily repository check compare it to
832
826
  GitHub's latest stable release so the guidance cannot silently drift.
833
- This command requires `@farthershore/cli` 0.39.0 or newer.
827
+ This command requires `@farthershore/cli` 0.40.0 or newer.
834
828
 
835
829
  ```bash
836
830
  set -euo pipefail
837
831
  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; } })'
832
+ 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] > 40 || (+m[2] === 40 && +m[3] >= 0))) { console.error("Stop: CLI 0.40.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
839
833
  farthershore skills install --help
840
834
  farthershore skills install
841
835
  ```
842
836
 
843
837
  If either prerequisite fails, stop and ask the human to run
844
- `npm install -g @farthershore/cli@0.39.0`, then repeat the checks.
838
+ `npm install -g @farthershore/cli@0.40.0`, then repeat the checks.
845
839
  Do not install or upgrade global tooling autonomously.
846
840
 
847
841
  The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -954,8 +948,8 @@ farthershore code run -e '
954
948
  `--side-effect read|write`, `--namespace <ns>`. Each hit shows the path
955
949
  (`fs.runtimeTokens.revoke`), a one-line summary and its flags (read/write,
956
950
  destructive, one-time secret, preview, paginated).
957
- - **`code describe <path|opKey>`** — accepts `runtimeTokens.revoke`,
958
- `fs.runtimeTokens.revoke` or the opKey `runtime_token.revoke`.
951
+ - **`code describe <refs...>`** — accepts `runtimeTokens.revoke`,
952
+ `fs.runtimeTokens.revoke`, the opKey `runtime_token.revoke`, or `docs:<page>` (1–25 refs).
959
953
  - **`code types [namespace]`** — a self-contained `.d.ts` for `fs`, generated
960
954
  from the same tables `code run` enforces, with JSDoc from the operation
961
955
  specs.
@@ -977,14 +971,14 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
977
971
 
978
972
  **Policy** (checked in the CLI process for every call, not in the script):
979
973
 
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`) |
974
+ | Call | Needs |
975
+ | ------------------------------------------------------- | ----------------------------------------------------------- |
976
+ | read | nothing |
977
+ | write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
978
+ | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
979
+ | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
980
+ | managed-as-code (contract) write | always refused |
981
+ | human-only action | no client or code-mode method; use the dashboard |
988
982
 
989
983
  One-time secrets (minted or rotated credentials) come back to the script as
990
984
  `{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
@@ -1072,3 +1066,12 @@ run in CI.
1072
1066
  ## License
1073
1067
 
1074
1068
  MIT
1069
+
1070
+ Code discovery includes docs guides: `farthershore code search runtime token`.
1071
+ Read one with `farthershore code describe docs:agents/overview`; describe accepts
1072
+ 1–25 method paths, opKeys, or docs refs. Use `--no-guides` or `--namespace` to
1073
+ search methods only. Use `--stage` to select stage docs; production is the default.
1074
+ For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.sideEffect === "read").map(m => m.method)'`
1075
+ or `--code-file script.js`. Filters have a frozen catalog and no platform access.
1076
+ `farthershore docs search "runtime token"` uses docs search and falls back to
1077
+ literal text when unavailable. `--literal` or `--collection` forces literal search.