lowdefy 5.6.0 → 6.1.0

package/dist/commands/agentSetup/agentSetup.js

@@ -0,0 +1,85 @@
+/*
+  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 'path';
+import findProjectRoot from './findProjectRoot.js';
+import getDevCommand from './getDevCommand.js';
+import upsertAgentsMdSection from './upsertAgentsMdSection.js';
+import upsertClaudeSettings from './upsertClaudeSettings.js';
+import upsertMcpServer from './upsertMcpServer.js';
+import writeSkillFile from './writeSkillFile.js';
+// Resolves where agent files should be written (the project root an agent is
+// launched from, not the app config directory) and the app's path relative
+// to it, so generated instructions work from that root.
+function resolveDirectories({ context }) {
+    const configDirectory = context.directories.config;
+    const projectDirectory = context.options.projectDirectory ? path.resolve(context.options.projectDirectory) : findProjectRoot({
+        configDirectory
+    });
+    const relative = path.relative(projectDirectory, configDirectory);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        context.logger.warn(`Project directory '${projectDirectory}' does not contain the config directory '${configDirectory}' - writing agent files into the config directory instead.`);
+        return {
+            projectDirectory: configDirectory,
+            appPath: ''
+        };
+    }
+    return {
+        projectDirectory,
+        appPath: relative.split(path.sep).join('/')
+    };
+}
+async function agentSetup({ context }) {
+    context.logger.info('Setting up this project for AI coding agents.');
+    const port = context.options.port;
+    const { projectDirectory, appPath } = resolveDirectories({
+        context
+    });
+    if (appPath !== '') {
+        context.logger.info(`Project root detected at '${projectDirectory}' - writing agent files there. The Lowdefy config is in '${appPath}/'.`);
+    }
+    const devCommand = getDevCommand({
+        configDirectory: context.directories.config,
+        projectDirectory
+    });
+    const runCommand = appPath === '' ? devCommand : `cd ${appPath} && ${devCommand}`;
+    await upsertMcpServer({
+        context,
+        projectDirectory,
+        port
+    });
+    await upsertClaudeSettings({
+        context,
+        projectDirectory
+    });
+    await writeSkillFile({
+        context,
+        projectDirectory,
+        appPath,
+        port
+    });
+    await upsertAgentsMdSection({
+        context,
+        projectDirectory,
+        appPath,
+        port,
+        devCommand: runCommand
+    });
+    await context.sendTelemetry();
+    context.logger.info('Annotate the app: press Cmd/Ctrl+/ in the browser to point, draw, and copy feedback, then paste it into your agent session.');
+    context.logger.info({
+        spin: 'succeed'
+    }, 'Project set up for AI coding agents.');
+}
+export default agentSetup;

package/dist/commands/agentSetup/agentsMd.js

@@ -0,0 +1,59 @@
+/*
+  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.
+*/ function agentsMd({ port, devCommand, appPath }) {
+    const appDescription = appPath === '' ? 'This project is a [Lowdefy](https://lowdefy.com) app' : `This project contains a [Lowdefy](https://lowdefy.com) app in \`${appPath}/\``;
+    return `## Lowdefy
+
+${appDescription}: a web app defined in YAML config files
+rather than hand-written code. Pages compose **blocks** (UI components), **operators** (logic
+like \`_if\`, \`_get\`, \`_state\`), **actions** (event handlers), and **connections/requests**
+(databases and APIs).
+
+### Running the app
+
+Start the development server with:
+
+\`\`\`bash
+${devCommand}
+\`\`\`
+
+This serves the app at \`http://localhost:${port}\` and hot-reloads on config changes.
+
+### Looking up types, schemas, and docs
+
+While the dev server is running, it serves documentation for every block, operator, action,
+connection, and request type installed in this project (including local plugins) at
+\`http://localhost:${port}/lowdefy-docs\`, and as MCP tools via the \`lowdefy-docs\` MCP server
+(see \`.mcp.json\`).
+
+**Never guess type names or properties.** Before writing or editing Lowdefy config:
+
+1. List available types: call \`lowdefy_list_types\` (or \`GET /lowdefy-docs/{kind}\`, e.g.
+   \`/lowdefy-docs/blocks\`) — this includes this project's local plugins.
+2. Get the exact schema: call \`lowdefy_get_schema\` (or \`GET /lowdefy-docs/schema/{kind}/{type}\`).
+3. See real usage: call \`lowdefy_get_examples\` (or \`GET /lowdefy-docs/examples/{type}\`).
+4. Read concept docs or search: call \`lowdefy_get_doc\` or \`lowdefy_search_docs\` (or
+   \`GET /lowdefy-docs/content/{slug}\`, \`GET /lowdefy-docs/search?q=...\`).
+
+### Visual feedback
+
+While the dev server is running, developers can press \`Cmd/Ctrl+/\` in the browser to point at,
+draw on, and comment on the running app; the annotation helper copies an agent-readable feedback
+block to their clipboard, which they paste into the agent session. Pasted blocks start with
+"Feedback:" and include the config file and line each annotation refers to — treat them as
+precise UI feedback.
+`;
+}
+export default agentsMd;

package/dist/commands/agentSetup/buildMcpServerEntry.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.
+*/ function buildMcpServerEntry({ port }) {
+    return {
+        type: 'http',
+        url: `http://localhost:${port}/lowdefy-docs/mcp`
+    };
+}
+export default buildMcpServerEntry;

package/dist/commands/agentSetup/findProjectRoot.js

@@ -0,0 +1,39 @@
+/*
+  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';
+// Coding agents (Claude Code, Codex, Cursor) discover .mcp.json, .claude/
+// skills, and instructions files from the directory they are launched in —
+// in practice the git checkout root. In a monorepo where the Lowdefy app
+// lives in a subdirectory, agent files written into the app directory are
+// never found, so agent-setup targets the nearest ancestor containing .git
+// instead. Falls back to the config directory when the app is not inside a
+// git repository (single-directory projects keep today's behavior).
+function findProjectRoot({ configDirectory }) {
+    let directory = configDirectory;
+    for(;;){
+        // .git is a directory in normal checkouts but a file in worktrees and
+        // submodules — existsSync covers both.
+        if (fs.existsSync(path.join(directory, '.git'))) {
+            return directory;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return configDirectory;
+        }
+        directory = parent;
+    }
+}
+export default findProjectRoot;

package/dist/commands/agentSetup/getDevCommand.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 fs from 'fs';
+import path from 'path';
+import { type } from '@lowdefy/helpers';
+const defaultCommand = 'npx lowdefy dev';
+// Prefer a package.json script that already runs "lowdefy dev" over the npx fallback,
+// using the package manager implied by the project's lockfile. Scripts come
+// from the app's own package.json; the lockfile may live at the workspace
+// root in a monorepo, so both directories are checked.
+function getDevCommand({ configDirectory, projectDirectory = configDirectory }) {
+    const packageJsonPath = path.join(configDirectory, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return defaultCommand;
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    } catch  {
+        return defaultCommand;
+    }
+    const scripts = packageJson.scripts ?? {};
+    const scriptName = Object.keys(scripts).find((name)=>scripts[name].includes('lowdefy dev'));
+    if (type.isNone(scriptName)) {
+        return defaultCommand;
+    }
+    function lockfileExists(lockfileName) {
+        return fs.existsSync(path.join(configDirectory, lockfileName)) || fs.existsSync(path.join(projectDirectory, lockfileName));
+    }
+    if (lockfileExists('pnpm-lock.yaml')) {
+        return `pnpm ${scriptName}`;
+    }
+    if (lockfileExists('yarn.lock')) {
+        return `yarn ${scriptName}`;
+    }
+    return `npm run ${scriptName}`;
+}
+export default getDevCommand;

package/dist/commands/agentSetup/skillMd.js

@@ -0,0 +1,48 @@
+/*
+  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.
+*/ function skillMd({ port, appPath }) {
+    const appPathLine = appPath === '' ? '' : `\nThe Lowdefy app config (lowdefy.yaml, pages, requests) lives in \`${appPath}/\`.\n`;
+    return `---
+name: lowdefy-config
+description: Use when writing or editing Lowdefy YAML config — pages, blocks, operators, actions, connections, or requests. Looks up exact type names, schemas, and examples from the running dev server instead of guessing.
+---
+
+# Writing Lowdefy config
+
+The dev server serves docs for everything installed in this project at
+\`http://localhost:${port}/lowdefy-docs\` (also as MCP tools via the \`lowdefy-docs\` server).
+${appPathLine}
+Never guess type names or properties. Before writing config:
+
+1. Call \`lowdefy_list_types\` (or \`GET /lowdefy-docs/blocks\`, \`/lowdefy-docs/operators\`,
+   \`/lowdefy-docs/actions\`, \`/lowdefy-docs/connections\`, \`/lowdefy-docs/requests\`) to find the exact
+   type name — this includes this project's local plugins.
+2. Call \`lowdefy_get_schema\` (or \`GET /lowdefy-docs/schema/{kind}/{type}\`) for the
+   exact properties and events of that type.
+3. Call \`lowdefy_get_examples\` (or \`GET /lowdefy-docs/examples/{type}\`) to see real
+   usage YAML for blocks.
+4. For concepts (state, operators, events, requests), call \`lowdefy_get_doc\`
+   or \`lowdefy_search_docs\`.
+
+## Visual feedback
+
+Developers can press \`Cmd/Ctrl+/\` in the running app to point at, draw on, and comment on
+what's on screen; the annotation helper copies an agent-readable feedback block to their
+clipboard, which they paste to you. Pasted blocks start with "Feedback:" and include the
+config file and line each annotation refers to — treat them as precise UI feedback and use
+\`lowdefy_inspect_state\` for the page's live state.
+`;
+}
+export default skillMd;

package/dist/commands/agentSetup/upsertAgentsMdSection.js

@@ -0,0 +1,63 @@
+/*
+  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 'path';
+import { readFile, writeFile } from '@lowdefy/node-utils';
+import { type } from '@lowdefy/helpers';
+import agentsMd from './agentsMd.js';
+const lowdefyHeadingPattern = /^##\s+Lowdefy\b/m;
+// Appends a "## Lowdefy" section to the project's existing agent instructions
+// file instead of creating a competing one: an existing AGENTS.md wins, then
+// an existing CLAUDE.md, and only when neither exists is an AGENTS.md
+// created. Never overwrites — the file may already document the rest of the
+// project.
+async function upsertAgentsMdSection({ context, projectDirectory, appPath, port, devCommand }) {
+    const candidates = [
+        'AGENTS.md',
+        'CLAUDE.md'
+    ].map((fileName)=>({
+            fileName,
+            filePath: path.join(projectDirectory, fileName)
+        }));
+    const existingFiles = [];
+    for (const candidate of candidates){
+        const content = await readFile(candidate.filePath);
+        if (!type.isNone(content)) {
+            existingFiles.push({
+                ...candidate,
+                content
+            });
+        }
+    }
+    const withSection = existingFiles.find((file)=>lowdefyHeadingPattern.test(file.content));
+    if (withSection) {
+        context.logger.info(`'${withSection.fileName}' already has a 'Lowdefy' section - skipping.`);
+        return;
+    }
+    const section = agentsMd({
+        port,
+        devCommand,
+        appPath
+    });
+    if (existingFiles.length === 0) {
+        await writeFile(path.join(projectDirectory, 'AGENTS.md'), `${section}`);
+        context.logger.info("Created 'AGENTS.md'.");
+        return;
+    }
+    const target = existingFiles[0];
+    const updated = `${target.content.replace(/\s+$/, '')}\n\n${section}`;
+    await writeFile(target.filePath, updated);
+    context.logger.info(`Added a 'Lowdefy' section to '${target.fileName}'.`);
+}
+export default upsertAgentsMdSection;

package/dist/commands/agentSetup/upsertClaudeSettings.js

@@ -0,0 +1,56 @@
+/*
+  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 'path';
+import { readFile, writeFile } from '@lowdefy/node-utils';
+import { type } from '@lowdefy/helpers';
+const MCP_SERVER_NAME = 'lowdefy-docs';
+// Pre-approves the lowdefy-docs MCP server for Claude Code so no developer is
+// prompted to trust it. Written to the committed '.claude/settings.json'
+// rather than the gitignored '.claude/settings.local.json' on purpose, so the
+// whole team inherits the approval from version control.
+async function upsertClaudeSettings({ context, projectDirectory }) {
+    const settingsRelativePath = path.join('.claude', 'settings.json');
+    const settingsPath = path.join(projectDirectory, settingsRelativePath);
+    const existing = await readFile(settingsPath);
+    if (type.isNone(existing)) {
+        const settings = {
+            enabledMcpjsonServers: [
+                MCP_SERVER_NAME
+            ]
+        };
+        await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+        context.logger.info(`Created '${settingsRelativePath}'.`);
+        return;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(existing);
+    } catch  {
+        context.logger.warn(`Could not parse existing '${settingsRelativePath}' as JSON - leaving it unchanged. Add '${MCP_SERVER_NAME}' to 'enabledMcpjsonServers' manually.`);
+        return;
+    }
+    const enabled = type.isArray(settings.enabledMcpjsonServers) ? settings.enabledMcpjsonServers : [];
+    if (enabled.includes(MCP_SERVER_NAME)) {
+        context.logger.info(`'${settingsRelativePath}' already enables the '${MCP_SERVER_NAME}' MCP server - leaving it unchanged.`);
+        return;
+    }
+    settings.enabledMcpjsonServers = [
+        ...enabled,
+        MCP_SERVER_NAME
+    ];
+    await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    context.logger.info(`Enabled the '${MCP_SERVER_NAME}' MCP server in '${settingsRelativePath}'.`);
+}
+export default upsertClaudeSettings;

package/dist/commands/agentSetup/upsertMcpServer.js

@@ -0,0 +1,83 @@
+/*
+  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';
+import { readFile, writeFile } from '@lowdefy/node-utils';
+import { type } from '@lowdefy/helpers';
+import buildMcpServerEntry from './buildMcpServerEntry.js';
+// A .mcp.json left in the app subdirectory by a pre-monorepo-fix run of
+// agent-setup is never discovered by agents launched from the project root.
+function warnStaleConfigDirMcpJson({ context, projectDirectory }) {
+    const configDirectory = context.directories.config;
+    if (projectDirectory === configDirectory) {
+        return;
+    }
+    if (fs.existsSync(path.join(configDirectory, '.mcp.json'))) {
+        context.logger.warn(`Found a '.mcp.json' in '${configDirectory}' - agents launched from the project root will not discover it. If it only contains the 'lowdefy-docs' server, it can be removed.`);
+    }
+}
+// Merges the "lowdefy-docs" MCP server into an existing .mcp.json instead of overwriting it,
+// since a project's .mcp.json may already declare other MCP servers.
+async function upsertMcpServer({ context, projectDirectory, port }) {
+    const mcpJsonPath = path.join(projectDirectory, '.mcp.json');
+    const existing = await readFile(mcpJsonPath);
+    const mcpServerEntry = buildMcpServerEntry({
+        port
+    });
+    if (type.isNone(existing)) {
+        const mcpJson = {
+            mcpServers: {
+                'lowdefy-docs': mcpServerEntry
+            }
+        };
+        await writeFile(mcpJsonPath, `${JSON.stringify(mcpJson, null, 2)}\n`);
+        context.logger.info("Created '.mcp.json'.");
+        warnStaleConfigDirMcpJson({
+            context,
+            projectDirectory
+        });
+        return;
+    }
+    let mcpJson;
+    try {
+        mcpJson = JSON.parse(existing);
+    } catch  {
+        context.logger.warn("Could not parse existing '.mcp.json' as JSON - leaving it unchanged. Add the 'lowdefy-docs' MCP server manually:\n" + JSON.stringify({
+            mcpServers: {
+                'lowdefy-docs': mcpServerEntry
+            }
+        }, null, 2));
+        return;
+    }
+    mcpJson.mcpServers = mcpJson.mcpServers ?? {};
+    const currentEntry = mcpJson.mcpServers['lowdefy-docs'];
+    if (!type.isNone(currentEntry)) {
+        if (currentEntry.url === mcpServerEntry.url) {
+            context.logger.info("'.mcp.json' already has a 'lowdefy-docs' MCP server - leaving it unchanged.");
+        } else {
+            // Likely a second Lowdefy app in the same project, or a stale port.
+            context.logger.warn(`'.mcp.json' already has a 'lowdefy-docs' MCP server pointing at '${currentEntry.url}', expected '${mcpServerEntry.url}' - leaving it unchanged. Rerun with --port to match, or add this app manually under a different server name.`);
+        }
+        return;
+    }
+    mcpJson.mcpServers['lowdefy-docs'] = mcpServerEntry;
+    await writeFile(mcpJsonPath, `${JSON.stringify(mcpJson, null, 2)}\n`);
+    context.logger.info("Added the 'lowdefy-docs' MCP server to '.mcp.json'.");
+    warnStaleConfigDirMcpJson({
+        context,
+        projectDirectory
+    });
+}
+export default upsertMcpServer;

package/dist/commands/agentSetup/writeSkillFile.js

@@ -0,0 +1,32 @@
+/*
+  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';
+import { writeFile } from '@lowdefy/node-utils';
+import skillMd from './skillMd.js';
+const skillRelativePath = path.join('.claude', 'skills', 'lowdefy-config', 'SKILL.md');
+async function writeSkillFile({ context, projectDirectory, appPath, port }) {
+    const skillPath = path.join(projectDirectory, skillRelativePath);
+    if (fs.existsSync(skillPath)) {
+        context.logger.info(`'${skillRelativePath}' already exists - skipping.`);
+        return;
+    }
+    await writeFile(skillPath, skillMd({
+        port,
+        appPath
+    }));
+    context.logger.info(`Created '${skillRelativePath}'.`);
+}
+export default writeSkillFile;

package/dist/commands/build/build.js

@@ -18,7 +18,7 @@ import getServer from '../../utils/getServer.js';
 import installServer from '../../utils/installServer.js';
 import resetServerPackageJson from '../../utils/resetServerPackageJson.js';
 import runLowdefyBuild from '../../utils/runLowdefyBuild.js';
-import runNextBuild from '../../utils/runNextBuild.js';
+import runClientBuild from '../../utils/runClientBuild.js';
 const serverPackages = {
     e2e: '@lowdefy/server-e2e'
 };
@@ -55,8 +55,8 @@ async function build({ context }) {
         context,
         directory
     });
-    if (context.options.nextBuild !== false) {
-        await runNextBuild({
+    if (context.options.clientBuild !== false && context.options.nextBuild !== false) {
+        await runClientBuild({
             context,
             directory
         });

package/dist/commands/dev/dev.js

@@ -12,28 +12,33 @@
   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 addCustomPluginsAsDeps from '../../utils/addCustomPluginsAsDeps.js';
-import checkPortAvailable from '../../utils/checkPortAvailable.js';
+*/ import { findAvailablePort } from '@lowdefy/node-utils';
+import addCustomPluginsAsDeps from '../../utils/addCustomPluginsAsDeps.js';
 import ensurePnpmWorkspaceYaml from '../../utils/ensurePnpmWorkspaceYaml.js';
 import installServer from '../../utils/installServer.js';
-import resetServerPackageJson from '../../utils/resetServerPackageJson.js';
 import runDevServer from './runDevServer.js';
 import getServer from '../../utils/getServer.js';
 async function dev({ context }) {
     const directory = context.directories.dev;
     context.logger.info('Starting development server.');
-    await checkPortAvailable({
+    const port = await findAvailablePort({
         port: context.options.port
     });
+    if (port !== context.options.port) {
+        context.logger.warn(`Port ${context.options.port} is in use, using port ${port} instead.`);
+        context.options.port = port;
+    }
     await getServer({
         context,
         packageName: '@lowdefy/server-dev',
         directory
     });
-    await resetServerPackageJson({
-        context,
-        directory
-    });
+    // Dev keeps the plugin dependency set accumulated by previous sessions —
+    // resetting package.json to package.original.json here would uninstall
+    // JIT-added plugin packages, churn the lockfile (invalidating Vite's
+    // optimizer cache), and force reinstalls on first navigation. The full
+    // `lowdefy build` recomputes the complete set, and getServer replaces
+    // package.json when the lowdefy version changes.
     await addCustomPluginsAsDeps({
         context,
         directory

package/dist/commands/dev/resolveMockUser.js

@@ -0,0 +1,37 @@
+/*
+  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.
+*/ const defaultMockUser = {
+    sub: 'lowdefy-dev',
+    id: 'lowdefy-dev',
+    name: 'Lowdefy Dev User',
+    roles: []
+};
+// Turns the `--mock-user [user]` CLI option into the JSON string the dev server
+// reads from LOWDEFY_DEV_USER. Bare flag (commander yields `true`) → a default
+// roleless user. A supplied value is validated here so an invalid `--mock-user`
+// fails at the CLI with a clear message instead of deep in the server runtime.
+function resolveMockUser(mockUser) {
+    if (mockUser === true) {
+        return JSON.stringify(defaultMockUser);
+    }
+    try {
+        return JSON.stringify(JSON.parse(mockUser));
+    } catch (error) {
+        throw new Error(`Invalid --mock-user value. Expected a JSON user object, received ${JSON.stringify(mockUser)}.`, {
+            cause: error
+        });
+    }
+}
+export default resolveMockUser;