@lowdefy/server-dev 6.1.0 → 7.0.0

package/manager/utils/publishBuildDirectory.order.test.mjs

@@ -0,0 +1,74 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { jest } from '@jest/globals';
+
+const realFs = await import('fs/promises');
+const moved = [];
+
+// readdir order is up to the file system. Listing in reverse alphabetical order puts the
+// maps ahead of idCounter.json, so only an explicit order passes.
+jest.unstable_mockModule('fs/promises', () => ({
+  default: {
+    ...realFs.default,
+    readdir: async (...args) => (await realFs.default.readdir(...args)).reverse(),
+    rename: async (from, to) => {
+      moved.push(path.basename(to));
+      return realFs.default.rename(from, to);
+    },
+  },
+}));
+
+const { default: publishBuildDirectory } = await import('./publishBuildDirectory.mjs');
+
+test('publishBuildDirectory moves idCounter.json before the key and ref maps', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-publish-order-'));
+  const buildDirectory = path.join(root, 'build');
+  const stagingDirectory = path.join(root, 'build-staging');
+  fs.mkdirSync(stagingDirectory, { recursive: true });
+  ['app.json', 'idCounter.json', 'keyMap.json', 'pageRegistry.json', 'refMap.json'].forEach(
+    (file) => fs.writeFileSync(path.join(stagingDirectory, file), '{}')
+  );
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+  fs.rmSync(root, { recursive: true, force: true });
+
+  expect(moved[0]).toBe('idCounter.json');
+  expect(moved.at(-1)).toBe('pageRegistry.json');
+  expect(moved.slice(1, -1).sort()).toEqual(['app.json', 'keyMap.json', 'refMap.json']);
+});
+
+test('publishBuildDirectory moves a byte-identical idCounter.json first and pageRegistry.json last', async () => {
+  moved.length = 0;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-publish-order-'));
+  const buildDirectory = path.join(root, 'build');
+  const stagingDirectory = path.join(root, 'build-staging');
+  fs.mkdirSync(stagingDirectory, { recursive: true });
+  fs.mkdirSync(buildDirectory, { recursive: true });
+  ['app.json', 'idCounter.json', 'keyMap.json', 'pageRegistry.json'].forEach((file) => {
+    fs.writeFileSync(path.join(stagingDirectory, file), '{}');
+    fs.writeFileSync(path.join(buildDirectory, file), '{}');
+  });
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+  fs.rmSync(root, { recursive: true, force: true });
+
+  expect(moved).toEqual(['idCounter.json', 'pageRegistry.json']);
+});

package/manager/utils/publishBuildDirectory.test.mjs

@@ -0,0 +1,262 @@
+/*
+  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 fsPromises from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+
+import publishBuildDirectory from './publishBuildDirectory.mjs';
+
+// The publish-window tests move 200 files through several thread pool fs calls
+// each while a poller runs on every loop turn, and the locked-rename test waits
+// out the full 3.3 s retry schedule. On a loaded machine they pass jest's 5 s
+// default, and a timed-out poller then fails the next test.
+jest.setTimeout(30000);
+
+let root;
+let buildDirectory;
+let stagingDirectory;
+
+function write(directory, file, content) {
+  const filePath = path.join(directory, file);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+function read(file) {
+  return fs.readFileSync(path.join(buildDirectory, file), 'utf8');
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-publish-build-'));
+  buildDirectory = path.join(root, 'build');
+  stagingDirectory = path.join(root, 'build-staging');
+  write(stagingDirectory, 'pageRegistry.json', 'new');
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+function lockedError(code) {
+  return Object.assign(new Error(`${code}: resource busy or locked, rename`), { code });
+}
+
+test('publishBuildDirectory replaces live files with the staged build', async () => {
+  write(buildDirectory, 'app.json', 'old');
+  write(buildDirectory, 'connections/db.json', 'old');
+  write(stagingDirectory, 'app.json', 'new');
+  write(stagingDirectory, 'connections/db.json', 'new');
+  write(stagingDirectory, 'api/endpoint.json', 'new');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(read('app.json')).toBe('new');
+  expect(read('connections/db.json')).toBe('new');
+  expect(read('api/endpoint.json')).toBe('new');
+});
+
+test('publishBuildDirectory removes live files the new build did not write', async () => {
+  write(buildDirectory, 'app.json', 'old');
+  write(buildDirectory, 'connections/removed.json', 'old');
+  write(buildDirectory, 'pages/jit-page.json', 'old');
+  write(stagingDirectory, 'app.json', 'new');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(fs.existsSync(path.join(buildDirectory, 'connections/removed.json'))).toBe(false);
+  expect(fs.existsSync(path.join(buildDirectory, 'pages/jit-page.json'))).toBe(false);
+  expect(read('app.json')).toBe('new');
+});
+
+test('publishBuildDirectory removes the staging directory', async () => {
+  write(stagingDirectory, 'app.json', 'new');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(fs.existsSync(stagingDirectory)).toBe(false);
+});
+
+test('publishBuildDirectory creates the live directory on the first build', async () => {
+  write(stagingDirectory, 'app.json', 'new');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(read('app.json')).toBe('new');
+});
+
+test('an artifact present in both builds exists at every point of the publish', async () => {
+  write(buildDirectory, 'connections/db.json', 'old');
+  write(stagingDirectory, 'connections/db.json', 'new');
+  for (let i = 0; i < 200; i++) {
+    write(buildDirectory, `api/endpoint-${i}.json`, 'old');
+    write(stagingDirectory, `api/endpoint-${i}.json`, 'new');
+  }
+
+  let checks = 0;
+  let missing = 0;
+  let publishing = true;
+  const check = () => {
+    checks += 1;
+    if (!fs.existsSync(path.join(buildDirectory, 'connections/db.json'))) {
+      missing += 1;
+    }
+    if (publishing) {
+      setImmediate(check);
+    }
+  };
+  setImmediate(check);
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+  publishing = false;
+
+  expect(checks).toBeGreaterThan(1);
+  expect(missing).toBe(0);
+  expect(read('connections/db.json')).toBe('new');
+});
+
+test('the page registry arrives after every other new file and after stale files are removed', async () => {
+  write(buildDirectory, 'pageRegistry.json', 'old');
+  write(buildDirectory, 'pages/jit-page/jit-page.json', 'old');
+  for (let i = 0; i < 200; i++) {
+    write(buildDirectory, `api/endpoint-${i}.json`, 'old');
+    write(stagingDirectory, `api/endpoint-${i}.json`, 'new');
+  }
+
+  let checks = 0;
+  let early = 0;
+  let publishing = true;
+  const check = () => {
+    if (!publishing) {
+      return;
+    }
+    checks += 1;
+    if (read('pageRegistry.json') === 'new') {
+      const oldEndpoint = [...Array(200).keys()].some(
+        (i) => read(`api/endpoint-${i}.json`) === 'old'
+      );
+      const stalePage = fs.existsSync(path.join(buildDirectory, 'pages/jit-page/jit-page.json'));
+      if (oldEndpoint || stalePage) {
+        early += 1;
+      }
+    }
+    setImmediate(check);
+  };
+  setImmediate(check);
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+  publishing = false;
+
+  expect(checks).toBeGreaterThan(1);
+  expect(early).toBe(0);
+  expect(read('pageRegistry.json')).toBe('new');
+});
+
+test('publishBuildDirectory keeps the control files the manager and dev tools write', async () => {
+  write(buildDirectory, '.restart', '{"reason":"Added a block type"}');
+  write(buildDirectory, 'buildStatus.json', '{"status":"ok"}');
+  write(buildDirectory, 'invalidatePages', '1');
+  write(buildDirectory, 'reload', '1');
+  write(stagingDirectory, 'app.json', 'new');
+  write(stagingDirectory, 'pageRegistry.json', '{}');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(read('.restart')).toBe('{"reason":"Added a block type"}');
+  expect(read('buildStatus.json')).toBe('{"status":"ok"}');
+  expect(read('invalidatePages')).toBe('1');
+  expect(read('reload')).toBe('1');
+});
+
+test('publishBuildDirectory retries a rename while another process holds the file', async () => {
+  write(buildDirectory, 'app.json', 'old');
+  write(stagingDirectory, 'app.json', 'new');
+  jest
+    .spyOn(fsPromises, 'rename')
+    .mockRejectedValueOnce(lockedError('EPERM'))
+    .mockRejectedValueOnce(lockedError('EBUSY'));
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(read('app.json')).toBe('new');
+  expect(read('pageRegistry.json')).toBe('new');
+});
+
+test('publishBuildDirectory fails with the rename error when a file stays locked', async () => {
+  write(stagingDirectory, 'app.json', 'new');
+  const rename = jest.spyOn(fsPromises, 'rename').mockRejectedValue(lockedError('EPERM'));
+
+  await expect(publishBuildDirectory({ buildDirectory, stagingDirectory })).rejects.toThrow(
+    'EPERM: resource busy or locked, rename'
+  );
+  expect(rename).toHaveBeenCalledTimes(11);
+});
+
+function setMtime(file, seconds) {
+  fs.utimesSync(path.join(buildDirectory, file), seconds, seconds);
+}
+
+function mtime(file) {
+  return fs.statSync(path.join(buildDirectory, file)).mtimeMs;
+}
+
+test('publishBuildDirectory leaves an unchanged artifact in place and replaces a changed one', async () => {
+  write(buildDirectory, 'app.json', 'same');
+  write(buildDirectory, 'client/page.json', 'old');
+  write(buildDirectory, 'client/sized.json', 'aaa');
+  setMtime('app.json', 1000);
+  setMtime('client/page.json', 1000);
+  setMtime('client/sized.json', 1000);
+  write(stagingDirectory, 'app.json', 'same');
+  write(stagingDirectory, 'client/page.json', 'new');
+  write(stagingDirectory, 'client/sized.json', 'bbb');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(mtime('app.json')).toBe(1000 * 1000);
+  expect(read('client/page.json')).toBe('new');
+  expect(mtime('client/page.json')).not.toBe(1000 * 1000);
+  expect(read('client/sized.json')).toBe('bbb');
+  expect(fs.existsSync(stagingDirectory)).toBe(false);
+});
+
+test('publishBuildDirectory moves a byte-identical page registry and id counter anyway', async () => {
+  write(buildDirectory, 'pageRegistry.json', 'new');
+  write(buildDirectory, 'idCounter.json', '{"prefix":"a1b2"}');
+  setMtime('pageRegistry.json', 1000);
+  setMtime('idCounter.json', 1000);
+  write(stagingDirectory, 'idCounter.json', '{"prefix":"a1b2"}');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(mtime('pageRegistry.json')).not.toBe(1000 * 1000);
+  expect(mtime('idCounter.json')).not.toBe(1000 * 1000);
+});
+
+test('publishBuildDirectory removes stale files and keeps control files when artifacts are unchanged', async () => {
+  write(buildDirectory, 'app.json', 'same');
+  write(buildDirectory, 'jitMaps/abc-1-1.json', '{}');
+  write(buildDirectory, 'buildStatus.json', '{"status":"ok"}');
+  write(stagingDirectory, 'app.json', 'same');
+
+  await publishBuildDirectory({ buildDirectory, stagingDirectory });
+
+  expect(read('app.json')).toBe('same');
+  expect(fs.existsSync(path.join(buildDirectory, 'jitMaps/abc-1-1.json'))).toBe(false);
+  expect(read('buildStatus.json')).toBe('{"status":"ok"}');
+  expect(fs.existsSync(stagingDirectory)).toBe(false);
+});

package/manager/utils/readBasePath.mjs

@@ -0,0 +1,27 @@
+/*
+  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';
+
+// The build always writes config.json, and Vite reads basePath from the same
+// file when the child starts, so the manager and the child agree on it.
+function readBasePath({ directories }) {
+  const config = JSON.parse(fs.readFileSync(path.join(directories.build, 'config.json'), 'utf8'));
+  return config.basePath ?? '';
+}
+
+export default readBasePath;

package/manager/utils/readBasePath.test.mjs

@@ -0,0 +1,43 @@
+/*
+  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 readBasePath from './readBasePath.mjs';
+
+let buildDirectory;
+
+beforeEach(() => {
+  buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-read-base-path-'));
+});
+
+afterEach(() => {
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+test('readBasePath returns the basePath from the build config', () => {
+  fs.writeFileSync(path.join(buildDirectory, 'config.json'), JSON.stringify({ basePath: '/app' }));
+
+  expect(readBasePath({ directories: { build: buildDirectory } })).toEqual('/app');
+});
+
+test('readBasePath returns an empty string when the app sets no basePath', () => {
+  fs.writeFileSync(path.join(buildDirectory, 'config.json'), JSON.stringify({ theme: {} }));
+
+  expect(readBasePath({ directories: { build: buildDirectory } })).toEqual('');
+});

package/manager/utils/readBuildStatusWait.mjs

@@ -0,0 +1,67 @@
+/*
+  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.
+*/
+
+// A lowdefy_build_status call is a small JSON-RPC message. A body of unknown length,
+// or larger than this, is forwarded unread, so the proxy never holds a large body in
+// memory before the dev server has checked the request.
+const MAX_WAIT_BODY_BYTES = 64 * 1024;
+
+function parseJson(body) {
+  try {
+    return JSON.parse(body.toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isBuildStatusWaitCall(message) {
+  return (
+    message?.method === 'tools/call' &&
+    message.params?.name === 'lowdefy_build_status' &&
+    message.params?.arguments?.wait === true
+  );
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+// Whether a proxied request is a build-status wait: GET build-status?wait=true,
+// or the lowdefy_build_status MCP tool called with wait: true. Telling the
+// second apart means reading the body of every MCP POST (small JSON-RPC
+// messages), so it is returned for the proxy to forward; body is undefined
+// for any other request, whose body is still unread.
+async function readBuildStatusWait({ basePath, req }) {
+  const { pathname, searchParams } = new URL(req.url, 'http://localhost');
+  if (req.method === 'GET' && pathname === `${basePath}/lowdefy-docs/build-status`) {
+    return { wait: searchParams.get('wait') === 'true', body: undefined };
+  }
+  if (req.method !== 'POST' || pathname !== `${basePath}/lowdefy-docs/mcp`) {
+    return { wait: false, body: undefined };
+  }
+  const contentLength = Number(req.headers['content-length']);
+  if (!Number.isInteger(contentLength) || contentLength > MAX_WAIT_BODY_BYTES) {
+    return { wait: false, body: undefined };
+  }
+  const body = await readBody(req);
+  return { wait: [parseJson(body)].flat().some(isBuildStatusWaitCall), body };
+}
+
+export default readBuildStatusWait;

package/manager/utils/readManagerVersion.mjs

@@ -0,0 +1,30 @@
+/*
+  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';
+
+// The manager's own package.json - in an app, the CLI's copy in .lowdefy/dev,
+// which carries the installed server-dev version. Read from the file, not
+// npm_package_version, which only a package manager's `run` sets: the CLI
+// starts the manager with node directly.
+function readManagerVersion() {
+  const packageJson = JSON.parse(
+    fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+  );
+  return packageJson.version;
+}
+
+export default readManagerVersion;

package/manager/utils/readManagerVersion.test.mjs

@@ -0,0 +1,35 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+
+import readManagerVersion from './readManagerVersion.mjs';
+
+test('readManagerVersion reads the version from the server package.json, without npm_package_version', () => {
+  const saved = process.env.npm_package_version;
+  delete process.env.npm_package_version;
+  try {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+    );
+    expect(readManagerVersion()).toBe(packageJson.version);
+    expect(packageJson.name).toBe('@lowdefy/server-dev');
+  } finally {
+    if (saved !== undefined) {
+      process.env.npm_package_version = saved;
+    }
+  }
+});

package/manager/utils/readPluginDefinitions.mjs

@@ -0,0 +1,36 @@
+/*
+  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 { get } from '@lowdefy/helpers';
+import { readFile } from '@lowdefy/node-utils';
+import YAML from 'yaml';
+
+// The plugins lowdefy.yaml lists, read straight from the file: the plugin
+// type maps are read before the config build, which needs them.
+async function readPluginDefinitions({ directories }) {
+  let lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yaml'));
+  if (!lowdefyYaml) {
+    lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yml'));
+  }
+  if (!lowdefyYaml) {
+    return [];
+  }
+  const lowdefy = YAML.parse(lowdefyYaml);
+  return get(lowdefy, 'plugins', { default: [] });
+}
+
+export default readPluginDefinitions;

package/manager/utils/resolveDevAuthUrl.mjs

@@ -0,0 +1,58 @@
+/*
+  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 LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+// The auth canonical origin for this dev server. BetterAuth trusts only that
+// origin (the CSRF Origin check, callbackURL targets) and builds magic-link and
+// verification links from it. A developer's BETTER_AUTH_URL usually names the
+// port they ran on before - http://localhost:3000 - but the dev server's port
+// is chosen at start (the hub allocates one, a busy port is skipped), and a
+// loopback origin on another port refuses every sign-in from the page this
+// server serves with "Invalid origin". So a plain-http loopback BETTER_AUTH_URL
+// with an explicit port follows the dev server's port.
+//
+// Everything else is the developer's deliberate choice and is kept: a tunnel or
+// LAN host, and a loopback origin the dev server cannot be serving itself - an
+// https one (it speaks plain http) or one on the default port (80 needs root),
+// which is a local reverse proxy (Caddy, mkcert) in front of it. An unset one
+// stays unset: the dev server then derives the origin from each request.
+//
+// Returns the origin to use and whether it was rewritten, so the caller reports
+// a rewrite and not a mere difference in whitespace.
+function resolveDevAuthUrl({ configured, port }) {
+  const value = configured?.trim();
+  if (!value) return { authUrl: value, rewritten: false };
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return { authUrl: value, rewritten: false };
+  }
+  if (
+    !LOOPBACK_HOSTNAMES.has(url.hostname) ||
+    url.protocol !== 'http:' ||
+    url.port === '' ||
+    url.port === String(port)
+  ) {
+    return { authUrl: value, rewritten: false };
+  }
+  url.port = String(port);
+  const authUrl = url.pathname === '/' ? url.origin : `${url.origin}${url.pathname}`;
+  return { authUrl, rewritten: true };
+}
+
+export default resolveDevAuthUrl;