@lowdefy/server-dev 6.1.0 → 7.1.0

package/manager/utils/findBuildFilesOutsideWatch.test.mjs

@@ -0,0 +1,111 @@
+/*
+  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 findBuildFilesOutsideWatch from './findBuildFilesOutsideWatch.mjs';
+
+let root;
+let buildDirectory;
+let configDirectory;
+
+function writeRefMap(refMap) {
+  fs.writeFileSync(path.join(buildDirectory, 'refMap.json'), JSON.stringify(refMap));
+  return path.join(buildDirectory, 'refMap.json');
+}
+
+function writeJitMaps(name, refMap) {
+  const filePath = path.join(buildDirectory, 'jitMaps', name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify({ keyMap: {}, refMap }));
+  return filePath;
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-build-files-'));
+  buildDirectory = path.join(root, 'app', '.lowdefy', 'server', 'build');
+  configDirectory = path.join(root, 'app');
+  fs.mkdirSync(buildDirectory, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('findBuildFilesOutsideWatch returns files the build read outside the watched directories', () => {
+  const refMapFile = writeRefMap({
+    1: { parent: null },
+    2: { parent: '1', path: 'pages.yaml' },
+    3: { parent: '2', path: '../shared/header.yaml' },
+    4: { parent: null, path: path.join(root, 'modules', 'layout', 'components', 'page.yaml') },
+    5: { parent: '4', path: path.join(root, 'modules', 'shared', 'title-block.yaml') },
+    6: { parent: '4', path: path.join(root, 'modules', 'shared', 'title-block.yaml') },
+  });
+
+  const files = findBuildFilesOutsideWatch({
+    mapsFiles: [refMapFile],
+    configDirectory,
+    watchRoots: [configDirectory, path.join(root, 'modules', 'layout')],
+  });
+
+  expect(files).toEqual([
+    path.join(root, 'shared', 'header.yaml'),
+    path.join(root, 'modules', 'shared', 'title-block.yaml'),
+  ]);
+});
+
+test('findBuildFilesOutsideWatch skips refs without a file path', () => {
+  const refMapFile = writeRefMap({
+    1: { parent: null },
+    2: { parent: '1', path: null, original: { resolver: 'resolver.js' } },
+  });
+
+  const files = findBuildFilesOutsideWatch({
+    mapsFiles: [refMapFile],
+    configDirectory,
+    watchRoots: [configDirectory],
+  });
+
+  expect(files).toEqual([]);
+});
+
+test("findBuildFilesOutsideWatch reads a JIT page build's refs from its jitMaps file alone", () => {
+  writeRefMap({ 1: { parent: null, path: '../shared/skeleton.yaml' } });
+  const jitMapsFile = writeJitMaps('abc123-1-1.json', {
+    p_abc123_1: { parent: null, path: 'pages/home.yaml' },
+    p_abc123_2: { parent: 'p_abc123_1', path: '../shared/header.yaml' },
+  });
+
+  const files = findBuildFilesOutsideWatch({
+    mapsFiles: [jitMapsFile],
+    configDirectory,
+    watchRoots: [configDirectory],
+  });
+
+  expect(files).toEqual([path.join(root, 'shared', 'header.yaml')]);
+});
+
+test('findBuildFilesOutsideWatch skips a jitMaps file pruned before it was read', () => {
+  const files = findBuildFilesOutsideWatch({
+    mapsFiles: [path.join(buildDirectory, 'jitMaps', 'gone-1-1.json')],
+    configDirectory,
+    watchRoots: [configDirectory],
+  });
+
+  expect(files).toEqual([]);
+});

package/manager/utils/importFresh.mjs

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { pathToFileURL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+
+// Node keeps every module it loads for the life of the process, and an ES
+// module can not be dropped from that cache, so importing a changed file again
+// in the manager returns the old module and the old modules it imports. A
+// plugin's type list is read from its built files, which change while the dev
+// server runs (a new block, request or operator type), so each read imports
+// the file in a new worker thread, which starts with an empty module cache.
+// Resolves to the module's default export (its namespace if it has none),
+// copied to the manager as structured-clone data.
+function importFresh(filePath) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL('./importFreshWorker.mjs', import.meta.url), {
+      workerData: { url: pathToFileURL(filePath).href },
+    });
+    worker.once('message', (value) => {
+      resolve(value);
+      worker.terminate();
+    });
+    worker.once('error', reject);
+    worker.once('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Importing "${filePath}" stopped with exit code ${code}.`));
+      }
+    });
+  });
+}
+
+export default importFresh;

package/manager/utils/importFresh.test.mjs

@@ -0,0 +1,72 @@
+/*
+  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 importFresh from './importFresh.mjs';
+
+let pluginDir;
+
+beforeEach(() => {
+  pluginDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-import-fresh-'));
+  fs.writeFileSync(path.join(pluginDir, 'package.json'), JSON.stringify({ type: 'module' }));
+  fs.writeFileSync(
+    path.join(pluginDir, 'types.js'),
+    "import * as metas from './metas.js';\nexport default { blocks: Object.keys(metas) };\n"
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(pluginDir, { recursive: true, force: true });
+});
+
+test('importFresh returns the default export of the module', async () => {
+  fs.writeFileSync(path.join(pluginDir, 'metas.js'), 'export const Card = {};\n');
+
+  const types = await importFresh(path.join(pluginDir, 'types.js'));
+
+  expect(types).toEqual({ blocks: ['Card'] });
+});
+
+test('importFresh sees a change to a module the imported file imports', async () => {
+  fs.writeFileSync(path.join(pluginDir, 'metas.js'), 'export const Card = {};\n');
+  const before = await importFresh(path.join(pluginDir, 'types.js'));
+
+  fs.writeFileSync(
+    path.join(pluginDir, 'metas.js'),
+    'export const Card = {};\nexport const TaskList = {};\n'
+  );
+  const after = await importFresh(path.join(pluginDir, 'types.js'));
+
+  expect(before).toEqual({ blocks: ['Card'] });
+  expect(after).toEqual({ blocks: ['Card', 'TaskList'] });
+});
+
+test('importFresh returns the namespace of a module without a default export', async () => {
+  fs.writeFileSync(path.join(pluginDir, 'messages.js'), "export const hello = 'Hello';\n");
+
+  const messages = await importFresh(path.join(pluginDir, 'messages.js'));
+
+  expect(messages).toEqual({ hello: 'Hello' });
+});
+
+test('importFresh rejects when the module throws', async () => {
+  fs.writeFileSync(path.join(pluginDir, 'broken.js'), "throw new Error('Broken plugin.');\n");
+
+  await expect(importFresh(path.join(pluginDir, 'broken.js'))).rejects.toThrow('Broken plugin.');
+});

package/manager/utils/importFreshWorker.mjs

@@ -0,0 +1,20 @@
+/*
+  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 { parentPort, workerData } from 'node:worker_threads';
+
+const module = await import(workerData.url);
+parentPort.postMessage(module.default ?? { ...module });

package/manager/utils/killTaggedBrowser.mjs

@@ -0,0 +1,35 @@
+/*
+  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 { spawn } from 'child_process';
+
+// Kills the browser a Vite child launched, found by the tag the manager gave
+// that child (see launchBrowser.js). A child that exits normally already
+// takes its browser with it; this is for one killed outright, whose system
+// Chrome runs in its own process group and is left running. Chrome's helper
+// processes do not carry the tag; they exit with the browser process.
+function killTaggedBrowser({ tag }) {
+  // Windows has no pkill. Best effort, as for the other process clean-up:
+  // the headless shell, the default browser, exits with its parent anyway.
+  if (process.platform === 'win32') {
+    return;
+  }
+  // pkill exits 1 when nothing matched, the usual case.
+  const pkill = spawn('pkill', ['-f', '--', `--lowdefy-browser-tag=${tag}`], { stdio: 'ignore' });
+  pkill.on('error', () => {});
+}
+
+export default killTaggedBrowser;

package/manager/utils/pagePathChanged.mjs

@@ -0,0 +1,56 @@
+/*
+  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 { resolvePagePath } from '@lowdefy/build/dev';
+
+// Whether a changed page file now declares a path other than the one its page
+// has in routes.json (adding or removing a path included). Page files are not
+// skeleton sources, so without this the old URL would keep matching and the
+// new one would 404 until the config is rebuilt.
+async function pagePathChanged({ changedFiles, context }) {
+  const changed = new Set(changedFiles);
+  const pageIds = [...context.pageRegistry.values()]
+    .filter((pageEntry) => changed.has(pageEntry.refPath))
+    .map((pageEntry) => pageEntry.pageId);
+  if (pageIds.length === 0) {
+    return false;
+  }
+  const routes = JSON.parse(
+    fs.readFileSync(path.join(context.directories.build, 'routes.json'), 'utf8')
+  );
+  const routePaths = new Map(routes.map((route) => [route.pageId, route.path]));
+  for (const pageId of pageIds) {
+    let pagePath;
+    try {
+      pagePath = await resolvePagePath({
+        pageId,
+        pageRegistry: context.pageRegistry,
+        context: context.buildContext,
+      });
+    } catch {
+      // A page file that does not resolve is reported by its page build.
+      continue;
+    }
+    if (pagePath !== routePaths.get(pageId)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export default pagePathChanged;

package/manager/utils/pruneRecordings.mjs

@@ -0,0 +1,85 @@
+/*
+  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';
+
+// Only what the dev server records. traces/production/ is the production
+// mining cache, pruned by its own command on its own schedule.
+const PRUNED_SOURCES = ['dev', 'journey'];
+const DATE_DIRECTORY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function listDateDirectories({ tracesDirectory }) {
+  return PRUNED_SOURCES.flatMap((source) => {
+    const sourceDirectory = path.join(tracesDirectory, source);
+    if (!fs.existsSync(sourceDirectory)) return [];
+    return fs
+      .readdirSync(sourceDirectory, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && DATE_DIRECTORY_PATTERN.test(entry.name))
+      .map((entry) => ({ date: entry.name, path: path.join(sourceDirectory, entry.name) }));
+  });
+}
+
+function listTraceFiles({ dateDirectories }) {
+  return dateDirectories.flatMap((directory) =>
+    fs
+      .readdirSync(directory.path, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
+      .map((entry) => {
+        const filePath = path.join(directory.path, entry.name);
+        const stat = fs.statSync(filePath);
+        return { path: filePath, size: stat.size, mtimeMs: stat.mtimeMs };
+      })
+  );
+}
+
+// Recordings are kept 7 days or 200 MB, whichever is smaller. Date
+// directories older than maxAgeDays go first, then the oldest files by mtime
+// until the rest fit, never the newest file (the tab recording right now).
+function pruneRecordings({
+  configDirectory,
+  now = Date.now(),
+  maxAgeDays = 7,
+  maxBytes = 200 * 1024 * 1024,
+}) {
+  const tracesDirectory = path.join(configDirectory, '.lowdefy', 'traces');
+  const cutoff = new Date(now - maxAgeDays * DAY_MS).toISOString().slice(0, 10);
+  const deleted = { directories: [], files: [] };
+
+  const dateDirectories = listDateDirectories({ tracesDirectory });
+  const kept = [];
+  dateDirectories.forEach((directory) => {
+    if (directory.date < cutoff) {
+      fs.rmSync(directory.path, { recursive: true, force: true });
+      deleted.directories.push(directory.path);
+      return;
+    }
+    kept.push(directory);
+  });
+
+  const files = listTraceFiles({ dateDirectories: kept }).sort((a, b) => a.mtimeMs - b.mtimeMs);
+  let total = files.reduce((sum, file) => sum + file.size, 0);
+  for (const file of files.slice(0, -1)) {
+    if (total <= maxBytes) break;
+    fs.rmSync(file.path, { force: true });
+    deleted.files.push(file.path);
+    total -= file.size;
+  }
+  return deleted;
+}
+
+export default pruneRecordings;

package/manager/utils/pruneRecordings.test.mjs

@@ -0,0 +1,117 @@
+/*
+  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 pruneRecordings from './pruneRecordings.mjs';
+
+const NOW = Date.parse('2026-10-03T12:00:00Z');
+let configDirectory;
+
+function tracePath(...segments) {
+  return path.join(configDirectory, '.lowdefy', 'traces', ...segments);
+}
+
+function writeFile({ segments, size = 10, mtimeMs = NOW }) {
+  const filePath = tracePath(...segments);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, 'x'.repeat(size));
+  fs.utimesSync(filePath, mtimeMs / 1000, mtimeMs / 1000);
+  return filePath;
+}
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-prune-'));
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+test('pruneRecordings deletes date directories older than 7 days under dev and journey', () => {
+  ['dev', 'journey'].forEach((source) => {
+    writeFile({ segments: [source, '2026-09-25', '20260925T100000Z-old000.jsonl'] });
+    writeFile({ segments: [source, '2026-09-26', '20260926T100000Z-keep00.jsonl'] });
+  });
+  const deleted = pruneRecordings({ configDirectory, now: NOW });
+  expect(deleted.directories).toHaveLength(2);
+  ['dev', 'journey'].forEach((source) => {
+    expect(fs.existsSync(tracePath(source, '2026-09-25'))).toBe(false);
+    expect(fs.existsSync(tracePath(source, '2026-09-26', '20260926T100000Z-keep00.jsonl'))).toBe(
+      true
+    );
+  });
+});
+
+test('pruneRecordings trims the oldest files by mtime until the rest fit, keeping the newest', () => {
+  const oldest = writeFile({
+    segments: ['dev', '2026-10-03', '20261003T080000Z-aaaaaa.jsonl'],
+    size: 40,
+    mtimeMs: NOW - 3000,
+  });
+  const middle = writeFile({
+    segments: ['journey', '2026-10-03', '20261003T090000Z-bbbbbb.jsonl'],
+    size: 40,
+    mtimeMs: NOW - 2000,
+  });
+  const newest = writeFile({
+    segments: ['dev', '2026-10-03', '20261003T100000Z-cccccc.jsonl'],
+    size: 40,
+    mtimeMs: NOW - 1000,
+  });
+  const deleted = pruneRecordings({ configDirectory, now: NOW, maxBytes: 90 });
+  expect(deleted.files).toEqual([oldest]);
+  expect(fs.existsSync(middle)).toBe(true);
+  expect(fs.existsSync(newest)).toBe(true);
+});
+
+test('pruneRecordings never deletes the newest file, even when it alone is over the limit', () => {
+  const older = writeFile({
+    segments: ['dev', '2026-10-03', '20261003T080000Z-aaaaaa.jsonl'],
+    size: 50,
+    mtimeMs: NOW - 2000,
+  });
+  const newest = writeFile({
+    segments: ['dev', '2026-10-03', '20261003T100000Z-cccccc.jsonl'],
+    size: 200,
+    mtimeMs: NOW - 1000,
+  });
+  pruneRecordings({ configDirectory, now: NOW, maxBytes: 100 });
+  expect(fs.existsSync(older)).toBe(false);
+  expect(fs.existsSync(newest)).toBe(true);
+});
+
+test('pruneRecordings leaves foreign files and the production cache alone', () => {
+  const production = writeFile({
+    segments: ['production', '2026-01-01', 'events.jsonl'],
+    size: 500,
+  });
+  const foreignDirectory = writeFile({ segments: ['dev', 'scratch', 'notes.jsonl'], size: 500 });
+  const foreignFile = writeFile({ segments: ['dev', '2026-10-03', 'notes.txt'], size: 500 });
+  const loose = writeFile({ segments: ['dev', 'old.jsonl'], size: 500, mtimeMs: NOW - 99999 });
+  writeFile({ segments: ['dev', '2026-10-03', '20261003T100000Z-cccccc.jsonl'], size: 10 });
+  const deleted = pruneRecordings({ configDirectory, now: NOW, maxBytes: 1 });
+  expect(deleted).toEqual({ directories: [], files: [] });
+  [production, foreignDirectory, foreignFile, loose].forEach((filePath) => {
+    expect(fs.existsSync(filePath)).toBe(true);
+  });
+});
+
+test('pruneRecordings does nothing when there are no traces', () => {
+  expect(pruneRecordings({ configDirectory, now: NOW })).toEqual({ directories: [], files: [] });
+});

package/manager/utils/publishBuildDirectory.mjs

@@ -0,0 +1,121 @@
+/*
+  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/promises';
+import path from 'path';
+
+import filesHaveSameBytes from './filesHaveSameBytes.mjs';
+
+async function listFiles(directory) {
+  const entries = await fs.readdir(directory, { recursive: true, withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.relative(directory, path.join(entry.parentPath, entry.name)));
+}
+
+// The dev server reads build artifacts from disk on every request. Emptying
+// the build directory and writing the new build into it leaves a window where
+// artifacts are missing, so the build is written to a staging directory and
+// moved over the live one file by file. A rename replaces a file in one step,
+// so a reader always finds each artifact, from the old build or the new one.
+// A staged file whose bytes equal the live one is left in staging, so the
+// live file keeps its mtime and Vite, which watches the build directory, does
+// not re-process every client artifact after each config build. Live files
+// the new build did not write are removed next. The page registry
+// is moved last: the JIT page builder rebuilds its cached build context, and
+// drops its built pages, when the registry changes, so the registry must
+// arrive after every other new file and after the old build's pages are gone.
+// It is moved even when its bytes are unchanged: the JIT page builder learns
+// of a config build only from its identity (inode and mtime), which a rename
+// always changes.
+// The live directory itself is never replaced, so file watchers on it keep
+// working.
+const pageRegistryFile = 'pageRegistry.json';
+
+// idCounter.json is moved first. A JIT page build writes keyMap.json and refMap.json
+// only while the live idCounter.json still names the config build it started from
+// (skipStaleMapWrites), so the new idCounter.json must be live before the new maps
+// arrive, or a page build of the old config could write its maps over them.
+// It is moved even when its bytes are unchanged, so the order holds for every
+// build.
+const idCounterFile = 'idCounter.json';
+
+// Files the manager and the dev tools write into the build directory to
+// signal each other. The build does not write them, so they are never in the
+// staged build, and removing them as stale would drop the signal: a restart
+// request (.restart), a page invalidation or client reload queued behind the
+// build, or the build status the dev tools read.
+const controlFiles = new Set(['.restart', 'buildStatus.json', 'invalidatePages', 'reload']);
+
+// On Windows a rename over a file another process has open (the dev server
+// reading it, a virus scanner, the search indexer) fails for a moment with
+// EPERM, EBUSY or EACCES, so each rename is retried for a few seconds before
+// the publish fails.
+const LOCKED_CODES = new Set(['EACCES', 'EBUSY', 'EPERM']);
+const RENAME_DELAYS_MS = [25, 50, 100, 200, 400, 500, 500, 500, 500, 500];
+const RM_OPTIONS = { force: true, recursive: true, maxRetries: 5 };
+
+async function renameWithRetry({ from, to }) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await fs.rename(from, to);
+      return;
+    } catch (error) {
+      if (!LOCKED_CODES.has(error.code) || attempt === RENAME_DELAYS_MS.length) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, RENAME_DELAYS_MS[attempt]));
+    }
+  }
+}
+
+async function moveFile({ buildDirectory, stagingDirectory, file }) {
+  const target = path.join(buildDirectory, file);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await renameWithRetry({ from: path.join(stagingDirectory, file), to: target });
+}
+
+async function publishBuildDirectory({ buildDirectory, stagingDirectory }) {
+  await fs.mkdir(buildDirectory, { recursive: true });
+  const stagedFiles = await listFiles(stagingDirectory);
+  const liveFiles = await listFiles(buildDirectory);
+
+  const firstFiles = stagedFiles.filter((file) => file === idCounterFile);
+  const otherFiles = stagedFiles.filter(
+    (file) => file !== idCounterFile && file !== pageRegistryFile
+  );
+  for (const file of firstFiles) {
+    await moveFile({ buildDirectory, stagingDirectory, file });
+  }
+  for (const file of otherFiles) {
+    const unchanged = await filesHaveSameBytes({
+      a: path.join(stagingDirectory, file),
+      b: path.join(buildDirectory, file),
+    });
+    if (!unchanged) {
+      await moveFile({ buildDirectory, stagingDirectory, file });
+    }
+  }
+
+  const staged = new Set(stagedFiles);
+  const staleFiles = liveFiles.filter((file) => !staged.has(file) && !controlFiles.has(file));
+  await Promise.all(staleFiles.map((file) => fs.rm(path.join(buildDirectory, file), RM_OPTIONS)));
+
+  await moveFile({ buildDirectory, stagingDirectory, file: pageRegistryFile });
+  await fs.rm(stagingDirectory, RM_OPTIONS);
+}
+
+export default publishBuildDirectory;