@lowdefy/server-dev 5.5.1 → 6.0.0

package/manager/processes/installPlugins.mjs

@@ -14,21 +14,29 @@
   limitations under the License.
 */
 
-import { spawnProcess } from '@lowdefy/node-utils';
+import { installIfPackageJsonChanged, spawnProcess } from '@lowdefy/node-utils';
 
-function installPlugins({ logger, packageManagerCmd }) {
+function installPlugins({ directories, logger, packageManagerCmd }) {
   return async () => {
-    logger.info({ spin: 'start' }, 'Installing plugins...');
-    await spawnProcess({
-      processOptions: {
-        // https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2#command-injection-via-args-parameter-of-child_processspawn-without-shell-option-enabled-on-windows-cve-2024-27980---high
-        shell: process.platform === 'win32',
+    const installed = await installIfPackageJsonChanged({
+      directory: directories.server,
+      install: async () => {
+        logger.info({ spin: 'start' }, 'Installing plugins...');
+        await spawnProcess({
+          processOptions: {
+            // https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2#command-injection-via-args-parameter-of-child_processspawn-without-shell-option-enabled-on-windows-cve-2024-27980---high
+            shell: process.platform === 'win32',
+          },
+          command: packageManagerCmd,
+          args: ['install', '--no-frozen-lockfile'],
+          stdOutLineHandler: (line) => logger.debug(line),
+        });
+        logger.info('Installed plugins.');
       },
-      command: packageManagerCmd,
-      args: ['install', '--no-frozen-lockfile'],
-      stdOutLineHandler: (line) => logger.debug(line),
     });
-    logger.info('Installed plugins.');
+    if (!installed) {
+      logger.debug('Plugin dependencies unchanged, skipped install.');
+    }
   };
 }
 

package/manager/processes/lowdefyBuild.mjs

@@ -14,9 +14,10 @@
   limitations under the License.
 */
 
-import { shallowBuild } from '@lowdefy/build/dev';
+import { serializeBuildException, shallowBuild } from '@lowdefy/build/dev';
 import createCustomPluginMessagesMap from '../utils/createCustomPluginMessagesMap.mjs';
 import createCustomPluginTypesMap from '../utils/createCustomPluginTypesMap.mjs';
+import writeBuildStatus from '../utils/writeBuildStatus.mjs';
 
 function formatDuration(ms) {
   if (ms < 1000) return `${ms}ms`;
@@ -30,13 +31,34 @@ function lowdefyBuild({ directories, logger, options }) {
     const customTypesMap = await createCustomPluginTypesMap({ directories, logger });
     const customMessagesMap = await createCustomPluginMessagesMap({ directories, logger });
 
-    const result = await shallowBuild({
-      customMessagesMap,
-      customTypesMap,
+    let result;
+    try {
+      result = await shallowBuild({
+        customMessagesMap,
+        customTypesMap,
+        directories,
+        logger,
+        refResolver: options.refResolver,
+        stage: 'dev',
+      });
+    } catch (error) {
+      // Write the artifact after the attempt fails - the build may have
+      // cleaned the build directory before failing, so this must not run
+      // before the attempt completes.
+      await writeBuildStatus({
+        directories,
+        status: 'error',
+        errors: error.errors ?? [{ message: error.message }],
+        warnings: error.warnings ?? [],
+      });
+      throw error;
+    }
+
+    await writeBuildStatus({
       directories,
-      logger,
-      refResolver: options.refResolver,
-      stage: 'dev',
+      status: 'ok',
+      errors: [],
+      warnings: (result.context.warnings ?? []).map(serializeBuildException),
     });
 
     // Return result so getContext can store registries

package/manager/processes/lowdefyBuild.test.mjs

@@ -0,0 +1,102 @@
+/*
+  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';
+
+const mockShallowBuild = jest.fn();
+const mockSerializeBuildException = jest.fn((exception) => ({ message: exception.message }));
+const mockWriteBuildStatus = jest.fn();
+const mockCreateCustomPluginTypesMap = jest.fn().mockResolvedValue({});
+const mockCreateCustomPluginMessagesMap = jest.fn().mockResolvedValue({});
+
+jest.unstable_mockModule('@lowdefy/build/dev', () => ({
+  shallowBuild: mockShallowBuild,
+  serializeBuildException: mockSerializeBuildException,
+}));
+jest.unstable_mockModule('../utils/writeBuildStatus.mjs', () => ({
+  default: mockWriteBuildStatus,
+}));
+jest.unstable_mockModule('../utils/createCustomPluginTypesMap.mjs', () => ({
+  default: mockCreateCustomPluginTypesMap,
+}));
+jest.unstable_mockModule('../utils/createCustomPluginMessagesMap.mjs', () => ({
+  default: mockCreateCustomPluginMessagesMap,
+}));
+
+const { default: lowdefyBuild } = await import('./lowdefyBuild.mjs');
+
+function createContext() {
+  return {
+    directories: { build: '/app/build' },
+    logger: { info: jest.fn() },
+    options: { refResolver: undefined },
+  };
+}
+
+test('lowdefyBuild writes an ok buildStatus.json after a successful build', async () => {
+  const context = createContext();
+  const warning = { message: 'Deprecated feature used' };
+  mockShallowBuild.mockResolvedValue({
+    components: {},
+    pageRegistry: {},
+    context: { warnings: [warning] },
+  });
+
+  const build = lowdefyBuild(context);
+  await build();
+
+  expect(mockWriteBuildStatus).toHaveBeenCalledWith({
+    directories: context.directories,
+    status: 'ok',
+    errors: [],
+    warnings: [{ message: 'Deprecated feature used' }],
+  });
+  expect(mockSerializeBuildException).toHaveBeenCalledWith(warning, 0, [warning]);
+});
+
+test('lowdefyBuild writes an error buildStatus.json and rethrows when the build fails', async () => {
+  const context = createContext();
+  const buildError = new Error('Build failed with 1 error(s). See above for details.');
+  buildError.errors = [{ message: 'Bad config' }];
+  buildError.warnings = [{ message: 'Deprecated feature used' }];
+  mockShallowBuild.mockRejectedValue(buildError);
+
+  const build = lowdefyBuild(context);
+  await expect(build()).rejects.toBe(buildError);
+
+  expect(mockWriteBuildStatus).toHaveBeenCalledWith({
+    directories: context.directories,
+    status: 'error',
+    errors: [{ message: 'Bad config' }],
+    warnings: [{ message: 'Deprecated feature used' }],
+  });
+});
+
+test('lowdefyBuild falls back to the raw error message when the thrown error has no errors array', async () => {
+  const context = createContext();
+  const buildError = new Error('Build failed due to internal error. See above for details.');
+  mockShallowBuild.mockRejectedValue(buildError);
+
+  const build = lowdefyBuild(context);
+  await expect(build()).rejects.toBe(buildError);
+
+  expect(mockWriteBuildStatus).toHaveBeenCalledWith({
+    directories: context.directories,
+    status: 'error',
+    errors: [{ message: 'Build failed due to internal error. See above for details.' }],
+    warnings: [],
+  });
+});

package/manager/processes/readDotEnv.mjs

@@ -18,8 +18,20 @@ import path from 'path';
 import dotenv from 'dotenv';
 
 function readDotEnv(context) {
+  // dotenv.config() never overwrites env vars that are already set, so on
+  // the first load the real shell environment wins over .env (standard
+  // dotenv behavior). On reloads triggered by the .env watcher the previous
+  // load has already populated process.env, so without override the changed
+  // values would never take effect and the server would restart with stale
+  // env.
+  let loadedOnce = false;
   return () => {
-    dotenv.config({ path: path.join(context.directories.config, '.env'), silent: true });
+    dotenv.config({
+      path: path.join(context.directories.config, '.env'),
+      silent: true,
+      override: loadedOnce,
+    });
+    loadedOnce = true;
   };
 }
 

package/manager/processes/shutdownServer.mjs

@@ -16,18 +16,18 @@
 
 function shutdownServer(context) {
   return () => {
-    if (context.nextServer) {
+    if (context.devServer) {
       context.logger.debug(
-        `Existing next server with pid ${context.nextServer.pid}, killed: ${context.nextServer.killed}`
+        `Existing dev server with pid ${context.devServer.pid}, killed: ${context.devServer.killed}`
       );
-      if (!context.nextServer.killed) {
+      if (!context.devServer.killed) {
         context.logger.info({ spin: 'start' }, 'Shutting down server...');
-        context.nextServer.kill();
+        context.devServer.kill();
         context.logger.debug(
-          `Killed next server with pid ${context.nextServer.pid}, killed: ${context.nextServer.killed}`
+          `Killed dev server with pid ${context.devServer.pid}, killed: ${context.devServer.killed}`
         );
       }
-      context.nextServer = null;
+      context.devServer = null;
     }
   };
 }

package/manager/processes/startProxy.mjs

@@ -0,0 +1,160 @@
+/*
+  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 http from 'node:http';
+import net from 'node:net';
+
+/*
+The manager owns the public port; the Vite child listens on an internal
+loopback port and every restart replaces only the child. Before this proxy the
+child bound the public port directly, so each restart (js module change, .env
+change, plugin install) dropped the TCP listener for the whole Vite boot —
+long-lived clients (MCP agents on /lowdefy-docs/mcp, the reload SSE stream,
+HMR websockets) saw ECONNREFUSED and gave up; coding agents in particular
+latch the failure and need a manual reconnect. Holding the listener here turns
+a restart into a briefly-slow request instead of a dead port.
+
+While the child is down, requests and upgrades wait for it to come back
+(probing every RETRY_MS up to HOLD_MS) rather than failing fast. HOLD_MS
+covers a Vite respawn with headroom; a child that stays down longer than that
+answers 503 so callers are not held forever. In-flight streams cannot survive
+a child exit — those sockets close and the client reconnects into the hold.
+*/
+
+const RETRY_MS = 250;
+const HOLD_MS = 30000;
+
+function probeChild(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    socket.once('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once('error', () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function waitForChild({ port }) {
+  const deadline = Date.now() + HOLD_MS;
+  for (;;) {
+    if (await probeChild(port)) return true;
+    if (Date.now() > deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+  }
+}
+
+function forwardRequest(context, req, res) {
+  // Wait for a live child BEFORE piping the request body — the body stream can
+  // only be consumed once, so retrying after a failed proxy request would need
+  // full-body buffering. A probe-then-forward race (child dies between the
+  // probe and the connect) surfaces as one 502, which the client's next
+  // attempt resolves through the hold.
+  waitForChild({ port: context.internalPort }).then((up) => {
+    if (req.destroyed) return;
+    if (!up) {
+      res.writeHead(503, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ message: 'Lowdefy dev server is restarting.' }));
+      return;
+    }
+    const proxyReq = http.request({
+      host: '127.0.0.1',
+      port: context.internalPort,
+      method: req.method,
+      path: req.url,
+      headers: req.headers,
+    });
+    proxyReq.on('response', (proxyRes) => {
+      res.writeHead(proxyRes.statusCode, proxyRes.headers);
+      // flushHeaders so SSE endpoints (reload stream, MCP notifications)
+      // reach the client before the first event.
+      res.flushHeaders?.();
+      proxyRes.pipe(res);
+    });
+    proxyReq.on('error', () => {
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ message: 'Lowdefy dev server connection dropped.' }));
+    });
+    req.pipe(proxyReq);
+    req.on('error', () => proxyReq.destroy());
+    // A client that goes away mid-response (a closed browser tab holding the
+    // reload SSE stream, an agent dropping its MCP stream) must reach the
+    // child as an aborted request — pipe() only unpipes, so without this the
+    // child keeps the stream open and, for SSE, its tab registered forever.
+    res.on('close', () => {
+      if (!res.writableFinished) proxyReq.destroy();
+    });
+  });
+}
+
+function forwardUpgrade(context, req, socket, head) {
+  waitForChild({ port: context.internalPort }).then((up) => {
+    if (socket.destroyed) return;
+    if (!up) {
+      socket.end('HTTP/1.1 503 Service Unavailable\r\nconnection: close\r\n\r\n');
+      return;
+    }
+    const upstream = net.connect({ host: '127.0.0.1', port: context.internalPort }, () => {
+      // Replay the upgrade request verbatim (rawHeaders preserves order and
+      // case) and splice the sockets — protocol-agnostic, so Vite HMR and app
+      // websockets both pass through untouched.
+      const lines = [`${req.method} ${req.url} HTTP/1.1`];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
+      }
+      upstream.write(lines.join('\r\n') + '\r\n\r\n');
+      if (head?.length) upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+    upstream.on('error', () => socket.destroy());
+    socket.on('error', () => upstream.destroy());
+    upstream.on('close', () => socket.destroy());
+    socket.on('close', () => upstream.destroy());
+  });
+}
+
+function startProxy(context) {
+  if (context.proxyServer) return Promise.resolve();
+  const proxy = http.createServer((req, res) => forwardRequest(context, req, res));
+  proxy.on('upgrade', (req, socket, head) => forwardUpgrade(context, req, socket, head));
+  // Long-lived streams (SSE, MCP) must not be reaped by the default 5-minute
+  // request timeout; keep the proxy transparent.
+  proxy.requestTimeout = 0;
+  proxy.headersTimeout = 60000;
+  context.proxyServer = proxy;
+  return new Promise((resolve, reject) => {
+    proxy.once('error', reject);
+    // 'localhost' for parity with the Vite default host the child used to bind
+    // — the dev server stays loopback-only, not exposed on the LAN.
+    proxy.listen(context.options.port, 'localhost', () => {
+      proxy.removeListener('error', reject);
+      context.logger.debug(
+        `Proxy listening on port ${context.options.port}, forwarding to ${context.internalPort}.`
+      );
+      resolve();
+    });
+  });
+}
+
+export default startProxy;

package/manager/processes/startProxy.test.mjs

@@ -0,0 +1,102 @@
+/*
+  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 http from 'node:http';
+import net from 'node:net';
+
+import { jest } from '@jest/globals';
+
+const { default: startProxy } = await import('./startProxy.mjs');
+
+function listen(server) {
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+  });
+}
+
+function close(server) {
+  return new Promise((resolve) => {
+    server.closeAllConnections?.();
+    server.close(() => resolve());
+  });
+}
+
+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 child;
+let context;
+
+afterEach(async () => {
+  if (context?.proxyServer) await close(context.proxyServer);
+  if (child) await close(child);
+  child = undefined;
+  context = undefined;
+});
+
+async function startChildAndProxy(handler) {
+  child = http.createServer(handler);
+  const internalPort = await listen(child);
+  context = {
+    internalPort,
+    options: { port: await getFreePort() },
+    logger: { debug: jest.fn() },
+  };
+  await startProxy(context);
+  return context.options.port;
+}
+
+test('startProxy forwards a request to the child and relays its response', async () => {
+  const port = await startChildAndProxy((req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ path: req.url }));
+  });
+  const response = await fetch(`http://localhost:${port}/api/ping?x=1`);
+  expect(response.status).toBe(200);
+  expect(await response.json()).toEqual({ path: '/api/ping?x=1' });
+});
+
+test('startProxy aborts the child request when the client drops a streaming response', async () => {
+  let upstreamClosed;
+  const upstreamClosedPromise = new Promise((resolve) => {
+    upstreamClosed = resolve;
+  });
+  const port = await startChildAndProxy((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/event-stream' });
+    res.flushHeaders();
+    res.write('event: tab\ndata: {}\n\n');
+    // Never ends — like the reload SSE stream, it lives until the client goes.
+    req.on('close', () => upstreamClosed('closed'));
+  });
+
+  const clientRequest = http.get(`http://localhost:${port}/api/reload`);
+  const clientResponse = await new Promise((resolve) => clientRequest.on('response', resolve));
+  await new Promise((resolve) => clientResponse.once('data', resolve));
+  clientRequest.destroy();
+
+  const outcome = await Promise.race([
+    upstreamClosedPromise,
+    new Promise((resolve) => setTimeout(() => resolve('still open'), 2000)),
+  ]);
+  expect(outcome).toBe('closed');
+});

package/manager/processes/startServer.mjs

@@ -16,12 +16,14 @@
 
 import { spawn } from 'child_process';
 
+import warnAuthUrlPortMismatch from './warnAuthUrlPortMismatch.mjs';
+
 function createStdErrLineHandler({ context }) {
-  const port = context.options.port;
+  const port = context.internalPort;
   return function stdErrLineHandler(line) {
     if (line.includes('EADDRINUSE')) {
       context.logger.error(
-        `Port ${port} is already in use. Stop the other process or use a different port with --port.`
+        `Internal port ${port} is already in use. Stop the other process or use a different port with --port.`
       );
       return;
     }
@@ -31,18 +33,33 @@ function createStdErrLineHandler({ context }) {
 
 function startServer(context) {
   context.shutdownServer();
+  warnAuthUrlPortMismatch({ context });
 
-  const nextServer = spawn('node', [context.bin.next, 'start'], {
-    stdio: ['ignore', 'inherit', 'pipe'],
-    env: {
-      ...process.env,
-      LOWDEFY_DIRECTORY_CONFIG: context.directories.config,
-      PORT: context.options.port,
-    },
-  });
+  // The child binds context.internalPort on loopback; the manager's proxy owns
+  // the public context.options.port (see startProxy.mjs) so a restart never
+  // drops the listener that browsers, SSE reload streams and MCP agents hold.
+  const devServer = spawn(
+    'node',
+    [
+      context.bin.vite,
+      '--host',
+      '127.0.0.1',
+      '--port',
+      String(context.internalPort),
+      '--strictPort',
+    ],
+    {
+      stdio: ['ignore', 'inherit', 'pipe'],
+      env: {
+        ...process.env,
+        LOWDEFY_DIRECTORY_CONFIG: context.directories.config,
+        PORT: context.internalPort,
+      },
+    }
+  );
 
   const stdErrLineHandler = createStdErrLineHandler({ context });
-  nextServer.stderr.on('data', (data) => {
+  devServer.stderr.on('data', (data) => {
     data
       .toString('utf8')
       .split('\n')
@@ -51,14 +68,14 @@ function startServer(context) {
       });
   });
 
-  context.logger.debug(`Started next server with pid ${nextServer.pid}.`);
-  nextServer.on('exit', (code, signal) => {
-    context.logger.debug(`nextServer exit ${nextServer.pid}, signal: ${signal}, code: ${code}`);
+  context.logger.debug(`Started dev server with pid ${devServer.pid}.`);
+  devServer.on('exit', (code, signal) => {
+    context.logger.debug(`devServer exit ${devServer.pid}, signal: ${signal}, code: ${code}`);
   });
-  nextServer.on('error', (error) => {
+  devServer.on('error', (error) => {
     context.logger.error(error);
   });
-  context.nextServer = nextServer;
+  context.devServer = devServer;
 }
 
 export default startServer;

package/manager/processes/startWatchers.mjs

@@ -17,7 +17,7 @@
 import envWatcher from '../watchers/envWatcher.mjs';
 import lowdefyBuildWatcher from '../watchers/lowdefyBuildWatcher.mjs';
 import moduleBuildWatcher from '../watchers/moduleBuildWatcher.mjs';
-import nextBuildWatcher from '../watchers/nextBuildWatcher.mjs';
+import serverArtifactWatcher from '../watchers/serverArtifactWatcher.mjs';
 
 function startWatchers(context) {
   return async () => {
@@ -25,7 +25,7 @@ function startWatchers(context) {
       envWatcher(context),
       lowdefyBuildWatcher(context),
       moduleBuildWatcher(context),
-      nextBuildWatcher(context),
+      serverArtifactWatcher(context),
     ]);
   };
 }

package/manager/processes/warnAuthUrlPortMismatch.mjs

@@ -0,0 +1,47 @@
+/*
+  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.
+*/
+
+// Auth.js derives the app origin from request headers (trustHost), so an unset
+// AUTH_URL works on whatever port the dev server binds to. But when AUTH_URL (or
+// the v4 fallback NEXTAUTH_URL) is set, @auth/core pins the origin to it verbatim
+// — OAuth callbacks and sign-in redirects then target that URL. A pinned URL on a
+// mismatched port is left untouched but warned about.
+function warnAuthUrlPortMismatch({ context }) {
+  const { port } = context.options;
+  const name = process.env.AUTH_URL ? 'AUTH_URL' : 'NEXTAUTH_URL';
+  const current = process.env.AUTH_URL ?? process.env.NEXTAUTH_URL;
+
+  if (!current) return;
+
+  let currentPort;
+  try {
+    const url = new URL(current);
+    currentPort = url.port || (url.protocol === 'https:' ? '443' : '80');
+  } catch (_) {
+    context.logger.warn(`${name} (${current}) is not a valid URL.`);
+    return;
+  }
+
+  if (currentPort !== String(port)) {
+    context.logger.warn(
+      `${name} (${current}) does not match the dev server port ${port}. ` +
+        `Auth sign-in callbacks and redirects will target ${current}. ` +
+        `Update ${name} or unset it to derive the origin from the request.`
+    );
+  }
+}
+
+export default warnAuthUrlPortMismatch;