@revturbine/cli 0.21.2 → 0.21.4

package/README.md

@@ -96,7 +96,7 @@ Commands that read a config name the version explicitly — there is no default:
 
 | Selector | Meaning |
 |---|---|
-| `<file>` / `--file <path>` | a local Playbook file |
+| `<file>` | a local Playbook file, given as a positional path (only `show` also accepts `--file <path>`) |
 | `--draft` | the tenant's single open draft (resolved automatically) |
 | `--live` | the current live Release |
 | `--release <id>` | a specific playbook version / Release |
@@ -112,16 +112,16 @@ Commands that read a config name the version explicitly — there is no default:
 | `schema` | Emit the bundled `RevTurbineConfig` JSON schema (for agents to author against). |
 | `docs` | Print the canonical documentation URL. |
 | `download` | Fetch a config version (`--live` / `--draft` / `--release <id>`); `--save`. |
-| `validate` | Offline schema validation of a `<file>`, or the full server catalog against the open draft (`--draft`). |
-| `diff` | Compare any two versions (dry-run, no writes). A file vs `--draft`/`--live`/`--release` previews the launch — the server side is the base, so `+`/`-` read as created/pruned on launch. `--exit-code` makes the status machine-readable: `0` no differences, `1` differences, anything else an error (an unexpected internal error exits `70` so `1` always means "differences"). Every top-level Playbook collection is compared. |
+| `validate` | Offline schema validation of a `<file>`, or the full server catalog against the open draft (`--draft`). Offline mode also warns on unknown fields at any depth, naming the full path (`cli/unknown-field`). |
+| `diff` | Compare any two versions (dry-run, no writes). A file vs `--draft`/`--live`/`--release` previews the launch — the server side is the base, so `+`/`-` read as created/pruned on launch. `--exit-code` makes the status machine-readable: `0` no differences, `1` differences, anything else an error (an unexpected internal error exits `70` so `1` always means "differences"). Every top-level Playbook collection is compared, per `unique_handle`/`handle`, **semantically**: key order does not matter; `null`, `[]` and `{}` equal an absent property; server-owned fields (`created_at`/`updated_at`, item `id`, `segments[].dimension_id`, `entitlement_rules[].unit`, `entitlements[].tier_description`), the built-in `rt.*` segments, the Playbook header and `entitlements[].kind` `feature` vs `capability_tier` are ignored, so an uploaded-then-downloaded file reads as unchanged. A real change lists the changed fields, e.g. `~ pro (name)`; top-level objects and scalars are compared too. |
 | `show <kind>` | Summary tables: `plans` · `entitlements` · `segments` · `placements` · `trials` for any version. |
-| `upload` | Stage a Playbook file as the open draft. |
+| `upload` | Stage a Playbook file as the open draft. Warns, never blocks, on every unknown field at any depth with its full path (`entitlements[2].allocatoin`) and still posts the file unchanged. Lists every default the importer injected and every field it dropped. **Refuses with a 409 (exit `5`, nothing written)** when the open draft holds edits made since the last upload that the file would overwrite or remove, or when the in-flight version is beyond draft (awaiting approval, approved, deploying): the output names each edit, or the version id, its status and its holder, plus `revturbine download --draft --save <file>`, and in a terminal offers to save that backup first. `--dry-run` prints the plan (create / update / remove / conflict / no change) without writing: exit `0` with no conflicts, `1` with conflicts (an unexpected error exits `70`). `--report <path>` writes `{ outcome, plan, rejected, warnings }` as JSON (`outcome` is `applied`, `dry_run` or `refused`) for a 200, a 409, a 422 or a dry run, without changing the exit code. |
 | `launch` | Take a config live: validate (launch gate) → submit → approve → deploy. `launch <file>` or `launch --draft`. |
-| `discard` | Archive the open draft (`--yes`). |
+| `discard` | Archive the open draft (`--yes`). The confirmation names the version's status, and discarding deletes its staged edits: ask the human first, and save a copy with `download --draft --save <file>`. |
 | `restore` | Stage a draft that restores a past release from its frozen snapshot; `--launch` takes it live. Halts if a draft is open. |
 | `status` | The live Release and the open draft, side by side. |
 | `history` | The Release Version Log, newest first. |
-| `preview` | The open draft's staged changes. |
+| `preview` | The open draft's staged changes, plus the import notes (defaults injected, fields dropped, identifiers rewritten). |
 | `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. The ctx file carries the whole decision context — `plan_handle`, `traits`, `usage`, `trial` (or `trial_instances` + `now_iso`) — and `--usage` / `--trial-status` / `--now` override those keys, so usage-threshold and trial placements decide here exactly as they do in an app. Output reports `payload_ids`: which authored payload the resolver chose per placement, plus the SDK's `personalization_tokens`. |
 | `generate types` | Generate a TypeScript module of typed Playbook handles from any config version — `Entitlements` (namespaced by type, with the `EntitlementHandle` union for type-safe `can()`/`gate()`/`checkEntitlement()` call sites), plus `Plans`, `Segments`, `SurfaceTemplates`, and `UiPathActionTypes`. Const objects + literal-union types (erasable — no enums). `--out <path>` writes the file; the generated header records the exact command to regenerate it. `--json` for the raw handle map. |
 | `analytics catalog\|templates\|views\|view\|create\|preview\|query` | Work with the hosted Semantic Catalog and canonical analytics-view documents. Create and preview pass the document through unchanged to the same server contract used by the web editor and MCP tools; preview remains subject to the server's query limits. |
@@ -195,6 +195,7 @@ environment instead:
 | Variable | Meaning |
 |---|---|
 | `REVTURBINE_TOKEN` | Bearer token for every request. Wins over any stored credential (which is then ignored). With it set and no `-t/--tenant-id`, **no `x-tenant-id` header is sent** and the server resolves the token user's own tenant; `-t` still sends one (it must be that tenant). |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Honoured by every request (undici `EnvHttpProxyAgent`), for sandboxes that reach the internet only through a proxy. A failed request prints its cause and the variable that was in force (never its value, which can carry credentials). |
 | `REVTURBINE_HTTP_HEADERS` | A JSON object of extra headers added to every request to the RevTurbine instance, e.g. `{"x-vercel-protection-bypass":"…"}` to reach a protection-gated preview/staging deployment. It may not set `Authorization`, `x-tenant-id`, `x-rt-tenant-id` or `Content-Type`. A malformed value exits `2`. |
 
 Neither the token nor any header value is ever logged, echoed in an error, or