@lowdefy/server-dev 5.6.0 → 6.0.0

package/lib/docs/evalOperator.test.mjs

@@ -0,0 +1,157 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+// evalOperator.js only chooses between the tab and headless sources - the
+// sources' own behavior is covered by evalOperatorHeadless.test.mjs and (once
+// written) evalOperatorInTab's own tests. Mock both, plus tabAvailable, so
+// only the fallback logic is under test here.
+const mockEvalOperatorInTab = jest.fn();
+const mockEvalOperatorHeadless = jest.fn();
+const mockTabAvailable = jest.fn();
+
+jest.unstable_mockModule('./evalOperatorInTab.js', () => ({
+  default: mockEvalOperatorInTab,
+}));
+jest.unstable_mockModule('./evalOperatorHeadless.js', () => ({
+  default: mockEvalOperatorHeadless,
+}));
+jest.unstable_mockModule('./tabAvailable.js', () => ({
+  default: mockTabAvailable,
+}));
+
+const { default: evalOperator } = await import('./evalOperator.js');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+const expression = { _state: 'name' };
+
+test('evalOperator uses the tab when source is "tab" and it succeeds', async () => {
+  mockEvalOperatorInTab.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    source: 'tab',
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'tab' });
+  expect(mockEvalOperatorInTab).toHaveBeenCalledWith({ pageId: 'home', expression });
+  expect(mockEvalOperatorHeadless).not.toHaveBeenCalled();
+});
+
+test('evalOperator falls back to headless when source is "tab" but the tab errors', async () => {
+  mockEvalOperatorInTab.mockResolvedValue({ error: 'No browser tab connected.' });
+  mockEvalOperatorHeadless.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    source: 'tab',
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'headless' });
+  expect(mockEvalOperatorHeadless).toHaveBeenCalledWith({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+  });
+});
+
+test('evalOperator goes straight to headless when source is "headless"', async () => {
+  mockEvalOperatorHeadless.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    source: 'headless',
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'headless' });
+  expect(mockTabAvailable).not.toHaveBeenCalled();
+  expect(mockEvalOperatorInTab).not.toHaveBeenCalled();
+});
+
+test('evalOperator prefers the tab when source is unset and a tab is available', async () => {
+  mockTabAvailable.mockReturnValue(true);
+  mockEvalOperatorInTab.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'tab' });
+  expect(mockEvalOperatorHeadless).not.toHaveBeenCalled();
+});
+
+test('evalOperator ignores an available tab and passes the user to headless when a user is given', async () => {
+  mockTabAvailable.mockReturnValue(true);
+  mockEvalOperatorHeadless.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    user: { roles: ['admin'] },
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'headless' });
+  expect(mockEvalOperatorInTab).not.toHaveBeenCalled();
+  expect(mockEvalOperatorHeadless).toHaveBeenCalledWith({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    user: { roles: ['admin'] },
+  });
+});
+
+test('evalOperator errors when a user is combined with source "tab"', async () => {
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+    source: 'tab',
+    user: { roles: ['admin'] },
+  });
+
+  expect(result.error).toMatch(/cannot apply "user" to the developer's live tab/);
+  // Flagged as the caller's mistake so the HTTP route answers 400, not 502.
+  expect(result.invalidInput).toBe(true);
+  expect(mockEvalOperatorInTab).not.toHaveBeenCalled();
+  expect(mockEvalOperatorHeadless).not.toHaveBeenCalled();
+});
+
+test('evalOperator goes straight to headless when source is unset and no tab is available', async () => {
+  mockTabAvailable.mockReturnValue(false);
+  mockEvalOperatorHeadless.mockResolvedValue({ value: 'Jane', errors: [] });
+
+  const result = await evalOperator({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression,
+  });
+
+  expect(result).toEqual({ value: 'Jane', errors: [], source: 'headless' });
+  expect(mockEvalOperatorInTab).not.toHaveBeenCalled();
+});

package/lib/docs/evalOperatorHeadless.js

@@ -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 { type } from '@lowdefy/helpers';
+
+import { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+
+// Evaluates an operator expression against the live client state of a
+// headless Chromium tab navigated to the page's own route, using the page's
+// own WebParser instance so results match runtime exactly. Mirrors
+// Inspector.jsx's evalExpression (the live-tab equivalent).
+async function evalOperatorHeadless({ origin, pageId, expression, user, timeout = 15000 }) {
+  if (type.isNone(origin) || !type.isString(origin)) {
+    return {
+      error: `evalOperatorHeadless requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+    };
+  }
+  if (type.isNone(pageId) || !type.isString(pageId)) {
+    return {
+      error: `evalOperatorHeadless requires a "pageId" string. Received ${JSON.stringify(pageId)}.`,
+    };
+  }
+  if (type.isNone(expression)) {
+    return { error: 'evalOperatorHeadless requires an "expression".' };
+  }
+
+  let browser;
+  try {
+    browser = await getBrowser();
+  } catch (error) {
+    return {
+      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
+    };
+  }
+
+  const url = buildPageUrl({ origin, pageId });
+
+  let context;
+  try {
+    const opened = await openPage({ browser, origin, pageId, user, timeout });
+    context = opened.context;
+    // Passed through as JSON so the page-side parser always receives a plain
+    // value, matching how it arrives at Inspector.jsx's eval-request handler.
+    const expressionJson = JSON.stringify(expression);
+    const result = await opened.page.evaluate(
+      ({ id, exprJson }) => {
+        const lowdefy = window.lowdefy;
+        const pageContext = lowdefy?.contexts?.[`page:${id}`];
+        if (!pageContext) {
+          return { error: `No live context for page "${id}".` };
+        }
+        const input = JSON.parse(exprJson);
+        const { output, errors } = pageContext._internal.parser.parse({
+          input,
+          location: 'agent_eval',
+        });
+        return {
+          value: output === undefined ? undefined : JSON.parse(JSON.stringify(output)),
+          errors: errors.map((error) => error.message),
+        };
+      },
+      { id: pageId, exprJson: expressionJson }
+    );
+    return result;
+  } catch (error) {
+    return { error: `Failed to evaluate operator at "${url}": ${error.message}` };
+  } finally {
+    if (context) {
+      await context.close();
+    }
+  }
+}
+
+export default evalOperatorHeadless;

package/lib/docs/evalOperatorHeadless.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 { jest } from '@jest/globals';
+
+// A real headless evaluation needs an installed browser, which jest can't
+// rely on, so this only covers the error paths: bad input, and
+// chromium.launch failing (the "no browser installed" case). Mirrors
+// 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")) },
+}));
+
+// 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
+// imports it transitively) is loaded. Mirrors the pattern in
+// screenshotPage.test.mjs.
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-eval-operator-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+process.chdir(fixtureDir);
+
+const { default: evalOperatorHeadless } = await import('./evalOperatorHeadless.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+test('evalOperatorHeadless returns an error when origin is missing', async () => {
+  const result = await evalOperatorHeadless({ pageId: 'home', expression: { _state: 'x' } });
+  expect(result.error).toMatch(/requires an "origin" string/);
+});
+
+test('evalOperatorHeadless returns an error when pageId is missing', async () => {
+  const result = await evalOperatorHeadless({
+    origin: 'http://localhost:3001',
+    expression: { _state: 'x' },
+  });
+  expect(result.error).toMatch(/requires a "pageId" string/);
+});
+
+test('evalOperatorHeadless returns an error when expression is missing', async () => {
+  const result = await evalOperatorHeadless({ origin: 'http://localhost:3001', pageId: 'home' });
+  expect(result.error).toMatch(/requires an "expression"/);
+});
+
+test('evalOperatorHeadless returns an actionable error when no browser is available', async () => {
+  const result = await evalOperatorHeadless({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    expression: { _state: 'x' },
+  });
+  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+});

package/lib/docs/evalOperatorInTab.js

@@ -0,0 +1,48 @@
+/*
+  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 { type, serializer } from '@lowdefy/helpers';
+
+import { requestFromTab } from './tabChannel.js';
+
+// Evaluates an operator expression against the live client state of a page
+// open in a developer's real browser tab (e.g. `{ _state: 'myInput' }`),
+// using the page's own WebParser instance so results match runtime exactly.
+//
+// requestFromTab resolves directly with whatever the tab posted as `result`
+// (see tabChannel.js) — `{ value, errors }` on success, or an `{ error }`
+// object if no tab is connected, the request timed out, or Inspector.jsx
+// itself failed to evaluate the expression.
+async function evalOperatorInTab({ pageId, expression }) {
+  if (type.isNone(expression)) {
+    throw new Error('evalOperatorInTab requires an "expression".');
+  }
+  const response = await requestFromTab({
+    pageId,
+    event: 'eval-request',
+    payload: { expression },
+  });
+  if (response?.error) {
+    return { error: response.error };
+  }
+  const { value, errors } = response;
+  return {
+    value: type.isUndefined(value) ? undefined : serializer.deserializeFromString(value),
+    errors,
+  };
+}
+
+export default evalOperatorInTab;

package/lib/docs/findConfig.js

@@ -0,0 +1,260 @@
+/*
+  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 path from 'node:path';
+import { resolveConfigLocation } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+
+import buildPageIfNeeded from '../server/jitPageBuilder.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+const MAX_MATCHES = 20;
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Array segments in keyMap `key` paths look like `[0:home]` or
+// `[2:my_button:Button]` (see packages/build/src/build/addKeys.js recArray) —
+// match an id at either position.
+function buildIdPattern(id) {
+  return new RegExp(`\\[\\d+:${escapeRegExp(id)}(:[^\\]]*)?\\]`);
+}
+
+// The JIT page build runs addKeys on the page object itself (see
+// packages/build/src/build/jit/buildPageJit.js), so a built page's keyMap
+// subtree is keyed `root`, `root.blocks[...]` — the key path carries NO page
+// segment, and every built page looks identical by prefix. The page a keyMap
+// entry belongs to is only recoverable structurally: walk ~k_parent up to the
+// subtree root and compare against the page's own root. The page's root is
+// found from its build artifact — block objects in pages/<pageId>.json keep
+// their ~k, and any of them chains up to the page root. Skeleton-style keys
+// (`root.pages[N:pageId]...`) carry the page segment inline, so a containment
+// pattern covers those.
+function buildPageScope({ pageId, keyMap }) {
+  let rootKeyId = findPageRootKeyId({ pageId, keyMap });
+  // A page built during the skeleton build (e.g. the default 404 page) chains
+  // to the global config root, which every skeleton entry shares — useless as
+  // a page discriminator. Those pages' keys carry the page segment inline, so
+  // the pattern branch identifies them instead.
+  if (!type.isNone(rootKeyId) && rootKeyId === findGlobalRootId(keyMap)) {
+    rootKeyId = null;
+  }
+  return {
+    rootKeyId,
+    pagePattern: new RegExp(`\\bpages\\[\\d+:${escapeRegExp(pageId)}(:[^\\]]*)?\\]`),
+  };
+}
+
+function findGlobalRootId(keyMap) {
+  for (const [keyId, entry] of Object.entries(keyMap)) {
+    if (entry?.key === 'root.pages') {
+      return resolveChainRootId({ keyId, keyMap });
+    }
+  }
+  return null;
+}
+
+function findPageRootKeyId({ pageId, keyMap }) {
+  const artifact = readBuildArtifact({ name: `pages/${pageId}.json`, deserialize: true });
+  const keyId = findFirstKeyId(artifact);
+  if (type.isNone(keyId)) {
+    return null;
+  }
+  return resolveChainRootId({ keyId, keyMap });
+}
+
+function findFirstKeyId(node) {
+  if (type.isString(node?.['~k'])) {
+    return node['~k'];
+  }
+  if (type.isArray(node)) {
+    for (const item of node) {
+      const keyId = findFirstKeyId(item);
+      if (keyId) {
+        return keyId;
+      }
+    }
+    return null;
+  }
+  if (!type.isObject(node)) {
+    return null;
+  }
+  for (const key of Object.keys(node)) {
+    const keyId = findFirstKeyId(node[key]);
+    if (keyId) {
+      return keyId;
+    }
+  }
+  return null;
+}
+
+// Walk ~k_parent to the top of the entry's subtree. addKeys assigns the tree
+// root a parent id that is never written to keyMap, so "parent not in keyMap"
+// is the root. The seen-set guards against a corrupt artifact cycling forever.
+function resolveChainRootId({ keyId, keyMap }) {
+  let currentId = keyId;
+  const seen = new Set();
+  while (!seen.has(currentId)) {
+    seen.add(currentId);
+    const parentId = keyMap[currentId]?.['~k_parent'];
+    if (type.isNone(parentId) || type.isUndefined(keyMap[parentId])) {
+      return currentId;
+    }
+    currentId = parentId;
+  }
+  return currentId;
+}
+
+function belongsToPage({ keyId, entry, keyMap, pageScope }) {
+  if (pageScope.pagePattern.test(entry.key)) {
+    return true;
+  }
+  if (type.isNone(pageScope.rootKeyId)) {
+    return false;
+  }
+  return resolveChainRootId({ keyId, keyMap }) === pageScope.rootKeyId;
+}
+
+function scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope }) {
+  const pattern = buildIdPattern(id);
+  const matches = [];
+  for (const [keyId, entry] of Object.entries(keyMap)) {
+    if (matches.length >= MAX_MATCHES) {
+      break;
+    }
+    if (!type.isString(entry?.key)) {
+      continue;
+    }
+    if (!pattern.test(entry.key)) {
+      continue;
+    }
+    if (pageScope && !belongsToPage({ keyId, entry, keyMap, pageScope })) {
+      continue;
+    }
+    matches.push({
+      keyPath: entry.key,
+      location: resolveConfigLocation({ configKey: keyId, keyMap, refMap, configDirectory }),
+    });
+  }
+  return matches;
+}
+
+// List item blocks render with array indices applied to their ids
+// (`my_list.0.name`) while config — and therefore keyMap — holds the `$`
+// placeholder form (`my_list.$.name`, see applyArrayIndices in
+// @lowdefy/helpers). Fold numeric segments back to `$` so a runtime id from
+// inside a list resolves to the yaml that defines the item block instead of
+// missing and falling back to an ancestor (usually the list itself).
+function deIndexId(id) {
+  return id.replace(/\.\d+(?=\.|$)/g, () => '.$');
+}
+
+function scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory, pageScope }) {
+  const matches = scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope });
+  if (matches.length > 0) {
+    return matches;
+  }
+  const deIndexedId = deIndexId(id);
+  if (deIndexedId === id) {
+    return matches;
+  }
+  return scanKeyMap({ id: deIndexedId, keyMap, refMap, configDirectory, pageScope });
+}
+
+// Locates a block/request/connection/etc by id, or a page by pageId. Block
+// content only exists in keyMap once its page has been JIT-built (see
+// lib/server/jitPageBuilder.js), so pass `pageId` to force-build and scan a
+// specific page. Never throws on not-found — agents should be able to treat
+// "no matches" as a normal result and try another id or pageId.
+async function findConfig({ id, pageId }) {
+  if (type.isNone(id) || !type.isString(id)) {
+    throw new Error(
+      `findConfig requires an "id" string. Received ${JSON.stringify(id)}. ` +
+        'Use GET /lowdefy-docs/find/:id.'
+    );
+  }
+
+  const pageRegistry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+
+  // A page's root block renders with blockId === pageId, so open-in-editor
+  // and feedback enrichment hit this branch for it — they read
+  // matches[0].location.source, so the page result must carry a match, not
+  // just the file field the docs/MCP consumers use.
+  if (pageRegistry[id]) {
+    const refPath = pageRegistry[id].refPath;
+    const matches = [];
+    if (type.isString(refPath)) {
+      matches.push({
+        keyPath: `pages[${id}]`,
+        location: { source: path.resolve(configDirectory, refPath) },
+      });
+    }
+    return { kind: 'page', pageId: id, file: refPath, matches };
+  }
+
+  if (!type.isNone(pageId)) {
+    if (!pageRegistry[pageId]) {
+      return {
+        matches: [],
+        note:
+          `Unknown pageId "${pageId}". See GET /lowdefy-docs/find/${id} without ?pageId= ` +
+          'to scan all already-built pages, or check the pageId spelling.',
+      };
+    }
+
+    const buildDirectory = path.join(process.cwd(), 'build');
+    try {
+      await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+    } catch (error) {
+      return {
+        matches: [],
+        note: `Page "${pageId}" failed to build, so its config could not be scanned: ${error.message}`,
+      };
+    }
+
+    const keyMap = readBuildArtifact({ name: 'keyMap.json' }) ?? {};
+    const refMap = readBuildArtifact({ name: 'refMap.json' }) ?? {};
+    const matches = scanKeyMapWithDeIndex({
+      id,
+      keyMap,
+      refMap,
+      configDirectory,
+      pageScope: buildPageScope({ pageId, keyMap }),
+    });
+    return matches.length > 0
+      ? { matches }
+      : {
+          matches,
+          note:
+            `No config found with id "${id}" on page "${pageId}". Retry without ?pageId= to ` +
+            'scan all built pages and app-level config (connections, menus, api).',
+        };
+  }
+
+  const keyMap = readBuildArtifact({ name: 'keyMap.json' }) ?? {};
+  const refMap = readBuildArtifact({ name: 'refMap.json' }) ?? {};
+  const matches = scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory });
+  return {
+    matches,
+    note:
+      'Scanned without a pageId — content on pages that have not been JIT-built yet is not ' +
+      'in keyMap and was not covered. Pass ?pageId= to force-build and scan a specific page.',
+  };
+}
+
+export default findConfig;