@lowdefy/server-dev 6.0.0 → 7.0.0

package/src/routes/docs/mutants.js

@@ -0,0 +1,78 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import path from 'node:path';
+
+import buildPageIfNeeded from '../../../lib/server/jitPageBuilder.js';
+import getBuildId from '../../../lib/docs/getBuildId.js';
+import listMutants from '../../../lib/server/mutants/listMutants.js';
+import mapPageBuildErrors from '../../../lib/docs/mapPageBuildErrors.js';
+import readBuildArtifact from '../../../lib/docs/readBuildArtifact.js';
+import readMergedMaps from '../../../lib/server/readMergedMaps.js';
+import validateMutantsBody from '../../../lib/server/mutants/validateMutantsBody.js';
+
+// Lists every config mutant on the artifacts a set of journey runs exercised
+// (`lowdefy journeys harden`, step 3). Pages are built first, as the page
+// route builds them, so the artifacts read are the current config's. Reads
+// are never made through a mutant cookie: this route answers for the
+// unmutated build. A page that fails to build is a 422 with its errors.
+async function docsMutantsHandler(c) {
+  const parsed = validateMutantsBody(await c.req.json().catch(() => null));
+  if (parsed.error) {
+    return c.json({ error: parsed.error }, 400);
+  }
+  const { body } = parsed;
+  // Read before the pages build: an edit that lands while they build then
+  // gives the answer an older build id than the keys it lists, so the journey
+  // route refuses its mutants as stale instead of running them.
+  const buildId = getBuildId();
+  const buildDirectory = path.join(process.cwd(), 'build');
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const pageIds = [...new Set([...body.pages, ...body.requests.map((request) => request.pageId)])];
+  // A page no longer in the app lists no mutants, even while an older build
+  // of it is still on disk: a harden run asks after the pages an earlier run
+  // listed, to drop the mutants that are gone.
+  const removedPages = new Set();
+  for (const pageId of pageIds) {
+    try {
+      const built = await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+      if (built === false) {
+        removedPages.add(pageId);
+      }
+    } catch (error) {
+      return c.json(
+        {
+          error: `Page "${pageId}" fails to build, so its mutants cannot be listed until the errors are fixed.`,
+          buildErrors: mapPageBuildErrors(error),
+        },
+        422
+      );
+    }
+  }
+  // Page builds write their keys to jitMaps/, not keyMap.json.
+  const { keyMap, refMap } = await readMergedMaps({ buildDirectory });
+  const result = await listMutants({
+    ...body,
+    pages: body.pages.filter((pageId) => !removedPages.has(pageId)),
+    requests: body.requests.filter(({ pageId }) => !removedPages.has(pageId)),
+    readConfigFile: async (name) => readBuildArtifact({ name, deserialize: true }),
+    keyMap,
+    refMap,
+  });
+  return c.json({ buildId, ...result });
+}
+
+export default docsMutantsHandler;

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

@@ -0,0 +1,180 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { jest } from '@jest/globals';
+import { Hono } from 'hono';
+import { serializer } from '@lowdefy/helpers';
+
+import { endpointFixture, pageFixture } from '../../../lib/server/mutants/test/fixtures.mjs';
+
+const mockBuildPageIfNeeded = jest.fn();
+jest.unstable_mockModule('../../../lib/server/jitPageBuilder.js', () => ({
+  default: mockBuildPageIfNeeded,
+}));
+
+const { default: docsMutantsHandler } = await import('./mutants.js');
+
+const originalCwd = process.cwd();
+let serverDirectory;
+
+function write(name, content) {
+  const filePath = path.join(serverDirectory, 'build', name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, typeof content === 'string' ? content : JSON.stringify(content));
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockBuildPageIfNeeded.mockResolvedValue(true);
+  serverDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-mutants-route-'));
+  const page = pageFixture();
+  const endpoint = endpointFixture();
+  write('pages/tickets.json', serializer.serializeToString(page.root));
+  write('api/notify.json', serializer.serializeToString(endpoint.root));
+  write('keyMap.json', { ...page.keyMap });
+  write('refMap.json', {});
+  write('buildStatus.json', { status: 'ok', timestamp: '2026-10-03T08:00:00.000Z' });
+  process.chdir(serverDirectory);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(serverDirectory, { recursive: true, force: true });
+});
+
+async function post(body) {
+  const app = new Hono();
+  app.post('/lowdefy-docs/mutants', docsMutantsHandler);
+  const response = await app.request('/lowdefy-docs/mutants', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: response.status, data: await response.json() };
+}
+
+test('POST /lowdefy-docs/mutants lists the mutants of the posted pages and endpoints with the build id and artifact hashes', async () => {
+  const { status, data } = await post({ pages: ['tickets'], endpoints: ['notify'] });
+  expect(status).toBe(200);
+  expect(mockBuildPageIfNeeded).toHaveBeenCalledWith(
+    expect.objectContaining({ pageId: 'tickets' })
+  );
+  expect(data.buildId).toEqual(expect.any(String));
+  expect(Object.keys(data.artifacts)).toEqual(['pages/tickets.json', 'api/notify.json']);
+  expect(data.artifacts['pages/tickets.json']).toMatch(/^[0-9a-f]{40}$/);
+  const operators = new Set(data.mutants.map((mutant) => mutant.operator));
+  expect(operators).toEqual(
+    new Set([
+      'drop-action',
+      'skip-validate',
+      'flip-visible',
+      'swap-if',
+      'drop-payload',
+      'retarget-link',
+      'drop-block',
+      'drop-step',
+    ])
+  );
+  const dropStep = data.mutants.find((mutant) => mutant.operator === 'drop-step');
+  expect(dropStep).toMatchObject({
+    artifact: 'api/notify.json',
+    anchor: { type: 'endpoint', endpointId: 'notify' },
+    copies: [],
+    copyTargets: [],
+  });
+});
+
+test('POST /lowdefy-docs/mutants resolves config paths from the keys a page build wrote to jitMaps', async () => {
+  const page = pageFixture();
+  write('keyMap.json', {});
+  write('jitMaps/1-1-1.json', { keyMap: { ...page.keyMap }, refMap: {} });
+  const { status, data } = await post({ pages: ['tickets'] });
+  expect(status).toBe(200);
+  expect(data.mutants.length).toBeGreaterThan(0);
+  data.mutants.forEach((mutant) => {
+    expect(mutant.config).toEqual(expect.any(String));
+  });
+});
+
+test('POST /lowdefy-docs/mutants keeps only the operators asked for', async () => {
+  const { data } = await post({ pages: ['tickets'], operators: ['drop-block'] });
+  expect(new Set(data.mutants.map((mutant) => mutant.operator))).toEqual(new Set(['drop-block']));
+});
+
+test('POST /lowdefy-docs/mutants builds the page of every posted request', async () => {
+  await post({ requests: [{ pageId: 'tickets', requestId: 'assign_ticket' }] });
+  expect(mockBuildPageIfNeeded.mock.calls.map(([args]) => args.pageId)).toEqual(['tickets']);
+});
+
+test.each([
+  [{ pages: 'tickets' }, '"pages" must be an array of page ids'],
+  [{ requests: [{ pageId: 'tickets' }] }, '"requests" must be an array of { pageId, requestId }'],
+  [{ endpoints: [1] }, '"endpoints" must be an array of endpoint ids'],
+  [{ appEvents: 'yes' }, '"appEvents" must be a boolean'],
+  [{ operators: ['drop-everything'] }, '"operators" must be an array of operator names'],
+  [{ pages: ['../../secrets'] }, '"pages" must be an array of page ids'],
+  [
+    { requests: [{ pageId: 'tickets', requestId: '../x' }] },
+    '"requests" must be an array of { pageId, requestId }',
+  ],
+  [{ endpoints: ['../notify'] }, '"endpoints" must be an array of endpoint ids'],
+])(
+  'POST /lowdefy-docs/mutants answers a bad body %j with a 400 naming the field',
+  async (body, message) => {
+    const { status, data } = await post(body);
+    expect(status).toBe(400);
+    expect(data.error).toContain(message);
+    expect(mockBuildPageIfNeeded).not.toHaveBeenCalled();
+  }
+);
+
+test('POST /lowdefy-docs/mutants answers a page that fails to build with a 422 and its errors', async () => {
+  mockBuildPageIfNeeded.mockRejectedValue(new Error('Block type "Buton" not found.'));
+  const { status, data } = await post({ pages: ['tickets'] });
+  expect(status).toBe(422);
+  expect(data.buildErrors).toEqual([
+    { type: 'Error', message: 'Block type "Buton" not found.', source: null },
+  ]);
+});
+
+test('POST /lowdefy-docs/mutants answers with the build id read before the pages built', async () => {
+  // An edit lands while the page builds: its keys may be the new build's, so
+  // the answer must carry the older id and the journey route refuse it as stale.
+  mockBuildPageIfNeeded.mockImplementation(async () => {
+    write('buildStatus.json', { status: 'ok', timestamp: '2026-10-03T09:00:00.000Z' });
+    return true;
+  });
+  const { status, data } = await post({ pages: ['tickets'] });
+  expect(status).toBe(200);
+  expect(data.buildId).toEqual('2026-10-03T08:00:00.000Z');
+});
+
+test('POST /lowdefy-docs/mutants lists no mutants for a page no longer in the app, though its old build is on disk', async () => {
+  mockBuildPageIfNeeded.mockResolvedValue(false);
+  const { status, data } = await post({
+    pages: ['tickets'],
+    requests: [{ pageId: 'tickets', requestId: 'load' }],
+    endpoints: ['notify'],
+  });
+  expect(status).toBe(200);
+  expect(Object.keys(data.artifacts)).toEqual(['api/notify.json']);
+  expect(data.mutants.every(({ artifact }) => artifact === 'api/notify.json')).toBe(true);
+  expect(data.ids).toEqual(data.mutants.map(({ id }) => id));
+});

package/src/routes/docs/parsePathParamsParam.js

@@ -0,0 +1,41 @@
+/*
+  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';
+
+// The docs routes take a page instance's path values as a JSON string on the
+// GET routes (query params are always strings) and as an object in the POST
+// bodies. Returns { pathParams } or { error }; the page tools check the values
+// against the page's pattern.
+function parsePathParamsParam({ value }) {
+  if (type.isNone(value)) {
+    return {};
+  }
+  if (!type.isString(value)) {
+    return { pathParams: value };
+  }
+  try {
+    return { pathParams: JSON.parse(value) };
+  } catch {
+    return {
+      error: `The "pathParams" param must be JSON, e.g. {"ticket_id":"1"}. Received ${JSON.stringify(
+        value
+      )}.`,
+    };
+  }
+}
+
+export default parsePathParamsParam;

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

@@ -0,0 +1,42 @@
+/*
+  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 parsePathParamsParam from './parsePathParamsParam.js';
+
+test('parsePathParamsParam returns nothing when the param is absent', () => {
+  expect(parsePathParamsParam({ value: undefined })).toEqual({});
+  expect(parsePathParamsParam({ value: null })).toEqual({});
+});
+
+test('parsePathParamsParam parses a JSON string from a query param', () => {
+  expect(parsePathParamsParam({ value: '{"space":"s","ticket_id":"1"}' })).toEqual({
+    pathParams: { space: 's', ticket_id: '1' },
+  });
+});
+
+test('parsePathParamsParam passes an object from a JSON body through', () => {
+  expect(parsePathParamsParam({ value: { ticket_id: 1 } })).toEqual({
+    pathParams: { ticket_id: 1 },
+  });
+});
+
+test('parsePathParamsParam returns an error when the query param is not JSON', () => {
+  expect(parsePathParamsParam({ value: 'ticket_id=1' }).error).toMatch(/must be JSON/);
+});
+
+test('parsePathParamsParam leaves a parsed non-object for the page tools to refuse', () => {
+  expect(parsePathParamsParam({ value: '["1"]' })).toEqual({ pathParams: ['1'] });
+});

package/src/routes/docs/parseUserParam.js

@@ -16,36 +16,42 @@
 
 import { type } from '@lowdefy/helpers';
 
-// The docs routes take the headless caller as a JSON string on the GET routes
-// (query params are always strings) and as an object in the POST bodies, so both
-// arrive here and every route answers a bad `user` with the same message.
-// Returns { user } or { error }.
+const SHAPE =
+  'The "user" param must be a user object (JSON on a query string), e.g. {"roles":["admin"]}, "none" to act signed out, or the name of a user in the data set the "data" param names.';
+
+// The docs routes take the caller in the forms the MCP tools take (see
+// lib/docs/resolveToolCaller.js): a user object - a JSON string on the GET
+// routes, since query params are always strings, and an object in the POST
+// bodies - "none", or a data set user name. Both arrive here, so every route
+// answers a bad `user` with the same message. Returns { user } or { error }.
 function parseUserParam({ value }) {
   if (type.isNone(value)) {
     return {};
   }
-
-  let user = value;
-  if (type.isString(value)) {
-    try {
-      user = JSON.parse(value);
-    } catch {
-      return {
-        error: `The "user" param must be JSON, e.g. {"roles":["admin"]}. Received ${JSON.stringify(
-          value
-        )}.`,
-      };
-    }
+  if (type.isObject(value)) {
+    return { user: value };
   }
-
-  if (!type.isObject(user)) {
+  if (!type.isString(value) || value === '') {
+    return { error: `${SHAPE} Received ${JSON.stringify(value)}.` };
+  }
+  // A plain string is "none" or a data set user name; one that opens like JSON
+  // is a user object written as a query param.
+  if (!value.startsWith('{') && !value.startsWith('[')) {
+    return { user: value };
+  }
+  let user;
+  try {
+    user = JSON.parse(value);
+  } catch {
     return {
-      error: `The "user" param must be an object, e.g. {"roles":["admin"]}. Received ${JSON.stringify(
-        user
+      error: `The "user" param must be JSON, e.g. {"roles":["admin"]}. Received ${JSON.stringify(
+        value
       )}.`,
     };
   }
-
+  if (!type.isObject(user)) {
+    return { error: `${SHAPE} Received ${JSON.stringify(user)}.` };
+  }
   return { user };
 }
 

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

@@ -32,14 +32,26 @@ test('parseUserParam passes an object from a JSON body through', () => {
   });
 });
 
-test('parseUserParam returns an error when the query param is not JSON', () => {
-  expect(parseUserParam({ value: 'admin' }).error).toMatch(/must be JSON/);
+test('parseUserParam passes a data set user name through', () => {
+  expect(parseUserParam({ value: 'member' })).toEqual({ user: 'member' });
+});
+
+test('parseUserParam passes "none" through', () => {
+  expect(parseUserParam({ value: 'none' })).toEqual({ user: 'none' });
+});
+
+test('parseUserParam returns an error when a query param that opens like JSON is not JSON', () => {
+  expect(parseUserParam({ value: '{roles: [admin]}' }).error).toMatch(/must be JSON/);
 });
 
 test('parseUserParam returns an error when the param parses to a non-object', () => {
-  expect(parseUserParam({ value: '["admin"]' }).error).toMatch(/must be an object/);
+  expect(parseUserParam({ value: '["admin"]' }).error).toMatch(/must be a user object/);
+});
+
+test('parseUserParam returns an error when a body value is neither an object nor a string', () => {
+  expect(parseUserParam({ value: 42 }).error).toMatch(/must be a user object/);
 });
 
-test('parseUserParam returns an error when a body value is not an object', () => {
-  expect(parseUserParam({ value: 42 }).error).toMatch(/must be an object/);
+test('parseUserParam returns an error for an empty string', () => {
+  expect(parseUserParam({ value: '' }).error).toMatch(/must be a user object/);
 });

package/src/routes/docs/restart.js

@@ -0,0 +1,35 @@
+/*
+  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 requestRestart from '../../../lib/docs/requestRestart.js';
+
+async function docsRestartHandler(c) {
+  let body = {};
+  try {
+    body = await c.req.json();
+  } catch {
+    // An empty body is a valid request with no reason.
+  }
+  const reason = type.isString(body?.reason) ? body.reason : undefined;
+  const result = requestRestart({ reason });
+  return c.json({
+    ...result,
+    note: 'The dev server is restarting. Call GET /lowdefy-docs/build-status?wait=true (lowdefy_build_status with wait: true) before your next call; it answers once the server is back.',
+  });
+}
+
+export default docsRestartHandler;

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

@@ -0,0 +1,64 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Hono } from 'hono';
+
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-restart-route-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+process.chdir(fixtureDir);
+
+const { default: docsRestartHandler } = await import('./restart.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+function createApp() {
+  const app = new Hono();
+  app.post('/lowdefy-docs/restart', docsRestartHandler);
+  return app;
+}
+
+test('POST /lowdefy-docs/restart writes the sentinel and answers with the polling note', async () => {
+  const res = await createApp().request('/lowdefy-docs/restart', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ reason: 'stale cache' }),
+  });
+
+  expect(res.status).toBe(200);
+  expect(await res.json()).toEqual({
+    requested: true,
+    reason: 'stale cache',
+    note: 'The dev server is restarting. Call GET /lowdefy-docs/build-status?wait=true (lowdefy_build_status with wait: true) before your next call; it answers once the server is back.',
+  });
+  const sentinel = JSON.parse(fs.readFileSync(path.join(fixtureDir, 'build', '.restart'), 'utf8'));
+  expect(sentinel.reason).toBe('stale cache');
+});
+
+test('POST /lowdefy-docs/restart accepts an empty body', async () => {
+  const res = await createApp().request('/lowdefy-docs/restart', { method: 'POST' });
+
+  expect(res.status).toBe(200);
+  const body = await res.json();
+  expect(body.requested).toBe(true);
+  expect(body).not.toHaveProperty('reason');
+});

package/src/routes/docs/runEndpoint.js

@@ -0,0 +1,54 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+
+import parseUserParam from './parseUserParam.js';
+import runEndpoint from '../../../lib/docs/runEndpoint.js';
+
+// Refusals, routine rejects and endpoint errors are returned as 200 data (see
+// runEndpoint.js) - only malformed input (missing endpointId or a bad user,
+// thrown as a ConfigError) is a 400. Anything else is a fault and propagates to
+// the error handler.
+async function docsRunEndpointHandler(c) {
+  // Parse the body from a clone: runEndpoint builds a Lowdefy context whose
+  // resolveAuthentication reads c.req.raw (headers) to resolve the caller,
+  // so leave the original request body intact and read our own copy here.
+  const { endpointId, payload, user, data, system, saveResponse } = await c.req.raw.clone().json();
+  const { user: parsedUser, error: userError } = parseUserParam({ value: user });
+  if (userError) {
+    return c.json({ error: userError }, 400);
+  }
+  try {
+    const result = await runEndpoint({
+      endpointId,
+      payload,
+      user: parsedUser,
+      data,
+      system,
+      saveResponse,
+      honoContext: c,
+    });
+    return c.json(result);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      return c.json({ error: error.message }, 400);
+    }
+    throw error;
+  }
+}
+
+export default docsRunEndpointHandler;