@lowdefy/server-dev 6.1.0 → 7.1.0

package/manager/processes/startFirstServer.test.mjs

@@ -0,0 +1,326 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+const mockSpawn = jest.fn();
+const { spawnSync, execSync, exec, execFile, fork } = await import('child_process');
+jest.unstable_mockModule('child_process', () => ({
+  spawn: mockSpawn,
+  spawnSync,
+  execSync,
+  exec,
+  execFile,
+  fork,
+}));
+jest.unstable_mockModule('../utils/readBasePath.mjs', () => ({ default: () => '' }));
+const mockWaitForServer = jest.fn(async () => true);
+jest.unstable_mockModule('../utils/waitForServer.mjs', () => ({ default: mockWaitForServer }));
+
+const { default: optimizeDependencies } = await import('./optimizeDependencies.mjs');
+const { default: restartServer } = await import('./restartServer.mjs');
+const { default: startFirstServer } = await import('./startFirstServer.mjs');
+const { default: startServer } = await import('./startServer.mjs');
+const { default: syncServer } = await import('./syncServer.mjs');
+
+function createProcess() {
+  return Object.assign(new EventEmitter(), {
+    stdout: new EventEmitter(),
+    stderr: new EventEmitter(),
+  });
+}
+
+function createContext() {
+  const context = {
+    bin: { vite: '/server/node_modules/vite/bin/vite.js' },
+    directories: { config: '/apps/tenant', server: '/server' },
+    instance: { update: jest.fn() },
+    internalPort: 3211,
+    logger: { debug: jest.fn(), error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+    mailSink: null,
+    markServerReady: jest.fn(),
+    options: { port: 3210 },
+    serverArtifacts: { record: jest.fn() },
+    shutdownServer: jest.fn(),
+  };
+  context.optimizeDependencies = optimizeDependencies(context);
+  context.syncServer = syncServer(context);
+  return context;
+}
+
+// Like createServerArtifactTracker over a set of file contents. Its baseline
+// is taken when the context is made, before the initial build, so before the
+// first record every artifact reads as changed.
+function createTracker(files) {
+  let started = {};
+  return {
+    record: jest.fn(() => {
+      started = { ...files };
+    }),
+    check: jest.fn(() => {
+      const changed = Object.keys(files).filter((file) => files[file] !== started[file]);
+      return { install: changed.includes('package.json'), restart: changed.length > 0 };
+    }),
+  };
+}
+
+async function flush() {
+  await new Promise((resolve) => setImmediate(resolve));
+}
+
+let processes;
+
+beforeEach(() => {
+  processes = [];
+  mockWaitForServer.mockReset();
+  mockWaitForServer.mockImplementation(async () => true);
+  mockSpawn.mockImplementation(() => {
+    const child = createProcess();
+    processes.push(child);
+    return child;
+  });
+});
+
+test('startFirstServer runs the optimiser and waits for it to exit before it spawns the child', async () => {
+  const context = createContext();
+
+  const started = startFirstServer(context);
+  await flush();
+
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+  expect(mockSpawn.mock.calls[0][0]).toBe('node');
+  expect(mockSpawn.mock.calls[0][1]).toEqual(['/server/node_modules/vite/bin/vite.js', 'optimize']);
+  expect(mockSpawn.mock.calls[0][2].cwd).toBe('/server');
+
+  processes[0].emit('exit', 0);
+  await started;
+
+  expect(mockSpawn).toHaveBeenCalledTimes(2);
+  expect(mockSpawn.mock.calls[1][1].slice(0, 3)).toEqual([
+    '--expose-gc',
+    '/server/node_modules/vite/bin/vite.js',
+    '--host',
+  ]);
+  expect(context.logger.warn).not.toHaveBeenCalled();
+});
+
+test('startFirstServer still starts the child when the optimiser fails, and warns', async () => {
+  const context = createContext();
+
+  const started = startFirstServer(context);
+  await flush();
+  processes[0].stderr.emit('data', Buffer.from('error when optimizing deps:\nboom\n'));
+  processes[0].stderr.emit('end');
+  processes[0].emit('exit', 1);
+  await started;
+
+  expect(mockSpawn).toHaveBeenCalledTimes(2);
+  expect(context.logger.warn).toHaveBeenCalledTimes(1);
+  expect(context.logger.warn.mock.calls[0][0]).toContain('boom');
+});
+
+test('the optimiser resolves the same environment as the child, apart from the browser tag and stdin owner watch', async () => {
+  process.env.BETTER_AUTH_URL = 'http://localhost:3000';
+  try {
+    const context = createContext();
+    context.mailSink = {};
+
+    const started = startFirstServer(context);
+    await flush();
+    processes[0].emit('exit', 0);
+    await started;
+
+    const optimiserEnv = mockSpawn.mock.calls[0][2].env;
+    // The child alone has its stdin held by the manager, so only it exits when
+    // that pipe closes.
+    const { LOWDEFY_BROWSER_TAG, LOWDEFY_EXIT_ON_STDIN_CLOSE, ...childEnv } =
+      mockSpawn.mock.calls[1][2].env;
+    expect(LOWDEFY_BROWSER_TAG).toBeDefined();
+    expect(LOWDEFY_EXIT_ON_STDIN_CLOSE).toBe('1');
+    expect(optimiserEnv).toEqual(childEnv);
+    expect(optimiserEnv.BETTER_AUTH_URL).toBe('http://localhost:3210');
+    expect(optimiserEnv.LOWDEFY_SERVER_DEV_MAIL_SINK).toBe('true');
+    expect(optimiserEnv.LOWDEFY_DIRECTORY_CONFIG).toBe('/apps/tenant');
+  } finally {
+    delete process.env.BETTER_AUTH_URL;
+  }
+});
+
+test('a watcher sync during the optimise waits for the first start and restarts nothing', async () => {
+  const context = createContext();
+  context.serverArtifacts = createTracker({ 'build/config.json': 'a', 'package.json': 'a' });
+  context.restartServer = jest.fn(async () => startServer(context));
+
+  const started = startFirstServer(context);
+  await flush();
+  // A late file event from the initial build: its batch syncs during the optimise.
+  let synced = false;
+  const sync = context.syncServer().then(() => {
+    synced = true;
+  });
+  await flush();
+  expect(synced).toBe(false);
+
+  processes[0].emit('exit', 0);
+  await Promise.all([started, sync]);
+
+  expect(synced).toBe(true);
+  expect(context.restartServer).not.toHaveBeenCalled();
+  // The optimiser and one child.
+  expect(mockSpawn).toHaveBeenCalledTimes(2);
+  expect(mockSpawn.mock.calls[1][1]).toContain('--host');
+});
+
+test('a config edit during the optimise is rebuilt at once, and its sync resolves after the first start', async () => {
+  const context = createContext();
+  const files = { 'build/config.json': 'a', 'package.json': 'a' };
+  context.serverArtifacts = createTracker(files);
+  context.lowdefyBuild = jest.fn(async () => {
+    files['build/config.json'] = 'b';
+  });
+  context.restartServer = jest.fn(async () => {
+    context.serverArtifacts.record();
+    startServer(context);
+  });
+
+  const started = startFirstServer(context);
+  await flush();
+  // The lowdefyBuildWatcher batch for the edit.
+  let childrenAtSync;
+  const batch = (async () => {
+    await context.lowdefyBuild();
+    await context.syncServer();
+    childrenAtSync = mockSpawn.mock.calls.length;
+  })();
+  await flush();
+  expect(context.lowdefyBuild).toHaveBeenCalledTimes(1);
+  expect(childrenAtSync).toBeUndefined();
+
+  processes[0].emit('exit', 0);
+  await Promise.all([started, batch]);
+
+  // The child may have read the edited config at spawn; one restart covers the window.
+  expect(context.restartServer).toHaveBeenCalledTimes(1);
+  expect(childrenAtSync).toBe(3);
+});
+
+test('a plugin package added during the optimise is installed by the queued sync', async () => {
+  const context = createContext();
+  const files = { 'build/config.json': 'a', 'package.json': 'a' };
+  context.serverArtifacts = createTracker(files);
+  const events = [];
+  context.buildActivity = { track: (task) => task() };
+  context.installPlugins = jest.fn(async () => events.push('install'));
+  context.lowdefyBuild = jest.fn(async () => events.push('build'));
+  context.restartServer = jest.fn(async () => events.push('restart'));
+  let finishOptimise;
+  context.optimizeDependencies = jest.fn(async () => events.push('optimise'));
+  context.optimizeDependencies.mockImplementationOnce(
+    () =>
+      new Promise((resolve) => {
+        events.push('first optimise');
+        finishOptimise = resolve;
+      })
+  );
+  context.syncServer = syncServer(context);
+
+  const started = startFirstServer(context);
+  await flush();
+  // A config build during the optimise adds a plugin package to package.json.
+  files['package.json'] = 'b';
+  const sync = context.syncServer();
+  finishOptimise();
+  await Promise.all([started, sync]);
+
+  // The first child spawns with the new package.json, but it was never
+  // installed: the baseline is the one from before the optimise.
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+  expect(events).toEqual(['first optimise', 'install', 'build', 'optimise', 'restart']);
+});
+
+test('startFirstServer resolves once the first child answers, before a queued sync restarts it', async () => {
+  const context = createContext();
+  const files = { 'build/config.json': 'a', 'package.json': 'a' };
+  context.serverArtifacts = createTracker(files);
+  context.restartServer = jest.fn(async () => {
+    context.serverArtifacts.record();
+    startServer(context);
+  });
+  let answer;
+  mockWaitForServer.mockImplementationOnce(
+    () =>
+      new Promise((resolve) => {
+        answer = resolve;
+      })
+  );
+
+  const started = startFirstServer(context);
+  await flush();
+  // A config edit built during the optimise: its sync restarts the child.
+  files['build/config.json'] = 'b';
+  const sync = context.syncServer();
+  processes[0].emit('exit', 0);
+  await flush();
+
+  // The first child is waited on, and nothing restarts it before it answers,
+  // or the manager would never record the server as ready.
+  expect(mockWaitForServer).toHaveBeenCalledTimes(1);
+  expect(mockWaitForServer.mock.calls[0][0].child).toBe(processes[1]);
+  expect(context.restartServer).not.toHaveBeenCalled();
+
+  answer(true);
+  expect(await started).toBe(true);
+  await sync;
+  expect(context.restartServer).toHaveBeenCalledTimes(1);
+});
+
+test('startFirstServer marks the server ready when the first child answers', async () => {
+  const context = createContext();
+
+  const started = startFirstServer(context);
+  await flush();
+  processes[0].emit('exit', 0);
+
+  expect(await started).toBe(true);
+  expect(context.markServerReady).toHaveBeenCalledTimes(1);
+});
+
+test('a restart marks the server ready when the first child exited without answering', async () => {
+  const context = createContext();
+  context.buildActivity = { track: (task) => task() };
+  context.restartServer = restartServer(context);
+  context.serverArtifacts = createTracker({ 'build/config.json': 'a', 'package.json': 'a' });
+  // The first child exits at start (a plugin that fails to load): neither
+  // its wait nor the later one sees an answer. The restarted child answers.
+  mockWaitForServer.mockImplementationOnce(async () => false);
+  mockWaitForServer.mockImplementationOnce(async () => false);
+
+  const started = startFirstServer(context);
+  await flush();
+  processes[0].emit('exit', 0);
+  expect(await started).toBe(false);
+  await flush();
+  expect(context.markServerReady).not.toHaveBeenCalled();
+
+  // The fix to the plugin is a server-side plugin edit, which restarts.
+  await context.syncServer({ restart: true });
+
+  expect(mockSpawn).toHaveBeenCalledTimes(3);
+  expect(mockWaitForServer.mock.calls[2][0].child).toBe(processes[2]);
+  expect(context.markServerReady).toHaveBeenCalledTimes(1);
+});

package/manager/processes/startMailSink.mjs

@@ -0,0 +1,135 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import getMailOutboxDirectory from '../../lib/docs/getMailOutboxDirectory.js';
+
+/*
+With LOWDEFY_DEV_SMTP_PORT set, the dev server receives mail over SMTP on that
+loopback port and keeps it instead of delivering it: each message becomes one
+JSON file in <app>/.lowdefy/mail/, which journeys (the `email` step), agents and
+people read. The app sends through its own SMTP connection, pointed at this
+port by its own secrets, so the whole send path - connection config, delivery
+filter, nodemailer, templates - runs exactly as in production. The manager owns
+the listener so it survives restarts of the server child, and tells each child
+it is listening (startServer passes LOWDEFY_SERVER_DEV_MAIL_SINK), so a port
+added to .env after start is not mistaken for a running sink. The outbox is
+cleared at start, so a test run only ever sees the mail it caused.
+*/
+
+function readSmtpPort() {
+  const value = process.env.LOWDEFY_DEV_SMTP_PORT;
+  if (value === undefined || value === '') {
+    return undefined;
+  }
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`LOWDEFY_DEV_SMTP_PORT must be a port number. Received "${value}".`);
+  }
+  return port;
+}
+
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function createMessageWriter({ directory, PostalMime }) {
+  let sequence = 0;
+  return async function writeMessage({ raw, envelope }) {
+    // Numbered on arrival, before the parse, so the outbox order is the order
+    // the app sent in even when two parses finish out of order.
+    sequence += 1;
+    const id = String(sequence).padStart(6, '0');
+    const parsed = await PostalMime.parse(raw);
+    const message = {
+      id,
+      receivedAt: new Date().toISOString(),
+      from: envelope.mailFrom ? envelope.mailFrom.address : null,
+      to: envelope.rcptTo.map(({ address }) => address),
+      subject: parsed.subject ?? '',
+      html: parsed.html ?? null,
+      text: parsed.text ?? null,
+    };
+    const filePath = path.join(directory, `${id}.json`);
+    await fs.promises.writeFile(`${filePath}.tmp`, JSON.stringify(message, null, 2));
+    await fs.promises.rename(`${filePath}.tmp`, filePath);
+  };
+}
+
+function listen({ server, port }) {
+  return new Promise((resolve, reject) => {
+    function onError(error) {
+      if (error.code === 'EADDRINUSE') {
+        reject(
+          new Error(
+            `LOWDEFY_DEV_SMTP_PORT ${port} is already in use. Stop the other process or choose another port.`
+          )
+        );
+        return;
+      }
+      reject(error);
+    }
+    server.once('error', onError);
+    server.listen(port, '127.0.0.1', () => {
+      server.removeListener('error', onError);
+      resolve();
+    });
+  });
+}
+
+async function startMailSink(context) {
+  const port = readSmtpPort();
+  if (port === undefined) {
+    return null;
+  }
+  // Loaded only when capture is on: a dev server that never receives mail
+  // never loads an SMTP server.
+  const [{ default: PostalMime }, { default: smtpServer }] = await Promise.all([
+    import('postal-mime'),
+    import('smtp-server'),
+  ]);
+  const directory = getMailOutboxDirectory({ configDirectory: context.directories.config });
+  fs.rmSync(directory, { recursive: true, force: true });
+  fs.mkdirSync(directory, { recursive: true });
+  const writeMessage = createMessageWriter({ directory, PostalMime });
+
+  const server = new smtpServer.SMTPServer({
+    authOptional: true,
+    disabledCommands: ['AUTH', 'STARTTLS'],
+    logger: false,
+    onData(stream, session, callback) {
+      // The SMTP reply waits for the file, so by the time the app's send
+      // resolves the message is readable.
+      readStream(stream)
+        .then((raw) => writeMessage({ raw, envelope: session.envelope }))
+        .then(() => callback(), callback);
+    },
+  });
+  await listen({ server, port });
+  server.on('error', (error) => context.logger.error(error));
+  context.logger.info(
+    `Capturing mail sent to SMTP 127.0.0.1:${port} in ${directory} instead of delivering it.`
+  );
+  return server;
+}
+
+export default startMailSink;

package/manager/processes/startMailSink.test.mjs

@@ -0,0 +1,146 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+import { jest } from '@jest/globals';
+import nodemailer from 'nodemailer';
+
+import readMailOutbox from '../../lib/docs/readMailOutbox.js';
+
+const { default: startMailSink } = await import('./startMailSink.mjs');
+
+function getFreePort() {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+let configDirectory;
+let sink;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-mail-sink-'));
+});
+
+afterEach(async () => {
+  if (sink) {
+    await new Promise((resolve) => sink.close(resolve));
+  }
+  sink = undefined;
+  delete process.env.LOWDEFY_DEV_SMTP_PORT;
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+function createContext() {
+  return {
+    directories: { config: configDirectory },
+    logger: { info: jest.fn(), error: jest.fn() },
+  };
+}
+
+test('startMailSink keeps a message sent through nodemailer with its recipients, subject and links intact', async () => {
+  const port = await getFreePort();
+  process.env.LOWDEFY_DEV_SMTP_PORT = String(port);
+  const staleDirectory = path.join(configDirectory, '.lowdefy', 'mail');
+  fs.mkdirSync(staleDirectory, { recursive: true });
+  fs.writeFileSync(path.join(staleDirectory, '000001.json'), '{"subject":"previous run"}');
+  sink = await startMailSink(createContext());
+
+  // Long enough that quoted-printable folds it across lines, and full of `=`,
+  // which quoted-printable escapes: the stored link must still be the one sent.
+  const link = `http://localhost:3210/api/auth/verify-email?token=${'eyJhbGciOiJIUzI1NiJ9'.repeat(
+    8
+  )}&callbackURL=%2Fverify-email`;
+  const transport = nodemailer.createTransport({ host: '127.0.0.1', port, secure: false });
+  await transport.sendMail({
+    from: 'app@localhost',
+    to: 'Ada Lovelace <ada@example.test>',
+    bcc: 'audit@example.test',
+    subject: 'Verify your email address — café',
+    html: `<p>Hello</p><a href="${link}" target="_blank">Verify email address</a>`,
+    text: `Verify: ${link}`,
+  });
+  transport.close();
+
+  const messages = await readMailOutbox({ configDirectory });
+  expect(messages).toHaveLength(1);
+  expect(messages[0]).toMatchObject({
+    id: '000001',
+    from: 'app@localhost',
+    to: ['ada@example.test', 'audit@example.test'],
+    subject: 'Verify your email address — café',
+  });
+  expect(messages[0].text.trim()).toEqual(`Verify: ${link}`);
+  expect(messages[0].html).toContain(`href="${link}"`);
+  expect(Number.isNaN(Date.parse(messages[0].receivedAt))).toBe(false);
+});
+
+test('startMailSink numbers messages in the order they arrive', async () => {
+  const port = await getFreePort();
+  process.env.LOWDEFY_DEV_SMTP_PORT = String(port);
+  sink = await startMailSink(createContext());
+  const transport = nodemailer.createTransport({ host: '127.0.0.1', port, secure: false });
+  await transport.sendMail({ from: 'app@localhost', to: 'a@example.test', subject: 'First' });
+  await transport.sendMail({ from: 'app@localhost', to: 'a@example.test', subject: 'Second' });
+  transport.close();
+
+  const messages = await readMailOutbox({ configDirectory });
+  expect(messages.map(({ id, subject }) => [id, subject])).toEqual([
+    ['000001', 'First'],
+    ['000002', 'Second'],
+  ]);
+});
+
+test('startMailSink starts nothing and leaves the outbox alone when LOWDEFY_DEV_SMTP_PORT is unset', async () => {
+  const outbox = path.join(configDirectory, '.lowdefy', 'mail');
+  fs.mkdirSync(outbox, { recursive: true });
+  fs.writeFileSync(path.join(outbox, '000001.json'), '{}');
+  expect(await startMailSink(createContext())).toBe(null);
+  expect(fs.readdirSync(outbox)).toEqual(['000001.json']);
+});
+
+test.each(['smtp', '2525.5', '0', '70000'])(
+  'startMailSink rejects LOWDEFY_DEV_SMTP_PORT "%s"',
+  async (value) => {
+    process.env.LOWDEFY_DEV_SMTP_PORT = value;
+    await expect(startMailSink(createContext())).rejects.toThrow(
+      `LOWDEFY_DEV_SMTP_PORT must be a port number. Received "${value}".`
+    );
+  }
+);
+
+test('startMailSink fails with the port when LOWDEFY_DEV_SMTP_PORT is taken', async () => {
+  const blocker = net.createServer();
+  const port = await new Promise((resolve) => {
+    blocker.listen(0, '127.0.0.1', () => resolve(blocker.address().port));
+  });
+  process.env.LOWDEFY_DEV_SMTP_PORT = String(port);
+  try {
+    await expect(startMailSink(createContext())).rejects.toThrow(
+      `LOWDEFY_DEV_SMTP_PORT ${port} is already in use.`
+    );
+  } finally {
+    await new Promise((resolve) => blocker.close(resolve));
+  }
+});