@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/server/createLowdefyContext.test.mjs

@@ -25,19 +25,42 @@ import { operatorsServer } from '@lowdefy/operators-js';
 const secret = 'planted-dev-secret';
 process.env.LOWDEFY_SECRET_TEST = secret;
 
-jest.unstable_mockModule('@lowdefy/api', () => ({ createApiContext: jest.fn() }));
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  createApiContext: jest.fn(),
+  createRequestSignal: jest.fn(({ clientSignal, timeoutSignal }) =>
+    timeoutSignal ? AbortSignal.any([clientSignal, timeoutSignal]) : clientSignal
+  ),
+  // Returns what the server passes, so the test reads the auth-hook system context inputs.
+  createSystemContext: jest.fn((options) => options),
+  ensureMcpOauthResource: jest.fn(async () => {}),
+  normalizeInjectedCaller: jest.fn((user) => user),
+  resolveAuthentication: jest.fn(async () => {}),
+  resolvePinnedOrganization: jest.fn(async () => {}),
+  resolveTenantPreflight: jest.fn(async () => {}),
+}));
 jest.unstable_mockModule('../build/appMeta.js', () => ({ default: {} }));
 jest.unstable_mockModule('../build/config.js', () => ({ default: {} }));
+jest.unstable_mockModule('../build/auth.js', () => ({ default: {} }));
 jest.unstable_mockModule('../build/i18n.js', () => ({ default: {} }));
 jest.unstable_mockModule('./log/createHandleError.js', () => ({
   default: jest.fn(() => jest.fn()),
 }));
 jest.unstable_mockModule('./log/createLogger.js', () => ({
-  default: jest.fn(() => ({ debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() })),
+  default: jest.fn(() => ({
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  })),
 }));
 jest.unstable_mockModule('./fileCache.js', () => ({ default: {} }));
-jest.unstable_mockModule('./auth/session.js', () => ({ default: jest.fn(async () => undefined) }));
-jest.unstable_mockModule('./auth/strategies.js', () => ({ default: jest.fn(async () => null) }));
+jest.unstable_mockModule('./auth/getAuth.js', () => ({ default: jest.fn(() => null) }));
+jest.unstable_mockModule('./auth/getHeadlessUser.js', () => ({
+  default: jest.fn(() => null),
+}));
+jest.unstable_mockModule('./auth/getMockUser.js', () => ({ default: jest.fn(() => undefined) }));
+jest.unstable_mockModule('./auth/getStrategies.js', () => ({ default: jest.fn(() => null) }));
+jest.unstable_mockModule('./loadDynamicJsMap.js', () => ({ default: jest.fn(() => ({})) }));
 jest.unstable_mockModule('./log/logRequest.js', () => ({ default: jest.fn() }));
 
 // createLowdefyContext statically imports the app build's plugin artifacts,
@@ -51,10 +74,12 @@ const fixtures = [
   { file: 'connections.js', content: 'export default {};\n' },
   {
     file: 'notifications.js',
-    content: 'export default {};\nexport const interpolateProperties = () => {};\nexport const renderEmail = () => {};\n',
+    content:
+      'export default {};\nexport const interpolateProperties = () => {};\nexport const renderEmail = () => {};\n',
   },
   { file: path.join('operators', 'server.js'), content: 'export default {};\n' },
   { file: path.join('operators', 'serverJsMap.js'), content: 'export default {};\n' },
+  { file: 'steps.js', content: 'export default {};\n' },
   { file: 'websockets.js', content: 'export default {};\n' },
 ].map(({ file, content }) => ({ absolutePath: path.join(pluginsDir, file), content }));
 
@@ -69,9 +94,14 @@ fixtures.forEach(({ absolutePath, content }) => {
 
 // A checkout that has built an app already holds real artifacts here, which import plugins this
 // package does not depend on, so the stubs are also mocked over whatever is on disk.
+// The connection plugin map carries each type's meta.dataSet, which the data session gate reads.
+const connectionPlugins = {
+  MongoDBCollection: { meta: { tenant: true, dataSet: 'redirect' } },
+  Knex: {},
+};
 fixtures.forEach(({ absolutePath }) => {
   jest.unstable_mockModule(absolutePath, () => ({
-    default: {},
+    default: absolutePath.endsWith(`${path.sep}connections.js`) ? connectionPlugins : {},
     interpolateProperties: () => {},
     renderEmail: () => {},
   }));
@@ -82,13 +112,24 @@ afterAll(() => {
 });
 
 const { default: createLowdefyContext } = await import('./createLowdefyContext.js');
+const { default: createSystemContext } = await import('./auth/createSystemContext.js');
+const { journeyActorToken } = await import('./auth/journeyActor.js');
+const { createApiContext } = await import('@lowdefy/api');
+const { openMutantRun } = await import('./mutants/mutantRuns.js');
 
-function createHonoContext({ path: reqPath = '/api/request/foo' } = {}) {
+function createHonoContext({
+  path: reqPath = '/api/request/foo',
+  requestTimeoutSignal,
+  headers = {},
+} = {}) {
+  const variables = { requestTimeoutSignal };
   return {
+    get: (key) => variables[key],
     req: {
-      header: (name) => (name ? undefined : {}),
+      header: (name) => (name ? headers[name] : headers),
       path: reqPath,
       method: 'POST',
+      raw: { headers: new Headers(), signal: new AbortController().signal },
       url: `http://localhost${reqPath}`,
     },
   };
@@ -99,6 +140,23 @@ test('createLowdefyContext sets mode to dev', async () => {
   expect(context.mode).toEqual('dev');
 });
 
+test('createLowdefyContext cancels the request work with the incoming request signal', async () => {
+  const c = createHonoContext();
+  const context = await createLowdefyContext({ c });
+  expect(context.signal).toBe(c.req.raw.signal);
+});
+
+test('createLowdefyContext cancels the request work when the request timeout answers first', async () => {
+  const timeout = new AbortController();
+  const c = createHonoContext({ requestTimeoutSignal: timeout.signal });
+  const context = await createLowdefyContext({ c });
+  expect(context.signal.aborted).toBe(false);
+  const reason = new DOMException('The request timeout of 20ms was exceeded.', 'TimeoutError');
+  timeout.abort(reason);
+  expect(context.signal.aborted).toBe(true);
+  expect(context.signal.reason).toBe(reason);
+});
+
 test('createLowdefyContext scrubSecrets redacts a planted secret', async () => {
   const context = await createLowdefyContext({ c: createHonoContext() });
   expect(context.scrubSecrets(`token ${secret} end`)).toEqual('token [REDACTED] end');
@@ -115,3 +173,268 @@ test('_error on a dev context reads a caught message with a planted secret scrub
     'Connect failed with [REDACTED].'
   );
 });
+
+test('the auth-hook system context is built with mode dev and a scrubSecrets that redacts', () => {
+  const context = createSystemContext({ auth: null });
+  expect(context.mode).toEqual('dev');
+  expect(context.scrubSecrets(`token ${secret} end`)).toEqual('token [REDACTED] end');
+});
+
+test('createLowdefyContext forwards the verified loopback journey cookies on loopbackHeaders', async () => {
+  const context = await createLowdefyContext({
+    c: createHonoContext({
+      headers: {
+        cookie: `session=abc; lowdefy_journey_actor=${journeyActorToken}.203.0.113.7; lowdefy_journey_mutant=${journeyActorToken}.run1`,
+      },
+    }),
+  });
+  expect(context.loopbackHeaders).toEqual({
+    cookie: `lowdefy_journey_mutant=${journeyActorToken}.run1`,
+  });
+});
+
+test('createLowdefyContext forwards no Cookie header when the request carries no journey cookie', async () => {
+  const context = await createLowdefyContext({ c: createHonoContext() });
+  expect(context.loopbackHeaders).toEqual({});
+});
+
+test('createLowdefyContext serves the mutated artifact to a request whose cookie names an open mutant run', async () => {
+  const artifact = { id: 'page:form', blocks: [] };
+  createApiContext.mockImplementationOnce((context) => {
+    context.readConfigFile = async () => artifact;
+  });
+  const opened = openMutantRun({
+    mutant: {
+      buildId: 'b',
+      artifact: 'pages/form.json',
+      key: 'missing',
+      arg: null,
+      operator: 'drop-block',
+    },
+  });
+  const context = await createLowdefyContext({
+    c: createHonoContext({
+      headers: { cookie: `lowdefy_journey_mutant=${journeyActorToken}.${opened.cookiePayload}` },
+    }),
+  });
+  await context.readConfigFile('pages/form.json');
+  expect(opened.run.misses).toEqual([{ reason: 'key not found', path: 'pages/form.json' }]);
+  expect(context.loopbackHeaders.cookie).toEqual(
+    `lowdefy_journey_mutant=${journeyActorToken}.${opened.cookiePayload}`
+  );
+  opened.close();
+});
+
+test('createLowdefyContext leaves readConfigFile alone without a mutant cookie', async () => {
+  const readConfigFile = async () => ({});
+  createApiContext.mockImplementationOnce((context) => {
+    context.readConfigFile = readConfigFile;
+  });
+  const context = await createLowdefyContext({ c: createHonoContext() });
+  expect(context.readConfigFile).toBe(readConfigFile);
+});
+
+const { default: dataSessionRegistry } = await import('../docs/dataSets/dataSessionRegistry.js');
+const { default: getAuth } = await import('./auth/getAuth.js');
+const { default: getHeadlessUser } = await import('./auth/getHeadlessUser.js');
+const { default: getMockUser } = await import('./auth/getMockUser.js');
+const { resolveAuthentication, resolveTenantPreflight } = await import('@lowdefy/api');
+
+describe('data sessions', () => {
+  const realArtifact = {
+    type: 'MongoDBCollection',
+    properties: { databaseUri: { _secret: 'MONGODB_URI' }, collection: 'tickets' },
+  };
+
+  function registerSession(state = 'open') {
+    const session = {
+      id: 'session1',
+      name: 'staging-sample',
+      state,
+      databaseUri: 'mongodb://memory/',
+      prefix: 'ld_aaaaaaaaaaaa',
+      databaseName: 'ld_aaaaaaaaaaaa_0',
+      databases: new Map([[JSON.stringify(['secret:MONGODB_URI', null]), 'ld_aaaaaaaaaaaa_0']]),
+      databaseCount: 1,
+      work: new Set(),
+    };
+    dataSessionRegistry.set(session.id, session);
+    return session;
+  }
+
+  function mockReadConfigFile() {
+    const readConfigFile = jest.fn(async () => realArtifact);
+    createApiContext.mockImplementationOnce((context) => {
+      context.readConfigFile = readConfigFile;
+    });
+    return readConfigFile;
+  }
+
+  afterEach(() => {
+    dataSessionRegistry.clear();
+  });
+
+  test('a verified data cookie redirects connections, tracks background work, forwards the cookie and skips the tenant preflight', async () => {
+    const session = registerSession();
+    mockReadConfigFile();
+    getHeadlessUser.mockReturnValueOnce({ user: { id: 'u_1', roles: ['admin'] }, explicit: true });
+    const cookie = `lowdefy_journey_data=${journeyActorToken}.session1`;
+    const context = await createLowdefyContext({ c: createHonoContext({ headers: { cookie } }) });
+    expect((await context.readConfigFile('connections/tickets.json')).properties).toEqual({
+      databaseUri: 'mongodb://memory/',
+      databaseName: 'ld_aaaaaaaaaaaa_0',
+      collection: 'tickets',
+    });
+    expect(context.dataSet).toEqual('staging-sample');
+    expect(context.loopbackHeaders).toEqual({ cookie });
+    expect(resolveTenantPreflight).not.toHaveBeenCalled();
+    let release;
+    const work = new Promise((resolve) => {
+      release = resolve;
+    });
+    context.waitUntil(work);
+    expect(session.work.has(work)).toBe(true);
+    release();
+    await work;
+    await Promise.resolve();
+    expect(session.work.size).toBe(0);
+  });
+
+  test('a data-session request refuses a connection whose type declares no dataSet, naming it', async () => {
+    registerSession();
+    createApiContext.mockImplementationOnce((context) => {
+      context.readConfigFile = async () => ({
+        connectionId: 'warehouse',
+        type: 'Knex',
+        properties: { client: 'pg', connection: 'postgres://real/' },
+      });
+    });
+    const context = await createLowdefyContext({
+      c: createHonoContext({
+        headers: { cookie: `lowdefy_journey_data=${journeyActorToken}.session1` },
+      }),
+    });
+    await expect(context.readConfigFile('connections/warehouse.json')).rejects.toThrow(
+      'Connection "warehouse" (type Knex) cannot run under data set "staging-sample": its type does not say how to redirect it.'
+    );
+  });
+
+  test('a data session passed by a dev tool call redirects connections and rides the detached hop as a data cookie', async () => {
+    const session = registerSession();
+    mockReadConfigFile();
+    const context = await createLowdefyContext({ c: createHonoContext(), dataSession: session });
+    expect((await context.readConfigFile('connections/tickets.json')).properties).toEqual({
+      databaseUri: 'mongodb://memory/',
+      databaseName: 'ld_aaaaaaaaaaaa_0',
+      collection: 'tickets',
+    });
+    expect(context.dataSet).toEqual('staging-sample');
+    expect(context.loopbackHeaders).toEqual({
+      cookie: `lowdefy_journey_data=${journeyActorToken}.session1`,
+    });
+  });
+
+  test('a data cookie and a mutant cookie are both forwarded on loopbackHeaders', async () => {
+    registerSession();
+    const opened = openMutantRun({
+      mutant: {
+        buildId: 'b',
+        artifact: 'pages/form.json',
+        key: 'k',
+        arg: null,
+        operator: 'drop-block',
+      },
+    });
+    const data = `lowdefy_journey_data=${journeyActorToken}.session1`;
+    const mutant = `lowdefy_journey_mutant=${journeyActorToken}.${opened.cookiePayload}`;
+    const context = await createLowdefyContext({
+      c: createHonoContext({ headers: { cookie: `${mutant}; ${data}` } }),
+    });
+    expect(context.loopbackHeaders).toEqual({ cookie: `${data}; ${mutant}` });
+    opened.close();
+  });
+
+  test('a wrong token or no data cookie gets no redirect, no waitUntil and no data set', async () => {
+    registerSession();
+    for (const headers of [{ cookie: 'lowdefy_journey_data=forged.session1' }, {}]) {
+      const readConfigFile = mockReadConfigFile();
+      const context = await createLowdefyContext({ c: createHonoContext({ headers }) });
+      expect(context.readConfigFile).toBe(readConfigFile);
+      expect(context.waitUntil).toBeUndefined();
+      expect(context.dataSet).toBeUndefined();
+      expect(context.loopbackHeaders).toEqual({});
+    }
+    expect(resolveTenantPreflight).toHaveBeenCalledTimes(2);
+  });
+
+  test('a verified data cookie for a closed or unknown session is answered 410 and reads no database', async () => {
+    const session = registerSession();
+    dataSessionRegistry.delete(session.id);
+    for (const id of ['session1', 'never-opened']) {
+      const readConfigFile = mockReadConfigFile();
+      const error = await createLowdefyContext({
+        c: createHonoContext({
+          headers: { cookie: `lowdefy_journey_data=${journeyActorToken}.${id}` },
+        }),
+      }).catch((caught) => caught);
+      expect(error.status).toBe(410);
+      const response = error.getResponse();
+      expect(response.status).toBe(410);
+      expect(await response.json()).toEqual({
+        name: 'DataSessionEnded',
+        message: `Data session ${id} has ended; this request outlived its journey.`,
+      });
+      expect(readConfigFile).not.toHaveBeenCalled();
+      createApiContext.mockReset();
+    }
+    expect(getAuth).not.toHaveBeenCalled();
+  });
+
+  test('a data-session request with no headless cookie gets no auth engine and no user', async () => {
+    registerSession();
+    const context = await createLowdefyContext({
+      c: createHonoContext({
+        path: '/api/detached/nightly',
+        headers: { cookie: `lowdefy_journey_data=${journeyActorToken}.session1` },
+      }),
+    });
+    expect(context.auth).toBeNull();
+    expect(context.user).toBeNull();
+    expect(getAuth).not.toHaveBeenCalled();
+    expect(resolveAuthentication).not.toHaveBeenCalled();
+  });
+});
+
+describe('who a headless caller is under a dev mock user', () => {
+  const mockUser = { id: 'mock', roles: ['mock-role'] };
+
+  test('a journey user the caller named wins over the mock user', async () => {
+    getMockUser.mockReturnValueOnce(mockUser);
+    getHeadlessUser.mockReturnValueOnce({
+      user: { id: 'lowdefy-headless', name: 'Lowdefy Headless', roles: ['admin'] },
+      explicit: true,
+    });
+    const context = await createLowdefyContext({ c: createHonoContext() });
+    expect(context.auth).toBeNull();
+    expect(context.user.roles).toEqual(['admin']);
+  });
+
+  test('the roleless headless default yields to the mock user', async () => {
+    getMockUser.mockReturnValueOnce(mockUser);
+    getHeadlessUser.mockReturnValueOnce({
+      user: { id: 'lowdefy-headless', name: 'Lowdefy Headless', roles: [] },
+      explicit: false,
+    });
+    const context = await createLowdefyContext({ c: createHonoContext() });
+    expect(context.user).toEqual(mockUser);
+  });
+
+  test('the roleless headless default is the caller when no mock user is active', async () => {
+    getHeadlessUser.mockReturnValueOnce({
+      user: { id: 'lowdefy-headless', name: 'Lowdefy Headless', roles: [] },
+      explicit: false,
+    });
+    const context = await createLowdefyContext({ c: createHonoContext() });
+    expect(context.user).toEqual({ id: 'lowdefy-headless', name: 'Lowdefy Headless', roles: [] });
+  });
+});

package/lib/server/getClientAddress.js

@@ -0,0 +1,51 @@
+/*
+  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 net from 'node:net';
+import { type } from '@lowdefy/helpers';
+import { createClientAddressResolver } from '@lowdefy/node-utils';
+
+import lowdefyConfig from '../build/config.js';
+import { JOURNEY_COOKIES, readJourneyCookie } from './journeyCookies.js';
+
+const resolveClientAddress = createClientAddressResolver({
+  trustedProxies: lowdefyConfig.trustedProxies,
+});
+
+// The actor cookie's payload is the address; see journeyActor.js.
+function readJourneyActorAddress(cookieHeader) {
+  const address = readJourneyCookie({ cookieHeader, name: JOURNEY_COOKIES.actor.name });
+  if (address === null || net.isIP(address) === 0) {
+    return null;
+  }
+  return address;
+}
+
+// The dev server resolves the client address the way the production server
+// does - the connection peer, or the hop behind a trusted proxy - except that
+// its own headless browser gives each journey actor an address of its own.
+function getClientAddress(c) {
+  const journeyActorAddress = readJourneyActorAddress(c.req.header('cookie'));
+  if (!type.isNone(journeyActorAddress)) {
+    return journeyActorAddress;
+  }
+  return resolveClientAddress({
+    peerAddress: c.env?.incoming?.socket?.remoteAddress,
+    forwardedFor: c.req.header('x-forwarded-for'),
+  });
+}
+
+export default getClientAddress;

package/lib/server/getClientAddress.test.mjs

@@ -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 { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+jest.unstable_mockModule('../build/config.js', () => ({ default: {} }));
+
+const { default: getClientAddress } = await import('./getClientAddress.js');
+const { journeyActorToken } = await import('./auth/journeyActor.js');
+const { JOURNEY_COOKIES } = await import('./journeyCookies.js');
+
+async function resolve(headers) {
+  const app = new Hono();
+  app.get('/', (c) => c.json({ clientAddress: getClientAddress(c) }));
+  const env = { incoming: { socket: { remoteAddress: '127.0.0.1' } } };
+  const response = await app.request('/', { headers }, env);
+  return (await response.json()).clientAddress;
+}
+
+test.each([
+  [
+    'the actor address from its headless journey cookie',
+    `${journeyActorToken}.203.0.113.7`,
+    '203.0.113.7',
+  ],
+  ['the peer when the cookie carries another token', `${'0'.repeat(64)}.203.0.113.7`, '127.0.0.1'],
+  ['the peer when the cookie carries a shorter token', 'abc.203.0.113.7', '127.0.0.1'],
+  ['the peer when the cookie has no address', `${journeyActorToken}`, '127.0.0.1'],
+  [
+    'the peer when the cookie address is not an IP',
+    `${journeyActorToken}.example.com`,
+    '127.0.0.1',
+  ],
+])('the dev getClientAddress resolves %s', async (_, value, expected) => {
+  expect(await resolve({ cookie: `session=abc; ${JOURNEY_COOKIES.actor.name}=${value}` })).toBe(
+    expected
+  );
+});
+
+test('the dev getClientAddress ignores X-Forwarded-For without trusted proxies', async () => {
+  expect(await resolve({ 'x-forwarded-for': '203.0.113.9' })).toBe('127.0.0.1');
+});

package/lib/server/getPageJitEnrichment.test.mjs

@@ -53,12 +53,16 @@ test('getPageJitEnrichment scopes string-form, object-form, and args-nested _js
   expect(jsEntries).not.toContain("'hashAbsent'");
 });
 
+const zap = { node: [['path', { d: 'M4 14 14 3' }]] };
+const star = { node: [['path', { d: 'M12 2 15 9' }]] };
+const other = { node: [['path', { d: 'M0 0' }]] };
+
 test('getPageJitEnrichment discovers an icon name that appears only inside a _js source', () => {
   const client = {
-    // The icon name lives only in the function body, in double quotes — the
+    // The icon name lives only in the function body, single-quoted — the
     // served pageConfig has this replaced by the hash, so scanning the config
-    // alone would miss it. Only FiZap is a real dynamic icon.
-    hashIcon: 'return on ? "FiZap" : "FiZapOff";',
+    // alone would miss it. Only Zap is a dynamic icon.
+    hashIcon: "return on ? 'Zap' : 'ZapOff';",
   };
   const pageConfig = {
     id: 'p',
@@ -67,23 +71,37 @@ test('getPageJitEnrichment discovers an icon name that appears only inside a _js
 
   const { dynamicIcons } = getPageJitEnrichment({
     pageConfig,
-    buildContext: buildContext({ client, dynamicIconData: { FiZap: { tag: 'svg' } } }),
+    buildContext: buildContext({ client, dynamicIconData: { Zap: zap } }),
   });
 
-  expect(dynamicIcons).toEqual({ FiZap: { tag: 'svg' } });
+  expect(dynamicIcons).toEqual({ Zap: zap });
 });
 
 test('getPageJitEnrichment scopes icons referenced directly in the page config', () => {
-  const pageConfig = { id: 'p', blocks: [{ properties: { icon: 'FiStar' } }] };
+  const pageConfig = { id: 'p', blocks: [{ properties: { icon: 'Star' } }] };
 
   const { dynamicIcons } = getPageJitEnrichment({
     pageConfig,
-    buildContext: buildContext({
-      dynamicIconData: { FiStar: { tag: 'svg' }, FiOther: { tag: 'svg' } },
-    }),
+    buildContext: buildContext({ dynamicIconData: { Star: star, Other: other } }),
   });
 
-  expect(dynamicIcons).toEqual({ FiStar: { tag: 'svg' } });
+  expect(dynamicIcons).toEqual({ Star: star });
+});
+
+test('getPageJitEnrichment scopes icons named in data-icon attributes inside HTML', () => {
+  const { dynamicIcons } = getPageJitEnrichment({
+    pageConfig: { id: 'p', blocks: [{ properties: { html: '<i data-icon="lucide:Star"></i>' } }] },
+    buildContext: buildContext({ dynamicIconData: { 'lucide:Star': star, Other: other } }),
+  });
+  expect(dynamicIcons).toEqual({ 'lucide:Star': star });
+});
+
+test('getPageJitEnrichment scopes semantic icon names used on the page', () => {
+  const { dynamicIcons } = getPageJitEnrichment({
+    pageConfig: { id: 'p', blocks: [{ properties: { icon: 'edit' } }] },
+    buildContext: buildContext({ dynamicIconData: { edit: star, delete: other } }),
+  });
+  expect(dynamicIcons).toEqual({ edit: star });
 });
 
 test('getPageJitEnrichment returns {} when there is no build context', () => {
@@ -97,7 +115,7 @@ test('getPageJitEnrichment omits both fields when the page has no dynamic _js or
     pageConfig,
     buildContext: buildContext({
       client: { hashUnused: 'return 1;' },
-      dynamicIconData: { FiZap: {} },
+      dynamicIconData: { Zap: zap },
     }),
   });
 

package/lib/server/hashConfigContent.js

@@ -0,0 +1,26 @@
+/*
+  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 crypto from 'node:crypto';
+
+// The hash a page build record keeps for a config file's content, as
+// readConfigFile returned it: 'missing' for a file that does not exist.
+function hashConfigContent(content) {
+  if (content === null) return 'missing';
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+export default hashConfigContent;

package/lib/server/importAppCode.test.mjs

@@ -0,0 +1,57 @@
+/*
+  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 { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { jest } from '@jest/globals';
+
+jest.setTimeout(60000);
+
+const fixture = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'testFixtures/importAppCodeTwice.mjs'
+);
+
+let configDir;
+
+beforeEach(() => {
+  configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-import-app-code-'));
+  fs.writeFileSync(path.join(configDir, 'package.json'), '{ "type": "module" }');
+});
+
+afterEach(() => {
+  fs.rmSync(configDir, { recursive: true, force: true });
+});
+
+// The dev server's JIT page builds import app code through Vite's SSR module
+// runner when @lowdefy/build is linked (the monorepo), and natively when it is
+// installed from npm.
+test.each(['vite', 'node'])(
+  'importAppCode loaded by %s imports an edited transformer again and reuses an unchanged one',
+  async (loader) => {
+    const { stdout } = await promisify(execFile)(process.execPath, [fixture, loader, configDir]);
+    expect(JSON.parse(stdout)).toEqual({
+      first: 'before',
+      edited: 'after',
+      unchangedReused: true,
+    });
+  }
+);