@vibecheckai/cli 3.0.10 → 3.1.1

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

@@ -1,493 +1,490 @@
-/**
- * Entitlements v2 - CANONICAL Tier Enforcement
- * 
- * SINGLE SOURCE OF TRUTH for all tier gating in vibecheck CLI.
- * Every command runner MUST use this module for access control.
- * 
- * NO BYPASS ALLOWED:
- * - No owner-mode env vars
- * - No offline fallback that grants paid features
- * - No silent feature access
- * 
- * 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";
-
-const fs = require("fs");
-const path = require("path");
-const os = require("os");
-const crypto = require("crypto");
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXIT CODES
-// ═══════════════════════════════════════════════════════════════════════════════
-const EXIT_SUCCESS = 0;
-const EXIT_BLOCK_VERDICT = 2;
-const EXIT_FEATURE_NOT_ALLOWED = 3;
-const EXIT_MISCONFIG = 4;
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// 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 },
-};
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// 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");
-}
-
-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(home, ".config", "vibecheck", "config.json");
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIER COMPARISON
-// ═══════════════════════════════════════════════════════════════════════════════
-function tierMeetsMinimum(currentTier, requiredTier) {
-  const current = TIERS[currentTier]?.order ?? -1;
-  const required = TIERS[requiredTier]?.order ?? 999;
-  return current >= required;
-}
-
-function getTierLabel(tier) {
-  return TIERS[tier]?.name || tier.toUpperCase();
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// CORE API: getTier()
-// ═══════════════════════════════════════════════════════════════════════════════
-let _cachedTier = null;
-let _cachedTierExpiry = 0;
-
-async function getTier(options = {}) {
-  const { apiKey, projectPath, forceRefresh = false } = options;
-  
-  // Check cache (5 minute TTL)
-  if (!forceRefresh && _cachedTier && Date.now() < _cachedTierExpiry) {
-    return _cachedTier;
-  }
-  
-  // No API key = free tier
-  if (!apiKey) {
-    _cachedTier = "free";
-    _cachedTierExpiry = Date.now() + 300000;
-    return "free";
-  }
-  
-  // Fetch from API
-  try {
-    const res = await fetch(`${API_BASE_URL}/v1/entitlements`, {
-      method: "GET",
-      headers: { "Authorization": `Bearer ${apiKey}` },
-      signal: AbortSignal.timeout(5000),
-    });
-    
-    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;
-    }
-    
-    if (res.status === 401) {
-      return "free"; // Invalid key = free tier
-    }
-  } 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
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * 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 enforce(feature, options = {}) {
-  const { apiKey, projectPath, silent = false } = options;
-  
-  const tier = await getTier({ apiKey, projectPath });
-  const entitlement = ENTITLEMENTS[feature];
-  
-  if (!entitlement) {
-    // Unknown feature - block by default
-    return {
-      allowed: false,
-      tier,
-      exitCode: EXIT_MISCONFIG,
-      message: `Unknown feature: ${feature}`,
-    };
-  }
-  
-  const hasAccess = tierMeetsMinimum(tier, entitlement.minTier);
-  
-  if (hasAccess) {
-    // Full access
-    return {
-      allowed: true,
-      tier,
-      limits: getLimits(tier),
-      caps: entitlement.caps?.[tier] || null,
-    };
-  }
-  
-  // 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);
-      
-      if (!silent) {
-        console.log(message);
-      }
-      
-      return {
-        allowed: true,
-        tier,
-        downgrade: entitlement.downgrade,
-        limits: getLimits(tier),
-        caps,
-        message,
-      };
-    }
-  }
-  
-  // Not allowed - generate upgrade message
-  const message = formatUpgradeMessage(feature, tier, entitlement.minTier);
-  
-  if (!silent) {
-    console.error(message);
-  }
-  
-  return {
-    allowed: false,
-    tier,
-    requiredTier: entitlement.minTier,
-    exitCode: EXIT_FEATURE_NOT_ALLOWED,
-    message,
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// 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;
-  
-  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;
-  
-  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`;
-    }
-  }
-  
-  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 a command is allowed (does not print messages)
- */
-async function checkCommand(command, options = {}) {
-  return enforce(command, { ...options, silent: true });
-}
-
-/**
- * Enforce and exit if not allowed
- */
-async function enforceOrExit(feature, options = {}) {
-  const result = await enforce(feature, options);
-  if (!result.allowed) {
-    process.exit(result.exitCode);
-  }
-  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);
-    }
-  }
-  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 "Other";
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXPORTS
-// ═══════════════════════════════════════════════════════════════════════════════
-module.exports = {
-  // 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,
-};
+/**
+ * Entitlements v2 - CANONICAL Tier Enforcement
+ * 
+ * SINGLE SOURCE OF TRUTH for all tier gating in vibecheck CLI.
+ * Every command runner MUST use this module for access control.
+ * 
+ * NO BYPASS ALLOWED:
+ * - No owner-mode env vars
+ * - No offline fallback that grants paid features
+ * - No silent feature access
+ * 
+ * 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
+ * - PRO ($99/repo/mo): Full fix, prove, ai-test, share, advanced reality
+ * - COMPLETE ($199/repo/mo): Everything including permissions, graph, advanced compliance
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODES
+// ═══════════════════════════════════════════════════════════════════════════════
+const EXIT_SUCCESS = 0;
+const EXIT_BLOCK_VERDICT = 2;
+const EXIT_FEATURE_NOT_ALLOWED = 3;
+const EXIT_MISCONFIG = 4;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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 },
+  complete: { name: "COMPLETE", price: 199, order: 3 },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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: "pro" },
+  
+  // Reality testing
+  "reality": { minTier: "free", downgrade: "reality.preview" },
+  "reality.preview": { minTier: "free", caps: { free: { maxPages: 5, maxClicks: 20, noAuthBoundary: true } } },
+  "reality.full": { minTier: "pro" },
+  "reality.advanced_auth_boundary": { minTier: "complete" },
+  
+  // Prove command
+  "prove": { minTier: "pro" },
+  
+  // Fix command
+  "fix": { minTier: "free", downgrade: "fix.plan_only" },
+  "fix.plan_only": { minTier: "free" },
+  "fix.apply_patches": { minTier: "complete" },
+  
+  // Report formats
+  "report": { minTier: "free", downgrade: "report.html_md" },
+  "report.html_md": { minTier: "free" },
+  "report.sarif_csv": { minTier: "pro" },
+  "report.compliance_packs": { minTier: "complete" },
+  
+  // Setup & DX
+  "install": { minTier: "free" },
+  "init": { minTier: "free" },
+  "doctor": { minTier: "free" },
+  "status": { minTier: "free" },
+  "watch": { minTier: "free" },
+  "preflight": { minTier: "free" },
+  
+  // AI Truth
+  "ctx": { minTier: "free" },
+  "guard": { minTier: "free" },
+  "context": { minTier: "free" },
+  "mdc": { minTier: "free" },
+  
+  // PRO only
+  "replay": { minTier: "pro" },
+  "share": { minTier: "pro" },
+  "ai-test": { minTier: "pro" },
+  
+  // STARTER and above
+  "gate": { minTier: "starter" },
+  "pr": { minTier: "starter" },
+  "badge": { minTier: "starter" },
+  "launch": { minTier: "starter" },
+  "mcp": { minTier: "starter", downgrade: "mcp.help_only" },
+  "mcp.help_only": { minTier: "free", caps: { free: "help and print-config only" } },
+  
+  // COMPLETE only
+  "permissions": { minTier: "complete" },
+  "graph": { minTier: "complete" },
+  
+  // 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,
+  },
+  pro: {
+    realityMaxPages: -1, // unlimited
+    realityMaxClicks: -1,
+    realityAuthBoundary: true,
+    realityAdvancedAuth: false,
+    reportFormats: ["html", "md", "sarif", "csv"],
+    fixApplyPatches: false,
+    scansPerMonth: -1, // unlimited
+    shipChecksPerMonth: -1,
+  },
+  complete: {
+    realityMaxPages: -1,
+    realityMaxClicks: -1,
+    realityAuthBoundary: true,
+    realityAdvancedAuth: true,
+    reportFormats: ["html", "md", "sarif", "csv", "compliance"],
+    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");
+}
+
+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(home, ".config", "vibecheck", "config.json");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TIER COMPARISON
+// ═══════════════════════════════════════════════════════════════════════════════
+function tierMeetsMinimum(currentTier, requiredTier) {
+  const current = TIERS[currentTier]?.order ?? -1;
+  const required = TIERS[requiredTier]?.order ?? 999;
+  return current >= required;
+}
+
+function getTierLabel(tier) {
+  return TIERS[tier]?.name || tier.toUpperCase();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE API: getTier()
+// ═══════════════════════════════════════════════════════════════════════════════
+let _cachedTier = null;
+let _cachedTierExpiry = 0;
+
+async function getTier(options = {}) {
+  const { apiKey, projectPath, forceRefresh = false } = options;
+  
+  // Check cache (5 minute TTL)
+  if (!forceRefresh && _cachedTier && Date.now() < _cachedTierExpiry) {
+    return _cachedTier;
+  }
+  
+  // No API key = free tier
+  if (!apiKey) {
+    _cachedTier = "free";
+    _cachedTierExpiry = Date.now() + 300000;
+    return "free";
+  }
+  
+  // Fetch from API
+  try {
+    const res = await fetch(`${API_BASE_URL}/v1/entitlements`, {
+      method: "GET",
+      headers: { "Authorization": `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    
+    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;
+    }
+    
+    if (res.status === 401) {
+      return "free"; // Invalid key = free tier
+    }
+  } 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
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * 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 enforce(feature, options = {}) {
+  const { apiKey, projectPath, silent = false } = options;
+  
+  const tier = await getTier({ apiKey, projectPath });
+  const entitlement = ENTITLEMENTS[feature];
+  
+  if (!entitlement) {
+    // Unknown feature - block by default
+    return {
+      allowed: false,
+      tier,
+      exitCode: EXIT_MISCONFIG,
+      message: `Unknown feature: ${feature}`,
+    };
+  }
+  
+  const hasAccess = tierMeetsMinimum(tier, entitlement.minTier);
+  
+  if (hasAccess) {
+    // Full access
+    return {
+      allowed: true,
+      tier,
+      limits: getLimits(tier),
+      caps: entitlement.caps?.[tier] || null,
+    };
+  }
+  
+  // 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);
+      
+      if (!silent) {
+        console.log(message);
+      }
+      
+      return {
+        allowed: true,
+        tier,
+        downgrade: entitlement.downgrade,
+        limits: getLimits(tier),
+        caps,
+        message,
+      };
+    }
+  }
+  
+  // Not allowed - generate upgrade message
+  const message = formatUpgradeMessage(feature, tier, entitlement.minTier);
+  
+  if (!silent) {
+    console.error(message);
+  }
+  
+  return {
+    allowed: false,
+    tier,
+    requiredTier: entitlement.minTier,
+    exitCode: EXIT_FEATURE_NOT_ALLOWED,
+    message,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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;
+  
+  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;
+  
+  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`;
+    }
+  }
+  
+  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 a command is allowed (does not print messages)
+ */
+async function checkCommand(command, options = {}) {
+  return enforce(command, { ...options, silent: true });
+}
+
+/**
+ * Enforce and exit if not allowed
+ */
+async function enforceOrExit(feature, options = {}) {
+  const result = await enforce(feature, options);
+  if (!result.allowed) {
+    process.exit(result.exitCode);
+  }
+  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);
+    }
+  }
+  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 "Other";
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+module.exports = {
+  // 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,
+};