@lowdefy/server-dev 6.1.0 → 7.1.0

package/manager/processes/startServer.test.mjs

@@ -0,0 +1,155 @@
+/*
+  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();
+jest.unstable_mockModule('child_process', () => ({ spawn: mockSpawn }));
+jest.unstable_mockModule('../utils/readBasePath.mjs', () => ({ default: () => '' }));
+
+const { default: startServer } = await import('./startServer.mjs');
+
+function createContext({ mailSink }) {
+  return {
+    bin: { vite: 'vite.js' },
+    directories: { config: '/apps/tenant' },
+    instance: { update: jest.fn() },
+    internalPort: 3211,
+    logger: { debug: jest.fn(), error: jest.fn(), info: jest.fn() },
+    mailSink,
+    options: { port: 3210 },
+    serverArtifacts: { record: jest.fn() },
+    shutdownServer: jest.fn(),
+    version: '7.2.0',
+  };
+}
+
+beforeEach(() => {
+  mockSpawn.mockImplementation(() =>
+    Object.assign(new EventEmitter(), { stderr: new EventEmitter() })
+  );
+  process.env.LOWDEFY_DEV_SMTP_PORT = '2525';
+});
+
+afterEach(() => {
+  delete process.env.LOWDEFY_DEV_SMTP_PORT;
+  delete process.env.BETTER_AUTH_URL;
+});
+
+test.each([
+  ['tells the child a mail sink listens when the manager started one', {}, 'true'],
+  // The port alone, e.g. added to .env after start, starts no sink.
+  ['tells the child nothing when no sink listens, even with the port set', null, undefined],
+])('startServer %s', (_, mailSink, expected) => {
+  startServer(createContext({ mailSink }));
+
+  const { env } = mockSpawn.mock.calls[0][2];
+  expect(env.LOWDEFY_SERVER_DEV_MAIL_SINK).toBe(expected);
+  expect(env.LOWDEFY_DEV_SMTP_PORT).toBe('2525');
+});
+
+test('startServer moves a localhost BETTER_AUTH_URL onto the public dev port, and says so once', () => {
+  process.env.BETTER_AUTH_URL = 'http://localhost:3000';
+  const context = createContext({ mailSink: null });
+
+  startServer(context);
+  startServer(context);
+
+  const { env } = mockSpawn.mock.calls[0][2];
+  expect(env.BETTER_AUTH_URL).toBe('http://localhost:3210');
+  expect(mockSpawn.mock.calls[1][2].env.BETTER_AUTH_URL).toBe('http://localhost:3210');
+  expect(context.logger.info).toHaveBeenCalledTimes(1);
+  expect(context.logger.info.mock.calls[0][0]).toContain('http://localhost:3210');
+});
+
+test('startServer passes a non-loopback BETTER_AUTH_URL through', () => {
+  process.env.BETTER_AUTH_URL = 'https://dev.example.ngrok.app';
+  const context = createContext({ mailSink: null });
+
+  startServer(context);
+
+  expect(mockSpawn.mock.calls[0][2].env.BETTER_AUTH_URL).toBe('https://dev.example.ngrok.app');
+  expect(context.logger.info).not.toHaveBeenCalled();
+});
+
+test('startServer leaves BETTER_AUTH_URL unset when none is configured', () => {
+  startServer(createContext({ mailSink: null }));
+
+  expect(mockSpawn.mock.calls[0][2].env.BETTER_AUTH_URL).toBeUndefined();
+});
+
+test('startServer gives every child start its own browser tag', () => {
+  const context = createContext({ mailSink: null });
+
+  startServer(context);
+  startServer(context);
+
+  const first = mockSpawn.mock.calls[0][2].env.LOWDEFY_BROWSER_TAG;
+  const second = mockSpawn.mock.calls[1][2].env.LOWDEFY_BROWSER_TAG;
+  expect(first).toMatch(/^[0-9a-f-]{36}$/);
+  expect(second).toMatch(/^[0-9a-f-]{36}$/);
+  expect(second).not.toBe(first);
+});
+
+test('startServer kills the browser carrying the child tag when the child exits', () => {
+  const context = createContext({ mailSink: null });
+  startServer(context);
+  const tag = mockSpawn.mock.calls[0][2].env.LOWDEFY_BROWSER_TAG;
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+
+  context.devServer.emit('exit', null, 'SIGKILL');
+
+  if (process.platform === 'win32') {
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+    return;
+  }
+  expect(mockSpawn).toHaveBeenCalledTimes(2);
+  expect(mockSpawn.mock.calls[1][0]).toBe('pkill');
+  expect(mockSpawn.mock.calls[1][1]).toEqual(['-f', '--', `--lowdefy-browser-tag=${tag}`]);
+});
+
+test('startServer spawns the child with gc exposed, for its idle GC', () => {
+  startServer(createContext({ mailSink: null }));
+
+  const [command, args] = mockSpawn.mock.calls[0];
+  expect(command).toBe('node');
+  expect(args.slice(0, 2)).toEqual(['--expose-gc', 'vite.js']);
+});
+
+test('startServer holds the child stdin and tells it to exit when the pipe closes', () => {
+  process.env.LOWDEFY_EXIT_WITH_PID = '4242';
+  process.env.LOWDEFY_SERVER_REGISTRY_DIR = '/home/dev/.lowdefy/servers';
+  try {
+    startServer(createContext({ mailSink: null }));
+  } finally {
+    delete process.env.LOWDEFY_EXIT_WITH_PID;
+    delete process.env.LOWDEFY_SERVER_REGISTRY_DIR;
+  }
+
+  const { env, stdio } = mockSpawn.mock.calls[0][2];
+  expect(stdio[0]).toBe('pipe');
+  expect(env.LOWDEFY_EXIT_ON_STDIN_CLOSE).toBe('1');
+  expect(env.LOWDEFY_EXIT_WITH_PID).toBeUndefined();
+  expect(env.LOWDEFY_SERVER_REGISTRY_DIR).toBeUndefined();
+});
+
+test('startServer tells the child the Lowdefy version it reports to MCP clients', () => {
+  startServer(createContext({ mailSink: null }));
+
+  expect(mockSpawn.mock.calls[0][2].env.LOWDEFY_SERVER_DEV_VERSION).toBe('7.2.0');
+});

package/manager/processes/startWatchers.mjs

@@ -16,16 +16,18 @@
 
 import envWatcher from '../watchers/envWatcher.mjs';
 import lowdefyBuildWatcher from '../watchers/lowdefyBuildWatcher.mjs';
-import moduleBuildWatcher from '../watchers/moduleBuildWatcher.mjs';
-import serverArtifactWatcher from '../watchers/serverArtifactWatcher.mjs';
+import pluginSourceWatcher from '../watchers/pluginSourceWatcher.mjs';
+import restartRequestWatcher from '../watchers/restartRequestWatcher.mjs';
+import serverPackageWatcher from '../watchers/serverPackageWatcher.mjs';
 
 function startWatchers(context) {
   return async () => {
     await Promise.all([
       envWatcher(context),
       lowdefyBuildWatcher(context),
-      moduleBuildWatcher(context),
-      serverArtifactWatcher(context),
+      pluginSourceWatcher(context),
+      restartRequestWatcher(context),
+      serverPackageWatcher(context),
     ]);
   };
 }

package/manager/processes/syncServer.mjs

@@ -0,0 +1,69 @@
+/*
+  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.
+*/
+
+// Brings the running server up to date with the build: installs plugin
+// packages added to the server's package.json (by a config build, or by a
+// page build that found a missing package) and rebuilds so the plugin imports
+// include them, then restarts the server when anything it read at start
+// changed, or when the caller needs a new process anyway (.env, local plugin
+// code). Every watcher calls it after its build, so the restart a build
+// needs is part of that watcher's batch and a build-status wait covers it.
+// Calls run one at a time, after the first child start (startFirst): the
+// second finds the first's work done.
+function syncServer(context) {
+  async function sync({ restart = false } = {}) {
+    const changes = context.serverArtifacts.check();
+    if (changes.install) {
+      context.shutdownServer();
+      context.logger.warn('Plugin dependencies have changed and will be reinstalled.');
+      try {
+        await context.installPlugins();
+        await context.lowdefyBuild();
+        // The new plugins' dependencies are optimised in a short-lived
+        // process, so the restarted child starts warm (optimizeDependencies.mjs).
+        await context.buildActivity.track(() => context.optimizeDependencies());
+      } finally {
+        await context.restartServer();
+      }
+      return;
+    }
+    if (restart || changes.restart) {
+      await context.restartServer();
+    }
+  }
+
+  // The first child start heads the queue. The watchers start right after the
+  // initial build, so a batch can sync before the first child exists; it
+  // waits here instead of comparing against artifacts no child has read.
+  let runFirstStart;
+  const firstStart = new Promise((resolve) => {
+    runFirstStart = resolve;
+  }).then((start) => start());
+  let previous = firstStart.catch(() => {});
+
+  function queueSync(options) {
+    const next = previous.then(() => sync(options));
+    previous = next.catch(() => {});
+    return next;
+  }
+  queueSync.startFirst = (start) => {
+    runFirstStart(start);
+    return firstStart;
+  };
+  return queueSync;
+}
+
+export default syncServer;

package/manager/processes/syncServer.test.mjs

@@ -0,0 +1,141 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import syncServer from './syncServer.mjs';
+
+function createContext(changes) {
+  const events = [];
+  const record = (name, implementation = async () => {}) =>
+    jest.fn(async () => {
+      events.push(name);
+      return implementation();
+    });
+  return {
+    events,
+    buildActivity: {
+      track: jest.fn(async (task) => {
+        events.push('track');
+        return task();
+      }),
+    },
+    installPlugins: record('install'),
+    logger: { warn: jest.fn() },
+    lowdefyBuild: record('build'),
+    optimizeDependencies: record('optimize'),
+    restartServer: record('restart'),
+    serverArtifacts: { check: jest.fn(() => changes) },
+    shutdownServer: jest.fn(() => events.push('shutdown')),
+  };
+}
+
+// A queue whose first child start has run, as it has once run.mjs reaches startFirstServer.
+function createStartedSync(context) {
+  const sync = syncServer(context);
+  sync.startFirst(async () => {});
+  return sync;
+}
+
+test.each([
+  ['restarts when a server artifact changed', { install: false, restart: true }, {}, ['restart']],
+  ['does nothing when nothing changed', { install: false, restart: false }, {}, []],
+  ['restarts when asked to', { install: false, restart: false }, { restart: true }, ['restart']],
+  [
+    'installs new plugin packages, rebuilds, optimises them as build activity and restarts once',
+    { install: true, restart: true },
+    {},
+    ['shutdown', 'install', 'build', 'track', 'optimize', 'restart'],
+  ],
+])('syncServer %s', async (_, changes, options, expected) => {
+  const context = createContext(changes);
+
+  await createStartedSync(context)(options);
+
+  expect(context.events).toEqual(expected);
+});
+
+test('syncServer restarts the server after an install even when the rebuild fails', async () => {
+  const context = createContext({ install: true, restart: true });
+  context.lowdefyBuild.mockRejectedValueOnce(new Error('Build failed'));
+
+  await expect(createStartedSync(context)()).rejects.toThrow('Build failed');
+  expect(context.events).toEqual(['shutdown', 'install', 'restart']);
+});
+
+test('syncServer runs one sync at a time', async () => {
+  const context = createContext({ install: false, restart: true });
+  let finishFirst;
+  context.restartServer.mockImplementationOnce(
+    () =>
+      new Promise((resolve) => {
+        context.events.push('first restart');
+        finishFirst = resolve;
+      })
+  );
+  const sync = createStartedSync(context);
+  const first = sync();
+  const second = sync();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(context.serverArtifacts.check).toHaveBeenCalledTimes(1);
+  finishFirst();
+  await Promise.all([first, second]);
+
+  expect(context.serverArtifacts.check).toHaveBeenCalledTimes(2);
+});
+
+test('syncServer holds syncs until the first child start has run, then runs them after it', async () => {
+  const context = createContext({ install: false, restart: false });
+  const sync = syncServer(context);
+
+  let synced = false;
+  const queued = sync().then(() => {
+    synced = true;
+  });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(synced).toBe(false);
+  expect(context.serverArtifacts.check).not.toHaveBeenCalled();
+
+  let finishStart;
+  const started = sync.startFirst(
+    () =>
+      new Promise((resolve) => {
+        context.events.push('first start');
+        finishStart = resolve;
+      })
+  );
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(context.events).toEqual(['first start']);
+  expect(synced).toBe(false);
+
+  finishStart();
+  await Promise.all([started, queued]);
+  expect(synced).toBe(true);
+  expect(context.serverArtifacts.check).toHaveBeenCalledTimes(1);
+});
+
+test('syncServer still runs queued syncs when the first child start fails', async () => {
+  const context = createContext({ install: false, restart: true });
+  const sync = syncServer(context);
+
+  const queued = sync();
+  await expect(
+    sync.startFirst(async () => Promise.reject(new Error('spawn failed')))
+  ).rejects.toThrow('spawn failed');
+  await queued;
+
+  expect(context.events).toEqual(['restart']);
+});

package/manager/processes/waitForDevServer.mjs

@@ -0,0 +1,48 @@
+/*
+  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 waitForServer from '../utils/waitForServer.mjs';
+
+// Waits for the child just started (by the first start or a restart) to
+// answer, and resolves with whether it answered within the wait. Whichever
+// child answers first marks the server ready: a first child that exits at
+// start (a plugin that fails to load) leaves it to a later restart.
+//
+// A child still running when the wait ends may yet answer - a first start on
+// a loaded machine has taken two and a half minutes. Its first answer still
+// marks the server ready, or the hub would judge a working server stalled and
+// stop it. That later wait holds up nothing, and ends when the child exits
+// (a restart replaces it, or it crashes), so a child that never answers is
+// never marked ready.
+async function waitForDevServer(context) {
+  const options = {
+    basePath: context.basePath,
+    child: context.devServer,
+    port: context.internalPort,
+  };
+  if (await waitForServer(options)) {
+    context.markServerReady();
+    return true;
+  }
+  waitForServer({ ...options, timeoutMs: Infinity }).then((answered) => {
+    if (answered) {
+      context.markServerReady();
+    }
+  });
+  return false;
+}
+
+export default waitForDevServer;

package/manager/processes/waitForDevServer.test.mjs

@@ -0,0 +1,112 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import waitForDevServer from './waitForDevServer.mjs';
+
+const STEP_MS = 250;
+
+// The child's /api/ping: refused until answerAt, then ok. Date.now is faked,
+// so the wait's two-minute deadline runs on the same clock.
+function stubPing({ answerAt }) {
+  global.fetch = jest.fn(async () => {
+    if (Date.now() >= answerAt) {
+      return { ok: true };
+    }
+    throw new Error('connect ECONNREFUSED');
+  });
+}
+
+function createContext() {
+  return {
+    basePath: '',
+    devServer: { exitCode: null, signalCode: null },
+    internalPort: 3211,
+    markServerReady: jest.fn(),
+  };
+}
+
+async function advance(ms) {
+  for (let elapsed = 0; elapsed < ms; elapsed += STEP_MS) {
+    jest.advanceTimersByTime(STEP_MS);
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+
+const originalFetch = global.fetch;
+
+beforeEach(() => {
+  jest.useFakeTimers({ doNotFake: ['performance', 'setImmediate'] });
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+  global.fetch = originalFetch;
+});
+
+test('waitForDevServer marks the server ready when the child answers within the wait', async () => {
+  stubPing({ answerAt: Date.now() + 10000 });
+  const context = createContext();
+
+  let answered;
+  waitForDevServer(context).then((result) => {
+    answered = result;
+  });
+  await advance(11000);
+
+  expect(answered).toBe(true);
+  expect(context.markServerReady).toHaveBeenCalledTimes(1);
+});
+
+test('waitForDevServer marks the server ready when the child answers after the two-minute wait', async () => {
+  stubPing({ answerAt: Date.now() + 150000 });
+  const context = createContext();
+
+  let answered;
+  waitForDevServer(context).then((result) => {
+    answered = result;
+  });
+  await advance(121000);
+
+  // The manager warns that the server did not answer, and the record stays starting.
+  expect(answered).toBe(false);
+  expect(context.markServerReady).not.toHaveBeenCalled();
+
+  await advance(30000);
+  expect(context.markServerReady).toHaveBeenCalledTimes(1);
+});
+
+test('waitForDevServer never marks a child ready that exits without answering', async () => {
+  stubPing({ answerAt: Infinity });
+  const context = createContext();
+
+  let answered;
+  waitForDevServer(context).then((result) => {
+    answered = result;
+  });
+  await advance(121000);
+  expect(answered).toBe(false);
+
+  // A restart replaces the child: the old one exits, and the wait for it ends.
+  context.devServer.signalCode = 'SIGTERM';
+  await advance(1000);
+  const pings = global.fetch.mock.calls.length;
+  await advance(60000);
+
+  expect(global.fetch).toHaveBeenCalledTimes(pings);
+  expect(context.markServerReady).not.toHaveBeenCalled();
+});