@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/src/cli/diagnostics/plugin-checker.js

@@ -1,105 +1,52 @@
 /**
- * Plugin checker for RAG Pipeline Diagnostics
- * Checks plugin availability, version conflicts, and outdated plugins
+ * Plugin diagnostics: every custom plugin path under `plugins` exists and
+ * loads. Checked locally; no registry is contacted.
  */
 
-const fs = require("fs/promises");
+const fs = require("fs");
 const path = require("path");
 
-/**
- * Check plugin issues
- * @param {object} options - Doctor options (must include configPath)
- * @returns {Promise<Array>} Array of plugin issues
- */
 async function checkPlugins(options) {
-  const issues = [];
-
+  const configPath = path.resolve(options.configPath);
+  let config;
   try {
-    // First check if config file exists
-    await fs.access(options.configPath);
-
-    const configContent = await fs.readFile(options.configPath, "utf8");
-    const config = JSON.parse(configContent);
-
-    if (config.plugins) {
-      // Process plugins in the order expected by tests: loader first, then embedder
-      const categories = ["loader", "embedder"];
-      for (const category of categories) {
-        if (config.plugins[category]) {
-          const plugins = config.plugins[category];
-          const sortedPlugins = Object.keys(plugins).sort();
-          for (const pluginName of sortedPlugins) {
-            try {
-              // Check if plugin file exists (simplified check)
-              await fs.access(path.join("node_modules", pluginName));
-            } catch (error) {
-              issues.push({
-                category: "plugins",
-                severity: "error",
-                code: "PLUGIN_MISSING",
-                message: `Plugin not found: ${pluginName}`,
-                fix: `Install plugin: npm install ${pluginName}`,
-                autoFixable: true,
-              });
-            }
-          }
-        }
-      }
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return []; // reported by the configuration checker
+  }
 
-      // Check for version conflicts
-      try {
-        const {
-          resolvePluginVersions,
-        } = require("../../core/plugin-marketplace/version-resolver.js");
-        const resolution = await resolvePluginVersions(config.plugins);
-        if (resolution.conflicts) {
-          resolution.conflicts.forEach((conflict) => {
-            issues.push({
-              category: "plugins",
-              severity: "warning",
-              code: "PLUGIN_VERSION_CONFLICT",
-              message: `Version conflict: ${conflict.plugin} - ${conflict.conflict}`,
-              fix: "Update plugin versions to resolve conflicts",
-              autoFixable: false,
-            });
-          });
-        }
-      } catch (resolverError) {
-        // Version resolver not available, skip
+  const issues = [];
+  const configDir = path.dirname(configPath);
+  for (const [stage, plugins] of Object.entries(config.plugins || {})) {
+    if (!plugins || typeof plugins !== "object") continue;
+    for (const [name, modulePath] of Object.entries(plugins)) {
+      if (typeof modulePath !== "string") continue;
+      const resolved = path.resolve(configDir, modulePath);
+      if (!fs.existsSync(resolved)) {
+        issues.push({
+          category: "plugins",
+          severity: "error",
+          code: "PLUGIN_MISSING",
+          message: `Plugin ${stage}/${name} not found at ${modulePath}`,
+          fix: `Create ${modulePath} or fix the path in plugins.${stage}.${name}`,
+          autoFixable: false,
+        });
+        continue;
       }
-
-      // Check for outdated plugins
       try {
-        const registryUrl = "https://registry.rag-pipeline.dev";
-        const response = await fetch(`${registryUrl}/plugins`);
-        if (response.ok) {
-          const registry = await response.json();
-          for (const [category, plugins] of Object.entries(config.plugins)) {
-            for (const [pluginName, version] of Object.entries(plugins)) {
-              if (registry.plugins && registry.plugins[pluginName]) {
-                const latest = registry.plugins[pluginName].versions.latest;
-                if (version !== "latest" && version !== latest) {
-                  issues.push({
-                    category: "plugins",
-                    severity: "info",
-                    code: "PLUGIN_OUTDATED",
-                    message: `Plugin outdated: ${pluginName}@${version} (latest: ${latest})`,
-                    fix: `Update to latest version: rag-pipeline plugin install ${pluginName}@latest`,
-                    autoFixable: true,
-                  });
-                }
-              }
-            }
-          }
-        }
-      } catch (fetchError) {
-        // Registry not available, skip
+        require(resolved);
+      } catch (error) {
+        issues.push({
+          category: "plugins",
+          severity: "error",
+          code: "PLUGIN_LOAD_FAILED",
+          message: `Plugin ${stage}/${name} failed to load: ${error.message}`,
+          fix: `Fix the error in ${modulePath}`,
+          autoFixable: false,
+        });
       }
     }
-  } catch (configError) {
-    // Config issues handled in checkConfiguration
   }
-
   return issues;
 }
 

package/src/cli/doctor-command.js

@@ -38,6 +38,25 @@ const SEVERITY_LEVELS = {
   SUCCESS: "success",
 };
 
+/**
+ * Locate npm's CLI script next to the running node binary (Windows layout:
+ * <node dir>/node_modules/npm/bin/npm-cli.js).
+ * @returns {string}
+ */
+function resolveNpmCli() {
+  const candidate = path.join(
+    path.dirname(process.execPath),
+    "node_modules",
+    "npm",
+    "bin",
+    "npm-cli.js",
+  );
+  if (!require("fs").existsSync(candidate)) {
+    throw new Error("npm not found next to node; run npm install manually");
+  }
+  return candidate;
+}
+
 /**
  * Doctor command for pipeline diagnostics
  */
@@ -118,22 +137,32 @@ class PipelineDoctor {
       throw new Error(`Command not allowed: ${command}`);
     }
 
-    // Sanitize arguments
+    // Sanitize arguments. Backslashes are kept: there is no shell to
+    // interpret them, and they are path separators on Windows.
     const sanitizedArgs = args.map((arg) => {
       if (typeof arg !== "string") {
         throw new Error("All arguments must be strings");
       }
-      // Remove shell metacharacters
-      return arg.replace(/[;&|`$(){}[\]<>"'\\]/g, "");
+      return arg.replace(/[;&|`$(){}[\]<>"']/g, "");
     });
 
     const execOptions = {
-      shell: false, // Never use shell to prevent injection
       timeout: options.timeout || 30000,
       env: { ...process.env, PATH: process.env.PATH }, // Controlled environment
       ...options,
+      shell: false, // Never use a shell; set last so callers cannot override it
     };
 
+    // npm is a .cmd shim on Windows, which execFile cannot run without a
+    // shell; run npm's JS entry point with node instead.
+    if (command === "npm" && process.platform === "win32") {
+      return await execFileAsync(
+        process.execPath,
+        [resolveNpmCli(), ...sanitizedArgs],
+        execOptions,
+      );
+    }
+
     return await execFileAsync(command, sanitizedArgs, execOptions);
   }
 
@@ -168,7 +197,12 @@ class PipelineDoctor {
         // Validate config path is within project directory
         const configPath = path.resolve(this.options.configPath);
         const projectDir = path.resolve(".");
-        if (!configPath.startsWith(projectDir)) {
+        // Containment check: a bare startsWith(projectDir) also accepted
+        // sibling directories such as "/proj-evil".
+        const inside = ["/", "\\"].some((sep) =>
+          configPath.startsWith(projectDir + sep),
+        );
+        if (!inside) {
           throw new Error("Config path outside project directory");
         }
 

package/src/cli/enhanced-cli-commands.js

@@ -6,84 +6,38 @@
  */
 
 const { Command } = require("commander");
-const fs = require("fs/promises");
 
 const { logger } = require("../utils/logger.js");
 
 // Shared utilities
 const {
-  createProgressBar,
   parsePositiveInteger,
   generateCompletionScript,
   getVersion,
   getExtendedHelp,
 } = require("./shared/cli-utils.js");
 
-// Handler modules
-const { handleRun } = require("./handlers/run-handler.js");
-const { handleInit } = require("./handlers/init-handler.js");
-const {
-  handleDoctor,
-  handleValidate,
-  handleInfo,
-} = require("./handlers/diagnostics-handler.js");
-const {
-  handleConfigShow,
-  handleConfigSet,
-  handleConfigGet,
-} = require("./handlers/config-handler.js");
-const { handleIngest } = require("./handlers/ingest-handler.js");
-const { handleQuery } = require("./handlers/query-handler.js");
-
-// Mock dependencies for test compatibility
-const mockPluginMarketplaceCommands = () => {
-  const cmd = new Command("plugin");
-  cmd.description("Plugin marketplace commands");
-  cmd
-    .command("search")
-    .argument("[query]")
-    .action(() => {});
-  cmd
-    .command("install")
-    .argument("<name>")
-    .action(() => {});
-  cmd.command("publish").action(() => {});
-  return cmd;
-};
-
-const mockPipelineDoctor = async (options) => {
-  console.log("🏥 Running pipeline diagnostics");
-  if (options.categories) {
-    options.categories.forEach((cat) => {
-      console.log(`${cat.charAt(0).toUpperCase() + cat.slice(1)} Issues:`);
-      console.log("  ✅ No issues found");
-    });
-  } else {
-    console.log("✅ All systems operational");
-  }
-  return {
-    summary: { total: 0, passed: 0, warnings: 0, errors: 0 },
-    categories: {},
-    issues: [],
-  };
+// Handler modules load when their command runs, so `--help` or one command
+// does not pay for every other command's dependencies (inquirer, jsdom, ora,
+// marked, csv-parse...).
+/* eslint-disable global-require */
+const handlers = {
+  run: () => require("./handlers/run-handler.js"),
+  init: () => require("./handlers/init-handler.js"),
+  diagnostics: () => require("./handlers/diagnostics-handler.js"),
+  config: () => require("./handlers/config-handler.js"),
+  ingest: () => require("./handlers/ingest-handler.js"),
+  query: () => require("./handlers/query-handler.js"),
 };
+/* eslint-enable global-require */
 
-const mockValidateSchema = (config) => {
-  if (!config || typeof config !== "object") {
-    return {
-      valid: false,
-      errors: [{ message: "Invalid configuration format" }],
-    };
+function parseNonNegativeInt(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(`Expected a non-negative integer, got "${value}"`);
   }
-  if (config.plugins && typeof config.plugins === "string") {
-    return { valid: false, errors: [{ message: "Invalid plugins format" }] };
-  }
-  const isLegacy =
-    config.plugins &&
-    typeof config.plugins === "object" &&
-    Object.values(config.plugins).some((p) => typeof p === "string");
-  return { valid: true, legacy: isLegacy };
-};
+  return n;
+}
 
 /**
  * Enhanced CLI with improved UX and additional features
@@ -105,7 +59,7 @@ class EnhancedCLI {
       .version(getVersion(), "-v, --version", "Display version information")
       .option("--config <path>", "Configuration file path", ".ragrc.json")
       .option("--verbose", "Enable verbose output")
-      .option("--quiet", "Suppress non-essential output")
+      .option("--quiet", "Print only results, no status messages")
       .option("--no-color", "Disable colored output")
       .option("--dry-run", "Show what would be done without executing")
       .helpOption("-h, --help", "Display help information")
@@ -117,111 +71,116 @@ class EnhancedCLI {
    * Setup all CLI commands
    */
   setupCommands() {
-    // Interactive initialization command
     this.program
       .command("init")
-      .description("Initialize RAG pipeline configuration")
-      .option("--interactive", "Use interactive wizard", true)
-      .option("--no-interactive", "Skip interactive wizard")
-      .option("--template <name>", "Use configuration template")
+      .description("Create a .ragrc.json configuration")
+      .option("--no-interactive", "Use the template without prompting")
+      .option(
+        "--template <name>",
+        "Starting point: local, openai, ollama, anthropic",
+        "local",
+      )
       .option("--output <path>", "Output configuration file", ".ragrc.json")
       .option("--force", "Overwrite existing configuration")
       .action(async (options) => {
-        await handleInit(this.program.opts(), options, (outputPath) =>
-          this.createBasicConfig(outputPath),
-        );
+        const result = await handlers
+          .init()
+          .handleInit(this.program.opts(), options);
+        // After a connection test, exit even if a provider call left a
+        // socket or timer open (see exitAfterConnectionTest).
+        handlers.init().exitAfterConnectionTest(result);
       });
 
-    // Run pipeline command
     this.program
       .command("run")
-      .description("Execute RAG pipeline operations")
-      .option("--ingest <file>", "Ingest document into pipeline")
-      .option("--query <prompt>", "Query the pipeline")
-      .option("--stream", "Enable streaming output")
-      .option(
-        "--abort-timeout <ms>",
-        "Abort operation after timeout (milliseconds)",
-        parsePositiveInteger,
-      )
-      .option("--parallel", "Enable parallel processing")
+      .description("Ingest and/or query in one step")
+      .option("--ingest <path>", "File or directory to ingest first")
+      .option("--query <text>", "Question to ask after ingesting")
+      .option("--rebuild", "Discard the existing index before ingesting")
+      .option("--top-k <n>", "Passages to retrieve", parsePositiveInteger, 3)
+      .option("--json", "Print the query result as JSON")
       .action(async (options) => {
-        await handleRun(this.program.opts(), options);
+        await handlers.run().handleRun(this.program.opts(), options);
       });
 
-    // Doctor command for diagnostics
     this.program
       .command("doctor")
-      .description("Diagnose and fix common issues")
-      .option("--category <categories...>", "Diagnostic categories to check")
-      .option("--auto-fix", "Automatically fix issues where possible")
-      .option("--report <path>", "Save diagnostic report to file")
+      .description("Diagnose configuration, plugins and environment")
+      .option(
+        "--category <categories...>",
+        "Only run: configuration, plugins, dependencies, performance, security, environment",
+      )
+      .option(
+        "--auto-fix",
+        "Fix issues where possible (npm install, file permissions)",
+      )
+      .option("--report <path>", "Save the diagnostic report as JSON")
       .action(async (options) => {
-        await handleDoctor(this.program.opts(), options, mockPipelineDoctor);
+        await handlers.diagnostics().handleDoctor(this.program.opts(), options);
       });
 
-    // Enhanced ingest command
     this.program
       .command("ingest")
-      .description("Ingest documents into the pipeline")
-      .argument("<file>", "Document file to ingest")
-      .option("--validate", "Validate document before ingesting")
-      .option("--preview", "Show preview of document chunks")
-      .option("--parallel", "Enable parallel processing")
-      .option("--streaming", "Enable streaming with memory safeguards")
-      .option("--trace", "Enable detailed tracing and event logging")
-      .option("--stats", "Show pipeline metrics summary at the end")
-      .option(
-        "--export-observability <file>",
-        "Export observability data to file",
-      )
-      .option(
-        "--max-concurrency <number>",
-        "Maximum concurrent operations",
-        "3",
-      )
-      .option(
-        "--batch-size <number>",
-        "Batch size for parallel processing",
-        "10",
-      )
-      .option("--max-memory <number>", "Maximum memory usage in MB", "512")
-      .action(async (file, options) => {
-        await handleIngest(this.program.opts(), file, options);
+      .description("Load, embed and index documents")
+      .argument("<path>", "File or directory (.md, .html, .csv, .txt)")
+      .option("--rebuild", "Discard the existing index before ingesting")
+      .action(async (inputPath, options) => {
+        await handlers
+          .ingest()
+          .handleIngest(this.program.opts(), inputPath, options);
       });
 
-    // Enhanced query command
     this.program
       .command("query")
-      .description("Query the RAG pipeline")
-      .argument("<prompt>", "Query prompt")
-      .option("--stream", "Enable streaming response")
-      .option("--explain", "Show explanation of query processing")
-      .option("--parallel", "Enable parallel processing")
-      .option("--trace", "Enable detailed tracing and event logging")
-      .option("--stats", "Show pipeline metrics summary at the end")
+      .description("Ask a question against the ingested documents")
+      .argument("<question>", "Question text")
+      .option("--top-k <n>", "Passages to retrieve", parsePositiveInteger, 3)
+      .option("--json", "Print the result as JSON")
+      .option("--streaming", "Print the answer as it is generated")
       .option(
-        "--export-observability <file>",
-        "Export observability data to file",
+        "--timeout <ms>",
+        "Abort the query after this many milliseconds",
+        parsePositiveInteger,
+      )
+      .option("--trace", "Show time spent in each stage")
+      .option(
+        "--explain",
+        "Show passage scores and which passages support each answer sentence",
       )
-      .action(async (prompt, options) => {
-        await handleQuery(this.program.opts(), prompt, options);
+      .option("--stats", "Show latency and estimated tokens and cost")
+      .action(async (question, options) => {
+        await handlers
+          .query()
+          .handleQuery(this.program.opts(), question, options);
       });
 
-    // Configuration validation command
     this.program
       .command("validate")
-      .description("Validate configuration file")
-      .option("--schema", "Validate against schema only")
-      .option("--plugins", "Validate plugin availability")
-      .option("--dependencies", "Check plugin dependencies")
-      .option("--fix", "Attempt to fix validation issues")
+      .description("Validate the configuration and resolve its components")
+      .action(async () => {
+        await handlers.diagnostics().handleValidate(this.program.opts());
+      });
+
+    this.program
+      .command("serve")
+      .description("Serve GET /health and POST /query over HTTP (local use)")
+      .option(
+        "--port <n>",
+        "Port (0 picks a free one)",
+        parseNonNegativeInt,
+        3000,
+      )
+      .option("--host <host>", "Interface to bind", "127.0.0.1")
       .action(async (options) => {
-        await handleValidate(this.program.opts(), options, mockValidateSchema);
+        const { handleServe } = require("./handlers/serve-handler.js");
+        await handleServe(this.program.opts(), options);
       });
 
-    // Plugin marketplace commands
-    this.program.addCommand(mockPluginMarketplaceCommands());
+    const { PluginHubCLI } = require("./commands/plugin-hub.js");
+    this.program.addCommand(new PluginHubCLI().createCommands());
+
+    const { createAiCommand } = require("./commands/ai.js");
+    this.program.addCommand(createAiCommand(() => this.program.opts()));
 
     // Configuration management commands
     const configCmd = new Command("config");
@@ -230,10 +189,9 @@ class EnhancedCLI {
     configCmd
       .command("show")
       .description("Show current configuration")
-      .option("--format <format>", "Output format (json, yaml, table)", "json")
       .option("--section <section>", "Show specific configuration section")
       .action(async (options) => {
-        await handleConfigShow(this.program.opts(), options);
+        await handlers.config().handleConfigShow(this.program.opts(), options);
       });
 
     configCmd
@@ -242,7 +200,9 @@ class EnhancedCLI {
       .argument("<key>", "Configuration key (dot notation supported)")
       .argument("<value>", "Configuration value")
       .action(async (key, value, options) => {
-        await handleConfigSet(this.program.opts(), key, value);
+        await handlers
+          .config()
+          .handleConfigSet(this.program.opts(), key, value);
       });
 
     configCmd
@@ -250,7 +210,7 @@ class EnhancedCLI {
       .description("Get configuration value")
       .argument("<key>", "Configuration key (dot notation supported)")
       .action(async (key, options) => {
-        await handleConfigGet(this.program.opts(), key);
+        await handlers.config().handleConfigGet(this.program.opts(), key);
       });
 
     this.program.addCommand(configCmd);
@@ -259,11 +219,11 @@ class EnhancedCLI {
     this.program
       .command("info")
       .description("Show system and plugin information")
-      .option("--plugins", "Show registered plugin versions")
+      .option("--plugins", "Show built-in components and custom plugins")
       .option("--system", "Show system information")
       .option("--config", "Show configuration summary")
       .action(async (options) => {
-        await handleInfo(this.program.opts(), options);
+        await handlers.diagnostics().handleInfo(this.program.opts(), options);
       });
 
     // Completion command for shell autocompletion
@@ -277,64 +237,6 @@ class EnhancedCLI {
       });
   }
 
-  /**
-   * Create basic configuration
-   */
-  async createBasicConfig(outputPath) {
-    const { validateRagrc } = require("../config/enhanced-ragrc-schema.js");
-
-    const base = {
-      namespace: "default",
-      metadata: {
-        name: "rag-pipeline",
-        version: "1.0.0",
-        description: "RAG pipeline configuration",
-        createdAt: new Date().toISOString(),
-      },
-      pipeline: [
-        { stage: "loader", name: "fs-loader", version: "1.0.0" },
-        { stage: "embedder", name: "mock-embedder", version: "1.0.0" },
-        { stage: "retriever", name: "mock-retriever", version: "1.0.0" },
-        { stage: "llm", name: "mock-llm", version: "1.0.0" },
-      ],
-      performance: {
-        parallel: {
-          enabled: false,
-          maxConcurrency: 3,
-        },
-        caching: {
-          enabled: false,
-          maxSize: 1000,
-          ttl: 3600,
-        },
-      },
-      observability: {
-        logging: {
-          level: "info",
-          structured: true,
-        },
-      },
-    };
-
-    const result = validateRagrc(base);
-    if (!result.valid) {
-      result.errors?.forEach((error) =>
-        console.error(`  ${error.instancePath || ""}: ${error.message}`),
-      );
-      throw new Error("Failed to generate valid configuration");
-    }
-
-    if (outputPath) {
-      await fs.writeFile(
-        outputPath,
-        JSON.stringify(result.normalized, null, 2),
-      );
-      console.log(`✅ Basic configuration created: ${outputPath}`);
-    }
-
-    return result.normalized;
-  }
-
   /**
    * Run the CLI
    */
@@ -363,39 +265,8 @@ async function runEnhancedCLI(argv = process.argv) {
   await enhancedCLI.run(argv);
 }
 
-// CLI command surface for tests
-const init = async () => ({ ok: true });
-const ingest = async () => ({ ok: true });
-const query = async () => ({ ok: true });
-const handleError = async () => ({ ok: true });
-const validateArgs = () => true;
-const showHelp = () => "help text";
-
-// Extract createBasicConfig from the class for direct export
-const createBasicConfig = async (outputPath) => {
-  const cli = new EnhancedCLI();
-  return await cli.createBasicConfig(outputPath);
-};
-
-const enhancedCliCommands = {
-  init,
-  ingest,
-  query,
-  handleError,
-  validateArgs,
-  showHelp,
-};
-
 module.exports = {
   EnhancedCLI,
   enhancedCLI,
   runEnhancedCLI,
-  enhancedCliCommands,
-  init,
-  ingest,
-  query,
-  handleError,
-  validateArgs,
-  showHelp,
-  createBasicConfig,
 };