tina4-nodejs 3.0.0-rc.2

package/packages/core/src/devMailbox.ts

@@ -0,0 +1,316 @@
+/**
+ * Tina4 DevMailbox — File-backed development mailbox, zero dependencies.
+ *
+ * Captures emails to the filesystem instead of sending them via SMTP.
+ * Perfect for local development — no email server needed.
+ *
+ *   import { DevMailbox, createMessenger } from "@tina4/core";
+ *
+ *   const mailbox = new DevMailbox();
+ *   mailbox.capture({ to: "alice@test.com", subject: "Hello", body: "Hi!" });
+ *   const messages = mailbox.inbox();
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import type { SendResult, EmailMessage } from "./messenger.js";
+import { Messenger } from "./messenger.js";
+import { isTruthy } from "./dotenv.js";
+
+// ── DevMailbox ───────────────────────────────────────────────
+
+export class DevMailbox {
+  private mailboxDir: string;
+
+  constructor(mailboxDir?: string) {
+    this.mailboxDir = mailboxDir ?? process.env.TINA4_MAILBOX_DIR ?? "data/mailbox";
+  }
+
+  /**
+   * Ensure a folder directory exists.
+   */
+  private ensureFolder(folder: string): string {
+    const dir = join(this.mailboxDir, folder);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  /**
+   * Capture an email to the dev mailbox instead of sending it.
+   */
+  capture(options: {
+    to: string | string[];
+    subject: string;
+    body: string;
+    html?: boolean;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+    attachments?: string[];
+    from?: string;
+  }): SendResult {
+    const id = randomUUID();
+    const toList = Array.isArray(options.to) ? options.to : [options.to];
+    const now = new Date().toISOString();
+
+    const message: EmailMessage = {
+      id,
+      type: "outbox",
+      from: options.from ?? process.env.SMTP_FROM ?? "dev@localhost",
+      to: toList,
+      cc: options.cc ?? [],
+      bcc: options.bcc ?? [],
+      reply_to: options.replyTo,
+      subject: options.subject,
+      body: options.body,
+      html: options.html ?? false,
+      attachments: options.attachments ?? [],
+      date: now,
+      read: false,
+    };
+
+    // Save to outbox
+    const outboxDir = this.ensureFolder("outbox");
+    writeFileSync(join(outboxDir, `${id}.json`), JSON.stringify(message, null, 2));
+
+    // Also save a copy to each recipient's inbox
+    const inboxDir = this.ensureFolder("inbox");
+    const inboxMessage: EmailMessage = { ...message, type: "inbox" };
+    writeFileSync(join(inboxDir, `${id}.json`), JSON.stringify(inboxMessage, null, 2));
+
+    return { success: true, message: "Email captured to dev mailbox", id };
+  }
+
+  /**
+   * List messages from a folder (default: inbox).
+   */
+  inbox(limit: number = 50, offset: number = 0, folder: string = "inbox"): EmailMessage[] {
+    const dir = this.ensureFolder(folder);
+    const results: EmailMessage[] = [];
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter((f) => f.endsWith(".json")).sort().reverse();
+    } catch {
+      return [];
+    }
+
+    const sliced = files.slice(offset, offset + limit);
+
+    for (const file of sliced) {
+      try {
+        const msg: EmailMessage = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+        results.push(msg);
+      } catch {
+        // skip corrupt files
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Read a single message by ID. Searches all folders.
+   */
+  read(msgId: string): EmailMessage | null {
+    const folders = ["inbox", "outbox"];
+
+    for (const folder of folders) {
+      const filePath = join(this.mailboxDir, folder, `${msgId}.json`);
+      if (existsSync(filePath)) {
+        try {
+          const msg: EmailMessage = JSON.parse(readFileSync(filePath, "utf-8"));
+          // Mark as read
+          msg.read = true;
+          writeFileSync(filePath, JSON.stringify(msg, null, 2));
+          return msg;
+        } catch {
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Count unread messages in the inbox.
+   */
+  unreadCount(): number {
+    const dir = this.ensureFolder("inbox");
+    let count = 0;
+
+    try {
+      const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+      for (const file of files) {
+        try {
+          const msg: EmailMessage = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+          if (!msg.read) count++;
+        } catch {
+          // skip corrupt files
+        }
+      }
+    } catch {
+      // directory might not exist
+    }
+
+    return count;
+  }
+
+  /**
+   * Delete a message by ID. Removes from all folders.
+   */
+  delete(msgId: string): boolean {
+    let deleted = false;
+    const folders = ["inbox", "outbox"];
+
+    for (const folder of folders) {
+      const filePath = join(this.mailboxDir, folder, `${msgId}.json`);
+      if (existsSync(filePath)) {
+        try {
+          unlinkSync(filePath);
+          deleted = true;
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Clear all messages from a folder, or all folders if none specified.
+   */
+  clear(folder?: string): void {
+    const folders = folder ? [folder] : ["inbox", "outbox"];
+
+    for (const f of folders) {
+      const dir = join(this.mailboxDir, f);
+      try {
+        if (existsSync(dir)) {
+          const files = readdirSync(dir).filter((file) => file.endsWith(".json"));
+          for (const file of files) {
+            unlinkSync(join(dir, file));
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * Seed the mailbox with sample messages for development.
+   */
+  seed(count: number = 5): void {
+    const subjects = [
+      "Welcome to Tina4",
+      "Your account has been created",
+      "Weekly digest",
+      "Action required: Verify your email",
+      "New feature announcement",
+      "Security alert: New login detected",
+      "Invoice #1234",
+      "Meeting reminder",
+      "Password reset request",
+      "Feedback requested",
+    ];
+
+    const senders = [
+      "noreply@tina4.com",
+      "admin@example.com",
+      "support@company.com",
+      "billing@service.io",
+      "alerts@monitoring.dev",
+    ];
+
+    for (let i = 0; i < count; i++) {
+      const subject = subjects[i % subjects.length];
+      const from = senders[i % senders.length];
+      const date = new Date(Date.now() - i * 3600000).toISOString();
+      const id = randomUUID();
+
+      const message: EmailMessage = {
+        id,
+        type: "inbox",
+        from,
+        to: ["dev@localhost"],
+        cc: [],
+        bcc: [],
+        subject,
+        body: `This is sample email #${i + 1}.\n\nGenerated by DevMailbox.seed() for development purposes.`,
+        html: false,
+        attachments: [],
+        date,
+        read: i > 1, // first two are unread
+      };
+
+      const dir = this.ensureFolder("inbox");
+      writeFileSync(join(dir, `${id}.json`), JSON.stringify(message, null, 2));
+    }
+  }
+
+  /**
+   * Count messages in a folder, or all folders if none specified.
+   */
+  count(folder?: string): { inbox: number; outbox: number; total: number } {
+    const countDir = (f: string): number => {
+      const dir = join(this.mailboxDir, f);
+      try {
+        if (existsSync(dir)) {
+          return readdirSync(dir).filter((file) => file.endsWith(".json")).length;
+        }
+      } catch {
+        // ignore
+      }
+      return 0;
+    };
+
+    if (folder) {
+      const c = countDir(folder);
+      return { inbox: folder === "inbox" ? c : 0, outbox: folder === "outbox" ? c : 0, total: c };
+    }
+
+    const inbox = countDir("inbox");
+    const outbox = countDir("outbox");
+    return { inbox, outbox, total: inbox + outbox };
+  }
+}
+
+// ── Factory ──────────────────────────────────────────────────
+
+/**
+ * Create a Messenger or DevMailbox based on the environment.
+ *
+ * Returns DevMailbox when:
+ *   - TINA4_DEBUG is "true", OR
+ *   - No SMTP_HOST is configured
+ *
+ * Returns a real Messenger otherwise (SMTP configured + not debug mode).
+ *
+ * This follows the factory pattern from PHP's MessengerFactory.
+ */
+export function createMessenger(): Messenger | DevMailbox {
+  const debug = process.env.TINA4_DEBUG;
+  const smtpHost = process.env.SMTP_HOST;
+
+  // Force dev mode when TINA4_DEBUG is truthy
+  if (isTruthy(debug)) {
+    return new DevMailbox();
+  }
+
+  // No SMTP configured — must use dev mailbox
+  if (!smtpHost) {
+    return new DevMailbox();
+  }
+
+  // Non-production environment — use dev mailbox
+  if (!isProd) {
+    return new DevMailbox();
+  }
+
+  // Production with SMTP configured — use real Messenger
+  return new Messenger();
+}

package/packages/core/src/dotenv.ts

@@ -0,0 +1,172 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Parse a .env file content string into key-value pairs.
+ * Supports:
+ *   - KEY=value
+ *   - KEY="double quoted"
+ *   - KEY='single quoted'
+ *   - export KEY=value
+ *   - # comments
+ *   - Empty lines
+ *   - Multi-line with trailing backslash \
+ */
+function parseEnvContent(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = content.split("\n");
+  let i = 0;
+
+  while (i < lines.length) {
+    let line = lines[i].trim();
+    i++;
+
+    // Skip empty lines and comments
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+
+    // Strip "export " prefix
+    if (line.startsWith("export ")) {
+      line = line.slice(7).trim();
+    }
+
+    // Find the first = sign
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIndex).trim();
+    let value = line.slice(eqIndex + 1).trim();
+
+    // Handle quoted values
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+      // Process escape sequences in double-quoted values
+      value = value
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, "\\");
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      // Single-quoted: literal, no escape processing
+      value = value.slice(1, -1);
+    } else {
+      // Unquoted: handle multi-line with trailing backslash
+      while (value.endsWith("\\") && i < lines.length) {
+        value = value.slice(0, -1) + lines[i].trim();
+        i++;
+      }
+      // Strip inline comments (only for unquoted values)
+      const commentIndex = value.indexOf(" #");
+      if (commentIndex !== -1) {
+        value = value.slice(0, commentIndex).trim();
+      }
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Load environment variables from a .env file into process.env.
+ * Does not override existing process.env values unless they are undefined.
+ *
+ * @param path - Path to the .env file. Defaults to ".env" in the current working directory.
+ * @returns The parsed key-value pairs, or an empty object if the file doesn't exist.
+ */
+export function loadEnv(path?: string): Record<string, string> {
+  const envPath = resolve(path ?? ".env");
+
+  if (!existsSync(envPath)) {
+    return {};
+  }
+
+  const content = readFileSync(envPath, "utf-8");
+  const parsed = parseEnvContent(content);
+
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+      _loadedKeys.push(key);
+    }
+  }
+
+  return parsed;
+}
+
+/**
+ * Get an environment variable value with an optional default.
+ *
+ * @param key - The environment variable name.
+ * @param defaultValue - Value to return if the variable is not set.
+ * @returns The environment variable value, or the default.
+ */
+export function getEnv(key: string, defaultValue?: string): string | undefined {
+  return process.env[key] ?? defaultValue;
+}
+
+/**
+ * Get a required environment variable. Throws if not set.
+ *
+ * @param key - The environment variable name.
+ * @returns The environment variable value.
+ * @throws Error if the variable is not set.
+ */
+export function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (value === undefined) {
+    throw new Error(`Required environment variable "${key}" is not set.`);
+  }
+  return value;
+}
+
+/**
+ * Check if an environment variable exists (is defined in process.env).
+ *
+ * @param key - The environment variable name.
+ * @returns true if the variable is set, false otherwise.
+ */
+export function hasEnv(key: string): boolean {
+  return process.env[key] !== undefined;
+}
+
+/**
+ * Return all currently loaded environment variables.
+ *
+ * @returns A shallow copy of process.env as a record.
+ */
+export function allEnv(): Record<string, string | undefined> {
+  return { ...process.env };
+}
+
+/**
+ * Check if a value is truthy for env boolean checks.
+ *
+ * Accepts: "true", "True", "TRUE", "1", "yes", "Yes", "YES", "on", "On", "ON".
+ * Everything else is falsy (including empty string, undefined, not set).
+ *
+ * Mirrors Python's `is_truthy()` in `tina4_python.dotenv`.
+ */
+export function isTruthy(val: string | undefined | null): boolean {
+  if (val == null) return false;
+  return ["true", "1", "yes", "on"].includes(val.trim().toLowerCase());
+}
+
+/** Keys loaded by loadEnv, tracked for resetEnv(). */
+const _loadedKeys: string[] = [];
+
+/**
+ * Remove all environment variables that were loaded by loadEnv().
+ * Useful for testing. Only removes keys set by loadEnv(), not pre-existing system env vars.
+ */
+export function resetEnv(): void {
+  for (const key of _loadedKeys) {
+    delete process.env[key];
+  }
+  _loadedKeys.length = 0;
+}

package/packages/core/src/errorOverlay.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for errorOverlay module.
+ */
+
+import { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+function assertIncludes(html: string, needle: string, label: string): void {
+  assert(html.includes(needle), `${label}: expected HTML to include "${needle}"`);
+}
+
+function assertNotIncludes(html: string, needle: string, label: string): void {
+  assert(!html.includes(needle), `${label}: expected HTML NOT to include "${needle}"`);
+}
+
+function makeError(): Error {
+  try {
+    throw new TypeError("something broke");
+  } catch (e) {
+    return e as Error;
+  }
+}
+
+// ── renderErrorOverlay ──
+
+const err = makeError();
+const html = renderErrorOverlay(err);
+
+assert(typeof html === "string", "returns a string");
+assert(html.startsWith("<!DOCTYPE html>"), "starts with DOCTYPE");
+assertIncludes(html, "TypeError", "contains exception type");
+assertIncludes(html, "something broke", "contains exception message");
+assertIncludes(html, "errorOverlay.test", "contains file path");
+assertIncludes(html, "&#x25b6;", "contains error line marker");
+assertIncludes(html, "Stack Trace", "contains stack trace section");
+assertIncludes(html, "<details", "uses details element");
+assertIncludes(html, "open", "stack trace open by default");
+assertIncludes(html, "Environment", "contains environment section");
+assertIncludes(html, "Tina4 Node.js", "contains framework name");
+assertIncludes(html, "TINA4_DEBUG", "contains debug reference");
+
+// With request
+const htmlWithReq = renderErrorOverlay(err, {
+  method: "GET",
+  url: "/api/users",
+  headers: { host: "localhost" },
+});
+assertIncludes(htmlWithReq, "GET", "request method shown");
+assertIncludes(htmlWithReq, "/api/users", "request URL shown");
+assertIncludes(htmlWithReq, "localhost", "request header shown");
+assertIncludes(htmlWithReq, "Request Details", "request section present");
+
+// Without request
+assertNotIncludes(html, "Request Details", "no request section when no request");
+
+// XSS escaping
+const xssErr = new Error('<script>alert("xss")</script>');
+const xssHtml = renderErrorOverlay(xssErr);
+assertNotIncludes(xssHtml, "<script>", "escapes script tags");
+assertIncludes(xssHtml, "&lt;script&gt;", "HTML-encodes script tags");
+
+// ── renderProductionError ──
+
+const prodHtml = renderProductionError();
+assert(prodHtml.startsWith("<!DOCTYPE html>"), "production: starts with DOCTYPE");
+assertIncludes(prodHtml, "500", "production: contains 500");
+assertIncludes(prodHtml, "Internal Server Error", "production: default message");
+assertNotIncludes(prodHtml, "Stack Trace", "production: no stack trace");
+
+const prod404 = renderProductionError(404, "Not Found");
+assertIncludes(prod404, "404", "production 404: contains code");
+assertIncludes(prod404, "Not Found", "production 404: contains message");
+
+// ── isDebugMode ──
+
+const origDebug = process.env.TINA4_DEBUG;
+
+process.env.TINA4_DEBUG = "true";
+assert(isDebugMode() === true, "isDebugMode: true => true");
+
+process.env.TINA4_DEBUG = "false";
+assert(isDebugMode() === false, "isDebugMode: false => false");
+
+process.env.TINA4_DEBUG = "TRUE";
+assert(isDebugMode() === true, "isDebugMode: TRUE (uppercase) => true (case insensitive)");
+
+process.env.TINA4_DEBUG = "1";
+assert(isDebugMode() === true, "isDebugMode: 1 => true");
+
+process.env.TINA4_DEBUG = "yes";
+assert(isDebugMode() === true, "isDebugMode: yes => true");
+
+process.env.TINA4_DEBUG = "on";
+assert(isDebugMode() === true, "isDebugMode: on => true");
+
+process.env.TINA4_DEBUG = "0";
+assert(isDebugMode() === false, "isDebugMode: 0 => false");
+
+delete process.env.TINA4_DEBUG;
+assert(isDebugMode() === false, "isDebugMode: unset => false");
+
+// Restore
+if (origDebug !== undefined) {
+  process.env.TINA4_DEBUG = origDebug;
+}
+
+// ── Summary ──
+console.log(`\nerrorOverlay tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  process.exit(1);
+}