@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/getSchema.js

@@ -15,7 +15,9 @@
 */
 
 import { type } from '@lowdefy/helpers';
+import { JOURNEY_STEP_SCHEMAS, journeyStepSchema } from '@lowdefy/node-utils';
 
+import getHazards from './getHazards.js';
 import normalizeTypeKind from './normalizeTypeKind.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
@@ -27,11 +29,40 @@ const SCHEMA_ARTIFACTS = {
   requests: 'plugins/requestSchemas.json',
 };
 
+const JOURNEY_STEP_KINDS = ['journey-step', 'journey-steps'];
+
+// kind journey-step returns the journey step grammar: every step, or the one
+// step `type` names.
+function getJourneyStepSchema({ typeName }) {
+  if (type.isNone(typeName) || typeName === '' || typeName === 'all') {
+    return { kind: 'journey-step', schema: journeyStepSchema };
+  }
+  const schema = JOURNEY_STEP_SCHEMAS[typeName];
+  if (type.isNone(schema)) {
+    return null;
+  }
+  return { kind: 'journey-step', type: typeName, schema };
+}
+
 function getSchema({ kind, type: typeName }) {
+  if (JOURNEY_STEP_KINDS.includes(String(kind ?? '').toLowerCase())) {
+    return getJourneyStepSchema({ typeName });
+  }
   const normalizedKind = normalizeTypeKind({ kind });
   if (type.isNone(SCHEMA_ARTIFACTS[normalizedKind])) {
     throw new Error(
-      `No schemas available for type kind. Received ${JSON.stringify(kind)}. Use one of: blocks, operators, actions, connections, requests.`
+      `No schemas available for type kind. Received ${JSON.stringify(
+        kind
+      )}. Use one of: blocks, operators, actions, connections, requests, or journey-step for the journey step grammar.`
+    );
+  }
+  // type is optional only for journey-step, so a type kind without one is
+  // refused rather than looked up as "undefined".
+  if (type.isNone(typeName) || typeName === '') {
+    throw new Error(
+      `Getting a ${normalizedKind} schema requires a "type", the exact type name. Received ${JSON.stringify(
+        typeName
+      )}.`
     );
   }
   const schemas = readBuildArtifact({ name: SCHEMA_ARTIFACTS[normalizedKind] }) ?? {};
@@ -59,6 +90,7 @@ function getSchema({ kind, type: typeName }) {
       result.meta = blockMetas[typeName];
     }
   }
+  result.hazards = getHazards({ kind: normalizedKind, type: typeName });
   return result;
 }
 

package/lib/docs/getStaleStatus.js

@@ -0,0 +1,36 @@
+/*
+  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 readBuildArtifact from './readBuildArtifact.js';
+
+// When a dev rebuild fails the manager writes status "error" to
+// build/buildStatus.json but leaves the previous build's artifacts in place, so
+// every docs read keeps answering from a build that predates the caller's
+// edits. Returns null — not { stale: false } — when the build is ok or unknown:
+// a response with no stale fields means not stale, and a false flag on every
+// response costs tokens on every call.
+function getStaleStatus() {
+  const build = readBuildArtifact({ name: 'buildStatus.json' });
+  if (build?.status !== 'error') return null;
+  return {
+    stale: true,
+    staleSince: build.timestamp ?? null,
+    staleReason:
+      'The last build failed. The dev server is still serving the previous successful build, so this result may not reflect your latest edits. Call lowdefy_build_status (or GET /lowdefy-docs/build-status) for the errors.',
+  };
+}
+
+export default getStaleStatus;

package/lib/docs/getStaleStatus.test.mjs

@@ -0,0 +1,74 @@
+/*
+  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';
+
+// getStaleStatus reads build/buildStatus.json from process.cwd() — point it at
+// a throwaway server directory before the module is imported.
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-stale-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'));
+process.chdir(fixtureDir);
+
+const statusPath = path.join(fixtureDir, 'build', 'buildStatus.json');
+
+function writeStatus(status) {
+  fs.writeFileSync(statusPath, JSON.stringify(status));
+}
+
+function removeStatus() {
+  if (fs.existsSync(statusPath)) fs.rmSync(statusPath);
+}
+
+const { default: getStaleStatus } = await import('./getStaleStatus.js');
+
+test('getStaleStatus returns null when buildStatus.json is missing', () => {
+  removeStatus();
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns null when the build status is ok', () => {
+  writeStatus({ status: 'ok', timestamp: '2026-01-01T00:00:00.000Z', errors: [], warnings: [] });
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns null when the build status is unknown', () => {
+  writeStatus({ status: 'unknown' });
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns the stale fields with the artifact timestamp when the build failed', () => {
+  writeStatus({
+    status: 'error',
+    timestamp: '2026-02-03T04:05:06.000Z',
+    errors: [{ message: 'Block type "Buton" not found.' }],
+  });
+  const status = getStaleStatus();
+  expect(status.stale).toBe(true);
+  expect(status.staleSince).toEqual('2026-02-03T04:05:06.000Z');
+  expect(status.staleReason).toContain('The last build failed.');
+  expect(status.staleReason).toContain('lowdefy_build_status');
+});
+
+test('getStaleStatus returns a null staleSince when the failed build has no timestamp', () => {
+  writeStatus({ status: 'error', errors: [] });
+  expect(getStaleStatus()).toEqual({
+    stale: true,
+    staleSince: null,
+    staleReason: expect.any(String),
+  });
+});

package/lib/docs/guardJourneyOrigin.js

@@ -0,0 +1,39 @@
+/*
+  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.
+*/
+
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' };
+
+function portOf(url) {
+  return url.port === '' ? DEFAULT_PORTS[url.protocol] : url.port;
+}
+
+// The data cookie is set for the journey's origin only, so a request to the dev server's port on
+// another host (127.0.0.1 against localhost, [::1], a LAN address) would carry none and read the
+// real database as a signed-out caller. Such requests are aborted before they leave the browser and
+// handed to onLeave; requests to other ports and other sites are untouched.
+async function guardJourneyOrigin({ context, origin, onLeave }) {
+  const originUrl = new URL(origin);
+  const originPort = portOf(originUrl);
+  await context.route(
+    (url) => portOf(url) === originPort && url.hostname !== originUrl.hostname,
+    async (route) => {
+      onLeave(route.request().url());
+      await route.abort('blockedbyclient');
+    }
+  );
+}
+
+export default guardJourneyOrigin;

package/lib/docs/inspectState.js

@@ -22,25 +22,27 @@ import resolveSource from './resolveSource.js';
 // headless-only. Falls back to headless whenever the tab path isn't usable
 // (no tab connected, or `source: 'tab'` was requested but it errored) so
 // agents always get an answer.
-async function inspectState({ origin, pageId, source, user }) {
+async function inspectState({ origin, pageId, pathParams, source, user, data }) {
   const { tryTab, error, invalidInput } = resolveSource({
     name: 'inspectState',
     pageId,
+    pathParams,
     source,
     user,
+    data,
   });
   if (error) {
     return { error, invalidInput };
   }
 
   if (tryTab) {
-    const result = await inspectStateFromTab({ pageId });
+    const result = await inspectStateFromTab({ pageId, pathParams });
     if (!result?.error) {
       return { ...result, source: 'tab' };
     }
   }
 
-  const result = await inspectStateHeadless({ origin, pageId, user });
+  const result = await inspectStateHeadless({ origin, pageId, pathParams, user, data });
   return { ...result, source: 'headless' };
 }
 

package/lib/docs/inspectStateFromTab.js

@@ -26,8 +26,8 @@ import { requestFromTab } from './tabChannel.js';
 // (see tabChannel.js) — a serialized snapshot string on success, or an
 // `{ error }` object if no tab is connected, the request timed out, or
 // Inspector.jsx itself failed to build the snapshot.
-async function inspectStateFromTab({ pageId } = {}) {
-  const response = await requestFromTab({ pageId, event: 'inspect-request' });
+async function inspectStateFromTab({ pageId, pathParams } = {}) {
+  const response = await requestFromTab({ pageId, pathParams, event: 'inspect-request' });
   if (response?.error) {
     return { error: response.error };
   }

package/lib/docs/inspectStateHeadless.js

@@ -17,18 +17,27 @@
 import { type } from '@lowdefy/helpers';
 
 import { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+import noBrowserError from './noBrowserError.js';
+import resolvePageInstance from './resolvePageInstance.js';
+import resolveToolCaller from './resolveToolCaller.js';
+import unsettledPageNote from './unsettledPageNote.js';
+import withBrowserSlot from './withBrowserSlot.js';
+import withDataSession from './withDataSession.js';
 
 // Collects a state snapshot from a headless Chromium tab navigated to the
-// page's own route. Mirrors Inspector.jsx's buildSnapshot (the live-tab
+// page instance's own route (`pathParams` fill a patterned page's placeholders),
+// read under the instance key. Mirrors Inspector.jsx's buildSnapshot (the live-tab
 // equivalent), but window.lowdefy does not expose the app's serializer, so
 // the snapshot is round-tripped through JSON.parse(JSON.stringify(...))
 // inside the page instead. That strips functions/undefined and turns Dates
 // into plain ISO strings — good enough for agent inspection, just not a
 // byte-for-byte match of the app's own `~d`-tagged serialization.
-async function inspectStateHeadless({ origin, pageId, user, timeout = 15000 }) {
+async function inspectStateHeadless({ origin, pageId, pathParams, user, data, timeout = 15000 }) {
   if (type.isNone(origin) || !type.isString(origin)) {
     return {
-      error: `inspectStateHeadless requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+      error: `inspectStateHeadless requires an "origin" string. Received ${JSON.stringify(
+        origin
+      )}.`,
     };
   }
   if (type.isNone(pageId) || !type.isString(pageId)) {
@@ -37,40 +46,93 @@ async function inspectStateHeadless({ origin, pageId, user, timeout = 15000 }) {
     };
   }
 
+  const instance = resolvePageInstance({ pageId, pathParams });
+  if (!type.isUndefined(instance.error)) {
+    return { error: instance.error, invalidInput: true };
+  }
+
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
+  return withBrowserSlot({
+    task: () =>
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          inspectStateInBrowser({
+            origin,
+            pageId,
+            pathParams,
+            instance,
+            user: caller.user,
+            dataCookie,
+            timeout,
+          }),
+      }),
+  });
+}
+
+// The part of inspectStateHeadless that runs in the browser, inside a browser slot.
+async function inspectStateInBrowser({
+  origin,
+  pageId,
+  pathParams,
+  instance,
+  user,
+  dataCookie,
+  timeout,
+}) {
   let browser;
   try {
     browser = await getBrowser();
   } catch (error) {
-    return {
-      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
-    };
+    return { error: noBrowserError(error) };
   }
 
-  const url = buildPageUrl({ origin, pageId });
+  const url = buildPageUrl({ origin, pageId, path: instance.path, pathParams });
 
   let context;
   try {
-    const opened = await openPage({ browser, origin, pageId, user, timeout });
+    const opened = await openPage({
+      browser,
+      origin,
+      pageId,
+      path: instance.path,
+      pathParams,
+      user,
+      dataCookie,
+      timeout,
+    });
     context = opened.context;
-    const snapshot = await opened.page.evaluate((id) => {
-      const lowdefy = window.lowdefy;
-      const pageContext = lowdefy?.contexts?.[`page:${id}`];
-      if (!pageContext) {
-        return { error: `No live context for page "${id}".` };
-      }
-      return JSON.parse(
-        JSON.stringify({
-          pageId: id,
-          state: pageContext.state,
-          requests: pageContext.requests,
-          eventLog: (pageContext.eventLog ?? []).slice(-50),
-          global: lowdefy.lowdefyGlobal,
-          user: lowdefy.user,
-          input: lowdefy.inputs?.[`page:${id}`],
-          urlQuery: window.location.search,
-        })
-      );
-    }, pageId);
+    const snapshot = await opened.page.evaluate(
+      ({ id, instanceKey, path }) => {
+        const lowdefy = window.lowdefy;
+        const pageContext = lowdefy?.contexts?.[instanceKey];
+        if (!pageContext) {
+          return { error: `No live context for page "${id}" at "/${path}".` };
+        }
+        return JSON.parse(
+          JSON.stringify({
+            pageId: id,
+            pathParams: pageContext.pathParams,
+            instanceKey,
+            state: pageContext.state,
+            requests: pageContext.requests,
+            eventLog: (pageContext.eventLog ?? []).slice(-50),
+            global: lowdefy.lowdefyGlobal,
+            user: lowdefy.user,
+            input: lowdefy.inputs?.[instanceKey],
+            urlQuery: window.location.search,
+          })
+        );
+      },
+      { id: pageId, instanceKey: instance.instanceKey, path: instance.path }
+    );
+    if (!opened.ready) {
+      return { ...snapshot, ready: false, note: unsettledPageNote({ timeout }) };
+    }
     return snapshot;
   } catch (error) {
     return { error: `Failed to inspect state at "${url}": ${error.message}` };

package/lib/docs/inspectStateHeadless.test.mjs

@@ -25,7 +25,10 @@ import { jest } from '@jest/globals';
 // screenshotPage.test.mjs, which exercises the same getBrowser.js singleton.
 jest.unstable_mockModule('playwright-core', () => ({
   chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+  selectors: { register: jest.fn(async () => {}) },
 }));
+// A missing shell would otherwise start a real download.
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: () => null }));
 
 // lib/build/config.js reads build/config.json from process.cwd() at import
 // time — chdir into a fixture that has one before getBrowser.js (which
@@ -35,6 +38,10 @@ const originalCwd = process.cwd();
 const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-inspect-state-test-'));
 fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
 fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+fs.writeFileSync(
+  path.join(fixtureDir, 'build', 'routes.json'),
+  JSON.stringify([{ pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' }])
+);
 process.chdir(fixtureDir);
 
 const { default: inspectStateHeadless } = await import('./inspectStateHeadless.js');
@@ -56,5 +63,17 @@ test('inspectStateHeadless returns an error when pageId is missing', async () =>
 
 test('inspectStateHeadless returns an actionable error when no browser is available', async () => {
   const result = await inspectStateHeadless({ origin: 'http://localhost:3001', pageId: 'home' });
-  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+  expect(result.error).toMatch(
+    /No Chromium available. Run: npx playwright install chromium-headless-shell/
+  );
+});
+
+test('inspectStateHeadless returns the error naming a missing placeholder before opening a browser', async () => {
+  const result = await inspectStateHeadless({
+    origin: 'http://localhost:3001',
+    pageId: 'ticket',
+    pathParams: { space: 's' },
+  });
+  expect(result.invalidInput).toBe(true);
+  expect(result.error).toMatch(/missing a value for path placeholder "ticket_id"/);
 });

package/lib/docs/installHeadlessShell.failure.test.mjs

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+const mockSpawn = jest.fn();
+jest.unstable_mockModule('child_process', () => ({ spawn: mockSpawn, spawnSync: jest.fn() }));
+
+// A file of its own: installHeadlessShell keeps its one install per process
+// in module state.
+const { default: installHeadlessShell } = await import('./installHeadlessShell.js');
+
+test('installHeadlessShell logs a failed install once and does not retry it in this process', async () => {
+  const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  jest.spyOn(console, 'info').mockImplementation(() => {});
+  const installer = Object.assign(new EventEmitter(), { stderr: new EventEmitter() });
+  mockSpawn.mockReturnValue(installer);
+
+  const install = installHeadlessShell();
+  installer.stderr.emit('data', Buffer.from('Download failed: server returned code 503'));
+  installer.emit('exit', 1);
+  // An error event after exit (or before it) must not log twice.
+  installer.emit('error', new Error('spawn EPIPE'));
+
+  expect(await install).toMatchObject({ installed: false });
+  expect(installHeadlessShell()).toBe(install);
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+  expect(warn).toHaveBeenCalledTimes(1);
+  expect(warn.mock.calls[0][0]).toContain('Download failed: server returned code 503');
+});

package/lib/docs/installHeadlessShell.js

@@ -0,0 +1,123 @@
+/*
+  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, spawnSync } from 'child_process';
+import { createRequire } from 'module';
+import path from 'path';
+
+import { type } from '@lowdefy/helpers';
+
+// Read the way Playwright's own installer reads it, so a value that turns
+// Playwright's download off turns this one off too.
+function isDownloadSkipped() {
+  const value = process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD;
+  if (type.isNone(value) || value === '' || value === 'false' || value === '0') {
+    return false;
+  }
+  return true;
+}
+
+// The download is about 100 MB. Playwright 1.59's installer can stall for
+// good while unzipping on Node 26, so an install that has not finished by
+// then is treated as failed.
+const INSTALL_TIMEOUT_MS = 3 * 60 * 1000;
+
+// The installer forks a download process of its own, which holds the zip
+// open while it hangs, so its children go too. Only processes this server
+// started are signalled.
+function killInstaller(installer) {
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(installer.pid), '/T', '/F'], { stdio: 'ignore' });
+    return;
+  }
+  spawnSync('pkill', ['-KILL', '-P', String(installer.pid)], { stdio: 'ignore' });
+  installer.kill('SIGKILL');
+}
+
+function runInstall() {
+  // cli.js is not in playwright-core's exports, so it is found next to the
+  // package.json, which is. Running the installer of the playwright-core this
+  // server loads fetches exactly the shell revision it launches.
+  const require = createRequire(import.meta.url);
+  const cliPath = path.join(
+    path.dirname(require.resolve('playwright-core/package.json')),
+    'cli.js'
+  );
+  console.info('Installing chromium-headless-shell for the dev server browser tools.');
+  return new Promise((resolve) => {
+    let settled = false;
+    let stderr = '';
+    let timer = null;
+    function settle({ installed, reason }) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (!installed) {
+        console.warn(
+          `Could not install chromium-headless-shell (${reason}). The dev server browser tools use system Chrome when it is installed. Run: npx playwright install chromium-headless-shell`
+        );
+      }
+      resolve({ installed, reason });
+    }
+    // A short-lived process: the download and unzip never touch this
+    // server's memory. Playwright's registry lock serialises installs from
+    // several dev servers on one machine.
+    const installer = spawn(process.execPath, [cliPath, 'install', 'chromium-headless-shell'], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    timer = setTimeout(() => {
+      killInstaller(installer);
+      settle({
+        installed: false,
+        reason: `the install did not finish within ${
+          INSTALL_TIMEOUT_MS / 60000
+        } minutes; Playwright's installer can stall while unzipping on Node 26, where installing with Node 22 works`,
+      });
+    }, INSTALL_TIMEOUT_MS);
+    // Never the reason the dev server stays up.
+    timer.unref();
+    installer.stderr.on('data', (data) => {
+      stderr = `${stderr}${data.toString('utf8')}`.slice(-1000);
+    });
+    installer.on('error', (error) => settle({ installed: false, reason: error.message }));
+    installer.on('exit', (code) => {
+      if (code === 0) {
+        settle({ installed: true });
+        return;
+      }
+      settle({ installed: false, reason: stderr.trim() || `exit code ${code}` });
+    });
+  });
+}
+
+// One install per dev server process, shared by every caller. A failed
+// install is not retried in this process: system Chrome stays the fallback.
+let installPromise = null;
+
+// Resolves { installed: true } once the shell is installed, or
+// { installed: false, reason } when the install failed or timed out. Returns
+// null when downloads are turned off.
+function installHeadlessShell() {
+  if (isDownloadSkipped()) {
+    return null;
+  }
+  if (type.isNone(installPromise)) {
+    installPromise = runInstall();
+  }
+  return installPromise;
+}
+
+export default installHeadlessShell;