@devilsdev/rag-pipeline-utils 2.3.1 → 2.4.1

package/src/templates/scaffold.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @module templates/scaffold
+ * @description Creates complete project directories from templates.
+ */
+
+const { EventEmitter } = require('events');
+const fs = require('fs');
+const path = require('path');
+const { TemplateRegistry } = require('./template-registry');
+
+/** @type {Object} Default configuration for the project scaffolder */
+const DEFAULT_CONFIG = {
+  installDependencies: false,
+  overwrite: false,
+};
+
+/**
+ * Creates complete project directories from registered templates.
+ *
+ * @extends EventEmitter
+ * @fires ProjectScaffolder#created
+ *
+ * @example
+ * const scaffolder = new ProjectScaffolder();
+ * const result = scaffolder.create('document-qa', '/path/to/my-project');
+ * console.log(result.files); // list of created files
+ */
+class ProjectScaffolder extends EventEmitter {
+  /**
+   * @param {Object} [options={}] - Scaffolder configuration
+   * @param {boolean} [options.installDependencies=false] - Whether to auto-run npm install
+   * @param {boolean} [options.overwrite=false] - Allow overwriting existing directories
+   */
+  constructor(options = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...options };
+    this.registry = new TemplateRegistry();
+  }
+
+  /**
+   * Create a new project from a template.
+   *
+   * @param {string} templateKey - Key of the template to use
+   * @param {string} projectDir - Target directory for the new project
+   * @param {Object} [options={}] - Per-call overrides
+   * @param {boolean} [options.overwrite] - Override the instance-level overwrite setting
+   * @returns {{projectDir: string, files: string[], template: string}} Creation result
+   * @throws {Error} If template is not found or directory already exists
+   */
+  create(templateKey, projectDir, options = {}) {
+    const template = this.registry.get(templateKey);
+    if (!template) {
+      throw new Error(`Unknown template: "${templateKey}"`);
+    }
+
+    const resolvedDir = path.resolve(projectDir);
+    const allowOverwrite =
+      options.overwrite !== undefined
+        ? options.overwrite
+        : this.config.overwrite;
+
+    if (fs.existsSync(resolvedDir) && !allowOverwrite) {
+      throw new Error(
+        `Directory already exists: ${resolvedDir}. Use overwrite option to replace.`,
+      );
+    }
+
+    fs.mkdirSync(resolvedDir, { recursive: true });
+
+    const createdFiles = [];
+
+    // Write package.json
+    const projectName = path.basename(resolvedDir);
+    const packageJson = {
+      name: projectName,
+      version: '1.0.0',
+      description: template.description,
+      main: 'index.js',
+      scripts: {
+        start: 'node index.js',
+      },
+      dependencies: template.dependencies || {},
+      devDependencies: template.devDependencies || {},
+    };
+
+    const packageJsonPath = path.join(resolvedDir, 'package.json');
+    fs.writeFileSync(
+      packageJsonPath,
+      JSON.stringify(packageJson, null, 2) + '\n',
+    );
+    createdFiles.push('package.json');
+
+    // Write template files
+    const files = template.files || {};
+    for (const [fileName, content] of Object.entries(files)) {
+      const filePath = path.join(resolvedDir, fileName);
+      const fileDir = path.dirname(filePath);
+
+      if (fileDir !== resolvedDir) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+
+      fs.writeFileSync(filePath, content + '\n');
+      createdFiles.push(fileName);
+    }
+
+    // Write .ragrc.json from template config
+    if (template.config) {
+      const ragrcPath = path.join(resolvedDir, '.ragrc.json');
+      fs.writeFileSync(
+        ragrcPath,
+        JSON.stringify(template.config, null, 2) + '\n',
+      );
+      createdFiles.push('.ragrc.json');
+    }
+
+    const result = {
+      projectDir: resolvedDir,
+      files: createdFiles,
+      template: templateKey,
+    };
+
+    /**
+     * @event ProjectScaffolder#created
+     * @type {Object}
+     * @property {string} projectDir - Absolute path to created project
+     * @property {string[]} files - List of created file names
+     * @property {string} template - Template key that was used
+     */
+    this.emit('created', result);
+
+    return result;
+  }
+
+  /**
+   * List all available templates.
+   *
+   * @returns {Array<{key: string, name: string, description: string}>} Available templates
+   */
+  listTemplates() {
+    return this.registry.list();
+  }
+}
+
+module.exports = { ProjectScaffolder, DEFAULT_CONFIG };

package/src/templates/template-registry.js

@@ -0,0 +1,272 @@
+'use strict';
+
+/**
+ * @module templates/template-registry
+ * @description Registry of built-in project templates for RAG pipeline scaffolding.
+ */
+
+/** @type {Object<string, Object>} Built-in template definitions */
+const TEMPLATES = {
+  'document-qa': {
+    name: 'Document Q&A',
+    description: 'Question answering over documents (PDF, Markdown, HTML)',
+    dependencies: { '@devilsdev/rag-pipeline-utils': 'latest' },
+    devDependencies: {},
+    config: {
+      pipeline: {
+        loader: 'markdown',
+        embedder: 'openai',
+        retriever: 'memory',
+        llm: 'openai',
+      },
+      options: { topK: 5, citations: true, evaluate: true },
+    },
+    files: {
+      'index.js': [
+        '// Document Q&A Pipeline',
+        'const { createRagPipeline, ChunkingEngine } = require(\'@devilsdev/rag-pipeline-utils\');',
+        '',
+        '// Configure your pipeline',
+        'const pipeline = createRagPipeline({',
+        '  // Add your plugins here',
+        '  // loader: new YourLoader(),',
+        '  // embedder: new YourEmbedder({ apiKey: process.env.OPENAI_API_KEY }),',
+        '  // retriever: new YourRetriever(),',
+        '  // llm: new YourLLM({ apiKey: process.env.OPENAI_API_KEY }),',
+        '});',
+        '',
+        'async function main() {',
+        '  const result = await pipeline.run({',
+        '    query: \'What does this document say?\',',
+        '    options: { citations: true, evaluate: true },',
+        '  });',
+        '  console.log(\'Answer:\', result.answer);',
+        '  if (result.citations) {',
+        '    console.log(\'Groundedness:\', result.citations.groundednessScore);',
+        '  }',
+        '}',
+        '',
+        'main().catch(console.error);',
+      ].join('\n'),
+      'README.md': [
+        '# Document Q&A Pipeline',
+        '',
+        'A RAG pipeline for answering questions about your documents.',
+        '',
+        '## Setup',
+        '',
+        '1. Install dependencies: `npm install`',
+        '2. Set your API key: `export OPENAI_API_KEY=your-key`',
+        '3. Run: `node index.js`',
+      ].join('\n'),
+    },
+  },
+  chatbot: {
+    name: 'Chatbot',
+    description: 'Conversational chatbot with document context',
+    dependencies: { '@devilsdev/rag-pipeline-utils': 'latest' },
+    devDependencies: {},
+    config: {
+      pipeline: { embedder: 'openai', retriever: 'memory', llm: 'openai' },
+      options: { topK: 3, stream: true },
+    },
+    files: {
+      'index.js': [
+        '// Chatbot Pipeline',
+        'const { createRagPipeline } = require(\'@devilsdev/rag-pipeline-utils\');',
+        '',
+        'const pipeline = createRagPipeline({',
+        '  // Configure your chatbot plugins',
+        '});',
+        '',
+        'async function chat(question) {',
+        '  const result = await pipeline.run({',
+        '    query: question,',
+        '    options: { stream: false },',
+        '  });',
+        '  return result.results;',
+        '}',
+        '',
+        '// Example usage',
+        'chat(\'Hello, how can you help me?\').then(console.log).catch(console.error);',
+      ].join('\n'),
+      'README.md': [
+        '# Chatbot Pipeline',
+        '',
+        'A conversational RAG chatbot.',
+        '',
+        '## Setup',
+        '',
+        '1. `npm install`',
+        '2. `export OPENAI_API_KEY=your-key`',
+        '3. `node index.js`',
+      ].join('\n'),
+    },
+  },
+  'code-search': {
+    name: 'Code Search',
+    description: 'Search and explain code repositories',
+    dependencies: { '@devilsdev/rag-pipeline-utils': 'latest' },
+    devDependencies: {},
+    config: {
+      pipeline: {
+        loader: 'directory',
+        embedder: 'openai',
+        retriever: 'memory',
+        llm: 'openai',
+      },
+      options: { topK: 10 },
+    },
+    files: {
+      'index.js': [
+        '// Code Search Pipeline',
+        'const { createRagPipeline, ChunkingEngine } = require(\'@devilsdev/rag-pipeline-utils\');',
+        '',
+        'const chunker = new ChunkingEngine({ strategy: \'structure-aware\', chunkSize: 1024 });',
+        '',
+        'const pipeline = createRagPipeline({',
+        '  // Configure for code search',
+        '});',
+        '',
+        'async function searchCode(query) {',
+        '  const result = await pipeline.run({ query, options: { topK: 10 } });',
+        '  return result.results;',
+        '}',
+        '',
+        'searchCode(\'How does authentication work?\').then(console.log).catch(console.error);',
+      ].join('\n'),
+      'README.md': [
+        '# Code Search Pipeline',
+        '',
+        'Search and explain code in your repository.',
+        '',
+        '## Setup',
+        '',
+        '1. `npm install`',
+        '2. `export OPENAI_API_KEY=your-key`',
+        '3. `node index.js`',
+      ].join('\n'),
+    },
+  },
+  'customer-support': {
+    name: 'Customer Support',
+    description: 'AI-powered customer support with knowledge base',
+    dependencies: { '@devilsdev/rag-pipeline-utils': 'latest' },
+    devDependencies: {},
+    config: {
+      pipeline: {
+        loader: 'markdown',
+        embedder: 'openai',
+        retriever: 'memory',
+        llm: 'openai',
+      },
+      options: { topK: 5, citations: true, guardrails: true },
+    },
+    files: {
+      'index.js': [
+        '// Customer Support Pipeline',
+        'const { createRagPipeline, GuardrailsPipeline } = require(\'@devilsdev/rag-pipeline-utils\');',
+        '',
+        'const basePipeline = createRagPipeline({',
+        '  // Configure your support pipeline',
+        '});',
+        '',
+        '// Wrap with guardrails for production safety',
+        'const pipeline = new GuardrailsPipeline(basePipeline, {',
+        '  preRetrieval: { enableInjectionDetection: true },',
+        '  postGeneration: { enablePIIDetection: true, enableGroundednessCheck: true },',
+        '});',
+        '',
+        'async function handleTicket(question) {',
+        '  const result = await pipeline.run({ query: question });',
+        '  return { answer: result.answer, sources: result.citations, safe: result.guardrails };',
+        '}',
+        '',
+        'handleTicket(\'How do I reset my password?\').then(console.log).catch(console.error);',
+      ].join('\n'),
+      'README.md': [
+        '# Customer Support Pipeline',
+        '',
+        'AI-powered support with guardrails and citations.',
+        '',
+        '## Setup',
+        '',
+        '1. `npm install`',
+        '2. `export OPENAI_API_KEY=your-key`',
+        '3. `node index.js`',
+      ].join('\n'),
+    },
+  },
+};
+
+/**
+ * Registry of built-in and custom project templates.
+ *
+ * @example
+ * const registry = new TemplateRegistry();
+ * const templates = registry.list();
+ * const template = registry.get('document-qa');
+ */
+class TemplateRegistry {
+  constructor() {
+    /** @type {Map<string, Object>} */
+    this.templates = new Map(Object.entries(TEMPLATES));
+  }
+
+  /**
+   * List all available templates.
+   *
+   * @returns {Array<{key: string, name: string, description: string}>} Summary of each template
+   */
+  list() {
+    return Array.from(this.templates.entries()).map(([key, t]) => ({
+      key,
+      name: t.name,
+      description: t.description,
+    }));
+  }
+
+  /**
+   * Get a full template definition by key.
+   *
+   * @param {string} templateKey - Template identifier
+   * @returns {Object|null} Full template object, or null if not found
+   */
+  get(templateKey) {
+    return this.templates.get(templateKey) || null;
+  }
+
+  /**
+   * Register a custom template.
+   *
+   * @param {string} key - Template identifier
+   * @param {Object} template - Template definition
+   * @param {string} template.name - Display name
+   * @param {string} template.description - Short description
+   * @param {Object} template.dependencies - npm dependencies
+   * @param {Object} template.config - Pipeline configuration
+   * @param {Object} template.files - Map of filename to file content
+   * @returns {void}
+   */
+  register(key, template) {
+    if (!key || typeof key !== 'string') {
+      throw new TypeError('Template key must be a non-empty string');
+    }
+    if (!template || !template.name || !template.files) {
+      throw new TypeError('Template must have a name and files');
+    }
+    this.templates.set(key, template);
+  }
+
+  /**
+   * Check if a template exists.
+   *
+   * @param {string} key - Template identifier
+   * @returns {boolean} Whether the template is registered
+   */
+  has(key) {
+    return this.templates.has(key);
+  }
+}
+
+module.exports = { TemplateRegistry, TEMPLATES };

package/src/utils/contract-validator.js

@@ -15,6 +15,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { logger } = require('./logger');
 
 /**
  * ContractValidator class for validating plugin implementations
@@ -107,7 +108,7 @@ class ContractValidator {
           contracts[type] = this.loadContract(type);
         } catch (error) {
           // Skip invalid contracts
-          console.warn(`Skipping invalid contract: ${file}`);
+          logger.warn(`Skipping invalid contract: ${file}`);
         }
       }
     }

package/src/utils/input-sanitizer.js

@@ -313,118 +313,99 @@ class InputSanitizer {
     }
 
     // Check cache
-    if (this.options.enableCache) {
-      const cacheKey = `${rule}:${str}`;
-      if (this.cache.has(cacheKey)) {
-        this.cacheAccessTimes.set(cacheKey, Date.now());
-        this.stats.cached++;
-        return this.cache.get(cacheKey);
-      }
+    const cached = this._getCachedResult(rule, str);
+    if (cached !== undefined) {
+      return cached;
     }
 
-    let result;
-
-    switch (rule) {
-      case SanitizationRules.NONE:
-        result = str;
-        break;
-
-      case SanitizationRules.HTML:
-        result = this._escapeHtml(str);
-        break;
-
-      case SanitizationRules.HTML_STRICT:
-        result = this._stripHtml(str);
-        break;
-
-      case SanitizationRules.XSS:
-        result = this._sanitizeXss(str);
-        break;
-
-      case SanitizationRules.SQL:
-        result = this._sanitizeSql(str);
-        break;
-
-      case SanitizationRules.COMMAND:
-        result = this._sanitizeCommand(str);
-        break;
-
-      case SanitizationRules.PATH:
-        result = this._sanitizePath(str);
-        break;
-
-      case SanitizationRules.URL:
-        result = this._validateAndSanitizeUrl(str);
-        break;
-
-      case SanitizationRules.EMAIL:
-        result = this._validateEmail(str);
-        break;
+    const result = this._applyRule(str, rule);
 
-      case SanitizationRules.ALPHANUMERIC:
-        result = this._validateAlphanumeric(str);
-        break;
-
-      case SanitizationRules.UUID:
-        result = this._validateUuid(str);
-        break;
-
-      case SanitizationRules.INTEGER:
-        result = this._validateInteger(str);
-        break;
-
-      case SanitizationRules.FLOAT:
-        result = this._validateFloat(str);
-        break;
-
-      case SanitizationRules.BOOLEAN:
-        result = this._validateBoolean(str);
-        break;
-
-      case SanitizationRules.JSON:
-        result = this._validateJson(str);
-        break;
-
-      case SanitizationRules.BASE64:
-        result = this._validateBase64(str);
-        break;
+    // Cache result
+    if (this.options.enableCache) {
+      const cacheKey = `${rule}:${str}`;
+      this._addToCache(cacheKey, result);
+    }
 
-      case SanitizationRules.HEX:
-        result = this._validateHex(str);
-        break;
+    return result;
+  }
 
-      case SanitizationRules.SLUG:
-        result = this._validateSlug(str);
-        break;
+  /**
+   * Retrieve a previously cached sanitization result.
+   * @param {string} rule - The sanitization rule that was applied
+   * @param {string} str - The original input string
+   * @returns {*} The cached result, or undefined if not cached
+   * @private
+   */
+  _getCachedResult(rule, str) {
+    if (!this.options.enableCache) {
+      return undefined;
+    }
 
-      case SanitizationRules.DOMAIN:
-        result = this._validateDomain(str);
-        break;
+    const cacheKey = `${rule}:${str}`;
+    if (this.cache.has(cacheKey)) {
+      this.cacheAccessTimes.set(cacheKey, Date.now());
+      this.stats.cached++;
+      return this.cache.get(cacheKey);
+    }
 
-      case SanitizationRules.IPV4:
-        result = this._validateIpv4(str);
-        break;
+    return undefined;
+  }
 
-      case SanitizationRules.IPV6:
-        result = this._validateIpv6(str);
-        break;
+  /**
+   * Apply a sanitization or validation rule to an input string.
+   * Dispatches to the appropriate handler based on the rule name.
+   * @param {string} str - The input string to sanitize
+   * @param {string} rule - The sanitization rule to apply
+   * @returns {*} The sanitized or validated result
+   * @private
+   */
+  _applyRule(str, rule) {
+    const ruleHandlers = this._getRuleHandlers();
+    const handler = ruleHandlers[rule];
 
-      default:
-        // Check custom rules
-        if (this.options.customRules[rule]) {
-          result = this.options.customRules[rule](str);
-        } else {
-          result = this._escapeHtml(str); // Default to HTML escape
-        }
+    if (handler) {
+      return handler(str);
     }
 
-    // Cache result
-    if (this.options.enableCache) {
-      const cacheKey = `${rule}:${str}`;
-      this._addToCache(cacheKey, result);
+    // Check custom rules
+    if (this.options.customRules[rule]) {
+      return this.options.customRules[rule](str);
     }
 
-    return result;
+    // Default to HTML escape
+    return this._escapeHtml(str);
+  }
+
+  /**
+   * Build the mapping from sanitization rule names to their handler functions.
+   * @returns {Object.<string, Function>} Map of rule name to handler function
+   * @private
+   */
+  _getRuleHandlers() {
+    return {
+      [SanitizationRules.NONE]: (str) => str,
+      [SanitizationRules.HTML]: (str) => this._escapeHtml(str),
+      [SanitizationRules.HTML_STRICT]: (str) => this._stripHtml(str),
+      [SanitizationRules.XSS]: (str) => this._sanitizeXss(str),
+      [SanitizationRules.SQL]: (str) => this._sanitizeSql(str),
+      [SanitizationRules.COMMAND]: (str) => this._sanitizeCommand(str),
+      [SanitizationRules.PATH]: (str) => this._sanitizePath(str),
+      [SanitizationRules.URL]: (str) => this._validateAndSanitizeUrl(str),
+      [SanitizationRules.EMAIL]: (str) => this._validateEmail(str),
+      [SanitizationRules.ALPHANUMERIC]: (str) =>
+        this._validateAlphanumeric(str),
+      [SanitizationRules.UUID]: (str) => this._validateUuid(str),
+      [SanitizationRules.INTEGER]: (str) => this._validateInteger(str),
+      [SanitizationRules.FLOAT]: (str) => this._validateFloat(str),
+      [SanitizationRules.BOOLEAN]: (str) => this._validateBoolean(str),
+      [SanitizationRules.JSON]: (str) => this._validateJson(str),
+      [SanitizationRules.BASE64]: (str) => this._validateBase64(str),
+      [SanitizationRules.HEX]: (str) => this._validateHex(str),
+      [SanitizationRules.SLUG]: (str) => this._validateSlug(str),
+      [SanitizationRules.DOMAIN]: (str) => this._validateDomain(str),
+      [SanitizationRules.IPV4]: (str) => this._validateIpv4(str),
+      [SanitizationRules.IPV6]: (str) => this._validateIpv6(str),
+    };
   }
 
   /**

package/src/utils/performance-monitor.js

@@ -556,6 +556,3 @@ module.exports = {
   createPerformanceMonitor,
   monitor: defaultMonitor,
 };
-
-// CommonJS/ESM interop
-module.exports.default = module.exports;

package/src/utils/plugin-scaffolder.js

@@ -11,6 +11,7 @@ const path = require('path');
 // eslint-disable-line global-require
 const { pluginContracts } = require('../core/plugin-contracts.js');
 // eslint-disable-line global-require
+const { logger } = require('./logger');
 
 class PluginScaffolder {
   constructor(_options = {}) {
@@ -47,24 +48,16 @@ class PluginScaffolder {
     await this.generateReadme(pluginDir, pluginType, pluginName, _options);
     await this.generatePackageJson(pluginDir, pluginType, pluginName, _options);
 
-    console.log(`✅ Plugin scaffolded successfully at: ${pluginDir}`);
-    // eslint-disable-line no-console
-    console.log('📁 Generated files:');
-    // eslint-disable-line no-console
-    console.log(`   - src/${pluginName}-${pluginType}.js (main plugin)`);
-    // eslint-disable-line no-console
-    console.log(`   - __tests__/${pluginName}-${pluginType}.test.js (tests)`);
-    // eslint-disable-line no-console
-    console.log(
+    logger.info(`Plugin scaffolded successfully at: ${pluginDir}`);
+    logger.info('Generated files:');
+    logger.info(`   - src/${pluginName}-${pluginType}.js (main plugin)`);
+    logger.info(`   - __tests__/${pluginName}-${pluginType}.test.js (tests)`);
+    logger.info(
       `   - mocks/${pluginName}-${pluginType}-mock.js (mock implementation)`,
     );
-    // eslint-disable-line no-console
-    console.log('   - .ragrc.example.json (configuration example)');
-    // eslint-disable-line no-console
-    console.log('   - README.md (documentation)');
-    // eslint-disable-line no-console
-    console.log('   - package.json (npm package)');
-    // eslint-disable-line no-console
+    logger.info('   - .ragrc.example.json (configuration example)');
+    logger.info('   - README.md (documentation)');
+    logger.info('   - package.json (npm package)');
   }
 
   /**

package/src/utils/rate-limiter.js

@@ -241,4 +241,3 @@ class RateLimiter {
 }
 
 module.exports = RateLimiter;
-module.exports.default = module.exports;