@jxsuite/server 1.3.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -35,21 +35,21 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.5.1",
-    "@jxsuite/compiler": "^1.4.0",
-    "@jxsuite/create": "^1.2.1",
-    "@jxsuite/import": "^0.38.1",
-    "@jxsuite/protocol": "^0.6.1",
-    "@jxsuite/runtime": "^1.3.1",
-    "@jxsuite/schema": "^1.4.0",
-    "@jxsuite/starters": "^1.2.1",
+    "@jxsuite/collab": "^0.6.0",
+    "@jxsuite/compiler": "^1.5.0",
+    "@jxsuite/create": "^1.2.2",
+    "@jxsuite/import": "^0.38.2",
+    "@jxsuite/protocol": "^1.0.0",
+    "@jxsuite/runtime": "^1.3.2",
+    "@jxsuite/schema": "^1.5.0",
+    "@jxsuite/starters": "^1.2.2",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.4",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.4.1",
-    "@jxsuite/connector": "^0.4.1",
-    "@jxsuite/parser": "^1.4.0"
+    "@jxsuite/auth": "^0.4.2",
+    "@jxsuite/connector": "^0.4.2",
+    "@jxsuite/parser": "^1.4.1"
   }
 }

package/src/build.ts

@@ -1,5 +1,23 @@
 /** Build.js — Configurable Bun.build pipeline */
 
+import type { BuildConfig } from "bun";
+
+/**
+ * One watched build entry.
+ *
+ * `match` and `label` belong to the watcher; every other key is forwarded verbatim to `Bun.build`,
+ * so a consumer can supply `plugins`, `splitting`, `naming`, `define` and the rest. That forwarding
+ * was always the behaviour (the implementation spreads `...opts`) but was not in the type, so a
+ * caller had no way to know it could keep a watched rebuild byte-identical to its release build —
+ * and the repo's own dev server silently did not.
+ */
+export interface BuildEntry extends Partial<BuildConfig> {
+  entrypoints: string[];
+  outdir: string;
+  match?: ((path: string) => boolean) | RegExp;
+  label?: string;
+}
+
 /**
  * Build all entries with sensible defaults (browser target, ESM, linked sourcemaps).
  *
@@ -10,14 +28,7 @@
  *   label?: string;
  * }[]} builds
  */
-export async function buildAll(
-  builds: {
-    entrypoints: string[];
-    outdir: string;
-    match?: ((path: string) => boolean) | RegExp;
-    label?: string;
-  }[],
-) {
+export async function buildAll(builds: BuildEntry[]) {
   for (const entry of builds) {
     const { match: _match, label, ...opts } = entry;
     const result = await Bun.build({
@@ -48,15 +59,7 @@ export async function buildAll(
  * @param {string} changedFile
  * @returns {Promise<{ rebuilt: string[]; success: boolean }>}
  */
-export async function rebuild(
-  builds: {
-    entrypoints: string[];
-    outdir: string;
-    match?: ((path: string) => boolean) | RegExp;
-    label?: string;
-  }[],
-  changedFile: string,
-) {
+export async function rebuild(builds: BuildEntry[], changedFile: string) {
   const rebuilt = [];
   let ok = true;
   for (const entry of builds) {

package/src/server.ts

@@ -13,13 +13,18 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
-import { assertAccessible, handleStudioApi } from "./studio-api.ts";
+import {
+  assertAccessible,
+  assertCreatableParent,
+  handleStudioApi,
+  isOwnedProjectDir,
+} from "./studio-api.ts";
 import {
   containedPath,
   decodeAndNormalizePath,
@@ -217,6 +222,14 @@ export async function createDevServer(options: {
   }
   const absRoot = resolve(root);
 
+  /**
+   * Projects created through Studio's New Project modal, which land wherever the user pointed the
+   * Location field — normally outside `absRoot`. Remembering them lets the very next
+   * `/__studio/activate` open what was just created without widening the filesystem API to
+   * arbitrary directories.
+   */
+  const createdRoots: string[] = [];
+
   // ─── Build pipeline ─────────────────────────────────────────────────────────
 
   if (builds.length > 0) {
@@ -331,8 +344,10 @@ export async function createDevServer(options: {
         }
 
         // Activate project — tells the server which project root to use for static file fallback.
-        // Contain the requested root: it must be under absRoot or an explicitly allowed root, so a
-        // Hostile activate cannot widen the filesystem API to arbitrary directories.
+        // Contain the requested root: it must be under absRoot, an explicitly allowed root, a
+        // Project this server just created, or an existing project of the account's own
+        // (`isOwnedProjectDir`), so a hostile activate cannot widen the filesystem API to arbitrary
+        // Directories.
         if (path === "/__studio/activate" && req.method === "POST") {
           const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
@@ -343,7 +358,9 @@ export async function createDevServer(options: {
           const requested = resolve(absRoot, raw);
           const permitted =
             containedPath(requested, absRoot) !== null ||
-            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null);
+            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null) ||
+            createdRoots.some((created) => containedPath(requested, created) !== null) ||
+            isOwnedProjectDir(requested);
           if (!permitted) {
             return Response.json({ ok: false, error: "root not permitted" }, { status: 403 });
           }
@@ -357,14 +374,26 @@ export async function createDevServer(options: {
           return aiRes;
         }
 
-        // AI-guided site import (/__studio/import-site) — NDJSON progress stream
+        // AI-guided site import (/__studio/import-site) — NDJSON progress stream. An ABSOLUTE
+        // Directory is a destination the user chose in the New Project modal, so it is vetted the
+        // Same way a create is (specs/server.md §4.2). A RELATIVE one predates that field and stays
+        // Contained to the server root — resolving it there and then widening the check to the
+        // Creatable roots would let "../escape" out.
         const importRes = await handleImportApi(req, url, {
           resolveDest: (dir) => {
+            if (isAbsolute(dir)) {
+              assertCreatableParent(dirname(dir), absRoot, allowedRoots);
+              createdRoots.push(dir);
+              return dir;
+            }
             const dest = resolve(absRoot, dir);
             assertAccessible(dest, absRoot, activeProjectRoot);
             return dest;
           },
-          toRoot: (dest) => relative(absRoot, dest).replaceAll("\\", "/"),
+          toRoot: (dest) =>
+            containedPath(dest, absRoot) === null
+              ? dest
+              : relative(absRoot, dest).replaceAll("\\", "/"),
         });
         if (importRes) {
           return importRes;
@@ -375,7 +404,10 @@ export async function createDevServer(options: {
           return codeRes;
         }
 
-        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot);
+        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot, {
+          allowedRoots,
+          onProjectCreated: (created) => createdRoots.push(created),
+        });
         if (res) {
           return res;
         }

package/src/studio-api.ts

@@ -10,7 +10,9 @@
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
 import {
   buildExtensionsPayload,
   buildProjectExtensionRegistry,
@@ -175,6 +177,57 @@ export function assertAccessible(filePath: string, root: string, activeProjectRo
   throw new Error("Path outside project root");
 }
 
+/**
+ * Check that a NEW project may be scaffolded under `parent` (specs/server.md §4.2).
+ *
+ * Deliberately wider than {@link assertAccessible}: a new project is normally created _outside_ the
+ * server root — the whole point of the modal's Location field — so root containment cannot apply.
+ * What it still refuses is a destination the user did not name (relative paths) and anything
+ * outside the places a person keeps projects: the server root, any configured `allowedRoots`, and
+ * the account's home directory. That keeps a hostile page on the loopback origin from scaffolding
+ * into system paths while leaving every realistic location reachable.
+ *
+ * @param {string} parent
+ * @param {string} root
+ * @param {string[]} allowedRoots
+ */
+export function assertCreatableParent(parent: string, root: string, allowedRoots: string[] = []) {
+  if (!parent || !isAbsolute(parent)) {
+    throw new Error("Destination folder must be an absolute path");
+  }
+  const bases = [root, ...allowedRoots, homedir()].filter(Boolean);
+  if (bases.some((base) => containedPath(parent, resolve(base)) !== null)) {
+    return;
+  }
+  throw new Error(
+    "Destination folder is outside the permitted roots (the server root, an allowed root, or your home directory)",
+  );
+}
+
+/**
+ * True when `dir` is a Jx project this account already owns: an absolute directory holding a
+ * `project.json`, somewhere under the user's home directory (specs/server.md §4.2).
+ *
+ * Existing projects live outside the server root as a matter of course — the dev server serving
+ * this monorepo is not where anyone keeps their sites — so root containment alone would leave
+ * `?project=/abs/path`, the Open Project picker, and the recent-projects list unable to activate
+ * anything but a project inside the checkout. This admits those without opening the filesystem API
+ * to arbitrary directories: a hostile page on the loopback origin still cannot bind the server to
+ * `/etc` or another account's files, only to a project the account already has on disk.
+ *
+ * @param {string} dir
+ */
+export function isOwnedProjectDir(dir: string): boolean {
+  const home = homedir();
+  if (!home || !dir || !isAbsolute(dir)) {
+    return false;
+  }
+  if (containedPath(dir, resolve(home)) === null) {
+    return false;
+  }
+  return existsSync(resolve(dir, "project.json"));
+}
+
 const statusMap: Record<string, string> = {
   A: "A",
   C: "C",
@@ -253,6 +306,18 @@ export function parseGitStatus(out: string) {
   return { ahead, behind, branch, files };
 }
 
+/** Host hooks for the routes that reach outside the server root (project creation). */
+export interface StudioApiOptions {
+  /** Extra roots a new project may be created under, mirroring `createDevServer.allowedRoots`. */
+  allowedRoots?: string[];
+  /**
+   * Called with the absolute root of a project this API just created, so the host can permit a
+   * subsequent `/__studio/activate` on it — a project created outside the server root is otherwise
+   * unreachable by the very request that made it.
+   */
+  onProjectCreated?: (projectRoot: string) => void;
+}
+
 /**
  * Handle /__studio/* requests.
  *
@@ -260,6 +325,7 @@ export function parseGitStatus(out: string) {
  * @param {URL} url
  * @param {string} root
  * @param {string | null} [activeProjectRoot]
+ * @param {StudioApiOptions} [opts]
  * @returns {Promise<Response | null>}
  */
 export async function handleStudioApi(
@@ -267,6 +333,7 @@ export async function handleStudioApi(
   url: URL,
   root: string,
   activeProjectRoot: string | null = null,
+  opts: StudioApiOptions = {},
 ) {
   const path = url.pathname;
 
@@ -416,6 +483,74 @@ export async function handleStudioApi(
     }
   }
 
+  /*
+   * Recover the absolute path of a directory the browser picked with `showDirectoryPicker()`.
+   *
+   * A `FileSystemDirectoryHandle` exposes only `.name`, never a filesystem path (§8.2), and unlike
+   * /__studio/find-project there is no `project.json` to search for — the whole point is that the
+   * folder is empty. So the client tags the folder with a hidden LOCATION_ID_FILE holding a random
+   * id and asks us which directory carries that id.
+   *
+   * Identity lives in the file's CONTENTS, not its name: matching the id is exact where matching a
+   * path shape is only probable — two folders can share a basename, and a file left behind by a
+   * crashed session can still be on disk. A candidate whose contents do not equal `id` is skipped,
+   * so a stale tag can never redirect a create. The winning file is deleted here, the moment it has
+   * served its purpose, rather than being left for the client to tidy up.
+   */
+  if (path === "/__studio/locate-directory" && req.method === "GET") {
+    const name = url.searchParams.get("name");
+    const id = url.searchParams.get("id");
+    // `name` is interpolated into a glob; the id is only ever compared, never used as a pattern.
+    if (!name || !id || !/^[a-f0-9]{32}$/.test(id) || !/^[^/\\]+$/.test(name)) {
+      return Response.json({ error: "Missing or invalid name/id" }, { status: 400 });
+    }
+    try {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      if (!home) {
+        return Response.json({ path: null });
+      }
+      /** The tagged directory when this candidate holds our id, else null. */
+      const claim = (dir: string): string | null => {
+        const file = resolve(dir, LOCATION_ID_FILE);
+        try {
+          if (readFileSync(file, "utf8").trim() !== id) {
+            return null;
+          }
+        } catch {
+          return null;
+        }
+        try {
+          unlinkSync(file);
+        } catch {
+          // Read-only or already gone; the client's own cleanup is the backstop.
+        }
+        return dir;
+      };
+
+      // The home directory itself is a legitimate pick, and no `**/<name>/` glob can match it.
+      const atHome = claim(home);
+      if (atHome) {
+        return Response.json({ path: atHome });
+      }
+      // `dot: true` — the tag is a dotfile, so a dot-blind scan would never see it.
+      const glob = new Bun.Glob(`**/${name}/${LOCATION_ID_FILE}`);
+      try {
+        for await (const match of glob.scan({ cwd: home, dot: true })) {
+          if (match.includes("node_modules") || match.includes(".Trash")) {
+            continue;
+          }
+          const claimed = claim(resolve(home, dirname(match)));
+          if (claimed) {
+            return Response.json({ path: claimed });
+          }
+        }
+      } catch {}
+      return Response.json({ path: null });
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
@@ -453,6 +588,7 @@ export async function handleStudioApi(
         url?: string;
         adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
         directory?: string;
+        destination?: { kind?: string; parent?: string };
         starter?: string;
         template?: string;
         design?: DesignOptions;
@@ -463,6 +599,7 @@ export async function handleStudioApi(
         url: siteUrl,
         adapter,
         directory,
+        destination,
         starter,
         template,
         design,
@@ -470,12 +607,32 @@ export async function handleStudioApi(
       if (!name || !directory) {
         return Response.json({ error: "name and directory are required" }, { status: 400 });
       }
+      // The destination is the user's to choose (specs/server.md §4.2). Without one the project
+      // Would silently land under the server root — which, when the dev server is the jx checkout,
+      // Means scaffolding into the monorepo. Refuse instead of guessing.
+      if (destination?.kind !== "path" || !destination.parent) {
+        return Response.json({ error: "A destination folder is required." }, { status: 400 });
+      }
+      // `directory` names the project FOLDER, not a path: a separator or dot-segment would walk out
+      // Of the parent that was just vetted below, which is exactly what the vetting is for.
+      if (/[/\\]/.test(directory) || directory === "." || directory === "..") {
+        return Response.json(
+          { error: "Directory must be a folder name, not a path" },
+          { status: 400 },
+        );
+      }
       const { isTemplateId } = await import("@jxsuite/create/templates");
       if (template !== undefined && !isTemplateId(template)) {
         return Response.json({ error: `Unknown template: "${template}"` }, { status: 400 });
       }
-      const destPath = resolve(root, directory);
-      assertAccessible(destPath, root, activeProjectRoot);
+      // A bad destination is client input, so answer 400 rather than letting the guard's throw fall
+      // Through to the catch-all 500 below.
+      try {
+        assertCreatableParent(destination.parent, root, opts.allowedRoots);
+      } catch (error) {
+        return Response.json({ error: errorMessage(error) }, { status: 400 });
+      }
+      const destPath = resolve(destination.parent, directory);
 
       const { generateProject } = await import("@jxsuite/create/generate");
       await generateProject(destPath, {
@@ -491,8 +648,12 @@ export async function handleStudioApi(
       const config = JSON.parse(
         await readFile(resolve(destPath, "project.json"), "utf8"),
       ) as ProjectConfig;
-      const projectRoot = fwd(relative(root, destPath));
-      return Response.json({ config, root: projectRoot });
+      // Root-relative while the project happens to sit under the server root (the historical
+      // Shape every caller already handles); absolute otherwise, which is the same shape
+      // /__studio/find-project returns for an external project.
+      const inRoot = containedPath(destPath, root) !== null;
+      opts.onProjectCreated?.(destPath);
+      return Response.json({ config, root: inRoot ? fwd(relative(root, destPath)) : destPath });
     } catch (error) {
       return Response.json({ error: errorMessage(error) }, { status: 500 });
     }