@unrdf/kgn 5.0.1

package/src/injection/rollback-manager.js

@@ -0,0 +1,373 @@
+/**
+ * KGEN Rollback Manager
+ *
+ * Manages rollback operations for failed injections, including
+ * backup restoration and operation undo capabilities.
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname, basename } from 'path';
+import { createHash } from 'crypto';
+
+import { ERROR_CODES, CHECKSUM_ALGORITHMS } from './constants.js';
+
+export class RollbackManager {
+  constructor(config = {}) {
+    this.config = config;
+    this.rollbackHistory = new Map();
+    this.operationBackups = new Map();
+  }
+
+  /**
+   * Rollback a failed operation
+   */
+  async rollbackOperation(operationId, operationData) {
+    const rollbackEntry = {
+      operationId,
+      timestamp: Date.now(),
+      phase: 'starting',
+      restoredFiles: [],
+      errors: []
+    };
+
+    try {
+      rollbackEntry.phase = 'restoring-files';
+
+      // Restore files from backups
+      if (operationData.backups && operationData.backups.length > 0) {
+        for (const backup of operationData.backups) {
+          try {
+            await this._restoreFromBackup(backup.filePath, backup.backupPath);
+            rollbackEntry.restoredFiles.push({
+              file: backup.filePath,
+              backup: backup.backupPath,
+              success: true
+            });
+          } catch (error) {
+            rollbackEntry.errors.push({
+              file: backup.filePath,
+              error: error.message
+            });
+          }
+        }
+      }
+
+      // Clean up temporary files
+      rollbackEntry.phase = 'cleanup';
+      await this._cleanupTemporaryFiles(operationData);
+
+      // Release locks
+      await this._releaseLocks(operationData);
+
+      rollbackEntry.phase = 'completed';
+      rollbackEntry.success = rollbackEntry.errors.length === 0;
+
+      this.rollbackHistory.set(operationId, rollbackEntry);
+
+      return {
+        success: rollbackEntry.success,
+        filesRestored: rollbackEntry.restoredFiles.length,
+        errors: rollbackEntry.errors
+      };
+
+    } catch (error) {
+      rollbackEntry.phase = 'failed';
+      rollbackEntry.error = error.message;
+      this.rollbackHistory.set(operationId, rollbackEntry);
+
+      throw new Error(`Rollback failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Undo a completed operation
+   */
+  async undoOperation(operationId) {
+    const operationHistory = this._getOperationHistory(operationId);
+    if (!operationHistory) {
+      throw new Error(`Operation ${operationId} not found in history`);
+    }
+
+    if (operationHistory.phase !== 'committed') {
+      throw new Error(`Cannot undo operation ${operationId} - not in committed state`);
+    }
+
+    const undoEntry = {
+      originalOperationId: operationId,
+      undoOperationId: `undo-${operationId}`,
+      timestamp: Date.now(),
+      phase: 'starting',
+      restoredFiles: [],
+      errors: []
+    };
+
+    try {
+      // Find backups for this operation
+      const backups = this._findOperationBackups(operationId);
+      if (backups.length === 0) {
+        throw new Error(`No backups found for operation ${operationId}`);
+      }
+
+      undoEntry.phase = 'restoring';
+
+      for (const backup of backups) {
+        try {
+          await this._restoreFromBackup(backup.targetPath, backup.backupPath);
+          undoEntry.restoredFiles.push({
+            file: backup.targetPath,
+            backup: backup.backupPath,
+            success: true
+          });
+        } catch (error) {
+          undoEntry.errors.push({
+            file: backup.targetPath,
+            error: error.message
+          });
+        }
+      }
+
+      undoEntry.phase = 'completed';
+      undoEntry.success = undoEntry.errors.length === 0;
+
+      // Mark original operation as undone
+      operationHistory.undone = true;
+      operationHistory.undoTimestamp = Date.now();
+
+      this.rollbackHistory.set(undoEntry.undoOperationId, undoEntry);
+
+      return {
+        success: undoEntry.success,
+        filesRestored: undoEntry.restoredFiles.length,
+        errors: undoEntry.errors,
+        operationId: undoEntry.undoOperationId
+      };
+
+    } catch (error) {
+      undoEntry.phase = 'failed';
+      undoEntry.error = error.message;
+      this.rollbackHistory.set(undoEntry.undoOperationId, undoEntry);
+
+      throw error;
+    }
+  }
+
+  /**
+   * Register backup for tracking
+   */
+  registerBackup(operationId, targetPath, backupPath, checksum) {
+    if (!this.operationBackups.has(operationId)) {
+      this.operationBackups.set(operationId, []);
+    }
+
+    this.operationBackups.get(operationId).push({
+      targetPath,
+      backupPath,
+      checksum,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Get rollback history
+   */
+  getRollbackHistory(operationId = null) {
+    if (operationId) {
+      return this.rollbackHistory.get(operationId);
+    }
+    return Array.from(this.rollbackHistory.values());
+  }
+
+  /**
+   * Clean up old backups
+   */
+  async cleanupOldBackups(maxAge = 24 * 60 * 60 * 1000) { // 24 hours default
+    const cutoffTime = Date.now() - maxAge;
+    const toCleanup = [];
+
+    for (const [operationId, backups] of this.operationBackups.entries()) {
+      const oldBackups = backups.filter(backup => backup.timestamp < cutoffTime);
+
+      for (const backup of oldBackups) {
+        try {
+          await fs.unlink(backup.backupPath);
+          toCleanup.push(backup);
+        } catch (error) {
+          console.warn(`Failed to cleanup backup ${backup.backupPath}:`, error.message);
+        }
+      }
+
+      // Remove cleaned up backups from tracking
+      const remainingBackups = backups.filter(backup => backup.timestamp >= cutoffTime);
+      if (remainingBackups.length === 0) {
+        this.operationBackups.delete(operationId);
+      } else {
+        this.operationBackups.set(operationId, remainingBackups);
+      }
+    }
+
+    return {
+      cleanedBackups: toCleanup.length,
+      remainingOperations: this.operationBackups.size
+    };
+  }
+
+  /**
+   * Private Methods
+   */
+
+  async _restoreFromBackup(targetPath, backupPath) {
+    // Verify backup exists
+    try {
+      await fs.access(backupPath);
+    } catch (error) {
+      throw new Error(`Backup file not found: ${backupPath}`);
+    }
+
+    // Verify backup integrity if checksum available
+    const backupChecksum = await this._calculateFileChecksum(backupPath);
+
+    // Create target directory if it doesn't exist
+    const targetDir = dirname(targetPath);
+    await fs.mkdir(targetDir, { recursive: true });
+
+    // Copy backup to target (atomic operation)
+    const tempPath = `${targetPath}.kgen-restore-${Date.now()}`;
+
+    try {
+      await fs.copyFile(backupPath, tempPath);
+      await fs.rename(tempPath, targetPath);
+
+      // Verify restoration
+      const restoredChecksum = await this._calculateFileChecksum(targetPath);
+      if (restoredChecksum !== backupChecksum) {
+        throw new Error('Restored file checksum does not match backup');
+      }
+
+    } catch (error) {
+      // Clean up temp file on failure
+      try {
+        await fs.unlink(tempPath);
+      } catch (cleanupError) {
+        console.warn('Failed to cleanup temp restore file:', tempPath);
+      }
+      throw error;
+    }
+  }
+
+  async _cleanupTemporaryFiles(operationData) {
+    // Clean up any temporary files created during operation
+    if (operationData.tempFiles) {
+      for (const tempFile of operationData.tempFiles) {
+        try {
+          await fs.unlink(tempFile);
+        } catch (error) {
+          console.warn(`Failed to cleanup temp file ${tempFile}:`, error.message);
+        }
+      }
+    }
+  }
+
+  async _releaseLocks(operationData) {
+    // Release any locks held by the operation
+    if (operationData.locks) {
+      for (const lockFile of operationData.locks) {
+        try {
+          await fs.unlink(lockFile);
+        } catch (error) {
+          console.warn(`Failed to release lock ${lockFile}:`, error.message);
+        }
+      }
+    }
+  }
+
+  _getOperationHistory(operationId) {
+    // This would normally come from the injection engine's history
+    // For now, return a mock structure
+    return {
+      id: operationId,
+      phase: 'committed',
+      results: [],
+      metadata: {}
+    };
+  }
+
+  _findOperationBackups(operationId) {
+    return this.operationBackups.get(operationId) || [];
+  }
+
+  async _calculateFileChecksum(filePath, algorithm = CHECKSUM_ALGORITHMS.SHA256) {
+    const content = await fs.readFile(filePath);
+    const hash = createHash(algorithm);
+    hash.update(content);
+    return hash.digest('hex');
+  }
+
+  /**
+   * Verify operation can be undone
+   */
+  async verifyUndoable(operationId) {
+    const operationHistory = this._getOperationHistory(operationId);
+    if (!operationHistory) {
+      return { undoable: false, reason: 'Operation not found' };
+    }
+
+    if (operationHistory.undone) {
+      return { undoable: false, reason: 'Operation already undone' };
+    }
+
+    if (operationHistory.phase !== 'committed') {
+      return { undoable: false, reason: 'Operation not completed successfully' };
+    }
+
+    const backups = this._findOperationBackups(operationId);
+    if (backups.length === 0) {
+      return { undoable: false, reason: 'No backups available' };
+    }
+
+    // Verify all backup files exist
+    for (const backup of backups) {
+      try {
+        await fs.access(backup.backupPath);
+      } catch (error) {
+        return { undoable: false, reason: `Backup file missing: ${backup.backupPath}` };
+      }
+    }
+
+    return { undoable: true, backupsCount: backups.length };
+  }
+
+  /**
+   * Create operation snapshot for recovery
+   */
+  async createOperationSnapshot(operationId, targets) {
+    const snapshot = {
+      operationId,
+      timestamp: Date.now(),
+      targets: [],
+      checksums: new Map()
+    };
+
+    for (const target of targets) {
+      try {
+        const exists = await fs.access(target.resolvedPath).then(() => true, () => false);
+        const targetInfo = {
+          path: target.resolvedPath,
+          exists,
+          checksum: null,
+          stats: null
+        };
+
+        if (exists) {
+          targetInfo.checksum = await this._calculateFileChecksum(target.resolvedPath);
+          targetInfo.stats = await fs.stat(target.resolvedPath);
+        }
+
+        snapshot.targets.push(targetInfo);
+      } catch (error) {
+        console.warn(`Failed to snapshot target ${target.resolvedPath}:`, error.message);
+      }
+    }
+
+    return snapshot;
+  }
+}

package/src/injection/target-resolver.js

@@ -0,0 +1,323 @@
+/**
+ * KGEN Target Resolver
+ *
+ * Resolves injection targets from template configuration with deterministic
+ * path resolution, glob pattern matching, and security validation.
+ */
+
+import { promises as fs } from 'fs';
+import { resolve, join, relative, dirname, basename } from 'path';
+// Simple glob implementation for basic pattern matching
+// In production, use a proper glob library like 'glob' or 'fast-glob'
+function simpleGlob(pattern, options = {}) {
+  // Very basic glob implementation for demo purposes
+  return Promise.resolve([]);
+}
+const glob = simpleGlob;
+
+import { ERROR_CODES, DEFAULT_CONFIG } from './constants.js';
+
+export class TargetResolver {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.projectRoot = config.projectRoot || process.cwd();
+  }
+
+  /**
+   * Resolve all targets from template configuration
+   */
+  async resolveTargets(templateConfig, variables = {}) {
+    const targets = [];
+
+    // Handle single target
+    if (templateConfig.to) {
+      const target = await this._resolveSingleTarget(templateConfig, variables);
+      targets.push(target);
+    }
+
+    // Handle multiple targets
+    if (templateConfig.targets && Array.isArray(templateConfig.targets)) {
+      for (const targetConfig of templateConfig.targets) {
+        const target = await this._resolveSingleTarget(targetConfig, variables);
+        targets.push(target);
+      }
+    }
+
+    if (targets.length === 0) {
+      throw new Error('No injection targets specified');
+    }
+
+    // Sort targets for deterministic processing
+    targets.sort((a, b) => a.resolvedPath.localeCompare(b.resolvedPath));
+
+    return targets;
+  }
+
+  /**
+   * Private Methods
+   */
+
+  async _resolveSingleTarget(targetConfig, variables) {
+    let targetPath = targetConfig.to;
+
+    if (!targetPath) {
+      throw new Error('Target path (to) is required');
+    }
+
+    // Variable interpolation
+    targetPath = this._interpolateVariables(targetPath, variables);
+
+    // Handle glob patterns
+    if (this._isGlobPattern(targetPath)) {
+      return await this._resolveGlobTargets(targetPath, targetConfig, variables);
+    }
+
+    // Resolve single path
+    const resolvedPath = this._resolvePath(targetPath);
+
+    // Security validation
+    this._validatePath(resolvedPath);
+
+    // Create target object
+    const target = {
+      originalPath: targetConfig.to,
+      resolvedPath,
+      mode: targetConfig.inject ? targetConfig.mode || 'append' : 'create',
+      ...targetConfig
+    };
+
+    // Apply content-based filtering if configured
+    if (targetConfig.targetIf) {
+      const shouldTarget = await this._evaluateTargetCondition(target, targetConfig.targetIf);
+      if (!shouldTarget) {
+        return null; // Skip this target
+      }
+    }
+
+    return target;
+  }
+
+  async _resolveGlobTargets(globPattern, targetConfig, variables) {
+    // Use glob to find matching files
+    const matches = await glob(globPattern, {
+      cwd: this.projectRoot,
+      absolute: true,
+      dot: false // Don't match hidden files by default
+    });
+
+    // Apply exclusion patterns
+    let filteredMatches = matches;
+    if (targetConfig.exclude) {
+      filteredMatches = this._applyExclusions(matches, targetConfig.exclude);
+    }
+
+    // Sort for deterministic order
+    if (this.config.sortGlobResults) {
+      filteredMatches.sort();
+    }
+
+    // Convert to target objects
+    const targets = [];
+    for (const matchPath of filteredMatches) {
+      this._validatePath(matchPath);
+
+      const target = {
+        originalPath: targetConfig.to,
+        resolvedPath: matchPath,
+        mode: targetConfig.inject ? targetConfig.mode || 'append' : 'create',
+        isGlobMatch: true,
+        ...targetConfig
+      };
+
+      // Apply content-based filtering
+      if (targetConfig.targetIf) {
+        const shouldTarget = await this._evaluateTargetCondition(target, targetConfig.targetIf);
+        if (shouldTarget) {
+          targets.push(target);
+        }
+      } else {
+        targets.push(target);
+      }
+    }
+
+    return targets;
+  }
+
+  _interpolateVariables(template, variables) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, variable) => {
+      const value = variables[variable];
+      if (value === undefined) {
+        throw new Error(`Variable '${variable}' not provided for path interpolation`);
+      }
+      return value;
+    });
+  }
+
+  _isGlobPattern(path) {
+    return /[*?{}\[\]]/.test(path);
+  }
+
+  _resolvePath(targetPath) {
+    // Convert to absolute path
+    if (!targetPath.startsWith('/')) {
+      return resolve(this.projectRoot, targetPath);
+    }
+    return resolve(targetPath);
+  }
+
+  _validatePath(resolvedPath) {
+    // Security: Prevent path traversal
+    if (this.config.preventPathTraversal) {
+      const relativePath = relative(this.projectRoot, resolvedPath);
+      if (relativePath.startsWith('..') || resolve(relativePath) === resolve('.')) {
+        throw new Error(`Path traversal blocked: ${resolvedPath}`, ERROR_CODES.PATH_TRAVERSAL);
+      }
+    }
+
+    // Validate file extension if configured
+    if (this.config.allowedExtensions && this.config.allowedExtensions.length > 0) {
+      const ext = this._getFileExtension(resolvedPath);
+      if (!this.config.allowedExtensions.includes(ext)) {
+        throw new Error(`File extension not allowed: ${ext}`);
+      }
+    }
+  }
+
+  _applyExclusions(matches, exclusions) {
+    const exclusionPatterns = Array.isArray(exclusions) ? exclusions : [exclusions];
+
+    return matches.filter(match => {
+      const relativePath = relative(this.projectRoot, match);
+
+      return !exclusionPatterns.some(pattern => {
+        if (this._isGlobPattern(pattern)) {
+          // Use minimatch for glob pattern exclusions
+          return this._matchesGlob(relativePath, pattern);
+        } else {
+          // Simple string includes
+          return relativePath.includes(pattern);
+        }
+      });
+    });
+  }
+
+  _matchesGlob(path, pattern) {
+    // Simple glob matching - in production, use minimatch or similar
+    const regex = pattern
+      .replace(/\*\*/g, '.*')
+      .replace(/\*/g, '[^/]*')
+      .replace(/\?/g, '[^/]');
+
+    return new RegExp(`^${regex}$`).test(path);
+  }
+
+  async _evaluateTargetCondition(target, condition) {
+    try {
+      // Check if file exists first
+      const fileExists = await this._fileExists(target.resolvedPath);
+      if (!fileExists) {
+        return false; // Can't evaluate content conditions on non-existent files
+      }
+
+      // Read file content
+      const content = await fs.readFile(target.resolvedPath, 'utf8');
+
+      // Handle different condition types
+      if (typeof condition === 'string') {
+        // Simple string or regex match
+        if (condition.startsWith('/') && condition.endsWith('/')) {
+          // Regex pattern
+          const pattern = condition.slice(1, -1);
+          const regex = new RegExp(pattern, target.regexFlags || 'gm');
+          return regex.test(content);
+        } else {
+          // Simple string search
+          return content.includes(condition);
+        }
+      }
+
+      if (typeof condition === 'function') {
+        // Custom function
+        return await condition(target, content);
+      }
+
+      if (typeof condition === 'object') {
+        // Complex condition object
+        return await this._evaluateComplexCondition(target, content, condition);
+      }
+
+      return true;
+
+    } catch (error) {
+      console.warn(`Failed to evaluate target condition for ${target.resolvedPath}:`, error.message);
+      return false;
+    }
+  }
+
+  async _evaluateComplexCondition(target, content, condition) {
+    const { pattern, size, lines, encoding } = condition;
+
+    if (pattern) {
+      if (typeof pattern === 'string') {
+        return content.includes(pattern);
+      }
+      if (pattern instanceof RegExp) {
+        return pattern.test(content);
+      }
+    }
+
+    if (size) {
+      const stats = await fs.stat(target.resolvedPath);
+      if (size.min !== undefined && stats.size < size.min) return false;
+      if (size.max !== undefined && stats.size > size.max) return false;
+    }
+
+    if (lines) {
+      const lineCount = content.split('\n').length;
+      if (lines.min !== undefined && lineCount < lines.min) return false;
+      if (lines.max !== undefined && lineCount > lines.max) return false;
+    }
+
+    if (encoding) {
+      // Check if file appears to be in expected encoding
+      const detectedEncoding = this._detectEncoding(content);
+      if (detectedEncoding !== encoding) return false;
+    }
+
+    return true;
+  }
+
+  async _fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  _getFileExtension(filePath) {
+    const name = basename(filePath);
+    const dotIndex = name.lastIndexOf('.');
+    return dotIndex === -1 ? '' : name.slice(dotIndex);
+  }
+
+  _detectEncoding(content) {
+    // Simple encoding detection - in production use a proper library
+    try {
+      // Check for UTF-8 BOM
+      if (content.startsWith('\uFEFF')) {
+        return 'utf8-bom';
+      }
+
+      // Check for non-ASCII characters
+      if (/[^\x00-\x7F]/.test(content)) {
+        return 'utf8';
+      }
+
+      return 'ascii';
+    } catch {
+      return 'unknown';
+    }
+  }
+}