@karmaniverous/jeeves-watcher 0.20.0 → 0.21.0-0

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

@@ -2,11 +2,35 @@
 import { substituteEnvVars, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
 import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-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 { isPlainObject as isPlainObject$1, findReservedPropertyNames, sourceConfigSchema, jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, WATCHER_CATALOG, API_KEY_ENV_VAR, VCS_EXCLUDE_CONFIRM_THRESHOLD, reindexScopeSchema, WATCHER_SKILL, WATCHER_PROMPT_RULES, 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 } from 'node:fs';
 import { cosmiconfig } from 'cosmiconfig';
 import { ZodError, z } from 'zod';
+import { createCatalogClient, CatalogClientError } from '@karmaniverous/jeeves/catalog';
+
+/**
+ * @module util/threadpool
+ * The libuv threadpool size the service runs with (D170). Pure: edits the given environment object.
+ */
+/** `UV_THREADPOOL_SIZE` the service uses unless the environment sets one. */
+const SERVICE_THREADPOOL_SIZE = '16';
+/**
+ * Default `UV_THREADPOOL_SIZE` to 16, keeping a value already set. libuv
+ * reads it when the threadpool first starts, so this must run before any
+ * threadpool work: the CLI entry imports it first.
+ *
+ * @param env - The environment to edit (`process.env` in the entry).
+ */
+function ensureThreadpoolSize(env) {
+    env.UV_THREADPOOL_SIZE ??= SERVICE_THREADPOOL_SIZE;
+}
+
+/**
+ * @module cli/jeeves-watcher/threadpool
+ * Side effect only: sets `UV_THREADPOOL_SIZE` (D170) before anything else in the CLI loads. Imported first by the entry point.
+ */
+ensureThreadpoolSize(process.env);
 
 /**
  * @module api/handlers/configMerge
@@ -666,7 +690,7 @@ async function drainQueues(queues, timeoutMs, logger) {
 /**
  * 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
+ * close stores. When a queue step or a producer's bounded stop 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.
@@ -677,9 +701,13 @@ 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);
+    let producersIdle = true;
+    for (const producer of producers) {
+        if ((await producer?.stop()) === false)
+            producersIdle = false;
+    }
+    const queuesIdle = await drainQueues(components, timeoutMs, logger);
+    const idle = producersIdle && queuesIdle;
     valuesManager?.stopAutoFlush();
     valuesManager?.flush();
     if (idle) {
@@ -750,7 +778,7 @@ async function startFromConfig(configPath, descriptor) {
     });
     // 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-C9-xTM7k.js');
+    const { JeevesWatcher } = await import('./index-CGVLEt3K.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -758,8 +786,300 @@ async function startFromConfig(configPath, descriptor) {
 }
 
 /**
- * @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.
+ * @module WatcherError
+ * The single error class thrown by the SDK: client-side validation, timeouts, network failures, non-2xx responses and unparseable responses. No I/O.
+ */
+/**
+ * The one error type thrown by every SDK call. The SDK never retries; inspect
+ * `status` and `code` to decide whether to.
+ */
+class WatcherError extends Error {
+    /** Machine-readable code: a {@link WatcherClientErrorCode} or a server code. */
+    code;
+    /** HTTP status, when a response was received. */
+    status;
+    /** Structured details (Zod issues, server `details`, or the raw body). */
+    details;
+    /**
+     * Delay the server asked for before a retry (`Retry-After` on a `503` or
+     * `429`), in milliseconds, clamped to 0..3,600,000 (D78). The SDK never
+     * waits or retries itself.
+     */
+    retryAfterMs;
+    /**
+     * Create a watcher error.
+     *
+     * @param init - Code, message and optional status, details, retry delay and cause.
+     */
+    constructor(init) {
+        super(init.message, init.cause === undefined ? {} : { cause: init.cause });
+        this.name = 'WatcherError';
+        this.code = init.code;
+        this.status = init.status;
+        this.details = init.details;
+        this.retryAfterMs = init.retryAfterMs;
+    }
+}
+/**
+ * Type guard for {@link WatcherError}.
+ *
+ * @param value - Any value (typically a caught error).
+ * @returns `true` when `value` is a {@link WatcherError}.
+ */
+function isWatcherError(value) {
+    return value instanceof WatcherError;
+}
+
+/**
+ * @module documents
+ * The `documents` method group over the catalog's `notifyDocuments` (POST /documents, 202 or ?wait=true) and `deleteDocuments` (POST /documents/delete) entries (D60). Network I/O via the client methods it wraps.
+ */
+/**
+ * Build the `documents` method group.
+ *
+ * @param notifyDocuments - Client method of the `notifyDocuments` entry.
+ * @param deleteDocuments - Client method of the `deleteDocuments` entry.
+ * @returns The {@link DocumentsApi}.
+ */
+function createDocumentsApi(notifyDocuments, deleteDocuments) {
+    return {
+        notify: (async (documents, options) => {
+            const wait = options?.wait === true;
+            const body = await notifyDocuments(wait ? { documents, wait: 'true' } : { documents });
+            if (wait !== 'results' in body) {
+                throw new WatcherError({
+                    code: 'invalid_response',
+                    message: `notifyDocuments answered without ${wait ? 'per-document results' : 'accepted references'}`,
+                    details: body,
+                });
+            }
+            return body;
+        }),
+        delete: (request) => deleteDocuments(request),
+    };
+}
+
+/**
+ * @module options
+ * Client options for createWatcherClient and their validation/normalisation (base URL, API key, timeout, fetch injection). Pure; throws WatcherError invalid_options.
+ */
+/**
+ * Default request timeout in milliseconds. Shorter than the server's
+ * longest waits (`RootGitLock` 30 s, document lock 10 s): raise `timeoutMs`
+ * for state-changing VCS calls and `documents.notify(..., { wait: true })`.
+ */
+const DEFAULT_TIMEOUT_MS = 10_000;
+const invalid = (message) => new WatcherError({ code: 'invalid_options', message });
+/**
+ * Adapt a {@link FetchLike} to the `fetch` signature jeeves's catalog client
+ * takes. The client always passes a URL string and an init object.
+ *
+ * @param fetchImpl - The caller's fetch.
+ * @returns A `typeof fetch` that calls `fetchImpl`.
+ */
+function adaptFetch(fetchImpl) {
+    return (input, init) => fetchImpl(typeof input === 'string'
+        ? input
+        : input instanceof URL
+            ? input.href
+            : input.url, init ?? {});
+}
+/**
+ * Validate and normalise client options.
+ *
+ * @param options - Caller options.
+ * @returns Resolved options.
+ * @throws {@link WatcherError} `invalid_options` on a bad base URL (not http(s), or carrying a query string or fragment), empty API key, non-positive timeout or missing `fetch`.
+ */
+function resolveClientOptions(options) {
+    const { baseUrl, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    if (!URL.canParse(baseUrl) || !/^https?:$/.test(new URL(baseUrl).protocol)) {
+        throw invalid(`baseUrl must be an http(s) URL, got "${baseUrl}"`);
+    }
+    // Entry paths are appended to baseUrl, so a query or fragment would
+    // swallow them. Check the raw string: URL drops an empty `?` or `#`.
+    if (/[?#]/.test(baseUrl)) {
+        throw invalid(`baseUrl must not contain a query string or fragment, got "${baseUrl}"`);
+    }
+    if (apiKey?.length === 0) {
+        throw invalid('apiKey must be a non-empty string when set');
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw invalid('timeoutMs must be a positive number');
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (fetchImpl === undefined) {
+        throw invalid('No fetch implementation available; pass options.fetch');
+    }
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        apiKey,
+        timeoutMs,
+        fetch: adaptFetch(fetchImpl),
+    };
+}
+
+/**
+ * @module toWatcherError
+ * The one mapping from jeeves's `CatalogClientError` to {@link WatcherError}: the server body's `code` wins; client-side failures get the SDK's own codes; `retryAfterMs` is clamped. Pure.
+ */
+/** Largest `retryAfterMs` the SDK reports: one hour (D78). */
+const MAX_RETRY_AFTER_MS = 3_600_000;
+/**
+ * Clamp a server-requested delay to 0..{@link MAX_RETRY_AFTER_MS}.
+ *
+ * @param ms - jeeves's `CatalogClientError.retryAfterMs` (uncapped).
+ * @returns The clamped delay, or `undefined` when the server sent none.
+ */
+function clampRetryAfter(ms) {
+    return ms === undefined
+        ? undefined
+        : Math.min(Math.max(ms, 0), MAX_RETRY_AFTER_MS);
+}
+const stringField = (body, key) => {
+    const value = body?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+/** Longest message kept from a body without a `code` (a proxy's error page, say); the whole body stays in `details`. */
+const MAX_UNCODED_MESSAGE_LENGTH = 200;
+/**
+ * Code, message and details of a non-2xx response body.
+ *
+ * @param status - HTTP status.
+ * @param body - jeeves's parsed error body (`{ error, ... }`).
+ * @returns The mapped parts.
+ */
+function serverError(status, body) {
+    const error = stringField(body, 'error');
+    const extra = stringField(body, 'message');
+    const message = error === undefined
+        ? (extra ?? `HTTP ${String(status)}`)
+        : extra !== undefined && extra !== error
+            ? `${error}: ${extra}`
+            : error;
+    const code = stringField(body, 'code');
+    return {
+        code: code ?? `http_${String(status)}`,
+        message: code === undefined && message.length > MAX_UNCODED_MESSAGE_LENGTH
+            ? `${message.slice(0, MAX_UNCODED_MESSAGE_LENGTH)}...`
+            : message,
+        details: body !== undefined && 'details' in body ? body.details : body,
+    };
+}
+/**
+ * The SDK code of a failure that produced no response.
+ *
+ * @param cause - The underlying error.
+ * @returns `timeout`, `invalid_response` (an unparseable 2xx body) or `network_error`.
+ *
+ * @remarks
+ * Assumes jeeves's client wraps a `SyntaxError` only from parsing a 2xx
+ * body; a caller's own `fetch` throwing one before any response would also
+ * read as `invalid_response`.
+ */
+function noResponseCode(cause) {
+    if (cause instanceof Error && cause.name === 'TimeoutError')
+        return 'timeout';
+    if (cause instanceof SyntaxError)
+        return 'invalid_response';
+    return 'network_error';
+}
+/**
+ * Convert a failed catalog call to a {@link WatcherError}.
+ *
+ * @param error - What the catalog client threw.
+ * @param operation - Catalog entry name (used in messages).
+ * @param timeoutMs - The client's timeout (used in the timeout message).
+ * @returns The error to throw.
+ */
+function toWatcherError(error, operation, timeoutMs) {
+    if (!(error instanceof CatalogClientError)) {
+        return new WatcherError({
+            code: 'network_error',
+            message: `${operation} request failed: ${String(error)}`,
+            cause: error,
+        });
+    }
+    const retryAfterMs = clampRetryAfter(error.retryAfterMs);
+    const common = {
+        cause: error,
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    };
+    if (error.status >= 300) {
+        return new WatcherError({
+            ...serverError(error.status, error.body),
+            status: error.status,
+            ...common,
+        });
+    }
+    if (error.issues !== undefined) {
+        const responded = error.status > 0;
+        return new WatcherError({
+            code: responded ? 'invalid_response' : 'invalid_request',
+            message: responded
+                ? `${operation} response did not match the expected shape`
+                : error.message,
+            details: error.issues,
+            ...(responded ? { status: error.status } : {}),
+            ...common,
+        });
+    }
+    const code = noResponseCode(error.cause);
+    const message = code === 'timeout'
+        ? `${operation} timed out after ${String(timeoutMs)} ms`
+        : code === 'invalid_response'
+            ? `${operation} returned a response that is not JSON`
+            : `${operation} request failed: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}`;
+    return new WatcherError({ code, message, ...common });
+}
+
+/**
+ * @module createWatcherClient
+ * Typed watcher API client built on jeeves's catalog client: one method per `WATCHER_CATALOG` entry, named by the entry, plus the `documents` group; every failure is a {@link WatcherError}. Network I/O via fetch.
+ */
+/**
+ * Create a watcher API client.
+ *
+ * @example
+ * ```ts
+ * const watcher = createWatcherClient({
+ *   baseUrl: 'http://watcher.internal.example:1936',
+ *   apiKey: process.env.WATCHER_API_KEY,
+ * });
+ * await watcher.documents.notify([{ source: 'app://chat/thread/123', rule: 'chat-thread' }]);
+ * ```
+ *
+ * @param options - Base URL, optional API key, timeout (default 10000 ms) and `fetch`.
+ * @returns A {@link WatcherClient}.
+ * @throws {@link WatcherError} `invalid_options` when the options are invalid.
+ */
+function createWatcherClient(options) {
+    const resolved = resolveClientOptions(options);
+    const catalogClient = createCatalogClient(WATCHER_CATALOG, {
+        baseUrl: resolved.baseUrl,
+        ...(resolved.apiKey === undefined
+            ? {}
+            : { auth: { bearer: resolved.apiKey } }),
+        timeoutMs: resolved.timeoutMs,
+        fetch: resolved.fetch,
+    });
+    const methods = Object.fromEntries(WATCHER_CATALOG.entries.map(({ name }) => {
+        const call = catalogClient[name];
+        const method = (input) => call(input).catch((error) => {
+            throw toWatcherError(error, name, resolved.timeoutMs);
+        });
+        return [name, method];
+    }));
+    const { notifyDocuments, deleteDocuments, ...rest } = methods;
+    return {
+        ...rest,
+        documents: createDocumentsApi(notifyDocuments, deleteDocuments),
+    };
+}
+
+/**
+ * @module cli/jeeves-watcher/cliClient
+ * The SDK client every API-calling CLI command uses (D37): `http://<host>:<port>`, the resolved bearer key, and a 60 s timeout (D119). Also the key resolution and the key hint printed after a 401. No I/O until a method is called.
  *
  * @remarks
  * Key resolution ({@link resolveApiKey}): the `--api-key` flag, then the
@@ -767,15 +1087,14 @@ async function startFromConfig(configPath, descriptor) {
  * 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). */
+/**
+ * Request timeout of every CLI command, in milliseconds (D119): longer than
+ * any server-side wait (`RootGitLock` 30 s, document lock 10 s), so a busy
+ * server's `503` reaches the user instead of a timeout.
+ */
+const CLI_TIMEOUT_MS = 60_000;
+/** Where the CLI reads its API key from (named in the 401 hint). */
 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;
@@ -791,67 +1110,44 @@ function resolveApiKey(flag, env = process.env) {
     return nonBlank(flag) ?? nonBlank(env[API_KEY_ENV_VAR]);
 }
 /**
- * Error text for a `401` CLI response (core `unauthorizedMessage` naming
- * {@link CLI_KEY_SOURCES}). Never contains the key. Pure.
+ * The hint printed after a `401`. Never contains the key. Pure.
  *
  * @param keySent - Whether the request carried a bearer key.
  * @returns Guidance on supplying (or checking) the key.
  */
-function cliUnauthorizedMessage(keySent) {
-    return unauthorizedMessage(keySent, CLI_KEY_SOURCES);
+function unauthorizedHint(keySent) {
+    return keySent
+        ? `The watcher API rejected the API key. Check ${CLI_KEY_SOURCES} against the service's api.apiKey.`
+        : `The watcher API requires an API key. Provide it via ${CLI_KEY_SOURCES}.`;
 }
 /**
- * Send one request; map 401 and other non-OK statuses to errors.
+ * The SDK client for a command invocation.
  *
- * @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>`.
- */
-async function send(url, init, keySent) {
-    const res = await fetch(url, init);
-    if (res.status === 401) {
-        throw new Error(cliUnauthorizedMessage(keySent));
-    }
-    if (!res.ok) {
-        const info = httpError(res.status, res.statusText, await res.text());
-        throw new Error(formatHttpError(info));
-    }
-    return res.json();
-}
-/**
- * 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 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),
-    };
+ * @param opts - Parsed command options.
+ * @returns A client for `http://<host>:<port>` with the resolved key and
+ *   {@link CLI_TIMEOUT_MS}.
+ */
+function cliClient(opts) {
+    const apiKey = resolveApiKey(opts.apiKey);
+    return createWatcherClient({
+        baseUrl: `http://${opts.host}:${opts.port}`,
+        ...(apiKey === undefined ? {} : { apiKey }),
+        timeoutMs: CLI_TIMEOUT_MS,
+    });
 }
 
 /**
  * @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.
+ * Commander plumbing shared by the API-calling CLI commands: --port/--host/--api-key, running a command against the SDK client, error reporting (`<code>: <message>` on stderr, exit code 1) and output (pretty JSON or raw text on stdout).
  */
 const DEFAULT_PORT = String(API_DEFAULTS.port);
 const DEFAULT_HOST = API_DEFAULTS.host;
 /**
  * Add the standard `--port`, `--host` and `--api-key` options to a command.
  * The key has no default, so it never appears in `--help` output.
+ *
+ * @param cmd - The command.
+ * @returns The command with the options added.
  */
 function withApiOptions(cmd) {
     return cmd
@@ -860,43 +1156,74 @@ function withApiOptions(cmd) {
         .option('--api-key <key>', `API bearer key (defaults to the ${API_KEY_ENV_VAR} environment variable)`);
 }
 /**
- * Build the API client for a command invocation.
+ * Describe a failure as `<code>: <message>`. A 401 adds the key hint; a
+ * timeout of a state-changing command adds that the operation may still
+ * complete on the server, and how to check (D119).
  *
- * @param opts - Parsed command options.
- * @returns A client for `http://<host>:<port>` carrying the resolved key.
+ * @param err - What the command threw.
+ * @param apiKey - `--api-key` value, to tell "no key" from "wrong key".
+ * @param checkAfterTimeout - How to check a timed-out state change.
+ * @returns The text to print (one or more lines).
  */
-function apiClient(opts) {
-    return createApiClient({
-        baseUrl: `http://${opts.host}:${opts.port}`,
-        apiKey: resolveApiKey(opts.apiKey),
-    });
+function describeError(err, apiKey, checkAfterTimeout) {
+    if (!isWatcherError(err)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const lines = [`${err.code}: ${err.message}`];
+    if (err.status === 401) {
+        lines.push(unauthorizedHint(resolveApiKey(apiKey) !== undefined));
+    }
+    if (err.code === 'timeout' && checkAfterTimeout !== undefined) {
+        lines.push(`The operation may still complete on the server; check with ${checkAfterTimeout}.`);
+    }
+    return lines.join('\n');
 }
-/** Wrap an async action with standard error handling (stderr + exit code 1). */
-function handleErrors(fn) {
-    return async () => {
-        try {
-            await fn();
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-        }
-    };
+/**
+ * Run a command against the SDK client: any failure is printed with
+ * {@link describeError} and sets exit code 1.
+ *
+ * @param opts - The command's connection options.
+ * @param fn - The command body.
+ * @param checkAfterTimeout - For state-changing commands: how to check
+ *   whether a timed-out call completed.
+ */
+async function runApiCommand(opts, fn, checkAfterTimeout) {
+    try {
+        await fn(cliClient(opts));
+    }
+    catch (err) {
+        console.error(describeError(err, opts.apiKey, checkAfterTimeout));
+        process.exitCode = 1;
+    }
 }
-/** Print JSON response to stdout. */
+/**
+ * Print a JSON response to stdout, pretty-printed.
+ *
+ * @param data - The response.
+ */
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * Print a text response to stdout as received.
+ *
+ * @param text - The response.
+ */
+function printText(text) {
+    process.stdout.write(text);
+}
 
 /**
  * @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.
+ * Re-wires core's `config` and `config apply` CLI commands through the SDK client (`config`, `configApply`), adding `--api-key` so they send the bearer key. Reads patches from a file or stdin.
  *
  * @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.
+ * output, adds `--api-key` and replaces only the action handlers, which call
+ * the SDK with the CLI's 60 s timeout. Failures print core's prefix, then
+ * `<code>: <message>`. When the commands are absent (e.g. a bare test
+ * program) it does nothing.
  */
 /** Host core's config commands always address. */
 const CONFIG_HOST = API_DEFAULTS.host;
@@ -916,8 +1243,8 @@ 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)}`);
+function reportFailure(prefix, err, apiKey) {
+    console.error(`${prefix}: ${describeError(err, apiKey)}`);
     process.exitCode = 1;
 }
 /**
@@ -969,13 +1296,12 @@ function authenticateConfigCommands(program) {
     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}`));
+            const client = cliClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.config(jsonpath ? { path: jsonpath } : {}));
         }
         catch (err) {
-            reportFailure('Config query failed', err);
+            reportFailure('Config query failed', err, opts.apiKey);
         }
     });
     const applyCmd = findCommand(configCmd, 'apply');
@@ -986,14 +1312,14 @@ function authenticateConfigCommands(program) {
         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));
+            const client = cliClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.configApply({
+                patch,
+                ...(opts.replace ? { replace: true } : {}),
+            }));
         }
         catch (err) {
-            reportFailure('Config apply failed', err);
+            reportFailure('Config apply failed', err, opts.apiKey);
         }
     });
 }
@@ -1084,10 +1410,95 @@ function parseMetadataArgs(json, keys) {
     return metadata;
 }
 
+/**
+ * @module cli/jeeves-watcher/vcsCommands
+ * The `vcs` command group (#213): status, history, show, diff, revert, check and exclude, each one SDK call (`getVcsStatus`, `listVcsHistory`, `showVcsFile`, `diffVcs`, `revertVcs`, `checkVcsExclusion`, `excludeVcsPath`). JSON replies print as pretty JSON; `show` and `diff` print the raw text.
+ */
+/** How to check whether a timed-out exclusion completed (D119). */
+const CHECK_EXCLUDE = '`jeeves-watcher vcs check <path>` or `vcs status`';
+/** How to check whether a timed-out revert completed (D119). */
+const CHECK_REVERT = '`jeeves-watcher vcs history <glob>`';
+/**
+ * Register the `vcs` command group.
+ *
+ * @param program - The Commander program.
+ */
+function registerVcsCommands(program) {
+    const vcs = program
+        .command('vcs')
+        .description('Version history of the watched files (/vcs/*)');
+    withApiOptions(vcs
+        .command('status')
+        .description('VCS state of every root (GET /vcs/status)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.getVcsStatus());
+    }));
+    withApiOptions(vcs
+        .command('history')
+        .description('Change history of a path or glob (GET /vcs/history)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .option('--since <date>', 'Only commits after this date')
+        .option('--until <date>', 'Only commits before this date')
+        .option('--limit <n>', 'Most commits to return (server default 20)')).action((glob, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.listVcsHistory({
+            glob,
+            since: opts.since,
+            until: opts.until,
+            limit: opts.limit,
+        }));
+    }));
+    withApiOptions(vcs
+        .command('show')
+        .description('File content at a commit (GET /vcs/show)')
+        .argument('<path>', 'File path inside a VCS root')
+        .argument('<commit>', 'Commit to read the file from')).action((path, commit, opts) => runApiCommand(opts, async (client) => {
+        printText(await client.showVcsFile({ path, commit }));
+    }));
+    withApiOptions(vcs
+        .command('diff')
+        .description('Unified diff from a commit (GET /vcs/diff)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .argument('<commit>', 'Commit to diff from')
+        .option('--to <commit>', 'Commit to diff to (default: the working tree)')).action((glob, commit, opts) => runApiCommand(opts, async (client) => {
+        printText(await client.diffVcs({ glob, commit, commitEnd: opts.to }));
+    }));
+    withApiOptions(vcs
+        .command('revert')
+        .description('Restore files from a commit, as a new commit (POST /vcs/revert)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .argument('<commit>', 'Commit to restore from')
+        .option('--existing-only', 'Restore only files that exist now')).action((glob, commit, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.revertVcs({
+            glob,
+            commit,
+            ...(opts.existingOnly ? { existingOnly: true } : {}),
+        }));
+    }, CHECK_REVERT));
+    withApiOptions(vcs
+        .command('check')
+        .description('Whether git ignores a path, and the rule, file and line (GET /vcs/check-exclusion)')
+        .argument('<path>', 'Path inside a VCS root')).action((path, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.checkVcsExclusion({ path }));
+    }));
+    withApiOptions(vcs
+        .command('exclude')
+        .description('Exclude a gitignore pattern from version history (it stays in search) and untrack the files it matches, or remove the exclusion (POST /vcs/exclude)')
+        .argument('<glob>', 'One gitignore pattern (escape brackets to name a file: Report \\[draft\\].docx)')
+        .option('--remove', 'Remove the exclusion instead of adding it')
+        .option('--root <root>', 'VCS root the glob is relative to')
+        .option('--confirm', `Allow untracking more than ${String(VCS_EXCLUDE_CONFIRM_THRESHOLD)} files`)).action((glob, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.excludeVcsPath({
+            glob,
+            root: opts.root,
+            ...(opts.remove ? { remove: true } : {}),
+            ...(opts.confirm ? { confirm: true } : {}),
+        }));
+    }, CHECK_EXCLUDE));
+}
+
 /**
  * @module cli/jeeves-watcher/customCommands
  * Domain-specific CLI commands registered via the descriptor's customCliCommands.
- * Every API call goes through the shared client (`apiClient`), which sends the bearer key when one is resolved.
+ * Every API call is one SDK client call (D37) with a 60 s timeout (`cliClient`), sending the bearer key when one is resolved.
  */
 /**
  * Register all domain-specific commands on the given Commander program.
@@ -1102,33 +1513,21 @@ function registerCustomCommands(program) {
         .command('search')
         .description('Search the vector store (POST /search)')
         .argument('<query>', 'Search query')
-        .option('-l, --limit <limit>', 'Max results', '10')).action(async (query, opts) => {
-        await handleErrors(async () => {
-            const result = await apiClient(opts).post(getEndpoint('search').path, {
-                query,
-                limit: Number(opts.limit),
-            });
-            printJson(result);
-        })();
-    });
+        .option('-l, --limit <limit>', 'Max results', '10')).action((query, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.search({ query, limit: Number(opts.limit) }));
+    }));
     // --- enrich ---
     withApiOptions(program
         .command('enrich')
         .description('Enrich document metadata (POST /metadata)')
         .argument('<path>', 'File path to enrich')
         .option('-k, --key <key=value...>', 'Metadata key-value pairs (repeatable)', [])
-        .option('-j, --json <json>', 'Metadata as JSON string (e.g., \'{"key":"value"}\')')).action(async (path, opts) => {
-        await handleErrors(async () => {
-            const metadata = parseMetadataArgs(opts.json, opts.key);
-            if (!metadata)
-                return;
-            const result = await apiClient(opts).post(getEndpoint('metadata').path, {
-                path,
-                metadata,
-            });
-            printJson(result);
-        })();
-    });
+        .option('-j, --json <json>', 'Metadata as JSON string (e.g., \'{"key":"value"}\')')).action((path, opts) => runApiCommand(opts, async (client) => {
+        const metadata = parseMetadataArgs(opts.json, opts.key);
+        if (!metadata)
+            return;
+        printJson(await client.setMetadata({ path, metadata }));
+    }));
     // --- scan ---
     withApiOptions(program
         .command('scan')
@@ -1137,85 +1536,80 @@ function registerCustomCommands(program) {
         .option('-l, --limit <limit>', 'Max results', '100')
         .option('-c, --cursor <cursor>', 'Cursor from previous response')
         .option('--fields <fields>', 'Fields to return (comma-separated)')
-        .option('--count-only', 'Return count only')).action(async (opts) => {
-        await handleErrors(async () => {
-            const filterObj = JSON.parse(opts.filter);
-            const result = await apiClient(opts).post(getEndpoint('scan').path, {
-                filter: filterObj,
-                limit: Number(opts.limit),
-                cursor: opts.cursor,
-                fields: opts.fields
-                    ? opts.fields.split(',').map((f) => f.trim())
-                    : undefined,
-                countOnly: opts.countOnly,
-            });
-            printJson(result);
-        })();
-    });
+        .option('--count-only', 'Return count only')).action((opts) => runApiCommand(opts, async (client) => {
+        const filter = JSON.parse(opts.filter);
+        printJson(await client.scan({
+            filter,
+            limit: Number(opts.limit),
+            cursor: opts.cursor,
+            fields: opts.fields
+                ? opts.fields.split(',').map((f) => f.trim())
+                : undefined,
+            countOnly: opts.countOnly,
+        }));
+    }));
+    // --- walk ---
+    withApiOptions(program
+        .command('walk')
+        .description('List watched files matching globs (POST /walk)')
+        .argument('<globs...>', 'Glob patterns to intersect with watch paths')).action((globs, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.walk({ globs }));
+    }));
     // --- reindex ---
     withApiOptions(program
         .command('reindex')
         .description('Trigger a reindex operation (POST /reindex)')
         .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 (!reindexScopeSchema.safeParse(opts.scope).success) {
-                console.error(`Invalid scope "${opts.scope}". Must be one of: ${reindexScopeSchema.options.join(', ')}`);
-                process.exitCode = 1;
-                return;
-            }
-            const body = { scope: opts.scope };
-            if (opts.path) {
-                body.path = opts.path.length === 1 ? opts.path[0] : opts.path;
-            }
-            const result = await apiClient(opts).post(getEndpoint('reindex').path, body);
-            printJson(result);
-        })();
-    });
+        .option('-t, --path <paths...>', 'Target path(s) for path or rules scope')
+        .option('--dry-run', 'Return the plan without running it')).action((opts) => runApiCommand(opts, async (client) => {
+        const scope = reindexScopeSchema.safeParse(opts.scope);
+        if (!scope.success) {
+            console.error(`Invalid scope "${opts.scope}". Must be one of: ${reindexScopeSchema.options.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        printJson(await client.reindex({
+            scope: scope.data,
+            ...(opts.path
+                ? { path: opts.path.length === 1 ? opts.path[0] : opts.path }
+                : {}),
+            ...(opts.dryRun ? { dryRun: true } : {}),
+        }));
+    }));
     // --- rebuild-metadata ---
     withApiOptions(program
         .command('rebuild-metadata')
-        .description('Rebuild metadata store from Qdrant (POST /rebuild-metadata)')).action(async (opts) => {
-        await handleErrors(async () => {
-            const result = await apiClient(opts).post(getEndpoint('rebuildMetadata').path, {});
-            printJson(result);
-        })();
-    });
+        .description('Rebuild metadata store from Qdrant (POST /rebuild-metadata)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.rebuildMetadata({}));
+    }));
     // --- issues ---
     withApiOptions(program
         .command('issues')
-        .description('List current processing issues (GET /issues)')).action(async (opts) => {
-        await handleErrors(async () => {
-            const result = await apiClient(opts).get(getEndpoint('issues').path);
-            printJson(result);
-        })();
-    });
+        .description('List current processing issues (GET /issues)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.listIssues());
+    }));
     // --- helpers ---
-    withApiOptions(program.command('helpers').description('List available helper functions')).action(async (opts) => {
-        await handleErrors(async () => {
-            const client = apiClient(opts);
-            const query = (path) => client.get(`${getEndpoint('config').path}?path=${encodeURIComponent(path)}`);
-            const [mapResult, tplResult] = await Promise.all([
-                query('$.mapHelpers'),
-                query('$.templateHelpers'),
-            ]);
-            const mapData = mapResult.result[0];
-            const tplData = tplResult.result[0];
-            const sections = [];
-            const mapSection = formatHelperSection('JsonMap lib functions', mapData);
-            if (mapSection)
-                sections.push(mapSection);
-            const tplSection = formatHelperSection('Handlebars helpers', tplData);
-            if (tplSection)
-                sections.push(tplSection);
-            if (sections.length === 0) {
-                console.log('No helpers configured.');
-            }
-            else {
-                console.log(sections.join('\n\n'));
-            }
-        })();
-    });
+    withApiOptions(program.command('helpers').description('List available helper functions')).action((opts) => runApiCommand(opts, async (client) => {
+        const query = (path) => client.config({ path });
+        const [mapResult, tplResult] = await Promise.all([
+            query('$.mapHelpers'),
+            query('$.templateHelpers'),
+        ]);
+        const mapData = mapResult.result[0];
+        const tplData = tplResult.result[0];
+        const sections = [];
+        const mapSection = formatHelperSection('JsonMap lib functions', mapData);
+        if (mapSection)
+            sections.push(mapSection);
+        const tplSection = formatHelperSection('Handlebars helpers', tplData);
+        if (tplSection)
+            sections.push(tplSection);
+        console.log(sections.length === 0
+            ? 'No helpers configured.'
+            : sections.join('\n\n'));
+    }));
+    // --- vcs ---
+    registerVcsCommands(program);
 }
 
 /**
@@ -1252,6 +1646,9 @@ const watcherDescriptor = {
     configSchema: jeevesWatcherConfigSchema,
     configFileName: 'config.json',
     initTemplate: () => ({ ...INIT_CONFIG_TEMPLATE }),
+    // Agent-facing text, shared with the plugin through watcher-core.
+    promptRules: WATCHER_PROMPT_RULES,
+    skill: WATCHER_SKILL,
     // onConfigApply is overridden in createApiServer (api/index.ts) via the
     // descriptor passed as a dependency, where it has access to the live
     // reindex tracker and config getter.
@@ -1280,7 +1677,8 @@ const watcherDescriptor = {
  * jeeves-watcher CLI entrypoint.
  * Uses core's createServiceCli factory with the watcher descriptor.
  */
+// First: libuv reads UV_THREADPOOL_SIZE when its threadpool starts (D170).
 const program = createServiceCli(watcherDescriptor);
 program.parse();
 
-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 };
+export { validateFacetTypes as a, mergeInferenceRules as b, findReservedFieldWarnings as c, shutdownComponents as d, startFromConfig as e, findUnknownSourceKeys as f, loadConfig as l, mergeSchemas as m, resolveAndCoerce as r, settlesWithin as s, validateSchemaCompleteness as v };