@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/getBuildStatus.js

@@ -14,24 +14,72 @@
   limitations under the License.
 */
 
+import getLowdefyVersion from '../../manager/utils/getLowdefyVersion.mjs';
+import checkAgentFiles from './checkAgentFiles.js';
 import clientErrorStore from './clientErrorStore.js';
+import getBuildId from './getBuildId.js';
+import getPageBuildStatus from './getPageBuildStatus.js';
+import serverErrorStore from './serverErrorStore.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
+const EARLIER_ERRORS_NOTE =
+  'Reported under an earlier build, before the latest config build or page edit, so they may already be fixed. Reload or re-run the page to see whether they still happen.';
+
+function splitByBuild({ entries, buildId }) {
+  return {
+    current: entries.filter((entry) => entry.buildId === buildId),
+    earlier: entries.filter((entry) => entry.buildId !== buildId),
+  };
+}
+
+// Notices about Lowdefy's agent block (see checkAgentFiles), checked on every
+// read: the root files are not watched, so a stored result would outlive a fix.
+async function getAgentFiles() {
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const lowdefyVersion = await getLowdefyVersion({
+    directories: { config: configDirectory },
+  }).catch(() => null);
+  return checkAgentFiles({ configDirectory, lowdefyVersion });
+}
+
 // 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() {
+// build/buildStatus.json), the page builds (see getPageBuildStatus), plus
+// recent browser errors reported via POST /api/client-error, plus recent server
+// errors (request, endpoint, MCP and agent tool failures) collected by
+// createHandleError. Lets an agent check "did my last edit work?" without
+// tailing terminal logs. Errors reported under an earlier build are listed
+// apart under earlierErrors. `buildId` names the build being served now.
+// Notices about the agent files come under agentFiles, apart from the build's
+// warnings, and only when there are any.
+async function getBuildStatus({ checked } = {}) {
   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 {
+  const buildId = getBuildId();
+  const clientErrors = splitByBuild({ entries: clientErrorStore.list(), buildId });
+  const serverErrors = splitByBuild({ entries: serverErrorStore.list(), buildId });
+  const status = {
+    buildId,
     build,
-    clientErrors: clientErrorStore.list(),
+    pages: await getPageBuildStatus({ checked }),
+    clientErrors: clientErrors.current,
+    serverErrors: serverErrors.current,
   };
+  if (clientErrors.earlier.length > 0 || serverErrors.earlier.length > 0) {
+    status.earlierErrors = {
+      note: EARLIER_ERRORS_NOTE,
+      clientErrors: clientErrors.earlier,
+      serverErrors: serverErrors.earlier,
+    };
+  }
+  const agentFiles = await getAgentFiles();
+  if (agentFiles.length > 0) {
+    status.agentFiles = agentFiles;
+  }
+  return status;
 }
 
 export default getBuildStatus;

package/lib/docs/getBuildStatus.test.mjs

@@ -0,0 +1,133 @@
+/*
+  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';
+
+const mockClientErrors = jest.fn();
+jest.unstable_mockModule('./clientErrorStore.js', () => ({ default: { list: mockClientErrors } }));
+const mockServerErrors = jest.fn();
+jest.unstable_mockModule('./serverErrorStore.js', () => ({ default: { list: mockServerErrors } }));
+jest.unstable_mockModule('./getBuildId.js', () => ({ default: () => 'build-2' }));
+const mockGetPageBuildStatus = jest.fn(() => ({ unbuilt: 0 }));
+jest.unstable_mockModule('./getPageBuildStatus.js', () => ({ default: mockGetPageBuildStatus }));
+jest.unstable_mockModule('./readBuildArtifact.js', () => ({
+  default: () => ({ status: 'ok', errors: [], warnings: ['a build warning'] }),
+}));
+
+const { default: getBuildStatus } = await import('./getBuildStatus.js');
+
+test('getBuildStatus lists errors from earlier builds apart from the current ones', async () => {
+  mockClientErrors.mockReturnValue([
+    { message: 'old render error', buildId: 'build-1' },
+    { message: 'live render error', buildId: 'build-2' },
+  ]);
+  mockServerErrors.mockReturnValue([{ message: 'old request error', buildId: 'build-1' }]);
+
+  const status = await getBuildStatus();
+
+  expect(status.clientErrors).toEqual([{ message: 'live render error', buildId: 'build-2' }]);
+  expect(status.serverErrors).toEqual([]);
+  expect(status.earlierErrors).toEqual({
+    note: expect.stringContaining('may already be fixed'),
+    clientErrors: [{ message: 'old render error', buildId: 'build-1' }],
+    serverErrors: [{ message: 'old request error', buildId: 'build-1' }],
+  });
+});
+
+test('getBuildStatus leaves out earlierErrors when every error is current', async () => {
+  mockClientErrors.mockReturnValue([{ message: 'live', buildId: 'build-2' }]);
+  mockServerErrors.mockReturnValue([]);
+
+  expect((await getBuildStatus()).earlierErrors).toBeUndefined();
+});
+
+test('getBuildStatus passes the pages build status just built to the page status', async () => {
+  mockClientErrors.mockReturnValue([]);
+  mockServerErrors.mockReturnValue([]);
+
+  const status = await getBuildStatus({ checked: ['home'] });
+
+  expect(mockGetPageBuildStatus).toHaveBeenCalledWith({ checked: ['home'] });
+  expect(status.pages).toEqual({ unbuilt: 0 });
+  expect(status.build.status).toBe('ok');
+});
+
+test('getBuildStatus names the build being served as a top-level buildId', async () => {
+  mockClientErrors.mockReturnValue([]);
+  mockServerErrors.mockReturnValue([]);
+
+  expect((await getBuildStatus()).buildId).toBe('build-2');
+});
+
+describe('agentFiles', () => {
+  let root;
+  let previousConfigDirectory;
+
+  beforeEach(() => {
+    mockClientErrors.mockReturnValue([]);
+    mockServerErrors.mockReturnValue([]);
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-build-status-'));
+    fs.mkdirSync(path.join(root, '.git'));
+    fs.writeFileSync(path.join(root, 'lowdefy.yaml'), 'lowdefy: 7.1.0\n');
+    fs.writeFileSync(path.join(root, 'CLAUDE.md'), '@AGENTS.md\n');
+    previousConfigDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
+    process.env.LOWDEFY_DIRECTORY_CONFIG = root;
+  });
+
+  afterEach(() => {
+    if (previousConfigDirectory === undefined) {
+      delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+    } else {
+      process.env.LOWDEFY_DIRECTORY_CONFIG = previousConfigDirectory;
+    }
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  const writeBlock = (version) =>
+    fs.writeFileSync(
+      path.join(root, 'AGENTS.md'),
+      `<!-- BEGIN:lowdefy-agent-rules version=${version} -->\n<!-- END:lowdefy-agent-rules -->\n`
+    );
+
+  test('lists notices apart from the build warnings, and a fix shows on the next call', async () => {
+    writeBlock('7.0.0');
+
+    const before = await getBuildStatus();
+    expect(before.agentFiles).toEqual([
+      {
+        code: 'version_mismatch',
+        message: expect.stringContaining('npx lowdefy@7.1.0 agent-setup'),
+      },
+    ]);
+    expect(before.build.warnings).toEqual(['a build warning']);
+
+    writeBlock('7.1.2');
+
+    const after = await getBuildStatus();
+    expect(after).not.toHaveProperty('agentFiles');
+    expect(after.build.warnings).toEqual(['a build warning']);
+  });
+
+  test('leaves agentFiles out when lowdefy.yaml cannot be read', async () => {
+    writeBlock('6.0.0');
+    fs.rmSync(path.join(root, 'lowdefy.yaml'));
+
+    expect(await getBuildStatus()).not.toHaveProperty('agentFiles');
+  });
+});

package/lib/docs/getBuildStatusAfterEdits.js

@@ -0,0 +1,35 @@
+/*
+  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 buildEditedPages from './buildEditedPages.js';
+import getBuildStatus from './getBuildStatus.js';
+import waitForBuild from './waitForBuild.js';
+
+// Build status for wait: true. Waits until the dev server has processed the
+// latest edits, then builds the pages they touched, so the answer covers
+// those pages whether or not anything has requested them since. A request
+// through the manager's proxy has been held there until the edits - and any
+// restart they caused - were processed (proxyWait), so it does not wait again.
+async function getBuildStatusAfterEdits({ proxyWait } = {}) {
+  const waited = proxyWait ?? (await waitForBuild());
+  if (!waited.settled) {
+    return { ...waited, ...(await getBuildStatus()) };
+  }
+  const checked = await buildEditedPages();
+  return { ...waited, ...(await getBuildStatus({ checked })) };
+}
+
+export default getBuildStatusAfterEdits;

package/lib/docs/getBuildStatusAfterEdits.test.mjs

@@ -0,0 +1,76 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+const mockWaitForBuild = jest.fn();
+jest.unstable_mockModule('./waitForBuild.js', () => ({ default: mockWaitForBuild }));
+const mockBuildEditedPages = jest.fn();
+jest.unstable_mockModule('./buildEditedPages.js', () => ({ default: mockBuildEditedPages }));
+const mockGetBuildStatus = jest.fn(({ checked } = {}) => ({ build: { status: 'ok' }, checked }));
+jest.unstable_mockModule('./getBuildStatus.js', () => ({ default: mockGetBuildStatus }));
+
+const { default: getBuildStatusAfterEdits } = await import('./getBuildStatusAfterEdits.js');
+const { default: readProxyBuildWait } = await import('./readProxyBuildWait.js');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+test('getBuildStatusAfterEdits builds the edited pages once the edits are processed', async () => {
+  mockWaitForBuild.mockResolvedValue({ settled: true, sawBuild: false, waitedMs: 1000 });
+  mockBuildEditedPages.mockResolvedValue(['home']);
+
+  const result = await getBuildStatusAfterEdits();
+
+  expect(mockWaitForBuild.mock.invocationCallOrder[0]).toBeLessThan(
+    mockBuildEditedPages.mock.invocationCallOrder[0]
+  );
+  expect(result).toEqual({
+    settled: true,
+    sawBuild: false,
+    waitedMs: 1000,
+    build: { status: 'ok' },
+    checked: ['home'],
+  });
+});
+
+test('getBuildStatusAfterEdits builds no pages when the wait gave up', async () => {
+  mockWaitForBuild.mockResolvedValue({ settled: false, waitedMs: 60000 });
+
+  const result = await getBuildStatusAfterEdits();
+
+  expect(mockBuildEditedPages).not.toHaveBeenCalled();
+  expect(result.settled).toBe(false);
+  expect(result.checked).toBeUndefined();
+});
+
+test('getBuildStatusAfterEdits uses the wait the manager proxy made instead of waiting again', async () => {
+  mockBuildEditedPages.mockResolvedValue([]);
+
+  const result = await getBuildStatusAfterEdits({
+    proxyWait: readProxyBuildWait({
+      getHeader: () => 'settled=true&sawBuild=true&waitedMs=4200',
+    }),
+  });
+
+  expect(mockWaitForBuild).not.toHaveBeenCalled();
+  expect(result).toMatchObject({ settled: true, sawBuild: true, waitedMs: 4200, checked: [] });
+});
+
+test('readProxyBuildWait returns null for a request that did not come through the proxy wait', () => {
+  expect(readProxyBuildWait({ getHeader: () => undefined })).toBe(null);
+});

package/lib/docs/getCoreDoc.js

@@ -19,6 +19,7 @@ import path from 'node:path';
 import { type } from '@lowdefy/helpers';
 
 import getDocsManifest from './getDocsManifest.js';
+import getHazards from './getHazards.js';
 
 function findDoc({ manifest, slug, kind, typeName }) {
   if (!type.isNone(slug)) {
@@ -57,7 +58,14 @@ function getCoreDoc({ slug, kind, type: typeName }) {
     return null;
   }
   const markdown = fs.readFileSync(path.join(manifest.contentDir, doc.path), 'utf8');
-  return { slug: doc.slug, title: doc.title, section: doc.section, markdown };
+  const result = { slug: doc.slug, title: doc.title, section: doc.section, markdown };
+  // Hazards belong to the type the caller asked about, not to the doc page:
+  // findDoc remaps requests onto their connection's page, and a request
+  // must carry its own hazards rather than inherit the connection's.
+  if (type.isNone(slug) && !type.isNone(typeName)) {
+    result.hazards = getHazards({ kind, type: typeName });
+  }
+  return result;
 }
 
 export default getCoreDoc;

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;

package/lib/docs/getDocsIndex.js

@@ -0,0 +1,152 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+import getDocsManifest from './getDocsManifest.js';
+import listModuleDocEntries from './listModuleDocEntries.js';
+import listPackageDocFiles from './listPackageDocFiles.js';
+import listPluginDocEntries from './listPluginDocEntries.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+// The build artifacts that change when the app's plugins change. The dev
+// build leaves an artifact whose bytes are unchanged with its old mtime, so a
+// config-only edit leaves their stats alone.
+const PLUGIN_ARTIFACTS = [
+  'plugins/availableTypes.json',
+  'customTypesMap.json',
+  'installedPluginPackages.json',
+];
+
+let coreEntries;
+let index = null;
+let indexKey = null;
+let localDirs = [];
+let modulesStat = null;
+let modules = null;
+let modulesKey = null;
+
+// The core docs change only with a release, so their entries are read once.
+function getCoreEntries() {
+  if (!type.isUndefined(coreEntries)) {
+    return coreEntries;
+  }
+  const manifest = getDocsManifest();
+  if (type.isNone(manifest)) {
+    coreEntries = [];
+    return coreEntries;
+  }
+  coreEntries = manifest.docs.map((doc) => ({
+    ...doc,
+    source: 'core',
+    package: '@lowdefy/docs-content',
+    version: manifest.version,
+    filePath: path.join(manifest.contentDir, doc.path),
+  }));
+  return coreEntries;
+}
+
+function statKey(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return 'none';
+  }
+}
+
+// Component bodies are left out: only the ids and descriptions are shown.
+function componentsKey({ components }) {
+  if (!type.isArray(components)) {
+    return components;
+  }
+  return components.map((item) => (type.isObject(item) ? [item.id, item.description] : item));
+}
+
+// modules.json also holds what a config edit changes (resolved var values,
+// page bodies), so only the parts the docs read are compared.
+function readModules() {
+  const stat = statKey(path.join(process.cwd(), 'build', 'modules.json'));
+  if (stat === modulesStat) {
+    return;
+  }
+  modulesStat = stat;
+  modules = readBuildArtifact({ name: 'modules.json', deserialize: true }) ?? {};
+  modulesKey = JSON.stringify(
+    Object.values(modules).map((moduleEntry) => [
+      moduleEntry.id,
+      moduleEntry.source,
+      moduleEntry.moduleRoot,
+      moduleEntry.isLocal,
+      moduleEntry.varDefs,
+      moduleEntry.manifest?.name,
+      moduleEntry.manifest?.description,
+      moduleEntry.manifest?.exports,
+      componentsKey({ components: moduleEntry.manifest?.components }),
+    ])
+  );
+}
+
+// Doc files of local plugins and modules can be added, removed or edited
+// while the server runs.
+function localDocsKey() {
+  return localDirs
+    .map((dir) => {
+      const { readme, docs } = listPackageDocFiles({ dir });
+      return [readme, ...docs]
+        .filter((filePath) => !type.isNone(filePath))
+        .map((filePath) => `${filePath}@${statKey(filePath)}`);
+    })
+    .join('|');
+}
+
+function createIndexKey() {
+  readModules();
+  const buildDirectory = path.join(process.cwd(), 'build');
+  return [
+    ...PLUGIN_ARTIFACTS.map((name) => statKey(path.join(buildDirectory, name))),
+    modulesKey,
+    localDocsKey(),
+  ].join('\n');
+}
+
+function buildIndex() {
+  const plugins = listPluginDocEntries();
+  const moduleDocs = listModuleDocEntries({ modules });
+  localDirs = [...plugins.localDirs, ...moduleDocs.localDirs];
+  return {
+    entries: [...getCoreEntries(), ...plugins.entries, ...moduleDocs.entries],
+    typeDocs: plugins.typeDocs,
+  };
+}
+
+// Every doc the app can use: the core docs, and the docs its own plugins and
+// modules ship. Rebuilt on the first call after the plugins or modules change.
+// The key of a rebuilt index names the local doc files the build found, so it
+// is taken again after the build.
+function getDocsIndex() {
+  const key = createIndexKey();
+  if (key === indexKey) {
+    return index;
+  }
+  index = buildIndex();
+  indexKey = createIndexKey();
+  return index;
+}
+
+export default getDocsIndex;