@lowdefy/server 6.1.0 → 7.0.0

package/src/html/renderPage.test.mjs

@@ -0,0 +1,189 @@
+/*
+  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 { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const { default: getPageConfig } = await import('@lowdefy/api/routes/page/getPageConfig.js');
+
+const mockGetRootConfig = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  createContentSecurityPolicy: jest.fn(),
+  getPageConfig,
+  getRootConfig: mockGetRootConfig,
+}));
+
+jest.unstable_mockModule('../../lib/build/app.js', () => ({ default: {} }));
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: { authPages: { signIn: '/auth/login', twoFactorEnrol: '/two-factor-enrol' } },
+}));
+jest.unstable_mockModule('../../lib/build/config.js', () => ({ default: { basePath: '' } }));
+jest.unstable_mockModule('../../lib/build/security.js', () => ({
+  default: { contentSecurityPolicy: null },
+}));
+jest.unstable_mockModule('../../lib/build/theme.js', () => ({ default: {} }));
+jest.unstable_mockModule('./getAssets.js', () => ({ default: () => ({}) }));
+jest.unstable_mockModule('./getPageAssets.js', () => ({ default: () => ({}) }));
+jest.unstable_mockModule('./template.js', () => ({
+  default: ({ config, title }) => JSON.stringify({ config, title }),
+}));
+
+const { default: renderPage } = await import('./renderPage.js');
+const { default: mountPageRoutes } = await import('../routes/mountPageRoutes.js');
+
+const routes = [
+  { pageId: '404', path: '404' },
+  { pageId: 'home', path: 'home' },
+  { pageId: 'state-title', path: 'state-title' },
+  { pageId: 'ticket', path: '{space}/tickets/{ticket_id}' },
+  { pageId: 'section', path: '{section}' },
+];
+
+const pages = {
+  404: { id: '404' },
+  home: { id: 'home' },
+  'state-title': { id: 'state-title', properties: { title: { _state: 'title' } } },
+  ticket: { id: 'ticket', properties: { title: 'Ticket' } },
+  section: { id: 'section' },
+};
+
+function createApp({
+  outcome = 'allow',
+  pagesProtectedByDefault = false,
+  routeTable = routes,
+  user = { id: 'u1' },
+} = {}) {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      authEnforcement: { pagesProtectedByDefault },
+      authorizeOutcome: () => outcome,
+      logger: { info: jest.fn() },
+      readConfigFile: async (file) => {
+        if (file === 'routes.json') return routeTable;
+        return pages[file.slice('pages/'.length, -'.json'.length)] ?? null;
+      },
+      user,
+    });
+    await next();
+  });
+  mountPageRoutes({ app, basePath: '', renderPage });
+  return app;
+}
+
+beforeEach(() => {
+  mockGetRootConfig.mockResolvedValue({
+    home: { configured: true, pageId: 'home', pathParams: {} },
+  });
+});
+
+async function readConfig(res) {
+  return JSON.parse(await res.text()).config;
+}
+
+test('renderPage embeds pageId, pathParams and matchedPath for a patterned page', async () => {
+  const res = await createApp().request('/support/tickets/1234');
+  expect(res.status).toEqual(200);
+  const config = await readConfig(res);
+  expect(config.pageId).toEqual('ticket');
+  expect(config.pathParams).toEqual({ space: 'support', ticket_id: '1234' });
+  expect(config.matchedPath).toEqual('support/tickets/1234');
+  expect(config.pageConfig).toEqual({ id: 'ticket', properties: { title: 'Ticket' } });
+});
+
+test('renderPage decodes an encoded "/" in a value once and keeps matchedPath encoded', async () => {
+  const res = await createApp().request('/support/tickets/a%2Fb/');
+  const config = await readConfig(res);
+  expect(config.pathParams).toEqual({ space: 'support', ticket_id: 'a/b' });
+  expect(config.matchedPath).toEqual('support/tickets/a%2Fb');
+});
+
+test('renderPage redirects an unmatched path to /404', async () => {
+  const res = await createApp().request('/support/tickets');
+  expect(res.status).toEqual(302);
+  expect(res.headers.get('location')).toEqual('/404');
+});
+
+test('renderPage redirects an unmatched path to sign-in with the path and query under pagesProtectedByDefault', async () => {
+  const res = await createApp({ pagesProtectedByDefault: true, user: null }).request(
+    '/support/tickets?tab=2'
+  );
+  expect(res.status).toEqual(302);
+  expect(res.headers.get('location')).toEqual(
+    `/auth/login?callbackUrl=${encodeURIComponent('/support/tickets?tab=2')}`
+  );
+});
+
+test('renderPage redirects a protected patterned page to sign-in with the path and query', async () => {
+  const res = await createApp({ outcome: 'deny', user: null }).request(
+    '/support/tickets/1234?tab=2'
+  );
+  expect(res.headers.get('location')).toEqual(
+    `/auth/login?callbackUrl=${encodeURIComponent('/support/tickets/1234?tab=2')}`
+  );
+});
+
+test('renderPage serves a page without path at its id', async () => {
+  const res = await createApp().request('/home');
+  const config = await readConfig(res);
+  expect(config.pageId).toEqual('home');
+  expect(config.pathParams).toEqual({});
+  expect(config.matchedPath).toEqual('home');
+});
+
+test('renderPage serves the configured home page at /', async () => {
+  const res = await createApp().request('/');
+  expect(res.status).toEqual(200);
+  const config = await readConfig(res);
+  expect(config.pageId).toEqual('home');
+  expect(config.matchedPath).toEqual('');
+});
+
+test('renderPage redirects / to the home menu link built from its pathParams', async () => {
+  mockGetRootConfig.mockResolvedValue({
+    home: {
+      configured: false,
+      pageId: 'ticket',
+      pathParams: { space: 'support', ticket_id: '12 34' },
+    },
+  });
+  const res = await createApp().request('/');
+  expect(res.status).toEqual(302);
+  expect(res.headers.get('location')).toEqual('/support/tickets/12%2034');
+});
+
+test('renderPage serves /404 as a fixed route with status 404', async () => {
+  const res = await createApp().request('/404');
+  expect(res.status).toEqual(404);
+  const config = await readConfig(res);
+  expect(config.pageId).toEqual('404');
+});
+
+test('renderPage returns a plain 404 when the build has no 404 page', async () => {
+  const res = await createApp({ routeTable: [{ pageId: 'home', path: 'home' }] }).request('/404');
+  expect(res.status).toEqual(404);
+  expect(await res.text()).toEqual('Page not found.');
+});
+
+test('renderPage serves the page title written as a string', async () => {
+  const res = await createApp().request('/support/tickets/1234');
+  expect(JSON.parse(await res.text()).title).toEqual('Ticket');
+});
+
+test('renderPage serves the page id as the title when the title is an operator', async () => {
+  const res = await createApp().request('/state-title');
+  expect(JSON.parse(await res.text()).title).toEqual('state-title');
+});

package/src/html/template.js

@@ -14,6 +14,9 @@
   limitations under the License.
 */
 
+import { addNonceToElements } from '@lowdefy/api';
+import { appStorageKey, type } from '@lowdefy/helpers';
+
 import safeScriptJson from '../lib/safeScriptJson.js';
 
 const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
@@ -27,19 +30,22 @@ function escapeHtml(value) {
 // prependQueue to inject <style> tags at the top of <head>, which would
 // otherwise make @layer antd the first (lowest priority) layer.
 // MutationObserver fires before paint, so the browser never sees the wrong
-// cascade order.
-const layerOrderScript = `(function(){var s=document.createElement("style");s.id="__lf-layer-order";s.textContent="@layer theme, base, antd, components, utilities;";document.head.prepend(s);new MutationObserver(function(){if(document.head.firstChild!==s)document.head.prepend(s)}).observe(document.head,{childList:true})})();`;
+// cascade order. The style element takes the script's own nonce, which a
+// Content-Security-Policy needs to apply it.
+const layerOrderScript = `(function(){var s=document.createElement("style");s.id="__lf-layer-order";var n=document.currentScript&&document.currentScript.nonce;if(n)s.nonce=n;s.textContent="@layer theme, base, antd, components, utilities;";document.head.prepend(s);new MutationObserver(function(){if(document.head.firstChild!==s)document.head.prepend(s)}).observe(document.head,{childList:true})})();`;
 
 // Synchronous pre-hydration script setting the <html> background and
 // color-scheme — prevents a mode-mismatch flash of the page and of browser
 // chrome (scrollbars, form controls) on page load. Mirrors useDarkMode.js
-// resolution order: configDarkMode → localStorage → prefers-color-scheme.
-function darkModeScript({ configColorMode, darkBg, lightBg }) {
+// resolution order: configDarkMode → localStorage → prefers-color-scheme. The preference is
+// kept under the app's storage key; a value under the bare key from before keys were kept per
+// app is read until useDarkMode moves it.
+function darkModeScript({ configColorMode, darkBg, lightBg, storageKey }) {
   return `(function(){var c=${safeScriptJson(configColorMode)};var db=${safeScriptJson(
     darkBg
-  )};var lb=${safeScriptJson(
-    lightBg
-  )};var d;if(c==="dark")d=true;else if(c==="light")d=false;else{try{var p=localStorage.getItem("lowdefy_darkMode");if(p==="dark")d=true;else if(p==="light")d=false;else d=window.matchMedia("(prefers-color-scheme:dark)").matches}catch(e){d=window.matchMedia("(prefers-color-scheme:dark)").matches}}var bg=d?db:lb;document.documentElement.style.colorScheme=d?"dark":"light";if(bg)document.documentElement.style.backgroundColor=bg})();`;
+  )};var lb=${safeScriptJson(lightBg)};var k=${safeScriptJson(
+    storageKey
+  )};var d;if(c==="dark")d=true;else if(c==="light")d=false;else{try{var p=localStorage.getItem(k);if(p===null)p=localStorage.getItem("lowdefy_darkMode");if(p==="dark")d=true;else if(p==="light")d=false;else d=window.matchMedia("(prefers-color-scheme:dark)").matches}catch(e){d=window.matchMedia("(prefers-color-scheme:dark)").matches}}var bg=d?db:lb;document.documentElement.style.colorScheme=d?"dark":"light";if(bg)document.documentElement.style.backgroundColor=bg})();`;
 }
 
 function template({
@@ -48,6 +54,9 @@ function template({
   assets,
   basePath = '',
   config,
+  nonce = null,
+  pageAssets,
+  slug,
   themeConfig = {},
   title,
 }) {
@@ -58,12 +67,29 @@ function template({
   const darkBg = themeConfig?.antd?.darkToken?.colorBgLayout ?? '#000';
   const lightBg = themeConfig?.antd?.lightToken?.colorBgLayout ?? '';
 
-  const cssLinks = assets.css
+  // The page's plugin chunks are preloaded with the main entry, so the first
+  // render's wait for them overlaps the main bundle's download.
+  const cssLinks = [...assets.css, ...pageAssets.css]
     .map((file) => `<link rel="stylesheet" href="${basePath}/${file}" />`)
     .join('\n    ');
-  const modulePreloads = assets.imports
+  const modulePreloads = [...assets.imports, ...pageAssets.js]
     .map((file) => `<link rel="modulepreload" href="${basePath}/${file}" />`)
     .join('\n    ');
+  // Lazy block implementations load on mount; prefetch fills the cache at idle
+  // priority. crossorigin matches the CORS mode of the module and stylesheet
+  // requests Vite makes on mount, so they are served from that cache.
+  const prefetches = pageAssets.prefetch
+    .map((file) => `<link rel="prefetch" href="${basePath}/${file}" crossorigin />`)
+    .join('\n    ');
+
+  // With a Content-Security-Policy, every script and style element Lowdefy writes
+  // or the app appends carries the render's nonce. The csp-nonce meta tag is
+  // where the client (antd's style tags) and Vite read it.
+  const hasNonce = !type.isNull(nonce);
+  const nonceAttribute = hasNonce ? ` nonce="${nonce}"` : '';
+  const nonceMeta = hasNonce ? `<meta property="csp-nonce" nonce="${nonce}" />` : '';
+  const head = hasNonce ? addNonceToElements({ html: appendHead, nonce }) : appendHead;
+  const body = hasNonce ? addNonceToElements({ html: appendBody, nonce }) : appendBody;
 
   // appendHead and appendBody are intentionally raw HTML from app config
   // (analytics snippets, font links) — they must not be escaped. The config
@@ -72,8 +98,14 @@ function template({
 <html class="lowdefy">
   <head>
     <meta charset="utf-8" />
-    <script>${layerOrderScript}</script>
-    <script>${darkModeScript({ configColorMode, darkBg, lightBg })}</script>
+    ${nonceMeta}
+    <script${nonceAttribute}>${layerOrderScript}</script>
+    <script${nonceAttribute}>${darkModeScript({
+      configColorMode,
+      darkBg,
+      lightBg,
+      storageKey: appStorageKey({ basePath, name: 'lowdefy_darkMode', slug }),
+    })}</script>
     <link rel="manifest" href="${basePath}/manifest.webmanifest" />
     <link rel="icon" type="image/svg+xml" href="${basePath}/icon.svg" />
     <link rel="apple-touch-icon" href="${basePath}/apple-touch-icon.png" />
@@ -81,13 +113,16 @@ function template({
     ${title ? `<title>${escapeHtml(title)}</title>` : ''}
     ${cssLinks}
     ${modulePreloads}
-    ${appendHead}
+    ${prefetches}
+    ${head}
   </head>
   <body>
     <div id="root"></div>
-    <script id="__LOWDEFY_CONFIG__" type="application/json">${safeScriptJson(config)}</script>
-    ${appendBody}
-    <script type="module" src="${basePath}/${assets.js}"></script>
+    <script id="__LOWDEFY_CONFIG__" type="application/json"${nonceAttribute}>${safeScriptJson(
+      config
+    )}</script>
+    ${body}
+    <script type="module" src="${basePath}/${assets.js}"${nonceAttribute}></script>
   </body>
 </html>`;
 }

package/src/html/template.test.mjs

@@ -0,0 +1,126 @@
+/*
+  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 template from './template.js';
+
+const assets = {
+  js: 'assets/main.js',
+  css: ['assets/main.css'],
+  imports: ['assets/react.js'],
+};
+
+test('template preloads the page types chunks and links their stylesheets', () => {
+  const html = template({
+    assets,
+    basePath: '/app',
+    config: { pageConfig: {} },
+    pageAssets: {
+      js: ['assets/aaaa.js', 'assets/antd.js'],
+      css: ['assets/antd.css'],
+      prefetch: [],
+    },
+  });
+  expect(html).toContain('<link rel="stylesheet" href="/app/assets/main.css" />');
+  expect(html).toContain('<link rel="stylesheet" href="/app/assets/antd.css" />');
+  expect(html).toContain('<link rel="modulepreload" href="/app/assets/react.js" />');
+  expect(html).toContain('<link rel="modulepreload" href="/app/assets/aaaa.js" />');
+  expect(html).toContain('<link rel="modulepreload" href="/app/assets/antd.js" />');
+  expect(html).toContain('<script type="module" src="/app/assets/main.js"></script>');
+});
+
+test('template prefetches the page lazy block chunks after its preloads', () => {
+  const html = template({
+    assets,
+    basePath: '/app',
+    config: { pageConfig: {} },
+    pageAssets: {
+      js: ['assets/aaaa.js'],
+      css: [],
+      prefetch: ['assets/AgentChat.lazy.js', 'assets/AgentChat.css'],
+    },
+  });
+  expect(html).toContain(
+    '<link rel="prefetch" href="/app/assets/AgentChat.lazy.js" crossorigin />'
+  );
+  expect(html).toContain('<link rel="prefetch" href="/app/assets/AgentChat.css" crossorigin />');
+  expect(html).not.toContain('<link rel="modulepreload" href="/app/assets/AgentChat.lazy.js" />');
+  expect(html.indexOf('rel="prefetch"')).toBeGreaterThan(
+    html.indexOf('<link rel="modulepreload" href="/app/assets/aaaa.js" />')
+  );
+});
+
+test('template writes no prefetch links for a page without lazy blocks', () => {
+  const html = template({
+    assets,
+    config: { pageConfig: {} },
+    pageAssets: { js: ['assets/aaaa.js'], css: [], prefetch: [] },
+  });
+  expect(html).not.toContain('rel="prefetch"');
+});
+
+test('template dark mode script reads the preference under the app key', () => {
+  const html = template({
+    assets,
+    basePath: '/app',
+    config: { pageConfig: {} },
+    pageAssets: { js: [], css: [], prefetch: [] },
+    slug: 'sales',
+  });
+  expect(html).toContain('var k="lowdefy:sales:/app:lowdefy_darkMode";');
+  expect(html).toContain(
+    'var p=localStorage.getItem(k);if(p===null)p=localStorage.getItem("lowdefy_darkMode");'
+  );
+});
+
+const pageAssets = { js: [], css: [], prefetch: [] };
+
+test('template puts the nonce on every script element, the appended ones included', () => {
+  const html = template({
+    appendHead: '<script src="https://cdn.example.com/a.js"></script><style>p{}</style>',
+    appendBody: '<script>window.b = 1;</script>',
+    assets,
+    config: { pageConfig: {} },
+    nonce: 'bm9uY2U=',
+    pageAssets,
+  });
+  const scripts = html.match(/<script\b[^>]*>/g);
+  expect(scripts.length).toEqual(6);
+  scripts.forEach((tag) => expect(tag).toContain(' nonce="bm9uY2U="'));
+  expect(html).toContain('<style nonce="bm9uY2U=">p{}</style>');
+  expect(html).toContain('<meta property="csp-nonce" nonce="bm9uY2U=" />');
+});
+
+test('template has the layer order style take the nonce of its script', () => {
+  const html = template({ assets, config: { pageConfig: {} }, nonce: 'bm9uY2U=', pageAssets });
+  expect(html).toContain(
+    'var n=document.currentScript&&document.currentScript.nonce;if(n)s.nonce=n;'
+  );
+});
+
+test('template writes no nonce without a Content-Security-Policy', () => {
+  const html = template({
+    appendHead: '<script src="https://cdn.example.com/a.js"></script>',
+    appendBody: '<script>window.b = 1;</script>',
+    assets,
+    config: { pageConfig: {} },
+    nonce: null,
+    pageAssets,
+  });
+  expect(html).not.toContain(' nonce="');
+  expect(html).not.toContain('csp-nonce');
+  expect(html).toContain('<script src="https://cdn.example.com/a.js"></script>');
+  expect(html).toContain('<script>window.b = 1;</script>');
+});

package/src/index.js

@@ -15,42 +15,19 @@
 */
 
 import { serve } from '@hono/node-server';
-import * as Sentry from '@sentry/node';
 import { WebSocketServer } from 'ws';
 
-import checkEnvironmentGuards from '@lowdefy/node-utils/checkEnvironmentGuards.js';
+import registerServer from '@lowdefy/node-utils/registerServer.js';
+import watchOwner from '@lowdefy/node-utils/watchOwner.js';
 
-import initSentryServer from '../lib/server/sentry/initSentry.js';
+import initServer from './initServer.js';
 
-// Auth.js v5 reads AUTH_URL but not NEXTAUTH_URL — alias the v4 variable
-// before any auth config loads so existing deployments keep working.
-if (process.env.NEXTAUTH_URL && !process.env.AUTH_URL) {
-  process.env.AUTH_URL = process.env.NEXTAUTH_URL;
-}
-
-const sentryEnabled = initSentryServer();
-
-// Import after Sentry init so instrumentation observes the module graph.
-const { default: createApp } = await import('./app.js');
-const { default: createLogger } = await import('../lib/server/log/createLogger.js');
+const { createApp, logger, sentry } = await initServer();
 const { default: appMeta } = await import('../lib/build/appMeta.js');
-const { default: config } = await import('../lib/build/config.js');
-
-// The build checked the current environment's guards, but an image built once can be started with
-// different variables, so they are checked again before the server takes any traffic.
-checkEnvironmentGuards({
-  name: config.environment,
-  guards: config.environments?.[config.environment]?.guards,
-});
 
 const app = createApp();
-const logger = createLogger({ server: 'lowdefy' });
 const port = Number(process.env.PORT ?? 3000);
 
-if (sentryEnabled) {
-  logger.info('Sentry enabled: server');
-}
-
 // Handles /api/websocket upgrades via serve({ websocket }). 256 KiB max frame,
 // aligned with Vercel's documented default for WebSocket functions.
 const wss = new WebSocketServer({ noServer: true, maxPayload: 256 * 1024 });
@@ -62,6 +39,14 @@ const server = serve({ fetch: app.fetch, port, websocket: { server: wss } }, (in
     { port: info.port, lowdefy_version: appMeta.lowdefyVersion },
     `Lowdefy server listening on http://localhost:${info.port}`
   );
+  // Only when the CLI asks (it sets the registry directory), so a server run
+  // directly - Docker, Vercel, systemd - records nothing.
+  registerServer({
+    kind: 'server',
+    port: info.port,
+    configDirectory: process.env.LOWDEFY_DIRECTORY_CONFIG,
+    logger,
+  });
 });
 
 // Container runtimes send SIGTERM and escalate to SIGKILL after a grace period
@@ -79,8 +64,12 @@ function shutdown() {
   // Drop idle keep-alive connections so close() only waits on in-flight requests.
   server.closeIdleConnections?.();
   server.close(() => {
-    // Flush queued Sentry events; resolves immediately when Sentry is not enabled.
-    Sentry.close(2000).finally(() => process.exit(0));
+    if (!sentry) {
+      process.exit(0);
+      return;
+    }
+    // Send queued Sentry events before exiting.
+    sentry.close(2000).finally(() => process.exit(0));
   });
   // In-flight requests that outlive the grace period would otherwise hold the
   // process open until SIGKILL — exit first so shutdown stays clean.
@@ -89,6 +78,16 @@ function shutdown() {
 
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
+process.on('SIGHUP', shutdown);
+
+// A server started by the CLI, a test runner or a script stops when that
+// owner stops, however it ends. Inert unless the spawner set its variables.
+watchOwner({
+  onExit: ({ reason }) => {
+    logger.info({ reason }, 'The process that started this server is gone. Shutting down.');
+    shutdown();
+  },
+});
 
 // Vercel's Node.js builder consumes the exported server — the same pattern
 // Vercel documents for WebSocket support with Hono on Fluid compute.

package/src/initServer.js

@@ -0,0 +1,61 @@
+/*
+  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 checkEnvironmentGuards from '@lowdefy/node-utils/checkEnvironmentGuards.js';
+
+import initSentryServer from '../lib/server/sentry/initSentry.js';
+
+// The startup every production entry runs before it serves: the Node server (src/index.js) and the
+// Vercel function entry that `lowdefy vercel-output` generates. Keeping it in one place stops the
+// entries drifting apart. The build artifacts are read relative to process.cwd(), so an entry that
+// has to change directory imports this module dynamically, after the chdir. A serverless entry
+// passes serverless: true, so Sentry reports errors only unless the app turns tracing on.
+async function initServer({ serverless = false } = {}) {
+  const sentry = await initSentryServer({ serverless });
+
+  // The build checked the current environment's guards, but an image built once can be started
+  // with different variables, so they are checked again before the server takes any traffic — and
+  // before the app loads, so a misconfigured start fails without importing every plugin under the
+  // wrong variables. The failure is sent to Sentry here because the Vercel launcher catches errors
+  // thrown while it imports the function entry, so no global handler would report it, and the
+  // instance can be torn down before a queued event is sent.
+  const { default: config } = await import('../lib/build/config.js');
+  try {
+    checkEnvironmentGuards({
+      name: config.environment,
+      guards: config.environments?.[config.environment]?.guards,
+    });
+  } catch (error) {
+    if (sentry) {
+      sentry.captureException(error);
+      await sentry.flush(2000);
+    }
+    throw error;
+  }
+
+  // Import after Sentry init so instrumentation observes the module graph.
+  const { default: createApp } = await import('./app.js');
+  const { default: createLogger } = await import('../lib/server/log/createLogger.js');
+
+  const logger = createLogger({ server: 'lowdefy' });
+  if (sentry) {
+    logger.info('Sentry enabled: server');
+  }
+
+  return { createApp, logger, sentry };
+}
+
+export default initServer;