@ssmeo/mcp-local-rag 0.18.6

package/dist/utils/scan.js

@@ -0,0 +1,209 @@
+// Shared bounded directory scan for supported document files: the single
+// walker behind CLI `ingest`, CLI `list`, and the MCP `list_files` scan.
+//
+// The collect predicates live in `classifyScanEntry` so a path a caller names
+// explicitly (`classifyRequestedPath`) is judged by the same rules as one the
+// walk discovers — sync accepts both, and only one used to be filtered.
+//
+// Warning wording and sort/dedupe stay with each caller. This helper returns
+// path-granular coverage facts instead, so a caller can tell an unobserved
+// region apart from a whole-scan failure.
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+import { SUPPORTED_EXTENSIONS } from '../parser/index.js';
+import { MAX_SCAN_DEPTH } from './limits.js';
+import { isInScope, isUnderOrEqual, shouldVisitDir } from './scope-match.js';
+import { errorCode } from './type-guards.js';
+/**
+ * Canonical identity key for the `list`/`list_files` cross-reference: a file's
+ * realpath, falling back to the input path when realpath fails (orphaned or
+ * raw-data entries). Matching ingested DB entries against scanned files by this
+ * key recognizes the same physical file across symlinked spellings (prefix or
+ * alias). Storage, lookup, and display still use the normal resolve() path —
+ * realpath here is the file-identity comparison, not a user-facing value.
+ */
+export async function realpathForMatch(filePath) {
+    try {
+        return await realpath(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+/**
+ * Canonical form of one explicitly requested path: its parent chain resolved
+ * through symbolic links, with the final component appended verbatim. `null` when
+ * the parent chain cannot be resolved at all — absent, or a directory this
+ * process may not traverse — which a caller must treat as "not contained",
+ * because telling those cases apart would report the state of paths outside its
+ * configured roots.
+ *
+ * Only the parent chain is resolved, because the requested entry itself is judged
+ * by {@link classifyRequestedPath}'s `lstat`: a symbolic link named directly
+ * inside a root is an in-root entry that is refused as a link, not a path to be
+ * reported by whatever it points at.
+ *
+ * `realpath` here is the containment (security) boundary, the same role it plays
+ * in `DocumentParser.validateFilePath` — never a spelling anything is stored,
+ * looked up, or displayed under. Those stay `resolve()`-only.
+ */
+export async function canonicalizeRequestedPath(path) {
+    try {
+        return join(await realpath(dirname(path)), basename(path));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `fullPath` sits under one of the configured excluded prefixes (the
+ * database or cache directory).
+ *
+ * Case-folded on Windows, whose filesystem is case-insensitive: the prefixes are
+ * built with `resolve()` only, which preserves whatever case `BASE_DIRS` and
+ * `DB_PATH` were spelled in, so a raw comparison let `C:\Docs\lancedb\raw.md`
+ * past `c:\docs\lancedb\`. That is worse than a plain miss, because sync's prune
+ * guard compares case-folded keys (`toSyncPathKey`): the internals were ingested
+ * and then could never be pruned. Both sides now agree.
+ *
+ * Exact-or-descendant via `isUnderOrEqual`: the prefixes carry a trailing
+ * separator, so `startsWith` matched the directory's contents but not the
+ * directory itself, and the walk descended into it once per run.
+ *
+ * Purely lexical — no `realpath`, `stat`, or any other syscall, because this runs
+ * once per directory entry on the walk shared with `list_files`, CLI `list`, and
+ * CLI `ingest`.
+ */
+function isUnderExcludedPrefix(fullPath, excludePaths, platform) {
+    const fold = (path) => (platform === 'win32' ? path.toLowerCase() : path);
+    const candidate = fold(fullPath);
+    return excludePaths.some((prefix) => isUnderOrEqual(candidate, fold(prefix)));
+}
+/**
+ * The collect predicates of {@link bfsCollectSupportedFiles} as one decision,
+ * so a discovered entry and an explicitly requested path are judged by the same
+ * rules rather than by two implementations that drift.
+ *
+ * Evaluation order is part of the contract: a symbolic link is reported as a
+ * link even under an excluded prefix, and a directory needs no extension test.
+ *
+ * `platform` is a parameter so the Windows exclusion semantics are provable on
+ * a POSIX host. Both `Dirent` and `Stats` satisfy {@link EntryTypeFacts}.
+ */
+export function classifyScanEntry(fullPath, entry, excludePaths, platform = process.platform) {
+    if (entry.isSymbolicLink()) {
+        return 'symlink';
+    }
+    if (isUnderExcludedPrefix(fullPath, excludePaths, platform)) {
+        return 'excluded';
+    }
+    if (entry.isDirectory()) {
+        return 'directory';
+    }
+    if (!entry.isFile()) {
+        return 'irregular';
+    }
+    return SUPPORTED_EXTENSIONS.has(extname(fullPath).toLowerCase()) ? 'file' : 'unsupported';
+}
+/**
+ * Classify one explicitly requested path with {@link classifyScanEntry}, so a
+ * path a caller names is subject to the same predicates as a path the walker
+ * discovers.
+ *
+ * `lstat` rather than `stat`, so a symbolic link is reported as a link instead of
+ * as whatever it points at; and `lstat` rather than any read, so a caller can
+ * refuse the path before its bytes cost anything — reading a FIFO blocks forever,
+ * and reading through a link reaches outside the configured roots.
+ *
+ * Any stat failure is `'missing'`: an unreachable path and an absent one are the
+ * same non-answer to "what is here".
+ */
+export async function classifyRequestedPath(path, excludePaths, platform = process.platform) {
+    try {
+        return classifyScanEntry(path, await lstat(path), excludePaths, platform);
+    }
+    catch {
+        return 'missing';
+    }
+}
+/** Directory entries, or the errno that made the directory unreadable. */
+async function readDirEntries(dirPath) {
+    try {
+        return { entries: await readdir(dirPath, { withFileTypes: true, encoding: 'utf8' }) };
+    }
+    catch (error) {
+        return { code: errorCode(error) ?? 'UNKNOWN' };
+    }
+}
+/**
+ * Route one directory's entries: symlinks are recorded and never followed,
+ * in-scope directories are enqueued one level deeper, and in-scope supported
+ * files are collected.
+ */
+function sortEntries(entries, visit, rules, sinks) {
+    for (const entry of entries) {
+        const fullPath = join(visit.dirPath, entry.name);
+        const kind = classifyScanEntry(fullPath, entry, rules.excludePaths, rules.platform);
+        if (kind === 'symlink') {
+            sinks.skippedSymlinks.push(fullPath);
+        }
+        else if (kind === 'directory' && shouldVisitDir(fullPath, rules.scope)) {
+            sinks.queue.push({ dirPath: fullPath, depth: visit.depth + 1 });
+        }
+        else if (kind === 'file' && isInScope(fullPath, rules.scope)) {
+            sinks.files.push(fullPath);
+        }
+    }
+}
+/**
+ * Bounded BFS scan of a single root, depth counted from `rootPath` itself.
+ * Symlinks are never followed. An unreadable directory is recorded and does
+ * not abort the scan.
+ *
+ * Does not sort, dedupe, or emit warnings — each caller owns its own output
+ * contract for those.
+ */
+export async function bfsCollectSupportedFiles(rootPath, excludePaths, options = {}) {
+    const { maxDepth = MAX_SCAN_DEPTH, scope, platform = process.platform } = options;
+    const files = [];
+    const unreadableDirs = [];
+    const depthLimitedDirs = [];
+    const skippedSymlinks = [];
+    // Scope pushdown (shared with scanBaseDir via scope-match): visit a directory
+    // only if it is in-scope or an ancestor of the scoped subtree, and collect a
+    // file only if it is in-scope. A root intersecting no prefix is skipped
+    // without any `readdir`; absent scope leaves traversal/collection unchanged.
+    const queue = shouldVisitDir(rootPath, scope)
+        ? [{ dirPath: rootPath, depth: 0 }]
+        : [];
+    while (queue.length > 0) {
+        const visit = queue.shift();
+        if (visit === undefined) {
+            break;
+        }
+        if (visit.depth >= maxDepth) {
+            // `dirPath` was reached but never read, so it is the first unvisited
+            // directory of this branch: it and all its descendants are unobserved.
+            depthLimitedDirs.push(visit.dirPath);
+            continue;
+        }
+        const read = await readDirEntries(visit.dirPath);
+        if ('code' in read) {
+            unreadableDirs.push({ dirPath: visit.dirPath, code: read.code });
+            continue;
+        }
+        sortEntries(read.entries, visit, { excludePaths, scope, platform }, {
+            files,
+            skippedSymlinks,
+            queue,
+        });
+    }
+    return {
+        files,
+        unreadableDirs,
+        depthLimitedDirs,
+        skippedSymlinks,
+        depthLimited: depthLimitedDirs.length > 0,
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/utils/scan.js.map

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

package/dist/utils/scope-match.d.ts

@@ -0,0 +1,38 @@
+export interface NormalizedScopePrefix {
+    exact: string;
+    descendant: string;
+}
+/** Normalize one scope prefix for both in-memory and LanceDB matching. */
+export declare function normalizeScopePrefix(prefix: string): NormalizedScopePrefix;
+/**
+ * True when `path` equals `prefix` or descends from it, with a separator
+ * boundary so `/foo/bar` does not match `/foo/barista`. Trailing separators on
+ * `prefix` are normalized; `path` is compared verbatim, matching the SQL
+ * contract in `buildPrefixPredicate`.
+ */
+export declare function isUnderOrEqual(path: string, prefix: string): boolean;
+/**
+ * True when `path` is under-or-equal any prefix in `prefixes` (union). Empty or
+ * undefined `prefixes` semantics are the caller's concern; an empty list yields
+ * false (membership against no prefixes).
+ */
+export declare function matchesAnyScope(path: string, prefixes: string[]): boolean;
+/**
+ * The prefixes in `scope` that are not absolute paths. Such a prefix matches
+ * nothing under the exact-or-descendant contract, so both list surfaces warn
+ * while keeping that "matches nothing" result.
+ */
+export declare function nonAbsolutePrefixes(scope: string[]): string[];
+/**
+ * Directory-visit predicate for the scoped walk, shared by both walkers. Visit
+ * `dir` when there is no scope, when it is in-scope, or when it is an ancestor
+ * of a prefix and must be descended to reach the scoped subtree.
+ */
+export declare function shouldVisitDir(dir: string, scope?: string[]): boolean;
+/**
+ * File-collect predicate for the scoped BFS walk, shared by both walkers.
+ * Collect `path` when there is no scope, or when `path` is in-scope. An absent
+ * or empty `scope` collects every supported file (collection unchanged).
+ */
+export declare function isInScope(path: string, scope?: string[]): boolean;
+//# sourceMappingURL=scope-match.d.ts.map

package/dist/utils/scope-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-match.d.ts","sourceRoot":"","sources":["../../src/utils/scope-match.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAO1E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAKrE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAEjE"}

package/dist/utils/scope-match.js

@@ -0,0 +1,86 @@
+// Boundary-safe exact-or-descendant prefix matcher, shared by both BFS walkers
+// and both list surfaces.
+//
+// The JS counterpart of `vectordb`'s SQL `buildPrefixPredicate`: same
+// exact-or-descendant contract, same separator-boundary and trailing-separator
+// normalization. A change to one must be mirrored in the other.
+import { isAbsolute, sep as PATH_SEP } from 'node:path';
+// A slash identifies slash-style paths even when a legal filename segment
+// contains a backslash. Pure backslash-style paths retain Windows support.
+function deriveSeparator(prefix) {
+    if (prefix.includes('/')) {
+        return '/';
+    }
+    if (prefix.includes('\\')) {
+        return '\\';
+    }
+    return PATH_SEP;
+}
+// Strip trailing separators so `/a/b`, `/a/b/`, `/a/b//` normalize alike. A
+// prefix of only separators (e.g. a lone posix root `/`) is kept as a single
+// separator so its descendant boundary is `/<sep>` rather than empty.
+function stripTrailingSeparators(prefix, separator) {
+    let end = prefix.length;
+    while (end > 0 && prefix[end - 1] === separator) {
+        end--;
+    }
+    if (end === 0) {
+        return separator;
+    }
+    return prefix.slice(0, end);
+}
+/** Normalize one scope prefix for both in-memory and LanceDB matching. */
+export function normalizeScopePrefix(prefix) {
+    const separator = deriveSeparator(prefix);
+    const exact = stripTrailingSeparators(prefix, separator);
+    return {
+        exact,
+        descendant: exact.endsWith(separator) ? exact : exact + separator,
+    };
+}
+/**
+ * True when `path` equals `prefix` or descends from it, with a separator
+ * boundary so `/foo/bar` does not match `/foo/barista`. Trailing separators on
+ * `prefix` are normalized; `path` is compared verbatim, matching the SQL
+ * contract in `buildPrefixPredicate`.
+ */
+export function isUnderOrEqual(path, prefix) {
+    const { exact, descendant } = normalizeScopePrefix(prefix);
+    return path === exact || path.startsWith(descendant);
+}
+/**
+ * True when `path` is under-or-equal any prefix in `prefixes` (union). Empty or
+ * undefined `prefixes` semantics are the caller's concern; an empty list yields
+ * false (membership against no prefixes).
+ */
+export function matchesAnyScope(path, prefixes) {
+    return prefixes.some((prefix) => isUnderOrEqual(path, prefix));
+}
+/**
+ * The prefixes in `scope` that are not absolute paths. Such a prefix matches
+ * nothing under the exact-or-descendant contract, so both list surfaces warn
+ * while keeping that "matches nothing" result.
+ */
+export function nonAbsolutePrefixes(scope) {
+    return scope.filter((prefix) => !isAbsolute(prefix));
+}
+/**
+ * Directory-visit predicate for the scoped walk, shared by both walkers. Visit
+ * `dir` when there is no scope, when it is in-scope, or when it is an ancestor
+ * of a prefix and must be descended to reach the scoped subtree.
+ */
+export function shouldVisitDir(dir, scope) {
+    if (!scope || scope.length === 0) {
+        return true;
+    }
+    return matchesAnyScope(dir, scope) || scope.some((prefix) => isUnderOrEqual(prefix, dir));
+}
+/**
+ * File-collect predicate for the scoped BFS walk, shared by both walkers.
+ * Collect `path` when there is no scope, or when `path` is in-scope. An absent
+ * or empty `scope` collects every supported file (collection unchanged).
+ */
+export function isInScope(path, scope) {
+    return !scope || scope.length === 0 || matchesAnyScope(path, scope);
+}
+//# sourceMappingURL=scope-match.js.map

package/dist/utils/scope-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-match.js","sourceRoot":"","sources":["../../src/utils/scope-match.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,0BAA0B;AAC1B,EAAE;AACF,sEAAsE;AACtE,+EAA+E;AAC/E,gEAAgE;AAEhE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEvD,0EAA0E;AAC1E,2EAA2E;AAC3E,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,4EAA4E;AAC5E,6EAA6E;AAC7E,sEAAsE;AACtE,SAAS,uBAAuB,CAAC,MAAc,EAAE,SAAiB;IAChE,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,CAAA;IACvB,OAAO,GAAG,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAChD,GAAG,EAAE,CAAA;IACP,CAAC;IACD,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QACd,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAC7B,CAAC;AAOD,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACzC,MAAM,KAAK,GAAG,uBAAuB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACxD,OAAO;QACL,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS;KAClE,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAc;IACzD,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAC1D,OAAO,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAA;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,QAAkB;IAC9D,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAe;IACjD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAgB;IAC1D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAgB;IACtD,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AACrE,CAAC"}

package/dist/utils/sensitive-path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The literal prefixes joined with their `realpath`-resolved forms. Without
+ * canonicalization macOS would let `/etc` (which realpaths to `/private/etc`)
+ * slip past. The literal is always kept, so a realpath failure cannot weaken
+ * the policy.
+ */
+export declare function buildSensitivePrefixes(realpathSyncFn?: (p: string) => string): string[];
+export declare function checkSensitivePath(value: string, flagName: string): string | undefined;
+//# sourceMappingURL=sensitive-path.d.ts.map

package/dist/utils/sensitive-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-path.d.ts","sourceRoot":"","sources":["../../src/utils/sensitive-path.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAqB,GACnD,MAAM,EAAE,CAcV;AAmCD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUtF"}

package/dist/utils/sensitive-path.js

@@ -0,0 +1,78 @@
+// Sensitive-path policy shared by the CLI and the MCP server entry point, so
+// neither can drift: pre-multi-root code enforced it at the CLI surface only,
+// which left `BASE_DIRS=["/etc"]` silently accepted in the server.
+//
+// Deliberately simple — a small exclusion list of system mount points and
+// credential directories under `$HOME`, not a sandbox. `DocumentParser`
+// remains the authoritative path-traversal / symlink-escape boundary.
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+// Normalize a path for comparison: forward-slash separators throughout and
+// lower-case on Windows (case-insensitive filesystem). Used by the security
+// boundary checks below so `C:\Users\me\.ssh` and `c:/users/me/.ssh` resolve
+// to the same comparable form.
+function toComparable(p) {
+    const slashed = p.replace(/\\/g, '/');
+    return process.platform === 'win32' ? slashed.toLowerCase() : slashed;
+}
+const SENSITIVE_PATH_LITERALS = ['/etc', '/usr', '/sys', '/proc', '/var'];
+/**
+ * The literal prefixes joined with their `realpath`-resolved forms. Without
+ * canonicalization macOS would let `/etc` (which realpaths to `/private/etc`)
+ * slip past. The literal is always kept, so a realpath failure cannot weaken
+ * the policy.
+ */
+export function buildSensitivePrefixes(realpathSyncFn = realpathSync) {
+    const set = new Set();
+    for (const literal of SENSITIVE_PATH_LITERALS) {
+        set.add(literal);
+        try {
+            const canonical = realpathSyncFn(literal);
+            if (typeof canonical === 'string' && canonical.length > 0) {
+                set.add(canonical);
+            }
+        }
+        catch {
+            // realpath unavailable on this platform; literal already retained.
+        }
+    }
+    return [...set];
+}
+const SENSITIVE_PATH_PREFIXES = buildSensitivePrefixes();
+/**
+ * Directories under `$HOME` that hold credentials and must never be opened
+ * as document roots even when the user expands the path themselves.
+ */
+const SENSITIVE_HOME_PREFIXES = ['.ssh', '.gnupg'];
+/**
+ * Returns a user-facing error string when `value` resolves to a sensitive
+ * system or credential directory, `undefined` otherwise.
+ *
+ * `flagName` is interpolated so the rejection names the surface actually
+ * consulted — `--base-dir`, `BASE_DIR`, or `BASE_DIRS`. The trailing-separator
+ * check guards against a sibling like `/etcetera`, and both `~/.ssh` and its
+ * expanded form are rejected so the policy holds when `$HOME` is unset.
+ */
+/** True when `pathCmp` is `prefixCmp` itself or sits underneath it. */
+function isAtOrUnder(pathCmp, prefixCmp) {
+    return pathCmp === prefixCmp || pathCmp.startsWith(`${prefixCmp}/`);
+}
+/** True when `value` names one of the sensitive home subdirectories. */
+function matchesSensitiveHomeDir(value, valueCmp, home) {
+    return SENSITIVE_HOME_PREFIXES.some((dir) => {
+        if (home.length > 0 && isAtOrUnder(valueCmp, toComparable(`${home}/${dir}`))) {
+            return true;
+        }
+        // Unexpanded `~/...` form — caught even when `home` is empty.
+        return value === `~/${dir}` || value.startsWith(`~/${dir}/`);
+    });
+}
+export function checkSensitivePath(value, flagName) {
+    const home = process.env['HOME'] || homedir();
+    const expanded = value.startsWith('~/') ? `${home}/${value.slice(2)}` : value;
+    const valueCmp = toComparable(expanded);
+    const isSensitive = SENSITIVE_PATH_PREFIXES.some((prefix) => isAtOrUnder(valueCmp, toComparable(prefix))) ||
+        matchesSensitiveHomeDir(value, valueCmp, home);
+    return isSensitive ? `Refusing to use sensitive system path for ${flagName}: ${value}` : undefined;
+}
+//# sourceMappingURL=sensitive-path.js.map

package/dist/utils/sensitive-path.js.map

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

package/dist/utils/sync-path-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve `path` into the absolute, normalized key sync reconciles with.
+ * Windows keys are case-folded, POSIX keys keep their case.
+ *
+ * `platform` is a parameter and selects the resolver as well as the case-fold,
+ * so the Windows branch is provable on POSIX — the host-bound `resolve()` would
+ * otherwise turn a Windows path into a cwd-relative POSIX one.
+ *
+ * Purely lexical: symbolic links are not followed, and a path no longer on disk
+ * must still yield a key. This is an internal reconciliation identity — never a
+ * replacement for the verbatim stored spellings used for deletion.
+ */
+export declare function toSyncPathKey(path: string, platform?: NodeJS.Platform): string;
+//# sourceMappingURL=sync-path-key.d.ts.map

package/dist/utils/sync-path-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-path-key.d.ts","sourceRoot":"","sources":["../../src/utils/sync-path-key.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAKhG"}

package/dist/utils/sync-path-key.js

@@ -0,0 +1,27 @@
+// Sync-only comparison-key generation.
+//
+// This module deliberately holds no boundary logic. Containment is delegated to
+// the unchanged `isUnderOrEqual` in `scope-match.ts`, composed by the caller as
+// `isUnderOrEqual(toSyncPathKey(candidate), toSyncPathKey(prefix))`, so the
+// exact-or-descendant, separator-boundary, and trailing-separator semantics
+// stay in exactly one place.
+import { posix, win32 } from 'node:path';
+/**
+ * Resolve `path` into the absolute, normalized key sync reconciles with.
+ * Windows keys are case-folded, POSIX keys keep their case.
+ *
+ * `platform` is a parameter and selects the resolver as well as the case-fold,
+ * so the Windows branch is provable on POSIX — the host-bound `resolve()` would
+ * otherwise turn a Windows path into a cwd-relative POSIX one.
+ *
+ * Purely lexical: symbolic links are not followed, and a path no longer on disk
+ * must still yield a key. This is an internal reconciliation identity — never a
+ * replacement for the verbatim stored spellings used for deletion.
+ */
+export function toSyncPathKey(path, platform = process.platform) {
+    if (platform === 'win32') {
+        return win32.resolve(path).toLowerCase();
+    }
+    return posix.resolve(path);
+}
+//# sourceMappingURL=sync-path-key.js.map

package/dist/utils/sync-path-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-path-key.js","sourceRoot":"","sources":["../../src/utils/sync-path-key.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,6BAA6B;AAE7B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IACtF,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AAC5B,CAAC"}

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,18 @@
+/** True for any non-null object, narrowing it to an indexable record. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * True for anything property access works on, functions included. Use this
+ * where the value may be a callable third-party handle rather than a plain
+ * object; {@link isRecord} covers the plain-object case.
+ */
+export declare function isObjectLike(value: unknown): value is Record<string, unknown>;
+/** True when `value` is one of `list`'s members, narrowing to that union. */
+export declare function isMemberOf<T extends string>(list: readonly T[], value: string): value is T;
+/** True for a finite integer, narrowing `unknown` to `number`. */
+export declare function isInteger(value: unknown): value is number;
+/**
+ * The `code` a Node system error carries (`ENOENT`, `EACCES`, ...), or
+ * `undefined` when the caught value is not one.
+ */
+export declare function errorCode(error: unknown): string | undefined;
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAGA,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE7E;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,CAAC,CAE1F;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM5D"}

package/dist/utils/type-guards.js

@@ -0,0 +1,34 @@
+// Narrowing helpers for values from outside the type system: parsed JSON,
+// third-party results, and `catch` bindings.
+/** True for any non-null object, narrowing it to an indexable record. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * True for anything property access works on, functions included. Use this
+ * where the value may be a callable third-party handle rather than a plain
+ * object; {@link isRecord} covers the plain-object case.
+ */
+export function isObjectLike(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}
+/** True when `value` is one of `list`'s members, narrowing to that union. */
+export function isMemberOf(list, value) {
+    return list.some((member) => member === value);
+}
+/** True for a finite integer, narrowing `unknown` to `number`. */
+export function isInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value);
+}
+/**
+ * The `code` a Node system error carries (`ENOENT`, `EACCES`, ...), or
+ * `undefined` when the caught value is not one.
+ */
+export function errorCode(error) {
+    if (!isRecord(error)) {
+        return undefined;
+    }
+    const code = error['code'];
+    return typeof code === 'string' ? code : undefined;
+}
+//# sourceMappingURL=type-guards.js.map

package/dist/utils/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6CAA6C;AAE7C,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAA;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,OAAO,KAAK,KAAK,UAAU,CAAA;AACrF,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAmB,IAAkB,EAAE,KAAa;IAC5E,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,KAAK,CAAC,CAAA;AAChD,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;IAC1B,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACpD,CAAC"}

package/dist/utils/visual-profile.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Visual-quality profile. `fast` is SmolVLM-256M / IDEFICS3 (~250 MB cache);
+ * `quality` is Qwen2.5-VL-3B-Instruct-ONNX (~2.9 GB, ~2x per-page inference,
+ * better on figures with in-image text).
+ */
+export declare const QUALITY_PROFILES: readonly ['fast', 'quality'];
+export type QualityProfile = (typeof QUALITY_PROFILES)[number];
+/** True for one of the supported profiles; anything else, including a stored legacy value, is not. */
+export declare function isQualityProfile(value: unknown): value is QualityProfile;
+//# sourceMappingURL=visual-profile.d.ts.map

package/dist/utils/visual-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-profile.d.ts","sourceRoot":"","sources":["../../src/utils/visual-profile.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,SAAS,CAAU,CAAA;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/utils/visual-profile.js

@@ -0,0 +1,15 @@
+// The visual-quality profile vocabulary, shared by ingestion, storage-facing
+// planning, CLI and MCP. It lives in `utils/` so a consumer that only needs the
+// domain value never takes a runtime dependency on the VLM modules.
+import { isMemberOf } from './type-guards.js';
+/**
+ * Visual-quality profile. `fast` is SmolVLM-256M / IDEFICS3 (~250 MB cache);
+ * `quality` is Qwen2.5-VL-3B-Instruct-ONNX (~2.9 GB, ~2x per-page inference,
+ * better on figures with in-image text).
+ */
+export const QUALITY_PROFILES = ['fast', 'quality'];
+/** True for one of the supported profiles; anything else, including a stored legacy value, is not. */
+export function isQualityProfile(value) {
+    return typeof value === 'string' && isMemberOf(QUALITY_PROFILES, value);
+}
+//# sourceMappingURL=visual-profile.js.map

package/dist/utils/visual-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-profile.js","sourceRoot":"","sources":["../../src/utils/visual-profile.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,gFAAgF;AAChF,oEAAoE;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,CAAU,CAAA;AAG5D,sGAAsG;AACtG,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;AACzE,CAAC"}