@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/getBuildStatus.js

@@ -14,24 +14,98 @@
   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),
+  };
+}
+
+// buildStatus.json covers the config build only; pages build later, on first
+// request. So that build.status alone answers "does the app build", an ok
+// config build with a failed page reads pages_failed, and failedPages names
+// those pages. A failed page changed since that build is left out: its failure
+// may already be fixed, and pages.changedSinceBuild lists it until it is
+// rebuilt. A config build that is not ok keeps its status and names no pages,
+// since the config is what to fix first. The page errors stay under
+// pages.failed either way. configStatus keeps the config build's own status for
+// callers that wait on a published config build, whatever the pages do.
+function withFailedPages({ build, pages }) {
+  const configBuild = { ...build, configStatus: build.status };
+  if (build.status !== 'ok') {
+    return configBuild;
+  }
+  const changedSinceBuild = new Set(pages.changedSinceBuild ?? []);
+  const failedPages = (pages.failed ?? [])
+    .map(({ pageId }) => pageId)
+    .filter((pageId) => !changedSinceBuild.has(pageId));
+  if (failedPages.length === 0) {
+    return configBuild;
+  }
+  return { ...configBuild, status: 'pages_failed', failedPages };
+}
+
+// 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, with page failures folded in by withFailedPages),
+// 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 {
-    build,
-    clientErrors: clientErrorStore.list(),
+  const buildId = getBuildId();
+  const clientErrors = splitByBuild({ entries: clientErrorStore.list(), buildId });
+  const serverErrors = splitByBuild({ entries: serverErrorStore.list(), buildId });
+  const pages = await getPageBuildStatus({ checked });
+  const status = {
+    buildId,
+    build: withFailedPages({ build, pages }),
+    pages,
+    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,229 @@
+/*
+  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 }));
+const okBuild = () => ({ status: 'ok', errors: [], warnings: ['a build warning'] });
+const mockReadBuildArtifact = jest.fn(okBuild);
+jest.unstable_mockModule('./readBuildArtifact.js', () => ({ default: mockReadBuildArtifact }));
+
+const { default: getBuildStatus } = await import('./getBuildStatus.js');
+
+describe('page failures in build.status', () => {
+  const failed = [
+    { pageId: 'orders', errors: [{ type: 'ConfigError', message: 'Bad.', source: null }] },
+    { pageId: 'invoices', errors: [{ type: 'ConfigError', message: 'Worse.', source: null }] },
+  ];
+
+  beforeEach(() => {
+    mockClientErrors.mockReturnValue([]);
+    mockServerErrors.mockReturnValue([]);
+  });
+
+  afterEach(() => {
+    mockReadBuildArtifact.mockImplementation(okBuild);
+    mockGetPageBuildStatus.mockImplementation(() => ({ unbuilt: 0 }));
+  });
+
+  test('reads pages_failed and names the pages when the config builds but a page fails', async () => {
+    mockGetPageBuildStatus.mockResolvedValue({ failed, unbuilt: 0 });
+
+    const status = await getBuildStatus();
+
+    expect(status.build).toEqual({
+      status: 'pages_failed',
+      configStatus: 'ok',
+      errors: [],
+      warnings: ['a build warning'],
+      failedPages: ['orders', 'invoices'],
+    });
+    expect(status.pages.failed).toEqual(failed);
+  });
+
+  test('keeps error and names no pages when the config build failed too', async () => {
+    mockReadBuildArtifact.mockReturnValue({
+      status: 'error',
+      errors: ['Bad config.'],
+      warnings: [],
+    });
+    mockGetPageBuildStatus.mockResolvedValue({ failed: failed.slice(0, 1), unbuilt: 0 });
+
+    const status = await getBuildStatus();
+
+    expect(status.build.status).toBe('error');
+    expect(status.build.configStatus).toBe('error');
+    expect(status.build).not.toHaveProperty('failedPages');
+    expect(status.pages.failed).toEqual(failed.slice(0, 1));
+  });
+
+  test('keeps unknown and names no pages before the first config build is written', async () => {
+    mockReadBuildArtifact.mockReturnValue(null);
+    mockGetPageBuildStatus.mockResolvedValue({ failed, unbuilt: 0 });
+
+    const { build } = await getBuildStatus();
+
+    expect(build.status).toBe('unknown');
+    expect(build.configStatus).toBe('unknown');
+    expect(build).not.toHaveProperty('failedPages');
+  });
+
+  test('leaves out a failed page changed since its last build, since its failure may be fixed', async () => {
+    mockGetPageBuildStatus.mockResolvedValue({
+      failed,
+      changedSinceBuild: ['orders'],
+      unbuilt: 0,
+    });
+
+    const { build } = await getBuildStatus();
+
+    expect(build.status).toBe('pages_failed');
+    expect(build.failedPages).toEqual(['invoices']);
+  });
+
+  test('stays ok when every failed page has changed since its last build', async () => {
+    mockGetPageBuildStatus.mockResolvedValue({
+      failed: failed.slice(0, 1),
+      changedSinceBuild: ['orders', 'home'],
+      unbuilt: 0,
+    });
+
+    const status = await getBuildStatus();
+
+    expect(status.build.status).toBe('ok');
+    expect(status.build).not.toHaveProperty('failedPages');
+    expect(status.pages.failed).toEqual(failed.slice(0, 1));
+  });
+
+  test('stays ok with no failedPages when every built page builds', async () => {
+    mockGetPageBuildStatus.mockResolvedValue({ checked: ['orders'], unbuilt: 2 });
+
+    const { build } = await getBuildStatus({ checked: ['orders'] });
+
+    expect(build.status).toBe('ok');
+    expect(build.configStatus).toBe('ok');
+    expect(build).not.toHaveProperty('failedPages');
+  });
+});
+
+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;