@inbrx/cli 0.0.1-alpha.2

package/bin/inbrx.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const cliPath = resolve(root, 'dist/cli.js');
+
+if (!existsSync(cliPath)) {
+  console.error('Build output is missing. Run "npm run build" before using the CLI.');
+  process.exit(1);
+}
+
+const { runCli } = await import('../dist/cli.js');
+
+runCli(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,67 @@
+import { Command } from 'commander';
+import { getDefaultConfig, loadConfig } from './config.js';
+import { startApp } from './index.js';
+export async function runCli(argv) {
+    const program = createCliProgram();
+    await program.parseAsync(normalizeArgv(argv), { from: 'node' });
+}
+export function createCliProgram() {
+    const defaults = getDefaultConfig();
+    const program = new Command();
+    program
+        .name('inbrx')
+        .description('Start a local SMTP capture server and web UI.')
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    program
+        .command('start')
+        .description('Start the SMTP server and HTTP API/UI.')
+        .option('--smtp-host <host>', `SMTP bind host. Default: ${defaults.smtpHost}`)
+        .option('--smtp-port <port>', `SMTP port. Default: ${defaults.smtpPort}`)
+        .option('--http-host <host>', `HTTP bind host. Default: ${defaults.httpHost}`)
+        .option('--http-port <port>', `HTTP port. Default: ${defaults.httpPort}`)
+        .option('--max-messages <count>', `Maximum retained messages. Default: ${defaults.maxMessages}`)
+        .addHelpText('after', `
+
+Environment:
+  SMTP_TEST_SMTP_HOST
+  SMTP_TEST_SMTP_PORT
+  SMTP_TEST_HTTP_HOST
+  SMTP_TEST_HTTP_PORT
+  SMTP_TEST_MAX_MESSAGES`)
+        .action(async (options) => {
+        await startServer(options);
+    });
+    return program;
+}
+async function startServer(options) {
+    const config = loadConfig(options);
+    const app = await startApp(config);
+    console.log('SMTP test server ready');
+    console.log(`SMTP: smtp://${config.smtpHost}:${config.smtpPort}`);
+    console.log(`Web UI: http://${config.httpHost}:${config.httpPort}`);
+    console.log('Press Ctrl+C to stop.');
+    const shutdown = async () => {
+        console.log('\nShutting down...');
+        await app.stop();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+function normalizeArgv(argv) {
+    const firstArg = argv[2];
+    if (!firstArg) {
+        return [...argv, 'start'];
+    }
+    if (firstArg.startsWith('-') && firstArg !== '-h' && firstArg !== '--help') {
+        return [argv[0] || 'node', argv[1] || 'inbrx', 'start', ...argv.slice(2)];
+    }
+    return argv;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runCli(process.argv).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/config.js

@@ -0,0 +1,50 @@
+const DEFAULTS = {
+    smtpHost: '127.0.0.1',
+    smtpPort: 2525,
+    httpHost: '127.0.0.1',
+    httpPort: 3000,
+    maxMessages: 500
+};
+export function loadConfig(overrides = {}) {
+    const config = {
+        smtpHost: readString(overrides.smtpHost, process.env.SMTP_TEST_SMTP_HOST, DEFAULTS.smtpHost),
+        smtpPort: readNumber(overrides.smtpPort, process.env.SMTP_TEST_SMTP_PORT, DEFAULTS.smtpPort),
+        httpHost: readString(overrides.httpHost, process.env.SMTP_TEST_HTTP_HOST, DEFAULTS.httpHost),
+        httpPort: readNumber(overrides.httpPort, process.env.SMTP_TEST_HTTP_PORT, DEFAULTS.httpPort),
+        maxMessages: readNumber(overrides.maxMessages, process.env.SMTP_TEST_MAX_MESSAGES, DEFAULTS.maxMessages)
+    };
+    assertPort(config.smtpPort, 'SMTP port');
+    assertPort(config.httpPort, 'HTTP port');
+    if (!Number.isInteger(config.maxMessages) || config.maxMessages < 1) {
+        throw new Error('Max messages must be a positive integer.');
+    }
+    return config;
+}
+export function getDefaultConfig() {
+    return { ...DEFAULTS };
+}
+function readString(override, envValue, fallback) {
+    if (override !== undefined && override !== '') {
+        return String(override);
+    }
+    if (envValue !== undefined && envValue !== '') {
+        return envValue;
+    }
+    return fallback;
+}
+function readNumber(override, envValue, fallback) {
+    const value = override ?? envValue;
+    if (value === undefined || value === '') {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed)) {
+        throw new Error(`Expected an integer, received "${value}".`);
+    }
+    return parsed;
+}
+function assertPort(value, label) {
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new Error(`${label} must be an integer between 1 and 65535.`);
+    }
+}

package/dist/http/server.js

@@ -0,0 +1,137 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WEB_ROOT = path.resolve(__dirname, '../../..', 'web/dist');
+export function createHttpServer({ store }) {
+    const app = createHttpApp({ store });
+    let server = null;
+    return {
+        listen(port, host) {
+            return new Promise((resolve, reject) => {
+                const listeningServer = serve({
+                    fetch: app.fetch,
+                    hostname: host,
+                    port
+                }, () => {
+                    listeningServer.off('error', reject);
+                    server = listeningServer;
+                    resolve();
+                });
+                listeningServer.once('error', reject);
+            });
+        },
+        close() {
+            return new Promise((resolve, reject) => {
+                if (!server) {
+                    resolve();
+                    return;
+                }
+                server.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    server = null;
+                    resolve();
+                });
+            });
+        }
+    };
+}
+export function createHttpApp({ store }) {
+    const app = new Hono();
+    app.onError((error, c) => {
+        console.error(error);
+        return c.json({ error: 'Internal server error' }, 500);
+    });
+    app.get('/api/health', (c) => c.json({ status: 'ok' }));
+    app.get('/api/messages', (c) => c.json({
+        messages: store.list().map(toMessageSummary)
+    }));
+    app.delete('/api/messages', (c) => {
+        const deleted = store.clear();
+        return c.json({ deleted });
+    });
+    app.get('/api/messages/:id', (c) => {
+        const message = store.get(c.req.param('id'));
+        if (!message) {
+            return c.json({ error: 'Message not found' }, 404);
+        }
+        return c.json({ message: toMessageDetail(message) });
+    });
+    app.delete('/api/messages/:id', (c) => {
+        const deleted = store.delete(c.req.param('id'));
+        return c.json({ deleted }, deleted ? 200 : 404);
+    });
+    app.all('*', (c) => serveStatic(new URL(c.req.url).pathname));
+    return app;
+}
+function toMessageSummary(message) {
+    return {
+        id: message.id,
+        receivedAt: message.receivedAt,
+        from: message.from,
+        to: message.to,
+        subject: message.subject,
+        rawSizeBytes: message.rawSizeBytes
+    };
+}
+function toMessageDetail(message) {
+    return {
+        ...toMessageSummary(message),
+        cc: message.cc,
+        bcc: message.bcc,
+        headers: message.headers,
+        text: message.text,
+        html: message.html,
+        attachments: message.attachments,
+        raw: message.raw,
+        smtp: message.smtp
+    };
+}
+async function serveStatic(urlPath) {
+    const relativePath = urlPath === '/' ? 'index.html' : decodeURIComponent(urlPath.slice(1));
+    const filePath = path.resolve(WEB_ROOT, relativePath);
+    if (!filePath.startsWith(`${WEB_ROOT}${path.sep}`) && filePath !== WEB_ROOT) {
+        return textResponse('Forbidden', 403);
+    }
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            return textResponse('Not found', 404);
+        }
+    }
+    catch {
+        return textResponse('Not found', 404);
+    }
+    return new Response(Readable.toWeb(createReadStream(filePath)), {
+        headers: {
+            'content-type': contentTypeFor(filePath)
+        }
+    });
+}
+function textResponse(text, statusCode) {
+    return new Response(text, {
+        status: statusCode,
+        headers: {
+            'content-type': 'text/plain; charset=utf-8'
+        }
+    });
+}
+function contentTypeFor(filePath) {
+    if (filePath.endsWith('.html')) {
+        return 'text/html; charset=utf-8';
+    }
+    if (filePath.endsWith('.css')) {
+        return 'text/css; charset=utf-8';
+    }
+    if (filePath.endsWith('.js')) {
+        return 'text/javascript; charset=utf-8';
+    }
+    return 'application/octet-stream';
+}

package/dist/index.js

@@ -0,0 +1,18 @@
+import { createHttpServer } from './http/server.js';
+import { createMemoryStore } from './store/memory-store.js';
+import { createSmtpServer } from './smtp/server.js';
+export async function startApp(config) {
+    const store = createMemoryStore({ maxMessages: config.maxMessages });
+    const smtpServer = createSmtpServer({ store });
+    const httpServer = createHttpServer({ store });
+    await Promise.all([
+        smtpServer.listen(config.smtpPort, config.smtpHost),
+        httpServer.listen(config.httpPort, config.httpHost)
+    ]);
+    return {
+        store,
+        async stop() {
+            await Promise.allSettled([smtpServer.close(), httpServer.close()]);
+        }
+    };
+}

package/dist/mail/parser.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { simpleParser } from 'mailparser';
+export async function parseMessage({ raw, envelope, smtp }) {
+    const parsed = await simpleParser(Buffer.from(raw));
+    return {
+        id: randomUUID(),
+        receivedAt: new Date().toISOString(),
+        from: envelope.from || firstAddress(parsed.from),
+        to: envelope.to.length > 0 ? envelope.to : addressList(parsed.to),
+        cc: addressList(parsed.cc),
+        bcc: addressList(parsed.bcc),
+        subject: parsed.subject || null,
+        headers: headersToRecord(parsed.headers),
+        text: parsed.text || null,
+        html: typeof parsed.html === 'string' ? parsed.html : null,
+        attachments: parsed.attachments.map((attachment) => ({
+            filename: attachment.filename || null,
+            contentType: attachment.contentType,
+            sizeBytes: attachment.size,
+            contentId: attachment.contentId
+        })),
+        rawSizeBytes: Buffer.byteLength(raw),
+        raw,
+        smtp
+    };
+}
+function headersToRecord(parsedHeaders) {
+    const record = {};
+    for (const [key, value] of parsedHeaders) {
+        record[key] = headerValueToString(value);
+    }
+    return record;
+}
+function headerValueToString(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item));
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'object' && value !== null) {
+        return 'text' in value ? value.text : JSON.stringify(value);
+    }
+    return String(value);
+}
+function firstAddress(value) {
+    return value?.value.find((address) => Boolean(address.address))?.address || null;
+}
+function addressList(value) {
+    const values = Array.isArray(value) ? value : value ? [value] : [];
+    return values.flatMap((item) => item.value.map((address) => address.address).filter(Boolean));
+}

package/dist/smtp/server.js

@@ -0,0 +1,86 @@
+import { SMTPServer } from 'smtp-server';
+import { parseMessage } from '../mail/parser.js';
+export function createSmtpServer({ store }) {
+    const server = new SMTPServer({
+        name: 'inbrx',
+        banner: 'inbrx ready',
+        authOptional: true,
+        disabledCommands: ['AUTH', 'STARTTLS'],
+        hidePIPELINING: true,
+        logger: false,
+        onMailFrom(_address, _session, callback) {
+            callback();
+        },
+        onRcptTo(_address, _session, callback) {
+            callback();
+        },
+        onData(stream, session, callback) {
+            void handleData(stream, session, store)
+                .then((messageId) => callback(null, `OK captured as ${messageId}`))
+                .catch((error) => callback(error instanceof Error ? error : new Error(String(error))));
+        }
+    });
+    return {
+        listen(port, host) {
+            return new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve) => {
+                server.close(resolve);
+            });
+        }
+    };
+}
+async function handleData(stream, session, store) {
+    const raw = await readStream(stream);
+    const smtp = toCapturedSmtpSession(session);
+    const envelope = toMailEnvelope(smtp);
+    const message = await parseMessage({ raw, envelope, smtp });
+    store.add(message);
+    return message.id;
+}
+function readStream(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        stream.on('error', reject);
+        stream.on('end', () => {
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+    });
+}
+function toCapturedSmtpSession(session) {
+    return {
+        id: session.id,
+        remoteAddress: session.remoteAddress,
+        remotePort: session.remotePort,
+        clientHostname: session.clientHostname,
+        openingCommand: session.openingCommand,
+        hostNameAppearsAs: session.hostNameAppearsAs,
+        secure: session.secure,
+        envelope: {
+            mailFrom: session.envelope.mailFrom ? toCapturedAddress(session.envelope.mailFrom) : null,
+            rcptTo: session.envelope.rcptTo.map(toCapturedAddress)
+        }
+    };
+}
+function toCapturedAddress(address) {
+    return {
+        address: address.address,
+        args: address.args && typeof address.args === 'object' ? address.args : {}
+    };
+}
+function toMailEnvelope(smtp) {
+    return {
+        from: smtp.envelope.mailFrom?.address || null,
+        to: smtp.envelope.rcptTo.map((recipient) => recipient.address)
+    };
+}

package/dist/store/memory-store.js

@@ -0,0 +1,37 @@
+export function createMemoryStore({ maxMessages }) {
+    const messages = new Map();
+    const order = [];
+    return {
+        add(message) {
+            messages.set(message.id, message);
+            order.unshift(message.id);
+            while (order.length > maxMessages) {
+                const removedId = order.pop();
+                if (removedId) {
+                    messages.delete(removedId);
+                }
+            }
+            return message;
+        },
+        list() {
+            return order.map((id) => messages.get(id)).filter((message) => Boolean(message));
+        },
+        get(id) {
+            return messages.get(id) || null;
+        },
+        delete(id) {
+            const existed = messages.delete(id);
+            const index = order.indexOf(id);
+            if (index !== -1) {
+                order.splice(index, 1);
+            }
+            return existed;
+        },
+        clear() {
+            const count = messages.size;
+            messages.clear();
+            order.length = 0;
+            return count;
+        }
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@inbrx/cli",
+  "version": "0.0.1-alpha.2",
+  "description": "SMTP capture server and CLI for inbrx.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuaixr/inbrx.git"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "bin": {
+    "inbrx": "./bin/inbrx.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "npm run build && node ./bin/inbrx.js start",
+    "dev": "tsx watch ./src/cli.ts start",
+    "test": "vitest run --exclude \"dist/**\"",
+    "test:watch": "vitest",
+    "check": "tsc --noEmit -p tsconfig.json && node --check ./bin/inbrx.js && npm run test"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.8",
+    "@inbrx/web": "0.0.1-alpha.2",
+    "commander": "^15.0.0",
+    "hono": "^4.12.27",
+    "mailparser": "^3.9.14",
+    "smtp-server": "^3.19.2"
+  },
+  "devDependencies": {
+    "@types/mailparser": "^3.4.6",
+    "@types/nodemailer": "^8.0.1",
+    "@types/smtp-server": "^3.5.13",
+    "nodemailer": "^9.0.3",
+    "tsx": "^4.19.0",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}