@revturbine/cli 0.5.0 → 0.5.2

package/dist/cli.js

@@ -7,7 +7,7 @@ import { createRequire } from "module";
 import { createInterface } from "readline/promises";
 import { spawn as spawn2 } from "child_process";
 import { Command, CommanderError, Option } from "commander";
-import { z as z27 } from "zod";
+import { z as z29 } from "zod";
 
 // src/schema/exported-config.snapshot.mjs
 import { z as z2 } from "zod";
@@ -5223,6 +5223,344 @@ var AuthSsoProviderSchema = IdField.extend({
   domain: z26.string().min(1).meta(Unrestricted23)
 }).meta({ id: "AuthSsoProvider", "x-revturbine-schema-persistence": Persisted23, "x-revturbine-schema-exposure": Internal19 });
 
+// src/schema/validators.snapshot.mjs
+import { z as z27 } from "zod";
+import { z as z28 } from "zod";
+var SeveritySchema2 = z27.enum([
+  "error_draft",
+  "error_launch",
+  "warning",
+  "ai_check"
+]);
+var CallSiteSchema = z27.enum([
+  "studio",
+  // inline studio editing / modal commit
+  "publish",
+  // the launch gate (literal kept as 'publish' — see NOTE above)
+  "ingestion",
+  // external ingestion — CLI / MCP / agents
+  "compile"
+  // compile / activate backstop
+]);
+var TargetRefSchema = z27.object({
+  object_type: z27.string().optional(),
+  object_id: z27.string().optional(),
+  field: z27.string().optional(),
+  /** Studio key the UI resolves a deep-link against. */
+  studio: z27.string().optional(),
+  /** A free-form deep-link target the UI can resolve into a URL. */
+  href: z27.string().optional(),
+  /** Zod issue path, for structural-tier findings. */
+  path: z27.array(z27.union([z27.string(), z27.number()])).optional()
+});
+var ValidationFindingSchema = z27.object({
+  /** Stable rule ID (e.g. `VAL-PLN-01`); for schema findings, the Zod issue code. */
+  code: z27.string(),
+  severity: SeveritySchema2,
+  targetRef: TargetRefSchema,
+  /** Single user-facing message — same string at the gate, modal, and CLI. */
+  message: z27.string(),
+  /** Pointer to the originating spec rule. Beta inspection aid — remove post-beta. */
+  specRef: z27.string().optional(),
+  /** Optional extended context (preserved from the old `ValidationIssue.detail`). */
+  detail: z27.string().optional(),
+  /**
+   * Set by `evaluate` when a `focus` is supplied and this finding touches the
+   * focused object — surfaces use it to spotlight inline. Never narrows what is
+   * checked (spec §3.1).
+   */
+  spotlight: z27.boolean().optional()
+});
+var CATALOG = {
+  // no-Stripe-price. Interim `warning` (does not block): a plan price that has
+  // all its billing info but is entered statically rather than synced from
+  // Stripe is valid to launch — it should warn, not block. The stricter
+  // three-way model (block if billing info is INCOMPLETE; warn if complete-but-
+  // static; pass if complete-and-Stripe-connected) is a tracked follow-up
+  // (static-pricing plan). Spec §5.3's blanket error_launch is superseded by
+  // that follow-up; see the plan.
+  "VAL-PLN-01": {
+    id: "VAL-PLN-01",
+    severity: "warning",
+    message: "Plan '{plan}' has no Stripe price linked.",
+    specRef: "optimization-studio-ui.md \xA73.1; plans-entitlements-studio-ui.md \xA72.2"
+  },
+  // entitlement-rule overlap. Origin: the `rule.overlap` check (plan 40).
+  "VAL-PLN-05": {
+    id: "VAL-PLN-05",
+    severity: "warning",
+    message: "These entitlement rules target the same plan and segment \u2014 only one will apply.",
+    specRef: "config-validation.md \xA75.3 (provisional \u2014 plan 73 Q-1)"
+  },
+  // multiple public variations. Origin: `*_variation.multiple_public`.
+  "VAL-PLN-06": {
+    id: "VAL-PLN-06",
+    severity: "error_draft",
+    message: "Only one public variation is allowed per billing period and segment.",
+    specRef: "config-validation.md \xA75.3 (provisional \u2014 plan 73 Q-1)"
+  }
+};
+function getCatalogEntry(id) {
+  return CATALOG[id];
+}
+function runSemanticRules(graph) {
+  return [
+    ...checkPlansHaveStripePrice(graph),
+    ...checkRuleOverlaps(graph),
+    ...checkPublicVariationCollisions(graph)
+  ];
+}
+function finding(catalogId, target, opts = {}) {
+  const entry = getCatalogEntry(catalogId);
+  const severity = entry?.severity ?? "warning";
+  return {
+    code: catalogId,
+    severity,
+    targetRef: target,
+    message: opts.message ?? entry?.message ?? catalogId,
+    ...entry?.specRef ? { specRef: entry.specRef } : {},
+    ...opts.detail ? { detail: opts.detail } : {}
+  };
+}
+function checkPlansHaveStripePrice(graph) {
+  const plans = graph.plans;
+  if (!plans?.length) return [];
+  const plansWithVariations = /* @__PURE__ */ new Set();
+  const pricedPlanIds = /* @__PURE__ */ new Set();
+  for (const v of graph.plan_variations ?? []) {
+    const planId = String(v.plan_id ?? "");
+    if (!planId) continue;
+    plansWithVariations.add(planId);
+    const priceId = v.stripe_price_id;
+    if (typeof priceId === "string" && priceId.length > 0) pricedPlanIds.add(planId);
+  }
+  const findings = [];
+  for (const row of plans) {
+    const planKeys = [String(row.handle ?? ""), String(row.id ?? "")].filter(Boolean);
+    const hasVariations = planKeys.some((k) => plansWithVariations.has(k));
+    if (!hasVariations) continue;
+    const hasStripePrice = planKeys.some((k) => pricedPlanIds.has(k));
+    if (hasStripePrice) continue;
+    const id = String(row.handle ?? row.id ?? "");
+    const name = String(row.name ?? id);
+    findings.push(
+      finding(
+        "VAL-PLN-01",
+        {
+          object_type: "plan",
+          object_id: id,
+          field: "plan_variations",
+          studio: "plans-entitlements"
+        },
+        {
+          message: `Plan '${name}' has no Stripe price linked.`,
+          detail: "Link a Plan Variation to a Stripe Price before activating the plan for paid customers."
+        }
+      )
+    );
+  }
+  return findings;
+}
+function checkRuleOverlaps(graph) {
+  const rules = graph.entitlement_rules;
+  if (!rules?.length) return [];
+  const segmentDimensions = /* @__PURE__ */ new Map();
+  for (const seg of graph.segments ?? []) {
+    const segId = String(seg.handle ?? seg.id ?? "");
+    const dim = typeof seg.dimension_id === "string" ? seg.dimension_id : "";
+    if (segId) segmentDimensions.set(segId, dim);
+  }
+  const sigs = [];
+  for (const rule of rules) {
+    const id = String(rule.handle ?? rule.id ?? "");
+    const targetIds = /* @__PURE__ */ new Set();
+    if (Array.isArray(rule.targets)) {
+      for (const t of rule.targets) {
+        if (t && typeof t === "object") {
+          const obj = t;
+          if (typeof obj.id === "string") {
+            const kind = typeof obj.kind === "string" ? obj.kind : "plan";
+            targetIds.add(`${kind}:${obj.id}`);
+          }
+        }
+      }
+    } else if (Array.isArray(rule.plan_ids)) {
+      for (const pid of rule.plan_ids) {
+        if (typeof pid === "string") targetIds.add(`plan:${pid}`);
+      }
+    } else if (rule.plan_id !== void 0 && rule.plan_id !== null) {
+      targetIds.add(`plan:${String(rule.plan_id)}`);
+    }
+    const segmentIds = Array.isArray(rule.segment_ids) ? rule.segment_ids.filter((s) => typeof s === "string") : [];
+    const segmentPairs = /* @__PURE__ */ new Set();
+    for (const segId of segmentIds) {
+      const dim = segmentDimensions.get(segId) ?? "";
+      segmentPairs.add(`${dim}::${segId}`);
+    }
+    sigs.push({
+      rule,
+      id,
+      targetIds,
+      segmentPairs,
+      matchesAllSegments: segmentIds.length === 0
+    });
+  }
+  const overlapping = /* @__PURE__ */ new Set();
+  for (let i = 0; i < sigs.length; i++) {
+    for (let j = i + 1; j < sigs.length; j++) {
+      const a = sigs[i];
+      const b = sigs[j];
+      let sharedTarget = false;
+      for (const t of a.targetIds) {
+        if (b.targetIds.has(t)) {
+          sharedTarget = true;
+          break;
+        }
+      }
+      if (!sharedTarget) continue;
+      let overlaps = false;
+      if (a.matchesAllSegments || b.matchesAllSegments) {
+        overlaps = true;
+      } else {
+        for (const pair of a.segmentPairs) {
+          if (b.segmentPairs.has(pair)) {
+            overlaps = true;
+            break;
+          }
+        }
+      }
+      if (overlaps) {
+        overlapping.add(i);
+        overlapping.add(j);
+      }
+    }
+  }
+  const findings = [];
+  for (const idx of overlapping) {
+    const sig = sigs[idx];
+    const name = String(sig.rule.name ?? sig.id);
+    findings.push(
+      finding(
+        "VAL-PLN-05",
+        {
+          object_type: "entitlement_rule",
+          object_id: sig.id,
+          studio: "plans-entitlements"
+        },
+        {
+          message: `Entitlement rule '${name}' overlaps another rule on a shared target and segment \u2014 only one will apply.`,
+          detail: "Where rules overlap, the most permissive value applies (plans-entitlements-studio-ui.md \xA72.3.2). Adjust the segment selection if this is unintended."
+        }
+      )
+    );
+  }
+  return findings;
+}
+function checkPublicVariationCollisions(graph) {
+  return [
+    ...collectPublicCollisions(graph.plan_variations, "plan_variation", "plan_id"),
+    ...collectPublicCollisions(graph.addon_variations, "addon_variation", "addon_id")
+  ];
+}
+function collectPublicCollisions(rows, objectType, parentField) {
+  if (!rows?.length) return [];
+  const publicByTuple = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.is_current === false) continue;
+    if (String(row.visibility ?? "public") !== "public") continue;
+    const tenant = String(row.tenant_id ?? "");
+    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 id = String(row.handle ?? row.id ?? "");
+    const bucket = publicByTuple.get(key);
+    if (bucket) bucket.ids.push(id);
+    else publicByTuple.set(key, { ids: [id], parent, period, segment });
+  }
+  const findings = [];
+  for (const bucket of publicByTuple.values()) {
+    if (bucket.ids.length < 2) continue;
+    const allIds = [...bucket.ids].sort();
+    const segmentLabel = bucket.segment === "_default" ? "no segment" : `segment ${bucket.segment}`;
+    const parentLabel = parentField === "plan_id" ? "plan" : "add-on";
+    for (const id of bucket.ids) {
+      findings.push(
+        finding(
+          "VAL-PLN-06",
+          {
+            object_type: objectType,
+            object_id: id,
+            field: "visibility",
+            studio: "plans-entitlements"
+          },
+          {
+            message: `Variation '${id}' is one of ${bucket.ids.length} marked Public for the same ${parentLabel}, billing period '${bucket.period}', and ${segmentLabel} \u2014 only one may be Public.`,
+            detail: `Set all but one of [${allIds.join(", ")}] to Unlisted or Legacy before deploying.`
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
+function fieldLabel(path3) {
+  if (!path3 || path3.length === 0) return "This value";
+  return String(path3[path3.length - 1]);
+}
+function messageForZodIssue(issue) {
+  const field = fieldLabel(issue.path);
+  switch (issue.code) {
+    case "invalid_type":
+      return issue.input === void 0 ? `${field} is required.` : `${field} must be a ${issue.expected ?? "valid value"}.`;
+    case "invalid_value":
+      return `${field} must be one of the allowed values.`;
+    case "invalid_format":
+      return `${field} isn't in a valid format.`;
+    case "too_small":
+      return `${field} is too small.`;
+    case "too_big":
+      return `${field} is too large.`;
+    case "unrecognized_keys":
+      return `${field} isn't a recognized setting.`;
+    default:
+      return issue.message ?? `${field} is invalid.`;
+  }
+}
+function targetRefForIssue(issue, basePath) {
+  const path3 = [...basePath, ...issue.path ?? []].map(
+    (seg) => typeof seg === "number" ? seg : String(seg)
+  );
+  return { path: path3 };
+}
+function zodErrorToFindings(error, opts = {}) {
+  const basePath = opts.basePath ?? [];
+  return error.issues.map((issue) => ({
+    code: issue.code ?? "invalid",
+    severity: "error_draft",
+    targetRef: targetRefForIssue(issue, basePath),
+    message: messageForZodIssue(issue),
+    ...opts.specRef ? { specRef: opts.specRef } : {}
+  }));
+}
+function spotlights(finding2, focus) {
+  if (!focus) return false;
+  const { object_type, object_id } = finding2.targetRef;
+  if (focus.object_id != null && object_id !== focus.object_id) return false;
+  if (focus.object_type != null && object_type !== focus.object_type) return false;
+  return focus.object_id != null || focus.object_type != null;
+}
+function evaluate(graph, opts = {}) {
+  const findings = [];
+  if (opts.structuralErrors) {
+    const errors = Array.isArray(opts.structuralErrors) ? opts.structuralErrors : [opts.structuralErrors];
+    for (const error of errors) findings.push(...zodErrorToFindings(error));
+  }
+  findings.push(...runSemanticRules(graph));
+  if (!opts.focus) return findings;
+  return findings.map((f) => spotlights(f, opts.focus) ? { ...f, spotlight: true } : f);
+}
+
 // src/schema/version.ts
 var SCHEMA_VERSION = "0.1.107";
 
@@ -5556,8 +5894,8 @@ function formatDiff(diff) {
 
 // src/lib/config-validate.ts
 var BLOCKING_SEVERITIES = /* @__PURE__ */ new Set(["error_draft", "error_launch"]);
-function isBlockingFinding(finding) {
-  return BLOCKING_SEVERITIES.has(finding.severity);
+function isBlockingFinding(finding2) {
+  return BLOCKING_SEVERITIES.has(finding2.severity);
 }
 function hasBlockingFindings(findings) {
   return findings.some(isBlockingFinding);
@@ -5686,6 +6024,16 @@ function requireSelectors(opts, positionalFiles, {
   return found;
 }
 
+// src/lib/version-trail.ts
+function serverSchemaIsNewer(config, bundledVersion) {
+  const server = config?.schema_version;
+  if (typeof server !== "string" || !server) return null;
+  const parse = (v) => v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [a, b] = [parse(server), parse(bundledVersion)];
+  const newer = a[0] !== b[0] ? a[0] > b[0] : a[1] !== b[1] ? a[1] > b[1] : (a[2] ?? 0) > (b[2] ?? 0);
+  return newer ? server : null;
+}
+
 // src/cli.ts
 var DOCS_URL = "https://github.com/revt-eng/revturbine-cli#readme";
 var DEFAULT_URL = "https://revturbine.com/app";
@@ -5766,11 +6114,21 @@ async function getJson(conn, pathname) {
   const json = await res.json().catch(() => ({}));
   return { res, json };
 }
+function warnIfSchemaBehind(config) {
+  const server = serverSchemaIsNewer(config, SCHEMA_VERSION);
+  if (server) {
+    diag(
+      `WARNING: the server's schema (${server}) is newer than this CLI's bundled snapshot (${SCHEMA_VERSION}) \u2014 offline validation may be missing rules. Update: npm i -g @revturbine/cli`
+    );
+  }
+}
 async function downloadConfig(conn, playbookVersionId) {
   const qs = playbookVersionId ? `?playbookVersionId=${encodeURIComponent(playbookVersionId)}` : "";
   const res = await request(conn, `/api/config/export${qs}`);
   if (!res.ok) httpFail(conn, "download", res.status);
-  return res.json().catch(() => ({}));
+  const config = await res.json().catch(() => ({}));
+  warnIfSchemaBehind(config);
+  return config;
 }
 async function requireOpenDraft(conn) {
   const { ok, status, draft } = await resolveActiveDraft(conn.url, conn.headers);
@@ -6055,7 +6413,7 @@ program.command("whoami").description("Show the resolved instance, tenant, crede
 });
 program.command("schema").description("Emit the bundled RevTurbineConfig JSON schema for an agent to author against.").option("--json", "Accepted for symmetry; output is always JSON").action(() => {
   try {
-    const jsonSchema = z27.toJSONSchema(RevTurbineConfigSchema, { unrepresentable: "any" });
+    const jsonSchema = z29.toJSONSchema(RevTurbineConfigSchema, { unrepresentable: "any" });
     emit({ schema_version: SCHEMA_VERSION, schema: jsonSchema }, true);
   } catch (err) {
     fail(EXIT.UNEXPECTED, `could not render the bundled schema (${SCHEMA_VERSION}): ${err.message}`);
@@ -6112,9 +6470,23 @@ program.command("validate").description("Validate a Config File offline (schema)
     throw new SelectorError("STATE_REQUIRED \u2014 validate needs a version: <file> (offline) or --draft (server catalog).");
   }
   if (!opts.draft) {
-    const failures = files.filter((file) => verifyConfig(file) === null).length;
-    if (files.length > 1) diag(`${files.length - failures}/${files.length} passed.`);
-    process.exit(failures > 0 ? EXIT.VALIDATION : 0);
+    let blockedFiles = 0;
+    for (const file of files) {
+      const raw = loadConfig(file);
+      const parsed = schema.safeParse(raw);
+      const findings = evaluate(parsed.success ? parsed.data : raw, {
+        structuralErrors: parsed.success ? void 0 : parsed.error
+      });
+      diag(`Validation for ${file} (offline, schema ${SCHEMA_VERSION}):`);
+      process.stdout.write(`${formatFindings(findings)}
+`);
+      if (hasBlockingFindings(findings)) blockedFiles += 1;
+    }
+    if (files.length > 1) diag(`${files.length - blockedFiles}/${files.length} passed.`);
+    if (blockedFiles > 0) {
+      fail(EXIT.VALIDATION, `${blockedFiles} file(s) have blocking findings.`);
+    }
+    process.exit(0);
   }
   const conn = connect(opts.url, opts.tenantId);
   const playbookVersionId = await requireOpenDraft(conn);

package/package.json

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