@karmaniverous/jeeves-watcher 0.2.0 → 0.2.2

package/dist/cjs/index.js

@@ -1,12 +1,11 @@
 'use strict';
 
 var Fastify = require('fastify');
-var radash = require('radash');
-var node_crypto = require('node:crypto');
 var promises = require('node:fs/promises');
 var node_path = require('node:path');
 var picomatch = require('picomatch');
-var chokidar = require('chokidar');
+var radash = require('radash');
+var node_crypto = require('node:crypto');
 var cosmiconfig = require('cosmiconfig');
 var zod = require('zod');
 var jsonmap = require('@karmaniverous/jsonmap');
@@ -20,6 +19,7 @@ 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);
@@ -41,74 +41,28 @@ function _interopNamespaceDefault(e) {
 var cheerio__namespace = /*#__PURE__*/_interopNamespaceDefault(cheerio);
 
 /**
- * @module metadata/metadata
- * Persists file metadata as .meta.json. I/O: reads/writes/deletes metadata files under metadataDir. Path mapping via SHA-256 hash.
- */
-/**
- * Normalise a file path for deterministic mapping: lowercase, forward slashes, strip leading drive letter colon.
- *
- * @param filePath - The original file path.
- * @returns The normalised path string.
- */
-function normalisePath$1(filePath) {
-    return filePath
-        .replace(/\\/g, '/')
-        .replace(/^([A-Za-z]):/, (_m, letter) => letter.toLowerCase())
-        .toLowerCase();
-}
-/**
- * Derive a deterministic `.meta.json` path for a given file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @returns The full path to the metadata file.
- */
-function metadataPath(filePath, metadataDir) {
-    const normalised = normalisePath$1(filePath);
-    const hash = node_crypto.createHash('sha256').update(normalised, 'utf8').digest('hex');
-    return node_path.join(metadataDir, `${hash}.meta.json`);
-}
-/**
- * Read persisted metadata for a file.
- *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @returns The parsed metadata object, or `null` if not found.
- */
-async function readMetadata(filePath, metadataDir) {
-    try {
-        const raw = await promises.readFile(metadataPath(filePath, metadataDir), 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Write metadata for a file.
+ * @module util/normalizeError
  *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
- * @param metadata - The metadata to persist.
+ * Normalizes unknown thrown values into proper Error objects for pino serialization.
  */
-async function writeMetadata(filePath, metadataDir, metadata) {
-    const dest = metadataPath(filePath, metadataDir);
-    await promises.mkdir(node_path.dirname(dest), { recursive: true });
-    await promises.writeFile(dest, JSON.stringify(metadata, null, 2), 'utf8');
-}
 /**
- * Delete metadata for a file.
+ * Convert an unknown thrown value into a proper Error with message, stack, and cause.
+ * Pino's built-in `err` serializer requires an Error instance to extract message/stack.
  *
- * @param filePath - The watched file path.
- * @param metadataDir - The root metadata directory.
+ * @param error - The caught value (may not be an Error).
+ * @returns A proper Error instance.
  */
-async function deleteMetadata(filePath, metadataDir) {
-    try {
-        await promises.rm(metadataPath(filePath, metadataDir));
-    }
-    catch {
-        // Ignore if file doesn't exist.
-    }
+function normalizeError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === 'string')
+        return new Error(error);
+    const message = typeof error === 'object' && error !== null && 'message' in error
+        ? String(error.message)
+        : String(error);
+    const normalized = new Error(message);
+    normalized.cause = error;
+    return normalized;
 }
 
 /**
@@ -208,107 +162,266 @@ async function processAllFiles(watchPaths, ignoredPaths, processor, method) {
 }
 
 /**
- * Create the Fastify API server with all routes registered.
- *
- * The returned instance is not yet listening — call `server.listen()` to start.
+ * @module api/handlers/configReindex
+ * Fastify route handler for POST /config-reindex. Triggers an async reindex job scoped to rules or full processing.
+ */
+/**
+ * Create handler for POST /config-reindex.
  *
- * @param options - The server options.
- * @returns A configured Fastify instance.
+ * @param deps - Route dependencies.
  */
-function createApiServer(options) {
-    const { processor, vectorStore, embeddingProvider, logger } = options;
-    const app = Fastify({ logger: false });
-    app.get('/status', () => ({
-        status: 'ok',
-        uptime: process.uptime(),
-    }));
-    app.post('/metadata', async (request, reply) => {
+function createConfigReindexHandler(deps) {
+    return async (request, reply) => {
         try {
-            const { path, metadata } = request.body;
-            await processor.processMetadataUpdate(path, metadata);
-            return { ok: true };
+            const scope = request.body.scope ?? 'rules';
+            // Return immediately and run async
+            void (async () => {
+                try {
+                    if (scope === 'rules') {
+                        const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processRulesUpdate');
+                        deps.logger.info({ scope, filesProcessed: count }, 'Config reindex (rules) completed');
+                    }
+                    else {
+                        const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processFile');
+                        deps.logger.info({ scope, filesProcessed: count }, 'Config reindex (full) completed');
+                    }
+                }
+                catch (error) {
+                    deps.logger.error({ err: normalizeError(error), scope }, 'Config reindex failed');
+                }
+            })();
+            return await reply.status(200).send({ status: 'started', scope });
         }
         catch (error) {
-            logger.error({ error }, 'Metadata update failed');
-            return reply.status(500).send({ error: 'Internal server error' });
+            deps.logger.error({ err: normalizeError(error) }, 'Config reindex request failed');
+            return await reply.status(500).send({ error: 'Internal server error' });
         }
-    });
-    app.post('/search', async (request, reply) => {
+    };
+}
+
+/**
+ * @module api/handlers/metadata
+ * Fastify route handler for POST /metadata. Performs enrichment metadata updates via the document processor.
+ */
+/**
+ * Create handler for POST /metadata.
+ *
+ * @param deps - Route dependencies.
+ */
+function createMetadataHandler(deps) {
+    return async (request, reply) => {
         try {
-            const { query, limit = 10 } = request.body;
-            const vectors = await embeddingProvider.embed([query]);
-            const results = await vectorStore.search(vectors[0], limit);
-            return results;
+            const { path, metadata } = request.body;
+            await deps.processor.processMetadataUpdate(path, metadata);
+            return { ok: true };
         }
         catch (error) {
-            logger.error({ error }, 'Search failed');
+            deps.logger.error({ err: normalizeError(error) }, 'Metadata update failed');
             return reply.status(500).send({ error: 'Internal server error' });
         }
-    });
-    app.post('/reindex', async (_request, reply) => {
-        try {
-            const count = await processAllFiles(options.config.watch.paths, options.config.watch.ignored, processor, 'processFile');
-            return await reply.status(200).send({ ok: true, filesIndexed: count });
-        }
-        catch (error) {
-            logger.error({ error }, 'Reindex failed');
-            return await reply.status(500).send({ error: 'Internal server error' });
-        }
-    });
-    app.post('/rebuild-metadata', async (_request, reply) => {
+    };
+}
+
+/**
+ * @module util/normalizePath
+ * Normalizes file paths for deterministic mapping: lowercase, forward slashes, optional drive letter stripping.
+ */
+/**
+ * Normalize a file path: lowercase, forward slashes, optionally strip drive letter colon.
+ *
+ * @param filePath - The original file path.
+ * @param stripDriveLetter - Whether to strip the colon from a leading drive letter (e.g. `C:` → `c`).
+ * @returns The normalized path string.
+ */
+function normalizePath(filePath, stripDriveLetter = false) {
+    let result = filePath.replace(/\\/g, '/').toLowerCase();
+    if (stripDriveLetter) {
+        result = result.replace(/^([a-z]):/, (_m, letter) => letter);
+    }
+    return result;
+}
+
+/**
+ * @module metadata/metadata
+ * Persists file metadata as .meta.json. I/O: reads/writes/deletes metadata files under metadataDir. Path mapping via SHA-256 hash.
+ */
+/**
+ * Derive a deterministic `.meta.json` path for a given file.
+ *
+ * @param filePath - The watched file path.
+ * @param metadataDir - The root metadata directory.
+ * @returns The full path to the metadata file.
+ */
+function metadataPath(filePath, metadataDir) {
+    const normalised = normalizePath(filePath, true);
+    const hash = node_crypto.createHash('sha256').update(normalised, 'utf8').digest('hex');
+    return node_path.join(metadataDir, `${hash}.meta.json`);
+}
+/**
+ * Read persisted metadata for a file.
+ *
+ * @param filePath - The watched file path.
+ * @param metadataDir - The root metadata directory.
+ * @returns The parsed metadata object, or `null` if not found.
+ */
+async function readMetadata(filePath, metadataDir) {
+    try {
+        const raw = await promises.readFile(metadataPath(filePath, metadataDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write metadata for a file.
+ *
+ * @param filePath - The watched file path.
+ * @param metadataDir - The root metadata directory.
+ * @param metadata - The metadata to persist.
+ */
+async function writeMetadata(filePath, metadataDir, metadata) {
+    const dest = metadataPath(filePath, metadataDir);
+    await promises.mkdir(node_path.dirname(dest), { recursive: true });
+    await promises.writeFile(dest, JSON.stringify(metadata, null, 2), 'utf8');
+}
+/**
+ * Delete metadata for a file.
+ *
+ * @param filePath - The watched file path.
+ * @param metadataDir - The root metadata directory.
+ */
+async function deleteMetadata(filePath, metadataDir) {
+    try {
+        await promises.rm(metadataPath(filePath, metadataDir));
+    }
+    catch {
+        // Ignore if file doesn't exist.
+    }
+}
+
+/**
+ * @module metadata/constants
+ * Shared constants for metadata key classification. System keys are injected by the indexing pipeline, not user-provided.
+ */
+/** Keys managed by the indexing pipeline (not user enrichment). */
+const SYSTEM_METADATA_KEYS = [
+    'file_path',
+    'chunk_index',
+    'total_chunks',
+    'content_hash',
+    'chunk_text',
+];
+
+/**
+ * @module api/handlers/rebuildMetadata
+ * Fastify route handler for POST /rebuild-metadata. Recreates enrichment metadata files from vector store payloads.
+ */
+/**
+ * Create handler for POST /rebuild-metadata.
+ *
+ * @param deps - Route dependencies.
+ */
+function createRebuildMetadataHandler(deps) {
+    return async (_request, reply) => {
         try {
-            const metadataDir = options.config.metadataDir ?? '.jeeves-metadata';
-            const SYSTEM_KEYS = [
-                'file_path',
-                'chunk_index',
-                'total_chunks',
-                'content_hash',
-                'chunk_text',
-            ];
-            for await (const point of vectorStore.scroll()) {
+            const metadataDir = deps.config.metadataDir ?? '.jeeves-metadata';
+            const systemKeys = [...SYSTEM_METADATA_KEYS];
+            for await (const point of deps.vectorStore.scroll()) {
                 const payload = point.payload;
                 const filePath = payload['file_path'];
                 if (typeof filePath !== 'string' || filePath.length === 0)
                     continue;
                 // Persist only enrichment-ish fields, not chunking/index fields.
-                const enrichment = radash.omit(payload, SYSTEM_KEYS);
+                const enrichment = radash.omit(payload, systemKeys);
                 await writeMetadata(filePath, metadataDir, enrichment);
             }
             return await reply.status(200).send({ ok: true });
         }
         catch (error) {
-            logger.error({ error }, 'Rebuild metadata failed');
+            deps.logger.error({ err: normalizeError(error) }, 'Rebuild metadata failed');
             return await reply.status(500).send({ error: 'Internal server error' });
         }
-    });
-    app.post('/config-reindex', async (request, reply) => {
+    };
+}
+
+/**
+ * @module api/handlers/reindex
+ * Fastify route handler for POST /reindex. Reprocesses all watched files through the processor.
+ */
+/**
+ * Create handler for POST /reindex.
+ *
+ * @param deps - Route dependencies.
+ */
+function createReindexHandler(deps) {
+    return async (_request, reply) => {
         try {
-            const scope = request.body.scope ?? 'rules';
-            // Return immediately and run async
-            void (async () => {
-                try {
-                    if (scope === 'rules') {
-                        // Re-apply inference rules to all files, update Qdrant payloads (no re-embedding)
-                        const count = await processAllFiles(options.config.watch.paths, options.config.watch.ignored, processor, 'processRulesUpdate');
-                        logger.info({ scope, filesProcessed: count }, 'Config reindex (rules) completed');
-                    }
-                    else {
-                        // Full reindex: re-extract, re-embed, re-upsert
-                        const count = await processAllFiles(options.config.watch.paths, options.config.watch.ignored, processor, 'processFile');
-                        logger.info({ scope, filesProcessed: count }, 'Config reindex (full) completed');
-                    }
-                }
-                catch (error) {
-                    logger.error({ error, scope }, 'Config reindex failed');
-                }
-            })();
-            return await reply.status(200).send({ status: 'started', scope });
+            const count = await processAllFiles(deps.config.watch.paths, deps.config.watch.ignored, deps.processor, 'processFile');
+            return await reply.status(200).send({ ok: true, filesIndexed: count });
         }
         catch (error) {
-            logger.error({ error }, 'Config reindex request failed');
+            deps.logger.error({ err: normalizeError(error) }, 'Reindex failed');
             return await reply.status(500).send({ error: 'Internal server error' });
         }
+    };
+}
+
+/**
+ * @module api/handlers/search
+ * Fastify route handler for POST /search. Embeds a query and performs vector store similarity search.
+ */
+/**
+ * Create handler for POST /search.
+ *
+ * @param deps - Route dependencies.
+ */
+function createSearchHandler(deps) {
+    return async (request, reply) => {
+        try {
+            const { query, limit = 10 } = request.body;
+            const vectors = await deps.embeddingProvider.embed([query]);
+            const results = await deps.vectorStore.search(vectors[0], limit);
+            return results;
+        }
+        catch (error) {
+            deps.logger.error({ err: normalizeError(error) }, 'Search failed');
+            return reply.status(500).send({ error: 'Internal server error' });
+        }
+    };
+}
+
+/**
+ * @module api/handlers/status
+ * Fastify route handler for GET /status. Pure handler: returns process uptime and health.
+ */
+/**
+ * Create handler for GET /status.
+ */
+function createStatusHandler() {
+    return () => ({
+        status: 'ok',
+        uptime: process.uptime(),
     });
+}
+
+/**
+ * Create the Fastify API server with all routes registered.
+ *
+ * The returned instance is not yet listening — call `server.listen()` to start.
+ *
+ * @param options - The server options.
+ * @returns A configured Fastify instance.
+ */
+function createApiServer(options) {
+    const { processor, vectorStore, embeddingProvider, logger, config } = options;
+    const app = Fastify({ logger: false });
+    app.get('/status', createStatusHandler());
+    app.post('/metadata', createMetadataHandler({ processor, logger }));
+    app.post('/search', createSearchHandler({ embeddingProvider, vectorStore, logger }));
+    app.post('/reindex', createReindexHandler({ config, processor, logger }));
+    app.post('/rebuild-metadata', createRebuildMetadataHandler({ config, vectorStore, logger }));
+    app.post('/config-reindex', createConfigReindexHandler({ config, processor, logger }));
     return app;
 }
 
@@ -554,6 +667,51 @@ const jeevesWatcherConfigSchema = zod.z.object({
         .describe('Timeout in milliseconds for graceful shutdown.'),
 });
 
+/**
+ * @module config/substituteEnvVars
+ *
+ * Deep-walks config objects and replaces `${VAR_NAME}` patterns with environment variable values.
+ */
+const ENV_PATTERN = /\$\{([^}]+)\}/g;
+/**
+ * Replace `${VAR_NAME}` patterns in a string with `process.env.VAR_NAME`.
+ *
+ * @param value - The string to process.
+ * @returns The string with env vars substituted.
+ * @throws If a referenced env var is not set.
+ */
+function substituteString(value) {
+    return value.replace(ENV_PATTERN, (match, varName) => {
+        const envValue = process.env[varName];
+        if (envValue === undefined) {
+            throw new Error(`Environment variable \${${varName}} referenced in config is not set.`);
+        }
+        return envValue;
+    });
+}
+/**
+ * Deep-walk a value and substitute `${VAR_NAME}` patterns in all string values.
+ *
+ * @param value - The value to walk (object, array, or primitive).
+ * @returns A new value with all env var references resolved.
+ */
+function substituteEnvVars(value) {
+    if (typeof value === 'string') {
+        return substituteString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => substituteEnvVars(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = substituteEnvVars(val);
+        }
+        return result;
+    }
+    return value;
+}
+
 const MODULE_NAME = 'jeeves-watcher';
 /**
  * Merge sensible defaults into a loaded configuration.
@@ -589,7 +747,8 @@ async function loadConfig(configPath) {
     }
     try {
         const validated = jeevesWatcherConfigSchema.parse(result.config);
-        return applyDefaults(validated);
+        const withDefaults = applyDefaults(validated);
+        return substituteEnvVars(withDefaults);
     }
     catch (error) {
         if (error instanceof zod.ZodError) {
@@ -602,6 +761,31 @@ async function loadConfig(configPath) {
     }
 }
 
+/**
+ * @module util/logger
+ * Logger fallback helper. Provides a unified warn interface that delegates to pino or console.
+ */
+/**
+ * Return a minimal logger that delegates to pino if available, otherwise console.
+ *
+ * @param logger - Optional pino logger instance.
+ * @returns A minimal logger.
+ */
+function getLogger(logger) {
+    if (logger)
+        return logger;
+    return {
+        warn(obj, msg) {
+            if (msg) {
+                console.warn(obj, msg);
+            }
+            else {
+                console.warn(obj);
+            }
+        },
+    };
+}
+
 /**
  * @module util/retry
  * Small async retry helper with exponential backoff. Side effects: sleeps between attempts; can invoke onRetry callback for logging.
@@ -706,6 +890,7 @@ function createGeminiProvider(config, logger) {
         throw new Error('Gemini embedding provider requires config.embedding.apiKey');
     }
     const dimensions = config.dimensions ?? 3072;
+    const log = getLogger(logger);
     const embedder = new googleGenai.GoogleGenerativeAIEmbeddings({
         apiKey: config.apiKey,
         model: config.model,
@@ -715,17 +900,7 @@ function createGeminiProvider(config, logger) {
         async embed(texts) {
             const vectors = await retry(async (attempt) => {
                 if (attempt > 1) {
-                    const msg = {
-                        attempt,
-                        provider: 'gemini',
-                        model: config.model,
-                    };
-                    if (logger) {
-                        logger.warn(msg, 'Retrying embedding request');
-                    }
-                    else {
-                        console.warn(msg, 'Retrying embedding request');
-                    }
+                    log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
                 }
                 // embedDocuments returns vectors for multiple texts
                 return embedder.embedDocuments(texts);
@@ -735,19 +910,13 @@ function createGeminiProvider(config, logger) {
                 maxDelayMs: 10_000,
                 jitter: 0.2,
                 onRetry: ({ attempt, delayMs, error }) => {
-                    const msg = {
+                    log.warn({
                         attempt,
                         delayMs,
                         provider: 'gemini',
                         model: config.model,
-                        error,
-                    };
-                    if (logger) {
-                        logger.warn(msg, 'Embedding call failed; will retry');
-                    }
-                    else {
-                        console.warn(msg, 'Embedding call failed; will retry');
-                    }
+                        err: normalizeError(error),
+                    }, 'Embedding call failed; will retry');
                 },
             });
             // Validate dimensions
@@ -828,15 +997,6 @@ function contentHash(text) {
  */
 /** Namespace UUID for jeeves-watcher point IDs. */
 const NAMESPACE = '6a6f686e-6761-4c74-ad6a-656576657321';
-/**
- * Normalise a file path for deterministic point ID generation.
- *
- * @param filePath - The original file path.
- * @returns The normalised path string.
- */
-function normalisePath(filePath) {
-    return filePath.replace(/\\/g, '/').toLowerCase();
-}
 /**
  * Generate a deterministic UUID v5 point ID for a file (and optional chunk index).
  *
@@ -846,8 +1006,8 @@ function normalisePath(filePath) {
  */
 function pointId(filePath, chunkIndex) {
     const key = chunkIndex !== undefined
-        ? `${normalisePath(filePath)}#${String(chunkIndex)}`
-        : normalisePath(filePath);
+        ? `${normalizePath(filePath)}#${String(chunkIndex)}`
+        : normalizePath(filePath);
     return uuid.v5(key, NAMESPACE);
 }
 
@@ -864,6 +1024,9 @@ function pointId(filePath, chunkIndex) {
  */
 function extractMarkdownFrontmatter(markdown) {
     const trimmed = markdown.replace(/^\uFEFF/, '');
+    // Only attempt frontmatter parsing if the file starts with ---
+    if (!/^\s*---/.test(trimmed))
+        return { body: markdown };
     const match = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/m.exec(trimmed);
     if (!match)
         return { body: markdown };
@@ -966,66 +1129,11 @@ async function extractText(filePath, extension) {
 }
 
 /**
- * Build {@link FileAttributes} from a file path and stat info.
- *
- * @param filePath - The file path.
- * @param stats - The file stats.
- * @param extractedFrontmatter - Optional extracted frontmatter.
- * @param extractedJson - Optional parsed JSON content.
- * @returns The constructed file attributes.
+ * @module rules/templates
+ * Resolves template variables (`${path.to.value}`) in rule `set` objects against file attributes.
  */
-function buildAttributes(filePath, stats, extractedFrontmatter, extractedJson) {
-    const normalised = filePath.replace(/\\/g, '/');
-    const attrs = {
-        file: {
-            path: normalised,
-            directory: node_path.dirname(normalised).replace(/\\/g, '/'),
-            filename: node_path.basename(normalised),
-            extension: node_path.extname(normalised),
-            sizeBytes: stats.size,
-            modified: stats.mtime.toISOString(),
-        },
-    };
-    if (extractedFrontmatter)
-        attrs.frontmatter = extractedFrontmatter;
-    if (extractedJson)
-        attrs.json = extractedJson;
-    return attrs;
-}
 /**
- * Create an ajv instance with a custom `glob` format for picomatch glob matching.
- *
- * @returns The configured ajv instance.
- */
-function createRuleAjv() {
-    const ajv = new Ajv({ allErrors: true });
-    addFormats(ajv);
-    ajv.addKeyword({
-        keyword: 'glob',
-        type: 'string',
-        schemaType: 'string',
-        validate: (pattern, data) => picomatch.isMatch(data, pattern),
-    });
-    return ajv;
-}
-/**
- * Compile an array of inference rules into executable validators.
- *
- * @param rules - The inference rule definitions.
- * @returns An array of compiled rules.
- */
-function compileRules(rules) {
-    const ajv = createRuleAjv();
-    return rules.map((rule, idx) => ({
-        rule,
-        validate: ajv.compile({
-            $id: `rule-${String(idx)}`,
-            ...rule.match,
-        }),
-    }));
-}
-/**
- * Resolve `$\{template.vars\}` in a value against the given attributes.
+ * Resolve `${template.vars}` in a value against the given attributes.
  *
  * @param value - The value to resolve.
  * @param attributes - The file attributes for variable lookup.
@@ -1055,9 +1163,13 @@ function resolveSet(setObj, attributes) {
     }
     return result;
 }
+
+/**
+ * @module rules/apply
+ * Applies compiled inference rules to file attributes, producing merged metadata via template resolution and JsonMap transforms.
+ */
 /**
  * Create the lib object for JsonMap transformations.
- * Provides utility functions for path manipulation.
  *
  * @returns The lib object.
  */
@@ -1081,7 +1193,7 @@ function createJsonMapLib() {
  * @param compiledRules - The compiled rules to evaluate.
  * @param attributes - The file attributes to match against.
  * @param namedMaps - Optional record of named JsonMap definitions.
- * @param logger - Optional pino logger for warnings (falls back to console.warn).
+ * @param logger - Optional logger for warnings (falls back to console.warn).
  * @returns The merged metadata from all matching rules.
  */
 async function applyRules(compiledRules, attributes, namedMaps, logger) {
@@ -1131,6 +1243,80 @@ async function applyRules(compiledRules, attributes, namedMaps, logger) {
     return merged;
 }
 
+/**
+ * @module rules/attributes
+ * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
+ */
+/**
+ * Build {@link FileAttributes} from a file path and stat info.
+ *
+ * @param filePath - The file path.
+ * @param stats - The file stats.
+ * @param extractedFrontmatter - Optional extracted frontmatter.
+ * @param extractedJson - Optional parsed JSON content.
+ * @returns The constructed file attributes.
+ */
+function buildAttributes(filePath, stats, extractedFrontmatter, extractedJson) {
+    const normalised = filePath.replace(/\\/g, '/');
+    const attrs = {
+        file: {
+            path: normalised,
+            directory: node_path.dirname(normalised).replace(/\\/g, '/'),
+            filename: node_path.basename(normalised),
+            extension: node_path.extname(normalised),
+            sizeBytes: stats.size,
+            modified: stats.mtime.toISOString(),
+        },
+    };
+    if (extractedFrontmatter)
+        attrs.frontmatter = extractedFrontmatter;
+    if (extractedJson)
+        attrs.json = extractedJson;
+    return attrs;
+}
+
+/**
+ * @module rules/ajvSetup
+ * AJV instance factory with custom glob keyword for picomatch-based pattern matching in rule schemas.
+ */
+/**
+ * Create an AJV instance with a custom `glob` format for picomatch glob matching.
+ *
+ * @returns The configured AJV instance.
+ */
+function createRuleAjv() {
+    const ajv = new Ajv({ allErrors: true });
+    addFormats(ajv);
+    ajv.addKeyword({
+        keyword: 'glob',
+        type: 'string',
+        schemaType: 'string',
+        validate: (pattern, data) => picomatch.isMatch(data, pattern),
+    });
+    return ajv;
+}
+
+/**
+ * @module rules/compile
+ * Compiles inference rule definitions into executable AJV validators for efficient rule evaluation.
+ */
+/**
+ * Compile an array of inference rules into executable validators.
+ *
+ * @param rules - The inference rule definitions.
+ * @returns An array of compiled rules.
+ */
+function compileRules(rules) {
+    const ajv = createRuleAjv();
+    return rules.map((rule, idx) => ({
+        rule,
+        validate: ajv.compile({
+            $id: `rule-${String(idx)}`,
+            ...rule.match,
+        }),
+    }));
+}
+
 /**
  * @module processor/buildMetadata
  * Builds merged metadata from file content, inference rules, and enrichment. I/O: reads files, extracts text, loads enrichment .meta.json.
@@ -1298,7 +1484,7 @@ class DocumentProcessor {
             this.logger.info({ filePath, chunks: chunks.length }, 'File processed successfully');
         }
         catch (error) {
-            this.logger.error({ filePath, error }, 'Failed to process file');
+            this.logger.error({ filePath, err: normalizeError(error) }, 'Failed to process file');
         }
     }
     /**
@@ -1318,7 +1504,7 @@ class DocumentProcessor {
             this.logger.info({ filePath }, 'File deleted from index');
         }
         catch (error) {
-            this.logger.error({ filePath, error }, 'Failed to delete file');
+            this.logger.error({ filePath, err: normalizeError(error) }, 'Failed to delete file');
         }
     }
     /**
@@ -1346,7 +1532,7 @@ class DocumentProcessor {
             return merged;
         }
         catch (error) {
-            this.logger.error({ filePath, error }, 'Failed to update metadata');
+            this.logger.error({ filePath, err: normalizeError(error) }, 'Failed to update metadata');
             return null;
         }
     }
@@ -1376,7 +1562,7 @@ class DocumentProcessor {
             return metadata;
         }
         catch (error) {
-            this.logger.error({ filePath, error }, 'Failed to re-apply rules');
+            this.logger.error({ filePath, err: normalizeError(error) }, 'Failed to re-apply rules');
             return null;
         }
     }
@@ -1543,7 +1729,7 @@ class VectorStoreClient {
     client;
     collectionName;
     dims;
-    logger;
+    log;
     /**
      * Create a new VectorStoreClient.
      *
@@ -1559,7 +1745,7 @@ class VectorStoreClient {
         });
         this.collectionName = config.collectionName;
         this.dims = dimensions;
-        this.logger = logger;
+        this.log = getLogger(logger);
     }
     /**
      * Ensure the collection exists with correct dimensions and Cosine distance.
@@ -1588,17 +1774,7 @@ class VectorStoreClient {
             return;
         await retry(async (attempt) => {
             if (attempt > 1) {
-                const msg = {
-                    attempt,
-                    operation: 'qdrant.upsert',
-                    points: points.length,
-                };
-                if (this.logger) {
-                    this.logger.warn(msg, 'Retrying Qdrant upsert');
-                }
-                else {
-                    console.warn(msg, 'Retrying Qdrant upsert');
-                }
+                this.log.warn({ attempt, operation: 'qdrant.upsert', points: points.length }, 'Retrying Qdrant upsert');
             }
             await this.client.upsert(this.collectionName, {
                 wait: true,
@@ -1614,13 +1790,12 @@ class VectorStoreClient {
             maxDelayMs: 10_000,
             jitter: 0.2,
             onRetry: ({ attempt, delayMs, error }) => {
-                const msg = { attempt, delayMs, operation: 'qdrant.upsert', error };
-                if (this.logger) {
-                    this.logger.warn(msg, 'Qdrant upsert failed; will retry');
-                }
-                else {
-                    console.warn(msg, 'Qdrant upsert failed; will retry');
-                }
+                this.log.warn({
+                    attempt,
+                    delayMs,
+                    operation: 'qdrant.upsert',
+                    err: normalizeError(error),
+                }, 'Qdrant upsert failed; will retry');
             },
         });
     }
@@ -1634,17 +1809,7 @@ class VectorStoreClient {
             return;
         await retry(async (attempt) => {
             if (attempt > 1) {
-                const msg = {
-                    attempt,
-                    operation: 'qdrant.delete',
-                    ids: ids.length,
-                };
-                if (this.logger) {
-                    this.logger.warn(msg, 'Retrying Qdrant delete');
-                }
-                else {
-                    console.warn(msg, 'Retrying Qdrant delete');
-                }
+                this.log.warn({ attempt, operation: 'qdrant.delete', ids: ids.length }, 'Retrying Qdrant delete');
             }
             await this.client.delete(this.collectionName, {
                 wait: true,
@@ -1656,13 +1821,12 @@ class VectorStoreClient {
             maxDelayMs: 10_000,
             jitter: 0.2,
             onRetry: ({ attempt, delayMs, error }) => {
-                const msg = { attempt, delayMs, operation: 'qdrant.delete', error };
-                if (this.logger) {
-                    this.logger.warn(msg, 'Qdrant delete failed; will retry');
-                }
-                else {
-                    console.warn(msg, 'Qdrant delete failed; will retry');
-                }
+                this.log.warn({
+                    attempt,
+                    delayMs,
+                    operation: 'qdrant.delete',
+                    err: normalizeError(error),
+                }, 'Qdrant delete failed; will retry');
             },
         });
     }
@@ -1816,7 +1980,7 @@ class FileSystemWatcher {
             this.queue.enqueue({ type: 'delete', path, priority: 'normal' }, () => this.processor.deleteFile(path));
         });
         this.watcher.on('error', (error) => {
-            this.logger.error({ error }, 'Watcher error');
+            this.logger.error({ err: normalizeError(error) }, 'Watcher error');
         });
         this.queue.process();
         this.logger.info({ paths: this.config.paths }, 'Filesystem watcher started');
@@ -1833,63 +1997,141 @@ 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.
+ */
+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 app/shutdown
+ * Process signal shutdown orchestration. Installs SIGINT/SIGTERM handlers that invoke a provided async stop function.
+ */
+/**
+ * Install process signal handlers.
+ *
+ * @param stop - Async stop function to invoke on shutdown signals.
+ */
+function installShutdownHandlers(stop) {
+    const shutdown = async () => {
+        await stop();
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void shutdown());
+    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) => new FileSystemWatcher(config, queue, processor, logger),
+    createApiServer,
+};
 /**
  * Main application class that wires together all components.
  */
 class JeevesWatcher {
     config;
     configPath;
+    factories;
     logger;
     watcher;
     queue;
     server;
     processor;
     configWatcher;
-    configDebounce;
     /**
      * Create a new JeevesWatcher instance.
      *
      * @param config - The application configuration.
      * @param configPath - Optional config file path to watch for changes.
+     * @param factories - Optional component factories (for dependency injection).
      */
-    constructor(config, configPath) {
+    constructor(config, configPath, factories = {}) {
         this.config = config;
         this.configPath = configPath;
+        this.factories = { ...defaultFactories, ...factories };
     }
     /**
      * Start the watcher, API server, and all components.
      */
     async start() {
-        const logger = createLogger(this.config.logging);
+        const logger = this.factories.createLogger(this.config.logging);
         this.logger = logger;
         let embeddingProvider;
         try {
-            embeddingProvider = createEmbeddingProvider(this.config.embedding, logger);
+            embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
         }
         catch (error) {
-            logger.fatal({ error }, 'Failed to create embedding provider');
+            logger.fatal({ err: normalizeError(error) }, 'Failed to create embedding provider');
             throw error;
         }
-        const vectorStore = new VectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
+        const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
         await vectorStore.ensureCollection();
-        const compiledRules = compileRules(this.config.inferenceRules ?? []);
+        const compiledRules = this.factories.compileRules(this.config.inferenceRules ?? []);
         const processorConfig = {
             metadataDir: this.config.metadataDir ?? '.jeeves-metadata',
             chunkSize: this.config.embedding.chunkSize,
             chunkOverlap: this.config.embedding.chunkOverlap,
             maps: this.config.maps,
         };
-        const processor = new DocumentProcessor(processorConfig, embeddingProvider, vectorStore, compiledRules, logger);
+        const processor = this.factories.createDocumentProcessor(processorConfig, embeddingProvider, vectorStore, compiledRules, logger);
         this.processor = processor;
-        const queue = new EventQueue({
+        const 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 watcher = new FileSystemWatcher(this.config.watch, queue, processor, logger);
+        const watcher = this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger);
         this.watcher = watcher;
-        const server = createApiServer({
+        const server = this.factories.createApiServer({
             processor,
             vectorStore,
             embeddingProvider,
@@ -1945,28 +2187,18 @@ class JeevesWatcher {
             return;
         }
         const debounceMs = this.config.configWatch?.debounceMs ?? 10000;
-        this.configWatcher = chokidar.watch(this.configPath, {
-            ignoreInitial: true,
-        });
-        this.configWatcher.on('change', () => {
-            if (this.configDebounce)
-                clearTimeout(this.configDebounce);
-            this.configDebounce = setTimeout(() => {
-                void this.reloadConfig();
-            }, debounceMs);
-        });
-        this.configWatcher.on('error', (error) => {
-            logger.error({ error }, 'Config watcher error');
+        this.configWatcher = new ConfigWatcher({
+            configPath: this.configPath,
+            enabled,
+            debounceMs,
+            logger,
+            onChange: async () => this.reloadConfig(),
         });
-        logger.info({ configPath: this.configPath, debounceMs }, 'Config watcher started');
+        this.configWatcher.start();
     }
     async stopConfigWatch() {
-        if (this.configDebounce) {
-            clearTimeout(this.configDebounce);
-            this.configDebounce = undefined;
-        }
         if (this.configWatcher) {
-            await this.configWatcher.close();
+            await this.configWatcher.stop();
             this.configWatcher = undefined;
         }
     }
@@ -1977,14 +2209,14 @@ class JeevesWatcher {
             return;
         logger.info({ configPath: this.configPath }, 'Config change detected, reloading...');
         try {
-            const newConfig = await loadConfig(this.configPath);
+            const newConfig = await this.factories.loadConfig(this.configPath);
             this.config = newConfig;
-            const compiledRules = compileRules(newConfig.inferenceRules ?? []);
+            const compiledRules = this.factories.compileRules(newConfig.inferenceRules ?? []);
             processor.updateRules(compiledRules);
             logger.info({ configPath: this.configPath, rules: compiledRules.length }, 'Config reloaded');
         }
         catch (error) {
-            logger.error({ error }, 'Failed to reload config');
+            logger.error({ err: normalizeError(error) }, 'Failed to reload config');
         }
     }
 }
@@ -1997,12 +2229,7 @@ class JeevesWatcher {
 async function startFromConfig(configPath) {
     const config = await loadConfig(configPath);
     const app = new JeevesWatcher(config, configPath);
-    const shutdown = async () => {
-        await app.stop();
-        process.exit(0);
-    };
-    process.on('SIGTERM', () => void shutdown());
-    process.on('SIGINT', () => void shutdown());
+    installShutdownHandlers(() => app.stop());
     await app.start();
     return app;
 }