@jxsuite/server 0.1.0 → 0.5.1

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "packages/server"
+  },
   "files": [
     "src/"
   ],
@@ -10,6 +15,9 @@
   "exports": {
     ".": "./src/server.js"
   },
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "upgrade": "bunx npm-check-updates -u && bun install"
   },

package/src/server.js

@@ -1,13 +1,13 @@
 /**
  * @example
- *   import { createDevServer } from "@jxplatform/server";
+ *   import { createDevServer } from "@jxsuite/server";
  *
  *   await createDevServer({
  *   root: import.meta.dir,
  *   builds: [{ entrypoints: ["./src/app.js"], outdir: "./dist", match: /src/, label: "app" }],
  *   });
  *
- *   jxplatform/server — Jx development server
+ *   jxsuite/server — Jx development server
  *
  *   Provides builds, live reload, $src module proxying, timing: "server" function
  *   proxying, and studio filesystem integration as a single createDevServer() call.
@@ -27,7 +27,7 @@ import { existsSync, readFileSync } from "node:fs";
  * /pages/@scope/pkg/file → @scope/pkg/file).
  *
  * @param {string} root - Absolute project root
- * @param {string} urlPath - URL pathname (e.g. "/pages/@jxplatform/parser/Foo.class.json")
+ * @param {string} urlPath - URL pathname (e.g. "/pages/@jxsuite/parser/Foo.class.json")
  * @returns {string | null} Absolute file path or null
  */
 function resolveNpmPath(root, urlPath) {
@@ -141,7 +141,7 @@ export async function createDevServer(options) {
     middleware,
   } = options;
 
-  if (!root) throw new Error("@jxplatform/server: root is required");
+  if (!root) throw new Error("@jxsuite/server: root is required");
   const absRoot = resolve(root);
 
   // ─── Build pipeline ─────────────────────────────────────────────────────────
@@ -163,6 +163,10 @@ export async function createDevServer(options) {
   /** @type {Map<string, string>} */
   const bundleCache = new Map();
 
+  // Active studio project root (set via /__studio/activate, used for static file fallback)
+  /** @type {string | null} */
+  let activeProjectRoot = null;
+
   // ─── HTTP server ────────────────────────────────────────────────────────────
 
   const server = Bun.serve({
@@ -191,10 +195,19 @@ export async function createDevServer(options) {
 
       // Studio filesystem API
       if (enableStudio && path.startsWith("/__studio/")) {
+        // Activate project — tells the server which project root to use for static file fallback
+        if (path === "/__studio/activate" && req.method === "POST") {
+          const body = await req.json();
+          const raw = body.root || null;
+          // Always store as absolute path
+          activeProjectRoot = raw ? resolve(absRoot, raw) : null;
+          return Response.json({ ok: true, root: activeProjectRoot });
+        }
+
         const codeRes = await handleCodeApi(req, url);
         if (codeRes) return codeRes;
 
-        const res = await handleStudioApi(req, url, absRoot);
+        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot);
         if (res) return res;
       }
 
@@ -205,8 +218,32 @@ export async function createDevServer(options) {
       }
 
       // Static files
+
+      // If the URL path is an absolute filesystem path under the active project, serve directly.
+      // Browsers produce "//abs/path" when an absolute path is used as a URL path — normalise.
+      const fsPath = path.startsWith("//") ? path.slice(1) : path;
+      if (activeProjectRoot && fsPath.startsWith(activeProjectRoot)) {
+        const file = Bun.file(fsPath);
+        if (await file.exists()) {
+          return new Response(file);
+        }
+      }
+
       const file = Bun.file(resolve(absRoot, "." + path));
       if (!(await file.exists())) {
+        // Try resolving relative to active studio project root
+        if (activeProjectRoot) {
+          const projectFile = Bun.file(resolve(activeProjectRoot, "." + path));
+          if (await projectFile.exists()) {
+            return new Response(projectFile);
+          }
+          // Mirror production: public/ contents are served at root
+          const publicFile = Bun.file(resolve(activeProjectRoot, "public", "." + path));
+          if (await publicFile.exists()) {
+            return new Response(publicFile);
+          }
+        }
+
         // Resolve npm-style bare specifiers via node_modules.
         // Bundle on-demand so internal bare specifiers (e.g. lit/...) resolve.
         const resolved = resolveNpmPath(absRoot, path);
@@ -247,7 +284,7 @@ export async function createDevServer(options) {
     },
   });
 
-  console.log(`\n@jxplatform/server listening on http://localhost:${server.port}`);
+  console.log(`\n@jxsuite/server listening on http://localhost:${server.port}`);
 
   return server;
 }

package/src/studio-api.js

@@ -7,17 +7,29 @@
  * All paths are relative to the project root. Directory traversal above root is rejected.
  */
 
-import { resolve, relative, basename, dirname } from "node:path";
+import { resolve, relative, basename, dirname, isAbsolute } from "node:path";
 import { readdir, stat, readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { readFileSync, existsSync } from "node:fs";
 
+/** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
+const fwd = (/** @type {string} */ p) => p.replaceAll("\\", "/");
+
 /**
+ * Check that a path is under either the server root OR the active project root. This allows file
+ * operations on external projects that have been explicitly activated via /__studio/activate.
+ *
  * @param {string} filePath
  * @param {string} root
+ * @param {string | null} activeProjectRoot
  */
-function assertUnderRoot(filePath, root) {
+function assertAccessible(filePath, root, activeProjectRoot) {
   const rel = relative(root, filePath);
-  if (rel.startsWith("..") || rel.startsWith("/")) throw new Error("Path outside project root");
+  if (!rel.startsWith("..") && !rel.startsWith("/")) return;
+  if (activeProjectRoot) {
+    const relActive = relative(activeProjectRoot, filePath);
+    if (!relActive.startsWith("..") && !relActive.startsWith("/")) return;
+  }
+  throw new Error("Path outside project root");
 }
 
 /**
@@ -26,8 +38,9 @@ function assertUnderRoot(filePath, root) {
  * @param {Request} req
  * @param {URL} url
  * @param {string} root
+ * @param {string | null} [activeProjectRoot]
  */
-export async function handleStudioApi(req, url, root) {
+export async function handleStudioApi(req, url, root, activeProjectRoot = null) {
   const path = url.pathname;
 
   // Project metadata
@@ -46,15 +59,15 @@ export async function handleStudioApi(req, url, root) {
 
   // Project info — probe a directory for site-project characteristics
   if (path === "/__studio/project-info" && req.method === "GET") {
-    const dir = url.searchParams.get("dir") ?? ".";
-    const absDir = resolve(root, dir);
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const absDir = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
-      assertUnderRoot(absDir, root);
+      assertAccessible(absDir, root, activeProjectRoot);
     } catch (/** @type {any} */ e) {
       return Response.json({ error: e.message }, { status: 400 });
     }
     try {
-      const projectRoot = relative(root, absDir) || ".";
+      const projectRoot = fwd(absDir);
       const conventionalDirs = [
         "pages",
         "layouts",
@@ -97,19 +110,18 @@ export async function handleStudioApi(req, url, root) {
       let dir = dirname(
         filePath.startsWith("~") ? filePath.replace("~", process.env.HOME || "") : filePath,
       );
-      const stopAt = "/";
-      while (dir && dir !== stopAt) {
+      while (dir) {
         const candidate = resolve(dir, "project.json");
         if (existsSync(candidate)) {
           const config = JSON.parse(readFileSync(candidate, "utf8"));
-          const relPath = relative(root, dir);
+          const relPath = fwd(dir);
           const absFile = filePath.startsWith("~")
             ? filePath.replace("~", process.env.HOME || "")
             : filePath;
-          const fileRelPath = relative(dir, absFile);
+          const fileRelPath = fwd(relative(dir, absFile));
           return Response.json({
             sitePath: dir,
-            relPath: relPath || ".",
+            relPath: relPath,
             fileRelPath,
             projectConfig: config,
           });
@@ -124,19 +136,43 @@ export async function handleStudioApi(req, url, root) {
     }
   }
 
+  // Find a project directory by name — searches $HOME for the first matching directory with a
+  // project.json. Dev-mode workaround for when showDirectoryPicker() can't provide absolute paths.
+  if (path === "/__studio/find-project" && req.method === "GET") {
+    const name = url.searchParams.get("name");
+    if (!name) return Response.json({ error: "Missing name" }, { status: 400 });
+    try {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      if (!home) return Response.json({ path: null });
+      const glob = new Bun.Glob(`**/${name}/project.json`);
+      for await (const match of glob.scan({ cwd: home, dot: false })) {
+        if (match.includes("node_modules") || match.includes(".Trash")) continue;
+        const abs = resolve(home, dirname(match));
+        return Response.json({ path: abs });
+      }
+      return Response.json({ path: null });
+    } catch (/** @type {any} */ e) {
+      return Response.json({ error: e.message }, { status: 500 });
+    }
+  }
+
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
       const glob = new Bun.Glob("**/project.json");
       const sites = [];
       for await (const match of glob.scan({ cwd: root, dot: false })) {
-        if (match.includes("node_modules") || match.includes("dist/") || match.includes(".claude/"))
+        if (
+          match.includes("node_modules") ||
+          fwd(match).includes("dist/") ||
+          fwd(match).includes(".claude/")
+        )
           continue;
         const fp = resolve(root, match);
         try {
           const raw = JSON.parse(await readFile(fp, "utf8"));
           if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-            const projectDir = dirname(match) === "." ? "." : dirname(match).replaceAll("\\", "/");
+            const projectDir = fwd(dirname(fp));
             sites.push({ path: projectDir, config: raw });
           }
         } catch {}
@@ -149,15 +185,24 @@ export async function handleStudioApi(req, url, root) {
 
   // List files
   if (path === "/__studio/files" && req.method === "GET") {
-    const dir = url.searchParams.get("dir") ?? ".";
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
     const pattern = url.searchParams.get("glob");
-    const absDir = resolve(root, dir);
+    const absDir = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
-      assertUnderRoot(absDir, root);
+      assertAccessible(absDir, root, activeProjectRoot);
     } catch (/** @type {any} */ e) {
       return Response.json({ error: e.message }, { status: 400 });
     }
 
+    /** Report a path relative to the active project root (or server root as fallback). */
+    const reportRelative = (/** @type {string} */ fp) => {
+      if (activeProjectRoot) {
+        const rel = relative(activeProjectRoot, fp);
+        if (!rel.startsWith("..")) return fwd(rel);
+      }
+      return fwd(relative(root, fp));
+    };
+
     try {
       if (pattern) {
         const glob = new Bun.Glob(pattern);
@@ -169,7 +214,7 @@ export async function handleStudioApi(req, url, root) {
             if (!s.isDirectory()) {
               files.push({
                 name: basename(match),
-                path: relative(root, fp),
+                path: reportRelative(fp),
                 size: s.size,
                 modified: s.mtime.toISOString(),
               });
@@ -187,7 +232,7 @@ export async function handleStudioApi(req, url, root) {
         const s = await stat(fp);
         files.push({
           name: entry.name,
-          path: relative(root, fp),
+          path: reportRelative(fp),
           type: entry.isDirectory() ? "directory" : "file",
           size: s.size,
           modified: s.mtime.toISOString(),
@@ -201,36 +246,60 @@ export async function handleStudioApi(req, url, root) {
 
   // Component discovery — scan project for custom element definitions
   if (path === "/__studio/components" && req.method === "GET") {
-    const dir = url.searchParams.get("dir");
-    const scanRoot = dir ? resolve(root, dir) : root;
-    if (dir) {
-      try {
-        assertUnderRoot(scanRoot, root);
-      } catch (/** @type {any} */ e) {
-        return Response.json({ error: e.message }, { status: 400 });
-      }
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+    try {
+      assertAccessible(scanRoot, root, activeProjectRoot);
+    } catch (/** @type {any} */ e) {
+      return Response.json({ error: e.message }, { status: 400 });
     }
     try {
-      const glob = new Bun.Glob("**/*.json");
+      const glob = new Bun.Glob("**/*.{json,md}");
       const components = [];
       for await (const match of glob.scan({ cwd: scanRoot, dot: false })) {
-        if (match.includes("node_modules") || match.includes("dist/") || match.includes(".claude/"))
+        if (
+          match.includes("node_modules") ||
+          fwd(match).includes("dist/") ||
+          fwd(match).includes(".claude/")
+        )
           continue;
         const fp = resolve(scanRoot, match);
         try {
-          const content = JSON.parse(await readFile(fp, "utf8"));
+          /** @type {any} */
+          let content;
+          if (match.endsWith(".md")) {
+            // Parse YAML frontmatter to check for Jx component
+            const source = await readFile(fp, "utf8");
+            const fmMatch = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+            if (!fmMatch) continue;
+            // Quick check: must have tagName with hyphen
+            if (!/^tagName:\s*.+-.+/m.test(fmMatch[1])) continue;
+            const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
+            content = transpileJxMarkdown(source);
+          } else {
+            content = JSON.parse(await readFile(fp, "utf8"));
+          }
           if (content.tagName && content.tagName.includes("-")) {
             components.push({
               tagName: content.tagName,
               $id: content.$id || null,
-              path: match,
+              path: fwd(match),
               source: "jx",
               props: Object.entries(content.state || {})
-                .filter(
-                  ([, d]) =>
-                    d && typeof d === "object" && !d.$prototype && !d.$handler && !d.$compute,
-                )
-                .map(([name, d]) => ({ name, type: d.type, default: d.default })),
+                .filter(([, d]) => {
+                  if (d == null) return false;
+                  // Shorthand: "key": "value" or "key": 0 etc.
+                  if (typeof d !== "object") return true;
+                  // Full form: skip computed/handler/prototype entries
+                  return !d.$prototype && !d.$handler && !d.$compute;
+                })
+                .map(([name, d]) => {
+                  if (typeof d !== "object") {
+                    // Shorthand: infer type from value
+                    return { name, type: typeof d, default: d };
+                  }
+                  return { name, type: d.type, default: d.default };
+                }),
               hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
             });
           }
@@ -312,8 +381,8 @@ export async function handleStudioApi(req, url, root) {
 
   // List CEM-bearing npm packages
   if (path === "/__studio/packages" && req.method === "GET") {
-    const dir = url.searchParams.get("dir");
-    const scanRoot = dir ? resolve(root, dir) : root;
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
       const pkgPath = resolve(scanRoot, "package.json");
       if (!existsSync(pkgPath)) return Response.json([]);
@@ -350,8 +419,8 @@ export async function handleStudioApi(req, url, root) {
   if (path === "/__studio/cem" && req.method === "GET") {
     const pkg = url.searchParams.get("pkg");
     if (!pkg) return new Response("Missing pkg", { status: 400 });
-    const dir = url.searchParams.get("dir");
-    const scanRoot = dir ? resolve(root, dir) : root;
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
       const depPkgPath = resolve(scanRoot, "node_modules", ...pkg.split("/"), "package.json");
       const fallbackPath = resolve(root, "node_modules", ...pkg.split("/"), "package.json");
@@ -379,8 +448,8 @@ export async function handleStudioApi(req, url, root) {
       const name = body.name;
       if (!name || typeof name !== "string")
         return Response.json({ error: "Missing name" }, { status: 400 });
-      const dir = body.dir;
-      const cwd = dir ? resolve(root, dir) : root;
+      const dir = body.dir || activeProjectRoot;
+      const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
       const args = ["add", name];
       if (body.dev) args.splice(1, 0, "-d");
       const proc = Bun.spawn(["bun", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
@@ -405,8 +474,8 @@ export async function handleStudioApi(req, url, root) {
       const name = body.name;
       if (!name || typeof name !== "string")
         return Response.json({ error: "Missing name" }, { status: 400 });
-      const dir = body.dir;
-      const cwd = dir ? resolve(root, dir) : root;
+      const dir = body.dir || activeProjectRoot;
+      const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
       const proc = Bun.spawn(["bun", "remove", name], { cwd, stdout: "pipe", stderr: "pipe" });
       const exitCode = await proc.exited;
       if (exitCode !== 0) {
@@ -422,27 +491,20 @@ export async function handleStudioApi(req, url, root) {
     }
   }
 
-  // Read file (supports absolute system paths for ?open= workflow)
+  // Read file
   if (path === "/__studio/file" && req.method === "GET") {
     const fp = url.searchParams.get("path");
     if (!fp) return new Response("Missing path", { status: 400 });
-    const isAbsolute = fp.startsWith("/") || fp.startsWith("~");
-    const abs = isAbsolute
-      ? fp.startsWith("~")
-        ? fp.replace("~", process.env.HOME || "")
-        : fp
-      : resolve(root, fp);
-    if (!isAbsolute) {
-      try {
-        assertUnderRoot(abs, root);
-      } catch (/** @type {any} */ e) {
-        return new Response(e.message, { status: 400 });
-      }
+    const abs = fp.startsWith("~") ? fp.replace("~", process.env.HOME || "") : fp;
+    try {
+      assertAccessible(abs, root, activeProjectRoot);
+    } catch (/** @type {any} */ e) {
+      return new Response(e.message, { status: 400 });
     }
     try {
       return Response.json({
         content: await readFile(abs, "utf8"),
-        path: isAbsolute ? fp : relative(root, abs),
+        path: fp,
       });
     } catch (/** @type {any} */ e) {
       return e.code === "ENOENT"
@@ -457,14 +519,34 @@ export async function handleStudioApi(req, url, root) {
     if (!fp) return new Response("Missing path", { status: 400 });
     const abs = resolve(root, fp);
     try {
-      assertUnderRoot(abs, root);
+      assertAccessible(abs, root, activeProjectRoot);
     } catch (/** @type {any} */ e) {
       return new Response(e.message, { status: 400 });
     }
     try {
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, await req.text(), "utf8");
-      return Response.json({ ok: true, path: relative(root, abs) });
+      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
+    } catch (/** @type {any} */ e) {
+      return Response.json({ error: e.message }, { status: 500 });
+    }
+  }
+
+  // Upload binary file
+  if (path === "/__studio/file/upload" && req.method === "POST") {
+    const fp = url.searchParams.get("path");
+    if (!fp) return new Response("Missing path", { status: 400 });
+    const abs = resolve(root, fp);
+    try {
+      assertAccessible(abs, root, activeProjectRoot);
+    } catch (/** @type {any} */ e) {
+      return new Response(e.message, { status: 400 });
+    }
+    try {
+      await mkdir(dirname(abs), { recursive: true });
+      const buffer = await req.arrayBuffer();
+      await Bun.write(abs, new Uint8Array(buffer));
+      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
     } catch (/** @type {any} */ e) {
       return Response.json({ error: e.message }, { status: 500 });
     }
@@ -476,13 +558,13 @@ export async function handleStudioApi(req, url, root) {
     if (!fp) return new Response("Missing path", { status: 400 });
     const abs = resolve(root, fp);
     try {
-      assertUnderRoot(abs, root);
+      assertAccessible(abs, root, activeProjectRoot);
     } catch (/** @type {any} */ e) {
       return new Response(e.message, { status: 400 });
     }
     try {
       await unlink(abs);
-      return Response.json({ ok: true, path: relative(root, abs) });
+      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
     } catch (/** @type {any} */ e) {
       return e.code === "ENOENT"
         ? new Response("Not found", { status: 404 })
@@ -503,15 +585,19 @@ export async function handleStudioApi(req, url, root) {
     const absFrom = resolve(root, from);
     const absTo = resolve(root, to);
     try {
-      assertUnderRoot(absFrom, root);
-      assertUnderRoot(absTo, root);
+      assertAccessible(absFrom, root, activeProjectRoot);
+      assertAccessible(absTo, root, activeProjectRoot);
     } catch (/** @type {any} */ e) {
       return new Response(e.message, { status: 400 });
     }
     try {
       await mkdir(dirname(absTo), { recursive: true });
       await rename(absFrom, absTo);
-      return Response.json({ ok: true, from: relative(root, absFrom), to: relative(root, absTo) });
+      return Response.json({
+        ok: true,
+        from: fwd(relative(root, absFrom)),
+        to: fwd(relative(root, absTo)),
+      });
     } catch (/** @type {any} */ e) {
       return Response.json({ error: e.message }, { status: 500 });
     }
@@ -533,8 +619,8 @@ export async function handleStudioApi(req, url, root) {
       const matches = [];
       for await (const match of glob.scan({ cwd: root, dot: false })) {
         // Skip node_modules / dist / hidden dirs
-        if (match.includes("node_modules") || match.includes("dist/")) continue;
-        matches.push(match.split("\\").join("/"));
+        if (match.includes("node_modules") || fwd(match).includes("dist/")) continue;
+        matches.push(fwd(match));
       }
       if (matches.length === 0) return Response.json({ path: null });
       return Response.json({

package/src/watch.js

@@ -53,12 +53,13 @@ export function injectSSE(html) {
  *
  * @param {string} root - Absolute path to watch
  * @param {any[]} builds - Build entries (for selective rebuild)
- * @param {{ ignore?: string[]; debounce?: number }} [opts]
+ * @param {{ ignore?: string[]; debounce?: number; reloadOnAnyChange?: boolean }} [opts]
  * @returns {{ broadcast: () => void; handleSSE: () => Response }}
  */
 export function createWatcher(root, builds, opts = {}) {
   const ignore = opts.ignore ?? DEFAULT_IGNORE;
   const debounceMs = opts.debounce ?? 50;
+  const reloadOnAnyChange = opts.reloadOnAnyChange ?? false;
 
   /** @type {Set<(msg: string) => void>} */
   const clients = new Set();
@@ -126,7 +127,7 @@ export function createWatcher(root, builds, opts = {}) {
         }
       }
       console.log(`Changed  → ${filename}`);
-      broadcast();
+      if (reloadOnAnyChange) broadcast();
     }, debounceMs);
   });