@farthershore/cli 0.12.0 → 0.13.0

package/README.md

@@ -240,7 +240,7 @@ farthershore plan create weather-api \
   --key included \
   --name "Included" \
   --recurring-fee-cents 2000 \
-  --recurring-credit-grant-cents 2000 \
+  --grant recurring:2000 \
   --format json
 
 # Free plan
@@ -269,27 +269,49 @@ Read recent usage off the management API.
 farthershore usage summary weather-api --format json
 ```
 
-### `farthershore metering tokens`
+### `farthershore backend`
 
-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`.
+Create BYO backends and provision runtime tokens for upstream services. Core
+stores only token hashes; the raw token is returned once and should be deployed
+as `FS_RUNTIME_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
+farthershore backend list weather-api --format json
+farthershore backend create weather-api \
+  --name "Production API" \
+  --origin-url https://api.example.com \
+  --format json
+farthershore backend tokens list weather-api --format json
+farthershore backend tokens create weather-api --backend <backendId> --format json
+farthershore backend tokens rotate weather-api <tokenId> --format json
+farthershore backend tokens revoke weather-api <tokenId> --yes --format json
+farthershore backend delete weather-api <backendId> --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,
-});
+import { fartherShore, withUsage } from "@farthershore/metering";
+
+const fs = fartherShore.initFromEnv();
+
+export async function POST(request: Request) {
+  const url = new URL(request.url);
+  const body = await request.clone().arrayBuffer();
+
+  await fs.verifyRequest({
+    method: request.method,
+    path: url.pathname,
+    query: url.search,
+    headers: request.headers,
+    body: new Uint8Array(body),
+  });
+
+  const result = await runWorkflow(await request.json());
+  return withUsage(request, Response.json(result), {
+    tokens_used: result.tokensUsed,
+  });
+}
 ```
 
 ### `farthershore connect`
@@ -314,18 +336,17 @@ farthershore token revoke <tokenId> --yes --format json
 
 #### Plan knobs
 
-Every plan is a configuration of 5 orthogonal knobs (shared-types
-v0.53.0). Older shapes with `pricing.{model, monthlyPriceCents}` and
-top-level `billing.strategy` are no longer accepted by the validator.
+Every plan is a configuration of orthogonal billing knobs. Older shapes with
+`pricing.{model, monthlyPriceCents}`, top-level `billing.strategy`, or scalar
+credit grant fields are no longer accepted by the validator.
 
-| Knob                           | Cents/unit       | Meaning                                                 |
-| ------------------------------ | ---------------- | ------------------------------------------------------- |
-| `meters[]`                     | micros/unit      | Per-dimension usage price (zero or more dimensions)     |
-| `recurring_fee_cents`          | cents            | Charged each billing period (recurring subscription)    |
-| `recurring_credit_grant_cents` | cents            | Credit issued each period; drains against meter charges |
-| `one_time_credit_grant_cents`  | cents            | Prepaid balance at subscription start; drains once      |
-| `trial_days`                   | days             | Waive everything for N days at the start                |
-| `max_monthly_spend_cents`      | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
+| Knob                      | Cents/unit       | Meaning                                                 |
+| ------------------------- | ---------------- | ------------------------------------------------------- |
+| `meters[]`                | micros/unit      | Per-dimension usage price (zero or more dimensions)     |
+| `recurring_fee_cents`     | cents            | Charged each billing period (recurring subscription)    |
+| `grants[]`                | varies by kind   | Credit grants, top-ups, rollover, and recharge policy   |
+| `trial_days`              | days             | Waive everything for N days at the start                |
+| `max_monthly_spend_cents` | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
 
 Billing math (handled by Stripe Billing v2 at invoice finalization):
 `bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
@@ -355,7 +376,9 @@ plans:
   - key: pro
     name: Pro
     recurring_fee_cents: 2000
-    recurring_credit_grant_cents: 2000
+    grants:
+      - kind: recurring
+        amount_cents: 2000
     meters:
       - dimension: requests
         price_per_unit_micros: 1000 # $0.001/request
@@ -371,7 +394,9 @@ plans:
   # Prepaid: one-time grant + metered
   - key: prepaid
     name: Prepaid
-    one_time_credit_grant_cents: 10000
+    grants:
+      - kind: one_time
+        amount_cents: 10000
     meters:
       - dimension: requests
         price_per_unit_micros: 1000
@@ -390,13 +415,11 @@ plans:
         price_per_unit_micros: 100
 ```
 
-#### `grants[]` array (shared-types v0.56.0)
+#### `grants[]` array
 
-Plans now accept a typed `grants[]` array that supersedes the two
-legacy grant knobs (`recurring_credit_grant_cents`,
-`one_time_credit_grant_cents`). When `grants[]` is present, the legacy
-knobs are ignored. When absent, the validator silently synthesizes
-entries from the legacy knobs so existing specs keep working.
+Plans accept a typed `grants[]` array. It is the only public credit surface.
+For CLI plan create/update, pass one or more canonical grants with
+`--grant <kind:amount_cents>`.
 
 Valid `kind` values:
 
@@ -410,7 +433,7 @@ Valid `kind` values:
 | `top_up`        | `sku`, `label`, `price_cents`, `credit_cents`          | Buy-extra-credit SKU exposed in checkout            |
 | `auto_recharge` | `threshold_cents`, `refill_cents`                      | "When balance < $X auto-purchase $Y"                |
 
-`recurring`, `rollover`, and `trial` are single-shot per plan;
+`recurring`, `one_time`, `rollover`, and `trial` are single-shot per plan;
 declaring more than one entry of the same kind triggers a warning
 (only the first is honored).
 
@@ -443,9 +466,8 @@ plans:
 Validation surfaces:
 
 - **error** — invalid `kind` is rewritten to `Unknown grant kind. Valid kinds: …`
-- **warning** — `grants[]` declares `recurring`/`one_time` _and_ the matching legacy knob is also non-zero (legacy is silently ignored)
 - **warning** — `{ kind: trial }` declared but `trial_days` is 0
-- **warning** — singleton kinds (`recurring`, `rollover`, `trial`) declared more than once
+- **warning** — singleton kinds (`recurring`, `one_time`, `rollover`, `trial`) declared more than once
 
 #### Deprecation window (Phase 3b)
 
@@ -498,12 +520,21 @@ farthershore build --format json
 
 ## MCP server
 
-The MCP server (`farthershore-mcp`) exposes one tool:
-
-- `farthershore_status` — return product list context and selected product
-  metadata.
-
-Both accept optional `product` and `env` fields and return JSON.
+The MCP server (`farthershore-mcp`) projects tool definitions from the same
+operation registry that generates the CLI command groups. Tool names use the
+`fs_*` prefix and cover the agent-writable product surface:
+
+- Products: `fs_product_list`, `fs_brand_update`, `fs_product_publish`
+- Environments: `fs_env_list`, `fs_env_create`
+- Plans: `fs_plan_list`
+- Backends: `fs_backend_list`, `fs_backend_create`, `fs_backend_delete`
+- Runtime tokens: `fs_runtime_token_list`, `fs_runtime_token_mint`,
+  `fs_runtime_token_rotate`, `fs_runtime_token_revoke`
+- Personas: `fs_persona_bootstrap`, `fs_persona_list`, `fs_persona_revoke`
+- Usage and maker tokens: `fs_usage_read`, `fs_maker_token_list`
+
+Every MCP tool has a sibling CLI operation by construction; the parity test in
+`apps/cli/src/operations/mcp-cli-parity.test.ts` enforces that invariant.
 
 ## Errors and exit codes