@farthershore/cli 0.7.3 → 0.9.0

package/README.md

@@ -49,14 +49,14 @@ farthershore auth logout         # Clear stored credentials
 
 ## Global flags
 
-| Flag                   | Description                                           |
-| ---------------------- | ----------------------------------------------------- |
-| `--token <token>`      | Override auth token for this command                  |
-| `--api-url <url>`      | Override API base URL                                 |
-| `--env <environment>`  | Environment scope (use `production`/`prod`/`main`)    |
-| `--format <format>`    | `json` for machine-readable output (default for non-TTY) |
-| `--version`            | Show version                                          |
-| `--help`               | Show help                                             |
+| Flag                  | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| `--token <token>`     | Override auth token for this command                     |
+| `--api-url <url>`     | Override API base URL                                    |
+| `--env <environment>` | Environment scope (use `production`/`prod`/`main`)       |
+| `--format <format>`   | `json` for machine-readable output (default for non-TTY) |
+| `--version`           | Show version                                             |
+| `--help`              | Show help                                                |
 
 ## Environment variables
 
@@ -70,9 +70,9 @@ farthershore auth logout         # Clear stored credentials
 
 ### `farthershore init`
 
-Scaffold a starter `product.yaml` from a named plan preset. Each preset
-fills in the 5-knob spec for a common shape so first-time builders skip
-the blank-page problem.
+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.
 
 ```bash
 # Interactive walkthrough (TTY only) — pick a preset by number/name + path
@@ -86,20 +86,38 @@ farthershore init --template metered --format json
 
 Templates (sourced from shared-types `listPlanPresets()`):
 
-| Template  | Shape                                                              |
-| --------- | ------------------------------------------------------------------ |
-| `free`    | $0 plan, hard-enforced 1k requests/month limit                    |
-| `starter` | $20/mo + $20 included usage, $0.001/request overage               |
-| `pro`     | $100/mo + $200 included usage, 14-day trial, $0.0005/request      |
-| `prepaid` | $50 one-time signup credit, then PAYG                              |
-| `metered` | Pure pay-as-you-go at $0.001/request                               |
+| Template  | Shape                                                        |
+| --------- | ------------------------------------------------------------ |
+| `free`    | $0 plan, hard-enforced 1k requests/month limit               |
+| `starter` | $20/mo + $20 included usage, $0.001/request overage          |
+| `pro`     | $100/mo + $200 included usage, 14-day trial, $0.0005/request |
+| `prepaid` | $50 one-time signup credit, then PAYG                        |
+| `metered` | Pure pay-as-you-go at $0.001/request                         |
 
-After `init`, edit `product.name` + `product.baseUrl`, then run
-`farthershore validate` to confirm the scaffolded YAML is acceptable.
+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.
+
+### `farthershore build`
+
+Build a product-as-code `product/product.config.ts` with the repo-local
+`./node_modules/.bin/farthershore-manifest-build` binary. The command
+emits a Manifest IR envelope to `manifest-ir.json` by default.
+
+```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
+```
 
 ### `farthershore product`
 
-Product lifecycle commands — direct API, no local `product.yaml` round-trip.
+Product lifecycle commands — direct API, no local manifest upload flow.
 
 ```bash
 farthershore product list --format json
@@ -112,7 +130,18 @@ farthershore product create \
   --base-url 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
+
+# Or a fully custom meter list (key[:display[:unit]], repeatable):
+farthershore product create --name image-api \
+  --meter requests \
+  --meter images:Images:image \
+  --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
@@ -122,7 +151,27 @@ 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. Plan pricing lives on the
 plan (see `farthershore plan create` below) — the product itself no
-longer carries a `billingStrategy`.
+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.
+
+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 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
+```
+
+`product publish` enforces the same gates as the dashboard: at least one
+plan, a base URL, and a verified Stripe connection (clear remediation is
+printed for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` /
+`BILLING_TAX_NOT_ENROLLED`).
 
 ### `farthershore env`
 
@@ -138,8 +187,8 @@ farthershore env delete weather-api preview --yes --format json
 ### `farthershore plan`
 
 Plan CRUD via the management API. The body uses the unified 5-knob
-spec (see "`product.yaml` plan shape" below) — pass cents-denominated
-flags for whichever knobs the plan flavor needs.
+shape (see "Plan knobs" below) — pass cents-denominated flags for
+whichever knobs the plan flavor needs.
 
 ```bash
 # Human-readable table (default in TTY)
@@ -210,34 +259,31 @@ farthershore token create --name "ci-bot" --scope products:update products:publi
 farthershore token revoke <tokenId> --yes --format json
 ```
 
-### `farthershore validate`
+### `farthershore build --validate <product>`
 
-Validate the managed repo (`product.yaml`, `brand.yaml`, `docs/`,
-`skills/`, `.github/workflows/`) through the same backend checks the
-Farther Shore GitHub bot runs.
+`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 validate
-farthershore validate --format json
+farthershore build --validate weather-api --format json
+farthershore build --validate weather-api --env preview --format json
 ```
 
-Emits GitHub Actions-formatted annotations when run under `CI` /
-`GITHUB_ACTIONS`.
-
-#### `product.yaml` plan shape
+#### 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.
 
-| 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)    |
+| `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) |
 
 Billing math (handled by Stripe Billing v2 at invoice finalization):
 `bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
@@ -258,21 +304,21 @@ plans:
         capacity: 1000
         enforcement: enforce
 
-# Flat subscription: recurring fee only
+  # Flat subscription: recurring fee only
   - key: starter
     name: Starter
     recurring_fee_cents: 2900
 
-# Included usage: fee + monthly credit grant + metered
+  # Included usage: fee + monthly credit grant + metered
   - key: pro
     name: Pro
     recurring_fee_cents: 2000
     recurring_credit_grant_cents: 2000
     meters:
       - dimension: requests
-        price_per_unit_micros: 1000        # $0.001/request
+        price_per_unit_micros: 1000 # $0.001/request
 
-# Overage: fee + metered, no credit
+  # Overage: fee + metered, no credit
   - key: growth
     name: Growth
     recurring_fee_cents: 4900
@@ -280,7 +326,7 @@ plans:
       - dimension: requests
         price_per_unit_micros: 500
 
-# Prepaid: one-time grant + metered
+  # Prepaid: one-time grant + metered
   - key: prepaid
     name: Prepaid
     one_time_credit_grant_cents: 10000
@@ -288,13 +334,13 @@ plans:
       - dimension: requests
         price_per_unit_micros: 1000
 
-# Trial: trial_days + recurring fee
+  # Trial: trial_days + recurring fee
   - key: trial
     name: Trial
     recurring_fee_cents: 2900
     trial_days: 14
 
-# Pay-as-you-go: metered only (no recurring fee)
+  # Pay-as-you-go: metered only (no recurring fee)
   - key: metered
     name: Metered
     meters:
@@ -312,20 +358,19 @@ entries from the legacy knobs so existing specs keep working.
 
 Valid `kind` values:
 
-| Kind            | Required fields                                            | Use case                                                 |
-| --------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
-| `recurring`     | `amount_cents`                                             | Monthly credit (e.g. $20 included usage)                 |
-| `one_time`      | `amount_cents`                                             | Signup bonus / prepaid balance                           |
-| `promotional`   | `amount_cents`, `label`, optional `expires_after_days`     | Launch bonus, win-back, holiday promo                    |
-| `trial`         | (none)                                                     | Trial entry — requires `trial_days > 0` on the plan      |
-| `rollover`      | `percent` (0–100)                                          | "Unused balance rolls over X% to the next period"        |
-| `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"                     |
-| `minimum_commit`| `period` (`monthly` / `annual`), `amount_cents`            | Floor for billing — charge at least this much            |
-
-`recurring`, `rollover`, `trial`, and `minimum_commit` are single-shot
-per plan; declaring more than one entry of the same kind triggers a
-warning (only the first is honored).
+| Kind            | Required fields                                        | Use case                                            |
+| --------------- | ------------------------------------------------------ | --------------------------------------------------- |
+| `recurring`     | `amount_cents`                                         | Monthly credit (e.g. $20 included usage)            |
+| `one_time`      | `amount_cents`                                         | Signup bonus / prepaid balance                      |
+| `promotional`   | `amount_cents`, `label`, optional `expires_after_days` | Launch bonus, win-back, holiday promo               |
+| `trial`         | (none)                                                 | Trial entry — requires `trial_days > 0` on the plan |
+| `rollover`      | `percent` (0–100)                                      | "Unused balance rolls over X% to the next period"   |
+| `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;
+declaring more than one entry of the same kind triggers a warning
+(only the first is honored).
 
 Example:
 
@@ -351,22 +396,19 @@ plans:
       - kind: auto_recharge
         threshold_cents: 500
         refill_cents: 5000
-      - kind: minimum_commit
-        period: monthly
-        amount_cents: 5000
 ```
 
-The validator surfaces:
+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** — `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`, `minimum_commit`) declared more than once
+- **warning** — singleton kinds (`recurring`, `rollover`, `trial`) declared more than once
 
 #### Deprecation window (Phase 3b)
 
 The product top-level `lifecycle.breaking_changes` block declares the
-breaking-change governance policy enforced on `apply`:
+breaking-change governance policy validated during `build --validate`:
 
 ```yaml
 lifecycle:
@@ -377,52 +419,16 @@ lifecycle:
 
 When the policy is set:
 
-- `farthershore validate` emits an informational warning so the builder
+- `build --validate` emits an informational warning so the builder
   sees the active policy locally.
-- `farthershore apply` (which compares the proposed spec against the
-  accepted spec) emits a `route_removed` change for every route
-  dropped from `features.<x>.routes[]` and warns that the server-side
-  `breaking-change-safety-check` cron will gate the publish via
+- 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,
-  the apply path additionally surfaces a successor-required warning.
+  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).
-The CLI's job is to surface the policy and the route delta locally so
-the builder knows what the gate will see.
-
-### `farthershore apply [product]`
-
-Publish the shared server draft as one product release. Core accepts the
-release only after schema validation, transition-safety validation, and
-a compiler dry-run all pass.
-
-```bash
-# Publish the current shared draft
-farthershore apply
-
-# Or pass the product slug/UUID explicitly
-farthershore apply weather-api
-
-# Validate and compile without publishing
-farthershore apply --dry-run --format json
-farthershore apply --env preview --dry-run --format json
-
-# Submit a local product.yaml as a one-off proposal
-farthershore apply --to product.yaml --dry-run --format json
-farthershore apply --to product.yaml --format json
-
-# Also stage that file as the shared draft before publishing
-farthershore apply --to product.yaml --save-draft --format json
-
-# Pin compilation to a specific branch
-farthershore apply weather-api --branch feature/billing-change --dry-run --format json
-```
-
-JSON output is stable: `{ ok, success, errors, warnings, lifecyclePlan,
-nextActions, ... }`. `lifecyclePlan` is always present (or `null` on
-first deploys / older core builds) and surfaces ADR-0010 per-domain
-subscriber-migration actions.
 
 ## Agent workflow
 
@@ -440,27 +446,23 @@ farthershore plan create weather-api --key free --name "Free" --free --format js
 farthershore plan create weather-api \
   --key pro --name "Pro" --recurring-fee-cents 2900 --format json
 
-farthershore apply weather-api --dry-run --format json
-farthershore apply weather-api --format json
+farthershore build --validate weather-api --format json
 farthershore product show weather-api --format json
 ```
 
-For a YAML-driven flow, edit `product.yaml` in the managed repo, then:
+For product updates, edit `product/product.config.ts` or any modules it imports
+and validate with:
 
 ```bash
-farthershore validate --format json
-farthershore apply --to product.yaml --dry-run --format json
-farthershore apply --to product.yaml --format json
+farthershore build --validate weather-api --format json
 ```
 
 ## MCP server
 
-The MCP server (`farthershore-mcp`) exposes two tools:
+The MCP server (`farthershore-mcp`) exposes one tool:
 
-- `farthershore_draft_validate` — run server-side validation on the shared
-  draft.
-- `farthershore_apply` — apply the draft, optionally with a `product.yaml`
-  proposal via `toFile`. Defaults to `dryRun: true`.
+- `farthershore_status` — return product list context and selected product
+  metadata.
 
 Both accept optional `product` and `env` fields and return JSON.
 
@@ -486,5 +488,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. `validate` and `apply` emit GitHub Actions-formatted
-annotations when run under `CI` / `GITHUB_ACTIONS`.
+safe to script. `farthershore build --validate` is CI-safe and can be
+run under `CI` / `GITHUB_ACTIONS` for automation.