@jxsuite/server 7.0.0 → 8.0.1

package/README.md

@@ -1,6 +1,6 @@
 # `@jxsuite/server`
 
-> Bun-native development server for Jx projects with live reload, proxy resolution, and Studio API.
+> Development server for Jx projects with live reload, proxy resolution, and Studio API, plus the project server, package operations and package service that also run on Node.
 
 ## Overview
 
@@ -73,7 +73,29 @@ OXC-powered tools for the Studio function body editor:
 | ---------- | ----------------------------- |
 | `chokidar` | File watching for live reload |
 
-Bun built-ins used: `Bun.serve`, `Bun.build`, `Bun.Transpiler`.
+| `@npmcli/arborist` | Package operations (npm's installer) |
+| `npm-package-arg` | Validating a package spec before anything is installed |
+| `ws` | WebSockets for `serve()` on Node |
+
+`createDevServer()` and the build pipeline run on Bun (`Bun.serve`, `Bun.build`, `Bun.Transpiler`).
+
+## Running on Node
+
+The desktop app runs the project server on the Node inside Electron, so everything it loads is runtime-neutral, with the Bun implementation chosen by the `bun` export condition:
+
+- **`@jxsuite/server/serve`**: `serve()`, one HTTP and WebSocket server over `Bun.serve` under Bun and `node:http` with `ws` under Node. It is async, because Node binds asynchronously.
+- **`@jxsuite/server/fs-glob`** and **`@jxsuite/server/file-response`**: globbing and file responses that answer as Bun's own built-ins do.
+- **`@jxsuite/server/packages`**: add, remove, install and update-versions, run in-process on npm's Arborist. Install scripts never run, only the public registry is read, and the operation writes `package-lock.json` (a project's `bun.lock` is replaced on its first install).
+- **`@jxsuite/server/packages-service`**: the same operations over HTTP, lockfile-only, for a host with no filesystem of its own. The Jx cloud platform runs it from the [jxsuite/package-manager](https://github.com/jxsuite/package-manager) container image.
+
+## Upgrading to 8.0
+
+8.0 is the release that made the server runtime-neutral. Code that imports these from `@jxsuite/server` needs to change:
+
+- `createProjectServer()`, `startSitePreview()`, `sitePreviewOrigin()` and `stopSitePreviews()` return promises. Await them.
+- `documentGlob()` returns the glob pattern as a string instead of a `Bun.Glob`. Scan it with `scanFiles()` from `@jxsuite/server/fs-glob`.
+- `bunExecutable()` is removed: package operations no longer run a package manager in a subprocess.
+- `installDependencies()`, `addPackage()`, `removePackage()` and `setPackageVersions()` take an options argument and write `package-lock.json` rather than `bun.lock`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "7.0.0",
+  "version": "8.0.1",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,12 @@
     "src/"
   ],
   "type": "module",
+  "imports": {
+    "#serve": {
+      "bun": "./src/serve.bun.ts",
+      "default": "./src/serve.node.ts"
+    }
+  },
   "exports": {
     ".": "./src/server.ts",
     "./dev": "./src/dev.ts",
@@ -29,7 +35,14 @@
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts",
     "./jx-mounts": "./src/jx-mounts.ts",
-    "./dev-vars": "./src/dev-vars.ts"
+    "./dev-vars": "./src/dev-vars.ts",
+    "./fs-glob": "./src/fs-glob.ts",
+    "./serve": {
+      "bun": "./src/serve.bun.ts",
+      "default": "./src/serve.node.ts"
+    },
+    "./file-response": "./src/file-response.ts",
+    "./packages-service": "./src/packages-service.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -41,25 +54,32 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.41.0",
-    "@jxsuite/catalog": "^0.1.3",
-    "@jxsuite/collab": "^0.11.3",
-    "@jxsuite/compiler": "^7.0.0",
-    "@jxsuite/create": "^1.4.1",
-    "@jxsuite/import": "^0.41.1",
-    "@jxsuite/protocol": "^5.0.0",
-    "@jxsuite/runtime": "^6.0.0",
-    "@jxsuite/schema": "^4.1.0",
-    "@jxsuite/site": "^2.2.1",
-    "@jxsuite/starters": "^3.1.1",
+    "@jxsuite/ai": "^0.41.2",
+    "@jxsuite/catalog": "^0.1.5",
+    "@jxsuite/collab": "^0.11.4",
+    "@jxsuite/compiler": "^8.0.1",
+    "@jxsuite/create": "^1.5.1",
+    "@jxsuite/import": "^0.42.1",
+    "@jxsuite/protocol": "^6.1.0",
+    "@jxsuite/runtime": "^6.0.1",
+    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/site": "^2.2.2",
+    "@jxsuite/starters": "^3.1.3",
+    "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.7",
-    "oxfmt": "^0.74.0",
+    "npm-package-arg": "^14.0.0",
+    "oxfmt": "^0.75.0",
+    "ws": "^8.22.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.1",
-    "@jxsuite/connector": "^0.8.1",
-    "@jxsuite/parser": "^4.1.1"
+    "@jxsuite/auth": "^0.8.2",
+    "@jxsuite/connector": "^0.8.2",
+    "@jxsuite/parser": "^4.1.2",
+    "@jxsuite/test-support": "^0.0.0",
+    "@types/npm-package-arg": "^6.1.4",
+    "@types/npmcli__arborist": "^6.3.3",
+    "@types/ws": "^8.18.2"
   }
 }

package/src/collab.ts

@@ -24,7 +24,7 @@ import {
   selectSubprotocol,
 } from "@jxsuite/collab/negotiate";
 import { assertAccessible } from "./studio-api";
-import type { ServerWebSocket, WebSocketHandler } from "bun";
+import type { ServeServer, ServeSocket, ServeWebSocketHandler } from "./serve.ts";
 import type { HostConnection } from "@jxsuite/collab/room";
 import { problem } from "./problem.ts";
 
@@ -66,20 +66,15 @@ export interface CollabSocketData {
 export interface CollabRegistry {
   /**
    * Handle a request to /__studio/collab: WebSocket upgrades become collab connections; a plain GET
-   * answers the capability probe. Returns undefined when the upgrade was accepted (Bun sends the
-   * 101 itself).
+   * answers the capability probe. Returns undefined when the upgrade was accepted (the server sends
+   * the 101 itself).
    */
   handleRequest: (
     req: Request,
-    server: {
-      upgrade: (
-        req: Request,
-        opts: { data: CollabSocketData; headers?: Record<string, string> },
-      ) => boolean;
-    },
+    server: Pick<ServeServer<CollabSocketData>, "upgrade">,
   ) => Response | undefined;
-  /** Bun.serve websocket handlers backing the upgraded connections. */
-  websocket: WebSocketHandler<CollabSocketData>;
+  /** The websocket handlers backing the upgraded connections (`serve.ts`). */
+  websocket: ServeWebSocketHandler<CollabSocketData>;
   /** Watcher hook: a file changed on disk (absolute path). Echoes of our write-back are ignored. */
   handleExternalChange: (absPath: string) => void;
   /** Flush pending write-backs and tear everything down. */
@@ -253,17 +248,17 @@ export function createCollabRegistry(opts: {
     },
 
     websocket: {
-      close(ws: ServerWebSocket<CollabSocketData>) {
+      close(ws: ServeSocket<CollabSocketData>) {
         ws.data.connection?.close();
         ws.data.connection = null;
       },
-      message(ws: ServerWebSocket<CollabSocketData>, message: string | Buffer) {
+      message(ws: ServeSocket<CollabSocketData>, message: string | Buffer) {
         if (isString(message)) {
           return;
         }
         ws.data.connection?.handleMessage(new Uint8Array(message));
       },
-      open(ws: ServerWebSocket<CollabSocketData>) {
+      open(ws: ServeSocket<CollabSocketData>) {
         connectionCounter += 1;
         const login = `local-${connectionCounter}`;
         ws.data.connection = host.connect(

package/src/extension-catalog.ts

@@ -8,10 +8,11 @@
  *    `extensions/` tree, so core keeps no dependency on an extension package (§2).
  * 2. The project's own dependencies, scanned for anything exporting a `jx-extension.json`.
  *
- * Both are then annotated with two facts only a backend holds: whether the PROJECT resolves the
- * package, and whether THIS HOST does. Those are probed rather than declared, because what a
- * desktop build stages and what a Worker bundles are different facts and neither is knowable from a
- * package list — which is also why the catalogue is a platform capability instead of a constant.
+ * Both are then annotated with the one fact only a backend holds: whether the PROJECT resolves the
+ * package. It is probed rather than declared, and it is the only resolution asked about: an
+ * extension resolves from the project's own install and never from this host, first-party ones
+ * included (specs/extensions.md §3), so enabling one the project lacks is always
+ * install-then-enable.
  *
  * **`installed` is answered here rather than by the client**, because `listPackages` does not mean
  * one thing across backends: the dev server's own packages route drops a declared dependency it
@@ -184,11 +185,6 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
     if (meta.requires) {
       entry.requires = meta.requires;
     }
-    // Bundled means "resolves without a project install": the host answers for it, and the
-    // Project does not have to.
-    if (found.host && !found.project) {
-      entry.bundled = true;
-    }
     entries.push(entry);
   }
 
@@ -238,9 +234,6 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
     if (loaded.formats.length > 0) {
       entry.formats = loaded.formats;
     }
-    if (found.host) {
-      entry.bundled = true;
-    }
     entries.push(entry);
   }
 

package/src/file-response.ts

@@ -0,0 +1,140 @@
+/**
+ * File responses on `node:fs`, answering what `new Response(Bun.file(path))` answered.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so the servers it reaches
+ * cannot hand `Bun.file` to a `Response`. `openAsBlob` is the shared equivalent: a lazily read,
+ * file-backed `Blob` whose `type` becomes the response's `Content-Type`. What it lacks is Bun's
+ * inference of that type from the extension, which {@link HOST_MEDIA_TYPES} reproduces for every
+ * extension a project or the Studio assets serve; `tests/file-response.test.ts` holds each entry
+ * equal to `Bun.file(...).type`. The corrections Jx makes to a host's table (`mediaTypeForPath`)
+ * are applied by callers on top of this, exactly as they were on top of Bun's.
+ *
+ * @docs studio/desktop
+ */
+import { openAsBlob, statSync } from "node:fs";
+import { extname } from "node:path";
+
+/** The type `Bun.file` infers for an extension, where it is not `application/octet-stream`. */
+export const HOST_MEDIA_TYPES = new Map<string, string>([
+  [".7z", "application/x-7z-compressed"],
+  [".aac", "audio/x-aac"],
+  [".ai", "application/postscript"],
+  [".apng", "image/apng"],
+  [".atom", "application/atom+xml"],
+  [".avif", "image/avif"],
+  [".bmp", "image/x-ms-bmp"],
+  [".cjs", "text/javascript;charset=utf-8"],
+  [".class", "application/java-vm"],
+  [".css", "text/css;charset=utf-8"],
+  [".csv", "text/csv"],
+  [".dmg", "application/x-apple-diskimage"],
+  [".doc", "application/msword"],
+  [".docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  [".eot", "application/vnd.ms-fontobject"],
+  [".eps", "application/postscript"],
+  [".epub", "application/epub+zip"],
+  [".exe", "application/x-msdownload"],
+  [".flac", "audio/x-flac"],
+  [".gif", "image/gif"],
+  [".glb", "model/gltf-binary"],
+  [".gltf", "model/gltf+json"],
+  [".gz", "application/gzip"],
+  [".hbs", "text/x-handlebars-template"],
+  [".heic", "image/heic"],
+  [".htm", "text/html;charset=utf-8"],
+  [".html", "text/html;charset=utf-8"],
+  [".ico", "image/x-icon"],
+  [".ics", "text/calendar"],
+  [".iso", "application/x-iso9660-image"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".js", "text/javascript;charset=utf-8"],
+  [".json", "application/json;charset=utf-8"],
+  [".jsonld", "application/ld+json"],
+  [".jsx", "text/javascript;charset=utf-8"],
+  [".log", "text/plain;charset=utf-8"],
+  [".m4a", "audio/x-m4a"],
+  [".map", "application/json;charset=utf-8"],
+  [".markdown", "text/markdown"],
+  [".md", "text/markdown"],
+  [".mdx", "text/mdx"],
+  [".mjs", "text/javascript;charset=utf-8"],
+  [".mov", "video/quicktime"],
+  [".mp3", "audio/mpeg"],
+  [".mp4", "video/mp4"],
+  [".mts", "text/javascript;charset=utf-8"],
+  [".oga", "audio/ogg"],
+  [".ogg", "audio/ogg"],
+  [".ogv", "video/ogg"],
+  [".opus", "audio/ogg"],
+  [".otf", "font/otf"],
+  [".pdf", "application/pdf"],
+  [".php", "application/x-httpd-php"],
+  [".png", "image/png"],
+  [".ppt", "application/vnd.ms-powerpoint"],
+  [".pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation"],
+  [".psd", "image/vnd.adobe.photoshop"],
+  [".rar", "application/x-rar-compressed"],
+  [".rss", "application/rss+xml"],
+  [".rtf", "text/rtf"],
+  [".sh", "application/x-sh"],
+  [".srt", "application/x-subrip"],
+  [".svg", "image/svg+xml"],
+  [".tar", "application/x-tar"],
+  [".tif", "image/tiff"],
+  [".tiff", "image/tiff"],
+  [".toml", "application/toml"],
+  [".ts", "text/javascript;charset=utf-8"],
+  [".tsv", "text/tab-separated-values"],
+  [".tsx", "text/javascript;charset=utf-8"],
+  [".ttf", "font/ttf"],
+  [".txt", "text/plain;charset=utf-8"],
+  [".vtt", "text/vtt"],
+  [".wasm", "application/wasm"],
+  [".wav", "audio/x-wav"],
+  [".weba", "audio/webm"],
+  [".webm", "video/webm"],
+  [".webmanifest", "application/manifest+json"],
+  [".webp", "image/webp"],
+  [".woff", "font/woff"],
+  [".woff2", "font/woff2"],
+  [".xls", "application/vnd.ms-excel"],
+  [".xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  [".xml", "application/xml"],
+  [".yaml", "text/yaml"],
+  [".yml", "text/yaml"],
+  [".zip", "application/zip"],
+]);
+
+const FALLBACK_MEDIA_TYPE = "application/octet-stream";
+
+/** The media type Bun would infer for `path` from its extension (case-insensitive). */
+export function hostMediaType(path: string): string {
+  return HOST_MEDIA_TYPES.get(extname(path).toLowerCase()) ?? FALLBACK_MEDIA_TYPE;
+}
+
+/** True when `path` names a regular file (Bun's `exists()` is false for a directory). */
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The file at `path` as a lazily read `Blob` typed by its extension, or null when there is no
+ * regular file there.
+ */
+export async function openFile(path: string): Promise<Blob | null> {
+  if (!isFile(path)) {
+    return null;
+  }
+  return openAsBlob(path, { type: hostMediaType(path) });
+}
+
+/** A response streaming the file at `path`, or null when there is no regular file there. */
+export async function fileResponse(path: string, init?: ResponseInit): Promise<Response | null> {
+  const blob = await openFile(path);
+  return blob ? new Response(blob, init) : null;
+}

package/src/fs-glob.ts

@@ -0,0 +1,45 @@
+/**
+ * File globbing on `node:fs`, answering what `Bun.Glob#scan({ cwd, dot: false })` answered.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so nothing it reaches may
+ * call `Bun.Glob`. `fs.promises.glob` is the shared API, and two of its defaults differ from Bun's:
+ * it yields directories as well as files, and it yields a symbolic link as itself. A third
+ * difference is in the matcher, below. Bun's scan yields regular files only and does not follow
+ * links, so both are filtered here. `tests/fs-glob.test.ts` holds the two answers equal on the same
+ * tree.
+ *
+ * Paths are relative to `cwd` with the platform's own separator, as Bun's were.
+ */
+import type { Dirent } from "node:fs";
+import { glob, opendir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+/** Bun's scan neither yields nor descends through a symbolic link, file or directory. */
+function isLink(entry: Dirent): boolean {
+  return entry.isSymbolicLink();
+}
+
+/**
+ * Bun expands a one-alternative brace (`*.{json}`) and Node's matcher keeps it literal, so a
+ * pattern built from a list that happens to hold one extension would match nothing. Unwrap those.
+ */
+function unwrapSingleBraces(pattern: string): string {
+  return pattern.replaceAll(/\{([^{},]*)\}/g, "$1");
+}
+
+/**
+ * Every regular file under `cwd` matching `pattern`, skipping dot-prefixed names.
+ *
+ * @yields {string} Each match, relative to `cwd`
+ */
+export async function* scanFiles(pattern: string, cwd: string): AsyncGenerator<string> {
+  // Bun's scan throws for a root it cannot read; Node's glob yields nothing. Opening it first throws.
+  const dir = await opendir(cwd);
+  await dir.close();
+  const options = { cwd, exclude: isLink, withFileTypes: true } as const;
+  for await (const entry of glob(unwrapSingleBraces(pattern), options)) {
+    if (entry.isFile()) {
+      yield relative(cwd, join(entry.parentPath, entry.name));
+    }
+  }
+}

package/src/live-preview.ts

@@ -54,6 +54,9 @@ import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { loopbackGate, originHostGate } from "./net-guard.ts";
 import { problem } from "./problem.ts";
+import { scanFiles } from "./fs-glob.ts";
+import { serve } from "#serve";
+import { bundleToString } from "@jxsuite/compiler/bundler";
 
 /** A running live preview for one project. */
 export interface LivePreview {
@@ -116,7 +119,7 @@ function overlayFor(projectRoot: string): Overlay {
 }
 
 interface Running extends LivePreview {
-  server: { stop: (closeActiveConnections?: boolean) => void };
+  server: { stop: (closeActiveConnections?: boolean) => Promise<void> };
   hub: SseHub;
   /** This origin's own resolver credential, distinct from any editing server's. */
   token: string;
@@ -132,6 +135,8 @@ interface Running extends LivePreview {
 
 /** One origin per project root — a second Open in Browser reuses the first one's port. */
 const running = new Map<string, Running>();
+/** Origins mid-bind, so two starts racing for one project share a server. */
+const starting = new Map<string, Promise<Running>>();
 
 /** The runtime bundle is the same bytes for every project, so it is read once per process. */
 let runtimeBundle: string | null = null;
@@ -162,11 +167,10 @@ async function loadRuntimeBundle(): Promise<string> {
   } catch {
     // No published dist on this install; fall through and build one.
   }
-  const result = await Bun.build({
-    entrypoints: [require_.resolve("@jxsuite/runtime")],
+  runtimeBundle = await bundleToString(require_.resolve("@jxsuite/runtime"), {
+    minify: false,
     target: "browser",
   });
-  runtimeBundle = await result.outputs[0]!.text();
   return runtimeBundle;
 }
 
@@ -178,7 +182,7 @@ async function treePaths(projectRoot: string, overlay: Map<string, string>): Pro
     if (!existsSync(dir)) {
       continue;
     }
-    for await (const match of new Bun.Glob("**/*").scan({ cwd: dir, dot: false })) {
+    for await (const match of scanFiles("**/*", dir)) {
       found.add(`${root}${match.replaceAll("\\", "/")}`);
     }
   }
@@ -419,7 +423,20 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
     await ensureCache(existing, projectRoot);
     return report(existing, projectRoot);
   }
+  let pending = starting.get(projectRoot);
+  if (!pending) {
+    pending = listen(projectRoot).finally(() => starting.delete(projectRoot));
+    starting.set(projectRoot, pending);
+  }
+  const entry = await pending;
+  /* Counted before answering, because the caller reports it to the author and "0 pages" from a site
+     with pages is worse than the moment it costs to walk the tree. */
+  await ensureCache(entry, projectRoot);
+  return report(entry, projectRoot);
+}
 
+/** Bind the live preview origin for `projectRoot` and register it. */
+async function listen(projectRoot: string): Promise<Running> {
   const entry: Running = {
     burstStartedAt: null,
     cache: null,
@@ -431,11 +448,11 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
     port: 0,
     reloadTimer: null,
     routes: 0,
-    server: { stop: () => {} },
+    server: { stop: async () => {} },
     token: crypto.randomUUID(),
   };
 
-  const server = Bun.serve({
+  const server = await serve({
     fetch: (req) => handle(entry, projectRoot, req),
     hostname: "127.0.0.1",
     /* The composed page is assembled per request and the stream is long-lived; the dev server's
@@ -449,10 +466,7 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
   entry.origin = server.url.origin;
   entry.port = Number(server.url.port);
   running.set(projectRoot, entry);
-  /* Counted before answering, because the caller reports it to the author and "0 pages" from a site
-     with pages is worse than the moment it costs to walk the tree. */
-  await ensureCache(entry, projectRoot);
-  return report(entry, projectRoot);
+  return entry;
 }
 
 /** What a caller hands back to Studio. */
@@ -616,7 +630,7 @@ export function stopLivePreviews(): void {
     if (entry.reloadTimer) {
       clearTimeout(entry.reloadTimer);
     }
-    entry.server.stop(true);
+    void entry.server.stop(true);
   }
   running.clear();
 }

package/src/net-guard.ts

@@ -21,6 +21,7 @@ import { realpathSync } from "node:fs";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import { problem } from "./problem.ts";
+import { fileResponse } from "./file-response.ts";
 
 export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
@@ -300,11 +301,7 @@ export async function serveContained(absPath: string, root: string): Promise<Res
   if (!safe) {
     return null;
   }
-  const file = Bun.file(safe);
-  if (await file.exists()) {
-    return new Response(file);
-  }
-  return null;
+  return fileResponse(safe);
 }
 
 /**