@farthershore/cli 0.41.0 → 0.43.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
@@ -1,9 +1,33 @@
1
1
  # Changelog — @farthershore/cli
2
2
 
3
+ ## [0.43.0] - 2026-11-18
4
+
5
+ - Global npm installs on macOS and Linux silently check npm latest hourly after successful commands. Upgrade-required responses update and re-run once (not when the command read stdin). pnpm and Windows installs are not updated automatically.
6
+ - Add `farthershore update`, `FARTHERSHORE_NO_UPDATE=1`, and `autoUpdate: false` configuration (a config file with only `autoUpdate` is valid). CI and unowned installs skip automatic updates.
7
+
8
+ > A CLI published to `latest` must work against the Core running in
9
+ > production at publish time. A CLI that needs an unreleased Core is
10
+ > published under the `next` dist-tag and promoted to `latest` after the
11
+ > platform release.
12
+
13
+ ## [0.42.0] - 2026-11-18
14
+
15
+ - Use `/agent/v1/whoami` for login and credential validation after retirement of `/management`. Core now requires CLI 0.42.0 or newer.
16
+
3
17
  All notable changes to the `farthershore` CLI are documented here. The CLI
4
18
  versions independently from the SDKs. Pre-1.0: minor versions may include
5
19
  breaking changes. Releases before 0.35.0 are recorded only in the git history.
6
20
 
21
+ ## [Unreleased]
22
+
23
+ - **Breaking:** Removed `business rollback` and the retired BusinessApply/Rollback workflow filters. Recover a Business contract through a reviewed repository fix and a new release.
24
+
25
+ - Protect configuration lock recovery and release with owner identity; identify reused processes and explain safe manual recovery when ownership cannot be confirmed.
26
+
27
+ - Serialize concurrent link and notice updates; warn when older directory links need explicit relinking with `farthershore link <business>`.
28
+
29
+ - Write configuration atomically, reject corrupt configuration, and scope directory links and saved organization selection to the API URL.
30
+
7
31
  ## [0.41.0] - 2026-11-09
8
32
 
9
33
  - **Breaking:** `business rollback` now sends `publishId` and reads
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.41.0`.** Pre-1.0 — the command surface is stable but may still
6
+ **Status: `0.43.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.41.0
23
+ npm install -g @farthershore/cli@0.43.0
24
24
  ```
25
25
 
26
26
  Or run it directly with npx:
27
27
 
28
28
  ```bash
29
- npx -p @farthershore/cli@0.41.0 farthershore --help
29
+ npx -p @farthershore/cli@0.43.0 farthershore --help
30
30
  ```
31
31
 
32
32
  ## Authentication
@@ -135,6 +135,16 @@ write commands cover **operational** state that lives outside the manifest
135
135
  | `FS_CLI_CHANNEL` | `stage` enables stage-channel commands for one invocation (see below) |
136
136
  | `FS_CLI_STAGE_HOSTS` | Extra hosts (comma separated) the stage-channel gate treats as stage |
137
137
 
138
+ Directory links (business, organization, and environment) and the saved default
139
+ organization apply only to the API base URL where they were selected. Switching
140
+ `--api-url` or `FARTHERSHORE_API_URL` does not reuse another API's context. Existing
141
+ unscoped directory links must be recreated with `farthershore link`; select a
142
+ default organization again with `farthershore auth organization use`.
143
+
144
+ Configuration writes use an atomic replacement. If an existing
145
+ `~/.farthershore/config.json` is corrupt or lacks a valid API URL, commands fail
146
+ with a repair message; restore or repair the file before continuing.
147
+
138
148
  ## Stage-channel commands
139
149
 
140
150
  A few operations exist only to service stage. `farthershore business delete` is
@@ -163,7 +173,7 @@ Business deletion for teardown uses only the stage command’s raw request.
163
173
 
164
174
  The raw `api` command applies both gates too: a request that the platform
165
175
  serves as `business delete` (`-X DELETE /businesses/<id>`, or its
166
- `/management/...` and `/agent/v1/...` forms) is refused with
176
+ `/agent/v1/...` forms) is refused with
167
177
  `COMMAND_NOT_AVAILABLE_IN_PRODUCTION` outside the stage channel and against a
168
178
  non-stage api-url, before any request and whatever `--yes` says.
169
179
 
@@ -309,7 +319,6 @@ farthershore business create weather-api \
309
319
  --format json
310
320
 
311
321
  farthershore business publish weather-api --format json
312
- farthershore business rollback weather-api wfe_previous --reason "bad release" --yes --format json
313
322
  ```
314
323
 
315
324
  Deleting a business is **stage only** — the command is not registered in the
@@ -349,11 +358,9 @@ farthershore business update weather-api \
349
358
 
350
359
  `business publish` enforces the same go-live gates as the dashboard and returns
351
360
  stable remediation errors when a prerequisite is missing.
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.
361
+ Recover a Business contract by correcting or reverting its program in Git,
362
+ validating it in preview, and publishing a new release. Use `business status`
363
+ and Apply Timeline to verify the expected release is serving.
357
364
 
358
365
  `business rbac` reads a business's Managed-RBAC state — the platform-owned
359
366
  `rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
@@ -459,9 +466,10 @@ If a create or update times out, run `token list --org` before trying again.
459
466
  ### `farthershore stripe`
460
467
 
461
468
  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.
469
+ signed-in owner session. Connecting Stripe, finishing its setup, opening payout
470
+ settings, disconnecting and closing require a person in the dashboard after a
471
+ fresh sign-in; disconnecting and closing also ask for the name to be typed. The
472
+ CLI does not perform these actions.
465
473
 
466
474
  ```bash
467
475
  farthershore stripe status weather-api --format json
@@ -543,6 +551,9 @@ farthershore plan list weather-api # table (default in TTY)
543
551
  farthershore plan list weather-api --format json
544
552
  ```
545
553
 
554
+ Plan listings show recurring fees, trial days, and status. The v2 listing no longer
555
+ includes plan kind, a free flag, or a monthly spend cap.
556
+
546
557
  ### `farthershore frontend`
547
558
 
548
559
  Managed Frontend Hosting status, rollback, and a local preview. Builds are
@@ -683,7 +694,14 @@ public `FS_PUBLIC_*` values and secret metadata. Business-wide variables are
683
694
  inherited by previews unless an environment override exists. Inherited secrets
684
695
  require a verified repository pusher with write access; fork previews and
685
696
  previews without verified identity cannot use them. Rotation updates the source
686
- value without copying secrets into previews.
697
+ value without copying secrets into previews. A preview stops using inherited
698
+ secrets within 15 seconds of GitHub reporting that the pusher was removed or their
699
+ access changed, for example a lowered collaborator permission or a team losing
700
+ the repository. Write access is also checked again every 15 minutes, so a change
701
+ GitHub does not report stops them within about 20 minutes.
702
+
703
+ Revoke, rotate and delete take effect for live requests within 15 seconds of
704
+ being acknowledged; until then a request may still use the previous value.
687
705
 
688
706
  Use `--production-only` when creating a business-wide secret to exclude it from
689
707
  previews. The flag cannot be used for public variables or with a preview
@@ -827,19 +845,23 @@ Use `--all-plans` to clear plan scoping.
827
845
  Install or refresh the platform-verified skills bundle together. The platform
828
846
  pins this immutable release, and CI plus a daily repository check compare it to
829
847
  GitHub's latest stable release so the guidance cannot silently drift.
830
- This command requires `@farthershore/cli` 0.41.0 or newer.
848
+
849
+ The v4.0.0 bundle replaces five prior workflow names with the six current
850
+ workflows. After a successful install, exact Farther Shore-owned retired
851
+ entries are moved to recoverable `.farthershore-retired-skills-*` backups only
852
+ in directories containing the complete verified new bundle. Incomplete installs,
853
+ custom and unrecognized skills are left in place.
831
854
 
832
855
  ```bash
833
856
  set -euo pipefail
834
- CLI_VERSION=$(farthershore --version)
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; } })'
836
857
  farthershore skills install --help
837
858
  farthershore skills install
838
859
  ```
839
860
 
840
- If either prerequisite fails, stop and ask the human to run
841
- `npm install -g @farthershore/cli@0.41.0`, then repeat the checks.
842
- Do not install or upgrade global tooling autonomously.
861
+ If the platform-owned skills installer is unavailable, stop and ask the human to run
862
+ `npm install -g @farthershore/cli@0.43.0`, then repeat the installer help check.
863
+ The CLI keeps itself current (see Staying up to date); do not otherwise install
864
+ or upgrade global tooling autonomously.
843
865
 
844
866
  The Farther Shore CLI downloads the exact installer archive and verifies this
845
867
  SHA-512 before it extracts or executes any installer code.
@@ -864,7 +886,7 @@ yet. Every endpoint is described in the platform's OpenAPI document
864
886
  farthershore api /businesses
865
887
  farthershore api 'businesses/{business}/environments' --paginate
866
888
  farthershore api -X PATCH 'businesses/{business}' -f displayName='Weather API'
867
- farthershore api 'management/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
889
+ farthershore api 'agent/v1/businesses/{business}/backends' -f name=api -f originUrl=https://api.example.com -F isDefault=true --dry-run
868
890
  farthershore api -X POST 'businesses/{business}/promo-codes' --input promo.json
869
891
  farthershore api -X DELETE 'businesses/{business}/environments/{env}' --env preview-1 --yes
870
892
  farthershore api 'builder/organizations/{org}/members' --include
@@ -1074,7 +1096,40 @@ Code discovery includes docs guides: `farthershore code search runtime token`.
1074
1096
  Read one with `farthershore code describe docs:agents/overview`; describe accepts
1075
1097
  1–25 method paths, opKeys, or docs refs. Use `--no-guides` or `--namespace` to
1076
1098
  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)'`
1099
+ For exact catalog filtering, use `farthershore code search --code 'return catalog.filter(m => m.required.includes("tokenId")).map(m => m.method)'`
1078
1100
  or `--code-file script.js`. Filters have a frozen catalog and no platform access.
1101
+ Entries include `input` and `output` as TypeScript text (`input` is null for
1102
+ methods without arguments), and `required` lists top-level required field names.
1079
1103
  `farthershore docs search "runtime token"` uses docs search and falls back to
1080
1104
  literal text when unavailable. `--literal` or `--collection` forces literal search.
1105
+
1106
+ Rename a usage unit for display without changing reporting keys or balances:
1107
+
1108
+ ```sh
1109
+ farthershore business update <business> --usage-unit-label "Requests"
1110
+ farthershore business update <business> --clear-usage-unit-label
1111
+ ```
1112
+
1113
+ The same operation is available to MCP as `fs.businesses.brand.update` with
1114
+ `body.usageUnitLabel: { unitKey: "credits:tokens", label: "Requests" }`.
1115
+ Use `label: null` to restore the default.
1116
+
1117
+ ## Staying up to date
1118
+
1119
+ Global npm installs on macOS and Linux (including a custom npm `prefix` set
1120
+ in `~/.npmrc`) update automatically to npm `latest` in
1121
+ the background after a successful command, at most once an hour. A command
1122
+ refused because the CLI is too old updates immediately and re-runs once; a
1123
+ command that read standard input is not re-run, so run it again yourself.
1124
+ Updates only move forward, use the official npm registry, and never change
1125
+ command stdout. pnpm installs, Windows, CI, source checkouts, project
1126
+ dependencies, and `npx` runs are not updated automatically; update those with
1127
+ the tool you used to install the CLI.
1128
+
1129
+ To opt out, set `FARTHERSHORE_NO_UPDATE=1` or add `"autoUpdate": false` to
1130
+ `~/.farthershore/config.json`. A config file containing only
1131
+ `{"autoUpdate": false}` is valid. If that file exists but cannot be read,
1132
+ automatic updates stay off. Automation should set the environment variable.
1133
+ Run `farthershore update` to check and update explicitly, ignoring the hourly
1134
+ window and opt-outs (including CI); `--format json` reports
1135
+ `{ from, to, updated }`.