@karmaniverous/jeeves-watcher 0.3.0 → 0.4.0

package/dist/index.iife.js

@@ -1,4 +1,4 @@
-(function (exports, Fastify, promises, node_path, picomatch, radash, node_crypto, cosmiconfig, zod, jsonmap, googleGenai, node_fs, ignore, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest, chokidar) {
+(function (exports, Fastify, promises, node_path, picomatch, radash, node_crypto, node_fs, ignore, Handlebars, dayjs, hastUtilToMdast, mdastUtilFromAdf, mdastUtilToMarkdown, rehypeParse, unified, chokidar, cosmiconfig, zod, jsonmap, googleGenai, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest) {
     'use strict';
 
     function _interopNamespaceDefault(e) {
@@ -416,6 +416,486 @@
         return app;
     }
 
+    /**
+     * @module gitignore
+     * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
+     */
+    /**
+     * Find the git repo root by walking up from `startDir` looking for `.git/`.
+     * Returns `undefined` if no repo is found.
+     */
+    function findRepoRoot(startDir) {
+        let dir = node_path.resolve(startDir);
+        const root = node_path.resolve('/');
+        while (dir !== root) {
+            if (node_fs.existsSync(node_path.join(dir, '.git')) &&
+                node_fs.statSync(node_path.join(dir, '.git')).isDirectory()) {
+                return dir;
+            }
+            const parent = node_path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return undefined;
+    }
+    /**
+     * Convert a watch path (directory, file path, or glob) to a concrete directory
+     * that can be scanned for a repo root.
+     */
+    function watchPathToScanDir(watchPath) {
+        const absPath = node_path.resolve(watchPath);
+        try {
+            return node_fs.statSync(absPath).isDirectory() ? absPath : node_path.dirname(absPath);
+        }
+        catch {
+            // ignore
+        }
+        // If this is a glob, fall back to the non-glob prefix.
+        const globMatch = /[*?[{]/.exec(watchPath);
+        if (!globMatch)
+            return undefined;
+        const prefix = watchPath.slice(0, globMatch.index);
+        const trimmed = prefix.trim();
+        const baseDir = trimmed.length === 0
+            ? '.'
+            : trimmed.endsWith('/') || trimmed.endsWith('\\')
+                ? trimmed
+                : node_path.dirname(trimmed);
+        const resolved = node_path.resolve(baseDir);
+        if (!node_fs.existsSync(resolved))
+            return undefined;
+        return resolved;
+    }
+    /**
+     * Recursively find all `.gitignore` files under `dir`.
+     * Skips `.git` and `node_modules` directories for performance.
+     */
+    function findGitignoreFiles(dir) {
+        const results = [];
+        const gitignorePath = node_path.join(dir, '.gitignore');
+        if (node_fs.existsSync(gitignorePath)) {
+            results.push(gitignorePath);
+        }
+        let entries;
+        try {
+            entries = node_fs.readdirSync(dir);
+        }
+        catch {
+            return results;
+        }
+        for (const entry of entries) {
+            if (entry === '.git' || entry === 'node_modules')
+                continue;
+            const fullPath = node_path.join(dir, entry);
+            try {
+                if (node_fs.statSync(fullPath).isDirectory()) {
+                    results.push(...findGitignoreFiles(fullPath));
+                }
+            }
+            catch {
+                // Skip inaccessible entries
+            }
+        }
+        return results;
+    }
+    /**
+     * Parse a `.gitignore` file into an `ignore` instance.
+     */
+    function parseGitignore(gitignorePath) {
+        const content = node_fs.readFileSync(gitignorePath, 'utf8');
+        return ignore().add(content);
+    }
+    /**
+     * Normalize a path to use forward slashes (required by `ignore` package).
+     */
+    function toForwardSlash(p) {
+        return p.replace(/\\/g, '/');
+    }
+    /**
+     * Processor-level gitignore filter. Checks file paths against the nearest
+     * `.gitignore` chain in git repositories.
+     */
+    class GitignoreFilter {
+        repos = new Map();
+        /**
+         * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
+         *
+         * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
+         */
+        constructor(watchPaths) {
+            this.scan(watchPaths);
+        }
+        /**
+         * Scan paths for git repos and their `.gitignore` files.
+         */
+        scan(watchPaths) {
+            this.repos.clear();
+            const scannedDirs = new Set();
+            for (const watchPath of watchPaths) {
+                const scanDir = watchPathToScanDir(watchPath);
+                if (!scanDir)
+                    continue;
+                if (scannedDirs.has(scanDir))
+                    continue;
+                scannedDirs.add(scanDir);
+                const repoRoot = findRepoRoot(scanDir);
+                if (!repoRoot)
+                    continue;
+                if (this.repos.has(repoRoot))
+                    continue;
+                const gitignoreFiles = findGitignoreFiles(repoRoot);
+                const entries = gitignoreFiles.map((gf) => ({
+                    dir: node_path.dirname(gf),
+                    ig: parseGitignore(gf),
+                }));
+                // Sort deepest-first so nested `.gitignore` files are checked first
+                entries.sort((a, b) => b.dir.length - a.dir.length);
+                this.repos.set(repoRoot, { root: repoRoot, entries });
+            }
+        }
+        /**
+         * 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) {
+            const absPath = node_path.resolve(filePath);
+            for (const [, repo] of this.repos) {
+                // Check if file is within this repo
+                const relToRepo = node_path.relative(repo.root, absPath);
+                // On Windows, path.relative() across drives (e.g. D:\ → J:\) produces
+                // an absolute path with a drive letter instead of a relative one. The
+                // `ignore` library rejects these with a RangeError. Skip repos on
+                // different drives to avoid cross-drive gitignore mismatches.
+                if (relToRepo.startsWith('..') ||
+                    relToRepo.startsWith(node_path.resolve('/')) ||
+                    /^[a-zA-Z]:/.test(relToRepo)) {
+                    continue;
+                }
+                // Check each `.gitignore` entry (deepest-first)
+                for (const entry of repo.entries) {
+                    const relToEntry = node_path.relative(entry.dir, absPath);
+                    if (relToEntry.startsWith('..') || /^[a-zA-Z]:/.test(relToEntry))
+                        continue;
+                    const normalized = toForwardSlash(relToEntry);
+                    if (entry.ig.ignores(normalized)) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        }
+        /**
+         * 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) {
+            const absPath = node_path.resolve(gitignorePath);
+            const gitignoreDir = node_path.dirname(absPath);
+            for (const [, repo] of this.repos) {
+                const relToRepo = node_path.relative(repo.root, gitignoreDir);
+                if (relToRepo.startsWith('..'))
+                    continue;
+                // Remove old entry for this directory
+                repo.entries = repo.entries.filter((e) => e.dir !== gitignoreDir);
+                // Re-parse if file still exists
+                if (node_fs.existsSync(absPath)) {
+                    repo.entries.push({ dir: gitignoreDir, ig: parseGitignore(absPath) });
+                    // Re-sort deepest-first
+                    repo.entries.sort((a, b) => b.dir.length - a.dir.length);
+                }
+                return;
+            }
+            // If not in any known repo, check if it's in a repo we haven't scanned
+            const repoRoot = findRepoRoot(gitignoreDir);
+            if (repoRoot && node_fs.existsSync(absPath)) {
+                const entries = [
+                    { dir: gitignoreDir, ig: parseGitignore(absPath) },
+                ];
+                if (this.repos.has(repoRoot)) {
+                    const repo = this.repos.get(repoRoot);
+                    repo.entries.push(entries[0]);
+                    repo.entries.sort((a, b) => b.dir.length - a.dir.length);
+                }
+                else {
+                    this.repos.set(repoRoot, { root: repoRoot, entries });
+                }
+            }
+        }
+    }
+
+    /**
+     * @module templates/helpers
+     * Registers built-in Handlebars helpers for content templates.
+     */
+    /** Pre-built rehype parser for HTML → hast conversion. */
+    const htmlParser = unified.unified().use(rehypeParse, { fragment: true });
+    /**
+     * Register all built-in helpers on a Handlebars instance.
+     *
+     * @param hbs - The Handlebars instance.
+     */
+    function registerBuiltinHelpers(hbs) {
+        // Structural: ADF → Markdown
+        hbs.registerHelper('adfToMarkdown', function (adf) {
+            if (!adf || typeof adf !== 'object')
+                return '';
+            try {
+                const mdast = mdastUtilFromAdf.fromADF(adf);
+                return new hbs.SafeString(mdastUtilToMarkdown.toMarkdown(mdast).trim());
+            }
+            catch {
+                return '<!-- ADF conversion failed -->';
+            }
+        });
+        // Structural: HTML → Markdown
+        hbs.registerHelper('markdownify', function (html) {
+            if (typeof html !== 'string' || !html.trim())
+                return '';
+            try {
+                const hast = htmlParser.parse(html);
+                const mdast = hastUtilToMdast.toMdast(hast);
+                return new hbs.SafeString(mdastUtilToMarkdown.toMarkdown(mdast).trim());
+            }
+            catch {
+                return '<!-- HTML conversion failed -->';
+            }
+        });
+        // Formatting: dateFormat
+        hbs.registerHelper('dateFormat', function (value, format) {
+            if (value === undefined || value === null)
+                return '';
+            const fmt = typeof format === 'string' ? format : 'YYYY-MM-DD';
+            return dayjs(value).format(fmt);
+        });
+        // Formatting: join
+        hbs.registerHelper('join', function (arr, separator) {
+            if (!Array.isArray(arr))
+                return '';
+            const sep = typeof separator === 'string' ? separator : ', ';
+            return arr.join(sep);
+        });
+        // Formatting: pluck
+        hbs.registerHelper('pluck', function (arr, key) {
+            if (!Array.isArray(arr) || typeof key !== 'string')
+                return [];
+            return arr.map((item) => item && typeof item === 'object'
+                ? item[key]
+                : undefined);
+        });
+        // String transforms
+        hbs.registerHelper('lowercase', (text) => typeof text === 'string' ? text.toLowerCase() : '');
+        hbs.registerHelper('uppercase', (text) => typeof text === 'string' ? text.toUpperCase() : '');
+        hbs.registerHelper('capitalize', (text) => typeof text === 'string' ? radash.capitalize(text) : '');
+        hbs.registerHelper('title', (text) => typeof text === 'string' ? radash.title(text) : '');
+        hbs.registerHelper('camel', (text) => typeof text === 'string' ? radash.camel(text) : '');
+        hbs.registerHelper('snake', (text) => typeof text === 'string' ? radash.snake(text) : '');
+        hbs.registerHelper('dash', (text) => typeof text === 'string' ? radash.dash(text) : '');
+        // default helper
+        hbs.registerHelper('default', function (value, fallback) {
+            return value ?? fallback ?? '';
+        });
+        // eq helper (deep equality)
+        hbs.registerHelper('eq', function (a, b) {
+            return radash.isEqual(a, b);
+        });
+        // json helper
+        hbs.registerHelper('json', function (value) {
+            return new hbs.SafeString(JSON.stringify(value, null, 2));
+        });
+    }
+
+    /**
+     * @module templates/engine
+     * Handlebars template compilation, caching, and resolution (file path vs named ref vs inline).
+     */
+    /**
+     * 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.
+     */
+    function resolveTemplateSource(value, namedTemplates, configDir, visited = new Set()) {
+        // File path detection
+        if (value.endsWith('.hbs') || value.endsWith('.handlebars')) {
+            return node_fs.readFileSync(node_path.resolve(configDir, value), 'utf-8');
+        }
+        // Named ref
+        if (namedTemplates?.[value] !== undefined) {
+            if (visited.has(value)) {
+                throw new Error(`Circular template reference detected: ${value}`);
+            }
+            visited.add(value);
+            return resolveTemplateSource(namedTemplates[value], namedTemplates, configDir, visited);
+        }
+        // Inline
+        return value;
+    }
+    /**
+     * Create a configured Handlebars instance with built-in helpers registered.
+     *
+     * @returns A Handlebars instance with helpers.
+     */
+    function createHandlebarsInstance() {
+        const hbs = Handlebars.create();
+        registerBuiltinHelpers(hbs);
+        return hbs;
+    }
+    /**
+     * 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.
+     */
+    async function loadCustomHelpers(hbs, paths, configDir) {
+        for (const p of paths) {
+            const resolved = node_path.resolve(configDir, p);
+            const mod = (await import(resolved));
+            if (typeof mod.default === 'function') {
+                mod.default(hbs);
+            }
+        }
+    }
+    /**
+     * The template engine: holds compiled templates and renders them against context.
+     */
+    class TemplateEngine {
+        hbs;
+        compiled = new Map();
+        constructor(hbs) {
+            this.hbs = hbs;
+        }
+        /**
+         * 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, source) {
+            const fn = this.hbs.compile(source);
+            this.compiled.set(key, fn);
+            return fn;
+        }
+        /**
+         * Get a previously compiled template by key.
+         *
+         * @param key - The cache key.
+         * @returns The compiled template, or undefined.
+         */
+        get(key) {
+            return this.compiled.get(key);
+        }
+        /**
+         * 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, context) {
+            const fn = this.compiled.get(key);
+            if (!fn)
+                return null;
+            return fn(context);
+        }
+    }
+
+    /**
+     * @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.
+     */
+    async function buildTemplateEngine(rules, namedTemplates, templateHelperPaths, configDir) {
+        const rulesWithTemplates = rules.filter((r) => r.template);
+        if (rulesWithTemplates.length === 0)
+            return undefined;
+        const hbs = createHandlebarsInstance();
+        // Load custom helpers
+        if (templateHelperPaths?.length && configDir) {
+            await loadCustomHelpers(hbs, templateHelperPaths, configDir);
+        }
+        const engine = new TemplateEngine(hbs);
+        // Compile all rule templates
+        for (const [index, rule] of rules.entries()) {
+            if (!rule.template)
+                continue;
+            const source = resolveTemplateSource(rule.template, namedTemplates, configDir ?? '.');
+            engine.compile(`rule-${String(index)}`, source);
+        }
+        return engine;
+    }
+
+    /**
+     * @module app/configWatcher
+     * Watches the config file for changes and triggers debounced reload. Isolated I/O wrapper around chokidar.
+     */
+    /**
+     * Debounced config file watcher.
+     */
+    class ConfigWatcher {
+        options;
+        watcher;
+        debounce;
+        constructor(options) {
+            this.options = options;
+        }
+        start() {
+            if (!this.options.enabled)
+                return;
+            this.watcher = chokidar.watch(this.options.configPath, {
+                ignoreInitial: true,
+            });
+            this.watcher.on('change', () => {
+                if (this.debounce)
+                    clearTimeout(this.debounce);
+                this.debounce = setTimeout(() => {
+                    void this.options.onChange();
+                }, this.options.debounceMs);
+            });
+            this.watcher.on('error', (error) => {
+                this.options.logger.error({ err: normalizeError(error) }, 'Config watcher error');
+            });
+            this.options.logger.info({
+                configPath: this.options.configPath,
+                debounceMs: this.options.debounceMs,
+            }, 'Config watcher started');
+        }
+        async stop() {
+            if (this.debounce) {
+                clearTimeout(this.debounce);
+                this.debounce = undefined;
+            }
+            if (this.watcher) {
+                await this.watcher.close();
+                this.watcher = undefined;
+            }
+        }
+    }
+
     /**
      * @module config/defaults
      * Default configuration values for jeeves-watcher. Pure data export, no I/O or side effects.
@@ -617,7 +1097,12 @@
         map: zod.z
             .union([jsonmap.jsonMapMapSchema, zod.z.string()])
             .optional()
-            .describe('JsonMap transformation (inline definition or named map reference).'),
+            .describe('JsonMap transformation (inline definition, named map reference, or .json file path).'),
+        /** Handlebars template (inline string, named ref, or .hbs/.handlebars file path). */
+        template: zod.z
+            .string()
+            .optional()
+            .describe('Handlebars content template (inline string, named ref, or .hbs/.handlebars file path).'),
     });
     /**
      * Top-level configuration for jeeves-watcher.
@@ -654,7 +1139,23 @@
         maps: zod.z
             .record(zod.z.string(), jsonmap.jsonMapMapSchema)
             .optional()
-            .describe('Reusable named JsonMap transformations.'),
+            .describe('Reusable named JsonMap transformations.'),
+        /** Reusable named Handlebars templates (inline strings or .hbs/.handlebars file paths). */
+        templates: zod.z
+            .record(zod.z.string(), zod.z.string())
+            .optional()
+            .describe('Named reusable Handlebars templates (inline strings or .hbs/.handlebars file paths).'),
+        /** Custom Handlebars helper registration. */
+        templateHelpers: zod.z
+            .object({
+            /** File paths to custom helper modules. */
+            paths: zod.z
+                .array(zod.z.string())
+                .optional()
+                .describe('File paths to custom helper modules.'),
+        })
+            .optional()
+            .describe('Custom Handlebars helper registration.'),
         /** Logging configuration. */
         logging: loggingConfigSchema.optional().describe('Logging configuration.'),
         /** Timeout in milliseconds for graceful shutdown. */
@@ -904,266 +1405,60 @@
             dimensions,
             async embed(texts) {
                 const vectors = await retry(async (attempt) => {
-                    if (attempt > 1) {
-                        log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
-                    }
-                    // embedDocuments returns vectors for multiple texts
-                    return embedder.embedDocuments(texts);
-                }, {
-                    attempts: 5,
-                    baseDelayMs: 500,
-                    maxDelayMs: 10_000,
-                    jitter: 0.2,
-                    onRetry: ({ attempt, delayMs, error }) => {
-                        log.warn({
-                            attempt,
-                            delayMs,
-                            provider: 'gemini',
-                            model: config.model,
-                            err: normalizeError(error),
-                        }, 'Embedding call failed; will retry');
-                    },
-                });
-                // Validate dimensions
-                for (const vector of vectors) {
-                    if (vector.length !== dimensions) {
-                        throw new Error(`Gemini embedding returned invalid dimensions: expected ${String(dimensions)}, got ${String(vector.length)}`);
-                    }
-                }
-                return vectors;
-            },
-        };
-    }
-    function createMockFromConfig(config) {
-        const dimensions = config.dimensions ?? 768;
-        return createMockProvider(dimensions);
-    }
-    const embeddingProviderRegistry = new Map([
-        ['mock', createMockFromConfig],
-        ['gemini', createGeminiProvider],
-    ]);
-    /**
-     * Create an embedding provider based on the given configuration.
-     *
-     * Each provider is responsible for its own default dimensions.
-     *
-     * @param config - The embedding configuration.
-     * @param logger - Optional pino logger for retry warnings.
-     * @returns An {@link EmbeddingProvider} instance.
-     * @throws If the configured provider is not supported.
-     */
-    function createEmbeddingProvider(config, logger) {
-        const factory = embeddingProviderRegistry.get(config.provider);
-        if (!factory) {
-            throw new Error(`Unsupported embedding provider: ${config.provider}`);
-        }
-        return factory(config, 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.
-     */
-    /**
-     * Find the git repo root by walking up from `startDir` looking for `.git/`.
-     * Returns `undefined` if no repo is found.
-     */
-    function findRepoRoot(startDir) {
-        let dir = node_path.resolve(startDir);
-        const root = node_path.resolve('/');
-        while (dir !== root) {
-            if (node_fs.existsSync(node_path.join(dir, '.git')) &&
-                node_fs.statSync(node_path.join(dir, '.git')).isDirectory()) {
-                return dir;
-            }
-            const parent = node_path.dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-        return undefined;
-    }
-    /**
-     * Convert a watch path (directory, file path, or glob) to a concrete directory
-     * that can be scanned for a repo root.
-     */
-    function watchPathToScanDir(watchPath) {
-        const absPath = node_path.resolve(watchPath);
-        try {
-            return node_fs.statSync(absPath).isDirectory() ? absPath : node_path.dirname(absPath);
-        }
-        catch {
-            // ignore
-        }
-        // If this is a glob, fall back to the non-glob prefix.
-        const globMatch = /[*?[{]/.exec(watchPath);
-        if (!globMatch)
-            return undefined;
-        const prefix = watchPath.slice(0, globMatch.index);
-        const trimmed = prefix.trim();
-        const baseDir = trimmed.length === 0
-            ? '.'
-            : trimmed.endsWith('/') || trimmed.endsWith('\\')
-                ? trimmed
-                : node_path.dirname(trimmed);
-        const resolved = node_path.resolve(baseDir);
-        if (!node_fs.existsSync(resolved))
-            return undefined;
-        return resolved;
-    }
-    /**
-     * Recursively find all `.gitignore` files under `dir`.
-     * Skips `.git` and `node_modules` directories for performance.
-     */
-    function findGitignoreFiles(dir) {
-        const results = [];
-        const gitignorePath = node_path.join(dir, '.gitignore');
-        if (node_fs.existsSync(gitignorePath)) {
-            results.push(gitignorePath);
-        }
-        let entries;
-        try {
-            entries = node_fs.readdirSync(dir);
-        }
-        catch {
-            return results;
-        }
-        for (const entry of entries) {
-            if (entry === '.git' || entry === 'node_modules')
-                continue;
-            const fullPath = node_path.join(dir, entry);
-            try {
-                if (node_fs.statSync(fullPath).isDirectory()) {
-                    results.push(...findGitignoreFiles(fullPath));
-                }
-            }
-            catch {
-                // Skip inaccessible entries
-            }
-        }
-        return results;
-    }
-    /**
-     * Parse a `.gitignore` file into an `ignore` instance.
-     */
-    function parseGitignore(gitignorePath) {
-        const content = node_fs.readFileSync(gitignorePath, 'utf8');
-        return ignore().add(content);
-    }
-    /**
-     * Normalize a path to use forward slashes (required by `ignore` package).
-     */
-    function toForwardSlash(p) {
-        return p.replace(/\\/g, '/');
-    }
-    /**
-     * Processor-level gitignore filter. Checks file paths against the nearest
-     * `.gitignore` chain in git repositories.
-     */
-    class GitignoreFilter {
-        repos = new Map();
-        /**
-         * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
-         *
-         * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
-         */
-        constructor(watchPaths) {
-            this.scan(watchPaths);
-        }
-        /**
-         * Scan paths for git repos and their `.gitignore` files.
-         */
-        scan(watchPaths) {
-            this.repos.clear();
-            const scannedDirs = new Set();
-            for (const watchPath of watchPaths) {
-                const scanDir = watchPathToScanDir(watchPath);
-                if (!scanDir)
-                    continue;
-                if (scannedDirs.has(scanDir))
-                    continue;
-                scannedDirs.add(scanDir);
-                const repoRoot = findRepoRoot(scanDir);
-                if (!repoRoot)
-                    continue;
-                if (this.repos.has(repoRoot))
-                    continue;
-                const gitignoreFiles = findGitignoreFiles(repoRoot);
-                const entries = gitignoreFiles.map((gf) => ({
-                    dir: node_path.dirname(gf),
-                    ig: parseGitignore(gf),
-                }));
-                // Sort deepest-first so nested `.gitignore` files are checked first
-                entries.sort((a, b) => b.dir.length - a.dir.length);
-                this.repos.set(repoRoot, { root: repoRoot, entries });
-            }
-        }
-        /**
-         * 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) {
-            const absPath = node_path.resolve(filePath);
-            for (const [, repo] of this.repos) {
-                // Check if file is within this repo
-                const relToRepo = node_path.relative(repo.root, absPath);
-                if (relToRepo.startsWith('..') || relToRepo.startsWith(node_path.resolve('/'))) {
-                    continue;
-                }
-                // Check each `.gitignore` entry (deepest-first)
-                for (const entry of repo.entries) {
-                    const relToEntry = node_path.relative(entry.dir, absPath);
-                    if (relToEntry.startsWith('..'))
-                        continue;
-                    const normalized = toForwardSlash(relToEntry);
-                    if (entry.ig.ignores(normalized)) {
-                        return true;
-                    }
-                }
-            }
-            return false;
-        }
-        /**
-         * 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) {
-            const absPath = node_path.resolve(gitignorePath);
-            const gitignoreDir = node_path.dirname(absPath);
-            for (const [, repo] of this.repos) {
-                const relToRepo = node_path.relative(repo.root, gitignoreDir);
-                if (relToRepo.startsWith('..'))
-                    continue;
-                // Remove old entry for this directory
-                repo.entries = repo.entries.filter((e) => e.dir !== gitignoreDir);
-                // Re-parse if file still exists
-                if (node_fs.existsSync(absPath)) {
-                    repo.entries.push({ dir: gitignoreDir, ig: parseGitignore(absPath) });
-                    // Re-sort deepest-first
-                    repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-                }
-                return;
-            }
-            // If not in any known repo, check if it's in a repo we haven't scanned
-            const repoRoot = findRepoRoot(gitignoreDir);
-            if (repoRoot && node_fs.existsSync(absPath)) {
-                const entries = [
-                    { dir: gitignoreDir, ig: parseGitignore(absPath) },
-                ];
-                if (this.repos.has(repoRoot)) {
-                    const repo = this.repos.get(repoRoot);
-                    repo.entries.push(entries[0]);
-                    repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-                }
-                else {
-                    this.repos.set(repoRoot, { root: repoRoot, entries });
+                    if (attempt > 1) {
+                        log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
+                    }
+                    // embedDocuments returns vectors for multiple texts
+                    return embedder.embedDocuments(texts);
+                }, {
+                    attempts: 5,
+                    baseDelayMs: 500,
+                    maxDelayMs: 10_000,
+                    jitter: 0.2,
+                    onRetry: ({ attempt, delayMs, error }) => {
+                        log.warn({
+                            attempt,
+                            delayMs,
+                            provider: 'gemini',
+                            model: config.model,
+                            err: normalizeError(error),
+                        }, 'Embedding call failed; will retry');
+                    },
+                });
+                // Validate dimensions
+                for (const vector of vectors) {
+                    if (vector.length !== dimensions) {
+                        throw new Error(`Gemini embedding returned invalid dimensions: expected ${String(dimensions)}, got ${String(vector.length)}`);
+                    }
                 }
-            }
+                return vectors;
+            },
+        };
+    }
+    function createMockFromConfig(config) {
+        const dimensions = config.dimensions ?? 768;
+        return createMockProvider(dimensions);
+    }
+    const embeddingProviderRegistry = new Map([
+        ['mock', createMockFromConfig],
+        ['gemini', createGeminiProvider],
+    ]);
+    /**
+     * Create an embedding provider based on the given configuration.
+     *
+     * Each provider is responsible for its own default dimensions.
+     *
+     * @param config - The embedding configuration.
+     * @param logger - Optional pino logger for retry warnings.
+     * @returns An {@link EmbeddingProvider} instance.
+     * @throws If the configured provider is not supported.
+     */
+    function createEmbeddingProvider(config, logger) {
+        const factory = embeddingProviderRegistry.get(config.provider);
+        if (!factory) {
+            throw new Error(`Unsupported embedding provider: ${config.provider}`);
         }
+        return factory(config, logger);
     }
 
     /**
@@ -1395,7 +1690,7 @@
         };
     }
     /**
-     * Apply compiled inference rules to file attributes, returning merged metadata.
+     * 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,
@@ -1405,15 +1700,18 @@
      * @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.
      */
-    async function applyRules(compiledRules, attributes, namedMaps, logger) {
+    async function applyRules(compiledRules, attributes, namedMaps, logger, templateEngine, configDir) {
         // JsonMap's type definitions expect a generic JsonMapLib shape with unary functions.
         // Our helper functions accept multiple args, which JsonMap supports at runtime.
         const lib = createJsonMapLib();
         let merged = {};
+        let renderedContent = null;
         const log = logger ?? console;
-        for (const { rule, validate } of compiledRules) {
+        for (const [ruleIndex, { rule, validate }] of compiledRules.entries()) {
             if (validate(attributes)) {
                 // Apply set resolution
                 const setOutput = resolveSet(rule.set, attributes);
@@ -1423,10 +1721,24 @@
                     let mapDef;
                     // Resolve map reference
                     if (typeof rule.map === 'string') {
-                        mapDef = namedMaps?.[rule.map];
-                        if (!mapDef) {
-                            log.warn(`Map reference "${rule.map}" not found in named maps. Skipping map transformation.`);
-                            continue;
+                        if (rule.map.endsWith('.json') && configDir) {
+                            // File path: load from .json file
+                            try {
+                                const mapPath = node_path.resolve(configDir, rule.map);
+                                const raw = node_fs.readFileSync(mapPath, 'utf-8');
+                                mapDef = JSON.parse(raw);
+                            }
+                            catch (error) {
+                                log.warn(`Failed to load map file "${rule.map}": ${error instanceof Error ? error.message : String(error)}`);
+                                continue;
+                            }
+                        }
+                        else {
+                            mapDef = namedMaps?.[rule.map];
+                            if (!mapDef) {
+                                log.warn(`Map reference "${rule.map}" not found in named maps. Skipping map transformation.`);
+                                continue;
+                            }
                         }
                     }
                     else {
@@ -1449,9 +1761,31 @@
                         log.warn(`JsonMap transformation failed: ${error instanceof Error ? error.message : String(error)}`);
                     }
                 }
+                // Render template if present
+                if (rule.template && templateEngine) {
+                    const templateKey = `rule-${String(ruleIndex)}`;
+                    // Build template context: attributes (with json spread at top) + map output
+                    const context = {
+                        ...(attributes.json ?? {}),
+                        ...attributes,
+                        ...merged,
+                    };
+                    try {
+                        const result = templateEngine.render(templateKey, context);
+                        if (result && result.trim()) {
+                            renderedContent = result;
+                        }
+                        else {
+                            log.warn(`Template for rule ${String(ruleIndex)} rendered empty output. Falling back to raw content.`);
+                        }
+                    }
+                    catch (error) {
+                        log.warn(`Template render failed for rule ${String(ruleIndex)}: ${error instanceof Error ? error.message : String(error)}. Falling back to raw content.`);
+                    }
+                }
             }
         }
-        return merged;
+        return { metadata: merged, renderedContent };
     }
 
     /**
@@ -1540,23 +1874,32 @@
      * @param metadataDir - The metadata directory for enrichment files.
      * @param maps - Optional named JsonMap definitions.
      * @param logger - Optional logger for rule warnings.
+     * @param templateEngine - Optional template engine for content templates.
+     * @param configDir - Optional config directory for resolving file paths.
      * @returns The merged metadata and intermediate data.
      */
-    async function buildMergedMetadata(filePath, compiledRules, metadataDir, maps, logger) {
+    async function buildMergedMetadata(filePath, compiledRules, metadataDir, maps, logger, templateEngine, configDir) {
         const ext = node_path.extname(filePath);
         const stats = await promises.stat(filePath);
         // 1. Extract text and structured data
         const extracted = await extractText(filePath, ext);
         // 2. Build attributes + apply rules
         const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-        const inferred = await applyRules(compiledRules, attributes, maps, logger);
+        const { metadata: inferred, renderedContent } = await applyRules(compiledRules, attributes, maps, logger, templateEngine, configDir);
         // 3. Read enrichment metadata (merge, enrichment wins)
         const enrichment = await readMetadata(filePath, metadataDir);
         const metadata = {
             ...inferred,
             ...(enrichment ?? {}),
         };
-        return { inferred, enrichment, metadata, attributes, extracted };
+        return {
+            inferred,
+            enrichment,
+            metadata,
+            attributes,
+            extracted,
+            renderedContent,
+        };
     }
 
     /**
@@ -1627,6 +1970,7 @@
         vectorStore;
         compiledRules;
         logger;
+        templateEngine;
         /**
          * Create a new DocumentProcessor.
          *
@@ -1635,13 +1979,15 @@
          * @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, embeddingProvider, vectorStore, compiledRules, logger) {
+        constructor(config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine) {
             this.config = config;
             this.embeddingProvider = embeddingProvider;
             this.vectorStore = vectorStore;
             this.compiledRules = compiledRules;
             this.logger = logger;
+            this.templateEngine = templateEngine;
         }
         /**
          * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
@@ -1652,13 +1998,15 @@
             try {
                 const ext = node_path.extname(filePath);
                 // 1. Build merged metadata + extract text
-                const { metadata, extracted } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
-                if (!extracted.text.trim()) {
+                const { metadata, extracted, renderedContent } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger, this.templateEngine, this.config.configDir);
+                // Use rendered template content if available, otherwise raw extracted text
+                const textToEmbed = renderedContent ?? extracted.text;
+                if (!textToEmbed.trim()) {
                     this.logger.debug({ filePath }, 'Skipping empty file');
                     return;
                 }
                 // 2. Content hash check — skip if unchanged
-                const hash = contentHash(extracted.text);
+                const hash = contentHash(textToEmbed);
                 const baseId = pointId(filePath, 0);
                 const existingPayload = await this.vectorStore.getPayload(baseId);
                 if (existingPayload && existingPayload['content_hash'] === hash) {
@@ -1670,7 +2018,7 @@
                 const chunkSize = this.config.chunkSize ?? 1000;
                 const chunkOverlap = this.config.chunkOverlap ?? 200;
                 const splitter = createSplitter(ext, chunkSize, chunkOverlap);
-                const chunks = await splitter.splitText(extracted.text);
+                const chunks = await splitter.splitText(textToEmbed);
                 // 4. Embed all chunks
                 const vectors = await this.embeddingProvider.embed(chunks);
                 // 5. Upsert all chunk points
@@ -1764,7 +2112,7 @@
                     return null;
                 }
                 // Build merged metadata (lightweight — no embedding)
-                const { metadata } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
+                const { metadata } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger, this.templateEngine, this.config.configDir);
                 // Update all chunk payloads
                 const totalChunks = getChunkCount(existingPayload);
                 const ids = chunkIds(filePath, totalChunks);
@@ -1782,8 +2130,17 @@
          *
          * @param compiledRules - The newly compiled rules.
          */
-        updateRules(compiledRules) {
+        /**
+         * Update compiled inference rules and optionally the template engine.
+         *
+         * @param compiledRules - The newly compiled rules.
+         * @param templateEngine - Optional updated template engine.
+         */
+        updateRules(compiledRules, templateEngine) {
             this.compiledRules = compiledRules;
+            if (templateEngine) {
+                this.templateEngine = templateEngine;
+            }
             this.logger.info({ rules: compiledRules.length }, 'Inference rules updated');
         }
     }
@@ -2312,6 +2669,76 @@
         }
     }
 
+    /**
+     * @module watcher/globToDir
+     * Adapts glob-based watch config to chokidar v4+, which removed glob support
+     * (see paulmillr/chokidar#1350). Chokidar v4 treats glob patterns as literal
+     * strings, silently producing zero events. This module extracts static directory
+     * roots from glob patterns for chokidar to watch, then filters emitted events
+     * against the original globs via picomatch.
+     */
+    /**
+     * Extract the static directory root from a glob pattern.
+     * Stops at the first segment containing glob characters (`*`, `{`, `?`, `[`).
+     *
+     * @param glob - A glob pattern (e.g., `j:/domains/**\/*.json`).
+     * @returns The static directory prefix (e.g., `j:/domains`).
+     */
+    function globRoot(glob) {
+        const normalized = glob.replace(/\\/g, '/');
+        const segments = normalized.split('/');
+        const staticSegments = [];
+        for (const seg of segments) {
+            if (/[*?{[\]]/.test(seg))
+                break;
+            staticSegments.push(seg);
+        }
+        return staticSegments.join('/') || '.';
+    }
+    /**
+     * Deduplicate directory roots, removing paths that are subdirectories of others.
+     *
+     * @param roots - Array of directory paths.
+     * @returns Deduplicated array with subdirectories removed.
+     */
+    function deduplicateRoots(roots) {
+        const normalized = roots.map((r) => r.replace(/\\/g, '/').toLowerCase());
+        const sorted = [...new Set(normalized)].sort();
+        return sorted.filter((root, _i, arr) => {
+            const withSlash = root.endsWith('/') ? root : root + '/';
+            return !arr.some((other) => other !== root && withSlash.startsWith(other + '/'));
+        });
+    }
+    /**
+     * Build a picomatch matcher from an array of glob patterns.
+     * Normalizes Windows paths (backslash → forward slash, lowercase drive letter)
+     * before matching.
+     *
+     * @param globs - Glob patterns to match against.
+     * @returns A function that tests whether a file path matches any of the globs.
+     */
+    function buildGlobMatcher(globs) {
+        const normalizedGlobs = globs.map((g) => g.replace(/\\/g, '/'));
+        const isMatch = picomatch(normalizedGlobs, { dot: true, nocase: true });
+        return (filePath) => {
+            const normalized = filePath.replace(/\\/g, '/');
+            return isMatch(normalized);
+        };
+    }
+    /**
+     * Convert an array of glob patterns into chokidar-compatible directory roots
+     * and a filter function for post-hoc event filtering.
+     *
+     * @param globs - Glob patterns from the watch config.
+     * @returns Object with `roots` (directories for chokidar) and `matches` (filter function).
+     */
+    function resolveWatchPaths(globs) {
+        const rawRoots = globs.map(globRoot);
+        const roots = deduplicateRoots(rawRoots);
+        const matches = buildGlobMatcher(globs);
+        return { roots, matches };
+    }
+
     /**
      * @module watcher
      * Filesystem watcher wrapping chokidar. I/O: watches files/directories for add/change/unlink events, enqueues to processing queue.
@@ -2326,6 +2753,7 @@
         logger;
         health;
         gitignoreFilter;
+        globMatches;
         watcher;
         /**
          * Create a new FileSystemWatcher.
@@ -2342,6 +2770,7 @@
             this.processor = processor;
             this.logger = logger;
             this.gitignoreFilter = options.gitignoreFilter;
+            this.globMatches = () => true;
             const healthOptions = {
                 maxRetries: options.maxRetries,
                 maxBackoffMs: options.maxBackoffMs,
@@ -2354,7 +2783,13 @@
          * Start watching the filesystem and processing events.
          */
         start() {
-            this.watcher = chokidar.watch(this.config.paths, {
+            // Chokidar v4+ removed glob support (paulmillr/chokidar#1350).
+            // Glob patterns are silently treated as literal strings, producing zero
+            // events. We extract static directory roots for chokidar to watch, then
+            // filter emitted events against the original globs via picomatch.
+            const { roots, matches } = resolveWatchPaths(this.config.paths);
+            this.globMatches = matches;
+            this.watcher = chokidar.watch(roots, {
                 ignored: this.config.ignored,
                 usePolling: this.config.usePolling,
                 interval: this.config.pollIntervalMs,
@@ -2365,6 +2800,8 @@
             });
             this.watcher.on('add', (path) => {
                 this.handleGitignoreChange(path);
+                if (!this.globMatches(path))
+                    return;
                 if (this.isGitignored(path))
                     return;
                 this.logger.debug({ path }, 'File added');
@@ -2372,6 +2809,8 @@
             });
             this.watcher.on('change', (path) => {
                 this.handleGitignoreChange(path);
+                if (!this.globMatches(path))
+                    return;
                 if (this.isGitignored(path))
                     return;
                 this.logger.debug({ path }, 'File changed');
@@ -2379,6 +2818,8 @@
             });
             this.watcher.on('unlink', (path) => {
                 this.handleGitignoreChange(path);
+                if (!this.globMatches(path))
+                    return;
                 if (this.isGitignored(path))
                     return;
                 this.logger.debug({ path }, 'File removed');
@@ -2451,51 +2892,21 @@
     }
 
     /**
-     * @module app/configWatcher
-     * Watches the config file for changes and triggers debounced reload. Isolated I/O wrapper around chokidar.
-     */
-    /**
-     * Debounced config file watcher.
+     * @module app/factories
+     * Component factory interfaces and defaults for {@link JeevesWatcher}. Override in tests to inject mocks.
      */
-    class ConfigWatcher {
-        options;
-        watcher;
-        debounce;
-        constructor(options) {
-            this.options = options;
-        }
-        start() {
-            if (!this.options.enabled)
-                return;
-            this.watcher = chokidar.watch(this.options.configPath, {
-                ignoreInitial: true,
-            });
-            this.watcher.on('change', () => {
-                if (this.debounce)
-                    clearTimeout(this.debounce);
-                this.debounce = setTimeout(() => {
-                    void this.options.onChange();
-                }, this.options.debounceMs);
-            });
-            this.watcher.on('error', (error) => {
-                this.options.logger.error({ err: normalizeError(error) }, 'Config watcher error');
-            });
-            this.options.logger.info({
-                configPath: this.options.configPath,
-                debounceMs: this.options.debounceMs,
-            }, 'Config watcher started');
-        }
-        async stop() {
-            if (this.debounce) {
-                clearTimeout(this.debounce);
-                this.debounce = undefined;
-            }
-            if (this.watcher) {
-                await this.watcher.close();
-                this.watcher = undefined;
-            }
-        }
-    }
+    /** Default component factories wiring real implementations. */
+    const defaultFactories = {
+        loadConfig,
+        createLogger,
+        createEmbeddingProvider,
+        createVectorStoreClient: (config, dimensions, logger) => new VectorStoreClient(config, dimensions, logger),
+        compileRules,
+        createDocumentProcessor: (config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine) => new DocumentProcessor(config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine),
+        createEventQueue: (options) => new EventQueue(options),
+        createFileSystemWatcher: (config, queue, processor, logger, options) => new FileSystemWatcher(config, queue, processor, logger, options),
+        createApiServer,
+    };
 
     /**
      * @module app/shutdown
@@ -2515,17 +2926,28 @@
         process.on('SIGINT', () => void shutdown());
     }
 
-    const defaultFactories = {
-        loadConfig,
-        createLogger,
-        createEmbeddingProvider,
-        createVectorStoreClient: (config, dimensions, logger) => new VectorStoreClient(config, dimensions, logger),
-        compileRules,
-        createDocumentProcessor: (config, embeddingProvider, vectorStore, compiledRules, logger) => new DocumentProcessor(config, embeddingProvider, vectorStore, compiledRules, logger),
-        createEventQueue: (options) => new EventQueue(options),
-        createFileSystemWatcher: (config, queue, processor, logger, options) => new FileSystemWatcher(config, queue, processor, logger, options),
-        createApiServer,
-    };
+    /**
+     * @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.
+     */
+    async function startFromConfig(configPath) {
+        const config = await loadConfig(configPath);
+        const app = new JeevesWatcher(config, configPath);
+        installShutdownHandlers(() => app.stop());
+        await app.start();
+        return app;
+    }
+
+    /**
+     * @module app
+     * Main application orchestrator. Wires components, manages lifecycle (start/stop/reload).
+     */
     /**
      * Main application class that wires together all components.
      */
@@ -2560,56 +2982,26 @@
         async start() {
             const logger = this.factories.createLogger(this.config.logging);
             this.logger = logger;
-            let embeddingProvider;
-            try {
-                embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
-            }
-            catch (error) {
-                logger.fatal({ err: normalizeError(error) }, 'Failed to create embedding provider');
-                throw error;
-            }
-            const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
-            await vectorStore.ensureCollection();
+            const { embeddingProvider, vectorStore } = await this.initEmbeddingAndStore(logger);
             const compiledRules = this.factories.compileRules(this.config.inferenceRules ?? []);
-            const processorConfig = {
+            const configDir = this.configPath ? node_path.dirname(this.configPath) : '.';
+            const templateEngine = await buildTemplateEngine(this.config.inferenceRules ?? [], this.config.templates, this.config.templateHelpers?.paths, configDir);
+            const processor = this.factories.createDocumentProcessor({
                 metadataDir: this.config.metadataDir ?? '.jeeves-metadata',
                 chunkSize: this.config.embedding.chunkSize,
                 chunkOverlap: this.config.embedding.chunkOverlap,
                 maps: this.config.maps,
-            };
-            const processor = this.factories.createDocumentProcessor(processorConfig, embeddingProvider, vectorStore, compiledRules, logger);
+                configDir,
+            }, embeddingProvider, vectorStore, compiledRules, logger, templateEngine);
             this.processor = processor;
-            const queue = this.factories.createEventQueue({
+            this.queue = this.factories.createEventQueue({
                 debounceMs: this.config.watch.debounceMs ?? 2000,
                 concurrency: this.config.embedding.concurrency ?? 5,
                 rateLimitPerMinute: this.config.embedding.rateLimitPerMinute,
             });
-            this.queue = queue;
-            const respectGitignore = this.config.watch.respectGitignore ?? true;
-            const gitignoreFilter = respectGitignore
-                ? new GitignoreFilter(this.config.watch.paths)
-                : undefined;
-            const watcher = this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger, {
-                maxRetries: this.config.maxRetries,
-                maxBackoffMs: this.config.maxBackoffMs,
-                onFatalError: this.runtimeOptions.onFatalError,
-                gitignoreFilter,
-            });
-            this.watcher = watcher;
-            const server = this.factories.createApiServer({
-                processor,
-                vectorStore,
-                embeddingProvider,
-                queue,
-                config: this.config,
-                logger,
-            });
-            this.server = server;
-            await server.listen({
-                host: this.config.api?.host ?? '127.0.0.1',
-                port: this.config.api?.port ?? 3456,
-            });
-            watcher.start();
+            this.watcher = this.createWatcher(this.queue, processor, logger);
+            this.server = await this.startApiServer(processor, vectorStore, embeddingProvider, logger);
+            this.watcher.start();
             this.startConfigWatch();
             logger.info('jeeves-watcher started');
         }
@@ -2640,22 +3032,61 @@
             }
             this.logger?.info('jeeves-watcher stopped');
         }
+        async initEmbeddingAndStore(logger) {
+            let embeddingProvider;
+            try {
+                embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
+            }
+            catch (error) {
+                logger.fatal({ err: normalizeError(error) }, 'Failed to create embedding provider');
+                throw error;
+            }
+            const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
+            await vectorStore.ensureCollection();
+            return { embeddingProvider, vectorStore };
+        }
+        createWatcher(queue, processor, logger) {
+            const respectGitignore = this.config.watch.respectGitignore ?? true;
+            const gitignoreFilter = respectGitignore
+                ? new GitignoreFilter(this.config.watch.paths)
+                : undefined;
+            return this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger, {
+                maxRetries: this.config.maxRetries,
+                maxBackoffMs: this.config.maxBackoffMs,
+                onFatalError: this.runtimeOptions.onFatalError,
+                gitignoreFilter,
+            });
+        }
+        async startApiServer(processor, vectorStore, embeddingProvider, logger) {
+            const server = this.factories.createApiServer({
+                processor,
+                vectorStore,
+                embeddingProvider,
+                queue: this.queue,
+                config: this.config,
+                logger,
+            });
+            await server.listen({
+                host: this.config.api?.host ?? '127.0.0.1',
+                port: this.config.api?.port ?? 3456,
+            });
+            return server;
+        }
         startConfigWatch() {
             const logger = this.logger;
             if (!logger)
                 return;
             const enabled = this.config.configWatch?.enabled ?? true;
-            if (!enabled)
-                return;
-            if (!this.configPath) {
-                logger.debug('Config watch enabled, but no config path was provided');
+            if (!enabled || !this.configPath) {
+                if (!this.configPath) {
+                    logger.debug('Config watch enabled, but no config path was provided');
+                }
                 return;
             }
-            const debounceMs = this.config.configWatch?.debounceMs ?? 10000;
             this.configWatcher = new ConfigWatcher({
                 configPath: this.configPath,
                 enabled,
-                debounceMs,
+                debounceMs: this.config.configWatch?.debounceMs ?? 10000,
                 logger,
                 onChange: async () => this.reloadConfig(),
             });
@@ -2677,7 +3108,9 @@
                 const newConfig = await this.factories.loadConfig(this.configPath);
                 this.config = newConfig;
                 const compiledRules = this.factories.compileRules(newConfig.inferenceRules ?? []);
-                processor.updateRules(compiledRules);
+                const reloadConfigDir = node_path.dirname(this.configPath);
+                const newTemplateEngine = await buildTemplateEngine(newConfig.inferenceRules ?? [], newConfig.templates, newConfig.templateHelpers?.paths, reloadConfigDir);
+                processor.updateRules(compiledRules, newTemplateEngine);
                 logger.info({ configPath: this.configPath, rules: compiledRules.length }, 'Config reloaded');
             }
             catch (error) {
@@ -2685,19 +3118,7 @@
             }
         }
     }
-    /**
-     * Create and start a JeevesWatcher from a config file path.
-     *
-     * @param configPath - Optional path to the configuration file.
-     * @returns The running JeevesWatcher instance.
-     */
-    async function startFromConfig(configPath) {
-        const config = await loadConfig(configPath);
-        const app = new JeevesWatcher(config, configPath);
-        installShutdownHandlers(() => app.stop());
-        await app.start();
-        return app;
-    }
+    // startFromConfig re-exported from ./startFromConfig
 
     exports.DocumentProcessor = DocumentProcessor;
     exports.EventQueue = EventQueue;
@@ -2705,15 +3126,18 @@
     exports.GitignoreFilter = GitignoreFilter;
     exports.JeevesWatcher = JeevesWatcher;
     exports.SystemHealth = SystemHealth;
+    exports.TemplateEngine = TemplateEngine;
     exports.VectorStoreClient = VectorStoreClient;
     exports.apiConfigSchema = apiConfigSchema;
     exports.applyRules = applyRules;
     exports.buildAttributes = buildAttributes;
+    exports.buildTemplateEngine = buildTemplateEngine;
     exports.compileRules = compileRules;
     exports.configWatchConfigSchema = configWatchConfigSchema;
     exports.contentHash = contentHash;
     exports.createApiServer = createApiServer;
     exports.createEmbeddingProvider = createEmbeddingProvider;
+    exports.createHandlebarsInstance = createHandlebarsInstance;
     exports.createLogger = createLogger;
     exports.deleteMetadata = deleteMetadata;
     exports.embeddingConfigSchema = embeddingConfigSchema;
@@ -2721,13 +3145,16 @@
     exports.inferenceRuleSchema = inferenceRuleSchema;
     exports.jeevesWatcherConfigSchema = jeevesWatcherConfigSchema;
     exports.loadConfig = loadConfig;
+    exports.loadCustomHelpers = loadCustomHelpers;
     exports.loggingConfigSchema = loggingConfigSchema;
     exports.metadataPath = metadataPath;
     exports.pointId = pointId;
     exports.readMetadata = readMetadata;
+    exports.registerBuiltinHelpers = registerBuiltinHelpers;
+    exports.resolveTemplateSource = resolveTemplateSource;
     exports.startFromConfig = startFromConfig;
     exports.vectorStoreConfigSchema = vectorStoreConfigSchema;
     exports.watchConfigSchema = watchConfigSchema;
     exports.writeMetadata = writeMetadata;
 
-})(this["jeeves-watcher"] = this["jeeves-watcher"] || {}, Fastify, promises, node_path, picomatch, radash, node_crypto, cosmiconfig, zod, jsonmap, googleGenai, node_fs, ignore, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest, chokidar);
+})(this["jeeves-watcher"] = this["jeeves-watcher"] || {}, Fastify, promises, node_path, picomatch, radash, node_crypto, node_fs, ignore, Handlebars, dayjs, hastUtilToMdast, mdastUtilFromAdf, mdastUtilToMarkdown, rehypeParse, unified, chokidar, cosmiconfig, zod, jsonmap, googleGenai, pino, uuid, cheerio, yaml, mammoth, Ajv, addFormats, textsplitters, jsClientRest);