@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/src/debug/execution-tracer.js

@@ -28,10 +28,17 @@ function generateTraceId() {
 }
 
 /**
- * Truncate a value if its JSON representation exceeds maxSize bytes
- * @param {*} value - Value to truncate
+ * Snapshot a value for a trace: a JSON copy, or a truncated string when its
+ * JSON exceeds maxSize characters.
+ *
+ * Always a copy, never the live object: the traced run attaches the trace to
+ * its result (`result.trace`), so storing the result itself made the trace
+ * circular and exportTraces('json') threw. A copy also keeps later changes to
+ * the result out of the recorded trace.
+ *
+ * @param {*} value - Value to snapshot
  * @param {number} maxSize - Maximum serialized size in characters
- * @returns {*} Original value or truncated string
+ * @returns {*} JSON copy of the value, or a truncated string
  */
 function truncatePayload(value, maxSize) {
   if (value === undefined || value === null) {
@@ -43,8 +50,11 @@ function truncatePayload(value, maxSize) {
   } catch {
     return '[unserializable]';
   }
+  if (serialized === undefined) {
+    return undefined; // functions and symbols have no JSON form
+  }
   if (serialized.length <= maxSize) {
-    return value;
+    return JSON.parse(serialized);
   }
   return serialized.slice(0, maxSize) + '...[truncated]';
 }

package/src/dev/dev-server.js

@@ -7,20 +7,25 @@
  * for rapid plugin and configuration development.
  *
  * Features:
+ * - Local HTTP API over the configured pipeline:
+ *     GET  /health  -> { status, uptime }
+ *     POST /query   -> { question, topK? } => { answer, results, citations }
+ *   Binds to 127.0.0.1 by default, JSON only, no CORS headers, request
+ *   bodies limited to 64 KB, no static file serving.
  * - Automatic hot reloading of plugins and configuration
- * - Live feedback on reload status
- * - Error notifications
  * - Statistics dashboard
- * - WebSocket support for real-time updates (optional)
  *
  * @module dev/dev-server
  * @since 2.4.0
  */
 
+const http = require('http');
 const { EventEmitter } = require('events');
 const { createHotReloadManager } = require('./hot-reload');
 const { logger } = require('../utils/logger');
 
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
 /**
  * Development Server
  *
@@ -31,9 +36,12 @@ class DevServer extends EventEmitter {
     super();
 
     this.options = {
-      port: options.port || 3000,
-      host: options.host || 'localhost',
-      watchPaths: options.watchPaths || ['./src/plugins', './src/mocks'],
+      port: options.port ?? 3000, // 0 picks a free port
+      host: options.host || '127.0.0.1',
+      watchPaths: options.watchPaths || [],
+      maxBodyBytes: options.maxBodyBytes || 64 * 1024,
+      // Optional custom handler: async ({ question, topK }) => result
+      query: options.query || null,
       configPath: options.configPath || '.ragrc.json',
       verbose: options.verbose !== false,
       autoReload: options.autoReload !== false,
@@ -147,12 +155,23 @@ class DevServer extends EventEmitter {
     // Start hot reload
     await this.hotReload.start();
 
+    this.server = http.createServer((req, res) => {
+      this._handleRequest(req, res).catch((error) => {
+        this._send(res, 500, { error: error.message });
+      });
+    });
+    await new Promise((resolve, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(this.options.port, this.options.host, () => {
+        this.server.off('error', reject);
+        resolve();
+      });
+    });
+    this.port = this.server.address().port;
+
     this.isRunning = true;
 
-    this._log(
-      `Development server started on ${this.options.host}:${this.options.port}`,
-      'success',
-    );
+    this._log(`Development server listening on ${this.url}`, 'success');
     this._log(`Watching: ${this.options.watchPaths.join(', ')}`, 'info');
     this._log(
       'Hot reload enabled - changes will be applied automatically',
@@ -178,6 +197,11 @@ class DevServer extends EventEmitter {
     // Stop hot reload
     await this.hotReload.stop();
 
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(() => resolve()));
+      this.server = null;
+    }
+
     this.isRunning = false;
 
     const uptime = this.startTime ? Date.now() - this.startTime : 0;
@@ -202,7 +226,8 @@ class DevServer extends EventEmitter {
       isRunning: this.isRunning,
       uptime,
       host: this.options.host,
-      port: this.options.port,
+      port: this.port ?? this.options.port,
+      url: this.isRunning ? this.url : null,
       watchPaths: this.options.watchPaths,
       configPath: this.options.configPath,
       hotReload: {
@@ -249,6 +274,143 @@ ${this.options.watchPaths.map((p) => `║   - ${p.padEnd(56)}║`).join('\n')}
    * @param {string} type - Type ('plugin' or 'config')
    * @returns {Promise<void>}
    */
+  /** @returns {string} Base URL of the running server */
+  get url() {
+    return `http://${this.options.host}:${this.port ?? this.options.port}`;
+  }
+
+  /**
+   * Route a request. Only GET /health and POST /query exist.
+   * @private
+   */
+  async _handleRequest(req, res) {
+    // DNS rebinding: a web page can point its own domain at 127.0.0.1 and
+    // then call this server same-origin. When bound to loopback, only accept
+    // requests addressed to a loopback name.
+    if (
+      LOOPBACK_HOSTS.has(this.options.host) &&
+      !this._isLoopbackHostHeader(req)
+    ) {
+      return this._send(res, 403, { error: 'Forbidden host' });
+    }
+
+    const { pathname } = new URL(req.url, 'http://localhost');
+
+    if (pathname === '/health') {
+      if (req.method !== 'GET')
+        return this._send(res, 405, { error: 'Use GET' });
+      const uptime = this.startTime ? Date.now() - this.startTime : 0;
+      return this._send(res, 200, { status: 'ok', uptime });
+    }
+
+    if (pathname === '/query') {
+      if (req.method !== 'POST')
+        return this._send(res, 405, { error: 'Use POST' });
+      let body;
+      try {
+        body = await this._readJson(req);
+      } catch (error) {
+        return this._send(res, error.statusCode || 400, {
+          error: error.message,
+        });
+      }
+      const { question, topK } = body || {};
+      if (typeof question !== 'string' || !question.trim()) {
+        return this._send(res, 400, {
+          error: '"question" must be a non-empty string',
+        });
+      }
+      if (
+        topK !== undefined &&
+        !(Number.isInteger(topK) && topK > 0 && topK <= 50)
+      ) {
+        return this._send(res, 400, {
+          error: '"topK" must be an integer from 1 to 50',
+        });
+      }
+      const result = await this._runQuery({ question, topK: topK || 3 });
+      return this._send(res, 200, result);
+    }
+
+    return this._send(res, 404, { error: 'Not found' });
+  }
+
+  /** @private */
+  _isLoopbackHostHeader(req) {
+    const header = req.headers.host || '';
+    const hostname = header.startsWith('[')
+      ? header.slice(0, header.indexOf(']') + 1)
+      : header.split(':')[0];
+    return LOOPBACK_HOSTS.has(hostname.toLowerCase());
+  }
+
+  /**
+   * Answer with the custom `query` option, or the pipeline described by the
+   * config file (reloaded per request, so config edits apply immediately).
+   * @private
+   */
+  async _runQuery({ question, topK }) {
+    if (this.options.query) return this.options.query({ question, topK });
+    const { loadCliConfig } = require('../cli/shared/config-context');
+    const { query } = require('../cli/services/rag-service');
+    const { config, configDir } = loadCliConfig({
+      config: this.options.configPath,
+    });
+    // The HTTP response keeps its shape: answer, results, citations.
+    const { timings, durationMs, ...result } = await query({
+      config,
+      configDir,
+      question,
+      topK,
+    });
+    return result;
+  }
+
+  /** @private */
+  _readJson(req) {
+    return new Promise((resolve, reject) => {
+      const type = req.headers['content-type'] || '';
+      if (!type.includes('application/json')) {
+        const error = new Error('Content-Type must be application/json');
+        error.statusCode = 415;
+        return reject(error);
+      }
+      let size = 0;
+      const chunks = [];
+      req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > this.options.maxBodyBytes) {
+          const error = new Error('Request body too large');
+          error.statusCode = 413;
+          reject(error);
+          // Stop buffering but keep draining, so the 413 response is delivered
+          req.removeAllListeners('data');
+          req.resume();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on('end', () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'));
+        } catch {
+          reject(new Error('Invalid JSON body'));
+        }
+      });
+      req.on('error', reject);
+    });
+  }
+
+  /** @private */
+  _send(res, status, payload) {
+    if (res.headersSent) return;
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'X-Content-Type-Options': 'nosniff',
+    });
+    res.end(JSON.stringify(payload));
+  }
+
   async triggerReload(filePath, type = 'plugin') {
     this._log(`Manually triggering reload: ${filePath}`, 'info');
     await this.hotReload.triggerReload(filePath, type);

package/src/dev/hot-reload.js

@@ -18,7 +18,8 @@
  */
 
 const { EventEmitter } = require('events');
-const chokidar = require('chokidar');
+// chokidar loads when watching starts, not on import.
+const loadChokidar = () => require('chokidar'); // eslint-disable-line global-require
 const path = require('path');
 const fs = require('fs');
 const {
@@ -28,6 +29,42 @@ const {
 } = require('../utils/error-formatter');
 const { logger } = require('../utils/logger');
 
+const RELOADABLE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs']);
+
+/**
+ * chokidar 4 removed glob support, so glob strings in `ignored` were treated
+ * as literal paths and matched nothing. Convert them to one matcher function.
+ *
+ * @param {Array<string|RegExp|Function>} patterns
+ * @returns {(filePath: string) => boolean}
+ */
+function toIgnoreMatcher(patterns) {
+  const matchers = patterns.map((pattern) => {
+    if (typeof pattern === 'function') return pattern;
+    if (pattern instanceof RegExp) return (p) => pattern.test(p);
+    const regex = new RegExp(
+      '^' +
+        pattern
+          .split('**/')
+          .map((part) =>
+            part
+              .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+              .replace(/\*\*/g, '\u0000') // a remaining ** (e.g. trailing) spans directories
+              .replace(/\*/g, '[^/]*')
+              .replace(/\?/g, '[^/]')
+              .replace(/\u0000/g, '.*'),
+          )
+          .join('(?:.*/)?') +
+        '$',
+    );
+    return (p) => regex.test(p);
+  });
+  return (filePath) => {
+    const normalized = filePath.split(path.sep).join('/');
+    return matchers.some((match) => match(normalized));
+  };
+}
+
 /**
  * Hot Reload Manager
  *
@@ -134,8 +171,8 @@ class HotReloadManager extends EventEmitter {
    * @returns {Promise<void>}
    */
   async _watchPlugins() {
-    const watcher = chokidar.watch(this.options.watchPaths, {
-      ignored: this.options.ignorePatterns,
+    const watcher = loadChokidar().watch(this.options.watchPaths, {
+      ignored: toIgnoreMatcher(this.options.ignorePatterns),
       persistent: true,
       ignoreInitial: true,
       awaitWriteFinish: {
@@ -178,7 +215,7 @@ class HotReloadManager extends EventEmitter {
       return;
     }
 
-    const watcher = chokidar.watch(this.options.configPath, {
+    const watcher = loadChokidar().watch(this.options.configPath, {
       persistent: true,
       ignoreInitial: true,
       awaitWriteFinish: {
@@ -206,6 +243,8 @@ class HotReloadManager extends EventEmitter {
    * @param {string} filePath - Changed file path
    */
   _handlePluginChange(filePath) {
+    // Only JavaScript modules can be re-required; ignore data and docs.
+    if (!RELOADABLE_EXTENSIONS.has(path.extname(filePath))) return;
     this._log(`Plugin changed: ${filePath}`);
 
     // Debounce rapid changes
@@ -803,6 +842,7 @@ function createHotReloadManager(options = {}) {
 }
 
 module.exports = {
+  toIgnoreMatcher,
   HotReloadManager,
   createHotReloadManager,
 };

package/src/ecosystem/plugin-checks.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * Automated certification checks for a local plugin. Every score is computed
+ * from the plugin's files: the stage contract (checked in a separate
+ * process), the static security scan, tests and documentation. Nothing is
+ * assumed; checks that cannot be computed score 0 with a reason.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanPlugin } = require('./plugin-scanner');
+const { probeContract } = require('./plugin-probe');
+const { relativeWithin } = require('./tar-extract');
+
+/** Automated score needed for each level (manual review/audit are separate). */
+const LEVELS = [
+  {
+    level: 'ENTERPRISE',
+    score: 95,
+    requires: 'manual review and security audit',
+  },
+  { level: 'VERIFIED', score: 80, requires: 'manual review' },
+  { level: 'BASIC', score: 60, requires: null },
+];
+
+const TEST_FILE = /(^|[\\/])(__tests__|tests?)[\\/]|\.(test|spec)\.[cm]?js$/;
+
+function listFiles(dir) {
+  const out = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relativeWithin(dir, full));
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function securityCheck(root) {
+  const scan = scanPlugin(root);
+  const { high, medium, low } = scan.counts;
+  const score = Math.max(0, 100 - 40 * high - 10 * medium - 2 * low);
+  return {
+    id: 'security',
+    label: 'Security scan',
+    weight: 30,
+    score,
+    details: scan.findings.map(
+      (f) =>
+        `${f.severity}: ${f.message} (${f.file}${f.line ? `:${f.line}` : ''})`,
+    ),
+  };
+}
+
+function testsCheck(files, manifest) {
+  const testFiles = files.filter((f) => TEST_FILE.test(f));
+  const script = manifest.scripts?.test;
+  const realScript = Boolean(script) && !/no test specified/.test(script);
+  let score = 0;
+  if (testFiles.length > 0) score = realScript ? 100 : 60;
+  return {
+    id: 'tests',
+    label: 'Tests',
+    weight: 15,
+    score,
+    details: [
+      `${testFiles.length} test file(s)`,
+      realScript
+        ? `test script: ${script}`
+        : 'no "test" script in package.json',
+    ],
+  };
+}
+
+function docsCheck(root, files, manifest) {
+  const readme = files.find((f) => /^readme(\.md|\.txt)?$/i.test(f));
+  const readmeLength = readme
+    ? fs.readFileSync(path.join(root, readme), 'utf8').trim().length
+    : 0;
+  const parts = [
+    [Boolean(readme), 50, readme ? `${readme} present` : 'no README'],
+    [
+      readmeLength >= 300,
+      20,
+      `README length ${readmeLength} chars (300+ expected)`,
+    ],
+    [
+      Boolean(manifest.description),
+      15,
+      manifest.description
+        ? 'package description present'
+        : 'no package description',
+    ],
+    [
+      Boolean(manifest.license),
+      15,
+      manifest.license ? `license: ${manifest.license}` : 'no license field',
+    ],
+  ];
+  return {
+    id: 'documentation',
+    label: 'Documentation',
+    weight: 20,
+    score: parts.reduce((sum, [ok, points]) => sum + (ok ? points : 0), 0),
+    details: parts.map(([ok, , text]) => `${ok ? 'ok' : 'missing'}: ${text}`),
+  };
+}
+
+/**
+ * @param {string} pluginPath - Plugin directory or single .js file
+ * @param {object} options
+ * @param {string} [options.stage] - Overrides package.json "ragPipeline.stage"
+ * @returns {Promise<{plugin: string, stage: string, checks: object[], score: number, level: string|null, nextLevel: object|null}>}
+ */
+async function runPluginChecks(pluginPath, options = {}) {
+  const absolute = path.resolve(pluginPath);
+  if (!fs.existsSync(absolute))
+    throw new Error(`Plugin not found: ${pluginPath}`);
+  const isDir = fs.statSync(absolute).isDirectory();
+  const root = isDir ? absolute : path.dirname(absolute);
+  const manifestPath = path.join(root, 'package.json');
+  const manifest =
+    isDir && fs.existsSync(manifestPath)
+      ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+      : {};
+  const stage = options.stage || manifest.ragPipeline?.stage;
+  if (!stage) {
+    throw new Error(
+      'Unknown stage. Pass --stage or set "ragPipeline.stage" in package.json.',
+    );
+  }
+  const entry = isDir
+    ? path.resolve(root, manifest.main || 'index.js')
+    : absolute;
+  const files = isDir ? listFiles(root) : [path.basename(absolute)];
+
+  const probe = await probeContract(entry, stage);
+  const contract = {
+    id: 'contract',
+    label: `${stage} contract`,
+    weight: 35,
+    score: probe.ok ? 100 : 0,
+    details: probe.ok
+      ? [`methods: ${probe.methods.join(', ')}`]
+      : [probe.error || `missing: ${probe.missing.join(', ')}`],
+  };
+
+  const checks = [
+    contract,
+    isDir ? securityCheck(root) : securityCheck(absolute),
+    testsCheck(files, manifest),
+    docsCheck(root, isDir ? files : [], manifest),
+  ];
+  const totalWeight = checks.reduce((sum, c) => sum + c.weight, 0);
+  const score = Math.round(
+    checks.reduce((sum, c) => sum + c.score * c.weight, 0) / totalWeight,
+  );
+
+  // A failed contract means the plugin cannot run, whatever else scores.
+  const eligible =
+    contract.score === 100 ? LEVELS.filter((l) => score >= l.score) : [];
+  const best = eligible[0] || null;
+  const nextLevel = [...LEVELS].reverse().find((l) => score < l.score) || null;
+
+  return {
+    plugin: manifest.name || path.basename(absolute),
+    version: manifest.version || null,
+    stage,
+    checks,
+    score,
+    level: best ? best.level : null,
+    pendingReview: best ? best.requires : null,
+    nextLevel: nextLevel && { level: nextLevel.level, score: nextLevel.score },
+  };
+}
+
+module.exports = { runPluginChecks, LEVELS };