@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/installHeadlessShell.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';
+
+const mockSpawn = jest.fn();
+jest.unstable_mockModule('child_process', () => ({ spawn: mockSpawn, spawnSync: jest.fn() }));
+
+// installHeadlessShell keeps one install per process in module state, so the
+// tests below run in order against one module: the skipped calls first, then
+// the one install. The failure path is in installHeadlessShell.failure.test.mjs.
+const { default: installHeadlessShell } = await import('./installHeadlessShell.js');
+
+function createInstaller() {
+  return Object.assign(new EventEmitter(), { stderr: new EventEmitter() });
+}
+
+beforeEach(() => {
+  jest.spyOn(console, 'info').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+  delete process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD;
+});
+
+test.each(['1', 'true'])(
+  'installHeadlessShell installs nothing when PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is %s',
+  (value) => {
+    process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = value;
+
+    expect(installHeadlessShell()).toBeNull();
+    expect(mockSpawn).not.toHaveBeenCalled();
+  }
+);
+
+test("installHeadlessShell runs playwright-core's own installer once per process, however many calls arrive", async () => {
+  // Playwright reads "0" and "false" as unset.
+  process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = 'false';
+  const installer = createInstaller();
+  mockSpawn.mockReturnValue(installer);
+
+  const first = installHeadlessShell();
+  const second = installHeadlessShell();
+  installer.emit('exit', 0);
+
+  expect(await first).toEqual({ installed: true });
+  expect(second).toBe(first);
+  expect(installHeadlessShell()).toBe(first);
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+  const [command, args] = mockSpawn.mock.calls[0];
+  expect(command).toBe(process.execPath);
+  expect(args[0]).toMatch(/playwright-core[/\\]cli\.js$/);
+  expect(args.slice(1)).toEqual(['install', 'chromium-headless-shell']);
+});

package/lib/docs/installHeadlessShell.timeout.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 { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+const mockSpawn = jest.fn();
+const mockSpawnSync = jest.fn();
+jest.unstable_mockModule('child_process', () => ({ spawn: mockSpawn, spawnSync: mockSpawnSync }));
+
+// A file of its own: installHeadlessShell keeps its one install per process
+// in module state.
+const { default: installHeadlessShell } = await import('./installHeadlessShell.js');
+
+test('installHeadlessShell kills an install that has not finished within 3 minutes and gives up', async () => {
+  // performance is not redefinable on this Node, and nothing here reads it.
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  jest.spyOn(console, 'info').mockImplementation(() => {});
+  try {
+    const installer = Object.assign(new EventEmitter(), {
+      pid: 4242,
+      stderr: new EventEmitter(),
+      kill: jest.fn(),
+    });
+    mockSpawn.mockReturnValue(installer);
+
+    const install = installHeadlessShell();
+    jest.advanceTimersByTime(3 * 60 * 1000 - 1);
+    expect(installer.kill).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(1);
+
+    const result = await install;
+    expect(result.installed).toBe(false);
+    expect(result.reason).toContain('did not finish within 3 minutes');
+    if (process.platform === 'win32') {
+      // taskkill /T stops the installer and its download process together.
+      expect(mockSpawnSync).toHaveBeenCalledWith('taskkill', ['/pid', '4242', '/T', '/F'], {
+        stdio: 'ignore',
+      });
+    } else {
+      // The installer's own download process goes too.
+      expect(mockSpawnSync).toHaveBeenCalledWith('pkill', ['-KILL', '-P', '4242'], {
+        stdio: 'ignore',
+      });
+      expect(installer.kill).toHaveBeenCalledWith('SIGKILL');
+    }
+    expect(warn).toHaveBeenCalledTimes(1);
+    // The exit that follows the kill does not log again, and nothing retries.
+    installer.emit('exit', null, 'SIGKILL');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(installHeadlessShell()).toBe(install);
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+  } finally {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  }
+});

package/lib/docs/isHeadlessShellIncomplete.js

@@ -0,0 +1,34 @@
+/*
+  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';
+
+// Playwright's installer writes INSTALLATION_COMPLETE into the browser
+// directory last, after extracting and chmod-ing the executable. An install
+// that was killed or crashed after the executable landed leaves a directory
+// without it: chromium.launch() checks only the executable and fails with a
+// launch error, while a new `playwright install` sees the missing marker and
+// installs again. The registry is Playwright's own (an exported subpath of the
+// pinned playwright-core), so the directory honours PLAYWRIGHT_BROWSERS_PATH.
+async function isHeadlessShellIncomplete() {
+  const { browserDirectoryToMarkerFilePath, registry } = await import(
+    'playwright-core/lib/server/registry/index'
+  );
+  const { directory } = registry.findExecutable('chromium-headless-shell');
+  return fs.existsSync(directory) && !fs.existsSync(browserDirectoryToMarkerFilePath(directory));
+}
+
+export default isHeadlessShellIncomplete;

package/lib/docs/isHeadlessShellIncomplete.test.mjs

@@ -0,0 +1,63 @@
+/*
+  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';
+
+// Playwright's registry reads PLAYWRIGHT_BROWSERS_PATH when it loads, so it
+// is set before the first import.
+const browsersPath = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-shell-'));
+process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+
+const { registry } = await import('playwright-core/lib/server/registry/index');
+const { default: isHeadlessShellIncomplete } = await import('./isHeadlessShellIncomplete.js');
+
+const { directory } = registry.findExecutable('chromium-headless-shell');
+
+afterEach(() => {
+  fs.rmSync(directory, { recursive: true, force: true });
+});
+
+afterAll(() => {
+  fs.rmSync(browsersPath, { recursive: true, force: true });
+  delete process.env.PLAYWRIGHT_BROWSERS_PATH;
+});
+
+test('the shell directory resolves under PLAYWRIGHT_BROWSERS_PATH', () => {
+  expect(path.dirname(directory)).toBe(browsersPath);
+});
+
+test('isHeadlessShellIncomplete is false when the shell was never installed', async () => {
+  expect(await isHeadlessShellIncomplete()).toBe(false);
+});
+
+test('isHeadlessShellIncomplete is true when the executable exists without the INSTALLATION_COMPLETE marker', async () => {
+  const executable = registry.findExecutable('chromium-headless-shell').executablePath();
+  fs.mkdirSync(path.dirname(executable), { recursive: true });
+  fs.writeFileSync(executable, '');
+
+  expect(await isHeadlessShellIncomplete()).toBe(true);
+});
+
+test('isHeadlessShellIncomplete is false once the install wrote its marker', async () => {
+  const executable = registry.findExecutable('chromium-headless-shell').executablePath();
+  fs.mkdirSync(path.dirname(executable), { recursive: true });
+  fs.writeFileSync(executable, '');
+  fs.writeFileSync(path.join(directory, 'INSTALLATION_COMPLETE'), '');
+
+  expect(await isHeadlessShellIncomplete()).toBe(false);
+});

package/lib/docs/isPageReady.js

@@ -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.
+*/
+
+// Serialized into the browser by page.waitForFunction, so this function must
+// be pure: it may reference nothing but `window`. An import or a closed-over
+// binding would be undefined once the source is evaluated inside the page.
+//
+// Checks are ordered cheapest-first and return false on the first failure.
+// A missing key always means "not configured", never "not finished" —
+// iterating only the entries that exist gives that for free.
+//
+// It reads the instance the app is showing, the most recently rendered
+// instance of the shown page, so a caller waits out a redirect (a protected
+// page sending a signed-out caller to sign in) instead of waiting for a page
+// that will never mount.
+//
+// No page is ready while the app is between pages: a client navigation (a
+// Link, even one in onInit) has changed the URL, but window.lowdefy.pageId
+// still names the page being left until the next page renders (the dev
+// client's Routing.jsx and Page.jsx mark that span).
+function isPageReady() {
+  const lowdefy = window.lowdefy;
+  if (lowdefy?._devNavigating === true) return false;
+  const shownKey = lowdefy?.pageInstances?.[lowdefy?.pageId]?.at(-1);
+  const context = lowdefy?.contexts?.[shownKey];
+  if (!context) return false;
+
+  if (context._internal?.onInitDone !== true) return false;
+  // runOnInitAsync is always invoked once runOnInit resolves, so this settles
+  // even for a page that declares no onInitAsync event.
+  if (context._internal?.onInitAsyncDone !== true) return false;
+  // The app onInitAsync runs once per app load, alongside the first page's events.
+  const appContext = lowdefy?.appContext;
+  if (appContext && appContext._internal?.onInitAsyncDone !== true) return false;
+
+  // Covers onMountAsync (fired without await by Block.js) and any other event
+  // still running, such as an onClick from an earlier tool call.
+  const blocks = Object.values(context._internal?.RootSlots?.map ?? {});
+  for (const block of blocks) {
+    const events = Object.values(block?.Events?.events ?? {});
+    if (events.some((event) => event?.loading === true)) return false;
+  }
+
+  const requests = Object.values(context.requests ?? {});
+  if (requests.some((calls) => calls?.[0]?.loading)) return false;
+
+  // A subscription is settled once it has connected or failed; a page with no
+  // subscriptions has {} and passes.
+  const channels = Object.values(context.websockets ?? {});
+  if (channels.some((channel) => channel?.connected !== true && !channel?.error)) return false;
+
+  // Lazy blocks on screen still showing their fallback (createLazyBlock in
+  // @lowdefy/block-utils). The global is absent until a lazy block first
+  // mounts, and absent means none are loading.
+  if ((window.__lowdefyLazyLoads ?? 0) > 0) return false;
+  // Tables holding their loading skeleton for its minimum time after the
+  // load (useSkeletonTiming in @lowdefy/blocks-antd): their rows are about to
+  // replace it. Absent, like the lazy count, until a table first holds one.
+  if ((window.__lowdefySkeletonHolds ?? 0) > 0) return false;
+
+  return true;
+}
+
+export default isPageReady;

package/lib/docs/isPageReady.test.mjs

@@ -0,0 +1,235 @@
+/*
+  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 isPageReady from './isPageReady.js';
+
+// isPageReady runs against `window` inside the browser, so each case installs
+// a stub context on global.window and asserts the boolean.
+function setWindow(context) {
+  global.window = {
+    lowdefy: {
+      pageId: 'home',
+      pageInstances: { home: ['page:home'] },
+      contexts: context === undefined ? {} : { 'page:home': context },
+    },
+  };
+}
+
+function settledContext({ blocks = {}, requests = {}, websockets = {} } = {}) {
+  return {
+    _internal: { onInitDone: true, onInitAsyncDone: true, RootSlots: { map: blocks } },
+    requests,
+    websockets,
+  };
+}
+
+const originalWindow = global.window;
+
+afterEach(() => {
+  global.window = originalWindow;
+});
+
+test('isPageReady returns false when the page context does not exist', () => {
+  setWindow(undefined);
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady reads the page the app shows', () => {
+  global.window = {
+    lowdefy: { contexts: { 'page:login': settledContext() }, pageInstances: {} },
+  };
+  expect(isPageReady()).toBe(false);
+
+  // A protected page redirected to sign in: the login page is what mounted.
+  global.window.lowdefy.pageId = 'login';
+  global.window.lowdefy.pageInstances.login = ['page:login'];
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady reads the most recently rendered instance of the shown page', () => {
+  const loading = settledContext();
+  loading._internal.onInitDone = false;
+  global.window = {
+    lowdefy: {
+      pageId: 'ticket',
+      contexts: {
+        'page:ticket#tickets/s/1': settledContext(),
+        'page:ticket#tickets/s/2': loading,
+      },
+      pageInstances: { ticket: ['page:ticket#tickets/s/1', 'page:ticket#tickets/s/2'] },
+    },
+  };
+  expect(isPageReady()).toBe(false);
+
+  global.window.lowdefy.pageInstances.ticket = [
+    'page:ticket#tickets/s/2',
+    'page:ticket#tickets/s/1',
+  ];
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a client navigation has not rendered the next page', () => {
+  // A Link in onInit pushed the next URL; the page being left is still the
+  // one window.lowdefy names, and its context has settled.
+  global.window = {
+    lowdefy: {
+      pageId: 'guarded',
+      pageInstances: { guarded: ['page:guarded'] },
+      contexts: { 'page:guarded': settledContext() },
+      _devNavigating: true,
+    },
+  };
+  expect(isPageReady()).toBe(false);
+
+  // The next page rendered: window.lowdefy names it and waits on its context.
+  global.window.lowdefy._devNavigating = false;
+  global.window.lowdefy.pageId = 'home';
+  global.window.lowdefy.pageInstances.home = ['page:home'];
+  expect(isPageReady()).toBe(false);
+  global.window.lowdefy.contexts['page:home'] = settledContext();
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false when window.lowdefy is not defined', () => {
+  global.window = {};
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns false while onInit has not finished', () => {
+  setWindow({ _internal: { RootSlots: { map: {} } }, requests: {} });
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns false while onInitAsync has not finished', () => {
+  setWindow({ _internal: { onInitDone: true, RootSlots: { map: {} } }, requests: {} });
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns false while the app onInitAsync has not finished', () => {
+  setWindow(settledContext());
+  global.window.lowdefy.appContext = { _internal: { onInitDone: true } };
+  expect(isPageReady()).toBe(false);
+
+  global.window.lowdefy.appContext._internal.onInitAsyncDone = true;
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a block onMountAsync event is loading', () => {
+  setWindow(
+    settledContext({
+      blocks: { list: { Events: { events: { onMountAsync: { loading: true } } } } },
+    })
+  );
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns true when a block event has finished loading', () => {
+  setWindow(
+    settledContext({
+      blocks: { list: { Events: { events: { onMountAsync: { loading: false } } } } },
+    })
+  );
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a request is loading', () => {
+  setWindow(settledContext({ requests: { get_users: [{ loading: true }] } }));
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns true when a request has resolved', () => {
+  setWindow(settledContext({ requests: { get_users: [{ loading: false, response: [] }] } }));
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a websocket channel has not connected', () => {
+  setWindow(settledContext({ websockets: { orders: { connected: false, error: null } } }));
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns true when a websocket channel failed with an error', () => {
+  setWindow(settledContext({ websockets: { orders: { connected: false, error: 'refused' } } }));
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns true when every websocket channel is connected', () => {
+  setWindow(settledContext({ websockets: { orders: { connected: true, error: null } } }));
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns true for a settled page with blocks, requests and websockets', () => {
+  setWindow(
+    settledContext({
+      blocks: { list: { Events: { events: { onMountAsync: { loading: false } } } } },
+      requests: { get_users: [{ loading: false }] },
+      websockets: { orders: { connected: true, error: null } },
+    })
+  );
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns true for a page with no blocks, requests or websockets', () => {
+  setWindow({ _internal: { onInitDone: true, onInitAsyncDone: true } });
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a lazy block on the page is still loading', () => {
+  setWindow(settledContext());
+  global.window.__lowdefyLazyLoads = 1;
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns true once every lazy block has loaded', () => {
+  setWindow(settledContext());
+  global.window.__lowdefyLazyLoads = 0;
+
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns true when no lazy block has mounted and the counter is absent', () => {
+  setWindow(settledContext());
+
+  expect(global.window.__lowdefyLazyLoads).toBeUndefined();
+  expect(isPageReady()).toBe(true);
+});
+
+test('isPageReady returns false while a table holds its loading skeleton', () => {
+  setWindow(settledContext());
+  global.window.__lowdefySkeletonHolds = 1;
+
+  expect(isPageReady()).toBe(false);
+});
+
+test('isPageReady returns true once no table holds its loading skeleton', () => {
+  setWindow(settledContext());
+  global.window.__lowdefySkeletonHolds = 0;
+
+  expect(isPageReady()).toBe(true);
+});

package/lib/docs/isRunErrorEntry.js

@@ -0,0 +1,25 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The recording sources a headless run stamps its errors with. An entry
+// carrying one belongs to that run's own error buffer, not the shared stores.
+const RUN_SOURCES = ['journey'];
+
+function isRunErrorEntry(entry) {
+  return RUN_SOURCES.includes(entry.recording?.source);
+}
+
+export default isRunErrorEntry;