@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/addWriteFlags.js

@@ -0,0 +1,77 @@
+/*
+  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 readRoutineSteps from './readRoutineSteps.js';
+
+// A request writes when its type declares meta.checkWrite: true. An endpoint
+// writes when a step of its routine has such a type, or when an endpoint it
+// reaches through CallApi writes, so a caller that writes only through a
+// nested endpoint still reads as a write.
+async function addWriteFlags({ requests, endpoints, readConfigFile, requestSchemas }) {
+  function isWriteType(stepType) {
+    return requestSchemas[stepType]?.meta?.checkWrite === true;
+  }
+
+  const routines = new Map();
+  async function readEndpoint(endpointId) {
+    if (!routines.has(endpointId)) {
+      const artifact = await readConfigFile(`api/${endpointId}.json`);
+      const steps = readRoutineSteps({ routine: artifact.routine });
+      routines.set(endpointId, {
+        writes: steps.some((step) => isWriteType(step.type)),
+        targets: steps
+          .filter((step) => step.type === 'CallApi' && type.isString(step.properties?.endpointId))
+          .map((step) => step.properties.endpointId),
+      });
+    }
+    return routines.get(endpointId);
+  }
+
+  async function reachesWrite(endpointId) {
+    const visited = new Set([endpointId]);
+    const queue = [endpointId];
+    while (queue.length > 0) {
+      const { writes, targets } = await readEndpoint(queue.shift());
+      if (writes) {
+        return true;
+      }
+      targets
+        .filter((target) => !visited.has(target))
+        .forEach((target) => {
+          visited.add(target);
+          queue.push(target);
+        });
+    }
+    return false;
+  }
+
+  const requestsWithWrite = [];
+  for (const request of requests) {
+    const artifact = await readConfigFile(
+      `pages/${request.pageId}/requests/${request.requestId}.json`
+    );
+    requestsWithWrite.push({ ...request, write: isWriteType(artifact?.type) });
+  }
+  const endpointsWithWrite = [];
+  for (const endpoint of endpoints) {
+    endpointsWithWrite.push({ ...endpoint, write: await reachesWrite(endpoint.endpointId) });
+  }
+  return { requests: requestsWithWrite, endpoints: endpointsWithWrite };
+}
+
+export default addWriteFlags;

package/lib/docs/buildEditedPages.js

@@ -0,0 +1,50 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import path from 'node:path';
+
+import buildPageIfNeeded from '../server/jitPageBuilder.js';
+import reviewPageBuilds from './reviewPageBuilds.js';
+
+// Page builds share one build context, and most of a build is waiting on file
+// reads, so a few run at once; more would only compete for the same process.
+const CONCURRENT_BUILDS = 4;
+
+// Builds every page an edit touched (see reviewPageBuilds), the same build a
+// page request runs (with its per-page lock), so build status covers pages
+// nobody has opened since the edit. A failed build is recorded by the page
+// builder and reported from there.
+async function buildEditedPages() {
+  const { edited } = await reviewPageBuilds();
+  const buildDirectory = path.join(process.cwd(), 'build');
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const queue = [...edited];
+  async function buildNext() {
+    while (queue.length > 0) {
+      const pageId = queue.shift();
+      try {
+        await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+      } catch {
+        // Reported by getPageBuildStatus from the page's build record.
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(CONCURRENT_BUILDS, queue.length) }, buildNext));
+  return edited;
+}
+
+export { CONCURRENT_BUILDS };
+export default buildEditedPages;

package/lib/docs/buildWaitHeader.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.
+*/
+
+// The header the manager's proxy adds to a build-status wait it has already
+// waited out (see readProxyBuildWait).
+const buildWaitHeader = 'x-lowdefy-build-wait';
+
+export default buildWaitHeader;

package/lib/docs/captureAnnotatedScreenshot.js

@@ -17,34 +17,40 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { urlQuery as urlQueryFn } from '@lowdefy/helpers';
+
 import drawAnnotationsSvg from '../../client/feedback/drawAnnotationsSvg.js';
 import { getBrowser, openPage } from './getBrowser.js';
+import noBrowserError from './noBrowserError.js';
+import readPagePath from './readPagePath.js';
+import withBrowserSlot from './withBrowserSlot.js';
 
-// Renders the page headless at the batch's recorded viewport/scroll, injects
-// the developer's drawn shapes and element outlines as an SVG layer inside
-// the page, screenshots the composite, and saves it under the config dir's
-// .lowdefy/annotations/ (gitignored). The saved path goes into the formatted
-// feedback text so an agent can read the image. Never throws — returns
-// { path } or { error }.
-async function captureAnnotatedScreenshot({ origin, batch, fileName }) {
+// Renders the batch's page instance (pageId, pathParams, urlQuery) headless at
+// the batch's recorded viewport/scroll, injects the developer's drawn shapes
+// and element outlines as an SVG layer inside the page, screenshots the
+// composite, and saves it under the config dir's .lowdefy/annotations/
+// (gitignored). The saved path goes into the formatted feedback text so an
+// agent can read the image. Never throws — returns { path } or { error }.
+async function captureInBrowser({ origin, batch, fileName }) {
   let browser;
   try {
     browser = await getBrowser();
   } catch (error) {
-    return { error: `No Chromium available for the annotated screenshot (${error.message}).` };
+    return { error: noBrowserError(error) };
   }
 
   const viewport = batch.viewport ?? {};
   const width = viewport.width || 1280;
   const height = viewport.height || 800;
-  const urlQuery = batch.urlQuery && batch.urlQuery !== '?' ? batch.urlQuery : '';
-
   let context;
   try {
     const opened = await openPage({
       browser,
       origin,
-      pageId: `${batch.pageId}${urlQuery}`,
+      pageId: batch.pageId,
+      path: readPagePath({ pageId: batch.pageId }),
+      pathParams: batch.pathParams,
+      urlQuery: urlQueryFn.parse(batch.urlQuery ?? ''),
       width,
       height,
     });
@@ -75,7 +81,7 @@ async function captureAnnotatedScreenshot({ origin, batch, fileName }) {
       fileName ?? `${batch.pageId}-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
     fs.writeFileSync(path.join(dir, name), buffer);
 
-    return { path: path.join('.lowdefy', 'annotations', name) };
+    return { path: path.posix.join('.lowdefy', 'annotations', name) };
   } catch (error) {
     return { error: `Failed to capture annotated screenshot: ${error.message}` };
   } finally {
@@ -85,4 +91,9 @@ async function captureAnnotatedScreenshot({ origin, batch, fileName }) {
   }
 }
 
+// One browser slot for the whole capture.
+async function captureAnnotatedScreenshot({ origin, batch, fileName }) {
+  return withBrowserSlot({ task: () => captureInBrowser({ origin, batch, fileName }) });
+}
+
 export default captureAnnotatedScreenshot;

package/lib/docs/checkAgentFiles.js

@@ -0,0 +1,148 @@
+/*
+  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 path from 'path';
+
+const BLOCK_BEGIN = '<!-- BEGIN:lowdefy-agent-rules';
+const MARKER = /<!-- BEGIN:lowdefy-agent-rules\b([^>]*?)-->/;
+
+// The nearest folder holding .git (a directory in a checkout, a file in a
+// linked worktree), walking up from the config directory; outside git, the
+// config directory. The same rule as the CLI's agentSetup/findProjectRoot.js,
+// kept here because server-dev does not depend on the CLI.
+function findProjectRoot(configDirectory) {
+  let directory = configDirectory;
+  for (;;) {
+    if (fs.existsSync(path.join(directory, '.git'))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return configDirectory;
+    }
+    directory = parent;
+  }
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// The nearest AGENTS.md, then CLAUDE.md, holding Lowdefy's block, from the
+// config directory up to the project root.
+function findBlock({ configDirectory, projectRoot }) {
+  let directory = configDirectory;
+  for (;;) {
+    for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+      const text = readText(path.join(directory, name));
+      if (text?.includes(BLOCK_BEGIN)) {
+        const attributes = text.match(MARKER)?.[1] ?? '';
+        return {
+          directory,
+          name,
+          version: attributes.match(/\bversion=(\S+)/)?.[1] ?? null,
+        };
+      }
+    }
+    if (directory === projectRoot) {
+      return null;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return null;
+    }
+    directory = parent;
+  }
+}
+
+function majorMinor(version) {
+  const match = /^v?(\d+)\.(\d+)/.exec(version ?? '');
+  return match ? `${match[1]}.${match[2]}` : null;
+}
+
+function hasClaudeImport(directory) {
+  const text = readText(path.join(directory, 'CLAUDE.md'));
+  return text !== null && text.split(/\r?\n/).some((line) => line.trim() === '@AGENTS.md');
+}
+
+function hasLowdefyMcpServer(projectRoot) {
+  const text = readText(path.join(projectRoot, '.mcp.json'));
+  if (text === null) {
+    return false;
+  }
+  try {
+    return Boolean(JSON.parse(text)?.mcpServers?.lowdefy);
+  } catch {
+    return false;
+  }
+}
+
+// Checks Lowdefy's agent block that `lowdefy agent-setup` writes: missing,
+// from a different major.minor version than the app runs, or in AGENTS.md
+// while the CLAUDE.md beside it lacks its import. Returns notices for build status's
+// agentFiles field, never build warnings. Only reads; computed on every call,
+// since the root files are not watched.
+function checkAgentFiles({ configDirectory, lowdefyVersion }) {
+  if (typeof lowdefyVersion !== 'string' || lowdefyVersion === '') {
+    return [];
+  }
+  const start = path.resolve(configDirectory);
+  const projectRoot = findProjectRoot(start);
+  const block = findBlock({ configDirectory: start, projectRoot });
+  // agent-setup refuses `lowdefy: local` apps, so neither fix can run there.
+  const local = lowdefyVersion === 'local';
+  const notices = [];
+
+  if (!block) {
+    if (!local && hasLowdefyMcpServer(projectRoot)) {
+      notices.push({
+        code: 'block_missing',
+        message: `Lowdefy's agent instructions are missing from AGENTS.md. Tell the developer; don't run agent-setup yourself. They add them with \`npx lowdefy@${lowdefyVersion} agent-setup\`.`,
+      });
+    }
+    return notices;
+  }
+
+  const appMinor = majorMinor(lowdefyVersion);
+  if (!local && appMinor !== null && majorMinor(block.version) !== appMinor) {
+    const from = majorMinor(block.version)
+      ? `Lowdefy ${block.version}`
+      : 'an unknown Lowdefy version';
+    notices.push({
+      code: 'version_mismatch',
+      message: `Agent instructions are from ${from}, this app runs ${lowdefyVersion}, so some of their guidance may not apply. Tell the developer; don't run agent-setup yourself. They fix it with \`npx lowdefy@${lowdefyVersion} agent-setup\`, unless another app in this repository runs a different version.`,
+    });
+  }
+
+  // agent-setup writes CLAUDE.md beside the AGENTS.md it chose, and `@AGENTS.md`
+  // resolves relative to the file holding it, so the import is looked for
+  // there: the project root, or a --project-directory below it.
+  if (block.name === 'AGENTS.md' && !hasClaudeImport(block.directory)) {
+    notices.push({
+      code: 'claude_import_missing',
+      message:
+        'Claude Code may not read AGENTS.md. Tell the developer: add `@AGENTS.md` to the top of CLAUDE.md, or run agent-setup.',
+    });
+  }
+  return notices;
+}
+
+export default checkAgentFiles;

package/lib/docs/checkAgentFiles.test.mjs

@@ -0,0 +1,225 @@
+/*
+  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 checkAgentFiles from './checkAgentFiles.js';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-agent-files-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+function write(relativePath, text) {
+  const filePath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, text);
+}
+
+function block(version) {
+  const attribute = version ? ` version=${version}` : '';
+  return `# Project\n\n<!-- BEGIN:lowdefy-agent-rules${attribute} -->\n## Lowdefy\n<!-- END:lowdefy-agent-rules -->\n`;
+}
+
+// A git checkout with the app at its root, AGENTS.md holding the block and
+// CLAUDE.md importing it.
+function checkout({ version = '7.1.4' } = {}) {
+  fs.mkdirSync(path.join(root, '.git'));
+  write('AGENTS.md', block(version));
+  write('CLAUDE.md', '@AGENTS.md\n');
+}
+
+const check = (lowdefyVersion, configDirectory = root) =>
+  checkAgentFiles({ configDirectory, lowdefyVersion });
+
+describe('version', () => {
+  test('a patch difference is no notice', () => {
+    checkout({ version: '7.1.4' });
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('a minor difference is a version_mismatch with the fix', () => {
+    checkout({ version: '7.0.3' });
+    expect(check('7.1.0')).toEqual([
+      {
+        code: 'version_mismatch',
+        message:
+          "Agent instructions are from Lowdefy 7.0.3, this app runs 7.1.0, so some of their guidance may not apply. Tell the developer; don't run agent-setup yourself. They fix it with `npx lowdefy@7.1.0 agent-setup`, unless another app in this repository runs a different version.",
+      },
+    ]);
+  });
+
+  test('a marker without a version is a version_mismatch from an unknown version', () => {
+    checkout({ version: null });
+    const notices = check('7.1.0');
+    expect(notices).toHaveLength(1);
+    expect(notices[0].code).toBe('version_mismatch');
+    expect(notices[0].message).toMatch(/^Agent instructions are from an unknown Lowdefy version, /);
+  });
+
+  test('an app on local is not version-checked', () => {
+    checkout({ version: '6.0.0' });
+    expect(check('local')).toEqual([]);
+  });
+
+  test('no notices when the app version cannot be read', () => {
+    checkout({ version: '6.0.0' });
+    expect(check(null)).toEqual([]);
+  });
+});
+
+describe('Claude import', () => {
+  test('block in AGENTS.md and no root CLAUDE.md is claude_import_missing', () => {
+    checkout();
+    fs.rmSync(path.join(root, 'CLAUDE.md'));
+    expect(check('7.1.0')).toEqual([
+      {
+        code: 'claude_import_missing',
+        message:
+          'Claude Code may not read AGENTS.md. Tell the developer: add `@AGENTS.md` to the top of CLAUDE.md, or run agent-setup.',
+      },
+    ]);
+  });
+
+  test('the import on any line of the root CLAUDE.md counts', () => {
+    checkout();
+    write('CLAUDE.md', '# Notes\n\n  @AGENTS.md  \nMore.\n');
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('a line that only mentions @AGENTS.md is not the import', () => {
+    checkout();
+    write('CLAUDE.md', 'See @AGENTS.md for rules.\n');
+    expect(check('7.1.0').map((notice) => notice.code)).toEqual(['claude_import_missing']);
+  });
+
+  test('only .claude/CLAUDE.md importing it is claude_import_missing', () => {
+    checkout();
+    fs.rmSync(path.join(root, 'CLAUDE.md'));
+    write('.claude/CLAUDE.md', '@AGENTS.md\n');
+    expect(check('7.1.0').map((notice) => notice.code)).toEqual(['claude_import_missing']);
+  });
+
+  test('block in CLAUDE.md needs no import', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('CLAUDE.md', block('7.1.0'));
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('the import is looked for beside an AGENTS.md below the git root', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('CLAUDE.md', '@AGENTS.md\n');
+    write('apps/web/AGENTS.md', block('7.1.0'));
+    expect(check('7.1.0', path.join(root, 'apps/web')).map((notice) => notice.code)).toEqual([
+      'claude_import_missing',
+    ]);
+    write('apps/web/CLAUDE.md', '@AGENTS.md\n');
+    expect(check('7.1.0', path.join(root, 'apps/web'))).toEqual([]);
+  });
+
+  test('applies to an app on local', () => {
+    checkout();
+    fs.rmSync(path.join(root, 'CLAUDE.md'));
+    expect(check('local').map((notice) => notice.code)).toEqual(['claude_import_missing']);
+  });
+});
+
+describe('finding the block', () => {
+  test('a block in the app folder below the git root is found', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('apps/web/CLAUDE.md', '@AGENTS.md\n');
+    write('.mcp.json', JSON.stringify({ mcpServers: { lowdefy: {} } }));
+    write('apps/web/AGENTS.md', block('7.0.0'));
+    expect(check('7.1.0', path.join(root, 'apps/web')).map((notice) => notice.code)).toEqual([
+      'version_mismatch',
+    ]);
+  });
+
+  test('the nearest block wins, AGENTS.md before CLAUDE.md', () => {
+    checkout({ version: '6.0.0' });
+    write('apps/web/CLAUDE.md', block('7.1.0'));
+    write('apps/web/AGENTS.md', 'No block here.\n');
+    expect(check('7.1.0', path.join(root, 'apps/web'))).toEqual([]);
+  });
+
+  test('a nested worktree never reads the outer checkout', () => {
+    checkout({ version: '6.0.0' });
+    write('.mcp.json', JSON.stringify({ mcpServers: { lowdefy: {} } }));
+    write('worktrees/feature/.git', 'gitdir: ../../.git/worktrees/feature\n');
+    write('worktrees/feature/app/lowdefy.yaml', 'lowdefy: 7.1.0\n');
+    expect(check('7.1.0', path.join(root, 'worktrees/feature/app'))).toEqual([]);
+  });
+
+  test('outside git, only the config directory is read', () => {
+    write('AGENTS.md', block('6.0.0'));
+    fs.mkdirSync(path.join(root, 'app'));
+    expect(check('7.1.0', path.join(root, 'app'))).toEqual([]);
+  });
+});
+
+describe('missing block', () => {
+  test('.mcp.json naming the lowdefy server is block_missing', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('.mcp.json', JSON.stringify({ mcpServers: { lowdefy: { command: 'npx' } } }));
+    expect(check('7.1.0')).toEqual([
+      {
+        code: 'block_missing',
+        message:
+          "Lowdefy's agent instructions are missing from AGENTS.md. Tell the developer; don't run agent-setup yourself. They add them with `npx lowdefy@7.1.0 agent-setup`.",
+      },
+    ]);
+  });
+
+  test('no .mcp.json is no notice', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('.mcp.json with only other servers is no notice', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('.mcp.json', JSON.stringify({ mcpServers: { other: {} } }));
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('an unparsable .mcp.json is no notice', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('.mcp.json', '{ not json');
+    expect(check('7.1.0')).toEqual([]);
+  });
+
+  test('an app on local is no notice', () => {
+    fs.mkdirSync(path.join(root, '.git'));
+    write('.mcp.json', JSON.stringify({ mcpServers: { lowdefy: {} } }));
+    expect(check('local')).toEqual([]);
+  });
+});
+
+test('never writes a file', () => {
+  fs.mkdirSync(path.join(root, '.git'));
+  write('AGENTS.md', block('6.0.0'));
+  write('.mcp.json', JSON.stringify({ mcpServers: { lowdefy: {} } }));
+  const before = fs.readdirSync(root).sort();
+  check('7.1.0');
+  expect(fs.readdirSync(root).sort()).toEqual(before);
+  expect(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8')).toBe(block('6.0.0'));
+});