@revturbine/cli 0.16.0 → 0.16.2

package/README.md

@@ -1,6 +1,6 @@
 # revturbine-cli (`revturbine`)
 
-Validate [RevTurbine](https://revturbine.com) **Config Files** and ship them to
+Validate [RevTurbine](https://revturbine.com) **Playbooks** and ship them to
 a RevTurbine instance through the playbook-version lifecycle (draft → Release) —
 from the terminal, the same operations the in-app studios perform.
 
@@ -39,11 +39,11 @@ Requires Node ≥ 22.13. Source builds use the npm 11.18.0 version declared in
 ```bash
 revturbine signup                             # create an account (email + password + emailed code)
 revturbine login                              # authorize this machine (device flow)
-revturbine download --live --save ./config.json
-# …edit ./config.json…
-revturbine validate ./config.json             # schema-validate locally (no network)
-revturbine diff ./config.json --live          # what would change (no writes)
-revturbine launch ./config.json               # upload, gate, and go live
+revturbine download --live --save ./revturbine.playbook.json
+# …edit ./revturbine.playbook.json…
+revturbine validate ./revturbine.playbook.json             # schema-validate locally (no network)
+revturbine diff ./revturbine.playbook.json --live          # what would change (no writes)
+revturbine launch ./revturbine.playbook.json               # upload, gate, and go live
 ```
 
 `revturbine <command> --help` documents every flag.
@@ -54,7 +54,7 @@ Commands that read a config name the version explicitly — there is no default:
 
 | Selector | Meaning |
 |---|---|
-| `<file>` / `--file <path>` | a local Config File |
+| `<file>` / `--file <path>` | a local Playbook file |
 | `--draft` | the tenant's single open draft (resolved automatically) |
 | `--live` | the current live Release |
 | `--release <id>` | a specific playbook version / Release |
@@ -71,9 +71,9 @@ Commands that read a config name the version explicitly — there is no default:
 | `docs` | Print the canonical documentation URL. |
 | `download` | Fetch a config version (`--live` / `--draft` / `--release <id>`); `--save`, `--format flatbuffer`. |
 | `validate` | Offline schema validation of a `<file>`, or the full server catalog against the open draft (`--draft`). |
-| `diff` | Compare any two versions, first → second (dry-run, no writes). |
+| `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. |
 | `show <kind>` | Summary tables: `plans` · `entitlements` · `segments` · `placements` · `trials` for any version. |
-| `upload` | Stage a Config File as the open draft. |
+| `upload` | Stage a Playbook file as the open draft. |
 | `launch` | Take a config live: validate (launch gate) → submit → approve → deploy. `launch <file>` or `launch --draft`. |
 | `discard` | Archive the open draft (`--yes`). |
 | `restore` | Stage a draft that restores a past release from its frozen snapshot; `--launch` takes it live. Halts if a draft is open. |
@@ -81,7 +81,7 @@ Commands that read a config name the version explicitly — there is no default:
 | `history` | The Release Version Log, newest first. |
 | `preview` | The open draft's staged changes. |
 | `evaluate` | Run the live config's placement/entitlement decisions for a user context. |
-| `generate types` | Generate a TypeScript module of entitlement handles (namespaced by entitlement type) from any config version, for type-safe `can()`/`gate()` call sites. `--out <path>` writes the file; the generated header records the exact command to regenerate it. `--json` for the raw handle map. |
+| `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. |
 
 `--json` on read commands emits machine-readable output. Results go to stdout,
 diagnostics to stderr.

package/dist/cli.js

@@ -8967,7 +8967,7 @@ Account created. Enter the verification code emailed to ${opts.email}.`);
 }
 
 // src/lib/track.ts
-var CLI_UNTRACKED_COMMANDS = /* @__PURE__ */ new Set(["login", "signup", "logout", "verify"]);
+var CLI_UNTRACKED_COMMANDS = /* @__PURE__ */ new Set(["login", "signup", "logout"]);
 function shouldTrackCommandExecution(name, hasUrl) {
   return hasUrl && !CLI_UNTRACKED_COMMANDS.has(name);
 }
@@ -9750,6 +9750,13 @@ function collectSelectors(opts, positionalFiles = []) {
   if (opts.release) found.push({ kind: "release", id: opts.release });
   return found;
 }
+function orderDiffSelectors(sels) {
+  if (sels.length !== 2) return sels;
+  const [first, second] = sels;
+  if (second.kind === "live" && first.kind !== "live") return [second, first];
+  if (first.kind === "file" && second.kind !== "file") return [second, first];
+  return sels;
+}
 function describeSelector(sel) {
   switch (sel.kind) {
     case "file":
@@ -10079,7 +10086,7 @@ Command groups:
   Keys          ingest-keys create|list|revoke
 
 Version selectors (no defaults \u2014 a command that reads a config requires one):
-  <file>            a local Config File (positional, or --file <path>)
+  <file>            a local Playbook file (positional, or --file <path>)
   --draft           the tenant's single open draft (resolved automatically)
   --live            the current live Release
   --release <id>    a specific playbook version / Release
@@ -10090,13 +10097,13 @@ Common workflows:
 
   # Author, validate, and ship against the default instance (revturbine.com/app)
   revturbine login
-  revturbine download --live --save ./config.json
-  revturbine validate ./config.json
-  revturbine diff ./config.json --live
-  revturbine launch ./config.json
+  revturbine download --live --save ./revturbine.playbook.json
+  revturbine validate ./revturbine.playbook.json
+  revturbine diff ./revturbine.playbook.json --live
+  revturbine launch ./revturbine.playbook.json
 
   # Manual review flow (stage \u2192 inspect \u2192 launch)
-  revturbine upload ./config.json          # stage as the open draft
+  revturbine upload ./revturbine.playbook.json          # stage as the open draft
   revturbine preview                       # inspect the open draft
   revturbine validate --draft              # full server catalog
   revturbine launch --draft
@@ -10126,7 +10133,7 @@ program.hook("postAction", async (_thisCommand, actionCommand) => {
     command: actionCommand.name()
   });
 });
-program.name("revturbine").description("Validate RevTurbine Config Files and ship them through the playbook-version lifecycle (draft \u2192 Release).").version(`${pkgVersion} (schema ${SCHEMA_VERSION})`, "-V, --version", "Print the revturbine and bundled schema versions").option(NO_LOCAL_FLAG, "Ignore the repo-pinned CLI and run this installation").showHelpAfterError().addHelpText("after", HELP_AFTER);
+program.name("revturbine").description("Validate RevTurbine Playbooks and ship them through the playbook-version lifecycle (draft \u2192 Release).").version(`${pkgVersion} (schema ${SCHEMA_VERSION})`, "-V, --version", "Print the revturbine and bundled schema versions").option(NO_LOCAL_FLAG, "Ignore the repo-pinned CLI and run this installation").showHelpAfterError().addHelpText("after", HELP_AFTER);
 function runInstall(manager, args, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn2(manager, args, { cwd, stdio: "inherit", shell: true });
@@ -10427,7 +10434,7 @@ program.command("download").description("Fetch a config version from the server.
     }
   }
 );
-program.command("validate").description("Validate a Config File offline (schema), or the open draft against the full server catalog (--draft).").argument("[file...]", "Path(s) to a Config File (offline mode)").option("--draft", "Validate the open draft server-side (full catalog)").option("-u, --url <url>", "RevTurbine instance URL (used with --draft)", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
+program.command("validate").description("Validate a Playbook file offline (schema), or the open draft against the full server catalog (--draft).").argument("[file...]", "Path(s) to a Playbook file (offline mode)").option("--draft", "Validate the open draft server-side (full catalog)").option("-u, --url <url>", "RevTurbine instance URL (used with --draft)", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
   if (opts.draft && files.length > 0) fail(EXIT.USAGE, "validate takes either <file> or --draft, not both.");
   if (!opts.draft && files.length === 0) {
     throw new SelectorError("STATE_REQUIRED \u2014 validate needs a version: <file> (offline) or --draft (server catalog).");
@@ -10469,16 +10476,17 @@ program.command("validate").description("Validate a Config File offline (schema)
   }
   diag("\u2713 No blocking findings.");
 });
-program.command("diff").description("Compare two config versions (first \u2192 second). Dry-run, no writes.").argument("[file...]", "Local Config File path(s)").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
+program.command("diff").description("Compare two config versions (first \u2192 second; a file vs --draft/--live/--release previews the launch \u2014 the server side is the base). Dry-run, no writes.").argument("[file...]", "Local Playbook file path(s)").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
   const sels = requireSelectors(opts, files, { count: 2, allowed: ["file", "draft", "live", "release"], command: "diff" });
-  const needsServer = sels.some((s) => s.kind !== "file");
+  const ordered = orderDiffSelectors(sels);
+  const needsServer = ordered.some((s) => s.kind !== "file");
   const conn = needsServer ? connect(opts.url, opts.tenantId) : null;
-  const [a, b] = await Promise.all(sels.map((s) => loadVersion(conn, s)));
-  diag(`Diff (${sels.map((s) => s.kind === "file" ? s.path : s.kind === "release" ? `--release ${s.id}` : `--${s.kind}`).join(" \u2192 ")}):`);
+  const [a, b] = await Promise.all(ordered.map((s) => loadVersion(conn, s)));
+  diag(`Diff (${ordered.map((s) => s.kind === "file" ? s.path : s.kind === "release" ? `--release ${s.id}` : `--${s.kind}`).join(" \u2192 ")}):`);
   process.stdout.write(`${formatDiff(diffExportedConfig(a, b))}
 `);
 });
-program.command("show").description(`Render a summary view of a config version. <kind> \u2208 ${SHOW_KINDS.join(" | ")}.`).argument("<kind>", `One of: ${SHOW_KINDS.join(", ")}`).option("--file <path>", "A local Config File").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(
+program.command("show").description(`Render a summary view of a config version. <kind> \u2208 ${SHOW_KINDS.join(" | ")}.`).argument("<kind>", `One of: ${SHOW_KINDS.join(", ")}`).option("--file <path>", "A local Playbook file").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(
   async (kind, opts) => {
     if (!SHOW_KINDS.includes(kind)) {
       fail(EXIT.USAGE, `unknown kind '${kind}' \u2014 use one of: ${SHOW_KINDS.join(", ")}.`);
@@ -10493,7 +10501,7 @@ program.command("show").description(`Render a summary view of a config version.
 );
 var PRUNE_OPTION = ["--prune", "Confirm a convergent delete past the mass-deletion guard (removes entities absent from the file)"];
 var NO_PRUNE_OPTION = ["--no-prune", "Additive import \u2014 keep entities that are absent from the file (disables convergent delete)"];
-program.command("upload").description("Stage a Config File as the open draft (POST /api/config/import).").argument("<config>", "Path to a Config File").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option(...PRUNE_OPTION).option(...NO_PRUNE_OPTION).action(async (configFile2, opts) => {
+program.command("upload").description("Stage a Playbook file as the open draft (POST /api/config/import).").argument("<config>", "Path to a Playbook file").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option(...PRUNE_OPTION).option(...NO_PRUNE_OPTION).action(async (configFile2, opts) => {
   const config = verifyConfig(configFile2);
   if (config === null) fail(EXIT.VALIDATION, `Fix the issues above in ${configFile2}, then re-run.`);
   const conn = connect(opts.url, uploadTenantFor(opts.url, config, opts.tenantId));
@@ -10514,7 +10522,7 @@ program.command("upload").description("Stage a Config File as the open draft (PO
   if (playbookVersionId) diagRaw(`  playbook_version_id: ${playbookVersionId}`);
   diag("Launch it with `revturbine launch --draft`, or from the UI (Drafts & Releases).");
 });
-program.command("launch").description("Take a config live as a new Release: validate (launch gate), then submit \u2192 approve \u2192 deploy. Synchronous.").argument("[file]", "Config File to upload and launch directly").option("--draft", "Launch the already-open draft").option("--force", "Launch past incomplete-but-valid findings (error_launch); structural errors (error_draft) still block").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option(...PRUNE_OPTION).option(...NO_PRUNE_OPTION).option("--yes", "Accepted for parity with discard/restore; launch has no confirmation prompt").action(async (file, opts) => {
+program.command("launch").description("Take a config live as a new Release: validate (launch gate), then submit \u2192 approve \u2192 deploy. Synchronous.").argument("[file]", "Playbook file to upload and launch directly").option("--draft", "Launch the already-open draft").option("--force", "Launch past incomplete-but-valid findings (error_launch); structural errors (error_draft) still block").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option(...PRUNE_OPTION).option(...NO_PRUNE_OPTION).option("--yes", "Accepted for parity with discard/restore; launch has no confirmation prompt").action(async (file, opts) => {
   const [sel] = requireSelectors(opts, file ? [file] : [], { count: 1, allowed: ["file", "draft"], command: "launch" });
   let conn;
   let playbookVersionId;
@@ -10658,7 +10666,7 @@ program.command("evaluate").description("Run placement/entitlement decisions for
 var generateCmd = program.command("generate").description("Code generation from a config version (see: generate types).");
 generateCmd.command("types").description(
   "Generate a TypeScript module of Playbook handles \u2014 entitlements (namespaced by type), plans, segments, surface-template ids, and ui-path action types \u2014 for type-safe call sites."
-).argument("[file...]", "Path to a Config File").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-o, --out <path>", "Write the generated module to this path (parent dirs created); default stdout").option("--json", "Emit the handle map as JSON instead of TypeScript").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
+).argument("[file...]", "Path to a Playbook file").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-o, --out <path>", "Write the generated module to this path (parent dirs created); default stdout").option("--json", "Emit the handle map as JSON instead of TypeScript").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
   async (files, opts) => {
     const [sel] = requireSelectors(opts, files, {
       count: 1,
@@ -10728,23 +10736,23 @@ var COMMAND_EXAMPLES = {
   download: [
     "",
     "Examples:",
-    "  revturbine download --live --save ./config.json     The live config \u2192 file",
+    "  revturbine download --live --save ./revturbine.playbook.json     The live config \u2192 file",
     "  revturbine download --draft                         The open draft (rendered on demand) \u2192 stdout",
     "  revturbine download --release cs_1a2b3c --format flatbuffer --save ./bundle.fb"
   ].join("\n"),
   validate: [
     "",
     "Examples:",
-    "  revturbine validate ./config.json      Offline schema validation (no network)",
+    "  revturbine validate ./revturbine.playbook.json      Offline schema validation (no network)",
     "  revturbine validate --draft            Full server catalog against the open draft"
   ].join("\n"),
   diff: [
     "",
     "Examples:",
-    "  revturbine diff ./config.json --live   Local edits vs the live config",
+    "  revturbine diff ./revturbine.playbook.json --live   Local edits vs the live config",
     "  revturbine diff --live --draft         What the open draft would change"
   ].join("\n"),
-  show: ["", "Examples:", "  revturbine show plans --live", "  revturbine show segments --file ./config.json"].join("\n"),
+  show: ["", "Examples:", "  revturbine show plans --live", "  revturbine show segments --file ./revturbine.playbook.json"].join("\n"),
   generate: [
     "",
     "Examples:",
@@ -10756,11 +10764,11 @@ var COMMAND_EXAMPLES = {
     "entitlement type) and the `EntitlementHandle` union for can()/gate()",
     "call sites. Its header records the exact command to regenerate it."
   ].join("\n"),
-  upload: ["", "Example:", "  revturbine upload ./config.json        Stage as the open draft"].join("\n"),
+  upload: ["", "Example:", "  revturbine upload ./revturbine.playbook.json        Stage as the open draft"].join("\n"),
   launch: [
     "",
     "Examples:",
-    "  revturbine launch ./config.json        Upload, gate, and go live",
+    "  revturbine launch ./revturbine.playbook.json        Upload, gate, and go live",
     "  revturbine launch --draft              Launch the already-open draft"
   ].join("\n"),
   evaluate: [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.16.0",
-  "description": "revturbine — verify RevTurbine ExportedConfig files and ship them to a RevTurbine instance through the Change Set lifecycle.",
+  "version": "0.16.2",
+  "description": "revturbine — validate RevTurbine Playbooks and ship them to a RevTurbine instance through the playbook-version lifecycle (draft → Release).",
   "license": "MIT",
   "repository": {
     "type": "git",