@revturbine/cli 0.4.0 → 0.5.1

package/README.md

@@ -63,7 +63,7 @@ Commands that read a config name the version explicitly — there is no default:
 | `upload` | Stage a Config 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`). |
-| `rollback` | Revert a deployed playbook version (creates a reverting draft; becomes `restore` once server-side entry copying lands). |
+| `restore` | Stage a draft that restores a past release from its frozen snapshot; `--launch` takes it live. Halts if a draft is open. |
 | `status` | The live Release and the open draft, side by side. |
 | `history` | The Release Version Log, newest first. |
 | `preview` | The open draft's staged changes. |

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);
@@ -5890,7 +6228,7 @@ Command groups:
   Auth & meta   login, logout, signup, whoami, schema, docs
   Download      download
   Check         validate, diff, show
-  Stage/launch  upload, launch, discard, rollback
+  Stage/launch  upload, launch, discard, restore
   Inspect       status, history, preview, evaluate
 
 Version selectors (no defaults \u2014 a command that reads a config requires one):
@@ -5916,7 +6254,7 @@ Common workflows:
   # Inspect and roll back
   revturbine status
   revturbine history
-  revturbine rollback <playbook-version-id>
+  revturbine restore <playbook-version-id> --launch
 
 Exit-code classes: 0 ok \xB7 1 unexpected \xB7 2 usage \xB7 3 auth \xB7 4 validation
 blocked \xB7 5 conflict/stale \xB7 6 network \xB7 7 server error.
@@ -5924,7 +6262,7 @@ blocked \xB7 5 conflict/stale \xB7 6 network \xB7 7 server error.
 Auth:
   Most commands need a token \u2014 run \`login\` first. Credentials live at
   ~/.revturbine/credentials.json (0600); the token's tenant is used by default,
-  override with -t/--tenant-id. Mutating commands (discard, rollback) prompt
+  override with -t/--tenant-id. Mutating commands (discard, restore) prompt
   for confirmation unless --yes.
 
 Full reference: ${DOCS_URL}
@@ -6055,7 +6393,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 +6450,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);
@@ -6172,7 +6524,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("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Accepted for parity with discard/rollback; 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]", "Config File to upload and launch directly").option("--draft", "Launch the already-open draft").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").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" });
   const conn = connect(opts.url, opts.tenantId);
   let playbookVersionId;
@@ -6201,17 +6553,22 @@ program.command("discard").description("Discard (archive) the open draft so a fr
   if (!res.ok) httpFail(conn, "discard", res.status, json);
   diag(`\u2713 Discarded draft ${playbookVersionId}.`);
 });
-program.command("rollback").description("Roll back a deployed playbook version (creates a reverting draft). Becomes `restore <release>` once server-side entry copying lands (plan 131 TASK-6).").argument("<playbook-version-id>", "The deployed playbook_version_id to revert").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (playbookVersionId, opts) => {
+program.command("restore").description("Stage a draft that restores a past release (from its frozen snapshot); `--launch` takes it live. Halts if a draft is already open.").argument("<playbook-version-id>", "The deployed playbook version to restore (see `history`)").option("--launch", "Launch the restoring draft immediately (gate + submit \u2192 approve \u2192 deploy)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (playbookVersionId, opts) => {
   const conn = connect(opts.url, opts.tenantId);
   await confirmOrExit(
-    `Roll back playbook version ${playbookVersionId} on ${conn.url}? This changes the LIVE configuration.`,
+    `Restore playbook version ${playbookVersionId} on ${conn.url}?${opts.launch ? " --launch will take it LIVE." : " (stages a draft; launch separately)"}`,
     !!opts.yes
   );
   const { res, json } = await postJson(conn, `/api/playbook-versions/${playbookVersionId}/rollback`, {});
-  if (!res.ok) httpFail(conn, "rollback", res.status, json);
-  diag(`\u2713 Rollback requested for playbook version ${playbookVersionId}.`);
+  if (!res.ok) httpFail(conn, "restore", res.status, json);
   const reverting = json?.item?.id ?? json?.playbook_version_id;
-  if (reverting) diagRaw(`  reverting draft: ${reverting}`);
+  diag(`\u2713 Staged a restoring draft from ${playbookVersionId}${reverting ? ` (${reverting})` : ""}.`);
+  if (!opts.launch) {
+    diag("Launch it with `revturbine launch --draft`, or discard it with `revturbine discard --yes`.");
+    return;
+  }
+  if (!reverting) fail(EXIT.SERVER, "No reverting draft id returned \u2014 cannot launch.");
+  await launchDraft(conn, reverting);
 });
 program.command("status").description("The current live Release and the open draft, side by side.").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 (opts) => {
   const conn = connect(opts.url, opts.tenantId);

package/package.json

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