@lowdefy/server-dev 5.6.0 → 6.1.0

package/lib/docs/loadState.js

@@ -0,0 +1,152 @@
+/*
+  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 lowdefyConfig from '../build/config.js';
+import { getBrowser, openPage } from './getBrowser.js';
+import { loadMocks } from './devMockRegistry.js';
+import { readCheckpoint } from './checkpointStore.js';
+
+const VERIFY_KEY_COUNT = 3;
+
+// Loads a state checkpoint's recorded requests into devMockRegistry (shared
+// by both modes below — src/routes/request.js consults it regardless of how
+// the page was opened), then either:
+//   - 'headless': drives a headless page to the checkpoint's pageId/urlQuery,
+//     injects its recorded state directly into the live context, and verifies
+//     a few keys round-tripped. Good for an agent verifying its own change.
+//     Takes a `user` so a checkpoint captured on a role-gated page restores
+//     into a page that actually renders (see resolveHeadlessUser.js).
+//   - 'registry-only': just returns a URL a human can open in a real browser
+//     tab — client/Inspector.jsx's `?_checkpoint=` bootstrap does the state
+//     injection client-side once that tab loads.
+async function loadState({ origin, name, mode = 'headless', user }) {
+  if (type.isNone(name) || !type.isString(name)) {
+    return { error: `loadState requires a "name" string. Received ${JSON.stringify(name)}.` };
+  }
+
+  // `user` only reaches a page this function opens itself. In 'registry-only'
+  // mode the developer opens the returned URL in their own browser, carrying
+  // their own session, so an injected caller would be silently dropped.
+  if (!type.isNone(user) && mode === 'registry-only') {
+    return {
+      error:
+        'loadState cannot apply "user" in "registry-only" mode — the developer opens the returned URL in their own browser, carrying their own session. Use the default "headless" mode.',
+      invalidInput: true,
+    };
+  }
+
+  let checkpoint;
+  try {
+    checkpoint = readCheckpoint({ name });
+  } catch (error) {
+    return { error: error.message };
+  }
+
+  const pageId = checkpoint.checkpoint.pageId;
+  if (type.isNone(pageId)) {
+    return { error: `Checkpoint "${name}" has no recorded pageId.` };
+  }
+
+  loadMocks({ pageId, mocks: checkpoint.requests });
+
+  const basePath = lowdefyConfig.basePath ?? '';
+  const urlQuery = checkpoint.urlQuery ?? '';
+
+  if (mode === 'registry-only') {
+    const separator = urlQuery.includes('?') ? '&' : '?';
+    const url = `${origin}${basePath}/${pageId}${urlQuery}${separator}_checkpoint=${encodeURIComponent(
+      name
+    )}`;
+    return {
+      url,
+      instructions:
+        'Open this URL in a browser — state is injected on load, requests serve recorded data.',
+    };
+  }
+
+  if (mode !== 'headless') {
+    return {
+      error: `loadState "mode" must be "headless" or "registry-only". Received ${JSON.stringify(
+        mode
+      )}.`,
+    };
+  }
+
+  if (type.isNone(origin) || !type.isString(origin)) {
+    return { error: `loadState requires an "origin" string. Received ${JSON.stringify(origin)}.` };
+  }
+
+  let browser;
+  try {
+    browser = await getBrowser();
+  } catch (error) {
+    return {
+      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
+    };
+  }
+
+  let context;
+  try {
+    // buildPageUrl (used internally by openPage) joins origin/basePath/pageId
+    // as a plain string, so folding the query string into the pageId segment
+    // reproduces the checkpoint's exact URL without needing a query-aware
+    // variant of openPage.
+    const opened = await openPage({ browser, origin, pageId: `${pageId}${urlQuery}`, user });
+    context = opened.context;
+    const { page } = opened;
+
+    await page.waitForFunction((id) => Boolean(window.lowdefy?.contexts?.[`page:${id}`]), pageId, {
+      timeout: 15000,
+    });
+
+    const stateEntries = Object.entries(checkpoint.state ?? {});
+    await page.evaluate(
+      ({ id, entries }) => {
+        const pageContext = window.lowdefy.contexts[`page:${id}`];
+        entries.forEach(([key, value]) => {
+          pageContext._internal.State.set(key, value);
+        });
+        pageContext._internal.update();
+      },
+      { id: pageId, entries: stateEntries }
+    );
+
+    const verifyKeys = stateEntries.slice(0, VERIFY_KEY_COUNT).map(([key]) => key);
+    const verifiedKeys = await page.evaluate(
+      ({ id, keys }) => {
+        const pageContext = window.lowdefy.contexts[`page:${id}`];
+        const result = {};
+        keys.forEach((key) => {
+          result[key] = pageContext.state?.[key];
+        });
+        return result;
+      },
+      { id: pageId, keys: verifyKeys }
+    );
+
+    return { loaded: true, mode, url: opened.url, verifiedKeys };
+  } catch (error) {
+    return { error: `Failed to load checkpoint "${name}": ${error.message}` };
+  } finally {
+    if (context) {
+      await context.close();
+    }
+  }
+}
+
+export default loadState;

package/lib/docs/mapPageBuildErrors.js

@@ -0,0 +1,28 @@
+/*
+  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.
+*/
+
+// Mirrors the error mapping in src/routes/jitPage.js so agent-facing page
+// config responses carry the same shape as the dev client's JIT build errors.
+function mapPageBuildErrors(error) {
+  const rawErrors = error.buildErrors ?? [error];
+  return rawErrors.map((err) => ({
+    type: err.name ?? 'Error',
+    message: err.message,
+    source: err.source ?? null,
+  }));
+}
+
+export default mapPageBuildErrors;

package/lib/docs/normalizeTypeKind.js

@@ -0,0 +1,40 @@
+/*
+  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.
+*/
+
+const KINDS = {
+  action: 'actions',
+  actions: 'actions',
+  agent: 'agents',
+  agents: 'agents',
+  block: 'blocks',
+  blocks: 'blocks',
+  connection: 'connections',
+  connections: 'connections',
+  notification: 'notifications',
+  notifications: 'notifications',
+  operator: 'operators',
+  operators: 'operators',
+  request: 'requests',
+  requests: 'requests',
+  websocket: 'websockets',
+  websockets: 'websockets',
+};
+
+function normalizeTypeKind({ kind }) {
+  return KINDS[String(kind ?? '').toLowerCase()] ?? null;
+}
+
+export default normalizeTypeKind;

package/{pages/api/endpoints/[...endpointId].js → lib/docs/readBuildArtifact.js}

@@ -14,19 +14,22 @@
   limitations under the License.
 */
 
-import { callEndpoint } from '@lowdefy/api';
+import fs from 'node:fs';
+import path from 'node:path';
+import { serializer } from '@lowdefy/helpers';
 
-import apiWrapper from '../../../lib/server/apiWrapper.js';
-
-async function handler({ context, req, res }) {
-  if (req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+// Read fresh on every call — the dev build rewrites artifacts on config
+// change and the docs routes must serve the current state.
+function readBuildArtifact({ name, deserialize = false }) {
+  const filePath = path.join(process.cwd(), 'build', name);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  if (deserialize) {
+    return serializer.deserialize(raw);
   }
-  const endpointId = req.query.endpointId.join('/');
-  const { blockId, payload, pageId } = req.body;
-  context.logger.info({ event: 'call_api_endpoint', blockId, endpointId, pageId });
-  const response = await callEndpoint(context, { blockId, endpointId, pageId, payload });
-  res.status(200).json(response);
+  return raw;
 }
 
-export default apiWrapper(handler);
+export default readBuildArtifact;

package/lib/docs/readPageArtifact.js

@@ -0,0 +1,26 @@
+/*
+  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 readBuildArtifact from './readBuildArtifact.js';
+
+// Factored out of getPageConfig so the artifact-read side (deserializing
+// build/pages/<pageId>.json) is testable without exercising the JIT build
+// pipeline (buildPageIfNeeded) that getPageConfig also drives.
+function readPageArtifact({ pageId }) {
+  return readBuildArtifact({ name: `pages/${pageId}.json`, deserialize: true });
+}
+
+export default readPageArtifact;

package/lib/docs/resolvePluginDir.js

@@ -0,0 +1,49 @@
+/*
+  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 { createRequire } from 'node:module';
+import path from 'node:path';
+
+// Resolve from the server directory so installed plugins (including local
+// workspace: packages) resolve exactly as the server imports them.
+const require = createRequire(path.join(process.cwd(), 'package.json'));
+
+const cache = new Map();
+
+function resolvePluginDir({ packageName }) {
+  if (cache.has(packageName)) {
+    return cache.get(packageName);
+  }
+  let dir = null;
+  // Installed plugins are direct deps of the server, so node_modules holds a
+  // link to each. Plugin exports maps rarely expose ./package.json, so
+  // require.resolve on it fails — check the directory first.
+  const linked = path.join(process.cwd(), 'node_modules', packageName);
+  if (fs.existsSync(path.join(linked, 'package.json'))) {
+    dir = fs.realpathSync(linked);
+  } else {
+    try {
+      dir = path.dirname(require.resolve(`${packageName}/package.json`));
+    } catch {
+      // Package not resolvable — degrade gracefully.
+    }
+  }
+  cache.set(packageName, dir);
+  return dir;
+}
+
+export default resolvePluginDir;

package/lib/docs/resolveSource.js

@@ -0,0 +1,48 @@
+/*
+  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 tabAvailable from './tabAvailable.js';
+
+// The single tab-vs-headless decision, shared by inspectState and evalOperator
+// so a change to the rule lands in both. Prefers a real, already-open browser
+// tab over a fresh headless one — a live tab reflects whatever a developer is
+// actually looking at (their own interactions, in-flight requests), while
+// headless always starts a clean navigation.
+//
+// `user` is headless-only — the developer's tab carries their real session,
+// which the dev server cannot re-identify — so it selects the headless source,
+// and contradicts an explicit `source: 'tab'`.
+//
+// Returns { tryTab }, or { error, invalidInput } for a contradictory call.
+// `invalidInput` marks the caller's own mistake rather than a failed render, so
+// the HTTP routes can answer 400 instead of a 502 that reads as "the renderer
+// broke, retry".
+function resolveSource({ name, pageId, source, user }) {
+  const hasUser = !type.isNone(user);
+  if (hasUser && source === 'tab') {
+    return {
+      error: `${name} cannot apply "user" to the developer's live tab — it carries their real session. Omit "source", or use "headless".`,
+      invalidInput: true,
+    };
+  }
+  return {
+    tryTab: source === 'tab' || (source === undefined && !hasUser && tabAvailable({ pageId })),
+  };
+}
+
+export default resolveSource;

package/lib/docs/resolveSource.test.mjs

@@ -0,0 +1,100 @@
+/*
+  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 mockTabAvailable = jest.fn();
+
+jest.unstable_mockModule('./tabAvailable.js', () => ({
+  default: mockTabAvailable,
+}));
+
+const { default: resolveSource } = await import('./resolveSource.js');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+test('resolveSource tries the tab when source is "tab"', () => {
+  expect(resolveSource({ name: 'inspectState', pageId: 'home', source: 'tab' })).toEqual({
+    tryTab: true,
+  });
+  expect(mockTabAvailable).not.toHaveBeenCalled();
+});
+
+test('resolveSource does not try the tab when source is "headless"', () => {
+  expect(resolveSource({ name: 'inspectState', pageId: 'home', source: 'headless' })).toEqual({
+    tryTab: false,
+  });
+  expect(mockTabAvailable).not.toHaveBeenCalled();
+});
+
+test('resolveSource tries the tab when source is unset and a tab is available', () => {
+  mockTabAvailable.mockReturnValue(true);
+
+  expect(resolveSource({ name: 'inspectState', pageId: 'home' })).toEqual({ tryTab: true });
+  expect(mockTabAvailable).toHaveBeenCalledWith({ pageId: 'home' });
+});
+
+test('resolveSource does not try the tab when source is unset and no tab is available', () => {
+  mockTabAvailable.mockReturnValue(false);
+
+  expect(resolveSource({ name: 'inspectState', pageId: 'home' })).toEqual({ tryTab: false });
+});
+
+test('resolveSource selects headless over an available tab when a user is given', () => {
+  mockTabAvailable.mockReturnValue(true);
+
+  expect(
+    resolveSource({ name: 'inspectState', pageId: 'home', user: { roles: ['admin'] } })
+  ).toEqual({ tryTab: false });
+});
+
+test('resolveSource marks a user combined with source "tab" as invalid input', () => {
+  const result = resolveSource({
+    name: 'inspectState',
+    pageId: 'home',
+    source: 'tab',
+    user: { roles: ['admin'] },
+  });
+
+  expect(result.invalidInput).toBe(true);
+  expect(result.error).toBe(
+    'inspectState cannot apply "user" to the developer\'s live tab — it carries their real session. Omit "source", or use "headless".'
+  );
+  expect(result.tryTab).toBeUndefined();
+});
+
+test('resolveSource names the calling function in the invalid-input error', () => {
+  const result = resolveSource({
+    name: 'evalOperator',
+    pageId: 'home',
+    source: 'tab',
+    user: { roles: ['admin'] },
+  });
+
+  expect(result.error).toMatch(/^evalOperator cannot apply "user"/);
+});
+
+test('resolveSource treats a null user as no user', () => {
+  mockTabAvailable.mockReturnValue(true);
+
+  expect(
+    resolveSource({ name: 'inspectState', pageId: 'home', source: 'tab', user: null })
+  ).toEqual({
+    tryTab: true,
+  });
+});

package/lib/docs/revertConfigCheckpoint.js

@@ -0,0 +1,73 @@
+/*
+  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 path from 'path';
+import { type } from '@lowdefy/helpers';
+
+import {
+  getCheckpointsRoot,
+  getConfigDirectory,
+  listConfigFiles,
+  MANIFEST_FILE_NAME,
+} from './checkpointPaths.js';
+
+function copyFromSnapshot({ snapshotDirectory, configDirectory, relativeFilePath }) {
+  const source = path.join(snapshotDirectory, relativeFilePath);
+  const destination = path.join(configDirectory, relativeFilePath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+// Restores the config directory to exactly the state captured by checkpoint
+// `id`: every file the manifest lists is copied back (covering both
+// modified files and files deleted after the checkpoint was taken), and any
+// config-relevant file that exists now but isn't in the manifest is deleted
+// (covering files added after the checkpoint). The manifest — not a diff
+// against the live directory — is the single source of truth for what
+// "restored" means, so reverts are exact and repeatable.
+function revertConfigCheckpoint({ id }) {
+  if (type.isNone(id) || !type.isString(id)) {
+    throw new Error(
+      `revertConfigCheckpoint requires an "id" string. Received ${JSON.stringify(id)}.`
+    );
+  }
+
+  const checkpointsRoot = getCheckpointsRoot();
+  const snapshotDirectory = path.join(checkpointsRoot, id);
+  const manifestPath = path.join(snapshotDirectory, MANIFEST_FILE_NAME);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`Config checkpoint "${id}" not found.`);
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const configDirectory = getConfigDirectory();
+
+  manifest.files.forEach((relativeFilePath) => {
+    copyFromSnapshot({ snapshotDirectory, configDirectory, relativeFilePath });
+  });
+
+  const manifestFiles = new Set(manifest.files);
+  const currentFiles = listConfigFiles({ configDirectory });
+  const deleted = currentFiles.filter((relativeFilePath) => !manifestFiles.has(relativeFilePath));
+  deleted.forEach((relativeFilePath) => {
+    fs.rmSync(path.join(configDirectory, relativeFilePath));
+  });
+
+  return { restored: manifest.files, deleted };
+}
+
+export default revertConfigCheckpoint;