@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/docs.test.mjs

@@ -48,6 +48,14 @@ jest.unstable_mockModule('../server/createLowdefyContext.js', () => ({
 const mockBuildPageIfNeeded = jest.fn(async () => true);
 jest.unstable_mockModule('../server/jitPageBuilder.js', () => ({
   default: mockBuildPageIfNeeded,
+  reviewBuiltPage: async () => 'current',
+  syncBuildSignals: () => ({
+    registry: JSON.parse(
+      fs.readFileSync(path.join(fixtureDir, 'build', 'pageRegistry.json'), 'utf8')
+    ),
+    eventCounter: 0,
+    generation: 1,
+  }),
 }));
 
 const { default: listTypes } = await import('./listTypes.js');
@@ -61,6 +69,7 @@ const { default: searchDocs } = await import('./searchDocs.js');
 const { default: normalizeTypeKind } = await import('./normalizeTypeKind.js');
 const { default: clientErrorStore } = await import('./clientErrorStore.js');
 const { default: getBuildStatus } = await import('./getBuildStatus.js');
+const { default: serverErrorStore } = await import('./serverErrorStore.js');
 const { default: getPageConfig } = await import('./getPageConfig.js');
 const { default: readPageArtifact } = await import('./readPageArtifact.js');
 const { default: findConfig } = await import('./findConfig.js');
@@ -113,6 +122,24 @@ test('getSchema returns block schema with meta', () => {
   expect(result.meta.category).toEqual('display');
 });
 
+test('getSchema returns hazards for a block: type-attached first, then framework-level', () => {
+  const result = getSchema({ kind: 'blocks', type: 'TestBlock' });
+  expect(result.hazards.map((hazard) => hazard.id)).toEqual([
+    'test-block-hazard',
+    'visible-false-prunes-state',
+  ]);
+  // The plugin's own entry wins a duplicate id.
+  expect(result.hazards[1].message).toEqual('Plugin wording for visible: false.');
+});
+
+test('getSchema returns hazards for a request, including a meta.hazards entry', () => {
+  const result = getSchema({ kind: 'requests', type: 'WriteRequest' });
+  expect(result.hazards.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+  ]);
+});
+
 test('getSchema returns connection schema with request list', () => {
   const result = getSchema({ kind: 'connections', type: 'AxiosHttp' });
   expect(result.schema).toBeDefined();
@@ -131,6 +158,29 @@ test('getSchema returns null for unknown type', () => {
 
 test('getSchema throws for kinds without schemas', () => {
   expect(() => getSchema({ kind: 'websockets', type: 'X' })).toThrow('No schemas available');
+  expect(() => getSchema({ kind: 'tool', type: 'run_journey' })).toThrow(
+    'or journey-step for the journey step grammar'
+  );
+});
+
+test('getSchema throws when a type kind is given no type', () => {
+  expect(() => getSchema({ kind: 'blocks' })).toThrow(
+    'Getting a blocks schema requires a "type", the exact type name. Received undefined.'
+  );
+});
+
+test('getSchema returns the journey step grammar for kind journey-step', () => {
+  const result = getSchema({ kind: 'journey-step' });
+  expect(result.kind).toEqual('journey-step');
+  expect(result.schema.title).toEqual('Journey step');
+  expect(result.schema.oneOf.map((step) => step.required[0])).toContain('wait');
+});
+
+test('getSchema returns one journey step schema when type names the step', () => {
+  const result = getSchema({ kind: 'journey-step', type: 'wait' });
+  expect(result).toMatchObject({ kind: 'journey-step', type: 'wait' });
+  expect(result.schema.properties.wait.examples).toContainEqual({ wait: { ms: 500 } });
+  expect(getSchema({ kind: 'journey-step', type: 'hover' })).toBeNull();
 });
 
 test('getExamples reads example yaml from plugin dist by convention', () => {
@@ -152,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');
@@ -163,6 +220,24 @@ test('getCoreDoc resolves a doc by kind and type name', () => {
   expect(doc.slug).toEqual('operators/_get');
 });
 
+test('getCoreDoc returns hazards for the requested type when resolved by kind and type', () => {
+  const doc = getCoreDoc({ kind: 'operator', type: '_get' });
+  expect(doc.hazards.map((hazard) => hazard.id)).toEqual(['get-fixture-hazard']);
+});
+
+test('getCoreDoc does not attach hazards when resolved by slug', () => {
+  const doc = getCoreDoc({ slug: 'operators/_get' });
+  expect(doc.hazards).toBeUndefined();
+});
+
+test('getCoreDoc resolves a request doc on its connection page but keeps request hazards', () => {
+  // findDoc remaps request → connection to find the page; hazards must come
+  // from the request kind the caller asked about.
+  const doc = getCoreDoc({ kind: 'request', type: 'MongoDBFind' });
+  expect(doc.slug).toEqual('connections/mongodb');
+  expect(doc.hazards.map((hazard) => hazard.id)).toEqual(['state-in-request-properties']);
+});
+
 test('getCoreDoc returns null for unknown slug', () => {
   expect(getCoreDoc({ slug: 'nope/nope' })).toBeNull();
 });
@@ -182,6 +257,7 @@ test('getOverview includes counts and route guidance', () => {
   expect(overview).toContain('2 block types');
   expect(overview).toContain('/lowdefy-docs/schema/{kind}/{type}');
   expect(overview).toContain('lowdefy_list_types');
+  expect(overview).not.toContain('config.basePath');
 });
 
 test('normalizeTypeKind maps singular and plural, rejects unknown', () => {
@@ -200,15 +276,26 @@ test('clientErrorStore caps at 50 entries, evicting the oldest first', () => {
   expect(entries[49].index).toEqual(59);
 });
 
-test('getBuildStatus returns the build artifact plus reported client errors', () => {
-  const result = getBuildStatus();
+test('getBuildStatus returns the build artifact plus reported client and server errors', async () => {
+  serverErrorStore.push({ name: 'RequestError', message: 'Bad filter.', source: 'pages/a.yaml:3' });
+  const result = await getBuildStatus();
   expect(result.build.status).toEqual('ok');
   expect(result.clientErrors.length).toEqual(50);
+  expect(result.serverErrors).toEqual([
+    {
+      name: 'RequestError',
+      message: 'Bad filter.',
+      source: 'pages/a.yaml:3',
+      buildId: '2026-01-01T00:00:00.000Z',
+    },
+  ]);
+  expect(result.earlierErrors).toBeUndefined();
+  expect(result.pages.unbuilt).toEqual(expect.any(Number));
 });
 
-test('getBuildStatus reports unknown status when buildStatus.json is missing', () => {
+test('getBuildStatus reports unknown status when buildStatus.json is missing', async () => {
   fs.rmSync(path.join(fixtureDir, 'build', 'buildStatus.json'));
-  const result = getBuildStatus();
+  const result = await getBuildStatus();
   expect(result.build.status).toEqual('unknown');
   expect(result.build.message).toContain('No build status yet');
 });
@@ -235,7 +322,37 @@ test('findConfig resolves a known pageId to its source file', async () => {
   // A page's root block renders with blockId === pageId — open-in-editor and
   // feedback enrichment read matches[0].location.source from this result.
   expect(result.matches.length).toEqual(1);
-  expect(result.matches[0].location.source).toContain('pages/home.yaml');
+  expect(result.matches[0].location.source).toContain(path.join('pages', 'home.yaml'));
+});
+
+test('findConfig returns hazards per match for the matched node type', async () => {
+  const result = await findConfig({ id: 'my_button', pageId: 'home' });
+  expect(result.matches[0].hazards.map((hazard) => hazard.id)).toEqual([
+    'visible-false-prunes-state',
+  ]);
+});
+
+test('findConfig fires tenant-wall-lookup on a request over a walled connection only', async () => {
+  const walled = await findConfig({ id: 'req-tenant', pageId: 'other' });
+  expect(walled.matches.length).toEqual(1);
+  expect(walled.matches[0].hazards.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+    'tenant-wall-lookup',
+  ]);
+
+  const shared = await findConfig({ id: 'req-shared', pageId: 'other' });
+  expect(shared.matches.length).toEqual(1);
+  expect(shared.matches[0].hazards.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+  ]);
+});
+
+test('findConfig resolves a request connection across pages when no pageId is given', async () => {
+  const result = await findConfig({ id: 'req-tenant' });
+  expect(result.matches.length).toEqual(1);
+  expect(result.matches[0].hazards.map((hazard) => hazard.id)).toContain('tenant-wall-lookup');
 });
 
 test('findConfig scans keyMap for a matching id when no pageId is given', async () => {
@@ -243,7 +360,7 @@ test('findConfig scans keyMap for a matching id when no pageId is given', async
   const result = await findConfig({ id: 'my_button' });
   expect(result.matches.length).toEqual(2);
   expect(result.matches[0].keyPath).toEqual('root.blocks[2:my_button:Button]');
-  expect(result.matches[0].location.source).toContain('pages/home.yaml:5');
+  expect(result.matches[0].location.source).toContain(`${path.join('pages', 'home.yaml')}:5`);
   expect(result.matches[1].keyPath).toEqual('root.blocks[0:my_button:Button]');
   expect(result.note).toContain('Pass ?pageId=');
 });
@@ -255,14 +372,14 @@ test('findConfig with pageId only returns matches on that page', async () => {
   const result = await findConfig({ id: 'my_button', pageId: 'other' });
   expect(result.matches.length).toEqual(1);
   expect(result.matches[0].keyPath).toEqual('root.blocks[0:my_button:Button]');
-  expect(result.matches[0].location.source).toContain('pages/other.yaml:4');
+  expect(result.matches[0].location.source).toContain(`${path.join('pages', 'other.yaml')}:4`);
 });
 
 test('findConfig with pageId resolves the same id to each page respectively', async () => {
   const result = await findConfig({ id: 'my_button', pageId: 'home' });
   expect(result.matches.length).toEqual(1);
   expect(result.matches[0].keyPath).toEqual('root.blocks[2:my_button:Button]');
-  expect(result.matches[0].location.source).toContain('pages/home.yaml:5');
+  expect(result.matches[0].location.source).toContain(`${path.join('pages', 'home.yaml')}:5`);
 });
 
 test('findConfig scopes skeleton-built pages via the page key segment', async () => {
@@ -271,7 +388,7 @@ test('findConfig scopes skeleton-built pages via the page key segment', async ()
   const result = await findConfig({ id: 'legal_button', pageId: 'legal' });
   expect(result.matches.length).toEqual(1);
   expect(result.matches[0].keyPath).toEqual('root.pages[2:legal].blocks[0:legal_button:Button]');
-  expect(result.matches[0].location.source).toContain('pages/legal.yaml:3');
+  expect(result.matches[0].location.source).toContain(`${path.join('pages', 'legal.yaml')}:3`);
 });
 
 test('findConfig with a skeleton-built pageId does not leak other pages ids', async () => {
@@ -293,7 +410,7 @@ test('findConfig resolves a runtime list item id to its $ placeholder config id'
   const result = await findConfig({ id: 'my_list.0.item_title' });
   expect(result.matches.length).toEqual(1);
   expect(result.matches[0].keyPath).toContain('[0:my_list.$.item_title:Title]');
-  expect(result.matches[0].location.source).toContain('pages/home.yaml:9');
+  expect(result.matches[0].location.source).toContain(`${path.join('pages', 'home.yaml')}:9`);
 });
 
 test('findConfig resolves a runtime list item id within a pageId scope', async () => {
@@ -400,17 +517,56 @@ test('runRequest returns a structured error instead of throwing when callRequest
   expect(result.error).toEqual({ name: 'Error', message: 'boom' });
 });
 
-test('runRequest truncates responses larger than the size cap', async () => {
+test('runRequest writes a response larger than the inline limit to a file', async () => {
+  const rows = Array.from({ length: 500 }, (_, index) => ({ _id: index, title: 'x'.repeat(100) }));
   mockCallRequest.mockResolvedValueOnce({
     id: 'req-read',
     success: true,
     type: 'ReadOnlyRequest',
-    response: 'x'.repeat(200_000),
+    response: rows,
   });
   const result = await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
-  expect(result.truncated).toBe(true);
-  expect(result.note).toContain('truncated');
-  expect(result.response.length).toEqual(100_000);
+  expect(result.response).toBeUndefined();
+  expect(result.responseItems).toEqual(500);
+  expect(path.dirname(result.responseFile)).toEqual(
+    path.join(fs.realpathSync(fixtureDir), '.lowdefy', 'responses')
+  );
+  expect(path.basename(result.responseFile).startsWith('home.req-read-')).toBe(true);
+  expect(JSON.parse(fs.readFileSync(result.responseFile, 'utf8'))).toEqual(rows);
+});
+
+test('runRequest builds the page before it reads the request', async () => {
+  mockBuildPageIfNeeded.mockClear();
+  mockCallRequest.mockClear();
+  await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
+  expect(mockBuildPageIfNeeded).toHaveBeenCalledWith(expect.objectContaining({ pageId: 'home' }));
+  expect(mockBuildPageIfNeeded.mock.invocationCallOrder[0]).toBeLessThan(
+    mockCallRequest.mock.invocationCallOrder[0]
+  );
+});
+
+test('runRequest refuses with the build errors when the page fails to build', async () => {
+  const error = new Error('Page "home" build failed with 1 error(s).');
+  error.buildErrors = [
+    {
+      name: 'ConfigError',
+      message: 'Block type "Buton" was used but is not defined.',
+      source: 'pages/home.yaml:4',
+    },
+  ];
+  mockBuildPageIfNeeded.mockRejectedValueOnce(error);
+  mockCallRequest.mockClear();
+  const result = await runRequest({ pageId: 'home', requestId: 'req-read', honoContext: {} });
+  expect(result.refused).toBe(true);
+  expect(result.reason).toContain('fails to build');
+  expect(result.buildErrors).toEqual([
+    {
+      type: 'ConfigError',
+      message: 'Block type "Buton" was used but is not defined.',
+      source: 'pages/home.yaml:4',
+    },
+  ]);
+  expect(mockCallRequest).not.toHaveBeenCalled();
 });
 
 test('getAppMap includes built page detail and a note for unbuilt pages', () => {

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',
+  ]);
+});