@devilsdev/rag-pipeline-utils 2.4.4 → 2.5.0

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

@@ -1,44 +1,75 @@
 /**
- * Environment checker for RAG Pipeline Diagnostics
- * Checks for missing environment variables referenced in configuration
+ * Environment diagnostics: API keys the configured providers need, ${VAR}
+ * references in the config, and whether the file-store index exists yet.
  */
 
-const fs = require("fs/promises");
+const fs = require("fs");
+const path = require("path");
 
-/**
- * Check environment issues
- * @param {object} options - Doctor options (must include configPath)
- * @returns {Promise<Array>} Array of environment issues
- */
-async function checkEnvironment(options) {
-  const issues = [];
+const PROVIDER_KEYS = {
+  openai: "OPENAI_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  cohere: "COHERE_API_KEY",
+};
+
+function missingVar(envVar, reason) {
+  return {
+    category: "environment",
+    severity: "error",
+    code: "ENV_VAR_MISSING",
+    message: `Required environment variable missing: ${envVar}${reason ? ` (${reason})` : ""}`,
+    fix: `Set environment variable: export ${envVar}=your_key`,
+    autoFixable: false,
+  };
+}
 
+async function checkEnvironment(options) {
+  const configPath = path.resolve(options.configPath);
+  let config;
   try {
-    const configContent = await fs.readFile(options.configPath, "utf8");
-    const config = JSON.parse(configContent);
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return []; // reported by the configuration checker
+  }
 
-    // Check for missing environment variables
-    const configStr = JSON.stringify(config);
-    const envVarMatches = configStr.match(/\$\{([^}]+)\}/g);
-    if (envVarMatches) {
-      envVarMatches.forEach((match) => {
-        const envVar = match.slice(2, -1);
-        if (!process.env[envVar]) {
-          issues.push({
-            category: "environment",
-            severity: "error",
-            code: "ENV_VAR_MISSING",
-            message: `Required environment variable missing: ${envVar}`,
-            fix: `Set environment variable: export ${envVar}=your_key`,
-            autoFixable: false,
-          });
-        }
-      });
+  const issues = [];
+  const seen = new Set();
+  for (const entry of Array.isArray(config.pipeline) ? config.pipeline : []) {
+    const envVar = PROVIDER_KEYS[entry?.name];
+    if (
+      envVar &&
+      !entry.config?.apiKey &&
+      !process.env[envVar] &&
+      !seen.has(envVar)
+    ) {
+      seen.add(envVar);
+      issues.push(missingVar(envVar, `used by ${entry.stage} "${entry.name}"`));
+    }
+    if (entry?.stage === "retriever" && entry.name === "file-store") {
+      const indexPath = path.resolve(
+        path.dirname(configPath),
+        entry.config?.path || ".rag/index.json",
+      );
+      if (!fs.existsSync(indexPath)) {
+        issues.push({
+          category: "environment",
+          severity: "info",
+          code: "INDEX_MISSING",
+          message: `No index yet at ${path.relative(process.cwd(), indexPath)}`,
+          fix: "Run: rag-pipeline ingest <file-or-directory>",
+          autoFixable: false,
+        });
+      }
     }
-  } catch (error) {
-    // Config issues handled elsewhere
   }
 
+  for (const match of JSON.stringify(config).match(/\$\{([^}]+)\}/g) || []) {
+    const envVar = match.slice(2, -1);
+    if (!process.env[envVar] && !seen.has(envVar)) {
+      seen.add(envVar);
+      issues.push(missingVar(envVar, "referenced in the config"));
+    }
+  }
   return issues;
 }
 

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");
         }