aios-core 2.1.0

package/bin/utils/install-transaction.js

@@ -0,0 +1,445 @@
+/**
+ * InstallTransaction - Transaction manager for AIOS installer
+ *
+ * Provides atomic installation operations with automatic rollback on failure.
+ * Backs up files before modification and restores them if installation fails.
+ *
+ * @module bin/utils/install-transaction
+ * @see Story 1.9 - Error Handling & Rollback
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+
+// Error classification constants
+const ERROR_TYPES = {
+  CRITICAL: 'CRITICAL',
+  RECOVERABLE: 'RECOVERABLE',
+  WARNING: 'WARNING',
+};
+
+// Critical errors that trigger immediate rollback
+const CRITICAL_ERRORS = [
+  'EACCES',   // Permission denied
+  'ENOSPC',   // No space left on device
+  'EROFS',    // Read-only file system
+  'ENOTDIR',  // Not a directory
+  'EISDIR',   // Is a directory
+];
+
+class InstallTransaction {
+  /**
+   * Create a new installation transaction
+   *
+   * @param {Object} options - Transaction options
+   * @param {string} [options.backupDir] - Custom backup directory path
+   * @param {string} [options.logFile] - Custom log file path
+   */
+  constructor(options = {}) {
+    this.backupDir = options.backupDir || path.join(process.cwd(), '.aios-backup', this._generateTimestamp());
+    this.logFile = options.logFile || path.join(process.cwd(), '.aios-install.log');
+    this.backups = [];  // [{original, backup, hash, isDirectory}]
+    this.operations = [];  // [{timestamp, level, message}]
+    this.isCommitted = false;
+    this.isRolledBack = false;
+  }
+
+  /**
+   * Generate timestamp for backup directory naming
+   * Format: 2025-01-23_14-30-45-123Z
+   *
+   * @private
+   * @returns {string} ISO timestamp with safe filename characters
+   */
+  _generateTimestamp() {
+    // Replace colons, dots, and T separator for Windows compatibility
+    return new Date().toISOString()
+      .replace(/:/g, '-')
+      .replace(/\./g, '-')
+      .replace('T', '_');
+  }
+
+  /**
+   * Backup a single file before modification
+   *
+   * @param {string} filePath - Path to file to backup
+   * @throws {Error} If backup operation fails
+   *
+   * @example
+   * await transaction.backup('package.json');
+   */
+  async backup(filePath) {
+    const originalPath = path.resolve(filePath);
+
+    // Check if file exists
+    if (!(await fs.pathExists(originalPath))) {
+      this.log('WARN', `File not found for backup: ${filePath}`);
+      return;
+    }
+
+    // Prevent symlink attacks (security)
+    const stats = await fs.lstat(originalPath);
+    if (stats.isSymbolicLink()) {
+      throw new Error(`Symlink detected in backup path - potential security risk: ${filePath}`);
+    }
+
+    // Skip if already backed up
+    if (this.backups.find((b) => b.original === originalPath)) {
+      this.log('DEBUG', `File already backed up: ${filePath}`);
+      return;
+    }
+
+    // Generate unique backup filename using path hash to prevent collisions
+    // e.g., /app/config.json and /data/config.json won't overwrite each other
+    const pathHash = crypto.createHash('sha256').update(originalPath).digest('hex').substring(0, 8);
+    const backupFilename = `${path.basename(filePath)}.${pathHash}.backup`;
+    const backupPath = path.join(this.backupDir, backupFilename);
+    await fs.ensureDir(this.backupDir);
+
+    // Set restrictive permissions on backup directory (owner only)
+    try {
+      await fs.chmod(this.backupDir, 0o700);
+    } catch (error) {
+      // Windows doesn't support chmod - log warning but continue
+      this.log('DEBUG', `Could not set backup directory permissions: ${error.message}`);
+    }
+
+    await fs.copy(originalPath, backupPath);
+
+    const hash = await this._calculateHash(originalPath);
+    this.backups.push({ original: originalPath, backup: backupPath, hash });
+    this.log('INFO', `Backed up: ${filePath}`);
+  }
+
+  /**
+   * Backup entire directory recursively
+   *
+   * @param {string} dirPath - Path to directory to backup
+   * @throws {Error} If backup operation fails
+   *
+   * @example
+   * await transaction.backupDirectory('.aios-core/');
+   */
+  async backupDirectory(dirPath) {
+    const originalPath = path.resolve(dirPath);
+
+    if (!(await fs.pathExists(originalPath))) {
+      this.log('WARN', `Directory not found for backup: ${dirPath}`);
+      return;
+    }
+
+    // Prevent symlink attacks (security) - use lstat to detect symlinks
+    const stats = await fs.lstat(originalPath);
+    if (stats.isSymbolicLink()) {
+      throw new Error(`Symlink detected in backup path - potential security risk: ${dirPath}`);
+    }
+
+    if (!stats.isDirectory()) {
+      throw new Error(`Path is not a directory: ${dirPath}`);
+    }
+
+    // Skip if already backed up
+    if (this.backups.find((b) => b.original === originalPath)) {
+      this.log('DEBUG', `Directory already backed up: ${dirPath}`);
+      return;
+    }
+
+    // Generate unique backup dirname using path hash to prevent collisions
+    const pathHash = crypto.createHash('sha256').update(originalPath).digest('hex').substring(0, 8);
+    const backupDirname = `${path.basename(dirPath)}.${pathHash}`;
+    const backupPath = path.join(this.backupDir, backupDirname);
+    await fs.ensureDir(this.backupDir);
+
+    // Set restrictive permissions
+    try {
+      await fs.chmod(this.backupDir, 0o700);
+    } catch (error) {
+      this.log('DEBUG', `Could not set backup directory permissions: ${error.message}`);
+    }
+
+    await fs.copy(originalPath, backupPath, { recursive: true });
+
+    this.backups.push({ original: originalPath, backup: backupPath, isDirectory: true });
+    this.log('INFO', `Backed up directory: ${dirPath}`);
+  }
+
+  /**
+   * Calculate SHA-256 hash of file for verification
+   *
+   * @private
+   * @param {string} filePath - Path to file
+   * @returns {Promise<string>} Hex-encoded hash
+   */
+  async _calculateHash(filePath) {
+    const content = await fs.readFile(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  }
+
+  /**
+   * Verify backup integrity by comparing hashes
+   *
+   * @private
+   * @param {Object} backup - Backup entry {original, backup, hash}
+   * @returns {Promise<boolean>} True if backup is valid
+   */
+  async _verifyBackup(backup) {
+    if (backup.isDirectory) {
+      // For directories, just check existence
+      return await fs.pathExists(backup.backup);
+    }
+
+    if (!(await fs.pathExists(backup.backup))) {
+      return false;
+    }
+
+    const backupHash = await this._calculateHash(backup.backup);
+    return backupHash === backup.hash;
+  }
+
+  /**
+   * Rollback all changes by restoring backups
+   *
+   * @returns {Promise<boolean>} True if rollback succeeded, false if partial failure
+   *
+   * @example
+   * try {
+   *   await installAIOS();
+   * } catch (error) {
+   *   await transaction.rollback();
+   * }
+   */
+  async rollback() {
+    if (this.isCommitted) {
+      this.log('ERROR', 'Cannot rollback: transaction already committed');
+      return false;
+    }
+
+    if (this.isRolledBack) {
+      this.log('WARN', 'Transaction already rolled back');
+      return true;
+    }
+
+    this.log('ERROR', 'Installation failed. Starting rollback...');
+    let rollbackSuccess = true;
+    const failedRestores = [];
+
+    // Restore in reverse order (LIFO - last backup restored first)
+    for (const backup of [...this.backups].reverse()) {
+      try {
+        // Verify backup integrity before restore
+        const isValid = await this._verifyBackup(backup);
+        if (!isValid) {
+          this.log('ERROR', `Backup verification failed for ${backup.original}`);
+          failedRestores.push(backup.original);
+          rollbackSuccess = false;
+          continue;
+        }
+
+        // Atomic restore: Copy to temp first, then move to original
+        // This prevents data loss if copy fails
+        const tempPath = `${backup.original}.restore-temp`;
+
+        try {
+          // Copy backup to temporary location
+          await fs.copy(backup.backup, tempPath, { recursive: backup.isDirectory });
+
+          // Remove failed installation artifacts (safe now that restore is ready)
+          if (await fs.pathExists(backup.original)) {
+            await fs.remove(backup.original);
+          }
+
+          // Atomic move from temp to original
+          await fs.move(tempPath, backup.original, { overwrite: true });
+        } finally {
+          // Cleanup temp file if it still exists (error case)
+          if (await fs.pathExists(tempPath)) {
+            await fs.remove(tempPath);
+          }
+        }
+
+        this.log('INFO', `Restored: ${backup.original}`);
+      } catch (error) {
+        this.log('ERROR', `Failed to restore ${backup.original}: ${error.message}`);
+        failedRestores.push(backup.original);
+        rollbackSuccess = false;
+      }
+    }
+
+    // Cleanup backup directory
+    try {
+      await fs.remove(this.backupDir);
+      this.log('INFO', 'Backup directory cleaned up');
+    } catch (error) {
+      this.log('WARN', `Failed to cleanup backup directory: ${error.message}`);
+    }
+
+    this.isRolledBack = true;
+
+    if (failedRestores.length > 0) {
+      this.log('ERROR', `Rollback completed with errors. Failed to restore: ${failedRestores.join(', ')}`);
+    } else {
+      this.log('INFO', 'Rollback completed successfully');
+    }
+
+    return rollbackSuccess;
+  }
+
+  /**
+   * Commit transaction and cleanup backups (installation succeeded)
+   *
+   * @example
+   * await transaction.commit();
+   * console.log('Installation successful!');
+   */
+  async commit() {
+    if (this.isRolledBack) {
+      this.log('ERROR', 'Cannot commit: transaction already rolled back');
+      return;
+    }
+
+    if (this.isCommitted) {
+      this.log('WARN', 'Transaction already committed');
+      return;
+    }
+
+    this.log('INFO', 'Installation successful. Cleaning up backups...');
+
+    try {
+      await fs.remove(this.backupDir);
+      this.log('INFO', 'Backups cleaned up successfully');
+    } catch (error) {
+      this.log('WARN', `Failed to cleanup backups: ${error.message}`);
+    }
+
+    this.isCommitted = true;
+  }
+
+  /**
+   * Log message with timestamp and level
+   * Sanitizes credentials before writing to log file
+   *
+   * @param {string} level - Log level (INFO, WARN, ERROR, DEBUG)
+   * @param {string} message - Log message
+   */
+  log(level, message) {
+    const timestamp = new Date().toISOString();
+    const logLine = `[${timestamp}] [${level}] ${message}\n`;
+
+    // Sanitize credentials (API keys, tokens, passwords)
+    const sanitized = this._sanitizeCredentials(logLine);
+
+    // Write to log file (append mode)
+    try {
+      fs.appendFileSync(this.logFile, sanitized);
+    } catch (error) {
+      // If logging fails, don't crash - just write to console
+      console.error(`Failed to write to log file: ${error.message}`);
+    }
+
+    // Store in memory for programmatic access
+    this.operations.push({ timestamp, level, message });
+
+    // Rotate log if it exceeds 10MB
+    this._rotateLogIfNeeded();
+  }
+
+  /**
+   * Sanitize sensitive data from log messages
+   * Prevents API keys, tokens, and passwords from being logged
+   *
+   * @private
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   */
+  _sanitizeCredentials(text) {
+    // Pattern 1: Long hex strings (API keys, tokens)
+    let sanitized = text.replace(/[a-f0-9]{32,}/gi, '[REDACTED]');
+
+    // Pattern 2: Bearer tokens
+    sanitized = sanitized.replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]');
+
+    // Pattern 3: Password fields (password=xxx, pwd=xxx)
+    sanitized = sanitized.replace(/(password|pwd|token|key|secret|auth)[:=]\s*[^\s,}]+/gi, '$1=[REDACTED]');
+
+    // Pattern 4: Environment variables that look like secrets
+    sanitized = sanitized.replace(/([A-Z_]+_(?:KEY|TOKEN|SECRET|PASSWORD|AUTH))[:=]\s*[^\s,}]+/gi, '$1=[REDACTED]');
+
+    return sanitized;
+  }
+
+  /**
+   * Rotate log file if it exceeds 10MB
+   * Keeps last 5 logs
+   *
+   * @private
+   */
+  _rotateLogIfNeeded() {
+    try {
+      // Check if log file exists before trying to get stats
+      if (!fs.existsSync(this.logFile)) {
+        return;
+      }
+
+      const stats = fs.statSync(this.logFile);
+      const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+      const MAX_LOG_FILES = 5;
+
+      if (stats.size < MAX_LOG_SIZE) {
+        return;
+      }
+
+      // Rotate existing logs (log.4 -> log.5, log.3 -> log.4, etc.)
+      for (let i = MAX_LOG_FILES - 1; i >= 1; i--) {
+        const oldPath = `${this.logFile}.${i}`;
+        const newPath = `${this.logFile}.${i + 1}`;
+
+        if (fs.existsSync(oldPath)) {
+          if (i === MAX_LOG_FILES - 1) {
+            fs.unlinkSync(oldPath); // Delete oldest log
+          } else {
+            fs.renameSync(oldPath, newPath);
+          }
+        }
+      }
+
+      // Move current log to .1
+      fs.renameSync(this.logFile, `${this.logFile}.1`);
+
+      this.log('INFO', 'Log file rotated');
+    } catch (error) {
+      // Rotation failure is non-critical
+      console.error(`Log rotation failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Classify error type based on error code
+   *
+   * @param {Error} error - Error object
+   * @returns {string} ERROR_TYPES constant (CRITICAL, RECOVERABLE, WARNING)
+   */
+  classifyError(error) {
+    if (!error.code) {
+      return ERROR_TYPES.RECOVERABLE;
+    }
+
+    if (CRITICAL_ERRORS.includes(error.code)) {
+      return ERROR_TYPES.CRITICAL;
+    }
+
+    return ERROR_TYPES.RECOVERABLE;
+  }
+
+  /**
+   * Check if error is critical (requires rollback)
+   *
+   * @param {Error} error - Error object
+   * @returns {boolean} True if error is critical
+   */
+  isCriticalError(error) {
+    return this.classifyError(error) === ERROR_TYPES.CRITICAL;
+  }
+}
+
+module.exports = { InstallTransaction, ERROR_TYPES, CRITICAL_ERRORS };

package/index.d.ts

@@ -0,0 +1,19 @@
+// AIOS-FullStack Workspace - TypeScript Definitions
+declare module '@aios-fullstack/workspace' {
+    export class AIOS {
+        constructor(config?: any);
+        initialize(): Promise<AIOS>;
+        createAgent(config: any): Promise<any>;
+        createTask(taskConfig: any): Promise<any>;
+        search(query: string, options?: any): Promise<any[]>;
+        healthCheck(): Promise<any>;
+    }
+    
+    export * as core from '@aios-fullstack/core';
+    export * as memory from '@aios-fullstack/memory';
+    export * as security from '@aios-fullstack/security';
+    export * as performance from '@aios-fullstack/performance';
+    export * as telemetry from '@aios-fullstack/telemetry';
+    
+    export default AIOS;
+}

package/index.esm.js

@@ -0,0 +1,21 @@
+// AIOS-FullStack Workspace - ES Module Entry Point
+import * as core from '@aios-fullstack/core';
+import * as memory from '@aios-fullstack/memory';
+import * as security from '@aios-fullstack/security';
+import * as performance from '@aios-fullstack/performance';
+import * as telemetry from '@aios-fullstack/telemetry';
+
+// Re-export the AIOS class from CommonJS version
+import workspace from './index.js';
+const { AIOS } = workspace;
+
+export {
+    AIOS,
+    core,
+    memory,
+    security,
+    performance,
+    telemetry
+};
+
+export default AIOS;

package/index.js

@@ -0,0 +1,94 @@
+// AIOS-FullStack Workspace - Complete Framework Entry Point
+const core = require('@aios-fullstack/core');
+const memory = require('@aios-fullstack/memory');
+const security = require('@aios-fullstack/security');
+const performance = require('@aios-fullstack/performance');
+const telemetry = require('@aios-fullstack/telemetry');
+
+// Main AIOS class that orchestrates all components
+class AIOS {
+  constructor(config = {}) {
+    this.config = config;
+    this.core = null;
+    this.memory = null;
+    this.security = null;
+    this.performance = null;
+    this.telemetry = null;
+    this.initialized = false;
+  }
+
+  async initialize() {
+    if (this.initialized) return this;
+
+    try {
+      // Initialize security first
+      this.security = new security.Sanitizer(this.config.security);
+            
+      // Initialize memory layer
+      this.memory = new memory.MemoryAdapter(this.config.memory);
+      await this.memory.initialize();
+            
+      // Initialize performance monitoring
+      this.performance = new performance.PerformanceMonitor(this.config.performance);
+            
+      // Initialize telemetry (with consent)
+      if (this.config.telemetry?.enabled !== false) {
+        this.telemetry = new telemetry.ConsentManager(this.config.telemetry);
+      }
+            
+      // Initialize core meta-agent
+      this.core = new core.MetaAgent({
+        ...this.config.core,
+        memory: this.memory,
+        security: this.security,
+        performance: this.performance,
+        telemetry: this.telemetry,
+      });
+            
+      this.initialized = true;
+      return this;
+    } catch (error) {
+      throw new Error(`AIOS initialization failed: ${error.message}`);
+    }
+  }
+
+  // Convenience methods
+  async createAgent(config) {
+    if (!this.initialized) await this.initialize();
+    return this.core.createAgent(config);
+  }
+
+  async createTask(taskConfig) {
+    if (!this.initialized) await this.initialize();
+    return this.core.createTask(taskConfig);
+  }
+
+  async search(query, options = {}) {
+    if (!this.initialized) await this.initialize();
+    return this.memory.search(query, options);
+  }
+
+  // Health check
+  async healthCheck() {
+    return {
+      initialized: this.initialized,
+      components: {
+        core: !!this.core,
+        memory: !!this.memory,
+        security: !!this.security,
+        performance: !!this.performance,
+        telemetry: !!this.telemetry,
+      },
+      version: require('./package.json').version,
+    };
+  }
+}
+
+module.exports = {
+  AIOS,
+  core,
+  memory,
+  security,
+  performance,
+  telemetry,
+};