mcp-local-rag 0.14.2 → 0.15.1

package/README.md

@@ -383,6 +383,7 @@ The MCP server is configured by environment variables only — pass them through
 | `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100MB) | Maximum file size in bytes |
 | `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Minimum chunk length in characters (1–10000) |
 | `RAG_DEVICE` | — | `cpu` | Execution device. Passed straight to ONNX Runtime. See the [Transformers.js device source code](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/utils/devices.js) for the live list of supported backend names. If initialization fails, the server throws an error. |
+| `RAG_DTYPE` | — | `fp32` | Embedding quantization dtype. Opt-in and passed straight through; accepts any dtype the chosen model provides (`fp32`, `fp16`, `q8`, `int8`, …). If the model lacks the requested variant, the server throws an error naming the dtypes it does provide. Changing `RAG_DEVICE`/`RAG_DTYPE` changes the embedding space — re-ingest existing data. |
 
 **Model choice tips:**
 - Multilingual docs → e.g., `onnx-community/embeddinggemma-300m-ONNX` (100+ languages)
@@ -607,6 +608,9 @@ Yes, but you must delete your database and re-ingest all documents. Different mo
 **GPU acceleration?**
 Opt-in via `RAG_DEVICE`. Devices are passed straight to ONNX Runtime. GPU support is highly dependent on your system, Node.js version, and the underlying ONNX backend. See the [Transformers.js device source code](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/utils/devices.js) for the live list of supported backend names. If the requested device fails to initialize, the server throws an error — set `RAG_DEVICE=cpu` to revert.
 
+**Can I change the embedding precision (dtype)?**
+Opt-in via `RAG_DTYPE` (default `fp32`); accepted values are in the env-var table above. A recognized dtype the model lacks errors and lists the available ones; an unrecognized value (a typo) silently falls back to `fp32`. Changing `RAG_DEVICE`/`RAG_DTYPE` changes the embedding space — delete `DB_PATH` and re-ingest.
+
 **Multi-user support?**
 No. Designed for single-user, local access. Multi-user would require authentication/access control.
 

package/dist/cli/common.d.ts

@@ -2,6 +2,20 @@ import { Embedder } from '../embedder/index.js';
 import { type BaseDirsConfig, type BaseDirsConfigWarning } from '../utils/base-dirs.js';
 import { VectorStore } from '../vectordb/index.js';
 import { type ResolvedGlobalConfig } from './options.js';
+/**
+ * Render an unknown caught value for a CLI failure site: every link of the
+ * `.cause` chain (via {@link getCauseChain}) followed by its stack, joined so
+ * the operator sees the full diagnostic. Deeper links are prefixed
+ * `Caused by: `; the outermost link is not.
+ *
+ * The CLI is operator-facing, so — unlike the MCP client boundary, which never
+ * leaks the cause chain — the full chain IS printed (Contract-Delta CLI row:
+ * `message` → `message` + cause chain on stderr). Callers keep their own
+ * operation prefix and exit-code policy; this function only produces the
+ * rendered reason. Single source for the CLI catch-block error-rendering
+ * pattern, replacing the former message-only renderer.
+ */
+export declare function formatCliError(error: unknown): string;
 /**
  * Create an uninitialized VectorStore from resolved global config.
  * Callers are responsible for calling initialize() before use.

package/dist/cli/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/cli/common.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC/C,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAG3B,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,KAAK,oBAAoB,EAA+B,MAAM,cAAc,CAAA;AAErF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,WAAW,CAK3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,QAAQ,CAOrE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAqDjG"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/cli/common.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC/C,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAG3B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,KAAK,oBAAoB,EAA6C,MAAM,cAAc,CAAA;AAEnG;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQrD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,WAAW,CAK3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,QAAQ,CAerE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAqDjG"}

package/dist/cli/common.js

@@ -2,9 +2,32 @@
 // plus base-directory resolution shared by every subcommand that scans files.
 import { Embedder } from '../embedder/index.js';
 import { parseBaseDirsEnv, resolveBaseDirs, } from '../utils/base-dirs.js';
+import { getCauseChain } from '../utils/errors.js';
 import { checkSensitivePath } from '../utils/sensitive-path.js';
 import { VectorStore } from '../vectordb/index.js';
-import { resolveDevice, validatePath } from './options.js';
+import { resolveDevice, resolveDtype, validatePath } from './options.js';
+/**
+ * Render an unknown caught value for a CLI failure site: every link of the
+ * `.cause` chain (via {@link getCauseChain}) followed by its stack, joined so
+ * the operator sees the full diagnostic. Deeper links are prefixed
+ * `Caused by: `; the outermost link is not.
+ *
+ * The CLI is operator-facing, so — unlike the MCP client boundary, which never
+ * leaks the cause chain — the full chain IS printed (Contract-Delta CLI row:
+ * `message` → `message` + cause chain on stderr). Callers keep their own
+ * operation prefix and exit-code policy; this function only produces the
+ * rendered reason. Single source for the CLI catch-block error-rendering
+ * pattern, replacing the former message-only renderer.
+ */
+export function formatCliError(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    return getCauseChain(err)
+        .map((link, index) => {
+        const header = index === 0 ? '' : 'Caused by: ';
+        return `${header}${link.stack || `${link.name}: ${link.message}`}`;
+    })
+        .join('\n');
+}
 /**
  * Create an uninitialized VectorStore from resolved global config.
  * Callers are responsible for calling initialize() before use.
@@ -20,12 +43,20 @@ export function createVectorStore(config) {
  * Callers are responsible for managing the Embedder lifecycle.
  */
 export function createEmbedder(config) {
-    return new Embedder({
+    const embedderConfig = {
         modelPath: config.modelName,
         batchSize: 16,
         cacheDir: config.cacheDir,
         device: resolveDevice(process.env['RAG_DEVICE']),
-    });
+    };
+    // Set dtype only when RAG_DTYPE resolves to a defined value, mirroring the
+    // server path — an unset RAG_DTYPE leaves config.dtype undefined so the
+    // embedder applies its fp32 default.
+    const dtype = resolveDtype(process.env['RAG_DTYPE']);
+    if (dtype !== undefined) {
+        embedderConfig.dtype = dtype;
+    }
+    return new Embedder(embedderConfig);
 }
 /**
  * Resolve effective base directories for a CLI subcommand using the shared

package/dist/cli/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/cli/common.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/cli/common.ts"],"names":[],"mappings":"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"}

package/dist/cli/delete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/cli/delete.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAkFjD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiGhG"}
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/cli/delete.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAkFjD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGhG"}

package/dist/cli/delete.js

@@ -2,7 +2,7 @@
 import { unlink } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { generateMetaJsonPath, generateRawDataPath, isPathInRawDataDirLexical, } from '../utils/raw-data-utils.js';
-import { createVectorStore } from './common.js';
+import { createVectorStore, formatCliError } from './common.js';
 import { resolveGlobalConfig, validatePath } from './options.js';
 // ============================================
 // Help
@@ -108,7 +108,8 @@ export async function runDelete(args, globalOptions = {}) {
             targetPath = generateRawDataPath(globalConfig.dbPath, parsed.source, 'markdown');
         }
         else {
-            // Use provided file path, resolve to absolute
+            // DB key is the resolve()'d ingest path, so look up by resolve() (never
+            // realpath) — realpath stays in validatePath/validateFilePath.
             targetPath = resolve(parsed.filePath);
             // Validate path (reject sensitive system directories)
             const pathError = validatePath(targetPath, '<file-path>');
@@ -156,7 +157,7 @@ export async function runDelete(args, globalOptions = {}) {
         process.stdout.write(JSON.stringify(result));
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
+        const reason = formatCliError(error);
         console.error(`Error: ${reason}`);
         process.exit(1);
     }

package/dist/cli/delete.js.map

@@ -1 +1 @@
-{"version":3,"file":"delete.js","sourceRoot":"","sources":["../../src/cli/delete.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"delete.js","sourceRoot":"","sources":["../../src/cli/delete.ts"],"names":[],"mappings":"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"}

package/dist/cli/file-collection.d.ts

@@ -0,0 +1,2 @@
+export declare function collectFiles(targetPath: string, baseDirs: readonly string[], excludePaths: string[]): Promise<string[]>;
+//# sourceMappingURL=file-collection.d.ts.map

package/dist/cli/file-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-collection.d.ts","sourceRoot":"","sources":["../../src/cli/file-collection.ts"],"names":[],"mappings":"AAeA,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CA0DnB"}

package/dist/cli/file-collection.js

@@ -0,0 +1,53 @@
+// CLI ingest file collection.
+//
+// Resolves the positional ingest path into the concrete list of supported
+// files to ingest. Single-file mode validates the extension; directory mode
+// confirms the path is inside a configured root and delegates the bounded
+// BFS walk to `bfsCollectSupportedFiles`. Out-of-root directory targets exit
+// the process (preserved from the original inline implementation).
+import { realpath, stat } from 'node:fs/promises';
+import { extname, resolve, sep } from 'node:path';
+import { SUPPORTED_EXTENSIONS } from '../parser/index.js';
+import { MAX_SCAN_DEPTH } from '../utils/limits.js';
+import { bfsCollectSupportedFiles } from '../utils/scan.js';
+export async function collectFiles(targetPath, baseDirs, excludePaths) {
+    const resolved = resolve(targetPath);
+    const info = await stat(resolved);
+    if (info.isFile()) {
+        const ext = extname(resolved).toLowerCase();
+        if (!SUPPORTED_EXTENSIONS.has(ext)) {
+            console.error(`Unsupported file extension: ${ext} (supported: ${[...SUPPORTED_EXTENSIONS].join(', ')})`);
+            return [];
+        }
+        // Store the resolve()'d path (the DB key), not realpath — path policy:
+        // realpath only at the security boundary, resolve() everywhere user-facing.
+        return [resolved];
+    }
+    if (info.isDirectory()) {
+        // realpath both sides so a symlinked positional path still matches a
+        // root whose realpath agrees. baseDirs from resolveCliBaseDirsOrExit
+        // are already realpath-normalized with a trailing sep.
+        const realResolved = await realpath(resolved);
+        const realResolvedWithSep = realResolved.endsWith(sep) ? realResolved : realResolved + sep;
+        const insideAnyRoot = baseDirs.some((root) => realResolvedWithSep === root || realResolvedWithSep.startsWith(root));
+        if (!insideAnyRoot) {
+            console.error(`Error: ${targetPath} is not under any configured base directory. ` +
+                `Allowed roots: ${baseDirs.join(', ')}. ` +
+                `Provide a path inside one of the configured roots, or set BASE_DIRS / --base-dir to include the desired tree.`);
+            process.exit(1);
+        }
+        // `realResolved` is used ONLY for the in-root containment check (security).
+        // The walk uses the resolve()'d `resolved` so the stored DB keys match what
+        // `list`/`delete`/`read_chunk_neighbors` use (resolve(), not realpath).
+        const { files: collected, unreadableDirs, depthLimited, } = await bfsCollectSupportedFiles(resolved, excludePaths);
+        for (const { dirPath } of unreadableDirs) {
+            console.error(`Warning: cannot read directory: ${dirPath}`);
+        }
+        if (depthLimited) {
+            console.error(`Warning: some directories were skipped because they exceed the maximum depth (${MAX_SCAN_DEPTH})`);
+        }
+        return [...new Set(collected)].sort();
+    }
+    return [];
+}
+//# sourceMappingURL=file-collection.js.map

package/dist/cli/file-collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-collection.js","sourceRoot":"","sources":["../../src/cli/file-collection.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,mEAAmE;AAEnE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAkB,EAClB,QAA2B,EAC3B,YAAsB;IAEtB,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACpC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAA;IAEjC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAA;QAC3C,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CACX,+BAA+B,GAAG,gBAAgB,CAAC,GAAG,oBAAoB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1F,CAAA;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QACD,uEAAuE;QACvE,4EAA4E;QAC5E,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnB,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACvB,qEAAqE;QACrE,qEAAqE;QACrE,uDAAuD;QACvD,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAC7C,MAAM,mBAAmB,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,GAAG,GAAG,CAAA;QAC1F,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CACjC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,KAAK,IAAI,IAAI,mBAAmB,CAAC,UAAU,CAAC,IAAI,CAAC,CAC/E,CAAA;QACD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CACX,UAAU,UAAU,+CAA+C;gBACjE,kBAAkB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBACzC,+GAA+G,CAClH,CAAA;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QAED,4EAA4E;QAC5E,4EAA4E;QAC5E,wEAAwE;QACxE,MAAM,EACJ,KAAK,EAAE,SAAS,EAChB,cAAc,EACd,YAAY,GACb,GAAG,MAAM,wBAAwB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;QAE1D,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,cAAc,EAAE,CAAC;YACzC,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,EAAE,CAAC,CAAA;QAC7D,CAAC;QAED,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CACX,iFAAiF,cAAc,GAAG,CACnG,CAAA;QACH,CAAC;QAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/cli/ingest.d.ts

@@ -86,12 +86,10 @@ export type IngestSingleFileOptions = {
  * visual-enrichment path: `parsePdfPages` + VLM captioning (`pdf-visual`
  * orchestrator) + joined-text chunking. `pdf-visual` is loaded via dynamic
  * `await import('../pdf-visual/index.js')` so the default (non-visual) path
- * never pulls the VLM module into the bundle (NFR-1 dynamic-import discipline,
- * verified by AC-001 Proxy sentinel in T4.6).
+ * never pulls the VLM module into the bundle.
  *
- * Non-visual, non-PDF, and `visual: true` + non-PDF (silently falls through
- * to the default branch — AC-006) paths are byte-identical to the post-T0.3
- * state and never load `pdf-visual`.
+ * Non-visual, non-PDF, and `visual: true` + non-PDF paths all use the default
+ * text-only branch and never load `pdf-visual`.
  */
 export declare function ingestSingleFile(filePath: string, parser: DocumentParser, chunker: SemanticChunker, embedder: Embedder, vectorStore: VectorStore, options?: IngestSingleFileOptions): Promise<number>;
 /**

package/dist/cli/ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/cli/ingest.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,cAAc,EAAwB,MAAM,oBAAoB,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAoBvE,UAAU,YAAY;IACpB,QAAQ,EAAE,cAAc,CAAA;IACxB,gBAAgB,EAAE,qBAAqB,EAAE,CAAA;IACzC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD,UAAU,gBAAgB;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CAC3C;AAED,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,OAAO,EAAE,gBAAgB,CAAA;IACzB,IAAI,EAAE,OAAO,CAAA;CACd;AAmCD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA+FpD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,oBAAoB,EAClC,aAAa,GAAE,gBAAqB,GACnC,OAAO,CAAC,YAAY,CAAC,CAyDvB;AAmHD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,GAC9B;IACE,MAAM,EAAE,IAAI,CAAA;IACZ,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAAA;AAEL;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,CAAC,CAuGjB;AAMD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0IhG"}
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/cli/ingest.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAQvD,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAevE,UAAU,YAAY;IACpB,QAAQ,EAAE,cAAc,CAAA;IACxB,gBAAgB,EAAE,qBAAqB,EAAE,CAAA;IACzC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD,UAAU,gBAAgB;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CAC3C;AAED,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,OAAO,EAAE,gBAAgB,CAAA;IACzB,IAAI,EAAE,OAAO,CAAA;CACd;AAmCD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAmFpD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,oBAAoB,EAClC,aAAa,GAAE,gBAAqB,GACnC,OAAO,CAAC,YAAY,CAAC,CAyDvB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,GAC9B;IACE,MAAM,EAAE,IAAI,CAAA;IACZ,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAAA;AAEL;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,CAAC,CA2EjB;AAMD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuIhG"}

package/dist/cli/ingest.js

@@ -1,22 +1,19 @@
 // CLI ingest subcommand — bulk file ingestion with single optimize() at end
-import { randomUUID } from 'node:crypto';
-import { opendir, realpath, stat } from 'node:fs/promises';
-import { basename, extname, join, resolve, sep } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
 import { SemanticChunker } from '../chunker/index.js';
-import { buildChunksAndEmbeddings } from '../ingest/compute.js';
+import { buildChunksAndEmbeddings, buildVectorChunks } from '../ingest/compute.js';
 import { prepareVisualPdfChunks } from '../ingest/visual.js';
-import { DocumentParser, SUPPORTED_EXTENSIONS } from '../parser/index.js';
-import { createEmbedder, createVectorStore, resolveCliBaseDirsOrExit } from './common.js';
-import { consumeBaseDirArg, resolveDevice, resolveGlobalConfig, validateChunkMinLength, validateMaxFileSize, validatePath, } from './options.js';
-// ============================================
-// Constants
-// ============================================
-const MAX_DEPTH = 10;
+import { DocumentParser } from '../parser/index.js';
+import { DEFAULT_MAX_FILE_SIZE } from '../utils/limits.js';
+import { createEmbedder, createVectorStore, formatCliError, resolveCliBaseDirsOrExit, } from './common.js';
+import { collectFiles } from './file-collection.js';
+import { consumeBaseDirArg, requireFlagValue, resolveDevice, resolveGlobalConfig, validateChunkMinLength, validateMaxFileSize, validatePath, } from './options.js';
 // ============================================
 // Defaults
 // ============================================
 const INGEST_DEFAULTS = {
-    maxFileSize: 104857600,
+    maxFileSize: DEFAULT_MAX_FILE_SIZE,
 };
 // ============================================
 // Help
@@ -71,31 +68,23 @@ export function parseArgs(args) {
                 break;
             }
             case '--max-file-size': {
-                const raw = args[++i];
-                if (raw === undefined || raw.startsWith('-')) {
-                    console.error('Missing value for --max-file-size');
-                    process.exit(1);
-                }
+                const raw = requireFlagValue(args, i, '--max-file-size');
                 if (!/^\d+$/.test(raw)) {
                     console.error(`Invalid value for --max-file-size: "${raw.slice(0, 100)}"`);
                     process.exit(1);
                 }
                 options.maxFileSize = Number.parseInt(raw, 10);
-                i++;
+                i += 2;
                 break;
             }
             case '--chunk-min-length': {
-                const raw = args[++i];
-                if (raw === undefined || raw.startsWith('-')) {
-                    console.error('Missing value for --chunk-min-length');
-                    process.exit(1);
-                }
+                const raw = requireFlagValue(args, i, '--chunk-min-length');
                 if (!/^\d+$/.test(raw)) {
                     console.error(`Invalid value for --chunk-min-length: "${raw.slice(0, 100)}"`);
                     process.exit(1);
                 }
                 options.chunkMinLength = Number.parseInt(raw, 10);
-                i++;
+                i += 2;
                 break;
             }
             case '--visual':
@@ -104,17 +93,13 @@ export function parseArgs(args) {
                 i++;
                 break;
             case '--visual-quality': {
-                const value = args[++i];
-                if (value === undefined || value.startsWith('-')) {
-                    console.error('Missing value for --visual-quality');
-                    process.exit(1);
-                }
+                const value = requireFlagValue(args, i, '--visual-quality');
                 if (value !== 'fast' && value !== 'quality') {
                     console.error(`Invalid value for --visual-quality: "${value.slice(0, 100)}". Expected "fast" or "quality".`);
                     process.exit(1);
                 }
                 options.visualQuality = value;
-                i++;
+                i += 2;
                 break;
             }
             default:
@@ -202,86 +187,6 @@ export async function resolveConfig(globalConfig, ingestOptions = {}) {
     }
     return resolved;
 }
-// ============================================
-// File Collection
-// ============================================
-/**
- * BFS-walk a single directory up to {@link MAX_DEPTH} levels, returning every
- * supported file path under it. Skips symlinks, permission errors, and excluded
- * directories. Reports a single shared `depthLimited` flag via an out-param so
- * the caller can emit one combined warning across multiple roots instead of
- * one per root.
- */
-async function walkDirectory(rootPath, excludePaths, state) {
-    const files = [];
-    const queue = [{ dirPath: rootPath, depth: 0 }];
-    while (queue.length > 0) {
-        const { dirPath, depth } = queue.shift();
-        if (depth >= MAX_DEPTH) {
-            state.depthLimited = true;
-            continue;
-        }
-        let dir;
-        try {
-            dir = await opendir(dirPath);
-        }
-        catch {
-            console.error(`Warning: cannot read directory: ${dirPath}`);
-            continue;
-        }
-        for await (const entry of dir) {
-            const fullPath = join(dirPath, entry.name);
-            // `join(dirPath, entry.name)` always produces a path under `dirPath`,
-            // which itself stays under `rootPath` because the BFS only enqueues
-            // descendants of `rootPath`. We therefore do not need a per-entry
-            // `startsWith(rootPath)` re-check here.
-            if (entry.isSymbolicLink())
-                continue;
-            if (excludePaths.some((ep) => fullPath.startsWith(ep)))
-                continue;
-            if (entry.isDirectory()) {
-                queue.push({ dirPath: fullPath, depth: depth + 1 });
-            }
-            else if (entry.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
-                files.push(fullPath);
-            }
-        }
-    }
-    return files;
-}
-async function collectFiles(targetPath, baseDirs, excludePaths) {
-    const resolved = resolve(targetPath);
-    const info = await stat(resolved);
-    if (info.isFile()) {
-        const ext = extname(resolved).toLowerCase();
-        if (!SUPPORTED_EXTENSIONS.has(ext)) {
-            console.error(`Unsupported file extension: ${ext} (supported: ${[...SUPPORTED_EXTENSIONS].join(', ')})`);
-            return [];
-        }
-        return [resolved];
-    }
-    if (info.isDirectory()) {
-        // realpath both sides so a symlinked positional path still matches a
-        // root whose realpath agrees. baseDirs from resolveCliBaseDirsOrExit
-        // are already realpath-normalized with a trailing sep.
-        const realResolved = await realpath(resolved);
-        const realResolvedWithSep = realResolved.endsWith(sep) ? realResolved : realResolved + sep;
-        const insideAnyRoot = baseDirs.some((root) => realResolvedWithSep === root || realResolvedWithSep.startsWith(root));
-        if (!insideAnyRoot) {
-            console.error(`Error: ${targetPath} is not under any configured base directory. ` +
-                `Allowed roots: ${baseDirs.join(', ')}. ` +
-                `Provide a path inside one of the configured roots, or set BASE_DIRS / --base-dir to include the desired tree.`);
-            process.exit(1);
-        }
-        const state = { depthLimited: false };
-        const collected = await walkDirectory(resolved, excludePaths, state);
-        if (state.depthLimited) {
-            console.error(`Warning: some directories were skipped because they exceed the maximum depth (${MAX_DEPTH})`);
-        }
-        return [...new Set(collected)].sort();
-    }
-    return [];
-}
 /**
  * Ingest a single file: parse, chunk, embed, delete old chunks, insert new chunks.
  * Returns the number of chunks inserted.
@@ -290,12 +195,10 @@ async function collectFiles(targetPath, baseDirs, excludePaths) {
  * visual-enrichment path: `parsePdfPages` + VLM captioning (`pdf-visual`
  * orchestrator) + joined-text chunking. `pdf-visual` is loaded via dynamic
  * `await import('../pdf-visual/index.js')` so the default (non-visual) path
- * never pulls the VLM module into the bundle (NFR-1 dynamic-import discipline,
- * verified by AC-001 Proxy sentinel in T4.6).
+ * never pulls the VLM module into the bundle.
  *
- * Non-visual, non-PDF, and `visual: true` + non-PDF (silently falls through
- * to the default branch — AC-006) paths are byte-identical to the post-T0.3
- * state and never load `pdf-visual`.
+ * Non-visual, non-PDF, and `visual: true` + non-PDF paths all use the default
+ * text-only branch and never load `pdf-visual`.
  */
 export async function ingestSingleFile(filePath, parser, chunker, embedder, vectorStore, options) {
     // Parse file
@@ -329,26 +232,12 @@ export async function ingestSingleFile(filePath, parser, chunker, embedder, vect
         // pre-existing `metadata.fileSize` semantics (post-enrichment,
         // pre-chunking text length).
         await vectorStore.deleteChunks(filePath);
-        const timestamp = new Date().toISOString();
-        const vectorChunks = chunks.map((chunk, index) => {
-            const embedding = embeddings[index];
-            if (!embedding) {
-                throw new Error(`Missing embedding for chunk ${index}`);
-            }
-            return {
-                id: randomUUID(),
-                filePath,
-                chunkIndex: chunk.index,
-                text: chunk.text,
-                vector: embedding,
-                metadata: {
-                    fileName: basename(filePath),
-                    fileSize: visualResult.text.length,
-                    fileType: extname(filePath).slice(1),
-                },
-                fileTitle: title,
-                timestamp,
-            };
+        const vectorChunks = buildVectorChunks({
+            filePath,
+            chunks,
+            embeddings,
+            fileSize: visualResult.text.length,
+            fileTitle: title,
         });
         await vectorStore.insertChunks(vectorChunks);
         return vectorChunks.length;
@@ -363,7 +252,7 @@ export async function ingestSingleFile(filePath, parser, chunker, embedder, vect
         text = result.content;
         title = result.title || null;
     }
-    // Chunk text + generate embeddings via the shared computation layer (Phase 0).
+    // Chunk text + generate embeddings via the shared computation layer.
     const { chunks, embeddings } = await buildChunksAndEmbeddings(text, title, chunker, embedder);
     if (chunks.length === 0) {
         console.error(`  Warning: 0 chunks generated (file may be empty or too short)`);
@@ -372,26 +261,12 @@ export async function ingestSingleFile(filePath, parser, chunker, embedder, vect
     // Delete existing chunks for this file
     await vectorStore.deleteChunks(filePath);
     // Build vector chunks
-    const timestamp = new Date().toISOString();
-    const vectorChunks = chunks.map((chunk, index) => {
-        const embedding = embeddings[index];
-        if (!embedding) {
-            throw new Error(`Missing embedding for chunk ${index}`);
-        }
-        return {
-            id: randomUUID(),
-            filePath,
-            chunkIndex: chunk.index,
-            text: chunk.text,
-            vector: embedding,
-            metadata: {
-                fileName: basename(filePath),
-                fileSize: text.length,
-                fileType: extname(filePath).slice(1),
-            },
-            fileTitle: title,
-            timestamp,
-        };
+    const vectorChunks = buildVectorChunks({
+        filePath,
+        chunks,
+        embeddings,
+        fileSize: text.length,
+        fileTitle: title,
     });
     // Insert chunks
     await vectorStore.insertChunks(vectorChunks);
@@ -434,14 +309,13 @@ export async function runIngest(args, globalOptions = {}) {
     const config = await resolveConfig(globalConfig, options);
     const excludePaths = [`${resolve(config.dbPath)}${sep}`, `${resolve(config.cacheDir)}${sep}`];
     // Surface resolver warnings (precedence, nested-root pruning) on stderr
-    // before scan output starts. Scan-loop multi-root behavior is P2-T2; this
-    // task only wires the resolver so the warnings are visible today.
+    // before scan output starts.
     for (const warning of config.baseDirsWarnings) {
         console.error(warning.message);
     }
     // Collect files: when `targetPath` is a directory, the scan iterates every
-    // effective root in `config.baseDirs.baseDirs` (P2-T2) — the positional
-    // directory only triggers directory mode and is no longer the scan target.
+    // effective root in `config.baseDirs.baseDirs`; the positional directory
+    // only triggers directory mode and is no longer the scan target.
     // Single-file mode is unchanged. See `collectFiles` for the full rationale.
     const files = await collectFiles(targetPath, config.baseDirs.baseDirs, excludePaths);
     if (files.length === 0) {
@@ -452,9 +326,7 @@ export async function runIngest(args, globalOptions = {}) {
     // Initialize components (single instances reused across all files).
     // The parser receives the full multi-root config. The directory-scan loop
     // (`collectFiles`) iterates every effective root in `config.baseDirs.baseDirs`
-    // (P2-T2). Under a single configured root this is byte-identical to the
-    // pre-P2-T2 single-root scan; under multiple roots it walks each one and
-    // dedupes overlap.
+    // and dedupes overlap.
     const parser = new DocumentParser({
         baseDirs: config.baseDirs.baseDirs,
         maxFileSize: config.maxFileSize,
@@ -502,7 +374,7 @@ export async function runIngest(args, globalOptions = {}) {
                 }
             }
             catch (error) {
-                const reason = error instanceof Error ? error.message : String(error);
+                const reason = formatCliError(error);
                 console.error(`${label} ${filePath} ... FAILED: ${reason}`);
                 summary.failed++;
             }