@jxsuite/server 3.0.0 → 4.1.0

package/src/studio-api.ts

@@ -22,13 +22,19 @@ import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
 import { handleDataApi } from "./data-api.ts";
 import { containedPath } from "./net-guard.ts";
 import { startSitePreview } from "./site-preview.ts";
+import {
+  clearLivePreviewOverlay,
+  navigateLivePreview,
+  setLivePreviewOverlay,
+  startLivePreview,
+} from "./live-preview.ts";
 import { applyRename } from "./refactor/apply.ts";
 import { findReferences } from "./refactor/find-refs.ts";
 import {
   bunExecutable,
   dependenciesNeedInstall,
   installDependencies,
-  outdatedPackages,
+  packageVersions,
   setPackageVersions,
 } from "./packages.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
@@ -288,6 +294,17 @@ export interface StudioApiOptions {
    * unreachable by the very request that made it.
    */
   onProjectCreated?: (projectRoot: string) => void;
+  /**
+   * Tell the collaboration registry a path changed underneath it — the same hook the file watcher
+   * uses (`server.ts`), handed to the one mutation the watcher cannot describe.
+   *
+   * A rename MOVES a file, and a live room is keyed by the old path. Without this the room survives
+   * the move holding pre-rename content, and `stop()`'s graceful-shutdown flush writes it back —
+   * RECREATING the file the rename deleted. `pendingPersist` receives a path on the room's seed
+   * transaction, so a clean editor does not protect against it either. Passing the OLD absolute
+   * path lets the registry reset that room, which deletes it and makes the later flush a no-op.
+   */
+  onFileMoved?: (absPath: string) => void;
 }
 
 /**
@@ -323,6 +340,23 @@ function conflictingPaths(output: string): string[] {
   return [...paths];
 }
 
+/**
+ * Order a directory listing so two identical requests answer identically.
+ *
+ * `readdir` and `Bun.Glob.scan` both answer in FILESYSTEM order, which is not an order at all: it
+ * varies with the directory's internal layout and therefore with the history of writes to it. That
+ * reached the screenshots as a picture that changed on its own — `blog-grid.png` photographs a
+ * content collection, `content-source.ts` inserts rows in listing order (deliberately, so a
+ * concurrent read cannot decide it), and the listing underneath was unsorted. The collection's
+ * three posts swapped places between runs and rewrote the image 15 times in ten days.
+ *
+ * Codepoint order, not `localeCompare`: the comparison has to answer the same on a maintainer's
+ * machine and in the capture container, and a locale-aware collation does not promise that.
+ */
+function byPathOrder<T extends { path: string }>(entries: T[]): T[] {
+  return entries.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
 export async function handleStudioApi(
   req: Request,
   url: URL,
@@ -701,7 +735,7 @@ export async function handleStudioApi(
             }
           } catch {}
         }
-        return Response.json(files);
+        return Response.json(byPathOrder(files));
       }
 
       const entries = await readdir(absDir, { withFileTypes: true });
@@ -720,7 +754,7 @@ export async function handleStudioApi(
           type: entry.isDirectory() ? "directory" : "file",
         });
       }
-      return Response.json(files);
+      return Response.json(byPathOrder(files));
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -889,6 +923,76 @@ export async function handleStudioApi(
     }
   }
 
+  /**
+   * Preview the site LIVE — the working tree browsable at real routes, with no build on the path.
+   *
+   * The sibling of `/__studio/build` and the one Open in Browser reaches first. What it answers
+   * with is not compiler output: `@jxsuite/site` composes each page on demand and
+   * `@jxsuite/runtime` assembles it in the reader's browser, so what opens is the tree as it stands
+   * — the author's unsaved edits included, because Studio publishes those as an overlay this origin
+   * reads first.
+   *
+   * `reused` is the second answer and the caller must honour it. A tab already holding this
+   * project's reload stream is retargeted in place, and opening another would give the author two
+   * tabs on one project — which is the thing the retarget exists to prevent.
+   */
+  if (path === "/__studio/preview" && req.method === "POST") {
+    const dir = activeProjectRoot ?? root;
+    if (!existsSync(resolve(dir, "project.json"))) {
+      return problem("invalidRequest", "Not a site project");
+    }
+    let body: { route?: string };
+    try {
+      body = (await req.json()) as { route?: string };
+    } catch {
+      return problem("invalidRequest", "Invalid JSON body");
+    }
+    try {
+      const preview = await startLivePreview(dir);
+      const reused = body.route ? await navigateLivePreview(dir, body.route) : false;
+      return Response.json({
+        errors: preview.errors,
+        /* A live preview writes nothing, so there are no files to count. The field is part of the
+           shared shape and saying zero is the honest answer rather than an omission. */
+        files: 0,
+        mode: "live",
+        reused,
+        routes: preview.routes,
+        url: preview.origin,
+      });
+    } catch (error) {
+      return problem("internalError", errorMessage(error));
+    }
+  }
+
+  /**
+   * The unsaved bytes a live preview reads before the disk.
+   *
+   * POST publishes one document, DELETE retracts one or all of them. Studio owns the lifecycle — it
+   * knows which documents are dirty and when a save, a close or a discard ends that — so this route
+   * stores what it is told and decides nothing.
+   */
+  if (path === "/__studio/preview/overlay") {
+    const dir = activeProjectRoot ?? root;
+    let body: { path?: string; contents?: string };
+    try {
+      body = (await req.json()) as { path?: string; contents?: string };
+    } catch {
+      return problem("invalidRequest", "Invalid JSON body");
+    }
+    if (req.method === "POST") {
+      if (typeof body.path !== "string" || typeof body.contents !== "string") {
+        return problem("invalidRequest", "Missing path or contents");
+      }
+      setLivePreviewOverlay(dir, body.path, body.contents);
+      return new Response(null, { status: 204 });
+    }
+    if (req.method === "DELETE") {
+      clearLivePreviewOverlay(dir, typeof body.path === "string" ? body.path : undefined);
+      return new Response(null, { status: 204 });
+    }
+  }
+
   // ─── Package management ──────────────────────────────────────────────────────
 
   // List CEM-bearing npm packages
@@ -1046,12 +1150,12 @@ export async function handleStudioApi(
     return Response.json({ needsInstall: dependenciesNeedInstall(scanRoot) });
   }
 
-  // Dependencies with a newer version available
-  if (path === "/__studio/packages/outdated" && req.method === "GET") {
+  // The newest published version of each dependency (whether or not it is behind)
+  if (path === "/__studio/packages/versions" && req.method === "GET") {
     try {
       const dir = url.searchParams.get("dir") || activeProjectRoot || root;
       const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
-      return Response.json(await outdatedPackages(scanRoot));
+      return Response.json(await packageVersions(scanRoot));
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -1193,6 +1297,9 @@ export async function handleStudioApi(
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
+    // Immediately, and before the refactor pass: a room still keyed to the old path would be
+    // Flushed back onto disk at shutdown, recreating the file this rename just moved.
+    opts.onFileMoved?.(absFrom);
     // Refactor pass: rewrite path references project-wide and, for a component, auto-rename its tag.
     // The move already succeeded, so a refactor failure is reported but never fails the rename.
     const scanRoot = activeProjectRoot ?? root;
@@ -1201,29 +1308,42 @@ export async function handleStudioApi(
       const report = await applyRename({ absFrom, absTo, registry, root: scanRoot });
       return Response.json(report);
     } catch (error) {
+      /* Project-relative, like the report this stands in for. The route takes its `from`/`to` in
+         server space and answers in project space; emitting two spaces from one route is what
+         made the sibling `references` route's own confusion survive review (issue 239). */
       return Response.json({
         error: errorMessage(error),
-        from: fwd(relative(root, absFrom)),
+        from: fwd(relative(scanRoot, absFrom)),
         ok: true,
-        to: fwd(relative(root, absTo)),
+        to: fwd(relative(scanRoot, absTo)),
       });
     }
   }
 
   // Where a file / component tag is used (the read side of the rename refactor's walker)
   if (path === "/__studio/references" && req.method === "GET") {
-    const target = url.searchParams.get("path");
+    let target = url.searchParams.get("path");
     const tag = url.searchParams.get("tag");
     if (!target && !tag) {
       return problem("invalidRequest", "Missing path or tag");
     }
     const scanRoot = activeProjectRoot ?? root;
     if (target) {
+      /* Server-root-relative in (like every sibling route, and like the adapter's `serverPath()`
+         sends), project-relative out. The sweep runs in the project's space, so the target has to
+         be re-expressed into it: resolving against `scanRoot` directly doubles the prefix, and a
+         doubled prefix names a file that does not exist — which reads as a confident zero (issue 239). */
+      const abs = resolve(root, target);
       try {
-        assertAccessible(resolve(scanRoot, target), root, activeProjectRoot);
+        assertAccessible(abs, root, activeProjectRoot);
       } catch (error) {
         return new Response(errorMessage(error), { status: 400 });
       }
+      const inProject = fwd(relative(scanRoot, abs));
+      if (inProject === "" || inProject.startsWith("../") || isAbsolute(inProject)) {
+        return problem("invalidRequest", "path is outside the active project");
+      }
+      target = inProject;
     }
     try {
       const registry = await getFormatRegistry(scanRoot);

package/src/watch.ts

@@ -5,6 +5,7 @@ import { relative } from "node:path";
 import { rebuild } from "./build.ts";
 import { coalesceFsEvents, toFsEvent } from "./refactor/fs-events.ts";
 import { createWatchIgnore } from "./watch-policy.ts";
+import { createSseHub } from "./sse.ts";
 import { invalidateReferenceCache } from "./refactor/find-refs.ts";
 import type { BuildEntry } from "./types.ts";
 import type { FsEventPayload } from "./refactor/fs-events.ts";
@@ -51,14 +52,14 @@ function shouldIgnore(pathname: string, ignore: string[]) {
 
 export { shouldIgnore };
 
-/**
- * Reconnection time advertised on the stream, in milliseconds (HTML Standard, `retry:`).
- *
- * The default is user-agent defined and measured in seconds, which on a dev server restart is long
- * enough for a save to look like it did nothing. Both endpoints are on loopback, so a reconnect
- * costs nothing and half a second lands inside a typical restart.
+/*
+ * The stream itself lives in `sse.ts`, shared with the live preview origin's channel — the reading
+ * of the EventSource contract it encodes (`retry:`, the `id:` that arms `Last-Event-ID`, one reload
+ * on resume and none on a first connection) is specified once, in specs/server.md §3.1, and having
+ * two of it is how one of them silently stops reconnecting. Re-exported here because `RECONNECT_MS`
+ * is part of what this module's consumers already read.
  */
-export const RECONNECT_MS = 500;
+export { RECONNECT_MS } from "./sse.ts";
 
 export const SSE_SCRIPT = `\n<script>new EventSource('/__reload').onmessage=()=>location.reload()</script>`;
 
@@ -102,96 +103,7 @@ export function createWatcher(
   const reloadOnAnyChange = opts.reloadOnAnyChange ?? false;
   const { preReload } = opts;
 
-  const clients = new Set<(msg: string) => void>();
-  const encoder = new TextEncoder();
-
-  /*
-   * Monotonic reload counter, sent as the SSE `id:` of every reload frame.
-   *
-   * Its only job is to arm the browser: a stream that has never sent an `id:` makes the client omit
-   * `Last-Event-ID` on reconnect, and then the server cannot tell a first connection from a
-   * reconnection. **Nothing is buffered against it and nothing is replayed.** A reconnecting client
-   * gets exactly one reload, because the page it is holding was built before the disconnect and a
-   * full reload subsumes every event it missed — one is as correct as a hundred and finishes
-   * sooner. Do not "complete" this into a replay buffer; there is no per-event state to replay.
-   */
-  let lastEventId = 0;
-
-  function broadcast() {
-    lastEventId += 1;
-    const frame = `id: ${lastEventId}\ndata: reload\n\n`;
-    for (const send of clients) {
-      send(frame);
-    }
-  }
-
-  /**
-   * Send a _named_ SSE event. The preview iframe only listens to the default (unnamed) `onmessage`,
-   * so named events (e.g. "fs") reach the studio shell without triggering a preview reload.
-   */
-  function broadcastEvent(event: string, payload: unknown) {
-    const frame = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
-    for (const send of clients) {
-      send(frame);
-    }
-  }
-
-  /**
-   * Open the live-reload stream.
-   *
-   * Two halves of the HTML Standard's EventSource contract that were missing, and are the whole of
-   * `gap:sse-reconnect`:
-   *
-   * - **`retry:`** sets the reconnection time. The default is user-agent defined and is measured in
-   *   seconds; during a dev-server restart that is long enough to watch a save do nothing. 500ms is
-   *   loopback, so the reconnect costs nothing and lands inside the restart.
-   * - **`Last-Event-ID`** is how the browser says "I was here before". It gets **one** reload and no
-   *   replay — see the note on `lastEventId`. A dev server has no event log and needs none: the
-   *   reload is idempotent and total.
-   *
-   * @param {Request} [request] - The stream request; read only for its `Last-Event-ID`
-   * @returns {Response}
-   */
-  function handleSSE(request?: Request) {
-    const resuming = (request?.headers.get("Last-Event-ID") ?? "") !== "";
-    /** @type {((msg: string) => void) | undefined} */
-    let send: ((msg: string) => void) | undefined;
-    const stream = new ReadableStream({
-      cancel() {
-        if (send) {
-          clients.delete(send);
-        }
-      },
-      start(c) {
-        send = (msg: string) => {
-          try {
-            c.enqueue(encoder.encode(msg));
-          } catch {}
-        };
-        clients.add(send);
-        // The retry interval is a stream-level field, so it is set once, before any event.
-        send(`retry: ${RECONNECT_MS}\n\n`);
-        if (resuming) {
-          lastEventId += 1;
-          send(`id: ${lastEventId}\ndata: reload\n\n`);
-        }
-        const hb = setInterval(() => {
-          try {
-            c.enqueue(encoder.encode(": heartbeat\n\n"));
-          } catch {
-            clearInterval(hb);
-          }
-        }, 15_000);
-      },
-    });
-    return new Response(stream, {
-      headers: {
-        "Cache-Control": "no-cache",
-        Connection: "keep-alive",
-        "Content-Type": "text/event-stream",
-      },
-    });
-  }
+  const { broadcast, broadcastEvent, handleSSE } = createSseHub();
 
   let timer: ReturnType<typeof setTimeout> | null = null;
   let fsTimer: ReturnType<typeof setTimeout> | null = null;