@karmaniverous/jeeves-watcher 0.6.9 → 0.7.1

package/dist/index.js

@@ -1,6 +1,6 @@
+import { resolve, extname, basename, dirname, isAbsolute, join, relative } from 'node:path';
 import Fastify from 'fastify';
 import { readFileSync, statSync, existsSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
-import { resolve, extname, basename, dirname, join, relative } from 'node:path';
 import { JsonMap, jsonMapMapSchema } from '@karmaniverous/jsonmap';
 import { pathToFileURL } from 'node:url';
 import Handlebars from 'handlebars';
@@ -11,6 +11,7 @@ import { toMarkdown } from 'mdast-util-to-markdown';
 import { capitalize, title, camel, snake, dash, isEqual, get, omit } from 'radash';
 import rehypeParse from 'rehype-parse';
 import { unified } from 'unified';
+import yaml from 'js-yaml';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import picomatch from 'picomatch';
@@ -18,13 +19,13 @@ import { readdir, stat, writeFile, rm, readFile, mkdir } from 'node:fs/promises'
 import { z, ZodError } from 'zod';
 import { JSONPath } from 'jsonpath-plus';
 import { createHash } from 'node:crypto';
+import crypto from 'crypto';
 import chokidar from 'chokidar';
 import { cosmiconfig } from 'cosmiconfig';
 import { GoogleGenerativeAIEmbeddings } from '@langchain/google-genai';
 import pino from 'pino';
 import { v5 } from 'uuid';
 import * as cheerio from 'cheerio';
-import yaml from 'js-yaml';
 import mammoth from 'mammoth';
 import { MarkdownTextSplitter, RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
 import { QdrantClient } from '@qdrant/js-client-rest';
@@ -334,6 +335,146 @@ async function buildTemplateEngine(rules, namedTemplates, templateHelpers, confi
     return engine;
 }
 
+/**
+ * @module templates/rebaseHeadings
+ * Rebase Markdown heading levels so the minimum heading depth starts at baseHeading+1.
+ */
+/**
+ * Rebase Markdown headings.
+ *
+ * Finds all ATX headings (lines starting with one or more '#'),
+ * computes the minimum heading level present, and shifts all headings
+ * so that the minimum becomes baseHeading+1.
+ */
+function rebaseHeadings(markdown, baseHeading) {
+    if (!markdown.trim())
+        return markdown;
+    const lines = markdown.split(/\r?\n/);
+    const headingLevels = [];
+    for (const line of lines) {
+        const m = line.match(/^(#{1,6})\s+/);
+        if (m)
+            headingLevels.push(m[1].length);
+    }
+    if (headingLevels.length === 0)
+        return markdown;
+    const minLevel = Math.min(...headingLevels);
+    const targetMin = Math.min(6, Math.max(1, baseHeading + 1));
+    const delta = targetMin - minLevel;
+    if (delta === 0)
+        return markdown;
+    const rebased = lines.map((line) => {
+        const m = line.match(/^(#{1,6})(\s+.*)$/);
+        if (!m)
+            return line;
+        const level = m[1].length;
+        const newLevel = Math.min(6, Math.max(1, level + delta));
+        return `${'#'.repeat(newLevel)}${m[2]}`;
+    });
+    return rebased.join('\n');
+}
+
+/**
+ * @module templates/renderDoc
+ * Declarative renderer for YAML frontmatter + structured Markdown body.
+ */
+function renderSectionHeading(section, hbs, context = {}) {
+    const level = Math.min(6, Math.max(1, section.heading));
+    const label = section.label
+        ? hbs.compile(section.label)(context)
+        : title(section.path);
+    return `${'#'.repeat(level)} ${label}`;
+}
+function callFormatHelper(hbs, helperName, value, args) {
+    const helper = hbs.helpers[helperName];
+    if (typeof helper !== 'function') {
+        throw new Error(`Format helper not found: ${helperName}`);
+    }
+    // Handlebars helpers may return SafeString or other values; coerce to string
+    const safeArgs = args ?? [];
+    const result = helper(value, ...safeArgs);
+    return typeof result === 'string' ? result : String(result);
+}
+function renderValueAsMarkdown(hbs, section, value) {
+    if (value === null || value === undefined)
+        return '';
+    if (section.format) {
+        const md = callFormatHelper(hbs, section.format, value, section.formatArgs);
+        return rebaseHeadings(md, section.heading);
+    }
+    const strValue = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+    return hbs.Utils.escapeExpression(strValue);
+}
+function renderEach(hbs, section, value) {
+    if (!Array.isArray(value))
+        return '';
+    const items = [...value];
+    if (section.sort) {
+        items.sort((a, b) => {
+            const av = get(a, section.sort);
+            const bv = get(b, section.sort);
+            const aStr = typeof av === 'string' ? av : JSON.stringify(av ?? '');
+            const bStr = typeof bv === 'string' ? bv : JSON.stringify(bv ?? '');
+            return aStr.localeCompare(bStr);
+        });
+    }
+    const subHeadingLevel = Math.min(6, section.heading + 1);
+    const headingTpl = section.headingTemplate
+        ? hbs.compile(section.headingTemplate)
+        : undefined;
+    const parts = [];
+    for (const item of items) {
+        const headingText = headingTpl
+            ? headingTpl(item)
+            : '';
+        if (headingText) {
+            parts.push(`${'#'.repeat(subHeadingLevel)} ${headingText}`);
+        }
+        const contentVal = section.contentPath
+            ? get(item, section.contentPath)
+            : item;
+        const md = renderValueAsMarkdown(hbs, { ...section, heading: subHeadingLevel }, contentVal);
+        if (md.trim())
+            parts.push(md.trim());
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Render a document according to a RenderConfig.
+ */
+function renderDoc(context, config, hbs) {
+    const parts = [];
+    // Frontmatter
+    const fmObj = {};
+    for (const key of config.frontmatter) {
+        const v = get(context, key);
+        if (v !== undefined) {
+            fmObj[key] = v;
+        }
+    }
+    if (Object.keys(fmObj).length > 0) {
+        parts.push('---');
+        parts.push(yaml.dump(fmObj, { skipInvalid: true }).trim());
+        parts.push('---');
+        parts.push('');
+    }
+    // Body
+    for (const section of config.body) {
+        const heading = renderSectionHeading(section, hbs, context);
+        parts.push(heading);
+        parts.push('');
+        const v = get(context, section.path);
+        const body = section.each
+            ? renderEach(hbs, section, v)
+            : renderValueAsMarkdown(hbs, section, v);
+        if (body.trim()) {
+            parts.push(body.trim());
+        }
+        parts.push('');
+    }
+    return parts.join('\n').trim() + '\n';
+}
+
 /**
  * @module util/normalizeError
  *
@@ -820,15 +961,30 @@ async function applyRules(compiledRules, attributes, options = {}) {
                     log.warn(`JsonMap transformation failed: ${normalizeError(error).message}`);
                 }
             }
+            // Build template context: attributes (with json spread at top) + map output
+            const context = {
+                ...(attributes.json ?? {}),
+                ...attributes,
+                ...merged,
+            };
+            // Render via renderDoc if present
+            if (rule.render) {
+                try {
+                    const result = renderDoc(context, rule.render, hbs);
+                    if (result && result.trim()) {
+                        renderedContent = result;
+                    }
+                    else {
+                        log.warn(`renderDoc for rule "${rule.name}" rendered empty output. Falling back to raw content.`);
+                    }
+                }
+                catch (error) {
+                    log.warn(`renderDoc failed for rule "${rule.name}": ${normalizeError(error).message}. Falling back to raw content.`);
+                }
+            }
             // Render template if present
             if (rule.template && templateEngine) {
                 const templateKey = rule.name;
-                // 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()) {
@@ -894,6 +1050,26 @@ function buildAttributes(filePath, stats, extractedFrontmatter, extractedJson) {
         attrs.json = extractedJson;
     return attrs;
 }
+/**
+ * Build synthetic file attributes from a path string (no actual file I/O).
+ * Used by API handlers that need to match rules against paths without reading files.
+ *
+ * @param filePath - The file path.
+ * @returns Synthetic file attributes with zeroed stats.
+ */
+function buildSyntheticAttributes(filePath) {
+    const normalised = normalizeSlashes(filePath);
+    return {
+        file: {
+            path: normalised,
+            directory: normalizeSlashes(dirname(normalised)),
+            filename: basename(normalised),
+            extension: extname(normalised),
+            sizeBytes: 0,
+            modified: new Date(0).toISOString(),
+        },
+    };
+}
 
 /**
  * @module rules/ajvSetup
@@ -961,8 +1137,14 @@ function compileRules(rules) {
 }
 
 /**
- * @module util/retry
- * Small async retry helper with exponential backoff. Side effects: sleeps between attempts; can invoke onRetry callback for logging.
+ * @module util/sleep
+ * Abort-aware async sleep.
+ */
+/**
+ * Sleep for a given duration with optional abort support.
+ *
+ * @param ms - Duration in milliseconds.
+ * @param signal - Optional abort signal.
  */
 function sleep(ms, signal) {
     if (ms <= 0)
@@ -974,7 +1156,7 @@ function sleep(ms, signal) {
         }, ms);
         const onAbort = () => {
             cleanup();
-            reject(new Error('Retry sleep aborted'));
+            reject(new Error('Sleep aborted'));
         };
         const cleanup = () => {
             clearTimeout(timer);
@@ -990,6 +1172,11 @@ function sleep(ms, signal) {
         }
     });
 }
+
+/**
+ * @module util/retry
+ * Small async retry helper with exponential backoff. Side effects: sleeps between attempts; can invoke onRetry callback for logging.
+ */
 function computeDelayMs(attempt, baseDelayMs, maxDelayMs, jitter = 0) {
     const exp = Math.max(0, attempt - 1);
     const raw = Math.min(maxDelayMs, baseDelayMs * 2 ** exp);
@@ -1283,7 +1470,12 @@ const apiConfigSchema = z.object({
         .optional()
         .describe('Host address for API server (e.g., "127.0.0.1", "0.0.0.0").'),
     /** Port to listen on. */
-    port: z.number().optional().describe('Port for API server (e.g., 3456).'),
+    port: z.number().optional().describe('Port for API server (e.g., 1936).'),
+    /** Read endpoint cache TTL in milliseconds. */
+    cacheTtlMs: z
+        .number()
+        .optional()
+        .describe('TTL in milliseconds for caching read-heavy endpoints (e.g., /status, /config/query). Default: 30000.'),
 });
 /**
  * Logging configuration.
@@ -1337,10 +1529,61 @@ const schemaReferenceSchema = z.union([
     z.string().describe('Named reference to a global schema.'),
     schemaObjectSchema,
 ]);
+/** Render body section. */
+const renderBodySectionSchema = z.object({
+    /** Key path in the template context to render. */
+    path: z.string().min(1).describe('Key path in template context to render.'),
+    /** Markdown heading level for this section (1-6). */
+    heading: z.number().min(1).max(6).describe('Markdown heading level (1-6).'),
+    /** Override heading text (default: titlecased path). */
+    label: z.string().optional().describe('Override heading text.'),
+    /** Name of a registered Handlebars helper used as a format handler. */
+    format: z
+        .string()
+        .optional()
+        .describe('Name of a registered Handlebars helper used as a format handler.'),
+    /** Additional args passed to the format helper. */
+    formatArgs: z
+        .array(z.unknown())
+        .optional()
+        .describe('Additional args passed to the format helper.'),
+    /** If true, the value at path is treated as an array and iterated. */
+    each: z
+        .boolean()
+        .optional()
+        .describe('If true, the value at path is treated as an array and iterated.'),
+    /** Handlebars template string for per-item heading text (used when each=true). */
+    headingTemplate: z
+        .string()
+        .optional()
+        .describe('Handlebars template string for per-item heading text (used when each=true).'),
+    /** Key path within each item to use as renderable content (used when each=true). */
+    contentPath: z
+        .string()
+        .optional()
+        .describe('Key path within each item to use as renderable content (used when each=true).'),
+    /** Key path within each item to sort by (used when each=true). */
+    sort: z
+        .string()
+        .optional()
+        .describe('Key path within each item to sort by (used when each=true).'),
+});
+/** Render config: YAML frontmatter + ordered body sections. */
+const renderConfigSchema = z.object({
+    /** Keys to extract from context and include as YAML frontmatter. */
+    frontmatter: z
+        .array(z.string().min(1))
+        .describe('Keys to extract from context and include as YAML frontmatter.'),
+    /** Ordered markdown body sections. */
+    body: z
+        .array(renderBodySectionSchema)
+        .describe('Ordered markdown body sections.'),
+});
 /**
  * An inference rule that enriches document metadata.
  */
-const inferenceRuleSchema = z.object({
+const inferenceRuleSchema = z
+    .object({
     /** Unique name for this inference rule. */
     name: z
         .string()
@@ -1370,6 +1613,19 @@ const inferenceRuleSchema = z.object({
         .string()
         .optional()
         .describe('Handlebars content template (inline string, named ref, or .hbs/.handlebars file path).'),
+    /** Declarative structured renderer configuration (mutually exclusive with template). */
+    render: renderConfigSchema
+        .optional()
+        .describe('Declarative render configuration for frontmatter + structured Markdown output (mutually exclusive with template).'),
+})
+    .superRefine((val, ctx) => {
+    if (val.render && val.template) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['render'],
+            message: 'render is mutually exclusive with template',
+        });
+    }
 });
 
 /**
@@ -1753,17 +2009,7 @@ function createConfigMatchHandler(options) {
             return;
         }
         const matches = body.paths.map((path) => {
-            const normalised = normalizeSlashes(path);
-            const attrs = {
-                file: {
-                    path: normalised,
-                    directory: normalizeSlashes(dirname(normalised)),
-                    filename: basename(normalised),
-                    extension: extname(normalised),
-                    sizeBytes: 0,
-                    modified: new Date(0).toISOString(),
-                },
-            };
+            const attrs = buildSyntheticAttributes(path);
             // Find matching rules
             const matchingRules = [];
             for (const compiled of compiledRules) {
@@ -1772,6 +2018,7 @@ function createConfigMatchHandler(options) {
                 }
             }
             // Check watch scope: matches watch paths and not in ignored
+            const normalised = attrs.file.path;
             const watched = watchMatcher(normalised) && !ignoreMatcher?.(normalised);
             return { rules: matchingRules, watched };
         });
@@ -1834,6 +2081,8 @@ function buildMergedDocument(options) {
     }));
     return {
         description: config['description'] ?? '',
+        watch: config.watch,
+        configWatch: config.configWatch ?? {},
         search: config.search ?? {},
         schemas: config.schemas ?? {},
         inferenceRules,
@@ -1923,6 +2172,9 @@ function resolveReferences(doc, resolveTypes) {
 /**
  * Create handler for POST /config/query.
  *
+ * Uses direct error handling (returns 400) rather than wrapHandler (which returns 500),
+ * because invalid JSONPath expressions are client errors, not server errors.
+ *
  * @param deps - Route dependencies.
  */
 function createConfigQueryHandler(deps) {
@@ -2038,7 +2290,7 @@ function createConfigSchemaHandler() {
 /**
  * Validate helper file references (mapHelpers, templateHelpers).
  */
-function validateHelperFiles(config) {
+function validateHelperFiles(config, configDir) {
     const errors = [];
     for (const section of ['mapHelpers', 'templateHelpers']) {
         const helpers = config[section];
@@ -2047,15 +2299,18 @@ function validateHelperFiles(config) {
         for (const [name, helper] of Object.entries(helpers)) {
             if (!helper.path)
                 continue;
-            if (!existsSync(helper.path)) {
+            const resolvedPath = isAbsolute(helper.path)
+                ? helper.path
+                : resolve(configDir, helper.path);
+            if (!existsSync(resolvedPath)) {
                 errors.push({
                     path: `${section}.${name}.path`,
-                    message: `File not found: ${helper.path}`,
+                    message: `File not found: ${resolvedPath}`,
                 });
                 continue;
             }
             try {
-                readFileSync(helper.path, 'utf-8');
+                readFileSync(resolvedPath, 'utf-8');
             }
             catch (err) {
                 errors.push({
@@ -2108,7 +2363,7 @@ function createConfigValidateHandler(deps) {
         if (errors.length > 0) {
             return { valid: false, errors };
         }
-        const helperErrors = validateHelperFiles(candidateRaw);
+        const helperErrors = validateHelperFiles(candidateRaw, deps.configDir);
         if (helperErrors.length > 0) {
             return { valid: false, errors: helperErrors };
         }
@@ -2212,17 +2467,7 @@ function getValueType(value) {
  */
 function validateMetadataPayload(config, path, metadata) {
     const compiled = compileRules(config.inferenceRules ?? []);
-    const normalised = normalizeSlashes(path);
-    const attrs = {
-        file: {
-            path: normalised,
-            directory: normalizeSlashes(dirname(normalised)),
-            filename: basename(normalised),
-            extension: extname(normalised),
-            sizeBytes: 0,
-            modified: new Date(0).toISOString(),
-        },
-    };
+    const attrs = buildSyntheticAttributes(path);
     const matched = compiled.filter((r) => r.validate(attrs));
     const matchedNames = matched.map((m) => m.rule.name);
     const schemaRefs = matched.flatMap((m) => m.rule.schema ?? []);
@@ -2496,7 +2741,6 @@ function createReindexHandler(deps) {
  */
 function createRulesReapplyHandler(deps) {
     return wrapHandler(async (request) => {
-        await Promise.resolve();
         const { globs } = request.body;
         if (!Array.isArray(globs) || globs.length === 0) {
             throw new Error('Missing required field: globs (non-empty string array)');
@@ -2539,7 +2783,6 @@ function createRulesReapplyHandler(deps) {
  */
 function createRulesRegisterHandler(deps) {
     return wrapHandler(async (request) => {
-        await Promise.resolve();
         const { source, rules } = request.body;
         if (!source || typeof source !== 'string') {
             throw new Error('Missing required field: source');
@@ -2550,11 +2793,11 @@ function createRulesRegisterHandler(deps) {
         deps.virtualRuleStore.register(source, rules);
         deps.onRulesChanged();
         deps.logger.info({ source, ruleCount: rules.length }, 'Virtual rules registered');
-        return {
+        return await Promise.resolve({
             source,
             registered: rules.length,
             totalVirtualRules: deps.virtualRuleStore.size,
-        };
+        });
     }, deps.logger, 'RulesRegister');
 }
 
@@ -2562,21 +2805,25 @@ function createRulesRegisterHandler(deps) {
  * @module api/handlers/rulesUnregister
  * Fastify route handler for DELETE /rules/unregister.
  */
+/**
+ * Core unregister logic shared by body and param handlers.
+ */
+function unregisterSource(deps, source) {
+    if (!source || typeof source !== 'string') {
+        throw new Error('Missing required field: source');
+    }
+    const removed = deps.virtualRuleStore.unregister(source);
+    if (removed)
+        deps.onRulesChanged();
+    deps.logger.info({ source, removed }, 'Virtual rules unregister');
+    return { source, removed };
+}
 /**
  * Create handler for DELETE /rules/unregister (body-based).
  */
 function createRulesUnregisterHandler(deps) {
     return wrapHandler(async (request) => {
-        await Promise.resolve();
-        const { source } = request.body;
-        if (!source || typeof source !== 'string') {
-            throw new Error('Missing required field: source');
-        }
-        const removed = deps.virtualRuleStore.unregister(source);
-        if (removed)
-            deps.onRulesChanged();
-        deps.logger.info({ source, removed }, 'Virtual rules unregister');
-        return { source, removed };
+        return Promise.resolve(unregisterSource(deps, request.body.source));
     }, deps.logger, 'RulesUnregister');
 }
 /**
@@ -2584,16 +2831,7 @@ function createRulesUnregisterHandler(deps) {
  */
 function createRulesUnregisterParamHandler(deps) {
     return wrapHandler(async (request) => {
-        await Promise.resolve();
-        const { source } = request.params;
-        if (!source || typeof source !== 'string') {
-            throw new Error('Missing required param: source');
-        }
-        const removed = deps.virtualRuleStore.unregister(source);
-        if (removed)
-            deps.onRulesChanged();
-        deps.logger.info({ source, removed }, 'Virtual rules unregister');
-        return { source, removed };
+        return Promise.resolve(unregisterSource(deps, request.params.source));
     }, deps.logger, 'RulesUnregister');
 }
 
@@ -2642,6 +2880,57 @@ function createStatusHandler(deps) {
     };
 }
 
+/**
+ * In-memory response cache
+ */
+const cache = new Map();
+/**
+ * Generates a deterministic hash for an object
+ */
+function hashObject(obj) {
+    if (obj === undefined)
+        return 'undefined';
+    if (obj === null)
+        return 'null';
+    const str = typeof obj === 'string' ? obj : JSON.stringify(obj);
+    return crypto.createHash('sha256').update(str).digest('hex');
+}
+/**
+ * Higher-order function to wrap Fastify route handlers with an in-memory TTL cache.
+ * Uses request method, URL, and body hash as the cache key.
+ *
+ * @param ttlMs - Time to live in milliseconds
+ * @param handler - The original route handler
+ * @returns A new route handler that implements caching
+ */
+function withCache(ttlMs, handler) {
+    return async (req, reply) => {
+        const fReq = req;
+        const fReply = reply;
+        // Generate deterministic cache key: METHOD:URL:BODY_HASH
+        const bodyHash = hashObject(fReq.body);
+        const key = fReq.method + ':' + fReq.url + ':' + bodyHash;
+        // Check cache
+        const now = Date.now();
+        const entry = cache.get(key);
+        if (entry && entry.expiresAt > now) {
+            return entry.value;
+        }
+        // Cache miss - call handler
+        const result = await handler(req, reply);
+        // Don't cache errors (Fastify reply properties might indicate error)
+        if (fReply.statusCode >= 400) {
+            return result;
+        }
+        // Store in cache
+        cache.set(key, {
+            value: result,
+            expiresAt: now + ttlMs,
+        });
+        return result;
+    };
+}
+
 /**
  * @module api/ReindexTracker
  * Tracks reindex operation state for status reporting. Single instance shared across handlers.
@@ -2703,11 +2992,12 @@ function createApiServer(options) {
             issuesManager,
         }, scope);
     };
-    app.get('/status', createStatusHandler({
+    const cacheTtlMs = config.api?.cacheTtlMs ?? 30000;
+    app.get('/status', withCache(cacheTtlMs, createStatusHandler({
         vectorStore,
         collectionName: config.vectorStore.collectionName,
         reindexTracker,
-    }));
+    })));
     app.post('/metadata', createMetadataHandler({ processor, config, logger }));
     const hybridConfig = config.search?.hybrid
         ? {
@@ -2728,10 +3018,10 @@ function createApiServer(options) {
         logger,
     }));
     app.post('/config-reindex', createConfigReindexHandler({ config, processor, logger, reindexTracker }));
-    app.get('/issues', createIssuesHandler({ issuesManager }));
-    app.get('/config/schema', createConfigSchemaHandler());
+    app.get('/issues', withCache(cacheTtlMs, createIssuesHandler({ issuesManager })));
+    app.get('/config/schema', withCache(cacheTtlMs, createConfigSchemaHandler()));
     app.post('/config/match', createConfigMatchHandler({ config, logger }));
-    app.post('/config/query', createConfigQueryHandler({
+    app.post('/config/query', withCache(cacheTtlMs, createConfigQueryHandler({
         config,
         valuesManager,
         issuesManager,
@@ -2740,8 +3030,12 @@ function createApiServer(options) {
         getVirtualRules: virtualRuleStore
             ? () => virtualRuleStore.getAll()
             : undefined,
+    })));
+    app.post('/config/validate', createConfigValidateHandler({
+        config,
+        logger,
+        configDir: dirname(configPath),
     }));
-    app.post('/config/validate', createConfigValidateHandler({ config, logger }));
     app.post('/config/apply', createConfigApplyHandler({
         config,
         configPath,
@@ -3101,6 +3395,7 @@ const CONFIG_WATCH_DEFAULTS = {
 const API_DEFAULTS = {
     host: '127.0.0.1',
     port: 1936,
+    cacheTtlMs: 30000,
 };
 /** Default logging values. */
 const LOGGING_DEFAULTS = {
@@ -3579,13 +3874,10 @@ const extractorRegistry = new Map([
  * @returns Extracted text and optional structured data.
  */
 async function extractText(filePath, extension, additionalExtractors) {
-    // Merge additional extractors with built-in registry
-    const registry = new Map(extractorRegistry);
-    if (additionalExtractors) {
-        for (const [ext, extractor] of additionalExtractors) {
-            registry.set(ext, extractor);
-        }
-    }
+    // Use base registry directly unless additional extractors provided
+    const registry = additionalExtractors
+        ? new Map([...extractorRegistry, ...additionalExtractors])
+        : extractorRegistry;
     const extractor = registry.get(extension.toLowerCase());
     if (extractor)
         return extractor(filePath);
@@ -4671,28 +4963,7 @@ class SystemHealth {
         if (delay <= 0)
             return;
         this.logger.warn({ delayMs: delay, consecutiveFailures: this.consecutiveFailures }, 'Backing off before next attempt');
-        await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                cleanup();
-                resolve();
-            }, delay);
-            const onAbort = () => {
-                cleanup();
-                reject(new Error('Backoff aborted'));
-            };
-            const cleanup = () => {
-                clearTimeout(timer);
-                if (signal)
-                    signal.removeEventListener('abort', onAbort);
-            };
-            if (signal) {
-                if (signal.aborted) {
-                    onAbort();
-                    return;
-                }
-                signal.addEventListener('abort', onAbort, { once: true });
-            }
-        });
+        await sleep(delay, signal);
     }
     /** Current consecutive failure count. */
     get failures() {
@@ -5520,7 +5791,7 @@ class JeevesWatcher {
         });
         await server.listen({
             host: this.config.api?.host ?? '127.0.0.1',
-            port: this.config.api?.port ?? 3456,
+            port: this.config.api?.port ?? 1936,
         });
         return server;
     }