aiox-core 5.0.0 → 5.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiox-core",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Synkra AIOX: AI-Orchestrated System for Full Stack Development - Core Framework",
   "bin": {
     "aiox": "bin/aiox.js",

package/packages/installer/src/wizard/pro-setup.js

@@ -36,6 +36,173 @@ try {
  */
 const LICENSE_SERVER_URL = process.env.AIOX_LICENSE_API_URL || 'https://aiox-license-server.vercel.app';
 
+/**
+ * Inline License Client — lightweight HTTP client for pre-bootstrap license checks.
+ *
+ * Used when @aiox-fullstack/pro is not yet installed (first install scenario).
+ * Implements the same interface subset as LicenseApiClient using Node.js native https.
+ */
+class InlineLicenseClient {
+  constructor(baseUrl = LICENSE_SERVER_URL) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Make an HTTPS request and return parsed JSON.
+   * @param {string} method - HTTP method
+   * @param {string} urlPath - URL path (e.g., '/api/v1/auth/check-email')
+   * @param {Object} [body] - JSON body for POST requests
+   * @param {Object} [headers] - Additional headers
+   * @returns {Promise<Object>} Parsed JSON response
+   */
+  _request(method, urlPath, body, headers = {}) {
+    return new Promise((resolve, reject) => {
+      const https = require('https');
+      const url = new URL(urlPath, this.baseUrl);
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname + url.search,
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': 'aiox-installer',
+          ...headers,
+        },
+        timeout: 15000,
+      };
+
+      const req = https.request(options, (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (res.statusCode >= 400) {
+              const err = new Error(parsed.message || `HTTP ${res.statusCode}`);
+              err.code = parsed.code;
+              reject(err);
+            } else {
+              resolve(parsed);
+            }
+          } catch {
+            reject(new Error(`Invalid JSON response (HTTP ${res.statusCode})`));
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        const networkErr = new Error(err.message);
+        networkErr.code = 'NETWORK_ERROR';
+        reject(networkErr);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        const timeoutErr = new Error('Request timeout');
+        timeoutErr.code = 'NETWORK_ERROR';
+        reject(timeoutErr);
+      });
+
+      if (body) {
+        req.write(JSON.stringify(body));
+      }
+      req.end();
+    });
+  }
+
+  /** @returns {Promise<boolean>} true if license server is reachable */
+  async isOnline() {
+    try {
+      await this._request('GET', '/health');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if email is a buyer and has an account.
+   * @param {string} email
+   * @returns {Promise<{isBuyer: boolean, hasAccount: boolean}>}
+   */
+  async checkEmail(email) {
+    return this._request('POST', '/api/v1/auth/check-email', { email });
+  }
+
+  /**
+   * Login with email and password.
+   * @param {string} email
+   * @param {string} password
+   * @returns {Promise<{sessionToken: string, emailVerified: boolean}>}
+   */
+  async login(email, password) {
+    return this._request('POST', '/api/v1/auth/login', { email, password });
+  }
+
+  /**
+   * Create a new account.
+   * @param {string} email
+   * @param {string} password
+   * @returns {Promise<Object>}
+   */
+  async signup(email, password) {
+    return this._request('POST', '/api/v1/auth/signup', { email, password });
+  }
+
+  /**
+   * Activate Pro using an authenticated session.
+   * @param {string} token - Session token
+   * @param {string} machineId - Machine fingerprint
+   * @param {string} version - aiox-core version
+   * @returns {Promise<Object>} Activation result
+   */
+  async activateByAuth(token, machineId, version) {
+    return this._request('POST', '/api/v1/auth/activate-pro', {
+      machineId,
+      version,
+    }, {
+      Authorization: `Bearer ${token}`,
+    });
+  }
+
+  /**
+   * Activate Pro using a license key (legacy flow).
+   * @param {string} licenseKey - License key
+   * @param {string} machineId - Machine fingerprint
+   * @param {string} version - aiox-core version
+   * @returns {Promise<Object>} Activation result
+   */
+  async activate(licenseKey, machineId, version) {
+    return this._request('POST', '/api/v1/licenses/activate', {
+      key: licenseKey,
+      machineId,
+      version,
+    });
+  }
+
+  /**
+   * Check if user's email has been verified.
+   * @param {string} sessionToken - Session token
+   * @returns {Promise<{verified: boolean}>}
+   */
+  async checkEmailVerified(sessionToken) {
+    return this._request('GET', '/api/v1/auth/email-verified', null, {
+      Authorization: `Bearer ${sessionToken}`,
+    });
+  }
+
+  /**
+   * Resend verification email.
+   * @param {string} email - User email
+   * @returns {Promise<Object>}
+   */
+  async resendVerification(email) {
+    return this._request('POST', '/api/v1/auth/resend-verification', { email });
+  }
+}
+
 /**
  * License key format: PRO-XXXX-XXXX-XXXX-XXXX
  */
@@ -211,6 +378,27 @@ function loadFeatureGate() {
   return loadProModule('feature-gate');
 }
 
+/**
+ * Get a license API client instance.
+ *
+ * Prefers the full LicenseApiClient from @aiox-fullstack/pro when available.
+ * Falls back to InlineLicenseClient (native https) for pre-bootstrap scenarios.
+ *
+ * @returns {Object} Client instance with isOnline, checkEmail, login, signup, activateByAuth
+ */
+function getLicenseClient() {
+  const loader = module.exports._testing ? module.exports._testing.loadLicenseApi : loadLicenseApi;
+  const licenseModule = loader();
+
+  if (licenseModule) {
+    const { LicenseApiClient } = licenseModule;
+    return new LicenseApiClient();
+  }
+
+  // Fallback: use inline client for pre-bootstrap (no @aiox-fullstack/pro yet)
+  return new InlineLicenseClient();
+}
+
 /**
  * Try to load the pro scaffolder via lazy import.
  *
@@ -351,18 +539,7 @@ async function stepLicenseGateWithEmail() {
   const trimmedEmail = email.trim();
 
   // Step 2: Check buyer status + account existence
-  const loader = module.exports._testing ? module.exports._testing.loadLicenseApi : loadLicenseApi;
-  const licenseModule = loader();
-
-  if (!licenseModule) {
-    return {
-      success: false,
-      error: t('proModuleNotAvailable'),
-    };
-  }
-
-  const { LicenseApiClient } = licenseModule;
-  const client = new LicenseApiClient();
+  const client = getLicenseClient();
 
   // Check connectivity
   const online = await client.isOnline();
@@ -630,18 +807,7 @@ async function createAccountFlow(client, email) {
  * @returns {Promise<Object>} Result with { success, key, activationResult }
  */
 async function authenticateWithEmail(email, password) {
-  const loader = module.exports._testing ? module.exports._testing.loadLicenseApi : loadLicenseApi;
-  const licenseModule = loader();
-
-  if (!licenseModule) {
-    return {
-      success: false,
-      error: t('proModuleNotAvailable'),
-    };
-  }
-
-  const { LicenseApiClient } = licenseModule;
-  const client = new LicenseApiClient();
+  const client = getLicenseClient();
 
   // Check connectivity
   const online = await client.isOnline();
@@ -947,19 +1113,7 @@ async function stepLicenseGateWithKey(key) {
  * @returns {Promise<Object>} Result with { success, data?, error? }
  */
 async function validateKeyWithApi(key) {
-  // Use exports._testing for testability (allows mock injection)
-  const loader = module.exports._testing ? module.exports._testing.loadLicenseApi : loadLicenseApi;
-  const licenseModule = loader();
-
-  if (!licenseModule) {
-    return {
-      success: false,
-      error: t('proModuleNotAvailable'),
-    };
-  }
-
-  const { LicenseApiClient } = licenseModule;
-  const client = new LicenseApiClient();
+  const client = getLicenseClient();
 
   try {
     // Check if API is reachable
@@ -1036,50 +1190,23 @@ async function stepInstallScaffold(targetDir, options = {}) {
 
   const path = require('path');
   const fs = require('fs');
-  const { execSync } = require('child_process');
-
-  const proSourceDir = path.join(targetDir, 'node_modules', '@aiox-fullstack', 'pro');
-
-  // Step 2a: Ensure package.json exists (greenfield projects)
-  const packageJsonPath = path.join(targetDir, 'package.json');
-  if (!fs.existsSync(packageJsonPath)) {
-    const initSpinner = createSpinner(t('proInitPackageJson'));
-    initSpinner.start();
-    try {
-      execSync('npm init -y', { cwd: targetDir, stdio: 'pipe' });
-      initSpinner.succeed(t('proPackageJsonCreated'));
-    } catch (err) {
-      initSpinner.fail(t('proPackageJsonFailed'));
-      return { success: false, error: tf('proNpmInitFailed', { message: err.message }) };
-    }
-  }
 
-  // Step 2b: Install @aiox-fullstack/pro if not present
-  if (!fs.existsSync(proSourceDir)) {
-    const installSpinner = createSpinner(t('proInstallingPackage'));
-    installSpinner.start();
-    try {
-      execSync('npm install @aiox-fullstack/pro', {
-        cwd: targetDir,
-        stdio: 'pipe',
-        timeout: 120000,
-      });
-      installSpinner.succeed(t('proPackageInstalled'));
-    } catch (err) {
-      installSpinner.fail(t('proPackageInstallFailed'));
-      return {
-        success: false,
-        error: tf('proNpmInstallFailed', { message: err.message }),
-      };
-    }
-
-    // Validate installation
-    if (!fs.existsSync(proSourceDir)) {
-      return {
-        success: false,
-        error: t('proPackageNotFound'),
-      };
-    }
+  // Resolve pro source directory from multiple locations:
+  // 1. Bundled in aiox-core package (pro/ submodule — npx and local dev)
+  // 2. @aiox-fullstack/pro in node_modules (legacy brownfield)
+  const bundledProDir = path.resolve(__dirname, '..', '..', '..', '..', 'pro');
+  const npmProDir = path.join(targetDir, 'node_modules', '@aiox-fullstack', 'pro');
+
+  let proSourceDir;
+  if (fs.existsSync(bundledProDir) && fs.existsSync(path.join(bundledProDir, 'squads'))) {
+    proSourceDir = bundledProDir;
+  } else if (fs.existsSync(npmProDir)) {
+    proSourceDir = npmProDir;
+  } else {
+    return {
+      success: false,
+      error: t('proPackageNotFound'),
+    };
   }
 
   // Step 2c: Scaffold pro content
@@ -1232,49 +1359,7 @@ async function runProWizard(options = {}) {
     showProHeader();
   }
 
-  // Pre-check: If license module is not available (brownfield upgrade from older version),
-  // install @aiox-fullstack/pro first to get the license API, then proceed with gate.
-  if (!loadLicenseApi()) {
-    const fs = require('fs');
-    const path = require('path');
-    const { execSync } = require('child_process');
-
-    showInfo(t('proModuleBootstrap'));
-
-    // Ensure package.json exists
-    const packageJsonPath = path.join(targetDir, 'package.json');
-    if (!fs.existsSync(packageJsonPath)) {
-      execSync('npm init -y', { cwd: targetDir, stdio: 'pipe' });
-    }
-
-    // Install @aiox-fullstack/pro to get license module
-    const proDir = path.join(targetDir, 'node_modules', '@aiox-fullstack', 'pro');
-    if (!fs.existsSync(proDir)) {
-      const installSpinner = createSpinner(t('proInstallingPackage'));
-      installSpinner.start();
-      try {
-        execSync('npm install @aiox-fullstack/pro', {
-          cwd: targetDir,
-          stdio: 'pipe',
-          timeout: 120000,
-        });
-        installSpinner.succeed(t('proPackageInstalled'));
-      } catch (err) {
-        installSpinner.fail(t('proPackageInstallFailed'));
-        result.error = tf('proNpmInstallFailed', { message: err.message });
-        return result;
-      }
-    }
-
-    // Clear require cache so loadLicenseApi() picks up newly installed module
-    Object.keys(require.cache).forEach((key) => {
-      if (key.includes('license-api') || key.includes('@aiox-fullstack')) {
-        delete require.cache[key];
-      }
-    });
-  }
-
-  // Step 1: License Gate
+  // Step 1: License Gate (uses InlineLicenseClient if @aiox-fullstack/pro not yet installed)
   const licenseResult = await stepLicenseGate({
     key: options.key || process.env.AIOX_PRO_KEY,
     email: options.email || process.env.AIOX_PRO_EMAIL,
@@ -1341,6 +1426,8 @@ module.exports = {
     loadLicenseApi,
     loadFeatureGate,
     loadProScaffolder,
+    getLicenseClient,
+    InlineLicenseClient,
     LICENSE_SERVER_URL,
     MAX_RETRIES,
     LICENSE_KEY_PATTERN,

package/pro/README.md

@@ -0,0 +1,66 @@
+# AIOX Pro
+
+Premium features for [Synkra AIOX](https://github.com/SynkraAI/aiox-core).
+
+## Overview
+
+AIOX Pro extends the open-source AIOX framework with premium capabilities:
+
+- **Premium Squads** - Pre-built squads for SaaS, e-commerce, and fintech
+- **Persistent Memory** - Cross-session context and memory analytics
+- **Usage Metrics** - Dashboards, team analytics, and cost tracking
+- **Enterprise Integrations** - ClickUp, Google Drive, GitLab, Jira, Azure DevOps
+
+## Installation
+
+AIOX Pro requires an active license and is distributed via npm.
+
+```bash
+# Install
+npm install @aiox-fullstack/pro
+
+# Activate license
+aiox pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
+```
+
+## Usage with aiox-core
+
+AIOX Pro is designed to work as a git submodule of `aiox-core`:
+
+```bash
+# Clone aiox-core with pro submodule
+git clone --recurse-submodules https://github.com/SynkraAI/aiox-core.git
+
+# Or add to existing clone
+cd aiox-core
+git submodule update --init pro
+```
+
+## Activate License
+
+```bash
+aiox pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
+aiox pro status
+```
+
+## Structure
+
+```
+aiox-pro/
+├── squads/          # Premium squad definitions
+├── memory/          # Persistent memory modules
+├── metrics/         # Usage dashboards and analytics
+├── integrations/    # Enterprise integration adapters
+├── license/         # License infrastructure
+└── pro-config.yaml  # Pro extension configuration
+```
+
+## Requirements
+
+- Node.js >= 18
+- aiox-core >= 3.12.0
+- Active AIOX Pro license
+
+## License
+
+Proprietary - Copyright (c) 2026 SynkraAI. All rights reserved.

package/pro/license/degradation.js

@@ -0,0 +1,220 @@
+/**
+ * Graceful Degradation Module
+ *
+ * Utilities for handling pro feature unavailability with user-friendly
+ * messages that preserve data and provide clear next steps.
+ *
+ * Per ADR-PRO-003 and AC-8:
+ * - Never show upgrade prompts on core features
+ * - Never delete or corrupt user data
+ * - Always provide actionable next steps
+ * - Keep messages non-intrusive
+ *
+ * @module pro/license/degradation
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const { featureGate } = require('./feature-gate');
+const { ProFeatureError } = require('./errors');
+
+/**
+ * Default degradation message template.
+ * @private Reserved for future customization support.
+ */
+const _DEFAULT_MESSAGE_TEMPLATE = `
+{featureName} requires an active AIOS Pro license.
+
+Your data and configurations are preserved.
+
+Activate: aios pro activate --key <KEY>
+Purchase: https://synkra.ai/pro
+`;
+
+/**
+ * Handle pro feature gracefully - return fallback instead of throwing.
+ *
+ * Use this when you want to provide a degraded experience instead
+ * of completely blocking the feature.
+ *
+ * @param {string} featureId - Feature ID to check
+ * @param {Function} proAction - Function to execute if feature is available
+ * @param {Function} [fallbackAction] - Function to execute if not available
+ * @param {object} [options] - Options
+ * @param {boolean} [options.silent=false] - Don't log degradation message
+ * @returns {*} Result of proAction or fallbackAction
+ */
+function withGracefulDegradation(featureId, proAction, fallbackAction, options = {}) {
+  if (featureGate.isAvailable(featureId)) {
+    return proAction();
+  }
+
+  if (!options.silent) {
+    const featureName = getFeatureFriendlyName(featureId);
+    logDegradationMessage(featureName, featureId);
+  }
+
+  if (typeof fallbackAction === 'function') {
+    return fallbackAction();
+  }
+
+  return null;
+}
+
+/**
+ * Execute action only if pro feature is available.
+ *
+ * Unlike featureGate.require(), this doesn't throw - it just
+ * returns undefined if the feature isn't available.
+ *
+ * @param {string} featureId - Feature ID to check
+ * @param {Function} action - Action to execute if available
+ * @returns {*|undefined} Result of action or undefined
+ */
+function ifProAvailable(featureId, action) {
+  if (featureGate.isAvailable(featureId)) {
+    return action();
+  }
+  return undefined;
+}
+
+/**
+ * Get a user-friendly name for a feature.
+ *
+ * @param {string} featureId - Feature ID
+ * @returns {string} Friendly name
+ */
+function getFeatureFriendlyName(featureId) {
+  const all = featureGate.listAll();
+  const feature = all.find((f) => f.id === featureId);
+  return feature ? feature.name : featureId;
+}
+
+/**
+ * Log a degradation message to the console.
+ *
+ * This is used internally when a pro feature is accessed without
+ * a license. Messages are non-intrusive and informative.
+ *
+ * @param {string} featureName - Human-friendly feature name
+ * @param {string} _featureId - Feature ID for reference (reserved for logging)
+ */
+function logDegradationMessage(featureName, _featureId) {
+  console.log('');
+  console.log(`  ${featureName} requires an active AIOS Pro license.`);
+  console.log('');
+  console.log('  Your data and configurations are preserved.');
+  console.log('');
+  console.log('  Activate: aios pro activate --key <KEY>');
+  console.log('  Purchase: https://synkra.ai/pro');
+  console.log('');
+}
+
+/**
+ * Create a degradation-aware wrapper for a pro module.
+ *
+ * This creates a proxy that catches ProFeatureError and provides
+ * a graceful degradation experience.
+ *
+ * @param {object} proModule - Pro module with methods
+ * @param {object} fallbacks - Map of method names to fallback functions
+ * @returns {Proxy} Wrapped module
+ *
+ * @example
+ *   const safePremiumSquads = createDegradationWrapper(
+ *     PremiumSquads,
+ *     {
+ *       listTemplates: () => ['basic'], // Fallback to basic templates
+ *       exportSquad: () => null,        // No export without license
+ *     }
+ *   );
+ */
+function createDegradationWrapper(proModule, fallbacks = {}) {
+  return new Proxy(proModule, {
+    get(target, prop) {
+      const original = target[prop];
+
+      if (typeof original !== 'function') {
+        return original;
+      }
+
+      return function (...args) {
+        try {
+          return original.apply(target, args);
+        } catch (error) {
+          if (error instanceof ProFeatureError) {
+            if (fallbacks[prop]) {
+              logDegradationMessage(error.friendlyName, error.featureId);
+              return fallbacks[prop](...args);
+            }
+            // Re-throw if no fallback
+            throw error;
+          }
+          // Re-throw non-license errors
+          throw error;
+        }
+      };
+    },
+  });
+}
+
+/**
+ * Check if the system is in degraded mode (expired/no license).
+ *
+ * @returns {boolean} true if pro features are unavailable
+ */
+function isInDegradedMode() {
+  const state = featureGate.getLicenseState();
+  return state === 'Expired' || state === 'Not Activated';
+}
+
+/**
+ * Get degradation status summary.
+ *
+ * @returns {{ degraded: boolean, reason: string, action: string }}
+ */
+function getDegradationStatus() {
+  const state = featureGate.getLicenseState();
+
+  if (state === 'Active') {
+    return {
+      degraded: false,
+      reason: 'License is active',
+      action: null,
+    };
+  }
+
+  if (state === 'Grace') {
+    return {
+      degraded: false,
+      reason: 'License in grace period - revalidate soon',
+      action: 'aios pro validate',
+    };
+  }
+
+  if (state === 'Expired') {
+    return {
+      degraded: true,
+      reason: 'License has expired',
+      action: 'aios pro activate --key <KEY>',
+    };
+  }
+
+  return {
+    degraded: true,
+    reason: 'No license activated',
+    action: 'aios pro activate --key <KEY>',
+  };
+}
+
+module.exports = {
+  withGracefulDegradation,
+  ifProAvailable,
+  getFeatureFriendlyName,
+  logDegradationMessage,
+  createDegradationWrapper,
+  isInDegradedMode,
+  getDegradationStatus,
+};