@lowdefy/server-dev 5.6.0 → 6.0.0

package/lib/docs/getBrowser.test.mjs

@@ -0,0 +1,122 @@
+/*
+  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';
+
+// openPage takes its browser as a parameter, so a fake one covers the cookie
+// injection without a real Chromium. lib/build/config.js reads build/config.json
+// from process.cwd() at import time — chdir into a fixture that has one before
+// getBrowser.js is loaded. Mirrors the pattern in screenshotPage.test.mjs.
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-get-browser-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+process.chdir(fixtureDir);
+
+const { openPage } = await import('./getBrowser.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+function createBrowser() {
+  const addCookies = jest.fn();
+  const page = {
+    goto: jest.fn().mockResolvedValue(undefined),
+    waitForFunction: jest.fn().mockResolvedValue(undefined),
+  };
+  const context = {
+    addCookies,
+    newPage: jest.fn().mockResolvedValue(page),
+  };
+  return {
+    browser: { newContext: jest.fn().mockResolvedValue(context) },
+    addCookies,
+    context,
+  };
+}
+
+function decodeUserCookie(addCookies) {
+  const [[[cookie]]] = addCookies.mock.calls;
+  return JSON.parse(Buffer.from(cookie.value, 'base64').toString());
+}
+
+test('openPage injects the default roleless user when no user is given', async () => {
+  const { browser, addCookies } = createBrowser();
+
+  await openPage({ browser, origin: 'http://localhost:3001', pageId: 'home' });
+
+  expect(decodeUserCookie(addCookies)).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'lowdefy-headless',
+    name: 'Lowdefy Headless',
+    roles: [],
+  });
+});
+
+test('openPage injects a per-call user with roles', async () => {
+  const { browser, addCookies } = createBrowser();
+
+  await openPage({
+    browser,
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    user: { id: 'agent', roles: ['user-admin'] },
+  });
+
+  expect(decodeUserCookie(addCookies)).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'agent',
+    name: 'Lowdefy Headless',
+    roles: ['user-admin'],
+  });
+});
+
+test('openPage gives concurrent calls their own identity', async () => {
+  const admin = createBrowser();
+  const member = createBrowser();
+
+  await Promise.all([
+    openPage({
+      browser: admin.browser,
+      origin: 'http://localhost:3001',
+      pageId: 'home',
+      user: { roles: ['user-admin'] },
+    }),
+    openPage({
+      browser: member.browser,
+      origin: 'http://localhost:3001',
+      pageId: 'home',
+      user: { roles: ['member'] },
+    }),
+  ]);
+
+  expect(decodeUserCookie(admin.addCookies).roles).toEqual(['user-admin']);
+  expect(decodeUserCookie(member.addCookies).roles).toEqual(['member']);
+});
+
+test('openPage rejects an invalid user before opening a browser context', async () => {
+  const { browser } = createBrowser();
+
+  await expect(
+    openPage({ browser, origin: 'http://localhost:3001', pageId: 'home', user: 'admin' })
+  ).rejects.toThrow('Headless "user" must be an object. Received "admin".');
+  expect(browser.newContext).not.toHaveBeenCalled();
+});

package/lib/docs/getBuildStatus.js

@@ -0,0 +1,37 @@
+/*
+  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 clientErrorStore from './clientErrorStore.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+// Feedback loop for agents: build status (written by the build manager to
+// build/buildStatus.json) plus recent browser errors reported via
+// POST /api/client-error. Lets an agent check "did my last edit work?"
+// without tailing terminal logs.
+function getBuildStatus() {
+  const build = readBuildArtifact({ name: 'buildStatus.json' }) ?? {
+    status: 'unknown',
+    message:
+      'No build status yet — the build manager has not written build/buildStatus.json. ' +
+      'This is expected before the first build completes.',
+  };
+  return {
+    build,
+    clientErrors: clientErrorStore.list(),
+  };
+}
+
+export default getBuildStatus;

package/lib/docs/getCoreDoc.js

@@ -0,0 +1,63 @@
+/*
+  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 path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+import getDocsManifest from './getDocsManifest.js';
+
+function findDoc({ manifest, slug, kind, typeName }) {
+  if (!type.isNone(slug)) {
+    return manifest.docs.find((doc) => doc.slug === slug) ?? null;
+  }
+  if (type.isNone(typeName)) {
+    return null;
+  }
+  let singularKind = type.isNone(kind) ? null : String(kind).toLowerCase().replace(/s$/, '');
+  // Requests are documented on their connection's page (e.g. MongoDBFind → MongoDB).
+  if (singularKind === 'request') {
+    singularKind = 'connection';
+  }
+  const candidates = manifest.docs.filter(
+    (doc) => doc.typeName && (type.isNone(singularKind) || doc.kind === singularKind)
+  );
+  const exact = candidates.find((doc) => doc.typeName === typeName);
+  if (exact) {
+    return exact;
+  }
+  // Connection docs are titled per package (e.g. "MongoDB" covers
+  // MongoDBCollection and all MongoDB requests) — fall back to prefix match.
+  const prefixed = candidates
+    .filter((doc) => typeName.startsWith(doc.typeName))
+    .sort((a, b) => b.typeName.length - a.typeName.length);
+  return prefixed[0] ?? null;
+}
+
+function getCoreDoc({ slug, kind, type: typeName }) {
+  const manifest = getDocsManifest();
+  if (type.isNone(manifest)) {
+    return null;
+  }
+  const doc = findDoc({ manifest, slug, kind, typeName });
+  if (type.isNone(doc)) {
+    return null;
+  }
+  const markdown = fs.readFileSync(path.join(manifest.contentDir, doc.path), 'utf8');
+  return { slug: doc.slug, title: doc.title, section: doc.section, markdown };
+}
+
+export default getCoreDoc;

package/lib/docs/getDocsManifest.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 fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+let manifest;
+
+function getDocsManifest() {
+  if (manifest !== undefined) {
+    return manifest;
+  }
+  try {
+    const manifestPath = require.resolve('@lowdefy/docs-content/index.json');
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    manifest.contentDir = path.dirname(manifestPath);
+  } catch {
+    // docs-content not installed — core docs unavailable, plugin data still served.
+    manifest = null;
+  }
+  return manifest;
+}
+
+export default getDocsManifest;

package/lib/docs/getExamples.js

@@ -0,0 +1,58 @@
+/*
+  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 path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+import readBuildArtifact from './readBuildArtifact.js';
+import resolvePluginDir from './resolvePluginDir.js';
+
+const EXAMPLE_FILES = ['gallery.yaml', 'examples.yaml', 'tests.yaml'];
+
+// Block example yaml ships in plugin dist by convention
+// (dist/blocks/<Block>/gallery.yaml). Local plugins may only ship some of
+// these files, or none — return whatever exists, never throw.
+function getExamples({ type: typeName }) {
+  const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
+  const definition = availableTypes.blocks?.[typeName];
+  if (type.isNone(definition)) {
+    return null;
+  }
+  const pluginDir = resolvePluginDir({ packageName: definition.package });
+  if (type.isNone(pluginDir)) {
+    return null;
+  }
+  const files = {};
+  for (const baseDir of ['dist/blocks', 'src/blocks', 'blocks']) {
+    const blockDir = path.join(pluginDir, baseDir, definition.originalTypeName);
+    for (const fileName of EXAMPLE_FILES) {
+      const filePath = path.join(blockDir, fileName);
+      if (!files[fileName] && fs.existsSync(filePath)) {
+        files[fileName] = fs.readFileSync(filePath, 'utf8');
+      }
+    }
+    if (Object.keys(files).length > 0) {
+      break;
+    }
+  }
+  if (Object.keys(files).length === 0) {
+    return null;
+  }
+  return { type: typeName, package: definition.package, files };
+}
+
+export default getExamples;

package/lib/docs/getOverview.js

@@ -0,0 +1,115 @@
+/*
+  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 getDocsManifest from './getDocsManifest.js';
+import listPlugins from './listPlugins.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+function countKinds({ availableTypes }) {
+  return {
+    blocks: Object.keys(availableTypes.blocks ?? {}).length,
+    operators: new Set([
+      ...Object.keys(availableTypes.operators?.client ?? {}),
+      ...Object.keys(availableTypes.operators?.server ?? {}),
+    ]).size,
+    actions: Object.keys(availableTypes.actions ?? {}).length,
+    connections: Object.keys(availableTypes.connections ?? {}).length,
+    requests: Object.keys(availableTypes.requests ?? {}).length,
+  };
+}
+
+function getOverview() {
+  const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
+  const counts = countKinds({ availableTypes });
+  const plugins = listPlugins();
+  const manifest = getDocsManifest();
+  const sections = [...new Set((manifest?.docs ?? []).map((doc) => doc.section))];
+
+  const lines = [
+    '# Lowdefy Docs for AI Coding Agents',
+    '',
+    'Lowdefy is a config-driven web framework: apps are YAML files composing **blocks** (UI components), **operators** (logic like `_if`, `_get`, `_state`), **actions** (event handlers), and **connections/requests** (databases and APIs).',
+    '',
+    'This server describes everything installed in THIS project — never guess type names or properties, look them up here first.',
+    '',
+    '## What is available',
+    '',
+    `- ${counts.blocks} block types, ${counts.operators} operators, ${counts.actions} actions, ${counts.connections} connections, ${counts.requests} request types (from ${plugins.length} plugin packages, including this project's local plugins).`,
+    manifest
+      ? `- ${manifest.docs.length} core documentation pages (sections: ${sections.join(', ')}).`
+      : '- Core documentation package (@lowdefy/docs-content) is not installed.',
+    '',
+    '## How to use this (recommended order)',
+    '',
+    '1. **List what exists**: `GET /lowdefy-docs/blocks`, `/lowdefy-docs/operators`, `/lowdefy-docs/actions`, `/lowdefy-docs/connections`, `/lowdefy-docs/requests` — or the `lowdefy_list_types` MCP tool. Each entry links to its schema, examples, and doc.',
+    '2. **Get the exact contract**: `GET /lowdefy-docs/schema/{kind}/{type}` (e.g. `/lowdefy-docs/schema/blocks/Button`) — or `lowdefy_get_schema`. JSON Schema of all properties.',
+    '3. **See real usage**: `GET /lowdefy-docs/examples/{type}` — or `lowdefy_get_examples`. YAML examples for block types.',
+    '4. **Read concept docs**: `GET /lowdefy-docs/content/{slug}` (e.g. `/lowdefy-docs/content/operators/_get`) — or `lowdefy_get_doc`. Start with `concepts/lowdefy-schema`, `concepts/blocks`, `concepts/events-and-actions`, `concepts/connections-and-requests`, `concepts/operators`.',
+    '5. **Search**: `GET /lowdefy-docs/search?q=...` — or `lowdefy_search_docs`.',
+    '6. **Plugin packages**: `GET /lowdefy-docs/plugins` lists every installed plugin; `GET /lowdefy-docs/plugin-doc/{package}` returns markdown a plugin ships itself (READMEs, guides).',
+    '',
+    '## The feedback loop (after every edit)',
+    '',
+    'The dev server rebuilds automatically when config files change. After EVERY edit:',
+    '',
+    '1. **Check what broke**: `GET /lowdefy-docs/build-status` — or `lowdefy_build_status`. Current build errors and warnings with source file locations, plus recent browser runtime errors.',
+    '2. **Verify the page**: `GET /lowdefy-docs/page-config/{pageId}` — or `lowdefy_get_page_config`. The fully built page config, or its structured build errors.',
+    '3. **See it rendered**: `GET /lowdefy-docs/screenshot/{pageId}` — or `lowdefy_screenshot_page`. PNG of the page in headless Chromium.',
+    '4. **Locate config**: `GET /lowdefy-docs/find/{id}?pageId=...` — or `lowdefy_find_config`. Which yaml file defines a page/block/request id.',
+    '5. **Scaffold**: `lowdefy_scaffold_page` creates a canonical new page file (then register it in lowdefy.yaml).',
+    '',
+    '## Live state and testing',
+    '',
+    "1. **Inspect live state**: `GET /lowdefy-docs/inspect-state/{pageId}` — or `lowdefy_inspect_state`. The actual state, request results, and event log of a running page. Reads the developer's open browser tab when connected (ask them to interact, then inspect), else runs the page headless.",
+    '2. **Evaluate operators**: `POST /lowdefy-docs/eval-operator` `{pageId, expression}` — or `lowdefy_eval_operator`. A REPL for config: run any operator expression against live page state. The operator goes in the `expression` body key (`operator` is accepted as an alias).',
+    '3. **Run a request**: `POST /lowdefy-docs/run-request` `{pageId, requestId, payload}` — or `lowdefy_run_request`. Verify the data shape a request returns. Read-only types always run; writes need `cli.agentTools.allowWriteRequests: true` in lowdefy.yaml.',
+    '4. **Understand the app**: `GET /lowdefy-docs/app-map` — or `lowdefy_app_map`. Every page, menu, connection, endpoint, agent, and websocket in one call.',
+    '5. **Config checkpoints**: `POST /lowdefy-docs/checkpoints` `{label}` / `POST /lowdefy-docs/checkpoints/revert` `{id}` — or `lowdefy_checkpoint` / `lowdefy_revert_checkpoint`. Snapshot config files before risky changes; revert instantly.',
+    "6. **State checkpoints**: `POST /lowdefy-docs/state-checkpoints/snapshot` `{pageId, name}` captures live page state + request responses into .lowdefy/state-checkpoints/<name>/ (gitignored — checkpoints contain user/session data); `POST /lowdefy-docs/state-checkpoints/load` `{name, mode}` restores it — 'registry-only' mode returns a ?_checkpoint URL a human can open to test the app in that exact state. `lowdefy_checkpoint_to_mocks` converts one into e2e mocks.yaml fixtures.",
+    '',
+    '## Visual feedback (annotation helper)',
+    '',
+    'The developer can press Cmd/Ctrl+/ in the running app to point at elements, draw, and comment; the helper copies an agent-readable feedback block to their clipboard which they paste into their agent session. Pasted blocks start with "Feedback:" and carry the blockId, resolved config file:line, drawn shapes (usable as screenshot clip geometry), and recent console entries — treat them as precise UI feedback.',
+    '',
+    '## Routes',
+    '',
+    '| Route | Purpose |',
+    '| --- | --- |',
+    '| `GET /lowdefy-docs` | This overview |',
+    '| `GET /lowdefy-docs/{kind}` | List all available types of a kind (blocks, operators, actions, connections, requests, agents, notifications, websockets) |',
+    '| `GET /lowdefy-docs/plugins` | Installed plugin packages and the types each provides |',
+    '| `GET /lowdefy-docs/schema/{kind}/{type}` | JSON schema for a type |',
+    '| `GET /lowdefy-docs/examples/{type}` | Example yaml for a block type |',
+    '| `GET /lowdefy-docs/content/{slug}` | Core doc page as markdown |',
+    '| `GET /lowdefy-docs/search?q={query}` | Search core docs |',
+    '| `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package |',
+    '| `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser errors |',
+    '| `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors |',
+    '| `GET /lowdefy-docs/screenshot/{pageId}` | PNG screenshot of the rendered page |',
+    '| `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |',
+    '| `GET /lowdefy-docs/inspect-state/{pageId}?source=` | Live state/requests/eventLog of a running page (tab or headless) |',
+    '| `POST /lowdefy-docs/eval-operator` | Evaluate an operator expression against live page state |',
+    '| `POST /lowdefy-docs/run-request` | Execute a request with a test payload (read-only unless opted in) |',
+    '| `GET /lowdefy-docs/app-map` | Whole-app graph: pages, menus, connections, endpoints, agents |',
+    '| `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints: list, create, revert |',
+    '| `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints: capture/restore live app state |',
+    '| `POST /lowdefy-feedback` | Annotation helper: enrich + format a feedback batch (overlay → clipboard) |',
+    '| `ALL /lowdefy-docs/mcp` | MCP endpoint (streamable HTTP) exposing all of the above as tools |',
+  ];
+  return lines.join('\n');
+}
+
+export default getOverview;

package/lib/docs/getPageConfig.js

@@ -0,0 +1,53 @@
+/*
+  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 '../server/jitPageBuilder.js';
+import mapPageBuildErrors from './mapPageBuildErrors.js';
+import readBuildArtifact from './readBuildArtifact.js';
+import readPageArtifact from './readPageArtifact.js';
+
+// JIT-builds a page (same pipeline as GET /api/page/*, see src/routes/jitPage.js)
+// and returns its built config so agents can inspect a page's blocks/requests
+// without a browser. Returns null when the pageId isn't registered at all.
+async function getPageConfig({ pageId }) {
+  const registry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
+  if (!registry[pageId]) {
+    return null;
+  }
+
+  const buildDirectory = path.join(process.cwd(), 'build');
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+
+  let buildResult;
+  try {
+    buildResult = await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+  } catch (error) {
+    return { buildError: true, errors: mapPageBuildErrors(error) };
+  }
+
+  if (buildResult === false) {
+    return null;
+  }
+  if (buildResult && buildResult.installing) {
+    return { installing: true, packages: buildResult.packages };
+  }
+
+  return readPageArtifact({ pageId }) ?? {};
+}
+
+export default getPageConfig;

package/lib/docs/getPluginDoc.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 'node:fs';
+import path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+import resolvePluginDir from './resolvePluginDir.js';
+
+// Local plugins have no doc convention — probe the common locations and
+// return whatever markdown ships with the package.
+function getPluginDoc({ packageName }) {
+  const pluginDir = resolvePluginDir({ packageName });
+  if (type.isNone(pluginDir)) {
+    return null;
+  }
+  const sections = [];
+  for (const readme of ['README.md', 'readme.md']) {
+    const readmePath = path.join(pluginDir, readme);
+    if (fs.existsSync(readmePath)) {
+      sections.push(fs.readFileSync(readmePath, 'utf8'));
+      break;
+    }
+  }
+  for (const docsDir of ['docs', 'dist/docs']) {
+    const dirPath = path.join(pluginDir, docsDir);
+    if (!fs.existsSync(dirPath)) {
+      continue;
+    }
+    for (const fileName of fs.readdirSync(dirPath).sort()) {
+      if (fileName.endsWith('.md')) {
+        sections.push(fs.readFileSync(path.join(dirPath, fileName), 'utf8'));
+      }
+    }
+  }
+  if (sections.length === 0) {
+    return null;
+  }
+  return { package: packageName, markdown: sections.join('\n\n---\n\n') };
+}
+
+export default getPluginDoc;

package/lib/docs/getSchema.js

@@ -0,0 +1,65 @@
+/*
+  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 normalizeTypeKind from './normalizeTypeKind.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+const SCHEMA_ARTIFACTS = {
+  actions: 'plugins/actionSchemas.json',
+  blocks: 'plugins/blockSchemas.json',
+  connections: 'plugins/connectionSchemas.json',
+  operators: 'plugins/operatorSchemas.json',
+  requests: 'plugins/requestSchemas.json',
+};
+
+function getSchema({ kind, type: typeName }) {
+  const normalizedKind = normalizeTypeKind({ kind });
+  if (type.isNone(SCHEMA_ARTIFACTS[normalizedKind])) {
+    throw new Error(
+      `No schemas available for type kind. Received ${JSON.stringify(kind)}. Use one of: blocks, operators, actions, connections, requests.`
+    );
+  }
+  const schemas = readBuildArtifact({ name: SCHEMA_ARTIFACTS[normalizedKind] }) ?? {};
+  const entry = schemas[typeName];
+  if (type.isNone(entry)) {
+    return null;
+  }
+  const result = { kind: normalizedKind, type: typeName };
+  if (normalizedKind === 'connections') {
+    result.schema = entry.schema ?? entry;
+    if (entry.requests) {
+      result.requests = entry.requests;
+    }
+  } else if (normalizedKind === 'requests') {
+    result.schema = entry.schema ?? entry;
+    if (entry.meta) {
+      result.meta = entry.meta;
+    }
+  } else {
+    result.schema = entry;
+  }
+  if (normalizedKind === 'blocks') {
+    const blockMetas = readBuildArtifact({ name: 'plugins/blockMetas.json' }) ?? {};
+    if (blockMetas[typeName]) {
+      result.meta = blockMetas[typeName];
+    }
+  }
+  return result;
+}
+
+export default getSchema;

package/lib/docs/inspectState.js

@@ -0,0 +1,47 @@
+/*
+  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 inspectStateFromTab from './inspectStateFromTab.js';
+import inspectStateHeadless from './inspectStateHeadless.js';
+import resolveSource from './resolveSource.js';
+
+// resolveSource picks the tab or headless — including why `user` is
+// headless-only. Falls back to headless whenever the tab path isn't usable
+// (no tab connected, or `source: 'tab'` was requested but it errored) so
+// agents always get an answer.
+async function inspectState({ origin, pageId, source, user }) {
+  const { tryTab, error, invalidInput } = resolveSource({
+    name: 'inspectState',
+    pageId,
+    source,
+    user,
+  });
+  if (error) {
+    return { error, invalidInput };
+  }
+
+  if (tryTab) {
+    const result = await inspectStateFromTab({ pageId });
+    if (!result?.error) {
+      return { ...result, source: 'tab' };
+    }
+  }
+
+  const result = await inspectStateHeadless({ origin, pageId, user });
+  return { ...result, source: 'headless' };
+}
+
+export default inspectState;