@lowdefy/server-dev 0.0.0-experimental-20261007124348 → 0.0.0-experimental-20261009073700

package/client/recorder/createPairingBuffer.test.mjs

@@ -18,7 +18,8 @@
 */
 
 import { jest } from '@jest/globals';
-import { validateTraceRecord } from '@lowdefy/node-utils';
+// Only the validator: the package index loads undici, which needs Node globals jsdom lacks.
+import validateTraceRecord from '@lowdefy/node-utils/journeyTrace/validateTraceRecord.js';
 
 import createPairingBuffer, { HOLD_MS } from './createPairingBuffer.js';
 import createPasswordRedactor from './createPasswordRedactor.js';

package/lib/docs/createDocsMcpServer.js

@@ -28,7 +28,7 @@ import getBuildStatus from './getBuildStatus.js';
 import getBuildStatusAfterEdits from './getBuildStatusAfterEdits.js';
 import readJourneySession from './readJourneySession.js';
 import readProxyBuildWait from './readProxyBuildWait.js';
-import getCoreDoc from './getCoreDoc.js';
+import getDoc from './getDoc.js';
 import getExamples from './getExamples.js';
 import getOverview from './getOverview.js';
 import getPageConfig from './getPageConfig.js';
@@ -420,7 +420,7 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
   });
 
   registerDevTool('lowdefy_get_doc', ({ slug, kind, type }) => {
-    const doc = getCoreDoc({ slug, kind, type });
+    const doc = getDoc({ slug, kind, type });
     if (doc === null) {
       return notFoundResult(
         `No doc found${slug ? ` for slug "${slug}"` : ''}${
@@ -431,7 +431,9 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
     return textResult(appendHazards(doc));
   });
 
-  registerDevTool('lowdefy_search_docs', ({ query }) => textResult(searchDocs({ query })));
+  registerDevTool('lowdefy_search_docs', ({ query, source }) =>
+    textResult(searchDocs({ query, source }))
+  );
 
   registerDevTool('lowdefy_search_icons', async ({ query, limit }) =>
     textResult(await searchIcons({ query, limit }))

package/lib/docs/devToolDefinitions.js

@@ -16,6 +16,7 @@
 
 import { z } from 'zod';
 
+import docSources from './docSources.js';
 import { MAX_JOURNEY_TIMEOUT } from './validateJourneyTimeout.js';
 import { MAX_VIEWPORT_SIZE } from './validateViewport.js';
 
@@ -27,7 +28,7 @@ import { MAX_VIEWPORT_SIZE } from './validateViewport.js';
 
 const INSTRUCTIONS = `Lowdefy documentation and feedback server for this project. Lowdefy apps are YAML config composing blocks (UI), operators (logic), actions (event handlers), and connections/requests (data).
 
-Discovery workflow: start with lowdefy_overview. Use lowdefy_list_types with a kind to discover ALL installed blocks/operators/actions/connections/requests — never guess type names. Then lowdefy_get_schema and lowdefy_get_examples for the exact contract of a type, and lowdefy_get_doc / lowdefy_search_docs for concept documentation. Icons: use a semantic name (icon: edit); otherwise use a Lucide name in PascalCase (icon: Receipt) found with lowdefy_search_icons; never invent an icon name, never emoji; in any HTML string use <i data-icon="edit"></i>, data-tooltip="…" and data-popover="…", ClickableHtml with data-event for clicks (list each event in its dataEvents property; escape request and user data in the HTML), <a data-page-id="page" data-url-query="k=v"> for in-app links (never a hard-coded href; data-new-tab, not target), and data-tag="success" / data-status="success" for statuses (never inline-styled pills), <time datetime="…" data-time="relative">, data-format="currency" data-currency="USD" on raw numbers, data-avatar="Name" (never an avatar image service), data-copy, data-truncate="2", data-tone="secondary" (never inline grey colours) and, in ClickableHtml, confirm on destructive events in dataEvents ({ name: onDelete, confirm: "…" }); lowdefy_get_doc concepts/html-attributes lists them all. lowdefy_list_plugins and lowdefy_get_plugin_doc cover this project's local plugin packages.
+Discovery workflow: start with lowdefy_overview. Use lowdefy_list_types with a kind to discover ALL installed blocks/operators/actions/connections/requests — never guess type names. Then lowdefy_get_schema and lowdefy_get_examples for the exact contract of a type, and lowdefy_get_doc / lowdefy_search_docs for concept documentation. Icons: use a semantic name (icon: edit); otherwise use a Lucide name in PascalCase (icon: Receipt) found with lowdefy_search_icons; never invent an icon name, never emoji; in any HTML string use <i data-icon="edit"></i>, data-tooltip="…" and data-popover="…", ClickableHtml with data-event for clicks (list each event in its dataEvents property; escape request and user data in the HTML), <a data-page-id="page" data-url-query="k=v"> for in-app links (never a hard-coded href; data-new-tab, not target), and data-tag="success" / data-status="success" for statuses (never inline-styled pills), <time datetime="…" data-time="relative">, data-format="currency" data-currency="USD" on raw numbers, data-avatar="Name" (never an avatar image service), data-copy, data-truncate="2", data-tone="secondary" (never inline grey colours) and, in ClickableHtml, confirm on destructive events in dataEvents ({ name: onDelete, confirm: "…" }); lowdefy_get_doc concepts/html-attributes lists them all. lowdefy_search_docs and lowdefy_get_doc also cover the docs this app's own plugins and modules ship (READMEs, docs/*.md, and modules/<id>/manifest for a module's components, exports and vars), so read those before reading plugin or module source.
 
 Push events: build results, server restarts and browser/server errors arrive as notifications/message from logger "lowdefy" (data.type is one of build, restart, client_error, server_error; a build event carries status, errors, warnings and stale). Act on them without polling — lowdefy_build_status remains the full picture.
 
@@ -457,7 +458,7 @@ const devToolDefinitions = {
 
   lowdefy_get_doc: {
     description:
-      'Get a core Lowdefy documentation page as markdown. Look up by slug (e.g. "concepts/lowdefy-schema", "operators/_get") or by kind + type name. Key concept slugs: concepts/lowdefy-schema, concepts/blocks, concepts/events-and-actions, concepts/connections-and-requests, concepts/operators, concepts/page-and-app-state.' +
+      'Get a Lowdefy documentation page as markdown. Look up by slug (e.g. "concepts/lowdefy-schema", "operators/_get") or by kind + type name. Also returns the docs this app\'s own plugins and modules ship: "plugins/<package>" and "modules/<id>" for a README, "plugins/<package>/<file>" and "modules/<id>/<file>" for a docs/*.md file, and "modules/<id>/manifest" for the components, exports and vars a module declares. Key concept slugs: concepts/lowdefy-schema, concepts/blocks, concepts/events-and-actions, concepts/connections-and-requests, concepts/operators, concepts/page-and-app-state.' +
       HAZARDS_NOTE,
     inputSchema: {
       slug: z.string().optional().describe('Doc slug, e.g. "operators/_get".'),
@@ -470,9 +471,14 @@ const devToolDefinitions = {
   },
 
   lowdefy_search_docs: {
-    description: 'Search the core Lowdefy docs by keyword. Returns matching slugs with snippets.',
+    description:
+      'Search the Lowdefy docs by keywords. The query is split into words, and pages are ranked by how many match, title matches first. Returns up to 20 hits, each with its slug, snippet, source, package and version; read one with lowdefy_get_doc.',
     inputSchema: {
-      query: z.string().describe('Search keywords.'),
+      query: z.string().describe('Search keywords, e.g. "Link action pathParams".'),
+      source: z
+        .enum(docSources)
+        .optional()
+        .describe('Only search docs from this source. Default: all.'),
     },
   },
 
@@ -492,7 +498,7 @@ const devToolDefinitions = {
 
   lowdefy_get_plugin_doc: {
     description:
-      "Get markdown documentation shipped inside an installed plugin package (README, guides). Useful for this project's local custom plugins.",
+      'Get all the markdown an installed plugin package ships (README, docs/*.md) as one page. lowdefy_search_docs and lowdefy_get_doc reach the same files page by page.',
     inputSchema: {
       package: z.string().describe('The package name, e.g. "@lowdefy/blocks-antd".'),
     },

package/lib/docs/docSources.js

@@ -0,0 +1,21 @@
+/*
+  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.
+*/
+
+// Where a docs index entry comes from. Search hits name it, and the search
+// source filter takes one of these.
+const docSources = ['core', 'plugin', 'local-plugin', 'module'];
+
+export default docSources;

package/lib/docs/docs.test.mjs

@@ -202,6 +202,13 @@ test('getPluginDoc returns null for packages without docs', () => {
   expect(getPluginDoc({ packageName: 'no-such-package' })).toBeNull();
 });
 
+test('getPluginDoc reads only the app plugins, never a path out of node_modules', () => {
+  fs.writeFileSync(path.join(fixtureDir, 'README.md'), '# Server readme\n');
+  expect(getPluginDoc({ packageName: '..' })).toBeNull();
+  expect(getPluginDoc({ packageName: 'test-plugin/../..' })).toBeNull();
+  fs.rmSync(path.join(fixtureDir, 'README.md'));
+});
+
 test('getCoreDoc returns markdown by slug from docs-content', () => {
   const doc = getCoreDoc({ slug: 'operators/_get' });
   expect(doc.title).toEqual('_get');

package/lib/docs/docsIndex.test.mjs

@@ -0,0 +1,377 @@
+/*
+  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 { serializer } from '@lowdefy/helpers';
+
+// A server directory whose build lists an installed plugin, a local plugin
+// linked from outside node_modules, one of Lowdefy's own plugins and a local
+// module. resolvePluginDir reads process.cwd() at import, so the directory is
+// made and entered before the docs modules are imported.
+const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-docs-index-test-'));
+const serverDir = path.join(rootDir, 'server');
+const localPluginDir = path.join(rootDir, 'plugins', 'local-tools');
+const moduleRoot = path.join(rootDir, 'modules', 'contacts');
+
+function write(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, typeof data === 'string' ? data : JSON.stringify(data));
+}
+
+function writeBuild(name, data) {
+  const filePath = path.join(serverDir, 'build', name);
+  write(filePath, data);
+  // A rewrite inside the same millisecond would keep the old mtime.
+  const later = new Date(Date.now() + Math.floor(Math.random() * 100000));
+  fs.utimesSync(filePath, later, later);
+}
+
+function moduleEntry(overrides = {}) {
+  return {
+    id: 'contacts',
+    source: 'file:../modules/contacts',
+    moduleRoot,
+    packageRoot: moduleRoot,
+    isLocal: true,
+    consumerVars: { owner_field: 'created_by' },
+    resolvedVarCache: {},
+    varDefs: {
+      collection: { type: 'string', description: 'Collection of contacts.', default: 'contacts' },
+      labels: {
+        description: 'Display labels.',
+        properties: {
+          title: { type: 'string', description: 'List title.', default: 'Contacts' },
+        },
+      },
+      owner_field: { type: 'string', required: true, description: 'Field with the owner id.' },
+      sort: { description: 'Sort order.', default: { '_build.env': 'SORT' } },
+      template: {
+        description: 'Card template.',
+        default: { '~deferred': 'contacts:vars.template' },
+      },
+    },
+    manifest: {
+      name: 'Contacts',
+      description: 'A contact list.',
+      exports: {
+        pages: [{ id: 'contact-list', description: 'All contacts.' }],
+        components: [{ id: 'contact-card', description: 'One contact as a card.' }],
+      },
+      components: [{ id: 'contact-card', component: { '~deferred': 'contacts:c.0' } }],
+      pages: [{ id: 'contacts/contact-list', type: 'Box' }],
+    },
+    ...overrides,
+  };
+}
+
+write(path.join(serverDir, 'package.json'), { name: 'server', version: '1.0.0' });
+writeBuild('plugins/availableTypes.json', {
+  actions: {},
+  blocks: {
+    Button: { package: '@lowdefy/blocks-antd', version: '5.0.0' },
+    ButtonPlus: { package: 'fancy-blocks', version: '2.1.0' },
+    FancyCard: { package: 'fancy-blocks', version: '2.1.0' },
+    PlainCard: { package: 'fancy-blocks', version: '2.1.0' },
+    SetState: { package: 'fancy-blocks', version: '2.1.0' },
+  },
+  operators: {
+    client: { _shout: { package: 'local-tools', version: 'workspace:*' } },
+    server: { _shout: { package: 'local-tools', version: 'workspace:*' } },
+  },
+});
+writeBuild('customTypesMap.json', {
+  operators: { client: { _shout: { package: 'local-tools', version: 'workspace:*' } } },
+});
+writeBuild('installedPluginPackages.json', ['@lowdefy/blocks-antd', 'fancy-blocks', 'local-tools']);
+writeBuild('modules.json', serializer.serialize({ contacts: moduleEntry() }));
+
+write(path.join(serverDir, 'node_modules/@lowdefy/blocks-antd/package.json'), {
+  name: '@lowdefy/blocks-antd',
+  version: '5.0.0',
+});
+write(path.join(serverDir, 'node_modules/@lowdefy/blocks-antd/README.md'), '# Antd blocks\n');
+write(path.join(serverDir, 'node_modules/fancy-blocks/package.json'), {
+  name: 'fancy-blocks',
+  version: '2.1.0',
+});
+write(path.join(serverDir, 'node_modules/fancy-blocks/README.md'), '# Fancy blocks\n\nCards.\n');
+write(
+  path.join(serverDir, 'node_modules/fancy-blocks/dist/docs/FancyCard.md'),
+  '# FancyCard block\n\nA card with a gradient border.\n'
+);
+write(path.join(localPluginDir, 'package.json'), { name: 'local-tools', version: '0.3.1' });
+write(path.join(localPluginDir, 'README.md'), '# Local tools\n\nShouting operators.\n');
+write(path.join(localPluginDir, 'docs/_shout.md'), '# The _shout operator\n\nUppercases text.\n');
+// Links out of the package, a link to nowhere and a directory named like a
+// doc are never indexed.
+write(path.join(rootDir, 'outside.md'), '# Outside\n\nNot part of the plugin.\n');
+fs.symlinkSync(path.join(rootDir, 'outside.md'), path.join(localPluginDir, 'docs/leak.md'));
+fs.symlinkSync(path.join(rootDir, 'missing.md'), path.join(localPluginDir, 'docs/broken.md'));
+fs.mkdirSync(path.join(localPluginDir, 'docs/folder.md'));
+fs.symlinkSync(localPluginDir, path.join(serverDir, 'node_modules/local-tools'));
+write(path.join(moduleRoot, 'README.md'), '# Contacts module\n\nA list of people you work with.\n');
+write(path.join(moduleRoot, 'docs/setup.md'), '# Setting up contacts\n\nCreate the collection.\n');
+
+process.chdir(serverDir);
+
+const { default: getDocsIndex } = await import('./getDocsIndex.js');
+const { default: getDoc } = await import('./getDoc.js');
+const { default: listPlugins } = await import('./listPlugins.js');
+const { default: listTypes } = await import('./listTypes.js');
+const { default: searchDocs } = await import('./searchDocs.js');
+
+function appEntries() {
+  return getDocsIndex()
+    .entries.filter((entry) => entry.source !== 'core')
+    .map(({ slug, source, package: packageName, version, title }) => ({
+      slug,
+      source,
+      package: packageName,
+      version,
+      title,
+    }));
+}
+
+afterAll(() => {
+  process.chdir(os.tmpdir());
+  fs.rmSync(rootDir, { recursive: true, force: true });
+});
+
+test('docs index lists plugin and module docs, leaving out Lowdefy plugins', () => {
+  expect(appEntries()).toEqual([
+    {
+      slug: 'plugins/fancy-blocks',
+      source: 'plugin',
+      package: 'fancy-blocks',
+      version: '2.1.0',
+      title: 'fancy-blocks',
+    },
+    {
+      slug: 'plugins/fancy-blocks/FancyCard',
+      source: 'plugin',
+      package: 'fancy-blocks',
+      version: '2.1.0',
+      title: 'FancyCard block',
+    },
+    {
+      slug: 'plugins/local-tools',
+      source: 'local-plugin',
+      package: 'local-tools',
+      version: '0.3.1',
+      title: 'local-tools',
+    },
+    {
+      slug: 'plugins/local-tools/_shout',
+      source: 'local-plugin',
+      package: 'local-tools',
+      version: '0.3.1',
+      title: 'The _shout operator',
+    },
+    {
+      slug: 'modules/contacts',
+      source: 'module',
+      package: 'file:../modules/contacts',
+      version: 'local',
+      title: 'Contacts module',
+    },
+    {
+      slug: 'modules/contacts/setup',
+      source: 'module',
+      package: 'file:../modules/contacts',
+      version: 'local',
+      title: 'Setting up contacts',
+    },
+    {
+      slug: 'modules/contacts/manifest',
+      source: 'module',
+      package: 'file:../modules/contacts',
+      version: 'local',
+      title: 'contacts module: components, exports and vars',
+    },
+  ]);
+});
+
+test('a plugin type points at its own doc, else at the package README', () => {
+  expect(getDoc({ kind: 'block', type: 'FancyCard' }).slug).toEqual(
+    'plugins/fancy-blocks/FancyCard'
+  );
+  expect(getDoc({ kind: 'block', type: 'PlainCard' }).slug).toEqual('plugins/fancy-blocks');
+  expect(getDoc({ type: '_shout' }).slug).toEqual('plugins/local-tools/_shout');
+});
+
+test('a plugin type named like a core type gets its plugin doc, not the core prefix match', () => {
+  expect(getDoc({ kind: 'block', type: 'ButtonPlus' }).slug).toEqual('plugins/fancy-blocks');
+});
+
+test('a plugin type named like a core type of another kind leaves the core page to the core type', () => {
+  expect(getDoc({ type: 'SetState' }).slug).toEqual('actions/setstate');
+  expect(getDoc({ kind: 'action', type: 'SetState' }).slug).toEqual('actions/setstate');
+  expect(getDoc({ kind: 'block', type: 'SetState' }).slug).toEqual('plugins/fancy-blocks');
+});
+
+test('docs that link outside the package, link nowhere or are directories are left out', () => {
+  const slugs = getDocsIndex().entries.map((entry) => entry.slug);
+  expect(slugs).toContain('plugins/local-tools/_shout');
+  expect(slugs).not.toContain('plugins/local-tools/leak');
+  expect(slugs).not.toContain('plugins/local-tools/broken');
+  expect(slugs).not.toContain('plugins/local-tools/folder');
+  expect(getDoc({ slug: 'plugins/local-tools/leak' })).toBeNull();
+});
+
+test('getDoc returns plugin and module docs by slug with their source', () => {
+  const readme = getDoc({ slug: 'modules/contacts' });
+  expect(readme).toEqual(
+    expect.objectContaining({
+      slug: 'modules/contacts',
+      source: 'module',
+      package: 'file:../modules/contacts',
+      version: 'local',
+    })
+  );
+  expect(readme.markdown).toContain('A list of people you work with.');
+  expect(getDoc({ slug: 'plugins/local-tools' }).markdown).toContain('Shouting operators.');
+  expect(getDoc({ slug: 'plugins/@lowdefy/blocks-antd' })).toBeNull();
+});
+
+test('getDoc still returns core docs first', () => {
+  expect(getDoc({ slug: 'actions/setstate' }).slug).toEqual('actions/setstate');
+  expect(getDoc({ kind: 'action', type: 'SetState' }).slug).toEqual('actions/setstate');
+});
+
+test('module manifest page lists vars, components and exports', () => {
+  const { markdown } = getDoc({ slug: 'modules/contacts/manifest' });
+  expect(markdown).toContain('A contact list.');
+  expect(markdown).toContain(
+    '- `collection` (string, default `"contacts"`): Collection of contacts.'
+  );
+  expect(markdown).toContain('  - `labels.title` (string, default `"Contacts"`): List title.');
+  expect(markdown).toContain('- `owner_field` (string, required): Field with the owner id.');
+  expect(markdown).toContain('- `sort` (default computed): Sort order.');
+  expect(markdown).toContain('- `template` (default computed): Card template.');
+  expect(markdown).toContain('- `contact-card`: One contact as a card.');
+  expect(markdown).toContain('- `contact-list`: All contacts.');
+});
+
+test('searchDocs finds module and local plugin docs by source', () => {
+  expect(searchDocs({ query: 'owner_field', source: 'module' }).map((hit) => hit.slug)).toEqual([
+    'modules/contacts/manifest',
+  ]);
+  const [hit] = searchDocs({ query: 'shouting operators', source: 'local-plugin' });
+  expect(hit).toEqual(
+    expect.objectContaining({
+      slug: 'plugins/local-tools',
+      source: 'local-plugin',
+      package: 'local-tools',
+      version: '0.3.1',
+    })
+  );
+});
+
+test('listTypes and listPlugins name plugin doc slugs', () => {
+  const fancy = listTypes({ kind: 'blocks' }).find((item) => item.type === 'FancyCard');
+  expect(fancy.docSlug).toEqual('plugins/fancy-blocks/FancyCard');
+  const plugins = listPlugins();
+  expect(plugins.find((plugin) => plugin.package === 'local-tools').docSlug).toEqual(
+    'plugins/local-tools'
+  );
+  expect(plugins.find((plugin) => plugin.package === '@lowdefy/blocks-antd').docSlug).toBe(
+    undefined
+  );
+});
+
+test('a config-only edit leaves the docs index alone', () => {
+  const before = getDocsIndex();
+  writeBuild(
+    'modules.json',
+    serializer.serialize({
+      contacts: moduleEntry({
+        consumerVars: { owner_field: 'owner' },
+        resolvedVarCache: { 'labels.title': 'People' },
+      }),
+    })
+  );
+  writeBuild('pages/home.json', { id: 'home', type: 'Box' });
+  expect(getDocsIndex()).toBe(before);
+});
+
+test('a module change rebuilds the docs index', () => {
+  const before = getDocsIndex();
+  const changed = moduleEntry();
+  changed.varDefs.collection.description = 'Where contacts are stored.';
+  writeBuild('modules.json', serializer.serialize({ contacts: changed }));
+  const after = getDocsIndex();
+  expect(after).not.toBe(before);
+  expect(getDoc({ slug: 'modules/contacts/manifest' }).markdown).toContain(
+    'Where contacts are stored.'
+  );
+});
+
+test('a plugin change rebuilds the docs index', () => {
+  const before = getDocsIndex();
+  writeBuild('installedPluginPackages.json', [
+    '@lowdefy/blocks-antd',
+    'fancy-blocks',
+    'local-tools',
+    'x',
+  ]);
+  expect(getDocsIndex()).not.toBe(before);
+});
+
+test('a doc file added to a local plugin or module rebuilds the docs index', () => {
+  const before = getDocsIndex();
+  write(path.join(localPluginDir, 'docs/whisper.md'), '# Whispering\n\nLowercases text.\n');
+  const afterPlugin = getDocsIndex();
+  expect(afterPlugin).not.toBe(before);
+  expect(afterPlugin.entries.map((entry) => entry.slug)).toContain('plugins/local-tools/whisper');
+  write(path.join(moduleRoot, 'docs/import.md'), '# Importing contacts\n');
+  expect(getDocsIndex().entries.map((entry) => entry.slug)).toContain('modules/contacts/import');
+});
+
+test('a malformed module manifest names the bad parts on its page and breaks no docs call', () => {
+  const broken = moduleEntry({
+    id: 'broken',
+    varDefs: { good: { type: 'string' }, bad: null, nested: { properties: { inner: 'x' } } },
+    manifest: {
+      components: { card: {} },
+      exports: { pages: ['home', null, { id: 'list' }], api: 'all' },
+    },
+  });
+  writeBuild('modules.json', serializer.serialize({ contacts: moduleEntry(), broken }));
+  const { markdown } = getDoc({ slug: 'modules/broken/manifest' });
+  expect(markdown).toContain('- `good` (string)');
+  expect(markdown).toContain(
+    '- `bad`: not valid in module.lowdefy.yaml, expected an object. Received null.'
+  );
+  expect(markdown).toContain(
+    '  - `nested.inner`: not valid in module.lowdefy.yaml, expected an object. Received "x".'
+  );
+  expect(markdown).toContain(
+    '- `components`: not valid in module.lowdefy.yaml, expected a list. Received {"card":{}}.'
+  );
+  expect(markdown).toContain(
+    '- `exports.pages.0`: not valid in module.lowdefy.yaml, expected an object with a string id. Received "home".'
+  );
+  expect(markdown).toContain('- `list`');
+  expect(markdown).toContain(
+    '- `exports.api`: not valid in module.lowdefy.yaml, expected a list. Received "all".'
+  );
+  expect(searchDocs({ query: 'not valid', source: 'module' }).map((hit) => hit.slug)).toEqual([
+    'modules/broken/manifest',
+  ]);
+});

package/lib/docs/getDoc.js

@@ -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 { type } from '@lowdefy/helpers';
+
+import getCoreDoc from './getCoreDoc.js';
+import getDocsIndex from './getDocsIndex.js';
+import readDocEntry from './readDocEntry.js';
+
+function singularKind({ kind }) {
+  return type.isNone(kind) ? null : String(kind).toLowerCase().replace(/s$/, '');
+}
+
+function findTypeSlug({ typeDocs, kind, typeName, anyKind }) {
+  const exactKind = singularKind({ kind });
+  if (!type.isNone(exactKind) && typeDocs.has(`${exactKind}:${typeName}`)) {
+    return typeDocs.get(`${exactKind}:${typeName}`);
+  }
+  if (!type.isNone(exactKind) && !anyKind) {
+    return null;
+  }
+  for (const [key, slug] of typeDocs) {
+    if (key.slice(key.indexOf(':') + 1) === typeName) {
+      return slug;
+    }
+  }
+  return null;
+}
+
+// With no kind, a core page for exactly this type name belongs to a Lowdefy
+// type, unless a plugin registers the name in that same kind and so replaces
+// it. A plugin type of another kind must not take that page's place.
+function namesOtherCoreType({ entries, typeDocs, kind, typeName }) {
+  if (!type.isNone(kind)) {
+    return false;
+  }
+  return entries.some(
+    (entry) =>
+      entry.source === 'core' &&
+      entry.typeName === typeName &&
+      !typeDocs.has(`${entry.kind}:${typeName}`)
+  );
+}
+
+function makePluginDoc({ entries, slug }) {
+  const entry = entries.find((item) => item.source !== 'core' && item.slug === slug);
+  if (type.isUndefined(entry)) {
+    return null;
+  }
+  return {
+    slug: entry.slug,
+    title: entry.title,
+    section: entry.section,
+    source: entry.source,
+    package: entry.package,
+    version: entry.version,
+    markdown: readDocEntry({ entry }),
+  };
+}
+
+// A doc page by slug or by type: the core docs, and the docs the app's own
+// plugins and modules ship. A type a plugin registers is looked up in its
+// plugin's docs before the core docs, whose type lookup falls back to a
+// prefix match (MongoDB covers MongoDBFind) that would claim a plugin type
+// named like a core one. Plugin types the caller names under another kind
+// (the kinds get_doc takes do not cover every kind) come last.
+function getDoc({ slug, kind, type: typeName }) {
+  const { entries, typeDocs } = getDocsIndex();
+  if (!type.isNone(slug)) {
+    return getCoreDoc({ slug }) ?? makePluginDoc({ entries, slug });
+  }
+  if (type.isNone(typeName)) {
+    return null;
+  }
+  const pluginSlug = findTypeSlug({ typeDocs, kind, typeName, anyKind: false });
+  if (!type.isNone(pluginSlug) && !namesOtherCoreType({ entries, typeDocs, kind, typeName })) {
+    return makePluginDoc({ entries, slug: pluginSlug });
+  }
+  const coreDoc = getCoreDoc({ kind, type: typeName });
+  if (!type.isNone(coreDoc)) {
+    return coreDoc;
+  }
+  const otherKindSlug = findTypeSlug({ typeDocs, kind, typeName, anyKind: true });
+  return type.isNone(otherKindSlug) ? null : makePluginDoc({ entries, slug: otherKindSlug });
+}
+
+export default getDoc;