@vibecheckai/cli 3.0.7 → 3.0.9

package/bin/runners/lib/entitlements-v2.js

@@ -1,18 +1,25 @@
 /**
- * Entitlements v2 - Signed Receipts (CANONICAL)
+ * Entitlements v2 - CANONICAL Tier Enforcement
  * 
- * This is the canonical entitlements module. Use this for all new code.
+ * SINGLE SOURCE OF TRUTH for all tier gating in vibecheck CLI.
+ * Every command runner MUST use this module for access control.
  * 
- * Proper server-side metering with signed receipts:
- * 1. Every ship check requests a signed usage receipt from API
- * 2. Receipt includes: {userId, tier, remainingShipChecks, expiresAt, signature}
- * 3. CLI caches receipt in .vibecheck/.entitlements.json
- * 4. Offline grace: 24h using last valid receipt
+ * NO BYPASS ALLOWED:
+ * - No owner-mode env vars
+ * - No offline fallback that grants paid features
+ * - No silent feature access
  * 
- * Spec tiers:
- * - Free: $0, 10 ship checks/month
- * - Pro: $39/mo, unlimited ship + reality + fix + share
- * - Team: $99/mo, + PR gating + CI automation
+ * Exit Codes:
+ * - 0: Success
+ * - 2: BLOCK verdict (CI failure)
+ * - 3: Feature not allowed (upgrade required)
+ * - 4: Misconfiguration/env error
+ * 
+ * Tiers:
+ * - FREE ($0): Basic scanning and validation
+ * - STARTER ($29/repo/mo): CI gates, launch, PR, badge, MCP
+ * - PRO ($99/repo/mo): Full fix, prove, ai-test, share, advanced reality
+ * - ENTERPRISE: Custom (placeholder only)
  */
 
 "use strict";
@@ -22,362 +29,465 @@ const path = require("path");
 const os = require("os");
 const crypto = require("crypto");
 
-// Constants
-const FREE_SHIP_CHECKS_PER_MONTH = 10;
-const RECEIPT_GRACE_HOURS = 24;
-const API_BASE_URL = process.env.VIBECHECK_API_URL || "https://api.vibecheckai.dev";
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODES
+// ═══════════════════════════════════════════════════════════════════════════════
+const EXIT_SUCCESS = 0;
+const EXIT_BLOCK_VERDICT = 2;
+const EXIT_FEATURE_NOT_ALLOWED = 3;
+const EXIT_MISCONFIG = 4;
 
-// Public key for receipt verification (would be fetched from API in production)
-const VIBECHECK_PUBLIC_KEY = process.env.VIBECHECK_PUBLIC_KEY || `-----BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Z3VS5JJcds3xfn/ygWb
-rAnr6J6WvLW3YNHQZ8vJqUvBcl3L9S2gKj3wBi3M8N9pYhEj5Y5h5gJq5v5l5n5o
-placeholder-key-for-development
-AQIDAQAB
------END PUBLIC KEY-----`;
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIER DEFINITIONS - SOURCE OF TRUTH
+// ═══════════════════════════════════════════════════════════════════════════════
+const TIERS = {
+  free: { name: "FREE", price: 0, order: 0 },
+  starter: { name: "STARTER", price: 29, order: 1 },
+  pro: { name: "PRO", price: 99, order: 2 },
+  enterprise: { name: "ENTERPRISE", price: 499, order: 3 },
+};
 
-/**
- * Get entitlements cache path (project-local)
- */
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENTITLEMENTS MATRIX - SOURCE OF TRUTH
+// Format: feature -> { minTier, caps?, downgrade? }
+// ═══════════════════════════════════════════════════════════════════════════════
+const ENTITLEMENTS = {
+  // Core commands
+  "scan": { minTier: "free" },
+  "ship": { minTier: "free", caps: { free: "static-only" } },
+  "ship.static": { minTier: "free" },
+  "ship.full": { minTier: "starter" },
+  
+  // Reality testing
+  "reality": { minTier: "free", downgrade: "reality.preview" },
+  "reality.preview": { minTier: "free", caps: { free: { maxPages: 5, maxClicks: 20, noAuthBoundary: true } } },
+  "reality.full": { minTier: "starter" },
+  "reality.advanced_auth_boundary": { minTier: "pro" },
+  
+  // Prove command
+  "prove": { minTier: "pro" },
+  
+  // Fix command
+  "fix": { minTier: "free", downgrade: "fix.plan_only" },
+  "fix.plan_only": { minTier: "free" },
+  "fix.apply_patches": { minTier: "pro" },
+  
+  // Report formats
+  "report": { minTier: "free", downgrade: "report.html_md" },
+  "report.html_md": { minTier: "free" },
+  "report.sarif_csv": { minTier: "starter" },
+  "report.compliance_packs": { minTier: "pro" },
+  
+  // Setup & DX
+  "install": { minTier: "free" },
+  "init": { minTier: "free" },
+  "doctor": { minTier: "free" },
+  "status": { minTier: "free" },
+  "watch": { minTier: "free" },
+  
+  // AI Truth
+  "ctx": { minTier: "free" },
+  "guard": { minTier: "free" },
+  "context": { minTier: "free" },
+  "mdc": { minTier: "free" },
+  
+  // CI & Collaboration (STARTER+)
+  "gate": { minTier: "starter" },
+  "launch": { minTier: "starter" },
+  "pr": { minTier: "starter" },
+  "badge": { minTier: "starter" },
+  "mcp": { minTier: "starter" },
+  
+  // PRO only
+  "share": { minTier: "pro" },
+  "ai-test": { minTier: "pro" },
+  
+  // Account (always free)
+  "login": { minTier: "free" },
+  "logout": { minTier: "free" },
+  "whoami": { minTier: "free" },
+  
+  // Labs/experimental
+  "labs": { minTier: "free" },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LIMITS BY TIER
+// ═══════════════════════════════════════════════════════════════════════════════
+const LIMITS = {
+  free: {
+    realityMaxPages: 5,
+    realityMaxClicks: 20,
+    realityAuthBoundary: false,
+    reportFormats: ["html", "md"],
+    fixApplyPatches: false,
+    scansPerMonth: 50,
+    shipChecksPerMonth: 20,
+  },
+  starter: {
+    realityMaxPages: 50,
+    realityMaxClicks: 500,
+    realityAuthBoundary: true,
+    reportFormats: ["html", "md", "sarif", "csv"],
+    fixApplyPatches: false,
+    scansPerMonth: -1, // unlimited
+    shipChecksPerMonth: -1,
+  },
+  pro: {
+    realityMaxPages: -1, // unlimited
+    realityMaxClicks: -1,
+    realityAuthBoundary: true,
+    realityAdvancedAuth: true,
+    reportFormats: ["html", "md", "sarif", "csv", "compliance"],
+    fixApplyPatches: true,
+    scansPerMonth: -1,
+    shipChecksPerMonth: -1,
+  },
+  enterprise: {
+    realityMaxPages: -1,
+    realityMaxClicks: -1,
+    realityAuthBoundary: true,
+    realityAdvancedAuth: true,
+    reportFormats: ["html", "md", "sarif", "csv", "compliance", "custom"],
+    fixApplyPatches: true,
+    scansPerMonth: -1,
+    shipChecksPerMonth: -1,
+  },
+};
+
+const API_BASE_URL = process.env.VIBECHECK_API_URL || "https://api.vibecheckai.dev";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CACHE PATHS
+// ═══════════════════════════════════════════════════════════════════════════════
 function getEntitlementsCachePath(projectPath) {
   return path.join(projectPath || process.cwd(), ".vibecheck", ".entitlements.json");
 }
 
-/**
- * Get global config path (user home)
- */
 function getGlobalConfigPath() {
   const home = os.homedir();
   if (process.platform === "win32") {
-    return path.join(
-      process.env.APPDATA || path.join(home, "AppData", "Roaming"),
-      "vibecheck",
-      "config.json"
-    );
+    return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "vibecheck", "config.json");
   }
   return path.join(home, ".config", "vibecheck", "config.json");
 }
 
-/**
- * Load cached entitlements receipt
- */
-function loadCachedReceipt(projectPath) {
-  const cachePath = getEntitlementsCachePath(projectPath);
-  try {
-    if (fs.existsSync(cachePath)) {
-      return JSON.parse(fs.readFileSync(cachePath, "utf8"));
-    }
-  } catch {}
-  return null;
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIER COMPARISON
+// ═══════════════════════════════════════════════════════════════════════════════
+function tierMeetsMinimum(currentTier, requiredTier) {
+  const current = TIERS[currentTier]?.order ?? -1;
+  const required = TIERS[requiredTier]?.order ?? 999;
+  return current >= required;
 }
 
-/**
- * Save entitlements receipt to cache
- */
-function saveCachedReceipt(projectPath, receipt) {
-  const cachePath = getEntitlementsCachePath(projectPath);
-  const dir = path.dirname(cachePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  fs.writeFileSync(cachePath, JSON.stringify(receipt, null, 2), { mode: 0o600 });
+function getTierLabel(tier) {
+  return TIERS[tier]?.name || tier.toUpperCase();
 }
 
-/**
- * Verify receipt signature (HMAC-SHA256 for simplicity, RSA in production)
- */
-function verifyReceiptSignature(receipt) {
-  if (!receipt || !receipt.signature || !receipt.data) {
-    return false;
-  }
-  
-  // In production: use RSA signature verification with public key
-  // For now: use HMAC with a shared secret (server would use same secret)
-  const secret = process.env.VIBECHECK_RECEIPT_SECRET || "vibecheck-receipt-v1";
-  const dataStr = JSON.stringify(receipt.data);
-  const expectedSig = crypto.createHmac("sha256", secret).update(dataStr).digest("hex");
-  
-  return receipt.signature === expectedSig;
-}
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE API: getTier()
+// ═══════════════════════════════════════════════════════════════════════════════
+let _cachedTier = null;
+let _cachedTierExpiry = 0;
 
-/**
- * Check if receipt is within grace period
- */
-function isReceiptInGrace(receipt) {
-  if (!receipt || !receipt.data || !receipt.data.issuedAt) {
-    return false;
+async function getTier(options = {}) {
+  const { apiKey, projectPath, forceRefresh = false } = options;
+  
+  // Check cache (5 minute TTL)
+  if (!forceRefresh && _cachedTier && Date.now() < _cachedTierExpiry) {
+    return _cachedTier;
   }
   
-  const issuedAt = new Date(receipt.data.issuedAt).getTime();
-  const graceMs = RECEIPT_GRACE_HOURS * 3600 * 1000;
-  return Date.now() - issuedAt < graceMs;
-}
-
-/**
- * Get current month key (YYYY-MM)
- */
-function getCurrentMonthKey() {
-  const now = new Date();
-  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
-}
-
-/**
- * Request ship usage from server
- * Returns signed receipt with updated usage
- */
-async function requestShipUsage(apiKey, projectPath) {
+  // No API key = free tier
   if (!apiKey) {
-    return { error: "No API key" };
+    _cachedTier = "free";
+    _cachedTierExpiry = Date.now() + 300000;
+    return "free";
   }
   
+  // Fetch from API
   try {
-    const res = await fetch(`${API_BASE_URL}/v1/ship/use`, {
-      method: "POST",
-      headers: {
-        "Authorization": `Bearer ${apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        projectPath: projectPath ? path.basename(projectPath) : "unknown",
-        timestamp: new Date().toISOString()
-      }),
-      signal: AbortSignal.timeout(10000)
+    const res = await fetch(`${API_BASE_URL}/v1/entitlements`, {
+      method: "GET",
+      headers: { "Authorization": `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(5000),
     });
     
-    if (!res.ok) {
-      if (res.status === 429) {
-        return { error: "rate_limited", message: "Ship check limit reached" };
-      }
-      if (res.status === 401) {
-        return { error: "unauthorized", message: "Invalid API key" };
-      }
-      return { error: "api_error", message: `API returned ${res.status}` };
-    }
-    
-    const receipt = await res.json();
-    
-    // Validate receipt signature
-    if (!verifyReceiptSignature(receipt)) {
-      console.warn("Warning: Receipt signature invalid, proceeding with caution");
+    if (res.ok) {
+      const data = await res.json();
+      _cachedTier = data.tier || "free";
+      _cachedTierExpiry = Date.now() + 300000;
+      
+      // Cache locally
+      try {
+        const cachePath = getEntitlementsCachePath(projectPath);
+        const dir = path.dirname(cachePath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify({ tier: _cachedTier, fetchedAt: new Date().toISOString() }, null, 2));
+      } catch {}
+      
+      return _cachedTier;
     }
     
-    // Cache receipt
-    saveCachedReceipt(projectPath, receipt);
-    
-    return receipt;
-  } catch (error) {
-    // Network error - try to use cached receipt
-    const cached = loadCachedReceipt(projectPath);
-    if (cached && isReceiptInGrace(cached)) {
-      console.log("  (offline mode - using cached entitlements)");
-      return { ...cached, offline: true };
+    if (res.status === 401) {
+      return "free"; // Invalid key = free tier
     }
-    
-    return { error: "network", message: error.message };
+  } catch {
+    // Network error - check local cache
+    try {
+      const cachePath = getEntitlementsCachePath(projectPath);
+      if (fs.existsSync(cachePath)) {
+        const cached = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+        // Only use cache if less than 24 hours old
+        const fetchedAt = new Date(cached.fetchedAt).getTime();
+        if (Date.now() - fetchedAt < 24 * 3600 * 1000) {
+          return cached.tier || "free";
+        }
+      }
+    } catch {}
   }
+  
+  // Default to free (no offline bypass to paid features)
+  return "free";
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE API: getLimits()
+// ═══════════════════════════════════════════════════════════════════════════════
+function getLimits(tier) {
+  return LIMITS[tier] || LIMITS.free;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE API: enforce() - THE GATEKEEPER
+// ═══════════════════════════════════════════════════════════════════════════════
 /**
- * Check if user can run ship (main entitlement check)
+ * Enforce feature access. Returns enforcement result.
+ * 
+ * @param {string} feature - Feature key (e.g., "prove", "fix.apply_patches")
+ * @param {object} options - { apiKey?, projectPath?, silent? }
+ * @returns {object} - { allowed, tier, downgrade?, exitCode, message }
  */
-async function canShip(projectPath, options = {}) {
-  const { apiKey, skipMeter = false } = options;
+async function enforce(feature, options = {}) {
+  const { apiKey, projectPath, silent = false } = options;
   
-  // Demo/owner mode bypass
-  if (process.env.VIBECHECK_DEMO === "1" || process.env.VIBECHECK_OWNER === "1") {
+  const tier = await getTier({ apiKey, projectPath });
+  const entitlement = ENTITLEMENTS[feature];
+  
+  if (!entitlement) {
+    // Unknown feature - block by default
     return {
-      allowed: true,
-      tier: "enterprise",
-      reason: "Demo/owner mode",
-      remaining: Infinity
+      allowed: false,
+      tier,
+      exitCode: EXIT_MISCONFIG,
+      message: `Unknown feature: ${feature}`,
     };
   }
   
-  // If no API key, use free tier with local metering
-  if (!apiKey) {
-    return checkFreeTierLocal(projectPath, skipMeter);
+  const hasAccess = tierMeetsMinimum(tier, entitlement.minTier);
+  
+  if (hasAccess) {
+    // Full access
+    return {
+      allowed: true,
+      tier,
+      limits: getLimits(tier),
+      caps: entitlement.caps?.[tier] || null,
+    };
   }
   
-  // Request usage from server (meters the ship check)
-  if (!skipMeter) {
-    const receipt = await requestShipUsage(apiKey, projectPath);
-    
-    if (receipt.error) {
-      // If network error but within grace, allow
-      if (receipt.offline && receipt.data) {
-        return {
-          allowed: true,
-          tier: receipt.data.tier || "free",
-          reason: "Offline grace period",
-          remaining: receipt.data.remainingShipChecks || 0,
-          offline: true
-        };
-      }
+  // Check for downgrade option
+  if (entitlement.downgrade) {
+    const downgradeEntitlement = ENTITLEMENTS[entitlement.downgrade];
+    if (downgradeEntitlement && tierMeetsMinimum(tier, downgradeEntitlement.minTier)) {
+      // Downgrade allowed
+      const caps = downgradeEntitlement.caps?.[tier] || null;
+      const message = formatDowngradeMessage(feature, entitlement.downgrade, tier, entitlement.minTier, caps);
       
-      // Rate limited
-      if (receipt.error === "rate_limited") {
-        return {
-          allowed: false,
-          tier: "free",
-          reason: "Ship check limit reached for this month",
-          remaining: 0
-        };
+      if (!silent) {
+        console.log(message);
       }
       
-      // Other errors - fall back to free tier
-      return checkFreeTierLocal(projectPath, skipMeter);
+      return {
+        allowed: true,
+        tier,
+        downgrade: entitlement.downgrade,
+        limits: getLimits(tier),
+        caps,
+        message,
+      };
     }
-    
-    // Valid receipt from server
-    const data = receipt.data || receipt;
-    return {
-      allowed: true,
-      tier: data.tier || "pro",
-      reason: "Authenticated",
-      remaining: data.remainingShipChecks,
-      receipt
-    };
   }
   
-  // Skip meter - just check tier
-  const cached = loadCachedReceipt(projectPath);
-  if (cached && cached.data) {
-    return {
-      allowed: true,
-      tier: cached.data.tier || "pro",
-      reason: "Cached entitlements",
-      remaining: cached.data.remainingShipChecks
-    };
+  // Not allowed - generate upgrade message
+  const message = formatUpgradeMessage(feature, tier, entitlement.minTier);
+  
+  if (!silent) {
+    console.error(message);
   }
   
-  return { allowed: true, tier: "pro", reason: "API key provided" };
+  return {
+    allowed: false,
+    tier,
+    requiredTier: entitlement.minTier,
+    exitCode: EXIT_FEATURE_NOT_ALLOWED,
+    message,
+  };
 }
 
-/**
- * Check free tier with local metering (fallback)
- */
-function checkFreeTierLocal(projectPath, skipMeter = false) {
-  const cachePath = getEntitlementsCachePath(projectPath);
-  const currentMonth = getCurrentMonthKey();
+// ═══════════════════════════════════════════════════════════════════════════════
+// MESSAGING
+// ═══════════════════════════════════════════════════════════════════════════════
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  magenta: "\x1b[35m",
+};
+
+function formatUpgradeMessage(feature, currentTier, requiredTier) {
+  const tierColors = { starter: c.cyan, pro: c.magenta, enterprise: c.yellow };
+  const reqColor = tierColors[requiredTier] || c.yellow;
   
-  let usage = { month: currentMonth, shipChecks: 0 };
+  return `
+${c.red}${c.bold}⛔ Feature Not Available${c.reset}
+
+  ${c.yellow}${feature}${c.reset} requires ${reqColor}${getTierLabel(requiredTier)}${c.reset} plan.
+  Your current plan: ${c.dim}${getTierLabel(currentTier)}${c.reset}
+
+  ${c.cyan}Upgrade at:${c.reset} https://vibecheckai.dev/pricing
+
+  ${c.dim}Exit code: ${EXIT_FEATURE_NOT_ALLOWED}${c.reset}
+`;
+}
+
+function formatDowngradeMessage(feature, downgradeTo, currentTier, requiredTier, caps) {
+  const tierColors = { starter: c.cyan, pro: c.magenta, enterprise: c.yellow };
+  const reqColor = tierColors[requiredTier] || c.yellow;
   
-  try {
-    const cached = loadCachedReceipt(projectPath);
-    if (cached && cached.freeUsage && cached.freeUsage.month === currentMonth) {
-      usage = cached.freeUsage;
+  let capsStr = "";
+  if (caps) {
+    if (typeof caps === "string") {
+      capsStr = `  ${c.dim}Mode: ${caps}${c.reset}\n`;
+    } else if (typeof caps === "object") {
+      const entries = Object.entries(caps).map(([k, v]) => `${k}: ${v}`).join(", ");
+      capsStr = `  ${c.dim}Limits: ${entries}${c.reset}\n`;
     }
-  } catch {}
-  
-  const remaining = FREE_SHIP_CHECKS_PER_MONTH - usage.shipChecks;
-  
-  if (remaining <= 0) {
-    return {
-      allowed: false,
-      tier: "free",
-      reason: `Free tier limit reached (${FREE_SHIP_CHECKS_PER_MONTH}/month)`,
-      remaining: 0,
-      upgradeUrl: "https://vibecheckai.dev/pricing"
-    };
-  }
-  
-  // Increment usage if not skipping meter
-  if (!skipMeter) {
-    usage.shipChecks++;
-    try {
-      saveCachedReceipt(projectPath, {
-        freeUsage: usage,
-        data: { tier: "free", remainingShipChecks: remaining - 1 },
-        issuedAt: new Date().toISOString()
-      });
-    } catch {}
   }
   
-  return {
-    allowed: true,
-    tier: "free",
-    reason: "Free tier",
-    remaining: remaining - (skipMeter ? 0 : 1)
-  };
+  return `
+${c.yellow}${c.bold}⚠ Running in Preview Mode${c.reset}
+
+  Full ${c.yellow}${feature}${c.reset} requires ${reqColor}${getTierLabel(requiredTier)}${c.reset} plan.
+  Running ${c.green}${downgradeTo}${c.reset} instead.
+${capsStr}
+  ${c.cyan}Upgrade for full access:${c.reset} https://vibecheckai.dev/pricing
+`;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONVENIENCE HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
 /**
- * Check if user has access to a specific feature
+ * Check if a command is allowed (does not print messages)
  */
-async function hasFeatureAccess(feature, projectPath, apiKey) {
-  const entitlement = await canShip(projectPath, { apiKey, skipMeter: true });
-  
-  const featureTiers = {
-    // Free features
-    ship: ["free", "pro", "team", "enterprise"],
-    scan: ["free", "pro", "team", "enterprise"],
-    ctx: ["free", "pro", "team", "enterprise"],
-    install: ["free", "pro", "team", "enterprise"],
-    
-    // Pro features
-    reality: ["pro", "team", "enterprise"],
-    fix_autopilot: ["pro", "team", "enterprise"],
-    share: ["pro", "team", "enterprise"],
-    
-    // Team features
-    pr_gate: ["team", "enterprise"],
-    ci_automation: ["team", "enterprise"]
-  };
-  
-  const allowedTiers = featureTiers[feature] || ["enterprise"];
-  const hasAccess = allowedTiers.includes(entitlement.tier);
-  
-  return {
-    allowed: hasAccess,
-    tier: entitlement.tier,
-    requiredTier: allowedTiers[0],
-    upgradeUrl: hasAccess ? null : "https://vibecheckai.dev/pricing"
-  };
+async function checkCommand(command, options = {}) {
+  return enforce(command, { ...options, silent: true });
 }
 
 /**
- * Get usage stats for display
+ * Enforce and exit if not allowed
  */
-function getUsageStats(projectPath) {
-  const cached = loadCachedReceipt(projectPath);
-  const currentMonth = getCurrentMonthKey();
-  
-  if (!cached) {
-    return {
-      tier: "free",
-      shipChecksUsed: 0,
-      shipChecksRemaining: FREE_SHIP_CHECKS_PER_MONTH,
-      month: currentMonth
-    };
+async function enforceOrExit(feature, options = {}) {
+  const result = await enforce(feature, options);
+  if (!result.allowed) {
+    process.exit(result.exitCode);
   }
-  
-  if (cached.freeUsage && cached.freeUsage.month === currentMonth) {
-    return {
-      tier: "free",
-      shipChecksUsed: cached.freeUsage.shipChecks,
-      shipChecksRemaining: FREE_SHIP_CHECKS_PER_MONTH - cached.freeUsage.shipChecks,
-      month: currentMonth
-    };
+  return result;
+}
+
+/**
+ * Get the minimum tier required for a feature
+ */
+function getMinTierForFeature(feature) {
+  return ENTITLEMENTS[feature]?.minTier || "enterprise";
+}
+
+/**
+ * Check if tier has access to feature (sync, for help display)
+ */
+function tierHasFeature(tier, feature) {
+  const entitlement = ENTITLEMENTS[feature];
+  if (!entitlement) return false;
+  return tierMeetsMinimum(tier, entitlement.minTier);
+}
+
+/**
+ * Get all features for a tier
+ */
+function getFeaturesForTier(tier) {
+  const features = [];
+  for (const [feature, def] of Object.entries(ENTITLEMENTS)) {
+    if (tierMeetsMinimum(tier, def.minTier)) {
+      features.push(feature);
+    }
   }
-  
-  if (cached.data) {
-    return {
-      tier: cached.data.tier || "unknown",
-      shipChecksRemaining: cached.data.remainingShipChecks,
-      month: currentMonth,
-      issuedAt: cached.data.issuedAt
-    };
+  return features;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMMAND GROUPING FOR HELP DISPLAY
+// ═══════════════════════════════════════════════════════════════════════════════
+const COMMAND_GROUPS = {
+  "Proof Loop": ["scan", "ship", "reality", "prove", "fix", "report"],
+  "Setup & DX": ["install", "init", "doctor", "status", "watch", "launch"],
+  "AI Truth": ["ctx", "guard", "context", "mdc"],
+  "CI & Collaboration": ["gate", "pr", "badge"],
+  "Reporting": ["report"],
+  "Automation": ["ai-test", "mcp", "share"],
+};
+
+function getCommandGroup(command) {
+  for (const [group, commands] of Object.entries(COMMAND_GROUPS)) {
+    if (commands.includes(command)) return group;
   }
-  
-  return { tier: "unknown", month: currentMonth };
+  return "Other";
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
 module.exports = {
-  canShip,
-  hasFeatureAccess,
-  getUsageStats,
-  loadCachedReceipt,
-  saveCachedReceipt,
-  requestShipUsage,
-  FREE_SHIP_CHECKS_PER_MONTH,
-  RECEIPT_GRACE_HOURS
+  // Core API
+  getTier,
+  getLimits,
+  enforce,
+  enforceOrExit,
+  checkCommand,
+  
+  // Tier helpers
+  tierMeetsMinimum,
+  getTierLabel,
+  getMinTierForFeature,
+  tierHasFeature,
+  getFeaturesForTier,
+  
+  // Command grouping
+  COMMAND_GROUPS,
+  getCommandGroup,
+  
+  // Constants
+  TIERS,
+  ENTITLEMENTS,
+  LIMITS,
+  EXIT_SUCCESS,
+  EXIT_BLOCK_VERDICT,
+  EXIT_FEATURE_NOT_ALLOWED,
+  EXIT_MISCONFIG,
 };