entkapp 5.4.0 → 5.6.0

package/README.md

@@ -1,4 +1,4 @@
-# 🕸️ entkapp Ultimate v5.4.0
+# 🕸️ entkapp Ultimate v5.6.0
 
 > **The Ultimate Enterprise Codebase Janitor.** High-speed OXC integration, type-aware analysis, and automated structural healing. Fully standalone architectural orchestrator.
 
@@ -35,6 +35,12 @@ Starts the interactive analysis:
 npx entkapp -r
 ```
 
+### Headless Analysis Mode
+Ideal for CI/CD pipelines. Performs analysis without prompts and outputs JSON:
+```bash
+npx entkapp --analyze
+```
+
 ### Auto-Fix Mode
 Automatically resolves dependency conflicts and structural issues:
 ```bash

package/bin/cli.js

@@ -2,10 +2,10 @@
 
 /**
  * ============================================================================
- * 🚀 entkapp: The High-Performance Codebase Orchestrator
+ * 🏁 loui CLI Entry Point
  * ============================================================================
- * Command-line interface for executing architectural audits, structural 
- * refactoring cycles, and autonomous codebase healing.
+ * Handles option compilation, environment orchestration, option validation,
+ * and initiates the primary operational pipeline loop.
  */
 
 import { Command } from 'commander';
@@ -13,104 +13,163 @@ import ansis from 'ansis';
 import path from 'path';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
-import { ConfigLoader } from '../src/resolution/ConfigLoader.js';
+import readline from 'readline/promises';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(await fs.readFile(path.join(__dirname, '../package.json'), 'utf8'));
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const program = new Command();
 
-async function main() {
+async function bootstrap() {
   try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
     program
       .name('entkapp')
-      .description('Autonomous architectural refactoring and codebase optimization engine')
-      .version(pkg.version)
-      .argument('[path]', 'Target directory for codebase analysis and refactoring', '.')
-      .option('-f, --fix', 'Automatically apply identified structural optimizations and healing', false)
+      .description(ansis.cyan('The Ultimate Enterprise Codebase Janitor with OXC integration, type-aware analysis, and automated structural healing.'))
+      .version(packageJsonContent.version || '5.6.0');
+
+    program
+      .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
+      .option('-d, --debug', 'Developer`s comprehensive telemetry debug diagnostics', false)
+      .option('--fix', 'Enable atomic code updates, structural file pruning, and active type sanitization', false)
       .option('--tsconfig <filename>', 'Specify path to custom layout configurations', 'tsconfig.json')
       .option('--test-command <command>', 'Integrated continuous safety test validation script execution path', 'npm test')
       .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
       .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false)
       .option('--visualize', 'Generate an interactive execution graph visualization', false)
-      .option('-ef, --entry-file <path>', 'Manually specify a primary entry file for analysis')
       .option('-r, --run', 'Execute the primary operational pipeline loop', false)
       .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false)
       .option('--timeout <ms>', 'Set execution timeout in milliseconds', '30000');
 
     program.parse(process.argv);
-
     const options = program.opts();
-    const targetCwd = path.resolve(process.cwd(), program.args[0] || '.');
-
-    // Load configuration
-    const configLoader = new ConfigLoader(targetCwd);
-    const localConfig = await configLoader.loadConfig(options);
-
-    if (options.verbose) {
-      const summary = {
-        packages: localConfig.workspacePackages?.length || 0,
-        tsconfigs: localConfig.workspaceTsConfigs?.length || 0,
-        configs: localConfig.workspaceConfigFiles?.length || 0
-      };
-      console.log(ansis.dim(`[ConfigLoader] Monorepo detected – ${summary.packages} package(s), ${summary.tsconfigs} tsconfig(s), ${summary.configs} *.config file(s) loaded`));
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    // --- Onboarding Check (Skipped in Non-Interactive Mode) ---
+    // FIX: Ensure options.cwd is always a string, never undefined
+    const targetCwd = path.resolve(options.cwd || process.cwd());
+    const pkgJsonPath = path.join(targetCwd, 'package.json');
+    const configDirPath = path.join(targetCwd, 'entkapp');
+
+    let pkgJson;
+    try {
+      pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
+    } catch (e) {}
+
+    let configInstalled = false;
+    if (!options.yes && !options.run) {
+      // 1. Ask to install script
+      if (pkgJson && !pkgJson.scripts?.['entkapp:run']) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "entkapp:run" script found in package.json. Install it? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          pkgJson.scripts = pkgJson.scripts || {};
+          pkgJson.scripts['entkapp:run'] = 'npx entkapp --fix';
+          await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+          console.log(ansis.green('✅ "entkapp:run" script added to package.json.'));
+        }
+      }
+
+      // 2. Ask to install config folder
+      try {
+        await fs.access(configDirPath);
+        configInstalled = true;
+      } catch (e) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "/entkapp" configuration folder found. Create it with defaults? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          await fs.mkdir(configDirPath, { recursive: true });
+          await fs.mkdir(path.join(configDirPath, 'plugins'), { recursive: true });
+          const defaultConfig = {
+            interface: "CLI",
+            useBuiltinPlugins: true,
+            useCustomPlugins: true,
+
+            options: { verbose: false, fastMode: true, selfHealing: true },
+            enabledPlugins: ["nextjs", "nuxt", "remix", "sveltekit", "astro"]
+          };
+          await fs.writeFile(path.join(configDirPath, 'config.json'), JSON.stringify(defaultConfig, null, 2));
+          console.log(ansis.green('✅ "/entkapp" folder? and default config created.'));
+          configInstalled = true;
+        }
+      }
+
+      if (pkgJson?.scripts?.['entkapp:run'] || configInstalled) {
+        console.log(ansis.bold.cyan('\n🚀 Setup complete! To start the engine, run:'));
+        console.log(ansis.white(`   - npx entkapp -r`));
+        console.log(ansis.white(`   - npm run entkapp:run\n`));
+      }
     }
 
+    rl.close();
+
+    // Load local config if available
+    let localConfig = {};
+    try {
+      const { ConfigLoader } = await import('../src/resolution/ConfigLoader.js');
+      const loader = new ConfigLoader(targetCwd);
+      localConfig = await loader.loadConfig();
+    } catch (e) {}
+
+    // Merge options with local config
+    const finalInterface = localConfig.interface || 'CLI';
+    if (finalInterface === 'GUI') {
+      console.log(ansis.bold.magenta('🎨 GUI Mode Detected. Starting Web Interface...'));
+      return;
+    }
+
+    // Only proceed to execution if -r/--run is provided
+    if (!options.run) {
+      return;
+    }
+
+    // --- Timeout Handling ---
+    const timeoutMs = parseInt(options.timeout);
     const timeoutTimer = setTimeout(() => {
-      console.error(ansis.red(`\n❌ Execution Timeout: Operation exceeded ${options.timeout}ms limit.`));
+      console.error(ansis.bold.red(`\n🚨 Execution Timeout: The process exceeded the limit of ${timeoutMs}ms.`));
       process.exit(1);
-    }, parseInt(options.timeout));
+    }, timeoutMs);
+    timeoutTimer.unref(); // Allow process to exit if work finishes
 
-    console.log('\n' + ansis.bold.cyan(`📦 entkapp v${pkg.version} Engine Activation`));
+    console.log(ansis.bold.green(`\n📦 entkapp v${packageJsonContent.version || '5.6.0'} Engine Activation`));
     console.log(ansis.dim('------------------------------------------------------------'));
-    console.log(`${ansis.bold('Target Workspace Root')} : ${targetCwd}`);
-    console.log(`${ansis.bold('Refactoring Mode')}     : ${options.fix ? ansis.yellow('Automated Healing Active') : 'Dry-Run Reporting Only'}`);
-    console.log(`${ansis.bold('Validation Sandbox')}   : ${options.testCommand}`);
+    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(targetCwd)}`);
+    console.log(`${ansis.bold('Refactoring Mode     :')} ${options.fix ? ansis.yellow('Active Fixing & Self-Healing Enabled') : ansis.gray('Dry-Run Reporting Only')}`);
+    console.log(`${ansis.bold('Validation Sandbox   :')} ${ansis.magenta(options.testCommand)}`);
     console.log(ansis.dim('------------------------------------------------------------\n'));
 
     const { RefactoringEngine } = await import('../src/index.js');
 
-    // Prepare entry points - EXTREMELY ROBUST ARRAY HANDLING
-    let entryPoints = [];
-    if (localConfig.entryPoints && typeof localConfig.entryPoints[Symbol.iterator] === 'function') {
-      entryPoints = [...localConfig.entryPoints];
-    } else if (localConfig.entryPoints) {
-      entryPoints = [localConfig.entryPoints];
-    }
-    
-    if (options.entryFile) {
-      const absEntry = path.resolve(targetCwd, options.entryFile).replace(/\\/g, '/');
-      if (!entryPoints.includes(absEntry)) {
-        entryPoints.push(absEntry);
-      }
-    }
-
     const engine = new RefactoringEngine({
       cwd: targetCwd,
       autoFix: options.fix,
       tsconfig: options.tsconfig,
       testCommand: options.testCommand,
-      workspace: options.workspace || localConfig.workspace || false,
+      workspace: options.workspace,
       verbose: options.verbose,
       skipConfirm: options.yes,
-      entryPoints: entryPoints,
-      exclude: localConfig.exclude || [],
-      rules: localConfig.rules || {},
+      // Pass through local config settings
+      entryPoints: localConfig.entryPoints,
+      exclude: localConfig.exclude,
+      rules: localConfig.rules,
       debug: options.debug,
       visualize: options.visualize,
-      workspacePackages:    localConfig.workspacePackages || [],
-      workspaceTsConfigs:   localConfig.workspaceTsConfigs || [],
-      workspaceConfigFiles: localConfig.workspaceConfigFiles || [],
     });
 
     await engine.run();
     
     clearTimeout(timeoutTimer);
-  } catch (err) {
-    console.error(ansis.red(`\n❌ Engine Failure: ${err.message}`));
-    if (program.opts().verbose) console.error(err);
+    console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
+    process.exit(0);
+
+  } catch (criticalBootError) {
+    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Boot Instability: ${criticalBootError.message}`));
+    if (criticalBootError.stack) {
+      console.error(ansis.dim(criticalBootError.stack));
+    }
     process.exit(1);
   }
 }
 
-main();
+bootstrap();

package/bin/cli.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * ============================================================================
+ * 🏁 loui CLI Entry Point
+ * ============================================================================
+ * Handles option compilation, environment orchestration, option validation,
+ * and initiates the primary operational pipeline loop.
+ */
+
+import { Command } from 'commander';
+import ansis from 'ansis';
+import path from 'path';
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+import readline from 'readline/promises';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+async function bootstrap() {
+  try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
+    program
+      .name('entkapp')
+      .description(ansis.cyan('The Ultimate Enterprise Codebase Janitor with OXC integration, type-aware analysis, and automated structural healing.'))
+      .version(packageJsonContent.version || '5.6.0');
+
+    program
+      .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
+      .option('-d, --debug', 'Developer`s comprehensive telemetry debug diagnostics', false)
+      .option('--fix', 'Enable atomic code updates, structural file pruning, and active type sanitization', false)
+      .option('--tsconfig <filename>', 'Specify path to custom layout configurations', 'tsconfig.json')
+      .option('--test-command <command>', 'Integrated continuous safety test validation script execution path', 'npm test')
+      .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
+      .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false)
+      .option('--visualize', 'Generate an interactive execution graph visualization', false)
+      .option('-r, --run', 'Execute the primary operational pipeline loop', false)
+      .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false)
+      .option('--timeout <ms>', 'Set execution timeout in milliseconds', '30000');
+
+    program.parse(process.argv);
+    const options = program.opts();
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    // --- Onboarding Check (Skipped in Non-Interactive Mode) ---
+    // FIX: Ensure options.cwd is always a string, never undefined
+    const targetCwd = path.resolve(options.cwd || process.cwd());
+    const pkgJsonPath = path.join(targetCwd, 'package.json');
+    const configDirPath = path.join(targetCwd, 'entkapp');
+
+    let pkgJson;
+    try {
+      pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
+    } catch (e) {}
+
+    let configInstalled = false;
+    if (!options.yes && !options.run) {
+      // 1. Ask to install script
+      if (pkgJson && !pkgJson.scripts?.['entkapp:run']) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "entkapp:run" script found in package.json. Install it? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          pkgJson.scripts = pkgJson.scripts || {};
+          pkgJson.scripts['entkapp:run'] = 'npx entkapp --fix';
+          await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+          console.log(ansis.green('✅ "entkapp:run" script added to package.json.'));
+        }
+      }
+
+      // 2. Ask to install config folder
+      try {
+        await fs.access(configDirPath);
+        configInstalled = true;
+      } catch (e) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "/entkapp" configuration folder found. Create it with defaults? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          await fs.mkdir(configDirPath, { recursive: true });
+          await fs.mkdir(path.join(configDirPath, 'plugins'), { recursive: true });
+          const defaultConfig = {
+            interface: "CLI",
+            useBuiltinPlugins: true,
+            useCustomPlugins: true,
+
+            options: { verbose: false, fastMode: true, selfHealing: true },
+            enabledPlugins: ["nextjs", "nuxt", "remix", "sveltekit", "astro"]
+          };
+          await fs.writeFile(path.join(configDirPath, 'config.json'), JSON.stringify(defaultConfig, null, 2));
+          console.log(ansis.green('✅ "/entkapp" folder? and default config created.'));
+          configInstalled = true;
+        }
+      }
+
+      if (pkgJson?.scripts?.['entkapp:run'] || configInstalled) {
+        console.log(ansis.bold.cyan('\n🚀 Setup complete! To start the engine, run:'));
+        console.log(ansis.white(`   - npx entkapp -r`));
+        console.log(ansis.white(`   - npm run entkapp:run\n`));
+      }
+    }
+
+    rl.close();
+
+    // Load local config if available
+    let localConfig = {};
+    try {
+      const { ConfigLoader } = await import('../src/resolution/ConfigLoader.mjs');
+      const loader = new ConfigLoader(targetCwd);
+      localConfig = await loader.loadConfig();
+    } catch (e) {}
+
+    // Merge options with local config
+    const finalInterface = localConfig.interface || 'CLI';
+    if (finalInterface === 'GUI') {
+      console.log(ansis.bold.magenta('🎨 GUI Mode Detected. Starting Web Interface...'));
+      return;
+    }
+
+    // Only proceed to execution if -r/--run is provided
+    if (!options.run) {
+      return;
+    }
+
+    // --- Timeout Handling ---
+    const timeoutMs = parseInt(options.timeout);
+    const timeoutTimer = setTimeout(() => {
+      console.error(ansis.bold.red(`\n🚨 Execution Timeout: The process exceeded the limit of ${timeoutMs}ms.`));
+      process.exit(1);
+    }, timeoutMs);
+    timeoutTimer.unref(); // Allow process to exit if work finishes
+
+    console.log(ansis.bold.green(`\n📦 entkapp v${packageJsonContent.version || '5.6.0'} Engine Activation`));
+    console.log(ansis.dim('------------------------------------------------------------'));
+    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(targetCwd)}`);
+    console.log(`${ansis.bold('Refactoring Mode     :')} ${options.fix ? ansis.yellow('Active Fixing & Self-Healing Enabled') : ansis.gray('Dry-Run Reporting Only')}`);
+    console.log(`${ansis.bold('Validation Sandbox   :')} ${ansis.magenta(options.testCommand)}`);
+    console.log(ansis.dim('------------------------------------------------------------\n'));
+
+    const { RefactoringEngine } = await import('../src/index.mjs');
+
+    const engine = new RefactoringEngine({
+      cwd: targetCwd,
+      autoFix: options.fix,
+      tsconfig: options.tsconfig,
+      testCommand: options.testCommand,
+      workspace: options.workspace,
+      verbose: options.verbose,
+      skipConfirm: options.yes,
+      // Pass through local config settings
+      entryPoints: localConfig.entryPoints,
+      exclude: localConfig.exclude,
+      rules: localConfig.rules,
+      debug: options.debug,
+      visualize: options.visualize,
+    });
+
+    await engine.run();
+    
+    clearTimeout(timeoutTimer);
+    console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
+    process.exit(0);
+
+  } catch (criticalBootError) {
+    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Boot Instability: ${criticalBootError.message}`));
+    if (criticalBootError.stack) {
+      console.error(ansis.dim(criticalBootError.stack));
+    }
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/index.cjs

@@ -0,0 +1,18 @@
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * entkapp Legacy CJS Wrapper
+ * Allows the tool to be used in older Node.js environments.
+ */
+module.exports = async function runLegacy() {
+  console.log("⚠️ Running in Legacy CommonJS mode...");
+  const { EntkappEngine } = await import('./src/index.js');
+  const { EngineContext } = await import('./src/EngineContext.js');
+  
+  const targetCwd = process.cwd();
+  const context = new EngineContext(targetCwd);
+  const engine = new EntkappEngine(context);
+  
+  return engine.run();
+};

package/index.mjs

@@ -0,0 +1,51 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import ansis from 'ansis';
+import { Initializer } from './src/Initializer.mjs';
+import { EngineContext } from './src/EngineContext.mjs';
+import { EntkappEngine } from './src/index.mjs';
+
+/**
+ * entkapp Ultimate v5.2.0
+ * The main interactive entry point that orchestrates the entire workflow.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const isVerbose = args.includes('--verbose');
+  const cwdIdx = args.indexOf('--cwd');
+  const targetCwd = (cwdIdx !== -1 && args[cwdIdx + 1]) ? path.resolve(args[cwdIdx + 1]) : process.cwd();
+
+  try {
+    const context = new EngineContext(targetCwd);
+    context.verbose = isVerbose;
+    context.options = {
+      autoFix: args.includes('--fix'),
+      skipConfirm: args.includes('-y') || args.includes('--yes'),
+      debug: args.includes('--debug')
+    };
+
+    // 1. Initialize Project (Scaffold / package.json)
+    const initializer = new Initializer(context);
+    await initializer.run();
+
+    // 2. Run Engine
+    const engine = new EntkappEngine(context);
+    await engine.run();
+
+  } catch (err) {
+    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Failure: ${err.message}`));
+    if (isVerbose) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+// Only run if executed directly
+const currentFilePath = path.resolve(process.argv[1]);
+const indexFilePath = path.resolve(import.meta.url.replace('file://', ''));
+
+if (currentFilePath === indexFilePath) {
+  main();
+}
+
+export { EntkappEngine, EngineContext, Initializer };

package/package.json

@@ -1,20 +1,20 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "name": "entkapp",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "The Ultimate Enterprise Codebase Janitor. High-speed OXC integration, type-aware analysis, and automated structural healing. Fully standalone architectural orchestrator.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "entkapp": "./bin/cli.js"
+    "entkapp": "./bin/cli.mjs"
   },
   "scripts": {
-    "start": "node bin/cli.js",
+    "start": "node bin/cli.mjs",
     "entkapp:run": "npx entkapp --fix",
-    "test": "echo \"Error: no test specified\" && exit 0",
+    "test": "node test.js",
     "test:stability": "npm run test",
     "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs && cp docs/sitemap.xml docs/.vitepress/dist/ && cp docs/robots.txt docs/.vitepress/dist && cp logo.png docs/.vitepress/dist",
+    "docs:build": "vitepress build docs && (cp docs/sitemap.xml docs/.vitepress/dist/ || true) && (cp docs/robots.txt docs/.vitepress/dist || true) && (cp logo.png docs/.vitepress/dist || true)",
     "docs:preview": "vitepress preview docs"
   },
   "keywords": [
@@ -82,7 +82,8 @@
     "enhanced-resolve": "^5.24.0",
     "execa": "^8.0.1",
     "oxc-parser": "^0.135.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "glob": "^10.3.10"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/EngineContext.js

@@ -419,12 +419,6 @@ export class EngineContext {
     report.importedUnusedPackages = Array.from(this.importedUnusedPackages);
     report.unusedBinaries = Array.from(this.unusedBinaries);
 
-    // UPGRADE 5.4.3: Integrate enhanced results from GraphAnalyzer
-    const analyzer = new (await import('./resolution/GraphAnalyzer.js')).GraphAnalyzer(this);
-    const { unusedImports, boundaryViolations } = await analyzer.findDeadCode();
-    report.unusedImports = unusedImports;
-    report.boundaryViolations = boundaryViolations;
-
     return report;
   }
 }