@lowdefy/server-dev 5.5.1 → 6.0.0

package/lib/docs/inspectState.test.mjs

@@ -0,0 +1,140 @@
+/*
+  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';
+
+// inspectState.js only chooses between the tab and headless sources - the
+// sources' own behavior is covered by inspectStateHeadless.test.mjs and (once
+// written) inspectStateFromTab's own tests. Mock both, plus tabAvailable, so
+// only the fallback logic is under test here.
+const mockInspectStateFromTab = jest.fn();
+const mockInspectStateHeadless = jest.fn();
+const mockTabAvailable = jest.fn();
+
+jest.unstable_mockModule('./inspectStateFromTab.js', () => ({
+  default: mockInspectStateFromTab,
+}));
+jest.unstable_mockModule('./inspectStateHeadless.js', () => ({
+  default: mockInspectStateHeadless,
+}));
+jest.unstable_mockModule('./tabAvailable.js', () => ({
+  default: mockTabAvailable,
+}));
+
+const { default: inspectState } = await import('./inspectState.js');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+test('inspectState uses the tab when source is "tab" and it succeeds', async () => {
+  mockInspectStateFromTab.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    source: 'tab',
+  });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'tab' });
+  expect(mockInspectStateFromTab).toHaveBeenCalledWith({ pageId: 'home' });
+  expect(mockInspectStateHeadless).not.toHaveBeenCalled();
+});
+
+test('inspectState falls back to headless when source is "tab" but the tab errors', async () => {
+  mockInspectStateFromTab.mockResolvedValue({ error: 'No browser tab connected.' });
+  mockInspectStateHeadless.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    source: 'tab',
+  });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'headless' });
+  expect(mockInspectStateHeadless).toHaveBeenCalledWith({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+  });
+});
+
+test('inspectState goes straight to headless when source is "headless"', async () => {
+  mockInspectStateHeadless.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    source: 'headless',
+  });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'headless' });
+  expect(mockTabAvailable).not.toHaveBeenCalled();
+  expect(mockInspectStateFromTab).not.toHaveBeenCalled();
+});
+
+test('inspectState prefers the tab when source is unset and a tab is available', async () => {
+  mockTabAvailable.mockReturnValue(true);
+  mockInspectStateFromTab.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({ origin: 'http://localhost:3001', pageId: 'home' });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'tab' });
+  expect(mockInspectStateHeadless).not.toHaveBeenCalled();
+});
+
+test('inspectState goes straight to headless when source is unset and no tab is available', async () => {
+  mockTabAvailable.mockReturnValue(false);
+  mockInspectStateHeadless.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({ origin: 'http://localhost:3001', pageId: 'home' });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'headless' });
+  expect(mockInspectStateFromTab).not.toHaveBeenCalled();
+});
+
+test('inspectState ignores an available tab and passes the user to headless when a user is given', async () => {
+  mockTabAvailable.mockReturnValue(true);
+  mockInspectStateHeadless.mockResolvedValue({ state: { a: 1 } });
+
+  const result = await inspectState({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    user: { roles: ['admin'] },
+  });
+
+  expect(result).toEqual({ state: { a: 1 }, source: 'headless' });
+  expect(mockInspectStateFromTab).not.toHaveBeenCalled();
+  expect(mockInspectStateHeadless).toHaveBeenCalledWith({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    user: { roles: ['admin'] },
+  });
+});
+
+test('inspectState errors when a user is combined with source "tab"', async () => {
+  const result = await inspectState({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    source: 'tab',
+    user: { roles: ['admin'] },
+  });
+
+  expect(result.error).toMatch(/cannot apply "user" to the developer's live tab/);
+  // Flagged as the caller's mistake so the HTTP route answers 400, not 502.
+  expect(result.invalidInput).toBe(true);
+  expect(mockInspectStateFromTab).not.toHaveBeenCalled();
+  expect(mockInspectStateHeadless).not.toHaveBeenCalled();
+});

package/lib/docs/inspectStateFromTab.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.
+*/
+
+import { type, serializer } from '@lowdefy/helpers';
+
+import { requestFromTab } from './tabChannel.js';
+
+// Reads the live state of a page open in a developer's real browser tab, via
+// the SSE + POST /api/dev-inspect round trip set up in Inspector.jsx. Lets an
+// agent inspect actual client state (not just what the build would produce).
+//
+// requestFromTab resolves directly with whatever the tab posted as `result`
+// (see tabChannel.js) — a serialized snapshot string on success, or an
+// `{ error }` object if no tab is connected, the request timed out, or
+// Inspector.jsx itself failed to build the snapshot.
+async function inspectStateFromTab({ pageId } = {}) {
+  const response = await requestFromTab({ pageId, event: 'inspect-request' });
+  if (response?.error) {
+    return { error: response.error };
+  }
+  if (!type.isString(response)) {
+    return { error: 'Browser tab responded with an unexpected payload.' };
+  }
+  return serializer.deserializeFromString(response);
+}
+
+export default inspectStateFromTab;

package/lib/docs/inspectStateHeadless.js

@@ -0,0 +1,84 @@
+/*
+  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 { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+
+// Collects a state snapshot from a headless Chromium tab navigated to the
+// page's own route. Mirrors Inspector.jsx's buildSnapshot (the live-tab
+// equivalent), but window.lowdefy does not expose the app's serializer, so
+// the snapshot is round-tripped through JSON.parse(JSON.stringify(...))
+// inside the page instead. That strips functions/undefined and turns Dates
+// into plain ISO strings — good enough for agent inspection, just not a
+// byte-for-byte match of the app's own `~d`-tagged serialization.
+async function inspectStateHeadless({ origin, pageId, user, timeout = 15000 }) {
+  if (type.isNone(origin) || !type.isString(origin)) {
+    return {
+      error: `inspectStateHeadless requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+    };
+  }
+  if (type.isNone(pageId) || !type.isString(pageId)) {
+    return {
+      error: `inspectStateHeadless requires a "pageId" string. Received ${JSON.stringify(pageId)}.`,
+    };
+  }
+
+  let browser;
+  try {
+    browser = await getBrowser();
+  } catch (error) {
+    return {
+      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
+    };
+  }
+
+  const url = buildPageUrl({ origin, pageId });
+
+  let context;
+  try {
+    const opened = await openPage({ browser, origin, pageId, user, timeout });
+    context = opened.context;
+    const snapshot = await opened.page.evaluate((id) => {
+      const lowdefy = window.lowdefy;
+      const pageContext = lowdefy?.contexts?.[`page:${id}`];
+      if (!pageContext) {
+        return { error: `No live context for page "${id}".` };
+      }
+      return JSON.parse(
+        JSON.stringify({
+          pageId: id,
+          state: pageContext.state,
+          requests: pageContext.requests,
+          eventLog: (pageContext.eventLog ?? []).slice(-50),
+          global: lowdefy.lowdefyGlobal,
+          user: lowdefy.user,
+          input: lowdefy.inputs?.[`page:${id}`],
+          urlQuery: window.location.search,
+        })
+      );
+    }, pageId);
+    return snapshot;
+  } catch (error) {
+    return { error: `Failed to inspect state at "${url}": ${error.message}` };
+  } finally {
+    if (context) {
+      await context.close();
+    }
+  }
+}
+
+export default inspectStateHeadless;

package/lib/docs/inspectStateHeadless.test.mjs

@@ -0,0 +1,60 @@
+/*
+  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 { jest } from '@jest/globals';
+
+// A real headless inspection needs an installed browser, which jest can't
+// rely on, so this only covers the error paths: bad input, and
+// chromium.launch failing (the "no browser installed" case). Mirrors
+// screenshotPage.test.mjs, which exercises the same getBrowser.js singleton.
+jest.unstable_mockModule('playwright-core', () => ({
+  chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+}));
+
+// lib/build/config.js reads build/config.json from process.cwd() at import
+// time — chdir into a fixture that has one before getBrowser.js (which
+// imports it transitively) is loaded. Mirrors the pattern in
+// screenshotPage.test.mjs.
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-inspect-state-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+process.chdir(fixtureDir);
+
+const { default: inspectStateHeadless } = await import('./inspectStateHeadless.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+test('inspectStateHeadless returns an error when origin is missing', async () => {
+  const result = await inspectStateHeadless({ pageId: 'home' });
+  expect(result.error).toMatch(/requires an "origin" string/);
+});
+
+test('inspectStateHeadless returns an error when pageId is missing', async () => {
+  const result = await inspectStateHeadless({ origin: 'http://localhost:3001' });
+  expect(result.error).toMatch(/requires a "pageId" string/);
+});
+
+test('inspectStateHeadless returns an actionable error when no browser is available', async () => {
+  const result = await inspectStateHeadless({ origin: 'http://localhost:3001', pageId: 'home' });
+  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+});

package/lib/docs/isWriteRequestsAllowed.js

@@ -0,0 +1,50 @@
+/*
+  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 { get, type } from '@lowdefy/helpers';
+import { readFile } from '@lowdefy/node-utils';
+import YAML from 'yaml';
+
+// The top-level "cli" key in lowdefy.yaml never reaches a build artifact:
+// the build's root schema (packages/build/src/lowdefySchema.js) accepts an
+// arbitrary "cli" object, but no builder copies it onto `components`, so it
+// is never written to build/config.json (which only ever holds
+// components.config — see packages/build/src/build/writeConfig.js). The
+// Lowdefy CLI itself reads "cli" straight from lowdefy.yaml rather than from
+// a build artifact (packages/cli/src/utils/getLowdefyYaml.js) — this mirrors
+// that precedent instead of inventing a new build artifact for one dev-only
+// opt-in flag. Read fresh (no caching) so toggling the flag in lowdefy.yaml
+// takes effect without a server restart.
+async function isWriteRequestsAllowed() {
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  let raw = await readFile(path.join(configDirectory, 'lowdefy.yaml'));
+  if (type.isNone(raw)) {
+    raw = await readFile(path.join(configDirectory, 'lowdefy.yml'));
+  }
+  if (type.isNone(raw)) {
+    return false;
+  }
+  let lowdefy;
+  try {
+    lowdefy = YAML.parse(raw);
+  } catch {
+    return false;
+  }
+  return get(lowdefy, 'cli.agentTools.allowWriteRequests', { default: false }) === true;
+}
+
+export default isWriteRequestsAllowed;

package/lib/docs/listConfigCheckpoints.js

@@ -0,0 +1,55 @@
+/*
+  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 { getCheckpointsRoot, MANIFEST_FILE_NAME } from './checkpointPaths.js';
+
+// Lists stored config checkpoints, most recent first. Reads manifest.json
+// from each snapshot directory rather than re-scanning the config
+// directory — the manifest is the source of truth for what a checkpoint
+// contains, and stays accurate even after later checkpoints or reverts.
+function listConfigCheckpoints() {
+  const checkpointsRoot = getCheckpointsRoot();
+  if (!fs.existsSync(checkpointsRoot)) {
+    return [];
+  }
+
+  const checkpoints = fs
+    .readdirSync(checkpointsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const manifestPath = path.join(checkpointsRoot, entry.name, MANIFEST_FILE_NAME);
+      if (!fs.existsSync(manifestPath)) {
+        // A checkpoint directory without a manifest is not one this module
+        // wrote (or was interrupted mid-write) — skip rather than guess.
+        return null;
+      }
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      return {
+        id: manifest.id,
+        label: manifest.label,
+        createdAt: manifest.createdAt,
+        fileCount: manifest.files.length,
+      };
+    })
+    .filter((checkpoint) => checkpoint !== null);
+
+  return checkpoints.sort((a, b) => (a.id < b.id ? 1 : -1));
+}
+
+export default listConfigCheckpoints;

package/lib/docs/listPlugins.js

@@ -0,0 +1,80 @@
+/*
+  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';
+
+function addTypes({ plugins, store, kind }) {
+  for (const [typeName, definition] of Object.entries(store ?? {})) {
+    if (!plugins[definition.package]) {
+      plugins[definition.package] = { package: definition.package, version: definition.version, types: {} };
+    }
+    const plugin = plugins[definition.package];
+    if (!plugin.types[kind]) {
+      plugin.types[kind] = [];
+    }
+    plugin.types[kind].push(typeName);
+  }
+}
+
+function listPlugins() {
+  const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
+  const customTypesMap = readBuildArtifact({ name: 'customTypesMap.json' }) ?? {};
+  const installedPackages = readBuildArtifact({ name: 'installedPluginPackages.json' }) ?? [];
+
+  const plugins = {};
+  addTypes({ plugins, store: availableTypes.actions, kind: 'actions' });
+  addTypes({ plugins, store: availableTypes.agents, kind: 'agents' });
+  addTypes({ plugins, store: availableTypes.blocks, kind: 'blocks' });
+  addTypes({ plugins, store: availableTypes.connections, kind: 'connections' });
+  addTypes({ plugins, store: availableTypes.notifications, kind: 'notifications' });
+  addTypes({ plugins, store: availableTypes.operators?.client, kind: 'operators' });
+  addTypes({ plugins, store: availableTypes.operators?.server, kind: 'operators' });
+  addTypes({ plugins, store: availableTypes.requests, kind: 'requests' });
+  addTypes({ plugins, store: availableTypes.websockets, kind: 'websockets' });
+
+  const customPackages = new Set();
+  const customStores = [
+    customTypesMap.actions,
+    customTypesMap.agents,
+    customTypesMap.blocks,
+    customTypesMap.connections,
+    customTypesMap.operators?.client,
+    customTypesMap.operators?.server,
+    customTypesMap.requests,
+    customTypesMap.websockets,
+  ];
+  for (const store of customStores) {
+    for (const definition of Object.values(store ?? {})) {
+      customPackages.add(definition.package);
+    }
+  }
+
+  return Object.values(plugins)
+    .map((plugin) => ({
+      ...plugin,
+      custom: customPackages.has(plugin.package),
+      installed: installedPackages.includes(plugin.package),
+      types: Object.fromEntries(
+        Object.entries(plugin.types).map(([kind, typeNames]) => [
+          kind,
+          [...new Set(typeNames)].sort(),
+        ])
+      ),
+    }))
+    .sort((a, b) => a.package.localeCompare(b.package));
+}
+
+export default listPlugins;

package/lib/docs/listTypes.js

@@ -0,0 +1,105 @@
+/*
+  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 getDocsManifest from './getDocsManifest.js';
+import normalizeTypeKind from './normalizeTypeKind.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+function usedTypeNames({ store }) {
+  const used = new Set();
+  for (const [typeName, definition] of Object.entries(store ?? {})) {
+    if (type.isObject(definition) && (definition.count ?? 0) > 0) {
+      used.add(typeName);
+    }
+  }
+  return used;
+}
+
+function flattenKind({ kind, availableTypes }) {
+  if (kind === 'operators') {
+    const merged = {};
+    for (const [typeName, definition] of Object.entries(availableTypes.operators?.client ?? {})) {
+      merged[typeName] = { ...definition, environments: ['client'] };
+    }
+    for (const [typeName, definition] of Object.entries(availableTypes.operators?.server ?? {})) {
+      if (merged[typeName]) {
+        merged[typeName].environments.push('server');
+      } else {
+        merged[typeName] = { ...definition, environments: ['server'] };
+      }
+    }
+    return merged;
+  }
+  return availableTypes[kind] ?? {};
+}
+
+function listTypes({ kind }) {
+  const normalizedKind = normalizeTypeKind({ kind });
+  if (type.isNone(normalizedKind)) {
+    throw new Error(
+      `Unknown type kind. Received ${JSON.stringify(kind)}. Use one of: blocks, operators, actions, connections, requests, agents, notifications, websockets.`
+    );
+  }
+  const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
+  const types = readBuildArtifact({ name: 'types.json', deserialize: true }) ?? {};
+  const blockMetas = readBuildArtifact({ name: 'plugins/blockMetas.json' }) ?? {};
+  const manifest = getDocsManifest();
+
+  const docSlugsByType = new Map();
+  const kindSingular = normalizedKind.slice(0, -1);
+  for (const doc of manifest?.docs ?? []) {
+    if (doc.kind === kindSingular && doc.typeName) {
+      docSlugsByType.set(doc.typeName, doc.slug);
+    }
+  }
+
+  let used;
+  if (normalizedKind === 'operators') {
+    used = new Set([
+      ...usedTypeNames({ store: types.operators?.client }),
+      ...usedTypeNames({ store: types.operators?.server }),
+    ]);
+  } else {
+    used = usedTypeNames({ store: types[normalizedKind] });
+  }
+
+  const flattened = flattenKind({ kind: normalizedKind, availableTypes });
+  return Object.entries(flattened)
+    .map(([typeName, definition]) => {
+      const entry = {
+        type: typeName,
+        kind: normalizedKind,
+        package: definition.package,
+        version: definition.version,
+        used: used.has(typeName),
+      };
+      if (definition.environments) {
+        entry.environments = definition.environments;
+      }
+      if (normalizedKind === 'blocks' && blockMetas[typeName]?.category) {
+        entry.category = blockMetas[typeName].category;
+      }
+      if (docSlugsByType.has(typeName)) {
+        entry.docSlug = docSlugsByType.get(typeName);
+      }
+      return entry;
+    })
+    .sort((a, b) => a.type.localeCompare(b.type));
+}
+
+export default listTypes;