unrag 0.2.9 → 0.2.11

package/dist/cli/index.js

@@ -19,7 +19,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // cli/run.ts
-import { intro, outro as outro5 } from "@clack/prompts";
+import { intro, outro as outro6 } from "@clack/prompts";
 
 // cli/commands/init.ts
 import {
@@ -97,6 +97,11 @@ var writeText = async (filePath, content) => {
   await ensureDir(path2.dirname(filePath));
   await writeFile(filePath, content, "utf8");
 };
+var rewriteRegistryAliasImports = (content, aliasBase) => {
+  if (!content.includes("@registry"))
+    return content;
+  return content.replaceAll("@registry/", `${aliasBase}/`);
+};
 var EXTRACTOR_FACTORY = {
   "pdf-llm": "createPdfLlmExtractor",
   "pdf-text-layer": "createPdfTextLayerExtractor",
@@ -400,6 +405,26 @@ async function copyRegistryFiles(selection) {
       src: path2.join(selection.registryRoot, "core/rerank.ts"),
       dest: path2.join(installBaseAbs, "core/rerank.ts")
     },
+    {
+      src: path2.join(selection.registryRoot, "core/debug-emitter.ts"),
+      dest: path2.join(installBaseAbs, "core/debug-emitter.ts")
+    },
+    {
+      src: path2.join(selection.registryRoot, "core/debug-events.ts"),
+      dest: path2.join(installBaseAbs, "core/debug-events.ts")
+    },
+    {
+      src: path2.join(selection.registryRoot, "extractors/_shared/fetch.ts"),
+      dest: path2.join(installBaseAbs, "extractors/_shared/fetch.ts")
+    },
+    {
+      src: path2.join(selection.registryRoot, "extractors/_shared/media.ts"),
+      dest: path2.join(installBaseAbs, "extractors/_shared/media.ts")
+    },
+    {
+      src: path2.join(selection.registryRoot, "extractors/_shared/text.ts"),
+      dest: path2.join(installBaseAbs, "extractors/_shared/text.ts")
+    },
     {
       src: path2.join(selection.registryRoot, "embedding/_shared.ts"),
       dest: path2.join(installBaseAbs, "embedding/_shared.ts")
@@ -455,29 +480,29 @@ async function copyRegistryFiles(selection) {
   ];
   if (selection.storeAdapter === "drizzle") {
     fileMappings.push({
-      src: path2.join(selection.registryRoot, "store/drizzle-postgres-pgvector/index.ts"),
+      src: path2.join(selection.registryRoot, "store/drizzle/index.ts"),
       dest: path2.join(installBaseAbs, "store/drizzle/index.ts")
     }, {
-      src: path2.join(selection.registryRoot, "store/drizzle-postgres-pgvector/schema.ts"),
+      src: path2.join(selection.registryRoot, "store/drizzle/schema.ts"),
       dest: path2.join(installBaseAbs, "store/drizzle/schema.ts")
     }, {
-      src: path2.join(selection.registryRoot, "store/drizzle-postgres-pgvector/store.ts"),
+      src: path2.join(selection.registryRoot, "store/drizzle/store.ts"),
       dest: path2.join(installBaseAbs, "store/drizzle/store.ts")
     });
   } else if (selection.storeAdapter === "raw-sql") {
     fileMappings.push({
-      src: path2.join(selection.registryRoot, "store/raw-sql-postgres-pgvector/index.ts"),
+      src: path2.join(selection.registryRoot, "store/raw-sql/index.ts"),
       dest: path2.join(installBaseAbs, "store/raw-sql/index.ts")
     }, {
-      src: path2.join(selection.registryRoot, "store/raw-sql-postgres-pgvector/store.ts"),
+      src: path2.join(selection.registryRoot, "store/raw-sql/store.ts"),
       dest: path2.join(installBaseAbs, "store/raw-sql/store.ts")
     });
   } else {
     fileMappings.push({
-      src: path2.join(selection.registryRoot, "store/prisma-postgres-pgvector/index.ts"),
+      src: path2.join(selection.registryRoot, "store/prisma/index.ts"),
       dest: path2.join(installBaseAbs, "store/prisma/index.ts")
     }, {
-      src: path2.join(selection.registryRoot, "store/prisma-postgres-pgvector/store.ts"),
+      src: path2.join(selection.registryRoot, "store/prisma/store.ts"),
       dest: path2.join(installBaseAbs, "store/prisma/store.ts")
     });
   }
@@ -505,7 +530,8 @@ async function copyRegistryFiles(selection) {
       }
     }
     const raw = await readText(mapping.src);
-    const content = mapping.transform ? mapping.transform(raw) : raw;
+    const transformed = mapping.transform ? mapping.transform(raw) : raw;
+    const content = rewriteRegistryAliasImports(transformed, selection.aliasBase);
     await writeText(mapping.dest, content);
   }
 }
@@ -543,7 +569,8 @@ async function copyConnectorFiles(selection) {
       }
     }
     const raw = await readText(src);
-    await writeText(dest, raw);
+    const content = rewriteRegistryAliasImports(raw, selection.aliasBase);
+    await writeText(dest, content);
   }
 }
 async function copyExtractorFiles(selection) {
@@ -569,7 +596,8 @@ async function copyExtractorFiles(selection) {
       return false;
     try {
       const [srcRaw, destRaw] = await Promise.all([readText(src), readText(dest)]);
-      if (srcRaw === destRaw)
+      const nextSrc = rewriteRegistryAliasImports(srcRaw, selection.aliasBase);
+      if (nextSrc === destRaw)
         return false;
     } catch {}
     const answer = await confirm({
@@ -591,7 +619,8 @@ async function copyExtractorFiles(selection) {
     if (!await shouldWrite(src, dest))
       continue;
     const raw = await readText(src);
-    await writeText(dest, raw);
+    const content = rewriteRegistryAliasImports(raw, selection.aliasBase);
+    await writeText(dest, content);
   }
   for (const src of sharedFiles) {
     if (!await exists(src)) {
@@ -602,7 +631,8 @@ async function copyExtractorFiles(selection) {
     if (!await shouldWrite(src, dest))
       continue;
     const raw = await readText(src);
-    await writeText(dest, raw);
+    const content = rewriteRegistryAliasImports(raw, selection.aliasBase);
+    await writeText(dest, content);
   }
 }
 async function copyBatteryFiles(selection) {
@@ -614,6 +644,14 @@ async function copyBatteryFiles(selection) {
     throw new Error(`Unknown battery registry: ${path2.relative(selection.registryRoot, batteryRegistryAbs)}`);
   }
   const batteryFiles = await listFilesRecursive(batteryRegistryAbs);
+  const filteredBatteryFiles = batteryFiles.filter((abs) => {
+    if (batteryRegistryDir === "debug") {
+      const rel = path2.relative(batteryRegistryAbs, abs).replace(/\\/g, "/");
+      if (rel === "tui" || rel.startsWith("tui/"))
+        return false;
+    }
+    return true;
+  });
   const destRootAbs = path2.join(installBaseAbs, batteryRegistryDir);
   const nonInteractive = Boolean(selection.yes) || !process.stdin.isTTY;
   const overwritePolicy = selection.overwrite ?? "skip";
@@ -626,7 +664,8 @@ async function copyBatteryFiles(selection) {
       return false;
     try {
       const [srcRaw, destRaw] = await Promise.all([readText(src), readText(dest)]);
-      if (srcRaw === destRaw)
+      const nextSrc = rewriteRegistryAliasImports(srcRaw, selection.aliasBase);
+      if (nextSrc === destRaw)
         return false;
     } catch {}
     const answer = await confirm({
@@ -639,7 +678,7 @@ async function copyBatteryFiles(selection) {
     }
     return Boolean(answer);
   };
-  for (const src of batteryFiles) {
+  for (const src of filteredBatteryFiles) {
     if (!await exists(src)) {
       throw new Error(`Registry file missing: ${src}`);
     }
@@ -648,7 +687,8 @@ async function copyBatteryFiles(selection) {
     if (!await shouldWrite(src, dest))
       continue;
     const raw = await readText(src);
-    await writeText(dest, raw);
+    const content = rewriteRegistryAliasImports(raw, selection.aliasBase);
+    await writeText(dest, content);
   }
 }
 
@@ -887,6 +927,9 @@ function depsForBattery(battery) {
     deps["@ai-sdk/cohere"] = "^3.0.1";
   }
   if (battery === "eval") {}
+  if (battery === "debug") {
+    deps["ws"] = "^8.18.0";
+  }
   return { deps, devDeps };
 }
 function installCmd(pm) {
@@ -1038,7 +1081,7 @@ var EVAL_PACKAGE_JSON_SCRIPTS = {
   "unrag:eval:ci": `bun run scripts/unrag-eval.ts -- --dataset .unrag/eval/datasets/sample.json --ci`
 };
 function renderEvalRunnerScript(opts) {
-  const installImportBase = `../${opts.installDir.replace(/\\/g, "/")}`;
+  const aliasBase = String(opts.aliasBase ?? "").trim() || "@unrag";
   return `/**
  * Unrag eval runner entrypoint (generated).
  *
@@ -1048,7 +1091,7 @@ function renderEvalRunnerScript(opts) {
 import path from "node:path";
 import { access, readFile } from "node:fs/promises";
 
-import { createUnragEngine } from "../unrag.config";
+import { createUnragEngine } from "${aliasBase}/config";
 import {
   runEval,
   readEvalReportFromFile,
@@ -1060,7 +1103,7 @@ import {
   type EvalMode,
   type EvalThresholds,
   type EvalCleanupPolicy,
-} from "${installImportBase}/eval";
+} from "${aliasBase}/eval";
 
 type CliArgs = {
   dataset?: string;
@@ -1565,6 +1608,7 @@ async function initCommand(args) {
         projectRoot: root,
         registryRoot,
         installDir,
+        aliasBase,
         extractor,
         yes: nonInteractive,
         overwrite: overwritePolicy
@@ -1595,6 +1639,7 @@ async function initCommand(args) {
         projectRoot: root,
         registryRoot,
         installDir,
+        aliasBase,
         connector,
         yes: nonInteractive,
         overwrite: overwritePolicy
@@ -1622,6 +1667,7 @@ async function initCommand(args) {
         projectRoot: root,
         registryRoot,
         installDir,
+        aliasBase,
         battery,
         yes: nonInteractive,
         overwrite: overwritePolicy
@@ -1674,7 +1720,7 @@ async function initCommand(args) {
 `);
     await writeIfMissing(evalConfigAbs, JSON.stringify(EVAL_CONFIG_DEFAULT, null, 2) + `
 `);
-    await writeIfMissing(scriptAbs, renderEvalRunnerScript({ installDir }));
+    await writeIfMissing(scriptAbs, renderEvalRunnerScript({ aliasBase }));
     const pkg2 = await readPackageJson(root);
     const existingScripts = pkg2.scripts ?? {};
     const toAdd = {};
@@ -1690,8 +1736,11 @@ async function initCommand(args) {
   }
   const pm = await detectPackageManager(root);
   const installLine = merged.changes.length === 0 ? "Dependencies already satisfied." : noInstall ? `Next: run \`${installCmd(pm)}\`` : "Dependencies installed.";
-  const isNext = Boolean((merged.pkg.dependencies ?? {})["next"]) || Boolean((merged.pkg.devDependencies ?? {})["next"]);
-  const tsconfigResult = isNext ? await patchTsconfigPaths({ projectRoot: root, installDir, aliasBase }) : { changed: false };
+  const tsconfigResult = await patchTsconfigPaths({
+    projectRoot: root,
+    installDir,
+    aliasBase
+  });
   const envHint = (() => {
     if (embeddingProvider === "ai") {
       return [
@@ -1801,7 +1850,7 @@ async function initCommand(args) {
     `- Embedding provider: ${embeddingProvider}`,
     richMediaEnabled ? `- Extractors: ${selectedExtractors.length > 0 ? selectedExtractors.join(", ") : "none"}` : "",
     richMediaEnabled ? `  Tip: you can tweak extractors + assetProcessing flags in unrag.config.ts later.` : `  Tip: re-run \`unrag init --rich-media\` (or edit unrag.config.ts) to enable rich media later.`,
-    isNext ? tsconfigResult.changed ? `- Next.js: updated ${tsconfigResult.file} (added aliases)` : `- Next.js: no tsconfig changes needed` : `- Next.js: not detected`,
+    tsconfigResult.changed ? `- TypeScript: updated ${tsconfigResult.file} (added aliases)` : `- TypeScript: no tsconfig changes needed`,
     "",
     merged.changes.length > 0 ? `Added deps: ${merged.changes.map((c) => c.name).join(", ")}` : "Added deps: none",
     installLine,
@@ -1983,6 +2032,7 @@ Available batteries: ${Array.from(availableBatteries).join(", ")}`);
       projectRoot: root,
       registryRoot,
       installDir: config.installDir,
+      aliasBase: config.aliasBase ?? "@unrag",
       battery,
       yes: nonInteractive
     });
@@ -2038,7 +2088,7 @@ Available batteries: ${Array.from(availableBatteries).join(", ")}`);
         cleanup: "none",
         ingest: true
       };
-      const installImportBase = `../${config.installDir.replace(/\\/g, "/")}`;
+      const aliasBase = String(config.aliasBase ?? "").trim() || "@unrag";
       const script = `/**
  * Unrag eval runner entrypoint (generated).
  *
@@ -2048,7 +2098,7 @@ Available batteries: ${Array.from(availableBatteries).join(", ")}`);
 import path from "node:path";
 import { access, readFile } from "node:fs/promises";
 
-import { createUnragEngine } from "../unrag.config";
+import { createUnragEngine } from "${aliasBase}/config";
 import {
   runEval,
   readEvalReportFromFile,
@@ -2060,7 +2110,7 @@ import {
   type EvalMode,
   type EvalThresholds,
   type EvalCleanupPolicy,
-} from "${installImportBase}/eval";
+} from "${aliasBase}/eval";
 
 type CliArgs = {
   dataset?: string;
@@ -2326,6 +2376,50 @@ main().catch((err) => {
         "  bun run unrag:eval",
         "  bun run unrag:eval:ci"
       ].filter(Boolean).join(`
+`));
+      return;
+    }
+    if (battery === "debug") {
+      const configAbs = path7.join(root, ".unrag/debug/config.json");
+      const debugConfig = {
+        port: 3847,
+        host: "localhost"
+      };
+      if (await shouldWriteFile(configAbs, root, nonInteractive)) {
+        await writeTextFile(configAbs, JSON.stringify(debugConfig, null, 2) + `
+`);
+      }
+      const scriptsToAdd = {
+        "unrag:debug": "bunx unrag debug"
+      };
+      const scriptsResult = await addPackageJsonScripts({
+        projectRoot: root,
+        pkg,
+        scripts: scriptsToAdd,
+        nonInteractive
+      });
+      outro2([
+        `Installed battery: ${battery}.`,
+        "",
+        `- Code: ${path7.join(config.installDir, "debug")}`,
+        `- Config: .unrag/debug/config.json`,
+        "",
+        merged2.changes.length > 0 ? `Added deps: ${merged2.changes.map((c) => c.name).join(", ")}` : "Added deps: none",
+        merged2.changes.length > 0 && !noInstall ? "Dependencies installed." : merged2.changes.length > 0 && noInstall ? "Dependencies not installed (skipped)." : "",
+        scriptsResult.added.length > 0 ? `Added scripts: ${scriptsResult.added.join(", ")}` : "Added scripts: none",
+        scriptsResult.kept.length > 0 ? `Kept existing scripts: ${scriptsResult.kept.join(", ")}` : "",
+        "",
+        "Usage:",
+        "  1. Set UNRAG_DEBUG=true in your app's environment",
+        "  2. Run your app (debug server auto-starts on port 3847)",
+        "  3. In another terminal: bun run unrag:debug",
+        "",
+        "The debug panel will connect to your app and show live events for:",
+        "  - Ingest operations (chunking, embedding, storage)",
+        "  - Retrieve operations (embedding, database queries)",
+        "  - Rerank operations (scoring, reordering)",
+        "  - Delete operations"
+      ].filter(Boolean).join(`
 `));
       return;
     }
@@ -2369,6 +2463,7 @@ Available connectors: ${Array.from(availableConnectors).join(", ")}`);
       projectRoot: root,
       registryRoot,
       installDir: config.installDir,
+      aliasBase: config.aliasBase ?? "@unrag",
       connector,
       yes: nonInteractive
     });
@@ -2406,6 +2501,7 @@ Available extractors: ${Array.from(availableExtractors).join(", ")}`);
     projectRoot: root,
     registryRoot,
     installDir: config.installDir,
+    aliasBase: config.aliasBase ?? "@unrag",
     extractor,
     yes: nonInteractive
   });
@@ -5042,6 +5138,103 @@ async function doctorCommand(args) {
   }
 }
 
+// cli/commands/debug.ts
+import { outro as outro5 } from "@clack/prompts";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+function parseDebugArgs(args) {
+  const out = {};
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--url") {
+      out.url = args[++i];
+    } else if (arg === "--port" || arg === "-p") {
+      const portStr = args[++i] ?? "";
+      out.port = parseInt(portStr, 10);
+      if (isNaN(out.port)) {
+        throw new Error(`Invalid port: ${portStr}`);
+      }
+    } else if (arg === "--help" || arg === "-h") {
+      out.help = true;
+    }
+  }
+  return out;
+}
+function renderDebugHelp() {
+  return [
+    "unrag debug — Real-time TUI debugger for RAG operations",
+    "",
+    "Usage:",
+    "  bunx unrag debug [options]",
+    "",
+    "Options:",
+    "  --url <ws://...>    WebSocket URL (default: ws://localhost:3847)",
+    "  --port, -p <num>    Port to connect to (default: 3847)",
+    "  -h, --help          Show this help",
+    "",
+    "Setup:",
+    "  1. Set UNRAG_DEBUG=true in your app's environment",
+    "  2. Start your app (debug server auto-starts on port 3847)",
+    "  3. Run: bunx unrag debug",
+    "",
+    "Keyboard shortcuts (in TUI):",
+    "  Shift+Tab     Cycle tabs",
+    "  1-8           Jump to specific tab",
+    "  j/k or arrows Navigate event list",
+    "  Enter/e       View event details",
+    "  a/i/r/k/d     Filter events by type",
+    "  ?/h           Show help",
+    "  q             Quit",
+    "",
+    "Environment variables (in your app):",
+    "  UNRAG_DEBUG=true         Enable debug mode",
+    "  UNRAG_DEBUG_PORT=3847    Debug server port (optional)",
+    ""
+  ].join(`
+`);
+}
+function getTuiModulePath() {
+  const __filename4 = fileURLToPath3(import.meta.url);
+  const __dirname4 = dirname(__filename4);
+  const dev = process.env.UNRAG_DEBUG_TUI_DEV === "1";
+  const devPath = join(__dirname4, "..", "debug-tui", "index.dev.js");
+  const prodPath = join(__dirname4, "..", "debug-tui", "index.js");
+  if (dev) {
+    if (existsSync(devPath))
+      return devPath;
+    throw new Error("UNRAG_DEBUG_TUI_DEV=1 was set but dev TUI bundle was not found. Rebuild unrag with: `bun run build:debug-tui:dev`");
+  }
+  return prodPath;
+}
+async function debugCommand(args) {
+  try {
+    const parsed = parseDebugArgs(args);
+    if (parsed.help) {
+      outro5(renderDebugHelp());
+      return;
+    }
+    let url = parsed.url;
+    if (!url && parsed.port) {
+      url = `ws://localhost:${parsed.port}`;
+    }
+    url = url ?? "ws://localhost:3847";
+    console.log(`Connecting to debug server at ${url}...`);
+    console.log(`Press ? for help, q to quit
+`);
+    const tuiPath = getTuiModulePath();
+    const { runDebugTui } = await import(tuiPath);
+    await runDebugTui({ url });
+  } catch (error) {
+    if (error instanceof Error) {
+      outro5(`Error: ${error.message}`);
+    } else {
+      outro5(`Error: ${String(error)}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
 // cli/run.ts
 function renderHelp() {
   return [
@@ -5055,9 +5248,10 @@ function renderHelp() {
     "  init                Install core files (config + store adapter templates)",
     "  add <connector>     Install a connector (notion, google-drive)",
     "  add extractor <n>   Install an extractor (pdf-llm, image-ocr, etc.)",
-    "  add battery <name>  Install a battery module (reranker, etc.)",
+    "  add battery <name>  Install a battery module (reranker, eval, debug)",
     "  doctor              Validate installation and configuration",
     "  doctor setup        Generate project-specific doctor config and scripts",
+    "  debug               Open real-time debug TUI (requires UNRAG_DEBUG=true in app)",
     "  help                Show this help",
     "",
     "Global options:",
@@ -5113,7 +5307,7 @@ async function run(argv) {
   const [, , command, ...rest] = argv;
   intro("unrag");
   if (!command || command === "help" || command === "--help" || command === "-h") {
-    outro5(renderHelp());
+    outro6(renderHelp());
     return;
   }
   if (command === "init") {
@@ -5128,7 +5322,11 @@ async function run(argv) {
     await doctorCommand(rest);
     return;
   }
-  outro5([`Unknown command: ${command}`, "", renderHelp()].join(`
+  if (command === "debug") {
+    await debugCommand(rest);
+    return;
+  }
+  outro6([`Unknown command: ${command}`, "", renderHelp()].join(`
 `));
   process.exitCode = 1;
 }