@lowdefy/server-dev 5.6.0 → 6.0.0

package/src/routes/feedback.test.mjs

@@ -0,0 +1,204 @@
+/*
+  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 { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+// enrichFeedback (findConfig → force-builds a page) is covered on its own in
+// lib/docs/formatFeedback.test.mjs — here it's stubbed as a pass-through so
+// this file only exercises the route: origin check, validation, and enrich +
+// format wiring.
+const mockEnrichFeedback = jest.fn(async ({ batch }) => batch);
+jest.unstable_mockModule('../../lib/docs/enrichFeedback.js', () => ({
+  default: mockEnrichFeedback,
+}));
+const mockCaptureAnnotatedScreenshot = jest.fn(async () => ({
+  path: '.lowdefy/annotations/test.png',
+}));
+jest.unstable_mockModule('../../lib/docs/captureAnnotatedScreenshot.js', () => ({
+  default: mockCaptureAnnotatedScreenshot,
+}));
+
+const { default: feedbackHandler } = await import('./feedback.js');
+
+function createApp() {
+  const app = new Hono();
+  app.all('/api/feedback', feedbackHandler);
+  return app;
+}
+
+let configDirectory;
+const originalConfigDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-feedback-test-'));
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+});
+
+afterEach(() => {
+  mockEnrichFeedback.mockClear();
+  mockCaptureAnnotatedScreenshot.mockClear();
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+  if (originalConfigDirectory === undefined) {
+    delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+  } else {
+    process.env.LOWDEFY_DIRECTORY_CONFIG = originalConfigDirectory;
+  }
+});
+
+test('feedbackHandler returns 403 when the Origin header is missing', async () => {
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: { host: 'localhost:3001', 'content-type': 'application/json' },
+    body: JSON.stringify({ annotations: [] }),
+  });
+  expect(res.status).toEqual(403);
+});
+
+test('feedbackHandler returns 403 when the Origin host does not match the request host', async () => {
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://evil.example.com',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ annotations: [] }),
+  });
+  expect(res.status).toEqual(403);
+});
+
+test('feedbackHandler returns 400 with a helpful message when annotations is missing', async () => {
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://localhost:3001',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ pageId: 'login' }),
+  });
+  expect(res.status).toEqual(400);
+  const body = await res.json();
+  expect(body.error).toMatch(/annotations/);
+  expect(body.error).toMatch(/\/lowdefy-docs/);
+});
+
+test('feedbackHandler enriches a valid batch and returns the formatted text', async () => {
+  const batch = { pageId: 'login', annotations: [{ id: '1', kind: 'region', comment: 'x' }] };
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://localhost:3001',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(batch),
+  });
+
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.ok).toBe(true);
+  expect(typeof body.formatted).toBe('string');
+  expect(body.formatted).toContain('login');
+  expect(mockEnrichFeedback).toHaveBeenCalledWith({ batch });
+});
+
+// A real 1x1 red PNG so the saved file is a valid image, not just bytes.
+const PNG_1X1_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
+
+test('feedbackHandler saves a tab-captured screenshot and skips the headless capture', async () => {
+  const batch = {
+    pageId: 'dashboard',
+    annotations: [{ id: '1', kind: 'region', comment: 'x' }],
+    screenshot: `data:image/png;base64,${PNG_1X1_BASE64}`,
+  };
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://localhost:3001',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(batch),
+  });
+
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.ok).toBe(true);
+  expect(body.formatted).toContain('.lowdefy/annotations/dashboard-');
+  // The data URL must never leak into the agent-readable text.
+  expect(body.formatted).not.toContain(PNG_1X1_BASE64);
+  expect(mockCaptureAnnotatedScreenshot).not.toHaveBeenCalled();
+
+  const dir = path.join(configDirectory, '.lowdefy', 'annotations');
+  const files = fs.readdirSync(dir);
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^dashboard-.*\.png$/);
+  expect(fs.readFileSync(path.join(dir, files[0]))).toEqual(
+    Buffer.from(PNG_1X1_BASE64, 'base64')
+  );
+});
+
+test('feedbackHandler falls back to the headless capture when the screenshot is not a PNG data URL', async () => {
+  const batch = {
+    pageId: 'dashboard',
+    annotations: [{ id: '1', kind: 'region', comment: 'x' }],
+    screenshot: 'data:image/jpeg;base64,notpng',
+  };
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://localhost:3001',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(batch),
+  });
+
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.ok).toBe(true);
+  // Not a valid tab capture — no file saved, and no screenshotPath claimed
+  // for it (the invalid-string branch logs a warning instead).
+  expect(fs.existsSync(path.join(configDirectory, '.lowdefy', 'annotations'))).toBe(false);
+});
+
+test('feedbackHandler uses the headless capture when the batch has no screenshot', async () => {
+  const batch = {
+    pageId: 'dashboard',
+    annotations: [{ id: '1', kind: 'region', comment: 'x' }],
+  };
+  const res = await createApp().request('/api/feedback', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin: 'http://localhost:3001',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(batch),
+  });
+
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.formatted).toContain('.lowdefy/annotations/dashboard-');
+  expect(mockCaptureAnnotatedScreenshot).toHaveBeenCalledTimes(1);
+});

package/src/routes/jitPage.js

@@ -0,0 +1,86 @@
+/*
+  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 { getPageConfig } from '@lowdefy/api';
+
+import buildPageIfNeeded, { getPageJitEnrichment } from '../../lib/server/jitPageBuilder.js';
+import getPathSegments from '../lib/getPathSegments.js';
+
+// JIT page build + config response. The response shapes are a frozen contract
+// with the dev client:
+//   200 { installing: true, packages }  — plugin install in progress, client polls
+//   500 { buildError: true, errors, message, source }  — build failed
+//   404 'Page not found.'
+//   200 pageConfig (+ _warnings, + _jsEntries module text, + _dynamicIcons data)
+async function jitPageHandler(c) {
+  const context = c.get('lowdefyContext');
+  const pageId = getPathSegments(c, '/api/page/').join('/');
+
+  let buildResult;
+  try {
+    buildResult = await buildPageIfNeeded({
+      pageId,
+      buildDirectory: context.buildDirectory,
+      configDirectory: context.configDirectory,
+    });
+  } catch (error) {
+    const rawErrors = error.buildErrors ?? [error];
+    const errors = [];
+    for (const err of rawErrors) {
+      await context.handleError(err);
+      errors.push({
+        type: err.name ?? 'Error',
+        message: err.message,
+        source: err.source ?? null,
+        stack: err.stack ?? null,
+      });
+    }
+    return c.json(
+      {
+        buildError: true,
+        errors,
+        // Keep top-level message/source for backward compatibility
+        message: error.message,
+        source: error.source ?? null,
+      },
+      500
+    );
+  }
+
+  if (buildResult && buildResult.installing) {
+    return c.json({
+      installing: true,
+      packages: buildResult.packages,
+    });
+  }
+
+  const pageConfig = await getPageConfig(context, { pageId, urlQuery: c.req.query() });
+  if (pageConfig === null) {
+    return c.text('Page not found.', 404);
+  }
+  if (buildResult?.warnings?.length > 0) {
+    pageConfig._warnings = buildResult.warnings;
+  }
+  // Fold this page's JIT-discovered _js entries and dynamic icons into the
+  // response the client already awaits, so first paint has everything it needs
+  // without the two secondary fetches that stalled in Vite's transform window.
+  const { jsEntries, dynamicIcons } = getPageJitEnrichment({ pageConfig });
+  if (jsEntries) pageConfig._jsEntries = jsEntries;
+  if (dynamicIcons) pageConfig._dynamicIcons = dynamicIcons;
+  return c.json(pageConfig);
+}
+
+export default jitPageHandler;

package/src/routes/mcp.js

@@ -0,0 +1,34 @@
+/*
+  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 { StreamableHTTPTransport } from '@hono/mcp';
+import { createMcpServer } from '@lowdefy/api';
+
+// Stateless per-request MCP server over the app's configured endpoints. The
+// apiContext middleware has already resolved the caller's session, so tool
+// listing and calls are authorized per request.
+async function mcpHandler(c) {
+  const context = c.get('lowdefyContext');
+  const server = await createMcpServer({ context });
+  if (!server) {
+    return c.json({ error: 'MCP is not configured.' }, 404);
+  }
+  const transport = new StreamableHTTPTransport();
+  await server.connect(transport);
+  return transport.handleRequest(c);
+}
+
+export default mcpHandler;

package/{pages/api → src/routes}/ping.js

@@ -14,6 +14,8 @@
   limitations under the License.
 */
 
-export default async function handler(req, res) {
-  res.status(200).json({ timestamp: new Date().toISOString() });
+function pingHandler(c) {
+  return c.json({ timestamp: new Date().toISOString() });
 }
+
+export default pingHandler;

package/src/routes/reload.js

@@ -0,0 +1,79 @@
+/*
+  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 { randomUUID } from 'node:crypto';
+
+import chokidar from 'chokidar';
+import { streamSSE } from 'hono/streaming';
+
+import { registerTab, unregisterTab } from '../../lib/docs/tabChannel.js';
+
+// SSE endpoint — notifies the client when build/reload is written so it can
+// mutate the SWR cache and refetch config. Also doubles as the transport for
+// the agent-state-xray tab channel (lib/docs/tabChannel.js): every
+// connection is a browser tab (client/Reload.jsx opens exactly one per tab),
+// so each is registered as an inspectable dev tab and told its id in a `tab`
+// event, after which an agent can push it inspect-request/eval-request
+// events on the same stream.
+//
+// One stream per tab is deliberate: dev serves over HTTP/1.1, where browsers
+// allow six connections per host, and an open event stream holds one for the
+// life of the tab. The tab's page is not carried on this connection — it
+// would force a reconnect on every navigation — but posted by
+// client/Inspector.jsx to /api/dev-inspect/page (routes/devInspect.js) as
+// { tabId, pageId } whenever it changes.
+async function reloadHandler(c) {
+  return streamSSE(c, async (stream) => {
+    const watcher = chokidar.watch(['./build/reload'], {
+      persistent: true,
+      ignoreInitial: true,
+    });
+
+    const tabId = randomUUID();
+    registerTab({
+      id: tabId,
+      send: (event, data) => stream.writeSSE({ event, data: JSON.stringify(data) }),
+    });
+
+    let open = true;
+    stream.onAbort(() => {
+      open = false;
+      watcher.close();
+      unregisterTab({ id: tabId });
+    });
+
+    await stream.writeSSE({ event: 'tab', data: JSON.stringify({ tabId }) });
+
+    const reload = () => {
+      stream.writeSSE({ event: 'reload', data: JSON.stringify({}) });
+    };
+    watcher.on('add', () => reload());
+    watcher.on('change', () => reload());
+    // Do not reload on unlink — cleanBuildDirectory deletes build/reload during
+    // skeleton rebuilds, which would send a premature SSE event before the new
+    // build artifacts are written. The real reload comes via add/change when
+    // reloadClients() creates the file after the build completes.
+
+    while (open) {
+      await stream.sleep(15000);
+      if (open) {
+        await stream.writeSSE({ event: 'ping', data: '' });
+      }
+    }
+  });
+}
+
+export default reloadHandler;

package/src/routes/request.js

@@ -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 { callRequest, redactErrorResponse } from '@lowdefy/api';
+import { serializer } from '@lowdefy/helpers';
+
+import buildPageIfNeeded from '../../lib/server/jitPageBuilder.js';
+import getPathSegments from '../lib/getPathSegments.js';
+import { getMock } from '../../lib/docs/devMockRegistry.js';
+
+async function requestHandler(c) {
+  if (c.req.method !== 'POST') {
+    throw new Error('Only POST requests are supported.');
+  }
+  const context = c.get('lowdefyContext');
+  const segments = getPathSegments(c, '/api/request/');
+  if (segments.length < 2) {
+    return c.json({ error: 'Invalid request path' }, 400);
+  }
+  const requestId = segments[segments.length - 1];
+  const pageId = segments.slice(0, -1).join('/');
+  const { actionId, blockId, payload } = await c.req.json();
+
+  // Dev-only agent tooling: once a state checkpoint has been loaded
+  // (lib/docs/loadState.js), its recorded request/response pairs live in
+  // devMockRegistry keyed by (pageId, requestId). Short-circuit here, before
+  // ever touching the real connection, so a headless verification page, a
+  // human tester's browser tab, or an e2e test replays exactly what was
+  // recorded. The response shape mirrors @lowdefy/api's callRequest contract
+  // (see callRequestResolver.js / callRequest.js success shape, and
+  // middleware/errorHandler.js for the error shape) so the client's
+  // Requests.js can't tell the difference from a real request.
+  const mock = getMock({ pageId, requestId });
+  if (mock) {
+    context.logger.info({ event: 'dev_mock_request', pageId, requestId, blockId, actionId });
+    if (mock.error) {
+      const error = mock.error instanceof Error ? mock.error : new Error(mock.error);
+      return c.json(redactErrorResponse(context, error), 500);
+    }
+    return c.json({ success: true, response: serializer.serialize(mock.response) });
+  }
+
+  // Page artifacts (including pages/{pageId}/requests/{requestId}.json) are
+  // built JIT by GET /api/page/* and thrown away on every page invalidation
+  // (lowdefyBuildWatcher / moduleBuildWatcher). A client that already holds
+  // the page config keeps firing requests across that window — and a request
+  // that arrived before the page was rebuilt failed with
+  // `Request "x" does not exist.` Run the same idempotent build the page route
+  // runs (a no-op once the page is compiled) so the request artifact is there.
+  await buildPageIfNeeded({
+    pageId,
+    buildDirectory: context.buildDirectory,
+    configDirectory: context.configDirectory,
+  });
+
+  context.logger.info({ event: 'call_request', pageId, requestId, blockId, actionId });
+  const response = await callRequest(context, { blockId, pageId, payload, requestId });
+  return c.json(response);
+}
+
+export default requestHandler;

package/src/routes/request.test.mjs

@@ -0,0 +1,124 @@
+/*
+  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 mockCallRequest = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  callRequest: mockCallRequest,
+  redactErrorResponse: jest.fn((context, error) => ({ error: error.message })),
+}));
+
+const mockBuildPageIfNeeded = jest.fn(async () => true);
+jest.unstable_mockModule('../../lib/server/jitPageBuilder.js', () => ({
+  default: mockBuildPageIfNeeded,
+  getPageJitEnrichment: jest.fn(() => ({})),
+}));
+
+const mockGetMock = jest.fn(() => null);
+jest.unstable_mockModule('../../lib/docs/devMockRegistry.js', () => ({
+  getMock: mockGetMock,
+}));
+
+const { default: requestHandler } = await import('./request.js');
+
+const callOrder = [];
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      buildDirectory: '/build',
+      configDirectory: '/config',
+      logger: { debug: jest.fn(), info: jest.fn(), error: jest.fn() },
+    });
+    await next();
+  });
+  app.all('/api/request/*', requestHandler);
+  return app;
+}
+
+function post(app, path, body = { actionId: 'a', blockId: 'b', payload: {} }) {
+  return app.request(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+beforeEach(() => {
+  callOrder.length = 0;
+  mockBuildPageIfNeeded.mockImplementation(async () => {
+    callOrder.push('build');
+    return true;
+  });
+  mockCallRequest.mockImplementation(async () => {
+    callOrder.push('call');
+    return { success: true, response: { ok: true } };
+  });
+});
+
+afterEach(() => {
+  mockCallRequest.mockReset();
+  mockBuildPageIfNeeded.mockReset();
+  mockGetMock.mockReset();
+  mockGetMock.mockImplementation(() => null);
+});
+
+test('requestHandler builds the page JIT before calling the request', async () => {
+  const res = await post(createApp(), '/api/request/dashboard/get_rows');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ success: true, response: { ok: true } });
+  expect(mockBuildPageIfNeeded).toHaveBeenCalledWith({
+    pageId: 'dashboard',
+    buildDirectory: '/build',
+    configDirectory: '/config',
+  });
+  expect(mockCallRequest).toHaveBeenCalledWith(
+    expect.objectContaining({ buildDirectory: '/build' }),
+    { blockId: 'b', pageId: 'dashboard', payload: {}, requestId: 'get_rows' }
+  );
+  expect(callOrder).toEqual(['build', 'call']);
+});
+
+test('requestHandler builds nested page ids as one page', async () => {
+  await post(createApp(), '/api/request/user-account/login/get_session');
+  expect(mockBuildPageIfNeeded).toHaveBeenCalledWith(
+    expect.objectContaining({ pageId: 'user-account/login' })
+  );
+  expect(mockCallRequest).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({ pageId: 'user-account/login', requestId: 'get_session' })
+  );
+});
+
+test('requestHandler replays a dev mock without building or calling the request', async () => {
+  mockGetMock.mockImplementation(() => ({ response: { rows: [1] } }));
+  const res = await post(createApp(), '/api/request/dashboard/get_rows');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ success: true, response: { rows: [1] } });
+  expect(mockBuildPageIfNeeded).not.toHaveBeenCalled();
+  expect(mockCallRequest).not.toHaveBeenCalled();
+});
+
+test('requestHandler rejects non-POST methods', async () => {
+  const app = createApp();
+  app.onError((err, c) => c.json({ error: err.message }, 500));
+  const res = await app.request('/api/request/dashboard/get_rows');
+  expect(res.status).toEqual(500);
+  expect(mockBuildPageIfNeeded).not.toHaveBeenCalled();
+});

package/{pages/api → src/routes}/root.js

@@ -15,11 +15,11 @@
 */
 
 import { getRootConfig } from '@lowdefy/api';
-import apiWrapper from '../../lib/server/apiWrapper.js';
 
-async function handler({ context, res }) {
+async function rootHandler(c) {
+  const context = c.get('lowdefyContext');
   const rootConfig = await getRootConfig(context);
-  res.status(200).json(rootConfig);
+  return c.json(rootConfig);
 }
 
-export default apiWrapper(handler);
+export default rootHandler;

package/src/routes/usage.js

@@ -0,0 +1,46 @@
+/*
+  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 'node:fs';
+import path from 'node:path';
+
+const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+
+async function usageHandler(c) {
+  if (c.req.method !== 'POST') {
+    throw new Error('Only POST requests are supported.');
+  }
+  const context = c.get('lowdefyContext');
+  const { user, machine } = await c.req.json();
+  const host = c.req.header('host');
+  context.logger.info({ event: 'log_usage', user, machine });
+
+  const timestamp = Date.now();
+
+  return c.json({
+    offline: false,
+    data: {
+      gitSha: context.appMeta.gitSha,
+      host,
+      machine,
+      timestamp,
+      user,
+      version: packageJson.version,
+    },
+  });
+}
+
+export default usageHandler;