@lowdefy/server-dev 6.0.0 → 7.0.0

package/manager/processes/lowdefyBuild.test.mjs

@@ -21,6 +21,7 @@ const mockSerializeBuildException = jest.fn((exception) => ({ message: exception
 const mockWriteBuildStatus = jest.fn();
 const mockCreateCustomPluginTypesMap = jest.fn().mockResolvedValue({});
 const mockCreateCustomPluginMessagesMap = jest.fn().mockResolvedValue({});
+const mockPublishBuildDirectory = jest.fn(async () => {});
 
 jest.unstable_mockModule('@lowdefy/build/dev', () => ({
   shallowBuild: mockShallowBuild,
@@ -35,12 +36,15 @@ jest.unstable_mockModule('../utils/createCustomPluginTypesMap.mjs', () => ({
 jest.unstable_mockModule('../utils/createCustomPluginMessagesMap.mjs', () => ({
   default: mockCreateCustomPluginMessagesMap,
 }));
+jest.unstable_mockModule('../utils/publishBuildDirectory.mjs', () => ({
+  default: mockPublishBuildDirectory,
+}));
 
 const { default: lowdefyBuild } = await import('./lowdefyBuild.mjs');
 
 function createContext() {
   return {
-    directories: { build: '/app/build' },
+    directories: { build: '/app/build', buildStaging: '/app/build-staging' },
     logger: { info: jest.fn() },
     options: { refResolver: undefined },
   };
@@ -100,3 +104,134 @@ test('lowdefyBuild falls back to the raw error message when the thrown error has
     warnings: [],
   });
 });
+
+test('lowdefyBuild writes an error buildStatus.json when lowdefy.yaml cannot be read for its plugins', async () => {
+  const context = createContext();
+  const parseError = new Error('All sequence items must start at the same column at line 7');
+  mockCreateCustomPluginTypesMap.mockRejectedValueOnce(parseError);
+
+  const build = lowdefyBuild(context);
+  await expect(build()).rejects.toBe(parseError);
+
+  expect(mockShallowBuild).not.toHaveBeenCalled();
+  expect(mockWriteBuildStatus).toHaveBeenCalledWith({
+    directories: context.directories,
+    status: 'error',
+    errors: [{ message: 'All sequence items must start at the same column at line 7' }],
+    warnings: [],
+  });
+});
+
+test('lowdefyBuild builds into the staging directory and then publishes it', async () => {
+  const context = createContext();
+  mockShallowBuild.mockResolvedValue({ components: {}, pageRegistry: {}, context: {} });
+
+  const build = lowdefyBuild(context);
+  await build();
+
+  expect(mockShallowBuild.mock.calls[0][0].directories).toEqual({
+    build: '/app/build-staging',
+    buildStaging: '/app/build-staging',
+  });
+  expect(mockPublishBuildDirectory).toHaveBeenCalledWith({
+    buildDirectory: '/app/build',
+    stagingDirectory: '/app/build-staging',
+  });
+  expect(mockPublishBuildDirectory.mock.invocationCallOrder[0]).toBeLessThan(
+    mockWriteBuildStatus.mock.invocationCallOrder[0]
+  );
+});
+
+test('lowdefyBuild leaves the live build in place when the build fails', async () => {
+  const context = createContext();
+  mockShallowBuild.mockRejectedValue(new Error('Build failed'));
+
+  const build = lowdefyBuild(context);
+  await expect(build()).rejects.toThrow('Build failed');
+
+  expect(mockPublishBuildDirectory).not.toHaveBeenCalled();
+});
+
+test('lowdefyBuild writes an error buildStatus.json and rethrows when publishing the build fails', async () => {
+  const context = createContext();
+  mockShallowBuild.mockResolvedValue({ components: {}, pageRegistry: {}, context: {} });
+  const renameError = new Error("EPERM: operation not permitted, rename 'a' -> 'b'");
+  mockPublishBuildDirectory.mockRejectedValueOnce(renameError);
+
+  const build = lowdefyBuild(context);
+  await expect(build()).rejects.toThrow(
+    "Publishing the build to /app/build failed: EPERM: operation not permitted, rename 'a' -> 'b'"
+  );
+
+  expect(mockWriteBuildStatus).toHaveBeenCalledTimes(1);
+  expect(mockWriteBuildStatus).toHaveBeenCalledWith({
+    directories: context.directories,
+    status: 'error',
+    errors: [
+      {
+        message:
+          "Publishing the build to /app/build failed: EPERM: operation not permitted, rename 'a' -> 'b'",
+      },
+    ],
+    warnings: [],
+  });
+});
+
+test('lowdefyBuild starts a build only after the previous one has finished', async () => {
+  const context = createContext();
+  const events = [];
+  let finishFirst;
+  mockShallowBuild
+    .mockImplementationOnce(() => {
+      events.push('first start');
+      return new Promise((resolve) => {
+        finishFirst = () => {
+          events.push('first end');
+          resolve({ components: {}, pageRegistry: {}, context: {} });
+        };
+      });
+    })
+    .mockImplementationOnce(async () => {
+      events.push('second start');
+      return { components: {}, pageRegistry: {}, context: {} };
+    });
+
+  const build = lowdefyBuild(context);
+  const first = build();
+  const second = build();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(events).toEqual(['first start']);
+  finishFirst();
+  await Promise.all([first, second]);
+
+  expect(events).toEqual(['first start', 'first end', 'second start']);
+});
+
+test('lowdefyBuild runs the next build after a failed one', async () => {
+  const context = createContext();
+  mockShallowBuild
+    .mockRejectedValueOnce(new Error('Build failed'))
+    .mockResolvedValueOnce({ components: {}, pageRegistry: {}, context: {} });
+
+  const build = lowdefyBuild(context);
+  const first = build();
+  const second = build();
+
+  await expect(first).rejects.toThrow('Build failed');
+  await expect(second).resolves.toEqual({ components: {}, pageRegistry: {}, context: {} });
+});
+
+test('lowdefyBuild reads the plugin types and messages maps in parallel', async () => {
+  const context = createContext();
+  let releaseTypes;
+  mockCreateCustomPluginTypesMap.mockImplementationOnce(
+    () => new Promise((resolve) => (releaseTypes = () => resolve({})))
+  );
+  mockShallowBuild.mockResolvedValue({ components: {}, pageRegistry: {}, context: {} });
+
+  const build = lowdefyBuild(context)();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(mockCreateCustomPluginMessagesMap).toHaveBeenCalledTimes(1);
+  releaseTypes();
+  await build;
+});

package/manager/processes/optimizeDependencies.mjs

@@ -0,0 +1,59 @@
+/*
+  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 { spawnProcess } from '@lowdefy/node-utils';
+
+import createServerEnv from '../utils/createServerEnv.mjs';
+
+// Runs Vite's dependency optimiser in a short-lived process before the Vite
+// child starts, so the long-lived child starts against a warm
+// node_modules/.vite/deps cache and never optimises itself. Rolldown keeps
+// 500-600 MB of native memory after optimising, and only ending the process
+// gives it back. With a valid cache this returns after resolving the config.
+// Runs after a build: vite.config.js reads build/config.json when it loads.
+function optimizeDependencies(context) {
+  return async () => {
+    const started = Date.now();
+    context.logger.debug('Optimizing dependencies...');
+    const stderr = [];
+    try {
+      await spawnProcess({
+        command: 'node',
+        args: [context.bin.vite, 'optimize'],
+        processOptions: {
+          cwd: context.directories.server,
+          env: createServerEnv(context),
+        },
+        stdOutLineHandler: (line) => context.logger.debug(line),
+        stdErrLineHandler: (line) => {
+          stderr.push(String(line));
+        },
+      });
+    } catch (error) {
+      // Never stops the server from starting: the child then optimises
+      // itself, as it did before this step existed.
+      context.logger.warn(
+        `Dependency optimization failed (${
+          error.message
+        }); the dev server optimizes on start instead.\n${stderr.slice(-20).join('\n')}`
+      );
+      return;
+    }
+    context.logger.debug(`Optimized dependencies in ${Date.now() - started} ms.`);
+  };
+}
+
+export default optimizeDependencies;

package/manager/processes/restartServer.mjs

@@ -15,14 +15,42 @@
 */
 
 import startServer from './startServer.mjs';
+import waitForChildExit from '../utils/waitForChildExit.mjs';
+import waitForDevServer from './waitForDevServer.mjs';
 
+// Resolves once the new server answers, and counts as build activity until
+// then, so lowdefy_build_status({ wait: true }) waits through a restart
+// instead of answering before it and leaving the next call to hit it.
 function restartServer(context) {
-  return () => {
-    context.shutdownServer();
-    context.logger.info({ spin: 'start' }, 'Restarting server...');
-    startServer(context);
-    context.logger.info({ spin: 'succeed' }, 'Restarted server.');
-  };
+  return () =>
+    context.buildActivity.track(async () => {
+      context.shutdownServer();
+      context.logger.info({ spin: 'start' }, 'Restarting server...');
+      // The new child binds the internal port with --strictPort, so it fails
+      // with "Port in use" if the old child is still exiting. A caller that
+      // shut the server down earlier (syncServer's install path) is covered
+      // too: the stopped child is kept until a restart has waited for it.
+      const stoppedChild = context.stoppedDevServer;
+      const exited = await waitForChildExit({ child: stoppedChild });
+      if (context.stoppedDevServer === stoppedChild) {
+        context.stoppedDevServer = null;
+      }
+      if (!exited) {
+        context.logger.warn(
+          `The old dev server (pid ${stoppedChild.pid}) did not exit after SIGKILL; starting the new one anyway.`
+        );
+      }
+      // What this server reads at start, so a later build restarts it only
+      // when one of those files changed.
+      context.serverArtifacts.record();
+      startServer(context);
+      const ready = await waitForDevServer(context);
+      if (ready) {
+        context.logger.info({ spin: 'succeed' }, 'Restarted server.');
+        return;
+      }
+      context.logger.warn('The restarted dev server did not answer - check the output above.');
+    });
 }
 
 export default restartServer;

package/manager/processes/restartServer.test.mjs

@@ -0,0 +1,162 @@
+/*
+  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 events = [];
+
+jest.unstable_mockModule('./startServer.mjs', () => ({
+  default: jest.fn((context) => {
+    events.push('start');
+    context.devServer = createChild();
+  }),
+}));
+jest.unstable_mockModule('../utils/waitForServer.mjs', () => ({
+  default: jest.fn(async () => true),
+}));
+
+function createChild() {
+  return Object.assign(new EventEmitter(), {
+    exitCode: null,
+    signalCode: null,
+    killed: false,
+    pid: 1234,
+    kill: jest.fn(),
+  });
+}
+
+async function createContext({ devServer = null } = {}) {
+  const { default: shutdownServer } = await import('./shutdownServer.mjs');
+  const context = {
+    buildActivity: { track: (fn) => fn() },
+    devServer,
+    logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn() },
+    markServerReady: jest.fn(),
+    serverArtifacts: { record: jest.fn() },
+  };
+  context.shutdownServer = shutdownServer(context);
+  return context;
+}
+
+beforeEach(() => {
+  events.length = 0;
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+async function flush() {
+  for (let i = 0; i < 10; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+async function advance(ms) {
+  await flush();
+  jest.advanceTimersByTime(ms);
+  await flush();
+}
+
+test('restartServer starts the new child only after the old child exits', async () => {
+  const { default: restartServer } = await import('./restartServer.mjs');
+  const oldChild = createChild();
+  const context = await createContext({ devServer: oldChild });
+
+  const restarting = restartServer(context)();
+  await flush();
+  expect(oldChild.kill).toHaveBeenCalledTimes(1);
+  expect(events).toEqual([]);
+
+  oldChild.signalCode = 'SIGTERM';
+  oldChild.emit('exit', null, 'SIGTERM');
+  await restarting;
+
+  expect(events).toEqual(['start']);
+  expect(context.devServer).not.toBe(oldChild);
+  expect(context.stoppedDevServer).toBe(null);
+  expect(context.logger.warn).not.toHaveBeenCalled();
+});
+
+test('restartServer SIGKILLs an old child that ignores SIGTERM, then starts the new child', async () => {
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  const { default: restartServer } = await import('./restartServer.mjs');
+  const oldChild = createChild();
+  oldChild.kill.mockImplementation((signal) => {
+    if (signal === 'SIGKILL') {
+      oldChild.signalCode = 'SIGKILL';
+      oldChild.emit('exit', null, 'SIGKILL');
+    }
+  });
+  const context = await createContext({ devServer: oldChild });
+
+  const restarting = restartServer(context)();
+  await flush();
+  expect(events).toEqual([]);
+  await advance(10000);
+  await restarting;
+
+  expect(oldChild.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(events).toEqual(['start']);
+  expect(context.logger.warn).not.toHaveBeenCalled();
+});
+
+test('restartServer finishes after both timeouts and warns when the old child never exits', async () => {
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  const { default: restartServer } = await import('./restartServer.mjs');
+  const oldChild = createChild();
+  const context = await createContext({ devServer: oldChild });
+
+  const restarting = restartServer(context)();
+  await advance(10000);
+  expect(events).toEqual([]);
+  await advance(5000);
+  await restarting;
+
+  expect(oldChild.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(events).toEqual(['start']);
+  expect(context.logger.warn).toHaveBeenCalledWith(expect.stringContaining('did not exit'));
+});
+
+test('restartServer waits for a child that syncServer shut down before installing', async () => {
+  const { default: restartServer } = await import('./restartServer.mjs');
+  const oldChild = createChild();
+  const context = await createContext({ devServer: oldChild });
+  context.shutdownServer();
+  expect(context.devServer).toBe(null);
+
+  const restarting = restartServer(context)();
+  await flush();
+  expect(events).toEqual([]);
+  oldChild.exitCode = 0;
+  oldChild.emit('exit', 0, null);
+  await restarting;
+
+  expect(events).toEqual(['start']);
+});
+
+test('restartServer with no previous child starts at once', async () => {
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  const { default: restartServer } = await import('./restartServer.mjs');
+  const context = await createContext();
+
+  await restartServer(context)();
+
+  expect(events).toEqual(['start']);
+  expect(jest.getTimerCount()).toBe(0);
+});

package/manager/processes/shutdownServer.mjs

@@ -20,6 +20,17 @@ function shutdownServer(context) {
       context.logger.debug(
         `Existing dev server with pid ${context.devServer.pid}, killed: ${context.devServer.killed}`
       );
+      const child = context.devServer;
+      // A signalled child keeps answering on the internal port until it
+      // exits; the proxy waits for this before probing for its replacement,
+      // or the probe would reach the old child and confirm the new one.
+      context.devServerExited =
+        child.exitCode !== null || child.signalCode !== null
+          ? Promise.resolve()
+          : new Promise((resolve) => child.once('exit', resolve));
+      // Kept so a restart can wait for this child to free the internal port,
+      // and SIGKILL it if it does not.
+      context.stoppedDevServer = child;
       if (!context.devServer.killed) {
         context.logger.info({ spin: 'start' }, 'Shutting down server...');
         context.devServer.kill();

package/manager/processes/shutdownServer.test.mjs

@@ -0,0 +1,45 @@
+/*
+  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';
+
+import shutdownServer from './shutdownServer.mjs';
+
+test('shutdownServer records when the stopped child has exited, for the proxy to wait on', async () => {
+  const child = Object.assign(new EventEmitter(), {
+    exitCode: null,
+    signalCode: null,
+    killed: false,
+    kill: jest.fn(),
+  });
+  const context = { devServer: child, logger: { debug: jest.fn(), info: jest.fn() } };
+
+  shutdownServer(context)();
+
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(context.devServer).toBe(null);
+  let exited = false;
+  context.devServerExited.then(() => {
+    exited = true;
+  });
+  await Promise.resolve();
+  expect(exited).toBe(false);
+  child.emit('exit', null, 'SIGTERM');
+  await context.devServerExited;
+  expect(exited).toBe(true);
+});

package/manager/processes/startFirstServer.mjs

@@ -0,0 +1,46 @@
+/*
+  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 startServer from './startServer.mjs';
+import waitForDevServer from './waitForDevServer.mjs';
+
+// The manager's first child start: dependencies are optimised in a
+// short-lived process first, so the child never runs the optimiser itself
+// (see optimizeDependencies.mjs). It runs at the head of syncServer's queue,
+// so a watcher batch during the optimise (a late file event from the initial
+// build, an edit) builds at once and syncs after this start, instead of
+// restarting a child that does not exist yet.
+//
+// The server artifacts are recorded before the optimise, not when the child
+// spawns: a build during the optimise that adds a plugin package to
+// package.json must still read as an install for the queued sync. An
+// artifact that changed in that window costs one extra restart at most.
+//
+// The wait for the child to answer is part of the start, as it is in
+// restartServer: a queued sync that restarted the child before it answered
+// would end the wait on the killed child, and the manager would never record
+// the server as ready. Resolves with whether the child answered within the
+// wait; waitForDevServer marks the server ready, also on a later answer.
+function startFirstServer(context) {
+  return context.syncServer.startFirst(async () => {
+    context.serverArtifacts.record();
+    await context.optimizeDependencies();
+    startServer(context);
+    return waitForDevServer(context);
+  });
+}
+
+export default startFirstServer;