toiljs 0.0.45 → 0.0.47

package/src/compiler/index.ts

@@ -228,6 +228,33 @@ function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher'])
     });
 }
 
+/**
+ * Make `Ctrl+C` actually kill the dev server. Without this the process can hang
+ * on shutdown (the native uWebSockets listener / Vite's watcher don't always
+ * close promptly), so an old `toiljs dev` is left ORPHANED — still watching and
+ * rebuilding — and the next run races it (parallel double rebuilds), while the
+ * console is left with a hidden cursor. On SIGINT/SIGTERM we restore the cursor,
+ * close the servers, and force-exit after a short grace period no matter what.
+ */
+function installDevShutdown(close: () => Promise<void> | void): void {
+    let closing = false;
+    const shutdown = (): void => {
+        if (closing) return;
+        closing = true;
+        // Restore the cursor (anything that hid it leaves the terminal odd on exit).
+        process.stdout.write('\x1b[?25h');
+        process.stdout.write(pc.dim('\n  shutting down dev server…') + '\n');
+        // Force-exit even if a server hangs on close (the orphan-prevention).
+        const hard = setTimeout(() => process.exit(0), 1500);
+        hard.unref();
+        Promise.resolve()
+            .then(close)
+            .catch(() => {})
+            .finally(() => process.exit(0));
+    };
+    for (const sig of ['SIGINT', 'SIGTERM'] as const) process.once(sig, shutdown);
+}
+
 /** The server wasm artifact path from the toilconfig `release` target (toilscript's output). */
 function serverWasmFile(root: string): string {
     let outFile = 'build/server/release.wasm';
@@ -268,6 +295,23 @@ export interface ToilCommandOptions {
     readonly serverOnly?: boolean;
 }
 
+/** Prints the email-preview URL under the dev banner, when the project has an
+ *  `emails/` folder. `localUrl` is the resolved base (ends in `/`); skipped if
+ *  the server didn't report one. */
+function printEmailsUrl(cfg: ResolvedToilConfig, localUrl: string | undefined): void {
+    if (!localUrl || !fs.existsSync(path.join(cfg.root, 'emails'))) return;
+    process.stdout.write(
+        '  ' +
+            pc.green('✉') +
+            '  ' +
+            pc.bold('Emails') +
+            ':  ' +
+            pc.cyan(`${localUrl}__toil/emails`) +
+            pc.dim('  (preview)') +
+            '\n',
+    );
+}
+
 /**
  * Starts the dev server. Client-only projects get the plain Vite dev server on
  * the configured port, unchanged. Projects with a server target
@@ -293,6 +337,8 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
         const server = await createServer(await createViteConfig(cfg));
         await server.listen();
         server.printUrls();
+        printEmailsUrl(cfg, server.resolvedUrls?.local?.[0]);
+        installDevShutdown(() => server.close());
         return server;
     }
 
@@ -325,10 +371,15 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
             pc.dim('  (wasm server + vite)') +
             '\n',
     );
+    printEmailsUrl(cfg, `http://localhost:${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.
     watchServer(cfg, server.watcher);
+    installDevShutdown(async () => {
+        await front.close();
+        await server.close();
+    });
     return server;
 }
 

package/src/compiler/plugin.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { type Plugin, version as viteVersion } from 'vite';
 
 import { AiProvider, type DevtoolsAiConfig, type ResolvedToilConfig } from './config.js';
+import { emailsVersion, listEmails, previewShellHtml, renderEmailByName } from './email-preview.js';
 import { generate } from './generate.js';
 import { scanRoutes } from './routes.js';
 
@@ -58,7 +59,9 @@ async function aiComplete(ai: DevtoolsAiConfig, prompt: string): Promise<string>
 /** Reads a package's version resolved from `<fromDir>`, or 'unknown'. */
 function depVersion(fromDir: string, name: string): string {
     try {
-        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(`${name}/package.json`);
+        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(
+            `${name}/package.json`,
+        );
         const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
         return raw.version ?? 'unknown';
     } catch {
@@ -69,7 +72,12 @@ function depVersion(fromDir: string, name: string): string {
 /** toiljs's own version (package.json two levels up from build/compiler). */
 function frameworkVersion(): string {
     try {
-        const p = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const p = path.resolve(
+            path.dirname(fileURLToPath(import.meta.url)),
+            '..',
+            '..',
+            'package.json',
+        );
         const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as { version?: string };
         return raw.version ?? '0.0.0';
     } catch {
@@ -231,7 +239,9 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             const parsed = JSON.parse(body || '{}') as { prompt?: string };
                             // Cap the prompt actually forwarded upstream (independent of the raw-body cap).
                             const prompt =
-                                typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                                typeof parsed.prompt === 'string'
+                                    ? parsed.prompt.slice(0, 16000)
+                                    : '';
                             const text = await aiComplete(ai, prompt);
                             res.setHeader('content-type', 'application/json');
                             res.end(JSON.stringify({ text }));
@@ -243,7 +253,11 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             );
                             res.statusCode = 500;
                             res.setHeader('content-type', 'application/json');
-                            res.end(JSON.stringify({ error: 'AI request failed (see dev server logs).' }));
+                            res.end(
+                                JSON.stringify({
+                                    error: 'AI request failed (see dev server logs).',
+                                }),
+                            );
                         }
                     })();
                 });
@@ -291,6 +305,76 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                 }
             });
 
+            // Email preview tool (dev only). `/__toil/emails` -> a standalone page that lists
+            // `emails/*.tsx`, renders the selected one through the live SSR server (so edits and
+            // imported `client/*` CSS show), and live-refreshes by polling `/version`.
+            // Sub-paths are registered before the page so connect's prefix match resolves them first.
+            server.middlewares.use('/__toil/emails/list', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(listEmails(cfg)));
+            });
+            server.middlewares.use('/__toil/emails/render', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                void (async () => {
+                    try {
+                        const name = new URL(req.url ?? '', 'http://localhost').searchParams.get(
+                            'name',
+                        );
+                        if (!name) {
+                            res.statusCode = 400;
+                            res.end();
+                            return;
+                        }
+                        const rendered = await renderEmailByName(server, cfg, name);
+                        if (!rendered) {
+                            res.statusCode = 404;
+                            res.end();
+                            return;
+                        }
+                        res.setHeader('content-type', 'application/json');
+                        res.end(JSON.stringify(rendered));
+                    } catch (e) {
+                        // Log the detail to the dev's terminal; the page shows a generic message.
+                        process.stderr.write(
+                            `toil: /__toil/emails/render failed: ${e instanceof Error ? e.message : String(e)}\n`,
+                        );
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                })();
+            });
+            // A tiny mtime fingerprint of `emails/*` + client CSS the page polls (~1s) to detect
+            // edits. Polling (not SSE) because the wasm dev server proxies `/__toil/*` to Vite by
+            // buffering the whole response, so a long-lived stream would hang; a short poll works
+            // in every mode.
+            server.middlewares.use('/__toil/emails/version', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                res.end(emailsVersion(cfg));
+            });
+            server.middlewares.use('/__toil/emails', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/html; charset=utf-8');
+                res.end(previewShellHtml());
+            });
+
             // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file: string): void => {

package/src/compiler/vite.ts

@@ -154,6 +154,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
             alias: {
                 'toiljs/client': cfg.runtimePath,
                 'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
+                // `client/*` -> the project's client source dir, so anything (pages, and notably
+                // `emails/*.tsx`) can reuse existing client assets, e.g. `import 'client/styles/x.css'`.
+                // Vite's string alias matches only `client` or `client/...`, never `toiljs/client`.
+                client: cfg.clientAbsDir,
                 // `shared/*` is resolved by sharedResolverPlugin (above) so a missing generated
                 // shared/server.ts gives an actionable error instead of an opaque load failure.
                 ...polyfillShimAliases,

package/test/email-preview.test.ts

@@ -0,0 +1,68 @@
+import path from 'node:path';
+
+import { createServer } from 'vite';
+import { describe, expect, it } from 'vitest';
+
+import { loadConfig } from '../src/compiler/config';
+import {
+    emailsVersion,
+    listEmails,
+    previewShellHtml,
+    renderEmailByName,
+} from '../src/compiler/email-preview';
+import { createViteConfig } from '../src/compiler/vite';
+
+const EXAMPLE = path.resolve(__dirname, '../examples/basic');
+
+describe('email preview end-to-end (examples/basic)', () => {
+    it('lists Welcome and inlines its emails/styles/email.css; client/* alias resolves', async () => {
+        const cfg = await loadConfig({ root: EXAMPLE });
+        const items = listEmails(cfg);
+        expect(items.map((i) => i.name)).toContain('Welcome');
+
+        const server = await createServer({
+            ...(await createViteConfig(cfg)),
+            server: { middlewareMode: true, hmr: false },
+            appType: 'custom',
+            logLevel: 'silent',
+        });
+        try {
+            const r = await renderEmailByName(server, cfg, 'Welcome');
+            if (!r) throw new Error('Welcome did not render');
+            // tokens discovered from props
+            expect(r.tokens).toEqual(['code', 'name']);
+            // subject token template
+            expect(r.subject).toBe('Welcome to toiljs, {{name}}');
+            // .email-title { color: #f5f6fa } from emails/styles/email.css inlined onto the <h1>
+            expect(r.html).toMatch(/<h1[^>]*style="[^"]*color:\s*#f5f6fa/i);
+            // .email-card { background-color: #0e1520 } inlined onto the card <table>
+            expect(r.html).toMatch(/<table[^>]*style="[^"]*background-color:\s*#0e1520/i);
+
+            // The `client/*` reuse alias still resolves project CSS (the documented
+            // `import 'client/styles/…'` path), independent of where the demo keeps its styles.
+            const aliased = (await server.ssrLoadModule('client/styles/main.css?inline')) as {
+                default?: unknown;
+            };
+            expect(typeof aliased.default).toBe('string');
+        } finally {
+            await server.close();
+        }
+    }, 30000);
+
+    it('emailsVersion is a non-empty mtime:count fingerprint', async () => {
+        const cfg = await loadConfig({ root: EXAMPLE });
+        const v = emailsVersion(cfg);
+        expect(v).toMatch(/^\d+(\.\d+)?:\d+$/);
+        // at least Welcome.tsx + the client CSS files were counted
+        expect(Number(v.split(':')[1])).toBeGreaterThan(1);
+    });
+
+    it('the preview shell wires the dev endpoints', () => {
+        const html = previewShellHtml();
+        expect(html).toContain("var BASE = '/__toil/emails'");
+        for (const frag of ["BASE + '/list'", "BASE + '/render?name='", "BASE + '/version'"]) {
+            expect(html).toContain(frag);
+        }
+        expect(html).toContain('/__toil/open?file='); // open-in-editor
+    });
+});

package/test/emails.test.ts

@@ -0,0 +1,58 @@
+import { createElement, type ReactElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { __test } from '../src/compiler/emails';
+
+const render = (el: unknown): string => renderToStaticMarkup(el as ReactElement);
+
+describe('renderModule', () => {
+    it('discovers props as {{tokens}} and renders placeholders (alpha-sorted, deduped)', async () => {
+        const mod = {
+            default: (p: { name: string; code: string }) =>
+                createElement('p', null, `Hi ${p.name}, code ${p.code}`),
+        };
+        const r = await __test.renderModule('Welcome', mod, render);
+        if (!r) throw new Error('expected a rendered email');
+        expect(r.tokens).toEqual(['code', 'name']);
+        expect(r.html).toContain('{{name}}');
+        expect(r.html).toContain('{{code}}');
+    });
+
+    it('returns null when there is no default-exported component', async () => {
+        expect(await __test.renderModule('X', { default: 'nope' }, render)).toBeNull();
+    });
+
+    it('inlines imported CSS into element style="" (the reuse path)', async () => {
+        const mod = { default: () => createElement('h1', { className: 'email-title' }, 'Hello') };
+        const css = '.email-title { color: #111827; font-size: 22px; }';
+        const r = await __test.renderModule('Styled', mod, render, css);
+        if (!r) throw new Error('expected a rendered email');
+        // The class rule is moved onto the element as an inline style by the inliner.
+        expect(r.html).toMatch(/<h1[^>]*style="[^"]*color:\s*#111827/i);
+        expect(r.html).toMatch(/font-size:\s*22px/i);
+    });
+});
+
+describe('renderModuleSource', () => {
+    it('generates a typed Emails.<Name>.send with alpha-sorted token params', () => {
+        const src = __test.renderModuleSource([
+            {
+                name: 'Welcome',
+                subject: 'Welcome, {{name}}!',
+                html: '<p>{{code}}</p>',
+                text: 'code {{code}}',
+                tokens: ['code', 'name'],
+                purpose: 'welcome',
+            },
+        ]);
+        expect(src).toContain('export namespace Emails {');
+        expect(src).toContain('export namespace Welcome {');
+        expect(src).toContain(
+            'export function send(to: string, code: string, name: string, purpose: string = "welcome")',
+        );
+        expect(src).toContain(
+            'return new EmailTemplate(SUBJECT, TEXT, HTML).send(to, __v, purpose);',
+        );
+    });
+});