@ssmeo/mcp-local-rag 0.18.6

package/dist/embedder/remote.js

@@ -0,0 +1,182 @@
+// Remote embedding server (TEI-compatible) backend.
+//
+// Activated by RAG_EMBEDDING_SERVER_URL: when set, the factory returns this
+// class instead of the local Transformers.js pipeline, so embedding compute
+// runs on a self-hosted server (e.g. HuggingFace TEI) while document content
+// never leaves the deployment network.
+//
+// Wire protocol: POST {serverUrl}/embed  {"inputs": string[]} → number[][]
+// (TEI-native shape; the server owns model choice, dtype, and truncation).
+import { AppError } from '../utils/errors.js';
+/** Remote embedding generation error. */
+export class RemoteEmbeddingError extends AppError {
+    constructor(message, options) {
+        super(message, 'embedder', 'internal', options);
+        this.name = 'RemoteEmbeddingError';
+    }
+}
+/** Server responded with a retryable failure (429 / 5xx). */
+export class RemoteEmbeddingRetryableError extends RemoteEmbeddingError {
+    status;
+    constructor(status, body, serverUrl) {
+        super(`HTTP ${status} from embedding server ${serverUrl}${body ? `: ${body.slice(0, 200)}` : ''}`);
+        this.name = 'RemoteEmbeddingRetryableError';
+        this.status = status;
+    }
+}
+// ============================================
+// Retry (exponential backoff + full jitter)
+// ============================================
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8000;
+function isRetryableError(e) {
+    // Client errors (401/403/404/422) never succeed on retry; network-level
+    // failures and 429/5xx do.
+    if (e instanceof RemoteEmbeddingRetryableError) {
+        return true;
+    }
+    return !(e instanceof RemoteEmbeddingError);
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function sleep(ms) {
+    const { promise, resolve } = Promise.withResolvers();
+    setTimeout(resolve, ms);
+    return promise;
+}
+/** Exponential backoff with full jitter: 500ms ×2^attempt, capped at 8s. */
+function backoffMs(attempt) {
+    const cap = Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt);
+    return Math.floor(Math.random() * cap);
+}
+async function withRetry(fn, context) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            lastError = e;
+            if (attempt === MAX_RETRIES || !isRetryableError(e)) {
+                throw e;
+            }
+            const wait = backoffMs(attempt);
+            console.error(`RemoteEmbedder: ${context} failed (attempt ${attempt + 1}/${MAX_RETRIES + 1}), retrying in ${wait}ms`);
+            await sleep(wait);
+        }
+    }
+    throw lastError;
+}
+async function withTimeout(run, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ============================================
+// RemoteEmbedder
+// ============================================
+/**
+ * Structural counterpart of the local `Embedder`: same public surface
+ * (`initialize / embed / embedBatch / dispose / tokenLimit`), with embedding
+ * compute delegated to a self-hosted server.
+ *
+ * Semantics intentionally aligned with the local class:
+ * - `tokenLimit` is always `null` — the remote server owns truncation, which
+ *   maps to the local class's "degraded mode" (no cap, no clamp).
+ * - `dispose()` is a no-op — no in-process model resources.
+ * - `device` / `dtype` / `cacheDir` / `modelPath` are server-side concerns.
+ */
+export class RemoteEmbedder {
+    config;
+    dims = null;
+    initialized = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Probe the server and record the embedding dimension so later responses
+     * can be validated (a dimension change means the server swapped models —
+     * fail fast instead of writing mixed-dimension vectors).
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        const [vector] = await this.postEmbed(['dimension probe']);
+        if (!Array.isArray(vector) || vector.length === 0) {
+            throw new RemoteEmbeddingError(`Remote embedding server returned an empty vector: ${this.config.serverUrl}`);
+        }
+        this.dims = vector.length;
+        this.initialized = true;
+        console.error(`RemoteEmbedder: connected to "${this.config.serverUrl}" (dimension ${this.dims})`);
+    }
+    async dispose() {
+        this.initialized = false;
+        this.dims = null;
+    }
+    /** Remote servers decide their own truncation: no local cap, no clamp. */
+    get tokenLimit() {
+        return null;
+    }
+    async embed(text) {
+        const vectors = await this.embedBatch([text]);
+        const vector = vectors[0];
+        if (vector === undefined) {
+            throw new RemoteEmbeddingError(`Remote embedding server returned no vector for a single input: ${this.config.serverUrl}`);
+        }
+        return vector;
+    }
+    async embedBatch(texts) {
+        await this.initialize();
+        const vectors = [];
+        for (let i = 0; i < texts.length; i += this.config.batchSize) {
+            const batch = texts.slice(i, i + this.config.batchSize);
+            const out = await withRetry(() => this.postEmbed(batch), `embedBatch(${batch.length} texts)`);
+            this.validate(out, batch.length);
+            vectors.push(...out);
+        }
+        return vectors;
+    }
+    validate(vectors, expectedCount) {
+        if (!Array.isArray(vectors) || vectors.length !== expectedCount) {
+            throw new RemoteEmbeddingError(`Remote embedding server returned ${Array.isArray(vectors) ? vectors.length : 'non-array'} ` +
+                `vectors for ${expectedCount} inputs: ${this.config.serverUrl}`);
+        }
+        if (this.dims !== null) {
+            for (const v of vectors) {
+                if (!Array.isArray(v) || v.length !== this.dims) {
+                    throw new RemoteEmbeddingError(`Remote embedding dimension drifted: expected ${this.dims}, got ` +
+                        `${Array.isArray(v) ? v.length : 'non-array'} (did the server switch models?): ` +
+                        this.config.serverUrl);
+                }
+            }
+        }
+    }
+    async postEmbed(inputs) {
+        return withTimeout(async (signal) => {
+            const res = await fetch(`${this.config.serverUrl}/embed`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ inputs }),
+                signal,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                if (isRetryableStatus(res.status)) {
+                    throw new RemoteEmbeddingRetryableError(res.status, body, this.config.serverUrl);
+                }
+                throw new RemoteEmbeddingError(`HTTP ${res.status} from embedding server ${this.config.serverUrl}${body ? `: ${body.slice(0, 200)}` : ''}`);
+            }
+            const vectors = await res.json();
+            return vectors;
+        }, this.config.timeoutMs ?? 30_000);
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/embedder/remote.js.map

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

package/dist/features/list.d.ts

@@ -0,0 +1,37 @@
+import { type ClassifiedSource } from '../utils/list-sources.js';
+export interface IngestedFileSummary {
+    filePath: string;
+    chunkCount: number;
+    timestamp: string;
+}
+export type ListedFile = {
+    filePath: string;
+    baseDir: string;
+    ingested: true;
+    chunkCount: number;
+    timestamp: string;
+} | {
+    filePath: string;
+    baseDir: string;
+    ingested: false;
+};
+export interface RootScanResult {
+    files: string[];
+    warnings: string[];
+}
+export interface ListDocumentsResult {
+    files: ListedFile[];
+    sources: ClassifiedSource[];
+    warnings: Array<{
+        baseDir: string;
+        message: string;
+    }>;
+}
+export declare function listDocuments(input: {
+    roots: readonly string[];
+    dbPath: string;
+    ingested: IngestedFileSummary[];
+    scope?: string[] | undefined;
+    scan: (root: string, scope?: string[] | undefined) => Promise<RootScanResult>;
+}): Promise<ListDocumentsResult>;
+//# sourceMappingURL=list.d.ts.map

package/dist/features/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/features/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAA2B,MAAM,0BAA0B,CAAA;AAGzF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,IAAI,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB,GACD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AAE1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtD;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE;IACzC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,mBAAmB,EAAE,CAAA;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;CAC9E,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA0C/B"}

package/dist/features/list.js

@@ -0,0 +1,41 @@
+import { classifyIngestedSources } from '../utils/list-sources.js';
+import { realpathForMatch } from '../utils/scan.js';
+export async function listDocuments(input) {
+    const ingestedKeyed = await Promise.all(input.ingested.map(async (entry) => ({ entry, key: await realpathForMatch(entry.filePath) })));
+    const ingestedByKey = new Map(ingestedKeyed.map(({ entry, key }) => [key, entry]));
+    const seenKeys = new Set();
+    const matchedKeys = new Set();
+    const files = [];
+    const warnings = [];
+    for (const baseDir of input.roots) {
+        const scanned = await input.scan(baseDir, input.scope);
+        warnings.push(...scanned.warnings.map((message) => ({ baseDir, message })));
+        for (const scannedPath of scanned.files) {
+            const key = await realpathForMatch(scannedPath);
+            if (seenKeys.has(key)) {
+                continue;
+            }
+            seenKeys.add(key);
+            const entry = ingestedByKey.get(key);
+            if (entry) {
+                matchedKeys.add(key);
+                files.push({
+                    filePath: entry.filePath,
+                    baseDir,
+                    ingested: true,
+                    chunkCount: entry.chunkCount,
+                    timestamp: entry.timestamp,
+                });
+            }
+            else {
+                files.push({ filePath: scannedPath, baseDir, ingested: false });
+            }
+        }
+    }
+    return {
+        files,
+        sources: classifyIngestedSources(ingestedKeyed, matchedKeys, input.dbPath, input.scope),
+        warnings,
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/features/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/features/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AA6BnD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAMnC;IACC,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAC9F,CAAA;IACD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;IAClF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACrC,MAAM,KAAK,GAAiB,EAAE,CAAA;IAC9B,MAAM,QAAQ,GAAgD,EAAE,CAAA;IAEhE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QACtD,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;QAE3E,KAAK,MAAM,WAAW,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAA;YAC/C,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,SAAQ;YACV,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAEjB,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACpC,IAAI,KAAK,EAAE,CAAC;gBACV,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;gBACpB,KAAK,CAAC,IAAI,CAAC;oBACT,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,OAAO;oBACP,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;iBAC3B,CAAC,CAAA;YACJ,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,OAAO,EAAE,uBAAuB,CAAC,aAAa,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC;QACvF,QAAQ;KACT,CAAA;AACH,CAAC"}

package/dist/features/sync.d.ts

@@ -0,0 +1,219 @@
+import type { ScanEntryKind } from '../utils/scan.js';
+import { type QualityProfile } from '../utils/visual-profile.js';
+/** Path-granular facts about the regions a directory scan could not observe. */
+export interface SyncScanCoverage {
+    unreadableDirs: {
+        dirPath: string;
+        code: string;
+    }[];
+    depthLimitedDirs: string[];
+    skippedSymlinks: string[];
+}
+/**
+ * Everything one run could not observe: the scan facts plus the files whose
+ * bytes were never read because they exceed the configured size limit. Every
+ * path here is an unobserved prefix, so the rows under it are protected from
+ * prune.
+ */
+export interface SyncCoverage extends SyncScanCoverage {
+    /** Files skipped by `hashFile` for exceeding the configured size limit. */
+    oversizedFiles: string[];
+}
+/** One bounded directory scan: the supported files found plus its coverage facts. */
+export interface SyncScanResult extends SyncScanCoverage {
+    files: string[];
+}
+/**
+ * One stored chunk row (or row group) of the database manifest. `filePath` is
+ * the verbatim stored spelling — the only value valid for deletion. A `null` or
+ * absent `contentHash` marks the row hashless, which makes its file dirty.
+ * `visualProfile` is the raw stored value, unvalidated: the vocabulary check
+ * belongs to the planner, not to the storage projection.
+ */
+export interface SyncManifestRow {
+    filePath: string;
+    contentHash?: string | null;
+    visualProfile?: string | null;
+}
+/** One supported file found on disk, with the hash of its current bytes. */
+export interface SyncDiskFile {
+    filePath: string;
+    contentHash: string;
+}
+/** How a sync invocation was addressed, after validation and classification. */
+export type SyncRequest = {
+    kind: 'roots';
+} | {
+    kind: 'directory';
+    path: string;
+} | {
+    kind: 'file';
+    path: string;
+};
+/**
+ * Result of classifying a requested path on disk. Anything other than
+ * `directory` or `file` is refused before the path is read: the union is the
+ * walker's own {@link ScanEntryKind} plus `missing`, so a path a caller names and
+ * a path the walk discovers pass the identical predicates.
+ */
+export type SyncPathKind = ScanEntryKind | 'missing';
+/** Re-ingest one disk file, then drop the other stored spellings of its key. */
+export interface SyncUpsertAction {
+    /** Verbatim disk path handed to `ingestFile`. */
+    filePath: string;
+    /** Verbatim stored spellings of the same comparison key, excluding `filePath`. */
+    staleStoredPaths: string[];
+    /**
+     * The profile this file must be re-ingested with, resolved once here so the
+     * CLI and MCP adapters cannot reach different conclusions. `null` means
+     * normal text ingestion, and is the only value a non-PDF ever carries.
+     */
+    visualProfile: QualityProfile | null;
+}
+/** Remove every stored spelling of one comparison key that left the disk. */
+export interface SyncPruneAction {
+    storedPaths: string[];
+}
+export interface SyncPlan {
+    upserts: SyncUpsertAction[];
+    /** Files whose stored content identity already matches the disk bytes. */
+    skipped: number;
+    prunes: SyncPruneAction[];
+}
+export interface SyncPlanInput {
+    roots: readonly string[];
+    dbPath: string;
+    /** Configured database/cache prefixes that must never be pruned. */
+    excludePaths: readonly string[];
+    platform: NodeJS.Platform;
+    request: SyncRequest;
+    diskFiles: readonly SyncDiskFile[];
+    dbRows: readonly SyncManifestRow[];
+    coverage: SyncCoverage;
+    /**
+     * Explicit per-invocation visual request. Present means every eligible PDF in
+     * scope is desired at this profile regardless of what is stored, which is also
+     * what repairs conflicting or unreadable stored state. Absent means each PDF
+     * inherits its own recorded profile.
+     */
+    visualProfile?: QualityProfile | undefined;
+}
+/** The one controlled error a failed run exposes. */
+export interface SyncError {
+    message: string;
+    /** The file, root, or requested path a failure is attributable to. */
+    filePath: string | null;
+}
+/** Append an attributable path only when the underlying message does not already contain it. */
+export declare function formatSyncError({ message, filePath }: SyncError): string;
+export interface SyncCounters {
+    upserted: number;
+    skipped: number;
+    empty: number;
+    /** Comparison keys removed from the index. Counts files, not rows, and is not part of `completed`. */
+    pruned: number;
+}
+/** One stored spelling per pruned comparison key, so a count of N reports N paths. */
+interface PrunedPaths {
+    prunedPaths: string[];
+}
+export interface SyncExecutionResult extends SyncCounters, PrunedPaths {
+    error: SyncError | null;
+}
+export interface SyncResult extends SyncCounters, PrunedPaths {
+    /** Scanner facts as data. Formatting and reporting belong to the adapters. */
+    coverage: SyncCoverage;
+    error: SyncError | null;
+}
+/** How one planned file must be ingested: run-level images, per-file profile. */
+export interface SyncIngestOptions {
+    /** `true` stores images for this file, from the current invocation alone. */
+    images: boolean;
+    /** The planner's resolved profile; `null` means normal text ingestion. */
+    visualProfile: QualityProfile | null;
+}
+/** Mutating collaborators, injected by the CLI and MCP adapters. */
+export interface SyncExecutor {
+    /**
+     * Parse, chunk, embed, build vectors, then delete-and-insert for this one
+     * file, returning the inserted chunk count. Returning `0` must leave the
+     * store untouched: the executor relies on that to keep a zero-chunk file's
+     * prior rows and hash intact.
+     */
+    ingestFile(filePath: string, options: SyncIngestOptions): Promise<number>;
+    /** Delete the rows of exactly one stored path spelling. */
+    deleteExactPath(filePath: string): Promise<number>;
+    optimize(): Promise<void>;
+}
+/** Everything {@link runSync} needs from the outside world. */
+export interface SyncCollaborators extends SyncExecutor {
+    /**
+     * Canonical form of the requested path — its parent chain resolved through
+     * symbolic links, the final component verbatim — or `null` when that chain
+     * cannot be resolved. Injected because this module performs no filesystem
+     * access; both adapters supply `canonicalizeRequestedPath` from `utils/scan.ts`.
+     */
+    canonicalizeRequestedPath(path: string): Promise<string | null>;
+    /**
+     * Classify the requested path WITHOUT reading it, applying the walker's collect
+     * predicates (`classifyRequestedPath` in `utils/scan.ts`) so both surfaces
+     * refuse the same paths.
+     */
+    classifyPath(path: string): Promise<SyncPathKind>;
+    /**
+     * Bounded scan of one root. Deliberately takes no scope predicate: a
+     * scope-pruned directory is reported in none of the coverage arrays, so a
+     * scope filter here would make unobserved regions invisible and prune unsafe.
+     */
+    scanDir(rootPath: string): Promise<SyncScanResult>;
+    /**
+     * Hash the file's current bytes, or return `null` to decline reading it because
+     * it exceeds the configured size limit. A declined file is left out of the disk
+     * manifest and recorded in `coverage.oversizedFiles`, which protects its stored
+     * rows from prune — omitting it without that record would make it look deleted.
+     */
+    hashFile(filePath: string): Promise<string | null>;
+    /** Every stored chunk row's verbatim path and hash, for the whole table. */
+    loadDbManifest(): Promise<SyncManifestRow[]>;
+}
+export interface RunSyncInput {
+    /** Configured roots in the `resolve()`-only spelling the DB keys live in. */
+    roots: readonly string[];
+    /**
+     * The same configured roots, canonicalized (realpath'd) — the security domain
+     * the requested path's canonical form is checked against. Both adapters already
+     * hold this list: the MCP server as `baseDirs`, the CLI as
+     * `config.baseDirs.baseDirs`, each the counterpart of its `roots` entry.
+     */
+    canonicalRoots: readonly string[];
+    dbPath: string;
+    excludePaths: readonly string[];
+    platform: NodeJS.Platform;
+    /** Omitted means "every configured root". */
+    requestedPath?: string | undefined;
+    /** `true` stores images for files already selected as new or changed. */
+    images?: boolean | undefined;
+    /** Explicit visual request, as on {@link SyncPlanInput}. Only the CLI supplies one. */
+    visualProfile?: QualityProfile | undefined;
+    collaborators: SyncCollaborators;
+}
+/**
+ * Decide the skip, upsert, and prune actions for one sync run.
+ *
+ * A key is pruned only when every one of four conditions holds: inside the
+ * requested scope, absent from disk, outside the excluded and managed paths,
+ * and outside every unobserved prefix. Dropping any one protects the rows.
+ *
+ * Throws when an eligible PDF's stored profiles admit no single answer; the
+ * caller must surface that before any mutation runs.
+ */
+export declare function planSync(input: SyncPlanInput): SyncPlan;
+export declare function executeSyncPlan(plan: SyncPlan, executor: SyncExecutor, images?: boolean): Promise<SyncExecutionResult>;
+/**
+ * Run one full sync. Counters and coverage facts are plain data — the caller
+ * owns printing and exit status. A run with nothing to do calls neither
+ * `ingestFile` nor `optimize`, so a true no-op never loads the model.
+ */
+export declare function runSync(input: RunSyncInput): Promise<SyncResult>;
+export {};
+//# sourceMappingURL=sync.d.ts.map

package/dist/features/sync.d.ts.map

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