@jxsuite/server 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
   "type": "module",
   "exports": {
     ".": "./src/server.ts",
+    "./dev": "./src/dev.ts",
     "./ai-api": "./src/ai-api.ts",
     "./data": "./src/data-api.ts",
     "./import-api": "./src/import-api.ts",
@@ -34,21 +35,21 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.3.0",
-    "@jxsuite/compiler": "^1.0.0",
-    "@jxsuite/create": "^1.0.0",
-    "@jxsuite/import": "^0.36.0",
-    "@jxsuite/protocol": "^0.4.0",
-    "@jxsuite/runtime": "^1.0.0",
-    "@jxsuite/schema": "^1.0.0",
-    "@jxsuite/starters": "^1.0.0",
+    "@jxsuite/collab": "^0.4.1",
+    "@jxsuite/compiler": "^1.2.0",
+    "@jxsuite/create": "^1.1.1",
+    "@jxsuite/import": "^0.37.1",
+    "@jxsuite/protocol": "^0.5.1",
+    "@jxsuite/runtime": "^1.2.0",
+    "@jxsuite/schema": "^1.2.0",
+    "@jxsuite/starters": "^1.1.1",
     "chokidar": "^5.0.0",
-    "kysely": "^0.29.3",
+    "kysely": "^0.29.4",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.2.0",
-    "@jxsuite/connector": "^0.2.0",
-    "@jxsuite/parser": "^1.0.0"
+    "@jxsuite/auth": "^0.3.1",
+    "@jxsuite/connector": "^0.3.1",
+    "@jxsuite/parser": "^1.2.0"
   }
 }

package/src/collab.ts

@@ -2,11 +2,15 @@
  * Collab.ts — the dev server's realtime co-editing endpoint (`/__studio/collab`): the reference
  * implementation of the Jx collab wire contract, built on `@jxsuite/collab/room`.
  *
- * Rooms are keyed by server-root-relative path; a room's Y.Text source seeds from the file on disk
- * and writes back (debounced) so every non-collab consumer — preview, live reload, plain editors —
- * keeps working off the real file. Genuinely external file changes (not our own write-back echo)
- * bump the doc's epoch and reset subscribers, per the contract. No persistence beyond the files
- * themselves: this is deliberately a reference implementation.
+ * Rooms are keyed by server-root-relative path; a room's Y.Text source seeds from the file on disk.
+ * Persistence is EXPLICIT: the shared source is written back to disk only on an explicit flush
+ * (Cmd+S / Save) and, as a last-ditch safety, on graceful server shutdown. Unsaved collaborative
+ * edits therefore live only in the room's in-memory Y.Doc until saved — non-collab consumers
+ * (preview, live reload, plain editors) intentionally keep working off the last-saved file until
+ * then. The host owns the room-level dirty signal broadcast to every peer; the embedder just tells
+ * it a persist landed via `markPersisted`. Genuinely external file changes (not our own write-back
+ * echo) bump the doc's epoch and reset subscribers, per the contract. No persistence beyond the
+ * files themselves: this is deliberately a reference implementation.
  */
 
 import { resolve } from "node:path";
@@ -17,7 +21,6 @@ import { assertAccessible } from "./studio-api";
 import type { ServerWebSocket, WebSocketHandler } from "bun";
 import type { HostConnection } from "@jxsuite/collab/room";
 
-const WRITE_BACK_DEBOUNCE_MS = 800;
 const EMPTY_ROOM_GRACE_MS = 30_000;
 
 const BINARY_EXTENSIONS = new Set([
@@ -79,8 +82,9 @@ export function createCollabRegistry(opts: {
   let connectionCounter = 0;
   let stopped = false;
 
-  const writeTimers = new Map<string, ReturnType<typeof setTimeout>>();
   const destroyTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Paths with unsaved edits (source changed since the last persist) — the shutdown worklist. */
+  const pendingPersist = new Set<string>();
   /** Content we last wrote (or are about to write) per path — the watcher-echo signature. */
   const lastWritten = new Map<string, string>();
 
@@ -103,13 +107,19 @@ export function createCollabRegistry(opts: {
       return;
     }
     if (lastWritten.get(path) === source) {
+      pendingPersist.delete(path);
       return;
     }
+    // Optimistic: closes the watcher-echo race (our own write must not read back as external).
     lastWritten.set(path, source);
     try {
       await writeFile(absPathFor(path), source, "utf8");
+      pendingPersist.delete(path);
+      // Tell the host the room is durable now: it resets the dirty baseline and broadcasts clean.
+      host.markPersisted(path);
     } catch {
-      // Disk write failures leave the room live; the next change retries.
+      // Write failed — clear the optimistic signature so the next explicit save retries.
+      lastWritten.delete(path);
     }
   };
 
@@ -126,34 +136,22 @@ export function createCollabRegistry(opts: {
       if (existing) {
         clearTimeout(existing);
       }
+      // Warnings-only model: an empty room is NOT auto-persisted (the last collaborator was warned
+      // Before leaving). Its unsaved edits are dropped when the room is torn down after the grace.
       destroyTimers.set(
         path,
         setTimeout(() => {
           destroyTimers.delete(path);
-          void persist(path).then(() => host.destroyRoomIfEmpty(path));
+          pendingPersist.delete(path);
+          host.destroyRoomIfEmpty(path);
         }, EMPTY_ROOM_GRACE_MS),
       );
     },
-    onFlush: (path) => {
-      const timer = writeTimers.get(path);
-      if (timer) {
-        clearTimeout(timer);
-        writeTimers.delete(path);
-      }
-      return persist(path);
-    },
+    onFlush: (path) => persist(path),
     onSourceChange: (path) => {
-      const existing = writeTimers.get(path);
-      if (existing) {
-        clearTimeout(existing);
-      }
-      writeTimers.set(
-        path,
-        setTimeout(() => {
-          writeTimers.delete(path);
-          void persist(path);
-        }, WRITE_BACK_DEBOUNCE_MS),
-      );
+      // No write-back: edits reach disk only on explicit flush (or graceful shutdown). The host
+      // Owns the dirty broadcast; we just note the path for the shutdown worklist.
+      pendingPersist.add(path);
     },
     rejectPath: (path) => {
       if (isBinaryPath(path)) {
@@ -205,17 +203,15 @@ export function createCollabRegistry(opts: {
         return;
       }
       stopped = true;
-      for (const timer of writeTimers.values()) {
-        clearTimeout(timer);
-      }
       for (const timer of destroyTimers.values()) {
         clearTimeout(timer);
       }
+      // Last-ditch safety on graceful shutdown: flush every path with unsaved edits.
       const flushes: Promise<void>[] = [];
-      for (const path of writeTimers.keys()) {
+      for (const path of pendingPersist) {
         flushes.push(persist(path));
       }
-      writeTimers.clear();
+      pendingPersist.clear();
       destroyTimers.clear();
       await Promise.all(flushes);
       host.destroy();

package/src/dev.ts

@@ -0,0 +1,141 @@
+/**
+ * Dev-server CLI entry — what `jx dev` spawns under Bun in a standalone project.
+ *
+ * Usage: bun @jxsuite/server/dev [--root <dir>] [--port <n>]
+ *
+ * For a site project (a project.json at the root), the entry builds the site up front, serves the
+ * built pages from dist/ ahead of the static-source fallback, and rebuilds before each live-reload
+ * broadcast so the browser always reloads into fresh output. Argument parsing and the middleware
+ * factory are exported for tests; the server boot runs only when executed directly
+ * (import.meta.main).
+ *
+ * @module @jxsuite/server/dev
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, normalize, resolve, sep } from "node:path";
+import { createDevServer } from "./server.ts";
+import { injectSSE } from "./watch.ts";
+
+export interface DevArgs {
+  port: number;
+  root: string;
+}
+
+/**
+ * Parse `--root`/`--port` (plus an optional positional root) into dev-server options.
+ *
+ * @param {string[]} argv - Raw arguments (process.argv.slice(2))
+ * @returns {DevArgs} Resolved root and port (default 3000)
+ */
+export function parseDevArgs(argv: string[]): DevArgs {
+  let root = ".";
+  let port = 3000;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--root") {
+      index += 1;
+      root = argv[index] ?? root;
+    } else if (arg === "--port") {
+      index += 1;
+      const parsed = Math.trunc(Number(argv[index] ?? ""));
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        port = parsed;
+      }
+    } else if (!arg.startsWith("--")) {
+      root = arg;
+    }
+  }
+  return { port, root: resolve(root) };
+}
+
+/**
+ * Middleware serving built pages from `<root>/dist` for page-like GET requests. Directory URLs
+ * (with or without a trailing slash) map to their index.html; anything not present in dist falls
+ * through to the dev server's static-source handling.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {(req: Request, url: URL) => Response | null}
+ */
+export function createDistMiddleware(
+  root: string,
+): (req: Request, url: URL) => Promise<Response | null> {
+  const distDir = join(root, "dist");
+  return async (req, url) => {
+    if (req.method !== "GET") {
+      return null;
+    }
+    const safe = normalize(decodeURIComponent(url.pathname)).replaceAll("\\", "/");
+    const candidate = resolve(distDir, `.${safe.startsWith("/") ? safe : `/${safe}`}`);
+    if (candidate !== distDir && !candidate.startsWith(distDir + sep)) {
+      return null;
+    }
+    let filePath: string | null = null;
+    if (existsSync(candidate)) {
+      filePath = statSync(candidate).isDirectory() ? join(candidate, "index.html") : candidate;
+    } else {
+      filePath = join(candidate, "index.html");
+    }
+    if (!filePath || !existsSync(filePath)) {
+      return null;
+    }
+    // Built pages get the live-reload client, like the server's own .html responses
+    if (filePath.endsWith(".html")) {
+      const html = await Bun.file(filePath).text();
+      return new Response(injectSSE(html), {
+        headers: { "Cache-Control": "no-cache", "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+    return new Response(Bun.file(filePath), { headers: { "Cache-Control": "no-cache" } });
+  };
+}
+
+export interface DevServerHandle {
+  port: number;
+  stop: () => void;
+}
+
+/**
+ * Boot the dev server for a root. Site projects (a project.json at the root) are built up front and
+ * rebuilt before every live-reload broadcast, with built pages served from dist/.
+ *
+ * @param {DevArgs} args - Resolved root and port
+ * @returns {Promise<DevServerHandle>} The listening server
+ */
+export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle> {
+  const isSite = existsSync(join(root, "project.json"));
+
+  let building = Promise.resolve();
+  const rebuild = () => {
+    building = building.then(async () => {
+      const { buildSite } = await import("@jxsuite/compiler/site");
+      const result = await buildSite(root, { verbose: false });
+      if (result.errors.length > 0) {
+        for (const err of result.errors) {
+          console.error(`  build error: ${err}`);
+        }
+      }
+    });
+    return building;
+  };
+
+  if (isSite) {
+    console.log(`Building ${root}...`);
+    await rebuild();
+  }
+
+  return (await createDevServer({
+    port,
+    root,
+    ...(isSite && {
+      middleware: createDistMiddleware(root),
+      watch: { preReload: () => rebuild(), reloadOnAnyChange: true },
+    }),
+  })) as DevServerHandle;
+}
+
+if (import.meta.main) {
+  const { port, root } = parseDevArgs(process.argv.slice(2));
+  const server = await startDev({ port, root });
+  console.log(`Jx dev server running at http://localhost:${server.port} (root: ${root})`);
+}

package/src/watch.ts

@@ -10,6 +10,7 @@ import type { FsEventPayload } from "./refactor/fs-events.ts";
 const DEFAULT_IGNORE = [
   "**/node_modules/**",
   "**/dist/**",
+  "**/.cache/**",
   "**/.git/**",
   "**/.jx/**",
   "**/.devenv/**",
@@ -62,7 +63,12 @@ export function injectSSE(html: string) {
  *
  * @param {string} root - Absolute path to watch
  * @param {BuildEntry[]} builds - Build entries (for selective rebuild)
- * @param {{ ignore?: string[]; debounce?: number; reloadOnAnyChange?: boolean }} [opts]
+ * @param {{
+ *   ignore?: string[];
+ *   debounce?: number;
+ *   reloadOnAnyChange?: boolean;
+ *   preReload?: (filename: string) => Promise<void> | void;
+ * }} [opts]
  * @returns {{
  *   broadcast: () => void;
  *   handleSSE: () => Response;
@@ -76,11 +82,14 @@ export function createWatcher(
     ignore?: string[];
     debounce?: number;
     reloadOnAnyChange?: boolean;
+    /** Runs before the reload broadcast — e.g. `jx dev` rebuilds the site here. */
+    preReload?: (filename: string) => Promise<void> | void;
   } = {},
 ) {
   const ignore = opts.ignore ?? DEFAULT_IGNORE;
   const debounceMs = opts.debounce ?? 50;
   const reloadOnAnyChange = opts.reloadOnAnyChange ?? false;
+  const { preReload } = opts;
 
   const clients = new Set<(msg: string) => void>();
   const encoder = new TextEncoder();
@@ -172,6 +181,13 @@ export function createWatcher(
 
     clearTimeout(timer ?? undefined);
     timer = setTimeout(async () => {
+      if (preReload) {
+        try {
+          await preReload(filename);
+        } catch (error) {
+          console.error(`[watch] preReload failed: ${(error as Error).message}`);
+        }
+      }
       if (builds.length > 0) {
         const result = await rebuild(builds, filename);
         if (!result.success) {