aios-core 4.2.13 → 4.2.15

package/pro/license/feature-gate.js

@@ -1,354 +1,354 @@
-/**
- * Feature Gate Module
- *
- * Singleton class that validates feature availability based on license cache.
- * Supports exact feature ID matching and wildcard patterns.
- *
- * Usage:
- *   const { featureGate } = require('./feature-gate');
- *
- *   // Check availability
- *   if (featureGate.isAvailable('pro.squads.premium')) {
- *     // Feature is licensed
- *   }
- *
- *   // Require feature (throws if not available)
- *   featureGate.require('pro.squads.premium', 'Premium Squads');
- *
- * @module pro/license/feature-gate
- * @see ADR-PRO-003 - Feature Gating & Licensing
- * @see Story PRO-6 - License Key & Feature Gating System
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('yaml');
-const { readLicenseCache, isExpired, isInGracePeriod, getLicenseState } = require('./license-cache');
-const { ProFeatureError } = require('./errors');
-
-/**
- * Path to the feature registry YAML file.
- */
-const REGISTRY_PATH = path.join(__dirname, '..', 'feature-registry.yaml');
-
-/**
- * FeatureGate class - validates feature availability.
- *
- * Singleton pattern ensures consistent state across the application.
- */
-class FeatureGate {
-  constructor() {
-    this._cache = null;
-    this._licensedFeatures = new Set();
-    this._registeredFeatures = new Map();
-    this._lastLoadTime = null;
-    this._cacheLoaded = false;
-    this._registryLoaded = false;
-  }
-
-  /**
-   * Load the feature registry from YAML.
-   *
-   * @private
-   */
-  _loadRegistry() {
-    if (this._registryLoaded) {
-      return;
-    }
-
-    try {
-      if (fs.existsSync(REGISTRY_PATH)) {
-        const content = fs.readFileSync(REGISTRY_PATH, 'utf8');
-        const registry = yaml.parse(content);
-
-        // Extract all features from modules
-        const modules = ['squads', 'memory', 'metrics', 'integrations', 'agents', 'cli', 'config'];
-
-        for (const module of modules) {
-          if (registry[module] && Array.isArray(registry[module])) {
-            for (const feature of registry[module]) {
-              this._registeredFeatures.set(feature.id, {
-                id: feature.id,
-                name: feature.name,
-                description: feature.description,
-                module: feature.module,
-              });
-            }
-          }
-        }
-
-        this._registryLoaded = true;
-      }
-    } catch {
-      // Registry load failed, features will still work via license patterns
-      this._registryLoaded = true;
-    }
-  }
-
-  /**
-   * Load the license cache and populate licensed features.
-   *
-   * @private
-   * @param {boolean} [force=false] - Force reload even if already loaded
-   */
-  _loadCache(force = false) {
-    if (this._cacheLoaded && !force) {
-      return;
-    }
-
-    // Load registry if not loaded
-    this._loadRegistry();
-
-    // Read license cache
-    this._cache = readLicenseCache();
-    this._licensedFeatures.clear();
-    this._lastLoadTime = Date.now();
-
-    if (!this._cache) {
-      this._cacheLoaded = true;
-      return;
-    }
-
-    // Check if cache is valid (not expired, or in grace period)
-    const state = getLicenseState(this._cache);
-
-    if (state === 'Expired') {
-      // Expired and past grace period - no features available
-      // Keep cache reference so getLicenseState can report 'Expired'
-      this._cacheLoaded = true;
-      return;
-    }
-
-    // Populate licensed features from cache
-    if (this._cache.features && Array.isArray(this._cache.features)) {
-      for (const featurePattern of this._cache.features) {
-        this._licensedFeatures.add(featurePattern);
-      }
-    }
-
-    this._cacheLoaded = true;
-  }
-
-  /**
-   * Check if a feature pattern matches a feature ID using wildcard matching.
-   *
-   * Supports:
-   * - Exact match: "pro.squads.premium" matches "pro.squads.premium"
-   * - Wildcard: "pro.squads.*" matches "pro.squads.premium", "pro.squads.custom"
-   * - Module wildcard: "pro.*" matches any pro feature
-   *
-   * @private
-   * @param {string} featureId - Feature ID to check
-   * @param {string} pattern - Pattern from license
-   * @returns {boolean} true if pattern matches feature ID
-   */
-  _matchWildcard(featureId, pattern) {
-    // Exact match
-    if (pattern === featureId) {
-      return true;
-    }
-
-    // Wildcard match: "pro.*" matches "pro.squads.premium"
-    if (pattern.endsWith('.*')) {
-      const prefix = pattern.slice(0, -1); // Remove trailing * → "pro."
-      return featureId.startsWith(prefix);
-    }
-
-    // BUG-7 fix (INS-1): Bare module pattern without dots (e.g., "pro")
-    // should match all features under that module (equivalent to "pro.*")
-    if (!pattern.includes('.') && featureId.startsWith(pattern + '.')) {
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Check if a feature is available (licensed).
-   *
-   * Performance: < 5ms (cache read only, per AC-13)
-   *
-   * @param {string} featureId - Feature ID to check (e.g., "pro.squads.premium")
-   * @returns {boolean} true if feature is licensed and available
-   */
-  isAvailable(featureId) {
-    this._loadCache();
-
-    if (this._licensedFeatures.size === 0) {
-      return false;
-    }
-
-    // Check direct match first (O(1))
-    if (this._licensedFeatures.has(featureId)) {
-      return true;
-    }
-
-    // Check wildcard patterns
-    for (const pattern of this._licensedFeatures) {
-      if (this._matchWildcard(featureId, pattern)) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Require a feature to be available, throw if not.
-   *
-   * Use this to gate premium functionality:
-   *
-   *   featureGate.require('pro.squads.premium', 'Premium Squads');
-   *
-   * @param {string} featureId - Feature ID to require
-   * @param {string} [friendlyName] - Human-friendly feature name for error message
-   * @throws {ProFeatureError} If feature is not licensed
-   */
-  require(featureId, friendlyName) {
-    if (!this.isAvailable(featureId)) {
-      const name = friendlyName || this._getFeatureName(featureId) || featureId;
-      throw new ProFeatureError(featureId, name);
-    }
-  }
-
-  /**
-   * Get the friendly name of a feature from registry.
-   *
-   * @private
-   * @param {string} featureId - Feature ID
-   * @returns {string|null} Feature name or null
-   */
-  _getFeatureName(featureId) {
-    this._loadRegistry();
-    const feature = this._registeredFeatures.get(featureId);
-    return feature ? feature.name : null;
-  }
-
-  /**
-   * List all available (licensed) feature IDs.
-   *
-   * Returns the resolved list of feature IDs, expanding wildcards
-   * against the registry.
-   *
-   * @returns {string[]} Array of available feature IDs
-   */
-  listAvailable() {
-    this._loadCache();
-    this._loadRegistry();
-
-    const available = new Set();
-
-    // Check each registered feature against licensed patterns
-    for (const [featureId] of this._registeredFeatures) {
-      if (this.isAvailable(featureId)) {
-        available.add(featureId);
-      }
-    }
-
-    return Array.from(available).sort();
-  }
-
-  /**
-   * List all registered features with their availability status.
-   *
-   * @returns {Array<{ id: string, name: string, description: string, module: string, available: boolean }>}
-   */
-  listAll() {
-    this._loadCache();
-    this._loadRegistry();
-
-    const features = [];
-
-    for (const [featureId, feature] of this._registeredFeatures) {
-      features.push({
-        ...feature,
-        available: this.isAvailable(featureId),
-      });
-    }
-
-    return features.sort((a, b) => a.id.localeCompare(b.id));
-  }
-
-  /**
-   * List features grouped by module.
-   *
-   * @returns {Object<string, Array<{ id: string, name: string, available: boolean }>>}
-   */
-  listByModule() {
-    const all = this.listAll();
-    const grouped = {};
-
-    for (const feature of all) {
-      if (!grouped[feature.module]) {
-        grouped[feature.module] = [];
-      }
-      grouped[feature.module].push(feature);
-    }
-
-    return grouped;
-  }
-
-  /**
-   * Force reload of the license cache.
-   *
-   * Call this after activation to pick up new features.
-   */
-  reload() {
-    this._cacheLoaded = false;
-    this._loadCache(true);
-  }
-
-  /**
-   * Get the current license state.
-   *
-   * @returns {'Active'|'Expired'|'Grace'|'Not Activated'} License state
-   */
-  getLicenseState() {
-    this._loadCache();
-    return getLicenseState(this._cache);
-  }
-
-  /**
-   * Get license information for display.
-   *
-   * @returns {{ state: string, features: string[], inGrace: boolean } | null}
-   */
-  getLicenseInfo() {
-    this._loadCache();
-
-    if (!this._cache) {
-      return null;
-    }
-
-    return {
-      state: getLicenseState(this._cache),
-      features: Array.from(this._licensedFeatures),
-      inGrace: isInGracePeriod(this._cache),
-      isExpired: isExpired(this._cache),
-    };
-  }
-
-  /**
-   * Clear internal state (for testing).
-   *
-   * @private
-   */
-  _reset() {
-    this._cache = null;
-    this._licensedFeatures.clear();
-    this._registeredFeatures.clear();
-    this._lastLoadTime = null;
-    this._cacheLoaded = false;
-    this._registryLoaded = false;
-  }
-}
-
-// Singleton instance
-const featureGate = new FeatureGate();
-
-module.exports = {
-  FeatureGate,
-  featureGate,
-};
+/**
+ * Feature Gate Module
+ *
+ * Singleton class that validates feature availability based on license cache.
+ * Supports exact feature ID matching and wildcard patterns.
+ *
+ * Usage:
+ *   const { featureGate } = require('./feature-gate');
+ *
+ *   // Check availability
+ *   if (featureGate.isAvailable('pro.squads.premium')) {
+ *     // Feature is licensed
+ *   }
+ *
+ *   // Require feature (throws if not available)
+ *   featureGate.require('pro.squads.premium', 'Premium Squads');
+ *
+ * @module pro/license/feature-gate
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+const { readLicenseCache, isExpired, isInGracePeriod, getLicenseState } = require('./license-cache');
+const { ProFeatureError } = require('./errors');
+
+/**
+ * Path to the feature registry YAML file.
+ */
+const REGISTRY_PATH = path.join(__dirname, '..', 'feature-registry.yaml');
+
+/**
+ * FeatureGate class - validates feature availability.
+ *
+ * Singleton pattern ensures consistent state across the application.
+ */
+class FeatureGate {
+  constructor() {
+    this._cache = null;
+    this._licensedFeatures = new Set();
+    this._registeredFeatures = new Map();
+    this._lastLoadTime = null;
+    this._cacheLoaded = false;
+    this._registryLoaded = false;
+  }
+
+  /**
+   * Load the feature registry from YAML.
+   *
+   * @private
+   */
+  _loadRegistry() {
+    if (this._registryLoaded) {
+      return;
+    }
+
+    try {
+      if (fs.existsSync(REGISTRY_PATH)) {
+        const content = fs.readFileSync(REGISTRY_PATH, 'utf8');
+        const registry = yaml.parse(content);
+
+        // Extract all features from modules
+        const modules = ['squads', 'memory', 'metrics', 'integrations', 'agents', 'cli', 'config'];
+
+        for (const module of modules) {
+          if (registry[module] && Array.isArray(registry[module])) {
+            for (const feature of registry[module]) {
+              this._registeredFeatures.set(feature.id, {
+                id: feature.id,
+                name: feature.name,
+                description: feature.description,
+                module: feature.module,
+              });
+            }
+          }
+        }
+
+        this._registryLoaded = true;
+      }
+    } catch {
+      // Registry load failed, features will still work via license patterns
+      this._registryLoaded = true;
+    }
+  }
+
+  /**
+   * Load the license cache and populate licensed features.
+   *
+   * @private
+   * @param {boolean} [force=false] - Force reload even if already loaded
+   */
+  _loadCache(force = false) {
+    if (this._cacheLoaded && !force) {
+      return;
+    }
+
+    // Load registry if not loaded
+    this._loadRegistry();
+
+    // Read license cache
+    this._cache = readLicenseCache();
+    this._licensedFeatures.clear();
+    this._lastLoadTime = Date.now();
+
+    if (!this._cache) {
+      this._cacheLoaded = true;
+      return;
+    }
+
+    // Check if cache is valid (not expired, or in grace period)
+    const state = getLicenseState(this._cache);
+
+    if (state === 'Expired') {
+      // Expired and past grace period - no features available
+      // Keep cache reference so getLicenseState can report 'Expired'
+      this._cacheLoaded = true;
+      return;
+    }
+
+    // Populate licensed features from cache
+    if (this._cache.features && Array.isArray(this._cache.features)) {
+      for (const featurePattern of this._cache.features) {
+        this._licensedFeatures.add(featurePattern);
+      }
+    }
+
+    this._cacheLoaded = true;
+  }
+
+  /**
+   * Check if a feature pattern matches a feature ID using wildcard matching.
+   *
+   * Supports:
+   * - Exact match: "pro.squads.premium" matches "pro.squads.premium"
+   * - Wildcard: "pro.squads.*" matches "pro.squads.premium", "pro.squads.custom"
+   * - Module wildcard: "pro.*" matches any pro feature
+   *
+   * @private
+   * @param {string} featureId - Feature ID to check
+   * @param {string} pattern - Pattern from license
+   * @returns {boolean} true if pattern matches feature ID
+   */
+  _matchWildcard(featureId, pattern) {
+    // Exact match
+    if (pattern === featureId) {
+      return true;
+    }
+
+    // Wildcard match: "pro.*" matches "pro.squads.premium"
+    if (pattern.endsWith('.*')) {
+      const prefix = pattern.slice(0, -1); // Remove trailing * → "pro."
+      return featureId.startsWith(prefix);
+    }
+
+    // BUG-7 fix (INS-1): Bare module pattern without dots (e.g., "pro")
+    // should match all features under that module (equivalent to "pro.*")
+    if (!pattern.includes('.') && featureId.startsWith(pattern + '.')) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if a feature is available (licensed).
+   *
+   * Performance: < 5ms (cache read only, per AC-13)
+   *
+   * @param {string} featureId - Feature ID to check (e.g., "pro.squads.premium")
+   * @returns {boolean} true if feature is licensed and available
+   */
+  isAvailable(featureId) {
+    this._loadCache();
+
+    if (this._licensedFeatures.size === 0) {
+      return false;
+    }
+
+    // Check direct match first (O(1))
+    if (this._licensedFeatures.has(featureId)) {
+      return true;
+    }
+
+    // Check wildcard patterns
+    for (const pattern of this._licensedFeatures) {
+      if (this._matchWildcard(featureId, pattern)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Require a feature to be available, throw if not.
+   *
+   * Use this to gate premium functionality:
+   *
+   *   featureGate.require('pro.squads.premium', 'Premium Squads');
+   *
+   * @param {string} featureId - Feature ID to require
+   * @param {string} [friendlyName] - Human-friendly feature name for error message
+   * @throws {ProFeatureError} If feature is not licensed
+   */
+  require(featureId, friendlyName) {
+    if (!this.isAvailable(featureId)) {
+      const name = friendlyName || this._getFeatureName(featureId) || featureId;
+      throw new ProFeatureError(featureId, name);
+    }
+  }
+
+  /**
+   * Get the friendly name of a feature from registry.
+   *
+   * @private
+   * @param {string} featureId - Feature ID
+   * @returns {string|null} Feature name or null
+   */
+  _getFeatureName(featureId) {
+    this._loadRegistry();
+    const feature = this._registeredFeatures.get(featureId);
+    return feature ? feature.name : null;
+  }
+
+  /**
+   * List all available (licensed) feature IDs.
+   *
+   * Returns the resolved list of feature IDs, expanding wildcards
+   * against the registry.
+   *
+   * @returns {string[]} Array of available feature IDs
+   */
+  listAvailable() {
+    this._loadCache();
+    this._loadRegistry();
+
+    const available = new Set();
+
+    // Check each registered feature against licensed patterns
+    for (const [featureId] of this._registeredFeatures) {
+      if (this.isAvailable(featureId)) {
+        available.add(featureId);
+      }
+    }
+
+    return Array.from(available).sort();
+  }
+
+  /**
+   * List all registered features with their availability status.
+   *
+   * @returns {Array<{ id: string, name: string, description: string, module: string, available: boolean }>}
+   */
+  listAll() {
+    this._loadCache();
+    this._loadRegistry();
+
+    const features = [];
+
+    for (const [featureId, feature] of this._registeredFeatures) {
+      features.push({
+        ...feature,
+        available: this.isAvailable(featureId),
+      });
+    }
+
+    return features.sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  /**
+   * List features grouped by module.
+   *
+   * @returns {Object<string, Array<{ id: string, name: string, available: boolean }>>}
+   */
+  listByModule() {
+    const all = this.listAll();
+    const grouped = {};
+
+    for (const feature of all) {
+      if (!grouped[feature.module]) {
+        grouped[feature.module] = [];
+      }
+      grouped[feature.module].push(feature);
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Force reload of the license cache.
+   *
+   * Call this after activation to pick up new features.
+   */
+  reload() {
+    this._cacheLoaded = false;
+    this._loadCache(true);
+  }
+
+  /**
+   * Get the current license state.
+   *
+   * @returns {'Active'|'Expired'|'Grace'|'Not Activated'} License state
+   */
+  getLicenseState() {
+    this._loadCache();
+    return getLicenseState(this._cache);
+  }
+
+  /**
+   * Get license information for display.
+   *
+   * @returns {{ state: string, features: string[], inGrace: boolean } | null}
+   */
+  getLicenseInfo() {
+    this._loadCache();
+
+    if (!this._cache) {
+      return null;
+    }
+
+    return {
+      state: getLicenseState(this._cache),
+      features: Array.from(this._licensedFeatures),
+      inGrace: isInGracePeriod(this._cache),
+      isExpired: isExpired(this._cache),
+    };
+  }
+
+  /**
+   * Clear internal state (for testing).
+   *
+   * @private
+   */
+  _reset() {
+    this._cache = null;
+    this._licensedFeatures.clear();
+    this._registeredFeatures.clear();
+    this._lastLoadTime = null;
+    this._cacheLoaded = false;
+    this._registryLoaded = false;
+  }
+}
+
+// Singleton instance
+const featureGate = new FeatureGate();
+
+module.exports = {
+  FeatureGate,
+  featureGate,
+};