@farthershore/cli 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to the `farthershore` CLI are documented here. The CLI
 versions independently from the SDKs. Pre-1.0: minor versions may include
 breaking changes. Releases before 0.35.0 are recorded only in the git history.
 
+## [Unreleased]
+
+## [0.38.0] - 2026-10-14
+
+### Changed
+
+- **Breaking:** `validate` runs the server check by default; `--business` is
+  no longer required. It finds the business from `--business`, then
+  `FARTHERSHORE_BUSINESS` or the directory link (`farthershore link`, with its
+  environment), then the repository's `origin` remote matched against each
+  business's connected repository. When the server check can't run
+  (`--local-only`, not logged in, an expired login, or no business found) the
+  local build and determinism check still run and the output says the server
+  check was skipped, why, and how to turn it on
+  (`data.serverCheck.checked: "skipped"`). Only the compiled business
+  definition and `docs/` files are sent; `business/` source never leaves the
+  machine, and `--local-only` sends nothing. A one-line notice is printed the
+  first time a server check runs.
+- **Breaking:** `validate` reports a **Business SDK** section and a **Docs**
+  section, laid out like the pull request comments, with one issue shape
+  (`{ code, message, file?, line?, column?, path? }`). JSON output carries
+  `businessSdk` and `docs`, each with `issues`, `checked` (`local`, `server`
+  or `skipped`) and a `reason` when skipped: in `data` on success, in
+  `error.details` on failure. Any problem in either section exits 2,
+  non-determinism included; a build that cannot run at all still exits 1.
+- The "Not authenticated" error carries the code `AUTH_REQUIRED`.
+- `promo-code update` sends only the flags you pass; omitted terms (cap,
+  expiry, plans, discount) are kept. It no longer requires the full spec
+  (`--kind`, `--duration-months`) for a partial edit.
+
+### Added
+
+- `validate` checks `docs/` on the server: it sends `docs/_index.yaml` and
+  every `docs/**/*.mdx` (the same set the pull request check reads) and lists
+  the result under **Docs**. A broken `business/` program doesn't stop the
+  docs check. Docs-only problems exit 2 with `DOCS_VALIDATION_FAILED`; no
+  `docs/` folder reports Docs as skipped. Requests over 500 files, 1 MB per
+  file or 10 MB in total are reported locally (`DOCS_TOO_MANY_FILES`,
+  `DOCS_FILE_TOO_LARGE`, `DOCS_TOO_LARGE`) and not sent. A busy check is
+  retried after `Retry-After`, then reported as `DOCS_CHECK_BUSY` (exit 5).
+
+## [0.37.0] - 2026-10-14
+
+### Changed
+
+- `business status` reports `serving` (`status`, `coherent`, `message`) in
+  place of `edgeCoherence` (no generations, epochs or digests), and
+  `latestDeployment.publishStatus` in place of `edgePublishStatus`.
+  `business routes` lists each route once (no compiled row id);
+  `business contract` and `business config-attempts` print the closed public
+  shapes (no raw proposal text or payload). `validate --business` no longer
+  echoes the server's spec hash; a failure's `irHash` is the locally built IR's.
+- `auth whoami` no longer prints a maker token's `authVersion` or a dashboard
+  session's identity-provider user id.
+- `agents`, `bulletin`, `automation`, `knowledge`, `resource-count`,
+  `denial`, `dependents` and `workflow-control` print the closed public
+  shapes: an agent run names a failure by code with a fixed message and
+  carries no trace object key; a denial carries no internal decision or ledger
+  ids; a rollback preview reports `currentCommitSha`.
+- The webhook commands print only the public webhook fields. Every endpoint
+  result carries the same fields (`failCount`, `disabledAt` and `updatedAt`
+  included); the signing secret appears only in `webhook create`,
+  `webhook rotate` and `webhook listen --print-secret`. A delivery's
+  `status` is `pending`, `success`, `failed` or `dead`, and `webhook test` /
+  `webhook trigger` results (and their `WEBHOOK_DELIVERY_FAILED` /
+  `WEBHOOK_REDIRECTED` errors) carry `deliveryId`, null when the attempt
+  could not be recorded.
+- New `webhook delivery <business> <webhookId> <deliveryId>` shows one
+  delivery's status, attempts and HTTP status.
+- `analytics log` events carry `request` (path, status code, subscriber, deny
+  code, gateway / backend timing) instead of the raw archived `payload`.
+  `usage summary` reports `activeApiKeys` (was `activeRuntimeKeys`) and no
+  business id. `stripe status` no longer prints the Stripe account id, and
+  `source` reads `business` | `organization`. `tax-settings show|update` print
+  `{ status, defaults: { taxBehavior, taxCode }, headOffice, missingFields }`
+  instead of the payment provider's settings object. `plan list` reads the
+  plan's `kind` and `isActive`.
+- `variables` mutations and `variables status` print the public operation
+  (no `mutationId`, `state` or `result`; `impact` is integrations and
+  subscriber count; a failed attempt shows fixed copy; `generation` is
+  `version`, also on `variables list`). `frontend status`
+  prints `activeReleaseId` and each build's `releaseId`; `frontend rollback`
+  prints the release now serving with its `environmentId`.
+
+- `agreements`, `promo-code` and `persona` print the closed public shapes:
+  no payment-provider ids on promo codes, no plan-version, user or membership
+  ids on personas, and `agreements pins` names the plan by key and version.
+- `apply-timeline list` / `inspect` print the public entry: no build id, IR
+  hash or internal trigger; apply phases are `publish` and `billing`, and a
+  failed platform step reads as a code plus the id to quote to support.
+  `proposal create|preview|list|get` print the public ChangeSet (no rollback
+  plan, correlation id or simulation fingerprint; `resetReason` replaces
+  `failureReason`), and `proposal create --dry-run` prints what it would record.
+  An unknown `--env` name on the `apply-timeline` and `proposal` commands now
+  fails with `ENVIRONMENT_NOT_FOUND` (apply-timeline used to show production
+  entries).
+- `env create` prints the full environment (now including `portalHostname`)
+  with `created` and `branchCreated`, and says when the environment already
+  existed. A failed `env delete` reports which cleanup steps did not finish
+  (`runtime`, `docs`, `branch`) instead of the underlying error text.
+- `backend list` prints each backend's `status` straight from the server; the
+  backend and runtime-token commands print only the public fields (a backend's
+  internal origin host and raw provisioning / readiness state are no longer
+  returned). `backend tokens create` / `rotate` results carry `envVar` and the
+  one-time `token` as the server returns them.
+- `business show`, `business list` and the other business reads print only the
+  public business fields. Internal platform state the server used to include
+  (release and sync bookkeeping, accepted specs, frontend activation details,
+  …) is no longer returned.
+
 ## [0.36.0] - 2026-10-13
 
 ### Changed

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.36.0`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.38.0`.** Pre-1.0 — the command surface is stable but may still
 change between minor versions. Pin an exact version in CI.
 
 FartherShore lets you define a software business as code, then sells, meters,
@@ -20,13 +20,13 @@ takes `--format json` for non-interactive scripting.
 ## Install
 
 ```bash
-npm install -g @farthershore/cli@0.36.0
+npm install -g @farthershore/cli@0.38.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.36.0 farthershore --help
+npx -p @farthershore/cli@0.38.0 farthershore --help
 ```
 
 ## Authentication
@@ -89,7 +89,7 @@ cd weather-api
 # ...author business/ with @farthershore/business...
 
 # 3. Validate the same way the PR check will, before pushing
-farthershore validate --business weather-api
+farthershore validate
 
 # 4. Push — the GitHub bot validates and records apply state
 git push --set-upstream origin feature/pricing
@@ -168,14 +168,14 @@ anchors. Paths come from the published docs index, not your working directory.
 
 ```bash
 farthershore docs ls --format json
-farthershore docs ls backend-sdk --format json
-farthershore docs tree backend-sdk --format json
-farthershore docs ls backend-sdk/connect-your-application --format json
-farthershore docs read backend-sdk/connect-your-application/metering --format json
-farthershore docs ls backend-sdk/connect-your-application/metering --format json
+farthershore docs ls sdks --format json
+farthershore docs tree sdks --format json
+farthershore docs ls sdks/connect-your-application --format json
+farthershore docs read sdks/connect-your-application/metering --format json
+farthershore docs ls sdks/connect-your-application/metering --format json
 farthershore docs read backend/metering --section "choose-the-correct-metering-channel" --format json
-farthershore docs search "runtime token" --collection backend-sdk --limit 10 --format json
-farthershore docs collection backend-sdk --format json
+farthershore docs search "runtime token" --collection sdks --limit 10 --format json
+farthershore docs collection sdks --format json
 ```
 
 Use an anchor returned by `docs ls <page>` for `--section`. `read` also accepts the canonical slug or an
@@ -235,15 +235,46 @@ farthershore build --format json
 ### `farthershore validate`
 
 Run the same verdict the GitHub `farthershore/validate` PR check produces, before
-you push. It builds the manifest twice and compares the IR hash (the determinism
-check the build runner enforces), then — when you pass `--business` — submits the
-IR for a server verdict that returns compile diagnostics, the semantic diff, and
-an economic-change verdict. Validation never accepts or publishes business
-state, so it is safe to repeat.
+you push. It builds `business/` on your machine twice and checks that both
+builds match (the determinism check the PR check enforces). It then sends the
+compiled business definition and your docs to the server, which checks them
+with the newest checks and returns the PR check's verdict: problems, the change
+summary, and whether the change is economic. Validation never accepts or
+publishes anything, so it is safe to repeat.
+
+What leaves your machine: only the compiled business definition (the output
+of the local build) and your docs files (`docs/_index.yaml` and the `.mdx`
+pages under `docs/`). Your `business/` source code never leaves it.
+`--local-only` sends nothing. Without a `docs/` folder, nothing is sent for
+docs. Docs over the size the check accepts (500 files, 1,000,000 bytes per file,
+10,000,000 bytes in all) are reported as a Docs problem without being sent.
+
+The server check runs by default against this repo's business: `--business`,
+else `FARTHERSHORE_BUSINESS`, else the directory link (`farthershore link`),
+else the business connected to the repo's GitHub `origin` remote. When none of
+those resolves, or you are not logged in, the local checks still run and the
+output says the server check was skipped and how to turn it on.
+
+The output has the PR check's two sections, **Business SDK** and **Docs**,
+each listing problems the way its PR comment does. Every problem has the same
+fields as the comment's JSON: `code`, `message`, and where known `file`,
+`line`, `column` and `path` (the location in the business definition). With
+`--format json` they are in `data.businessSdk` / `data.docs` (or
+`error.details.businessSdk` / `error.details.docs` when there are problems),
+each `{ issues, checked }`, where `checked` is `local`, `server` or `skipped`.
+Any problem in either section exits 2, whether the local build or the server
+found it.
+
+The docs check can also return warnings and info notes. They never fail
+`farthershore validate`: the Docs section lists them after the problems,
+labelled `Warning:` or `Info:`, and a run with only notes exits 0. In JSON they
+are in the same `issues` list, after the problems, each with a `severity` of
+`warning` or `info`; an issue without a `severity` is a problem. A build that could not run at all (for example, `business/`
+dependencies not installed) exits 1.
 
 ```bash
-farthershore validate                       # local build + determinism only
-farthershore validate --business weather-api
+farthershore validate                        # local build + server check
+farthershore validate --business weather-api # check against a named business
 farthershore validate --local-only --format json
 ```
 
@@ -708,6 +739,7 @@ farthershore webhook update weather-api <webhookId> --disable --format json
 farthershore webhook test weather-api <webhookId> --format json
 farthershore webhook trigger weather-api <webhookId> --type payment.failed --format json
 farthershore webhook deliveries weather-api <webhookId> --limit 20 --format json
+farthershore webhook delivery weather-api <webhookId> <deliveryId> --format json
 farthershore webhook rotate weather-api <webhookId> --yes --format json
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
@@ -720,6 +752,13 @@ in the receiving app. In human mode they also print it as an
 sends a signed, realistic sample of one catalog event (the deliveries log
 records it under that type) so every handler branch can be exercised locally.
 
+`webhook deliveries` lists recent attempts; `webhook delivery` shows one by its
+id (the `webhook-id` header your endpoint received, also the `deliveryId` that
+`webhook test` / `webhook trigger` return): its status, attempts, last HTTP
+status and when the next attempt is due. A `failed` delivery with no next
+attempt (a test send) is final. Neither returns the event payload or your
+endpoint's response body.
+
 For a receiver on your machine, `webhook listen` is the Stripe-CLI-style loop:
 it opens a Cloudflare quick tunnel to `--forward-to`, creates a temporary
 endpoint on it, prints the endpoint id / tunnel URL / (with `--print-secret`)
@@ -764,18 +803,18 @@ Use `--all-plans` to clear plan scoping.
 Install or refresh the platform-verified skills bundle together. The platform
 pins this immutable release, and CI plus a daily repository check compare it to
 GitHub's latest stable release so the guidance cannot silently drift.
-This command requires `@farthershore/cli` 0.36.0 or newer.
+This command requires `@farthershore/cli` 0.38.0 or newer.
 
 ```bash
 set -euo pipefail
 CLI_VERSION=$(farthershore --version)
-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] > 36 || (+m[2] === 36 && +m[3] >= 0))) { console.error("Stop: CLI 0.36.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
+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] > 38 || (+m[2] === 38 && +m[3] >= 0))) { console.error("Stop: CLI 0.38.0 or newer is required; ask the human to upgrade."); process.exitCode = 1; } })'
 farthershore skills install --help
 farthershore skills install
 ```
 
 If either prerequisite fails, stop and ask the human to run
-`npm install -g @farthershore/cli@0.36.0`, then repeat the checks.
+`npm install -g @farthershore/cli@0.38.0`, then repeat the checks.
 Do not install or upgrade global tooling autonomously.
 
 The Farther Shore CLI downloads the exact installer archive and verifies this