boondmanager-mcp-server 2.15.2 → 2.17.0

package/dist/services/http/retry.js

@@ -0,0 +1,101 @@
+/**
+ * Retry policy for the BoondManager client: configuration, the retryability
+ * decision, `Retry-After` parsing and full-jitter backoff. Pure functions,
+ * exported for unit testing; `send()` in `transport.ts` is the only consumer.
+ */
+import { readPositiveInt } from "../../config/env.js";
+import { DEFAULT_HTTP_MAX_RETRIES, DEFAULT_HTTP_RETRY_BASE_MS, DEFAULT_HTTP_RETRY_MAX_MS } from "../../constants.js";
+/** Resolve retry configuration from env, with safe fallbacks. Exported for tests. */
+export function resolveRetryConfig() {
+    return {
+        maxRetries: readPositiveInt("BOOND_HTTP_MAX_RETRIES", DEFAULT_HTTP_MAX_RETRIES, process.env, { allowZero: true }),
+        baseDelayMs: readPositiveInt("BOOND_HTTP_RETRY_BASE_MS", DEFAULT_HTTP_RETRY_BASE_MS),
+        maxDelayMs: readPositiveInt("BOOND_HTTP_RETRY_MAX_MS", DEFAULT_HTTP_RETRY_MAX_MS),
+    };
+}
+/**
+ * Decide whether a failed attempt is worth retrying.
+ *
+ * Retry policy is intentionally conservative for non-idempotent verbs to avoid
+ * silently duplicating writes when the server's response was lost or delayed:
+ *   - 429 (Too Many Requests) is always retried — the server explicitly
+ *     rejected the request before processing it, so it is safe regardless of
+ *     verb.
+ *   - For GET only, 5xx responses, network failures, and timeouts are retried
+ *     because GET is idempotent.
+ *   - 4xx responses (other than 429) are never retried — the client must change
+ *     the request before another attempt makes sense.
+ *
+ * Exported for unit testing.
+ */
+export function isRetryable(method, status, isNetworkOrTimeout) {
+    if (status === 429)
+        return true;
+    if (method !== "GET")
+        return false;
+    if (isNetworkOrTimeout)
+        return true;
+    if (status !== undefined && status >= 500 && status < 600)
+        return true;
+    return false;
+}
+/**
+ * Parse a `Retry-After` header value into milliseconds.
+ *
+ * Accepts either a non-negative number of seconds or an HTTP-date. Returns
+ * null when the value is absent or unparseable. Negative computed delays are
+ * clamped to 0. Exported for unit testing.
+ */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return null;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds)) {
+        // Numeric form is authoritative once we recognise it as a number — falling
+        // through to Date.parse on a negative/odd numeric would silently produce
+        // weird timestamps (e.g. Date.parse("-1") → year -1).
+        return seconds >= 0 ? Math.floor(seconds * 1000) : null;
+    }
+    const date = Date.parse(trimmed);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - now);
+    return null;
+}
+/**
+ * Compute the next backoff delay using full jitter:
+ *   delay = random(0, min(maxMs, baseMs * 2^attempt))
+ *
+ * Full jitter (vs. exponential-only) reduces thundering-herd risk when many
+ * clients retry in lockstep. Exported for unit testing.
+ */
+export function computeBackoffMs(attempt, baseMs, maxMs, random = Math.random) {
+    const exp = baseMs * 2 ** attempt;
+    const capped = Math.min(maxMs, exp);
+    return Math.floor(random() * capped);
+}
+/**
+ * Backoff sleep. With a `signal`, the wait ends the moment it fires — a
+ * cancelled caller does not sit out a 5 s `Retry-After` (issue #231); the
+ * rejection carries the signal's reason.
+ */
+export function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason ?? new Error("aborted"));
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("aborted"));
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/services/http/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/services/http/retry.ts"],"names":[],"mappings":"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"}

package/dist/services/http/transport.d.ts

@@ -0,0 +1,73 @@
+import type { JsonApiResponse } from "../../types.js";
+export type QueryValue = string | number | Array<string | number> | undefined;
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Resolve the per-request HTTP timeout in milliseconds.
+ *
+ * Reads BOOND_HTTP_TIMEOUT_MS at call time so tests / runtime overrides take
+ * effect without restarting the process. Falls back to the default for
+ * unset, non-numeric, or non-positive values.
+ *
+ * Exported for unit testing.
+ */
+export declare function resolveTimeoutMs(): number;
+/**
+ * Defense-in-depth against path traversal / query injection through entity
+ * ids interpolated into API paths at ~40 call sites. Even though the id
+ * schemas are now numeric-only, a future tool could forget to validate, so we
+ * assert here that the path is well-formed: it must start with `/`, carry no
+ * query (`?`) or fragment (`#`) — those arrive via `queryParams`, never the
+ * path — and contain no traversal (`..`) or percent/backslash escapes. Built
+ * paths only ever combine static segments with numeric ids and hyphenated tab
+ * names, so this rejects nothing legitimate. Exported for unit testing.
+ */
+export declare function assertSafeApiPath(path: string): void;
+/**
+ * Validates `path` and resolves it against `baseUrl`, returning the
+ * constructed URL. Throws if the path is unsafe (see `assertSafeApiPath`) or
+ * if the resolved URL escapes the configured API base origin/path. Exported
+ * for unit testing.
+ */
+export declare function resolveApiUrl(baseUrl: string, path: string): URL;
+/** What a helper hands to `send()`: everything but the plumbing. */
+export interface SendOptions {
+    method?: HttpMethod;
+    query?: Record<string, QueryValue>;
+    /**
+     * Request body, reused verbatim on every attempt: a JSON string or a
+     * `FormData` (both are re-serialised by `fetch` per call, so a retry never
+     * sends a consumed stream).
+     */
+    body?: string | FormData;
+    /** Extra headers (`Accept`, `Content-Type`); the auth header is added per attempt. */
+    headers?: Record<string, string>;
+    /**
+     * Cancellation signal. Defaults to the current MCP request's `extra.signal`
+     * (`currentRequestSignal()`, issue #231) — pass one only to override it.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Send one request through the whole pipeline — URL guard, per-identity rate
+ * limiter, auth header resolved per attempt (so an OAuth refresh between two
+ * tries is picked up), per-attempt timeout, retry policy with `Retry-After`,
+ * error mapping — and return the first **2xx** `Response`, body unread.
+ *
+ * Throws `BoondApiError` on a non-2xx that the policy does not retry (or once
+ * retries are exhausted), the standard timeout `Error` when an attempt never
+ * completed, `RequestCancelledError` (name `AbortError`) when the client
+ * cancelled — checked before each attempt, while waiting for a rate-limit
+ * token, during the fetch itself and during a backoff, and never retried —
+ * and the raw network error otherwise.
+ */
+export declare function send(path: string, options?: SendOptions): Promise<Response>;
+/** JSON:API request. `body` is serialised for POST / PUT / PATCH only. */
+export declare function apiRequest(path: string, method?: HttpMethod, body?: unknown, queryParams?: Record<string, QueryValue>): Promise<JsonApiResponse>;
+/**
+ * POST a multipart/form-data payload to the BoondManager API (document
+ * upload). Form values are simple string fields — the file itself travels by
+ * reference via the `fileUrl` field (Boond downloads it server-side), so the
+ * MCP server never buffers file bytes.
+ */
+export declare function apiUploadForm(path: string, fields: Record<string, string>): Promise<JsonApiResponse>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/services/http/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/services/http/transport.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAQtD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;AAC9E,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAWD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAUhE;AAoBD,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiIrF;AAkBD,0EAA0E;AAC1E,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,UAAkB,EAC1B,IAAI,CAAC,EAAE,OAAO,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,CAU1B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAQ1G"}

package/dist/services/http/transport.js

@@ -0,0 +1,272 @@
+/**
+ * The single HTTP send path towards BoondManager (issue #239).
+ *
+ * Before the split, `apiRequest`, `apiDownload` and `apiUploadForm` each
+ * carried their own copy of "resolve URL, acquire a rate-limit token, resolve
+ * the auth header, fetch with a timeout, map the error" — and they had
+ * diverged: the upload helper did not translate timeouts (a bare
+ * `TimeoutError` with no endpoint), retried nothing, and neither the download
+ * nor the upload helper honoured a 429. `send()` is now the only place that
+ * calls `fetch`, so the timeout, the rate limiter, the retry policy and the
+ * error shaping are the same for JSON, binary and multipart requests. The
+ * three helpers are thin wrappers that only decide what to do with the body.
+ */
+import { readPositiveInt } from "../../config/env.js";
+import { DEFAULT_HTTP_TIMEOUT_MS } from "../../constants.js";
+import { getConfig } from "./auth.js";
+import { BoondApiError, formatApiError, nonJsonResponseError, timeoutError } from "./errors.js";
+import { getRateLimiter } from "./rate-limit.js";
+import { computeBackoffMs, isRetryable, parseRetryAfter, resolveRetryConfig, sleep } from "./retry.js";
+import { currentRequestContext, RequestCancelledError, throwIfCancelled } from "../request-context.js";
+import { logger } from "../logger.js";
+/**
+ * Resolve the per-request HTTP timeout in milliseconds.
+ *
+ * Reads BOOND_HTTP_TIMEOUT_MS at call time so tests / runtime overrides take
+ * effect without restarting the process. Falls back to the default for
+ * unset, non-numeric, or non-positive values.
+ *
+ * Exported for unit testing.
+ */
+export function resolveTimeoutMs() {
+    return readPositiveInt("BOOND_HTTP_TIMEOUT_MS", DEFAULT_HTTP_TIMEOUT_MS);
+}
+/** True when an error from fetch() came from an AbortSignal firing. */
+function isAbortError(err) {
+    if (!(err instanceof Error))
+        return false;
+    // AbortSignal.timeout() rejects with a DOMException whose name is "TimeoutError";
+    // generic aborts surface as "AbortError". Both indicate the request never
+    // completed end-to-end and should be reported as a timeout.
+    return err.name === "TimeoutError" || err.name === "AbortError";
+}
+/**
+ * Defense-in-depth against path traversal / query injection through entity
+ * ids interpolated into API paths at ~40 call sites. Even though the id
+ * schemas are now numeric-only, a future tool could forget to validate, so we
+ * assert here that the path is well-formed: it must start with `/`, carry no
+ * query (`?`) or fragment (`#`) — those arrive via `queryParams`, never the
+ * path — and contain no traversal (`..`) or percent/backslash escapes. Built
+ * paths only ever combine static segments with numeric ids and hyphenated tab
+ * names, so this rejects nothing legitimate. Exported for unit testing.
+ */
+export function assertSafeApiPath(path) {
+    if (!path.startsWith("/")) {
+        throw new Error(`Invalid API path (must start with "/"): ${path}`);
+    }
+    // `?`/`#` would inject a query/fragment; `%`/`\` could encode a traversal;
+    // `..` is a literal traversal segment.
+    if (/[?#%\\]/.test(path) || path.includes("..")) {
+        throw new Error(`Unsafe API path rejected: ${path}`);
+    }
+}
+/**
+ * Validates `path` and resolves it against `baseUrl`, returning the
+ * constructed URL. Throws if the path is unsafe (see `assertSafeApiPath`) or
+ * if the resolved URL escapes the configured API base origin/path. Exported
+ * for unit testing.
+ */
+export function resolveApiUrl(baseUrl, path) {
+    assertSafeApiPath(path);
+    const url = new URL(`${baseUrl}${path}`);
+    // Belt-and-braces: confirm the constructed URL did not escape the API base
+    // origin/path despite the textual guard above.
+    const base = new URL(baseUrl);
+    if (url.origin !== base.origin || !url.pathname.startsWith(base.pathname)) {
+        throw new Error(`API path escaped the configured base URL: ${path}`);
+    }
+    return url;
+}
+/** Append query parameters; arrays use BoondManager's repeated bracket notation (`key[]=v1&key[]=v2`). */
+function applyQuery(url, queryParams) {
+    if (!queryParams)
+        return;
+    for (const [key, value] of Object.entries(queryParams)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            const bracketKey = key.endsWith("[]") ? key : `${key}[]`;
+            for (const v of value) {
+                if (v !== undefined && v !== null && v !== "") {
+                    url.searchParams.append(bracketKey, String(v));
+                }
+            }
+        }
+        else {
+            url.searchParams.set(key, String(value));
+        }
+    }
+}
+/**
+ * Send one request through the whole pipeline — URL guard, per-identity rate
+ * limiter, auth header resolved per attempt (so an OAuth refresh between two
+ * tries is picked up), per-attempt timeout, retry policy with `Retry-After`,
+ * error mapping — and return the first **2xx** `Response`, body unread.
+ *
+ * Throws `BoondApiError` on a non-2xx that the policy does not retry (or once
+ * retries are exhausted), the standard timeout `Error` when an attempt never
+ * completed, `RequestCancelledError` (name `AbortError`) when the client
+ * cancelled — checked before each attempt, while waiting for a rate-limit
+ * token, during the fetch itself and during a backoff, and never retried —
+ * and the raw network error otherwise.
+ */
+export async function send(path, options = {}) {
+    const method = options.method ?? "GET";
+    const { baseUrl, auth } = getConfig();
+    const url = resolveApiUrl(baseUrl, path);
+    applyQuery(url, options.query);
+    const timeoutMs = resolveTimeoutMs();
+    const retry = resolveRetryConfig();
+    const totalAttempts = retry.maxRetries + 1;
+    const limiter = getRateLimiter();
+    const context = currentRequestContext();
+    const signal = options.signal ?? context?.signal;
+    const corrId = context?.corrId;
+    // Correlation towards BoondManager (#236): the request id every log line
+    // carries, and the client's W3C trace context when it sent one. Header
+    // propagation only — no tracing SDK.
+    const correlationHeaders = {
+        ...(corrId ? { "X-Request-Id": corrId } : {}),
+        ...(context?.traceparent ? { traceparent: context.traceparent } : {}),
+    };
+    let lastError;
+    for (let attempt = 0; attempt < totalAttempts; attempt++) {
+        throwIfCancelled(signal, method, path);
+        // Acquire a token before each attempt so retries also count toward the
+        // rate budget — this is what actually protects us from feedback loops
+        // (transient 5xx → retry → transient 5xx → …) saturating the API.
+        if (limiter) {
+            try {
+                await limiter.acquire(signal);
+            }
+            catch (err) {
+                throwIfCancelled(signal, method, path);
+                throw err;
+            }
+        }
+        const authHeader = await auth();
+        const headers = {
+            [authHeader.name]: authHeader.value,
+            ...correlationHeaders,
+            ...options.headers,
+        };
+        const attemptStartedAt = Date.now();
+        const fetchOptions = {
+            method,
+            headers,
+            // Each attempt gets its own timeout signal — once a signal has fired it
+            // can't be reused for the next try. The request's cancellation signal
+            // is composed in so `notifications/cancelled` aborts the socket too.
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+        };
+        if (options.body !== undefined)
+            fetchOptions.body = options.body;
+        let response;
+        let networkError;
+        try {
+            response = await fetch(url.toString(), fetchOptions);
+        }
+        catch (err) {
+            // A cancellation is not a network failure: no retry, and the error
+            // says "cancelled", not "timed out".
+            if (signal?.aborted)
+                throw new RequestCancelledError(method, path, err);
+            networkError = isAbortError(err)
+                ? timeoutError(timeoutMs, method, path, err)
+                : err instanceof Error
+                    ? err
+                    : new Error(String(err));
+        }
+        // The query string is deliberately left out of every log line: `keywords`
+        // and the perimeter filters are end-user data.
+        const logFields = { corrId, method, path, attempt: attempt + 1, durationMs: Date.now() - attemptStartedAt };
+        if (response && response.ok) {
+            logger.debug({ ...logFields, status: response.status }, "boondmanager request");
+            return response;
+        }
+        let attemptError;
+        let isNetworkOrTimeout = false;
+        if (response) {
+            const errorText = await response.text().catch(() => "");
+            attemptError = new BoondApiError(formatApiError(response.status, response.statusText, method, path, errorText), response.status, method, path);
+        }
+        else {
+            attemptError = networkError;
+            isNetworkOrTimeout = true;
+        }
+        const hasMoreAttempts = attempt < totalAttempts - 1;
+        const timedOut = isNetworkOrTimeout && isAbortError(networkError.cause);
+        const failure = response ? { status: response.status } : { reason: timedOut ? "timeout" : "network" };
+        if (!hasMoreAttempts || !isRetryable(method, response?.status, isNetworkOrTimeout)) {
+            // A final 429 or timeout is worth a warning on its own; any other final
+            // failure reaches the tool log as `ok: false` and the tool's error text.
+            if (response?.status === 429 || timedOut) {
+                logger.warn({ ...logFields, ...failure, totalAttempts }, "boondmanager request failed");
+            }
+            else {
+                logger.debug({ ...logFields, ...failure, totalAttempts }, "boondmanager request failed");
+            }
+            throw attemptError;
+        }
+        // Only inspect Retry-After once we've actually decided to retry — keeps
+        // the fast path off the headers object and matches tests that build
+        // minimal Response stubs.
+        const retryAfterMs = response ? parseRetryAfter(response.headers?.get("retry-after") ?? null) : null;
+        const backoff = retryAfterMs !== null
+            ? Math.min(retry.maxDelayMs, retryAfterMs)
+            : computeBackoffMs(attempt, retry.baseDelayMs, retry.maxDelayMs);
+        logger.warn({ ...logFields, ...failure, totalAttempts, backoffMs: backoff }, "boondmanager request retried");
+        try {
+            await sleep(backoff, signal);
+        }
+        catch (err) {
+            throw new RequestCancelledError(method, path, err);
+        }
+        lastError = attemptError;
+    }
+    // Defensive — the loop always returns or throws. If somehow exhausted:
+    throw lastError ?? new Error("BoondManager API request exhausted retries with no recorded error.");
+}
+/**
+ * Read a 2xx body as JSON:API. A `204` / empty body (DELETE) is an empty page;
+ * a body that is not JSON becomes an error that names the endpoint instead of
+ * a bare `SyntaxError`.
+ */
+async function readJsonApi(response, method, path) {
+    if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return { data: [] };
+    }
+    try {
+        return (await response.json());
+    }
+    catch (err) {
+        throw nonJsonResponseError(response.status, method, path, err);
+    }
+}
+/** JSON:API request. `body` is serialised for POST / PUT / PATCH only. */
+export async function apiRequest(path, method = "GET", body, queryParams) {
+    const serialized = body && (method === "POST" || method === "PUT" || method === "PATCH") ? JSON.stringify(body) : undefined;
+    const response = await send(path, {
+        method,
+        ...(queryParams !== undefined ? { query: queryParams } : {}),
+        ...(serialized !== undefined ? { body: serialized } : {}),
+        headers: { Accept: "application/json", "Content-Type": "application/json" },
+    });
+    return readJsonApi(response, method, path);
+}
+/**
+ * POST a multipart/form-data payload to the BoondManager API (document
+ * upload). Form values are simple string fields — the file itself travels by
+ * reference via the `fileUrl` field (Boond downloads it server-side), so the
+ * MCP server never buffers file bytes.
+ */
+export async function apiUploadForm(path, fields) {
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        form.set(key, value);
+    }
+    // No Content-Type header: fetch derives the multipart boundary from FormData.
+    const response = await send(path, { method: "POST", body: form, headers: { Accept: "application/json" } });
+    return readJsonApi(response, "POST", path);
+}
+//# sourceMappingURL=transport.js.map

package/dist/services/http/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/services/http/transport.ts"],"names":[],"mappings":"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"}

package/dist/services/logger.d.ts

@@ -3,14 +3,65 @@ import pino from "pino";
  * Redaction paths for the structured logger. Defence-in-depth: nothing in the
  * codebase currently logs auth material, but if a request/error object that
  * carries credentials is ever passed to the logger, these paths censor it
- * before it reaches stdout / a log aggregator. Covers the BoondManager JWT
+ * before it reaches stderr / a log aggregator. Covers the BoondManager JWT
  * header, OAuth Bearer headers, and raw access tokens at one level of nesting.
  */
 export declare const REDACT_PATHS: string[];
+/**
+ * File descriptor every log line is written to: **stderr, on every transport**.
+ *
+ * On the stdio transport stdout *is* the JSON-RPC channel — anything that is
+ * not an MCP message corrupts the stream and the client drops the connection.
+ * Pino defaults to fd 1, and so does the pino-pretty transport when no
+ * `destination` is given, which is exactly how the "Access policy active"
+ * line, the update notice and the dictionary-override warnings used to land in
+ * the middle of the protocol (issue #225). stderr is what Claude Desktop
+ * captures into its log viewer, and it is equally fine for the HTTP transport,
+ * so there is one destination rather than one per transport.
+ */
+export declare const LOG_DESTINATION_FD = 2;
+/**
+ * Read the log level from env, falling back to 'info' for production-friendly
+ * defaults. DEBUG / trace logs are useful during development but too noisy
+ * in production. Pino's level hierarchy: trace < debug < info < warn < error < fatal.
+ */
+export declare function resolveLogLevel(env?: NodeJS.ProcessEnv): pino.Level;
+/** Human-readable (pretty) output in dev, JSON in prod. Override via LOG_FORMAT. */
+export declare function usePrettyOutput(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * `pino-pretty` is a **devDependency** (issue #246): it only serves the
+ * human-readable output of a development shell, and the `.mcpb` bundle and
+ * the Docker image are built with `--omit=dev`. Pino loads a transport by
+ * module name in a worker thread and throws at logger creation when the
+ * target is missing, so the pretty branch is taken only when the module
+ * resolves — otherwise the logger silently falls back to JSON on stderr,
+ * which is the production shape anyway.
+ */
+export declare function isPrettyTransportAvailable(): boolean;
+export type LoggerConfig = {
+    format: "pretty";
+    options: pino.LoggerOptions & {
+        transport: pino.TransportSingleOptions;
+    };
+} | {
+    format: "json";
+    options: pino.LoggerOptions;
+    destinationFd: number;
+};
+/**
+ * The two shapes the logger can take, as data — so a test can assert where each
+ * one writes without spawning a process. Pino refuses a stream argument when
+ * `transport` is set (the transport runs in a worker thread), which is why the
+ * destination travels inside the pino-pretty options on one branch and as a
+ * `pino.destination()` on the other.
+ */
+export declare function resolveLoggerConfig(env?: NodeJS.ProcessEnv, prettyAvailable?: boolean): LoggerConfig;
+export declare function createLogger(env?: NodeJS.ProcessEnv): pino.Logger;
 /**
  * Centralized structured logger. Use this instead of console.log/error for
  * all application logging — it provides timestamps, levels, and JSON output
- * (when LOG_FORMAT=json) that plays nicely with log aggregators.
+ * (when LOG_FORMAT=json) that plays nicely with log aggregators. It always
+ * writes to stderr (see `LOG_DESTINATION_FD`).
  *
  * Example:
  *   logger.info({ sessionId: "abc", userId: 123 }, "Session initialized");

package/dist/services/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,UAYxB,CAAC;AAcF;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,6BAejB,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAK9C"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAKxB;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,UAYxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAIpC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAAC,KAAK,CAIhF;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAOpD;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,IAAI,CAAC,aAAa,GAAG;QAAE,SAAS,EAAE,IAAI,CAAC,sBAAsB,CAAA;KAAE,CAAA;CAAE,GAC9F;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,eAAe,GAAE,OAAsC,GACtD,YAAY,CAuBd;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAAC,MAAM,CAI9E;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,6BAAiB,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAK9C"}