@lowdefy/server-dev 0.0.0-experimental-20260707145139 → 0.0.0-experimental-20260710073520

package/client/Inspector.jsx

@@ -0,0 +1,206 @@
+/*
+  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 { useEffect, useRef } from 'react';
+
+import { type, serializer } from '@lowdefy/helpers';
+
+// Dev-only agent-state-xray channel — a sibling of Reload.jsx, but with its
+// own /api/reload SSE connection (rather than reusing Reload's) so that
+// connection can carry ?pageId=<pageId>. routes/reload.js only registers a
+// connection as an inspectable tab (lib/docs/tabChannel.js) when that query
+// param is present, which keeps Reload.jsx's plain reload/ping connection
+// out of the tab registry entirely.
+//
+// pageId tracking: this effect depends on `pageId`, so React tears down and
+// reopens the EventSource (a fresh connection, fresh tab id server-side)
+// whenever the developer navigates to a different page — see the longer
+// design note in src/routes/reload.js.
+//
+// Never let a bad payload or a plugin's operator error crash the app this is
+// piggybacking on — every handler is wrapped, and the component itself
+// always renders null.
+function postResult({ basePath, requestId, result }) {
+  try {
+    fetch(`${basePath}/api/dev-inspect`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requestId, result }),
+    }).catch(() => {
+      // Best-effort — a failed callback just leaves the agent's request to
+      // time out server-side.
+    });
+  } catch {
+    // JSON.stringify or fetch throwing synchronously — still best-effort.
+  }
+}
+
+function buildSnapshot({ lowdefy, pageId }) {
+  const context = lowdefy?.contexts?.[`page:${pageId}`];
+  if (type.isNone(context)) {
+    return { error: `No live context for page "${pageId}".` };
+  }
+  return serializer.serializeToString({
+    pageId,
+    state: context.state,
+    requests: context.requests,
+    eventLog: (context.eventLog ?? []).slice(-50),
+    global: lowdefy.lowdefyGlobal,
+    user: lowdefy.user,
+    input: lowdefy.inputs?.[`page:${pageId}`],
+    urlQuery: window.location.search,
+  });
+}
+
+// Dev-only agent-state-xray: puts a human tester's real browser tab into a
+// checkpoint's recorded state when it loads a page with `?_checkpoint=<name>`
+// in the URL. Fetches the checkpoint's state part from
+// GET <basePath>/api/dev-inspect/checkpoint/<name> (src/routes/devInspect.js
+// — that fetch also loads the checkpoint's recorded requests into
+// devMockRegistry server-side, so this tab's own requests replay recorded
+// data), then injects state the same way e2e-utils' setState does:
+// context._internal.State.set(...) + context._internal.update(). Polls
+// briefly for the page context to exist since this can run before the page
+// has finished mounting. Never lets a bad checkpoint or a missing context
+// break the app — every step is try/catch, and failures just leave the app
+// running unmodified.
+async function bootstrapFromCheckpoint({ basePath, pageId, checkpointName, isCancelled }) {
+  try {
+    const response = await fetch(
+      `${basePath}/api/dev-inspect/checkpoint/${encodeURIComponent(checkpointName)}`
+    );
+    const body = await response.json();
+    if (!response.ok || body?.error) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `Failed to load checkpoint "${checkpointName}": ${body?.error ?? response.statusText}`
+      );
+      return;
+    }
+    const payload = serializer.deserialize(body);
+
+    const deadline = Date.now() + 5000;
+    let context;
+    while (!isCancelled() && Date.now() < deadline) {
+      context = window.lowdefy?.contexts?.[`page:${pageId}`];
+      if (context) {
+        break;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (isCancelled() || type.isNone(context)) {
+      return;
+    }
+
+    Object.entries(payload.state ?? {}).forEach(([key, value]) => {
+      context._internal.State.set(key, value);
+    });
+    context._internal.update();
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(`Failed to load checkpoint "${checkpointName}":`, error);
+  }
+}
+
+function evalExpression({ lowdefy, pageId, expression }) {
+  const context = lowdefy?.contexts?.[`page:${pageId}`];
+  if (type.isNone(context)) {
+    return { error: `No live context for page "${pageId}".` };
+  }
+  // Callers may pass the operator expression as a JSON-serializable object,
+  // or (since it travels as a JSON string end-to-end from an MCP tool
+  // argument) as a JSON string that needs one more parse.
+  const input = type.isString(expression) ? JSON.parse(expression) : expression;
+  const { output, errors } = context._internal.parser.parse({ input, location: 'agent_eval' });
+  return {
+    value: serializer.serializeToString(output),
+    errors: errors.map((error) => error.message),
+  };
+}
+
+const Inspector = ({ basePath, lowdefy, pageId }) => {
+  const pageIdRef = useRef(pageId);
+  pageIdRef.current = pageId;
+
+  useEffect(() => {
+    if (type.isNone(pageId)) {
+      return undefined;
+    }
+
+    const sse = new EventSource(`${basePath}/api/reload?pageId=${encodeURIComponent(pageId)}`);
+
+    sse.addEventListener('inspect-request', (message) => {
+      let requestId;
+      try {
+        const data = JSON.parse(message.data);
+        requestId = data.requestId;
+        const targetPageId = data.pageId ?? pageIdRef.current;
+        const result = buildSnapshot({ lowdefy, pageId: targetPageId });
+        postResult({ basePath, requestId, result });
+      } catch (error) {
+        postResult({ basePath, requestId, result: { error: error.message } });
+      }
+    });
+
+    sse.addEventListener('eval-request', (message) => {
+      let requestId;
+      try {
+        const data = JSON.parse(message.data);
+        requestId = data.requestId;
+        const targetPageId = data.pageId ?? pageIdRef.current;
+        const result = evalExpression({
+          lowdefy,
+          pageId: targetPageId,
+          expression: data.expression,
+        });
+        postResult({ basePath, requestId, result });
+      } catch (error) {
+        postResult({ basePath, requestId, result: { error: error.message } });
+      }
+    });
+
+    return () => {
+      sse.close();
+    };
+  }, [basePath, lowdefy, pageId]);
+
+  useEffect(() => {
+    if (type.isNone(pageId)) {
+      return undefined;
+    }
+    const checkpointName = new URLSearchParams(window.location.search).get('_checkpoint');
+    if (type.isNone(checkpointName)) {
+      return undefined;
+    }
+
+    let cancelled = false;
+    bootstrapFromCheckpoint({
+      basePath,
+      pageId,
+      checkpointName,
+      isCancelled: () => cancelled,
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [basePath, pageId]);
+
+  return null;
+};
+
+export default Inspector;

package/client/Routing.jsx

@@ -20,6 +20,7 @@ import Head from '@lowdefy/client/adapters/Head.js';
 import createLinkComponent from '@lowdefy/client/adapters/Link.js';
 
 import BuildingPage from '../lib/client/BuildingPage.jsx';
+import Inspector from './Inspector.jsx';
 import Reload from './Reload.jsx';
 import Page from './Page.jsx';
 import setPageId from '../lib/client/setPageId.js';
@@ -67,31 +68,34 @@ function Routing({ auth, lowdefy, router }) {
   }
 
   return (
-    <Reload basePath={router.basePath} lowdefy={lowdefy}>
-      {(resetContext) => (
-        <Suspense key={`${pageId}_${getReloadVersion()}`} fallback={<BuildingPage />}>
-          <Page
-            auth={auth}
-            Components={{ Head, Link }}
-            config={{
-              rootConfig,
-            }}
-            jsMap={staticJsMap}
-            lowdefy={lowdefy}
-            pageId={pageId}
-            resetContext={resetContext}
-            router={router}
-            types={{
-              actions,
-              blockMetas,
-              blocks,
-              icons,
-              operators,
-            }}
-          />
-        </Suspense>
-      )}
-    </Reload>
+    <>
+      <Inspector basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+      <Reload basePath={router.basePath} lowdefy={lowdefy}>
+        {(resetContext) => (
+          <Suspense key={`${pageId}_${getReloadVersion()}`} fallback={<BuildingPage />}>
+            <Page
+              auth={auth}
+              Components={{ Head, Link }}
+              config={{
+                rootConfig,
+              }}
+              jsMap={staticJsMap}
+              lowdefy={lowdefy}
+              pageId={pageId}
+              resetContext={resetContext}
+              router={router}
+              types={{
+                actions,
+                blockMetas,
+                blocks,
+                icons,
+                operators,
+              }}
+            />
+          </Suspense>
+        )}
+      </Reload>
+    </>
   );
 }
 

package/lib/docs/checkpointPaths.js

@@ -0,0 +1,91 @@
+/*
+  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';
+
+// Shared path/file-listing helpers for createConfigCheckpoint.js,
+// listConfigCheckpoints.js and revertConfigCheckpoint.js.
+
+const CONFIG_FILE_EXTENSIONS = ['.yaml', '.yml', '.json', '.md', '.js', '.env'];
+const EXCLUDED_DIRECTORY_NAMES = ['.lowdefy', 'node_modules', '.git', 'checkpoints'];
+const MAX_CHECKPOINTS = 20;
+const MANIFEST_FILE_NAME = 'manifest.json';
+
+function getConfigDirectory() {
+  return process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+}
+
+function getCheckpointsRoot() {
+  return path.join(getConfigDirectory(), '.lowdefy', 'checkpoints');
+}
+
+// path.extname('.env') is '' (dotfiles have no extension in Node's eyes), so a
+// dotfile named exactly ".env" needs its own basename check.
+function isConfigFile(filePath) {
+  if (path.basename(filePath) === '.env') {
+    return true;
+  }
+  return CONFIG_FILE_EXTENSIONS.includes(path.extname(filePath));
+}
+
+// Recursively lists config-relevant files under `configDirectory`, returned as
+// paths relative to it. Skips directories that should never be snapshotted —
+// build output (.lowdefy, which also holds the checkpoints themselves),
+// dependencies (node_modules) and version control (.git).
+function listConfigFiles({ configDirectory }) {
+  const results = [];
+
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRECTORY_NAMES.includes(entry.name)) {
+          continue;
+        }
+        walk(fullPath);
+      } else if (entry.isFile() && isConfigFile(fullPath)) {
+        results.push(path.relative(configDirectory, fullPath));
+      }
+    }
+  }
+
+  if (fs.existsSync(configDirectory)) {
+    walk(configDirectory);
+  }
+  return results;
+}
+
+// Slugifies a checkpoint label for use in a directory name — lowercase,
+// non-alphanumeric runs collapsed to a single "-", leading/trailing "-"
+// trimmed. Falls back to "checkpoint" when the label slugifies to nothing
+// (e.g. an empty string or a label made only of punctuation).
+function slug(label) {
+  const slugified = String(label ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slugified === '' ? 'checkpoint' : slugified;
+}
+
+export {
+  getCheckpointsRoot,
+  getConfigDirectory,
+  listConfigFiles,
+  MANIFEST_FILE_NAME,
+  MAX_CHECKPOINTS,
+  slug,
+};

package/lib/docs/checkpointStore.js

@@ -0,0 +1,231 @@
+/*
+  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';
+import { serializer, type } from '@lowdefy/helpers';
+
+import { getConfigDirectory } from './checkpointPaths.js';
+
+// State checkpoints (page state + recorded request/api responses) live in a
+// committable, human-diffable folder per checkpoint — <configDir>/checkpoints/
+// <name>/ — separate from the config-directory-snapshot checkpoints in
+// checkpointPaths.js/createConfigCheckpoint.js (those live under
+// .lowdefy/checkpoints and exist to let an agent revert an experimental
+// config edit). These two "checkpoint" concepts are unrelated: this one is
+// for putting the *running app* into a specific state (agent verification,
+// human testing, e2e test generation), not for reverting config files.
+const NAME_PATTERN = /^[a-z0-9-_]+$/i;
+
+function getStateCheckpointsRoot() {
+  return path.join(getConfigDirectory(), 'checkpoints');
+}
+
+function validateName(name) {
+  if (type.isNone(name) || !type.isString(name)) {
+    throw new Error(`Checkpoint "name" must be a string. Received ${JSON.stringify(name)}.`);
+  }
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Checkpoint name "${name}" is invalid — use only letters, numbers, "-" and "_".`
+    );
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(serializer.serialize(value), null, 2));
+}
+
+function readJsonFile(filePath, defaultValue) {
+  if (!fs.existsSync(filePath)) {
+    return defaultValue;
+  }
+  return serializer.deserialize(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+}
+
+// Requests/api responses arrive as either an array of entries (newest first —
+// the shape of context.requests in both Requests.js and Inspector.jsx's
+// buildSnapshot) or a single entry object. Either way only the newest
+// recording is kept per id.
+function newestEntry(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function writeEntries({ dir, subdir, entries, parts }) {
+  Object.entries(entries ?? {}).forEach(([id, value]) => {
+    const entry = newestEntry(value);
+    if (type.isNone(entry)) {
+      return;
+    }
+    const { payload, response, error, responseTime } = entry;
+    writeJsonFile(path.join(dir, subdir, `${id}.json`), { payload, response, error, responseTime });
+    parts.push(`${subdir}/${id}.json`);
+  });
+}
+
+function readEntries({ dir, subdir }) {
+  const entriesDir = path.join(dir, subdir);
+  const entries = {};
+  if (!fs.existsSync(entriesDir)) {
+    return entries;
+  }
+  fs.readdirSync(entriesDir)
+    .filter((fileName) => fileName.endsWith('.json'))
+    .forEach((fileName) => {
+      const id = fileName.slice(0, -'.json'.length);
+      entries[id] = readJsonFile(path.join(entriesDir, fileName), null);
+    });
+  return entries;
+}
+
+// Snapshots a running page's state + recorded request/api responses into a
+// committable folder. Refuses to clobber an existing checkpoint unless
+// `overwrite: true` — when overwriting, the old folder is removed first so a
+// checkpoint written with fewer requests than a previous one doesn't leave
+// stale per-request files behind.
+function writeCheckpoint({ name, snapshot, notes, overwrite }) {
+  validateName(name);
+  if (type.isNone(snapshot) || !type.isObject(snapshot)) {
+    throw new Error(
+      `writeCheckpoint requires a "snapshot" object. Received ${JSON.stringify(snapshot)}.`
+    );
+  }
+
+  const dir = path.join(getStateCheckpointsRoot(), name);
+  const exists = fs.existsSync(dir);
+  if (exists && overwrite !== true) {
+    throw new Error(`Checkpoint "${name}" already exists. Pass overwrite: true to replace it.`);
+  }
+  if (exists) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(dir, { recursive: true });
+
+  const parts = [];
+  const manifest = {
+    name,
+    pageId: snapshot.pageId ?? null,
+    url: snapshot.url ?? null,
+    capturedAt: new Date().toISOString(),
+    notes: notes ?? null,
+  };
+  writeJsonFile(path.join(dir, 'checkpoint.json'), manifest);
+  parts.push('checkpoint.json');
+
+  writeJsonFile(path.join(dir, 'state.json'), snapshot.state ?? {});
+  parts.push('state.json');
+  writeJsonFile(path.join(dir, 'urlQuery.json'), snapshot.urlQuery ?? '');
+  parts.push('urlQuery.json');
+  writeJsonFile(path.join(dir, 'inputs.json'), snapshot.input ?? {});
+  parts.push('inputs.json');
+  writeJsonFile(path.join(dir, 'user.json'), snapshot.user ?? null);
+  parts.push('user.json');
+  writeJsonFile(path.join(dir, 'global.json'), snapshot.global ?? {});
+  parts.push('global.json');
+
+  writeEntries({ dir, subdir: 'requests', entries: snapshot.requests, parts });
+  if (!type.isNone(snapshot.apiResponses)) {
+    writeEntries({ dir, subdir: 'api', entries: snapshot.apiResponses, parts });
+  }
+
+  return { dir, parts };
+}
+
+// Reads a checkpoint back, tolerant of individually missing parts (a
+// developer may hand-edit or delete files in a committed checkpoint folder) —
+// only a missing checkpoint directory itself is an error.
+function readCheckpoint({ name }) {
+  validateName(name);
+  const dir = path.join(getStateCheckpointsRoot(), name);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Checkpoint "${name}" not found.`);
+  }
+
+  const checkpoint = readJsonFile(path.join(dir, 'checkpoint.json'), {
+    name,
+    pageId: null,
+    url: null,
+    capturedAt: null,
+    notes: null,
+  });
+
+  return {
+    name,
+    checkpoint,
+    state: readJsonFile(path.join(dir, 'state.json'), {}),
+    urlQuery: readJsonFile(path.join(dir, 'urlQuery.json'), ''),
+    input: readJsonFile(path.join(dir, 'inputs.json'), {}),
+    user: readJsonFile(path.join(dir, 'user.json'), null),
+    global: readJsonFile(path.join(dir, 'global.json'), {}),
+    requests: readEntries({ dir, subdir: 'requests' }),
+    api: readEntries({ dir, subdir: 'api' }),
+  };
+}
+
+function checkpointExists({ name }) {
+  validateName(name);
+  return fs.existsSync(path.join(getStateCheckpointsRoot(), name));
+}
+
+// Lists stored state checkpoints, most recent first. Corrupted/hand-edited
+// checkpoints without a manifest still show up (with null fields) rather
+// than being silently hidden, since these folders are meant to be
+// human-editable and committable.
+function listStateCheckpoints() {
+  const root = getStateCheckpointsRoot();
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+
+  const checkpoints = fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(root, entry.name);
+      const manifest = readJsonFile(path.join(dir, 'checkpoint.json'), {
+        name: entry.name,
+        pageId: null,
+        capturedAt: null,
+        notes: null,
+      });
+      const requestsDir = path.join(dir, 'requests');
+      const requestCount = fs.existsSync(requestsDir)
+        ? fs.readdirSync(requestsDir).filter((fileName) => fileName.endsWith('.json')).length
+        : 0;
+      return {
+        name: entry.name,
+        pageId: manifest.pageId ?? null,
+        capturedAt: manifest.capturedAt ?? null,
+        notes: manifest.notes ?? null,
+        requestCount,
+      };
+    });
+
+  return checkpoints.sort((a, b) => {
+    if (type.isNone(a.capturedAt)) return 1;
+    if (type.isNone(b.capturedAt)) return -1;
+    return a.capturedAt < b.capturedAt ? 1 : -1;
+  });
+}
+
+export {
+  checkpointExists,
+  getStateCheckpointsRoot,
+  listStateCheckpoints,
+  readCheckpoint,
+  writeCheckpoint,
+};

package/lib/docs/checkpointToMocks.js

@@ -0,0 +1,65 @@
+/*
+  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 YAML from 'yaml';
+
+import { readCheckpoint } from './checkpointStore.js';
+
+// Errors can't round-trip through YAML as Error instances (and don't need
+// to) — @lowdefy/e2e-utils' createMockManager accepts a plain string and
+// wraps it itself (`error instanceof Error ? error : new Error(error)`), so
+// only the message is kept here.
+function toMockError(error) {
+  if (!error) {
+    return undefined;
+  }
+  return error.message ?? String(error);
+}
+
+function toMockEntries(entries, idKey, extraFields = {}) {
+  return Object.entries(entries ?? {}).map(([id, entry]) => {
+    const error = toMockError(entry?.error);
+    const base = { [idKey]: id, ...extraFields };
+    if (error) {
+      return { ...base, error };
+    }
+    return { ...base, response: entry?.response ?? null };
+  });
+}
+
+// Converts a state checkpoint's recorded requests/api responses into the
+// exact shape @lowdefy/e2e-utils' loadStaticMocks/createMockManager expect
+// (`{ requests: [...], api: [...] }`), so a checkpoint recorded from a live
+// dev session can seed a future AI-generated (or hand-written) e2e test's
+// mocks file directly.
+function checkpointToMocks({ name }) {
+  let checkpoint;
+  try {
+    checkpoint = readCheckpoint({ name });
+  } catch (error) {
+    return { error: error.message };
+  }
+
+  const pageId = checkpoint.checkpoint.pageId;
+  const requests = toMockEntries(checkpoint.requests, 'requestId', { pageId });
+  const api = toMockEntries(checkpoint.api, 'endpointId');
+
+  const yamlContent = YAML.stringify({ requests, api });
+
+  return { requests, api, yaml: yamlContent };
+}
+
+export default checkpointToMocks;