@novorb/mcp-core 2.1.2 → 3.0.0

package/dist/utils/envLoader.js

@@ -0,0 +1,399 @@
+/**
+ * @novorb/mcp-core - Env loader
+ *
+ * Every MCP server declares its own env schema (`EnvSchema`) and loads its environment through
+ * `loadEnv` (no dotenv). mcp-core's own keys (`CORE_ENV_SCHEMA`: transport,
+ * auth, logger, data storage) are merged in, so a server declares only its own keys.
+ *
+ * Sources, highest first: the real process env > `<rootDir>/.env` > the spec `value` default.
+ * `MCP_ENV_FILE` (read from the real env only) overrides the file path (absolute, or relative to
+ * rootDir); `MCP_ENV_FILE=none` disables the file. The file is parsed with Node's `util.parseEnv`.
+ *
+ *   const env = loadEnv([
+ *     { key: 'GITLAB_URL', type: 'url', value: 'https://gitlab.com', description: 'GitLab base URL' },
+ *     { key: 'GITLAB_PERSONAL_ACCESS_TOKEN', required: true, secret: true, description: 'API token' },
+ *   ], { rootDir: packageRootFrom(import.meta.url) });
+ *   if (!env.isConfigured()) getLogger().warn(`not configured: set ${env.missing.join(', ')}`);
+ *
+ * Values are never logged, never returned by `describe()`, and every set `secret: true` value is
+ * registered with the logger so it is masked verbatim in every log entry.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { parseEnv } from 'node:util';
+import { getLogger, MIN_SECRET_LENGTH, registerSecretValues } from './logger.js';
+/** mcp-core's own variables (transport, auth, logger, data storage), merged into every schema. */
+export const CORE_ENV_SCHEMA = [
+    {
+        key: 'MCP_TRANSPORT',
+        type: 'enum',
+        values: ['stdio', 'http'],
+        description: 'Transport: stdio (default) or http',
+    },
+    { key: 'PORT', type: 'int', description: 'HTTP listen port (default 8080)' },
+    { key: 'MCP_HTTP_HOST', description: 'HTTP bind address (default 0.0.0.0; 127.0.0.1 for local-only)' },
+    {
+        key: 'MCP_API_KEY',
+        secret: true,
+        description: 'Bearer token required on /mcp in HTTP mode (unless MCP_AUTH_DISABLED=true)',
+    },
+    { key: 'MCP_AUTH_DISABLED', type: 'bool', description: 'Run HTTP without auth (only behind a gateway)' },
+    { key: 'MCP_MAX_BODY_BYTES', type: 'int', description: 'Max POST body size in bytes (default 4 MiB)' },
+    { key: 'MCP_ALLOWED_HOSTS', description: 'Comma-separated Host allowlist (enables DNS-rebinding protection)' },
+    { key: 'MCP_ALLOWED_ORIGINS', description: 'Comma-separated Origin allowlist (enables DNS-rebinding protection)' },
+    { key: 'MCP_ENV_FILE', description: 'Env file path (absolute or relative to the package root); none disables it' },
+    { key: 'LOG_LEVEL', type: 'enum', values: ['DEBUG', 'INFO', 'WARN', 'ERROR'], description: 'Log level (INFO)' },
+    { key: 'LOG_FORMAT', type: 'enum', values: ['text', 'json'], description: 'Log line format (text)' },
+    { key: 'LOG_CONSOLE', type: 'bool', description: 'stderr log sink (true)' },
+    { key: 'LOG_FILE_MAIN', type: 'bool', description: 'Main <name>.log sink (true)' },
+    { key: 'LOG_FILE_EXCEPTIONS', type: 'bool', description: 'exceptions.log sink (true)' },
+    { key: 'LOG_FILE_DEBUG', type: 'bool', description: 'debug.log sink (true)' },
+    { key: 'LOG_PATH', description: 'Log directory (default <package root>/.logs)' },
+    { key: 'LOG_FILE', description: 'Main log file name (default <name>.log)' },
+    {
+        key: 'LOG_PROTOCOL',
+        type: 'bool',
+        description: 'Also send log entries to the client as MCP logging notifications (false; deprecated by 2026-07-28)',
+    },
+    { key: 'DATA_PATH', description: 'Data directory (default <package root>/.data)' },
+    {
+        key: 'DATA_STORAGE',
+        type: 'bool',
+        value: 'true',
+        description: 'Write to disk; false runs stateless (an invalid value also disables writes)',
+    },
+    {
+        key: 'MCP_LIST_PAGE_SIZE',
+        type: 'int',
+        description: 'tools/list (and resources/prompts) page size; 0 disables list pagination (default 100)',
+    },
+    {
+        key: 'MCP_MAX_RESULT_ITEMS',
+        type: 'int',
+        description: 'Max items per list-shaped tool result before it is paginated (default 100)',
+    },
+    {
+        key: 'MCP_MAX_RESULT_BYTES',
+        type: 'int',
+        description: 'Max serialized size of one tool result in bytes (default 262144)',
+    },
+    {
+        key: 'MCP_MAX_TOOL_INPUT_ELEMENTS',
+        type: 'int',
+        description: 'Max array elements plus object members in one tools/call arguments payload (default 10000)',
+    },
+    {
+        key: 'MCP_REQUEST_STATE_KEY',
+        secret: true,
+        description: 'Secret (at least 32 bytes) sealing multi-step requestState (AES-256-GCM); the same on every instance',
+    },
+    {
+        key: 'MCP_REQUEST_STATE_PREVIOUS_KEY',
+        secret: true,
+        multi: true,
+        description: 'Previous requestState secret(s) still accepted after a rotation (_1, _2, ...)',
+    },
+    {
+        key: 'MCP_CREDENTIAL_CHECKS',
+        type: 'bool',
+        value: 'true',
+        description: 'Run the credential checks once at startup; false skips them (offline or stateless starts)',
+    },
+    {
+        key: 'MCP_CREDENTIAL_RECHECK_MS',
+        type: 'int',
+        description: 'How long an invalid or expired credential waits before its check runs again (default 300000)',
+    },
+    {
+        key: 'MCP_CREDENTIAL_CHECK_TIMEOUT_MS',
+        type: 'int',
+        description: 'Timeout of one startup credential check in milliseconds (default 5000; a timeout reads unknown)',
+    },
+    {
+        key: 'MCP_REQUEST_STATE_TTL_SECONDS',
+        type: 'int',
+        description: 'Lifetime of a minted requestState in seconds (default 600)',
+    },
+];
+const ENV_FILE_NONE = 'none';
+/** A secret spec: `secret: true`, or any credential with a `check` (its value is a credential too). */
+export function isSecret(spec) {
+    return spec.secret === true || spec.check !== undefined;
+}
+const TRUE_WORDS = new Set(['true', '1', 'yes', 'on']);
+const FALSE_WORDS = new Set(['false', '0', 'no', 'off']);
+function parseBoolWord(value) {
+    const v = value.trim().toLowerCase();
+    if (TRUE_WORDS.has(v))
+        return true;
+    if (FALSE_WORDS.has(v))
+        return false;
+    return undefined;
+}
+function parseIntStrict(value) {
+    const v = value.trim();
+    if (!/^[+-]?\d+$/.test(v))
+        return undefined;
+    const n = Number(v);
+    return Number.isSafeInteger(n) ? n : undefined;
+}
+function isValidUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Merge schemas by key: a later spec for the same key replaces the earlier one (server overrides core). */
+function mergeSchemas(...schemas) {
+    const byKey = new Map();
+    for (const schema of schemas)
+        for (const spec of schema)
+            byKey.set(spec.key, spec);
+    return [...byKey.values()];
+}
+/** Order multi-family suffixes: numeric first (numeric order), then the rest alphabetically. */
+function compareSuffixes(a, b) {
+    const na = /^\d+$/.test(a);
+    const nb = /^\d+$/.test(b);
+    if (na && nb)
+        return Number(a) - Number(b) || a.localeCompare(b);
+    if (na)
+        return -1;
+    if (nb)
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function nonEmpty(value) {
+    return value === undefined || value === '' ? undefined : value;
+}
+function readEnvFile(rootDir, override) {
+    if (override !== undefined && override.trim().toLowerCase() === ENV_FILE_NONE)
+        return { file: null, values: {} };
+    const explicit = override !== undefined && override !== '';
+    const file = explicit ? path.resolve(rootDir, override) : path.join(path.resolve(rootDir), '.env');
+    if (!existsSync(file)) {
+        return explicit ? { file: null, values: {}, error: 'env file not found' } : { file: null, values: {} };
+    }
+    try {
+        const parsed = parseEnv(readFileSync(file, 'utf8'));
+        const values = {};
+        for (const [k, v] of Object.entries(parsed))
+            if (v !== undefined)
+                values[k] = v;
+        return { file, values };
+    }
+    catch {
+        return { file: null, values: {}, error: 'env file could not be read' };
+    }
+}
+function validate(spec, value) {
+    switch (spec.type) {
+        case 'int':
+            return parseIntStrict(value) === undefined ? 'must be an integer' : undefined;
+        case 'bool':
+            return parseBoolWord(value) === undefined ? 'must be a boolean (true/false, 1/0, yes/no, on/off)' : undefined;
+        case 'url':
+            return isValidUrl(value) ? undefined : 'must be a URL';
+        case 'enum': {
+            const allowed = spec.values ?? [];
+            return allowed.includes(value) ? undefined : `must be one of: ${allowed.join(', ')}`;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Load the environment for `schema` (merged with `CORE_ENV_SCHEMA`). Collects validation errors by key
+ * name (throws only with `strict: true`), warns once about undeclared env-file keys (names only),
+ * populates `env` for keys resolved from the file or a default (never overriding a set variable), and
+ * registers every set secret with the logger for verbatim masking.
+ */
+export function loadEnv(schema, options) {
+    const target = options.env ?? process.env;
+    const merged = options.includeCore === false ? mergeSchemas(schema) : mergeSchemas(CORE_ENV_SCHEMA, schema);
+    const specs = new Map(merged.map((s) => [s.key, s]));
+    const fileRead = readEnvFile(options.rootDir, target.MCP_ENV_FILE);
+    const resolved = new Map();
+    const resolveName = (name, fallback) => {
+        const fromEnv = nonEmpty(target[name]);
+        if (fromEnv !== undefined)
+            resolved.set(name, { value: fromEnv, source: 'env' });
+        else if (nonEmpty(fileRead.values[name]) !== undefined) {
+            resolved.set(name, { value: fileRead.values[name], source: 'file' });
+        }
+        else if (nonEmpty(fallback) !== undefined && fallback !== undefined) {
+            resolved.set(name, { value: fallback, source: 'default' });
+        }
+    };
+    // Multi families: KEY plus KEY_<suffix> from the env and the file, excluding keys declared on their own.
+    const families = new Map();
+    const claimed = new Set(specs.keys());
+    for (const spec of merged) {
+        resolveName(spec.key, spec.value);
+        if (!spec.multi)
+            continue;
+        const prefix = `${spec.key}_`;
+        const suffixes = new Set();
+        for (const name of [...Object.keys(target), ...Object.keys(fileRead.values)]) {
+            if (name.startsWith(prefix) && name.length > prefix.length && !specs.has(name)) {
+                suffixes.add(name.slice(prefix.length));
+            }
+        }
+        const members = [...suffixes].sort(compareSuffixes).map((s) => `${prefix}${s}`);
+        for (const member of members) {
+            claimed.add(member);
+            resolveName(member);
+        }
+        families.set(spec.key, members);
+    }
+    const errors = [];
+    if (fileRead.error)
+        errors.push({ key: 'MCP_ENV_FILE', message: fileRead.error });
+    for (const spec of merged) {
+        const names = [spec.key, ...(families.get(spec.key) ?? [])];
+        for (const name of names) {
+            const entry = resolved.get(name);
+            if (!entry)
+                continue;
+            const problem = validate(spec, entry.value);
+            if (problem)
+                errors.push({ key: name, message: problem });
+        }
+    }
+    const unknownFileKeys = Object.keys(fileRead.values)
+        .filter((k) => !claimed.has(k))
+        .sort();
+    if (unknownFileKeys.length > 0) {
+        getLogger().warn(`env file declares ${unknownFileKeys.length} key(s) no schema knows (not loaded): ${unknownFileKeys.join(', ')}`, 'Env');
+    }
+    // Populate the target env for file/default values so legacy `process.env.X` reads keep working.
+    for (const [name, entry] of resolved) {
+        if (entry.source !== 'env' && nonEmpty(target[name]) === undefined)
+            target[name] = entry.value;
+    }
+    // Secrets: hand every set secret value to the logger for verbatim masking.
+    const secretValues = [];
+    for (const spec of merged) {
+        if (!isSecret(spec))
+            continue;
+        for (const name of [spec.key, ...(families.get(spec.key) ?? [])]) {
+            const entry = resolved.get(name);
+            if (!entry)
+                continue;
+            secretValues.push(entry.value);
+            if (entry.value.length < MIN_SECRET_LENGTH) {
+                getLogger().warn(`env ${name} is a secret shorter than ${MIN_SECRET_LENGTH} characters and cannot be masked in logs or errors`, 'Env');
+            }
+        }
+    }
+    registerSecretValues(secretValues);
+    const has = (key) => {
+        if (resolved.has(key))
+            return true;
+        return (families.get(key) ?? []).some((m) => resolved.has(m));
+    };
+    const missing = merged.filter((s) => s.required && !has(s.key)).map((s) => s.key);
+    if (options.strict && errors.length > 0) {
+        throw new Error(`loadEnv: invalid environment: ${errors.map((e) => `${e.key} ${e.message}`).join('; ')}`);
+    }
+    const get = (key) => resolved.get(key)?.value;
+    const valid = (key) => {
+        const value = get(key);
+        if (value === undefined)
+            return undefined;
+        return errors.some((e) => e.key === key) ? undefined : value;
+    };
+    return {
+        schema: merged,
+        envFile: fileRead.file,
+        missing,
+        errors,
+        unknownFileKeys,
+        get,
+        members: (key) => [key, ...(families.get(key) ?? [])].filter((name) => resolved.has(name)),
+        getAll: (key) => {
+            const out = [];
+            const base = get(key);
+            if (base !== undefined)
+                out.push(base);
+            for (const member of families.get(key) ?? []) {
+                const value = get(member);
+                if (value !== undefined)
+                    out.push(value);
+            }
+            return out;
+        },
+        int: (key) => {
+            const value = valid(key);
+            return value === undefined ? undefined : parseIntStrict(value);
+        },
+        bool: (key) => {
+            const value = valid(key);
+            return value === undefined ? undefined : parseBoolWord(value);
+        },
+        has,
+        isConfigured: (keys) => (keys ?? merged.filter((s) => s.required).map((s) => s.key)).every(has),
+        describe: () => merged.map((spec) => {
+            const state = {
+                key: spec.key,
+                set: has(spec.key),
+                required: spec.required === true,
+                secret: isSecret(spec),
+            };
+            const source = resolved.get(spec.key)?.source;
+            if (source)
+                state.source = source;
+            if (spec.multi) {
+                state.count = [spec.key, ...(families.get(spec.key) ?? [])].filter((n) => resolved.has(n)).length;
+            }
+            return state;
+        }),
+    };
+}
+function escapeCell(text) {
+    return text.replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+}
+function typeLabel(spec) {
+    if (spec.type === 'enum')
+        return `enum (${(spec.values ?? []).join(', ')})`;
+    return spec.type ?? 'string';
+}
+/** A markdown table (key, type, required, multi, secret, default, description) for READMEs. */
+export function renderEnvTable(schema, options = {}) {
+    const specs = options.includeCore ? mergeSchemas(CORE_ENV_SCHEMA, schema) : mergeSchemas(schema);
+    const lines = [
+        '| Key | Type | Required | Multi | Secret | Default | Description |',
+        '|-----|------|----------|-------|--------|---------|-------------|',
+    ];
+    for (const s of specs) {
+        const key = s.multi ? `\`${s.key}\`, \`${s.key}_*\`` : `\`${s.key}\``;
+        const def = isSecret(s) || s.value === undefined || s.value === '' ? '' : `\`${escapeCell(s.value)}\``;
+        lines.push(`| ${key} | ${escapeCell(typeLabel(s))} | ${s.required ? 'yes' : 'no'} | ${s.multi ? 'yes' : 'no'} | ` +
+            `${isSecret(s) ? 'yes' : 'no'} | ${def} | ${escapeCell(s.description ?? '')} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** `.env.example` text: a comment per key, the default as the value, secrets always empty. */
+export function renderEnvExample(schema, options = {}) {
+    const specs = options.includeCore ? mergeSchemas(CORE_ENV_SCHEMA, schema) : mergeSchemas(schema);
+    const blocks = [];
+    for (const s of specs) {
+        const notes = [];
+        if (s.required)
+            notes.push('required');
+        if (isSecret(s))
+            notes.push('secret');
+        if (s.type && s.type !== 'string')
+            notes.push(typeLabel(s));
+        if (s.multi)
+            notes.push(`multi: also ${s.key}_1, ${s.key}_2, ...`);
+        const head = [s.description ?? '', notes.length ? `(${notes.join('; ')})` : ''].filter(Boolean).join(' ');
+        const value = isSecret(s) ? '' : (s.value ?? '');
+        blocks.push(`${head ? `# ${head.replace(/[\r\n]+/g, ' ')}\n` : ''}${s.key}=${value}`);
+    }
+    return `${blocks.join('\n\n')}\n`;
+}
+//# sourceMappingURL=envLoader.js.map

package/dist/utils/envLoader.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @novorb/mcp-core - Logger
+ *
+ * One logging utility for every MCP server. Sinks:
+ * - console: process.stderr only (never stdout, the stdio protocol channel)
+ * - <name>.log: the main log, every entry at or above the level
+ * - exceptions.log: ERROR entries only
+ * - debug.log: DEBUG entries only (so only when the level is DEBUG)
+ *
+ * Log directory: `<rootDir>/.logs` by default (rootDir = the consumer's package root, see
+ * `packageRootFrom`). LOG_PATH overrides it (absolute, or relative to rootDir). Without rootDir and
+ * without an absolute LOG_PATH the file sinks stay off (one console warning from initLogger); nothing
+ * is ever written relative to cwd.
+ *
+ * Switches (explicit config overrides env, env overrides the default):
+ *   LOG_LEVEL            DEBUG | INFO | WARN | ERROR             default INFO
+ *   LOG_FORMAT           text | json                             default text
+ *   LOG_CONSOLE          true | false                            default true
+ *   LOG_FILE_MAIN        true | false                            default true (needs a directory)
+ *   LOG_FILE_EXCEPTIONS  true | false                            default true (needs a directory)
+ *   LOG_FILE_DEBUG       true | false                            default true (needs a directory)
+ *   LOG_PATH             log directory                           default <rootDir>/.logs
+ *   LOG_FILE             main file name (absolute = as-is)       default <name>.log
+ *
+ * Text line: 2026-03-22T13:27:58.513Z | INFO  | Server | Starting... | {"meta":"json"}
+ * JSON line: {"level":"INFO","timestamp":"...","component":"Server","message":"Starting...",...meta}
+ *
+ * Every entry is sanitised: sensitive-keyed meta fields become [REDACTED], secret query parameters
+ * in strings become name=[REDACTED], and PII in the message and every meta string is masked
+ * ([EMAIL] [PHONE] [CARD] [IBAN] [JWT] [TOKEN] [IP]). Text mode also strips control characters.
+ *
+ * `initLogger` reconfigures the singleton IN PLACE, so a logger obtained with `getLogger()` at import
+ * time (before init) writes to the configured sinks after init.
+ */
+export { maskPii, redactSecrets } from './redact.js';
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+export type LogFormat = 'text' | 'json';
+export interface LoggerConfig {
+    /** Server name; the main log file is `<name>.log`. Required by initLogger when the main file is on. */
+    name?: string;
+    /** The consumer's package root; the default log directory is `<rootDir>/.logs`. */
+    rootDir?: string;
+    /** Log directory (overrides LOG_PATH); absolute, or relative to rootDir. */
+    logDir?: string;
+    /** Main log file name (overrides LOG_FILE); an absolute path is used as-is. */
+    logFile?: string;
+    /** Minimum level (LOG_LEVEL, default INFO). */
+    level: LogLevel;
+    /** Line format (LOG_FORMAT, default text). */
+    format: LogFormat;
+    /** stderr sink (LOG_CONSOLE, default true). */
+    console: boolean;
+    /** Main file sink (LOG_FILE_MAIN, default true). */
+    fileMain: boolean;
+    /** exceptions.log sink (LOG_FILE_EXCEPTIONS, default true). */
+    fileExceptions: boolean;
+    /** debug.log sink (LOG_FILE_DEBUG, default true). */
+    fileDebug: boolean;
+    /** Max size per file in bytes before rotation (default 10 MB). */
+    maxLogSize: number;
+    /** Rotated generations kept per file (default 5). */
+    maxLogFiles: number;
+    /** Log uncaught exceptions / unhandled rejections to main + exceptions, then exit(1). Default false. */
+    captureProcessErrors: boolean;
+}
+export type LoggerOptions = Partial<LoggerConfig>;
+/** The resolved sinks of a logger: console on/off and the absolute path of each active file. */
+export interface LogSinks {
+    console: boolean;
+    main?: string;
+    exceptions?: string;
+    debug?: string;
+}
+/** Registered secret values shorter than this are ignored (they would mask ordinary words). */
+export declare const MIN_SECRET_LENGTH = 6;
+/**
+ * Register secret VALUES (API tokens, passwords) that are masked verbatim as `[SECRET]` wherever they
+ * appear in any log entry, in both line formats (raw and JSON-escaped). The env loader calls this for
+ * every set `secret: true` variable. Process-global; values shorter than MIN_SECRET_LENGTH are ignored.
+ */
+export declare function registerSecretValues(values: Iterable<string>): void;
+/** Forget every registered secret value (tests). */
+export declare function clearSecretValues(): void;
+/** Replace every registered secret value in `s` with `[SECRET]` (longest first). */
+export declare function maskSecretValues(s: string): string;
+/** One accepted log entry as a listener sees it: already redacted and masked like the file lines. */
+export interface LogEntry {
+    level: LogLevel;
+    /** The logger name (`initLogger({ name })`), when set. */
+    logger?: string;
+    context: string;
+    message: string;
+    /** Redacted, PII-masked meta (secret values masked), or undefined. */
+    meta?: unknown;
+}
+/** Receives every entry the logger accepts (at or above its level), after redaction and masking. */
+export type LogListener = (entry: LogEntry) => void;
+/**
+ * Subscribe to accepted log entries (process-global, survives `initLogger` reconfiguration; cleared by
+ * `resetLogger`). Returns the unsubscribe function. A throwing listener is ignored, and a listener that
+ * logs from inside its own callback is not re-entered.
+ */
+export declare function addLogListener(listener: LogListener): () => void;
+export declare class Logger {
+    private config;
+    private resolved;
+    private fatalHandlers;
+    private sizes;
+    constructor(options?: LoggerOptions);
+    /**
+     * Reconfigure in place: recompute every setting from defaults + env + `options` (exactly as the
+     * constructor does), create the log directories, and install or remove the process-error handlers.
+     */
+    configure(options?: LoggerOptions): void;
+    /** The active sinks (console flag and absolute file paths). */
+    sinks(): LogSinks;
+    /** Remove the process-error handlers and this logger's claim on the stderr guard. */
+    detach(): void;
+    /** Remove the process-error handlers, if installed. */
+    detachProcessHandlers(): void;
+    private attachProcessHandlers;
+    private onFatal;
+    /** Write one WARN line to the console sink only (used for the directory warning). */
+    consoleWarn(message: string, context: string): void;
+    private formatText;
+    private formatJson;
+    private format;
+    private write;
+    private writeConsole;
+    private knownSize;
+    private writeFile;
+    /** maxLogFiles counts the active file: N keeps the active file plus N-1 rotated ones (minimum 1). */
+    private rotate;
+    debug(message: string, context?: string, meta?: unknown): void;
+    info(message: string, context?: string, meta?: unknown): void;
+    warn(message: string, context?: string, meta?: unknown): void;
+    error(message: string, context?: string, meta?: unknown): void;
+    setLevel(level: LogLevel): void;
+}
+/**
+ * Initialise (or reconfigure in place) the logger singleton. Call once at startup with the server
+ * `name` and its package `rootDir`. Throws when the main file is on, a directory exists, and neither
+ * `name` nor LOG_FILE is given. Warns once on the console when file sinks are on but there is no
+ * usable directory.
+ */
+export declare function initLogger(options?: LoggerOptions): Logger;
+/** Get the singleton, creating a default (console-only unless LOG_PATH is absolute) one if needed. */
+export declare function getLogger(options?: LoggerOptions): Logger;
+/** Drop the singleton, its process handlers and the process-global console state (tests). */
+export declare function resetLogger(): void;
+/**
+ * The package root of the module at `importMetaUrl` (pass `import.meta.url`): the nearest ancestor
+ * directory holding a package.json. Works from `src/` and `dist/` alike and is Windows-safe
+ * (`fileURLToPath`, never `URL.pathname`). Also accepts a plain file path.
+ */
+export declare function packageRootFrom(importMetaUrl: string | URL): string;
+/** Shape-only summary of tool arguments: one descriptor string per top-level key. */
+export type ArgsSummary = Record<string, string>;
+/**
+ * Summarise tool arguments by shape only, never by value. Per top-level key: `string(<len>)`,
+ * `array(<len>)`, `object{<key names, one level, max 20>}`, `number`, `boolean`, `null`, `undefined`,
+ * `bigint`, `function`. Non-object args are summarised under `_args`; null/undefined give `{}`.
+ */
+export declare function summarizeArgs(args: unknown): ArgsSummary;
+/** INFO `Tool call: <name>` with meta `{ tool, args: summarizeArgs(args) }`. Never the argument values. */
+export declare function logToolCall(name: string, args: unknown, context?: string): void;
+/**
+ * `Tool result: <name>` with meta `{ tool, isError, durationMs }` (durationMs rounded). INFO on
+ * success, WARN when isError. Never the result content.
+ */
+export declare function logToolResult(name: string, outcome: {
+    isError: boolean;
+    durationMs: number;
+}, context?: string): void;
+export default getLogger;
+//# sourceMappingURL=logger.d.ts.map

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

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