@karmaniverous/jeeves-watcher 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import pino from 'pino';
 import * as _karmaniverous_jsonmap from '@karmaniverous/jsonmap';
 import { JsonMapMap } from '@karmaniverous/jsonmap';
 import { z } from 'zod';
+import Handlebars from 'handlebars';
 import { Stats } from 'node:fs';
 
 /**
@@ -78,6 +79,7 @@ declare const inferenceRuleSchema: z.ZodObject<{
     match: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     map: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>;
+    template: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** An inference rule: JSON Schema match condition, set fields, and optional JsonMap transformation. */
 type InferenceRule = z.infer<typeof inferenceRuleSchema>;
@@ -123,8 +125,13 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         match: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         map: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>;
+        template: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     maps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>>>;
+    templates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    templateHelpers: z.ZodOptional<z.ZodObject<{
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     logging: z.ZodOptional<z.ZodObject<{
         level: z.ZodOptional<z.ZodString>;
         file: z.ZodOptional<z.ZodString>;
@@ -163,6 +170,104 @@ interface EmbeddingProvider {
  */
 declare function createEmbeddingProvider(config: EmbeddingConfig, logger?: pino.Logger): EmbeddingProvider;
 
+/**
+ * @module templates/engine
+ * Handlebars template compilation, caching, and resolution (file path vs named ref vs inline).
+ */
+
+/** A compiled Handlebars template function. */
+type CompiledTemplate = HandlebarsTemplateDelegate;
+/**
+ * Resolve a template value to its source string.
+ *
+ * Resolution order:
+ * 1. Ends in `.hbs` or `.handlebars` → file path (resolve relative to configDir)
+ * 2. Matches a key in namedTemplates → named ref (recursively resolve)
+ * 3. Otherwise → inline Handlebars template string
+ *
+ * @param value - The template reference (inline, file path, or named ref).
+ * @param namedTemplates - Named template definitions from config.
+ * @param configDir - Directory to resolve relative file paths against.
+ * @param visited - Set of visited named refs for cycle detection.
+ * @returns The resolved template source string.
+ */
+declare function resolveTemplateSource(value: string, namedTemplates: Record<string, string> | undefined, configDir: string, visited?: Set<string>): string;
+/**
+ * Create a configured Handlebars instance with built-in helpers registered.
+ *
+ * @returns A Handlebars instance with helpers.
+ */
+declare function createHandlebarsInstance(): typeof Handlebars;
+/**
+ * Load custom helpers from file paths.
+ *
+ * Each file should export a default function that receives the Handlebars instance.
+ *
+ * @param hbs - The Handlebars instance.
+ * @param paths - File paths to custom helper modules.
+ * @param configDir - Directory to resolve relative paths against.
+ */
+declare function loadCustomHelpers(hbs: typeof Handlebars, paths: string[], configDir: string): Promise<void>;
+/**
+ * The template engine: holds compiled templates and renders them against context.
+ */
+declare class TemplateEngine {
+    private readonly hbs;
+    private readonly compiled;
+    constructor(hbs: typeof Handlebars);
+    /**
+     * Compile and cache a template from its source string.
+     *
+     * @param key - Cache key (rule index or named template).
+     * @param source - Handlebars template source.
+     * @returns The compiled template.
+     */
+    compile(key: string, source: string): CompiledTemplate;
+    /**
+     * Get a previously compiled template by key.
+     *
+     * @param key - The cache key.
+     * @returns The compiled template, or undefined.
+     */
+    get(key: string): CompiledTemplate | undefined;
+    /**
+     * Render a compiled template against a context.
+     *
+     * @param key - The cache key of the compiled template.
+     * @param context - The data context for rendering.
+     * @returns The rendered string, or null if the template was not found.
+     */
+    render(key: string, context: Record<string, unknown>): string | null;
+}
+
+/**
+ * @module templates/buildTemplateEngine
+ * Factory to build a TemplateEngine from config, compiling all rule templates at load time.
+ */
+
+/**
+ * Build a TemplateEngine from configuration, pre-compiling all rule templates.
+ *
+ * @param rules - The inference rules (may contain template fields).
+ * @param namedTemplates - Named template definitions from config.
+ * @param templateHelperPaths - Paths to custom helper modules.
+ * @param configDir - Directory to resolve relative paths against.
+ * @returns The configured TemplateEngine, or undefined if no templates are used.
+ */
+declare function buildTemplateEngine(rules: InferenceRule[], namedTemplates?: Record<string, string>, templateHelperPaths?: string[], configDir?: string): Promise<TemplateEngine | undefined>;
+
+/**
+ * @module templates/helpers
+ * Registers built-in Handlebars helpers for content templates.
+ */
+
+/**
+ * Register all built-in helpers on a Handlebars instance.
+ *
+ * @param hbs - The Handlebars instance.
+ */
+declare function registerBuiltinHelpers(hbs: typeof Handlebars): void;
+
 /**
  * @module rules/attributes
  * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
@@ -238,7 +343,16 @@ interface RuleLogger {
     warn(msg: string): void;
 }
 /**
- * Apply compiled inference rules to file attributes, returning merged metadata.
+ * Result of applying inference rules.
+ */
+interface ApplyRulesResult {
+    /** Merged metadata from all matching rules. */
+    metadata: Record<string, unknown>;
+    /** Rendered template content from the last matching rule with a template, or null. */
+    renderedContent: string | null;
+}
+/**
+ * Apply compiled inference rules to file attributes, returning merged metadata and optional rendered content.
  *
  * Rules are evaluated in order; later rules override earlier ones.
  * If a rule has a `map`, the JsonMap transformation is applied after `set` resolution,
@@ -248,9 +362,11 @@ interface RuleLogger {
  * @param attributes - The file attributes to match against.
  * @param namedMaps - Optional record of named JsonMap definitions.
  * @param logger - Optional logger for warnings (falls back to console.warn).
- * @returns The merged metadata from all matching rules.
+ * @param templateEngine - Optional template engine for rendering content templates.
+ * @param configDir - Optional config directory for resolving .json map file paths.
+ * @returns The merged metadata and optional rendered content.
  */
-declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger): Promise<Record<string, unknown>>;
+declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger, templateEngine?: TemplateEngine, configDir?: string): Promise<ApplyRulesResult>;
 
 /**
  * A point to upsert into the vector store.
@@ -398,6 +514,8 @@ interface ProcessorConfig {
     chunkOverlap?: number;
     /** Named JsonMap definitions for rule transformations. */
     maps?: Record<string, JsonMapMap>;
+    /** Config directory for resolving relative file paths. */
+    configDir?: string;
 }
 /**
  * Core document processing pipeline.
@@ -410,6 +528,7 @@ declare class DocumentProcessor {
     private readonly vectorStore;
     private compiledRules;
     private readonly logger;
+    private templateEngine?;
     /**
      * Create a new DocumentProcessor.
      *
@@ -418,8 +537,9 @@ declare class DocumentProcessor {
      * @param vectorStore - The vector store client.
      * @param compiledRules - The compiled inference rules.
      * @param logger - The logger instance.
+     * @param templateEngine - Optional template engine for content templates.
      */
-    constructor(config: ProcessorConfig, embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: CompiledRule[], logger: pino.Logger);
+    constructor(config: ProcessorConfig, embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: CompiledRule[], logger: pino.Logger, templateEngine?: TemplateEngine);
     /**
      * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
      *
@@ -454,7 +574,13 @@ declare class DocumentProcessor {
      *
      * @param compiledRules - The newly compiled rules.
      */
-    updateRules(compiledRules: CompiledRule[]): void;
+    /**
+     * Update compiled inference rules and optionally the template engine.
+     *
+     * @param compiledRules - The newly compiled rules.
+     * @param templateEngine - Optional updated template engine.
+     */
+    updateRules(compiledRules: CompiledRule[], templateEngine?: TemplateEngine): void;
 }
 
 /**
@@ -693,6 +819,7 @@ declare class FileSystemWatcher {
     private readonly logger;
     private readonly health;
     private readonly gitignoreFilter?;
+    private globMatches;
     private watcher;
     /**
      * Create a new FileSystemWatcher.
@@ -732,6 +859,11 @@ declare class FileSystemWatcher {
     private wrapProcessing;
 }
 
+/**
+ * @module app/factories
+ * Component factory interfaces and defaults for {@link JeevesWatcher}. Override in tests to inject mocks.
+ */
+
 /**
  * Component factories for {@link JeevesWatcher}. Override in tests to inject mocks.
  */
@@ -747,7 +879,7 @@ interface JeevesWatcherFactories {
     /** Compile inference rules from config. */
     compileRules: typeof compileRules;
     /** Create a document processor for file ingestion. */
-    createDocumentProcessor: (config: ConstructorParameters<typeof DocumentProcessor>[0], embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: ConstructorParameters<typeof DocumentProcessor>[3], logger: pino.Logger) => DocumentProcessor;
+    createDocumentProcessor: (config: ConstructorParameters<typeof DocumentProcessor>[0], embeddingProvider: EmbeddingProvider, vectorStore: VectorStoreClient, compiledRules: ConstructorParameters<typeof DocumentProcessor>[3], logger: pino.Logger, templateEngine?: ConstructorParameters<typeof DocumentProcessor>[5]) => DocumentProcessor;
     /** Create an event queue for batching file-system events. */
     createEventQueue: (options: ConstructorParameters<typeof EventQueue>[0]) => EventQueue;
     /** Create a file-system watcher for the configured watch paths. */
@@ -755,9 +887,25 @@ interface JeevesWatcherFactories {
     /** Create the HTTP API server. */
     createApiServer: typeof createApiServer;
 }
+
 /**
- * Main application class that wires together all components.
+ * @module app/startFromConfig
+ * Convenience entry point: loads config from disk and starts a {@link JeevesWatcher}.
+ */
+
+/**
+ * Create and start a JeevesWatcher from a config file path.
+ *
+ * @param configPath - Optional path to the configuration file.
+ * @returns The running JeevesWatcher instance.
+ */
+declare function startFromConfig(configPath?: string): Promise<JeevesWatcher>;
+
+/**
+ * @module app
+ * Main application orchestrator. Wires components, manages lifecycle (start/stop/reload).
  */
+
 /**
  * Runtime options for {@link JeevesWatcher} that aren't serializable in config.
  */
@@ -796,17 +944,13 @@ declare class JeevesWatcher {
      * Gracefully stop all components.
      */
     stop(): Promise<void>;
+    private initEmbeddingAndStore;
+    private createWatcher;
+    private startApiServer;
     private startConfigWatch;
     private stopConfigWatch;
     private reloadConfig;
 }
-/**
- * Create and start a JeevesWatcher from a config file path.
- *
- * @param configPath - Optional path to the configuration file.
- * @returns The running JeevesWatcher instance.
- */
-declare function startFromConfig(configPath?: string): Promise<JeevesWatcher>;
 
 /**
  * Load the jeeves-watcher configuration.
@@ -891,5 +1035,5 @@ declare function deleteMetadata(filePath: string, metadataDir: string): Promise<
  */
 declare function pointId(filePath: string, chunkIndex?: number): string;
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loggingConfigSchema, metadataPath, pointId, readMetadata, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
-export type { ApiConfig, ApiServerOptions, CollectionInfo, CompiledRule, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, FileSystemWatcherOptions, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };
+export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, TemplateEngine, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
+export type { ApiConfig, ApiServerOptions, ApplyRulesResult, CollectionInfo, CompiledRule, CompiledTemplate, ConfigWatchConfig, EmbeddingConfig, EmbeddingProvider, EventQueueOptions, ExtractedText, FileAttributes, FileSystemWatcherOptions, InferenceRule, JeevesWatcherConfig, JeevesWatcherFactories, JeevesWatcherRuntimeOptions, LoggingConfig, PayloadFieldSchema, ProcessFn, ProcessorConfig, RuleLogger, ScrolledPoint, SearchResult, SystemHealthOptions, VectorPoint, VectorStoreConfig, WatchConfig, WatchEvent };