@lowdefy/server-dev 0.0.0-experimental-20260720072521 → 0.0.0-experimental-20260720135014

package/src/routes/docs/screenshot.js

@@ -1,66 +0,0 @@
-/*
-  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 { type } from '@lowdefy/helpers';
-
-import screenshotPage from '../../../lib/docs/screenshotPage.js';
-
-// Parses a query param as a number, or undefined if absent/not a valid
-// number — undefined (not NaN/0) so callers can tell "not provided" apart
-// from an explicit 0.
-function queryNumber(c, key) {
-  const raw = c.req.query(key);
-  if (type.isNone(raw)) {
-    return undefined;
-  }
-  const value = Number(raw);
-  return Number.isFinite(value) ? value : undefined;
-}
-
-async function docsScreenshotHandler(c) {
-  const pageId = c.req.param('pageId');
-  const fullPage = c.req.query('fullPage') === 'true';
-  // Derived from the incoming request rather than a config value — this is
-  // the origin an agent can actually reach the dev server on (host/port it
-  // just connected to), regardless of how the server is bound.
-  const origin = new URL(c.req.url).origin;
-
-  const clipX = queryNumber(c, 'x');
-  const clipY = queryNumber(c, 'y');
-  const clipWidth = queryNumber(c, 'width');
-  const clipHeight = queryNumber(c, 'height');
-  // Only build a clip when all four dimensions are present — a partial
-  // clip is ambiguous, so screenshotPage falls back to a normal viewport
-  // screenshot in that case (same as an invalid clip).
-  const clip =
-    !type.isNone(clipX) &&
-    !type.isNone(clipY) &&
-    !type.isNone(clipWidth) &&
-    !type.isNone(clipHeight)
-      ? { x: clipX, y: clipY, width: clipWidth, height: clipHeight }
-      : undefined;
-  const scrollX = queryNumber(c, 'scrollX') ?? 0;
-  const scrollY = queryNumber(c, 'scrollY') ?? 0;
-
-  const result = await screenshotPage({ origin, pageId, fullPage, clip, scrollX, scrollY });
-  if (result.error) {
-    return c.json({ error: result.error }, 502);
-  }
-  const buffer = Buffer.from(result.data, 'base64');
-  return c.body(buffer, 200, { 'Content-Type': result.mimeType });
-}
-
-export default docsScreenshotHandler;

package/src/routes/docs/search.js

@@ -1,27 +0,0 @@
-/*
-  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 searchDocs from '../../../lib/docs/searchDocs.js';
-
-function docsSearchHandler(c) {
-  const query = c.req.query('q');
-  if (!query || query.trim() === '') {
-    return c.json({ error: 'Missing search query. Use GET /lowdefy-docs/search?q=your+keywords.' }, 400);
-  }
-  return c.json(searchDocs({ query }));
-}
-
-export default docsSearchHandler;

package/src/routes/docs/snapshotState.js

@@ -1,36 +0,0 @@
-/*
-  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 snapshotState from '../../../lib/docs/snapshotState.js';
-
-// Lets an agent (or a developer) snapshot the running app's page state and
-// recorded request/api responses into a checkpoint folder under .lowdefy,
-// for later replay via POST /lowdefy-docs/state/load.
-async function docsSnapshotStateHandler(c) {
-  const { pageId, name, notes, source, overwrite } = await c.req.json();
-  // Derived from the incoming request rather than a config value — this is
-  // the origin an agent can actually reach the dev server on (host/port it
-  // just connected to), regardless of how the server is bound.
-  const origin = new URL(c.req.url).origin;
-
-  const result = await snapshotState({ origin, pageId, name, notes, source, overwrite });
-  if (result.error) {
-    return c.json({ error: result.error }, 502);
-  }
-  return c.json(result);
-}
-
-export default docsSnapshotStateHandler;

package/src/routes/docs/stateCheckpointsList.js

@@ -1,26 +0,0 @@
-/*
-  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 { listStateCheckpoints } from '../../../lib/docs/checkpointStore.js';
-
-// Lists state checkpoints (page state + recorded request/api
-// responses) — distinct from GET /lowdefy-docs/checkpoints, which lists
-// config-directory-snapshot checkpoints (see checkpointStore.js).
-function docsStateCheckpointsListHandler(c) {
-  return c.json(listStateCheckpoints());
-}
-
-export default docsStateCheckpointsListHandler;

package/src/routes/docs/types.js

@@ -1,33 +0,0 @@
-/*
-  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 listTypes from '../../../lib/docs/listTypes.js';
-import normalizeTypeKind from '../../../lib/docs/normalizeTypeKind.js';
-
-function docsTypesHandler(c) {
-  const kind = c.req.param('kind');
-  if (normalizeTypeKind({ kind }) === null) {
-    return c.json(
-      {
-        error: `Unknown docs kind "${kind}". Use one of: blocks, operators, actions, connections, requests, agents, notifications, websockets. See GET /lowdefy-docs for all routes.`,
-      },
-      404
-    );
-  }
-  return c.json(listTypes({ kind }));
-}
-
-export default docsTypesHandler;

package/src/routes/endpoints.js

@@ -1,76 +0,0 @@
-/*
-  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 { callEndpoint, getEndpointConfig, runWebhookEndpoint } from '@lowdefy/api';
-
-import getPathSegments from '../lib/getPathSegments.js';
-
-async function endpointsHandler(c) {
-  if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
-  }
-  const context = c.get('lowdefyContext');
-  const endpointId = getPathSegments(c, '/api/endpoints/').join('/');
-
-  // Endpoints opting in with `webhook` (true or a { verify } object) are
-  // third-party webhook receivers (SNS, Event Grid, Stripe, ...): they take the
-  // request RAW — body in the caller's own format (not the { payload }
-  // envelope), plus query + headers — and their return value is sent back
-  // verbatim, because webhook handshakes (e.g. Event Grid's validationResponse)
-  // require exact response shapes. The config lookup is a cached file read; an
-  // unknown endpoint falls through to the standard path so its error shape is
-  // unchanged. Everything about non-webhook endpoints is untouched.
-  let endpointConfig = null;
-  try {
-    endpointConfig = await getEndpointConfig(context, { endpointId });
-  } catch {
-    /* unknown endpoint — the standard path below reports it exactly as before */
-  }
-  if (endpointConfig?.webhook) {
-    // SNS posts JSON as text/plain — parse regardless of content-type; an
-    // unparseable body arrives as the raw string.
-    const raw = await c.req.text();
-    let body = raw;
-    try {
-      body = JSON.parse(raw);
-    } catch {
-      /* non-JSON body — raw string passthrough */
-    }
-    context.logger.info({ event: 'call_webhook_endpoint', endpointId });
-    const result = await runWebhookEndpoint(context, {
-      endpointId,
-      body,
-      query: c.req.query(),
-      headers: c.req.header(),
-    });
-    // A failed verify gate is a rejected caller (401), distinct from a routine
-    // error (500).
-    if (result.status === 'unauthorized') {
-      return c.json({ error: 'Webhook verification failed.' }, 401);
-    }
-    if (!result.success) {
-      return c.json({ error: 'Webhook failed.' }, 500);
-    }
-    return c.json(result.response ?? { ok: true });
-  }
-
-  const { blockId, payload, pageId } = await c.req.json();
-  context.logger.info({ event: 'call_api_endpoint', blockId, endpointId, pageId });
-  const response = await callEndpoint(context, { blockId, endpointId, pageId, payload });
-  return c.json(response);
-}
-
-export default endpointsHandler;

package/src/routes/feedback.js

@@ -1,110 +0,0 @@
-/*
-  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 enrichFeedback from '../../lib/docs/enrichFeedback.js';
-import formatFeedback from '../../lib/docs/formatFeedback.js';
-import createLogger from '../../lib/server/log/createLogger.js';
-
-const logger = createLogger({ server: 'lowdefy-dev-feedback' });
-
-// Receives annotation batches from the dev browser overlay (a developer
-// draws on a live page and comments), enriches each annotation with its
-// yaml file:line via findConfig, and returns the formatted agent-readable
-// text. The overlay copies that text to the clipboard — the developer
-// pastes it into whichever agent session they choose, which is also what
-// makes delivery unambiguous when several sessions share one dev server.
-// Same-origin check cloned from routes/clientError.js: only a page served
-// by this dev server (not an arbitrary site) should be able to use it.
-async function feedbackHandler(c) {
-  const origin = c.req.header('origin');
-  if (!origin) {
-    return c.json({ error: 'Forbidden' }, 403);
-  }
-  try {
-    if (new URL(origin).host !== c.req.header('host')) {
-      return c.json({ error: 'Forbidden' }, 403);
-    }
-  } catch {
-    return c.json({ error: 'Forbidden' }, 403);
-  }
-
-  const batch = await c.req.json();
-  if (!Array.isArray(batch?.annotations)) {
-    return c.json(
-      {
-        error:
-          'Feedback batch requires an "annotations" array. See GET /lowdefy-docs for the ' +
-          'feedback batch shape.',
-      },
-      400
-    );
-  }
-
-  // The tab screenshot rides in as a multi-MB data URL — lift it off the
-  // batch before enrichment so it never reaches the formatted text or the
-  // headless capture path.
-  const tabScreenshot = batch.screenshot;
-  delete batch.screenshot;
-  let enriched = await enrichFeedback({ batch });
-  delete enriched.screenshot;
-
-  // Default on — the overlay sends includeScreenshot: false when the
-  // developer unticks it.
-  if (batch.includeScreenshot !== false) {
-    const fileName = `${batch.pageId}-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
-    if (typeof tabScreenshot === 'string') {
-      // Preferred path: the overlay captured the developer's actual tab —
-      // theme, loaded data, exact pixels — with annotations already drawn.
-      const { default: saveAnnotatedScreenshot } = await import(
-        '../../lib/docs/saveAnnotatedScreenshot.js'
-      );
-      const result = saveAnnotatedScreenshot({ dataUrl: tabScreenshot, fileName });
-      if (result.path) {
-        enriched = { ...enriched, screenshotPath: result.path };
-      } else {
-        logger.warn(result.error);
-      }
-    } else {
-      // Fallback: re-render the page headless (batches from agents or older
-      // clients, or when the in-tab capture failed). The response must NOT
-      // wait for this capture: the overlay writes the clipboard when this
-      // returns, and Chrome's transient user-activation (required for
-      // clipboard writes) expires within ~5s — a headless browser launch can
-      // take longer. So the path is pre-assigned, the formatted text returns
-      // immediately, and the PNG lands on disk a moment later — well before
-      // a human pastes it anywhere.
-      // Deferred import: the capture module pulls in the browser singleton,
-      // which reads build artifacts at import time — only load it when a
-      // screenshot is actually wanted.
-      const { default: captureAnnotatedScreenshot } = await import(
-        '../../lib/docs/captureAnnotatedScreenshot.js'
-      );
-      const serverOrigin = new URL(c.req.url).origin;
-      enriched = { ...enriched, screenshotPath: `.lowdefy/annotations/${fileName}` };
-      captureAnnotatedScreenshot({ origin: serverOrigin, batch: enriched, fileName }).then(
-        (result) => {
-          if (result.error) {
-            logger.warn(result.error);
-          }
-        }
-      );
-    }
-  }
-
-  return c.json({ ok: true, formatted: formatFeedback({ items: [enriched] }) });
-}
-
-export default feedbackHandler;

package/src/routes/feedback.test.mjs

@@ -1,204 +0,0 @@
-/*
-  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/iconsDynamic.js

@@ -1,25 +0,0 @@
-/*
-  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 serveBuildJs from '../lib/serveBuildJs.js';
-
-function iconsDynamicHandler(c) {
-  return c.body(serveBuildJs(['plugins', 'iconsDynamic.js']), 200, {
-    'Content-Type': 'application/javascript',
-  });
-}
-
-export default iconsDynamicHandler;