@lowdefy/server-dev 6.0.0 → 7.0.0

package/manager/watchers/envWatcher.test.mjs

@@ -0,0 +1,87 @@
+/*
+  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 flushFsEvents from '../../test-utils/flushFsEvents.mjs';
+import waitFor from '../../test-utils/waitFor.mjs';
+
+const { default: envWatcher } = await import('./envWatcher.mjs');
+
+// macOS can hold file events back for tens of seconds on a busy machine.
+jest.setTimeout(180000);
+
+let configDir;
+let context;
+let watcher;
+
+beforeEach(async () => {
+  configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-env-watcher-test-'));
+  fs.writeFileSync(path.join(configDir, '.env'), 'LOWDEFY_SECRET_A=one\n');
+  // Otherwise the fixture write can reach the watcher as a second edit.
+  await flushFsEvents();
+  context = {
+    directories: { config: configDir },
+    logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+    lowdefyBuild: jest.fn(async () => {}),
+    buildActivity: { setBusy: jest.fn() },
+    readDotEnv: jest.fn(),
+    syncServer: jest.fn(async () => {}),
+  };
+});
+
+afterEach(async () => {
+  if (watcher) {
+    await watcher.close();
+    watcher = undefined;
+  }
+  fs.rmSync(configDir, { recursive: true, force: true });
+});
+
+test.each([
+  ['succeeds', async () => {}],
+  [
+    'fails',
+    async () => {
+      throw new Error('Build failed with 1 error(s).');
+    },
+  ],
+])(
+  'a .env edit reads the file, rebuilds and restarts the server when the build %s',
+  async (_, build) => {
+    context.lowdefyBuild.mockImplementation(build);
+    watcher = await envWatcher(context);
+
+    fs.writeFileSync(path.join(configDir, '.env'), 'LOWDEFY_SECRET_A=two\n');
+    await waitFor(() => context.syncServer.mock.calls.length > 0, {
+      description: 'the server sync',
+    });
+
+    expect(context.readDotEnv).toHaveBeenCalledTimes(1);
+    expect(context.lowdefyBuild).toHaveBeenCalledTimes(1);
+    expect(context.readDotEnv.mock.invocationCallOrder[0]).toBeLessThan(
+      context.lowdefyBuild.mock.invocationCallOrder[0]
+    );
+    expect(context.syncServer).toHaveBeenCalledWith({ restart: true });
+    await waitFor(() => context.buildActivity.setBusy.mock.calls.length === 2, {
+      description: 'the watcher to report it is idle',
+    });
+    expect(context.buildActivity.setBusy.mock.calls).toEqual([[true], [false]]);
+  }
+);

package/manager/watchers/listServerSidePackages.mjs

@@ -0,0 +1,47 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { get, type } from '@lowdefy/helpers';
+
+// Only these kinds are loaded by the server process and cached in its ESM
+// module cache. blocks, actions and operators.client are bundled by Vite,
+// which rebuilds and hot-reloads them itself.
+const serverSideKinds = [
+  'agents',
+  'connections',
+  'notifications',
+  'operators.server',
+  'requests',
+  'websockets',
+  'auth.adapters',
+  'auth.providers',
+  'auth.strategies',
+];
+
+function listServerSidePackages({ customTypesMap }) {
+  const packages = new Set();
+  for (const kind of serverSideKinds) {
+    const store = get(customTypesMap, kind, { default: {} });
+    for (const definition of Object.values(store ?? {})) {
+      if (type.isString(definition?.package)) {
+        packages.add(definition.package);
+      }
+    }
+  }
+  return packages;
+}
+
+export default listServerSidePackages;

package/manager/watchers/listServerSidePackages.test.mjs

@@ -0,0 +1,38 @@
+/*
+  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 listServerSidePackages from './listServerSidePackages.mjs';
+
+test('listServerSidePackages lists packages with server-side types once each, not client-only ones', () => {
+  const customTypesMap = {
+    actions: { Do: { package: '@app/ui-plugin', version: '1.0.0' } },
+    auth: { providers: { Corp: { package: '@app/auth-plugin', version: '1.0.0' } } },
+    blocks: { Fancy: { package: '@app/mixed-plugin', version: '1.0.0' } },
+    operators: {
+      client: { _ui: { package: '@app/ui-plugin', version: '1.0.0' } },
+      server: { _srv: { package: '@app/mixed-plugin', version: '1.0.0' } },
+    },
+    requests: {
+      Find: { package: '@app/mixed-plugin', version: '1.0.0' },
+      Insert: { package: '@app/mixed-plugin', version: '1.0.0' },
+    },
+  };
+
+  expect([...listServerSidePackages({ customTypesMap })].sort()).toEqual([
+    '@app/auth-plugin',
+    '@app/mixed-plugin',
+  ]);
+});

package/manager/watchers/lowdefyBuildWatcher.mjs

@@ -14,28 +14,60 @@
   limitations under the License.
 */
 
-import fs from 'fs';
 import path from 'path';
+import { type } from '@lowdefy/helpers';
+import { relativePosixPath } from '@lowdefy/node-utils';
+
+import createChangeSignal from '../utils/createChangeSignal.mjs';
+import findBuildFilesOutsideWatch from '../utils/findBuildFilesOutsideWatch.mjs';
 import getLowdefyVersion from '../utils/getLowdefyVersion.mjs';
 import loadSkeletonSourceFiles from '../utils/loadSkeletonSourceFiles.mjs';
+import pagePathChanged from '../utils/pagePathChanged.mjs';
 import setupWatcher from '../utils/setupWatcher.mjs';
 import updatePageTailwindCss from '../utils/updatePageTailwindCss.mjs';
 
-function lowdefyBuildWatcher(context) {
+function findLocalModuleRoots(context) {
+  return Object.values(context.buildContext.modules ?? {})
+    .filter((moduleEntry) => moduleEntry.isLocal)
+    .map((moduleEntry) => moduleEntry.moduleRoot);
+}
+
+// Watches the config directory, the --watch directories and local module
+// roots, and every other file the build reads (found in the build's ref maps).
+// A change to a file that shapes the skeleton (lowdefy.yaml, a
+// module.lowdefy.yaml, or a file in skeletonSourceFiles.json) rebuilds the
+// config, as does a page file edit that changes the page's path, and any
+// change after a failed config build. After every batch,
+// the dev server is told files changed (build/invalidatePages), and checks the
+// JIT-built pages against what they read.
+async function lowdefyBuildWatcher(context) {
+  const configDirectory = context.directories.config;
+  const writeChangeSignal = createChangeSignal({ buildDirectory: context.directories.build });
   const fixRelativePathConfigDir = (item) =>
-    path.isAbsolute(item) ? item : path.resolve(context.directories.config, item);
+    path.isAbsolute(item) ? item : path.resolve(configDirectory, item);
 
   const callback = async (filePaths) => {
-    const changedFiles = filePaths
-      .flat()
-      .map((filePath) => path.relative(context.directories.config, filePath));
+    const changedFiles = filePaths.flat();
+    // Skeleton source files and the page registry hold app refs as their
+    // forward-slash _ref paths relative to the config directory, and module
+    // refs as native absolute paths, so each change is checked both ways.
+    const relativeChangedFiles = changedFiles.map((filePath) =>
+      relativePosixPath({ from: configDirectory, to: filePath })
+    );
 
-    const lowdefyYamlModified = changedFiles.some(
+    const lowdefyYamlModified = relativeChangedFiles.some(
       (filePath) => filePath === 'lowdefy.yaml' || filePath === 'lowdefy.yml'
     );
     if (lowdefyYamlModified) {
-      const lowdefyVersion = await getLowdefyVersion(context);
-      if (lowdefyVersion !== context.version && lowdefyVersion !== 'local') {
+      // A lowdefy.yaml that cannot be read, such as one with a YAML syntax
+      // error, has no version to compare. The config build still runs, so the
+      // build status reports the error instead of the last build's result.
+      const lowdefyVersion = await getLowdefyVersion(context).catch(() => null);
+      if (
+        !type.isNone(lowdefyVersion) &&
+        lowdefyVersion !== context.version &&
+        lowdefyVersion !== 'local'
+      ) {
         context.shutdownServer();
         context.logger.warn('Lowdefy version changed. You should restart your development server.');
         process.exit();
@@ -44,37 +76,89 @@ function lowdefyBuildWatcher(context) {
 
     try {
       const skeletonSourceFiles = loadSkeletonSourceFiles(context.directories.build);
+      const moduleYamlModified = changedFiles.some(
+        (filePath) => path.basename(filePath) === 'module.lowdefy.yaml'
+      );
+      const skeletonFileModified = changedFiles.some(
+        (filePath, index) =>
+          skeletonSourceFiles.has(filePath) || skeletonSourceFiles.has(relativeChangedFiles[index])
+      );
 
-      const isSkeletonChange =
+      // skeletonSourceFiles.json comes from the last build that succeeded, so it
+      // cannot list a file only the failed build read, such as a new endpoint
+      // file whose error is being fixed. While the last build failed, any
+      // change rebuilds the config.
+      if (
+        context.lastBuildFailed ||
         lowdefyYamlModified ||
-        changedFiles.some((f) => skeletonSourceFiles.has(f));
-
-      if (isSkeletonChange) {
+        moduleYamlModified ||
+        skeletonFileModified ||
+        (await pagePathChanged({
+          changedFiles: [...changedFiles, ...relativeChangedFiles],
+          context,
+        }))
+      ) {
         await context.lowdefyBuild();
+        // In this batch, so a build-status wait also waits for the restart
+        // the build needs (a new connection type, a new plugin package).
+        await context.syncServer();
       } else {
-        const invalidatePath = path.join(context.directories.build, 'invalidatePages');
-        fs.writeFileSync(invalidatePath, String(Date.now()));
-        await updatePageTailwindCss({ changedFiles, context });
-        context.logger.info('Page files changed, invalidated all pages.');
+        await updatePageTailwindCss({ changedFiles: relativeChangedFiles, context });
+        context.logger.info('Page files changed.');
       }
     } catch (error) {
       context.logger.error(error);
     } finally {
+      // Also after a config build, failed or not: a failed build publishes
+      // nothing, and the edit must still reach the pages it touched.
+      writeChangeSignal();
       await context.reloadClients();
     }
   };
-  return setupWatcher({
+
+  const watchRoots = [
+    configDirectory,
+    ...context.options.watch.map(fixRelativePathConfigDir),
+    ...findLocalModuleRoots(context),
+  ];
+  const configWatcher = await setupWatcher({
     callback,
     context,
+    onBusy: context.buildActivity.setBusy,
     ignorePaths: [
       '**/node_modules/**',
       ...context.options.watchIgnore.map(fixRelativePathConfigDir),
     ],
-    watchPaths: [
-      context.directories.config,
-      ...context.options.watch.map(fixRelativePathConfigDir),
-    ],
+    watchPaths: watchRoots,
   });
+
+  // The config build writes refMap.json and each JIT page build writes a new
+  // file to jitMaps/, so the files they read outside the watched directories
+  // are added as they appear. Only the changed maps files are read.
+  const buildDirectory = context.directories.build;
+  const jitMapsDirectory = path.join(buildDirectory, 'jitMaps');
+  const watchBuildFilesOutsideWatch = (mapsFiles) => {
+    configWatcher.add(findBuildFilesOutsideWatch({ mapsFiles, configDirectory, watchRoots }));
+  };
+  watchBuildFilesOutsideWatch([path.join(buildDirectory, 'refMap.json')]);
+  const isMapsFile = (filePath) =>
+    filePath === buildDirectory ||
+    filePath === path.join(buildDirectory, 'refMap.json') ||
+    filePath === jitMapsDirectory ||
+    (path.dirname(filePath) === jitMapsDirectory && filePath.endsWith('.json'));
+  const mapsWatcher = await setupWatcher({
+    callback: (filePaths) => watchBuildFilesOutsideWatch([...new Set(filePaths.flat())]),
+    context,
+    // The build directory is watched rather than jitMaps/ itself, which does
+    // not exist until the first page build; everything else in it is ignored.
+    ignorePaths: [(filePath) => !isMapsFile(filePath)],
+    watchDotfiles: true,
+    watchPaths: [buildDirectory],
+  });
+
+  return {
+    close: () => Promise.all([configWatcher.close(), mapsWatcher.close()]),
+  };
 }
 
 export default lowdefyBuildWatcher;

package/manager/watchers/lowdefyBuildWatcher.test.mjs

@@ -0,0 +1,309 @@
+/*
+  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 flushFsEvents from '../../test-utils/flushFsEvents.mjs';
+import spyOnChokidar from '../../test-utils/spyOnChokidar.mjs';
+import waitFor from '../../test-utils/waitFor.mjs';
+
+// The path each page file declares now, as resolvePagePath would read it. A
+// page left out declares no path, so its path is its id.
+const declaredPaths = new Map();
+jest.unstable_mockModule('@lowdefy/build/dev', () => ({
+  resolvePagePath: jest.fn(async ({ pageId }) => declaredPaths.get(pageId) ?? pageId),
+}));
+
+const watchers = spyOnChokidar();
+const { default: lowdefyBuildWatcher } = await import('./lowdefyBuildWatcher.mjs');
+
+// macOS can hold file events back for tens of seconds on a busy machine.
+jest.setTimeout(180000);
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+let repoDir;
+let configDir;
+let buildDir;
+let localModuleRoot;
+let context;
+let watcher;
+
+// The path a ref map records for an app _ref: as written in YAML, relative to
+// the config directory with forward slashes on every platform.
+function appRefPath(filePath) {
+  return path.relative(configDir, filePath).split(path.sep).join('/');
+}
+
+function invalidated() {
+  return fs.existsSync(path.join(buildDir, 'invalidatePages'));
+}
+
+// Starts the watcher under test and returns the chokidar watcher it watches
+// the app with, the first one it creates.
+async function startWatcher() {
+  const first = watchers.length;
+  watcher = await lowdefyBuildWatcher(context);
+  return watchers[first].watcher;
+}
+
+function isWatched({ configWatcher, filePath }) {
+  const names = configWatcher.getWatched()[path.dirname(filePath)] ?? [];
+  return names.includes(path.basename(filePath));
+}
+
+// A file added to a running watcher is listed as watched a moment before its
+// event stream starts, so an edit made in that gap goes unseen. The file is
+// edited again every two seconds - well past the watcher's batch delay, so an
+// edit that was seen is processed before the next - until pages are
+// invalidated. Only a watched file can invalidate them.
+async function editUntilInvalidated(filePath) {
+  await waitFor(
+    () => {
+      if (invalidated()) return true;
+      fs.appendFileSync(filePath, 'type: Box\n');
+      return false;
+    },
+    { interval: 2000, description: `an edit to ${path.basename(filePath)} to invalidate pages` }
+  );
+}
+
+// The app lives in a git worktree under a dot-folder, like the worktrees
+// Claude Code creates under .claude/worktrees/.
+beforeEach(async () => {
+  const tmpDir = fs.realpathSync(os.tmpdir());
+  repoDir = fs.mkdtempSync(path.join(tmpDir, 'lowdefy-build-watcher-test-'));
+  const worktreeDir = path.join(repoDir, '.claude', 'worktrees', 'feature');
+  configDir = path.join(worktreeDir, 'app');
+  buildDir = path.join(configDir, '.lowdefy', 'server', 'build');
+  localModuleRoot = path.join(worktreeDir, 'modules', 'layout');
+
+  write(path.join(configDir, 'lowdefy.yaml'), 'lowdefy: local\n');
+  write(path.join(configDir, 'pages.yaml'), '- _ref: pages/home.yaml\n');
+  write(path.join(configDir, 'pages', 'home.yaml'), 'id: home\ntype: Box\n');
+  write(path.join(configDir, 'menus', 'main.yaml'), '- id: main\n');
+  write(path.join(localModuleRoot, 'module.lowdefy.yaml'), 'name: Layout\n');
+  write(path.join(localModuleRoot, 'menus.yaml'), '- id: main\n');
+  write(path.join(worktreeDir, 'modules', 'shared', 'title-block.yaml'), 'id: title\n');
+  write(
+    path.join(buildDir, 'skeletonSourceFiles.json'),
+    JSON.stringify(['menus/main.yaml', 'pages.yaml', path.join(localModuleRoot, 'menus.yaml')])
+  );
+  write(
+    path.join(buildDir, 'routes.json'),
+    JSON.stringify([{ pageId: 'home', path: 'home', auth: { public: true } }])
+  );
+  declaredPaths.clear();
+  write(
+    path.join(buildDir, 'refMap.json'),
+    JSON.stringify({
+      1: { parent: null },
+      2: { parent: '1', path: 'pages.yaml' },
+      3: { parent: '2', path: 'pages/home.yaml' },
+      4: { parent: null, path: path.join(localModuleRoot, 'components', 'page.yaml') },
+      5: { parent: '4', path: path.join(worktreeDir, 'modules', 'shared', 'title-block.yaml') },
+    })
+  );
+  // Otherwise the fixture writes can reach the watcher as edits: a
+  // lowdefy.yaml "edit" turns every page edit into a config rebuild.
+  await flushFsEvents();
+
+  context = {
+    buildContext: {
+      modules: {
+        layout: { isLocal: true, moduleRoot: localModuleRoot },
+        remote: { isLocal: false, moduleRoot: path.join(repoDir, 'cache', 'remote') },
+      },
+    },
+    directories: {
+      build: buildDir,
+      config: configDir,
+      server: path.join(configDir, '.lowdefy', 'server'),
+    },
+    logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+    buildActivity: { setBusy: jest.fn() },
+    lowdefyBuild: jest.fn(async () => {}),
+    pageRegistry: new Map([['home', { pageId: 'home', refPath: 'pages/home.yaml' }]]),
+    options: { watch: [], watchIgnore: [] },
+    reloadClients: jest.fn(async () => {}),
+    syncServer: jest.fn(async () => {}),
+    version: 'local',
+  };
+});
+
+afterEach(async () => {
+  if (watcher) {
+    await watcher.close();
+    watcher = undefined;
+  }
+  fs.rmSync(repoDir, { recursive: true, force: true });
+});
+
+test('a page file edit in an app under a dot-folder invalidates pages', async () => {
+  await startWatcher();
+  fs.appendFileSync(path.join(configDir, 'pages', 'home.yaml'), 'layout: {}\n');
+
+  await waitFor(invalidated, { description: 'pages to be invalidated' });
+  await waitFor(() => context.reloadClients.mock.calls.length > 0, {
+    description: 'clients to reload',
+  });
+  expect(context.lowdefyBuild).not.toHaveBeenCalled();
+  expect(context.syncServer).not.toHaveBeenCalled();
+});
+
+test('a page file edit that changes the page path rebuilds the config', async () => {
+  await startWatcher();
+  declaredPaths.set('home', 'start');
+  fs.appendFileSync(path.join(configDir, 'pages', 'home.yaml'), 'path: start\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+  await waitFor(invalidated, { description: 'the pages to be invalidated' });
+});
+
+test('adding a page to the pages list rebuilds the config', async () => {
+  await startWatcher();
+  fs.appendFileSync(path.join(configDir, 'pages.yaml'), '- _ref: pages/about.yaml\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+  await waitFor(invalidated, { description: 'the pages to be invalidated' });
+});
+
+test('a config rebuild stays busy until the server has caught up with the build', async () => {
+  let finishSync;
+  context.syncServer.mockImplementation(
+    () =>
+      new Promise((resolve) => {
+        finishSync = resolve;
+      })
+  );
+  await startWatcher();
+  fs.appendFileSync(path.join(configDir, 'pages.yaml'), '- _ref: pages/about.yaml\n');
+
+  await waitFor(() => context.syncServer.mock.calls.length === 1, {
+    description: 'the server sync',
+  });
+  expect(context.buildActivity.setBusy.mock.calls).toEqual([[true]]);
+  finishSync();
+  await waitFor(() => context.buildActivity.setBusy.mock.calls.length === 2, {
+    description: 'the watcher to report it is idle',
+  });
+  expect(context.buildActivity.setBusy.mock.calls).toEqual([[true], [false]]);
+});
+
+test('a lowdefy.yaml edit that breaks its YAML syntax still rebuilds the config', async () => {
+  await startWatcher();
+  write(path.join(configDir, 'lowdefy.yaml'), 'lowdefy: local\npages:\n  - id: a\n   - id: b\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+  expect(context.logger.error).not.toHaveBeenCalled();
+});
+
+test('after a failed config build, an edit to a file not in skeletonSourceFiles rebuilds the config', async () => {
+  context.lastBuildFailed = true;
+  await startWatcher();
+  write(path.join(localModuleRoot, 'api', 'check-name.yaml'), 'id: check-name\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+  await waitFor(invalidated, { description: 'the pages to be invalidated' });
+});
+
+test('a skeleton file in a subdirectory of the config directory rebuilds the config', async () => {
+  await startWatcher();
+  fs.appendFileSync(path.join(configDir, 'menus', 'main.yaml'), '- id: other\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+});
+
+test('a skeleton file in a local module outside the config directory rebuilds the config', async () => {
+  await startWatcher();
+  fs.appendFileSync(path.join(localModuleRoot, 'menus.yaml'), '- id: other\n');
+
+  await waitFor(() => context.lowdefyBuild.mock.calls.length === 1, {
+    description: 'a config build',
+  });
+});
+
+test('a file the build read outside every watched directory invalidates pages when edited', async () => {
+  const titleBlock = path.join(
+    repoDir,
+    '.claude',
+    'worktrees',
+    'feature',
+    'modules',
+    'shared',
+    'title-block.yaml'
+  );
+  const configWatcher = await startWatcher();
+
+  await waitFor(() => isWatched({ configWatcher, filePath: titleBlock }), {
+    description: 'title-block.yaml to be watched',
+  });
+  await editUntilInvalidated(titleBlock);
+  expect(context.lowdefyBuild).not.toHaveBeenCalled();
+});
+
+test('a file that appears in refMap.json after the watch started is watched', async () => {
+  const footer = path.join(repoDir, 'shared', 'footer.yaml');
+  write(footer, 'id: footer\n');
+  await flushFsEvents();
+  const configWatcher = await startWatcher();
+  expect(isWatched({ configWatcher, filePath: footer })).toBe(false);
+
+  const refMap = JSON.parse(fs.readFileSync(path.join(buildDir, 'refMap.json'), 'utf8'));
+  refMap[6] = { parent: '3', path: appRefPath(footer) };
+  fs.writeFileSync(path.join(buildDir, 'refMap.json'), JSON.stringify(refMap));
+
+  // The refMap watcher batches its change before adding the file.
+  await waitFor(() => isWatched({ configWatcher, filePath: footer }), {
+    description: 'footer.yaml to be watched',
+  });
+  await editUntilInvalidated(footer);
+});
+
+test('a file a JIT page build read outside every watched directory is watched from its jitMaps file', async () => {
+  const header = path.join(repoDir, 'shared', 'header.yaml');
+  write(header, 'id: header\n');
+  watcher = await lowdefyBuildWatcher(context);
+
+  write(
+    path.join(buildDir, 'jitMaps', 'abc123-1-1.json'),
+    JSON.stringify({
+      keyMap: {},
+      refMap: { p_abc123_1: { parent: null, path: appRefPath(header) } },
+    })
+  );
+  // The maps watcher batches its change for half a second before adding.
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  fs.appendFileSync(header, 'type: Box\n');
+
+  await waitFor(invalidated);
+});