@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/server/testFixtures/importAppCodeTwice.mjs

@@ -0,0 +1,70 @@
+/*
+  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.
+*/
+
+// Run by importAppCode.test.mjs in its own process: Jest can load neither Vite
+// nor a module URL with a query. Loads the build's importAppCode the way the dev
+// server's JIT page builds do, then imports an app code file, imports it again
+// unchanged, edits it and imports it again. With `vite`, through Vite's SSR
+// module runner (@lowdefy/build linked, as in the monorepo); with `node`,
+// natively (@lowdefy/build installed from npm, which Vite externalises).
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { createServer } from 'vite';
+
+const [loader, configDir] = process.argv.slice(2);
+const require = createRequire(import.meta.url);
+const serverDevDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+
+const buildDevEntry = require.resolve('@lowdefy/build/dev');
+const modulePath = path.join(path.dirname(buildDevEntry), 'utils/createImportAppCode.js');
+
+let server = null;
+if (loader === 'vite') {
+  server = await createServer({
+    configFile: false,
+    root: serverDevDir,
+    logLevel: 'error',
+    appType: 'custom',
+    server: { middlewareMode: true, hmr: false, watch: null },
+  });
+}
+
+try {
+  const { default: createImportAppCode } = server
+    ? await server.ssrLoadModule(modulePath)
+    : await import(pathToFileURL(modulePath).href);
+  const importAppCode = createImportAppCode({ directories: { config: configDir } });
+  const filePath = path.join(configDir, 'transformer.js');
+
+  fs.writeFileSync(filePath, "export default () => 'before';\n");
+  const first = await importAppCode('transformer.js');
+  const unchanged = await importAppCode('transformer.js');
+  fs.writeFileSync(filePath, "export default () => 'after';\n");
+  const edited = await importAppCode('transformer.js');
+
+  process.stdout.write(
+    JSON.stringify({
+      first: first(),
+      edited: edited(),
+      unchangedReused: unchanged === first,
+    })
+  );
+} finally {
+  await server?.close();
+}

package/lib/server/trackSessionWork.js

@@ -0,0 +1,30 @@
+/*
+  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.
+*/
+
+// The context.waitUntil of a data-session request: background work (scheduleBackground, the detached
+// dispatch and the detached run) is added to the session's work set, so closing the session waits
+// for it before it drops the database.
+function trackSessionWork({ session }) {
+  return function waitUntil(promise) {
+    session.work.add(promise);
+    const remove = () => {
+      session.work.delete(promise);
+    };
+    promise.then(remove, remove);
+  };
+}
+
+export default trackSessionWork;

package/lib/vite/createDevServerExclude.js

@@ -0,0 +1,40 @@
+/*
+  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.
+*/
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// The paths Vite serves itself; every other request routes to the Hono app.
+// @hono/vite-dev-server tests these against the raw request url, before Vite
+// strips its `base`, and Vite serves every module under `base` - so with
+// config.basePath the patterns must carry the prefix. Without it
+// `<basePath>/@vite/client` and `<basePath>/client/main.jsx` fall through to
+// the Hono page route and come back as the HTML shell.
+function createDevServerExclude({ basePath }) {
+  const prefix = escapeRegExp(basePath);
+  return [
+    new RegExp(`^${prefix}/client/.+`),
+    new RegExp(`^${prefix}/lib/.+`),
+    new RegExp(`^${prefix}/build/.+`),
+    new RegExp(`^${prefix}/@.+$`),
+    new RegExp(`^${prefix}/node_modules/.*`),
+    /\?t=\d+$/,
+    /^\/favicon\.ico$/,
+  ];
+}
+
+export default createDevServerExclude;

package/lib/vite/createDevServerExclude.test.mjs

@@ -0,0 +1,79 @@
+/*
+  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 createDevServerExclude from './createDevServerExclude.js';
+
+function isExcluded(exclude, url) {
+  return exclude.some((pattern) => pattern.test(url));
+}
+
+test('createDevServerExclude leaves Vite module paths to Vite when there is no basePath', () => {
+  const exclude = createDevServerExclude({ basePath: '' });
+
+  expect(isExcluded(exclude, '/@vite/client')).toBe(true);
+  expect(isExcluded(exclude, '/@react-refresh')).toBe(true);
+  expect(isExcluded(exclude, '/client/main.jsx')).toBe(true);
+  expect(isExcluded(exclude, '/build/plugins/blocks.js')).toBe(true);
+  expect(isExcluded(exclude, '/lib/client/ErrorBar.jsx')).toBe(true);
+  expect(isExcluded(exclude, '/node_modules/.vite/deps/react.js?v=1')).toBe(true);
+  expect(isExcluded(exclude, '/client/App.jsx?t=1712345678')).toBe(true);
+  expect(isExcluded(exclude, '/favicon.ico')).toBe(true);
+});
+
+test('createDevServerExclude routes page, api and docs paths to Hono when there is no basePath', () => {
+  const exclude = createDevServerExclude({ basePath: '' });
+
+  expect(isExcluded(exclude, '/')).toBe(false);
+  expect(isExcluded(exclude, '/home')).toBe(false);
+  expect(isExcluded(exclude, '/api/ping')).toBe(false);
+  expect(isExcluded(exclude, '/lowdefy-docs/mcp')).toBe(false);
+});
+
+test('createDevServerExclude leaves Vite module paths under the basePath to Vite', () => {
+  const exclude = createDevServerExclude({ basePath: '/app' });
+
+  expect(isExcluded(exclude, '/app/@vite/client')).toBe(true);
+  expect(isExcluded(exclude, '/app/@react-refresh')).toBe(true);
+  expect(isExcluded(exclude, '/app/@fs/Users/dev/app/plugin.js')).toBe(true);
+  expect(isExcluded(exclude, '/app/client/main.jsx')).toBe(true);
+  expect(isExcluded(exclude, '/app/build/plugins/blocks.js')).toBe(true);
+  expect(isExcluded(exclude, '/app/lib/client/ErrorBar.jsx')).toBe(true);
+  expect(isExcluded(exclude, '/app/node_modules/.vite/deps/react.js?v=1')).toBe(true);
+});
+
+test('createDevServerExclude routes page, api and docs paths under the basePath to Hono', () => {
+  const exclude = createDevServerExclude({ basePath: '/app' });
+
+  expect(isExcluded(exclude, '/app')).toBe(false);
+  expect(isExcluded(exclude, '/app/home')).toBe(false);
+  expect(isExcluded(exclude, '/app/client-list')).toBe(false);
+  expect(isExcluded(exclude, '/app/api/ping')).toBe(false);
+  expect(isExcluded(exclude, '/app/lowdefy-docs/mcp')).toBe(false);
+});
+
+test('createDevServerExclude does not hand unprefixed module paths to Vite under a basePath', () => {
+  const exclude = createDevServerExclude({ basePath: '/app' });
+
+  expect(isExcluded(exclude, '/@vite/client')).toBe(false);
+  expect(isExcluded(exclude, '/client/main.jsx')).toBe(false);
+});
+
+test('createDevServerExclude matches a basePath containing regular expression characters literally', () => {
+  const exclude = createDevServerExclude({ basePath: '/my.app' });
+
+  expect(isExcluded(exclude, '/my.app/@vite/client')).toBe(true);
+  expect(isExcluded(exclude, '/myxapp/@vite/client')).toBe(false);
+});

package/manager/getContext.mjs

@@ -25,13 +25,17 @@ import checkMockUserWarning from './processes/checkMockUserWarning.mjs';
 import initialBuild from './processes/initialBuild.mjs';
 import installPlugins from './processes/installPlugins.mjs';
 import lowdefyBuild from './processes/lowdefyBuild.mjs';
+import optimizeDependencies from './processes/optimizeDependencies.mjs';
 import readDotEnv from './processes/readDotEnv.mjs';
 import reloadClients from './processes/reloadClients.mjs';
 import restartServer from './processes/restartServer.mjs';
 import shutdownServer from './processes/shutdownServer.mjs';
 import startWatchers from './processes/startWatchers.mjs';
+import syncServer from './processes/syncServer.mjs';
 
+import createServerArtifactTracker from './utils/createServerArtifactTracker.mjs';
 import getViteBin from './utils/getViteBin.mjs';
+import readManagerVersion from './utils/readManagerVersion.mjs';
 
 const argv = yargs(hideBin(process.argv)).array('watch').array('watchIgnore').argv;
 
@@ -44,6 +48,7 @@ async function getContext() {
     },
     directories: {
       build: path.resolve(process.cwd(), './build'),
+      buildStaging: path.resolve(process.cwd(), './build-staging'),
       config: path.resolve(argv.configDirectory ?? env.LOWDEFY_DIRECTORY_CONFIG ?? process.cwd()),
       server: process.cwd(),
     },
@@ -54,8 +59,14 @@ async function getContext() {
       destination: pino.destination({ dest: 1, sync: true }),
     }),
     options: {
+      internalPort: env.LOWDEFY_SERVER_DEV_INTERNAL_PORT
+        ? Number(env.LOWDEFY_SERVER_DEV_INTERNAL_PORT)
+        : undefined,
+      owner: env.LOWDEFY_DEV_OWNER === 'hub' ? 'hub' : 'terminal',
       port: Number(argv.port ?? env.PORT ?? 3000),
       refResolver: argv.refResolver ?? env.LOWDEFY_BUILD_REF_RESOLVER,
+      skipPluginChecks: env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS === 'true',
+      strictPort: env.LOWDEFY_SERVER_DEV_STRICT_PORT === 'true',
       watch:
         argv.watch ?? env.LOWDEFY_SERVER_DEV_WATCH ? JSON.parse(env.LOWDEFY_SERVER_DEV_WATCH) : [],
       watchIgnore:
@@ -63,11 +74,12 @@ async function getContext() {
           ? JSON.parse(env.LOWDEFY_SERVER_DEV_WATCH_IGNORE)
           : [],
     },
-    version: env.npm_package_version,
+    version: readManagerVersion(),
 
     // JIT build state
     pageRegistry: null,
     buildContext: null,
+    lastBuildFailed: false,
   };
 
   context.packageManagerCmd = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
@@ -78,18 +90,28 @@ async function getContext() {
   // Wrap lowdefyBuild to capture and store the shallow build result
   const buildFn = lowdefyBuild(context);
   context.lowdefyBuild = async () => {
-    const result = await buildFn();
+    let result;
+    try {
+      result = await buildFn();
+    } catch (error) {
+      context.lastBuildFailed = true;
+      throw error;
+    }
+    context.lastBuildFailed = false;
     if (result) {
       context.pageRegistry = result.pageRegistry;
       context.buildContext = result.context;
     }
   };
 
+  context.optimizeDependencies = optimizeDependencies(context);
   context.readDotEnv = readDotEnv(context);
   context.reloadClients = reloadClients(context);
   context.restartServer = restartServer(context);
+  context.serverArtifacts = createServerArtifactTracker(context);
   context.shutdownServer = shutdownServer(context);
   context.startWatchers = startWatchers(context);
+  context.syncServer = syncServer(context);
 
   return context;
 }

package/manager/processes/initialBuild.mjs

@@ -15,12 +15,26 @@
   limitations under the License.
 */
 
+import { pluginChecksNeedRebuild } from '@lowdefy/node-utils';
+
 function initialBuild(context) {
   return async () => {
     context.readDotEnv();
     await context.lowdefyBuild();
     await context.checkMockUserWarning();
     await context.installPlugins();
+    // The build lists the plugins it used but could not check, since they were
+    // not installed. The install above added them, so build once more when that
+    // checks something new, unless no checks run this time anyway.
+    if (
+      !context.options.skipPluginChecks &&
+      pluginChecksNeedRebuild({
+        buildDirectory: context.directories.build,
+        serverDirectory: context.directories.server,
+      })
+    ) {
+      await context.lowdefyBuild();
+    }
   };
 }
 

package/manager/processes/initialBuild.test.mjs

@@ -0,0 +1,101 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+
+import initialBuild from './initialBuild.mjs';
+
+let buildDirectory;
+let calls;
+
+function createContext({ installPlugins, skipPluginChecks } = {}) {
+  const record = (name, impl) =>
+    jest.fn(async () => {
+      calls.push(name);
+      if (impl) await impl();
+    });
+  return {
+    directories: { build: buildDirectory, server: buildDirectory },
+    options: { skipPluginChecks },
+    readDotEnv: jest.fn(() => calls.push('readDotEnv')),
+    lowdefyBuild: record('lowdefyBuild'),
+    checkMockUserWarning: record('checkMockUserWarning'),
+    installPlugins: record('installPlugins', installPlugins),
+  };
+}
+
+beforeEach(() => {
+  calls = [];
+  buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-initial-build-'));
+});
+
+afterEach(() => {
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+test('initialBuild builds once when no plugin checks are pending', async () => {
+  const context = createContext();
+  await initialBuild(context)();
+  expect(context.lowdefyBuild).toHaveBeenCalledTimes(1);
+  expect(calls).toEqual(['readDotEnv', 'lowdefyBuild', 'checkMockUserWarning', 'installPlugins']);
+});
+
+test('initialBuild builds again after installing plugins when plugin checks are pending', async () => {
+  const context = createContext({
+    installPlugins: () =>
+      fs.writeFileSync(
+        path.join(buildDirectory, 'plugin-checks-pending.json'),
+        JSON.stringify({ packages: [{ name: '@acme/plugin', schemaChecked: true }] })
+      ),
+  });
+  await initialBuild(context)();
+  expect(context.lowdefyBuild).toHaveBeenCalledTimes(2);
+  expect(calls).toEqual([
+    'readDotEnv',
+    'lowdefyBuild',
+    'checkMockUserWarning',
+    'installPlugins',
+    'lowdefyBuild',
+  ]);
+});
+
+test('initialBuild builds once with skipPluginChecks, even when plugin checks are pending', async () => {
+  const context = createContext({
+    skipPluginChecks: true,
+    installPlugins: () =>
+      fs.writeFileSync(
+        path.join(buildDirectory, 'plugin-checks-pending.json'),
+        JSON.stringify({ packages: [{ name: '@acme/plugin', schemaChecked: true }] })
+      ),
+  });
+  await initialBuild(context)();
+  expect(context.lowdefyBuild).toHaveBeenCalledTimes(1);
+});
+
+test('initialBuild builds once when the pending plugins give nothing new to check', async () => {
+  const context = createContext({
+    installPlugins: () =>
+      fs.writeFileSync(
+        path.join(buildDirectory, 'plugin-checks-pending.json'),
+        JSON.stringify({ packages: [{ name: '@acme/connection', schemaChecked: false }] })
+      ),
+  });
+  await initialBuild(context)();
+  expect(context.lowdefyBuild).toHaveBeenCalledTimes(1);
+});

package/manager/processes/lowdefyBuild.mjs

@@ -17,6 +17,7 @@
 import { serializeBuildException, shallowBuild } from '@lowdefy/build/dev';
 import createCustomPluginMessagesMap from '../utils/createCustomPluginMessagesMap.mjs';
 import createCustomPluginTypesMap from '../utils/createCustomPluginTypesMap.mjs';
+import publishBuildDirectory from '../utils/publishBuildDirectory.mjs';
 import writeBuildStatus from '../utils/writeBuildStatus.mjs';
 
 function formatDuration(ms) {
@@ -25,26 +26,39 @@ function formatDuration(ms) {
 }
 
 function lowdefyBuild({ directories, logger, options }) {
-  return async () => {
+  async function build() {
     logger.info({ spin: 'start' }, 'Building config...');
     const startTime = Date.now();
-    const customTypesMap = await createCustomPluginTypesMap({ directories, logger });
-    const customMessagesMap = await createCustomPluginMessagesMap({ directories, logger });
 
+    // Reading the plugin maps parses lowdefy.yaml and imports each plugin's
+    // types, so a YAML syntax error or a broken plugin fails the build there,
+    // and the build status has to report it like any other build error. So
+    // does a publish that fails part way: the live build is then a mix of two
+    // builds, and the next change must rebuild and publish it whole.
     let result;
     try {
+      const [customTypesMap, customMessagesMap] = await Promise.all([
+        createCustomPluginTypesMap({ directories, logger }),
+        createCustomPluginMessagesMap({ directories, logger }),
+      ]);
       result = await shallowBuild({
         customMessagesMap,
         customTypesMap,
-        directories,
+        directories: { ...directories, build: directories.buildStaging },
         logger,
         refResolver: options.refResolver,
+        skipPluginChecks: options.skipPluginChecks,
         stage: 'dev',
       });
+      await publishBuildDirectory({
+        buildDirectory: directories.build,
+        stagingDirectory: directories.buildStaging,
+      }).catch((error) => {
+        throw new Error(`Publishing the build to ${directories.build} failed: ${error.message}`, {
+          cause: error,
+        });
+      });
     } 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',
@@ -65,6 +79,15 @@ function lowdefyBuild({ directories, logger, options }) {
     const duration = Date.now() - startTime;
     logger.info({ spin: 'succeed' }, `Built config in ${formatDuration(duration)}.`);
     return result;
+  }
+
+  // Watchers, restarts and plugin installs each start builds, and every build
+  // writes the same staging directory, so a build waits for the one before it.
+  let previousBuild = Promise.resolve();
+  return () => {
+    const nextBuild = previousBuild.then(build);
+    previousBuild = nextBuild.catch(() => {});
+    return nextBuild;
   };
 }
 

package/manager/processes/lowdefyBuild.skipPluginChecks.test.mjs

@@ -0,0 +1,62 @@
+/*
+  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();
+
+jest.unstable_mockModule('@lowdefy/build/dev', () => ({
+  shallowBuild: mockShallowBuild,
+  serializeBuildException: jest.fn((exception) => ({ message: exception.message })),
+}));
+jest.unstable_mockModule('../utils/writeBuildStatus.mjs', () => ({
+  default: jest.fn(),
+}));
+jest.unstable_mockModule('../utils/createCustomPluginTypesMap.mjs', () => ({
+  default: jest.fn().mockResolvedValue({}),
+}));
+jest.unstable_mockModule('../utils/createCustomPluginMessagesMap.mjs', () => ({
+  default: jest.fn().mockResolvedValue({}),
+}));
+jest.unstable_mockModule('../utils/publishBuildDirectory.mjs', () => ({
+  default: jest.fn(async () => {}),
+}));
+
+const { default: lowdefyBuild } = await import('./lowdefyBuild.mjs');
+
+function createContext(options) {
+  return {
+    directories: { build: '/app/build', buildStaging: '/app/build-staging' },
+    logger: { info: jest.fn() },
+    options,
+  };
+}
+
+beforeEach(() => {
+  mockShallowBuild.mockResolvedValue({ components: {}, pageRegistry: {}, context: {} });
+});
+
+test('lowdefyBuild passes skipPluginChecks true to shallowBuild', async () => {
+  await lowdefyBuild(createContext({ skipPluginChecks: true }))();
+  expect(mockShallowBuild.mock.calls[0][0].skipPluginChecks).toBe(true);
+});
+
+test('lowdefyBuild passes skipPluginChecks undefined to shallowBuild when the option is not set', async () => {
+  await lowdefyBuild(createContext({}))();
+  const [args] = mockShallowBuild.mock.calls[0];
+  expect(args.skipPluginChecks).toBeUndefined();
+  expect(args.stage).toEqual('dev');
+});