@karmaniverous/jeeves-watcher 0.19.1 → 0.20.0

package/dist/cli/jeeves-watcher/index.js

@@ -1,32 +1,17 @@
 #!/usr/bin/env node
-import { substituteEnvVars, DEFAULT_PORTS, postJson, fetchJson, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
-import { dirname, resolve, join, relative } from 'node:path';
+import { substituteEnvVars, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
+import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, extractWatchPathStrings, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
+import { isPlainObject as isPlainObject$1, findReservedPropertyNames, sourceConfigSchema, jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, bearerHeaders, API_KEY_ENV_VAR, httpError, formatHttpError, unauthorizedMessage, getEndpoint, reindexScopeSchema, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
 import { packageDirectorySync } from 'package-directory';
-import { readFileSync, existsSync, mkdirSync, renameSync, statSync, readdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { cosmiconfig } from 'cosmiconfig';
-import { ZodError } from 'zod';
-import { readdir, stat, access } from 'node:fs/promises';
-import { parallel } from 'radash';
-import ignore from 'ignore';
-import picomatch from 'picomatch';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { ZodError, z } from 'zod';
 
 /**
  * @module api/handlers/configMerge
  * Shared config merge utilities.
  */
-/**
- * Check whether a value is a plain object (not null, not an array).
- *
- * @param value - Value to check.
- * @returns True for plain objects.
- */
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /**
  * Deep-merge a config patch into a base config.
  *
@@ -48,7 +33,7 @@ function deepMergeConfig(base, patch) {
                 ? current
                 : undefined, value);
         }
-        else if (isPlainObject(current) && isPlainObject(value)) {
+        else if (isPlainObject$1(current) && isPlainObject$1(value)) {
             result[key] = deepMergeConfig(current, value);
         }
         else {
@@ -83,6 +68,401 @@ function mergeInferenceRules(existing, incoming) {
     return merged;
 }
 
+/**
+ * @module rules/coerceType
+ * Coerces values to target JSON Schema types.
+ */
+/**
+ * Coerce a value to a target type based on JSON Schema type.
+ *
+ * @param value - The value to coerce (typically a string from template interpolation).
+ * @param type - The target JSON Schema type.
+ * @returns The coerced value, or undefined if coercion fails.
+ */
+function coerceType(value, type) {
+    // Null and undefined always coerce to undefined
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    // Empty strings are only valid for the 'string' type
+    if (value === '' && type !== 'string') {
+        return undefined;
+    }
+    switch (type) {
+        case 'string': {
+            if (typeof value === 'string')
+                return value;
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                return String(value);
+            }
+            if (typeof value === 'object') {
+                // Stringify objects and arrays
+                return JSON.stringify(value);
+            }
+            // Unsupported types (symbol, function, etc.) - undefined
+            return undefined;
+        }
+        case 'integer': {
+            if (typeof value === 'string') {
+                // For strings, check that parsing yields an integer that matches the trimmed input
+                const trimmed = value.trim();
+                const num = parseInt(trimmed, 10);
+                if (Number.isInteger(num) && num.toString() === trimmed) {
+                    return num;
+                }
+                return undefined;
+            }
+            if (typeof value === 'number') {
+                return Number.isInteger(value) ? value : undefined;
+            }
+            return undefined;
+        }
+        case 'number': {
+            const num = typeof value === 'string' ? parseFloat(value) : Number(value);
+            return Number.isFinite(num) ? num : undefined;
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'string') {
+                const lower = value.toLowerCase();
+                if (lower === 'true')
+                    return true;
+                if (lower === 'false')
+                    return false;
+            }
+            return undefined;
+        }
+        case 'array': {
+            if (Array.isArray(value))
+                return value;
+            if (typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed))
+                        return parsed;
+                }
+                catch {
+                    // Invalid JSON
+                }
+            }
+            return undefined;
+        }
+        case 'object': {
+            if (typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (typeof parsed === 'object' &&
+                        parsed !== null &&
+                        !Array.isArray(parsed)) {
+                        return parsed;
+                    }
+                }
+                catch {
+                    // Invalid JSON
+                }
+                return undefined;
+            }
+            // Check for plain objects (not array) - null already filtered at top
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                return value;
+            }
+            return undefined;
+        }
+        default:
+            return value;
+    }
+}
+
+/**
+ * @module rules/templates
+ * Resolves Handlebars template expressions in rule `set` objects against file attributes.
+ */
+/**
+ * Resolve a Handlebars template expression against file attributes.
+ *
+ * @param value - The value to resolve (strings are compiled as Handlebars templates).
+ * @param attributes - The file or source attributes for variable lookup.
+ * @param hbs - Handlebars instance with registered helpers.
+ * @returns The resolved value.
+ */
+function resolveTemplateVars(value, attributes, hbs) {
+    if (typeof value !== 'string')
+        return value;
+    return hbs.compile(value, { noEscape: true })(attributes);
+}
+
+/**
+ * @module rules/schemaMerge
+ * Merges schema references into a resolved property schema with set extraction and type coercion.
+ */
+/**
+ * Resolve a schema entry (inline object or file path) to a schema object.
+ *
+ * @param entry - Schema entry (inline object or file path).
+ * @param configDir - Config directory for resolving file paths.
+ * @returns The resolved schema object.
+ */
+function resolveSchemaEntry(entry, configDir) {
+    if (typeof entry === 'string') {
+        // File path - load and parse JSON
+        const resolvedPath = configDir ? resolve(configDir, entry) : entry;
+        const raw = readFileSync(resolvedPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    return entry;
+}
+/**
+ * Merge an array of schema references into a single resolved schema.
+ * Later entries override earlier ones at the property level.
+ *
+ * @param refs - Array of schema references (named strings or inline objects).
+ * @param options - Options for schema merging.
+ * @returns The merged resolved schema.
+ */
+function mergeSchemas(refs, options = {}) {
+    const { globalSchemas = {}, configDir } = options;
+    const merged = { properties: {} };
+    for (const ref of refs) {
+        let schema;
+        if (typeof ref === 'string') {
+            // Named reference - resolve from global schemas
+            const globalEntry = globalSchemas[ref];
+            if (!globalEntry) {
+                throw new Error(`Schema reference "${ref}" not found in global schemas`);
+            }
+            schema = resolveSchemaEntry(globalEntry, configDir);
+        }
+        else {
+            // Inline object
+            schema = ref;
+        }
+        // Merge properties at the property level
+        if (schema.properties) {
+            for (const [propName, propDef] of Object.entries(schema.properties)) {
+                const existing = merged.properties[propName];
+                if (existing) {
+                    const incoming = propDef;
+                    // For array-typed properties, concatenate set values instead of replacing
+                    if (existing.type === 'array' &&
+                        Array.isArray(existing.set) &&
+                        incoming.set !== undefined) {
+                        const existingSet = existing.set;
+                        const incomingSet = Array.isArray(incoming.set)
+                            ? incoming.set
+                            : [incoming.set];
+                        merged.properties[propName] = {
+                            ...existing,
+                            ...propDef,
+                            set: existingSet.concat(incomingSet),
+                        };
+                    }
+                    else {
+                        merged.properties[propName] = {
+                            ...existing,
+                            ...propDef,
+                        };
+                    }
+                }
+                else {
+                    merged.properties[propName] = propDef;
+                }
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Resolve set templates against file attributes and coerce to declared types.
+ *
+ * @param schema - Resolved schema with type information.
+ * @param attributes - File attributes for template variable resolution.
+ * @returns Resolved and type-coerced metadata.
+ */
+function resolveAndCoerce(schema, attributes, hbs) {
+    const result = {};
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        const setTemplate = propDef.set;
+        if (setTemplate === undefined)
+            continue;
+        // For array-typed properties with array set values, resolve each element
+        if (Array.isArray(setTemplate)) {
+            const resolved = setTemplate.map((item) => resolveTemplateVars(item, attributes, hbs));
+            result[propName] = resolved;
+            continue;
+        }
+        // Resolve template
+        const rawValue = resolveTemplateVars(setTemplate, attributes, hbs);
+        // Coerce to declared type - returns undefined on failure
+        const coerced = coerceType(rawValue, propDef.type);
+        // Only include if coercion succeeded
+        if (coerced !== undefined) {
+            result[propName] = coerced;
+        }
+    }
+    return result;
+}
+/**
+ * Validate that all properties in a schema have a declared type.
+ * Throws if any property lacks a type.
+ *
+ * @param schema - Resolved schema to validate.
+ * @param ruleName - Name of the rule (for error messages).
+ */
+function validateSchemaCompleteness(schema, ruleName) {
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        if (!propDef.type) {
+            throw new Error(`Property "${propName}" in rule "${ruleName}" has no declared type. Every property must have a type.`);
+        }
+    }
+}
+/** Types that can produce trackable facet values. */
+const FACETABLE_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'integer',
+    'array',
+]);
+/**
+ * Validate that uiHint and enum are only applied to facetable property types.
+ * Throws if a non-facetable type (e.g. object) declares uiHint or enum.
+ *
+ * @param schema - Resolved schema to validate.
+ * @param ruleName - Name of the rule (for error messages).
+ */
+function validateFacetTypes(schema, ruleName) {
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        if (!propDef.type)
+            continue;
+        if (!FACETABLE_TYPES.has(propDef.type) &&
+            (propDef.uiHint !== undefined || propDef.enum !== undefined)) {
+            throw new Error(`Property "${propName}" in rule "${ruleName}" has type "${propDef.type}" with uiHint/enum. Facet hints are only valid on string, number, boolean, integer, or array types.`);
+        }
+    }
+}
+
+/**
+ * @module rules/reservedFieldWarnings
+ * Detects inference-rule schema properties named like reserved system payload fields and reports them as non-fatal config warnings (emitted by loadConfig and `/config/validate`). Reads file-based schemas via mergeSchemas.
+ */
+/**
+ * Find rule schema properties that use a reserved system field name.
+ *
+ * Rules whose schemas cannot be resolved are skipped: schema resolution
+ * failures are reported as errors by validation, not as warnings here.
+ *
+ * @param config - Config (or candidate config) with rules and global schemas.
+ * @param configDir - Directory used to resolve file-based schema paths.
+ * @returns One warning per offending rule property.
+ */
+function findReservedFieldWarnings(config, configDir) {
+    const warnings = [];
+    for (const rule of config.inferenceRules ?? []) {
+        if (typeof rule === 'string' || !rule.schema?.length)
+            continue;
+        let properties;
+        try {
+            properties = mergeSchemas(rule.schema, {
+                globalSchemas: config.schemas,
+                configDir,
+            }).properties;
+        }
+        catch {
+            continue;
+        }
+        for (const name of findReservedPropertyNames(properties)) {
+            warnings.push({
+                path: `inferenceRules[${rule.name}].schema.${name}`,
+                message: `Property "${name}" is a reserved system payload field; the system value overwrites rule metadata on upsert. Rename the property.`,
+            });
+        }
+    }
+    return warnings;
+}
+
+/**
+ * @module config/assertResolvedSecrets
+ * Fail-fast check that secret-bearing config values (api.apiKey, sources.*.url and headers) contain no unresolved `${VAR}` after env substitution, and that api.apiKey is not empty. Pure; throws.
+ */
+const UNRESOLVED_PATTERN = /\$\{[^}]*\}/;
+/**
+ * Collect config paths whose secret-bearing value still contains an
+ * unresolved `${…}` reference. Values themselves are never returned.
+ *
+ * @param config - Config after environment-variable substitution.
+ * @returns Dotted paths of offending values.
+ */
+function findUnresolvedSecrets(config) {
+    const paths = [];
+    const check = (path, value) => {
+        if (value !== undefined && UNRESOLVED_PATTERN.test(value))
+            paths.push(path);
+    };
+    check('api.apiKey', config.api?.apiKey);
+    for (const [name, source] of Object.entries(config.sources ?? {})) {
+        check(`sources.${name}.url`, source.url);
+        for (const [header, value] of Object.entries(source.headers ?? {})) {
+            check(`sources.${name}.headers.${header}`, value);
+        }
+    }
+    return paths;
+}
+/**
+ * Throw when any secret-bearing value still contains an unresolved `${…}`,
+ * or when `api.apiKey` is empty after substitution (e.g. its variable is set
+ * to an empty string). Errors name config paths only, never values.
+ *
+ * @param config - Config after environment-variable substitution.
+ * @throws Error listing the offending config paths.
+ */
+function assertResolvedSecrets(config) {
+    const paths = findUnresolvedSecrets(config);
+    if (paths.length > 0) {
+        throw new Error(`Unresolved environment variable reference in: ${paths.join(', ')}. Set the referenced environment variables before starting jeeves-watcher.`);
+    }
+    if (config.api?.apiKey === '') {
+        throw new Error('api.apiKey is empty after environment variable substitution. Set a non-empty key, or remove api.apiKey to disable authentication.');
+    }
+}
+
+/**
+ * @module config/sourceKeyWarnings
+ * Finds unknown keys under `sources.<name>` in a raw (unparsed) config, e.g. a misspelt or unsupported `batchUrl`, which the schema would silently drop. Pure.
+ */
+/** Keys a source entry may carry. */
+const KNOWN_SOURCE_KEYS = new Set(Object.keys(sourceConfigSchema.shape));
+/**
+ * Find keys under `sources.<name>` that the source schema does not define.
+ * Validation strips them, so without this warning a setting such as
+ * `batchUrl` would be ignored without notice.
+ *
+ * @param rawConfig - The config as written (before schema parsing).
+ * @returns One warning per unknown key, in config order.
+ */
+function findUnknownSourceKeys(rawConfig) {
+    if (!isPlainObject$1(rawConfig) || !isPlainObject$1(rawConfig.sources))
+        return [];
+    const warnings = [];
+    for (const [name, source] of Object.entries(rawConfig.sources)) {
+        if (!isPlainObject$1(source))
+            continue;
+        for (const key of Object.keys(source)) {
+            if (KNOWN_SOURCE_KEYS.has(key))
+                continue;
+            warnings.push({
+                path: `sources.${name}.${key}`,
+                message: `Unknown source setting "${key}" is ignored (supported: ${[...KNOWN_SOURCE_KEYS].join(', ')}).`,
+            });
+        }
+    }
+    return warnings;
+}
+
+/**
+ * @module config/loadConfig
+ * Loads the watcher config via cosmiconfig: schema validation, rule/map file resolution, defaults, env substitution and secret checks; reports non-fatal warnings (unknown source keys, reserved rule field names) through onWarning. Reads files.
+ */
 const MODULE_NAME = 'jeeves-watcher';
 /**
  * Merge sensible defaults into a loaded configuration.
@@ -105,10 +485,11 @@ function applyDefaults(raw) {
  * Load the jeeves-watcher configuration.
  *
  * @param configPath - Optional explicit path to a config file.
+ * @param options - Optional warning sink.
  * @returns The loaded configuration.
  * @throws If no configuration is found or validation fails.
  */
-async function loadConfig(configPath) {
+async function loadConfig(configPath, options = {}) {
     const explorer = cosmiconfig(MODULE_NAME);
     const result = configPath
         ? await explorer.load(configPath)
@@ -145,7 +526,15 @@ async function loadConfig(configPath) {
             }
         }
         const withDefaults = applyDefaults(validated);
-        return substituteEnvVars(withDefaults);
+        const substituted = substituteEnvVars(withDefaults);
+        assertResolvedSecrets(substituted);
+        const warnings = [
+            ...findUnknownSourceKeys(result.config),
+            ...findReservedFieldWarnings(substituted, configDir),
+        ];
+        for (const warning of warnings)
+            options.onWarning?.(warning);
+        return substituted;
     }
     catch (error) {
         if (error instanceof ZodError) {
@@ -209,8 +598,98 @@ function migrateConfigPath(configDir) {
 
 /**
  * @module app/shutdown
- * Process signal shutdown orchestration. Installs SIGINT/SIGTERM handlers that invoke a provided async stop function.
+ * Shutdown orchestration: closes the API server first (no new notifies), stops producers, drains and stops queues with timeouts, and closes stores only when no abandoned run is still in flight. Installs SIGINT/SIGTERM handlers.
+ */
+/**
+ * Wait for a promise, giving up after `timeoutMs`.
+ *
+ * @param promise - The work to wait for (its rejection counts as settled).
+ * @param timeoutMs - Maximum wait in milliseconds.
+ * @returns `true` when settled in time, `false` on timeout.
+ */
+async function settlesWithin(promise, timeoutMs) {
+    let timer;
+    const settled = await Promise.race([
+        promise.then(() => true, () => true),
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                resolve(false);
+            }, timeoutMs);
+        }),
+    ]);
+    clearTimeout(timer);
+    return settled;
+}
+/**
+ * Wait for a step, warning when it times out.
+ *
+ * @returns `true` when the step settled in time.
+ */
+async function step(label, work, timeoutMs, logger) {
+    const done = await settlesWithin(work, timeoutMs);
+    if (!done) {
+        logger?.warn({ timeoutMs, step: label }, `${label} timeout hit, forcing shutdown`);
+    }
+    return done;
+}
+/**
+ * Drain a queue, then stop it (whatever the drain did); each step bounded.
+ *
+ * @returns `true` when the stop finished, i.e. no run is still in flight.
+ */
+async function drainThenStop(label, queue, timeoutMs, logger) {
+    await step(`${label} drain`, queue.drain(), timeoutMs, logger);
+    return step(`${label} stop`, queue.stop(), timeoutMs, logger);
+}
+/**
+ * Drain and stop the file queue, then the source notify queue. Stopping
+ * drops work the drain did not reach, refuses new work and waits for
+ * in-flight runs; each step is bounded by `timeoutMs`.
+ *
+ * @param queues - The queues (absent ones are skipped).
+ * @param timeoutMs - Per-step timeout in milliseconds.
+ * @param logger - Logger for timeout warnings.
+ * @returns `true` when every stop finished, i.e. no run is still in flight.
+ */
+async function drainQueues(queues, timeoutMs, logger) {
+    let idle = true;
+    if (queues.queue) {
+        idle = await drainThenStop('Queue', queues.queue, timeoutMs, logger);
+    }
+    if (queues.sourceQueue) {
+        const { sourceQueue } = queues;
+        const stopped = await drainThenStop('Source queue', sourceQueue, timeoutMs, logger);
+        idle = stopped && idle;
+    }
+    return idle;
+}
+/**
+ * Stop every component in a safe order: close the API server (bounded), stop
+ * producers, drain and stop the queues (bounded), flush the values index, and
+ * close stores. When a queue step timed out, runs may still be in flight, so
+ * stores are left open (the process exits) rather than closed under them.
+ *
+ * @param components - The components.
+ * @param timeoutMs - Per-step timeout in milliseconds.
+ * @param logger - Logger for warnings.
  */
+async function shutdownComponents(components, timeoutMs, logger) {
+    const { server, producers = [], valuesManager, stores = [] } = components;
+    if (server)
+        await step('API server close', server.close(), timeoutMs, logger);
+    for (const producer of producers)
+        await producer?.stop();
+    const idle = await drainQueues(components, timeoutMs, logger);
+    valuesManager?.stopAutoFlush();
+    valuesManager?.flush();
+    if (idle) {
+        for (const store of stores)
+            store?.close();
+    }
+    else {
+        logger?.warn('Runs still in flight after shutdown timeout; stores left open');
+    }
+}
 /**
  * Install process signal handlers.
  *
@@ -262,10 +741,16 @@ async function startFromConfig(configPath, descriptor) {
             resolvedPath = undefined;
         }
     }
-    const config = await loadConfig(resolvedPath);
+    // The logger is built from the config, so load-time warnings go to the
+    // console like the migration warnings above.
+    const config = await loadConfig(resolvedPath, {
+        onWarning: (warning) => {
+            console.warn(`[jeeves-watcher] ${warning.path}: ${warning.message}`);
+        },
+    });
     // Dynamic import breaks the circular dependency between this module
     // and app/index.ts (which defines JeevesWatcher and re-exports startFromConfig).
-    const { JeevesWatcher } = await import('./index-C_bf9c9m.js');
+    const { JeevesWatcher } = await import('./index-C9-xTM7k.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -273,1151 +758,345 @@ async function startFromConfig(configPath, descriptor) {
 }
 
 /**
- * @module gitignore
- * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
+ * @module cli/jeeves-watcher/apiClient
+ * Shared HTTP client for every CLI command that calls the watcher API: JSON GET/POST via `fetch` with the core bearer header and core error mapping (errors carry the server `code`; 401 adds key guidance). Never prints the key.
+ *
+ * @remarks
+ * Key resolution ({@link resolveApiKey}): the `--api-key` flag, then the
+ * `JEEVES_WATCHER_API_KEY` environment variable (core `API_KEY_ENV_VAR`). The
+ * API commands do not load the watcher config file, so `api.apiKey` from
+ * config is not consulted.
  */
+/** Where the CLI reads its API key from (named in 401 guidance). */
+const CLI_KEY_SOURCES = `--api-key or the ${API_KEY_ENV_VAR} env var`;
+/** Options for {@link createApiClient}; the Zod schema is the source of truth. */
+const apiClientOptionsSchema = z.object({
+    /** API base URL, e.g. `http://127.0.0.1:1936`. */
+    baseUrl: z.string().min(1),
+    /** Bearer key; omitted = no `Authorization` header. */
+    apiKey: z.string().min(1).optional(),
+});
+/** Treat missing and blank values as unset. */
+function nonBlank(value) {
+    return value !== undefined && value.trim() !== '' ? value : undefined;
+}
 /**
- * Find the git repo root by walking up from `startDir` looking for `.git/`.
- * Returns `undefined` if no repo is found.
+ * Resolve the API key for a CLI invocation. Pure.
+ *
+ * @param flag - Value of the `--api-key` option, if given.
+ * @param env - Environment to read `API_KEY_ENV_VAR` from.
+ * @returns The first non-blank of `flag` and the env var, or `undefined`.
  */
-function findRepoRoot(startDir) {
-    let dir = resolve(startDir);
-    const root = resolve('/');
-    while (dir !== root) {
-        if (existsSync(join(dir, '.git')) &&
-            statSync(join(dir, '.git')).isDirectory()) {
-            return dir;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
+function resolveApiKey(flag, env = process.env) {
+    return nonBlank(flag) ?? nonBlank(env[API_KEY_ENV_VAR]);
 }
 /**
- * Convert a watch path (directory, file path, or glob) to a concrete directory
- * that can be scanned for a repo root.
+ * Error text for a `401` CLI response (core `unauthorizedMessage` naming
+ * {@link CLI_KEY_SOURCES}). Never contains the key. Pure.
+ *
+ * @param keySent - Whether the request carried a bearer key.
+ * @returns Guidance on supplying (or checking) the key.
  */
-function watchPathToScanDir(watchPath) {
-    const absPath = resolve(watchPath);
-    try {
-        return statSync(absPath).isDirectory() ? absPath : 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
-            : dirname(trimmed);
-    const resolved = resolve(baseDir);
-    if (!existsSync(resolved))
-        return undefined;
-    return resolved;
+function cliUnauthorizedMessage(keySent) {
+    return unauthorizedMessage(keySent, CLI_KEY_SOURCES);
 }
 /**
- * Recursively find all `.gitignore` files under `dir`.
- * Skips `.git` and `node_modules` directories for performance.
+ * Send one request; map 401 and other non-OK statuses to errors.
+ *
+ * @param url - Full request URL.
+ * @param init - Request init.
+ * @param keySent - Whether the request carries a bearer key.
+ * @returns The parsed JSON body.
+ * @throws On `401` with {@link cliUnauthorizedMessage}; on any other non-OK
+ *   status with
+ *   `HTTP <status> <code>: <message>`.
  */
-function findGitignoreFiles(dir) {
-    const results = [];
-    const gitignorePath = join(dir, '.gitignore');
-    if (existsSync(gitignorePath)) {
-        results.push(gitignorePath);
+async function send(url, init, keySent) {
+    const res = await fetch(url, init);
+    if (res.status === 401) {
+        throw new Error(cliUnauthorizedMessage(keySent));
     }
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        if (entry === '.git' || entry === 'node_modules')
-            continue;
-        const fullPath = join(dir, entry);
-        try {
-            if (statSync(fullPath).isDirectory()) {
-                results.push(...findGitignoreFiles(fullPath));
-            }
-        }
-        catch {
-            // Skip inaccessible entries
-        }
+    if (!res.ok) {
+        const info = httpError(res.status, res.statusText, await res.text());
+        throw new Error(formatHttpError(info));
     }
-    return results;
+    return res.json();
 }
 /**
- * Parse a `.gitignore` file into an `ignore` instance.
+ * Create a JSON client for the watcher API.
+ *
+ * @param options - Base URL and optional bearer key.
+ * @returns A client whose requests carry `Authorization: Bearer <apiKey>`
+ *   when a key is set, and no `Authorization` header otherwise.
  */
-function parseGitignore(gitignorePath) {
-    const content = readFileSync(gitignorePath, 'utf8');
-    return ignore().add(content);
+function createApiClient(options) {
+    const { baseUrl, apiKey } = apiClientOptionsSchema.parse(options);
+    const keySent = apiKey !== undefined;
+    const auth = bearerHeaders(apiKey);
+    return {
+        get: (path) => send(`${baseUrl}${path}`, keySent ? { headers: auth } : undefined, keySent),
+        post: (path, body) => send(`${baseUrl}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...auth },
+            body: JSON.stringify(body),
+        }, keySent),
+    };
 }
+
 /**
- * Normalize a path to use forward slashes (required by `ignore` package).
+ * @module cli/jeeves-watcher/apiOptions
+ * Commander plumbing shared by the API-calling CLI commands: --port/--host/--api-key options, API client construction, error handling and JSON output.
  */
-function toForwardSlash(p) {
-    return p.replace(/\\/g, '/');
-}
+const DEFAULT_PORT = String(API_DEFAULTS.port);
+const DEFAULT_HOST = API_DEFAULTS.host;
 /**
- * Create an `isGitignored` callback from an optional {@link GitignoreFilter}.
- *
- * Eliminates the repeated inline pattern:
- * ```ts
- * gitignoreFilter ? (filePath: string) => gitignoreFilter!.isIgnored(filePath) : undefined
- * ```
- *
- * @param filter - Optional gitignore filter instance.
- * @returns A callback that checks gitignore status, or `undefined` when no filter is available.
+ * Add the standard `--port`, `--host` and `--api-key` options to a command.
+ * The key has no default, so it never appears in `--help` output.
  */
-function createIsGitignored(filter) {
-    return filter ? (filePath) => filter.isIgnored(filePath) : undefined;
+function withApiOptions(cmd) {
+    return cmd
+        .option('-p, --port <port>', 'API port', DEFAULT_PORT)
+        .option('-H, --host <host>', 'API host', DEFAULT_HOST)
+        .option('--api-key <key>', `API bearer key (defaults to the ${API_KEY_ENV_VAR} environment variable)`);
 }
 /**
- * Processor-level gitignore filter. Checks file paths against the nearest
- * `.gitignore` chain in git repositories.
+ * Build the API client for a command invocation.
+ *
+ * @param opts - Parsed command options.
+ * @returns A client for `http://<host>:<port>` carrying the resolved key.
  */
-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) {
-                // No git repo found. Check for a standalone .gitignore at the scan dir.
-                // This handles directories like OpenClaw workspaces that have .gitignore
-                // but no .git directory.
-                const standaloneGitignore = join(scanDir, '.gitignore');
-                if (existsSync(standaloneGitignore) && !this.repos.has(scanDir)) {
-                    const entry = {
-                        dir: scanDir,
-                        ig: parseGitignore(standaloneGitignore),
-                    };
-                    this.repos.set(scanDir, { root: scanDir, entries: [entry] });
-                }
-                continue;
-            }
-            if (this.repos.has(repoRoot))
-                continue;
-            const gitignoreFiles = findGitignoreFiles(repoRoot);
-            const entries = gitignoreFiles.map((gf) => ({
-                dir: 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 = resolve(filePath);
-        for (const [, repo] of this.repos) {
-            // Check if file is within this repo
-            const relToRepo = 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(resolve('/')) ||
-                /^[a-zA-Z]:/.test(relToRepo)) {
-                continue;
-            }
-            // Check each `.gitignore` entry (deepest-first)
-            for (const entry of repo.entries) {
-                const relToEntry = 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 = resolve(gitignorePath);
-        const gitignoreDir = dirname(absPath);
-        for (const [, repo] of this.repos) {
-            const relToRepo = 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 (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;
+function apiClient(opts) {
+    return createApiClient({
+        baseUrl: `http://${opts.host}:${opts.port}`,
+        apiKey: resolveApiKey(opts.apiKey),
+    });
+}
+/** Wrap an async action with standard error handling (stderr + exit code 1). */
+function handleErrors(fn) {
+    return async () => {
+        try {
+            await fn();
         }
-        // If not in any known repo, check if it's in a repo we haven't scanned
-        const repoRoot = findRepoRoot(gitignoreDir);
-        if (repoRoot && 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 });
-            }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
         }
-    }
+    };
 }
-
-/**
- * @module util/normalizeSlashes
- * Converts backslashes to forward slashes in paths without other transformations.
- */
-/**
- * Normalize path separators: replace backslashes with forward slashes.
- *
- * Does NOT lowercase or strip drive letters — use `normalizePath()` if you need that.
- *
- * @param path - The path string to normalize.
- * @returns The path with forward slashes.
- */
-function normalizeSlashes(path) {
-    return path.replace(/\\/g, '/');
+/** Print JSON response to stdout. */
+function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
 }
 
 /**
- * @module util/isPathWatched
- * Checks whether a file path falls within the watched scope defined by watch config globs.
- */
-/**
- * Check whether a file path matches the watched scope.
- * A path is watched if it matches at least one `paths` glob
- * AND does not match any `ignored` glob. Mirrors chokidar's
- * inclusion/exclusion logic.
+ * @module cli/jeeves-watcher/configCommands
+ * Re-wires core's `config` and `config apply` CLI commands through the shared API client, adding `--api-key` so they send the bearer key. Reads patches from a file or stdin.
  *
- * @param filePath - The file path to check.
- * @param watchPaths - Glob patterns that define watched paths.
- * @param ignoredPaths - Glob patterns that exclude paths (optional).
- * @returns `true` if the file is within watched scope.
+ * @remarks
+ * Core's `createServiceCli` registers both commands with an HTTP helper that
+ * cannot attach headers. This module keeps their names, arguments, options and
+ * output, adds `--api-key` and replaces only the action handlers. When the
+ * commands are absent (e.g. a bare test program) it does nothing.
  */
-function isPathWatched(filePath, watchPaths, ignoredPaths) {
-    const normalised = normalizeSlashes(filePath);
-    const opts = { dot: true, nocase: process.platform === 'win32' };
-    const isIncluded = picomatch(watchPaths, opts);
-    if (!isIncluded(normalised))
-        return false;
-    if (ignoredPaths && ignoredPaths.length > 0) {
-        const isExcluded = picomatch(ignoredPaths, opts);
-        if (isExcluded(normalised))
-            return false;
-    }
-    return true;
+/** Host core's config commands always address. */
+const CONFIG_HOST = API_DEFAULTS.host;
+/** Parsed options of the re-wired commands; Zod is the source of truth. */
+const configOptsSchema = z.object({
+    port: z.string(),
+    apiKey: z.string().optional(),
+    file: z.string().optional(),
+    replace: z.boolean().optional(),
+});
+/** Find a direct subcommand by name. */
+function findCommand(parent, name) {
+    return parent.commands.find((cmd) => cmd.name() === name);
+}
+/** Add `--api-key` to a command (no default, so it never shows in help). */
+function addApiKeyOption(cmd) {
+    cmd.option('--api-key <key>', `API bearer key (defaults to the ${API_KEY_ENV_VAR} environment variable)`);
+}
+/** Print an error with core's prefix and set exit code 1. */
+function reportFailure(prefix, err) {
+    console.error(`${prefix}: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
 }
-
 /**
- * @module util/normalizeError
+ * Read a config patch from `file`, else from stdin (empty input = `{}`).
  *
- * Normalizes unknown thrown values into proper Error objects for pino serialization.
+ * @throws With a one-line message when the file cannot be read, the input
+ *   is not JSON, or it is not a JSON object.
  */
-/**
- * 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 error - The caught value (may not be an Error).
- * @returns A proper Error instance.
- */
-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;
-}
-
-/**
- * @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)
-        return Promise.resolve();
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            cleanup();
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            cleanup();
-            reject(new Error('Sleep aborted'));
-        };
-        const cleanup = () => {
-            clearTimeout(timer);
-            if (signal)
-                signal.removeEventListener('abort', onAbort);
-        };
-        if (signal) {
-            if (signal.aborted) {
-                onAbort();
-                return;
-            }
-            signal.addEventListener('abort', onAbort, { once: true });
-        }
-    });
-}
-
-/**
- * @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);
-    const factor = jitter > 0 ? 1 + Math.random() * jitter : 1;
-    return Math.round(raw * factor);
-}
-/**
- * Retry an async operation using exponential backoff.
- *
- * @param fn - Operation to execute.
- * @param options - Retry policy.
- * @returns The operation result.
- */
-async function retry(fn, options) {
-    const attempts = Math.max(1, options.attempts);
-    const shouldRetry = options.shouldRetry ?? (() => true);
-    let lastError;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
+async function readPatch(file) {
+    let input;
+    if (file) {
         try {
-            return await fn(attempt);
+            input = readFileSync(file, 'utf-8');
         }
-        catch (error) {
-            lastError = error;
-            const isLast = attempt >= attempts;
-            if (isLast || !shouldRetry(error))
-                break;
-            const delayMs = computeDelayMs(attempt, options.baseDelayMs, options.maxDelayMs, options.jitter);
-            options.onRetry?.({ attempt, attempts, delayMs, error });
-            await sleep(delayMs, options.signal);
+        catch (err) {
+            const { code } = err;
+            throw new Error(`cannot read patch file ${file}${typeof code === 'string' ? ` (${code})` : ''}`, { cause: err });
         }
     }
-    throw lastError;
-}
-
-/**
- * @module vcs/gitExec
- * Shared git execution utilities: the pinned argv prefix, timeouts, error
- * field extraction and classification, and path comparison helpers.
- */
-/** Promisified execFile for git commands. */
-const execFileAsync = promisify(execFile);
-/**
- * Leading git arguments applied to every VCS-owned git invocation.
- *
- * `-c core.longpaths=true` lets Windows checkouts handle paths beyond the
- * legacy MAX_PATH limit (260 chars) without requiring a machine-wide
- * `core.longpaths` git config or registry change. See #249.
- */
-const GIT_BASE_ARGS = ['-c', 'core.longpaths=true'];
-/**
- * Build a git argv array with {@link GIT_BASE_ARGS} prefixed.
- *
- * @param args - The subcommand and its arguments (e.g. `'commit', '-m', msg`).
- * @returns The full argv array, base args first.
- */
-function gitArgs(...args) {
-    return [...GIT_BASE_ARGS, ...args];
-}
-/** Standard timeout (ms) for most git operations. */
-const GIT_TIMEOUT_STANDARD = 30_000;
-/** Extended timeout (ms) for cherry-pick operations. */
-const GIT_TIMEOUT_CHERRY_PICK = 120_000;
-/** Timeout (ms) for push operations. */
-const GIT_TIMEOUT_PUSH = 60_000;
-/**
- * Extract string fields from a child-process error.
- * Node's execFile wraps failures in an Error with `stderr`, `stdout`, and
- * `code` properties that aren't part of the Error type.
- */
-function getExecErrorFields(error) {
-    if (!(error instanceof Error)) {
-        return { message: String(error), stderr: '', stdout: '' };
+    else {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        input = Buffer.concat(chunks).toString('utf-8');
     }
-    const rec = error;
-    const stderr = typeof rec['stderr'] === 'string' ? rec['stderr'] : '';
-    const stdout = typeof rec['stdout'] === 'string' ? rec['stdout'] : '';
-    return { message: error.message || '', stderr, stdout };
-}
-/**
- * Read the `code` property of an unknown rejection value, if present.
- * execFile rejects with the child's numeric exit status in `code`; fs calls
- * reject with a string errno code (e.g. `'ENOENT'`).
- *
- * @param error - The caught value.
- * @returns The code, or undefined if the value has none.
- */
-function getErrorCode(error) {
-    if (typeof error !== 'object' || error === null || !('code' in error)) {
-        return undefined;
+    if (!input.trim())
+        return {};
+    let patch;
+    try {
+        patch = JSON.parse(input);
     }
-    const { code } = error;
-    return typeof code === 'string' || typeof code === 'number'
-        ? code
-        : undefined;
-}
-/**
- * Check whether an error is caused by `index.lock` contention.
- *
- * Requires the literal `index.lock` in the message or stderr: a bare
- * `EEXIST` (any file that already exists) is not lock contention and must
- * not be retried as if it were. Only Error instances qualify.
- *
- * @param error - The caught value.
- * @returns true if the error names `index.lock`.
- */
-function isIndexLockError(error) {
-    if (!(error instanceof Error))
-        return false;
-    const { message, stderr } = getExecErrorFields(error);
-    return message.includes('index.lock') || stderr.includes('index.lock');
-}
-/**
- * Normalize a path for case-insensitive comparison on Windows.
- * On Windows, lowercases the entire path; on other platforms, returns as-is.
- *
- * @param p - The path string to normalize.
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The normalized path.
- */
-function normalizePathCase(p, platform = process.platform) {
-    return platform === 'win32' ? p.toLowerCase() : p;
-}
-/**
- * Build a comparison key for an absolute path: resolved, forward slashes,
- * and lowercased on Windows.
- *
- * @param p - The path.
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The comparison key.
- */
-function pathKey(p, platform = process.platform) {
-    return normalizePathCase(normalizeSlashes(resolve(p)), platform);
-}
-/**
- * Find the longest-prefix-match root for a normalized path.
- * Roots must be sorted longest-first for correct nested matching.
- *
- * @param roots - Root paths sorted longest-first.
- * @param normalizedPath - Normalized absolute path (forward slashes).
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The matching root, or undefined.
- */
-function findRootForPath(roots, normalizedPath, platform = process.platform) {
-    const comparePath = normalizePathCase(normalizedPath, platform);
-    for (const root of roots) {
-        const compareRoot = normalizePathCase(root, platform);
-        if (comparePath === compareRoot ||
-            comparePath.startsWith(compareRoot + '/')) {
-            return root;
-        }
+    catch (err) {
+        throw new Error(`patch is not valid JSON (${err instanceof Error ? err.message : String(err)})`, { cause: err });
     }
-    return undefined;
+    if (!isPlainObject$1(patch))
+        throw new Error('patch must be a JSON object');
+    return patch;
 }
-
 /**
- * Best-effort base directory inference for a glob pattern.
+ * Make core's `config` and `config apply` commands send the bearer key.
  *
- * For our use (watch paths in config), this only needs to be good enough
- * to scan the directory tree in integration tests.
+ * @param program - The service CLI program, after core registered its commands.
  */
-function globBase(pattern) {
-    const normalised = normalizeSlashes(pattern);
-    const globIdx = normalised.search(/[*?[]/);
-    if (globIdx === -1)
-        return resolve(pattern);
-    const prefix = normalised.slice(0, globIdx);
-    // If prefix ends mid-segment, dirname to get a real directory
-    const base = prefix.endsWith('/') ? prefix.slice(0, -1) : dirname(prefix);
-    return resolve(base);
-}
-async function* walk(dir) {
-    let entries;
-    try {
-        const dirents = await readdir(dir, { withFileTypes: true });
-        entries = dirents.map((d) => ({
-            name: d.name,
-            isDirectory: d.isDirectory(),
-        }));
-    }
-    catch {
+function authenticateConfigCommands(program) {
+    const configCmd = findCommand(program, 'config');
+    if (!configCmd)
         return;
-    }
-    for (const entry of entries) {
-        const full = resolve(dir, entry.name);
-        if (entry.isDirectory) {
-            yield* walk(full);
+    addApiKeyOption(configCmd);
+    configCmd.action(async () => {
+        const opts = configOptsSchema.parse(configCmd.opts());
+        const jsonpath = configCmd.args[0];
+        const qs = jsonpath ? `?path=${encodeURIComponent(jsonpath)}` : '';
+        try {
+            const client = apiClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.get(`${getEndpoint('config').path}${qs}`));
         }
-        else {
-            // ensure it's a file
-            try {
-                const st = await stat(full);
-                if (st.isFile())
-                    yield full;
-            }
-            catch {
-                // ignore
-            }
+        catch (err) {
+            reportFailure('Config query failed', err);
         }
-    }
-}
-/**
- * Walk filesystem trees rooted at the base directories of `patterns`,
- * applying ignore globs, a primary match filter, an optional extra filter,
- * and gitignore filtering. Returns a deduplicated array of matching files.
- */
-async function walkAndFilter(params) {
-    const { patterns, ignored, isGitignored, extraFilter } = params;
-    const normPatterns = patterns.map((p) => normalizeSlashes(p));
-    const normIgnored = ignored.map((p) => normalizeSlashes(p));
-    const match = picomatch(normPatterns, { dot: true, nocase: true });
-    const ignore = normIgnored.length
-        ? picomatch(normIgnored, { dot: true, nocase: true })
-        : () => false;
-    const bases = Array.from(new Set(patterns.map(globBase)));
-    const seen = new Set();
-    for (const base of bases) {
-        for await (const file of walk(base)) {
-            const rel = normalizeSlashes(file);
-            if (ignore(rel))
-                continue;
-            if (!match(rel))
-                continue;
-            if (extraFilter && !extraFilter(rel))
-                continue;
-            if (isGitignored?.(file))
-                continue;
-            seen.add(file);
+    });
+    const applyCmd = findCommand(configCmd, 'apply');
+    if (!applyCmd)
+        return;
+    addApiKeyOption(applyCmd);
+    applyCmd.action(async () => {
+        const opts = configOptsSchema.parse(applyCmd.opts());
+        try {
+            const patch = await readPatch(opts.file);
+            const body = { patch };
+            if (opts.replace)
+                body.replace = true;
+            const client = apiClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.post(getEndpoint('configApply').path, body));
+        }
+        catch (err) {
+            reportFailure('Config apply failed', err);
         }
-    }
-    return Array.from(seen);
-}
-/**
- * List files matching a set of globs, with optional ignore globs and gitignore filter.
- *
- * @param patterns - Glob patterns to match.
- * @param ignored - Glob patterns to exclude (optional).
- * @param isGitignored - Optional callback to check gitignore status per file.
- */
-async function listFilesFromGlobs(patterns, ignored = [], isGitignored) {
-    return walkAndFilter({ patterns, ignored, isGitignored });
-}
-/**
- * List files from watch root base directories, applying watch extension globs,
- * ignored globs, gitignore, and an additional caller-provided glob intersection filter.
- *
- * Unlike `listFilesFromGlobs` (which derives walk roots from the glob patterns themselves),
- * this function always walks from watch root base directories and applies the caller's
- * globs as an additional intersection filter within the watched universe.
- *
- * @param watchPatterns - The configured watch path globs (defines the watched universe).
- * @param ignored - Glob patterns to exclude.
- * @param callerGlobs - Additional globs to intersect with. Only files matching both
- *   the watch patterns AND the caller globs are returned.
- * @param isGitignored - Optional callback to check gitignore status per file.
- */
-async function listFilesFromWatchRoots(watchPatterns, ignored, callerGlobs, isGitignored) {
-    const normCaller = callerGlobs.map((p) => normalizeSlashes(p));
-    const matchCaller = picomatch(normCaller, { dot: true, nocase: true });
-    return walkAndFilter({
-        patterns: watchPatterns,
-        ignored,
-        isGitignored,
-        extraFilter: (normalizedPath) => matchCaller(normalizedPath),
     });
 }
-/**
- * Get the base directories of the configured watch paths.
- */
-function getWatchRootBases(watchPatterns) {
-    return Array.from(new Set(watchPatterns.map(globBase)));
-}
 
 /**
- * @module processAllFiles
- *
- * Shared helper for processing all files matching configured globs.
+ * @module cli/jeeves-watcher/helperFormat
+ * Pure formatting for the `helpers` CLI command: renders JsonMap and Handlebars helper namespaces from GET /config query results as text.
  */
-/** Default concurrency limit for reindex operations. */
-const DEFAULT_REINDEX_CONCURRENCY = 50;
 /**
- * Process all files from globs using the specified processor method.
+ * Format a helpers section for display. Pure.
  *
- * @param watchPaths - The glob patterns to match.
- * @param ignoredPaths - The glob patterns to ignore.
- * @param processor - The document processor instance.
- * @param method - The processor method to call ('processFile' or 'processRulesUpdate').
- * @param concurrency - Maximum concurrent file operations (default 50).
- * @param callbacks - Optional progress tracking callbacks.
- * @param isGitignored - Optional callback to check gitignore status per file.
- * @param preComputedFiles - Optional pre-computed file list (skips listFilesFromGlobs).
- * @returns The number of files processed.
- */
-async function processAllFiles(watchPaths, ignoredPaths, processor, method, concurrency = DEFAULT_REINDEX_CONCURRENCY, callbacks, isGitignored, preComputedFiles) {
-    const files = preComputedFiles ??
-        (await listFilesFromGlobs(watchPaths, ignoredPaths, isGitignored));
-    callbacks?.onTotal?.(files.length);
-    await parallel(concurrency, files, async (file) => {
-        await processor[method](file);
-        callbacks?.onFileProcessed?.();
-    });
-    return files.length;
-}
-
-/**
- * @module api/executeReindex
- * Shared reindex execution logic used by both the reindex handler and the triggerReindex lambda.
- */
-/** Ordered list of valid reindex scopes for validation. */
-const VALID_REINDEX_SCOPES = [
-    'issues',
-    'full',
-    'rules',
-    'path',
-    'prune',
-];
-/**
- * Valid scopes for config-watch auto-trigger.
- * `prune` is excluded - auto-pruning on config change is dangerous.
+ * @param title - Section heading.
+ * @param data - Helper namespaces keyed by name.
+ * @returns The rendered section, or `''` when there are no helpers.
  */
-const CONFIG_WATCH_VALID_SCOPES = [
-    'issues',
-    'full',
-    'rules',
-];
-/** Fire reindex callback with exponential backoff retry. */
-async function fireCallback(url, payload, logger) {
-    await retry(async () => {
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
-        });
-        if (!response.ok) {
-            throw new Error(`Non-OK response: ${String(response.status)}`);
+function formatHelperSection(title, data) {
+    if (!data || Object.keys(data).length === 0)
+        return '';
+    const lines = [`${title}:`];
+    for (const [namespace, entry] of Object.entries(data)) {
+        if (entry.description) {
+            lines.push(`  [${namespace}] ${entry.description}`);
         }
-    }, {
-        attempts: 3,
-        baseDelayMs: 1000,
-        maxDelayMs: 4000,
-        onRetry: ({ attempt, error }) => {
-            logger.warn({ attempt, err: normalizeError(error), url }, 'Reindex callback failed; will retry');
-        },
-    });
-}
-/**
- * Group file paths by their watch root prefix.
- * Each file is matched against `watchPaths` and grouped under the first matching root.
- * Files that don't match any root are grouped under `'(unmatched)'`.
- */
-function groupByRoot(filePaths, watchPaths) {
-    const byRoot = {};
-    for (const fp of filePaths) {
-        const normalised = normalizeSlashes(fp);
-        let matched = false;
-        for (const root of watchPaths) {
-            const rootNorm = normalizeSlashes(root).replace(/\/?\*\*.*$/, '');
-            if (normalised.startsWith(rootNorm)) {
-                byRoot[rootNorm] = (byRoot[rootNorm] ?? 0) + 1;
-                matched = true;
-                break;
+        if (entry.exports) {
+            for (const [name, desc] of Object.entries(entry.exports)) {
+                const descPart = desc ? ` - ${desc}` : '';
+                lines.push(`  ${name.padEnd(40)}${descPart}`);
             }
         }
-        if (!matched) {
-            byRoot['(unmatched)'] = (byRoot['(unmatched)'] ?? 0) + 1;
+        else {
+            lines.push(`  (no exports introspected)`);
         }
     }
-    return byRoot;
+    return lines.join('\n');
 }
-/** Default page size for prune scroll (smaller than search to reduce connection strain). */
-const PRUNE_SCROLL_PAGE_SIZE = 500;
-/** Max retry attempts for scroll page failures. */
-const SCROLL_RETRY_ATTEMPTS = 5;
-/** Base delay for scroll retry backoff (ms). */
-const SCROLL_RETRY_BASE_DELAY_MS = 1000;
+
 /**
- * Scroll one page with retry/resume on connection failure.
- * On failure, retries with exponential backoff from the same cursor.
+ * @module cli/jeeves-watcher/metadataArgs
+ * Parses the `enrich` command's --json and --key options into a metadata object; reports validation errors on stderr and sets the exit code.
  */
-async function scrollPageWithRetry(vectorStore, cursor, logger) {
-    let lastError;
-    for (let attempt = 1; attempt <= SCROLL_RETRY_ATTEMPTS; attempt++) {
-        try {
-            const page = await vectorStore.scrollPage(undefined, PRUNE_SCROLL_PAGE_SIZE, cursor, ['file_path']);
-            return { points: page.points, nextCursor: page.nextCursor };
-        }
-        catch (error) {
-            lastError = error;
-            if (attempt < SCROLL_RETRY_ATTEMPTS) {
-                const delay = SCROLL_RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1) +
-                    Math.random() * 500;
-                logger.warn({ attempt, err: normalizeError(error) }, `Prune scroll page failed; retrying in ${String(Math.round(delay))}ms`);
-                await new Promise((resolve) => setTimeout(resolve, delay));
-            }
-        }
-    }
-    throw lastError;
+/** Whether a parsed JSON value is a plain object (not null, an array or a primitive). */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Concurrency limit for fs.access() disk-existence checks. */
-const FS_ACCESS_CONCURRENCY = 100;
 /**
- * Compute the plan for a prune operation using a filter-first approach.
+ * Parse `--json` and `--key` options into a metadata object.
+ * `--json` must be a JSON object; null, arrays and primitives are rejected.
  *
- * 1. Enumerate all watched files from the filesystem → `watchedFiles` set.
- * 2. Scroll Qdrant points. For each point:
- *    - No `file_path` → orphan.
- *    - `file_path` not in `watchedFiles` → orphan (out of watch scope).
- *    - `file_path` in `watchedFiles` → check disk existence via `fs.access()`.
- *      If missing from disk → orphan (deleted file still in index).
- * 3. Batch `fs.access()` checks with bounded concurrency.
+ * @param json - Metadata as a JSON string, if given.
+ * @param keys - `key=value` pairs (applied after `json`).
+ * @returns The metadata, or `null` on validation failure (already reported).
  */
-async function computePrunePlan(deps) {
-    const { config, vectorStore, gitignoreFilter, logger } = deps;
-    if (!vectorStore) {
-        throw new Error('vectorStore is required for prune scope');
-    }
-    // Step 1: Build set of watched files from filesystem
-    const isGitignored = createIsGitignored(gitignoreFilter);
-    const watchedFileList = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-    const watchedFiles = new Set(watchedFileList.map((f) => normalizePathCase(normalizeSlashes(f))));
-    logger.info({ watchedFileCount: watchedFiles.size }, 'Prune: enumerated watched files from filesystem');
-    // Step 2: Scroll Qdrant and classify points
-    const seenFiles = new Set();
-    const orphanedFiles = new Set();
-    const diskCheckFiles = new Set();
-    const orphanedIds = [];
-    // Map from file_path → point IDs, for points needing disk-existence check
-    const diskCheckPointIds = new Map();
-    let totalPoints = 0;
-    let incomplete = false;
-    let cursor;
-    try {
-        let hasMore = true;
-        while (hasMore) {
-            const page = await scrollPageWithRetry(vectorStore, cursor, logger);
-            for (const point of page.points) {
-                totalPoints++;
-                const filePath = point.payload.file_path;
-                if (!filePath) {
-                    orphanedIds.push(point.id);
-                    continue;
-                }
-                const normalized = normalizePathCase(normalizeSlashes(filePath));
-                if (seenFiles.has(normalized)) {
-                    if (orphanedFiles.has(normalized)) {
-                        orphanedIds.push(point.id);
-                    }
-                    else if (diskCheckFiles.has(normalized)) {
-                        // Already queued for disk check — track its ID
-                        const ids = diskCheckPointIds.get(normalized);
-                        if (ids)
-                            ids.push(point.id);
-                    }
-                    continue;
-                }
-                seenFiles.add(normalized);
-                if (!watchedFiles.has(normalized)) {
-                    // Not in watch scope → definitely orphaned
-                    orphanedFiles.add(normalized);
-                    orphanedIds.push(point.id);
-                }
-                else {
-                    // In watch scope → needs disk-existence check
-                    diskCheckFiles.add(normalized);
-                    diskCheckPointIds.set(normalized, [point.id]);
-                }
-            }
-            // Progress logging every 100K points
-            if (totalPoints > 0 && totalPoints % 100000 === 0) {
-                logger.info({ totalPoints, orphanedCount: orphanedIds.length }, 'Prune scroll progress');
-            }
-            if (!page.nextCursor) {
-                hasMore = false;
-            }
-            else {
-                cursor = page.nextCursor;
-            }
-        }
-    }
-    catch (error) {
-        logger.error({ err: normalizeError(error), totalPoints, cursor }, 'Prune scroll failed after retries; returning partial plan');
-        incomplete = true;
-    }
-    // Step 3: Batch fs.access() checks for files in watch scope
-    const filesToCheck = [...diskCheckFiles];
-    await parallel(FS_ACCESS_CONCURRENCY, filesToCheck, async (filePath) => {
+function parseMetadataArgs(json, keys) {
+    let metadata = {};
+    if (json) {
+        let parsed;
         try {
-            await access(filePath);
+            parsed = JSON.parse(json);
         }
         catch {
-            // File doesn't exist on disk → orphaned
-            orphanedFiles.add(filePath);
-            const pointIds = diskCheckPointIds.get(filePath);
-            if (pointIds) {
-                orphanedIds.push(...pointIds);
-            }
-        }
-    });
-    const orphanedFileList = [...orphanedFiles];
-    const byRoot = groupByRoot(orphanedFileList, extractWatchPathStrings(config.watch.paths));
-    return {
-        plan: {
-            total: totalPoints,
-            toProcess: 0,
-            toDelete: orphanedIds.length,
-            byRoot,
-            ...(incomplete ? { incomplete: true } : {}),
-        },
-        orphanedIds,
-    };
-}
-/**
- * Execute a reindex operation: process files, track progress, and fire callback if configured.
- *
- * @param deps - Dependencies.
- * @param scope - Reindex scope: 'issues', 'full', 'rules', 'path', or 'prune'.
- * @param path - Target path (required when scope is 'path').
- * @param dryRun - When true, compute and return the plan without executing.
- * @returns The reindex result including the blast area plan.
- */
-async function executeReindex(deps, scope, path, dryRun = false) {
-    const { config, processor, logger, reindexTracker, valuesManager, gitignoreFilter, } = deps;
-    const isGitignored = createIsGitignored(gitignoreFilter);
-    if (!VALID_REINDEX_SCOPES.includes(scope)) {
-        throw new Error(`Invalid reindex scope: "${scope}". Valid scopes: ${VALID_REINDEX_SCOPES.join(', ')}`);
-    }
-    const pathArray = path
-        ? Array.isArray(path)
-            ? path
-            : [path]
-        : undefined;
-    if (scope === 'path' && (!pathArray || pathArray.length === 0)) {
-        throw new Error('The "path" parameter is required when scope is "path".');
-    }
-    if (scope === 'prune' && !deps.vectorStore) {
-        throw new Error('vectorStore is required for prune scope.');
-    }
-    // Compute plan before starting async work
-    let plan;
-    if (scope === 'prune') {
-        deps.queue?.pause();
-        await deps.queue?.waitForIdleWorkers();
-        let pruneResult;
-        try {
-            pruneResult = await computePrunePlan(deps);
-        }
-        catch (err) {
-            deps.queue?.resume();
-            throw err;
-        }
-        plan = pruneResult.plan;
-        if (dryRun) {
-            deps.queue?.resume();
-            return { filesProcessed: 0, durationMs: 0, errors: 0, plan };
-        }
-        // Abort live prune when plan is incomplete — never silently delete partial data
-        if (plan.incomplete) {
-            deps.queue?.resume();
-            logger.error({ totalPoints: plan.total, pointsToDelete: plan.toDelete }, 'Aborting live prune — scroll was incomplete; partial deletes are unsafe');
-            return { filesProcessed: 0, durationMs: 0, errors: 1, plan };
-        }
-        // Execute prune
-        reindexTracker?.start(scope);
-        const startTime = Date.now();
-        try {
-            if (pruneResult.orphanedIds.length > 0) {
-                const batchSize = 500;
-                for (let i = 0; i < pruneResult.orphanedIds.length; i += batchSize) {
-                    const batch = pruneResult.orphanedIds.slice(i, i + batchSize);
-                    await deps.vectorStore.delete(batch);
-                }
-            }
-            const durationMs = Date.now() - startTime;
-            logger.info({ scope, pointsDeleted: pruneResult.orphanedIds.length, durationMs }, `Reindex (prune) completed`);
-            reindexTracker?.complete();
-            if (config.reindex?.callbackUrl) {
-                await fireCallback(config.reindex.callbackUrl, {
-                    scope,
-                    filesProcessed: 0,
-                    durationMs,
-                    pointsDeleted: pruneResult.orphanedIds.length,
-                    errors: [],
-                }, logger);
-            }
-            return {
-                filesProcessed: 0,
-                durationMs,
-                errors: 0,
-                plan,
-            };
-        }
-        catch (error) {
-            const durationMs = Date.now() - startTime;
-            logger.error({ err: normalizeError(error), scope }, 'Prune failed');
-            reindexTracker?.complete();
-            if (config.reindex?.callbackUrl) {
-                await fireCallback(config.reindex.callbackUrl, {
-                    scope,
-                    filesProcessed: 0,
-                    durationMs,
-                    errors: [normalizeError(error).message],
-                }, logger);
-            }
-            return { filesProcessed: 0, durationMs, errors: 1, plan };
-        }
-        finally {
-            deps.queue?.resume();
-        }
-    }
-    // Non-prune scopes: compute plan from file lists
-    let fileList;
-    if (scope === 'issues' && deps.issuesManager) {
-        const issues = deps.issuesManager.getAll();
-        fileList = Object.keys(issues);
-    }
-    else if (scope === 'path' && pathArray) {
-        // Path plan computed inline in the execution block below
-        fileList = undefined;
-    }
-    else if (scope === 'rules' && pathArray && pathArray.length > 0) {
-        // Rules scope with path filter: list from watch roots intersected with caller globs
-        fileList = await listFilesFromWatchRoots(extractWatchPathStrings(config.watch.paths), config.watch.ignored, pathArray, isGitignored);
-    }
-    else {
-        // rules or full: list files from globs
-        fileList = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-    }
-    if (fileList !== undefined) {
-        plan = {
-            total: fileList.length,
-            toProcess: fileList.length,
-            toDelete: 0,
-            byRoot: groupByRoot(fileList, extractWatchPathStrings(config.watch.paths)),
-        };
-    }
-    if (dryRun) {
-        // For path scope without pre-computed plan, compute it now
-        if (plan === undefined && scope === 'path' && pathArray) {
-            const pathFiles = await collectPathFiles(pathArray, config, deps.gitignoreFilter);
-            plan = {
-                total: pathFiles.length,
-                toProcess: pathFiles.length,
-                toDelete: 0,
-                byRoot: groupByRoot(pathFiles, extractWatchPathStrings(config.watch.paths)),
-            };
-        }
-        return { filesProcessed: 0, durationMs: 0, errors: 0, plan };
-    }
-    reindexTracker?.start(scope);
-    const startTime = Date.now();
-    let filesProcessed = 0;
-    let errors = 0;
-    const concurrency = config.reindex?.concurrency ?? 50;
-    try {
-        if (scope === 'full' && valuesManager) {
-            valuesManager.clearAll();
-        }
-        if (scope === 'issues' && fileList) {
-            await parallel(concurrency, fileList, async (filePath) => {
-                try {
-                    await processor.processFile(filePath);
-                    filesProcessed++;
-                }
-                catch (error) {
-                    errors++;
-                    logger.warn({ filePath, err: normalizeError(error) }, 'Failed to reprocess issue file');
-                }
-            });
-        }
-        else if (scope === 'rules') {
-            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processRulesUpdate', concurrency, {
-                onTotal: (total) => reindexTracker?.setTotal(total),
-                onFileProcessed: () => reindexTracker?.incrementProcessed(),
-            }, isGitignored, fileList);
-        }
-        else if (scope === 'path' && pathArray) {
-            const uniqueFiles = await collectPathFiles(pathArray, config, deps.gitignoreFilter);
-            plan = {
-                total: uniqueFiles.length,
-                toProcess: uniqueFiles.length,
-                toDelete: 0,
-                byRoot: groupByRoot(uniqueFiles, extractWatchPathStrings(config.watch.paths)),
-            };
-            reindexTracker?.setTotal(uniqueFiles.length);
-            await parallel(concurrency, uniqueFiles, async (filePath) => {
-                await processor.processFile(filePath);
-                reindexTracker?.incrementProcessed();
-                filesProcessed++;
-            });
-        }
-        else {
-            // Full reindex
-            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processFile', concurrency, {
-                onTotal: (total) => reindexTracker?.setTotal(total),
-                onFileProcessed: () => reindexTracker?.incrementProcessed(),
-            }, isGitignored, fileList);
+            console.error('Invalid JSON:', json);
+            process.exitCode = 1;
+            return null;
         }
-        const durationMs = Date.now() - startTime;
-        logger.info({ scope, filesProcessed, durationMs }, `Reindex (${scope}) completed`);
-        reindexTracker?.complete();
-        if (config.reindex?.callbackUrl) {
-            await fireCallback(config.reindex.callbackUrl, { scope, filesProcessed, durationMs, errors: [] }, logger);
+        if (!isPlainObject(parsed)) {
+            console.error('JSON metadata must be an object:', json);
+            process.exitCode = 1;
+            return null;
         }
-        return { filesProcessed, durationMs, errors, plan };
+        metadata = parsed;
     }
-    catch (error) {
-        errors = 1;
-        const durationMs = Date.now() - startTime;
-        logger.error({ err: normalizeError(error), scope }, 'Reindex failed');
-        reindexTracker?.complete();
-        if (config.reindex?.callbackUrl) {
-            await fireCallback(config.reindex.callbackUrl, {
-                scope,
-                filesProcessed: 0,
-                durationMs,
-                errors: [normalizeError(error).message],
-            }, logger);
+    if (Array.isArray(keys) && keys.length > 0) {
+        for (const pair of keys) {
+            const eqIndex = pair.indexOf('=');
+            if (eqIndex === -1) {
+                console.error(`Invalid key-value pair: ${pair}`);
+                process.exitCode = 1;
+                return null;
+            }
+            metadata[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
         }
-        return { filesProcessed: 0, durationMs, errors, plan };
-    }
-}
-/**
- * Collect and deduplicate files for a path-scoped reindex.
- *
- * Iterates over each target path, resolves its file list, and returns a
- * deduplicated array. This eliminates the duplicate iteration + `new Set()`
- * that previously appeared in both the dryRun plan and execution branches.
- */
-async function collectPathFiles(pathArray, config, gitignoreFilter) {
-    const allFiles = [];
-    for (const p of pathArray) {
-        const files = await getPathFileList(p, config, gitignoreFilter);
-        allFiles.push(...files);
-    }
-    return [...new Set(allFiles)];
-}
-/**
- * Get the file list for a path-scoped reindex (for plan computation).
- */
-async function getPathFileList(targetPath, config, gitignoreFilter) {
-    const watched = isPathWatched(targetPath, extractWatchPathStrings(config.watch.paths), config.watch.ignored);
-    if (!watched) {
-        throw new Error(`Path is outside watch scope: ${targetPath}`);
-    }
-    if (gitignoreFilter?.isIgnored(targetPath)) {
-        throw new Error(`Path is gitignored: ${targetPath}`);
     }
-    const stats = await stat(targetPath);
-    if (stats.isFile())
-        return [targetPath];
-    if (stats.isDirectory()) {
-        const isGitignored = createIsGitignored(gitignoreFilter);
-        const allWatchedFiles = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-        const targetAbsPath = resolve(targetPath);
-        return allWatchedFiles.filter((f) => resolve(f).startsWith(targetAbsPath));
+    if (Object.keys(metadata).length === 0) {
+        console.error('No metadata provided. Use --key or --json.');
+        process.exitCode = 1;
+        return null;
     }
-    throw new Error(`Path is neither a file nor a directory: ${targetPath}`);
+    return metadata;
 }
 
 /**
  * @module cli/jeeves-watcher/customCommands
  * Domain-specific CLI commands registered via the descriptor's customCliCommands.
- * Uses fetchJson/postJson from core instead of hand-rolled API helpers.
+ * Every API call goes through the shared client (`apiClient`), which sends the bearer key when one is resolved.
  */
-const DEFAULT_PORT = String(DEFAULT_PORTS.watcher);
-const DEFAULT_HOST = '127.0.0.1';
-/** Build the API base URL from host and port options. */
-function baseUrl(opts) {
-    return `http://${opts.host}:${opts.port}`;
-}
-/** Add standard --port and --host options to a command. */
-function withApiOptions(cmd) {
-    return cmd
-        .option('-p, --port <port>', 'API port', DEFAULT_PORT)
-        .option('-H, --host <host>', 'API host', DEFAULT_HOST);
-}
-/** Wrap an async action with standard error handling. */
-function handleErrors(fn) {
-    return async () => {
-        try {
-            await fn();
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-        }
-    };
-}
-/** Print JSON response to stdout. */
-function printJson(data) {
-    console.log(JSON.stringify(data, null, 2));
-}
 /**
  * Register all domain-specific commands on the given Commander program.
  *
  * @param program - The Commander program from createServiceCli.
  */
 function registerCustomCommands(program) {
+    // Core's `config` / `config apply` call the API too: give them the key.
+    authenticateConfigCommands(program);
     // --- search ---
     withApiOptions(program
         .command('search')
@@ -1425,7 +1104,7 @@ function registerCustomCommands(program) {
         .argument('<query>', 'Search query')
         .option('-l, --limit <limit>', 'Max results', '10')).action(async (query, opts) => {
         await handleErrors(async () => {
-            const result = await postJson(`${baseUrl(opts)}/search`, {
+            const result = await apiClient(opts).post(getEndpoint('search').path, {
                 query,
                 limit: Number(opts.limit),
             });
@@ -1443,7 +1122,7 @@ function registerCustomCommands(program) {
             const metadata = parseMetadataArgs(opts.json, opts.key);
             if (!metadata)
                 return;
-            const result = await postJson(`${baseUrl(opts)}/metadata`, {
+            const result = await apiClient(opts).post(getEndpoint('metadata').path, {
                 path,
                 metadata,
             });
@@ -1461,7 +1140,7 @@ function registerCustomCommands(program) {
         .option('--count-only', 'Return count only')).action(async (opts) => {
         await handleErrors(async () => {
             const filterObj = JSON.parse(opts.filter);
-            const result = await postJson(`${baseUrl(opts)}/scan`, {
+            const result = await apiClient(opts).post(getEndpoint('scan').path, {
                 filter: filterObj,
                 limit: Number(opts.limit),
                 cursor: opts.cursor,
@@ -1480,8 +1159,8 @@ function registerCustomCommands(program) {
         .option('-s, --scope <scope>', 'Reindex scope (issues|full|rules|path|prune)', 'rules')
         .option('-t, --path <paths...>', 'Target path(s) for path or rules scope')).action(async (opts) => {
         await handleErrors(async () => {
-            if (!VALID_REINDEX_SCOPES.includes(opts.scope)) {
-                console.error(`Invalid scope "${opts.scope}". Must be one of: ${VALID_REINDEX_SCOPES.join(', ')}`);
+            if (!reindexScopeSchema.safeParse(opts.scope).success) {
+                console.error(`Invalid scope "${opts.scope}". Must be one of: ${reindexScopeSchema.options.join(', ')}`);
                 process.exitCode = 1;
                 return;
             }
@@ -1489,7 +1168,7 @@ function registerCustomCommands(program) {
             if (opts.path) {
                 body.path = opts.path.length === 1 ? opts.path[0] : opts.path;
             }
-            const result = await postJson(`${baseUrl(opts)}/reindex`, body);
+            const result = await apiClient(opts).post(getEndpoint('reindex').path, body);
             printJson(result);
         })();
     });
@@ -1498,7 +1177,7 @@ function registerCustomCommands(program) {
         .command('rebuild-metadata')
         .description('Rebuild metadata store from Qdrant (POST /rebuild-metadata)')).action(async (opts) => {
         await handleErrors(async () => {
-            const result = await postJson(`${baseUrl(opts)}/rebuild-metadata`, {});
+            const result = await apiClient(opts).post(getEndpoint('rebuildMetadata').path, {});
             printJson(result);
         })();
     });
@@ -1507,19 +1186,18 @@ function registerCustomCommands(program) {
         .command('issues')
         .description('List current processing issues (GET /issues)')).action(async (opts) => {
         await handleErrors(async () => {
-            const result = await fetchJson(`${baseUrl(opts)}/issues`);
+            const result = await apiClient(opts).get(getEndpoint('issues').path);
             printJson(result);
         })();
     });
     // --- helpers ---
     withApiOptions(program.command('helpers').description('List available helper functions')).action(async (opts) => {
         await handleErrors(async () => {
-            const base = baseUrl(opts);
-            const mapPath = encodeURIComponent('$.mapHelpers');
-            const tplPath = encodeURIComponent('$.templateHelpers');
+            const client = apiClient(opts);
+            const query = (path) => client.get(`${getEndpoint('config').path}?path=${encodeURIComponent(path)}`);
             const [mapResult, tplResult] = await Promise.all([
-                fetchJson(`${base}/config?path=${mapPath}`),
-                fetchJson(`${base}/config?path=${tplPath}`),
+                query('$.mapHelpers'),
+                query('$.templateHelpers'),
             ]);
             const mapData = mapResult.result[0];
             const tplData = tplResult.result[0];
@@ -1539,58 +1217,6 @@ function registerCustomCommands(program) {
         })();
     });
 }
-/** Parse --json and --key options into a metadata object. Returns null on validation failure. */
-function parseMetadataArgs(json, keys) {
-    let metadata = {};
-    if (json) {
-        try {
-            metadata = JSON.parse(json);
-        }
-        catch {
-            console.error('Invalid JSON:', json);
-            process.exitCode = 1;
-            return null;
-        }
-    }
-    if (Array.isArray(keys) && keys.length > 0) {
-        for (const pair of keys) {
-            const eqIndex = pair.indexOf('=');
-            if (eqIndex === -1) {
-                console.error(`Invalid key-value pair: ${pair}`);
-                process.exitCode = 1;
-                return null;
-            }
-            metadata[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
-        }
-    }
-    if (Object.keys(metadata).length === 0) {
-        console.error('No metadata provided. Use --key or --json.');
-        process.exitCode = 1;
-        return null;
-    }
-    return metadata;
-}
-/** Format a helpers section for display. */
-function formatHelperSection(title, data) {
-    if (!data || Object.keys(data).length === 0)
-        return '';
-    const lines = [`${title}:`];
-    for (const [namespace, entry] of Object.entries(data)) {
-        if (entry.description) {
-            lines.push(`  [${namespace}] ${entry.description}`);
-        }
-        if (entry.exports) {
-            for (const [name, desc] of Object.entries(entry.exports)) {
-                const descPart = desc ? ` - ${desc}` : '';
-                lines.push(`  ${name.padEnd(40)}${descPart}`);
-            }
-        }
-        else {
-            lines.push(`  (no exports introspected)`);
-        }
-    }
-    return lines.join('\n');
-}
 
 /**
  * @module descriptor
@@ -1657,4 +1283,4 @@ const watcherDescriptor = {
 const program = createServiceCli(watcherDescriptor);
 program.parse();
 
-export { CONFIG_WATCH_VALID_SCOPES as C, GIT_TIMEOUT_STANDARD as G, VALID_REINDEX_SCOPES as V, normalizeError as a, getErrorCode as b, GIT_TIMEOUT_CHERRY_PICK as c, GIT_TIMEOUT_PUSH as d, execFileAsync as e, normalizePathCase as f, gitArgs as g, findRootForPath as h, isIndexLockError as i, GitignoreFilter as j, executeReindex as k, isPathWatched as l, mergeInferenceRules as m, normalizeSlashes as n, getWatchRootBases as o, pathKey as p, loadConfig as q, retry as r, sleep as s, startFromConfig as t };
+export { validateFacetTypes as a, mergeInferenceRules as b, findReservedFieldWarnings as c, startFromConfig as d, findUnknownSourceKeys as f, loadConfig as l, mergeSchemas as m, resolveAndCoerce as r, shutdownComponents as s, validateSchemaCompleteness as v };