@revturbine/cli 0.13.1 → 0.15.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;
 }
@@ -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,181 @@ 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 collectStrings(values) {
+  const out = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const s = nonEmptyString(value);
+    if (s) out.add(s);
+  }
+  return [...out].sort();
+}
+function extractPlanHandles(config) {
+  if (!isRecord4(config) || !Array.isArray(config.plans)) return [];
+  return collectStrings(
+    config.plans.map(
+      (p) => isRecord4(p) ? nonEmptyString(p.unique_handle) ?? nonEmptyString(p.handle) ?? p.id : null
+    )
+  );
+}
+function extractSegmentHandles(config) {
+  if (!isRecord4(config) || !Array.isArray(config.segments)) return [];
+  return collectStrings(
+    config.segments.map((s) => isRecord4(s) ? nonEmptyString(s.handle) ?? s.id : null)
+  );
+}
+function extractSurfaceTemplateIds(config) {
+  if (!isRecord4(config)) return [];
+  const ids = [];
+  if (Array.isArray(config.surface_templates)) {
+    for (const t of config.surface_templates) {
+      if (isRecord4(t)) ids.push(t.id ?? t.template_id);
+    }
+  }
+  const surfacesOf = (payload) => {
+    if (!isRecord4(payload) || !Array.isArray(payload.surfaces)) return;
+    for (const surface of payload.surfaces) {
+      if (isRecord4(surface)) ids.push(surface.template_id);
+    }
+  };
+  if (Array.isArray(config.placements)) {
+    for (const placement of config.placements) {
+      if (!isRecord4(placement) || !Array.isArray(placement.payloads)) continue;
+      for (const payload of placement.payloads) surfacesOf(payload);
+    }
+  }
+  if (Array.isArray(config.placement_payloads)) {
+    for (const payload of config.placement_payloads) surfacesOf(payload);
+  }
+  return collectStrings(ids);
+}
+function extractUiPathActionTypes(config) {
+  if (!isRecord4(config) || !Array.isArray(config.content_ui_paths)) return [];
+  return collectStrings(
+    config.content_ui_paths.map((p) => isRecord4(p) ? p.action_type : null)
+  );
+}
+function renderFlatFamily(lines, opts) {
+  lines.push("", `/** ${opts.doc} */`);
+  if (opts.values.length === 0) {
+    lines.push(`export const ${opts.constName} = {} as const;`);
+    lines.push(`export type ${opts.typeName} = never;`);
+    return;
+  }
+  lines.push(`export const ${opts.constName} = {`);
+  for (const value of opts.values) {
+    lines.push(`  ${key(value)}: ${quote(value)},`);
+  }
+  lines.push("} as const;");
+  lines.push(`export type ${opts.typeName} =`);
+  opts.values.forEach((value, i) => {
+    lines.push(`  | ${quote(value)}${i === opts.values.length - 1 ? ";" : ""}`);
+  });
+}
+function generateHandleTypes(config, opts) {
+  const byType = extractEntitlementHandles(config);
+  const handles = [...new Set(Object.values(byType).flat())].sort();
+  const lines = [renderHandlesModule(byType, opts).trimEnd()];
+  renderFlatFamily(lines, {
+    doc: "Plan handles \u2014 the values plan targeting and planHandle options take.",
+    constName: "Plans",
+    typeName: "PlanHandle",
+    values: extractPlanHandles(config)
+  });
+  renderFlatFamily(lines, {
+    doc: "Segment handles.",
+    constName: "Segments",
+    typeName: "SegmentHandle",
+    values: extractSegmentHandles(config)
+  });
+  renderFlatFamily(lines, {
+    doc: "Surface-template ids \u2014 catalog entries plus every template a payload references.",
+    constName: "SurfaceTemplates",
+    typeName: "SurfaceTemplateId",
+    values: extractSurfaceTemplateIds(config)
+  });
+  renderFlatFamily(lines, {
+    doc: "Authored ui-path action types \u2014 exactly the key set uiPathResolvers must cover.",
+    constName: "UiPathActionTypes",
+    typeName: "UiPathActionType",
+    values: extractUiPathActionTypes(config)
+  });
+  lines.push("");
+  return { byType, handles, ts: lines.join("\n") };
+}
+
 // src/lib/output.ts
 var EXIT = {
   OK: 0,
@@ -9809,7 +9984,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 +10045,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>)
@@ -10448,25 +10625,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")
   );
 });
@@ -10508,6 +10715,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.1",
+  "version": "0.15.0",
   "description": "revturbine — verify RevTurbine ExportedConfig files and ship them to a RevTurbine instance through the Change Set lifecycle.",
   "license": "MIT",
   "repository": {