@lowdefy/server-dev 0.0.0-experimental-20260925210809 → 0.0.0-experimental-20260926170209

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/lib/docs/buildEditedPages.js +50 -0
  2. package/lib/docs/clientErrorStore.js +5 -2
  3. package/lib/docs/clientErrorStore.test.mjs +7 -3
  4. package/lib/docs/createDocsMcpServer.js +18 -9
  5. package/lib/docs/createDocsMcpServer.test.mjs +28 -0
  6. package/lib/docs/devToolDefinitions.js +43 -9
  7. package/lib/docs/docs.test.mjs +52 -6
  8. package/lib/docs/fitResponse.js +81 -0
  9. package/lib/docs/fitResponse.test.mjs +128 -0
  10. package/lib/docs/getBrowser.js +4 -1
  11. package/lib/docs/getBrowser.test.mjs +29 -0
  12. package/lib/docs/getBuildId.js +61 -0
  13. package/lib/docs/getBuildId.test.mjs +84 -0
  14. package/lib/docs/getBuildStatus.js +34 -8
  15. package/lib/docs/getBuildStatus.test.mjs +66 -0
  16. package/lib/docs/getBuildStatusAfterEdits.js +33 -0
  17. package/lib/docs/getBuildStatusAfterEdits.test.mjs +58 -0
  18. package/lib/docs/getOverview.js +7 -7
  19. package/lib/docs/getPageBuildStatus.js +46 -0
  20. package/lib/docs/pageBuildStatus.test.mjs +103 -0
  21. package/lib/docs/reviewPage.js +63 -0
  22. package/lib/docs/reviewPageBuilds.js +46 -0
  23. package/lib/docs/reviewPageBuilds.test.mjs +153 -0
  24. package/lib/docs/runCheckChild.js +4 -2
  25. package/lib/docs/runEndpoint.js +16 -3
  26. package/lib/docs/runEndpoint.test.mjs +61 -9
  27. package/lib/docs/runJourney.js +102 -11
  28. package/lib/docs/runJourney.test.mjs +231 -4
  29. package/lib/docs/runRequest.js +56 -22
  30. package/lib/docs/runRequest.test.mjs +58 -0
  31. package/lib/docs/screenshotPage.js +17 -2
  32. package/lib/docs/screenshotPage.test.mjs +16 -0
  33. package/lib/docs/selectFinalState.js +66 -0
  34. package/lib/docs/selectFinalState.test.mjs +51 -0
  35. package/lib/docs/serverErrorStore.js +5 -2
  36. package/lib/docs/serverErrorStore.test.mjs +9 -4
  37. package/lib/docs/validateJourneySteps.js +17 -3
  38. package/lib/docs/validateJourneySteps.test.mjs +17 -4
  39. package/lib/docs/validateStateSelection.js +33 -0
  40. package/lib/docs/validateStateSelection.test.mjs +33 -0
  41. package/lib/docs/validateViewport.js +46 -0
  42. package/lib/docs/validateViewport.test.mjs +33 -0
  43. package/lib/server/jitPageBuilder.js +5 -2
  44. package/lib/server/pageBuildRecords.js +82 -0
  45. package/lib/server/pageBuildRecords.test.mjs +157 -0
  46. package/manager/getContext.mjs +10 -1
  47. package/manager/processes/lowdefyBuild.mjs +21 -7
  48. package/manager/processes/lowdefyBuild.test.mjs +94 -1
  49. package/manager/processes/startWatchers.mjs +0 -2
  50. package/manager/utils/createCustomPluginMessagesMap.mjs +20 -15
  51. package/manager/utils/createCustomPluginTypesMap.mjs +19 -11
  52. package/manager/utils/createCustomPluginTypesMap.test.mjs +89 -0
  53. package/manager/utils/createDotPathIgnore.mjs +44 -0
  54. package/manager/utils/createDotPathIgnore.test.mjs +52 -0
  55. package/manager/utils/findBuildFilesOutsideWatch.mjs +41 -0
  56. package/manager/utils/findBuildFilesOutsideWatch.test.mjs +77 -0
  57. package/manager/utils/importFresh.mjs +46 -0
  58. package/manager/utils/importFresh.test.mjs +72 -0
  59. package/manager/utils/importFreshWorker.mjs +20 -0
  60. package/manager/utils/publishBuildDirectory.mjs +72 -0
  61. package/manager/utils/publishBuildDirectory.test.mjs +170 -0
  62. package/manager/utils/setupWatcher.mjs +2 -8
  63. package/manager/utils/writeBuildStatus.mjs +1 -1
  64. package/manager/watchers/lowdefyBuildWatcher.mjs +72 -16
  65. package/manager/watchers/lowdefyBuildWatcher.test.mjs +169 -0
  66. package/manager/watchers/restartRequestWatcher.mjs +9 -1
  67. package/manager/watchers/restartRequestWatcher.test.mjs +25 -0
  68. package/package.json +38 -39
  69. package/package.original.json +38 -39
  70. package/src/middleware/errorHandler.js +13 -0
  71. package/src/middleware/errorHandler.test.mjs +51 -0
  72. package/src/routes/docs/buildStatus.js +4 -3
  73. package/src/routes/docs/journey.js +7 -2
  74. package/src/routes/docs/journey.test.mjs +21 -1
  75. package/src/routes/docs/runEndpoint.js +2 -1
  76. package/src/routes/docs/runRequest.js +2 -1
  77. package/src/routes/docs/screenshot.js +37 -1
  78. package/src/routes/docs/screenshot.test.mjs +117 -0
  79. package/src/routes/mcp.test.mjs +16 -0
  80. package/src/routes/request.js +1 -1
  81. package/src/routes/websocket.js +9 -8
  82. package/src/websocket/devWebSocket.js +36 -26
  83. package/src/websocket/devWebSocket.test.mjs +124 -0
  84. package/vite.config.js +17 -11
  85. package/lib/docs/truncateResponse.js +0 -39
  86. package/lib/docs/truncateResponse.test.mjs +0 -49
  87. package/manager/watchers/moduleBuildWatcher.mjs +0 -80
@@ -0,0 +1,50 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ import path from 'node:path';
18
+
19
+ import buildPageIfNeeded from '../server/jitPageBuilder.js';
20
+ import reviewPageBuilds from './reviewPageBuilds.js';
21
+
22
+ // Page builds share one build context, and most of a build is waiting on file
23
+ // reads, so a few run at once; more would only compete for the same process.
24
+ const CONCURRENT_BUILDS = 4;
25
+
26
+ // Builds every page an edit touched (see reviewPageBuilds), the same build a
27
+ // page request runs (with its per-page lock), so build status covers pages
28
+ // nobody has opened since the edit. A failed build is recorded by the page
29
+ // builder and reported from there.
30
+ async function buildEditedPages() {
31
+ const { edited } = reviewPageBuilds();
32
+ const buildDirectory = path.join(process.cwd(), 'build');
33
+ const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
34
+ const queue = [...edited];
35
+ async function buildNext() {
36
+ while (queue.length > 0) {
37
+ const pageId = queue.shift();
38
+ try {
39
+ await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
40
+ } catch {
41
+ // Reported by getPageBuildStatus from the page's build record.
42
+ }
43
+ }
44
+ }
45
+ await Promise.all(Array.from({ length: Math.min(CONCURRENT_BUILDS, queue.length) }, buildNext));
46
+ return edited;
47
+ }
48
+
49
+ export { CONCURRENT_BUILDS };
50
+ export default buildEditedPages;
@@ -15,6 +15,7 @@
15
15
  */
16
16
 
17
17
  import { publish } from './devEventBus.js';
18
+ import getBuildId from './getBuildId.js';
18
19
 
19
20
  // Module-level ring buffer of recent client-reported errors — feeds the
20
21
  // getBuildStatus feedback endpoint so agents can see browser errors without
@@ -24,12 +25,14 @@ const MAX_ENTRIES = 50;
24
25
 
25
26
  const entries = [];
26
27
 
28
+ // Each entry is stamped with the build it happened under (see getBuildId).
27
29
  function push(entry) {
28
- entries.push(entry);
30
+ const stamped = { ...entry, buildId: getBuildId() };
31
+ entries.push(stamped);
29
32
  if (entries.length > MAX_ENTRIES) {
30
33
  entries.shift();
31
34
  }
32
- publish({ type: 'client_error', ...entry });
35
+ publish({ type: 'client_error', ...stamped });
33
36
  }
34
37
 
35
38
  function list() {
@@ -20,14 +20,18 @@ const mockPublish = jest.fn();
20
20
  jest.unstable_mockModule('./devEventBus.js', () => ({
21
21
  publish: mockPublish,
22
22
  }));
23
+ jest.unstable_mockModule('./getBuildId.js', () => ({
24
+ default: () => '2026-01-01T00:00:00.000Z',
25
+ }));
23
26
 
24
27
  const { default: clientErrorStore } = await import('./clientErrorStore.js');
25
28
 
26
- test('clientErrorStore push adds an entry, lists it, and publishes it as a client_error event', () => {
29
+ test('clientErrorStore push adds an entry stamped with the current build, lists it, and publishes it as a client_error event', () => {
27
30
  const entry = { timestamp: '2026-01-01T00:00:00.000Z', name: 'OperatorError', message: 'bad' };
31
+ const stamped = { ...entry, buildId: '2026-01-01T00:00:00.000Z' };
28
32
  clientErrorStore.push(entry);
29
- expect(clientErrorStore.list()).toEqual([entry]);
30
- expect(mockPublish).toHaveBeenCalledWith({ type: 'client_error', ...entry });
33
+ expect(clientErrorStore.list()).toEqual([stamped]);
34
+ expect(mockPublish).toHaveBeenCalledWith({ type: 'client_error', ...stamped });
31
35
  });
32
36
 
33
37
  test('clientErrorStore caps at 50 entries and drops the oldest', () => {
@@ -24,6 +24,7 @@ import evalOperator from './evalOperator.js';
24
24
  import findConfig from './findConfig.js';
25
25
  import getAppMap from './getAppMap.js';
26
26
  import getBuildStatus from './getBuildStatus.js';
27
+ import getBuildStatusAfterEdits from './getBuildStatusAfterEdits.js';
27
28
  import getCoreDoc from './getCoreDoc.js';
28
29
  import getExamples from './getExamples.js';
29
30
  import getOverview from './getOverview.js';
@@ -50,7 +51,6 @@ import scaffoldPage from './scaffoldPage.js';
50
51
  import screenshotPage from './screenshotPage.js';
51
52
  import searchDocs from './searchDocs.js';
52
53
  import searchIcons from './searchIcons.js';
53
- import waitForBuild from './waitForBuild.js';
54
54
 
55
55
  const logger = createLogger({ server: 'lowdefy-dev-mcp' });
56
56
 
@@ -140,12 +140,18 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
140
140
  return textResult(result);
141
141
  });
142
142
 
143
- registerDevTool('lowdefy_run_request', async ({ pageId, requestId, payload, user }) =>
144
- textResult(await runRequest({ pageId, requestId, payload, user, honoContext }))
143
+ registerDevTool(
144
+ 'lowdefy_run_request',
145
+ async ({ pageId, requestId, payload, user, saveResponse }) =>
146
+ textResult(await runRequest({ pageId, requestId, payload, user, saveResponse, honoContext }))
145
147
  );
146
148
 
147
- registerDevTool('lowdefy_run_endpoint', async ({ endpointId, payload, user, system }) =>
148
- textResult(await runEndpoint({ endpointId, payload, user, system, honoContext }))
149
+ registerDevTool(
150
+ 'lowdefy_run_endpoint',
151
+ async ({ endpointId, payload, user, system, saveResponse }) =>
152
+ textResult(
153
+ await runEndpoint({ endpointId, payload, user, system, saveResponse, honoContext })
154
+ )
149
155
  );
150
156
 
151
157
  registerDevTool('lowdefy_restart', ({ reason }) =>
@@ -198,7 +204,7 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
198
204
 
199
205
  registerDevTool('lowdefy_build_status', async ({ wait }) => {
200
206
  if (wait === true) {
201
- return textResult({ ...(await waitForBuild()), ...getBuildStatus() });
207
+ return textResult(await getBuildStatusAfterEdits());
202
208
  }
203
209
  return textResult(getBuildStatus());
204
210
  });
@@ -219,7 +225,7 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
219
225
 
220
226
  registerDevTool(
221
227
  'lowdefy_screenshot_page',
222
- async ({ pageId, fullPage, clip, scrollX, scrollY, user }) => {
228
+ async ({ pageId, fullPage, clip, scrollX, scrollY, user, width, height, colorScheme }) => {
223
229
  if (!origin) {
224
230
  return notFoundResult('Screenshot unavailable: server origin unknown for this transport.');
225
231
  }
@@ -231,6 +237,9 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
231
237
  scrollX,
232
238
  scrollY,
233
239
  user,
240
+ width,
241
+ height,
242
+ colorScheme,
234
243
  });
235
244
  if (result.error) {
236
245
  return notFoundResult(result.error);
@@ -239,11 +248,11 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
239
248
  }
240
249
  );
241
250
 
242
- registerDevTool('lowdefy_run_journey', async ({ pageId, steps, user, urlQuery }) => {
251
+ registerDevTool('lowdefy_run_journey', async ({ pageId, steps, user, urlQuery, state }) => {
243
252
  if (!origin) {
244
253
  return notFoundResult('Journey unavailable: server origin unknown for this transport.');
245
254
  }
246
- const result = await runJourney({ origin, pageId, steps, user, urlQuery });
255
+ const result = await runJourney({ origin, pageId, steps, user, urlQuery, state });
247
256
  if (result.error) {
248
257
  return notFoundResult(result.error);
249
258
  }
@@ -183,6 +183,32 @@ test('MCP tools that render a page headless advertise an optional user parameter
183
183
  await client.close();
184
184
  });
185
185
 
186
+ test('MCP lowdefy_screenshot_page advertises width, height and colorScheme', async () => {
187
+ const client = await connectClient();
188
+ const { tools } = await client.listTools();
189
+ const { properties } = tools.find((tool) => tool.name === 'lowdefy_screenshot_page').inputSchema;
190
+
191
+ expect(properties.width).toMatchObject({ type: 'integer', exclusiveMinimum: 0 });
192
+ expect(properties.height).toMatchObject({ type: 'integer', exclusiveMinimum: 0 });
193
+ expect(properties.colorScheme).toMatchObject({ enum: ['light', 'dark'] });
194
+ await client.close();
195
+ });
196
+
197
+ test('MCP lowdefy_run_journey advertises a state option of true, false or state paths', async () => {
198
+ const client = await connectClient();
199
+ const { tools } = await client.listTools();
200
+ const { properties, required } = tools.find(
201
+ (tool) => tool.name === 'lowdefy_run_journey'
202
+ ).inputSchema;
203
+
204
+ expect(properties.state.anyOf).toEqual([
205
+ { type: 'boolean' },
206
+ { type: 'array', items: { type: 'string', minLength: 1 } },
207
+ ]);
208
+ expect(required).not.toContain('state');
209
+ await client.close();
210
+ });
211
+
186
212
  test('MCP tools/call lowdefy_get_schema returns a block schema', async () => {
187
213
  const client = await connectClient();
188
214
  const result = await client.callTool({
@@ -330,6 +356,7 @@ test('MCP tools/call lowdefy_run_journey returns the JSON result followed by one
330
356
  steps: [{ screenshot: 'before' }, { click: 'nope' }],
331
357
  user: { roles: ['admin'] },
332
358
  urlQuery: { id: '1' },
359
+ state: ['saved'],
333
360
  },
334
361
  });
335
362
 
@@ -339,6 +366,7 @@ test('MCP tools/call lowdefy_run_journey returns the JSON result followed by one
339
366
  steps: [{ screenshot: 'before' }, { click: 'nope' }],
340
367
  user: { roles: ['admin'] },
341
368
  urlQuery: { id: '1' },
369
+ state: ['saved'],
342
370
  });
343
371
  expect(result.content).toHaveLength(3);
344
372
  const summary = JSON.parse(result.content[0].text);
@@ -28,11 +28,11 @@ Discovery workflow: start with lowdefy_overview. Use lowdefy_list_types with a k
28
28
 
29
29
  Push events: build results, server restarts and browser/server errors arrive as notifications/message from logger "lowdefy" (data.type is one of build, restart, client_error, server_error; a build event carries status, errors, warnings and stale). Act on them without polling — lowdefy_build_status remains the full picture.
30
30
 
31
- Feedback loop: after EVERY config edit, call lowdefy_build_status with wait: true — the dev server rebuilds on file change, wait: true answers once your edit has been processed, and this returns the current build errors/warnings (with source file locations), recent browser runtime errors, and recent server errors (request, endpoint, MCP and agent failures with their config source). Fix what it reports, then confirm the page builds with lowdefy_get_page_config, and visually verify with lowdefy_screenshot_page. Use lowdefy_find_config to locate where any id (page, block, request) is defined. lowdefy_scaffold_page creates a canonical new page file. Use lowdefy_app_map first to understand an existing app. If a tool result begins with "STALE:", the last build FAILED and the answer comes from the previous successful build, not from your latest edits — call lowdefy_build_status and fix the reported errors before trusting anything else.
31
+ Feedback loop: after EVERY config edit, call lowdefy_build_status with wait: true — the dev server rebuilds on file change, wait: true answers once your edit has been processed and the pages it touched have been built, and this returns the current build errors/warnings (with source file locations), the pages that fail to build (pages.failed), recent browser runtime errors, and recent server errors (request, endpoint, MCP and agent failures with their config source). Errors reported before your latest edit are listed apart under earlierErrors, since they may already be fixed. Fix what it reports, then confirm the page builds with lowdefy_get_page_config, and visually verify with lowdefy_screenshot_page. Use lowdefy_find_config to locate where any id (page, block, request) is defined. lowdefy_scaffold_page creates a canonical new page file. Use lowdefy_app_map first to understand an existing app. If a tool result begins with "STALE:", the last build FAILED and the answer comes from the previous successful build, not from your latest edits — call lowdefy_build_status and fix the reported errors before trusting anything else.
32
32
 
33
- Live state: lowdefy_inspect_state reads the ACTUAL state, request results, and event log of a running page — when the developer has the page open in their browser it reads THEIR live tab (ask them to interact, then inspect), otherwise it runs the page headless. lowdefy_eval_operator evaluates any operator expression against that live state — use it to debug _state/_request bindings. lowdefy_run_request executes a request with a test payload to verify data shape (read-only unless the app opts into writes). lowdefy_run_endpoint runs an Api endpoint routine headlessly with a test payload (always needs cli.agentTools.allowWriteRequests, since routines are not classified read-only); a :reject comes back as status "reject" with the routine's own error, not as a tool failure. Pass system: true to run a scheduled or detached-only InternalApi routine as a system context (no _user, auth not checked), exactly as cron would.
33
+ Live state: lowdefy_inspect_state reads the ACTUAL state, request results, and event log of a running page — when the developer has the page open in their browser it reads THEIR live tab (ask them to interact, then inspect), otherwise it runs the page headless. lowdefy_eval_operator evaluates any operator expression against that live state — use it to debug _state/_request bindings. lowdefy_run_request executes a request with a test payload to verify data shape (read-only unless the app opts into writes). A request or endpoint response too large to return inline is written in full to a file under .lowdefy/responses/ and the result gives its path as responseFile; pass saveResponse: true to always write it there. lowdefy_run_endpoint runs an Api endpoint routine headlessly with a test payload (always needs cli.agentTools.allowWriteRequests, since routines are not classified read-only); a :reject comes back as status "reject" with the routine's own error, not as a tool failure. Pass system: true to run a scheduled or detached-only InternalApi routine as a system context (no _user, auth not checked), exactly as cron would.
34
34
 
35
- Behaviour, not just layout: a screenshot shows what rendered, not what works. To verify behaviour, drive the page with lowdefy_run_journey — a declarative list of steps (click, fill, select, press, wait, screenshot, expect) addressed by blockId — and assert on state, visibility, text or url. A failing step stops the journey and comes back as data (passed: false, failure with expected/actual, the remaining steps skipped) together with the final page state, so you can read what the app actually did and write the next assertion. Pass user to act as a real member (e.g. {"roles":["admin"]}) when the flow is role-gated.
35
+ Behaviour, not just layout: a screenshot shows what rendered, not what works. To verify behaviour, drive the page with lowdefy_run_journey — a declarative list of steps (click, fill, select, press, back, wait, screenshot, expect) addressed by blockId — and assert on state, visibility, text, url or title. A failing step stops the journey and comes back as data (passed: false, failure with expected/actual, the remaining steps skipped) together with the final page state, so you can read what the app actually did and write the next assertion. A large final state comes back as a summary of its keys; pass state with the paths you need. Pass user to act as a real member (e.g. {"roles":["admin"]}) when the flow is role-gated.
36
36
 
37
37
  Role-gated pages: the headless renderer signs in as a roleless user, so a page or request gated on a role renders empty or refused. Pass user to lowdefy_screenshot_page, lowdefy_run_journey, lowdefy_inspect_state, lowdefy_eval_operator, lowdefy_load_state, lowdefy_run_request or lowdefy_run_endpoint to act as a specific caller — e.g. user {"roles":["admin"]} — and vary it per call to compare what different roles see. A request run without user runs as a roleless anonymous caller, so a tenant-walled or role-gated request returns empty rather than an error.
38
38
 
@@ -56,6 +56,14 @@ const userSchema = z
56
56
  'Act as this caller instead of the default roleless headless user, e.g. {"roles":["user-admin"]} to render a role-gated page. Merged over the default, so include email/profile/attributes fields too if the page reads them — no auth engine runs for an injected caller, so nothing derives them. Headless only: it is never applied to a page the developer opens in their own browser, so combining it with source "tab" or load_state mode "registry-only" is an error rather than a silently dropped role, and on lowdefy_run_request / lowdefy_run_endpoint it sets the caller the request or routine runs as.'
57
57
  );
58
58
 
59
+ // Shared by the request and endpoint runners.
60
+ const saveResponseSchema = z
61
+ .boolean()
62
+ .optional()
63
+ .describe(
64
+ 'Write the full response to a JSON file under .lowdefy/responses/ in the app directory and return its path (responseFile) instead of the response. A response too large to return inline is always written there.'
65
+ );
66
+
59
67
  const devToolDefinitions = {
60
68
  lowdefy_inspect_state: {
61
69
  description:
@@ -85,12 +93,13 @@ const devToolDefinitions = {
85
93
 
86
94
  lowdefy_run_request: {
87
95
  description:
88
- 'Execute a request in dev with a test payload to verify the data shape a page receives. Read-only request types always run; write requests are refused unless the app opts in (cli.agentTools.allowWriteRequests in lowdefy.yaml).',
96
+ 'Execute a request in dev with a test payload to verify the data shape a page receives. The page is built first when it changed since its last build, so the request that runs is the one in the config now; a page that fails to build is refused with its build errors. Read-only request types always run; write requests are refused unless the app opts in (cli.agentTools.allowWriteRequests in lowdefy.yaml). A response too large to return inline is written in full to responseFile.',
89
97
  inputSchema: {
90
98
  pageId: z.string().describe('The page the request is defined on.'),
91
99
  requestId: z.string().describe('The request id.'),
92
100
  payload: z.record(z.any()).optional().describe('Test payload for _payload operators.'),
93
101
  user: userSchema,
102
+ saveResponse: saveResponseSchema,
94
103
  },
95
104
  },
96
105
 
@@ -107,6 +116,7 @@ const devToolDefinitions = {
107
116
  .describe(
108
117
  'Run as a system context (like /api/cron and /api/detached): no user, auth not checked, InternalApi allowed. Cannot be combined with user.'
109
118
  ),
119
+ saveResponse: saveResponseSchema,
110
120
  },
111
121
  },
112
122
 
@@ -177,13 +187,13 @@ const devToolDefinitions = {
177
187
 
178
188
  lowdefy_build_status: {
179
189
  description:
180
- 'Call after every config edit. Returns the current build status: errors and warnings from the last build (with source file locations), recent browser runtime errors, and recent server errors — request, endpoint, MCP and agent tool failures with their config source. The dev server rebuilds automatically on file change — edit, then call this with wait: true to see what broke.',
190
+ 'Call after every config edit. Returns the current build status: errors and warnings from the last config build (with source file locations), the page builds (pages: failed lists the pages whose last build failed with their errors, changedSinceBuild the pages changed since they were built, unbuilt how many pages nothing has built since the dev server started), recent browser runtime errors, and recent server errors — request, endpoint, MCP and agent tool failures with their config source. Errors reported under an earlier build come apart under earlierErrors. The dev server rebuilds automatically on file change — edit, then call this with wait: true to see what broke.',
181
191
  inputSchema: {
182
192
  wait: z
183
193
  .boolean()
184
194
  .optional()
185
195
  .describe(
186
- 'Wait until the dev server has processed your latest edits (the rebuild or page invalidation they trigger) before answering, instead of returning the status of the build before them. Use it right after an edit. Waits up to a minute; `settled: false` in the result means it gave up.'
196
+ 'Wait until the dev server has processed your latest edits (the rebuild or page invalidation they trigger), then build every page they touched, before answering, instead of returning the status of the build before them. pages.checked lists the pages it built. Use it right after an edit. Waits up to a minute; `settled: false` in the result means it gave up.'
187
197
  ),
188
198
  },
189
199
  },
@@ -219,7 +229,7 @@ const devToolDefinitions = {
219
229
 
220
230
  lowdefy_screenshot_page: {
221
231
  description:
222
- 'Screenshot a page of the running dev server (headless Chromium) to visually verify layout and rendering. Returns a PNG image.',
232
+ 'Screenshot a page of the running dev server (headless Chromium) to visually verify layout and rendering. Returns a PNG image. Set width (and height) to check a narrow or phone layout, e.g. width 390, and colorScheme "dark" to check dark mode.',
223
233
  inputSchema: {
224
234
  pageId: z.string().describe('The page id to screenshot.'),
225
235
  fullPage: z.boolean().optional().describe('Capture the full scrollable page.'),
@@ -236,25 +246,49 @@ const devToolDefinitions = {
236
246
  ),
237
247
  scrollX: z.number().optional().describe('Scroll offset the clip was recorded at.'),
238
248
  scrollY: z.number().optional().describe('Scroll offset the clip was recorded at.'),
249
+ width: z
250
+ .number()
251
+ .int()
252
+ .positive()
253
+ .optional()
254
+ .describe('Viewport width in CSS pixels. Default 1280; 390 is a phone.'),
255
+ height: z
256
+ .number()
257
+ .int()
258
+ .positive()
259
+ .optional()
260
+ .describe('Viewport height in CSS pixels. Default 800.'),
261
+ colorScheme: z
262
+ .enum(['light', 'dark'])
263
+ .optional()
264
+ .describe(
265
+ 'The colour scheme the page\'s prefers-color-scheme reports. Default "light". An app that follows the system theme renders dark with "dark"; a darkMode fixed in the app config wins.'
266
+ ),
239
267
  user: userSchema,
240
268
  },
241
269
  },
242
270
 
243
271
  lowdefy_run_journey: {
244
272
  description:
245
- 'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId; a target object narrows to a grid row/cell ({"blockId": "grid", "row": 1, "column": "actions"}), to the control with exactly some text ({"blockId": "grid", "row": 1, "text": "Edit"}), or reaches portal-rendered controls page-wide by text alone ({"text": "OK"} for a confirm dialog or modal footer button, a menu item). A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. Always returns the final page state and any screenshots taken (as images after the JSON text).',
273
+ 'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId; a target object narrows to a grid row/cell ({"blockId": "grid", "row": 1, "column": "actions"}), to the control with exactly some text ({"blockId": "grid", "row": 1, "text": "Edit"}), or reaches portal-rendered controls page-wide by text alone ({"text": "OK"} for a confirm dialog or modal footer button, a menu item). A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. Returns the final page state (whole when small, otherwise stateOmitted with its size and top-level keys; see the state param) and any screenshots taken (as images after the JSON text).',
246
274
  inputSchema: {
247
275
  pageId: z.string().describe('The page id to open.'),
248
276
  steps: z
249
277
  .array(z.record(z.any()))
250
278
  .describe(
251
- 'Ordered steps, one key each: {"click": target} | {"fill": {...target, "value"}} | {"select": {...target, "value"}} (option by exact text) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"wait": {"ms": n} | {"request": requestId} | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": target} | {"text": {...target, "contains"}} | {"url": {"contains"}}}. A target is a blockId string, or an object of {"blockId", "row" (zero-based grid row as displayed), "column" (grid col-id), "text" (exact text of the interactive control to use), "nth" (zero-based pick among several matches)}; "text" without "blockId" searches the whole page, which is how confirm dialog / modal footer buttons and dropdown menu items are reached. fill, select and expect.text need a blockId. Each step gets 5s; after an interaction the runner waits for the page\'s pending events and requests to settle.'
279
+ 'Ordered steps, one key each: {"click": target} | {"fill": {...target, "value"}} | {"select": {...target, "value"}} (option by exact text: a dropdown option, or a radio, button or segmented option in the block) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"back": true} (the browser Back button) | {"wait": {"ms": n} | {"request": requestId} | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": target} | {"text": {...target, "contains"}} | {"url": {"contains"}} | {"title": {"equals"} | {"contains"}}} (title is the document title). A target is a blockId string, or an object of {"blockId", "row" (zero-based grid row as displayed), "column" (grid col-id), "text" (exact text of the interactive control to use), "nth" (zero-based pick among several matches)}; "text" without "blockId" searches the whole page, which is how confirm dialog / modal footer buttons and dropdown menu items are reached. fill, select and expect.text need a blockId. Each step gets 5s; after an interaction the runner waits for the page\'s pending events and requests to settle.'
252
280
  ),
253
281
  user: userSchema,
254
282
  urlQuery: z
255
283
  .record(z.any())
256
284
  .optional()
257
285
  .describe('Query params to open the page with, read by _url_query, e.g. {"id": "1"}.'),
286
+ state: z
287
+ .union([z.boolean(), z.array(z.string().min(1))])
288
+ .optional()
289
+ .describe(
290
+ 'What the result carries of the final page state. Omitted: the whole state when it is at most 10000 characters of JSON, otherwise stateOmitted (its size and each top-level key with its size). An array of state paths, e.g. ["form.name", "rows"]: state is {path: value} for each, null where undefined. true: the whole state, however large. false: no state.'
291
+ ),
258
292
  },
259
293
  },
260
294
 
@@ -244,8 +244,15 @@ test('getBuildStatus returns the build artifact plus reported client and server
244
244
  expect(result.build.status).toEqual('ok');
245
245
  expect(result.clientErrors.length).toEqual(50);
246
246
  expect(result.serverErrors).toEqual([
247
- { name: 'RequestError', message: 'Bad filter.', source: 'pages/a.yaml:3' },
247
+ {
248
+ name: 'RequestError',
249
+ message: 'Bad filter.',
250
+ source: 'pages/a.yaml:3',
251
+ buildId: '2026-01-01T00:00:00.000Z',
252
+ },
248
253
  ]);
254
+ expect(result.earlierErrors).toBeUndefined();
255
+ expect(result.pages.unbuilt).toEqual(expect.any(Number));
249
256
  });
250
257
 
251
258
  test('getBuildStatus reports unknown status when buildStatus.json is missing', () => {
@@ -472,17 +479,56 @@ test('runRequest returns a structured error instead of throwing when callRequest
472
479
  expect(result.error).toEqual({ name: 'Error', message: 'boom' });
473
480
  });
474
481
 
475
- test('runRequest truncates responses larger than the size cap', async () => {
482
+ test('runRequest writes a response larger than the inline limit to a file', async () => {
483
+ const rows = Array.from({ length: 500 }, (_, index) => ({ _id: index, title: 'x'.repeat(100) }));
476
484
  mockCallRequest.mockResolvedValueOnce({
477
485
  id: 'req-read',
478
486
  success: true,
479
487
  type: 'ReadOnlyRequest',
480
- response: 'x'.repeat(200_000),
488
+ response: rows,
481
489
  });
482
490
  const result = await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
483
- expect(result.truncated).toBe(true);
484
- expect(result.note).toContain('truncated');
485
- expect(result.response.length).toEqual(100_000);
491
+ expect(result.response).toBeUndefined();
492
+ expect(result.responseItems).toEqual(500);
493
+ expect(path.dirname(result.responseFile)).toEqual(
494
+ path.join(fs.realpathSync(fixtureDir), '.lowdefy', 'responses')
495
+ );
496
+ expect(path.basename(result.responseFile).startsWith('home.req-read-')).toBe(true);
497
+ expect(JSON.parse(fs.readFileSync(result.responseFile, 'utf8'))).toEqual(rows);
498
+ });
499
+
500
+ test('runRequest builds the page before it reads the request', async () => {
501
+ mockBuildPageIfNeeded.mockClear();
502
+ mockCallRequest.mockClear();
503
+ await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
504
+ expect(mockBuildPageIfNeeded).toHaveBeenCalledWith(expect.objectContaining({ pageId: 'home' }));
505
+ expect(mockBuildPageIfNeeded.mock.invocationCallOrder[0]).toBeLessThan(
506
+ mockCallRequest.mock.invocationCallOrder[0]
507
+ );
508
+ });
509
+
510
+ test('runRequest refuses with the build errors when the page fails to build', async () => {
511
+ const error = new Error('Page "home" build failed with 1 error(s).');
512
+ error.buildErrors = [
513
+ {
514
+ name: 'ConfigError',
515
+ message: 'Block type "Buton" was used but is not defined.',
516
+ source: 'pages/home.yaml:4',
517
+ },
518
+ ];
519
+ mockBuildPageIfNeeded.mockRejectedValueOnce(error);
520
+ mockCallRequest.mockClear();
521
+ const result = await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
522
+ expect(result.refused).toBe(true);
523
+ expect(result.reason).toContain('fails to build');
524
+ expect(result.buildErrors).toEqual([
525
+ {
526
+ type: 'ConfigError',
527
+ message: 'Block type "Buton" was used but is not defined.',
528
+ source: 'pages/home.yaml:4',
529
+ },
530
+ ]);
531
+ expect(mockCallRequest).not.toHaveBeenCalled();
486
532
  });
487
533
 
488
534
  test('getAppMap includes built page detail and a note for unbuilt pages', () => {
@@ -0,0 +1,81 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ import crypto from 'node:crypto';
18
+ import fs from 'node:fs';
19
+ import path from 'node:path';
20
+
21
+ // Largest response returned inline, in serialized characters. The tool result
22
+ // is pretty-printed, which adds roughly half again, so this keeps a result
23
+ // inside the output budget of common MCP clients.
24
+ const MAX_INLINE_RESPONSE_CHARS = 40_000;
25
+
26
+ // Saved responses kept per app; the oldest beyond this are deleted on write.
27
+ const MAX_SAVED_RESPONSES = 20;
28
+
29
+ function pruneResponseFiles({ directory }) {
30
+ const files = fs
31
+ .readdirSync(directory)
32
+ .filter((fileName) => fileName.endsWith('.json'))
33
+ .map((fileName) => {
34
+ const filePath = path.join(directory, fileName);
35
+ return { filePath, mtime: fs.statSync(filePath).mtimeMs };
36
+ })
37
+ .sort((a, b) => b.mtime - a.mtime);
38
+ files.slice(MAX_SAVED_RESPONSES).forEach(({ filePath }) => fs.rmSync(filePath, { force: true }));
39
+ }
40
+
41
+ function writeResponseFile({ name, response }) {
42
+ const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
43
+ const directory = path.join(configDirectory, '.lowdefy', 'responses');
44
+ const safeName = name.replace(/[^a-zA-Z0-9_.-]/g, '_');
45
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');
46
+ const suffix = crypto.randomBytes(3).toString('hex');
47
+ const filePath = path.join(directory, `${safeName}-${stamp}-${suffix}.json`);
48
+ fs.mkdirSync(directory, { recursive: true });
49
+ fs.writeFileSync(filePath, JSON.stringify(response, null, 2));
50
+ pruneResponseFiles({ directory });
51
+ return filePath;
52
+ }
53
+
54
+ // Returns the result untouched when its response fits inline. A larger
55
+ // response, or any response when saveResponse is set, is written in full to
56
+ // .lowdefy/responses/ in the config directory, and the result carries the
57
+ // file's path and size in its place, so nothing is cut and an agent can read
58
+ // or query the whole value.
59
+ function fitResponse({ result, name, saveResponse = false }) {
60
+ // A request can resolve with no response; it is written as null.
61
+ const { response = null, ...rest } = result;
62
+ const json = JSON.stringify(response);
63
+ if (!saveResponse && json.length <= MAX_INLINE_RESPONSE_CHARS) {
64
+ return result;
65
+ }
66
+ const fitted = {
67
+ ...rest,
68
+ responseFile: writeResponseFile({ name, response }),
69
+ responseChars: json.length,
70
+ };
71
+ if (Array.isArray(response)) {
72
+ fitted.responseItems = response.length;
73
+ }
74
+ fitted.note = saveResponse
75
+ ? 'The full response was written to responseFile.'
76
+ : `The response is ${json.length} characters, over the ${MAX_INLINE_RESPONSE_CHARS} returned inline, so it was written in full to responseFile. Read or query that file instead.`;
77
+ return fitted;
78
+ }
79
+
80
+ export { MAX_INLINE_RESPONSE_CHARS, MAX_SAVED_RESPONSES };
81
+ export default fitResponse;