@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 +61 -0
- package/README.md +41 -38
- package/dist/index.js +231 -235
- package/package.json +6 -5
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
160
|
-
|
|
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
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
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
|
|
804
|
-
|
|
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.
|
|
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] >
|
|
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.
|
|
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 <
|
|
958
|
-
`fs.runtimeTokens.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
|
-
|
|
|
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.
|