abb-opencode-local-rag 0.1.0

package/dist/utils/scan.js

@@ -0,0 +1,221 @@
+// Shared bounded directory scan for supported document files.
+//
+// The single bounded directory walker behind the CLI `ingest` walker, the CLI
+// `list` walker, and the MCP server's `list_files` scan: bounded depth, symlink
+// skipping, exclude-path filtering, and supported-extension matching.
+//
+// The four collect predicates live in `classifyScanEntry` so a path a caller
+// names explicitly (`classifyRequestedPath`) is judged by the same rules as a
+// path the walk discovers — sync accepts both, and only one of them used to be
+// filtered.
+//
+// Presentation (warning wording, when/where warnings are surfaced) and
+// post-processing (sort/dedup) stay with each caller — this helper returns
+// structured coverage facts (`unreadableDirs`, `depthLimitedDirs`,
+// `skippedSymlinks`, and the derived `depthLimited`) so callers preserve their
+// own, intentionally-different, user-facing messages. The path-granular facts
+// let a caller tell an unobserved region apart from an observed one instead of
+// treating any gap as 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';
+/**
+ * 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 directory entry and an explicitly requested path
+ * ({@link classifyRequestedPath}) are judged by exactly the same rules instead of
+ * by two implementations that can drift.
+ *
+ * Evaluation order is part of the contract and matches the walk: a symbolic link
+ * is reported as a link even under an excluded prefix, and a directory is
+ * accepted without any extension test.
+ *
+ * `platform` is a parameter rather than a direct `process.platform` read — the
+ * same reason `toSyncPathKey` takes one: the Windows exclusion semantics
+ * ({@link isUnderExcludedPrefix}) must be provable on a macOS/Linux machine. The
+ * default leaves every call site unchanged.
+ *
+ * Both `Dirent` (from `readdir`) and `Stats` (from `lstat`) satisfy
+ * {@link EntryTypeFacts} structurally.
+ */
+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';
+    }
+}
+/**
+ * Bounded BFS scan of a single root, collecting every supported file up to
+ * `maxDepth` levels deep, counted from `rootPath` itself. Symlinks are skipped
+ * (never followed) and recorded in `skippedSymlinks`; paths under any
+ * `excludePaths` prefix are filtered out. A per-directory `readdir` failure is
+ * captured into `unreadableDirs` and does not abort the scan (best-effort per
+ * directory); a branch pruned at `maxDepth` is captured into `depthLimitedDirs`.
+ *
+ * When `scope` is provided (non-empty), the predicate is pushed into the
+ * traversal: a directory is visited only if it is in-scope or an ancestor of
+ * some scope prefix, and a file is collected only if it is in-scope. A root that
+ * intersects no prefix is skipped without any `readdir`. An absent/empty `scope`
+ * leaves traversal and collection byte-for-byte unchanged.
+ *
+ * `platform` only selects how the exclusion comparison treats case (see
+ * {@link classifyScanEntry}); it defaults to the host, so every existing call is
+ * unchanged.
+ *
+ * Does not sort, dedupe, or emit warnings — callers handle those so their
+ * existing output contracts are preserved.
+ */
+export async function bfsCollectSupportedFiles(rootPath, excludePaths, maxDepth = MAX_SCAN_DEPTH, scope, platform = process.platform) {
+    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 { dirPath, depth } = queue.shift();
+        if (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(dirPath);
+            continue;
+        }
+        // TypeScript's `readdir` has overloads keyed on the options shape; pin the
+        // encoding to `'utf8'` and cast so the loop operates on string-encoded
+        // Dirent entries (matches the rest of the codebase).
+        let entries;
+        try {
+            entries = (await readdir(dirPath, {
+                withFileTypes: true,
+                encoding: 'utf8',
+            }));
+        }
+        catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? (error.code ?? 'UNKNOWN')
+                : 'UNKNOWN';
+            unreadableDirs.push({ dirPath, code });
+            continue;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dirPath, entry.name);
+            const kind = classifyScanEntry(fullPath, entry, excludePaths, platform);
+            if (kind === 'symlink') {
+                skippedSymlinks.push(fullPath);
+            }
+            else if (kind === 'directory') {
+                if (shouldVisitDir(fullPath, scope)) {
+                    queue.push({ dirPath: fullPath, depth: depth + 1 });
+                }
+            }
+            else if (kind === 'file' && isInScope(fullPath, scope)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    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,43 @@
+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 is a descendant of it, using a separator
+ * boundary so `/foo/bar` does not match `/foo/barista`. The separator is derived
+ * from `prefix`; trailing separators on `prefix` are normalized so `/a/b`,
+ * `/a/b/`, and `/a/b//` are equivalent. `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;
+/**
+ * Return the prefixes in `scope` that are NOT absolute paths (server-OS path
+ * style, via `node:path` `isAbsolute` — the same path style scope matching
+ * uses). A non-absolute prefix matches nothing under the exact-or-descendant
+ * contract, so both list surfaces surface these as non-fatal warnings while
+ * preserving the "matches nothing" result semantics. Input order is preserved.
+ */
+export declare function nonAbsolutePrefixes(scope: string[]): string[];
+/**
+ * Directory-visit predicate for the scoped BFS walk, shared by both walkers so
+ * the boundary semantics live in one place. Visit `dir` when there is no scope,
+ * when `dir` is in-scope (under-or-equal a prefix), or when `dir` is an ancestor
+ * of some prefix (must be descended to reach the scoped subtree). An absent or
+ * empty `scope` visits every directory (traversal unchanged).
+ */
+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":"AAgCA,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;;;;;;GAMG;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;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAGrE;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,87 @@
+// Boundary-safe, exact-or-descendant path prefix matcher shared by both BFS
+// walkers and both list surfaces (MCP `list_files` and the `list` CLI).
+//
+// This is the JS counterpart of `vectordb`'s SQL `buildPrefixPredicate`
+// (`src/vectordb/index.ts`): both implement the same exact-or-descendant
+// contract (`path = prefix OR path startsWith prefix + separator`) with the
+// same separator-boundary and trailing-separator normalization, so `/foo/bar`
+// matches `/foo/bar` and `/foo/bar/x.md` but not `/foo/barista`. Both reference
+// #146's boundary rules — 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) {
+    return prefix.includes('/') ? '/' : prefix.includes('\\') ? '\\' : 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 is a descendant of it, using a separator
+ * boundary so `/foo/bar` does not match `/foo/barista`. The separator is derived
+ * from `prefix`; trailing separators on `prefix` are normalized so `/a/b`,
+ * `/a/b/`, and `/a/b//` are equivalent. `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));
+}
+/**
+ * Return the prefixes in `scope` that are NOT absolute paths (server-OS path
+ * style, via `node:path` `isAbsolute` — the same path style scope matching
+ * uses). A non-absolute prefix matches nothing under the exact-or-descendant
+ * contract, so both list surfaces surface these as non-fatal warnings while
+ * preserving the "matches nothing" result semantics. Input order is preserved.
+ */
+export function nonAbsolutePrefixes(scope) {
+    return scope.filter((prefix) => !isAbsolute(prefix));
+}
+/**
+ * Directory-visit predicate for the scoped BFS walk, shared by both walkers so
+ * the boundary semantics live in one place. Visit `dir` when there is no scope,
+ * when `dir` is in-scope (under-or-equal a prefix), or when `dir` is an ancestor
+ * of some prefix (must be descended to reach the scoped subtree). An absent or
+ * empty `scope` visits every directory (traversal unchanged).
+ */
+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,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,wEAAwE;AACxE,yEAAyE;AACzE,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,yEAAyE;AAEzE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEvD,0EAA0E;AAC1E,2EAA2E;AAC3E,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;AAC7E,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;;;;;;GAMG;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;;;;;;GAMG;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;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAgB;IAC1D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7C,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,23 @@
+/**
+ * Returns the literal prefixes joined with their `realpath`-resolved forms.
+ * Without canonicalization macOS would let `/etc` (which realpaths to
+ * `/private/etc`) slip past once the resolver normalizes the path. The
+ * literal is always kept so a realpath failure cannot weaken the policy.
+ */
+export declare function buildSensitivePrefixes(realpathSyncFn?: (p: string) => string): string[];
+/**
+ * Returns a user-facing error string when `value` resolves to a sensitive
+ * system or credential directory. Returns `undefined` when the path is
+ * acceptable.
+ *
+ * `flagName` is interpolated into the error message so the surfacing
+ * surface (CLI flag, env var, ...) is visible at the call site. The CLI uses
+ * `'--base-dir'`; the server entry point uses `'BASE_DIR'` or `'BASE_DIRS'`
+ * to attribute the rejection to the env var actually consulted.
+ *
+ * The trailing-separator check on system prefixes guards against sibling
+ * paths like `/etcetera`. Both the `~/.ssh` and the expanded form are
+ * rejected so the policy holds when `$HOME` is unset.
+ */
+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":"AA4BA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAqB,GACnD,MAAM,EAAE,CAcV;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0BtF"}

package/dist/utils/sensitive-path.js

@@ -0,0 +1,91 @@
+// Sensitive-path policy shared by the CLI and the MCP server entry point.
+//
+// Both entry points must refuse to use system or credential directories as
+// document roots: pre-multi-root code only enforced this at the CLI surface,
+// which left a gap where `BASE_DIRS=["/etc"]` in the MCP server's environment
+// would be silently accepted. This module owns the single source of truth
+// for the policy so the CLI (`cli/options.ts` and `cli/common.ts`) and the
+// server entry point (`server-main.ts`) cannot drift.
+//
+// The policy is intentionally simple — a small allow-list-by-exclusion of
+// system mount points and credential directories under `$HOME`. It is not a
+// general-purpose sandboxing mechanism; the parser layer (`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'];
+/**
+ * Returns the literal prefixes joined with their `realpath`-resolved forms.
+ * Without canonicalization macOS would let `/etc` (which realpaths to
+ * `/private/etc`) slip past once the resolver normalizes the path. 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. Returns `undefined` when the path is
+ * acceptable.
+ *
+ * `flagName` is interpolated into the error message so the surfacing
+ * surface (CLI flag, env var, ...) is visible at the call site. The CLI uses
+ * `'--base-dir'`; the server entry point uses `'BASE_DIR'` or `'BASE_DIRS'`
+ * to attribute the rejection to the env var actually consulted.
+ *
+ * The trailing-separator check on system prefixes guards against sibling
+ * paths like `/etcetera`. Both the `~/.ssh` and the expanded form are
+ * rejected so the policy holds when `$HOME` is unset.
+ */
+export function checkSensitivePath(value, flagName) {
+    const home = process.env['HOME'] || homedir();
+    const expanded = value.startsWith('~/') ? `${home}/${value.slice(2)}` : value;
+    const valueCmp = toComparable(expanded);
+    for (const prefix of SENSITIVE_PATH_PREFIXES) {
+        const prefixCmp = toComparable(prefix);
+        if (valueCmp === prefixCmp || valueCmp.startsWith(`${prefixCmp}/`)) {
+            return `Refusing to use sensitive system path for ${flagName}: ${value}`;
+        }
+    }
+    for (const dir of SENSITIVE_HOME_PREFIXES) {
+        if (home.length > 0) {
+            const homePathCmp = toComparable(`${home}/${dir}`);
+            if (valueCmp === homePathCmp || valueCmp.startsWith(`${homePathCmp}/`)) {
+                return `Refusing to use sensitive system path for ${flagName}: ${value}`;
+            }
+        }
+        // Unexpanded `~/...` form — caught even when `home` is empty.
+        if (value === `~/${dir}` || value.startsWith(`~/${dir}/`)) {
+            return `Refusing to use sensitive system path for ${flagName}: ${value}`;
+        }
+    }
+    return 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,20 @@
+/**
+ * Resolve `path` into the absolute, normalized key sync uses to reconcile disk
+ * state against database state. Windows keys are case-folded because its
+ * filesystem is case-insensitive; POSIX keys keep their case.
+ *
+ * `platform` is a parameter rather than a direct `process.platform` read, and it
+ * selects the resolver as well as the case-fold, so the Windows branch is
+ * provable on a macOS/Linux machine — the host-bound `resolve()` would otherwise
+ * turn a Windows path into a cwd-relative POSIX one.
+ *
+ * Resolution is purely lexical, with no filesystem canonicalization: symbolic
+ * links are intentionally not followed, and a path that no longer exists on disk
+ * must still yield a key.
+ *
+ * The key is an internal reconciliation identity. It never replaces the verbatim
+ * stored `filePath` spellings used for deletion, nor the shared scope contract
+ * used by the query, list, and source-classification flows.
+ */
+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;;;;;;;;;;;;;;;;;GAiBG;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,33 @@
+// 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 uses to reconcile disk
+ * state against database state. Windows keys are case-folded because its
+ * filesystem is case-insensitive; POSIX keys keep their case.
+ *
+ * `platform` is a parameter rather than a direct `process.platform` read, and it
+ * selects the resolver as well as the case-fold, so the Windows branch is
+ * provable on a macOS/Linux machine — the host-bound `resolve()` would otherwise
+ * turn a Windows path into a cwd-relative POSIX one.
+ *
+ * Resolution is purely lexical, with no filesystem canonicalization: symbolic
+ * links are intentionally not followed, and a path that no longer exists on disk
+ * must still yield a key.
+ *
+ * The key is an internal reconciliation identity. It never replaces the verbatim
+ * stored `filePath` spellings used for deletion, nor the shared scope contract
+ * used by the query, list, and source-classification flows.
+ */
+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;;;;;;;;;;;;;;;;;GAiBG;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"}