@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 +15 -1
- package/README.md +70 -23
- package/dist/index.js +475 -214
- package/package.json +5 -5
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
|
-
## [
|
|
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.
|
|
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.
|
|
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.
|
|
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 --
|
|
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
|
-
|
|
672
|
-
|
|
673
|
-
|
|
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.
|
|
760
|
-
|
|
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.
|
|
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] >
|
|
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.
|
|
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,
|
|
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
|
|
978
|
-
|
|
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:
|