tina4-nodejs 3.13.92 → 3.13.94

package/types/core/src/job.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tina4 Queue Job — a single queue job with lifecycle methods.
+ */
+export interface JobData {
+    id: string;
+    payload: unknown;
+    status: "pending" | "reserved" | "failed" | "dead" | "completed";
+    createdAt: string;
+    attempts: number;
+    delayUntil: string | null;
+    priority: number;
+    topic: string;
+    error?: string;
+}
+export interface JobLifecycle {
+    /** Mark this job as completed. */
+    complete(): void;
+    /** Mark this job as failed with a reason. */
+    fail(reason?: string): void;
+    /** Reject this job with a reason. Alias for fail(). */
+    reject(reason?: string): void;
+    /** Re-queue this job with incremented attempts and optional delay. */
+    retry(delaySeconds?: number): void;
+    /** Return job fields as a flat array of values. */
+    toArray(): unknown[];
+    /** Return job as a plain object. */
+    toHash(): Record<string, unknown>;
+    /** Return job as a JSON string. */
+    toJson(): string;
+}
+export type QueueJob = JobData & JobLifecycle;
+export interface JobQueueBridge {
+    _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
+    _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
+    _completeJob(topic: string, job: QueueJob): void;
+    getMaxRetries(): number;
+}
+/** Create a QueueJob with lifecycle methods bound to a Queue instance. */
+export declare function createJob(data: JobData, queue: JobQueueBridge): QueueJob;

package/types/core/src/logger.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Structured logger for Tina4.
+ *
+ * Development (TINA4_DEBUG=true): colorized human-readable to stdout + file.
+ * Production (TINA4_DEBUG not truthy): clean structured JSON to stdout ONLY —
+ *   no log file by default (writing logs/tina4.log inside a container bloats the
+ *   writable layer + disk; 12-factor wants logs on stdout). stdout is ALWAYS on.
+ *
+ * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
+ * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
+ * TINA4_LOG_FILE path, always forces a file (explicit wins).
+ *
+ * Env vars:
+ *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. Empty = use TINA4_LOG_DIR + tina4.log
+ *   TINA4_LOG_DIR           — directory for log files (default: "logs")
+ *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text")
+ *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
+ *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
+ *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
+ *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
+ *
+ * Rotation is stdlib roll-your-own:
+ *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
+ *   - app.log.{N-1} → app.log.{N}, …, app.log → app.log.1 via fs.renameSync.
+ *   - Files beyond _KEEP are dropped via fs.unlinkSync.
+ *   - _SIZE=0 disables rotation entirely.
+ */
+export declare class Log {
+    private static requestId;
+    /**
+     * Re-read all log-related env vars. Called on every log() so tests that
+     * mutate process.env between calls see the new values without having to
+     * call configure() each time.
+     */
+    private static readEnv;
+    /**
+     * The single console-threshold predicate: does a message at `level` clear
+     * the configured minimum console level? This is the ONE place level
+     * comparison lives — both the live log() gate and the public isEnabled()
+     * predicate call it, so they can never disagree about what actually prints.
+     */
+    private static passesThreshold;
+    /**
+     * Return true if a message at `level` would pass the configured minimum
+     * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
+     *
+     * This reflects CONSOLE (stdout) visibility only. The log file always
+     * records every level regardless of this threshold, so don't use it to
+     * decide whether something gets persisted — use it to skip building an
+     * expensive payload that would not be shown:
+     *
+     *     if (Log.isEnabled("debug")) {
+     *       Log.debug("state", expensiveSnapshot());
+     *     }
+     *
+     * `level` is case-insensitive. "critical" is the highest severity (priority
+     * 4 > error 3) and flows through the ordinary threshold check like every
+     * other level — there is no toggle. It reuses the same passesThreshold()
+     * check the logger itself uses, so it never drifts from what print does.
+     */
+    static isEnabled(level: string): boolean;
+    /**
+     * Set the current request ID for log correlation.
+     */
+    static setRequestId(id: string | undefined): void;
+    /**
+     * Get the current request ID.
+     */
+    static getRequestId(): string | undefined;
+    /**
+     * Configure the log directory / filename. Mostly a no-op now —
+     * env vars are re-read on every call. Kept for backwards compatibility.
+     */
+    static configure(options: {
+        logDir?: string;
+        logFile?: string;
+    }): void;
+    /** Log an informational message. */
+    static info(message: string, data?: unknown): void;
+    /** Log a debug message. */
+    static debug(message: string, data?: unknown): void;
+    /** Log a warning message. */
+    static warning(message: string, data?: unknown): void;
+    /** Backwards-compat alias for warning(). */
+    static warn(message: string, data?: unknown): void;
+    /** Log an error message. */
+    static error(message: string, data?: unknown): void;
+    /**
+     * Log a critical message. CRITICAL is the highest severity (priority 4 >
+     * error 3) and ALWAYS emits like every other level — subject only to the
+     * console threshold, which it always passes at normal levels — and is always
+     * persisted to the log file (Node tees every level to a single tina4.log;
+     * critical 4 >= warning 2 so it would be in error.log on a split-file model).
+     * Matches Python master parity — there is no enable toggle.
+     */
+    static critical(message: string, data?: unknown): void;
+    /** Check if running in production mode (TINA4_DEBUG is not truthy). */
+    private static isProduction;
+    /** Get current ISO timestamp */
+    private static timestamp;
+    /** Ensure the log directory exists */
+    private static ensureLogDir;
+    /**
+     * Roll-your-own rotation, stdlib only.
+     *
+     * Sequence on each write:
+     *   1. statSync the current file. If size < rotateSize, return.
+     *   2. Drop any file beyond keep via unlinkSync (cap the historical count).
+     *   3. Atomic shift: app.log.{N-1} → app.log.{N}, …, app.log.1 → app.log.2.
+     *   4. Rename current app.log → app.log.1.
+     *   5. Truncate via writeFileSync(path, "") so subsequent appends start fresh.
+     *
+     * Sync calls per write are fine — the worst case is contention on a single
+     * file, and the OS atomically serialises rename/unlink anyway.
+     *
+     * `rotateSize` of 0 disables rotation entirely.
+     */
+    private static rotateIfNeeded;
+    /** Write a line to the log file, stripping ANSI codes. */
+    private static writeToFile;
+    /** Core log method */
+    private static log;
+}

package/types/core/src/mcp.d.ts

@@ -0,0 +1,248 @@
+export interface JsonRpcMessage {
+    jsonrpc: "2.0";
+    id?: number | string | null;
+    method?: string;
+    params?: Record<string, unknown>;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+export interface McpResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    handler: () => unknown;
+}
+export interface JsonSchema {
+    type: string;
+    properties: Record<string, {
+        type: string;
+        default?: unknown;
+    }>;
+    required?: string[];
+}
+export interface McpToolParam {
+    name: string;
+    type: "string" | "integer" | "number" | "boolean" | "array" | "object";
+    required?: boolean;
+    default?: unknown;
+}
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL_ERROR = -32603;
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const LATEST_PROTOCOL_VERSION: "2025-06-18";
+export declare function encodeResponse(requestId: number | string | null | undefined, result: unknown): string;
+export declare function encodeError(requestId: number | string | null | undefined, code: number, message: string, data?: unknown): string;
+export declare function encodeNotification(method: string, params?: Record<string, unknown>): string;
+export declare function decodeRequest(data: string | Record<string, unknown>): {
+    method: string;
+    params: Record<string, unknown>;
+    requestId: number | string | null;
+};
+/**
+ * Build a JSON Schema from an explicit parameter list.
+ * Since TypeScript erases types at runtime, we use explicit metadata.
+ */
+export declare function schemaFromParams(params: McpToolParam[]): JsonSchema;
+/**
+ * Informational only — whether the CONFIGURED host looks local.
+ *
+ * NOT the security gate. Reads `TINA4_HOST_NAME` (the configured bind address),
+ * which on a 0.0.0.0 bind looks "local" while still accepting remote clients.
+ * Trust decisions use {@link isRequestAllowed} with the RAW socket peer instead.
+ * Kept for diagnostics / back-compat.
+ */
+export declare function isLocalhost(): boolean;
+/**
+ * Whether an address is a loopback (in-process / same-host) peer.
+ *
+ * Operates on the RAW socket peer, never X-Forwarded-For. Empty/undefined means
+ * an in-process / synthetic request (no socket) and is trusted. The `::ffff:`
+ * IPv4-mapped prefix is stripped. NOTE: 0.0.0.0 is a BIND address, never a
+ * client address, so it is deliberately NOT loopback.
+ *
+ * Python master parity: tina4_python.mcp.is_loopback.
+ */
+export declare function isLoopback(ip: string | undefined | null): boolean;
+/**
+ * Capability gate — whether MCP may run at all.
+ *
+ * Pure capability, host-INDEPENDENT (Python master parity):
+ *   1. `TINA4_MCP` explicit on/off override (sysadmin, any host).
+ *   2. Else `TINA4_DEBUG=true` → MCP is a capability of this deployment.
+ *   3. Otherwise off.
+ *
+ * This NO LONGER consults the host. A debug box bound to 0.0.0.0 still "has"
+ * the capability, but {@link isRequestAllowed} decides whether a given CALLER
+ * may use it — loopback always, remote only with an explicit opt-in plus a
+ * valid token. Splitting capability from per-request authorisation closes the
+ * hole where a 0.0.0.0 bind auto-exposed DB/file tools to remote
+ * unauthenticated callers (the pre-3.13.40 isLocalhost() treated 0.0.0.0 local).
+ */
+export declare function mcpEnabled(): boolean;
+/**
+ * Per-request authorisation — whether THIS caller may use MCP.
+ *
+ * @param remoteIp        Raw socket peer (`req.socket.remoteAddress`), never XFF.
+ * @param hasValidToken   True when the request carried a token matching TINA4_MCP_TOKEN.
+ *
+ * Rules (Python master parity, tina4_python.mcp.is_request_allowed):
+ *   - Capability off ({@link mcpEnabled} false) → deny.
+ *   - Loopback peer → allow.
+ *   - Remote peer → only when TINA4_MCP_REMOTE is truthy AND a valid token was
+ *     presented. No configured token ⇒ remote can never pass.
+ */
+export declare function isRequestAllowed(remoteIp: string | undefined | null, hasValidToken?: boolean): boolean;
+/**
+ * Resolve the MCP HTTP port. Default: HTTP server port + 2000.
+ *
+ * `TINA4_MCP_PORT` overrides directly. The `mainPort` argument is the
+ * primary HTTP port (the framework passes `port` from `resolvePortAndHost`).
+ */
+export declare function mcpPort(mainPort?: number): number;
+export declare class McpServer {
+    static _instances: McpServer[];
+    path: string;
+    name: string;
+    version: string;
+    private _tools;
+    private _resources;
+    private _initialized;
+    private _sessions;
+    private _sseChannels;
+    constructor(mcpPath: string, name?: string, version?: string);
+    /** Mint a new session id and remember it. Called on `initialize`. */
+    openSession(): string;
+    /** True when `sessionId` was issued by this server and is still open. */
+    isValidSession(sessionId: string | undefined | null): boolean;
+    /** Forget a session (client DELETE or SSE stream close). */
+    closeSession(sessionId: string | undefined | null): boolean;
+    /**
+     * Pick the protocol version to run on. Echo the client's requested version
+     * when we support it (proper negotiation), else fall back to the newest we
+     * speak so an unversioned/old client still connects.
+     */
+    negotiateProtocolVersion(requested: string | undefined | null): string;
+    private _peekMethod;
+    /**
+     * Streamable HTTP POST handler. initialize mints a session id (returned in
+     * the Mcp-Session-Id response header); a non-initialize request with an
+     * unknown session id is a 404 (client re-inits); a notification is 202; else
+     * 200 with the JSON-RPC response as application/json (which the spec permits
+     * for a POST that resolves to a single response).
+     */
+    dispatchHttp(raw: string | Record<string, unknown>, sessionId?: string): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+    /**
+     * Legacy HTTP+SSE POST /message handler. When a live SSE stream is open for
+     * `sessionId`, run the message and push the response down that stream (202
+     * here); with no open stream it degrades to an inline Streamable HTTP
+     * response, so the same path serves a legacy SSE client and a plain POST.
+     */
+    dispatchSseMessage(raw: string | Record<string, unknown>, sessionId?: string): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+    /**
+     * Async generator of SSE frames for the legacy HTTP+SSE transport. Emits the
+     * `endpoint` event first (naming the POST target), then each queued JSON-RPC
+     * response as it arrives, with periodic keep-alive comments. Registers the
+     * per-session channel up front and tears it down (plus the session) when the
+     * client disconnects and the generator is closed.
+     */
+    sseStream(sessionId: string, endpointUrl: string, keepaliveMs?: number): AsyncGenerator<string>;
+    registerTool(name: string, handler: (args: Record<string, unknown>) => unknown, description?: string, schema?: JsonSchema): void;
+    registerResource(uri: string, handler: () => unknown, description?: string, mimeType?: string): void;
+    handleMessage(rawData: string | Record<string, unknown>): Promise<string>;
+    private _handleInitialize;
+    private _handleInitialized;
+    private _handlePing;
+    private _handleToolsList;
+    private _handleToolsCall;
+    private _handleResourcesList;
+    private _handleResourcesRead;
+    /** Coerce a route handler's parsed body into what the dispatchers accept. */
+    private _normalizeBody;
+    /**
+     * Register HTTP routes for this MCP server on the Tina4 router. Mounts both
+     * supported transports on `path`:
+     *   POST {path}          — Streamable HTTP (current transport)
+     *   POST {path}/message  — legacy HTTP+SSE message sink (+ inline fallback)
+     *   GET  {path}/sse      — legacy HTTP+SSE stream (persistent)
+     *
+     * A Streamable HTTP client (Claude Code `--transport http`) POSTs to `{path}`
+     * and reads the JSON-RPC response inline, with an Mcp-Session-Id header on
+     * initialize. A legacy SSE client GETs `{path}/sse`, gets the endpoint event,
+     * and its responses stream back on that connection.
+     */
+    registerRoutes(router: {
+        post: (pattern: string, handler: (req: unknown, res: unknown) => unknown) => {
+            noAuth: () => unknown;
+        };
+        get: (pattern: string, handler: (req: unknown, res: unknown) => unknown) => {
+            noAuth: () => unknown;
+        };
+    }): void;
+    /**
+     * Write/update .claude/settings.json with this MCP server config.
+     */
+    writeClaudeConfig(port?: number): void;
+}
+/**
+ * The default `/__dev/mcp` MCP server with the built-in dev tools registered.
+ *
+ * This is the single shared instance backing BOTH the browser REST shim
+ * (`/__dev/api/mcp/tools` + `/__dev/api/mcp/call`) and the JSON-RPC + SSE
+ * endpoints (`/__dev/mcp[/message]` + `/__dev/mcp/sse`) that real MCP clients
+ * (Claude Code/Desktop) speak. Tools are registered exactly once (idempotent).
+ * Mirrors Python's default MCP server used by `get_api_handlers()`.
+ */
+export declare function getDefaultDevServer(): McpServer;
+/**
+ * Register a function as an MCP tool.
+ *
+ * Usage:
+ *   const greet = mcpTool("greet", "Say hello", server, [
+ *     { name: "name", type: "string" },
+ *   ])((args) => `Hello, ${args.name}!`);
+ *
+ * Returns the original function with _mcpToolName attached.
+ */
+export declare function mcpTool(name: string, description?: string, server?: McpServer, params?: McpToolParam[]): <T extends (args: Record<string, unknown>) => unknown>(fn: T) => T & {
+    _mcpToolName: string;
+};
+/**
+ * Register a function as an MCP resource.
+ *
+ * Usage:
+ *   const tables = mcpResource("app://tables", "Database tables", "application/json", server)(
+ *     () => ["users", "products"]
+ *   );
+ */
+export declare function mcpResource(uri: string, description?: string, mimeType?: string, server?: McpServer): <T extends () => unknown>(fn: T) => T & {
+    _mcpResourceUri: string;
+};
+/**
+ * Register all built-in dev tools on the given McpServer (the api_* reflection
+ * tools plus code_search, the fuzzy FTS grounding tool).
+ */
+export declare function registerDevTools(server: McpServer): void;
+/** Alias for registerDevTools — parity with PHP/Ruby/Python. */
+export declare const register: typeof registerDevTools;

package/types/core/src/messenger.d.ts

@@ -0,0 +1,191 @@
+import { DevMailbox } from "./devMailbox.js";
+export interface SendResult {
+    success: boolean;
+    message: string;
+    id?: string;
+}
+/**
+ * Raised when an IMAP read fails to connect, authenticate, or speak the
+ * protocol (a `NO`/`BAD` tagged response, a refused/reset socket, a TLS or
+ * DNS failure). Distinct from a SUCCESSFUL fetch that simply has no messages —
+ * that still returns an empty result ([] / 0 / {}), NOT an error.
+ *
+ * inbox()/read()/unread()/search()/folders() LOG and then RAISE this on a
+ * connection/protocol failure so a dead mailbox is never silently mistaken for
+ * an empty one. send() is unchanged — it keeps returning { success, error }.
+ */
+export declare class MessengerConnectionError extends Error {
+    constructor(message: string);
+}
+export interface EmailMessage {
+    id: string;
+    type: "inbox" | "outbox";
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to?: string;
+    subject: string;
+    body: string;
+    /** Plain-text alternative. Carried on the dev path too, so the captured message
+     *  is the message: a mailbox that shows you something other than what you wrote
+     *  is worse than no mailbox. */
+    text?: string;
+    html: boolean;
+    attachments: string[];
+    date: string;
+    read: boolean;
+}
+interface MessengerOptions {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    fromAddress?: string;
+    fromName?: string;
+    encryption?: string;
+    /** @deprecated Use encryption instead */
+    useTls?: boolean;
+    imapHost?: string;
+    imapPort?: number;
+    imapUser?: string;
+    imapPass?: string;
+    /** IMAP transport security: "tls" (default), "starttls", or "none". */
+    imapEncryption?: string;
+}
+export interface ImapMessage {
+    uid: string;
+    subject: string;
+    from: string;
+    to: string;
+    date: string;
+    snippet: string;
+    seen: boolean;
+}
+export interface ImapFullMessage {
+    uid: string;
+    subject: string;
+    from: string;
+    to: string;
+    cc: string;
+    date: string;
+    bodyText: string;
+    bodyHtml: string;
+    headers: Record<string, string>;
+}
+export declare class Messenger {
+    private host;
+    private port;
+    private username;
+    private password;
+    private fromAddress;
+    private fromName;
+    private encryption;
+    private useTls;
+    /** Whether an SMTP host was actually configured (see the constructor). */
+    private smtpConfigured;
+    /** The local mailbox, present only when this messenger captures. */
+    devMailbox: DevMailbox | null;
+    private imapHost;
+    private imapPort;
+    private imapUser;
+    private imapPass;
+    private imapEncryption;
+    constructor(options?: MessengerOptions);
+    /**
+     * Read-only IMAP encryption mode for inspection / tests.
+     * Returns one of "tls", "starttls", "none", "ssl".
+     */
+    getImapEncryption(): string;
+    /**
+     * Send an email via SMTP.
+     */
+    /**
+     * Should send() capture locally instead of talking to SMTP?
+     *
+     * Availability decides, not verbosity. With no SMTP host configured sending is
+     * impossible, so simulate it into a folder rather than failing -- that is what
+     * makes a laptop with no mail server usable. TINA4_MAIL_CAPTURE forces capture
+     * even when a host IS configured.
+     *
+     * TINA4_DEBUG deliberately does NOT gate this, and neither does NODE_ENV. Debug
+     * must still be able to send, and the old `NODE_ENV !== "production"` clause
+     * silently swallowed every staging email.
+     */
+    private shouldCapture;
+    /** The local mailbox, created on first capture and reused after. */
+    private getDevMailbox;
+    send(to: string | string[], subject: string, body: string, html?: boolean, text?: string, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
+    /**
+     * Test the SMTP connection without sending an email.
+     */
+    testConnection(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Connect to the IMAP server via raw TCP/TLS.
+     * Returns the socket and reads the greeting.
+     */
+    private imapConnect;
+    /**
+     * Disconnect from IMAP cleanly.
+     */
+    private imapDisconnect;
+    /**
+     * Fetch latest messages from a folder.
+     * Returns list of message summaries.
+     */
+    inbox(limit?: number, offset?: number, folder?: string): Promise<ImapMessage[]>;
+    /**
+     * Read a single message by sequence number or UID.
+     */
+    read(uid: string, folder?: string): Promise<ImapFullMessage>;
+    /**
+     * Search messages using IMAP search criteria.
+     */
+    search(folder?: string, subject?: string, sender?: string, since?: string, before?: string, unseenOnly?: boolean, limit?: number): Promise<ImapMessage[]>;
+    /**
+     * Delete a message by UID.
+     */
+    deleteMessage(uid: string, folder?: string): Promise<void>;
+    /**
+     * Mark a message as read.
+     */
+    markRead(uid: string, folder?: string): Promise<void>;
+    /**
+     * Count unseen messages in a folder.
+     */
+    unread(folder?: string): Promise<number>;
+    /**
+     * List available IMAP folders/mailboxes.
+     */
+    folders(): Promise<string[]>;
+    /**
+     * Test IMAP connectivity without reading.
+     */
+    testImapConnection(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Create a Messenger configured for the current environment.
+ *
+ * Returns ONE concrete type, always. It used to return `Messenger | DevMailbox`,
+ * and those two shared NO sending method -- DevMailbox has capture(), Messenger has
+ * send() -- so the documented call threw TypeError whenever the dev branch was
+ * taken. That is nodejs#41. Capture is now a branch inside Messenger.send(), so the
+ * object you get back has one send() with one signature either way.
+ *
+ * The gate is availability, not verbosity:
+ *   - no TINA4_MAIL_HOST -> capture (sending is impossible, so simulate it)
+ *   - TINA4_MAIL_CAPTURE truthy -> capture even with SMTP configured
+ *   - otherwise -> send, EVEN WITH TINA4_DEBUG ON
+ *
+ * TINA4_DEBUG no longer forces capture: debug must still be able to send real mail.
+ * The `NODE_ENV !== "production"` clause is also gone -- it captured even with SMTP
+ * configured and debug off, which silently ate every staging email.
+ */
+export declare function createMessenger(): Messenger;
+export {};

package/types/core/src/metrics.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Two-tier analysis:
+ *   1. Quick metrics (instant): LOC, file counts, class/function counts
+ *   2. Full analysis (on-demand, cached): cyclomatic complexity, maintainability
+ *      index, coupling, Halstead metrics, violations
+ *
+ * Zero dependencies — uses only Node.js built-in modules.
+ */
+interface FunctionInfo {
+    name: string;
+    line: number;
+    complexity: number;
+    loc: number;
+    args: string[];
+    file?: string;
+}
+/**
+ * Stop a function being charged for the complexity of the functions nested
+ * inside it.
+ *
+ * Each function's raw score is measured over its whole span, so a branch inside
+ * a nested function landed on BOTH that function and every function enclosing
+ * it. The over-count compounded with depth: an IIFE wrapper or a registrar
+ * defining twenty inner handlers absorbed the entire file's complexity and
+ * topped the offenders list, hiding the genuine hot spots.
+ *
+ * The correction is exact. A raw score is 1 + every decision in the span, so
+ * (raw - 1) is the total decision count of a function's whole subtree.
+ * Subtracting that for each DIRECT child leaves the function's own branches:
+ *
+ *     own(F) = raw(F) - sum over direct children C of (raw(C) - 1)
+ *
+ * Anything the extractor does NOT list is deliberately unaffected: nothing
+ * subtracts it, so its decisions stay with the function that contains it -
+ * moved, never lost.
+ */
+export declare function chargeNestedComplexityToTheNestedFunction(functions: FunctionInfo[]): FunctionInfo[];
+export declare function quickMetrics(root?: string): Record<string, any>;
+export declare function fullAnalysis(root?: string): Record<string, any>;
+/** Severity ranking for sorting (higher = more severe). */
+export declare const SEVERITY_RANK: Record<string, number>;
+export interface Offender {
+    file: string;
+    line: number;
+    kind: string;
+    severity: "error" | "warn" | "info";
+    score: number;
+    detail: string;
+}
+export interface OffendersResult {
+    offenders: Offender[];
+    summary: Record<string, any>;
+}
+/**
+ * Rank the worst code-quality issues into a single "top offenders" list.
+ *
+ * Reuses {@link fullAnalysis} (does NOT re-analyze — the result is mtime-cached).
+ * Each offender is `{ file, line, kind, severity, score, detail }`.
+ *
+ * Rules (one offender per matching condition — SAME scoring as the master):
+ *   - function complexity > 10  → kind "complexity"
+ *         severity "error" if > 20 else "warn"; score = complexity
+ *   - file loc > 500            → kind "large_file" (warn); score = loc / 100
+ *   - file functions > 20       → kind "too_many_functions" (warn); score = functions / 4
+ *   - file maintainability < 40 → kind "low_maintainability"
+ *         severity "error" if < 20 else "warn"; score = 50 - mi
+ *   - file has_tests === false  → kind "untested" (info); score = loc / 100
+ *
+ * Sorted by (severity rank, score) DESCENDING and truncated to `top`.
+ *
+ * Returns `{ offenders, summary }` where summary carries the headline numbers
+ * the CLI prints (files_analyzed, total_functions, avg_complexity,
+ * avg_maintainability, scan_mode, scan_root, total_offenders).
+ */
+export declare function offenders(root?: string, top?: number): OffendersResult;
+export declare function fileDetail(filePath: string): Record<string, any>;
+export {};