@farthershore/cli 0.38.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,7 +4,82 @@ 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
- ## [Unreleased]
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
+
68
+ ## [0.39.0] - 2026-10-28
69
+
70
+ ### Changed
71
+
72
+ - **Breaking:** code mode (`farthershore code types` / `code describe`):
73
+ the `organizations.overview.read` output type renames
74
+ `organization.stripeConnected` to **`organization.billingConnected`**,
75
+ following `@farthershore/client`. Requires the matching platform release.
76
+ - **Breaking:** `farthershore api` applies the guard of the command for the
77
+ same operation. A destructive request (a delete, a revoke, a rollback) needs
78
+ the new `--yes` flag (else `DESTRUCTIVE_OP_REQUIRES_YES`), unless it is a
79
+ `--dry-run` of an operation that previews; so does a write to a path no
80
+ known operation serves. A request that deletes a business is refused
81
+ (`COMMAND_NOT_AVAILABLE_IN_PRODUCTION`): delete businesses from the
82
+ dashboard. Reads and non-destructive writes are unchanged.
8
83
 
9
84
  ## [0.38.0] - 2026-10-14
10
85
 
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.38.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.38.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.38.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,6 +158,15 @@ 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
 
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.
163
+
164
+ The raw `api` command applies both gates too: a request that the platform
165
+ serves as `business delete` (`-X DELETE /businesses/<id>`, or its
166
+ `/management/...` and `/agent/v1/...` forms) is refused with
167
+ `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` outside the stage channel and against a
168
+ non-stage api-url, before any request and whatever `--yes` says.
169
+
159
170
  Delete a production business from the dashboard instead.
160
171
 
161
172
  ## Commands
@@ -384,21 +395,21 @@ Manage preview/production environments. Production is the default scope when
384
395
  ```bash
385
396
  farthershore env list weather-api --format json
386
397
  farthershore env list weather-api --filter branch=env/preview --sort createdAt:desc --search preview --format json
387
- farthershore env create weather-api --name preview --branch env/preview --format json
398
+ farthershore env create weather-api --branch env/preview --format json
388
399
  farthershore env delete weather-api preview --yes --format json
389
400
  ```
390
401
 
391
402
  ### `farthershore organization`
392
403
 
393
404
  Manage organization members and the exact platform-permission roles assigned
394
- 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.
395
408
 
396
409
  ```bash
397
410
  farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
398
411
  farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
399
412
 
400
- # Primary owner only; hands ultimate authority to another existing member.
401
- farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
402
413
  ```
403
414
 
404
415
  Selecting the default organization is a local credential concern, not an API
@@ -444,21 +455,15 @@ If a create or update times out, run `token list --org` before trying again.
444
455
 
445
456
  ### `farthershore stripe`
446
457
 
447
- Read the Stripe Connect account a business bills through (a per-business
448
- override when one exists, otherwise the organization default) and remove a
449
- per-business override. Both require a signed-in owner session; a MakerToken is
450
- rejected. Connecting Stripe is a browser-only onboarding handshake with Stripe,
451
- so there is deliberately no `stripe connect` command — do it from the
452
- 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.
453
462
 
454
463
  ```bash
455
464
  farthershore stripe status weather-api --format json
456
- farthershore stripe disconnect weather-api --yes --format json
457
465
  ```
458
466
 
459
- `stripe disconnect` is refused while any subscription on the business is still
460
- money-bearing.
461
-
462
467
  ### `farthershore service-account`
463
468
 
464
469
  Manage service accounts owned by a subscriber organization. This is a separate
@@ -662,15 +667,28 @@ compiled integration that references it.
662
667
  farthershore variables list weather-api --format json
663
668
  printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
664
669
  SENTRY_AUTH_TOKEN --format json
670
+ printf '%s' "$PROVIDER_SECRET" | farthershore variables set weather-api \
671
+ PROVIDER_SECRET --production-only --format json
665
672
  printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
666
673
  FS_PUBLIC_POSTHOG_KEY --format json
667
674
  farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
668
675
  farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
669
676
  ```
670
677
 
671
- There is no builder-managed public-variable surface and values are never
672
- revealed after write. Rotation preserves the delivery phase; changing phase
673
- requires revoke, delete, and recreate.
678
+ Values are read from stdin. Secret plaintext is never returned; listing returns
679
+ public `FS_PUBLIC_*` values and secret metadata. Business-wide variables are
680
+ inherited by previews unless an environment override exists. Inherited secrets
681
+ require a verified repository pusher with write access; fork previews and
682
+ previews without verified identity cannot use them. Rotation updates the source
683
+ value without copying secrets into previews.
684
+
685
+ Use `--production-only` when creating a business-wide secret to exclude it from
686
+ previews. The flag cannot be used for public variables or with a preview
687
+ `--env`, and rotation preserves it. To change this scope, revoke, delete, and
688
+ recreate the binding. `variables list` displays `business-wide`, `environment`,
689
+ `production-only`, or `inherited` scope. JSON includes `productionOnly`,
690
+ `inheritedFrom` (`main` or null), and an `unavailableReason` when a preview
691
+ cannot use the inherited secret.
674
692
 
675
693
  ### `farthershore backend`
676
694
 
@@ -709,7 +727,7 @@ export async function POST(request: Request) {
709
727
  const ctx = await fs.verifyRequest({
710
728
  method: request.method,
711
729
  path: url.pathname,
712
- query: url.search,
730
+ query: url.search.slice(1), // the query after "?", exactly as signed
713
731
  headers: request.headers,
714
732
  body: new Uint8Array(body),
715
733
  });
@@ -756,8 +774,9 @@ records it under that type) so every handler branch can be exercised locally.
756
774
  id (the `webhook-id` header your endpoint received, also the `deliveryId` that
757
775
  `webhook test` / `webhook trigger` return): its status, attempts, last HTTP
758
776
  status and when the next attempt is due. A `failed` delivery with no next
759
- attempt (a test send) is final. Neither returns the event payload or your
760
- endpoint's response body.
777
+ attempt (a test send) is final. Lists omit payloads and response bodies. Single-delivery reads include the exact sent event envelope and the last response diagnostic for owners and admins. Diagnostics are capped at 4096 characters; unreachable endpoints get a plain-language reason that never names a host or IP. Maker tokens receive metadata only.
778
+
779
+ Use `farthershore webhook delivery-payload <businessId> <webhookId> <deliveryId>` to explicitly require payload access with a user session.
761
780
 
762
781
  For a receiver on your machine, `webhook listen` is the Stripe-CLI-style loop:
763
782
  it opens a Cloudflare quick tunnel to `--forward-to`, creates a temporary
@@ -773,8 +792,10 @@ farthershore webhook listen weather-api --forward-to localhost:3000/webhooks \
773
792
  --events subscription.created,payment.failed --format json
774
793
  ```
775
794
 
776
- `listen` needs `cloudflared` — bundled as an optional
777
- `@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
778
799
  killed hard leaves an
779
800
  endpoint with a `*.trycloudflare.com` URL; `webhook delete --yes` removes it.
780
801
 
@@ -803,18 +824,18 @@ Use `--all-plans` to clear plan scoping.
803
824
  Install or refresh the platform-verified skills bundle together. The platform
804
825
  pins this immutable release, and CI plus a daily repository check compare it to
805
826
  GitHub's latest stable release so the guidance cannot silently drift.
806
- This command requires `@farthershore/cli` 0.38.0 or newer.
827
+ This command requires `@farthershore/cli` 0.40.0 or newer.
807
828
 
808
829
  ```bash
809
830
  set -euo pipefail
810
831
  CLI_VERSION=$(farthershore --version)
811
- 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] > 38 || (+m[2] === 38 && +m[3] >= 0))) { console.error("Stop: CLI 0.38.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; } })'
812
833
  farthershore skills install --help
813
834
  farthershore skills install
814
835
  ```
815
836
 
816
837
  If either prerequisite fails, stop and ask the human to run
817
- `npm install -g @farthershore/cli@0.38.0`, then repeat the checks.
838
+ `npm install -g @farthershore/cli@0.40.0`, then repeat the checks.
818
839
  Do not install or upgrade global tooling autonomously.
819
840
 
820
841
  The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -842,6 +863,7 @@ farthershore api 'businesses/{business}/environments' --paginate
842
863
  farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
843
864
  farthershore api 'management/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
844
865
  farthershore api -X POST 'businesses/{business}/promo-codes' --input promo.json
866
+ farthershore api -X DELETE 'businesses/{business}/environments/{env}' --env preview-1 --yes
845
867
  farthershore api 'builder/organizations/{org}/members' --include
846
868
  farthershore api /businesses --format json | jq '.[].id'
847
869
  ```
@@ -869,6 +891,22 @@ farthershore api /businesses --format json | jq '.[].id'
869
891
  `--max-pages <n>` (default 100) bounds it.
870
892
  - **`-i, --include`** prints the HTTP status and response headers first.
871
893
  - **`--dry-run`** appends `dry_run=true`.
894
+ - **`--yes`** confirms a destructive request (see the guard below).
895
+
896
+ **Guard.** A raw request gets the guard of the command for the same
897
+ operation, so it is never weaker. The CLI matches the method and path to the
898
+ operation the platform serves there, then:
899
+
900
+ | Request | Needs |
901
+ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
902
+ | read (`GET`), or a write of a non-destructive operation | nothing |
903
+ | a destructive operation (a delete, a revoke, a rollback, ...) | `--yes` (else `DESTRUCTIVE_OP_REQUIRES_YES`) |
904
+ | `--dry-run` of a destructive operation that previews | nothing — it changes nothing |
905
+ | a write to a path no known operation serves | `--yes` (else `DESTRUCTIVE_OP_REQUIRES_YES`, `details.reason: "unknown_write"`) |
906
+ | a stage-only operation (business delete) | also the stage channel and a stage api-url (else `COMMAND_NOT_AVAILABLE_IN_PRODUCTION`) |
907
+
908
+ A path that serves several operations takes the strictest of their guards.
909
+ Every refusal happens before anything is sent.
872
910
 
873
911
  The body is printed as-is (pretty in a terminal, compact with `--format json`),
874
912
  never wrapped in the CLI envelope; there is no `--jq`, so pipe to `jq`. Errors
@@ -910,8 +948,8 @@ farthershore code run -e '
910
948
  `--side-effect read|write`, `--namespace <ns>`. Each hit shows the path
911
949
  (`fs.runtimeTokens.revoke`), a one-line summary and its flags (read/write,
912
950
  destructive, one-time secret, preview, paginated).
913
- - **`code describe <path|opKey>`** — accepts `runtimeTokens.revoke`,
914
- `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).
915
953
  - **`code types [namespace]`** — a self-contained `.d.ts` for `fs`, generated
916
954
  from the same tables `code run` enforces, with JSDoc from the operation
917
955
  specs.
@@ -940,6 +978,7 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
940
978
  | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
941
979
  | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
942
980
  | managed-as-code (contract) write | always refused |
981
+ | human-only action | no client or code-mode method; use the dashboard |
943
982
 
944
983
  One-time secrets (minted or rotated credentials) come back to the script as
945
984
  `{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
@@ -972,10 +1011,12 @@ isolated hosted runtime instead.
972
1011
  In `--format json` mode, every command prints a single canonical envelope to
973
1012
  stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failure,
974
1013
  where `error` carries a stable `code`, `message`, HTTP `status`, a `retryable`
975
- flag, and a remediation `hint` when one is registered. Diagnostics go to stderr.
1014
+ flag, a remediation `hint` when one is registered, and the `requestId` the API
1015
+ logged the request under. Diagnostics go to stderr.
976
1016
 
977
- In table mode, failures print `Error [CODE]: message` plus a `Hint:` line. The
978
- bracketed code is stable across releases — quote it in support threads.
1017
+ In table mode, failures print `Error [CODE]: message` plus a `Hint:` line and,
1018
+ for an API error, a `Reference:` line. The bracketed code is stable across
1019
+ releases — quote it, and the reference, in support threads.
979
1020
 
980
1021
  Exit codes are a branchable taxonomy so a script can tell failure classes apart
981
1022
  without parsing text:
@@ -1025,3 +1066,12 @@ run in CI.
1025
1066
  ## License
1026
1067
 
1027
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.