@rag-forge/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1260 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { existsSync } from "fs";
+import { cp, readFile, writeFile, readdir } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/lib/logger.ts
+import chalk from "chalk";
+var logger = {
+  info(message) {
+    console.log(chalk.blue("\u2139"), message);
+  },
+  success(message) {
+    console.log(chalk.green("\u2713"), message);
+  },
+  warn(message) {
+    console.log(chalk.yellow("\u26A0"), message);
+  },
+  error(message) {
+    console.error(chalk.red("\u2717"), message);
+  },
+  debug(message) {
+    if (process.env["DEBUG"]) {
+      console.log(chalk.gray("\u22A1"), message);
+    }
+  }
+};
+
+// src/commands/init.ts
+var AVAILABLE_TEMPLATES = ["basic", "hybrid", "agentic", "enterprise", "n8n"];
+function getTemplatesDir() {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(currentDir, "..", "..", "..", "templates");
+}
+async function listFiles(dir, prefix = "") {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await listFiles(join(dir, entry.name), rel));
+    } else {
+      files.push(rel);
+    }
+  }
+  return files;
+}
+function registerInitCommand(program2) {
+  program2.command("init").argument("[template]", "Project template to use", "basic").option("-d, --directory <dir>", "Target directory").option("--no-install", "Skip dependency installation").description("Scaffold a new RAG project from a template").action(async (template, options) => {
+    const templateName = template;
+    if (!AVAILABLE_TEMPLATES.includes(templateName)) {
+      logger.error(
+        `Unknown template "${template}". Available: ${AVAILABLE_TEMPLATES.join(", ")}`
+      );
+      process.exit(1);
+    }
+    const targetDir = resolve(options.directory ?? templateName);
+    if (existsSync(targetDir) && options.directory !== ".") {
+      const entries = await readdir(targetDir);
+      if (entries.length > 0) {
+        logger.error(`Directory "${targetDir}" already exists and is not empty.`);
+        process.exit(1);
+      }
+    }
+    const templatesDir = getTemplatesDir();
+    const sourceDir = join(templatesDir, templateName, "project");
+    if (!existsSync(sourceDir)) {
+      logger.error(`Template "${templateName}" not found at ${sourceDir}`);
+      process.exit(1);
+    }
+    logger.info(`Scaffolding ${templateName} RAG project in ${targetDir}...`);
+    await cp(sourceDir, targetDir, { recursive: true });
+    const projectName = targetDir.split(/[/\\]/).pop() ?? templateName;
+    const pyprojectPath = join(targetDir, "pyproject.toml");
+    if (existsSync(pyprojectPath)) {
+      let content = await readFile(pyprojectPath, "utf-8");
+      content = content.replace(/my-rag-pipeline/g, projectName);
+      await writeFile(pyprojectPath, content, "utf-8");
+    }
+    const files = await listFiles(targetDir);
+    for (const file of files) {
+      logger.success(`  Created ${file}`);
+    }
+    logger.info("");
+    logger.info("Next steps:");
+    logger.info(`  cd ${targetDir}`);
+    logger.info("  rag-forge index --source ./docs");
+    logger.info("  rag-forge audit --golden-set eval/golden_set.json");
+  });
+}
+
+// src/commands/index.ts
+import ora from "ora";
+
+// src/lib/python-bridge.ts
+import {
+  runPythonModule,
+  checkPythonAvailable
+} from "@rag-forge/shared";
+
+// src/commands/index.ts
+function registerIndexCommand(program2) {
+  program2.command("index").requiredOption("-s, --source <dir>", "Source directory of documents to index").option("-c, --collection <name>", "Collection name", "rag-forge").option("-e, --embedding <provider>", "Embedding provider: openai | local | mock", "mock").option("--strategy <name>", "Chunking strategy: fixed | recursive | semantic | structural | llm-driven", "recursive").option(
+    "--chunking-generator <provider>",
+    "Generator for LLM-driven chunking: claude | openai | mock"
+  ).option("--enrich", "Enable contextual enrichment (document summary prepending)").option(
+    "--sparse-index-path <path>",
+    "Path to persist BM25 sparse index"
+  ).option(
+    "--enrichment-generator <provider>",
+    "Generator for enrichment summaries: claude | openai | mock"
+  ).description("Index documents into the vector store").action(
+    async (options) => {
+      const spinner = ora("Indexing documents...").start();
+      try {
+        const configJson = JSON.stringify({
+          embedding_provider: options.embedding,
+          collection_name: options.collection,
+          chunk_size: 512,
+          overlap_ratio: 0.1
+        });
+        const args = [
+          "index",
+          "--source",
+          options.source,
+          "--collection",
+          options.collection,
+          "--embedding",
+          options.embedding,
+          "--config-json",
+          configJson
+        ];
+        args.push("--strategy", options.strategy);
+        if (options.strategy === "llm-driven" && !options.chunkingGenerator) {
+          spinner.fail("--chunking-generator is required for llm-driven strategy");
+          process.exit(1);
+        }
+        if (options.chunkingGenerator) {
+          args.push("--chunking-generator", options.chunkingGenerator);
+        }
+        if (options.enrichmentGenerator && !options.enrich) {
+          spinner.fail("--enrichment-generator requires --enrich");
+          process.exit(1);
+        }
+        if (options.enrich) {
+          args.push("--enrich");
+        }
+        if (options.sparseIndexPath) {
+          args.push("--sparse-index-path", options.sparseIndexPath);
+        }
+        if (options.enrichmentGenerator) {
+          args.push("--enrichment-generator", options.enrichmentGenerator);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          spinner.fail("Indexing failed");
+          logger.error(result.stderr || "Unknown error during indexing");
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (output.success) {
+          spinner.succeed("Indexing complete");
+          logger.info(`Documents processed: ${String(output.documents_processed)}`);
+          logger.info(`Chunks created: ${String(output.chunks_created)}`);
+          logger.info(`Chunks indexed: ${String(output.chunks_indexed)}`);
+          if (output.enrichment_summaries > 0) {
+            logger.info(
+              `Documents enriched: ${String(output.enrichment_summaries)}`
+            );
+          }
+        } else {
+          spinner.warn("Indexing completed with errors");
+          for (const error of output.errors) {
+            logger.error(error);
+          }
+          process.exit(1);
+        }
+      } catch (error) {
+        spinner.fail("Indexing failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/audit.ts
+import ora2 from "ora";
+function registerAuditCommand(program2) {
+  program2.command("audit").option("-i, --input <file>", "Path to telemetry JSONL file").option("-g, --golden-set <file>", "Path to golden set JSON file").option("-j, --judge <model>", "Judge model: mock | claude | openai", "mock").option("-o, --output <dir>", "Output directory for reports", "./reports").option("--evaluator <engine>", "Evaluator engine: llm-judge | ragas | deepeval", "llm-judge").option("--pdf", "Generate PDF report (requires Playwright)").description("Run evaluation on pipeline telemetry and generate audit report").action(
+    async (options) => {
+      if (!options.input && !options.goldenSet) {
+        logger.error("Either --input or --golden-set is required");
+        process.exit(1);
+      }
+      const spinner = ora2("Running RAG pipeline audit...").start();
+      try {
+        const args = ["audit", "--judge", options.judge, "--output", options.output, "--evaluator", options.evaluator];
+        if (options.input) {
+          args.push("--input", options.input);
+        }
+        if (options.goldenSet) {
+          args.push("--golden-set", options.goldenSet);
+        }
+        if (options.pdf) {
+          args.push("--pdf");
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          spinner.fail("Audit failed");
+          logger.error(result.stderr || "Unknown error during audit");
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (output.passed) {
+          spinner.succeed(
+            `Audit passed \u2014 RMM-${String(output.rmm_level)}: ${output.rmm_name}`
+          );
+        } else {
+          spinner.warn(
+            `Audit completed \u2014 RMM-${String(output.rmm_level)}: ${output.rmm_name}`
+          );
+        }
+        logger.info(`Overall score: ${output.overall_score.toFixed(2)}`);
+        logger.info(`Samples evaluated: ${String(output.samples_evaluated)}`);
+        for (const metric of output.metrics) {
+          const status = metric.passed ? "PASS" : "FAIL";
+          logger.info(
+            `  ${metric.name}: ${metric.score.toFixed(2)} (threshold: ${metric.threshold.toFixed(2)}) [${status}]`
+          );
+        }
+        logger.info(`Evaluator: ${output.evaluator_engine}`);
+        logger.success(`Report saved to: ${output.report_path}`);
+        if (output.pdf_report_path) {
+          logger.success(`PDF report: ${output.pdf_report_path}`);
+        }
+      } catch (error) {
+        spinner.fail("Audit failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/query.ts
+import ora3 from "ora";
+function registerQueryCommand(program2) {
+  program2.command("query").argument("<question>", "The question to ask the RAG pipeline").option("-k, --top-k <number>", "Number of chunks to retrieve", "5").option("-e, --embedding <provider>", "Embedding provider: openai | local | mock", "mock").option("-g, --generator <provider>", "Generation provider: claude | openai | mock", "mock").option("-c, --collection <name>", "Collection name", "rag-forge").option(
+    "--strategy <type>",
+    "Retrieval strategy: dense | sparse | hybrid",
+    "dense"
+  ).option(
+    "--alpha <number>",
+    "RRF alpha weighting for hybrid retrieval (0.0-1.0)",
+    "0.6"
+  ).option(
+    "--reranker <type>",
+    "Reranker: none | cohere | bge-local",
+    "none"
+  ).option(
+    "--sparse-index-path <path>",
+    "Path to BM25 sparse index"
+  ).option("--input-guard", "Enable input security guard").option("--output-guard", "Enable output security guard").option(
+    "--faithfulness-threshold <number>",
+    "Faithfulness score threshold (0.0-1.0)",
+    "0.85"
+  ).option("--rate-limit <number>", "Max queries per minute", "60").option("--cache", "Enable semantic query caching").option("--cache-ttl <seconds>", "Cache TTL in seconds", "3600").option("--cache-similarity <threshold>", "Cosine similarity threshold", "0.95").option("--agent-mode", "Enable multi-query decomposition").description("Execute a RAG query against the indexed pipeline").action(
+    async (question, options) => {
+      const spinner = ora3("Querying pipeline...").start();
+      try {
+        const args = [
+          "query",
+          "--question",
+          question,
+          "--embedding",
+          options.embedding,
+          "--generator",
+          options.generator,
+          "--collection",
+          options.collection,
+          "--top-k",
+          options.topK,
+          "--strategy",
+          options.strategy,
+          "--alpha",
+          options.alpha,
+          "--reranker",
+          options.reranker
+        ];
+        if (options.sparseIndexPath) {
+          args.push("--sparse-index-path", options.sparseIndexPath);
+        }
+        if (options.inputGuard) {
+          args.push("--input-guard");
+        }
+        if (options.outputGuard) {
+          args.push("--output-guard");
+        }
+        args.push("--faithfulness-threshold", options.faithfulnessThreshold);
+        args.push("--rate-limit", options.rateLimit);
+        if (options.cache) {
+          args.push("--cache");
+        }
+        args.push("--cache-ttl", options.cacheTtl);
+        args.push("--cache-similarity", options.cacheSimilarity);
+        if (options.agentMode) {
+          args.push("--agent-mode");
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          spinner.fail("Query failed");
+          logger.error(result.stderr || "Unknown error");
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (output.blocked) {
+          spinner.warn(`Query blocked: ${output.blocked_reason ?? "Unknown reason"}`);
+          return;
+        }
+        spinner.succeed(`Answer (${output.model_used}):`);
+        console.log("");
+        console.log(output.answer);
+        console.log("");
+        if (output.sources.length > 0) {
+          logger.info(`Sources (${String(output.chunks_retrieved)} chunks):`);
+          for (const source of output.sources) {
+            logger.info(
+              `  [${source.score.toFixed(3)}] ${source.text.slice(0, 120)}...`
+            );
+          }
+        }
+      } catch (error) {
+        spinner.fail("Query failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/serve.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function getMcpMainPath() {
+  const currentDir = fileURLToPath2(new URL(".", import.meta.url));
+  return resolve2(currentDir, "..", "..", "..", "mcp", "dist", "main.js");
+}
+function registerServeCommand(program2) {
+  program2.command("serve").option("--mcp", "Launch MCP server").option("--transport <type>", "Transport: stdio | http", "stdio").option("-p, --port <number>", "Port for HTTP transport", "3100").description("Start the RAG-Forge server").action(async (options) => {
+    if (!options.mcp) {
+      logger.error("Please specify a server mode. Currently supported: --mcp");
+      process.exit(1);
+    }
+    const mcpMain = getMcpMainPath();
+    if (!existsSync2(mcpMain)) {
+      logger.error(`MCP server not found at ${mcpMain}. Run 'pnpm run build' first.`);
+      process.exit(1);
+    }
+    const args = [mcpMain];
+    if (options.transport === "http") {
+      args.push("--transport", "http", "--port", options.port);
+      logger.info(`Starting MCP server on http://localhost:${options.port}/sse`);
+    } else {
+      logger.info("Starting MCP server on stdio...");
+    }
+    const child = spawn(process.execPath, args, {
+      stdio: "inherit"
+    });
+    child.on("error", (error) => {
+      logger.error(`MCP server failed: ${error.message}`);
+      process.exit(1);
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+    });
+  });
+}
+
+// src/commands/drift.ts
+import ora4 from "ora";
+function registerDriftCommand(program2) {
+  const drift = program2.command("drift").description("Query drift detection and baseline management");
+  drift.command("report").requiredOption("--current <file>", "Path to current embeddings JSON").requiredOption("--baseline <file>", "Path to baseline embeddings JSON").option("--threshold <number>", "Drift threshold (cosine distance)", "0.15").description("Analyze query distribution drift from baseline").action(
+    async (options) => {
+      const spinner = ora4("Analyzing query drift...").start();
+      try {
+        const result = await runPythonModule({
+          module: "rag_forge_observability.cli",
+          args: [
+            "drift-report",
+            "--current",
+            options.current,
+            "--baseline",
+            options.baseline,
+            "--threshold",
+            options.threshold
+          ]
+        });
+        if (result.exitCode !== 0) {
+          spinner.fail("Drift analysis failed");
+          logger.error(result.stderr || "Unknown error");
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("Drift analysis failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        if (output.is_drifting) {
+          spinner.warn(
+            `DRIFT DETECTED \u2014 distance: ${output.distance?.toFixed(4)} (threshold: ${output.threshold?.toFixed(4)})`
+          );
+        } else {
+          spinner.succeed(
+            `No drift \u2014 distance: ${output.distance?.toFixed(4)} (threshold: ${output.threshold?.toFixed(4)})`
+          );
+        }
+        if (output.details) {
+          logger.info(output.details);
+        }
+      } catch (error) {
+        spinner.fail("Drift analysis failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+  drift.command("save-baseline").requiredOption("--embeddings <file>", "Path to embeddings JSON").requiredOption("--output <file>", "Path to save baseline").description("Save current embeddings as drift baseline").action(async (options) => {
+    const spinner = ora4("Saving drift baseline...").start();
+    try {
+      const result = await runPythonModule({
+        module: "rag_forge_observability.cli",
+        args: [
+          "drift-save-baseline",
+          "--embeddings",
+          options.embeddings,
+          "--output",
+          options.output
+        ]
+      });
+      if (result.exitCode !== 0) {
+        spinner.fail("Failed to save baseline");
+        logger.error(result.stderr || "Unknown error");
+        process.exit(1);
+      }
+      const output = JSON.parse(result.stdout);
+      if (output.success) {
+        spinner.succeed(
+          `Baseline saved: ${String(output.vectors_saved)} vectors \u2192 ${output.baseline_path}`
+        );
+      } else {
+        spinner.fail("Failed to save baseline");
+        logger.error(output.error ?? "Unknown error");
+        process.exit(1);
+      }
+    } catch (error) {
+      spinner.fail("Failed to save baseline");
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error(message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/cost.ts
+import ora5 from "ora";
+function registerCostCommand(program2) {
+  program2.command("cost").requiredOption("--telemetry <file>", "Path to telemetry JSON file").option(
+    "--queries-per-day <number>",
+    "Projected daily query volume (overrides telemetry file)"
+  ).description("Estimate monthly pipeline costs from telemetry").action(
+    async (options) => {
+      const spinner = ora5("Estimating costs...").start();
+      try {
+        const args = ["cost", "--telemetry", options.telemetry];
+        if (options.queriesPerDay) {
+          args.push("--queries-per-day", options.queriesPerDay);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Cost estimation failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("Cost estimation failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        spinner.succeed("Cost estimation complete");
+        logger.info(
+          `Daily cost:   $${output.daily_cost.toFixed(4)} (${String(output.queries_per_day)} queries/day)`
+        );
+        logger.info(`Monthly cost: $${output.monthly_cost.toFixed(2)}`);
+        if (output.breakdown.length > 0) {
+          logger.info("Breakdown by model:");
+          for (const item of output.breakdown) {
+            logger.info(
+              `  ${item.model}: $${item.cost_per_query.toFixed(6)}/query`
+            );
+          }
+        }
+      } catch (error) {
+        spinner.fail("Cost estimation failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/golden.ts
+import ora6 from "ora";
+function registerGoldenCommand(program2) {
+  const golden = program2.command("golden").description("Golden set management for evaluation");
+  golden.command("add").requiredOption("-g, --golden-set <file>", "Path to golden set JSON", "eval/golden_set.json").option("--from-traffic <file>", "Sample from telemetry JSONL file").option("--sample-size <number>", "Number of entries to sample", "10").option("--query <question>", "Question to add manually").option("--keywords <list>", "Comma-separated expected keywords").option("--difficulty <level>", "Difficulty: easy | medium | hard", "medium").option("--topic <name>", "Topic category", "general").description("Add entries to the golden set (manual or from traffic)").action(
+    async (options) => {
+      const spinner = ora6("Adding to golden set...").start();
+      try {
+        const args = [
+          "golden-add",
+          "--golden-set",
+          options.goldenSet
+        ];
+        if (options.fromTraffic) {
+          args.push("--from-traffic", options.fromTraffic);
+          args.push("--sample-size", options.sampleSize);
+        } else if (options.query && options.keywords) {
+          args.push("--query", options.query);
+          args.push("--keywords", options.keywords);
+          args.push("--difficulty", options.difficulty);
+          args.push("--topic", options.topic);
+        } else {
+          spinner.fail("Provide --from-traffic <file> or --query <q> --keywords <k>");
+          process.exit(1);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Failed to add to golden set");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (output.success) {
+          spinner.succeed(
+            `Added ${String(output.added)} entries (total: ${String(output.total)}) \u2192 ${output.golden_set_path}`
+          );
+        } else {
+          spinner.fail("Failed to add to golden set");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+      } catch (error) {
+        spinner.fail("Failed to add to golden set");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+  golden.command("validate").requiredOption("-g, --golden-set <file>", "Path to golden set JSON", "eval/golden_set.json").description("Validate golden set coverage, balance, and schema").action(
+    async (options) => {
+      const spinner = ora6("Validating golden set...").start();
+      try {
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args: ["golden-validate", "--golden-set", options.goldenSet]
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Validation failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (output.valid) {
+          spinner.succeed(
+            `Golden set valid \u2014 ${String(output.total_entries)} entries, no issues`
+          );
+        } else {
+          spinner.warn(
+            `Golden set has ${String(output.errors.length)} issue(s):`
+          );
+          for (const err of output.errors) {
+            logger.warn(`  - ${err}`);
+          }
+        }
+      } catch (error) {
+        spinner.fail("Validation failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/assess.ts
+import ora7 from "ora";
+function registerAssessCommand(program2) {
+  program2.command("assess").option("--config <json>", "Pipeline config as JSON string").option("--audit-report <file>", "Path to latest audit JSON report").description("Run RAG Maturity Model assessment").action(
+    async (options) => {
+      const spinner = ora7("Running RMM assessment...").start();
+      try {
+        const args = ["assess"];
+        if (options.config) {
+          args.push("--config-json", options.config);
+        }
+        if (options.auditReport) {
+          args.push("--audit-report", options.auditReport);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Assessment failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("Assessment failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        spinner.succeed(output.badge);
+        for (const criteria of output.criteria) {
+          const icon = criteria.passed ? "PASS" : "----";
+          logger.info(`  [${icon}] RMM-${String(criteria.level)}: ${criteria.name}`);
+          for (const check of criteria.checks) {
+            const checkIcon = check.passed ? "+" : "-";
+            const source = check.source !== "config" ? ` (${check.source})` : "";
+            logger.info(`         [${checkIcon}] ${check.description}${source}`);
+          }
+        }
+      } catch (error) {
+        spinner.fail("Assessment failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/guardrails.ts
+import ora8 from "ora";
+function registerGuardrailsCommand(program2) {
+  const guardrails = program2.command("guardrails").description("Security testing and PII scanning");
+  guardrails.command("test").option("--corpus <file>", "Path to custom adversarial corpus JSON").description("Run adversarial prompt test suite against security guards").action(
+    async (options) => {
+      const spinner = ora8("Running adversarial tests...").start();
+      try {
+        const args = ["guardrails-test"];
+        if (options.corpus) {
+          args.push("--corpus", options.corpus);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Adversarial tests failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("Adversarial tests failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        const passPercent = (output.pass_rate * 100).toFixed(1);
+        if (output.failures.length === 0) {
+          spinner.succeed(
+            `All attacks blocked \u2014 ${String(output.blocked)}/${String(output.total_tested)} (${passPercent}% block rate)`
+          );
+        } else {
+          spinner.warn(
+            `${String(output.failures.length)} attacks got through \u2014 ${String(output.blocked)}/${String(output.total_tested)} blocked (${passPercent}% block rate)`
+          );
+        }
+        logger.info("By category:");
+        for (const [cat, stats] of Object.entries(output.by_category)) {
+          const rate = (stats.pass_rate * 100).toFixed(0);
+          logger.info(`  ${cat}: ${String(stats.blocked)}/${String(stats.tested)} blocked (${rate}%)`);
+        }
+        if (output.failures.length > 0) {
+          logger.warn("Failures (attacks that got through):");
+          for (const failure of output.failures) {
+            logger.warn(`  [${failure.severity}] ${failure.category}: ${failure.text.slice(0, 80)}...`);
+          }
+        }
+      } catch (error) {
+        spinner.fail("Adversarial tests failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+  guardrails.command("scan-pii").option("-c, --collection <name>", "Collection name", "rag-forge").description("Scan vector store for PII leakage").action(
+    async (options) => {
+      const spinner = ora8("Scanning for PII...").start();
+      try {
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args: ["guardrails-scan-pii", "--collection", options.collection]
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("PII scan failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("PII scan failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        if (output.chunks_with_pii === 0) {
+          spinner.succeed(
+            `No PII found \u2014 ${String(output.chunks_scanned)} chunks scanned`
+          );
+        } else {
+          spinner.warn(
+            `PII found in ${String(output.chunks_with_pii)}/${String(output.chunks_scanned)} chunks`
+          );
+          logger.warn("PII types detected:");
+          for (const [piiType, count] of Object.entries(output.pii_types)) {
+            logger.warn(`  ${piiType}: ${String(count)} occurrences`);
+          }
+        }
+      } catch (error) {
+        spinner.fail("PII scan failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/report.ts
+import ora9 from "ora";
+function registerReportCommand(program2) {
+  program2.command("report").option("-o, --output <dir>", "Output directory for reports", "./reports").option("--collection <name>", "Collection name", "rag-forge").description("Generate a pipeline health report dashboard").action(
+    async (options) => {
+      const spinner = ora9("Generating health report...").start();
+      try {
+        const result = await runPythonModule({
+          module: "rag_forge_evaluator.cli",
+          args: [
+            "report",
+            "--output",
+            options.output,
+            "--collection",
+            options.collection
+          ]
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Report generation failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.success) {
+          spinner.fail("Report generation failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        spinner.succeed("Health report generated");
+        logger.info(
+          `Indexed chunks: ${String(output.chunk_count ?? 0)}`
+        );
+        logger.info(
+          `Audit data: ${output.has_audit ? "included" : "none available"}`
+        );
+        logger.info(
+          `Drift baseline: ${output.drift_baseline ? "configured" : "not configured"}`
+        );
+        logger.success(`Report saved to: ${output.report_path ?? "unknown"}`);
+      } catch (error) {
+        spinner.fail("Report generation failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/cache.ts
+import ora10 from "ora";
+function registerCacheCommand(program2) {
+  const cache = program2.command("cache").description("Semantic cache management");
+  cache.command("stats").description("Show semantic cache hit/miss statistics").action(async () => {
+    const spinner = ora10("Fetching cache statistics...").start();
+    try {
+      const result = await runPythonModule({
+        module: "rag_forge_core.cli",
+        args: ["cache-stats"]
+      });
+      if (result.exitCode !== 0) {
+        let errorMessage = result.stderr || "Unknown error";
+        try {
+          const parsed = JSON.parse(
+            result.stdout
+          );
+          if (parsed.error) errorMessage = parsed.error;
+        } catch {
+        }
+        spinner.fail("Failed to fetch cache stats");
+        logger.error(errorMessage);
+        process.exit(1);
+      }
+      const output = JSON.parse(result.stdout);
+      if (!output.success) {
+        spinner.fail("Failed to fetch cache stats");
+        logger.error(output.error ?? "Unknown error");
+        process.exit(1);
+      }
+      spinner.succeed("Cache statistics");
+      const hitRate = output.hit_rate ?? 0;
+      const hitRatePercent = (hitRate * 100).toFixed(1);
+      logger.info(`Hit rate:  ${hitRatePercent}%`);
+      logger.info(`Hits:      ${String(output.hits ?? 0)}`);
+      logger.info(`Misses:    ${String(output.misses ?? 0)}`);
+      logger.info(`Total:     ${String(output.total ?? 0)}`);
+      logger.info(`Source:    ${output.source ?? "unknown"}`);
+      if (output.message) {
+        logger.info(output.message);
+      }
+    } catch (error) {
+      spinner.fail("Failed to fetch cache stats");
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error(message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/inspect.ts
+import ora11 from "ora";
+function registerInspectCommand(program2) {
+  program2.command("inspect").requiredOption("--chunk-id <id>", "The chunk ID to inspect").option("--collection <name>", "Collection name", "rag-forge").description("Inspect a specific chunk by ID").action(
+    async (options) => {
+      const spinner = ora11(
+        `Inspecting chunk ${options.chunkId}...`
+      ).start();
+      try {
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args: [
+            "inspect",
+            "--chunk-id",
+            options.chunkId,
+            "--collection",
+            options.collection
+          ]
+        });
+        if (result.exitCode !== 0) {
+          spinner.fail("Inspection failed");
+          logger.error(result.stderr || "Unknown error");
+          process.exit(1);
+        }
+        const output = JSON.parse(result.stdout);
+        if (!output.found) {
+          spinner.warn(
+            `Chunk not found: ${options.chunkId} in collection ${output.collection}`
+          );
+          if (output.error) {
+            logger.error(output.error);
+          }
+          return;
+        }
+        spinner.succeed(`Chunk found: ${output.chunk_id}`);
+        logger.info(`Collection: ${output.collection}`);
+        if (output.text !== void 0) {
+          logger.info("Text:");
+          logger.info(`  ${output.text}`);
+        }
+        if (output.metadata) {
+          logger.info("Metadata:");
+          for (const [key, value] of Object.entries(output.metadata)) {
+            logger.info(`  ${key}: ${String(value)}`);
+          }
+        }
+      } catch (error) {
+        spinner.fail("Inspection failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/add.ts
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { cp as cp2, mkdir } from "fs/promises";
+import { dirname as dirname2, resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function getPackageRoot() {
+  const currentDir = dirname2(fileURLToPath3(import.meta.url));
+  if (currentDir.endsWith("commands") || currentDir.endsWith("commands\\") || currentDir.endsWith("commands/")) {
+    return resolve3(currentDir, "..", "..");
+  }
+  return resolve3(currentDir, "..");
+}
+function getManifestPath() {
+  return resolve3(getPackageRoot(), "src", "modules", "manifest.json");
+}
+function getTemplateSourceDir() {
+  return resolve3(getPackageRoot(), "..", "..", "templates", "enterprise", "project", "src");
+}
+function registerAddCommand(program2) {
+  program2.command("add").argument(
+    "<module>",
+    "Module to add: guardrails | caching | reranking | enrichment | observability | hybrid-retrieval"
+  ).description("Add a feature module as editable source code (shadcn/ui model)").action(async (moduleName) => {
+    const manifestPath = getManifestPath();
+    if (!existsSync3(manifestPath)) {
+      logger.error(`Module manifest not found at ${manifestPath}`);
+      process.exit(1);
+    }
+    const manifest = JSON.parse(
+      readFileSync(manifestPath, "utf-8")
+    );
+    const mod = manifest.modules[moduleName];
+    if (!mod) {
+      const available = Object.keys(manifest.modules).join(", ");
+      logger.error(`Unknown module: ${moduleName}. Available: ${available}`);
+      process.exit(1);
+    }
+    logger.info(`Adding module: ${moduleName} \u2014 ${mod.description}`);
+    const sourceDir = getTemplateSourceDir();
+    let added = 0;
+    let skipped = 0;
+    let missingSources = 0;
+    for (const file of mod.files) {
+      const srcPath = resolve3(sourceDir, file.src);
+      const destPath = resolve3(process.cwd(), file.dest);
+      if (existsSync3(destPath)) {
+        logger.warn(`  Skip (exists): ${file.dest}`);
+        skipped++;
+        continue;
+      }
+      if (!existsSync3(srcPath)) {
+        logger.warn(`  Skip (source not found): ${file.src}`);
+        missingSources++;
+        continue;
+      }
+      await mkdir(dirname2(destPath), { recursive: true });
+      await cp2(srcPath, destPath);
+      logger.success(`  Added: ${file.dest}`);
+      added++;
+    }
+    logger.info(
+      `
+Added ${String(added)} files, skipped ${String(skipped)}, missing ${String(missingSources)}`
+    );
+    if (added === 0 && missingSources > 0) {
+      logger.error(
+        "No files were added because all sources are missing. This indicates a packaging or manifest problem."
+      );
+      process.exit(1);
+    }
+    if (mod.dependencies.length > 0) {
+      logger.info("\nInstall dependencies:");
+      logger.info(`  pip install ${mod.dependencies.join(" ")}`);
+    }
+  });
+}
+
+// src/commands/parse.ts
+import ora12 from "ora";
+function registerParseCommand(program2) {
+  program2.command("parse").option("-s, --source <directory>", "Source directory to parse", "./docs").description("Preview document extraction without indexing").action(async (options) => {
+    const spinner = ora12("Parsing documents...").start();
+    try {
+      const args = ["parse", "--source", options.source];
+      const result = await runPythonModule({
+        module: "rag_forge_core.cli",
+        args
+      });
+      if (result.exitCode !== 0) {
+        let errorMessage = result.stderr || "Unknown error";
+        try {
+          const parsed = JSON.parse(result.stdout);
+          if (parsed.error) errorMessage = parsed.error;
+        } catch {
+        }
+        spinner.fail("Parse preview failed");
+        logger.error(errorMessage);
+        process.exit(1);
+      }
+      const output = JSON.parse(result.stdout);
+      if (!output.success) {
+        spinner.fail("Parse preview failed");
+        logger.error(output.error ?? "Unknown error");
+        process.exit(1);
+      }
+      spinner.succeed(
+        `Found ${String(output.files_found)} files (${String(output.total_characters)} characters)`
+      );
+      if (output.files.length > 0) {
+        console.log("");
+        for (const file of output.files) {
+          logger.info(`  ${file.path} (${String(file.characters)} chars)`);
+        }
+      }
+      if (output.parse_errors.length > 0) {
+        console.log("");
+        logger.warn(`${String(output.parse_errors.length)} parse errors:`);
+        for (const err of output.parse_errors) {
+          logger.warn(`  ${err}`);
+        }
+      }
+    } catch (error) {
+      spinner.fail("Parse preview failed");
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error(message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/chunk.ts
+import ora13 from "ora";
+function registerChunkCommand(program2) {
+  program2.command("chunk").option("-s, --source <directory>", "Source directory to chunk", "./docs").option(
+    "--strategy <type>",
+    "Chunking strategy: fixed | recursive | semantic | structural | llm-driven",
+    "recursive"
+  ).option("--chunk-size <tokens>", "Target chunk size in tokens").description("Preview chunking without indexing").action(
+    async (options) => {
+      const spinner = ora13("Chunking documents...").start();
+      try {
+        const args = [
+          "chunk",
+          "--source",
+          options.source,
+          "--strategy",
+          options.strategy
+        ];
+        if (options.chunkSize) {
+          args.push("--chunk-size", options.chunkSize);
+        }
+        const result = await runPythonModule({
+          module: "rag_forge_core.cli",
+          args
+        });
+        if (result.exitCode !== 0) {
+          let errorMessage = result.stderr || "Unknown error";
+          try {
+            const parsed = JSON.parse(result.stdout);
+            if (parsed.error) errorMessage = parsed.error;
+          } catch {
+          }
+          spinner.fail("Chunk preview failed");
+          logger.error(errorMessage);
+          process.exit(1);
+        }
+        const output = JSON.parse(
+          result.stdout
+        );
+        if (!output.success) {
+          spinner.fail("Chunk preview failed");
+          logger.error(output.error ?? "Unknown error");
+          process.exit(1);
+        }
+        spinner.succeed(
+          `${String(output.total_chunks)} chunks (${output.strategy}, target ${String(output.chunk_size)} tokens)`
+        );
+        console.log("");
+        logger.info("Stats:");
+        logger.info(
+          `  Avg size: ${String(output.stats.avg_chunk_size)} tokens`
+        );
+        logger.info(
+          `  Min size: ${String(output.stats.min_chunk_size)} tokens`
+        );
+        logger.info(
+          `  Max size: ${String(output.stats.max_chunk_size)} tokens`
+        );
+        logger.info(
+          `  Total tokens: ${String(output.stats.total_tokens)}`
+        );
+        if (output.samples.length > 0) {
+          console.log("");
+          logger.info("Sample chunks:");
+          for (const sample of output.samples) {
+            logger.info(
+              `  [${String(sample.index)}] ${sample.source}: ${sample.preview}`
+            );
+          }
+        }
+      } catch (error) {
+        spinner.fail("Chunk preview failed");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        logger.error(message);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/commands/n8n.ts
+import ora14 from "ora";
+function registerN8nCommand(program2) {
+  program2.command("n8n").option(
+    "-o, --output <file>",
+    "Output file path",
+    "n8n-workflow.json"
+  ).option(
+    "--mcp-url <url>",
+    "MCP server SSE endpoint",
+    "http://localhost:3100/sse"
+  ).description("Export pipeline configuration as an importable n8n workflow").action(async (options) => {
+    const spinner = ora14("Generating n8n workflow...").start();
+    try {
+      const args = [
+        "n8n-export",
+        "--output",
+        options.output,
+        "--mcp-url",
+        options.mcpUrl
+      ];
+      const result = await runPythonModule({
+        module: "rag_forge_core.cli",
+        args
+      });
+      if (result.exitCode !== 0) {
+        spinner.fail("n8n export failed");
+        logger.error(result.stderr || "Unknown error");
+        process.exit(1);
+      }
+      const output = JSON.parse(
+        result.stdout
+      );
+      if (!output.success) {
+        spinner.fail("n8n export failed");
+        logger.error(output.error ?? "Unknown error");
+        process.exit(1);
+      }
+      spinner.succeed(
+        `Exported n8n workflow with ${String(output.nodes)} nodes`
+      );
+      logger.info(`  Output: ${output.output_path}`);
+      logger.info("");
+      logger.info("Import this file into n8n via:");
+      logger.info("  1. Open n8n dashboard");
+      logger.info("  2. Click 'Import from File'");
+      logger.info(`  3. Select ${output.output_path}`);
+    } catch (error) {
+      spinner.fail("n8n export failed");
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error(message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("rag-forge").description(
+  "Framework-agnostic CLI toolkit for production-grade RAG pipelines with evaluation baked in"
+).version("0.1.0");
+registerInitCommand(program);
+registerIndexCommand(program);
+registerAuditCommand(program);
+registerQueryCommand(program);
+registerServeCommand(program);
+registerDriftCommand(program);
+registerCostCommand(program);
+registerGoldenCommand(program);
+registerAssessCommand(program);
+registerGuardrailsCommand(program);
+registerReportCommand(program);
+registerCacheCommand(program);
+registerInspectCommand(program);
+registerAddCommand(program);
+registerParseCommand(program);
+registerChunkCommand(program);
+registerN8nCommand(program);
+program.parse();
+//# sourceMappingURL=index.js.map