pkg-scaffold 2.2.0 → 2.4.0

package/src/ast/BarrelParser.js

@@ -0,0 +1,177 @@
+import ts from 'typescript';
+import fs from 'fs/promises';
+
+/**
+ * Enterprise Wildcard Optimization & Flattening Layer for Barrel Operations
+ * Traces unreferenced paths through redistribution entries.
+ */
+export class BarrelParser {
+  constructor(context, resolver) {
+    this.context = context;
+    this.resolver = resolver;
+    this.cachedSpecifications = new Map();
+  }
+
+  /**
+   * Compiles the structural export layout for a specific index or barrel target.
+   * @param {string} filePath - Absolute path to on-disk target element
+   */
+  async parseBarrelSpecification(filePath) {
+    if (this.cachedSpecifications.has(filePath)) {
+      return this.cachedSpecifications.get(filePath);
+    }
+
+    const specification = {
+      isBarrelInstance: false,
+      wildcardExports: new Set(),         // export * from './module';
+      namespacedWildcardExports: new Map(), // export * as Utils from './module';
+      forwardedNamedExports: new Map(),   // export { token as alias } from './module';
+      declaredLocalExports: new Set()      // export const a = 1;
+    };
+
+    try {
+      const code = await fs.readFile(filePath, 'utf8');
+      const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
+
+      this.harvestExportSignatures(sourceFile, specification);
+
+      if (specification.wildcardExports.size > 0 || 
+          specification.namespacedWildcardExports.size > 0 || 
+          specification.forwardedNamedExports.size > 0) {
+        specification.isBarrelInstance = true;
+      }
+
+      this.cachedSpecifications.set(filePath, specification);
+      return specification;
+    } catch {
+      return specification; // Error state defaults to safe boundaries layout manifest
+    }
+  }
+
+  harvestExportSignatures(node, spec) {
+    if (!node) return;
+
+    switch (node.kind) {
+      case ts.SyntaxKind.ExportDeclaration: {
+        const targetSpecifier = node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)
+          ? node.moduleSpecifier.text
+          : null;
+
+        if (targetSpecifier) {
+          if (!node.exportClause) {
+            // Standard Wildcard Transfer: export * from './module';
+            spec.wildcardExports.add(targetSpecifier);
+          } else if (ts.isNamespaceExport(node.exportClause)) {
+            // Namespaced Wildcard Transfer: export * as Core from './module';
+            const namespaceAlias = node.exportClause.name.text;
+            spec.namespacedWildcardExports.set(namespaceAlias, targetSpecifier);
+          } else if (ts.isNamedExports(node.exportClause)) {
+            // Selective Re-export Forwarding: export { x, y as z } from './module';
+            node.exportClause.elements.forEach(element => {
+              const originalSymbol = element.propertyName ? element.propertyName.text : element.name.text;
+              const exposedAlias = element.name.text;
+              spec.forwardedNamedExports.set(exposedAlias, {
+                targetModule: targetSpecifier,
+                sourceSymbol: originalSymbol
+              });
+            });
+          }
+        }
+        break;
+      }
+
+      // Track items declared directly within the file boundary
+      case ts.SyntaxKind.FunctionDeclaration:
+      case ts.SyntaxKind.ClassDeclaration:
+      case ts.SyntaxKind.InterfaceDeclaration:
+      case ts.SyntaxKind.TypeAliasDeclaration:
+      case ts.SyntaxKind.EnumDeclaration: {
+        if (node.modifiers && node.modifiers.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) {
+          if (node.name && ts.isIdentifier(node.name)) {
+            spec.declaredLocalExports.add(node.name.text);
+          }
+        }
+        break;
+      }
+
+      case ts.SyntaxKind.VariableStatement: {
+        if (node.modifiers && node.modifiers.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) {
+          node.declarationList.declarations.forEach(decl => {
+            if (ts.isIdentifier(decl.name)) {
+              spec.declaredLocalExports.add(decl.name.text);
+            }
+          });
+        }
+        break;
+      }
+    }
+
+    ts.forEachChild(node, child => this.harvestExportSignatures(child, spec));
+  }
+
+  /**
+   * Challenge #3 Resolution Logic. Unwraps nested redistribution links to find origin source nodes.
+   * @param {string} contextFilePath - Current position filename vector pointer
+   * @param {string} targetSymbolName - Targeted semantic variable signature name
+   * @param {Map} activeProjectGraph - Global active module maps directory registry
+   * @param {Set} [protectionStack] - Avoids cyclic validation traps inside self-referencing links
+   */
+  async determineSymbolDeclarationOrigin(contextFilePath, targetSymbolName, activeProjectGraph, protectionStack = new Set()) {
+    if (protectionStack.has(contextFilePath)) {
+      return { originFile: contextFilePath, originSymbol: targetSymbolName };
+    }
+    protectionStack.add(contextFilePath);
+
+    const spec = await this.parseBarrelSpecification(contextFilePath);
+    if (!spec.isBarrelInstance) {
+      return { originFile: contextFilePath, originSymbol: targetSymbolName };
+    }
+
+    // Rule A: Settle boundary immediately if local declaration matches token signature name
+    if (spec.declaredLocalExports.has(targetSymbolName)) {
+      return { originFile: contextFilePath, originSymbol: targetSymbolName };
+    }
+
+    // Rule B: Evaluate explicit named re-export mappings
+    if (spec.forwardedNamedExports.has(targetSymbolName)) {
+      const routingRule = spec.forwardedNamedExports.get(targetSymbolName);
+      const fullyResolvedPath = this.resolver.resolveModulePath(contextFilePath, routingRule.targetModule);
+      return this.determineSymbolDeclarationOrigin(fullyResolvedPath, routingRule.sourceSymbol, activeProjectGraph, protectionStack);
+    }
+
+    // Rule C: Evaluate structural namespace alias groupings
+    if (spec.namespacedWildcardExports.has(targetSymbolName)) {
+      const relativeModule = spec.namespacedWildcardExports.get(targetSymbolName);
+      const fullyResolvedPath = this.resolver.resolveModulePath(contextFilePath, relativeModule);
+      return { originFile: fullyResolvedPath, originSymbol: '*' };
+    }
+
+    // Rule D: Sweep through anonymous star re-exports vectors
+    for (const relativePath of spec.wildcardExports) {
+      const fullyResolvedPath = this.resolver.resolveModulePath(contextFilePath, relativePath);
+      
+      // Look inside the graph metadata map configuration to verify child target availability
+      const targetSubSpec = await this.parseBarrelSpecification(fullyResolvedPath);
+      
+      if (targetSubSpec.declaredLocalExports.has(targetSymbolName) || 
+          targetSubSpec.forwardedNamedExports.has(targetSymbolName)) {
+        return this.determineSymbolDeclarationOrigin(fullyResolvedPath, targetSymbolName, activeProjectGraph, protectionStack);
+      }
+
+      // Dynamic recursive trace for multi-tier nested barrel file layouts
+      if (targetSubSpec.isBarrelInstance) {
+        const continuousResolutionTrace = await this.determineSymbolDeclarationOrigin(
+          fullyResolvedPath,
+          targetSymbolName,
+          activeProjectGraph,
+          protectionStack
+        );
+        if (continuousResolutionTrace && continuousResolutionTrace.originFile !== fullyResolvedPath) {
+          return continuousResolutionTrace;
+        }
+      }
+    }
+
+    return { originFile: contextFilePath, originSymbol: targetSymbolName };
+  }
+}

package/src/ast/MagicDetector.js

@@ -0,0 +1,154 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * Ecosystem Entry Point Manifest & Dynamic Framework Router Heuristic Validator
+ * Intercepts implicit conventions to handle cases where direct import statements are absent.
+ */
+export class MagicDetector {
+  constructor(context) {
+    this.context = context;
+    this.manifestSchemaRules = this.compileEcosystemSchemaMatrices();
+  }
+
+  /**
+   * Compiles explicit layout definitions to handle various web development environments.
+   */
+  compileEcosystemSchemaMatrices() {
+    return {
+      nextjs: {
+        configFiles: ['next.config.js', 'next.config.mjs', 'next.config.ts'],
+        routePatterns: [
+          /\/pages\/api\//,
+          /\/pages\/[a-zA-Z0-9_\-\[\]]+/i,
+          /\/app\/([\w\-\[\]]+\/)+(page|route|layout|loading|error|not-found)\.(ts|tsx|js|jsx)$/
+        ],
+        requiredSystemContracts: ['default', 'getServerSideProps', 'getStaticProps', 'getStaticPaths', 'generateMetadata', 'middleware']
+      },
+      nuxt: {
+        configFiles: ['nuxt.config.js', 'nuxt.config.ts'],
+        routePatterns: [
+          /\/pages\//,
+          /\/server\/(api|routes|middleware)\//,
+          /\/components\/[a-zA-Z0-9_\-\/]+\.vue$/
+        ],
+        requiredSystemContracts: ['default']
+      },
+      remix: {
+        configFiles: ['remix.config.js', 'vite.config.js', 'vite.config.ts'],
+        routePatterns: [
+          /\/app\/routes\//,
+          /\/app\/root\.(tsx|jsx)$/
+        ],
+        requiredSystemContracts: ['default', 'loader', 'action', 'meta', 'links']
+      },
+      sveltekit: {
+        configFiles: ['svelte.config.js', 'vite.config.ts'],
+        routePatterns: [
+          /\+page\.(svelte|ts|js)$/,
+          /\+page\.server\.(ts|js)$/,
+          /\+layout\.(svelte|ts|js)$/,
+          /\+server\.(ts|js)$/
+        ],
+        requiredSystemContracts: ['load', 'actions', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+      },
+      astro: {
+        configFiles: ['astro.config.mjs', 'astro.config.cjs', 'astro.config.ts'],
+        routePatterns: [
+          /\/src\/pages\/.*\.astro$/,
+          /\/src\/pages\/.*\.(ts|js)$/
+        ],
+        requiredSystemContracts: ['default', 'getStaticPaths']
+      }
+    };
+  }
+
+  /**
+   * Audits the project context to map active micro-framework ecosystems.
+   * @param {string} baseContextDirectory - Root file workspace context execution vector path
+   */
+  async identifyActiveProjectEcosystems(baseContextDirectory) {
+    const activeFrameworkFlags = [];
+    
+    for (const [frameworkKey, criteria] of Object.entries(this.manifestSchemaRules)) {
+      for (const configFile of criteria.configFiles) {
+        try {
+          await fs.access(path.join(baseContextDirectory, configFile));
+          activeFrameworkFlags.push(frameworkKey);
+          break; // Stop scanning once config criteria is found
+        } catch {
+          // File path criteria absent; proceed to standard verification loops
+        }
+      }
+    }
+    
+    // Universal infrastructure overrides (testing platforms and common bundlers)
+    activeFrameworkFlags.push('universal-tooling-vectors');
+    return activeFrameworkFlags;
+  }
+
+  /**
+   * Assesses if a file path acts as an implicit route entry point.
+   */
+  isImplicitlyRequiredByEcosystem(absolutePath, activeFrameworks) {
+    const normalizedSystemPath = absolutePath.replace(/\\/g, '/');
+
+    for (const framework of activeFrameworks) {
+      const frameworkRules = this.manifestSchemaRules[framework];
+      if (!frameworkRules) continue;
+
+      const matchesPattern = frameworkRules.routePatterns.some(regex => regex.test(normalizedSystemPath));
+      if (matchesPattern) return true;
+    }
+
+    // Apply baseline platform rules (Test suites, lint parameters, continuous integration files)
+    if (this.isCoreToolingSuiteElement(normalizedSystemPath)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  isCoreToolingSuiteElement(normalizedPath) {
+    // Testing and execution matrices rules configuration keys
+    if (/\.(test|spec|e2e|cy)\.(js|ts|tsx|jsx|stories\.tsx|stories\.ts)$/i.test(normalizedPath)) return true;
+    
+    // Testing tools and structural environment frameworks configuration keys
+    const testEnvironments = [
+      'jest.config.', 'vitest.config.', 'playwright.config.', 'cypress.config.',
+      'webpack.config.', 'vite.config.', 'rollup.config.', 'tailwind.config.',
+      '.eslintrc.', 'prettier.config.', '.postcssrc.', 'postcss.config.'
+    ];
+    
+    return testEnvironments.some(matchPattern => normalizedPath.includes(matchPattern));
+  }
+
+  /**
+   * Challenge #4 Framework Overrides. Protects interface boundaries from false positive report flags.
+   */
+  injectVirtualConsumerEdges(filePath, fileNode, activeFrameworks) {
+    if (!this.isImplicitlyRequiredByEcosystem(filePath, activeFrameworks)) return;
+
+    // Retain entry point elements within memory to keep verification safe
+    fileNode.isLibraryEntry = true;
+
+    // Apply dynamic exports coverage metrics based on active platform contracts
+    const normalizedPath = filePath.replace(/\\/g, '/');
+
+    for (const framework of activeFrameworks) {
+      const frameworkRules = this.manifestSchemaRules[framework];
+      if (!frameworkRules) continue;
+
+      // If the file path matches the active framework schema, protect its interface keywords
+      const appliesToFramework = frameworkRules.routePatterns.some(regex => regex.test(normalizedPath));
+      if (appliesToFramework) {
+        frameworkRules.requiredSystemContracts.forEach(contractMethodToken => {
+          if (fileNode.internalExports.has(contractMethodToken)) {
+            // Emulate active local reference linkages to protect the export
+            fileNode.instantiatedIdentifiers.add(contractMethodToken);
+          }
+        });
+      }
+    }
+  }
+}

package/src/healing/GitSandbox.js

@@ -0,0 +1,160 @@
+import { execSync } from 'child_process';
+import path from 'path';
+
+/**
+ * Ephemeral Git Sandbox & Version Control Islolation Gateway
+ * Manages atomic branch switching, working-tree stashing, and systemic rollbacks.
+ */
+export class GitSandbox {
+  constructor(context) {
+    this.context = context;
+    this.originalBranch = null;
+    this.sandboxBranch = null;
+    this.hasStashedChanges = false;
+    this.isGitRepository = false;
+  }
+
+  /**
+   * Validates the active environment and isolates the working directory.
+   */
+  async establishIsolationCheckpoint() {
+    this.verifyGitRepositoryPresence();
+    if (!this.isGitRepository) return;
+
+    try {
+      // Capture the current branch name
+      this.originalBranch = execSync('git rev-parse --abbrev-ref HEAD', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      // Check for uncommitted working directory changes
+      const statusOutput = execSync('git status --porcelain', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      if (statusOutput.length > 0) {
+        if (this.context.verbose) {
+          console.log('📦 Working tree contains uncommitted changes. Stashing before running pipeline...');
+        }
+        execSync('git stash save "pkg-scaffold: Ephemeral Checkpoint Stash"', { 
+          cwd: this.context.cwd, 
+          stdio: 'ignore' 
+        });
+        this.hasStashedChanges = true;
+      }
+
+      // Generate an isolated tracking branch name
+      this.sandboxBranch = `scaffold-heal-${Date.now()}`;
+      execSync(`git checkout -b ${this.sandboxBranch}`, { 
+        cwd: this.context.cwd, 
+        stdio: 'ignore' 
+      });
+
+      if (this.context.verbose) {
+        console.log(`🌿 Isolated sandbox branch successfully initialized: [${this.sandboxBranch}]`);
+      }
+    } catch (error) {
+      throw new Error(`Git Sandbox separation failure: ${error.message}`);
+    }
+  }
+
+  /**
+   * Commits all modifications within the sandbox branch for validation testing.
+   */
+  async stageAndCheckpointChanges(commitMessage = 'refactor(scaffold): apply structural optimizations') {
+    if (!this.isGitRepository) return;
+    this.assertActiveIsolation();
+
+    try {
+      execSync('git add .', { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      // Check if any mutations were actually staged
+      const diffIndex = execSync('git diff --cached --name-only', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      if (diffIndex.length === 0) return; // No modifications to verify
+
+      execSync(`git commit -m "${commitMessage}" --no-verify`, { 
+        cwd: this.context.cwd, 
+        stdio: 'ignore' 
+      });
+    } catch (error) {
+      throw new Error(`Failed to stage changes inside the sandbox: ${error.message}`);
+    }
+  }
+
+  /**
+   * Merges modifications back into the mainline branch if all validation test suites pass.
+   */
+  async acceptAndMergeOptimizations() {
+    if (!this.isGitRepository) return;
+    this.assertActiveIsolation();
+
+    try {
+      // Return to the original project branch boundary
+      execSync(`git checkout ${this.originalBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      // Merge the verified changes without creating a fast-forward bottleneck
+      execSync(`git merge --squash ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync('git commit -m "chore(refactor): apply verified dead-code removals" --no-verify', {
+        cwd: this.context.cwd,
+        stdio: 'ignore'
+      });
+
+      // Purge the temporary branch tracking reference
+      execSync(`git branch -D ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      this.restorePreviousWorkingState();
+    } catch (error) {
+      throw new Error(`Failed to merge sandbox modifications into mainline branch: ${error.message}`);
+    }
+  }
+
+  /**
+   * Reverts all disk changes instantly if testing suites flag an error.
+   */
+  async rejectAndAbortOptimizations() {
+    if (!this.isGitRepository) return;
+    if (!this.sandboxBranch) return;
+
+    try {
+      if (this.context.verbose) {
+        console.log('🔄 Aborting transaction loop. Resetting file systems...');
+      }
+      
+      execSync('git add . && git reset --hard HEAD', { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync(`git checkout ${this.originalBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync(`git branch -D ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      this.restorePreviousWorkingState();
+    } catch (error) {
+      console.error(`🚨 Critical Recovery Error: Failed to drop sandbox branch cleanly: ${error.message}`);
+    }
+  }
+
+  restorePreviousWorkingState() {
+    if (this.hasStashedChanges) {
+      execSync('git stash pop', { cwd: this.context.cwd, stdio: 'ignore' });
+      this.hasStashedChanges = false;
+    }
+    this.sandboxBranch = null;
+  }
+
+  verifyGitRepositoryPresence() {
+    try {
+      execSync('git rev-parse --is-inside-work-tree', { cwd: this.context.cwd, stdio: 'ignore' });
+      this.isGitRepository = true;
+    } catch {
+      this.isGitRepository = false;
+    }
+  }
+
+  assertActiveIsolation() {
+    if (!this.sandboxBranch) {
+      throw new Error('Git Sandbox operation error: No active sandbox tracking context exists.');
+    }
+  }
+}

package/src/healing/SelfHealer.js

@@ -0,0 +1,150 @@
+import { spawn } from 'child_process';
+import path from 'path';
+
+/**
+ * Self-Healing Test Orchestration & Regression Scanner
+ * Runs validation suites, intercepts stack traces, and controls transaction rollbacks.
+ */
+export class SelfHealer {
+  constructor(context, transactionManager, gitSandbox) {
+    this.context = context;
+    this.transactionManager = transactionManager;
+    this.gitSandbox = gitSandbox;
+    this.executionTimeout = 45000; // 45-second execution timeout wall
+  }
+
+  /**
+   * Validates the stability of staged code changes by running your project's test suite.
+   * @param {Function} refactorTask - The function containing code changes to evaluate
+   */
+  async runSelfHealingLifecycle(refactorTask) {
+    console.log('🛡️  Initializing transaction safety sandbox...');
+    
+    // Step 1: Open the transaction boundaries
+    await this.gitSandbox.establishIsolationCheckpoint();
+    await this.transactionManager.begin();
+
+    try {
+      // Step 2: Execute the codebase pruning transformations
+      await refactorTask();
+
+      // Step 3: Stage changes inside our Git tracking context
+      await this.gitSandbox.checkpointChanges();
+
+      console.log('🧪 Running testing suites to verify workspace integrity...');
+      const validationPassed = await this.verifyProjectHealthStatus();
+
+      if (validationPassed) {
+        console.log('✨ Build stable. Merging verified code improvements.');
+        await this.transactionManager.commit();
+        await this.gitSandbox.acceptAndMergeOptimizations();
+        return true;
+      } else {
+        console.warn('⚠️  Regression flagged during validation. Triggering self-healing rollback...');
+        await this.revertWorkspaceToSafeState();
+        return false;
+      }
+    } catch (pipelineError) {
+      console.error(`🚨 Critical Exception Intercepted: ${pipelineError.message}`);
+      await this.revertWorkspaceToSafeState();
+      return false;
+    }
+  }
+
+  /**
+   * Spawns testing processes to detect exit code alerts or compiler trace metrics.
+   * @returns {Promise<boolean>} True if the test suite runs with an exit code of 0
+   */
+  verifyProjectHealthStatus() {
+    return new Promise((resolve) => {
+      const commandTokens = this.context.testCommand.split(' ');
+      const executionBinary = commandTokens.shift();
+      
+      const processBuffer = [];
+      const testProcess = spawn(executionBinary, commandTokens, {
+        cwd: this.context.cwd,
+        shell: true
+      });
+
+      // Implement an execution timeout monitor to prevent hanging test suites from blocking the pipeline
+      const timeoutWatch = setTimeout(() => {
+        console.warn('⏱️  Test execution exceeded timeout limit. Terminating subprocess...');
+        testProcess.kill('SIGKILL');
+      }, this.executionTimeout);
+
+      testProcess.stdout.on('data', (data) => {
+        processBuffer.push(data);
+        if (this.context.verbose) {
+          process.stdout.write(data);
+        }
+      });
+
+      testProcess.stderr.on('data', (data) => {
+        processBuffer.push(data);
+        if (this.context.verbose) {
+          process.stderr.write(data);
+        }
+      });
+
+      testProcess.on('close', (exitCode) => {
+        clearTimeout(timeoutWatch);
+        
+        if (exitCode !== 0) {
+          const fullConsoleOutput = Buffer.concat(processBuffer).toString('utf8');
+          this.diagnoseErrorOutput(fullConsoleOutput);
+          resolve(false);
+        } else {
+          resolve(true);
+        }
+      });
+
+      testProcess.on('error', (err) => {
+        clearTimeout(timeoutWatch);
+        if (this.context.verbose) {
+          console.error(`Subprocess execution error: ${err.message}`);
+        }
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Traces error codes and console log outputs to identify the root cause of a broken build.
+   */
+  diagnoseErrorOutput(consoleLogOutput) {
+    console.log('\n🔍 [Diagnostics] Reviewing error output...');
+    
+    // Scan for standard TypeScript Compilation errors
+    const tsErrorPattern = /error\s+TS(\d+):\s+([\s\S]*?)$/m;
+    const tsMatches = consoleLogOutput.match(tsErrorPattern);
+    
+    if (tsMatches) {
+      console.error(`❌ Mapped Type Error Code [TS${tsMatches[1]}]: ${tsMatches[2].trim()}`);
+      return;
+    }
+
+    // Scan for missing file imports or runtime resolution exceptions
+    const missingModulePattern = /Cannot find module '([^']+)'/i;
+    const moduleMatches = consoleLogOutput.match(missingModulePattern);
+    
+    if (moduleMatches) {
+      console.error(`❌ Missing Dependency Reference Pointer: Cannot locate element [${moduleMatches[1]}]`);
+      return;
+    }
+
+    console.error('❌ Test suite execution failed. Check standard console output for details.');
+  }
+
+  /**
+   * Automatically executes a rollback event, restoring both file states and Git status.
+   */
+  async revertWorkspaceToSafeState() {
+    try {
+      await this.transactionManager.rollback();
+      await this.gitSandbox.rejectAndAbortOptimizations();
+      console.log('🔄 [Self-Healing] Rollback complete. Original project states restored.');
+    } catch (recoveryError) {
+      console.error(`🚨 Fatal Recovery Error: Failed to restore prior workspace configuration: ${recoveryError.message}`);
+    }
+  }
+}