@unrdf/kgn 5.0.1

package/src/injection/api.js

@@ -0,0 +1,260 @@
+/**
+ * KGEN Injection API
+ *
+ * Main API for injection operations. Provides a clean interface
+ * for the template engine to perform atomic, idempotent injections.
+ */
+
+import { InjectionEngine } from './injection-engine.js';
+import { DEFAULT_CONFIG } from './constants.js';
+
+// Global injection engine instance
+let globalInjectionEngine = null;
+
+/**
+ * Initialize injection system with configuration
+ */
+export function initializeInjection(config = {}) {
+  globalInjectionEngine = new InjectionEngine({ ...DEFAULT_CONFIG, ...config });
+  return globalInjectionEngine;
+}
+
+/**
+ * Main injection function - atomic, idempotent, deterministic
+ */
+export async function inject(templateConfig, content, variables = {}, options = {}) {
+  const engine = getInjectionEngine(options.config);
+
+  try {
+    return await engine.inject(templateConfig, content, variables);
+  } catch (error) {
+    // Enhance error with context
+    error.templateConfig = templateConfig;
+    error.variables = variables;
+    throw error;
+  }
+}
+
+/**
+ * Perform dry run to see what would be injected
+ */
+export async function dryRun(templateConfig, content, variables = {}, options = {}) {
+  const engine = getInjectionEngine(options.config);
+  return await engine.dryRun(templateConfig, content, variables);
+}
+
+/**
+ * Undo a previous injection operation
+ */
+export async function undo(operationId, options = {}) {
+  const engine = getInjectionEngine(options.config);
+  return await engine.undo(operationId);
+}
+
+/**
+ * Get injection operation history
+ */
+export function getOperationHistory(options = {}) {
+  const engine = getInjectionEngine(options.config);
+  return engine.getOperationHistory();
+}
+
+/**
+ * Batch injection operations
+ */
+export async function batchInject(operations, options = {}) {
+  const engine = getInjectionEngine(options.config);
+  const results = [];
+  const errors = [];
+
+  for (const operation of operations) {
+    try {
+      const result = await engine.inject(
+        operation.templateConfig,
+        operation.content,
+        operation.variables || {}
+      );
+      results.push({ ...result, operation });
+    } catch (error) {
+      errors.push({ error, operation });
+
+      // Stop on first error unless continueOnError is true
+      if (!options.continueOnError) {
+        break;
+      }
+    }
+  }
+
+  return {
+    results,
+    errors,
+    totalOperations: operations.length,
+    successfulOperations: results.length,
+    failedOperations: errors.length
+  };
+}
+
+/**
+ * Validate injection configuration without executing
+ */
+export async function validateInjectionConfig(templateConfig, variables = {}, options = {}) {
+  const engine = getInjectionEngine(options.config);
+
+  try {
+    // This would use internal validation methods
+    const targets = await engine.targetResolver.resolveTargets(templateConfig, variables);
+    const validationResults = await Promise.all(
+      targets.map(target => engine.validationEngine.validateTarget(target))
+    );
+
+    return {
+      valid: validationResults.every(r => r.valid),
+      targets: targets.length,
+      validationResults,
+      errors: validationResults.flatMap(r => r.errors),
+      warnings: validationResults.flatMap(r => r.warnings)
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error.message,
+      targets: 0
+    };
+  }
+}
+
+/**
+ * Get injection system status and metrics
+ */
+export function getInjectionStatus(options = {}) {
+  const engine = getInjectionEngine(options.config);
+
+  return {
+    initialized: !!engine,
+    config: engine.config,
+    activeOperations: engine.activeOperations.size,
+    operationHistory: engine.operationHistory.length,
+    cacheStats: {
+      idempotency: engine.idempotencyManager.contentCache.size,
+      validation: engine.validationEngine.validationCache.size
+    }
+  };
+}
+
+/**
+ * Clear all caches (useful for testing or memory management)
+ */
+export function clearCaches(options = {}) {
+  const engine = getInjectionEngine(options.config);
+
+  engine.idempotencyManager.clearCache();
+  engine.validationEngine.clearCache();
+
+  return {
+    cleared: true,
+    timestamp: Date.now()
+  };
+}
+
+/**
+ * Helper function to get or create injection engine
+ */
+function getInjectionEngine(config) {
+  if (config) {
+    // Create temporary engine with custom config
+    return new InjectionEngine(config);
+  }
+
+  if (!globalInjectionEngine) {
+    // Create default engine
+    globalInjectionEngine = new InjectionEngine(DEFAULT_CONFIG);
+  }
+
+  return globalInjectionEngine;
+}
+
+/**
+ * Export engine class for advanced usage
+ */
+export { InjectionEngine };
+
+/**
+ * Template integration helper - processes template with injection support
+ */
+export async function processTemplate(template, data, options = {}) {
+  const { frontmatter, content } = parseTemplate(template);
+
+  // Check if this template has injection configuration
+  if (frontmatter.inject) {
+    return await inject(frontmatter, content, data, options);
+  }
+
+  // Regular template processing would go here
+  throw new Error('Regular template processing not implemented - injection only');
+}
+
+/**
+ * Simple frontmatter parser for templates
+ */
+function parseTemplate(template) {
+  const frontmatterMatch = template.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+  if (!frontmatterMatch) {
+    return {
+      frontmatter: {},
+      content: template
+    };
+  }
+
+  try {
+    // Simple YAML-like parsing - in production use proper YAML parser
+    const frontmatterText = frontmatterMatch[1];
+    const frontmatter = parseFrontmatter(frontmatterText);
+    const content = frontmatterMatch[2];
+
+    return { frontmatter, content };
+  } catch (error) {
+    throw new Error(`Failed to parse template frontmatter: ${error.message}`);
+  }
+}
+
+/**
+ * Simple frontmatter parser (YAML-like)
+ */
+function parseFrontmatter(text) {
+  const result = {};
+  const lines = text.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.substring(0, colonIndex).trim();
+    const value = trimmed.substring(colonIndex + 1).trim();
+
+    // Simple value parsing
+    if (value === 'true') {
+      result[key] = true;
+    } else if (value === 'false') {
+      result[key] = false;
+    } else if (/^\d+$/.test(value)) {
+      result[key] = parseInt(value);
+    } else if (value.startsWith('"') && value.endsWith('"')) {
+      result[key] = value.slice(1, -1);
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      result[key] = value.slice(1, -1);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Export all injection modes for reference
+ */
+export { INJECTION_MODES, ERROR_CODES } from './constants.js';

package/src/injection/atomic-writer.js

@@ -0,0 +1,327 @@
+/**
+ * KGEN Atomic Writer
+ *
+ * Provides atomic file write operations with backup, rollback,
+ * and transactional capabilities for deterministic file modifications.
+ */
+
+import { promises as fs, createReadStream } from 'fs';
+import { join, dirname, basename, extname } from 'path';
+import { createHash } from 'crypto';
+import { pipeline } from 'stream/promises';
+
+import { ERROR_CODES, CHECKSUM_ALGORITHMS, LOCK_CONFIG } from './constants.js';
+
+export class AtomicWriter {
+  constructor(config = {}) {
+    this.config = config;
+    this.activeLocks = new Map();
+    this.activeTransactions = new Map();
+  }
+
+  /**
+   * Write file atomically using temporary file + rename
+   */
+  async writeAtomic(filePath, content, options = {}) {
+    const {
+      backup = this.config.backupEnabled,
+      operationId,
+      preserveMetadata = this.config.preservePermissions,
+      encoding = 'utf8'
+    } = options;
+
+    // Acquire file lock
+    const lockId = await this._acquireLock(filePath);
+
+    try {
+      let backupPath = null;
+      let originalStats = null;
+
+      // Create backup if enabled and file exists
+      if (backup) {
+        try {
+          originalStats = await fs.stat(filePath);
+          backupPath = await this._createBackup(filePath, operationId);
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          // File doesn't exist, no backup needed
+        }
+      }
+
+      // Create temporary file in same directory for atomic rename
+      const tempPath = await this._createTempFile(filePath);
+
+      try {
+        // Write content to temporary file
+        await fs.writeFile(tempPath, content, encoding);
+
+        // Preserve original file metadata
+        if (preserveMetadata && originalStats) {
+          await fs.chmod(tempPath, originalStats.mode);
+          await fs.utimes(tempPath, originalStats.atime, originalStats.mtime);
+        }
+
+        // Calculate checksum
+        const checksum = await this._calculateChecksum(tempPath);
+
+        // Atomic rename (this is the atomic operation)
+        await fs.rename(tempPath, filePath);
+
+        return {
+          success: true,
+          filePath,
+          backupPath,
+          checksum,
+          tempPath: null // Cleaned up by rename
+        };
+
+      } catch (error) {
+        // Clean up temp file on failure
+        try {
+          await fs.unlink(tempPath);
+        } catch (cleanupError) {
+          console.warn('Failed to cleanup temp file:', tempPath, cleanupError.message);
+        }
+
+        // Restore from backup if available
+        if (backupPath) {
+          try {
+            await fs.copyFile(backupPath, filePath);
+          } catch (restoreError) {
+            console.error('Failed to restore from backup:', restoreError);
+          }
+        }
+
+        throw error;
+      }
+
+    } finally {
+      await this._releaseLock(lockId);
+    }
+  }
+
+  /**
+   * Begin transaction for multi-file atomic operations
+   */
+  async beginTransaction(operationId) {
+    if (this.activeTransactions.has(operationId)) {
+      throw new Error(`Transaction ${operationId} already active`);
+    }
+
+    const transaction = new AtomicTransaction(operationId, this.config);
+    this.activeTransactions.set(operationId, transaction);
+
+    return transaction;
+  }
+
+  /**
+   * Private Methods
+   */
+
+  async _acquireLock(filePath) {
+    const lockId = `${filePath}-${Date.now()}-${Math.random()}`;
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < LOCK_CONFIG.TIMEOUT) {
+      // Simple file-based locking
+      const lockFile = `${filePath}.kgen-lock`;
+
+      try {
+        await fs.writeFile(lockFile, lockId, { flag: 'wx' }); // Exclusive create
+        this.activeLocks.set(lockId, lockFile);
+        return lockId;
+      } catch (error) {
+        if (error.code === 'EEXIST') {
+          // Lock exists, check if stale
+          try {
+            const lockStat = await fs.stat(lockFile);
+            if (Date.now() - lockStat.mtime > LOCK_CONFIG.TIMEOUT) {
+              // Stale lock, remove it
+              await fs.unlink(lockFile);
+            }
+          } catch (statError) {
+            // Lock file might have been removed, continue
+          }
+
+          // Wait and retry
+          await new Promise(resolve => setTimeout(resolve, LOCK_CONFIG.RETRY_DELAY));
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    throw new Error(`Failed to acquire lock for ${filePath} within timeout`);
+  }
+
+  async _releaseLock(lockId) {
+    const lockFile = this.activeLocks.get(lockId);
+    if (lockFile) {
+      try {
+        await fs.unlink(lockFile);
+      } catch (error) {
+        console.warn('Failed to release lock:', lockFile, error.message);
+      }
+      this.activeLocks.delete(lockId);
+    }
+  }
+
+  async _createBackup(filePath, operationId) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const ext = extname(filePath);
+    const base = basename(filePath, ext);
+    const dir = dirname(filePath);
+
+    const backupName = operationId
+      ? `${base}${this.config.backupSuffix}-${operationId}${ext}`
+      : `${base}${this.config.backupSuffix}-${timestamp}${ext}`;
+
+    const backupPath = join(dir, backupName);
+
+    await fs.copyFile(filePath, backupPath);
+    return backupPath;
+  }
+
+  async _createTempFile(filePath) {
+    const dir = dirname(filePath);
+    const base = basename(filePath);
+    const tempName = `.kgen-temp-${base}-${Date.now()}-${Math.random().toString(36)}`;
+    return join(dir, tempName);
+  }
+
+  async _calculateChecksum(filePath, algorithm = CHECKSUM_ALGORITHMS.SHA256) {
+    const hash = createHash(algorithm);
+    const stream = createReadStream(filePath);
+
+    await pipeline(stream, hash);
+    return hash.digest('hex');
+  }
+}
+
+/**
+ * Transaction class for multi-file atomic operations
+ */
+class AtomicTransaction {
+  constructor(operationId, config) {
+    this.operationId = operationId;
+    this.config = config;
+    this.preparedWrites = [];
+    this.backups = [];
+    this.locks = [];
+    this.committed = false;
+  }
+
+  async prepareWrite(filePath, content, options = {}) {
+    if (this.committed) {
+      throw new Error('Transaction already committed');
+    }
+
+    // Acquire lock
+    const atomicWriter = new AtomicWriter(this.config);
+    const lockId = await atomicWriter._acquireLock(filePath);
+    this.locks.push({ lockId, filePath, writer: atomicWriter });
+
+    // Create backup
+    let backupPath = null;
+    try {
+      backupPath = await atomicWriter._createBackup(filePath, this.operationId);
+      this.backups.push({ filePath, backupPath });
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+
+    // Create temp file with content
+    const tempPath = await atomicWriter._createTempFile(filePath);
+    await fs.writeFile(tempPath, content, options.encoding || 'utf8');
+
+    // Calculate checksum
+    const checksum = await atomicWriter._calculateChecksum(tempPath);
+
+    const preparedWrite = {
+      filePath,
+      tempPath,
+      backupPath,
+      checksum,
+      options
+    };
+
+    this.preparedWrites.push(preparedWrite);
+
+    return { checksum };
+  }
+
+  async commit() {
+    if (this.committed) {
+      throw new Error('Transaction already committed');
+    }
+
+    try {
+      // Validate all temp files exist and are ready
+      for (const write of this.preparedWrites) {
+        await fs.access(write.tempPath);
+      }
+
+      // Atomically rename all temp files to their targets
+      for (const write of this.preparedWrites) {
+        await fs.rename(write.tempPath, write.filePath);
+      }
+
+      this.committed = true;
+
+      // Clean up locks
+      await this._releaseLocks();
+
+      return {
+        success: true,
+        filesWritten: this.preparedWrites.length,
+        backups: this.backups.map(b => b.backupPath)
+      };
+
+    } catch (error) {
+      await this.rollback();
+      throw new Error(`Transaction commit failed: ${error.message}`);
+    }
+  }
+
+  async rollback() {
+    try {
+      // Clean up temp files
+      for (const write of this.preparedWrites) {
+        try {
+          await fs.unlink(write.tempPath);
+        } catch (error) {
+          console.warn('Failed to cleanup temp file:', write.tempPath);
+        }
+      }
+
+      // Restore from backups if any files were partially written
+      for (const backup of this.backups) {
+        try {
+          const targetExists = await fs.access(backup.filePath).then(() => true, () => false);
+          if (targetExists) {
+            await fs.copyFile(backup.backupPath, backup.filePath);
+          }
+        } catch (error) {
+          console.error('Failed to restore backup:', backup, error);
+        }
+      }
+
+      await this._releaseLocks();
+
+    } catch (error) {
+      console.error('Rollback failed:', error);
+      throw new Error(`Transaction rollback failed: ${error.message}`);
+    }
+  }
+
+  async _releaseLocks() {
+    for (const { lockId, writer } of this.locks) {
+      try {
+        await writer._releaseLock(lockId);
+      } catch (error) {
+        console.warn('Failed to release lock:', lockId, error);
+      }
+    }
+    this.locks = [];
+  }
+}

package/src/injection/constants.js

@@ -0,0 +1,136 @@
+/**
+ * Constants for KGEN Injection System
+ *
+ * Defines all constants, error codes, and configuration values
+ * used throughout the injection operations system.
+ */
+
+export const INJECTION_MODES = {
+  APPEND: 'append',
+  PREPEND: 'prepend',
+  BEFORE: 'before',
+  AFTER: 'after',
+  REPLACE: 'replace',
+  LINE_AT: 'lineAt',
+  CREATE: 'create'
+};
+
+export const SKIP_IF_LOGIC = {
+  AND: 'AND',
+  OR: 'OR'
+};
+
+export const VALIDATION_RULES = {
+  SYNTAX: 'syntax',
+  SEMANTICS: 'semantics',
+  CONFLICTS: 'conflicts',
+  ENCODING: 'encoding',
+  SIZE: 'size',
+  PERMISSIONS: 'permissions'
+};
+
+export const ERROR_CODES = {
+  TARGET_NOT_FOUND: 'TARGET_NOT_FOUND',
+  BINARY_FILE: 'BINARY_FILE',
+  READ_ONLY: 'READ_ONLY',
+  FILE_LOCKED: 'FILE_LOCKED',
+  PATH_TRAVERSAL: 'PATH_TRAVERSAL',
+  SIZE_EXCEEDED: 'SIZE_EXCEEDED',
+  VALIDATION_FAILED: 'VALIDATION_FAILED',
+  ATOMIC_FAILURE: 'ATOMIC_FAILURE',
+  ROLLBACK_FAILURE: 'ROLLBACK_FAILURE',
+  INSUFFICIENT_SPACE: 'INSUFFICIENT_SPACE',
+  ENCODING_ERROR: 'ENCODING_ERROR',
+  CONFLICT_DETECTED: 'CONFLICT_DETECTED'
+};
+
+export const DEFAULT_CONFIG = {
+  // Atomic operations
+  atomicWrites: true,
+  backupEnabled: true,
+  transactionTimeout: 30000, // 30 seconds
+
+  // File validation
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  maxLineCount: 10000,
+  validateEncoding: true,
+  preservePermissions: true,
+
+  // Deterministic behavior
+  sortGlobResults: true,
+  consistentLineEndings: true,
+  preserveWhitespace: true,
+
+  // Security
+  preventPathTraversal: true,
+  allowedExtensions: ['.js', '.ts', '.jsx', '.tsx', '.json', '.md', '.txt', '.html', '.css', '.scss'],
+
+  // Performance
+  streamLargeFiles: true,
+  streamThreshold: 1024 * 1024, // 1MB
+  maxConcurrentOperations: 5,
+
+  // Backup and recovery
+  backupSuffix: '.kgen-backup',
+  maxBackups: 10,
+  autoCleanup: true
+};
+
+export const REGEX_FLAGS = {
+  GLOBAL: 'g',
+  MULTILINE: 'm',
+  CASE_INSENSITIVE: 'i',
+  DOTALL: 's',
+  UNICODE: 'u'
+};
+
+export const LINE_ENDINGS = {
+  LF: '\n',      // Unix/Linux/macOS
+  CRLF: '\r\n',  // Windows
+  CR: '\r'       // Classic Mac
+};
+
+export const ENCODINGS = {
+  UTF8: 'utf8',
+  UTF16: 'utf16le',
+  ASCII: 'ascii',
+  LATIN1: 'latin1'
+};
+
+export const CHECKSUM_ALGORITHMS = {
+  SHA256: 'sha256',
+  MD5: 'md5',
+  SHA1: 'sha1'
+};
+
+// File type detection patterns
+export const BINARY_PATTERNS = [
+  /^\x00/,                    // Null bytes at start
+  /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/,  // Control characters
+  /\uFFFD/,                   // Replacement character (indicates binary)
+];
+
+// Content validation patterns
+export const CONTENT_PATTERNS = {
+  IMPORT_STATEMENT: /^import\s+.*from\s+['"][^'"]+['"];?\s*$/gm,
+  EXPORT_STATEMENT: /^export\s+.*$/gm,
+  FUNCTION_DECLARATION: /^(async\s+)?function\s+\w+\s*\(/gm,
+  CLASS_DECLARATION: /^class\s+\w+/gm,
+  INTERFACE_DECLARATION: /^interface\s+\w+/gm,
+  TYPE_DECLARATION: /^type\s+\w+/gm
+};
+
+// Operation metadata
+export const OPERATION_METADATA = {
+  CREATED_BY: 'KGEN Injection System',
+  VERSION: '1.0.0',
+  TIMESTAMP_FORMAT: 'YYYY-MM-DD HH:mm:ss UTC',
+  HASH_ALGORITHM: 'sha256'
+};
+
+// Concurrency control
+export const LOCK_CONFIG = {
+  TIMEOUT: 10000,     // 10 seconds
+  RETRY_DELAY: 100,   // 100ms
+  MAX_RETRIES: 100
+};