@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/tier-enforcement.js

@@ -0,0 +1,737 @@
+/**
+ * Bootspring Tier Enforcement
+ *
+ * Centralized tier/entitlement enforcement for the CLI.
+ * Fetches and caches entitlements from the API, enforces limits.
+ *
+ * @package bootspring
+ * @module core/tier-enforcement
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const auth = require('./auth');
+
+const BOOTSPRING_DIR = path.join(os.homedir(), '.bootspring');
+const ENTITLEMENTS_CACHE_FILE = path.join(BOOTSPRING_DIR, 'entitlements.json');
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+// Tier hierarchy for comparison
+const TIER_HIERARCHY = {
+  free: 0,
+  founder: 1,  // Founder = lifetime pro
+  pro: 1,
+  team: 2,
+  enterprise: 3,
+  custom: 3,
+};
+
+// Default limits per tier (fallback if API unavailable)
+const DEFAULT_LIMITS = {
+  free: {
+    projects: 1,
+    apiCallsPerMonth: 500,
+    devices: 1,
+    teamSeats: 1,
+    storage: '100MB',
+  },
+  founder: {
+    projects: 5,
+    apiCallsPerMonth: 10000,
+    devices: 3,
+    teamSeats: 1,
+    storage: '5GB',
+  },
+  pro: {
+    projects: 5,
+    apiCallsPerMonth: 10000,
+    devices: 3,
+    teamSeats: 1,
+    storage: '5GB',
+  },
+  team: {
+    projects: 20,
+    apiCallsPerMonth: 50000,
+    devices: 10,
+    teamSeats: 5,
+    storage: '50GB',
+  },
+  enterprise: {
+    projects: 100,
+    apiCallsPerMonth: 500000,
+    devices: 50,
+    teamSeats: 20,
+    storage: '500GB',
+  },
+  custom: {
+    projects: 999,
+    apiCallsPerMonth: 999999,
+    devices: 999,
+    teamSeats: 999,
+    storage: '1TB',
+  },
+};
+
+// Feature gates by tier
+const FEATURE_GATES = {
+  free: [
+    'agents.technical',
+    'skills.basic',
+    'workflows.basic',
+    'telemetry',
+    // Free preseed: setup, init, generate (local), sync, status, update, export
+    'preseed.setup',
+    'preseed.init',
+    'preseed.generate',
+    'preseed.sync',
+    'preseed.status',
+    'preseed.update',
+    'preseed.export',
+    // Free seed: setup, init, status, export
+    'seed.setup',
+    'seed.init',
+    'seed.status',
+    'seed.export',
+  ],
+  founder: [
+    'agents.technical',
+    'agents.business',
+    'skills.basic',
+    'skills.advanced',
+    'workflows.basic',
+    'workflows.advanced',
+    'telemetry',
+    'priority_support',
+    // Full preseed/seed access
+    'preseed.*',
+    'seed.*',
+  ],
+  pro: [
+    'agents.technical',
+    'agents.business',
+    'skills.basic',
+    'skills.advanced',
+    'workflows.basic',
+    'workflows.advanced',
+    'telemetry',
+    'priority_support',
+    // Full preseed/seed access
+    'preseed.*',
+    'seed.*',
+  ],
+  team: [
+    'agents.technical',
+    'agents.business',
+    'agents.enterprise',
+    'skills.basic',
+    'skills.advanced',
+    'skills.enterprise',
+    'workflows.basic',
+    'workflows.advanced',
+    'workflows.enterprise',
+    'telemetry',
+    'priority_support',
+    'team_features',
+    'presence',
+    // Full preseed/seed access
+    'preseed.*',
+    'seed.*',
+  ],
+  enterprise: [
+    'agents.*',
+    'skills.*',
+    'workflows.*',
+    'preseed.*',
+    'seed.*',
+    'telemetry',
+    'priority_support',
+    'team_features',
+    'presence',
+    'audit_logs',
+    'sso',
+    'custom_policies',
+  ],
+  custom: [
+    'agents.*',
+    'skills.*',
+    'workflows.*',
+    'preseed.*',
+    'seed.*',
+    'telemetry',
+    'priority_support',
+    'team_features',
+    'presence',
+    'audit_logs',
+    'sso',
+    'custom_policies',
+  ],
+};
+
+// Preseed commands that require paid tier
+const PRESEED_PAID_COMMANDS = [
+  'pull',       // Cloud sync download
+  'push',       // Cloud sync upload
+  'workflow',   // Approval workflows
+  'merge',      // Document merging
+  'start',      // Smart entry (includes merge)
+];
+
+// Seed commands that require paid tier
+const SEED_PAID_COMMANDS = [
+  'scaffold',   // Project generation
+  'synthesize', // AI synthesis from preseed
+  'generate',   // Advanced generation
+];
+
+// Agent tier requirements
+const AGENT_TIERS = {
+  // Pro tier agents
+  'business-strategy-expert': 'pro',
+  'competitive-analysis-expert': 'pro',
+  'financial-expert': 'pro',
+  'growth-expert': 'pro',
+  'legal-expert': 'pro',
+  'operations-expert': 'pro',
+  'sales-expert': 'pro',
+  // Team tier agents
+  'fundraising-expert': 'team',
+  'investor-relations-expert': 'team',
+  'partnerships-expert': 'team',
+  'private-equity-expert': 'team',
+};
+
+// Premium skill patterns (by category or specific pattern)
+const PREMIUM_SKILL_CATEGORIES = [
+  'ai',
+  'payments',
+  'security',
+  'performance',
+  'deployment',
+  'email',
+  'notifications',
+  'realtime',
+  'search',
+  'seo',
+  'files',
+  'analytics',
+];
+
+const PREMIUM_SKILL_PATTERNS = [
+  'auth/mfa',
+  'auth/rbac',
+  'database/multi-tenant',
+  'database/full-text-search',
+  'testing/e2e',
+  'testing/coverage',
+  'state/react-query',
+  'ui/command-palette',
+  'ui/data-tables',
+];
+
+// Free overrides (free even in premium category)
+const FREE_SKILL_OVERRIDES = [
+  'security/validation',
+  'deployment/docker',
+];
+
+/**
+ * Get cached entitlements
+ * @returns {object|null} Cached entitlements or null
+ */
+function getCachedEntitlements() {
+  try {
+    if (fs.existsSync(ENTITLEMENTS_CACHE_FILE)) {
+      const data = JSON.parse(fs.readFileSync(ENTITLEMENTS_CACHE_FILE, 'utf-8'));
+
+      // Check if cache is still valid
+      if (data.cachedAt && Date.now() - new Date(data.cachedAt).getTime() < CACHE_TTL_MS) {
+        return data;
+      }
+    }
+  } catch {
+    // Ignore cache read errors
+  }
+  return null;
+}
+
+/**
+ * Save entitlements to cache
+ * @param {object} entitlements - Entitlements data from API
+ */
+function cacheEntitlements(entitlements) {
+  try {
+    if (!fs.existsSync(BOOTSPRING_DIR)) {
+      fs.mkdirSync(BOOTSPRING_DIR, { recursive: true, mode: 0o700 });
+    }
+
+    const data = {
+      ...entitlements,
+      cachedAt: new Date().toISOString(),
+    };
+
+    fs.writeFileSync(ENTITLEMENTS_CACHE_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+  } catch {
+    // Ignore cache write errors
+  }
+}
+
+/**
+ * Clear entitlements cache
+ */
+function clearCache() {
+  try {
+    if (fs.existsSync(ENTITLEMENTS_CACHE_FILE)) {
+      fs.unlinkSync(ENTITLEMENTS_CACHE_FILE);
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+/**
+ * Fetch entitlements from API
+ * @returns {Promise<object|null>} Entitlements or null if not authenticated
+ */
+async function fetchEntitlements() {
+  if (!auth.isAuthenticated()) {
+    return null;
+  }
+
+  try {
+    // Lazy require to avoid circular dependency
+    const api = require('./api-client');
+    const entitlements = await api.resolveEntitlements();
+
+    // Cache the result
+    cacheEntitlements(entitlements);
+
+    // Update stored user tier if different
+    const user = auth.getUser();
+    if (user && entitlements.tier !== user.tier) {
+      const creds = auth.getCredentials();
+      if (creds) {
+        auth.saveCredentials({
+          ...creds,
+          user: { ...creds.user, tier: entitlements.tier }
+        });
+      }
+    }
+
+    return entitlements;
+  } catch (_error) {
+    // Return cached data if available, otherwise return default
+    const cached = getCachedEntitlements();
+    if (cached) return cached;
+
+    // Return minimal default entitlements
+    const tier = auth.getTier() || 'free';
+    return {
+      tier,
+      limits: DEFAULT_LIMITS[tier] || DEFAULT_LIMITS.free,
+      features: FEATURE_GATES[tier] || FEATURE_GATES.free,
+      agents: { denied: [] },
+    };
+  }
+}
+
+/**
+ * Get current entitlements (cached or fetched)
+ * @param {object} options - Options
+ * @param {boolean} options.forceRefresh - Force refresh from API
+ * @returns {Promise<object>} Entitlements
+ */
+async function getEntitlements(options = {}) {
+  // Check cache first unless force refresh
+  if (!options.forceRefresh) {
+    const cached = getCachedEntitlements();
+    if (cached) return cached;
+  }
+
+  // Fetch from API
+  const fetched = await fetchEntitlements();
+  if (fetched) return fetched;
+
+  // Fallback to defaults based on stored tier
+  const tier = auth.getTier() || 'free';
+  return {
+    tier,
+    limits: DEFAULT_LIMITS[tier] || DEFAULT_LIMITS.free,
+    features: FEATURE_GATES[tier] || FEATURE_GATES.free,
+    agents: { denied: [] },
+  };
+}
+
+/**
+ * Get current tier
+ * @returns {string} User tier
+ */
+function getTier() {
+  // Check cache first
+  const cached = getCachedEntitlements();
+  if (cached?.tier) return cached.tier;
+
+  // Fall back to stored tier
+  return auth.getTier() || 'free';
+}
+
+/**
+ * Get tier level for comparison
+ * @param {string} tier - Tier name
+ * @returns {number} Tier level
+ */
+function getTierLevel(tier) {
+  return TIER_HIERARCHY[tier?.toLowerCase()] ?? 0;
+}
+
+/**
+ * Check if user tier meets required tier
+ * @param {string} requiredTier - Required tier
+ * @param {string} userTier - User's tier (optional, uses current)
+ * @returns {boolean} Whether user meets tier requirement
+ */
+function meetsTierRequirement(requiredTier, userTier = null) {
+  const user = userTier || getTier();
+  return getTierLevel(user) >= getTierLevel(requiredTier);
+}
+
+/**
+ * Check if user can access an agent
+ * @param {string} agentId - Agent ID
+ * @returns {{allowed: boolean, requiredTier?: string, userTier: string}}
+ */
+function checkAgentAccess(agentId) {
+  const requiredTier = AGENT_TIERS[agentId];
+  const userTier = getTier();
+
+  if (!requiredTier) {
+    return { allowed: true, userTier };
+  }
+
+  return {
+    allowed: meetsTierRequirement(requiredTier, userTier),
+    requiredTier,
+    userTier,
+  };
+}
+
+/**
+ * Check if a skill/pattern is premium
+ * @param {string} skillId - Skill ID (e.g., "auth/oauth" or "external/some-skill")
+ * @returns {boolean} Whether skill is premium
+ */
+function isSkillPremium(skillId) {
+  // External skills are always premium
+  if (skillId.startsWith('external/')) {
+    return true;
+  }
+
+  // Check free overrides first
+  if (FREE_SKILL_OVERRIDES.includes(skillId)) {
+    return false;
+  }
+
+  // Check specific premium patterns
+  if (PREMIUM_SKILL_PATTERNS.includes(skillId)) {
+    return true;
+  }
+
+  // Check premium categories
+  const category = skillId.split('/')[0];
+  if (PREMIUM_SKILL_CATEGORIES.includes(category)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if user can access a skill
+ * @param {string} skillId - Skill ID
+ * @returns {{allowed: boolean, reason?: string, userTier: string}}
+ */
+function checkSkillAccess(skillId) {
+  const userTier = getTier();
+  const isPremium = isSkillPremium(skillId);
+
+  if (!isPremium) {
+    return { allowed: true, userTier };
+  }
+
+  // Premium skills require pro or higher
+  if (meetsTierRequirement('pro', userTier)) {
+    return { allowed: true, userTier };
+  }
+
+  return {
+    allowed: false,
+    reason: `This skill requires a Pro subscription. Current tier: ${userTier}`,
+    userTier,
+  };
+}
+
+/**
+ * Check if user has a specific feature
+ * @param {string} feature - Feature name (e.g., "team_features", "sso")
+ * @returns {boolean} Whether user has feature
+ */
+function hasFeature(feature) {
+  const tier = getTier();
+  const features = FEATURE_GATES[tier] || FEATURE_GATES.free;
+
+  // Check for wildcard match
+  const featureParts = feature.split('.');
+  for (const f of features) {
+    if (f === feature) return true;
+    if (f.endsWith('.*')) {
+      const prefix = f.slice(0, -2);
+      if (feature.startsWith(prefix)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get limits for current tier
+ * @returns {Promise<object>} Limits object
+ */
+async function getLimits() {
+  const entitlements = await getEntitlements();
+  return entitlements.limits || DEFAULT_LIMITS[entitlements.tier] || DEFAULT_LIMITS.free;
+}
+
+/**
+ * Check if user is within a specific limit
+ * @param {string} limitType - Limit type (projects, apiCallsPerMonth, etc.)
+ * @param {number} currentUsage - Current usage count
+ * @returns {Promise<{allowed: boolean, limit: number, usage: number, remaining: number}>}
+ */
+async function checkLimit(limitType, currentUsage) {
+  const limits = await getLimits();
+  const limit = limits[limitType] || 0;
+
+  return {
+    allowed: currentUsage < limit,
+    limit,
+    usage: currentUsage,
+    remaining: Math.max(0, limit - currentUsage),
+  };
+}
+
+/**
+ * Generate upgrade prompt for a blocked feature
+ * @param {string} feature - Feature or capability that's blocked
+ * @param {string} requiredTier - Tier required for feature
+ * @returns {string} Formatted upgrade prompt
+ */
+function getUpgradePrompt(feature, requiredTier = 'pro') {
+  const userTier = getTier();
+
+  const CYAN = '\x1b[36m';
+  const YELLOW = '\x1b[33m';
+  const DIM = '\x1b[2m';
+  const BOLD = '\x1b[1m';
+  const RESET = '\x1b[0m';
+
+  return `
+${YELLOW}${BOLD}Upgrade Required${RESET}
+
+${DIM}This feature requires ${requiredTier} tier or higher.${RESET}
+${DIM}Your current tier: ${userTier}${RESET}
+
+${BOLD}Upgrade options:${RESET}
+  ${CYAN}bootspring billing upgrade${RESET}
+
+${DIM}Or visit: https://bootspring.com/pricing${RESET}
+`;
+}
+
+/**
+ * Format tier badge for display
+ * @param {string} tier - Tier name
+ * @returns {string} Formatted badge
+ */
+function formatTierBadge(tier) {
+  const YELLOW = '\x1b[33m';
+  const GREEN = '\x1b[32m';
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+
+  switch (tier?.toLowerCase()) {
+    case 'pro':
+    case 'founder':
+      return `${YELLOW}[PRO]${RESET}`;
+    case 'team':
+      return `${CYAN}[TEAM]${RESET}`;
+    case 'enterprise':
+    case 'custom':
+      return `${CYAN}[ENT]${RESET}`;
+    default:
+      return `${GREEN}[FREE]${RESET}`;
+  }
+}
+
+/**
+ * Require a specific tier - throws if not met
+ * @param {string} requiredTier - Required tier
+ * @param {string} feature - Feature name for error message
+ * @throws {Error} If tier requirement not met
+ */
+function requireTier(requiredTier, feature = 'this feature') {
+  if (!meetsTierRequirement(requiredTier)) {
+    const error = new Error(`${feature} requires ${requiredTier} tier or higher`);
+    error.code = 'TIER_REQUIRED';
+    error.requiredTier = requiredTier;
+    error.userTier = getTier();
+    error.upgradePrompt = getUpgradePrompt(feature, requiredTier);
+    throw error;
+  }
+}
+
+/**
+ * Require a specific feature - throws if not available
+ * @param {string} feature - Feature name
+ * @throws {Error} If feature not available
+ */
+function requireFeature(feature) {
+  if (!hasFeature(feature)) {
+    const error = new Error(`${feature} is not available on your current plan`);
+    error.code = 'FEATURE_REQUIRED';
+    error.feature = feature;
+    error.userTier = getTier();
+    throw error;
+  }
+}
+
+/**
+ * Check if a preseed command requires paid tier
+ * @param {string} command - Preseed subcommand
+ * @returns {{allowed: boolean, requiredTier: string, userTier: string, feature: string}}
+ */
+function checkPreseedAccess(command) {
+  const userTier = getTier();
+  const isPaidCommand = PRESEED_PAID_COMMANDS.includes(command);
+
+  if (!isPaidCommand) {
+    return { allowed: true, requiredTier: 'free', userTier, feature: `preseed ${command}` };
+  }
+
+  // Check if user has preseed.* or specific preseed.command
+  const hasAccess = hasFeature(`preseed.${command}`) || hasFeature('preseed.*');
+
+  return {
+    allowed: hasAccess,
+    requiredTier: 'pro',
+    userTier,
+    feature: `preseed ${command}`,
+  };
+}
+
+/**
+ * Check if a seed command requires paid tier
+ * @param {string} command - Seed subcommand
+ * @returns {{allowed: boolean, requiredTier: string, userTier: string, feature: string}}
+ */
+function checkSeedAccess(command) {
+  const userTier = getTier();
+  const isPaidCommand = SEED_PAID_COMMANDS.includes(command);
+
+  if (!isPaidCommand) {
+    return { allowed: true, requiredTier: 'free', userTier, feature: `seed ${command}` };
+  }
+
+  // Check if user has seed.* or specific seed.command
+  const hasAccess = hasFeature(`seed.${command}`) || hasFeature('seed.*');
+
+  return {
+    allowed: hasAccess,
+    requiredTier: 'pro',
+    userTier,
+    feature: `seed ${command}`,
+  };
+}
+
+/**
+ * Require preseed command access - throws if not allowed
+ * @param {string} command - Preseed subcommand
+ * @throws {Error} If access not allowed
+ */
+function requirePreseedAccess(command) {
+  const access = checkPreseedAccess(command);
+  if (!access.allowed) {
+    const error = new Error(`preseed ${command} requires ${access.requiredTier} tier or higher`);
+    error.code = 'TIER_REQUIRED';
+    error.requiredTier = access.requiredTier;
+    error.userTier = access.userTier;
+    error.upgradePrompt = getUpgradePrompt(`preseed ${command}`, access.requiredTier);
+    throw error;
+  }
+}
+
+/**
+ * Require seed command access - throws if not allowed
+ * @param {string} command - Seed subcommand
+ * @throws {Error} If access not allowed
+ */
+function requireSeedAccess(command) {
+  const access = checkSeedAccess(command);
+  if (!access.allowed) {
+    const error = new Error(`seed ${command} requires ${access.requiredTier} tier or higher`);
+    error.code = 'TIER_REQUIRED';
+    error.requiredTier = access.requiredTier;
+    error.userTier = access.userTier;
+    error.upgradePrompt = getUpgradePrompt(`seed ${command}`, access.requiredTier);
+    throw error;
+  }
+}
+
+module.exports = {
+  // Cache management
+  getCachedEntitlements,
+  cacheEntitlements,
+  clearCache,
+
+  // Entitlements
+  fetchEntitlements,
+  getEntitlements,
+
+  // Tier checks
+  getTier,
+  getTierLevel,
+  meetsTierRequirement,
+  requireTier,
+
+  // Agent access
+  checkAgentAccess,
+  AGENT_TIERS,
+
+  // Skill access
+  isSkillPremium,
+  checkSkillAccess,
+  PREMIUM_SKILL_CATEGORIES,
+  PREMIUM_SKILL_PATTERNS,
+
+  // Feature access
+  hasFeature,
+  requireFeature,
+  FEATURE_GATES,
+
+  // Preseed/Seed access
+  checkPreseedAccess,
+  checkSeedAccess,
+  requirePreseedAccess,
+  requireSeedAccess,
+  PRESEED_PAID_COMMANDS,
+  SEED_PAID_COMMANDS,
+
+  // Limits
+  getLimits,
+  checkLimit,
+  DEFAULT_LIMITS,
+
+  // Display helpers
+  getUpgradePrompt,
+  formatTierBadge,
+  TIER_HIERARCHY,
+};