toiljs 0.0.92 → 0.0.94

package/src/compiler/config.ts

@@ -51,8 +51,13 @@ export interface ClientConfig {
     readonly outDir?: string;
     /** Public base path. Default `/`. */
     readonly base?: string;
-    /** Dev server port. Default `3000`. */
+    /** Port the dev server AND the self-host (`toiljs start`) listen on. Default `3000`.
+     *  Overridden by the `--port` CLI flag and the `PORT` env var (in that precedence). */
     readonly port?: number;
+    /** Bind host for the dev server AND the self-host. Default `127.0.0.1` (loopback only).
+     *  Set to `0.0.0.0` (or a specific interface) to accept LAN / public connections.
+     *  Overridden by the `--host` CLI flag and the `HOST` env var (in that precedence). */
+    readonly host?: string;
     /**
      * Optimize imported images at build time (resize/convert via `vite-imagetools` + sharp): an
      * import like `logo.png?w=400;800&format=webp&as=srcset` emits resized, compressed variants.
@@ -194,6 +199,8 @@ export interface ResolvedToilConfig {
     readonly outDir: string;
     readonly base: string;
     readonly port: number;
+    /** Bind host for the dev server + self-host (`toiljs start`). Default `127.0.0.1`. */
+    readonly host: string;
     /** Whether build-time image optimization (`vite-imagetools`) is enabled. */
     readonly images: boolean;
     /** Whether build-time font preloading is enabled. */
@@ -246,7 +253,7 @@ function resolveRuntimePath(): string {
 
 /** Finds and loads `toil.config.*` or `toiljs.config.*` from `root`, then resolves defaults. */
 export async function loadConfig(
-    opts: { root?: string; port?: number } = {},
+    opts: { root?: string; port?: number; host?: string } = {},
 ): Promise<ResolvedToilConfig> {
     const root = path.resolve(opts.root ?? process.cwd());
 
@@ -278,7 +285,12 @@ export async function loadConfig(
         toilDir: path.join(root, '.toil'),
         outDir: client.outDir ?? 'build/client',
         base: client.base ?? '/',
-        port: opts.port ?? client.port ?? 3000,
+        // Port + bind host for the dev server and the self-host, resolved with the
+        // precedence: CLI flag (opts) > env (PORT/HOST) > config (client.*) > default.
+        // `PORT`/`HOST` are the conventional PaaS env vars; a platform that injects
+        // `PORT` (Heroku, Render, Fly, containers) works with zero config.
+        port: opts.port ?? envPort() ?? client.port ?? 3000,
+        host: opts.host ?? envHost() ?? client.host ?? '127.0.0.1',
         images: client.images ?? true,
         fonts: client.fonts ?? true,
         viewTransitions: client.viewTransitions ?? false,
@@ -299,6 +311,21 @@ export async function loadConfig(
     };
 }
 
+/** The `PORT` env var as a positive integer, or `undefined` when unset/invalid
+ *  (so it falls through to the config value / default rather than binding to 0). */
+function envPort(): number | undefined {
+    const v = process.env.PORT;
+    if (v == null || v.trim() === '') return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+
+/** The `HOST` env var (trimmed), or `undefined` when unset/blank. */
+function envHost(): string | undefined {
+    const v = process.env.HOST;
+    return v != null && v.trim() !== '' ? v.trim() : undefined;
+}
+
 const DEV_NODE_MODES: readonly DevNodeMode[] = ['hot', 'regional', 'continental', 'daemon', 'all'];
 
 /** A `nodeMode` outside the enum falls back to `all` with a warning (fail-soft:

package/src/compiler/index.ts

@@ -845,6 +845,17 @@ async function collectDevCss(server: ViteDevServer): Promise<string> {
     return css;
 }
 
+/** The host to show in a clickable URL: a wildcard bind (`0.0.0.0`/`::`/empty) is
+ *  not universally openable, so present `localhost` for those; otherwise the host. */
+function displayHost(host: string): string {
+    return host === '0.0.0.0' || host === '::' || host === '' ? 'localhost' : host;
+}
+
+/** Whether the bind host exposes the server beyond loopback (worth flagging to the user). */
+function isExposedHost(host: string): boolean {
+    return host !== '127.0.0.1' && host !== 'localhost' && host !== '::1';
+}
+
 export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer> {
     const cfg = await loadConfig(opts);
     // Server first: build it (regenerating shared/server.ts) before the client dev server starts.
@@ -921,6 +932,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     const front = await startDevServer({
         root: cfg.root,
         port: cfg.port,
+        host: cfg.host,
         wasmFile: serverWasmFile(cfg.root),
         // The daemon (cold) emulator drives `release-cold.wasm` per `nodeMode`; absent for a
         // project with no `@daemon` (the cold artifact never gets built, so the host stays idle).
@@ -938,17 +950,21 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     server.httpServer?.once('close', () => {
         void front.close();
     });
+    const shownHost = displayHost(front.host);
     process.stdout.write(
         '\n  ' +
             pc.green('➜') +
             '  ' +
             pc.bold('Local') +
             ':   ' +
-            pc.cyan(`http://localhost:${pc.bold(String(front.port))}/`) +
+            pc.cyan(`http://${shownHost}:${pc.bold(String(front.port))}/`) +
             pc.dim('  (wasm server + vite)') +
+            (isExposedHost(front.host)
+                ? pc.yellow(`\n  ⚠  exposed on ${front.host}:${String(front.port)} (not just loopback)`)
+                : '') +
             '\n',
     );
-    printEmailsUrl(cfg, `http://localhost:${String(front.port)}/`);
+    printEmailsUrl(cfg, `http://${shownHost}:${String(front.port)}/`);
 
     // Rebuild the server on server-file changes; Vite HMRs the regenerated shared/server.ts
     // and the dev server hot-swaps the recompiled wasm module.
@@ -1044,7 +1060,9 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
         daemon: cfg.daemon,
         threads: opts.threads ?? cfg.threads,
         port: cfg.port,
-        host: opts.host,
+        // `cfg.host` already folds in the `--host` flag, `HOST` env, and `client.host`
+        // config (CLI > env > config > 127.0.0.1); see loadConfig.
+        host: cfg.host,
         email: cfg.email ?? undefined,
     });
 }

package/src/devserver/email/console.ts

@@ -0,0 +1,134 @@
+/**
+ * DEV EMAIL EMULATOR: renders an outgoing email as an ASCII-drawn box in the
+ * terminal so confirm / reset / 2FA flows are testable locally WITHOUT a real
+ * inbox (the whole point of dev). It converts the HTML body to readable text,
+ * lays it out under a left-barred box, and highlights the ACTION (the one-time
+ * link, which carries its token in the `#token=` fragment and so is directly
+ * clickable, or the numeric 2FA code). Dev-only; the production edge never renders
+ * or logs token material.
+ *
+ * The box uses a LEFT bar plus full top/bottom rules (no right border), so colored
+ * spans never break column alignment and long URLs stay on one unbroken, clickable
+ * line.
+ */
+import pc from 'picocolors';
+
+import { type ParsedEmail } from './wire.js';
+
+const WIDTH = 68; // wrap column for body text (URLs are left un-wrapped)
+
+/** Decode the handful of HTML entities our built-in templates can emit. */
+function decodeEntities(s: string): string {
+    return s
+        .replace(/ /g, ' ')
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#0*39;|&apos;/g, "'")
+        .replace(/&#x([0-9a-fA-F]+);/g, (_m, h: string) => String.fromCodePoint(parseInt(h, 16)))
+        .replace(/&#(\d+);/g, (_m, d: string) => String.fromCodePoint(parseInt(d, 10)));
+}
+
+/**
+ * A plain-text rendering of an HTML email body: anchors become `text (url)` so
+ * the URL stays visible + clickable, block elements become line breaks, remaining
+ * tags are stripped, entities decoded, and whitespace collapsed.
+ */
+export function htmlToText(html: string): string {
+    let s = html;
+    // <a href="URL">TEXT</a> -> "TEXT (URL)" (or just URL when text == url / empty)
+    s = s.replace(
+        /<a\b[^>]*\bhref=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi,
+        (_m, href: string, inner: string) => {
+            const t = inner.replace(/<[^>]+>/g, '').trim();
+            return t.length > 0 && t !== href ? `${t} (${href})` : href;
+        },
+    );
+    // block-level tags -> newlines (open OR close), <br> -> newline
+    s = s.replace(/<br\s*\/?>/gi, '\n');
+    s = s.replace(/<\/?(?:p|div|h[1-6]|li|tr|table|ul|ol|blockquote|section|header|footer)\b[^>]*>/gi, '\n');
+    // strip whatever tags remain
+    s = s.replace(/<[^>]+>/g, '');
+    s = decodeEntities(s);
+    // collapse intra-line whitespace, trim each line, cap blank runs at one
+    s = s.replace(/[ \t]+/g, ' ');
+    s = s
+        .split('\n')
+        .map((l) => l.trim())
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return s;
+}
+
+/** The actionable bit of an email: the first link, else a 4-8 digit code, else null. */
+export function emailAction(parsed: ParsedEmail): { kind: 'link' | 'code'; value: string } | null {
+    const body = parsed.body.length > 0 ? parsed.body : htmlToText(parsed.html);
+    const link = /https?:\/\/[^\s"'<>)]+/.exec(body);
+    if (link !== null) return { kind: 'link', value: link[0] };
+    const code = /\b(\d{4,8})\b/.exec(body);
+    if (code !== null) return { kind: 'code', value: code[1] };
+    return null;
+}
+
+/** Word-wrap to `width`; words longer than `width` (URLs, tokens) overflow rather
+ *  than being hard-split, so they stay intact and clickable. */
+function wrap(text: string, width: number): string[] {
+    const out: string[] = [];
+    for (const para of text.split('\n')) {
+        if (para.length === 0) {
+            out.push('');
+            continue;
+        }
+        let line = '';
+        for (const word of para.split(' ')) {
+            if (line.length === 0) line = word;
+            else if (line.length + 1 + word.length <= width) line += ' ' + word;
+            else {
+                out.push(line);
+                line = word;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+
+/**
+ * The full ASCII box for one dev email. `status` is a short label for the header
+ * (e.g. `not sent - no provider`, `sent`, `deduped`).
+ */
+export function renderEmailConsole(parsed: ParsedEmail, status: string): string {
+    const bar = pc.dim('  │ ');
+    const rule = (label: string): string => {
+        const head = label.length > 0 ? `─ ${label} ` : '─';
+        const fill = '─'.repeat(Math.max(0, WIDTH + 2 - head.length));
+        return pc.dim(`  ├${head}${fill}`);
+    };
+    const purpose = parsed.purpose.length > 0 ? ` · ${parsed.purpose}` : '';
+    const header = `─ ✉  ${pc.bold('Email')} ${pc.dim(`(dev${purpose} · ${status})`)} `;
+    const topFill = '─'.repeat(Math.max(0, WIDTH + 2 - `─ ✉  Email (dev${purpose} · ${status}) `.length));
+
+    const lines: string[] = [];
+    lines.push(pc.dim(`  ┌${header}${topFill}`));
+    lines.push(bar + pc.dim('To:      ') + parsed.to);
+    lines.push(bar + pc.dim('Subject: ') + parsed.subject);
+    lines.push(pc.dim('  │'));
+
+    const bodyText = parsed.body.length > 0 ? parsed.body : htmlToText(parsed.html);
+    for (const l of wrap(bodyText, WIDTH)) lines.push(l.length === 0 ? pc.dim('  │') : bar + l);
+
+    const action = emailAction(parsed);
+    if (action !== null) {
+        if (action.kind === 'link') {
+            lines.push(rule('🔗 click to continue'));
+            lines.push(bar + pc.cyan(pc.underline(action.value)));
+        } else {
+            lines.push(rule('🔢 code'));
+            lines.push(bar + pc.bold(pc.yellow(action.value)));
+        }
+    }
+    lines.push(pc.dim(`  └${'─'.repeat(WIDTH + 2)}`));
+    return lines.join('\n');
+}

package/src/devserver/runtime/host.ts

@@ -22,7 +22,8 @@ import { ratelimitCheck } from '../config/ratelimit.js';
 import { buildAnalyticsImports } from '../analytics/index.js';
 import { buildDatabaseImports, type DbDevState, freshDbState } from '../db/index.js';
 import { EmailStatus, getEmailService, recordSentEmail } from '../email/index.js';
-import { parseEmailBlob } from '../email/wire.js';
+import { renderEmailConsole } from '../email/console.js';
+import { type ParsedEmail, parseEmailBlob } from '../email/wire.js';
 import { buildCryptoImports, type CryptoState, freshCryptoState } from './crypto.js';
 
 /** Limits identical to the edge's `set_header` / `respond_file` bounds. */
@@ -204,6 +205,14 @@ function envLookup(
  * confirm/reset tests find their tokens whichever import the guest used. Mirrors
  * the edge's `email_send_import.rs`.
  */
+/** Render the dev EMAIL EMULATOR box (from the HTML) so confirm/reset/2FA flows are
+ *  testable without a real inbox. Skipped under vitest (tests read the
+ *  `__sentEmails` seam), where a box per email would just be noise. */
+function previewDevEmail(parsed: ParsedEmail, status: string): void {
+    if (process.env.VITEST) return;
+    process.stdout.write(renderEmailConsole(parsed, status) + '\n');
+}
+
 function devEmailSend(ref: MemoryRef, reqPtr: number, reqLen: number): number {
     const raw = readBytes(ref, reqPtr, reqLen);
     const svc = getEmailService();
@@ -212,6 +221,8 @@ function devEmailSend(ref: MemoryRef, reqPtr: number, reqLen: number): number {
         if (parsed !== null) recordSentEmail(parsed); // dev test seam
         const to = parsed?.to ?? '<unparsed>';
         process.stdout.write(`  ✉ dev email_send -> ${to} (no email config; not sent)\n`);
+        // Draw the email so the flow is testable with no mailer configured.
+        if (parsed !== null) previewDevEmail(parsed, 'not sent · no provider');
         return EmailStatus.Sent;
     }
     const { status, parsed } = svc.prepare(raw);
@@ -220,6 +231,7 @@ function devEmailSend(ref: MemoryRef, reqPtr: number, reqLen: number): number {
         return status;
     }
     recordSentEmail(parsed); // dev test seam
+    previewDevEmail(parsed, 'delivering via provider'); // shown even with a real provider
     void svc
         .deliver(parsed)
         .then((s) => {

package/test/config-host-port.test.ts

@@ -0,0 +1,59 @@
+/**
+ * loadConfig host/port resolution: the dev server AND the self-host (`toiljs start`)
+ * bind to a host+port resolved with the precedence CLI flag > env (PORT/HOST) >
+ * config (client.host/port) > default (127.0.0.1:3000). These lock that precedence
+ * and the env parsing (a blank/garbage PORT must fall through, never bind to 0).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { loadConfig } from '../src/compiler/config.js';
+
+// An empty dir with no toil.config so loadConfig exercises the env/opts/default path.
+const emptyRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-cfg-'));
+
+describe('loadConfig host/port precedence', () => {
+    const savedPort = process.env.PORT;
+    const savedHost = process.env.HOST;
+    afterEach(() => {
+        if (savedPort === undefined) delete process.env.PORT;
+        else process.env.PORT = savedPort;
+        if (savedHost === undefined) delete process.env.HOST;
+        else process.env.HOST = savedHost;
+    });
+
+    it('defaults to 127.0.0.1:3000 with no flag / env / config', async () => {
+        delete process.env.PORT;
+        delete process.env.HOST;
+        const cfg = await loadConfig({ root: emptyRoot });
+        expect(cfg.port).toBe(3000);
+        expect(cfg.host).toBe('127.0.0.1');
+    });
+
+    it('reads the PORT / HOST env vars', async () => {
+        process.env.PORT = '8080';
+        process.env.HOST = '0.0.0.0';
+        const cfg = await loadConfig({ root: emptyRoot });
+        expect(cfg.port).toBe(8080);
+        expect(cfg.host).toBe('0.0.0.0');
+    });
+
+    it('CLI opts win over env (CLI > env)', async () => {
+        process.env.PORT = '8080';
+        process.env.HOST = '0.0.0.0';
+        const cfg = await loadConfig({ root: emptyRoot, port: 4321, host: '192.168.1.5' });
+        expect(cfg.port).toBe(4321);
+        expect(cfg.host).toBe('192.168.1.5');
+    });
+
+    it('a blank / non-numeric PORT env falls through to the default (never binds to 0)', async () => {
+        process.env.PORT = '';
+        delete process.env.HOST;
+        expect((await loadConfig({ root: emptyRoot })).port).toBe(3000);
+        process.env.PORT = 'not-a-number';
+        expect((await loadConfig({ root: emptyRoot })).port).toBe(3000);
+    });
+});

package/test/email-console.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Dev email emulator (src/devserver/email/console.ts): the ASCII-drawn box + the
+ * HTML->text conversion + action (link/code) extraction that make confirm/reset/2FA
+ * flows testable in `toiljs dev` without a real inbox.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { emailAction, htmlToText, renderEmailConsole } from '../src/devserver/email/console.js';
+
+const confirmEmail = {
+    to: 'bob@gmail.com',
+    subject: 'Confirm your account',
+    purpose: 'verify',
+    body: 'Confirm your account by opening this link:\nhttp://localhost:3000/confirm#token=abc123\n',
+    html:
+        '<p>Confirm your account by clicking the link below:</p>' +
+        '<p><a href="http://localhost:3000/confirm#token=abc123">Confirm my account</a></p>',
+};
+
+/** picocolors may or may not emit ANSI depending on TTY; strip it for assertions. */
+const plain = (s: string): string => s.replace(/\[[0-9;]*m/g, '');
+
+describe('dev email emulator', () => {
+    it('htmlToText: anchors become "text (url)", blocks become newlines, entities decode', () => {
+        const t = htmlToText('<p>Hi &amp; welcome</p><p><a href="https://x.com/a?b=1">Open</a></p>');
+        expect(t).toContain('Hi & welcome');
+        expect(t).toContain('Open (https://x.com/a?b=1)');
+    });
+
+    it('emailAction extracts the link from a confirm email', () => {
+        expect(emailAction(confirmEmail)).toEqual({
+            kind: 'link',
+            value: 'http://localhost:3000/confirm#token=abc123',
+        });
+    });
+
+    it('emailAction extracts a 2FA code when there is no link', () => {
+        const twofa = { to: 'x', subject: 's', purpose: '2fa', body: 'Your code is 481920.', html: '' };
+        expect(emailAction(twofa)).toEqual({ kind: 'code', value: '481920' });
+    });
+
+    it('emailAction falls back to the HTML body when the text body is empty', () => {
+        expect(emailAction({ ...confirmEmail, body: '' })?.value).toBe(
+            'http://localhost:3000/confirm#token=abc123',
+        );
+    });
+
+    it('renderEmailConsole draws a box with recipient, subject, and the clickable link', () => {
+        const box = plain(renderEmailConsole(confirmEmail, 'not sent'));
+        expect(box).toContain('bob@gmail.com');
+        expect(box).toContain('Confirm your account');
+        expect(box).toContain('http://localhost:3000/confirm#token=abc123');
+        expect(box).toContain('┌');
+        expect(box).toContain('└');
+    });
+});