@lowdefy/server-dev 0.0.0-experimental-20260925210809 → 0.0.0-experimental-20260926150052
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.
- package/lib/docs/buildEditedPages.js +50 -0
- package/lib/docs/clientErrorStore.js +5 -2
- package/lib/docs/clientErrorStore.test.mjs +7 -3
- package/lib/docs/createDocsMcpServer.js +18 -9
- package/lib/docs/createDocsMcpServer.test.mjs +28 -0
- package/lib/docs/devToolDefinitions.js +43 -9
- package/lib/docs/docs.test.mjs +52 -6
- package/lib/docs/fitResponse.js +81 -0
- package/lib/docs/fitResponse.test.mjs +128 -0
- package/lib/docs/getBrowser.js +4 -1
- package/lib/docs/getBrowser.test.mjs +29 -0
- package/lib/docs/getBuildId.js +61 -0
- package/lib/docs/getBuildId.test.mjs +84 -0
- package/lib/docs/getBuildStatus.js +34 -8
- package/lib/docs/getBuildStatus.test.mjs +66 -0
- package/lib/docs/getBuildStatusAfterEdits.js +33 -0
- package/lib/docs/getBuildStatusAfterEdits.test.mjs +58 -0
- package/lib/docs/getOverview.js +7 -7
- package/lib/docs/getPageBuildStatus.js +46 -0
- package/lib/docs/pageBuildStatus.test.mjs +103 -0
- package/lib/docs/reviewPage.js +63 -0
- package/lib/docs/reviewPageBuilds.js +46 -0
- package/lib/docs/reviewPageBuilds.test.mjs +153 -0
- package/lib/docs/runCheckChild.js +4 -2
- package/lib/docs/runEndpoint.js +16 -3
- package/lib/docs/runEndpoint.test.mjs +61 -9
- package/lib/docs/runJourney.js +102 -11
- package/lib/docs/runJourney.test.mjs +231 -4
- package/lib/docs/runRequest.js +56 -22
- package/lib/docs/runRequest.test.mjs +58 -0
- package/lib/docs/screenshotPage.js +17 -2
- package/lib/docs/screenshotPage.test.mjs +16 -0
- package/lib/docs/selectFinalState.js +66 -0
- package/lib/docs/selectFinalState.test.mjs +51 -0
- package/lib/docs/serverErrorStore.js +5 -2
- package/lib/docs/serverErrorStore.test.mjs +9 -4
- package/lib/docs/validateJourneySteps.js +17 -3
- package/lib/docs/validateJourneySteps.test.mjs +17 -4
- package/lib/docs/validateStateSelection.js +33 -0
- package/lib/docs/validateStateSelection.test.mjs +33 -0
- package/lib/docs/validateViewport.js +46 -0
- package/lib/docs/validateViewport.test.mjs +33 -0
- package/lib/server/jitPageBuilder.js +5 -2
- package/lib/server/pageBuildRecords.js +82 -0
- package/lib/server/pageBuildRecords.test.mjs +157 -0
- package/manager/getContext.mjs +1 -0
- package/manager/processes/lowdefyBuild.mjs +21 -7
- package/manager/processes/lowdefyBuild.test.mjs +94 -1
- package/manager/processes/startWatchers.mjs +0 -2
- package/manager/utils/createCustomPluginMessagesMap.mjs +20 -15
- package/manager/utils/createCustomPluginTypesMap.mjs +19 -11
- package/manager/utils/createCustomPluginTypesMap.test.mjs +89 -0
- package/manager/utils/createDotPathIgnore.mjs +44 -0
- package/manager/utils/createDotPathIgnore.test.mjs +52 -0
- package/manager/utils/findBuildFilesOutsideWatch.mjs +41 -0
- package/manager/utils/findBuildFilesOutsideWatch.test.mjs +77 -0
- package/manager/utils/importFresh.mjs +46 -0
- package/manager/utils/importFresh.test.mjs +72 -0
- package/manager/utils/importFreshWorker.mjs +20 -0
- package/manager/utils/publishBuildDirectory.mjs +72 -0
- package/manager/utils/publishBuildDirectory.test.mjs +170 -0
- package/manager/utils/setupWatcher.mjs +2 -8
- package/manager/utils/writeBuildStatus.mjs +1 -1
- package/manager/watchers/lowdefyBuildWatcher.mjs +62 -16
- package/manager/watchers/lowdefyBuildWatcher.test.mjs +160 -0
- package/manager/watchers/restartRequestWatcher.mjs +9 -1
- package/manager/watchers/restartRequestWatcher.test.mjs +25 -0
- package/package.json +37 -37
- package/package.original.json +37 -37
- package/src/middleware/errorHandler.js +13 -0
- package/src/middleware/errorHandler.test.mjs +51 -0
- package/src/routes/docs/buildStatus.js +4 -3
- package/src/routes/docs/journey.js +7 -2
- package/src/routes/docs/journey.test.mjs +21 -1
- package/src/routes/docs/runEndpoint.js +2 -1
- package/src/routes/docs/runRequest.js +2 -1
- package/src/routes/docs/screenshot.js +37 -1
- package/src/routes/docs/screenshot.test.mjs +117 -0
- package/src/routes/mcp.test.mjs +16 -0
- package/src/routes/request.js +1 -1
- package/src/routes/websocket.js +9 -8
- package/src/websocket/devWebSocket.js +36 -26
- package/src/websocket/devWebSocket.test.mjs +124 -0
- package/vite.config.js +17 -11
- package/lib/docs/truncateResponse.js +0 -39
- package/lib/docs/truncateResponse.test.mjs +0 -49
- 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
|
-
|
|
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', ...
|
|
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([
|
|
30
|
-
expect(mockPublish).toHaveBeenCalledWith({ type: 'client_error', ...
|
|
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(
|
|
144
|
-
|
|
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(
|
|
148
|
-
|
|
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(
|
|
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
|
|
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.
|
|
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
|
|
package/lib/docs/docs.test.mjs
CHANGED
|
@@ -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
|
-
{
|
|
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
|
|
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:
|
|
488
|
+
response: rows,
|
|
481
489
|
});
|
|
482
490
|
const result = await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
|
|
483
|
-
expect(result.
|
|
484
|
-
expect(result.
|
|
485
|
-
expect(result.
|
|
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;
|