lowdefy 5.6.0 → 6.0.0

package/dist/commands/init-vercel/README.md

@@ -1,30 +1,104 @@
 # Vercel Deployment
 
-To deploy a Lowdefy app on Vercel a custom install script needs to run to download the server and build the Lowdefy configuration. This script creates a Next.js application that can then be built by Vercel. The install script needs to be placed in an empty directory and it installs the server in its working directory - by default this directory is called `deploy`.
+Lowdefy v6 builds a [Hono](https://hono.dev) server serving a [Vite](https://vite.dev)-built React
+client. To run that on Vercel, the app is deployed via the
+[Build Output API](https://vercel.com/docs/build-output-api) as **static assets on the CDN plus one
+Serverless Function** that runs the Hono app for every dynamic request.
 
-The script can be created using the `init-vercel` CLI command, or the following file can be created at `<config-directory>/deploy/vercel.install.sh`:
+`lowdefy init-vercel` scaffolds everything into a `deploy/` directory next to your `lowdefy.yaml`:
 
-###### vercel.install.sh
+- `vercel.install.sh` — install command: downloads the Lowdefy server into `deploy/` and builds the
+  config artifacts (skips the client build, which the build step runs).
+- `vercel.build.sh` — build command: builds the Vite client, then runs `lowdefy vercel-output` to
+  assemble the Vercel Build Output (`.vercel/output/`).
+- `vercel.json` — sets the build command; the deployment itself is described by the generated
+  `.vercel/output/config.json`.
 
-```bash
-# Read Lowdefy version from lowdefy.yaml using sed
-LOWDEFY_VERSION=$(sed -nE "s/lowdefy:(.*)/\1/p" ../lowdefy.yaml)
-# Substitution params are to trim whitespace from the LOWDEFY_VERSION var
-npx lowdefy@${LOWDEFY_VERSION//[[:space:]]/} build --config-directory ../  --server-directory . --no-next-build --log-level=debug
+## Project settings
+
+In the Vercel project settings:
+
+- **Framework Preset:** `Other` (not Next.js — Lowdefy v6 is not a Next.js app).
+- **Root Directory:** `<config-directory>/deploy`
+  - `<config-directory>` is where your `lowdefy.yaml` lives. If `lowdefy.yaml` is at the repo root,
+    use `deploy`; if it is in `apps/my-app`, use `apps/my-app/deploy`.
+- **Install Command:** `bash vercel.install.sh`.
+- **Build Command:** comes from `vercel.json` (`bash vercel.build.sh`); leave the dashboard override
+  off. There is no Output Directory setting — the build emits `.vercel/output`, which Vercel detects
+  automatically.
+- Enable **"Include files outside the root directory in the Build Step"** — the Lowdefy config
+  usually lives in the parent of `deploy/`.
+
+## Public files
+
+Files in your app's `public/` directory (favicon, icons, images, `manifest.webmanifest`, etc.) are
+copied into `dist/client` by Vite during the build, placed in `.vercel/output/static`, and served by
+the Vercel CDN — no extra configuration needed.
+
+## Secrets and environment variables
+
+Set secrets in the Vercel project's Environment Variables, prefixed with `LOWDEFY_SECRET_`. Use
+`AUTH_SECRET` (and, for OAuth, `AUTH_URL`) for auth. Different values can be set for Production and
+Preview deployments.
+
+## Scheduled endpoints (cron)
+
+An `Api` (or `InternalApi`) endpoint can declare `schedules` to run its routine on a timer:
+
+```yaml
+id: purge-stale-conversations
+type: Api
+schedules:
+  - cron: '0 6 * * *'
+    payload: { mode: full }
+  - cron: '*/15 * * * *'
+    payload: { mode: incremental }
+routine:
+  - id: purge
+    type: MongoDBDeleteMany
+    connectionId: conversations
+    properties:
+      filter: { updatedAt: { $lt: { _payload: cutoff } } }
 ```
 
-To deploy a Lowdefy app on Vercel:
+`lowdefy vercel-output` turns each schedule into a Vercel cron job in `.vercel/output/config.json`,
+pointing at `/api/cron/<endpointId>`. When it fires, Vercel makes a GET request to that path and the
+Hono app runs the endpoint's routine.
+
+- **Secure it:** add a project Environment Variable named exactly `CRON_SECRET` (a random string of
+  16+ characters). Vercel automatically sends it as `Authorization: Bearer <CRON_SECRET>`, and the
+  `/api/cron/*` route rejects any request whose header does not match. If `CRON_SECRET` is unset the
+  route always returns `401` (fail closed).
+- **System context:** scheduled runs have no logged-in user, so `_user` is `undefined`. The routine
+  has full access to connections, requests, operators and secrets — just not a user. The `payload`
+  for a run comes from the matching schedule's `payload`.
+- **UTC only.** Cron expressions use 5 fields (`minute hour day-of-month month day-of-week`); named
+  values like `MON`/`JAN` are not supported and day-of-month and day-of-week are mutually exclusive.
+- **Plan limits:** Vercel **Hobby** only allows daily crons (a sub-daily expression fails the
+  deployment); **Pro**/**Enterprise** allow per-minute. Up to 100 cron jobs per project.
+- **Idempotency:** Vercel does not retry failed runs and delivery is best-effort (a run can be
+  missed or delivered more than once). Write scheduled routines to be idempotent.
+
+## How it works
+
+`vercel.build.sh` builds the client and runs `lowdefy vercel-output`, which assembles:
+
+- `.vercel/output/static/` — the built client and `public/` files, served by the CDN.
+- `.vercel/output/functions/api.func/` — one Node Serverless Function: the Hono app plus its exact
+  runtime dependency closure, traced with [`@vercel/nft`](https://github.com/vercel/nft) (pnpm
+  symlinks and workspace packages included), and the `build/**`,
+  `dist/client/.vite/manifest.json` and `package.json` files it reads at runtime, with a
+  `.vc-config.json`.
+- `.vercel/output/config.json` — routes that serve static files first and send every other request
+  to the function (running with `serveStaticAssets: false`), plus the `crons` array.
 
-- Create a new project
-- Connect the GitHub, Gitlab or BitBucket repository with your Lowdefy app to the Vercel project
-- The framework preset should be Next.js
-- The root directory should be `<config-directory>/deploy`
-  - `<config-directory>` is the path to the directory in which the `lowdefy.yaml` file is placed
-  - Eg: If the `lowdefy.yaml` is in the top level of the repository the configured root directory should be `deploy`
-  - Eg: If the `lowdefy.yaml` is in the directory `apps/app_name` the configured root directory should be `apps/app_name/deploy`
-- The build command should be `pnpm next build`
-- The install command should be `sh vercel.install.sh`
+> The function runs on the Vercel **Node.js** runtime. Streaming agent responses (`/api/agent/*`)
+> are subject to Vercel's function response/duration limits; for heavy streaming or agent workloads
+> a long-lived Node host (Docker, Fly.io, Railway, Render) running `node src/index.js` may suit
+> better.
 
-Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`. Different secrets can be set for production and preview deployments.
+## Manual setup
 
-All other Vercel configuration like domain names, preview deploy branches, serverless regions and redirects can be configured as desired.
+The same files can be created by hand at `<config-directory>/deploy/` instead of running
+`lowdefy init-vercel`. All other Vercel configuration (domains, preview branches, regions,
+redirects) can be set as desired.

package/dist/commands/init-vercel/initVercel.js

@@ -15,13 +15,23 @@
 */ import path from 'path';
 import url from 'url';
 import { readFile, writeFile } from '@lowdefy/node-utils';
+// The Vercel function entry is no longer scaffolded here: the deployment uses the Vercel Build
+// Output API, and `lowdefy vercel-output` (run by vercel.build.sh) generates the function and
+// deployment config into .vercel/output at build time.
 async function initVercel({ context }) {
     context.logger.info('Initializing Vercel deployment.');
+    const deployDir = path.join(context.directories.config, 'deploy');
     const installScript = await readFile(url.fileURLToPath(new URL('./vercel.install.sh', import.meta.url)));
-    await writeFile(path.join(context.directories.config, 'deploy', 'vercel.install.sh'), installScript);
+    await writeFile(path.join(deployDir, 'vercel.install.sh'), installScript);
     context.logger.info("Created 'vercel.install.sh'.");
+    const buildScript = await readFile(url.fileURLToPath(new URL('./vercel.build.sh', import.meta.url)));
+    await writeFile(path.join(deployDir, 'vercel.build.sh'), buildScript);
+    context.logger.info("Created 'vercel.build.sh'.");
+    const vercelJson = await readFile(url.fileURLToPath(new URL('./vercel.json', import.meta.url)));
+    await writeFile(path.join(deployDir, 'vercel.json'), vercelJson);
+    context.logger.info("Created 'vercel.json'.");
     const readMe = await readFile(url.fileURLToPath(new URL('./README.md', import.meta.url)));
-    await writeFile(path.join(context.directories.config, 'deploy', 'README.md'), readMe);
+    await writeFile(path.join(deployDir, 'README.md'), readMe);
     context.logger.info("Created 'README.md'.");
     await context.sendTelemetry();
     context.logger.info({

package/dist/commands/init-vercel/vercel.build.sh

@@ -0,0 +1,8 @@
+# Vercel build command. The install step (vercel.install.sh) already downloaded the Hono server and
+# built the config artifacts into this directory. Here we build the Vite client, then assemble the
+# Vercel Build Output (.vercel/output) — including cron jobs generated from endpoint `schedules`.
+# Read Lowdefy version from lowdefy.yaml using sed.
+LOWDEFY_VERSION=$(sed -nE "s/lowdefy:(.*)/\1/p" ../lowdefy.yaml)
+# Substitution params are to trim whitespace from the LOWDEFY_VERSION var.
+pnpm run build:client
+npx lowdefy@${LOWDEFY_VERSION//[[:space:]]/} vercel-output --config-directory ../ --server-directory . --log-level=debug

package/dist/commands/init-vercel/vercel.install.sh

@@ -1,4 +1,6 @@
 # Read Lowdefy version from lowdefy.yaml using sed
 LOWDEFY_VERSION=$(sed -nE "s/lowdefy:(.*)/\1/p" ../lowdefy.yaml)
-# Substitution params are to trim whitespace from the LOWDEFY_VERSION var
-npx lowdefy@${LOWDEFY_VERSION//[[:space:]]/} build --config-directory ../  --server-directory . --no-next-build --log-level=debug
+# Substitution params are to trim whitespace from the LOWDEFY_VERSION var.
+# Writes the Hono server and config artifacts into this directory. The client build and the Vercel
+# Build Output assembly run separately in the build step (vercel.build.sh).
+npx lowdefy@${LOWDEFY_VERSION//[[:space:]]/} build --config-directory ../  --server-directory . --no-client-build --log-level=debug

package/dist/commands/init-vercel/vercel.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "buildCommand": "bash vercel.build.sh"
+}

package/dist/commands/start/runStart.js

@@ -31,8 +31,7 @@ async function runStart({ context, directory }) {
             env: {
                 ...process.env,
                 LOWDEFY_LOG_LEVEL: context.options.logLevel,
-                PORT: context.options.port,
-                NEXT_TELEMETRY_DISABLED: context.options.disableTelemetry ? '1' : undefined
+                PORT: context.options.port
             }
         }
     });

package/dist/commands/vercelOutput/apiHandler.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.
+*/ // The Vercel function entry, written into the Build Output at
+// .vercel/output/functions/api.func/<relServer>/api/index.js, where <relServer> is the server
+// directory's path relative to the trace base (empty for standalone apps). Kept as a string (not a
+// template file) so it ships verbatim — a real source file would be transpiled by the CLI's swc
+// build, stripping these comments. Its `../src/app.js` import and the chdir to `..` resolve to the
+// server directory inside the function, where the assembly places src/, build/, lib/ and the traced
+// dependency closure.
+const apiHandler = `/*
+  Vercel Serverless Function entry for a Lowdefy (Hono) app — generated into the Vercel Build Output
+  by lowdefy vercel-output.
+
+  The built client and public files are served from Vercel's CDN (.vercel/output/static); every
+  other request is routed here (config.json routes) and run through the Lowdefy Hono app (page
+  rendering, /api/* requests, endpoints, cron, auth, agents).
+
+  Runs on the Node runtime (the app uses fs to read its build). The request body is buffered eagerly
+  and a Web Request is built from it: Vercel's Node runtime does not drain a lazily-read body stream
+  reliably, so a streaming adapter hangs on every request that has a body (POST).
+*/
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The app reads its build artifacts relative to process.cwd(). On Vercel the function's cwd is the
+// lambda root (e.g. /var/task), not this directory, so point the cwd at the server directory (the
+// parent of this api/ folder) before loading the app. The import is dynamic so it runs AFTER chdir —
+// a static import is hoisted and would read files at the wrong cwd.
+process.chdir(path.join(path.dirname(fileURLToPath(import.meta.url)), '..'));
+
+const { default: createApp } = await import('../src/app.js');
+const app = createApp({ serveStaticAssets: false });
+
+export const config = { runtime: 'nodejs' };
+
+export default async function handler(req, res) {
+  const method = req.method || 'GET';
+
+  // Buffer the body eagerly — see the note above.
+  let body;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    if (chunks.length > 0) body = Buffer.concat(chunks);
+  }
+
+  const host = req.headers['x-forwarded-host'] ?? req.headers.host;
+  const protocol = req.headers['x-forwarded-proto'] ?? 'https';
+  const request = new Request(protocol + '://' + host + req.url, {
+    method,
+    headers: req.headers,
+    body,
+  });
+
+  const response = await app.fetch(request);
+
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => res.setHeader(key, value));
+  if (response.body) {
+    const reader = response.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  }
+  res.end();
+}
+`;
+export default apiHandler;

package/dist/commands/vercelOutput/vercelOutput.js

@@ -0,0 +1,138 @@
+/*
+  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 { cleanDirectory, copyFileOrDirectory, readFile, writeFile } from '@lowdefy/node-utils';
+import apiHandler from './apiHandler.js';
+import copyTracedFiles from '../../utils/copyTracedFiles.js';
+import findTraceBase from '../../utils/findTraceBase.js';
+// Function settings come from lowdefy.yaml `config.vercel` (written to build/config.json by
+// @lowdefy/build). maxDuration defaults to 60; plan limits are enforced by Vercel at deploy time.
+async function readFunctionConfig({ buildDirectory }) {
+    const raw = await readFile(path.join(buildDirectory, 'config.json'));
+    const config = raw ? JSON.parse(raw) : {};
+    const vercel = config.vercel ?? {};
+    return {
+        maxDuration: vercel.maxDuration ?? 60,
+        ...vercel.memory ? {
+            memory: vercel.memory
+        } : {}
+    };
+}
+// The crons array is generated from build/schedules.json (written by @lowdefy/build for endpoints
+// that declare `schedules`). A missing file means no schedules → no crons. Vercel fires crons only
+// on the production deployment, so with config.cron.environments the schedules of every other
+// environment are registered here too, as cron-forward jobs the production deployment relays to
+// that environment's own /api/cron route.
+async function readCrons({ buildDirectory }) {
+    const raw = await readFile(path.join(buildDirectory, 'schedules.json'));
+    if (!raw) return [];
+    const schedules = JSON.parse(raw);
+    return schedules.map(({ endpointId, cron, environment, forward })=>({
+            path: forward === true ? `/api/cron-forward/${environment}/${endpointId}` : `/api/cron/${endpointId}`,
+            schedule: cron
+        }));
+}
+// Assembles a Vercel Build Output (.vercel/output) from an already-built server directory, so the
+// deployment config — including cron jobs derived from endpoint `schedules` — is generated at build
+// time and never committed. Run after `lowdefy build` (server + config artifacts) and the client
+// build (dist/client).
+async function vercelOutput({ context }) {
+    const { directories, logger } = context;
+    logger.info('Assembling Vercel Build Output.');
+    const serverDirectory = path.resolve(directories.server);
+    const buildDirectory = path.resolve(directories.build);
+    const clientDirectory = path.join(serverDirectory, 'dist', 'client');
+    const outputDirectory = path.join(serverDirectory, '.vercel', 'output');
+    const staticDirectory = path.join(outputDirectory, 'static');
+    const functionDirectory = path.join(outputDirectory, 'functions', 'api.func');
+    const entrypoints = [
+        path.join(serverDirectory, 'src', 'index.js'),
+        path.join(serverDirectory, 'src', 'app.js')
+    ];
+    entrypoints.forEach((entrypoint)=>{
+        if (!fs.existsSync(entrypoint)) {
+            throw new Error(`Cannot trace "${entrypoint}" — run "lowdefy build" first.`);
+        }
+    });
+    // The function preserves paths relative to the trace base (the pnpm workspace root when the
+    // server directory is a workspace member), so the server's relative node_modules symlinks still
+    // resolve inside the function. The server lands at <relServer>/ inside api.func.
+    const base = findTraceBase({
+        serverDirectory
+    });
+    const relServer = path.relative(base, serverDirectory);
+    const functionServerDirectory = path.join(functionDirectory, relServer);
+    // Start clean so artifacts from a previous build do not leak into the deployment.
+    await cleanDirectory(outputDirectory);
+    // 1. Static assets + public files served by the Vercel CDN.
+    await copyFileOrDirectory(clientDirectory, staticDirectory);
+    // 2. The runtime file closure of the Hono server, traced with @vercel/nft — the app source, the
+    //    build-generated plugin import files, and exactly the node_modules files they resolve to
+    //    (through pnpm's symlinks, which are preserved).
+    const fileCount = await copyTracedFiles({
+        base,
+        entrypoints,
+        functionDirectory,
+        logger,
+        processCwd: serverDirectory
+    });
+    logger.info(`Traced ${fileCount} runtime files into the function.`);
+    // 3. Artifacts the server reads from the filesystem at runtime (not imported, so not traced),
+    //    plus src/ and lib/ wholesale as belt-and-braces alongside the traced copies.
+    await copyFileOrDirectory(path.join(serverDirectory, 'src'), path.join(functionServerDirectory, 'src'));
+    await copyFileOrDirectory(path.join(serverDirectory, 'lib'), path.join(functionServerDirectory, 'lib'));
+    await copyFileOrDirectory(buildDirectory, path.join(functionServerDirectory, 'build'));
+    await copyFileOrDirectory(path.join(clientDirectory, '.vite', 'manifest.json'), path.join(functionServerDirectory, 'dist', 'client', '.vite', 'manifest.json'));
+    await copyFileOrDirectory(path.join(serverDirectory, 'package.json'), path.join(functionServerDirectory, 'package.json'));
+    // 4. The function entry and its config. The handler path is relative to the api.func root.
+    const handler = path.posix.join(...relServer.split(path.sep), 'api', 'index.js');
+    const functionConfig = await readFunctionConfig({
+        buildDirectory
+    });
+    await writeFile(path.join(functionServerDirectory, 'api', 'index.js'), apiHandler);
+    await writeFile(path.join(functionDirectory, '.vc-config.json'), JSON.stringify({
+        runtime: 'nodejs22.x',
+        handler,
+        launcherType: 'Nodejs',
+        ...functionConfig
+    }, null, 2));
+    // 5. Deployment config: serve static files first, route everything else to the function, and
+    //    register the cron jobs.
+    const crons = await readCrons({
+        buildDirectory
+    });
+    const config = {
+        version: 3,
+        routes: [
+            {
+                handle: 'filesystem'
+            },
+            {
+                src: '/(.*)',
+                dest: '/api'
+            }
+        ]
+    };
+    if (crons.length > 0) {
+        config.crons = crons;
+    }
+    await writeFile(path.join(outputDirectory, 'config.json'), JSON.stringify(config, null, 2));
+    logger.info({
+        spin: 'succeed'
+    }, `Vercel Build Output assembled with ${crons.length} cron job${crons.length === 1 ? '' : 's'}.`);
+    await context.sendTelemetry();
+}
+export default vercelOutput;

package/dist/program.js

@@ -14,13 +14,17 @@
   limitations under the License.
 */ import { createRequire } from 'module';
 import { Command, Option } from 'commander';
+import agentSetup from './commands/agentSetup/agentSetup.js';
 import build from './commands/build/build.js';
 import dev from './commands/dev/dev.js';
+import dockerOutput from './commands/dockerOutput/dockerOutput.js';
+import emails from './commands/emails/emails.js';
 import init from './commands/init/init.js';
 import initDocker from './commands/init-docker/initDocker.js';
 import initVercel from './commands/init-vercel/initVercel.js';
 import start from './commands/start/start.js';
 import upgrade from './commands/upgrade/upgrade.js';
+import vercelOutput from './commands/vercelOutput/vercelOutput.js';
 import runCommand from './utils/runCommand.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -37,22 +41,36 @@ const options = {
         'info',
         'debug'
     ]).default('info').env('LOWDEFY_LOG_LEVEL'),
+    mockUser: new Option('--mock-user [user]', 'Start the dev server authenticated as a mock user (auth.dev.mockUser). Pass a JSON user object to set identity/roles, e.g. \'{"sub":"dev","roles":["admin"]}\'. Bare flag uses a default roleless user. Dev only.').env('LOWDEFY_DEV_USER'),
     port: new Option('--port <port>', 'Change the port the development server is hosted at. Default is 3000.').env('PORT'),
+    projectDirectory: new Option('--project-directory <project-directory>', 'Change the directory where agent files (.mcp.json, AGENTS.md, Claude Code skill) are written. Default is the nearest ancestor directory containing .git, falling back to the config directory.').env('LOWDEFY_DIRECTORY_PROJECT'),
     refResolver: new Option('--ref-resolver <ref-resolver-function-path>', 'Path to a JavaScript file containing a _ref resolver function to be used as the app default _ref resolver.'),
     serverDirectory: new Option('--server-directory <server-directory>', 'Change the server directory. Default is "<config-directory>/.lowdefy/server".').env('LOWDEFY_DIRECTORY_SERVER'),
     watch: new Option('--watch <paths...>', 'A list of paths to files or directories that should be watched for changes. Globs are supported. Specify each path to watch separated by spaces.'),
     watchIgnore: new Option('--watch-ignore <paths...>', 'A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. Specify each path to watch separated by spaces.')
 };
-program.command('build').description('Build a Lowdefy production app.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).option('--no-next-build', 'Do not build the Next.js server.').addOption(options.refResolver).addOption(new Option('--server <server>', 'Server package variant. Use "e2e" for @lowdefy/server-e2e.').choices([
+program.command('agent-setup').description('Set up this project for AI coding agents (.mcp.json, AGENTS.md, Claude Code skill).').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(options.port).addOption(options.projectDirectory).action(runCommand({
+    cliVersion,
+    handler: agentSetup
+}));
+program.command('build').description('Build a Lowdefy production app.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).option('--no-client-build', 'Do not run the Vite client build.').addOption(new Option('--no-next-build', 'Deprecated alias of --no-client-build.').hideHelp()).addOption(options.refResolver).addOption(new Option('--server <server>', 'Server package variant. Use "e2e" for @lowdefy/server-e2e.').choices([
     'e2e'
 ])).addOption(options.serverDirectory).action(runCommand({
     cliVersion,
     handler: build
 }));
-program.command('dev').description('Start a Lowdefy development server.').usage('[options]').addOption(options.configDirectory).addOption(options.devDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).option('--no-open', 'Do not open a new tab in the default browser.').addOption(options.port).addOption(options.refResolver).addOption(options.watch).addOption(options.watchIgnore).action(runCommand({
+program.command('dev').description('Start a Lowdefy development server.').usage('[options]').addOption(options.configDirectory).addOption(options.devDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(options.mockUser).option('--no-open', 'Do not open a new tab in the default browser.').addOption(options.port).addOption(options.refResolver).addOption(options.watch).addOption(options.watchIgnore).action(runCommand({
     cliVersion,
     handler: dev
 }));
+program.command('emails').description('Preview notification emails with the React Email preview server.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(new Option('--port <port>', 'Change the port the email preview server is hosted at. Default is 3001.').env('PORT')).addOption(options.refResolver).addOption(options.serverDirectory).action(runCommand({
+    cliVersion,
+    handler: emails
+}));
+program.command('docker-output').description('Assemble a minimal Docker runtime (.lowdefy/docker) from a built app.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(options.serverDirectory).action(runCommand({
+    cliVersion,
+    handler: dockerOutput
+}));
 program.command('init').description('Initialize a Lowdefy project.').usage('[options]').addOption(options.disableTelemetry).addOption(options.logLevel).action(runCommand({
     cliVersion,
     handler: init
@@ -65,6 +83,10 @@ program.command('init-vercel').description('Initialize Vercel deployment install
     cliVersion,
     handler: initVercel
 }));
+program.command('vercel-output').description('Assemble a Vercel Build Output (.vercel/output) from a built app.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(options.serverDirectory).action(runCommand({
+    cliVersion,
+    handler: vercelOutput
+}));
 program.command('start').description('Start a Lowdefy production app.').usage('[options]').addOption(options.configDirectory).addOption(options.disableTelemetry).addOption(options.logLevel).addOption(options.port).addOption(options.serverDirectory).action(runCommand({
     cliVersion,
     handler: start

package/dist/utils/checkPortAvailable.js

@@ -12,26 +12,19 @@
   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 net from 'net';
-function checkPortAvailable({ port }) {
-    return new Promise((resolve, reject)=>{
-        const server = net.createServer();
-        server.on('error', (error)=>{
-            if (error.code === 'EADDRINUSE') {
-                reject(new Error(`[Server Error] Port ${port} is already in use.
+*/ import { isPortAvailable } from '@lowdefy/node-utils';
+async function checkPortAvailable({ port }) {
+    const available = await isPortAvailable({
+        port
+    });
+    if (!available) {
+        throw new Error(`[Server Error] Port ${port} is already in use.
 
 To use a different port, either:
   - Run with the --port flag: pnpx lowdefy dev --port 3001
   - Set the port in your lowdefy.yaml:
     cli:
-      port: 3001`));
-            } else {
-                reject(error);
-            }
-        });
-        server.listen(port, ()=>{
-            server.close(()=>resolve());
-        });
-    });
+      port: 3001`);
+    }
 }
 export default checkPortAvailable;

package/dist/utils/copyTracedFiles.js

@@ -0,0 +1,94 @@
+/*
+  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/promises';
+import path from 'path';
+import { nodeFileTrace } from '@vercel/nft';
+const CONCURRENCY = 64;
+async function inBatches(items, worker) {
+    for(let i = 0; i < items.length; i += CONCURRENCY){
+        await Promise.all(items.slice(i, i + CONCURRENCY).map(worker));
+    }
+}
+// Traces the runtime file closure of the server entrypoints with @vercel/nft and reproduces it
+// under functionDirectory, preserving relative symlinks. pnpm layouts depend on this: the server's
+// node_modules entries are relative symlinks into a .pnpm virtual store (at the workspace root for
+// workspace members), and nft's fileList contains both the symlink paths and the real target files,
+// all relative to `base` — recreating both yields a working resolution tree inside the function.
+async function copyTracedFiles({ base, entrypoints, functionDirectory, logger, processCwd }) {
+    const { fileList, warnings } = await nodeFileTrace(entrypoints, {
+        base,
+        processCwd
+    });
+    for (const warning of warnings){
+        logger.debug(`nft: ${warning.message}`);
+    }
+    // Partition by lstat so links are recreated as links, not followed.
+    const symlinks = [];
+    const files = [];
+    const directories = [];
+    await inBatches([
+        ...fileList
+    ], async (file)=>{
+        let stat;
+        try {
+            stat = await fs.lstat(path.join(base, file));
+        } catch  {
+            logger.debug(`nft traced a missing file: ${file}`);
+            return;
+        }
+        if (stat.isSymbolicLink()) {
+            symlinks.push(file);
+        } else if (stat.isDirectory()) {
+            directories.push(file);
+        } else {
+            files.push({
+                file,
+                mode: stat.mode
+            });
+        }
+    });
+    await inBatches(directories, async (file)=>{
+        await fs.mkdir(path.join(functionDirectory, file), {
+            recursive: true
+        });
+    });
+    // Symlinks before files, parents before children: a file whose destination path traverses a
+    // symlinked directory must land at the link's target, not turn the link's path into a real
+    // directory. Sequential — symlink creation is cheap and ordering matters.
+    symlinks.sort((a, b)=>a.length - b.length);
+    for (const file of symlinks){
+        const source = path.join(base, file);
+        const destination = path.join(functionDirectory, file);
+        await fs.mkdir(path.dirname(destination), {
+            recursive: true
+        });
+        try {
+            await fs.symlink(await fs.readlink(source), destination);
+        } catch (error) {
+            if (error.code !== 'EEXIST') throw error;
+        }
+    }
+    await inBatches(files, async ({ file, mode })=>{
+        const source = path.join(base, file);
+        const destination = path.join(functionDirectory, file);
+        await fs.mkdir(path.dirname(destination), {
+            recursive: true
+        });
+        await fs.copyFile(source, destination);
+        await fs.chmod(destination, mode);
+    });
+    return fileList.size;
+}
+export default copyTracedFiles;