@revturbine/cli 0.13.0 → 0.14.0

package/README.md

@@ -81,6 +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. |
 
 `--json` on read commands emits machine-readable output. Results go to stdout,
 diagnostics to stderr.

package/dist/cli.js

@@ -6014,11 +6014,11 @@ function collectPublicCollisions(rows, objectType, parentField) {
     const parent = String(row[parentField] ?? "");
     const period = String(row.billing_period ?? "");
     const segment = row.segment_id == null ? "_default" : String(row.segment_id);
-    const key = `${tenant} ${parent} ${period} ${segment}`;
+    const key2 = `${tenant} ${parent} ${period} ${segment}`;
     const id = String(row.handle ?? row.id ?? "");
-    const bucket = publicByTuple.get(key);
+    const bucket = publicByTuple.get(key2);
     if (bucket) bucket.ids.push(id);
-    else publicByTuple.set(key, { ids: [id], parent, period, segment });
+    else publicByTuple.set(key2, { ids: [id], parent, period, segment });
   }
   const findings = [];
   for (const bucket of publicByTuple.values()) {
@@ -8785,9 +8785,9 @@ function getCredential(baseUrl) {
 }
 function removeCredential(baseUrl) {
   const data = read();
-  const key = urlKey(baseUrl);
-  if (!(key in data.credentials)) return false;
-  delete data.credentials[key];
+  const key2 = urlKey(baseUrl);
+  if (!(key2 in data.credentials)) return false;
+  delete data.credentials[key2];
   write(data);
   return true;
 }
@@ -9032,7 +9032,7 @@ function formatDiff(diff) {
     const parts = [];
     if (d.added.length) parts.push(`+${d.added.length} added`);
     if (d.changed.length) parts.push(`~${d.changed.length} changed`);
-    if (d.removed.length) parts.push(`-${d.removed.length} only in tenant (import never deletes)`);
+    if (d.removed.length) parts.push(`-${d.removed.length} only in tenant (pruned on launch unless --no-prune)`);
     lines.push(`  ${coll}: ${parts.join(", ")}`);
     for (const k of d.added) lines.push(`    + ${k}`);
     for (const k of d.changed) lines.push(`    ~ ${k}`);
@@ -9208,11 +9208,11 @@ async function revokeIngestKey(baseUrl, headers, id, fetchImpl = fetch) {
   });
   return { ok: res.ok, status: res.status };
 }
-function formatIngestKeyLine(key) {
-  const origins = key.originAllowlist.length ? key.originAllowlist.join(", ") : "(none)";
-  const ips = key.ipAllowlist.length ? `  ips: ${key.ipAllowlist.join(", ")}` : "";
-  const last = key.lastUsedAt ? `  last used ${key.lastUsedAt}` : "";
-  return `${key.id}  ${key.tokenPreview}  origins: ${origins}${ips}${last}`;
+function formatIngestKeyLine(key2) {
+  const origins = key2.originAllowlist.length ? key2.originAllowlist.join(", ") : "(none)";
+  const ips = key2.ipAllowlist.length ? `  ips: ${key2.ipAllowlist.join(", ")}` : "";
+  const last = key2.lastUsedAt ? `  last used ${key2.lastUsedAt}` : "";
+  return `${key2.id}  ${key2.tokenPreview}  origins: ${origins}${ips}${last}`;
 }
 
 // src/lib/delegate.ts
@@ -9280,7 +9280,7 @@ function unknownTopLevelKeys(raw) {
   const parsed = schema.safeParse(raw);
   if (!parsed.success || !isRecord3(parsed.data)) return [];
   const recognized = new Set(Object.keys(parsed.data));
-  return Object.keys(raw).filter((key) => !recognized.has(key) && !LEGACY_HEADER_ALIASES.has(key));
+  return Object.keys(raw).filter((key2) => !recognized.has(key2) && !LEGACY_HEADER_ALIASES.has(key2));
 }
 function offlineAdvisories(raw) {
   const advisories = [];
@@ -9292,12 +9292,12 @@ function offlineAdvisories(raw) {
       targetRef: { ...finding2.targetRef ?? {} }
     });
   }
-  for (const key of unknownTopLevelKeys(raw)) {
+  for (const key2 of unknownTopLevelKeys(raw)) {
     advisories.push({
       code: UNKNOWN_FIELD_CODE,
       severity: "warning",
-      message: `Unknown top-level field '${key}' is not part of the RevTurbine config schema (bundled offline snapshot). The CLI uploads it unchanged so the server can validate it \u2014 remove it if it was a typo.`,
-      targetRef: { field: key, path: [key] }
+      message: `Unknown top-level field '${key2}' is not part of the RevTurbine config schema (bundled offline snapshot). The CLI uploads it unchanged so the server can validate it \u2014 remove it if it was a typo.`,
+      targetRef: { field: key2, path: [key2] }
     });
   }
   return advisories;
@@ -9481,6 +9481,85 @@ function finalOutputLines(params) {
   return lines;
 }
 
+// src/lib/handles-codegen.ts
+var UNTYPED_GROUP = "untyped";
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function extractEntitlementHandles(config) {
+  if (!isRecord4(config) || !Array.isArray(config.entitlements)) return {};
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of config.entitlements) {
+    if (!isRecord4(entry)) continue;
+    const handle = nonEmptyString(entry.unique_handle) ?? nonEmptyString(entry.handle);
+    if (!handle) continue;
+    const type = nonEmptyString(entry.type) ?? UNTYPED_GROUP;
+    const set = groups.get(type) ?? /* @__PURE__ */ new Set();
+    set.add(handle);
+    groups.set(type, set);
+  }
+  const byType = {};
+  for (const type of [...groups.keys()].sort()) {
+    byType[type] = [...groups.get(type)].sort();
+  }
+  return byType;
+}
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var quote = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+var key = (s) => IDENTIFIER.test(s) ? s : quote(s);
+function renderHandlesModule(byType, opts) {
+  const lines = [
+    "// Generated by `revturbine generate types` \u2014 do not edit by hand.",
+    `// Source: ${opts.source}`,
+    "// Regenerate (rerun after any `launch` that changes entitlements):",
+    `//   ${opts.regenerate}`,
+    "",
+    "/** Entitlement handles, namespaced by entitlement type. */"
+  ];
+  const types = Object.keys(byType);
+  if (types.length === 0) {
+    lines.push("export const Entitlements = {} as const;");
+  } else {
+    lines.push("export const Entitlements = {");
+    for (const type of types) {
+      lines.push(`  ${key(type)}: {`);
+      for (const handle of byType[type]) {
+        lines.push(`    ${key(handle)}: ${quote(handle)},`);
+      }
+      lines.push("  },");
+    }
+    lines.push("} as const;");
+  }
+  const flat = [...new Set(types.flatMap((t) => byType[t]))].sort();
+  lines.push(
+    "",
+    "/** Every entitlement handle \u2014 the argument type for can() / gate() / checkEntitlement(). */"
+  );
+  if (flat.length === 0) {
+    lines.push("export type EntitlementHandle = never;");
+  } else {
+    lines.push("export type EntitlementHandle =");
+    flat.forEach((handle, i) => {
+      lines.push(`  | ${quote(handle)}${i === flat.length - 1 ? ";" : ""}`);
+    });
+  }
+  lines.push(
+    "",
+    "/** The entitlement-type namespaces present in this Playbook. */",
+    "export type EntitlementTypeName = keyof typeof Entitlements;",
+    ""
+  );
+  return lines.join("\n");
+}
+function generateHandleTypes(config, opts) {
+  const byType = extractEntitlementHandles(config);
+  const handles = [...new Set(Object.values(byType).flat())].sort();
+  return { byType, handles, ts: renderHandlesModule(byType, opts) };
+}
+
 // src/lib/output.ts
 var EXIT = {
   OK: 0,
@@ -9809,7 +9888,7 @@ function table(rows) {
 }
 var SHOW_KINDS = ["plans", "entitlements", "segments", "placements", "trials"];
 function renderShow(kind, config) {
-  const arr = (key) => Array.isArray(config[key]) ? config[key] : [];
+  const arr = (key2) => Array.isArray(config[key2]) ? config[key2] : [];
   const handleOf = (item) => item.handle ?? item.unique_handle ?? item.id ?? "";
   switch (kind) {
     case "plans": {
@@ -9870,6 +9949,8 @@ Command groups:
   Check         validate, diff, show
   Stage/launch  upload, launch, discard, restore
   Inspect       status, history, preview, evaluate
+  Codegen       generate types
+  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>)
@@ -10414,7 +10495,7 @@ 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 placement/slot (the getPlacement decision)").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. 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(
   async (opts) => {
     const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "evaluate" });
     const conn = connect(opts.url, opts.tenantId);
@@ -10427,13 +10508,18 @@ program.command("evaluate").description("Run placement/entitlement decisions for
     }
     const body = { ...ctx };
     if (opts.planHandle) body.plan_handle = opts.planHandle;
-    if (opts.entitlement && opts.slot) fail(EXIT.USAGE, "pass exactly one of --entitlement or --slot (or neither for the ctx file lists).");
+    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 = [];
     }
-    if (opts.slot) {
-      body.placement_ids = [opts.slot];
+    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 (sel.kind === "release") body.playbook_version_id = sel.id;
@@ -10443,25 +10529,55 @@ program.command("evaluate").description("Run placement/entitlement decisions for
     emit(json, true);
   }
 );
+var generateCmd = program.command("generate").description("Code generation from a config version (see: generate types).");
+generateCmd.command("types").description(
+  "Generate a TypeScript module of entitlement handles (namespaced by entitlement type) for type-safe can()/gate() calls."
+).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(
+  async (files, opts) => {
+    const [sel] = requireSelectors(opts, files, {
+      count: 1,
+      allowed: ["file", "draft", "live", "release"],
+      command: "generate types"
+    });
+    const conn = sel.kind !== "file" ? connect(opts.url, opts.tenantId) : null;
+    const config = await loadVersion(conn, sel);
+    const selectorArg = sel.kind === "file" ? sel.path : sel.kind === "release" ? `--release ${sel.id}` : `--${sel.kind}`;
+    const regenerate = ["revturbine generate types", selectorArg, ...opts.out ? ["--out", opts.out] : []].join(" ");
+    const result = generateHandleTypes(config, { source: describeSelector(sel), regenerate });
+    if (result.handles.length === 0) diag("No entitlement handles found in this config version.");
+    const content = opts.json ? `${JSON.stringify({ source: describeSelector(sel), entitlements: result.byType }, null, 2)}
+` : result.ts;
+    if (opts.out) {
+      const resolved = path2.resolve(opts.out);
+      mkdirSync2(path2.dirname(resolved), { recursive: true });
+      writeFileSync2(resolved, content);
+      diag(
+        `\u2713 Wrote ${result.handles.length} handle(s) across ${Object.keys(result.byType).length} type(s) to ${opts.out}`
+      );
+    } else {
+      process.stdout.write(content);
+    }
+  }
+);
 var ingestKeys = program.command("ingest-keys").description("Manage public ingest keys (embeddable SDK telemetry credentials) for the tenant.");
 ingestKeys.command("create").description("Mint a public ingest key. The full token is printed ONCE and cannot be retrieved again.").requiredOption("--origin <url...>", "Allowed browser origin(s), e.g. https://app.example.com (repeatable; at least one required)").option("--ip <cidr...>", "Optional IP / CIDR allowlist (empty = no IP restriction)").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 (token on stdout for scripted capture)").action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
   const result = await createIngestKey(conn.url, conn.headers, { originAllowlist: opts.origin, ipAllowlist: opts.ip });
   if (!result.ok || !result.key) httpFail(conn, "ingest-keys create", result.status, result.error);
-  const key = result.key;
+  const key2 = result.key;
   if (opts.json) {
-    emit(key, true);
+    emit(key2, true);
     return;
   }
   diag("\u2713 Minted a public ingest key. STORE THE TOKEN NOW \u2014 it is shown once and cannot be retrieved again.");
   emit(
-    key,
+    key2,
     false,
     [
-      `  id:      ${key.id}`,
-      `  token:   ${key.token}`,
-      `  origins: ${key.originAllowlist.join(", ")}`,
-      key.ipAllowlist.length ? `  ips:     ${key.ipAllowlist.join(", ")}` : void 0
+      `  id:      ${key2.id}`,
+      `  token:   ${key2.token}`,
+      `  origins: ${key2.originAllowlist.join(", ")}`,
+      key2.ipAllowlist.length ? `  ips:     ${key2.ipAllowlist.join(", ")}` : void 0
     ].filter((line) => Boolean(line)).join("\n")
   );
 });
@@ -10503,6 +10619,17 @@ var COMMAND_EXAMPLES = {
     "  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"),
+  generate: [
+    "",
+    "Examples:",
+    "  revturbine generate types revturbine.playbook.json --out src/revturbine-handles.ts",
+    "  revturbine generate types --live --out src/lib/revturbine-handles.gen.ts",
+    "  revturbine generate types --draft --json",
+    "",
+    "The generated module exports `Entitlements` (handles namespaced by",
+    "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"),
   launch: [
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "revturbine — verify RevTurbine ExportedConfig files and ship them to a RevTurbine instance through the Change Set lifecycle.",
   "license": "MIT",
   "repository": {