@farthershore/cli 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ 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

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.37.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.37.0
+npm install -g @farthershore/cli@0.38.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.37.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
 ```
 
@@ -772,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.37.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] > 37 || (+m[2] === 37 && +m[3] >= 0))) { console.error("Stop: CLI 0.37.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.37.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