@farthershore/cli 0.38.0 → 0.39.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,21 @@ 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.39.0] - 2026-10-28
8
+
9
+ ### Changed
10
+
11
+ - **Breaking:** code mode (`farthershore code types` / `code describe`):
12
+ the `organizations.overview.read` output type renames
13
+ `organization.stripeConnected` to **`organization.billingConnected`**,
14
+ following `@farthershore/client`. Requires the matching platform release.
15
+ - **Breaking:** `farthershore api` applies the guard of the command for the
16
+ same operation. A destructive request (a delete, a revoke, a rollback) needs
17
+ the new `--yes` flag (else `DESTRUCTIVE_OP_REQUIRES_YES`), unless it is a
18
+ `--dry-run` of an operation that previews; so does a write to a path no
19
+ known operation serves. A request that deletes a business is refused
20
+ (`COMMAND_NOT_AVAILABLE_IN_PRODUCTION`): delete businesses from the
21
+ dashboard. Reads and non-destructive writes are unchanged.
8
22
 
9
23
  ## [0.38.0] - 2026-10-14
10
24
 
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.39.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.39.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.39.0 farthershore --help
30
30
  ```
31
31
 
32
32
  ## Authentication
@@ -156,6 +156,19 @@ They are gated twice:
156
156
  or `FARTHERSHORE_API_URL` pointed at production. It exits **2** with
157
157
  `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` before any request is made.
158
158
 
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.
165
+
166
+ The raw `api` command applies both gates too: a request that the platform
167
+ serves as `business delete` (`-X DELETE /businesses/<id>`, or its
168
+ `/management/...` and `/agent/v1/...` forms) is refused with
169
+ `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` outside the stage channel and against a
170
+ non-stage api-url, before any request and whatever `--yes` says.
171
+
159
172
  Delete a production business from the dashboard instead.
160
173
 
161
174
  ## Commands
@@ -384,7 +397,7 @@ Manage preview/production environments. Production is the default scope when
384
397
  ```bash
385
398
  farthershore env list weather-api --format json
386
399
  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
400
+ farthershore env create weather-api --branch env/preview --format json
388
401
  farthershore env delete weather-api preview --yes --format json
389
402
  ```
390
403
 
@@ -662,15 +675,28 @@ compiled integration that references it.
662
675
  farthershore variables list weather-api --format json
663
676
  printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
664
677
  SENTRY_AUTH_TOKEN --format json
678
+ printf '%s' "$PROVIDER_SECRET" | farthershore variables set weather-api \
679
+ PROVIDER_SECRET --production-only --format json
665
680
  printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
666
681
  FS_PUBLIC_POSTHOG_KEY --format json
667
682
  farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
668
683
  farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
669
684
  ```
670
685
 
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.
686
+ Values are read from stdin. Secret plaintext is never returned; listing returns
687
+ public `FS_PUBLIC_*` values and secret metadata. Business-wide variables are
688
+ inherited by previews unless an environment override exists. Inherited secrets
689
+ require a verified repository pusher with write access; fork previews and
690
+ previews without verified identity cannot use them. Rotation updates the source
691
+ value without copying secrets into previews.
692
+
693
+ Use `--production-only` when creating a business-wide secret to exclude it from
694
+ previews. The flag cannot be used for public variables or with a preview
695
+ `--env`, and rotation preserves it. To change this scope, revoke, delete, and
696
+ recreate the binding. `variables list` displays `business-wide`, `environment`,
697
+ `production-only`, or `inherited` scope. JSON includes `productionOnly`,
698
+ `inheritedFrom` (`main` or null), and an `unavailableReason` when a preview
699
+ cannot use the inherited secret.
674
700
 
675
701
  ### `farthershore backend`
676
702
 
@@ -709,7 +735,7 @@ export async function POST(request: Request) {
709
735
  const ctx = await fs.verifyRequest({
710
736
  method: request.method,
711
737
  path: url.pathname,
712
- query: url.search,
738
+ query: url.search.slice(1), // the query after "?", exactly as signed
713
739
  headers: request.headers,
714
740
  body: new Uint8Array(body),
715
741
  });
@@ -756,8 +782,9 @@ records it under that type) so every handler branch can be exercised locally.
756
782
  id (the `webhook-id` header your endpoint received, also the `deliveryId` that
757
783
  `webhook test` / `webhook trigger` return): its status, attempts, last HTTP
758
784
  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.
785
+ 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.
786
+
787
+ Use `farthershore webhook delivery-payload <businessId> <webhookId> <deliveryId>` to explicitly require payload access with a user session.
761
788
 
762
789
  For a receiver on your machine, `webhook listen` is the Stripe-CLI-style loop:
763
790
  it opens a Cloudflare quick tunnel to `--forward-to`, creates a temporary
@@ -803,18 +830,18 @@ Use `--all-plans` to clear plan scoping.
803
830
  Install or refresh the platform-verified skills bundle together. The platform
804
831
  pins this immutable release, and CI plus a daily repository check compare it to
805
832
  GitHub's latest stable release so the guidance cannot silently drift.
806
- This command requires `@farthershore/cli` 0.38.0 or newer.
833
+ This command requires `@farthershore/cli` 0.39.0 or newer.
807
834
 
808
835
  ```bash
809
836
  set -euo pipefail
810
837
  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; } })'
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; } })'
812
839
  farthershore skills install --help
813
840
  farthershore skills install
814
841
  ```
815
842
 
816
843
  If either prerequisite fails, stop and ask the human to run
817
- `npm install -g @farthershore/cli@0.38.0`, then repeat the checks.
844
+ `npm install -g @farthershore/cli@0.39.0`, then repeat the checks.
818
845
  Do not install or upgrade global tooling autonomously.
819
846
 
820
847
  The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -842,6 +869,7 @@ farthershore api 'businesses/{business}/environments' --paginate
842
869
  farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
843
870
  farthershore api 'management/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
844
871
  farthershore api -X POST 'businesses/{business}/promo-codes' --input promo.json
872
+ farthershore api -X DELETE 'businesses/{business}/environments/{env}' --env preview-1 --yes
845
873
  farthershore api 'builder/organizations/{org}/members' --include
846
874
  farthershore api /businesses --format json | jq '.[].id'
847
875
  ```
@@ -869,6 +897,22 @@ farthershore api /businesses --format json | jq '.[].id'
869
897
  `--max-pages <n>` (default 100) bounds it.
870
898
  - **`-i, --include`** prints the HTTP status and response headers first.
871
899
  - **`--dry-run`** appends `dry_run=true`.
900
+ - **`--yes`** confirms a destructive request (see the guard below).
901
+
902
+ **Guard.** A raw request gets the guard of the command for the same
903
+ operation, so it is never weaker. The CLI matches the method and path to the
904
+ operation the platform serves there, then:
905
+
906
+ | Request | Needs |
907
+ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
908
+ | read (`GET`), or a write of a non-destructive operation | nothing |
909
+ | a destructive operation (a delete, a revoke, a rollback, ...) | `--yes` (else `DESTRUCTIVE_OP_REQUIRES_YES`) |
910
+ | `--dry-run` of a destructive operation that previews | nothing — it changes nothing |
911
+ | a write to a path no known operation serves | `--yes` (else `DESTRUCTIVE_OP_REQUIRES_YES`, `details.reason: "unknown_write"`) |
912
+ | a stage-only operation (business delete) | also the stage channel and a stage api-url (else `COMMAND_NOT_AVAILABLE_IN_PRODUCTION`) |
913
+
914
+ A path that serves several operations takes the strictest of their guards.
915
+ Every refusal happens before anything is sent.
872
916
 
873
917
  The body is printed as-is (pretty in a terminal, compact with `--format json`),
874
918
  never wrapped in the CLI envelope; there is no `--jq`, so pipe to `jq`. Errors
@@ -933,13 +977,14 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
933
977
 
934
978
  **Policy** (checked in the CLI process for every call, not in the script):
935
979
 
936
- | Call | Needs |
937
- | ------------------------------------------------------- | ----------------------------------------------------------- |
938
- | read | nothing |
939
- | write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
940
- | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
941
- | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
942
- | managed-as-code (contract) write | always refused |
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`) |
943
988
 
944
989
  One-time secrets (minted or rotated credentials) come back to the script as
945
990
  `{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
@@ -972,10 +1017,12 @@ isolated hosted runtime instead.
972
1017
  In `--format json` mode, every command prints a single canonical envelope to
973
1018
  stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failure,
974
1019
  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.
1020
+ flag, a remediation `hint` when one is registered, and the `requestId` the API
1021
+ logged the request under. Diagnostics go to stderr.
976
1022
 
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.
1023
+ In table mode, failures print `Error [CODE]: message` plus a `Hint:` line and,
1024
+ for an API error, a `Reference:` line. The bracketed code is stable across
1025
+ releases — quote it, and the reference, in support threads.
979
1026
 
980
1027
  Exit codes are a branchable taxonomy so a script can tell failure classes apart
981
1028
  without parsing text: