@lowdefy/server-dev 6.1.0 → 7.1.0

package/src/routes/docs/events.test.mjs

@@ -0,0 +1,117 @@
+/*
+  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 { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const mockSubscribe = jest.fn();
+const mockUnsubscribe = jest.fn();
+jest.unstable_mockModule('../../../lib/docs/devEventBus.js', () => ({
+  bootedAt: '2026-05-06T07:08:09.000Z',
+  subscribe: mockSubscribe,
+}));
+
+const { default: docsEventsHandler } = await import('./events.js');
+
+function createApp() {
+  const app = new Hono();
+  app.get('/lowdefy-docs/events', docsEventsHandler);
+  return app;
+}
+
+// Reads SSE frames off the response body one at a time.
+function createFrameReader(response) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  const nextFrame = async function nextFrame() {
+    while (!buffer.includes('\n\n')) {
+      const { value, done } = await reader.read();
+      if (done) throw new Error('Stream closed before a full frame arrived.');
+      buffer += decoder.decode(value, { stream: true });
+    }
+    const end = buffer.indexOf('\n\n');
+    const frame = buffer.slice(0, end);
+    buffer = buffer.slice(end + 2);
+    const lines = frame.split('\n');
+    return {
+      event: lines
+        .find((line) => line.startsWith('event:'))
+        ?.slice('event:'.length)
+        .trim(),
+      data: lines
+        .find((line) => line.startsWith('data:'))
+        ?.slice('data:'.length)
+        .trim(),
+    };
+  };
+  // Cancelling the body is what a dropped connection does to the stream.
+  nextFrame.close = () => reader.cancel();
+  return nextFrame;
+}
+
+beforeEach(() => {
+  mockSubscribe.mockReturnValue(mockUnsubscribe);
+});
+
+test('GET /lowdefy-docs/events opens an SSE stream whose first frame is the restart event', async () => {
+  const res = await createApp().request('/lowdefy-docs/events');
+
+  expect(res.status).toBe(200);
+  expect(res.headers.get('content-type')).toContain('text/event-stream');
+
+  const nextFrame = createFrameReader(res);
+  const frame = await nextFrame();
+  expect(frame.event).toBe('restart');
+  const data = JSON.parse(frame.data);
+  expect(data).toMatchObject({ type: 'restart', bootedAt: '2026-05-06T07:08:09.000Z' });
+  expect(new Date(data.timestamp).toISOString()).toEqual(data.timestamp);
+  await nextFrame.close();
+});
+
+test('a published event is written as an SSE frame named by its type', async () => {
+  const res = await createApp().request('/lowdefy-docs/events');
+  const nextFrame = createFrameReader(res);
+  await nextFrame();
+
+  expect(mockSubscribe).toHaveBeenCalledTimes(1);
+  const [send] = mockSubscribe.mock.calls[0];
+  const event = {
+    type: 'build',
+    timestamp: '2026-05-06T07:10:00.000Z',
+    status: 'error',
+    errorCount: 1,
+    stale: true,
+  };
+  await send(event);
+
+  const frame = await nextFrame();
+  expect(frame.event).toBe('build');
+  expect(JSON.parse(frame.data)).toEqual(event);
+  await nextFrame.close();
+});
+
+test('a dropped connection unsubscribes from the bus', async () => {
+  const res = await createApp().request('/lowdefy-docs/events');
+  const nextFrame = createFrameReader(res);
+  await nextFrame();
+  expect(mockSubscribe).toHaveBeenCalledTimes(1);
+  expect(mockUnsubscribe).not.toHaveBeenCalled();
+
+  await nextFrame.close();
+
+  expect(mockUnsubscribe).toHaveBeenCalledTimes(1);
+});

package/src/routes/docs/find.js

@@ -14,8 +14,13 @@
   limitations under the License.
 */
 
+import { ConfigError } from '@lowdefy/errors';
+
 import findConfig from '../../../lib/docs/findConfig.js';
 
+// findConfig throws a ConfigError only for a missing or non-string id; every
+// other failure is a fault and propagates to the error handler rather than
+// being reported to the caller as bad input.
 async function docsFindHandler(c) {
   const id = c.req.param('id');
   const pageId = c.req.query('pageId');
@@ -23,7 +28,10 @@ async function docsFindHandler(c) {
     const result = await findConfig({ id, pageId });
     return c.json(result);
   } catch (error) {
-    return c.json({ error: error.message }, 400);
+    if (error instanceof ConfigError) {
+      return c.json({ error: error.message }, 400);
+    }
+    throw error;
   }
 }
 

package/src/routes/docs/icons.js

@@ -0,0 +1,30 @@
+/*
+  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 searchIcons from '../../../lib/docs/searchIcons.js';
+
+async function docsIconsHandler(c) {
+  const query = c.req.query('q');
+  if (!query || query.trim() === '') {
+    return c.json(
+      { error: 'Missing search query. Use GET /lowdefy-docs/icons?q=your+keywords.' },
+      400
+    );
+  }
+  return c.json(await searchIcons({ query }));
+}
+
+export default docsIconsHandler;

package/src/routes/docs/inspectState.js

@@ -15,6 +15,7 @@
 */
 
 import inspectState from '../../../lib/docs/inspectState.js';
+import parsePathParamsParam from './parsePathParamsParam.js';
 import parseUserParam from './parseUserParam.js';
 
 async function docsInspectStateHandler(c) {
@@ -30,7 +31,21 @@ async function docsInspectStateHandler(c) {
     return c.json({ error: userError }, 400);
   }
 
-  const result = await inspectState({ origin, pageId, source, user });
+  const { pathParams, error: pathParamsError } = parsePathParamsParam({
+    value: c.req.query('pathParams'),
+  });
+  if (pathParamsError) {
+    return c.json({ error: pathParamsError }, 400);
+  }
+
+  const result = await inspectState({
+    origin,
+    pageId,
+    pathParams,
+    source,
+    user,
+    data: c.req.query('data'),
+  });
   if (result.error) {
     // A contradictory call (`user` with `source=tab`) is the caller's mistake,
     // not a failed render — 502 would read as "the renderer broke" and invite a

package/src/routes/docs/journey.js

@@ -0,0 +1,194 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { validateJourneySteps } from '@lowdefy/node-utils';
+
+import getBuildId from '../../../lib/docs/getBuildId.js';
+import lowdefyConfig from '../../../lib/build/config.js';
+import { openMutantRun } from '../../../lib/server/mutants/mutantRuns.js';
+import parseUserParam from './parseUserParam.js';
+import runJourney from '../../../lib/docs/runJourney.js';
+import validateJourneyTimeout from '../../../lib/docs/validateJourneyTimeout.js';
+import validateMutantParam from '../../../lib/server/mutants/validateMutantParam.js';
+import validateRecordingParam from '../../../lib/docs/validateRecordingParam.js';
+import validateStateSelection from '../../../lib/docs/validateStateSelection.js';
+
+// A failed journey is a 200 with passed: false — it is the result the caller
+// asked for. Malformed input (pageId, pathParams, steps, user, data) is a 400 before any browser
+// opens; only a render that could not run at all is a 502, so it is not
+// mistaken for a journey that failed on an assertion.
+async function docsJourneyHandler(c) {
+  const body = await c.req.json().catch(() => ({}));
+  const { pageId, pathParams, steps, urlQuery, state, timeout } = body;
+  if (type.isNone(pageId) || !type.isString(pageId)) {
+    return c.json(
+      {
+        error: `POST /lowdefy-docs/journey requires a "pageId" string in the JSON body, e.g. {"pageId": "home", "steps": [{"click": "submit"}]}. Received ${JSON.stringify(
+          pageId
+        )}.`,
+      },
+      400
+    );
+  }
+  const { error: stepsError } = validateJourneySteps({ steps });
+  if (stepsError) {
+    return c.json({ error: stepsError }, 400);
+  }
+  if (
+    !type.isNone(pathParams) &&
+    (!type.isObject(pathParams) || !Object.values(pathParams).every(type.isString))
+  ) {
+    return c.json(
+      {
+        error: `The "pathParams" param must be an object of strings, one per path placeholder. Received ${JSON.stringify(
+          pathParams
+        )}.`,
+      },
+      400
+    );
+  }
+  if (!type.isNone(urlQuery) && !type.isObject(urlQuery)) {
+    return c.json(
+      { error: `The "urlQuery" param must be an object. Received ${JSON.stringify(urlQuery)}.` },
+      400
+    );
+  }
+  const stateSelectionError = validateStateSelection({ state });
+  if (stateSelectionError) {
+    return c.json({ error: stateSelectionError }, 400);
+  }
+  const timeoutError = validateJourneyTimeout({ timeout });
+  if (timeoutError) {
+    return c.json({ error: timeoutError }, 400);
+  }
+  if (!type.isNone(body.data) && !type.isString(body.data)) {
+    return c.json(
+      {
+        error: `The "data" param must be a data set name string. Received ${JSON.stringify(
+          body.data
+        )}.`,
+      },
+      400
+    );
+  }
+  // One POST is one run. A journey with a list of users runs once per user:
+  // lowdefy test and lowdefy_run_journey expand the list, posting or running
+  // each user on its own.
+  if (type.isArray(body.user)) {
+    return c.json(
+      {
+        error: `POST /lowdefy-docs/journey runs one user. For a list of data set users, post once per user, or use lowdefy test or lowdefy_run_journey, which run the journey once as each. Received ${JSON.stringify(
+          body.user
+        )}.`,
+      },
+      400
+    );
+  }
+  // A string is a journey's own: `none` injects no caller, so the app's auth
+  // decides who the journey is, and any other string names a user of the
+  // journey's data set (runJourney looks it up). An object is a headless caller.
+  const { user, error: userError } = type.isString(body.user)
+    ? { user: body.user }
+    : parseUserParam({ value: body.user });
+  if (userError) {
+    return c.json({ error: userError }, 400);
+  }
+  const recordingError = validateRecordingParam(body.recording);
+  if (recordingError) {
+    return c.json({ error: recordingError }, 400);
+  }
+  if (!type.isNone(body.mutant)) {
+    const mutantError = validateMutantParam(body.mutant);
+    if (mutantError) {
+      return c.json({ error: mutantError }, 400);
+    }
+    // A mutant's key names a node only within the build it was listed
+    // against; against any other build it would mutate the wrong node.
+    if (body.mutant.buildId !== getBuildId()) {
+      return c.json(
+        {
+          error:
+            'The mutant was listed against another build. List the mutants again (POST /lowdefy-docs/mutants) and run the new one.',
+          stale: true,
+        },
+        409
+      );
+    }
+  }
+  // Derived from the incoming request rather than a config value — this is
+  // the origin an agent can actually reach the dev server on (host/port it
+  // just connected to), regardless of how the server is bound.
+  const origin = new URL(c.req.url).origin;
+
+  const mutantRun = type.isNone(body.mutant)
+    ? null
+    : openMutantRun({
+        mutant: {
+          buildId: body.mutant.buildId,
+          artifact: body.mutant.artifact,
+          key: body.mutant.key,
+          ...(type.isNone(body.mutant.pointer)
+            ? {}
+            : { pointer: body.mutant.pointer, nodeHash: body.mutant.nodeHash ?? null }),
+          arg: body.mutant.arg ?? null,
+          operator: body.mutant.operator,
+        },
+      });
+  let result;
+  try {
+    result = await runJourney({
+      origin,
+      pageId,
+      pathParams,
+      steps,
+      user,
+      urlQuery,
+      state,
+      stepTimeout: timeout,
+      basePath: lowdefyConfig.basePath ?? '',
+      mutantCookie: mutantRun?.cookiePayload,
+      data: body.data,
+      by: 'test',
+      // Journeys posted here come from `lowdefy test` and lowdefy_run_tests.
+      recording: type.isNone(body.recording)
+        ? undefined
+        : {
+            source: 'journey',
+            run: { id: body.recording.run, by: 'test', journey: body.recording.journey ?? null },
+          },
+    });
+  } finally {
+    // runJourney has closed every actor by now, so no request still carries
+    // the run's cookie.
+    mutantRun?.close();
+  }
+  // A journey refused before any browser opened (its data set, or who it acts
+  // as on one) is the caller's to fix: a 400, like the checks above.
+  if (result.refused === true) {
+    return c.json({ error: result.error }, 400);
+  }
+  if (result.error) {
+    return c.json({ error: result.error }, 502);
+  }
+  if (mutantRun !== null) {
+    const { id, applied, misses } = mutantRun.run;
+    return c.json({ ...result, mutant: { id, applied, misses } });
+  }
+  return c.json(result);
+}
+
+export default docsJourneyHandler;