aios-core 1.0.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/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "aios-core",
+  "version": "1.0.0",
+  "description": "Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework",
+  "bin": {
+    "aios": "bin/aios.js",
+    "aios-core": "bin/aios.js",
+    "aios-minimal": "bin/aios-minimal.js"
+  },
+  "preferGlobal": false,
+  "workspaces": [
+    "packages/*"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "packages/",
+    "tools/",
+    "templates/",
+    ".aios-core/",
+    ".claude/CLAUDE.md",
+    ".claude/rules/",
+    "squads/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "format": "prettier --write \"**/*.md\"",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --cache --cache-location .eslintcache",
+    "typecheck": "tsc --noEmit",
+    "release": "semantic-release",
+    "release:test": "semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'",
+    "generate:manifest": "node scripts/generate-install-manifest.js",
+    "validate:manifest": "node scripts/validate-manifest.js",
+    "validate:structure": "node .aios-core/infrastructure/scripts/source-tree-guardian/index.js",
+    "sync:ide": "node .aios-core/infrastructure/scripts/ide-sync/index.js sync",
+    "sync:ide:validate": "node .aios-core/infrastructure/scripts/ide-sync/index.js validate",
+    "sync:ide:check": "node .aios-core/infrastructure/scripts/ide-sync/index.js validate --strict",
+    "sync:ide:cursor": "node .aios-core/infrastructure/scripts/ide-sync/index.js sync --ide cursor",
+    "sync:ide:windsurf": "node .aios-core/infrastructure/scripts/ide-sync/index.js sync --ide windsurf",
+    "sync:ide:trae": "node .aios-core/infrastructure/scripts/ide-sync/index.js sync --ide trae",
+    "prepublishOnly": "npm run generate:manifest && npm run validate:manifest",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@kayvan/markdown-tree-parser": "^1.5.0",
+    "chalk": "^4.1.2",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.1",
+    "execa": "^5.1.1",
+    "fs-extra": "^11.3.2",
+    "glob": "^11.0.3",
+    "handlebars": "^4.7.8",
+    "inquirer": "^8.2.6",
+    "isolated-vm": "^5.0.4",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1",
+    "picocolors": "^1.1.1",
+    "semver": "^7.7.2",
+    "validator": "^13.15.15"
+  },
+  "keywords": [
+    "ai",
+    "aios",
+    "agile",
+    "agents",
+    "orchestrator",
+    "fullstack",
+    "development",
+    "cli",
+    "cross-platform",
+    "interactive",
+    "wizard",
+    "modern-ux",
+    "vite-style",
+    "automation"
+  ],
+  "author": "Synkra AIOS Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SynkraAI/aios-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SynkraAI/aios-core/issues"
+  },
+  "homepage": "https://github.com/SynkraAI/aios-core#readme",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^9.38.0",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "lint-staged": "^16.1.1",
+    "prettier": "^3.5.3",
+    "semantic-release": "^25.0.2",
+    "typescript": "^5.9.3",
+    "yaml-lint": "^1.7.0"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts}": [
+      "eslint --fix --cache --cache-location .eslintcache",
+      "prettier --write"
+    ],
+    "*.md": [
+      "prettier --write"
+    ],
+    ".aios-core/development/agents/*.md": [
+      "npm run sync:ide"
+    ]
+  }
+}

package/packages/installer/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aios/installer",
+  "version": "2.1.0",
+  "description": "AIOS Installer - Automated setup wizard for AIOS projects (greenfield & brownfield)",
+  "main": "src/index.js",
+  "bin": {
+    "aios-installer": "./src/index.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration"
+  },
+  "keywords": [
+    "aios",
+    "installer",
+    "wizard",
+    "cli",
+    "setup",
+    "greenfield",
+    "brownfield"
+  ],
+  "author": "AIOS Fullstack Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.3.2"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}
+