tina4-nodejs 3.13.92 → 3.13.95

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

@@ -0,0 +1,200 @@
+/**
+ * Structured logger for Tina4.
+ *
+ * FORMAT IS TEXT BY DEFAULT, and TINA4_LOG_FORMAT=json is the ONLY thing that
+ * selects JSON. Nothing else may. Until 3.13.95 an unset TINA4_DEBUG silently
+ * flipped BOTH sinks to JSON here, and "production" meant four different things
+ * across the four frameworks (Node: !TINA4_DEBUG; Ruby: TINA4_ENV/RACK_ENV/
+ * RUBY_ENV == "production"; Python: only configure(production=True); PHP: no
+ * switch at all, JSON always) — same machine, same .env, four log formats. That
+ * implicit switch is deleted; an object passed as the message is still
+ * JSON-encoded INLINE inside the text line, which is the only JSON a default
+ * install emits.
+ *
+ * TINA4_DEBUG still decides COLOUR — a terminal concern, not a format one — so
+ * a production pipe gets clean uncoloured bytes and a dev terminal stays
+ * readable.
+ *
+ * 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). stdout is ALWAYS on.
+ *
+ * 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") — the ONLY format switch
+ *   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")
+ *   TINA4_LOG_STRICT        — truthy: a log-write failure THROWS instead of being swallowed (default: off)
+ *
+ * Every one of these is read LAZILY, on each log() call — a script, worker, CLI
+ * tool or test that never boots a server still gets the operator's configuration.
+ *
+ * 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;
+    /**
+     * What configure() was explicitly told, held HERE rather than written back
+     * into process.env (ADR-0041).
+     *
+     * configure() used to assign to process.env.TINA4_LOG_DIR / _LOG_FILE. That
+     * reached the right answer -- the argument won -- through a mechanism no
+     * other framework has: it DESTROYED the operator's value for the rest of the
+     * process, and every child process spawned afterwards inherited the
+     * argument instead of what the operator set. Reading configuration must not
+     * write it. Keeping the explicit values in their own slot means resolution
+     * is explicit > env > default with the environment left intact and still
+     * readable.
+     */
+    private static explicitLogDir;
+    private static explicitLogFile;
+    /**
+     * 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 where logs are written.
+     *
+     * Logs land in a `logs/` folder by default. The argument OVERRIDES that, and
+     * it accepts a DIRECTORY or a FILE PATH:
+     *
+     *   configure()                              -> ./logs/tina4.log + ./logs/error.log
+     *   configure("/var/log/myapp")              -> /var/log/myapp/tina4.log + error.log
+     *   configure("/var/log/myapp/app.log")      -> that exact file (no error.log sibling)
+     *   configure({ logDir, logFile })           -> the explicit object form still works
+     *
+     * A plain string used to be accepted and silently ignored, because only the
+     * object form was read - so the call that works in the other three
+     * frameworks produced no log file here and said nothing (feature 2 of the
+     * audit, D4). Both forms now work.
+     */
+    static configure(options?: string | {
+        logDir?: string;
+        logFile?: string;
+    }): void;
+    /**
+     * Forget what configure() was told, so resolution falls back to the
+     * environment and then the built-in defaults. Parity with PHP's Log::reset().
+     *
+     * This exists because the explicit values are now HELD here rather than
+     * written back into process.env, and that makes them STICKY for the life of
+     * the process -- which is right for an application (configure() at boot is
+     * the operator's instruction and a later stray env write should not silently
+     * re-point the logs) and wrong for a long-lived test process that wants to
+     * drive the logger purely from the environment afterwards.
+     *
+     * I removed this method once for having no callers. That was correct about
+     * the grep and wrong about the code: the full suite is the caller. Before the
+     * explicit slots existed, configure() ASSIGNED to process.env, so a later
+     * direct assignment simply overwrote it and env-driven cases kept working by
+     * accident. test/logger.test.ts depends on exactly that -- it configures a
+     * file early, then runs the whole default-output block off the environment
+     * (see its own note: "these cases must NOT route through Log.configure").
+     * Three of those cases failed on the lab until this came back.
+     */
+    static reset(): void;
+    /**
+     * TINA4_LOG_APPEND — append (default) or overwrite on startup.
+     *
+     * APPEND IS THE DEFAULT: a log you can lose by restarting the process is not
+     * a log. Set it false for one file per run (a short CLI, a test fixture, a
+     * container shipping logs elsewhere); the files are truncated once here at
+     * configure time, never per line.
+     */
+    private static applyAppendMode;
+    /** Log an informational message. */
+    static info(message: unknown, data?: unknown): void;
+    /** Log a debug message. */
+    static debug(message: unknown, data?: unknown): void;
+    /** Log a warning message. */
+    static warning(message: unknown, data?: unknown): void;
+    /** Backwards-compat alias for warning(). */
+    static warn(message: unknown, data?: unknown): void;
+    /** Log an error message. */
+    static error(message: unknown, 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: unknown, 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.
+     *
+     * A failure is swallowed by default — logging must never crash the app. With
+     * TINA4_LOG_STRICT truthy it is RE-THROWN instead: an app that believes it is
+     * writing an audit trail into a read-only directory, and is not, is worse off
+     * than one that dies at the first line. Same contract in all four frameworks.
+     */
+    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(folder?: string, limit?: number, offset?: number): Promise<ImapMessage[]>;
+    /**
+     * Read a single message by sequence number or UID.
+     */
+    read(uid: string, folder?: string): Promise<ImapFullMessage | null>;
+    /**
+     * 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,41 @@
+export declare function quickMetrics(root?: string): Record<string, any>;
+/**
+ * The native metrics engine could not produce a payload.
+ *
+ * Thrown instead of falling back to a second implementation.
+ */
+export declare class MetricsEngineError extends Error {
+    constructor(message: string);
+}
+export declare const SEVERITY_RANK: Record<string, number>;
+/**
+ * Return [directory to scan, scanMode] for any metrics producer.
+ *
+ * The engine is language-agnostic and cannot know which directory holds a
+ * framework package, so root resolution and the "framework" label stay here,
+ * shared by the census and the engine adapter so the two never disagree.
+ */
+export declare function resolveScanTarget(root?: string): [string, string];
+/** Absolute path to the tina4 CLI binary, or null when it is not installed. */
+export declare function enginePath(): string | null;
+/** Full code analysis from the native engine, shaped for the dashboard. */
+export declare function fullAnalysis(root?: string): Record<string, any>;
+export interface OffendersResult {
+    offenders: Record<string, any>[];
+    summary: Record<string, any>;
+}
+/**
+ * Top code-health offenders from the native engine.
+ *
+ * The engine ranks and severity-tags them, and its own --fail-on gate reads the
+ * same list, so the CLI and the dashboard can never disagree about what counts
+ * as an offender.
+ */
+export declare function offenders(root?: string, top?: number): OffendersResult;
+/**
+ * Per-file metrics from the native engine.
+ *
+ * The engine accepts a single file for --path, so one code path serves both the
+ * whole-tree scan and one file.
+ */
+export declare function fileDetail(filePath: string): Record<string, any>;