@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/runRequest.js

@@ -14,15 +14,20 @@
   limitations under the License.
 */
 
-import { type } from '@lowdefy/helpers';
+import path from 'node:path';
+
 import { callRequest } from '@lowdefy/api';
+import { ConfigError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
 
+import buildPageIfNeeded, { syncBuildSignals } from '../server/jitPageBuilder.js';
+import fitResponse from './fitResponse.js';
 import isWriteRequestsAllowed from './isWriteRequestsAllowed.js';
+import mapPageBuildErrors from './mapPageBuildErrors.js';
 import readBuildArtifact from './readBuildArtifact.js';
-
-// Cap the serialized response so a large request result can't blow out an
-// agent's context window.
-const MAX_RESPONSE_CHARS = 100_000;
+import resolveToolCaller from './resolveToolCaller.js';
+import reviewPage from './reviewPage.js';
+import withDataSession from './withDataSession.js';
 
 function getRequestType({ pageId, requestId }) {
   // The request's `type` is stripped from build/pages/<pageId>.json by the
@@ -37,54 +42,63 @@ function getRequestType({ pageId, requestId }) {
   return requestConfig?.type ?? null;
 }
 
-function truncateResponse(result) {
-  const json = JSON.stringify(result.response);
-  if (json.length <= MAX_RESPONSE_CHARS) {
-    return result;
-  }
-  return {
-    ...result,
-    response: json.slice(0, MAX_RESPONSE_CHARS),
-    truncated: true,
-    note: `Response truncated to ${MAX_RESPONSE_CHARS} characters (original serialized size: ${json.length} characters).`,
-  };
-}
-
 // Executes a page request the same way POST /api/request/<pageId>/<requestId>
 // does (src/routes/request.js), but gated for agent use: requests whose type
 // is not declared read-only (checkWrite: false in requestSchemas.json meta)
 // are refused unless the app opts in via lowdefy.yaml's
 // cli.agentTools.allowWriteRequests. Never throws — errors and refusals are
-// returned as data so an agent can reason about them.
-async function runRequest({ pageId, requestId, payload = {}, honoContext }) {
+// returned as data so an agent can reason about them. `user` and `data` name
+// the caller as a journey's do (see resolveToolCaller); a data set runs the
+// request on that data set's own database.
+async function runRequest({
+  pageId,
+  requestId,
+  payload = {},
+  user,
+  data,
+  saveResponse = false,
+  honoContext,
+}) {
   if (type.isUndefined(pageId) || !type.isString(pageId)) {
-    throw new Error(`run_request requires a "pageId" string. Received ${JSON.stringify(pageId)}.`);
+    throw new ConfigError(
+      `run_request requires a "pageId" string. Received ${JSON.stringify(pageId)}.`
+    );
   }
   if (type.isUndefined(requestId) || !type.isString(requestId)) {
-    throw new Error(
+    throw new ConfigError(
       `run_request requires a "requestId" string. Received ${JSON.stringify(requestId)}.`
     );
   }
 
-  let requestType = getRequestType({ pageId, requestId });
-  if (type.isNone(requestType)) {
-    // In dev, page content (including per-request artifacts) is built JIT on
-    // first page request — trigger the same build GET /api/page/* runs so a
-    // freshly added request is found without the page ever being opened.
-    try {
-      const { default: buildPageIfNeeded } = await import('../server/jitPageBuilder.js');
-      const path = await import('node:path');
-      await buildPageIfNeeded({
-        pageId,
-        buildDirectory: path.join(process.cwd(), 'build'),
-        configDirectory: process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd(),
-      });
-      requestType = getRequestType({ pageId, requestId });
-    } catch {
-      // JIT build failure surfaces through lowdefy_build_status — fall
-      // through to the not-found refusal below.
-    }
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    throw new ConfigError(`run_request: ${caller.error}`);
+  }
+
+  if (!type.isBoolean(saveResponse)) {
+    throw new ConfigError(
+      `run_request "saveResponse" must be a boolean. Received ${JSON.stringify(saveResponse)}.`
+    );
   }
+
+  // Page content, including the per-request artifacts, is built JIT, and a
+  // page edit only marks pages for rebuilding: the previous build's artifacts
+  // stay on disk until something requests the page. Run the build the page
+  // route runs (a no-op while the page is current) so the request that runs is
+  // the one in the config now.
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const buildDirectory = path.join(process.cwd(), 'build');
+  try {
+    await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+  } catch (error) {
+    return {
+      refused: true,
+      reason: `Page "${pageId}" fails to build, so its requests cannot run until the errors are fixed.`,
+      buildErrors: mapPageBuildErrors(error),
+    };
+  }
+
+  const requestType = getRequestType({ pageId, requestId });
   if (type.isNone(requestType)) {
     return {
       refused: true,
@@ -116,26 +130,53 @@ async function runRequest({ pageId, requestId, payload = {}, honoContext }) {
   // at module load would break every consumer of this module (e.g. the MCP
   // server) in environments without a full build.
   const { default: createLowdefyContext } = await import('../server/createLowdefyContext.js');
-  const context = await createLowdefyContext({ c: honoContext });
-  context.logger.info({ event: 'agent_run_request', pageId, requestId });
-
-  try {
-    const result = await callRequest(context, {
-      blockId: undefined,
-      pageId,
-      payload,
-      requestId,
-    });
-    return { refused: false, ...truncateResponse(result) };
-  } catch (error) {
-    return {
-      refused: false,
-      error: {
-        name: error.name,
-        message: error.message,
-      },
-    };
+  const ran = await withDataSession({
+    dataSet: caller.dataSet,
+    task: async ({ dataSession }) => {
+      // "none" injects no caller: the app's own auth resolves this call, which
+      // carries no session, so it runs signed out.
+      const context = await createLowdefyContext({
+        c: honoContext,
+        user: caller.user === 'none' ? undefined : caller.user,
+        dataSession,
+      });
+      context.logger.info({ event: 'agent_run_request', pageId, requestId, user, data });
+      try {
+        const result = await callRequest(context, {
+          blockId: undefined,
+          pageId,
+          payload,
+          requestId,
+        });
+        return {
+          refused: false,
+          ...fitResponse({ result, name: `${pageId}.${requestId}`, saveResponse }),
+        };
+      } catch (error) {
+        return {
+          refused: false,
+          error: {
+            name: error.name,
+            message: error.message,
+          },
+        };
+      }
+    },
+  });
+  if (!type.isUndefined(ran.error) && type.isString(ran.error)) {
+    return { refused: true, reason: ran.error };
+  }
+  const signals = syncBuildSignals({ buildDirectory, configDirectory });
+  const review = await reviewPage({
+    pageId,
+    entry: signals.registry?.[pageId],
+    configDirectory,
+    signals,
+  });
+  if (review === 'edited') {
+    ran.staleConfig = `Page "${pageId}" changed on disk after its last build, but the dev server has not rebuilt it yet, so this ran the previous config. Call lowdefy_build_status with wait: true, then run the request again.`;
   }
+  return ran;
 }
 
 export default runRequest;

package/lib/docs/runRequest.test.mjs

@@ -0,0 +1,190 @@
+/*
+  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';
+
+// runRequest reads build artifacts, builds a Lowdefy context and calls
+// callRequest - all three only exist in a running server directory, so mock
+// them and leave only runRequest's own validation and pass-through under test.
+const mockCallRequest = jest.fn();
+const mockReadBuildArtifact = jest.fn();
+const mockIsWriteRequestsAllowed = jest.fn();
+const mockCreateLowdefyContext = jest.fn();
+const mockLoggerInfo = jest.fn();
+
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  callRequest: mockCallRequest,
+}));
+jest.unstable_mockModule('./readBuildArtifact.js', () => ({
+  default: mockReadBuildArtifact,
+}));
+jest.unstable_mockModule('./isWriteRequestsAllowed.js', () => ({
+  default: mockIsWriteRequestsAllowed,
+}));
+jest.unstable_mockModule('../server/createLowdefyContext.js', () => ({
+  default: mockCreateLowdefyContext,
+}));
+const mockBuildPageIfNeeded = jest.fn();
+const mockSyncBuildSignals = jest.fn(() => ({
+  registry: { home: { pageId: 'home', refPath: 'pages/home.yaml' } },
+  eventCounter: 0,
+  generation: 1,
+}));
+jest.unstable_mockModule('../server/jitPageBuilder.js', () => ({
+  default: mockBuildPageIfNeeded,
+  syncBuildSignals: mockSyncBuildSignals,
+}));
+const mockReviewPage = jest.fn();
+jest.unstable_mockModule('./reviewPage.js', () => ({
+  default: mockReviewPage,
+}));
+
+const { ConfigError } = await import('@lowdefy/errors');
+const { default: runRequest } = await import('./runRequest.js');
+
+const honoContext = { req: { path: '/lowdefy-docs/run-request' } };
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockReadBuildArtifact.mockImplementation(({ name }) => {
+    if (name === 'plugins/requestSchemas.json') {
+      return { MongoDBFind: { meta: { checkRead: true, checkWrite: false } } };
+    }
+    if (name === 'pageRegistry.json') {
+      return { home: { pageId: 'home', refPath: 'pages/home.yaml' }, other: { pageId: 'other' } };
+    }
+    return { type: 'MongoDBFind' };
+  });
+  mockIsWriteRequestsAllowed.mockResolvedValue(false);
+  mockCreateLowdefyContext.mockResolvedValue({ logger: { info: mockLoggerInfo } });
+  mockCallRequest.mockResolvedValue({ id: 'requests', response: [{ _id: 1 }] });
+  mockBuildPageIfNeeded.mockResolvedValue(true);
+  mockReviewPage.mockResolvedValue('current');
+});
+
+test('runRequest passes a user object to createLowdefyContext', async () => {
+  const user = { roles: ['admin'], organization_id: 'org_1' };
+
+  const result = await runRequest({
+    pageId: 'home',
+    requestId: 'get_rows',
+    user,
+    honoContext,
+  });
+
+  expect(mockCreateLowdefyContext).toHaveBeenCalledWith({ c: honoContext, user });
+  expect(result.refused).toBe(false);
+  expect(result.response).toEqual([{ _id: 1 }]);
+});
+
+test('runRequest logs the user it ran the request as', async () => {
+  const user = { roles: ['admin'] };
+
+  await runRequest({ pageId: 'home', requestId: 'get_rows', user, honoContext });
+
+  expect(mockLoggerInfo).toHaveBeenCalledWith({
+    event: 'agent_run_request',
+    pageId: 'home',
+    requestId: 'get_rows',
+    user,
+  });
+});
+
+test('runRequest throws a ConfigError when user is neither an object nor a data set user', async () => {
+  await expect(
+    runRequest({ pageId: 'home', requestId: 'get_rows', user: 'admin', honoContext })
+  ).rejects.toThrow(ConfigError);
+  await expect(
+    runRequest({ pageId: 'home', requestId: 'get_rows', user: ['admin'], honoContext })
+  ).rejects.toThrow(/run_request: "user" should be a user object/);
+  expect(mockCreateLowdefyContext).not.toHaveBeenCalled();
+});
+
+test('runRequest builds a context with an undefined user when user is omitted', async () => {
+  const result = await runRequest({ pageId: 'home', requestId: 'get_rows', honoContext });
+
+  expect(mockCreateLowdefyContext).toHaveBeenCalledWith({ c: honoContext, user: undefined });
+  expect(mockLoggerInfo).toHaveBeenCalledWith({
+    event: 'agent_run_request',
+    pageId: 'home',
+    requestId: 'get_rows',
+    user: undefined,
+  });
+  expect(result).toEqual({ refused: false, id: 'requests', response: [{ _id: 1 }] });
+});
+
+test('runRequest refuses a write request for an impersonated caller too', async () => {
+  mockReadBuildArtifact.mockImplementation(({ name }) => {
+    if (name === 'plugins/requestSchemas.json') {
+      return { MongoDBInsertOne: { meta: { checkWrite: true } } };
+    }
+    return { type: 'MongoDBInsertOne' };
+  });
+
+  const result = await runRequest({
+    pageId: 'home',
+    requestId: 'insert_row',
+    user: { roles: ['admin'] },
+    honoContext,
+  });
+
+  expect(result.refused).toBe(true);
+  expect(mockCreateLowdefyContext).not.toHaveBeenCalled();
+});
+
+test('runRequest notes stale config when the page changed but the dev server has not rebuilt it', async () => {
+  mockReviewPage.mockResolvedValue('edited');
+
+  const result = await runRequest({ pageId: 'home', requestId: 'get_rows', honoContext });
+
+  expect(result.response).toEqual([{ _id: 1 }]);
+  expect(result.staleConfig).toContain('has not rebuilt it yet');
+});
+
+test('runRequest does not note stale config for a page that is current', async () => {
+  const result = await runRequest({ pageId: 'home', requestId: 'get_rows', honoContext });
+
+  expect(result.staleConfig).toBeUndefined();
+});
+
+test('runRequest throws a ConfigError when saveResponse is not a boolean', async () => {
+  await expect(
+    runRequest({ pageId: 'home', requestId: 'get_rows', saveResponse: 1, honoContext })
+  ).rejects.toThrow(ConfigError);
+  expect(mockBuildPageIfNeeded).not.toHaveBeenCalled();
+});
+
+test('runRequest notes stale config on a request that fails', async () => {
+  mockReviewPage.mockResolvedValue('edited');
+  mockCallRequest.mockRejectedValue(new Error('connect ECONNREFUSED'));
+
+  const result = await runRequest({ pageId: 'home', requestId: 'get_rows', honoContext });
+
+  expect(result.error.message).toBe('connect ECONNREFUSED');
+  expect(result.staleConfig).toContain('ran the previous config');
+});
+
+test('runRequest reviews only the page it ran', async () => {
+  await runRequest({ pageId: 'home', requestId: 'get_rows', honoContext });
+
+  expect(mockReviewPage).toHaveBeenCalledTimes(1);
+  expect(mockReviewPage).toHaveBeenCalledWith(
+    expect.objectContaining({
+      pageId: 'home',
+      entry: { pageId: 'home', refPath: 'pages/home.yaml' },
+    })
+  );
+});

package/lib/docs/saveAnnotatedScreenshot.js

@@ -34,7 +34,7 @@ function saveAnnotatedScreenshot({ dataUrl, fileName }) {
     const dir = path.join(configDirectory, '.lowdefy', 'annotations');
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, fileName), buffer);
-    return { path: path.join('.lowdefy', 'annotations', fileName) };
+    return { path: path.posix.join('.lowdefy', 'annotations', fileName) };
   } catch (error) {
     return { error: `Failed to save annotated screenshot: ${error.message}` };
   }

package/lib/docs/scaffoldPage.js

@@ -49,6 +49,8 @@ function scaffoldPage({ pageId, title }) {
 
   const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
   const pageRelativePath = path.join('pages', `${pageId}.yaml`);
+  // _ref paths in config use forward slashes on every platform.
+  const pageRefPath = path.posix.join('pages', `${pageId}.yaml`);
   const pageFilePath = path.join(configDirectory, pageRelativePath);
 
   if (fs.existsSync(pageFilePath)) {
@@ -68,7 +70,7 @@ function scaffoldPage({ pageId, title }) {
 
   return {
     created: pageRelativePath,
-    next: `Add \`- _ref: ${pageRelativePath}\` under \`pages:\` in lowdefy.yaml (or the relevant pages file), then check lowdefy_build_status.`,
+    next: `Add \`- _ref: ${pageRefPath}\` under \`pages:\` in lowdefy.yaml (or the relevant pages file), then check lowdefy_build_status.`,
   };
 }
 

package/lib/docs/screenshotPage.js

@@ -15,8 +15,19 @@
 */
 
 import { type } from '@lowdefy/helpers';
+import { normaliseJourneySteps, validateJourneySteps } from '@lowdefy/node-utils';
 
 import { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+import noBrowserError from './noBrowserError.js';
+import openJourney from './openJourney.js';
+import resolvePageInstance from './resolvePageInstance.js';
+import resolveToolCaller from './resolveToolCaller.js';
+import runJourneySteps from './runJourneySteps.js';
+import unsettledPageNote from './unsettledPageNote.js';
+import validateJourneyMail from './validateJourneyMail.js';
+import validateViewport from './validateViewport.js';
+import withBrowserSlot from './withBrowserSlot.js';
+import withDataSession from './withDataSession.js';
 
 // A feedback annotation's elementRect/shapes are captured in the developer's
 // live tab, viewport-relative at whatever scroll position they were at
@@ -51,18 +62,59 @@ async function resolveClip({ page, clip, scrollX, scrollY }) {
   };
 }
 
+// Opens the page and, when `steps` are given, runs them before the capture —
+// the same step engine lowdefy_run_journey uses, so an agent can capture an
+// open dropdown, a picker's calendar or a modal. Returns the page, a cleanup
+// function, the page-open timeout, any captures `screenshot` steps took and any
+// step failure; the capture happens on whatever state the steps left (also
+// after a failed step, which is what the agent needs to see).
+async function openAndRunSteps({ browser, steps, stepTimeout, users, ...pageOptions }) {
+  if (steps.length === 0) {
+    const opened = await openPage({ browser, ...pageOptions });
+    return {
+      opened,
+      close: () => opened.context.close(),
+      openTimeout: pageOptions.timeout,
+      screenshots: [],
+    };
+  }
+  const { journey, main } = await openJourney({ browser, ...pageOptions, stepTimeout, users });
+  const { screenshots, failure } = await runJourneySteps({ journey, steps });
+  return {
+    opened: { ...journey.actors.current(), ready: main.ready },
+    close: journey.actors.closeAll,
+    openTimeout: journey.openTimeout,
+    screenshots,
+    failure,
+  };
+}
+
 // screenshotPage lets an agent visually verify a page rendered by the
-// running dev server.
+// running dev server, at a given viewport size and colour scheme. `pathParams`
+// fill a patterned page's placeholders, `urlQuery` opens the page at a query
+// string, and `steps` (see validateJourneySteps)
+// drive it first — open a dropdown, click a button — so the capture shows
+// that state; captures `screenshot` steps take come back as `screenshots`.
+// Popups antd renders in a portal at the end of <body> are part of the
+// document, so a fullPage or clip capture includes them. `user` and `data`
+// name the caller as a journey's do (see resolveToolCaller): a data set user
+// renders the page on that data set's own database.
 async function screenshotPage({
   origin,
   pageId,
+  pathParams,
+  urlQuery,
+  steps: inputSteps = [],
+  stepTimeout = 5000,
   fullPage = false,
   clip,
   scrollX = 0,
   scrollY = 0,
   user,
+  data,
   width = 1280,
   height = 800,
+  colorScheme = 'light',
   timeout = 15000,
 }) {
   if (type.isNone(origin) || !type.isString(origin)) {
@@ -75,34 +127,134 @@ async function screenshotPage({
       error: `screenshotPage requires a "pageId" string. Received ${JSON.stringify(pageId)}.`,
     };
   }
+  if (!type.isNone(urlQuery) && !type.isObject(urlQuery)) {
+    return {
+      error: `screenshotPage requires "urlQuery" to be an object. Received ${JSON.stringify(
+        urlQuery
+      )}.`,
+    };
+  }
+  const instance = resolvePageInstance({ pageId, pathParams });
+  if (!type.isUndefined(instance.error)) {
+    return { error: instance.error, invalidInput: true };
+  }
+  const { error: stepsError } = validateJourneySteps({ steps: inputSteps });
+  if (!type.isUndefined(stepsError)) {
+    return { error: stepsError };
+  }
+  const steps = normaliseJourneySteps({ steps: inputSteps });
+  const viewportError = validateViewport({ width, height, colorScheme });
+  if (!type.isUndefined(viewportError)) {
+    return { error: viewportError };
+  }
+  const mailError = validateJourneyMail({ steps });
+  if (!type.isUndefined(mailError)) {
+    return { error: mailError };
+  }
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
+  return withBrowserSlot({
+    task: () =>
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          screenshotInBrowser({
+            origin,
+            pageId,
+            path: instance.path,
+            pathParams,
+            urlQuery,
+            user: caller.user,
+            dataCookie,
+            users: caller.dataSet?.users,
+            width,
+            height,
+            colorScheme,
+            timeout,
+            steps,
+            stepTimeout,
+            clip,
+            scrollX,
+            scrollY,
+            fullPage,
+          }),
+      }),
+  });
+}
 
+// The part of screenshotPage that runs in the browser, inside a browser slot.
+async function screenshotInBrowser({
+  origin,
+  pageId,
+  path,
+  pathParams,
+  urlQuery,
+  user,
+  dataCookie,
+  users,
+  width,
+  height,
+  colorScheme,
+  timeout,
+  steps,
+  stepTimeout,
+  clip,
+  scrollX,
+  scrollY,
+  fullPage,
+}) {
   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, pathParams, urlQuery });
 
-  let context;
+  let close;
   try {
-    const opened = await openPage({ browser, origin, pageId, user, width, height, timeout });
-    context = opened.context;
+    const run = await openAndRunSteps({
+      browser,
+      origin,
+      pageId,
+      path,
+      pathParams,
+      urlQuery,
+      user,
+      dataCookie,
+      users,
+      width,
+      height,
+      colorScheme,
+      timeout,
+      steps,
+      stepTimeout,
+    });
+    const { opened, openTimeout, screenshots, failure } = run;
+    close = run.close;
     // Let post-load rendering (fonts, transitions, client-side state) settle.
     await opened.page.waitForTimeout(300);
 
     const docClip = await resolveClip({ page: opened.page, clip, scrollX, scrollY });
     const screenshotOptions = docClip ? { type: 'png', clip: docClip } : { type: 'png', fullPage };
     const buffer = await opened.page.screenshot(screenshotOptions);
-    return { data: buffer.toString('base64'), mimeType: 'image/png' };
+    const result = { data: buffer.toString('base64'), mimeType: 'image/png', screenshots };
+    if (!type.isUndefined(failure)) {
+      result.failure = failure;
+    }
+    if (!opened.ready) {
+      return { ...result, ready: false, note: unsettledPageNote({ timeout: openTimeout }) };
+    }
+    return result;
   } catch (error) {
     return { error: `Failed to screenshot "${url}": ${error.message}` };
   } finally {
-    if (context) {
-      await context.close();
+    if (close) {
+      await close();
     }
   }
 }