@karmaniverous/jeeves-watcher 0.3.1 → 0.4.1

package/dist/cjs/index.js

@@ -6,12 +6,20 @@ var node_path = require('node:path');
 var picomatch = require('picomatch');
 var radash = require('radash');
 var node_crypto = require('node:crypto');
+var node_fs = require('node:fs');
+var ignore = require('ignore');
+var Handlebars = require('handlebars');
+var dayjs = require('dayjs');
+var hastUtilToMdast = require('hast-util-to-mdast');
+var mdastUtilFromAdf = require('mdast-util-from-adf');
+var mdastUtilToMarkdown = require('mdast-util-to-markdown');
+var rehypeParse = require('rehype-parse');
+var unified = require('unified');
+var chokidar = require('chokidar');
 var cosmiconfig = require('cosmiconfig');
 var zod = require('zod');
 var jsonmap = require('@karmaniverous/jsonmap');
 var googleGenai = require('@langchain/google-genai');
-var node_fs = require('node:fs');
-var ignore = require('ignore');
 var pino = require('pino');
 var uuid = require('uuid');
 var cheerio = require('cheerio');
@@ -21,7 +29,6 @@ var Ajv = require('ajv');
 var addFormats = require('ajv-formats');
 var textsplitters = require('@langchain/textsplitters');
 var jsClientRest = require('@qdrant/js-client-rest');
-var chokidar = require('chokidar');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -438,6 +445,486 @@ function createApiServer(options) {
     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.
@@ -639,7 +1126,12 @@ const inferenceRuleSchema = zod.z.object({
     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.
@@ -677,6 +1169,22 @@ const jeevesWatcherConfigSchema = zod.z.object({
         .record(zod.z.string(), jsonmap.jsonMapMapSchema)
         .optional()
         .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. */
@@ -934,258 +1442,52 @@ function createGeminiProvider(config, logger) {
             }, {
                 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 });
+                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);
 }
 
 /**
@@ -1417,7 +1719,7 @@ function createJsonMapLib() {
     };
 }
 /**
- * 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,
@@ -1427,15 +1729,18 @@ function createJsonMapLib() {
  * @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);
@@ -1445,10 +1750,24 @@ async function applyRules(compiledRules, attributes, namedMaps, logger) {
                 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 {
@@ -1471,9 +1790,31 @@ async function applyRules(compiledRules, attributes, namedMaps, logger) {
                     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 };
 }
 
 /**
@@ -1562,23 +1903,32 @@ function compileRules(rules) {
  * @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,
+    };
 }
 
 /**
@@ -1649,6 +1999,7 @@ class DocumentProcessor {
     vectorStore;
     compiledRules;
     logger;
+    templateEngine;
     /**
      * Create a new DocumentProcessor.
      *
@@ -1657,13 +2008,15 @@ 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, 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.
@@ -1674,13 +2027,15 @@ class DocumentProcessor {
         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) {
@@ -1692,7 +2047,7 @@ class DocumentProcessor {
             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
@@ -1786,7 +2141,7 @@ class DocumentProcessor {
                 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);
@@ -1804,8 +2159,17 @@ class DocumentProcessor {
      *
      * @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');
     }
 }
@@ -2334,6 +2698,104 @@ class SystemHealth {
     }
 }
 
+/**
+ * @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 };
+}
+/**
+ * Convert ignored glob patterns to picomatch matcher functions.
+ *
+ * Chokidar v5 replaced the external `anymatch` dependency with an inline
+ * implementation that does **exact string equality** for string matchers,
+ * breaking glob-based `ignored` patterns. This function converts glob strings
+ * to picomatch functions that chokidar's `createPattern` passes through
+ * unchanged (`typeof matcher === 'function'`).
+ *
+ * Non-string entries (functions, RegExps) are passed through as-is.
+ *
+ * @param ignored - Array of ignored patterns (globs, functions, RegExps).
+ * @returns Array with glob strings replaced by picomatch matcher functions.
+ */
+function resolveIgnored(ignored) {
+    return ignored.map((entry) => {
+        if (typeof entry !== 'string')
+            return entry;
+        // If the string contains glob characters, convert to a picomatch function.
+        // Literal strings (exact paths) are also converted for consistent matching.
+        const normalizedPattern = entry.replace(/\\/g, '/');
+        const matcher = picomatch(normalizedPattern, { dot: true, nocase: true });
+        return (filePath) => {
+            const normalized = filePath.replace(/\\/g, '/');
+            return matcher(normalized);
+        };
+    });
+}
+
 /**
  * @module watcher
  * Filesystem watcher wrapping chokidar. I/O: watches files/directories for add/change/unlink events, enqueues to processing queue.
@@ -2348,6 +2810,7 @@ class FileSystemWatcher {
     logger;
     health;
     gitignoreFilter;
+    globMatches;
     watcher;
     /**
      * Create a new FileSystemWatcher.
@@ -2364,6 +2827,7 @@ class FileSystemWatcher {
         this.processor = processor;
         this.logger = logger;
         this.gitignoreFilter = options.gitignoreFilter;
+        this.globMatches = () => true;
         const healthOptions = {
             maxRetries: options.maxRetries,
             maxBackoffMs: options.maxBackoffMs,
@@ -2376,8 +2840,20 @@ class FileSystemWatcher {
      * Start watching the filesystem and processing events.
      */
     start() {
-        this.watcher = chokidar.watch(this.config.paths, {
-            ignored: this.config.ignored,
+        // 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;
+        // Chokidar v5's inline anymatch does exact string equality for string
+        // matchers, breaking glob-based ignored patterns. Convert to picomatch
+        // functions that chokidar passes through as-is.
+        const ignored = this.config.ignored
+            ? resolveIgnored(this.config.ignored)
+            : undefined;
+        this.watcher = chokidar.watch(roots, {
+            ignored,
             usePolling: this.config.usePolling,
             interval: this.config.pollIntervalMs,
             awaitWriteFinish: this.config.stabilityThresholdMs
@@ -2387,6 +2863,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('add', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File added');
@@ -2394,6 +2872,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('change', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File changed');
@@ -2401,6 +2881,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('unlink', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File removed');
@@ -2473,51 +2955,21 @@ class FileSystemWatcher {
 }
 
 /**
- * @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
@@ -2537,17 +2989,28 @@ function installShutdownHandlers(stop) {
     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.
  */
@@ -2582,56 +3045,26 @@ class JeevesWatcher {
     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');
     }
@@ -2662,22 +3095,61 @@ class JeevesWatcher {
         }
         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(),
         });
@@ -2699,7 +3171,9 @@ class JeevesWatcher {
             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) {
@@ -2707,19 +3181,7 @@ class 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;
-}
+// startFromConfig re-exported from ./startFromConfig
 
 exports.DocumentProcessor = DocumentProcessor;
 exports.EventQueue = EventQueue;
@@ -2727,15 +3189,18 @@ exports.FileSystemWatcher = FileSystemWatcher;
 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;
@@ -2743,10 +3208,13 @@ exports.extractText = extractText;
 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;