@karmaniverous/jeeves-watcher 0.9.9 → 0.10.1

package/dist/index.d.ts

@@ -31,7 +31,7 @@ type WatchConfig = z.infer<typeof watchConfigSchema>;
 declare const configWatchConfigSchema: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
     debounceMs: z.ZodOptional<z.ZodNumber>;
-    reindex: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"issues">, z.ZodLiteral<"full">]>>;
+    reindex: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"issues">, z.ZodLiteral<"full">, z.ZodLiteral<"rules">]>>;
 }, z.core.$strip>;
 /** Configuration file watch settings controlling auto-reload behavior on config changes. */
 type ConfigWatchConfig = z.infer<typeof configWatchConfigSchema>;
@@ -117,7 +117,7 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
     configWatch: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         debounceMs: z.ZodOptional<z.ZodNumber>;
-        reindex: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"issues">, z.ZodLiteral<"full">]>>;
+        reindex: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"issues">, z.ZodLiteral<"full">, z.ZodLiteral<"rules">]>>;
     }, z.core.$strip>>;
     embedding: z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
@@ -140,7 +140,6 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         port: z.ZodOptional<z.ZodNumber>;
         cacheTtlMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
-    extractors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     stateDir: z.ZodOptional<z.ZodString>;
     inferenceRules: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
@@ -188,7 +187,6 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         callbackUrl: z.ZodOptional<z.ZodURL>;
         concurrency: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
-    slots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     search: z.ZodOptional<z.ZodObject<{
         scoreThresholds: z.ZodOptional<z.ZodObject<{
             strong: z.ZodNumber;
@@ -218,6 +216,7 @@ type JeevesWatcherConfigInput = z.infer<typeof jeevesWatcherConfigSchema>;
  * After `loadConfig`, all string rule entries have been resolved to `InferenceRule` objects.
  */
 type JeevesWatcherConfig = Omit<JeevesWatcherConfigInput, 'inferenceRules'> & {
+    /** Resolved inference rules (string file paths have been loaded as InferenceRule objects). */
     inferenceRules?: InferenceRule[];
 };
 
@@ -290,6 +289,38 @@ type ProviderFactory = (config: EmbeddingConfig, logger?: pino.Logger) => Embedd
  */
 declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger, additionalProviders?: Map<string, ProviderFactory>): EmbeddingProvider;
 
+/**
+ * Processor-level gitignore filter. Checks file paths against the nearest
+ * `.gitignore` chain in git repositories.
+ */
+declare class GitignoreFilter {
+    private repos;
+    /**
+     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
+     *
+     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
+     */
+    constructor(watchPaths: string[]);
+    /**
+     * Scan paths for git repos and their `.gitignore` files.
+     */
+    private scan;
+    /**
+     * Check whether a file path is ignored by any applicable `.gitignore`.
+     *
+     * @param filePath - Absolute file path to check.
+     * @returns `true` if the file should be ignored.
+     */
+    isIgnored(filePath: string): boolean;
+    /**
+     * Invalidate and re-parse a specific `.gitignore` file.
+     * Call when a `.gitignore` file is added, changed, or removed.
+     *
+     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
+     */
+    invalidate(gitignorePath: string): void;
+}
+
 /**
  * @module helpers/introspect
  * JSDoc introspection for helper modules. Extracts function exports and their descriptions.
@@ -436,6 +467,7 @@ declare function loadCustomHelpers(hbs: typeof Handlebars, helpers: Record<strin
  * The template engine: holds compiled templates and renders them against context.
  */
 declare class TemplateEngine {
+    /** The Handlebars instance used for template compilation and rendering. */
     readonly hbs: typeof Handlebars;
     private readonly compiled;
     constructor(hbs: typeof Handlebars);
@@ -617,6 +649,54 @@ interface ApplyRulesOptions {
  */
 declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, options?: ApplyRulesOptions): Promise<ApplyRulesResult>;
 
+/**
+ * @module rules/virtualRules
+ * In-memory virtual rule store for externally registered inference rules.
+ *
+ * Virtual rules are registered at runtime by external consumers (e.g., OpenClaw plugins)
+ * and merge into the inference pipeline alongside config-file rules.
+ * They survive config reloads but NOT service restarts.
+ */
+
+/**
+ * In-memory store for virtual inference rules.
+ *
+ * Virtual rules are appended AFTER config-file rules in evaluation order.
+ * Since inference uses last-match-wins for overlapping fields,
+ * virtual rules take precedence over config rules when both match the same file.
+ */
+declare class VirtualRuleStore {
+    private readonly entries;
+    /**
+     * Register virtual rules from an external source.
+     * Idempotent: re-registering with the same source replaces previous rules.
+     *
+     * @param source - Unique identifier for the rule source.
+     * @param rules - Inference rule definitions to register.
+     */
+    register(source: string, rules: InferenceRule[]): void;
+    /**
+     * Remove virtual rules by source.
+     *
+     * @param source - The source identifier to unregister.
+     * @returns true if rules were found and removed.
+     */
+    unregister(source: string): boolean;
+    /**
+     * Get all compiled virtual rules in registration order.
+     */
+    getCompiled(): CompiledRule[];
+    /**
+     * Get all raw virtual rule definitions grouped by source.
+     * Used by the merged virtual document.
+     */
+    getAll(): Record<string, InferenceRule[]>;
+    /** Check if any virtual rules are registered. */
+    get isEmpty(): boolean;
+    /** Total number of virtual rules across all sources. */
+    get size(): number;
+}
+
 /**
  * @module values/ValuesManager
  * Manages per-rule distinct metadata value tracking. Persists to disk with in-memory caching and sorted deduplication.
@@ -1182,182 +1262,45 @@ declare class EventQueue {
 }
 
 /**
- * @module rules/virtualRules
- * In-memory virtual rule store for externally registered inference rules.
- *
- * Virtual rules are registered at runtime by external consumers (e.g., OpenClaw plugins)
- * and merge into the inference pipeline alongside config-file rules.
- * They survive config reloads but NOT service restarts.
- */
-
-/**
- * In-memory store for virtual inference rules.
- *
- * Virtual rules are appended AFTER config-file rules in evaluation order.
- * Since inference uses last-match-wins for overlapping fields,
- * virtual rules take precedence over config rules when both match the same file.
- */
-declare class VirtualRuleStore {
-    private readonly entries;
-    /**
-     * Register virtual rules from an external source.
-     * Idempotent: re-registering with the same source replaces previous rules.
-     *
-     * @param source - Unique identifier for the rule source.
-     * @param rules - Inference rule definitions to register.
-     */
-    register(source: string, rules: InferenceRule[]): void;
-    /**
-     * Remove virtual rules by source.
-     *
-     * @param source - The source identifier to unregister.
-     * @returns true if rules were found and removed.
-     */
-    unregister(source: string): boolean;
-    /**
-     * Get all compiled virtual rules in registration order.
-     */
-    getCompiled(): CompiledRule[];
-    /**
-     * Get all raw virtual rule definitions grouped by source.
-     * Used by the merged virtual document.
-     */
-    getAll(): Record<string, InferenceRule[]>;
-    /** Check if any virtual rules are registered. */
-    get isEmpty(): boolean;
-    /** Total number of virtual rules across all sources. */
-    get size(): number;
-}
-
-/**
- * @module api/ReindexTracker
- * Tracks reindex operation state for status reporting. Single instance shared across handlers.
+ * @module api/InitialScanTracker
+ * Tracks initial filesystem scan state for status reporting.
  */
-/** Reindex status snapshot for API consumers. */
-interface ReindexStatus {
-    /** Whether a reindex operation is currently in progress. */
+/** Initial scan status snapshot for API consumers. */
+interface InitialScanStatus {
+    /** Whether the initial scan is currently in progress. */
     active: boolean;
-    /** The active reindex scope (when {@link active} is true). */
-    scope?: string;
-    /** ISO 8601 timestamp when the current reindex started (when {@link active} is true). */
+    /** Number of files matched by watch globs. */
+    filesMatched?: number;
+    /** Number of files enqueued for processing so far. */
+    filesEnqueued?: number;
+    /** ISO 8601 timestamp when the scan started. */
     startedAt?: string;
-    /** Number of files processed so far (when {@link active} is true). */
-    filesProcessed?: number;
-    /** Total number of files to process (when {@link active} is true). */
-    totalFiles?: number;
+    /** ISO 8601 timestamp when the scan completed. */
+    completedAt?: string;
+    /** Total scan duration in milliseconds. */
+    durationMs?: number;
 }
 /**
- * Tracks the state of reindex operations.
+ * Tracks the state of the initial filesystem scan after service start.
  */
-declare class ReindexTracker {
+declare class InitialScanTracker {
     private _active;
-    private _scope?;
+    private _filesMatched;
+    private _filesEnqueued;
     private _startedAt?;
-    private _filesProcessed;
-    private _totalFiles;
-    /** Mark a reindex as started. */
-    start(scope: 'issues' | 'full'): void;
-    /** Set the total number of files to process. */
-    setTotal(total: number): void;
+    private _completedAt?;
+    private _durationMs?;
+    private _started;
+    /** Mark the initial scan as started. */
+    start(): void;
+    /** Set the total number of matched files. */
+    setMatched(count: number): void;
     /** Increment the processed file count. */
-    incrementProcessed(): void;
-    /** Mark the current reindex as complete. */
+    incrementEnqueued(): void;
+    /** Mark the scan as complete. */
     complete(): void;
-    /** Get current reindex status. */
-    getStatus(): ReindexStatus;
-}
-
-/**
- * @module api
- * Fastify API server factory. Registers all route handlers and returns an unstarted server instance.
- */
-
-/**
- * Options for {@link createApiServer}.
- */
-interface ApiServerOptions {
-    /** The document processor. */
-    processor: DocumentProcessorInterface;
-    /** The vector store client. */
-    vectorStore: VectorStoreClient;
-    /** The embedding provider. */
-    embeddingProvider: EmbeddingProvider;
-    /** The event queue. */
-    queue: EventQueue;
-    /** The application configuration. */
-    config: JeevesWatcherConfig;
-    /** The logger instance. */
-    logger: pino.Logger;
-    /** The issues manager. */
-    issuesManager: IssuesManager;
-    /** The values manager. */
-    valuesManager: ValuesManager;
-    /** The reindex tracker (optional, created if not provided). */
-    reindexTracker?: ReindexTracker;
-    /** Path to the config file on disk. */
-    configPath: string;
-    /** Helper introspection for merged document. */
-    helperIntrospection?: AllHelpersIntrospection;
-    /** Virtual rule store for externally registered inference rules. */
-    virtualRuleStore?: VirtualRuleStore;
-}
-/**
- * Create the Fastify API server with all routes registered.
- *
- * The returned instance is not yet listening — call `server.listen()` to start.
- *
- * @param options - The server options.
- * @returns A configured Fastify instance.
- */
-declare function createApiServer(options: ApiServerOptions): FastifyInstance;
-
-/**
- * @module logger
- * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
- */
-
-/**
- * Create a pino logger instance.
- *
- * @param config - Optional logging configuration.
- * @returns A configured pino logger.
- */
-declare function createLogger(config?: LoggingConfig): pino.Logger;
-
-/**
- * @module gitignore
- * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
- */
-/**
- * Processor-level gitignore filter. Checks file paths against the nearest
- * `.gitignore` chain in git repositories.
- */
-declare class GitignoreFilter {
-    private repos;
-    /**
-     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
-     *
-     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
-     */
-    constructor(watchPaths: string[]);
-    /**
-     * Scan paths for git repos and their `.gitignore` files.
-     */
-    private scan;
-    /**
-     * Check whether a file path is ignored by any applicable `.gitignore`.
-     *
-     * @param filePath - Absolute file path to check.
-     * @returns `true` if the file should be ignored.
-     */
-    isIgnored(filePath: string): boolean;
-    /**
-     * Invalidate and re-parse a specific `.gitignore` file.
-     * Call when a `.gitignore` file is added, changed, or removed.
-     *
-     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
-     */
-    invalidate(gitignorePath: string): void;
+    /** Get current scan status. */
+    getStatus(): InitialScanStatus;
 }
 
 /**
@@ -1431,6 +1374,8 @@ interface FileSystemWatcherOptions {
     onFatalError?: (error: unknown) => void;
     /** Optional gitignore filter for processor-level filtering. */
     gitignoreFilter?: GitignoreFilter;
+    /** Optional tracker for initial scan visibility in /status. */
+    initialScanTracker?: InitialScanTracker;
 }
 /**
  * Filesystem watcher that maps chokidar events to the processing queue.
@@ -1442,6 +1387,7 @@ declare class FileSystemWatcher {
     private readonly logger;
     private readonly health;
     private readonly gitignoreFilter?;
+    private readonly initialScanTracker?;
     private globMatches;
     private watcher;
     /**
@@ -1458,6 +1404,17 @@ declare class FileSystemWatcher {
      * Start watching the filesystem and processing events.
      */
     start(): void;
+    /**
+     * Get the list of all currently watched file paths (absolute).
+     *
+     * Uses chokidar's in-memory `getWatched()` state — no filesystem I/O.
+     * Returns an empty array if the watcher hasn't been started.
+     */
+    getWatchedFiles(): string[];
+    /**
+     * Whether the initial filesystem scan is complete.
+     */
+    get isReady(): boolean;
     /**
      * Stop the filesystem watcher.
      */
@@ -1482,6 +1439,109 @@ declare class FileSystemWatcher {
     private wrapProcessing;
 }
 
+/**
+ * @module api/ReindexTracker
+ * Tracks reindex operation state for status reporting. Single instance shared across handlers.
+ */
+/** Reindex status snapshot for API consumers. */
+interface ReindexStatus {
+    /** Whether a reindex operation is currently in progress. */
+    active: boolean;
+    /** The active reindex scope (when {@link active} is true). */
+    scope?: string;
+    /** ISO 8601 timestamp when the current reindex started (when {@link active} is true). */
+    startedAt?: string;
+    /** Number of files processed so far (when {@link active} is true). */
+    filesProcessed?: number;
+    /** Total number of files to process (when {@link active} is true). */
+    totalFiles?: number;
+}
+/**
+ * Tracks the state of reindex operations.
+ */
+declare class ReindexTracker {
+    private _active;
+    private _scope?;
+    private _startedAt?;
+    private _filesProcessed;
+    private _totalFiles;
+    /** Mark a reindex as started. */
+    start(scope: string): void;
+    /** Set the total number of files to process. */
+    setTotal(total: number): void;
+    /** Increment the processed file count. */
+    incrementProcessed(): void;
+    /** Mark the current reindex as complete. */
+    complete(): void;
+    /** Get current reindex status. */
+    getStatus(): ReindexStatus;
+}
+
+/**
+ * @module api
+ * Fastify API server factory. Registers all route handlers and returns an unstarted server instance.
+ */
+
+/**
+ * Options for {@link createApiServer}.
+ */
+interface ApiServerOptions {
+    /** The document processor. */
+    processor: DocumentProcessorInterface;
+    /** The vector store client. */
+    vectorStore: VectorStoreClient;
+    /** The embedding provider. */
+    embeddingProvider: EmbeddingProvider;
+    /** The event queue. */
+    queue: EventQueue;
+    /** The application configuration. */
+    config: JeevesWatcherConfig;
+    /** The logger instance. */
+    logger: pino.Logger;
+    /** The issues manager. */
+    issuesManager: IssuesManager;
+    /** The values manager. */
+    valuesManager: ValuesManager;
+    /** The reindex tracker (optional, created if not provided). */
+    reindexTracker?: ReindexTracker;
+    /** Path to the config file on disk. */
+    configPath: string;
+    /** Helper introspection for merged document. */
+    helperIntrospection?: AllHelpersIntrospection;
+    /** Virtual rule store for externally registered inference rules. */
+    virtualRuleStore?: VirtualRuleStore;
+    /** Gitignore filter for reindex path validation. */
+    gitignoreFilter?: GitignoreFilter;
+    /** Service version string for /status endpoint. */
+    version?: string;
+    /** Initial scan tracker for /status visibility. */
+    initialScanTracker?: InitialScanTracker;
+    /** Filesystem watcher instance for /walk endpoint (in-memory file list). */
+    fileSystemWatcher?: FileSystemWatcher;
+}
+/**
+ * Create the Fastify API server with all routes registered.
+ *
+ * The returned instance is not yet listening — call `server.listen()` to start.
+ *
+ * @param options - The server options.
+ * @returns A configured Fastify instance.
+ */
+declare function createApiServer(options: ApiServerOptions): FastifyInstance;
+
+/**
+ * @module logger
+ * Creates pino logger instances. I/O: optionally writes logs to file via pino/file transport. Defaults to stdout at info level.
+ */
+
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logging configuration.
+ * @returns A configured pino logger.
+ */
+declare function createLogger(config?: LoggingConfig): pino.Logger;
+
 /**
  * @module app/factories
  * Component factory interfaces and defaults for {@link JeevesWatcher}. Override in tests to inject mocks.
@@ -1556,6 +1616,9 @@ declare class JeevesWatcher {
     private virtualRuleStore;
     private vectorStore;
     private embeddingProvider;
+    private gitignoreFilter;
+    private readonly initialScanTracker;
+    private readonly version;
     /** Create a new JeevesWatcher instance. */
     constructor(config: JeevesWatcherConfig, configPath?: string, factories?: Partial<JeevesWatcherFactories>, runtimeOptions?: JeevesWatcherRuntimeOptions);
     /**
@@ -1658,5 +1721,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
-export type { AllHelpersIntrospection, ApiConfig, ApiServerOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, Extractor, FileAttributes, FileSystemWatcherOptions, HelperModuleIntrospection, InferenceRule, IssueRecord, IssuesFile, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, ProviderFactory, ReindexStatus, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, ValuesIndex, VectorPoint, VectorStore, VectorStoreConfig, WatchConfig, WatchEvent };
+export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, InitialScanTracker, IssuesManager, JeevesWatcher, ReindexTracker, SystemHealth, TemplateEngine, ValuesManager, VectorStoreClient, VirtualRuleStore, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, issueRecordSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
+export type { AllHelpersIntrospection, ApiConfig, ApiServerOptions, ApplyRulesOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, DocumentProcessorDeps, DocumentProcessorInterface, EmbeddingConfig, EmbeddingProvider, 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 };