@farthershore/cli 0.39.0 → 0.41.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 +67 -0
- package/README.md +46 -40
- package/dist/index.js +236 -246
- package/package.json +5 -4
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,73 @@ 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.41.0] - 2026-11-09
|
|
8
|
+
|
|
9
|
+
- **Breaking:** `business rollback` now sends `publishId` and reads
|
|
10
|
+
`rollbackPublishId` from the response; the publish receipt names the same
|
|
11
|
+
id `publishId`. Requires the matching platform release.
|
|
12
|
+
|
|
13
|
+
## [0.40.0] - 2026-11-06
|
|
14
|
+
|
|
15
|
+
- **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.
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- `code search` returns docs guides alongside matching methods. JSON guides
|
|
20
|
+
include the catalog methods named by each matching docs chunk (with an
|
|
21
|
+
excerpt fallback for older docs hosts). `--no-guides` or `--namespace`
|
|
22
|
+
searches methods only; `--stage` selects stage docs. If docs search is
|
|
23
|
+
unavailable, method search still works and JSON reports
|
|
24
|
+
`guidesUnavailable: true`. Guide search requires the matching platform release.
|
|
25
|
+
- `code search --code <js>` and `--code-file <file>` run a JavaScript filter
|
|
26
|
+
over a frozen `catalog`, with no platform access. Query words are optional
|
|
27
|
+
when using either flag; combining query words with a script, or both script
|
|
28
|
+
flags, fails with `INVALID_ARGUMENT`.
|
|
29
|
+
- `code describe` accepts 1–25 method paths, operation keys or `docs:<page>`
|
|
30
|
+
refs, and `--stage` selects stage docs. Docs refs return the full page's
|
|
31
|
+
Markdown. JSON for a single method is unchanged; multiple refs or a docs
|
|
32
|
+
ref return `{ methods, docs }`. Invalid page paths fail with
|
|
33
|
+
`DOCS_INVALID_PAGE`; more than 25 refs fail with `INVALID_ARGUMENT`.
|
|
34
|
+
Reading docs pages requires the matching platform release.
|
|
35
|
+
- `webhook event-types`, endpoint subscriptions, `webhook listen` and sample
|
|
36
|
+
sends support `customer.created`, `customer.deleted`,
|
|
37
|
+
`customer.member.added`, `customer.member.updated` and
|
|
38
|
+
`customer.member.removed`. Customer deletion includes test-persona cleanup
|
|
39
|
+
when it deletes the customer; starting a free subscription now emits
|
|
40
|
+
`subscription.created`. Requires the matching platform release.
|
|
41
|
+
|
|
42
|
+
### Changed
|
|
43
|
+
|
|
44
|
+
- **Breaking:** `docs search` uses semantic docs search by default, returning
|
|
45
|
+
page paths, titles, URLs and snippets. Use `--literal` for the previous
|
|
46
|
+
literal search; `--collection` implies literal search. If semantic search is
|
|
47
|
+
unavailable, it falls back to literal search with a notice and
|
|
48
|
+
`searchUnavailable: true` in JSON. Semantic search requires the matching
|
|
49
|
+
platform release.
|
|
50
|
+
- **Breaking:** `stripe disconnect` no longer accepts `--delete-account`.
|
|
51
|
+
It only removes a business's Stripe override. Close Stripe accounts from
|
|
52
|
+
the dashboard after a fresh sign-in check. Requires the matching platform
|
|
53
|
+
release.
|
|
54
|
+
- **Breaking:** customer context tokens are always enabled; remove
|
|
55
|
+
`customerContext.contextTokens` from Business SDK programs. Contract output
|
|
56
|
+
no longer includes `customer_context.context_tokens`. Requires the matching
|
|
57
|
+
platform release.
|
|
58
|
+
|
|
59
|
+
### Fixed
|
|
60
|
+
|
|
61
|
+
- **Breaking:** `webhook listen` uses only the bundled tunnel helper and no
|
|
62
|
+
longer runs an executable from `PATH`. A missing or unsupported helper
|
|
63
|
+
fails with `TUNNEL_BINARY_UNAVAILABLE`; reinstall the CLI with optional
|
|
64
|
+
dependencies enabled on a supported platform.
|
|
65
|
+
- **Breaking:** `backend scaffold` refuses a root `.gitignore` that is a
|
|
66
|
+
symbolic link, a hard-linked file or a special file
|
|
67
|
+
(`BACKEND_SCAFFOLD_GITIGNORE_UNSAFE`), and keeps its write bound to the
|
|
68
|
+
validated file.
|
|
69
|
+
- `frontend dev` / `frontend preview` with `--live --persona` wait for lease
|
|
70
|
+
renewal scheduling before reporting readiness. Shutdown waits for pending
|
|
71
|
+
renewal work and attempts to revoke the current lease even if cancelling
|
|
72
|
+
renewal fails; cancellation failures are reported after cleanup.
|
|
73
|
+
|
|
7
74
|
## [0.39.0] - 2026-10-28
|
|
8
75
|
|
|
9
76
|
### 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.41.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.41.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.41.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
|
|
@@ -351,8 +349,11 @@ farthershore business update weather-api \
|
|
|
351
349
|
|
|
352
350
|
`business publish` enforces the same go-live gates as the dashboard and returns
|
|
353
351
|
stable remediation errors when a prerequisite is missing.
|
|
354
|
-
`business rollback` enqueues a rollback of
|
|
355
|
-
and requires the exact `business:rollback` permission.
|
|
352
|
+
`business rollback` takes a `publishId` and enqueues a rollback of that prior publish
|
|
353
|
+
and requires the exact `business:rollback` permission. The async management publish receipt returns
|
|
354
|
+
`publishId`; its publish-status response returns the same value as
|
|
355
|
+
`execution.id`. Pass that value unchanged. The rollback receipt returns
|
|
356
|
+
`rollbackPublishId` for the newly queued rollback.
|
|
356
357
|
|
|
357
358
|
`business rbac` reads a business's Managed-RBAC state — the platform-owned
|
|
358
359
|
`rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
|
|
@@ -404,14 +405,14 @@ farthershore env delete weather-api preview --yes --format json
|
|
|
404
405
|
### `farthershore organization`
|
|
405
406
|
|
|
406
407
|
Manage organization members and the exact platform-permission roles assigned
|
|
407
|
-
to them. Built-in and custom roles use the same list contract.
|
|
408
|
+
to them. Built-in and custom roles use the same list contract. Deletion, ownership
|
|
409
|
+
transfer, and removing or demoting an owner require a person in the dashboard
|
|
410
|
+
after fresh sign-in and typed-name confirmation.
|
|
408
411
|
|
|
409
412
|
```bash
|
|
410
413
|
farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
|
|
411
414
|
farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
|
|
412
415
|
|
|
413
|
-
# Primary owner only; hands ultimate authority to another existing member.
|
|
414
|
-
farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
|
|
415
416
|
```
|
|
416
417
|
|
|
417
418
|
Selecting the default organization is a local credential concern, not an API
|
|
@@ -457,21 +458,15 @@ If a create or update times out, run `token list --org` before trying again.
|
|
|
457
458
|
|
|
458
459
|
### `farthershore stripe`
|
|
459
460
|
|
|
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`.
|
|
461
|
+
Read the Stripe account a business bills through. Reading status requires a
|
|
462
|
+
signed-in owner session. Connecting, disconnecting, closing or changing payout
|
|
463
|
+
settings requires a person in the dashboard after fresh sign-in and typed-name
|
|
464
|
+
confirmation. The CLI does not perform these actions.
|
|
466
465
|
|
|
467
466
|
```bash
|
|
468
467
|
farthershore stripe status weather-api --format json
|
|
469
|
-
farthershore stripe disconnect weather-api --yes --format json
|
|
470
468
|
```
|
|
471
469
|
|
|
472
|
-
`stripe disconnect` is refused while any subscription on the business is still
|
|
473
|
-
money-bearing.
|
|
474
|
-
|
|
475
470
|
### `farthershore service-account`
|
|
476
471
|
|
|
477
472
|
Manage service accounts owned by a subscriber organization. This is a separate
|
|
@@ -800,8 +795,10 @@ farthershore webhook listen weather-api --forward-to localhost:3000/webhooks \
|
|
|
800
795
|
--events subscription.created,payment.failed --format json
|
|
801
796
|
```
|
|
802
797
|
|
|
803
|
-
`listen` needs
|
|
804
|
-
|
|
798
|
+
`listen` needs the bundled tunnel helper, installed as an optional CLI
|
|
799
|
+
dependency. If it is missing, reinstall
|
|
800
|
+
the CLI with optional dependencies enabled; the listener does not search your
|
|
801
|
+
repository or PATH for an executable. A listener
|
|
805
802
|
killed hard leaves an
|
|
806
803
|
endpoint with a `*.trycloudflare.com` URL; `webhook delete --yes` removes it.
|
|
807
804
|
|
|
@@ -830,18 +827,18 @@ Use `--all-plans` to clear plan scoping.
|
|
|
830
827
|
Install or refresh the platform-verified skills bundle together. The platform
|
|
831
828
|
pins this immutable release, and CI plus a daily repository check compare it to
|
|
832
829
|
GitHub's latest stable release so the guidance cannot silently drift.
|
|
833
|
-
This command requires `@farthershore/cli` 0.
|
|
830
|
+
This command requires `@farthershore/cli` 0.41.0 or newer.
|
|
834
831
|
|
|
835
832
|
```bash
|
|
836
833
|
set -euo pipefail
|
|
837
834
|
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] >
|
|
835
|
+
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] > 41 || (+m[2] === 41 && +m[3] >= 0))) { console.error("Stop: CLI 0.41.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
|
|
839
836
|
farthershore skills install --help
|
|
840
837
|
farthershore skills install
|
|
841
838
|
```
|
|
842
839
|
|
|
843
840
|
If either prerequisite fails, stop and ask the human to run
|
|
844
|
-
`npm install -g @farthershore/cli@0.
|
|
841
|
+
`npm install -g @farthershore/cli@0.41.0`, then repeat the checks.
|
|
845
842
|
Do not install or upgrade global tooling autonomously.
|
|
846
843
|
|
|
847
844
|
The Farther Shore CLI downloads the exact installer archive and verifies this
|
|
@@ -954,8 +951,8 @@ farthershore code run -e '
|
|
|
954
951
|
`--side-effect read|write`, `--namespace <ns>`. Each hit shows the path
|
|
955
952
|
(`fs.runtimeTokens.revoke`), a one-line summary and its flags (read/write,
|
|
956
953
|
destructive, one-time secret, preview, paginated).
|
|
957
|
-
- **`code describe <
|
|
958
|
-
`fs.runtimeTokens.revoke
|
|
954
|
+
- **`code describe <refs...>`** — accepts `runtimeTokens.revoke`,
|
|
955
|
+
`fs.runtimeTokens.revoke`, the opKey `runtime_token.revoke`, or `docs:<page>` (1–25 refs).
|
|
959
956
|
- **`code types [namespace]`** — a self-contained `.d.ts` for `fs`, generated
|
|
960
957
|
from the same tables `code run` enforces, with JSDoc from the operation
|
|
961
958
|
specs.
|
|
@@ -977,14 +974,14 @@ until, deadlineMs })`, `console`, `setTimeout` / `clearTimeout` and
|
|
|
977
974
|
|
|
978
975
|
**Policy** (checked in the CLI process for every call, not in the script):
|
|
979
976
|
|
|
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
|
-
|
|
|
977
|
+
| Call | Needs |
|
|
978
|
+
| ------------------------------------------------------- | ----------------------------------------------------------- |
|
|
979
|
+
| read | nothing |
|
|
980
|
+
| write | `--allow-writes` (else `CODE_MODE_WRITE_NOT_ALLOWED`) |
|
|
981
|
+
| destructive or one-time-secret write | `--allow-writes --yes` (else `CODE_MODE_APPROVAL_REQUIRED`) |
|
|
982
|
+
| preview (`{ dryRun: true }` on a method marked preview) | nothing — it changes nothing |
|
|
983
|
+
| managed-as-code (contract) write | always refused |
|
|
984
|
+
| human-only action | no client or code-mode method; use the dashboard |
|
|
988
985
|
|
|
989
986
|
One-time secrets (minted or rotated credentials) come back to the script as
|
|
990
987
|
`{ redacted: true, last4 }` unless you pass `--reveal-secrets`; a redacted
|
|
@@ -1072,3 +1069,12 @@ run in CI.
|
|
|
1072
1069
|
## License
|
|
1073
1070
|
|
|
1074
1071
|
MIT
|
|
1072
|
+
|
|
1073
|
+
Code discovery includes docs guides: `farthershore code search runtime token`.
|
|
1074
|
+
Read one with `farthershore code describe docs:agents/overview`; describe accepts
|
|
1075
|
+
1–25 method paths, opKeys, or docs refs. Use `--no-guides` or `--namespace` to
|
|
1076
|
+
search methods only. Use `--stage` to select stage docs; production is the default.
|
|
1077
|
+
For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.sideEffect === "read").map(m => m.method)'`
|
|
1078
|
+
or `--code-file script.js`. Filters have a frozen catalog and no platform access.
|
|
1079
|
+
`farthershore docs search "runtime token"` uses docs search and falls back to
|
|
1080
|
+
literal text when unavailable. `--literal` or `--collection` forces literal search.
|