@farthershore/cli 0.37.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,60 @@ 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.
22
+
23
+ ## [0.38.0] - 2026-10-14
24
+
25
+ ### Changed
26
+
27
+ - **Breaking:** `validate` runs the server check by default; `--business` is
28
+ no longer required. It finds the business from `--business`, then
29
+ `FARTHERSHORE_BUSINESS` or the directory link (`farthershore link`, with its
30
+ environment), then the repository's `origin` remote matched against each
31
+ business's connected repository. When the server check can't run
32
+ (`--local-only`, not logged in, an expired login, or no business found) the
33
+ local build and determinism check still run and the output says the server
34
+ check was skipped, why, and how to turn it on
35
+ (`data.serverCheck.checked: "skipped"`). Only the compiled business
36
+ definition and `docs/` files are sent; `business/` source never leaves the
37
+ machine, and `--local-only` sends nothing. A one-line notice is printed the
38
+ first time a server check runs.
39
+ - **Breaking:** `validate` reports a **Business SDK** section and a **Docs**
40
+ section, laid out like the pull request comments, with one issue shape
41
+ (`{ code, message, file?, line?, column?, path? }`). JSON output carries
42
+ `businessSdk` and `docs`, each with `issues`, `checked` (`local`, `server`
43
+ or `skipped`) and a `reason` when skipped: in `data` on success, in
44
+ `error.details` on failure. Any problem in either section exits 2,
45
+ non-determinism included; a build that cannot run at all still exits 1.
46
+ - The "Not authenticated" error carries the code `AUTH_REQUIRED`.
47
+ - `promo-code update` sends only the flags you pass; omitted terms (cap,
48
+ expiry, plans, discount) are kept. It no longer requires the full spec
49
+ (`--kind`, `--duration-months`) for a partial edit.
50
+
51
+ ### Added
52
+
53
+ - `validate` checks `docs/` on the server: it sends `docs/_index.yaml` and
54
+ every `docs/**/*.mdx` (the same set the pull request check reads) and lists
55
+ the result under **Docs**. A broken `business/` program doesn't stop the
56
+ docs check. Docs-only problems exit 2 with `DOCS_VALIDATION_FAILED`; no
57
+ `docs/` folder reports Docs as skipped. Requests over 500 files, 1 MB per
58
+ file or 10 MB in total are reported locally (`DOCS_TOO_MANY_FILES`,
59
+ `DOCS_FILE_TOO_LARGE`, `DOCS_TOO_LARGE`) and not sent. A busy check is
60
+ retried after `Retry-After`, then reported as `DOCS_CHECK_BUSY` (exit 5).
8
61
 
9
62
  ## [0.37.0] - 2026-10-14
10
63
 
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.37.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.37.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.37.0 farthershore --help
29
+ npx -p @farthershore/cli@0.39.0 farthershore --help
30
30
  ```
31
31
 
32
32
  ## Authentication
@@ -89,7 +89,7 @@ cd weather-api
89
89
  # ...author business/ with @farthershore/business...
90
90
 
91
91
  # 3. Validate the same way the PR check will, before pushing
92
- farthershore validate --business weather-api
92
+ farthershore validate
93
93
 
94
94
  # 4. Push — the GitHub bot validates and records apply state
95
95
  git push --set-upstream origin feature/pricing
@@ -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
@@ -168,14 +181,14 @@ anchors. Paths come from the published docs index, not your working directory.
168
181
 
169
182
  ```bash
170
183
  farthershore docs ls --format json
171
- farthershore docs ls backend-sdk --format json
172
- farthershore docs tree backend-sdk --format json
173
- farthershore docs ls backend-sdk/connect-your-application --format json
174
- farthershore docs read backend-sdk/connect-your-application/metering --format json
175
- farthershore docs ls backend-sdk/connect-your-application/metering --format json
184
+ farthershore docs ls sdks --format json
185
+ farthershore docs tree sdks --format json
186
+ farthershore docs ls sdks/connect-your-application --format json
187
+ farthershore docs read sdks/connect-your-application/metering --format json
188
+ farthershore docs ls sdks/connect-your-application/metering --format json
176
189
  farthershore docs read backend/metering --section "choose-the-correct-metering-channel" --format json
177
- farthershore docs search "runtime token" --collection backend-sdk --limit 10 --format json
178
- farthershore docs collection backend-sdk --format json
190
+ farthershore docs search "runtime token" --collection sdks --limit 10 --format json
191
+ farthershore docs collection sdks --format json
179
192
  ```
180
193
 
181
194
  Use an anchor returned by `docs ls <page>` for `--section`. `read` also accepts the canonical slug or an
@@ -235,15 +248,46 @@ farthershore build --format json
235
248
  ### `farthershore validate`
236
249
 
237
250
  Run the same verdict the GitHub `farthershore/validate` PR check produces, before
238
- you push. It builds the manifest twice and compares the IR hash (the determinism
239
- check the build runner enforces), then — when you pass `--business` — submits the
240
- IR for a server verdict that returns compile diagnostics, the semantic diff, and
241
- an economic-change verdict. Validation never accepts or publishes business
242
- state, so it is safe to repeat.
251
+ you push. It builds `business/` on your machine twice and checks that both
252
+ builds match (the determinism check the PR check enforces). It then sends the
253
+ compiled business definition and your docs to the server, which checks them
254
+ with the newest checks and returns the PR check's verdict: problems, the change
255
+ summary, and whether the change is economic. Validation never accepts or
256
+ publishes anything, so it is safe to repeat.
257
+
258
+ What leaves your machine: only the compiled business definition (the output
259
+ of the local build) and your docs files (`docs/_index.yaml` and the `.mdx`
260
+ pages under `docs/`). Your `business/` source code never leaves it.
261
+ `--local-only` sends nothing. Without a `docs/` folder, nothing is sent for
262
+ docs. Docs over the size the check accepts (500 files, 1,000,000 bytes per file,
263
+ 10,000,000 bytes in all) are reported as a Docs problem without being sent.
264
+
265
+ The server check runs by default against this repo's business: `--business`,
266
+ else `FARTHERSHORE_BUSINESS`, else the directory link (`farthershore link`),
267
+ else the business connected to the repo's GitHub `origin` remote. When none of
268
+ those resolves, or you are not logged in, the local checks still run and the
269
+ output says the server check was skipped and how to turn it on.
270
+
271
+ The output has the PR check's two sections, **Business SDK** and **Docs**,
272
+ each listing problems the way its PR comment does. Every problem has the same
273
+ fields as the comment's JSON: `code`, `message`, and where known `file`,
274
+ `line`, `column` and `path` (the location in the business definition). With
275
+ `--format json` they are in `data.businessSdk` / `data.docs` (or
276
+ `error.details.businessSdk` / `error.details.docs` when there are problems),
277
+ each `{ issues, checked }`, where `checked` is `local`, `server` or `skipped`.
278
+ Any problem in either section exits 2, whether the local build or the server
279
+ found it.
280
+
281
+ The docs check can also return warnings and info notes. They never fail
282
+ `farthershore validate`: the Docs section lists them after the problems,
283
+ labelled `Warning:` or `Info:`, and a run with only notes exits 0. In JSON they
284
+ are in the same `issues` list, after the problems, each with a `severity` of
285
+ `warning` or `info`; an issue without a `severity` is a problem. A build that could not run at all (for example, `business/`
286
+ dependencies not installed) exits 1.
243
287
 
244
288
  ```bash
245
- farthershore validate # local build + determinism only
246
- farthershore validate --business weather-api
289
+ farthershore validate # local build + server check
290
+ farthershore validate --business weather-api # check against a named business
247
291
  farthershore validate --local-only --format json
248
292
  ```
249
293
 
@@ -353,7 +397,7 @@ Manage preview/production environments. Production is the default scope when
353
397
  ```bash
354
398
  farthershore env list weather-api --format json
355
399
  farthershore env list weather-api --filter branch=env/preview --sort createdAt:desc --search preview --format json
356
- farthershore env create weather-api --name preview --branch env/preview --format json
400
+ farthershore env create weather-api --branch env/preview --format json
357
401
  farthershore env delete weather-api preview --yes --format json
358
402
  ```
359
403
 
@@ -631,15 +675,28 @@ compiled integration that references it.
631
675
  farthershore variables list weather-api --format json
632
676
  printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
633
677
  SENTRY_AUTH_TOKEN --format json
678
+ printf '%s' "$PROVIDER_SECRET" | farthershore variables set weather-api \
679
+ PROVIDER_SECRET --production-only --format json
634
680
  printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
635
681
  FS_PUBLIC_POSTHOG_KEY --format json
636
682
  farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
637
683
  farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
638
684
  ```
639
685
 
640
- There is no builder-managed public-variable surface and values are never
641
- revealed after write. Rotation preserves the delivery phase; changing phase
642
- 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.
643
700
 
644
701
  ### `farthershore backend`
645
702
 
@@ -678,7 +735,7 @@ export async function POST(request: Request) {
678
735
  const ctx = await fs.verifyRequest({
679
736
  method: request.method,
680
737
  path: url.pathname,
681
- query: url.search,
738
+ query: url.search.slice(1), // the query after "?", exactly as signed
682
739
  headers: request.headers,
683
740
  body: new Uint8Array(body),
684
741
  });
@@ -725,8 +782,9 @@ records it under that type) so every handler branch can be exercised locally.
725
782
  id (the `webhook-id` header your endpoint received, also the `deliveryId` that
726
783
  `webhook test` / `webhook trigger` return): its status, attempts, last HTTP
727
784
  status and when the next attempt is due. A `failed` delivery with no next
728
- attempt (a test send) is final. Neither returns the event payload or your
729
- 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.
730
788
 
731
789
  For a receiver on your machine, `webhook listen` is the Stripe-CLI-style loop:
732
790
  it opens a Cloudflare quick tunnel to `--forward-to`, creates a temporary
@@ -772,18 +830,18 @@ Use `--all-plans` to clear plan scoping.
772
830
  Install or refresh the platform-verified skills bundle together. The platform
773
831
  pins this immutable release, and CI plus a daily repository check compare it to
774
832
  GitHub's latest stable release so the guidance cannot silently drift.
775
- This command requires `@farthershore/cli` 0.37.0 or newer.
833
+ This command requires `@farthershore/cli` 0.39.0 or newer.
776
834
 
777
835
  ```bash
778
836
  set -euo pipefail
779
837
  CLI_VERSION=$(farthershore --version)
780
- 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] > 37 || (+m[2] === 37 && +m[3] >= 0))) { console.error("Stop: CLI 0.37.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; } })'
781
839
  farthershore skills install --help
782
840
  farthershore skills install
783
841
  ```
784
842
 
785
843
  If either prerequisite fails, stop and ask the human to run
786
- `npm install -g @farthershore/cli@0.37.0`, then repeat the checks.
844
+ `npm install -g @farthershore/cli@0.39.0`, then repeat the checks.
787
845
  Do not install or upgrade global tooling autonomously.
788
846
 
789
847
  The Farther Shore CLI downloads the exact installer archive and verifies this
@@ -811,6 +869,7 @@ farthershore api 'businesses/{business}/environments' --paginate
811
869
  farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
812
870
  farthershore api 'management/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
813
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
814
873
  farthershore api 'builder/organizations/{org}/members' --include
815
874
  farthershore api /businesses --format json | jq '.[].id'
816
875
  ```
@@ -838,6 +897,22 @@ farthershore api /businesses --format json | jq '.[].id'
838
897
  `--max-pages <n>` (default 100) bounds it.
839
898
  - **`-i, --include`** prints the HTTP status and response headers first.
840
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.
841
916
 
842
917
  The body is printed as-is (pretty in a terminal, compact with `--format json`),
843
918
  never wrapped in the CLI envelope; there is no `--jq`, so pipe to `jq`. Errors
@@ -902,13 +977,14 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
902
977
 
903
978
  **Policy** (checked in the CLI process for every call, not in the script):
904
979
 
905
- | Call | Needs |
906
- | ------------------------------------------------------- | ----------------------------------------------------------- |
907
- | read | nothing |
908
- | write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
909
- | destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
910
- | preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
911
- | 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`) |
912
988
 
913
989
  One-time secrets (minted or rotated credentials) come back to the script as
914
990
  `{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
@@ -941,10 +1017,12 @@ isolated hosted runtime instead.
941
1017
  In `--format json` mode, every command prints a single canonical envelope to
942
1018
  stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failure,
943
1019
  where `error` carries a stable `code`, `message`, HTTP `status`, a `retryable`
944
- 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.
945
1022
 
946
- In table mode, failures print `Error [CODE]: message` plus a `Hint:` line. The
947
- 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.
948
1026
 
949
1027
  Exit codes are a branchable taxonomy so a script can tell failure classes apart
950
1028
  without parsing text: