@revturbine/cli 0.16.3 → 0.17.0

package/README.md

@@ -69,7 +69,7 @@ Commands that read a config name the version explicitly — there is no default:
 | `whoami` | The resolved instance, tenant, credentials source, and whether the stored token works. |
 | `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`, `--format flatbuffer`. |
+| `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. |
 | `show <kind>` | Summary tables: `plans` · `entitlements` · `segments` · `placements` · `trials` for any version. |

package/dist/cli.js

@@ -7,7 +7,7 @@ import { createRequire } from "module";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline/promises";
 import { spawn as spawn2, spawnSync } from "child_process";
-import { Command, CommanderError, Option } from "commander";
+import { Command, CommanderError } from "commander";
 import { z as z29 } from "zod";
 
 // src/schema/exported-config.snapshot.mjs
@@ -1869,7 +1869,14 @@ var ClientContextCapabilitiesSchema = z9.object({
 );
 var ClientContextPlanSchema = z9.object({
   /** The customer's current plan handle (`plans.unique_handle`). */
-  handle: z9.string().min(1).optional().meta({ ...Unrestricted6, ...ClientSafe })
+  handle: z9.string().min(1).optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  /**
+   * The plan's display name, resolved server-side from the plan record so
+   * client UI can render it without a Playbook lookup (plan 179 TASK-1 —
+   * Q-2 ruling: `{ handle, name }`). Plan names are already client-visible
+   * in every Playbook; no new exposure.
+   */
+  name: z9.string().min(1).optional().meta({ ...Unrestricted6, ...ClientSafe })
 }).meta(
   { id: "ClientContextPlan", "x-revturbine-schema-persistence": Transient6, "x-revturbine-schema-exposure": Internal5 }
 );
@@ -5940,6 +5947,18 @@ var CATALOG = {
     message: "These rules for the same entitlement target the same plan and segment \u2014 only one will apply.",
     specRef: "config-validation.md \xA75.3 (provisional \u2014 plan 73 Q-1)"
   },
+  // limit rule with unset enforcement. Promoted from §5.8 (plan 179 Q-6,
+  // Kent 2026-08-12): unset enforcement silently means "hard-block at the
+  // cap" (evaluator default since plan 34) — an author who wanted degrade or
+  // allow_overage gets a hard stop without being told. Explicitness warn on
+  // the corrected premise (the old "never blocks" mechanism was the SDK
+  // ignoring allowed:false, fixed in sdk 0.2.75).
+  "VAL-PLN-07": {
+    id: "VAL-PLN-07",
+    severity: "warning",
+    message: "This limit rule sets no enforcement \u2014 at the cap it blocks by default. Set enforcement explicitly (hard_block, soft_block, degrade, allow_overage) if that isn't the intent.",
+    specRef: "config-validation.md \xA75.8 (promoted \u2014 plan 179 Q-6)"
+  },
   // multiple public variations. Origin: `*_variation.multiple_public`.
   "VAL-PLN-06": {
     id: "VAL-PLN-06",
@@ -5976,11 +5995,33 @@ function runSemanticRules(graph) {
   return [
     ...checkPlansHaveStripePrice(graph),
     ...checkRuleOverlaps(graph),
+    ...checkLimitRuleEnforcement(graph),
     ...checkPublicVariationCollisions(graph),
     ...checkPayloadCtaOverflow(graph),
     ...checkTrialRuleWidestAudience(graph)
   ];
 }
+function checkLimitRuleEnforcement(graph) {
+  const findings = [];
+  const CAP_FIELDS = ["limit_value", "allowance_value", "included_count"];
+  for (const rule of graph.entitlement_rules ?? []) {
+    if (rule.enforcement !== void 0 && rule.enforcement !== null) continue;
+    const cappedField = CAP_FIELDS.find((f) => typeof rule[f] === "number" && Number.isFinite(rule[f]));
+    if (!cappedField) continue;
+    const id = String(rule.handle ?? rule.id ?? "");
+    const name = String(rule.name ?? id);
+    findings.push(
+      finding(
+        "VAL-PLN-07",
+        { object_type: "entitlement_rule", object_id: id, field: "enforcement", studio: "plans-entitlements" },
+        {
+          message: `Limit rule '${name}' sets no enforcement \u2014 at the cap it blocks by default. Set enforcement explicitly (hard_block, soft_block, degrade, allow_overage) if that isn't the intent.`
+        }
+      )
+    );
+  }
+  return findings;
+}
 function surfaceCtas(surface) {
   if (!surface || typeof surface !== "object") return 0;
   const ctas = surface.ctas;
@@ -8923,7 +8964,7 @@ function repairDeprecatedFields(config, schema = PlaybookObjectSchema2) {
 }
 
 // src/schema/version.ts
-var SCHEMA_VERSION = "0.1.167";
+var SCHEMA_VERSION = "0.1.168";
 
 // src/lib/credentials.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -9364,6 +9405,34 @@ async function resolveActiveDraft(baseUrl, headers, fetchImpl = fetch) {
   return { ok: res.ok, status: res.status, draft: res.ok ? json.active ?? null : null };
 }
 
+// src/lib/evaluate-local.ts
+import { initRevTurbine } from "@revturbine/sdk/headless";
+async function evaluateLocal(config, input) {
+  const user = { id: input.userId };
+  if (input.planHandle) user.plan_handle = input.planHandle;
+  if (input.traits && Object.keys(input.traits).length > 0) user.custom = input.traits;
+  const session = await initRevTurbine({
+    user,
+    localRuntime: { playbook: config }
+  });
+  const entitlements = {};
+  for (const handle of input.entitlementHandles ?? []) {
+    entitlements[handle] = await session.checkEntitlement(handle);
+  }
+  const decisions = [];
+  for (const placementId of input.placementIds ?? []) {
+    const controller = session.placement({ placement: { name: placementId } });
+    await controller.load();
+    decisions.push(controller.state.decision);
+  }
+  const placement = input.slot && (input.slot.slotId || input.slot.surfaceType) ? await session.getPlacement({
+    ...input.slot.slotId ? { slotId: input.slot.slotId } : {},
+    ...input.slot.surfaceType ? { surfaceType: input.slot.surfaceType } : {},
+    ...input.planHandle ? { planHandle: input.planHandle } : {}
+  }) : null;
+  return { decisions, entitlements, placement };
+}
+
 // src/lib/ingest-keys.ts
 async function readJson(res) {
   return await res.json().catch(() => ({}));
@@ -10611,27 +10680,11 @@ program.command("docs").description("Print the canonical documentation URL (and
     }
   }
 });
-program.command("download").description("Fetch a config version from the server. Requires --live, --draft, or --release <id>.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--draft", "The tenant's open draft (rendered on demand)").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").addOption(new Option("-f, --format <format>", "Representation").choices(["json", "flatbuffer"]).default("json")).option("--save <file>", "Write to <file> instead of stdout").action(
+program.command("download").description("Fetch a config version from the server. Requires --live, --draft, or --release <id>.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--draft", "The tenant's open draft (rendered on demand)").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("--save <file>", "Write to <file> instead of stdout").action(
   async (opts) => {
     const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "download" });
     const conn = connect(opts.url, opts.tenantId);
     const playbookVersionId = sel.kind === "release" ? sel.id : sel.kind === "draft" ? await requireOpenDraft(conn) : void 0;
-    if (opts.format === "flatbuffer") {
-      const qs = playbookVersionId ? `?playbookVersionId=${encodeURIComponent(playbookVersionId)}` : "";
-      const res = await request(conn, `/api/config/bundle${qs}`);
-      if (!res.ok) httpFail(conn, "bundle download", res.status);
-      const bytes = Buffer.from(await res.arrayBuffer());
-      if (opts.save) {
-        const out2 = path2.resolve(opts.save);
-        mkdirSync2(path2.dirname(out2), { recursive: true });
-        writeFileSync2(out2, bytes);
-        diag(`\u2713 Wrote ${bytes.length} bytes \u2192 ${out2}`);
-      } else {
-        process.stdout.write(`${bytes.toString("base64")}
-`);
-      }
-      return;
-    }
     const config = await downloadConfig(conn, playbookVersionId);
     diag(`Downloaded: ${describePlaybookHeader(readPlaybookHeader(config))}`);
     const out = `${JSON.stringify(config, null, 2)}
@@ -10841,7 +10894,9 @@ program.command("preview").description("The open draft's Runtime Impact summary
   ].join("\n");
   emit(data, Boolean(opts.json), text);
 });
-program.command("evaluate").description("Run placement/entitlement decisions for a user context against a config version. Requires --live, --draft, or --release <id>.").option("--live", "Evaluate the live configuration").option("--draft", "Evaluate the tenant's open draft (clean-room: no suppression/cap history)").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--surface-type <type>", "Disambiguate a slot that can render more than one surface (with --slot), or resolve by surface type alone").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
+program.command("evaluate").description(
+  "Run placement/entitlement decisions for a user context against a config version \u2014 evaluated LOCALLY: the CLI fetches the version's Playbook and runs the SDK engine in-process (plan 192; clean-room, no suppression/cap history). Requires --live, --draft, or --release <id>."
+).option("--live", "Evaluate the live (deployed) configuration").option("--draft", "Evaluate the tenant's open draft").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--surface-type <type>", "Disambiguate a slot that can render more than one surface (with --slot), or resolve by surface type alone").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
   async (opts) => {
     const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "evaluate" });
     const conn = connect(opts.url, opts.tenantId);
@@ -10852,27 +10907,48 @@ program.command("evaluate").description("Run placement/entitlement decisions for
     } catch (err) {
       fail(EXIT.VALIDATION, `invalid JSON in ${opts.user}: ${err.message}`);
     }
-    const body = { ...ctx };
-    if (opts.planHandle) body.plan_handle = opts.planHandle;
     const wantsSlot = Boolean(opts.slot || opts.surfaceType);
     if (opts.entitlement && wantsSlot) {
       fail(EXIT.USAGE, "pass exactly one of --entitlement or --slot/--surface-type (or neither for the ctx file lists).");
     }
-    if (opts.entitlement) {
-      body.entitlement_handles = [opts.entitlement];
-      body.placement_ids = [];
+    const userId = typeof ctx.user_id === "string" && ctx.user_id.length > 0 ? ctx.user_id : void 0;
+    if (!userId) fail(EXIT.VALIDATION, `user file must carry a non-empty string "user_id" (${opts.user})`);
+    if (typeof ctx.now_iso === "string") {
+      diag("WARNING: now_iso is ignored \u2014 local evaluation uses the real clock.");
     }
-    if (wantsSlot) {
-      if (opts.slot) body.slot_id = opts.slot;
-      if (opts.surfaceType) body.surface_type = opts.surfaceType;
-      body.placement_ids = [];
-      body.entitlement_handles = [];
+    if (typeof ctx.customer_id === "string") {
+      diag(
+        "WARNING: customer_id is ignored \u2014 supply plan_handle in the ctx file (or --plan-handle). The server-side customer\u2192plan lookup was retired with the decision endpoint (plan 192)."
+      );
     }
-    if (sel.kind === "release") body.playbook_version_id = sel.id;
-    if (sel.kind === "draft") body.playbook_version_id = await requireOpenDraft(conn);
-    const { res, json } = await postJson(conn, "/api/sdk/evaluate", body);
-    if (!res.ok) httpFail(conn, "evaluate", res.status, json);
-    emit(json, true);
+    let playbookVersionId;
+    if (sel.kind === "release") playbookVersionId = sel.id;
+    if (sel.kind === "draft") playbookVersionId = await requireOpenDraft(conn);
+    const config = await downloadConfig(conn, playbookVersionId);
+    const planHandle = opts.planHandle ?? (typeof ctx.plan_handle === "string" ? ctx.plan_handle : void 0);
+    const bulk = !opts.entitlement && !wantsSlot;
+    const asStringArray2 = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+    const traits = typeof ctx.traits === "object" && ctx.traits !== null && !Array.isArray(ctx.traits) ? ctx.traits : void 0;
+    const result = await evaluateLocal(config, {
+      userId,
+      planHandle,
+      traits,
+      entitlementHandles: opts.entitlement ? [opts.entitlement] : bulk ? asStringArray2(ctx.entitlement_handles) : [],
+      placementIds: bulk ? asStringArray2(ctx.placement_ids) : [],
+      slot: wantsSlot ? { slotId: opts.slot, surfaceType: opts.surfaceType } : void 0
+    });
+    emit(
+      {
+        tenant_id: conn.tenantId,
+        user_id: userId,
+        ...playbookVersionId ? { playbook_version_id: playbookVersionId } : {},
+        evaluated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        // Provenance: decided in-process by the SDK engine, not by a server.
+        evaluation: "local",
+        ...result
+      },
+      true
+    );
   }
 );
 var generateCmd = program.command("generate").description("Code generation from a config version (see: generate types).");
@@ -10950,7 +11026,7 @@ var COMMAND_EXAMPLES = {
     "Examples:",
     "  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"
+    "  revturbine download --release cs_1a2b3c --save ./release.playbook.json"
   ].join("\n"),
   validate: [
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "revturbine — validate RevTurbine Playbooks and ship them to a RevTurbine instance through the playbook-version lifecycle (draft → Release).",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,6 @@
   "scripts": {
     "build": "tsup",
     "generate:schema": "node scripts/generate-schema-snapshot.mjs",
-    "revt:sync": "node scripts/sync-revt-deps.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "eslint .",
@@ -31,6 +30,7 @@
     "verify": "npm run typecheck && npm run lint && npm run check:schema && npm run test"
   },
   "dependencies": {
+    "@revturbine/sdk": "^0.2.88",
     "commander": "^15.0.0",
     "zod": "4.4.3"
   },