@lowdefy/server-dev 6.1.0 → 7.0.0

package/manager/run.mjs

@@ -15,22 +15,30 @@
   limitations under the License.
 */
 
-import { wait } from '@lowdefy/helpers';
-import { findAvailablePort } from '@lowdefy/node-utils';
 import opener from 'opener';
+import { registerServer, watchOwner } from '@lowdefy/node-utils';
+import checkAgentFiles from '../lib/docs/checkAgentFiles.js';
 import getContext from './getContext.mjs';
+import getLowdefyVersion from './utils/getLowdefyVersion.mjs';
+import acquireDevInstance from './utils/acquireDevInstance.mjs';
+import createBuildActivity from './utils/createBuildActivity.mjs';
+import createIdleGc from './utils/createIdleGc.mjs';
+import createRequestActivity from './utils/createRequestActivity.mjs';
+import startMailSink from './processes/startMailSink.mjs';
 import startProxy from './processes/startProxy.mjs';
-import startServer from './processes/startServer.mjs';
+import startFirstServer from './processes/startFirstServer.mjs';
+import startRecordingPruner from './utils/startRecordingPruner.mjs';
 import formatNoticeBox from './utils/formatNoticeBox.mjs';
+import resolvePorts from './utils/resolvePorts.mjs';
 
 /*
 The run script does the following:
-  - Run the initial Lowdefy build, install plugins, and next build and read .env
+  - Read .env, run the initial Lowdefy build and install plugins
   - Start file watchers to reload config and restart server if necessary
   - Start the server
   - Open a browser window.
 
-  Three watchers are started:
+  Watchers (see processes/startWatchers.mjs):
 
   ## Lowdefy build watcher
   Watches:
@@ -48,25 +56,14 @@ The run script does the following:
   If the .env file is changed, the new file is parsed, and the server restarted with the new env
   and the server hard reloads.
 
-  ## Next build watcher
+  ## Local plugin, restart request and server package.json watchers
 
-  The Next build watcher watches for any files where the app should be rebuilt and restarted.
-  It watches:
-  - <build-dir>/plugins/**
-  - <build-dir>/config.json
-  - <server-dir>/package.json
+  A local plugin change rebuilds (and restarts when the plugin has server-side types), a restart
+  requested by the dev tools rebuilds and restarts, and a plugin package a page build added to
+  the server's package.json is installed.
 
-  If app config changes:
-    - <build-dir>/config.json changes, rebuild and restart server.
-
-  If user styles change:
-    - <public-dir>/styles.css changes, rebuild and restart server.
-
-  If new plugin type in an existing plugin package is used:
-    - <build-dir>/plugins/** changes,  rebuild next and restart server.
-
-  If new plugin type in a new plugin package is used:
-    - <server-dir>/package.json changes,  run npm install, rebuild next and restart server.
+  After every build, syncServer restarts the server when a file it read at start changed (config,
+  auth, connections, server operators), installing new plugin packages first.
 
   # Reload mechanism
 
@@ -81,45 +78,123 @@ The run script does the following:
 
 const context = await getContext();
 
+const instance = acquireDevInstance({
+  configDirectory: context.directories.config,
+  owner: context.options.owner,
+  version: context.version,
+});
+if (instance.acquired === false) {
+  const { holder } = instance;
+  const where = holder.port ? `, http://localhost:${holder.port}` : '';
+  context.logger.error(
+    `A dev server for this app is already running (${holder.owner ?? 'terminal'}${where}, pid ${
+      holder.pid
+    }). ` +
+      'Two dev servers race writing the build directory. Use the running one, or stop it first.'
+  );
+  process.exit(1);
+}
+process.on('exit', () => instance.release());
+startRecordingPruner({ configDirectory: context.directories.config, logger: context.logger });
+
+// Requests through the proxy and finished builds are use of the server; the
+// hub stops a server nobody has used for its idle limit (see
+// createRequestActivity).
+context.requestActivity = createRequestActivity({
+  onChange: (fields) => instance.update(fields),
+});
+
+// `building` is true while a change is queued or being processed, restarts
+// included. lowdefy_build_status({ wait: true }) waits on it, so an agent
+// reads the build that includes its last edit instead of the one before.
+// One full GC shortly after each build, which is when the manager's heap grows.
+const idleGc = createIdleGc();
+
+context.buildActivity = createBuildActivity({
+  onChange: (building) => {
+    instance.update({ building });
+    idleGc.onBuildingChange(building);
+    if (!building) {
+      context.requestActivity.touch();
+    }
+  },
+});
+
+// Machine-wide record of this manager and its owner, for `lowdefy hub ps|prune`.
+// Written only when the CLI sets the registry directory.
+const registration = registerServer({
+  kind: 'dev',
+  port: context.options.port,
+  configDirectory: context.directories.config,
+  logger: context.logger,
+});
+
+function shutdown() {
+  context.shutdownServer();
+  process.exit(0);
+}
+
 // Shut the Vite child down on direct signals (process managers, scripts/dev.mjs
 // signal forwarding) — terminal Ctrl+C signals the whole process group, but a
 // targeted SIGTERM would otherwise orphan the child.
-for (const signal of ['SIGINT', 'SIGTERM']) {
-  process.on(signal, () => {
-    context.shutdownServer();
-    process.exit(0);
-  });
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, shutdown);
 }
 
+// A manager started by the CLI, a test runner or a script stops when that
+// owner stops, however it ends. Inert unless the spawner set its variables.
+watchOwner({
+  onExit: ({ reason }) => {
+    context.logger.info(`The process that started this dev server is gone (${reason}).`);
+    shutdown();
+  },
+});
+
 try {
   await context.initialBuild();
 
-  // We are not waiting for the startWatchers promise to resolve (all watchers have fired the ready event)
-  // because chokidar sometimes doesn't fire this event, and it seems like there isn't an issue with not waiting.
+  // Not awaited: chokidar's ready event is unreliable. Started now so an edit
+  // made during the rest of the start-up is seen; a batch that syncs before
+  // the first child start waits for it (see syncServer).
   context.startWatchers();
 
-  // The manager is the component that binds the port, so it re-checks here to
+  // The manager is the component that binds the port, so it checks here to
   // cover every launch path (CLI, monorepo dev script, direct run.mjs) and any
   // process that grabbed the port during the initial build.
-  const availablePort = await findAvailablePort({ port: context.options.port });
-  if (availablePort !== context.options.port) {
-    context.logger.warn(
-      `Port ${context.options.port} is in use, using port ${availablePort} instead.`
-    );
-    context.options.port = availablePort;
-  }
+  const { port, internalPort } = await resolvePorts(context);
+  context.options.port = port;
+  context.internalPort = internalPort;
+  instance.update({ port, internalPort });
+  registration?.update({ port });
+  context.instance = instance;
+
+  // Called by waitForDevServer whenever a child answers: the first start's,
+  // one that answers after its wait, or a restart's after a first child that
+  // exited. The hub and the MCP shim wait on ready.
+  let ready = false;
+  context.markServerReady = () => {
+    if (ready) {
+      return;
+    }
+    ready = true;
+    // A slow first build must not make a fresh server look idle the moment it is ready.
+    context.requestActivity.touch();
+    instance.update({ state: 'ready' });
+  };
 
   // The manager holds the public port for the whole session and proxies to the
   // Vite child on an internal loopback port — restarting the child (js module
   // or .env change) then never drops the listener, so long-lived clients (MCP
   // agents, the reload SSE stream, HMR websockets) reconnect instead of dying
   // on ECONNREFUSED.
-  context.internalPort = await findAvailablePort({ port: context.options.port + 1 });
   await startProxy(context);
+  context.mailSink = await startMailSink(context);
 
-  startServer(context);
-  await wait(800);
-  const docsUrl = `http://localhost:${context.options.port}/lowdefy-docs`;
+  // Optimises dependencies, starts the child and waits for it to answer.
+  if (!(await startFirstServer(context))) {
+    context.logger.warn('The dev server did not answer within 2 minutes - check the output above.');
+  }
+  const docsUrl = `${context.url}/lowdefy-docs`;
   context.logger.info(
     { color: 'blue' },
     formatNoticeBox({
@@ -137,9 +212,19 @@ try {
       ],
     })
   );
-  if (process.env.LOWDEFY_SERVER_DEV_OPEN_BROWSER === 'true') {
+  // Lowdefy's agent block: missing, from another version, or not imported by
+  // CLAUDE.md. Build status reports the same notices to agents on every read.
+  const agentFiles = checkAgentFiles({
+    configDirectory: context.directories.config,
+    lowdefyVersion: await getLowdefyVersion(context).catch(() => null),
+  });
+  for (const notice of agentFiles) {
+    context.logger.warn(notice.message);
+  }
+  // A hub-owned server was started for an agent, not for a person at a browser.
+  if (process.env.LOWDEFY_SERVER_DEV_OPEN_BROWSER === 'true' && context.options.owner !== 'hub') {
     // TODO: Wait 1 sec for a ping and don't open if a ping is seen
-    opener(`http://localhost:${context.options.port}`);
+    opener(context.url);
   }
   await new Promise(() => {});
 } catch (error) {

package/manager/utils/BatchChanges.mjs

@@ -17,21 +17,40 @@
 import { type } from '@lowdefy/helpers';
 
 class BatchChanges {
-  constructor({ context, fn, delay }) {
+  constructor({ context, fn, delay, onBusy }) {
     this.context = context;
     this._call = this._call.bind(this);
     this.args = [];
+    this.busy = false;
     this.delay = delay || 500;
     this.fn = fn;
+    this.onBusy = onBusy ?? (() => {});
     this.repeat = false;
     this.running = false;
   }
 
   newChange(...args) {
     this.args.push(args.filter((arg) => type.isString(arg))); // filter for string paths since chokidar also returns an stats object on windows.
+    // Busy from the first change of a batch until the batch - and any batch
+    // queued behind it - has been processed, so a reader can wait for its
+    // edits to land instead of racing the debounce.
+    if (!this.busy) {
+      this.busy = true;
+      this.onBusy(true);
+    }
     this._startTimer();
   }
 
+  _settle() {
+    if (this.repeat) {
+      this.repeat = false;
+      this._call();
+      return;
+    }
+    this.busy = false;
+    this.onBusy(false);
+  }
+
   _startTimer() {
     if (this.timer) {
       clearTimeout(this.timer);
@@ -50,14 +69,11 @@ class BatchChanges {
       this.args = [];
       await this.fn(args);
       this.running = false;
-      if (this.repeat) {
-        this.repeat = false;
-        this._call();
-      }
     } catch (error) {
       this.running = false;
       this.context.logger.error(error?.message ?? error);
     }
+    this._settle();
   }
 }
 

package/manager/utils/BatchChanges.test.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 { jest } from '@jest/globals';
+import { wait } from '@lowdefy/helpers';
+
+import BatchChanges from './BatchChanges.mjs';
+
+const context = { logger: { error: jest.fn() } };
+
+test('BatchChanges reports busy from the first change until the batch is processed', async () => {
+  const events = [];
+  const fn = jest.fn(async () => {
+    events.push('processed');
+  });
+  const batch = new BatchChanges({
+    context,
+    fn,
+    delay: 20,
+    onBusy: (busy) => events.push(busy ? 'busy' : 'idle'),
+  });
+  batch.newChange('a.yaml');
+  batch.newChange('b.yaml');
+  expect(events).toEqual(['busy']);
+  await wait(80);
+  expect(events).toEqual(['busy', 'processed', 'idle']);
+  expect(fn).toHaveBeenCalledWith([['a.yaml'], ['b.yaml']]);
+});
+
+test('BatchChanges stays busy through a change that arrives while a batch is running', async () => {
+  const events = [];
+  let batch;
+  const fn = jest.fn(async (args) => {
+    events.push(`processed ${args.flat().join(',')}`);
+    if (args.flat().includes('a.yaml')) {
+      batch.newChange('b.yaml');
+      await wait(10);
+    }
+  });
+  batch = new BatchChanges({
+    context,
+    fn,
+    delay: 10,
+    onBusy: (busy) => events.push(busy ? 'busy' : 'idle'),
+  });
+  batch.newChange('a.yaml');
+  await wait(100);
+  expect(events).toEqual(['busy', 'processed a.yaml', 'processed b.yaml', 'idle']);
+});
+
+test('BatchChanges clears busy when processing throws', async () => {
+  const events = [];
+  const batch = new BatchChanges({
+    context,
+    fn: async () => {
+      throw new Error('build failed');
+    },
+    delay: 10,
+    onBusy: (busy) => events.push(busy ? 'busy' : 'idle'),
+  });
+  batch.newChange('a.yaml');
+  await wait(50);
+  expect(events).toEqual(['busy', 'idle']);
+});

package/manager/utils/acquireDevInstance.mjs

@@ -0,0 +1,99 @@
+/*
+  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';
+
+import { getDevInstancePath, getProcessStartTime, readDevInstance } from '@lowdefy/node-utils';
+
+function writeRecord({ instancePath, record }) {
+  // Written whole and renamed into place so readers never see half a record.
+  const temporaryPath = `${instancePath}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(instancePath), { recursive: true });
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporaryPath, instancePath);
+}
+
+// One dev server per app. Two managers on one app race each other's builds -
+// one wedges on a half-deleted pages directory and keeps serving a stale build
+// with no error anywhere - so the second refuses. The record doubles as the
+// discovery file: the CLI, the MCP shim and the hub read it to find this
+// server's port, owner and readiness without a registry of their own.
+// Creating the file exclusively decides a race between two managers starting
+// at once: exactly one create succeeds.
+function createRecord({ instancePath, record }) {
+  fs.mkdirSync(path.dirname(instancePath), { recursive: true });
+  try {
+    const fd = fs.openSync(instancePath, 'wx', 0o600);
+    fs.writeSync(fd, `${JSON.stringify(record, null, 2)}\n`);
+    fs.closeSync(fd);
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function acquireDevInstance({ configDirectory, owner, version }) {
+  const instancePath = getDevInstancePath({ configDirectory });
+  let record = {
+    pid: process.pid,
+    // Readers check it against the pid's process, so a record left by a
+    // killed manager never passes for a live one on a reused pid.
+    processStartTime: getProcessStartTime({ pid: process.pid }),
+    // The path as stored on disk, whatever case the terminal's working
+    // directory was typed in (macOS), so lowdefy mcp and the hub match it.
+    configDirectory: fs.realpathSync.native(configDirectory),
+    owner,
+    state: 'starting',
+    building: false,
+    version,
+    startedAt: new Date().toISOString(),
+  };
+  if (!createRecord({ instancePath, record })) {
+    const holder = readDevInstance({ configDirectory });
+    if (holder !== null && holder.pid !== process.pid) {
+      return { acquired: false, holder, instancePath };
+    }
+    // Stale: the holder exited, or the file was copied from another checkout.
+    fs.rmSync(instancePath, { force: true });
+    if (!createRecord({ instancePath, record })) {
+      return { acquired: false, holder: readDevInstance({ configDirectory }) ?? {}, instancePath };
+    }
+  }
+
+  function update(fields) {
+    record = { ...record, ...fields };
+    writeRecord({ instancePath, record });
+  }
+
+  function release() {
+    try {
+      const current = JSON.parse(fs.readFileSync(instancePath, 'utf8'));
+      if (current.pid === process.pid) {
+        fs.rmSync(instancePath, { force: true });
+      }
+    } catch {
+      // Already gone, or taken over after a crash - nothing to release.
+    }
+  }
+
+  return { acquired: true, instancePath, release, update };
+}
+
+export default acquireDevInstance;

package/manager/utils/acquireDevInstance.test.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 fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+import { getProcessStartTime, isProcessStartTime, readDevInstance } from '@lowdefy/node-utils';
+
+import acquireDevInstance from './acquireDevInstance.mjs';
+
+let configDirectory;
+
+beforeEach(() => {
+  configDirectory = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'dev-instance-')));
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+function instancePath() {
+  return path.join(configDirectory, '.lowdefy', 'instance.json');
+}
+
+function readRecord() {
+  return JSON.parse(fs.readFileSync(instancePath(), 'utf8'));
+}
+
+// Windows has no owner-only file mode bits.
+const onPosix = process.platform === 'win32' ? test.skip : test;
+
+test('acquireDevInstance writes a starting record for this process', () => {
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(instance.acquired).toBe(true);
+  expect(readRecord()).toMatchObject({
+    pid: process.pid,
+    configDirectory,
+    owner: 'terminal',
+    state: 'starting',
+    version: '6.0.0',
+  });
+});
+
+onPosix('acquireDevInstance writes the record readable only by the owner', () => {
+  acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(fs.statSync(instancePath()).mode & 0o777).toBe(0o600);
+});
+
+test('acquireDevInstance update merges fields into the record', () => {
+  const instance = acquireDevInstance({ configDirectory, owner: 'hub', version: '6.0.0' });
+  instance.update({ port: 4100, internalPort: 4101 });
+  instance.update({ state: 'ready' });
+  expect(readRecord()).toMatchObject({
+    owner: 'hub',
+    port: 4100,
+    internalPort: 4101,
+    state: 'ready',
+  });
+});
+
+test('acquireDevInstance release removes the record', () => {
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  instance.release();
+  expect(fs.existsSync(instancePath())).toBe(false);
+});
+
+test('acquireDevInstance refuses when a live process holds this app', () => {
+  // The parent process is alive for the whole test and is never this process,
+  // on every platform (Windows has no pid 1).
+  const livePid = process.ppid;
+  fs.mkdirSync(path.dirname(instancePath()), { recursive: true });
+  fs.writeFileSync(instancePath(), JSON.stringify({ pid: livePid, configDirectory, port: 3000 }));
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(instance.acquired).toBe(false);
+  expect(instance.holder).toEqual({ pid: livePid, configDirectory, port: 3000 });
+});
+
+test('acquireDevInstance takes over a record whose process has exited', () => {
+  const dead = spawnSync(process.execPath, ['-e', '']).pid;
+  fs.mkdirSync(path.dirname(instancePath()), { recursive: true });
+  fs.writeFileSync(instancePath(), JSON.stringify({ pid: dead, configDirectory }));
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(instance.acquired).toBe(true);
+  expect(readRecord().pid).toBe(process.pid);
+});
+
+test('acquireDevInstance takes over a record copied from another checkout', () => {
+  fs.mkdirSync(path.dirname(instancePath()), { recursive: true });
+  fs.writeFileSync(instancePath(), JSON.stringify({ pid: 1, configDirectory: '/other/checkout' }));
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(instance.acquired).toBe(true);
+});
+
+test('acquireDevInstance release leaves a record taken over by a newer manager', () => {
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  fs.writeFileSync(instancePath(), JSON.stringify({ pid: 1, configDirectory }));
+  instance.release();
+  expect(fs.existsSync(instancePath())).toBe(true);
+});
+
+// A start time in the form this platform reads, but not the one the pid's process has: on
+// Linux, the same ticks in another boot.
+function otherStartTime(pid) {
+  const startTime = getProcessStartTime({ pid });
+  if (typeof startTime === 'string') {
+    return startTime.replace(/^linux:[^:]+:/, 'linux:00000000-0000-0000-0000-000000000000:');
+  }
+  return 0;
+}
+
+test('acquireDevInstance takes over a record left on a pid another process now has', () => {
+  // pid 1 is alive, but it is not the manager that wrote this record.
+  fs.mkdirSync(path.dirname(instancePath()), { recursive: true });
+  fs.writeFileSync(
+    instancePath(),
+    JSON.stringify({ pid: 1, processStartTime: otherStartTime(1), configDirectory })
+  );
+  const instance = acquireDevInstance({ configDirectory, owner: 'terminal', version: '6.0.0' });
+  expect(instance.acquired).toBe(true);
+  expect(isProcessStartTime(readRecord().processStartTime)).toBe(true);
+});
+
+// Case variants name one directory only where the file system ignores case.
+const tmpReal = fs.realpathSync.native(os.tmpdir());
+const onCaseInsensitiveFs =
+  tmpReal !== tmpReal.toUpperCase() && fs.existsSync(tmpReal.toUpperCase()) ? test : test.skip;
+
+onCaseInsensitiveFs(
+  'acquireDevInstance records the path as stored on disk when started from a case variant of it',
+  () => {
+    const variant = configDirectory.toUpperCase();
+    const instance = acquireDevInstance({
+      configDirectory: variant,
+      owner: 'terminal',
+      version: '6.0.0',
+    });
+    try {
+      expect(readRecord().configDirectory).toEqual(configDirectory);
+      expect(readDevInstance({ configDirectory })).toMatchObject({ pid: process.pid });
+      expect(readDevInstance({ configDirectory: variant })).toMatchObject({ pid: process.pid });
+    } finally {
+      instance.release();
+    }
+  }
+);