@farthershore/cli 0.9.2 → 0.11.0

package/README.md

@@ -1,8 +1,8 @@
 # @farthershore/cli
 
-Create and manage [FartherShore](https://farthershore.com) API products from
-the terminal. Designed for AI agents and humans alike — every command supports
-`--format json` for non-TTY scripting.
+Create and manage [FartherShore](https://farthershore.com) software products
+from the terminal. Designed for AI agents and humans alike — every command
+supports `--format json` for non-TTY scripting.
 
 ## Install
 
@@ -52,7 +52,7 @@ farthershore auth logout         # Clear stored credentials
 | Flag                  | Description                                              |
 | --------------------- | -------------------------------------------------------- |
 | `--token <token>`     | Override auth token for this command                     |
-| `--api-url <url>`     | Override API base URL                                    |
+| `--api-url <url>`     | Override platform Core API URL                           |
 | `--env <environment>` | Environment scope (use `production`/`prod`/`main`)       |
 | `--format <format>`   | `json` for machine-readable output (default for non-TTY) |
 | `--version`           | Show version                                             |
@@ -60,19 +60,22 @@ farthershore auth logout         # Clear stored credentials
 
 ## Environment variables
 
-| Variable               | Description                                             |
-| ---------------------- | ------------------------------------------------------- |
-| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                |
-| `FARTHERSHORE_API_URL` | API base URL (default: `https://core.farthershore.com`) |
-| `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted       |
+| Variable               | Description                                                      |
+| ---------------------- | ---------------------------------------------------------------- |
+| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                         |
+| `FARTHERSHORE_API_URL` | Platform Core API URL (default: `https://core.farthershore.com`) |
+| `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted                |
 
 ## Commands
 
 ### `farthershore init`
 
-Scaffold a starter `product/product.config.ts` from a named plan preset. Each
-preset fills in the 5-knob spec through the Product SDK so first-time builders
-skip the blank-page problem.
+Scaffold a starter software-product repo from a named plan preset. Each preset
+fills in the 5-knob spec through `product/plans.ts`, with
+`product/product.config.ts` composing `meters.ts`, `features.ts`, and `plans.ts`.
+The command also creates a customer `frontend/` project, repo-local
+`product/package.json`, `product/tsconfig.json`, and `.gitignore`, matching the
+two-root shape generated by dashboard product creation.
 
 ```bash
 # Interactive walkthrough (TTY only) — pick a preset by number/name + path
@@ -82,6 +85,7 @@ farthershore init
 farthershore init --template free
 farthershore init --template starter --force
 farthershore init --template metered --format json
+farthershore init --template starter --surface frontend --surface agent
 ```
 
 Templates (sourced from shared-types `listPlanPresets()`):
@@ -94,30 +98,30 @@ Templates (sourced from shared-types `listPlanPresets()`):
 | `prepaid` | $50 one-time signup credit, then PAYG                        |
 | `metered` | Pure pay-as-you-go at $0.001/request                         |
 
-After `init`, edit the `fs.business(...)` product name + base URL in
-`product/product.config.ts`, split the product into any imported modules you
-want, then run `farthershore build --validate` to confirm the scaffolded
-manifest compiles.
+After `init`, edit the `fs.product(...)` product name and `origin` in
+`product/product.config.ts`. `origin` is the business logic destination Farther
+Shore calls for customer-facing actions. Keep the generated module split or
+reorganize the product into any imported files you want. Pass repeatable
+`--surface <frontend|api|docs|widget|dashboard|webhook|worker|agent>` to seed a
+frontend-only, agent, worker, API, or hybrid product. Omitting `--surface`
+keeps the default `frontend + api` starter and its sample gateway route. Run
+`npm install` in `product/` once, then run `farthershore build` from the repo
+root to confirm the scaffolded product compiles locally. Customize `frontend/`
+for signup, pricing, account, and usage screens.
 
 ### `farthershore build`
 
 Build a product-as-code `product/product.config.ts` with the Product SDK
 manifest builder. The CLI first uses the builder installed under `product/`,
 then falls back to a root install. The command emits a Manifest IR envelope to
-`manifest-ir.json` by default.
+`manifest-ir.json` by default. Server-side validation and accepted lifecycle
+state are handled by the GitHub bot when `product/**` changes are pushed to the
+repo-backed product.
 
 ```bash
 farthershore build
 farthershore build --entry product/product.config.ts --out manifest-ir.json
 farthershore build --format json
-
-# Optional dry-run compile against core after the local build succeeds
-farthershore build --validate weather-api --format json
-farthershore build --validate weather-api --env preview --format json
-
-# Apply the accepted lifecycle state through core without relying on GitHub
-farthershore build --apply weather-api --format json
-farthershore build --apply weather-api --env preview --format json
 ```
 
 ### `farthershore product`
@@ -134,53 +138,68 @@ farthershore product show weather-api --env preview --format json
 farthershore product create \
   --name weather-api \
   --display-name "Weather API" \
-  --base-url https://api.example.com \
+  --origin https://api.example.com \
   --format json
 
 # Meter templates — the same smart defaults the dashboard offers:
 #   requests (default) | ai-tokens | credits | spend | compute
-farthershore product create --name llm-api --meters ai-tokens --format json
+farthershore product create \
+  --name llm-api \
+  --origin https://api.llm.example.com \
+  --meters ai-tokens \
+  --format json
 
 # Or a fully custom meter list (key[:display[:unit]], repeatable):
 farthershore product create --name image-api \
+  --origin https://api.images.example.com \
   --meter requests \
   --meter images:Images:image \
   --format json
 
+# Seed initial Product SDK surfaces (repeatable). Defaults to frontend + API.
+farthershore product create \
+  --name support-agent \
+  --origin https://app.example.com \
+  --repo-owner acme \
+  --repo-name support-agent \
+  --surface frontend \
+  --surface agent \
+  --format json
+
 farthershore product update weather-api --display-name "Weather" --format json
 farthershore product publish weather-api --format json
 farthershore product delete weather-api --yes --format json
-
-farthershore product compile weather-api --dry-run --format json
-farthershore product compile weather-api --branch env/preview --format json
 ```
 
 `product create` provisions a managed GitHub repo and returns clone-URL +
 agent bootstrap instructions in the response. That repo is required for the
 starter `frontend/` project and normal customization workflow. Product SDK
-changes can be validated with `farthershore build --validate` and applied to the
-repo-backed product with `farthershore build --apply`.
+changes can be built locally with `farthershore build`; accepted changes are
+compiled and published by the GitHub bot after they are committed and pushed.
 
 Plan pricing lives on the plan (see `farthershore plan create` below) — the
 product itself no longer carries a `billingStrategy`. Omitting both meter flags
-gives the product a `requests` meter; variable-value meters (tokens, credits,
-spend) are settled from upstream `x-fs-cost-{key}` response headers.
+gives the product a `requests` meter. Plain request counting is
+platform-managed. Variable-value meters such as tokens, credits, or compute must
+be declared in the Product SDK as route `reports` and reported by the upstream
+with `@farthershore/metering`.
 
 A new product starts as a DRAFT with a generated `frontend/` project ready for
 customization. Going live mirrors the dashboard's "Finish setting up" checklist:
 
 ```bash
-farthershore product create --name llm-api --meters ai-tokens   # 1. create
+farthershore product create \
+  --name llm-api \
+  --origin https://api.example.com \
+  --meters ai-tokens                                            # 1. create
 farthershore connect stripe llm-api                             # 2. connect billing
 farthershore plan create llm-api --key pro --name "Pro" \
   --recurring-fee-cents 2900                                    # 3. how you charge
-farthershore product update llm-api \
-  --base-url https://api.example.com                            # 4. endpoint
-farthershore product publish llm-api                            # 5. go live
+farthershore product publish llm-api                            # 4. go live
 ```
 
 `product publish` enforces the same gates as the dashboard: at least one
-plan, a base URL, and a verified Stripe connection (clear remediation is
+plan, an origin, and a verified Stripe connection (clear remediation is
 printed for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` /
 `BILLING_TAX_NOT_ENROLLED`).
 
@@ -250,6 +269,29 @@ Read recent usage off the management API.
 farthershore usage summary weather-api --format json
 ```
 
+### `farthershore metering tokens`
+
+Provision runtime metering tokens for upstream services. Core stores only token
+hashes; the raw token is returned once and should be deployed as
+`FARTHERSHORE_METERING_TOKEN`.
+
+```bash
+farthershore metering tokens list weather-api --format json
+farthershore metering tokens create weather-api --name "prod-api" --format json
+farthershore metering tokens create weather-api --name "preview-api" --env preview --format json
+farthershore metering tokens revoke weather-api <tokenId> --yes --format json
+```
+
+Pair the token with `@farthershore/metering` in the upstream:
+
+```ts
+import { withUsage } from "@farthershore/metering";
+
+return withUsage(request, Response.json(result), {
+  tokens_used: result.tokensUsed,
+});
+```
+
 ### `farthershore connect`
 
 GitHub OAuth and Stripe Connect flows are browser-only. These commands
@@ -270,17 +312,6 @@ farthershore token create --name "ci-bot" --scope products:update products:publi
 farthershore token revoke <tokenId> --yes --format json
 ```
 
-### `farthershore build --validate <product>`
-
-`build --validate` runs a local manifest compile + server-side validation
-pass after `product/product.config.ts` is built. This is the replacement for the
-deleted `validate`/`apply` proposal flow.
-
-```bash
-farthershore build --validate weather-api --format json
-farthershore build --validate weather-api --env preview --format json
-```
-
 #### Plan knobs
 
 Every plan is a configuration of 5 orthogonal knobs (shared-types
@@ -419,7 +450,8 @@ Validation surfaces:
 #### Deprecation window (Phase 3b)
 
 The product top-level `lifecycle.breaking_changes` block declares the
-breaking-change governance policy validated during `build --validate`:
+breaking-change governance policy validated by the GitHub bot/Core release
+path:
 
 ```yaml
 lifecycle:
@@ -428,15 +460,11 @@ lifecycle:
     require_successor_route: true
 ```
 
-When the policy is set:
-
-- `build --validate` emits an informational warning so the builder
-  sees the active policy locally.
-- It emits a `route_removed` change for every route dropped from
-  `features.<x>.routes[]` and warns when the server-side
-  `breaking-change-safety-check` cron will gate publish via
-  `ConsumerActivity` lookup. When `require_successor_route` is true,
-  it also adds a successor-required warning.
+When the policy is set, Core emits a `route_removed` change for every route
+dropped from `features.<x>.routes[]` and warns when the server-side
+`breaking-change-safety-check` cron will gate publish via `ConsumerActivity`
+lookup. When `require_successor_route` is true, it also adds a
+successor-required warning.
 
 The CLI never blocks on the window itself — the per-consumer lookup
 lives server-side (Phase 1c `ConsumerActivity` table + Phase 3b cron).
@@ -450,22 +478,22 @@ export FARTHERSHORE_TOKEN=mk_xxx
 
 farthershore product create \
   --name weather-api \
-  --base-url https://api.example.com \
+  --origin https://api.example.com \
   --format json
 
 farthershore plan create weather-api --key free --name "Free" --free --format json
 farthershore plan create weather-api \
   --key pro --name "Pro" --recurring-fee-cents 2900 --format json
 
-farthershore build --validate weather-api --format json
+farthershore build --format json
 farthershore product show weather-api --format json
 ```
 
 For product updates, edit `product/product.config.ts` or any modules it imports
-and validate with:
+and build locally with:
 
 ```bash
-farthershore build --validate weather-api --format json
+farthershore build --format json
 ```
 
 ## MCP server
@@ -499,5 +527,5 @@ for CI scripts.
 The CLI is non-interactive whenever a token is available via the
 `--token` flag or `FARTHERSHORE_TOKEN` env var — `auth login` only
 prompts when stdin is a TTY and no token argument was passed, so it's
-safe to script. `farthershore build --validate` is CI-safe and can be
-run under `CI` / `GITHUB_ACTIONS` for automation.
+safe to script. `farthershore build` is CI-safe and can be run under `CI` /
+`GITHUB_ACTIONS` for local Product SDK compilation.