tina4-nodejs 3.13.133 → 3.13.134

package/packages/core/src/logger.ts

@@ -676,89 +676,58 @@ function isProduction(): boolean {
   return !isTruthy(process.env.TINA4_DEBUG);
 }
 
-/**
- * Resolve one fully-validated configuration snapshot from explicit options,
- * then environment, then default (ADR-0041) — WITHOUT touching the
- * filesystem. Every invalid setting throws LogConfigurationError before this
- * function returns, so a caller (configure() or the lazy first-use path)
- * commits nothing on a validation failure (LOG-C07, LOG-V01..V05).
- */
-function resolveSnapshot(options: ConfigureOptions): Omit<Snapshot, "mainSink" | "errorSink"> {
-  checkRemovedSettings();
-
-  const level = options.level !== undefined
-    ? parseLevel(options.level, "level")
-    : process.env.TINA4_LOG_LEVEL !== undefined
-      ? parseLevel(process.env.TINA4_LOG_LEVEL, "TINA4_LOG_LEVEL")
-      : DEFAULT_LEVEL;
-
-  const fileLevel = options.fileLevel !== undefined
-    ? parseLevel(options.fileLevel, "fileLevel")
-    : process.env.TINA4_LOG_FILE_LEVEL !== undefined
-      ? parseLevel(process.env.TINA4_LOG_FILE_LEVEL, "TINA4_LOG_FILE_LEVEL")
-      : DEFAULT_FILE_LEVEL;
-
-  // Format is DEBUG-DERIVED (Decision 3): explicit TINA4_LOG_FORMAT wins;
-  // otherwise truthy TINA4_DEBUG selects text, else json.
-  let format: "text" | "json";
-  const explicitFormat = options.format ?? process.env.TINA4_LOG_FORMAT;
-  if (explicitFormat !== undefined) {
-    const f = explicitFormat.trim().toLowerCase();
-    if (f !== "text" && f !== "json") {
-      throw new LogConfigurationError(`TINA4_LOG_FORMAT=${JSON.stringify(explicitFormat)} is not valid`, {
-        setting: "TINA4_LOG_FORMAT",
-        value: explicitFormat,
-        accepted: ["text", "json"],
-      });
-    }
-    format = f;
-  } else {
-    format = isTruthy(process.env.TINA4_DEBUG) ? "text" : "json";
-  }
+function resolveConfiguredLevel(
+  explicit: string | undefined,
+  envName: string,
+  explicitSetting: string,
+  fallback: LogLevel,
+): LogLevel {
+  const raw = explicit ?? process.env[envName];
+  return raw === undefined ? fallback : parseLevel(raw, explicit === undefined ? envName : explicitSetting);
+}
+
+function resolveFormat(explicit: string | undefined): "text" | "json" {
+  const raw = explicit ?? process.env.TINA4_LOG_FORMAT;
+  if (raw === undefined) return isTruthy(process.env.TINA4_DEBUG) ? "text" : "json";
+  const format = raw.trim().toLowerCase();
+  if (format === "text" || format === "json") return format;
+  throw new LogConfigurationError(`TINA4_LOG_FORMAT=${JSON.stringify(raw)} is not valid`, {
+    setting: "TINA4_LOG_FORMAT",
+    value: raw,
+    accepted: ["text", "json"],
+  });
+}
 
-  // Output: an explicit value (stdout/file/both) ALWAYS wins, full stop —
-  // naming a file (below) never itself enables the file sink (LOG-C08).
-  let outputSelector: "stdout" | "file" | "both";
-  const explicitOutput = options.output ?? process.env.TINA4_LOG_OUTPUT;
-  if (explicitOutput !== undefined) {
-    const o = explicitOutput.trim().toLowerCase();
-    if (o !== "stdout" && o !== "file" && o !== "both") {
-      throw new LogConfigurationError(`TINA4_LOG_OUTPUT=${JSON.stringify(explicitOutput)} is not valid`, {
-        setting: "TINA4_LOG_OUTPUT",
-        value: explicitOutput,
-        accepted: ["stdout", "file", "both"],
-      });
-    }
-    outputSelector = o;
-  } else {
-    // Unset: dev/prod-aware default — file only in development.
-    outputSelector = isProduction() ? "stdout" : "both";
-  }
-  const stdoutEnabled = outputSelector !== "file";
-  const fileEnabled = outputSelector !== "stdout";
+function resolveOutput(explicit: string | undefined): "stdout" | "file" | "both" {
+  const raw = explicit ?? process.env.TINA4_LOG_OUTPUT;
+  if (raw === undefined) return isProduction() ? "stdout" : "both";
+  const output = raw.trim().toLowerCase();
+  if (output === "stdout" || output === "file" || output === "both") return output;
+  throw new LogConfigurationError(`TINA4_LOG_OUTPUT=${JSON.stringify(raw)} is not valid`, {
+    setting: "TINA4_LOG_OUTPUT",
+    value: raw,
+    accepted: ["stdout", "file", "both"],
+  });
+}
 
-  const rotateSize = resolveInt(options.rotateSize, "TINA4_LOG_ROTATE_SIZE", DEFAULT_ROTATE_SIZE, MIN_ROTATE_SIZE);
-  const rotateKeep = resolveRotateKeep(options.rotateKeep, DEFAULT_ROTATE_KEEP);
-  const strict = resolveBool(options.strict, "TINA4_LOG_STRICT", false);
-  const callerCapture = resolveBool(options.caller, "TINA4_LOG_FUNC", false);
+interface ResolvedLogPaths {
+  logDir: string;
+  logFile: string | null;
+  layout: "directory" | "single";
+}
 
+function resolveLogPaths(options: ConfigureOptions): ResolvedLogPaths {
   const dirRaw = options.logDir ?? process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
   if (dirRaw === "") {
     throw new LogConfigurationError("logDir must not be empty", { setting: "TINA4_LOG_DIR", value: dirRaw });
   }
   const fileRaw = options.logFile ?? process.env.TINA4_LOG_FILE ?? "";
-  // A NUL byte can never be part of a real path (the underlying syscalls
-  // reject it), but that would otherwise only surface at OPEN time -- and
-  // only when the file sink ends up enabled. Reject it here, unconditionally,
-  // so a malformed path fails CONFIGURATION regardless of whether output
-  // happens to resolve to a sink that would ever touch the filesystem.
   if (dirRaw.includes("\0") || fileRaw.includes("\0")) {
     throw new LogConfigurationError("log path must not contain a NUL byte", {
       setting: dirRaw.includes("\0") ? "TINA4_LOG_DIR" : "TINA4_LOG_FILE",
     });
   }
 
-  const projectRoot = process.cwd();
   let dirCandidate = dirRaw;
   let fileCandidate = fileRaw;
   if (!fileCandidate && targetIsFile(dirCandidate)) {
@@ -766,17 +735,34 @@ function resolveSnapshot(options: ConfigureOptions): Omit<Snapshot, "mainSink" |
     dirCandidate = dirname(dirCandidate);
   }
 
-  const resolvedLogDir = (isAbsolute(dirCandidate) ? dirCandidate : join(projectRoot, dirCandidate)).replace(/\/$/, "");
+  const logDir = (isAbsolute(dirCandidate) ? dirCandidate : join(process.cwd(), dirCandidate)).replace(/\/$/, "");
+  if (!fileCandidate) return { logDir, logFile: null, layout: "directory" };
+  const logFile = isAbsolute(fileCandidate) ? fileCandidate : join(logDir, fileCandidate);
+  return { logDir, logFile, layout: "single" };
+}
 
-  let resolvedLogFile: string | null;
-  let layout: "directory" | "single";
-  if (fileCandidate) {
-    resolvedLogFile = isAbsolute(fileCandidate) ? fileCandidate : join(resolvedLogDir, fileCandidate);
-    layout = "single";
-  } else {
-    resolvedLogFile = null;
-    layout = "directory";
-  }
+/**
+ * Resolve one fully-validated configuration snapshot from explicit options,
+ * then environment, then default (ADR-0041) — WITHOUT touching the
+ * filesystem. Every invalid setting throws LogConfigurationError before this
+ * function returns, so a caller (configure() or the lazy first-use path)
+ * commits nothing on a validation failure (LOG-C07, LOG-V01..V05).
+ */
+function resolveSnapshot(options: ConfigureOptions): Omit<Snapshot, "mainSink" | "errorSink"> {
+  checkRemovedSettings();
+
+  const level = resolveConfiguredLevel(options.level, "TINA4_LOG_LEVEL", "level", DEFAULT_LEVEL);
+  const fileLevel = resolveConfiguredLevel(options.fileLevel, "TINA4_LOG_FILE_LEVEL", "fileLevel", DEFAULT_FILE_LEVEL);
+  const format = resolveFormat(options.format);
+  const outputSelector = resolveOutput(options.output);
+  const stdoutEnabled = outputSelector !== "file";
+  const fileEnabled = outputSelector !== "stdout";
+
+  const rotateSize = resolveInt(options.rotateSize, "TINA4_LOG_ROTATE_SIZE", DEFAULT_ROTATE_SIZE, MIN_ROTATE_SIZE);
+  const rotateKeep = resolveRotateKeep(options.rotateKeep, DEFAULT_ROTATE_KEEP);
+  const strict = resolveBool(options.strict, "TINA4_LOG_STRICT", false);
+  const callerCapture = resolveBool(options.caller, "TINA4_LOG_FUNC", false);
+  const paths = resolveLogPaths(options);
 
   return {
     level,
@@ -785,9 +771,9 @@ function resolveSnapshot(options: ConfigureOptions): Omit<Snapshot, "mainSink" |
     stdoutEnabled,
     fileEnabled,
     outputSelector,
-    logDir: resolvedLogDir,
-    logFile: resolvedLogFile,
-    layout,
+    logDir: paths.logDir,
+    logFile: paths.logFile,
+    layout: paths.layout,
     rotateSize,
     rotateKeep,
     strict,

package/packages/core/src/mcp.ts

@@ -989,77 +989,49 @@ function agentBackup(projectRoot: string, target: string): string | null {
  * - Uses spawnSync with 5-second timeout so a hung subprocess never
  *   blocks the MCP server.
  */
-function verifyNodeSyntax(absPath: string, relPath: string): string | null {
-  if (!relPath.startsWith("src/")) {
-    return null;
-  }
+function syntaxCheckTarget(relPath: string): { ext: string } | null {
+  if (!relPath.startsWith("src/")) return null;
   const ext = path.extname(relPath).toLowerCase();
-  if (![".js", ".ts", ".mjs", ".cjs"].includes(ext)) {
-    return null;
-  }
-  const base = path.basename(relPath);
-  if (/\.(test|spec)\.(ts|js|mjs|cjs)$/.test(base)) {
-    return null;
-  }
+  if (![".js", ".ts", ".mjs", ".cjs"].includes(ext)) return null;
+  if (/\.(test|spec)\.(ts|js|mjs|cjs)$/.test(path.basename(relPath))) return null;
+  return { ext };
+}
 
-  let cmd: string;
-  let args: string[];
-  if (ext === ".ts") {
-    cmd = "npx";
-    args = ["--no-install", "tsc", "--noEmit", "--allowJs", "--skipLibCheck", absPath];
-  } else {
-    cmd = "node";
-    args = ["--check", absPath];
-  }
+function syntaxCheckCommand(absPath: string, ext: string): { cmd: string; args: string[] } {
+  return ext === ".ts"
+    ? { cmd: "npx", args: ["--no-install", "tsc", "--noEmit", "--allowJs", "--skipLibCheck", absPath] }
+    : { cmd: "node", args: ["--check", absPath] };
+}
 
-  let proc;
+function syntaxCheckOutput(absPath: string, relPath: string, ext: string, proc: any): string | null {
+  if (ext === ".ts" && (proc.error || proc.status === null || proc.status === 127)) return null;
+  if (proc.error) return `verification subprocess failed: ${proc.error.message}`;
+  if (proc.status === 0) return null;
+  const raw = (ext === ".ts"
+    ? (proc.stdout || "") + (proc.stderr || "")
+    : (proc.stderr || "") + (proc.stdout || "")).trim();
+  if (ext === ".ts" && raw.includes("This is not the tsc command")) return null;
+  if (!raw) return `syntax check failed (exit ${proc.status}, no output)`;
+  const lines = raw.split(/\r?\n/).map((line: string) => line.trim()).filter(Boolean);
+  if (lines.length === 0) return `syntax check failed (exit ${proc.status})`;
+  const stripPath = (line: string): string => line.replace(absPath, relPath);
+  return stripPath(lines.find((line: string) => /error|SyntaxError|TS\d+/i.test(line)) || lines[0]);
+}
+
+function verifyNodeSyntax(absPath: string, relPath: string): string | null {
+  const target = syntaxCheckTarget(relPath);
+  if (!target) return null;
+  const { cmd, args } = syntaxCheckCommand(absPath, target.ext);
   try {
-    proc = spawnSync(cmd, args, {
+    const proc = spawnSync(cmd, args, {
       encoding: "utf-8",
       timeout: 5000,
       cwd: path.dirname(path.dirname(absPath)),
     });
+    return syntaxCheckOutput(absPath, relPath, target.ext, proc);
   } catch (e) {
     return `verification subprocess failed: ${(e as Error).message}`;
   }
-
-  // npx may fail to find tsc — gracefully return null instead of blocking.
-  if (ext === ".ts" && (proc.error || proc.status === null || proc.status === 127)) {
-    return null;
-  }
-  if (proc.error) {
-    return `verification subprocess failed: ${proc.error.message}`;
-  }
-  if (proc.status === 0) {
-    return null;
-  }
-
-  // Errors land on stderr for `node --check`, stdout for tsc.
-  const raw = (ext === ".ts" ? (proc.stdout || "") + (proc.stderr || "") : (proc.stderr || "") + (proc.stdout || "")).trim();
-  // npx placeholder when tsc isn't installed locally — bail silently
-  // rather than block the write with a meaningless banner.
-  if (ext === ".ts" && raw.includes("This is not the tsc command")) {
-    return null;
-  }
-  if (!raw) {
-    return `syntax check failed (exit ${proc.status}, no output)`;
-  }
-  const lines = raw.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  if (lines.length === 0) {
-    return `syntax check failed (exit ${proc.status})`;
-  }
-  // Strip the absolute path prefix from the first meaningful line so the
-  // LLM sees a stable, project-relative error message.
-  const stripPath = (line: string): string => line.replace(absPath, relPath);
-  // For tsc: the first line is usually "src/foo.ts(3,5): error TS1109: ...".
-  // For node --check: the first line is the file path; the actual error is
-  // a later "SyntaxError: ..." line. Pick the most informative line.
-  for (const line of lines) {
-    if (/error|SyntaxError|TS\d+/i.test(line)) {
-      return stripPath(line);
-    }
-  }
-  return stripPath(lines[0]);
 }
 
 /** Latest resolved KV cache stats snapshot (the async API resolves into this). */

package/packages/core/src/messenger.ts

@@ -177,6 +177,22 @@ interface SendOptions {
   headers?: Record<string, string>;
 }
 
+type SmtpSocket = net.Socket | tls.TLSSocket;
+
+interface MailRecipients {
+  toList: string[];
+  ccList: string[];
+  bccList: string[];
+  allRecipients: string[];
+}
+
+class SmtpCommandError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SmtpCommandError";
+  }
+}
+
 // ── SMTP helpers ─────────────────────────────────────────────
 
 /**
@@ -474,41 +490,12 @@ export class Messenger {
     return this.devMailbox;
   }
 
-  async send(
-    to: string | string[],
-    subject: string,
-    body: string,
-    html: boolean = false,
-    text?: string,
-    cc?: string | string[],
-    bcc?: string | string[],
-    replyTo?: string,
-    attachments?: string[],
-    headers?: Record<string, string>,
-  ): Promise<SendResult> {
-    const options: SendOptions = { to, subject, body, html, text, cc, bcc, replyTo, attachments, headers };
+  private prepareRecipients(options: SendOptions, redirect = false): MailRecipients {
     let toList = Array.isArray(options.to) ? options.to : [options.to];
     let ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
     let bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
     let allRecipients = [...toList, ...ccList, ...bccList];
-
-    // Dev capture is a BRANCH here, not a different object returned by the factory.
-    // createMessenger() used to hand back a DevMailbox, which has capture() and no
-    // send(), so the documented call threw TypeError (nodejs#41).
-    if (this.shouldCapture()) {
-      return this.getDevMailbox().capture(
-        to, subject, body, html, text, ccList, bccList, replyTo,
-        attachments, this.fromAddress || undefined,
-      );
-    }
-
-    // TINA4_MAIL_REDIRECT_TO (MAIL-DEC-01): on the REAL-SEND path only — capture
-    // already returned above, so this never touches the capture branch. When the
-    // list is non-empty, replace every recipient with the redirect list (so ONLY
-    // the dev list receives the mail, never the real recipients) and preserve the
-    // original recipients in X-Tina4-Original-To. Subject/body/attachments are
-    // untouched, and send()'s return shape is unchanged.
-    const redirectTo = parseMailRedirectList(process.env.TINA4_MAIL_REDIRECT_TO);
+    const redirectTo = redirect ? parseMailRedirectList(process.env.TINA4_MAIL_REDIRECT_TO) : [];
     if (redirectTo.length > 0) {
       const originalTo = allRecipients.join(", ");
       toList = redirectTo;
@@ -517,154 +504,146 @@ export class Messenger {
       allRecipients = [...toList];
       options.headers = { ...(options.headers ?? {}), "X-Tina4-Original-To": originalTo };
     }
+    return { toList, ccList, bccList, allRecipients };
+  }
 
-    const messageId = `${randomUUID()}@${this.host}`;
-
-    if (allRecipients.length === 0) {
-      return { success: false, message: "No recipients specified", id: null };
+  private async connectSmtpSocket(): Promise<SmtpSocket> {
+    if (this.port === 465) {
+      const socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
+      await new Promise<void>((resolve, reject) => {
+        socket.once("secureConnect", resolve);
+        socket.once("error", reject);
+      });
+      return socket;
     }
+    const socket = net.createConnection({ host: this.host, port: this.port });
+    await new Promise<void>((resolve, reject) => {
+      socket.once("connect", resolve);
+      socket.once("error", reject);
+    });
+    return socket;
+  }
 
-    if (!this.fromAddress) {
-      return { success: false, message: "No from address configured", id: null };
-    }
+  private async requireSmtpResponse(socket: SmtpSocket, command: string, expected: number, failure: string): Promise<{ code: number; text: string }> {
+    const response = command === "" ? await readResponse(socket) : await sendCommand(socket, command);
+    if (response.code !== expected) throw new SmtpCommandError(`${failure}: ${response.text}`);
+    return response;
+  }
 
+  private async openSmtpSession(): Promise<SmtpSocket> {
+    let socket = await this.connectSmtpSocket();
     try {
-      // Connect
-      let socket: net.Socket | tls.TLSSocket;
-
-      if (this.port === 465) {
-        // Implicit TLS (SMTPS)
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
-        await new Promise<void>((resolve, reject) => {
-          socket.once("secureConnect", resolve);
-          socket.once("error", reject);
-        });
-      } else {
-        socket = net.createConnection({ host: this.host, port: this.port });
-        await new Promise<void>((resolve, reject) => {
-          socket.once("connect", resolve);
-          socket.once("error", reject);
-        });
-      }
-
-      // Read greeting
-      const greeting = await readResponse(socket);
-      if (greeting.code !== 220) {
-        socket.destroy();
-        return { success: false, message: `SMTP greeting failed: ${greeting.text}`, id: null };
-      }
-
-      // EHLO
-      const ehlo = await sendCommand(socket, `EHLO ${this.host}`);
-      if (ehlo.code !== 250) {
-        socket.destroy();
-        return { success: false, message: `EHLO failed: ${ehlo.text}`, id: null };
-      }
-
-      // STARTTLS upgrade (for port 587 or when useTls is true and not already TLS)
+      await this.requireSmtpResponse(socket, "", 220, "SMTP greeting failed");
+      const ehlo = await this.requireSmtpResponse(socket, `EHLO ${this.host}`, 250, "EHLO failed");
       if (this.useTls && this.port !== 465 && ehlo.text.includes("STARTTLS")) {
-        const starttls = await sendCommand(socket, "STARTTLS");
-        if (starttls.code !== 220) {
-          socket.destroy();
-          return { success: false, message: `STARTTLS failed: ${starttls.text}`, id: null };
-        }
-
-        // Upgrade to TLS
+        await this.requireSmtpResponse(socket, "STARTTLS", 220, "STARTTLS failed");
         const plainSocket = socket as net.Socket;
-        socket = tls.connect(
-          { socket: plainSocket, host: this.host, rejectUnauthorized: tlsRejectUnauthorized() },
-        );
+        const secureSocket = tls.connect({ socket: plainSocket, host: this.host, rejectUnauthorized: tlsRejectUnauthorized() });
         await new Promise<void>((resolve, reject) => {
-          (socket as tls.TLSSocket).once("secureConnect", resolve);
-          (socket as tls.TLSSocket).once("error", reject);
+          secureSocket.once("secureConnect", resolve);
+          secureSocket.once("error", reject);
         });
-
-        // Re-EHLO after TLS upgrade
-        const ehlo2 = await sendCommand(socket, `EHLO ${this.host}`);
-        if (ehlo2.code !== 250) {
-          socket.destroy();
-          return { success: false, message: `EHLO after STARTTLS failed: ${ehlo2.text}`, id: null };
-        }
-      }
-
-      // AUTH LOGIN
-      if (this.username && this.password) {
-        const auth = await sendCommand(socket, "AUTH LOGIN");
-        if (auth.code !== 334) {
-          socket.destroy();
-          return { success: false, message: `AUTH LOGIN failed: ${auth.text}`, id: null };
-        }
-
-        const userResp = await sendCommand(socket, Buffer.from(this.username).toString("base64"));
-        if (userResp.code !== 334) {
-          socket.destroy();
-          return { success: false, message: `AUTH username failed: ${userResp.text}`, id: null };
-        }
-
-        const passResp = await sendCommand(socket, Buffer.from(this.password).toString("base64"));
-        if (passResp.code !== 235) {
-          socket.destroy();
-          return { success: false, message: `AUTH password failed: ${passResp.text}`, id: null };
-        }
-      }
-
-      // MAIL FROM
-      const mailFrom = await sendCommand(socket, `MAIL FROM:<${this.fromAddress}>`);
-      if (mailFrom.code !== 250) {
-        socket.destroy();
-        return { success: false, message: `MAIL FROM failed: ${mailFrom.text}`, id: null };
-      }
-
-      // RCPT TO for all recipients
-      for (const recipient of allRecipients) {
-        const rcpt = await sendCommand(socket, `RCPT TO:<${recipient}>`);
-        if (rcpt.code !== 250 && rcpt.code !== 251) {
-          socket.destroy();
-          return { success: false, message: `RCPT TO <${recipient}> failed: ${rcpt.text}`, id: null };
-        }
+        socket = secureSocket;
+        await this.requireSmtpResponse(socket, `EHLO ${this.host}`, 250, "EHLO after STARTTLS failed");
       }
+      return socket;
+    } catch (error) {
+      socket.destroy();
+      throw error;
+    }
+  }
 
-      // DATA
-      const dataCmd = await sendCommand(socket, "DATA");
-      if (dataCmd.code !== 354) {
-        socket.destroy();
-        return { success: false, message: `DATA failed: ${dataCmd.text}`, id: null };
-      }
+  private async authenticateSmtp(socket: SmtpSocket): Promise<void> {
+    if (!this.username || !this.password) return;
+    await this.requireSmtpResponse(socket, "AUTH LOGIN", 334, "AUTH LOGIN failed");
+    await this.requireSmtpResponse(socket, Buffer.from(this.username).toString("base64"), 334, "AUTH username failed");
+    await this.requireSmtpResponse(socket, Buffer.from(this.password).toString("base64"), 235, "AUTH password failed");
+  }
 
-      // Build and send the MIME message
-      const mimeMessage = buildMimeMessage({
-        from: this.fromAddress,
-        fromName: this.fromName,
-        to: toList,
-        cc: ccList,
-        subject: options.subject,
-        body: options.body,
-        html: options.html ?? false,
-        text: options.text,
-        replyTo: options.replyTo,
-        attachments: options.attachments,
-        headers: options.headers,
-        messageId,
-      });
+  private async sendSmtpEnvelope(socket: SmtpSocket, recipients: string[]): Promise<void> {
+    await this.requireSmtpResponse(socket, `MAIL FROM:<${this.fromAddress}>`, 250, "MAIL FROM failed");
+    for (const recipient of recipients) {
+      const response = await sendCommand(socket, `RCPT TO:<${recipient}>`);
+      if (response.code !== 250 && response.code !== 251) throw new SmtpCommandError(`RCPT TO <${recipient}> failed: ${response.text}`);
+    }
+  }
 
-      // Send message body, terminate with <CRLF>.<CRLF>
-      const endData = await sendCommand(socket, mimeMessage + "\r\n.");
-      if (endData.code !== 250) {
-        socket.destroy();
-        return { success: false, message: `Message delivery failed: ${endData.text}`, id: null };
-      }
+  private async sendSmtpMessage(socket: SmtpSocket, options: SendOptions, recipients: MailRecipients, messageId: string): Promise<void> {
+    await this.requireSmtpResponse(socket, "DATA", 354, "DATA failed");
+    const mimeMessage = buildMimeMessage({
+      from: this.fromAddress,
+      fromName: this.fromName,
+      to: recipients.toList,
+      cc: recipients.ccList,
+      subject: options.subject,
+      body: options.body,
+      html: options.html ?? false,
+      text: options.text,
+      replyTo: options.replyTo,
+      attachments: options.attachments,
+      headers: options.headers,
+      messageId,
+    });
+    await this.requireSmtpResponse(socket, mimeMessage + "\r\n.", 250, "Message delivery failed");
+    await sendCommand(socket, "QUIT");
+  }
 
-      // QUIT
-      await sendCommand(socket, "QUIT");
+  private async sendSmtp(options: SendOptions, recipients: MailRecipients, messageId: string): Promise<SendResult> {
+    let socket: SmtpSocket | null = null;
+    try {
+      socket = await this.openSmtpSession();
+      await this.authenticateSmtp(socket);
+      await this.sendSmtpEnvelope(socket, recipients.allRecipients);
+      await this.sendSmtpMessage(socket, options, recipients, messageId);
       socket.destroy();
-
       return { success: true, message: "Email sent successfully", id: messageId };
     } catch (err) {
+      socket?.destroy();
+      if (err instanceof SmtpCommandError) return { success: false, message: err.message, id: null };
       const errMsg = err instanceof Error ? err.message : String(err);
       return { success: false, message: `SMTP error: ${errMsg}`, id: null };
     }
   }
 
+  async send(
+    to: string | string[],
+    subject: string,
+    body: string,
+    html: boolean = false,
+    text?: string,
+    cc?: string | string[],
+    bcc?: string | string[],
+    replyTo?: string,
+    attachments?: string[],
+    headers?: Record<string, string>,
+  ): Promise<SendResult> {
+    const options: SendOptions = { to, subject, body, html, text, cc, bcc, replyTo, attachments, headers };
+    const capturedRecipients = this.prepareRecipients(options);
+
+    // Dev capture is a BRANCH here, not a different object returned by the factory.
+    // createMessenger() used to hand back a DevMailbox, which has capture() and no
+    // send(), so the documented call threw TypeError (nodejs#41).
+    if (this.shouldCapture()) {
+      return this.getDevMailbox().capture(
+        to, subject, body, html, text, capturedRecipients.ccList, capturedRecipients.bccList, replyTo,
+        attachments, this.fromAddress || undefined,
+      );
+    }
+    const recipients = this.prepareRecipients(options, true);
+
+    const messageId = `${randomUUID()}@${this.host}`;
+
+    if (recipients.allRecipients.length === 0) {
+      return { success: false, message: "No recipients specified", id: null };
+    }
+
+    if (!this.fromAddress) {
+      return { success: false, message: "No from address configured", id: null };
+    }
+
+    return this.sendSmtp(options, recipients, messageId);
+  }
+
   /**
    * Render a Frond template STRING and send it as an HTML email (G7, parity with
    * Python's send_template). Extra send() options (cc, bcc, replyTo, attachments,