@lowdefy/server-dev 6.1.0 → 7.0.0

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

@@ -0,0 +1,401 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+const mockRunJourney = jest.fn();
+
+jest.unstable_mockModule('../../../lib/docs/runJourney.js', () => ({
+  default: mockRunJourney,
+}));
+jest.unstable_mockModule('../../../lib/build/config.js', () => ({
+  default: { basePath: '/app' },
+}));
+const mockGetBuildId = jest.fn(() => 'build-1');
+jest.unstable_mockModule('../../../lib/docs/getBuildId.js', () => ({
+  default: mockGetBuildId,
+}));
+const { readMutantRun } = await import('../../../lib/server/mutants/mutantRuns.js');
+const { journeyActorToken } = await import('../../../lib/server/auth/journeyActor.js');
+
+const { default: docsJourneyHandler } = await import('./journey.js');
+
+function createContext(body) {
+  const request = new Request('http://localhost:3227/lowdefy-docs/journey', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const json = jest.fn((data, status) => ({ data, status: status ?? 200 }));
+  return { req: { url: request.url, json: () => request.json() }, json };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockRunJourney.mockResolvedValue({
+    pageId: 'form',
+    passed: true,
+    steps: [],
+    screenshots: [{ name: 'after', data: 'cG5n', mimeType: 'image/png' }],
+    state: {},
+  });
+});
+
+test('docsJourneyHandler runs the journey against the request origin and returns the result', async () => {
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    user: { roles: ['admin'] },
+    urlQuery: { id: '1' },
+  });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(mockRunJourney).toHaveBeenCalledWith({
+    origin: 'http://localhost:3227',
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    user: { roles: ['admin'] },
+    urlQuery: { id: '1' },
+    stepTimeout: undefined,
+    basePath: '/app',
+    by: 'test',
+  });
+  expect(result.status).toBe(200);
+  expect(result.data.passed).toBe(true);
+  expect(result.data.screenshots).toEqual([{ name: 'after', data: 'cG5n', mimeType: 'image/png' }]);
+});
+
+test('docsJourneyHandler returns a failed journey as 200 data', async () => {
+  mockRunJourney.mockResolvedValue({
+    pageId: 'form',
+    passed: false,
+    steps: [{ index: 0, step: { click: 'nope' }, status: 'failed', durationMs: 12 }],
+    failure: { index: 0, step: { click: 'nope' }, expected: 'x', actual: 'y', message: 'm' },
+    screenshots: [],
+    state: {},
+  });
+  const c = createContext({ pageId: 'form', steps: [{ click: 'nope' }] });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(200);
+  expect(result.data.passed).toBe(false);
+  expect(result.data.failure.index).toBe(0);
+});
+
+test('docsJourneyHandler returns 400 when pageId is missing', async () => {
+  const c = createContext({ steps: [] });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/requires a "pageId" string/);
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler returns 400 when steps is not an array', async () => {
+  const c = createContext({ pageId: 'form', steps: { click: 'a' } });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/requires "steps" to be an array/);
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler returns 400 naming an unknown step', async () => {
+  const c = createContext({ pageId: 'form', steps: [{ hover: 'a' }] });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toEqual(
+    'Step 0: Unknown journey step "hover". Steps are: click, open, fill, select, press, back, goto, email, as, wait, screenshot, expect.'
+  );
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler returns 400 when urlQuery is not an object', async () => {
+  const c = createContext({ pageId: 'form', steps: [], urlQuery: 'id=1' });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/"urlQuery" param must be an object/);
+});
+
+test('docsJourneyHandler passes the state option through to the runner', async () => {
+  const c = createContext({ pageId: 'form', steps: [], state: ['form.name'] });
+
+  await docsJourneyHandler(c);
+
+  expect(mockRunJourney).toHaveBeenCalledWith(expect.objectContaining({ state: ['form.name'] }));
+});
+
+test('docsJourneyHandler returns 400 when the state option is malformed', async () => {
+  const c = createContext({ pageId: 'form', steps: [], state: 'form.name' });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(
+    /"state" option must be true, false or an array of state paths/
+  );
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler returns 400 when user is malformed', async () => {
+  const c = createContext({ pageId: 'form', steps: [], user: 5 });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/must be a user object/);
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler refuses a list of users with 400: one POST is one run', async () => {
+  const c = createContext({ pageId: 'form', steps: [], data: 'crm', user: ['admin', 'member'] });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toBe(
+    '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 ["admin","member"].'
+  );
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler passes user none through so the journey signs in through the app', async () => {
+  const c = createContext({ pageId: 'login', steps: [{ goto: 'dashboard' }], user: 'none' });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(200);
+  expect(mockRunJourney).toHaveBeenCalledWith(expect.objectContaining({ user: 'none' }));
+});
+
+test('docsJourneyHandler passes the journey timeout to the runner as the step timeout', async () => {
+  const c = createContext({ pageId: 'form', steps: [], timeout: 20000 });
+
+  await docsJourneyHandler(c);
+
+  expect(mockRunJourney).toHaveBeenCalledWith(expect.objectContaining({ stepTimeout: 20000 }));
+});
+
+test('docsJourneyHandler returns 400 for a timeout outside 1 to 60000 ms', async () => {
+  const c = createContext({ pageId: 'form', steps: [], timeout: 120000 });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/"timeout" must be a whole number of milliseconds/);
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test('docsJourneyHandler returns 502 when the journey could not run', async () => {
+  mockRunJourney.mockResolvedValue({ error: 'No Chromium available.' });
+  const c = createContext({ pageId: 'form', steps: [] });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(502);
+  expect(result.data.error).toEqual('No Chromium available.');
+});
+
+test('docsJourneyHandler passes data and a user name through to the runner', async () => {
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    data: 'staging-sample',
+    user: 'member',
+  });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(200);
+  expect(mockRunJourney).toHaveBeenCalledWith(
+    expect.objectContaining({ data: 'staging-sample', user: 'member' })
+  );
+});
+
+test('docsJourneyHandler answers 400 when the runner refuses the journey before a browser opens', async () => {
+  mockRunJourney.mockResolvedValue({
+    error: 'Data set "staging-sample" declares no user "outsider". Declared: owner.',
+    refused: true,
+  });
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    data: 'staging-sample',
+    user: 'outsider',
+  });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data).toEqual({
+    error: 'Data set "staging-sample" declares no user "outsider". Declared: owner.',
+  });
+});
+
+test('docsJourneyHandler refuses a data param that is not a string with 400', async () => {
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }], data: { name: 'x' } });
+
+  const result = await docsJourneyHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch('The "data" param must be a data set name string.');
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+const mutant = {
+  buildId: 'build-1',
+  artifact: 'pages/form.json',
+  key: 'k1_5',
+  arg: null,
+  operator: 'drop-block',
+};
+
+test('docsJourneyHandler opens a mutant run, passes its cookie to every actor and closes it after', async () => {
+  let runDuringJourney;
+  mockRunJourney.mockImplementation(async ({ mutantCookie }) => {
+    runDuringJourney = readMutantRun(`lowdefy_journey_mutant=${journeyActorToken}.${mutantCookie}`);
+    runDuringJourney.applied = 2;
+    return { pageId: 'form', passed: true, steps: [], screenshots: [], state: {} };
+  });
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }], mutant });
+  const result = await docsJourneyHandler(c);
+  expect(result.status).toBe(200);
+  expect(runDuringJourney.mutant).toEqual(mutant);
+  expect(result.data.mutant).toEqual({ id: runDuringJourney.id, applied: 2, misses: [] });
+  expect(
+    readMutantRun(`lowdefy_journey_mutant=${journeyActorToken}.${runDuringJourney.id}`)
+  ).toBeNull();
+});
+
+test('docsJourneyHandler opens the run with the mutant pointer and node hash it was sent', async () => {
+  let runDuringJourney;
+  mockRunJourney.mockImplementation(async ({ mutantCookie }) => {
+    runDuringJourney = readMutantRun(`lowdefy_journey_mutant=${journeyActorToken}.${mutantCookie}`);
+    return { pageId: 'form', passed: true, steps: [], screenshots: [], state: {} };
+  });
+  const withPointer = { ...mutant, pointer: ['slots', 'content', 'blocks', 0], nodeHash: 'abc' };
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }], mutant: withPointer });
+  const result = await docsJourneyHandler(c);
+  expect(result.status).toBe(200);
+  expect(runDuringJourney.mutant).toEqual(withPointer);
+});
+
+test('docsJourneyHandler refuses a mutant pointer that is not keys and indexes with 400', async () => {
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    mutant: { ...mutant, pointer: [{ a: 1 }] },
+  });
+  const result = await docsJourneyHandler(c);
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch('"mutant.pointer" must be an array of keys and indexes');
+});
+
+test('docsJourneyHandler closes the mutant run when the journey throws', async () => {
+  let cookie;
+  mockRunJourney.mockImplementation(async ({ mutantCookie }) => {
+    cookie = mutantCookie;
+    throw new Error('browser crashed');
+  });
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }], mutant });
+  await expect(docsJourneyHandler(c)).rejects.toThrow('browser crashed');
+  expect(readMutantRun(`lowdefy_journey_mutant=${journeyActorToken}.${cookie}`)).toBeNull();
+});
+
+test('docsJourneyHandler refuses a mutant listed against another build with 409 and stale', async () => {
+  mockGetBuildId.mockReturnValueOnce('build-2');
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }], mutant });
+  const result = await docsJourneyHandler(c);
+  expect(result.status).toBe(409);
+  expect(result.data.stale).toBe(true);
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});
+
+test.each([['../x.json'], ['connections/a.json'], ['pages/../secrets.json'], [5]])(
+  'docsJourneyHandler refuses a mutant artifact %j with 400',
+  async (artifact) => {
+    const c = createContext({
+      pageId: 'form',
+      steps: [{ click: 'submit' }],
+      mutant: { ...mutant, artifact },
+    });
+    const result = await docsJourneyHandler(c);
+    expect(result.status).toBe(400);
+    expect(result.data.error).toContain('"mutant.artifact"');
+    expect(mockRunJourney).not.toHaveBeenCalled();
+  }
+);
+
+test.each([
+  [{ operator: 'drop-everything' }, '"mutant.operator"'],
+  [{ key: 5 }, '"mutant.key"'],
+])('docsJourneyHandler refuses a bad mutant %j with 400', async (override, field) => {
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    mutant: { ...mutant, ...override },
+  });
+  const result = await docsJourneyHandler(c);
+  expect(result.status).toBe(400);
+  expect(result.data.error).toContain(field);
+});
+
+test('docsJourneyHandler passes no mutant cookie and returns no mutant without a mutant', async () => {
+  const c = createContext({ pageId: 'form', steps: [{ click: 'submit' }] });
+  const result = await docsJourneyHandler(c);
+  expect(mockRunJourney.mock.calls[0][0].mutantCookie).toBeUndefined();
+  expect(result.data.mutant).toBeUndefined();
+});
+
+test('docsJourneyHandler passes a recording through as a test run of source journey', async () => {
+  const c = createContext({
+    pageId: 'form',
+    steps: [{ click: 'submit' }],
+    recording: { run: '20261003T151200Z-p0d4rm', journey: 'tests/journeys/a.yaml#Assign' },
+  });
+  await docsJourneyHandler(c);
+  expect(mockRunJourney).toHaveBeenCalledWith(
+    expect.objectContaining({
+      recording: {
+        source: 'journey',
+        run: { id: '20261003T151200Z-p0d4rm', by: 'test', journey: 'tests/journeys/a.yaml#Assign' },
+      },
+    })
+  );
+});
+
+test('docsJourneyHandler returns 400 for a malformed recording', async () => {
+  for (const recording of [
+    { run: '../x' },
+    { run: '' },
+    'run',
+    { run: '20261003T151200Z-p0d4rm', journey: 7 },
+  ]) {
+    const result = await docsJourneyHandler(
+      createContext({ pageId: 'form', steps: [{ click: 'submit' }], recording })
+    );
+    expect(result.status).toBe(400);
+  }
+  expect(mockRunJourney).not.toHaveBeenCalled();
+});

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

@@ -0,0 +1,71 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+// The real runner refuses these journeys before it fetches a browser; the mock
+// proves it never gets that far.
+const mockGetBrowser = jest.fn();
+jest.unstable_mockModule('../../../lib/docs/getBrowser.js', () => ({
+  getBrowser: mockGetBrowser,
+  openPage: jest.fn(),
+  buildPageUrl: jest.fn(),
+}));
+jest.unstable_mockModule('../../../lib/build/config.js', () => ({ default: { basePath: '' } }));
+jest.unstable_mockModule('../../../lib/docs/getBuildId.js', () => ({
+  default: jest.fn(() => 'build-1'),
+}));
+
+const { default: docsJourneyHandler } = await import('./journey.js');
+
+function createContext(body) {
+  const request = new Request('http://localhost:3227/lowdefy-docs/journey', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const json = jest.fn((data, status) => ({ data, status: status ?? 200 }));
+  return { req: { url: request.url, json: () => request.json() }, json };
+}
+
+test('POST /lowdefy-docs/journey answers 400 for a placeholder value (from: shape)', async () => {
+  const result = await docsJourneyHandler(
+    createContext({
+      pageId: 'form',
+      steps: [{ fill: { blockId: 'title', value: null, from: 'shape' } }],
+    })
+  );
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch('has a placeholder value (from: shape)');
+  expect(mockGetBrowser).not.toHaveBeenCalled();
+});
+
+test('POST /lowdefy-docs/journey answers 400 for an email step on a server with no mail sink', async () => {
+  const previous = process.env.LOWDEFY_SERVER_DEV_MAIL_SINK;
+  delete process.env.LOWDEFY_SERVER_DEV_MAIL_SINK;
+  try {
+    const result = await docsJourneyHandler(
+      createContext({ pageId: 'form', steps: [{ email: { to: 'ada@example.test' } }] })
+    );
+    expect(result.status).toBe(400);
+    expect(result.data.error).toMatch('this dev server captures no mail');
+    expect(mockGetBrowser).not.toHaveBeenCalled();
+  } finally {
+    if (previous !== undefined) {
+      process.env.LOWDEFY_SERVER_DEV_MAIL_SINK = previous;
+    }
+  }
+});

package/src/routes/docs/loadState.js

@@ -14,6 +14,8 @@
   limitations under the License.
 */
 
+import { parseRequestBody } from '@lowdefy/api';
+
 import loadState from '../../../lib/docs/loadState.js';
 import parseUserParam from './parseUserParam.js';
 
@@ -23,7 +25,7 @@ import parseUserParam from './parseUserParam.js';
 // devMockRegistry and returns a URL for a human to open in a real browser
 // tab (client/Inspector.jsx does the state injection there).
 async function docsLoadStateHandler(c) {
-  const body = await c.req.json();
+  const body = parseRequestBody({ text: await c.req.text() });
   const { name, mode } = body;
   // 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
@@ -35,7 +37,7 @@ async function docsLoadStateHandler(c) {
     return c.json({ error: userError }, 400);
   }
 
-  const result = await loadState({ origin, name, mode, user });
+  const result = await loadState({ origin, name, mode, user, data: body.data });
   if (result.error) {
     // A contradictory call (`user` in 'registry-only' mode) is the caller's
     // mistake, not a failed render — 502 would read as "the renderer broke" and

package/src/routes/docs/mcp.js

@@ -16,15 +16,46 @@
 
 import { StreamableHTTPTransport } from '@hono/mcp';
 
-import createDocsMcpServer from '../../../lib/docs/createDocsMcpServer.js';
+import createDocsMcpServer, {
+  subscribeMcpServerToDevEvents,
+} from '../../../lib/docs/createDocsMcpServer.js';
+import { bootedAt } from '../../../lib/docs/devEventBus.js';
+import keepEventStreamAlive from '../../../lib/docs/keepEventStreamAlive.js';
 
 // Stateless per-request server: docs tools read build artifacts fresh on
 // every call, so there is no session state worth keeping between requests.
+//
+// A GET opens the transport's standalone SSE stream, which is where server →
+// client notifications go, so only that request subscribes to dev events. The
+// POST path stays stateless — no sessionIdGenerator, no session registry.
 async function mcpHandler(c) {
-  const server = createDocsMcpServer({ origin: new URL(c.req.url).origin, honoContext: c });
+  const server = createDocsMcpServer({
+    origin: new URL(c.req.url).origin,
+    honoContext: c,
+    version: process.env.LOWDEFY_SERVER_DEV_VERSION,
+  });
   const transport = new StreamableHTTPTransport();
   await server.connect(transport);
-  return transport.handleRequest(c);
+  if (c.req.method !== 'GET') {
+    return keepEventStreamAlive({ response: await transport.handleRequest(c) });
+  }
+
+  // Three unsubscribe paths: an explicit close, a dropped connection, and (via
+  // the bus pruning a send that rejects) a stream gone without either firing.
+  const unsubscribe = subscribeMcpServerToDevEvents(server);
+  server.server.onclose = unsubscribe;
+  c.req.raw.signal?.addEventListener('abort', unsubscribe, { once: true });
+
+  // handleRequest registers the standalone stream synchronously inside
+  // streamSSE, so the restart notice must be sent after it — before, the
+  // transport has no stream to write to and drops the message silently.
+  const response = await transport.handleRequest(c);
+  await server.server.sendLoggingMessage({
+    level: 'info',
+    logger: 'lowdefy',
+    data: { type: 'restart', timestamp: new Date().toISOString(), bootedAt },
+  });
+  return response;
 }
 
 export default mcpHandler;

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

@@ -0,0 +1,130 @@
+/*
+  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';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// A real McpServer with the logging capability rides the real @hono/mcp
+// transport, so the test covers the actual notification path; only the docs
+// tool registrations and the bus subscription are stubbed out.
+const mockSubscribeMcpServerToDevEvents = jest.fn();
+const mockUnsubscribe = jest.fn();
+jest.unstable_mockModule('../../../lib/docs/createDocsMcpServer.js', () => ({
+  default: () =>
+    new McpServer(
+      { name: 'lowdefy-docs-test', version: '1.0.0' },
+      { capabilities: { logging: {} } }
+    ),
+  subscribeMcpServerToDevEvents: mockSubscribeMcpServerToDevEvents,
+}));
+jest.unstable_mockModule('../../../lib/docs/devEventBus.js', () => ({
+  bootedAt: '2026-05-06T07:08:09.000Z',
+}));
+
+const { default: docsMcpHandler } = await import('./mcp.js');
+
+function createApp() {
+  const app = new Hono();
+  app.all('/lowdefy-docs/mcp', docsMcpHandler);
+  return app;
+}
+
+async function readFirstFrame(response) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  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 frame = buffer.slice(0, buffer.indexOf('\n\n'));
+  const dataLine = frame.split('\n').find((line) => line.startsWith('data:'));
+  return JSON.parse(dataLine.slice('data:'.length));
+}
+
+beforeEach(() => {
+  mockSubscribeMcpServerToDevEvents.mockReturnValue(mockUnsubscribe);
+});
+
+test('GET /lowdefy-docs/mcp subscribes to dev events and pushes the restart notification first', async () => {
+  const controller = new AbortController();
+  const res = await createApp().request('/lowdefy-docs/mcp', {
+    headers: { accept: 'text/event-stream' },
+    signal: controller.signal,
+  });
+
+  expect(res.status).toBe(200);
+  expect(res.headers.get('content-type')).toContain('text/event-stream');
+  expect(mockSubscribeMcpServerToDevEvents).toHaveBeenCalledTimes(1);
+  const [server] = mockSubscribeMcpServerToDevEvents.mock.calls[0];
+  expect(server).toBeInstanceOf(McpServer);
+
+  const message = await readFirstFrame(res);
+  expect(message).toEqual({
+    jsonrpc: '2.0',
+    method: 'notifications/message',
+    params: {
+      level: 'info',
+      logger: 'lowdefy',
+      data: {
+        type: 'restart',
+        timestamp: expect.any(String),
+        bootedAt: '2026-05-06T07:08:09.000Z',
+      },
+    },
+  });
+  controller.abort();
+});
+
+test('aborting the GET stream unsubscribes from dev events', async () => {
+  const controller = new AbortController();
+  const res = await createApp().request('/lowdefy-docs/mcp', {
+    headers: { accept: 'text/event-stream' },
+    signal: controller.signal,
+  });
+  await readFirstFrame(res);
+  expect(mockUnsubscribe).not.toHaveBeenCalled();
+
+  controller.abort();
+  await new Promise((resolve) => setTimeout(resolve, 20));
+
+  expect(mockUnsubscribe).toHaveBeenCalled();
+});
+
+test('POST /lowdefy-docs/mcp stays stateless and does not subscribe to dev events', async () => {
+  const res = await createApp().request('/lowdefy-docs/mcp', {
+    method: 'POST',
+    headers: { accept: 'application/json, text/event-stream', 'content-type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'test-client', version: '1.0.0' },
+      },
+    }),
+  });
+
+  expect(res.status).toBe(200);
+  expect(res.headers.get('mcp-session-id')).toBeNull();
+  expect(mockSubscribeMcpServerToDevEvents).not.toHaveBeenCalled();
+  const message = await readFirstFrame(res);
+  expect(message.result.capabilities).toEqual({ logging: {} });
+});