@charlescms/astro 0.1.0

package/src/index.js

@@ -0,0 +1,681 @@
+import { fileURLToPath } from "node:url";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { createRequire } from "node:module";
+import { searchForWorkspaceRoot } from "vite";
+
+// Astro's View Transitions (ClientRouter) pull in these runtime modules. Vite
+// only discovers them on the FIRST navigation, which forces a mid-session
+// dependency re-optimize + full reload ("504 Outdated Optimize Dep") — that
+// reload tears the editor out from under the user. Pre-bundling them at startup
+// (when they exist) keeps navigation seamless. Resolved against the project so
+// older Astro versions without them are simply skipped.
+function viewTransitionDeps() {
+  const ids = [
+    "astro/virtual-modules/transitions-router.js",
+    "astro/virtual-modules/transitions-types.js",
+    "astro/virtual-modules/transitions-events.js",
+    "astro/virtual-modules/transitions-swap-functions.js"
+  ];
+  let resolve;
+  try {
+    resolve = createRequire(join(process.cwd(), "noop.js")).resolve;
+  } catch {
+    return [];
+  }
+  return ids.filter((id) => {
+    try { resolve(id); return true; } catch { return false; }
+  });
+}
+import { transformAstroSource, extractNavCollections, extractDataCollections } from "./analyzer.js";
+import { collectFrontmatterFields } from "./frontmatter.js";
+import { transformMarkdownSource } from "./markdown-analyzer.js";
+import { normalizeBlockHtml, sanitizeBlockHtml } from "./sanitize.js";
+
+/**
+ * CharlesCMS Astro integration — adds a source-native visual editor to an Astro
+ * site. Drop it into `astro.config.mjs` (`integrations: [charlesCMS()]`); the
+ * editor lives at `adminPath` and writes changes back to the project's source.
+ *
+ * @param {object} [options]
+ * @param {string} [options.adminPath="/cms"] Route the editor is served from.
+ * @param {string[]} [options.editablePaths] Page paths where the editor activates.
+ *   Defaults to all pages. Accepts a single string or an array.
+ * @param {string} [options.defaultEditPath] Page the editor opens first.
+ *   Defaults to the first `editablePaths` entry, else `/`.
+ * @param {boolean} [options.previewOnly=false] Run the editor read-only with no
+ *   publishing (e.g. a public demo).
+ * @param {string} [options.connector] Preset Cloudflare connector worker URL,
+ *   so editors never type connection details into a form.
+ * @param {string} [options.repo] Preset `owner/name` GitHub repository.
+ * @param {string} [options.branch] Preset branch to commit to.
+ * @param {string} [options.sourceRoot] Preset repo-relative path to the Astro
+ *   project root (for monorepos where the app is in a subfolder).
+ * @returns {import("astro").AstroIntegration} The Astro integration object.
+ */
+export default function charlesCMS(options = {}) {
+  const adminPath = normalizePath(options.adminPath || "/cms");
+  const editablePaths = normalizeEditablePaths(options.editablePaths);
+  const defaultEditPath = normalizePath(options.defaultEditPath || editablePaths[0] || "/");
+  const previewOnly = Boolean(options.previewOnly);
+  // Optional connection baked in by the site owner so editors never have to type
+  // connector/repo/branch (or the jargon-y source root) into a form. When set,
+  // /cms shows a clean "Start editing" screen instead of the developer form.
+  const connection = normalizeConnection(options);
+  const packageRoot = new URL(".", import.meta.url);
+  let projectRoot = process.cwd();
+  let sourceMapPath = "";
+  const sourceMap = {};
+  const sectionTemplates = {};
+  const virtualSourceMapId = "virtual:charlescms-source-map";
+  const resolvedVirtualSourceMapId = "\0charlescms-source-map";
+  const virtualConfigId = "virtual:charlescms-config";
+  const resolvedVirtualConfigId = "\0charlescms-config";
+  const virtualRuntimeId = "virtual:charlescms-runtime";
+  const resolvedVirtualRuntimeId = "\0charlescms-runtime";
+  const virtualSectionTemplatesId = "virtual:charlescms-section-templates";
+  const resolvedVirtualSectionTemplatesId = "\0charlescms-section-templates";
+  // After the editor mirrors a published file to disk it owns the single reload
+  // (it shows the success, then reloads once the refreshed map is ready). For a
+  // brief window after that write, suppress Vite's own HMR for the file so it
+  // doesn't fire an earlier reload that would re-read a not-yet-refreshed map.
+  let mirrorReloadGuardUntil = 0;
+  let logger = console;
+
+  return {
+    name: "@charlescms/astro",
+    hooks: {
+      "astro:config:done": async ({ config }) => {
+        projectRoot = fileURLToPath(config.root);
+        process.env.CHARLESCMS_PROJECT_ROOT = projectRoot;
+        sourceMapPath = `${projectRoot}.charlescms/source-map.json`;
+        await refreshSourceMap(projectRoot, sourceMapPath, sourceMap);
+        await refreshSectionTemplates(projectRoot, sectionTemplates, logger);
+      },
+      "astro:config:setup": ({ injectRoute, injectScript, updateConfig, logger: astroLogger }) => {
+        logger = astroLogger || logger;
+        injectScript("page", renderPageScript({
+          adminPath,
+          editablePaths,
+          defaultEditPath,
+          previewOnly,
+          connection
+        }));
+        updateConfig({
+          vite: {
+            // Allow Vite's dev server to serve this package's runtime files
+            // (boot.js, client.js) over /@fs — needed when the package resolves
+            // through a symlink outside the project root (a file: link, a
+            // monorepo workspace, or pnpm's store). Crucially, KEEP the project's
+            // own workspace root allowed too: setting `fs.allow` replaces Vite's
+            // default, and dropping the workspace root 403s the site's own CSS,
+            // fonts and assets in dev.
+            server: { fs: { allow: [searchForWorkspaceRoot(process.cwd()), fileURLToPath(new URL("..", import.meta.url))] } },
+            // Don't let Vite pre-bundle the editor package. Its browser files
+            // import a virtual module (virtual:charlescms-source-map) that the
+            // optimizer's esbuild pass can't resolve, so optimizing it forces a
+            // "504 Outdated Optimize Dep" + full reload every time the runtime is
+            // dynamically imported — a page-reload (blink) loop in dev.
+            optimizeDeps: {
+              exclude: ["@charlescms/astro"],
+              // micromark imports debug's CommonJS browser build. Because this
+              // package is excluded above, Vite needs the transitive dependency
+              // named explicitly so Git installs get a valid default export.
+              include: [
+                "debug",
+                "js-yaml",
+                "mdast-util-from-markdown",
+                "mdast-util-gfm",
+                "mdast-util-to-markdown",
+                "mdast-util-to-string",
+                "micromark-extension-gfm",
+                "parse5",
+                // Pre-bundle the Tiptap rich-text editor (lazy-loaded on the first
+                // rich edit) so its first import never triggers a mid-session
+                // re-optimize + reload that would close the editor.
+                "@tiptap/core",
+                "@tiptap/extension-document",
+                "@tiptap/extension-text",
+                "@tiptap/extension-bold",
+                "@tiptap/extension-italic",
+                "@tiptap/extension-code",
+                "@tiptap/extension-hard-break",
+                "@tiptap/extension-link",
+                // Pre-bundle Astro's View Transitions runtime so navigation never
+                // triggers a mid-session re-optimize that reloads away the editor.
+                ...viewTransitionDeps()
+              ]
+            },
+            plugins: [
+              {
+                name: "charlescms-virtual-source-map",
+                enforce: "pre",
+                resolveId(id) {
+                  if (id === virtualSourceMapId) return resolvedVirtualSourceMapId;
+                  if (id === virtualConfigId) return resolvedVirtualConfigId;
+                  if (id === virtualRuntimeId) return resolvedVirtualRuntimeId;
+                  if (id === virtualSectionTemplatesId) return resolvedVirtualSectionTemplatesId;
+                  return null;
+                },
+                async load(id) {
+                  if (id === resolvedVirtualSourceMapId) {
+                    return `export default ${JSON.stringify(await buildSerializableSourceMap(projectRoot, sourceMap))};`;
+                  }
+                  if (id === resolvedVirtualConfigId) {
+                    return `export default ${JSON.stringify({ adminPath, editablePaths, defaultEditPath, previewOnly, connection })};`;
+                  }
+                  if (id === resolvedVirtualRuntimeId) {
+                    return `import { bootCharlesCMS } from "@charlescms/astro/src/boot.js"; bootCharlesCMS();`;
+                  }
+                  if (id === resolvedVirtualSectionTemplatesId) {
+                    return `export default ${JSON.stringify(sectionTemplates)};`;
+                  }
+                  // Inject editable ids into .astro at LOAD time — before Astro
+                  // compiles it. A transform hook is too late for full-document
+                  // pages (`<!doctype html>…`): Astro compiles those to JS first,
+                  // so a transform only ever sees generated JS with no markup to
+                  // annotate. Loading the raw source ourselves guarantees the
+                  // ids reach Astro's compiler for every .astro, page or fragment.
+                  if (id.endsWith(".astro") && !id.includes("?")
+                    && !id.includes("/node_modules/")
+                    && !id.startsWith(fileURLToPath(packageRoot))) {
+                    try {
+                      const source = await readFile(id, "utf8");
+                      if (source.includes("__CHARLESCMS_PATH__")) return null;
+                      return (await transformAstroSource(source, id)).code;
+                    } catch {
+                      return null;
+                    }
+                  }
+                  return null;
+                },
+                // Right after the editor mirrors a published file to disk, swallow
+                // Vite's own HMR for that file: the editor reloads once on its own
+                // after the source map has refreshed, and Vite's earlier reload
+                // would otherwise re-read a stale map (the second edit to the same
+                // file would then fail byte-verification). A normal IDE edit, made
+                // outside this short window, still hot-updates as usual.
+                handleHotUpdate(ctx) {
+                  if (Date.now() < mirrorReloadGuardUntil && isProjectSourceFile(ctx.file, projectRoot)) {
+                    return [];
+                  }
+                },
+                configureServer(server) {
+                  const bootPath = new URL("boot.js", packageRoot).pathname;
+                  server.middlewares.use("/_charlescms/runtime.js", (_request, response) => {
+                    response.setHeader("content-type", "text/javascript");
+                    response.end(`import { bootCharlesCMS } from ${JSON.stringify(`/@fs${bootPath}`)}; bootCharlesCMS();`);
+                  });
+
+                  // Uploads publish to GitHub through the connector, but the dev
+                  // server serves public/ from the LOCAL disk — so a freshly
+                  // uploaded image would 404 locally until the next git pull.
+                  // This dev-only endpoint mirrors the uploaded bytes into the
+                  // local public/uploads folder, so the preview shows the image
+                  // immediately. Strictly limited to that one folder.
+                  //
+                  // Astro's dev server only serves public/ files that existed at
+                  // startup, so mirrored files also need serving: read /uploads/*
+                  // straight from disk here, falling through when absent.
+                  server.middlewares.use("/uploads", async (request, response, next) => {
+                    const name = decodeURIComponent(String(request.url || "").split("?")[0].replace(/^\/+/, ""));
+                    if (!/^[A-Za-z0-9._-]+$/.test(name)) return next();
+                    try {
+                      const bytes = await readFile(join(projectRoot, "public/uploads", name));
+                      const types = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml", avif: "image/avif", pdf: "application/pdf" };
+                      response.setHeader("content-type", types[name.split(".").pop().toLowerCase()] || "application/octet-stream");
+                      response.end(bytes);
+                    } catch {
+                      next();
+                    }
+                  });
+
+                  server.middlewares.use("/_charlescms/mirror-upload", (request, response) => {
+                    if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+                    let body = "";
+                    request.on("data", (chunk) => { body += chunk; });
+                    request.on("end", async () => {
+                      try {
+                        const { path, base64 } = JSON.parse(body || "{}");
+                        const safe = /^public\/uploads\/[A-Za-z0-9._-]+$/.test(String(path || ""));
+                        if (!safe) { response.statusCode = 400; response.end("invalid path"); return; }
+                        const target = join(projectRoot, path);
+                        await mkdir(dirname(target), { recursive: true });
+                        await writeFile(target, Buffer.from(String(base64 || ""), "base64"));
+                        response.statusCode = 204;
+                        response.end();
+                      } catch (error) {
+                        response.statusCode = 500;
+                        response.end(String(error?.message || error));
+                      }
+                    });
+                  });
+
+                  // Source edits publish to GitHub through the connector, but the
+                  // dev server reads source from the LOCAL disk. Without mirroring,
+                  // the local files (and the source map built from them) stay frozen
+                  // at the last build while GitHub moves ahead with each publish — so
+                  // the NEXT edit to the same file fails byte-verification ("source
+                  // changed since the CMS build"): the CMS never notices it already
+                  // published. Writing the published bytes back to disk keeps the dev
+                  // source map in lockstep; the watcher below then refreshes it.
+                  // Restricted to source files inside the project root. The write
+                  // opens a short guard window: the editor owns the single reload
+                  // after publishing, so the watcher and Vite's HMR both skip their
+                  // own reload during it; a hand edit in the IDE still reloads.
+                  server.middlewares.use("/_charlescms/mirror-source", (request, response) => {
+                    if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+                    let body = "";
+                    request.on("data", (chunk) => { body += chunk; });
+                    request.on("end", async () => {
+                      try {
+                        const { path, source } = JSON.parse(body || "{}");
+                        const target = safeProjectSourcePath(projectRoot, path);
+                        if (!target) { response.statusCode = 400; response.end("invalid path"); return; }
+                        mirrorReloadGuardUntil = Date.now() + 2000;
+                        await mkdir(dirname(target), { recursive: true });
+                        await writeFile(target, String(source ?? ""));
+                        response.statusCode = 204;
+                        response.end();
+                      } catch (error) {
+                        response.statusCode = 500;
+                        response.end(String(error?.message || error));
+                      }
+                    });
+                  });
+
+                  let refreshTimer;
+                  let refreshQueue = Promise.resolve();
+                  const scheduleRefresh = (file) => {
+                    if (isSectionTemplateFile(file, projectRoot)) {
+                      clearTimeout(refreshTimer);
+                      refreshTimer = setTimeout(() => {
+                        refreshQueue = refreshQueue
+                          .then(async () => {
+                            await refreshSectionTemplates(projectRoot, sectionTemplates, logger);
+                            const virtualModule = server.moduleGraph.getModuleById(resolvedVirtualSectionTemplatesId);
+                            if (virtualModule) server.moduleGraph.invalidateModule(virtualModule);
+                            server.ws.send({ type: "full-reload" });
+                          })
+                          .catch((error) => {
+                            server.config.logger.error(`[CharlesCMS] Could not refresh section templates: ${error.message}`);
+                          });
+                      }, 80);
+                      return;
+                    }
+                    if (!isProjectSourceFile(file, projectRoot)) return;
+                    // A publish the editor just mirrored to disk: refresh the map so
+                    // the next build/edit is byte-consistent, but let the editor do
+                    // the single reload (it shows the success first).
+                    const editorMirrored = Date.now() < mirrorReloadGuardUntil;
+                    clearTimeout(refreshTimer);
+                    refreshTimer = setTimeout(() => {
+                      refreshQueue = refreshQueue
+                        .then(async () => {
+                          await refreshSourceMap(projectRoot, sourceMapPath, sourceMap);
+                          const virtualModule = server.moduleGraph.getModuleById(resolvedVirtualSourceMapId);
+                          if (virtualModule) server.moduleGraph.invalidateModule(virtualModule);
+                          if (!editorMirrored) server.ws.send({ type: "full-reload" });
+                        })
+                        .catch((error) => {
+                          server.config.logger.error(`[CharlesCMS] Could not refresh the source map: ${error.message}`);
+                        });
+                    }, 80);
+                  };
+                  server.watcher.on("add", scheduleRefresh);
+                  server.watcher.on("change", scheduleRefresh);
+                  server.watcher.on("unlink", scheduleRefresh);
+                },
+                // .astro id injection now happens in load() above, before Astro
+                // compiles the source — see the note there.
+              }
+            ]
+          }
+        });
+        injectRoute({
+          pattern: adminPath,
+          entrypoint: new URL("admin.astro", packageRoot).pathname
+        });
+      }
+    }
+  };
+}
+
+/**
+ * Load the project's static section templates from `src/charlescms/templates`
+ * into `target` (mutated in place), skipping any non-static `.astro` file.
+ * @param {string} root Project root directory.
+ * @param {Object} target Template map to clear and repopulate.
+ * @param {Console} [logger=console] Logger for skipped-template warnings.
+ * @returns {Promise<void>}
+ */
+export async function refreshSectionTemplates(root, target, logger = console) {
+  const directory = join(root, "src/charlescms/templates");
+  const next = {};
+  let files = [];
+  try {
+    files = (await readdir(directory, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && /\.(?:html|astro)$/i.test(entry.name))
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    files = [];
+  }
+  for (const name of files) {
+    const source = (await readFile(join(directory, name), "utf8")).trim();
+    // A template must be PURE static markup: it is inserted verbatim as page
+    // content. An .astro file is welcome as long as it carries no frontmatter,
+    // no {expressions} and no components — those cannot become a static section.
+    if (/\.astro$/i.test(name) && (/^---/.test(source) || /[{}]/.test(source) || /<[A-Z]/.test(source))) {
+      logger.warn?.(`[CharlesCMS] Skipped dynamic section template (frontmatter/expressions/components are not supported): src/charlescms/templates/${name}`);
+      continue;
+    }
+    // Compare against the parser-normalized source, not the raw text: harmless
+    // formatting (`<img />`, attribute quoting) must not flag a template as
+    // unsafe — only content the sanitizer actually removes or rewrites does.
+    const html = sanitizeBlockHtml(source).trim();
+    if (!html || html !== normalizeBlockHtml(source).trim()) {
+      logger.warn?.(`[CharlesCMS] Skipped unsafe section template: src/charlescms/templates/${name}`);
+      continue;
+    }
+    const id = name.replace(/\.(?:html|astro)$/i, "");
+    next[id] = {
+      id,
+      label: id.split(/[-_]+/).filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join(" "),
+      html
+    };
+  }
+  for (const key of Object.keys(target)) delete target[key];
+  Object.assign(target, next);
+  return target;
+}
+
+function renderPageScript(config) {
+  return `window.__CHARLESCMS_PATH__=${JSON.stringify(config.adminPath)};
+window.__CHARLESCMS_EDIT_PATHS__=${JSON.stringify(config.editablePaths)};
+window.__CHARLESCMS_DEFAULT_EDIT_PATH__=${JSON.stringify(config.defaultEditPath)};
+window.__CHARLESCMS_PREVIEW_ONLY__=${JSON.stringify(config.previewOnly)};
+window.__CHARLESCMS_CONNECTION__=${JSON.stringify(config.connection || {})};
+import("virtual:charlescms-runtime");`;
+}
+
+// Pull an optional preset connection out of the integration options. Only
+// non-empty fields are kept so partial config still prefills the form.
+function normalizeConnection(options) {
+  const out = {};
+  const connector = String(options.connector || "").trim().replace(/\/+$/, "");
+  const repo = String(options.repo || "").trim().replace(/^\/+|\/+$/g, "");
+  const branch = String(options.branch || "").trim();
+  const sourceRoot = String(options.sourceRoot || "").trim().replace(/^\/+|\/+$/g, "");
+  if (connector) out.connector = connector;
+  if (repo) out.repo = repo;
+  if (branch) out.branch = branch;
+  if (sourceRoot) out.sourceRoot = sourceRoot;
+  return out;
+}
+
+/**
+ * Scan a project's `src` (and conventional root `data/`) for all editable
+ * regions, building the full source map of entry id → descriptor.
+ * @param {string} root Project root directory.
+ * @returns {Promise<Object>} The combined source-map entries for the project.
+ */
+export async function scanProjectSource(root) {
+  const sourceRoot = join(root, "src");
+  const files = await listSourceFiles(sourceRoot);
+  const dataRoots = projectDataRoots(root);
+  const entries = {};
+  // Data modules imported by a SHARED file (layout/component) — their content is
+  // rendered on every page, so it is site-wide regardless of the page's markup.
+  const sharedModules = new Set();
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    if (file.endsWith(".astro")) {
+      Object.assign(entries, (await transformAstroSource(source, file)).entries);
+      // Menus defined inline in a component's frontmatter.
+      Object.assign(entries, extractNavCollections(source, file));
+      Object.assign(entries, extractDataCollections(source, file));
+    } else {
+      Object.assign(entries, collectFrontmatterFields(source, file).entries);
+      Object.assign(entries, transformMarkdownSource(source, file).entries);
+    }
+    if (isSharedSourcePath(file)) {
+      for (const match of source.matchAll(/from\s*["']([^"'\n]+)["']/g)) {
+        const base = match[1].split("/").pop().replace(/\.(?:ts|js|mjs|cjs|json)$/i, "");
+        if (base) sharedModules.add(base);
+      }
+    }
+  }
+  // Menus imported from a data/config module live in plain JS/TS under src
+  // (src/data, src/consts.ts, src/config.ts, ...), and many Astro themes also
+  // keep site data in a conventional root-level data/ directory.
+  for (const file of await listProjectDataFiles(dataRoots)) {
+    const source = await readFile(file, "utf8");
+    Object.assign(entries, extractNavCollections(source, file));
+    Object.assign(entries, extractDataCollections(source, file));
+  }
+  // Markup-INDEPENDENT scope from Astro's file convention: content from
+  // src/components or src/layouts (or a data module they import) is shared across
+  // the site; content from src/pages belongs to that page. The Content panel uses
+  // this instead of guessing from <header>/<main>, which a dev may not use.
+  for (const entry of Object.values(entries)) {
+    const path = String(entry.file || "").replace(/\\/g, "/");
+    const base = (path.split("/").pop() || "").replace(/\.(?:ts|js|mjs|cjs|json|astro|md|mdx)$/i, "");
+    if (isSharedSourcePath(path) || sharedModules.has(base)) entry.scope = "shared";
+    else if (/\/src\/pages\//.test(path)) entry.scope = "page";
+  }
+  return entries;
+}
+
+function isSharedSourcePath(file) {
+  return /\/src\/(?:components|layouts)\//.test(String(file).replace(/\\/g, "/"));
+}
+
+function projectDataRoots(root) {
+  const sourceRoot = join(root, "src");
+  const rootData = join(root, "data");
+  return [sourceRoot, rootData];
+}
+
+async function listProjectDataFiles(roots) {
+  const seen = new Set();
+  const files = [];
+  for (const root of roots) {
+    for (const file of await listDataFiles(root)) {
+      const key = resolve(file);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      files.push(file);
+    }
+  }
+  return files;
+}
+
+/**
+ * Rebuild the source map for `root` and write it both into `target` (mutated in
+ * place) and to `path` on disk for the running editor to read.
+ * @param {string} root Project root directory.
+ * @param {string} path File path to write the serialized source map to.
+ * @param {Object} target Source-map object to clear and repopulate.
+ * @returns {Promise<void>}
+ */
+export async function refreshSourceMap(root, path, target) {
+  const next = await scanProjectSource(root);
+  for (const key of Object.keys(target)) delete target[key];
+  Object.assign(target, next);
+  await writeSourceMap(path, root, target);
+  return target;
+}
+
+function isProjectSourceFile(file, root) {
+  const path = String(file || "").replace(/\\/g, "/");
+  const sourceRoot = join(root, "src").replace(/\\/g, "/").replace(/\/+$/, "");
+  const rootData = join(root, "data").replace(/\\/g, "/").replace(/\/+$/, "");
+  const inSource = path.startsWith(`${sourceRoot}/`);
+  const inRootData = path.startsWith(`${rootData}/`);
+  if (!inSource && !inRootData) return false;
+  if (/\.(?:astro|md|mdx)$/.test(path)) return true;
+  // Any JS/TS module under src or conventional root-level data/ may define
+  // navigation/link-list data.
+  return /\.(?:ts|js|mjs|cjs)$/.test(path) && !/\.d\.ts$/.test(path);
+}
+
+// Resolve a connector-supplied, project-relative source path to an absolute file
+// for the dev mirror — but only if it stays inside the project root and names a
+// source file the analyzer actually edits. Anything traversing out, absolute, or
+// of another type is rejected, so the dev endpoint can't write arbitrary files.
+function safeProjectSourcePath(root, relativePath) {
+  const value = String(relativePath || "").replace(/\\/g, "/");
+  if (!value || value.startsWith("/") || value.split("/").includes("..")) return null;
+  if (!/\.(?:astro|md|mdx|ts|js|mjs|cjs)$/i.test(value) || /\.d\.ts$/i.test(value)) return null;
+  const target = resolve(root, value);
+  const base = resolve(root);
+  if (target !== base && !target.startsWith(base + sep)) return null;
+  return target;
+}
+
+function isSectionTemplateFile(file, root) {
+  const path = String(file || "").replace(/\\/g, "/");
+  const directory = join(root, "src/charlescms/templates").replace(/\\/g, "/").replace(/\/+$/, "");
+  return path.startsWith(`${directory}/`) && /\.(?:html|astro)$/i.test(path);
+}
+
+async function listDataFiles(dir) {
+  let files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files = files.concat(await listDataFiles(path));
+      } else if (entry.isFile() && isDataModule(entry.name)) {
+        files.push(path);
+      }
+    }
+  } catch {
+    return [];
+  }
+  return files;
+}
+
+function isDataModule(name) {
+  // Data sources that can hold editable content: plain JS/TS modules and JSON
+  // data files (including Astro content-collection `type: 'data'` entries).
+  // Type-declaration files carry no runtime values, so they are skipped.
+  return /\.(?:ts|js|mjs|cjs|json)$/.test(name) && !/\.d\.ts$/.test(name);
+}
+
+async function listSourceFiles(dir) {
+  let files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files = files.concat(await listSourceFiles(path));
+      } else if (entry.isFile() && /\.(?:astro|md|mdx)$/.test(entry.name)) {
+        files.push(path);
+      }
+    }
+  } catch {
+    return [];
+  }
+  return files;
+}
+
+async function writeSourceMap(path, root, entries) {
+  if (!path) return;
+  const sourceMap = toSerializableSourceMap(root, entries);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(sourceMap, null, 2)}\n`);
+}
+
+// The runtime form of the source map, plus an asset index so optimized
+// (astro:assets) images can be matched to their source file in production. Async
+// because it walks src/ for image files; only the virtual module needs it.
+async function buildSerializableSourceMap(root, entries) {
+  return { ...toSerializableSourceMap(root, entries), assetIndex: await buildAssetIndex(root) };
+}
+
+const IMAGE_EXT_RE = /\.(?:png|jpe?g|gif|webp|avif|svg)$/i;
+
+/**
+ * Map each image's basename → its repo-relative path for every image under `src/`.
+ *
+ * Astro keeps the original basename in optimized output (team1.HASH.webp), so the
+ * runtime can map a rendered, hashed `<img>` back to its source file. A basename
+ * used by more than one file is dropped: overwriting the wrong image is never
+ * acceptable, so ambiguous names stay non-editable (dev still resolves them
+ * exactly via the `/_image` href, which carries the full path).
+ *
+ * @param {string} root Project root directory.
+ * @returns {Promise<Object<string,string>>} Map of lowercase basename → repo path.
+ */
+export async function buildAssetIndex(root) {
+  const files = await listImageFiles(join(root, "src"));
+  const index = {};
+  const seen = new Set();
+  for (const file of files) {
+    const base = (file.split(/[\\/]/).pop() || "").replace(IMAGE_EXT_RE, "").toLowerCase();
+    if (!base) continue;
+    if (seen.has(base)) {
+      delete index[base];
+      continue;
+    }
+    seen.add(base);
+    index[base] = relative(root, file).replace(/\\/g, "/");
+  }
+  return index;
+}
+
+async function listImageFiles(dir) {
+  let files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) files = files.concat(await listImageFiles(path));
+      else if (entry.isFile() && IMAGE_EXT_RE.test(entry.name)) files.push(path);
+    }
+  } catch {
+    return [];
+  }
+  return files;
+}
+
+function toSerializableSourceMap(root, entries) {
+  const sorted = Object.fromEntries(
+    Object.entries(entries)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([id, entry]) => [
+        id,
+        {
+          ...entry,
+          file: relative(root, entry.file)
+        }
+      ])
+  );
+  return { version: 1, entries: sorted };
+}
+
+function normalizePath(path) {
+  const value = String(path || "/cms").trim();
+  const withSlash = value.startsWith("/") ? value : `/${value}`;
+  // Strip a trailing slash, but keep the root path as "/" — collapsing it to
+  // the admin-route fallback would make a single-page site's defaultEditPath
+  // equal adminPath ("/cms"), causing /cms to redirect to itself forever.
+  return withSlash.replace(/\/+$/, "") || "/";
+}
+
+// Optional allowlist of route prefixes where the in-page editor may activate.
+// Empty (default) keeps the original behavior: editable on every page. When set,
+// non-matching pages (e.g. a marketing landing page) never load the editor.
+function normalizeEditablePaths(value) {
+  if (!value) return [];
+  const list = Array.isArray(value) ? value : [value];
+  return list
+    .map((path) => String(path || "").trim())
+    .filter(Boolean)
+    .map((path) => (path.startsWith("/") ? path : `/${path}`))
+    .map((path) => path.replace(/\/+$/, "") || "/");
+}