@lowdefy/server-dev 6.1.0 → 7.1.0

package/manager/utils/resolveDevAuthUrl.test.mjs

@@ -0,0 +1,107 @@
+/*
+  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 resolveDevAuthUrl from './resolveDevAuthUrl.mjs';
+
+test('a localhost origin on another port follows the dev server port', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://localhost:3000', port: 4102 })).toEqual({
+    authUrl: 'http://localhost:4102',
+    rewritten: true,
+  });
+});
+
+test('127.0.0.1 and [::1] origins follow the dev server port', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://127.0.0.1:3000', port: 4102 })).toEqual({
+    authUrl: 'http://127.0.0.1:4102',
+    rewritten: true,
+  });
+  expect(resolveDevAuthUrl({ configured: 'http://[::1]:3000', port: 4102 })).toEqual({
+    authUrl: 'http://[::1]:4102',
+    rewritten: true,
+  });
+});
+
+test('a path on the configured origin is kept', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://localhost:3000/app', port: 4102 })).toEqual({
+    authUrl: 'http://localhost:4102/app',
+    rewritten: true,
+  });
+});
+
+test('a localhost origin already on the dev server port is returned as configured', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://localhost:4102', port: 4102 })).toEqual({
+    authUrl: 'http://localhost:4102',
+    rewritten: false,
+  });
+});
+
+test('surrounding whitespace is trimmed without counting as a rewrite', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://localhost:4102 ', port: 4102 })).toEqual({
+    authUrl: 'http://localhost:4102',
+    rewritten: false,
+  });
+});
+
+test('an https localhost origin is kept, since a local TLS proxy fronts the dev server', () => {
+  expect(resolveDevAuthUrl({ configured: 'https://localhost', port: 4102 })).toEqual({
+    authUrl: 'https://localhost',
+    rewritten: false,
+  });
+  expect(resolveDevAuthUrl({ configured: 'https://localhost:8443', port: 4102 })).toEqual({
+    authUrl: 'https://localhost:8443',
+    rewritten: false,
+  });
+});
+
+test('a localhost origin on the default port is kept, since a local proxy fronts the dev server', () => {
+  expect(resolveDevAuthUrl({ configured: 'http://localhost', port: 4102 })).toEqual({
+    authUrl: 'http://localhost',
+    rewritten: false,
+  });
+  expect(resolveDevAuthUrl({ configured: 'http://localhost:80', port: 4102 })).toEqual({
+    authUrl: 'http://localhost:80',
+    rewritten: false,
+  });
+});
+
+test('a non-loopback origin is kept', () => {
+  expect(resolveDevAuthUrl({ configured: 'https://dev.example.ngrok.app', port: 4102 })).toEqual({
+    authUrl: 'https://dev.example.ngrok.app',
+    rewritten: false,
+  });
+  expect(resolveDevAuthUrl({ configured: 'http://192.168.1.20:3000', port: 4102 })).toEqual({
+    authUrl: 'http://192.168.1.20:3000',
+    rewritten: false,
+  });
+});
+
+test('an unset origin stays unset', () => {
+  expect(resolveDevAuthUrl({ configured: undefined, port: 4102 })).toEqual({
+    authUrl: undefined,
+    rewritten: false,
+  });
+  expect(resolveDevAuthUrl({ configured: '', port: 4102 })).toEqual({
+    authUrl: '',
+    rewritten: false,
+  });
+});
+
+test('an unparseable value is returned as configured', () => {
+  expect(resolveDevAuthUrl({ configured: 'localhost:3000', port: 4102 })).toEqual({
+    authUrl: 'localhost:3000',
+    rewritten: false,
+  });
+});

package/manager/utils/resolvePorts.mjs

@@ -0,0 +1,49 @@
+/*
+  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 { findAvailablePort, isPortAvailable } from '@lowdefy/node-utils';
+
+// An explicit port (--port, PORT, cli.port, or one the hub allocated) is a
+// promise to whoever asked for it: moving silently to the next free port sent
+// agents to a different app's server on the port they expected. Only the
+// unrequested default still moves.
+async function resolvePort({ port, strict, name }) {
+  if (strict) {
+    if (!(await isPortAvailable({ port }))) {
+      throw new Error(
+        `${name} ${port} is already in use. Stop the process using it or choose another port.`
+      );
+    }
+    return port;
+  }
+  return findAvailablePort({ port });
+}
+
+async function resolvePorts(context) {
+  const { options } = context;
+  const port = await resolvePort({ port: options.port, strict: options.strictPort, name: 'Port' });
+  if (port !== options.port) {
+    context.logger.warn(`Port ${options.port} is in use, using port ${port} instead.`);
+  }
+  const internalPort = await resolvePort({
+    port: options.internalPort ?? port + 1,
+    strict: options.internalPort !== undefined,
+    name: 'Internal port',
+  });
+  return { port, internalPort };
+}
+
+export default resolvePorts;

package/manager/utils/setupWatcher.mjs

@@ -14,8 +14,22 @@
   limitations under the License.
 */
 
+import path from 'path';
+
 import chokidar from 'chokidar';
 import BatchChanges from './BatchChanges.mjs';
+import createDotPathIgnore from './createDotPathIgnore.mjs';
+
+// chokidar hands ignore functions a path with forward slashes on every platform
+// (anymatch normalizes it), while watch paths and the directories they are
+// compared with use the platform separator. Ignore functions get the platform
+// form, so a comparison with a watch path holds on Windows too.
+function withNativePath(ignore) {
+  if (typeof ignore !== 'function') {
+    return ignore;
+  }
+  return (filePath, ...rest) => ignore(path.normalize(filePath), ...rest);
+}
 
 function setupWatcher({
   callback,
@@ -24,26 +38,20 @@ function setupWatcher({
   ignorePaths = [],
   watchPaths,
   delay = 500,
+  onBusy,
 }) {
   return new Promise((resolve) => {
-    // const { watch = [], watchIgnore = [] } = context.options;
-    // const resolvedWatchPaths = watch.map((pathName) => path.resolve(pathName));
-
-    const batchChanges = new BatchChanges({ context, fn: callback, delay });
-    const defaultIgnorePaths = watchDotfiles
-      ? []
-      : [
-          /(^|[/\\])\../, // ignore dotfiles
-        ];
+    const batchChanges = new BatchChanges({ context, fn: callback, delay, onBusy });
+    const defaultIgnorePaths = watchDotfiles ? [] : [createDotPathIgnore({ watchPaths })];
     const configWatcher = chokidar.watch(watchPaths, {
-      ignored: [...defaultIgnorePaths, ...ignorePaths],
+      ignored: [...defaultIgnorePaths, ...ignorePaths].map(withNativePath),
       persistent: true,
       ignoreInitial: true,
     });
     configWatcher.on('add', (...args) => batchChanges.newChange(...args));
     configWatcher.on('change', (...args) => batchChanges.newChange(...args));
     configWatcher.on('unlink', (...args) => batchChanges.newChange(...args));
-    configWatcher.on('ready', () => resolve());
+    configWatcher.on('ready', () => resolve(configWatcher));
   });
 }
 

package/manager/utils/startRecordingPruner.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 pruneRecordings from './pruneRecordings.mjs';
+
+const HOUR_MS = 60 * 60 * 1000;
+
+// Runs in the manager, which lives as long as the session (the server child
+// restarts). Pruning runs whether or not recording is on, so old traces still
+// age out after a developer turns recording off. A failure is logged at debug
+// and never stops the dev server.
+function startRecordingPruner({ configDirectory, logger, intervalMs = HOUR_MS }) {
+  function prune() {
+    try {
+      const deleted = pruneRecordings({ configDirectory });
+      const count = deleted.directories.length + deleted.files.length;
+      if (count > 0) {
+        logger.debug(
+          `Pruned ${deleted.directories.length} recording date directories and ${deleted.files.length} recording files.`
+        );
+      }
+    } catch (error) {
+      logger.debug(`Pruning dev recordings failed: ${error.message}`);
+    }
+  }
+  prune();
+  const interval = setInterval(prune, intervalMs);
+  interval.unref();
+  return interval;
+}
+
+export default startRecordingPruner;

package/manager/utils/startRecordingPruner.test.mjs

@@ -0,0 +1,66 @@
+/*
+  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 mockPruneRecordings = jest.fn();
+jest.unstable_mockModule('./pruneRecordings.mjs', () => ({ default: mockPruneRecordings }));
+
+const { default: startRecordingPruner } = await import('./startRecordingPruner.mjs');
+
+const logger = { debug: jest.fn() };
+
+beforeEach(() => {
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  mockPruneRecordings.mockReset();
+  mockPruneRecordings.mockReturnValue({ directories: [], files: [] });
+  logger.debug.mockReset();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+test('startRecordingPruner prunes at start and then on the interval, with recording off', () => {
+  process.env.LOWDEFY_DEV_RECORD = 'false';
+  const interval = startRecordingPruner({ configDirectory: '/app', logger, intervalMs: 1000 });
+  expect(mockPruneRecordings).toHaveBeenCalledTimes(1);
+  expect(mockPruneRecordings).toHaveBeenCalledWith({ configDirectory: '/app' });
+  jest.advanceTimersByTime(2500);
+  expect(mockPruneRecordings).toHaveBeenCalledTimes(3);
+  clearInterval(interval);
+  delete process.env.LOWDEFY_DEV_RECORD;
+});
+
+test('startRecordingPruner logs a failure at debug and keeps running', () => {
+  mockPruneRecordings.mockImplementationOnce(() => {
+    throw new Error('EACCES');
+  });
+  const interval = startRecordingPruner({ configDirectory: '/app', logger, intervalMs: 1000 });
+  expect(logger.debug).toHaveBeenCalledWith('Pruning dev recordings failed: EACCES');
+  jest.advanceTimersByTime(1000);
+  expect(mockPruneRecordings).toHaveBeenCalledTimes(2);
+  clearInterval(interval);
+});
+
+test('startRecordingPruner logs what it deleted at debug', () => {
+  mockPruneRecordings.mockReturnValue({ directories: ['/a'], files: ['/b', '/c'] });
+  const interval = startRecordingPruner({ configDirectory: '/app', logger });
+  expect(logger.debug).toHaveBeenCalledWith(
+    'Pruned 1 recording date directories and 2 recording files.'
+  );
+  clearInterval(interval);
+});

package/manager/utils/waitForChildExit.mjs

@@ -0,0 +1,53 @@
+/*
+  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 hasExited(child) {
+  return child.exitCode !== null || child.signalCode !== null;
+}
+
+function waitForExit({ child, timeoutMs }) {
+  if (hasExited(child)) {
+    return Promise.resolve(true);
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      child.off('exit', onExit);
+      resolve(false);
+    }, timeoutMs);
+    function onExit() {
+      clearTimeout(timer);
+      resolve(true);
+    }
+    child.once('exit', onExit);
+  });
+}
+
+// Waits for a signalled child to let go of its port before a new one binds
+// it. The wait is bounded so a child that ignores SIGTERM, or never exits even
+// after SIGKILL, cannot hang a restart or the build-status wait around it.
+// Resolves true once the child has exited, false if it never did.
+async function waitForChildExit({ child, timeoutMs = 10000, killTimeoutMs = 5000 }) {
+  if (!child) {
+    return true;
+  }
+  if (await waitForExit({ child, timeoutMs })) {
+    return true;
+  }
+  child.kill('SIGKILL');
+  return waitForExit({ child, timeoutMs: killTimeoutMs });
+}
+
+export default waitForChildExit;

package/manager/utils/waitForChildExit.test.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.
+*/
+
+import { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+import waitForChildExit from './waitForChildExit.mjs';
+
+function createChild({ exitOn = [] } = {}) {
+  const child = Object.assign(new EventEmitter(), {
+    exitCode: null,
+    signalCode: null,
+    kill: jest.fn((signal) => {
+      if (exitOn.includes(signal)) {
+        setImmediate(() => {
+          child.signalCode = signal;
+          child.emit('exit', null, signal);
+        });
+      }
+    }),
+  });
+  return child;
+}
+
+test('waitForChildExit resolves at once when there is no child', async () => {
+  await expect(waitForChildExit({ child: null })).resolves.toBe(true);
+});
+
+test('waitForChildExit resolves at once when the child has already exited', async () => {
+  const child = createChild();
+  child.exitCode = 0;
+  await expect(waitForChildExit({ child, timeoutMs: 1000 })).resolves.toBe(true);
+  expect(child.kill).not.toHaveBeenCalled();
+});
+
+test('waitForChildExit resolves when the child exits within the timeout, without SIGKILL', async () => {
+  const child = createChild();
+  const waiting = waitForChildExit({ child, timeoutMs: 1000, killTimeoutMs: 1000 });
+  child.exitCode = 0;
+  child.emit('exit', 0, null);
+  await expect(waiting).resolves.toBe(true);
+  expect(child.kill).not.toHaveBeenCalled();
+});
+
+test('waitForChildExit SIGKILLs a child that ignores SIGTERM and resolves once it exits', async () => {
+  const child = createChild({ exitOn: ['SIGKILL'] });
+  await expect(waitForChildExit({ child, timeoutMs: 10, killTimeoutMs: 1000 })).resolves.toBe(true);
+  expect(child.kill).toHaveBeenCalledWith('SIGKILL');
+});
+
+test('waitForChildExit resolves false after both timeouts when the child never exits', async () => {
+  const child = createChild();
+  await expect(waitForChildExit({ child, timeoutMs: 10, killTimeoutMs: 10 })).resolves.toBe(false);
+  expect(child.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(child.listenerCount('exit')).toBe(0);
+});

package/manager/utils/waitForServer.mjs

@@ -0,0 +1,44 @@
+/*
+  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 { wait } from '@lowdefy/helpers';
+
+function hasExited(child) {
+  return child.exitCode !== null || child.signalCode !== null;
+}
+
+// The child answers <basePath>/api/ping once Vite and the Hono app are both up, so this
+// is the moment the server is really usable - waitForDevServer flips the
+// instance record to "ready" then, which is what the hub and the MCP shim
+// wait on. A child that exits (a plugin that fails to load) will never
+// answer, so the wait ends.
+async function waitForServer({ port, basePath, child, timeoutMs = 120000, intervalMs = 250 }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !hasExited(child)) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}${basePath}/api/ping`);
+      if (response.ok) {
+        return true;
+      }
+    } catch {
+      // Not listening yet.
+    }
+    await wait(intervalMs);
+  }
+  return false;
+}
+
+export default waitForServer;

package/manager/utils/writeBuildStatus.mjs

@@ -22,7 +22,7 @@ import { writeFileIfChanged } from '@lowdefy/node-utils';
 // process - a separate process from this manager, sharing only the build
 // directory - can serve current build errors/warnings to AI coding agents.
 // writeFileIfChanged creates the build directory if it does not exist, which
-// covers the case where the build attempt cleaned it before failing.
+// covers a first build that fails.
 async function writeBuildStatus({ directories, status, errors, warnings }) {
   const buildStatus = {
     status,

package/manager/watchers/createPluginSourceIgnore.mjs

@@ -0,0 +1,77 @@
+/*
+  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 path from 'path';
+
+const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.json']);
+
+// Watched packages are resolved to their real paths, which chokidar reports,
+// so the directories compared with them must be too (a config directory
+// reached through a symlink, or macOS's /var -> /private/var).
+function realPath(dir) {
+  return fs.existsSync(dir) ? fs.realpathSync(dir) : dir;
+}
+
+function statIfExists(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    // Already gone (an unlink): a removed directory's files are reported on their own.
+    return null;
+  }
+}
+
+function isInside({ filePath, dir }) {
+  const relative = path.relative(dir, filePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+// Only plugin code (and package.json, or a type list kept in JSON) can change
+// what the config build reads from a plugin. Everything else in a watched
+// package is ignored by path, without knowing who wrote it: a plugin package
+// that is also the config directory has its YAML and Markdown watched by the
+// config watcher already, and its ref resolvers write public/ on every build,
+// which would otherwise trigger the next build, forever. The build, staging
+// and server directories hold the build's own output.
+function createPluginSourceIgnore({ directories }) {
+  const ignoredDirs = [
+    path.join(directories.config, 'public'),
+    directories.build,
+    directories.buildStaging,
+    directories.server,
+  ]
+    .filter(Boolean)
+    .map(realPath);
+  return function isIgnored(filePath, stats) {
+    if (filePath.split(path.sep).includes('node_modules')) {
+      return true;
+    }
+    if (ignoredDirs.some((dir) => isInside({ filePath, dir }))) {
+      return true;
+    }
+    const extension = path.extname(filePath);
+    if (CODE_EXTENSIONS.has(extension)) {
+      return false;
+    }
+    // chokidar asks about directories too, often without their stats, and a
+    // directory must not be ignored, or nothing under it is watched.
+    const pathStats = stats ?? statIfExists(filePath);
+    return pathStats?.isDirectory() !== true;
+  };
+}
+
+export default createPluginSourceIgnore;

package/manager/watchers/envWatcher.mjs

@@ -21,12 +21,19 @@ function envWatcher(context) {
   const callback = async () => {
     context.logger.warn('.env file changed.');
     context.readDotEnv();
-    await context.lowdefyBuild();
-    context.restartServer();
+    // The server reads the environment only when it starts, and a later
+    // successful config build does not restart it, so it restarts with the
+    // new environment even when this build fails.
+    try {
+      await context.lowdefyBuild();
+    } finally {
+      await context.syncServer({ restart: true });
+    }
   };
   return setupWatcher({
     callback,
     context,
+    onBusy: context.buildActivity.setBusy,
     watchDotfiles: true,
     watchPaths: [path.join(context.directories.config, '.env')],
   });