@karmaniverous/jeeves-watcher 0.15.1 → 0.16.0

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import * as _karmaniverous_jsonmap from '@karmaniverous/jsonmap';
 import { JsonMapMap } from '@karmaniverous/jsonmap';
 import { z } from 'zod';
 import Handlebars from 'handlebars';
+import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
 import { Stats } from 'node:fs';
 
 /**
@@ -300,6 +301,7 @@ declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.
  * @module enrichment/EnrichmentStore
  * SQLite-backed enrichment metadata store. Persists path-keyed metadata at stateDir/enrichments.sqlite. Atomic writes, supports move.
  */
+
 /**
  * Interface for enrichment metadata persistence.
  */
@@ -322,12 +324,13 @@ interface EnrichmentStoreInterface {
  */
 declare class EnrichmentStore implements EnrichmentStoreInterface {
     private readonly db;
+    private readonly logger?;
     /**
      * Create or open the enrichment store.
      *
      * @param stateDir - Directory for the SQLite database file.
      */
-    constructor(stateDir: string);
+    constructor(stateDir: string, logger?: pino.Logger);
     get(path: string): Record<string, unknown> | null;
     set(path: string, metadata: Record<string, unknown>): void;
     delete(path: string): void;
@@ -806,6 +809,57 @@ declare class VirtualRuleStore {
     get size(): number;
 }
 
+/**
+ * @module util/BinaryFileStore
+ * Binary-backed read/modify/write store with in-memory caching and debounced flush.
+ *
+ * Persists a single JS object to disk using V8 structured clone serialization.
+ * I/O: synchronous fs read/write.
+ */
+
+/** Options for {@link BinaryFileStore}. */
+interface BinaryFileStoreOptions {
+    /** Path to the binary file on disk. */
+    filePath: string;
+    /** Logger for warnings. */
+    logger: pino.Logger;
+    /** Debounce interval in ms for flushing dirty state. Default: 5000. */
+    flushDebounceMs?: number;
+}
+/**
+ * Base class for binary file stores.
+ *
+ * @typeParam T - The stored data structure.
+ */
+declare abstract class BinaryFileStore<T> {
+    /** Path to the binary file on disk. */
+    protected readonly filePath: string;
+    /** In-memory cache of the file contents, or `null` if not yet loaded. */
+    protected cache: T | null;
+    /** Logger instance for warnings and diagnostics. */
+    protected readonly logger: pino.Logger;
+    private readonly flushDebounceMs;
+    private flushTimer;
+    private dirty;
+    protected constructor(options: BinaryFileStoreOptions);
+    /** Create an empty default value when file is missing or unreadable. */
+    protected abstract createEmpty(): T;
+    /** Load from disk into cache if not already loaded. */
+    protected load(): T;
+    /**
+     * Mark the store dirty and schedule a debounced flush.
+     */
+    protected markDirty(): void;
+    /**
+     * Flush cache to disk if dirty.
+     *
+     * Uses an atomic write (tmp + rename) to avoid partial files.
+     */
+    flush(): void;
+    /** Stop any pending scheduled flush. Does not flush automatically. */
+    stopAutoFlush(): void;
+}
+
 /**
  * @module values/ValuesManager
  * Manages per-rule distinct metadata value tracking. Persists to disk with in-memory caching and sorted deduplication.
@@ -816,7 +870,7 @@ type ValuesIndex = Record<string, Record<string, unknown[]>>;
 /**
  * Manages a persistent values.json file tracking distinct metadata values per rule.
  */
-declare class ValuesManager extends JsonFileStore<ValuesIndex> {
+declare class ValuesManager extends BinaryFileStore<ValuesIndex> {
     constructor(stateDir: string, logger: pino.Logger);
     protected createEmpty(): ValuesIndex;
     /** Check if a value is a trackable primitive (string, number, boolean). */
@@ -997,6 +1051,7 @@ interface VectorStore {
  */
 declare class VectorStoreClient implements VectorStore {
     private readonly client;
+    private writeClient;
     private readonly clientConfig;
     private readonly collectionName;
     private readonly dims;
@@ -1037,12 +1092,12 @@ declare class VectorStoreClient implements VectorStore {
      * @param fn - Async function to retry.
      */
     private retryOperation;
+    private getWriteClient;
     /**
      * Upsert points into the collection.
      *
-     * Uses a fresh QdrantClient per attempt to avoid stale keep-alive connections.
-     * Between embedding calls and upserts, idle connections may be closed by the
-     * server, causing ECONNRESET on reuse.
+     * Uses the shared client. On retry (after ECONNRESET from stale connections),
+     * creates a fresh client to recover.
      *
      * @param points - The points to upsert.
      */
@@ -1050,7 +1105,7 @@ declare class VectorStoreClient implements VectorStore {
     /**
      * Delete points by their IDs.
      *
-     * Uses a fresh QdrantClient per attempt to avoid stale keep-alive connections.
+     * Uses the shared client. On retry, creates a fresh client to recover.
      *
      * @param ids - The point IDs to delete.
      */
@@ -1360,6 +1415,7 @@ declare class EventQueue {
     private readonly concurrency;
     private readonly rateLimitPerMinute?;
     private started;
+    private paused;
     private active;
     private readonly debounceTimers;
     private readonly latestByKey;
@@ -1368,6 +1424,7 @@ declare class EventQueue {
     private tokens;
     private lastRefillMs;
     private drainWaiters;
+    private idleWorkerWaiters;
     /**
      * Create an event queue.
      *
@@ -1385,12 +1442,28 @@ declare class EventQueue {
      * Start processing events.
      */
     process(): void;
+    /**
+     * Pause processing events. Events can still be enqueued but will not be processed.
+     */
+    pause(): void;
+    /**
+     * Resume processing events.
+     */
+    resume(): void;
     /**
      * Wait for the queue to become idle (no pending debounces, no queued items, no active work).
      *
      * @returns A promise that resolves when the queue is drained.
      */
     drain(): Promise<void>;
+    /**
+     * Wait until there is no in-flight work.
+     *
+     * Unlike {@link drain}, this does NOT wait for debounced or queued items to be empty.
+     * It's useful when you need to temporarily quiesce outgoing work without losing
+     * or rejecting new enqueues.
+     */
+    waitForIdleWorkers(): Promise<void>;
     private push;
     private refillTokens;
     private takeToken;
@@ -1398,6 +1471,7 @@ declare class EventQueue {
     private pump;
     private isIdle;
     private maybeResolveDrain;
+    private maybeResolveIdleWorkers;
 }
 
 /**
@@ -1663,6 +1737,8 @@ interface ApiServerOptions {
     initialScanTracker?: InitialScanTracker;
     /** Filesystem watcher instance for /walk endpoint (in-memory file list). */
     fileSystemWatcher?: FileSystemWatcher;
+    /** Getter for live filesystem watcher access after hot-reload rebuilds. */
+    getFileSystemWatcher?: () => FileSystemWatcher | undefined;
     /** Optional enrichment store for persisted enrichment metadata. */
     enrichmentStore?: EnrichmentStoreInterface;
 }
@@ -1726,7 +1802,12 @@ interface JeevesWatcherFactories {
 /**
  * Create and start a JeevesWatcher from a config file path.
  *
- * @param configPath - Optional path to the configuration file.
+ * When no explicit config path is given, auto-migrates the legacy flat
+ * config (`jeeves-watcher.config.json`) to the namespaced convention
+ * (`jeeves-watcher/config.json`) before loading.
+ *
+ * @param configPath - Optional explicit path to the configuration file.
+ *   When provided, the file is loaded as-is (no migration).
  * @returns The running JeevesWatcher instance.
  */
 declare function startFromConfig(configPath?: string): Promise<JeevesWatcher>;
@@ -1791,6 +1872,18 @@ declare class JeevesWatcher {
  */
 declare function loadConfig(configPath?: string): Promise<JeevesWatcherConfig>;
 
+/**
+ * @module descriptor
+ * Jeeves Component Descriptor for the watcher service. Single source of truth
+ * consumed by core factories (CLI, plugin tools, HTTP handlers, service manager).
+ */
+
+/**
+ * Watcher component descriptor. Single source of truth for service identity,
+ * config schema, and extension points consumed by core factories.
+ */
+declare const watcherDescriptor: JeevesComponentDescriptor;
+
 /**
  * @module extractors
  *
@@ -1836,5 +1929,5 @@ declare function contentHash(text: string): string;
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema };
+export { ContentHashCache, DocumentProcessor, EnrichmentStore, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, mergeEnrichment, pointId, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, watcherDescriptor };
 export type { AllHelpersIntrospection, ApiConfig, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingConfig, EmbeddingProvider, EnrichmentStoreInterface, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InferenceRule, InitialScanStatus, IssueRecord, IssuesFile, JeevesWatcherConfig, JeevesWatcherConfigInput, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, ProviderFactory, ReindexStatus, RenderResult, RuleLogger, ScrollPageResult, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, VectorStoreConfig, WatchConfig, WatchEvent };