@jxsuite/server 0.10.2 → 0.11.0

package/README.md

@@ -0,0 +1,80 @@
+# `@jxsuite/server`
+
+> Bun-native development server for Jx projects with live reload, proxy resolution, and Studio API.
+
+## Overview
+
+`@jxsuite/server` provides a single `createDevServer()` call that covers live reload, `$src`/`$prototype` proxy resolution (Node.js-side), `timing: "server"` function execution, a Studio filesystem API, and OXC-powered code services.
+
+## Installation
+
+```bash
+bun add @jxsuite/server
+```
+
+## Usage
+
+```js
+import { createDevServer } from "@jxsuite/server";
+
+await createDevServer({
+  root: "./my-project",
+  port: 3000,
+  builds: [{ entrypoints: ["./index.html"], outdir: "./dist", label: "app" }],
+});
+```
+
+## Endpoints
+
+### Live reload — `GET /__reload`
+
+SSE endpoint. `chokidar` watches the project root and pushes change events to connected browsers, triggering automatic page reload.
+
+### `$prototype`/`$src` proxy — `POST /__jx_resolve__`
+
+Resolves external `$prototype` data sources server-side. Supports `.js` modules and `.class.json` schemas. Avoids browser CORS issues and enables Node.js-only dependencies (`fs`, `glob`, etc.).
+
+### Server functions — `POST /__jx_server__`
+
+Executes `timing: "server"` function entries during development. The runtime sends `{ $src, $export, arguments }` and receives the return value as JSON.
+
+### Studio filesystem API — `/__studio/*`
+
+REST API for the Studio visual builder:
+
+| Method         | Path                    | Description                |
+| -------------- | ----------------------- | -------------------------- |
+| GET            | `/__studio/project`     | Project metadata           |
+| GET            | `/__studio/files`       | Directory listing          |
+| GET/PUT/DELETE | `/__studio/file`        | Read / write / delete file |
+| POST           | `/__studio/file/rename` | Rename or move file        |
+| GET            | `/__studio/components`  | Discover custom elements   |
+| GET            | `/__studio/search`      | Search file contents       |
+
+All file operations are constrained to the project root (path traversal is rejected).
+
+### Code services — `/__studio/code/*`
+
+OXC-powered tools for the Studio function body editor:
+
+| Endpoint                     | Tool             | Description         |
+| ---------------------------- | ---------------- | ------------------- |
+| `POST /__studio/code/format` | oxfmt            | Format a JS snippet |
+| `POST /__studio/code/minify` | `Bun.Transpiler` | Minify a JS snippet |
+| `POST /__studio/code/lint`   | oxlint           | Lint a JS snippet   |
+
+## Build pipeline
+
+`buildAll(options)` uses `Bun.build` to bundle entrypoints. Incremental rebuilds (`rebuild(changedPath)`) are triggered by the file watcher and reprocess only affected entrypoints.
+
+## Dependencies
+
+| Package    | Purpose                       |
+| ---------- | ----------------------------- |
+| `chokidar` | File watching for live reload |
+
+Bun built-ins used: `Bun.serve`, `Bun.build`, `Bun.Transpiler`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {

package/src/server.js

@@ -113,6 +113,8 @@ function resolveNpmPath(root, urlPath) {
   return null;
 }
 
+export { resolveNpmPath };
+
 /**
  * Create and start a Jx development server.
  *

package/src/studio-api.js

@@ -10,6 +10,7 @@
 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";
+import { transpileJxMarkdown } from "@jxsuite/parser/transpile";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (/** @type {string} */ p) => p.replaceAll("\\", "/");
@@ -325,13 +326,10 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
           /** @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"));

package/src/watch.js

@@ -40,6 +40,8 @@ function shouldIgnore(pathname, ignore) {
   });
 }
 
+export { shouldIgnore };
+
 export const SSE_SCRIPT = `\n<script>new EventSource('/__reload').onmessage=()=>location.reload()</script>`;
 
 /** @param {string} html */
@@ -55,7 +57,11 @@ export function injectSSE(html) {
  * @param {string} root - Absolute path to watch
  * @param {any[]} builds - Build entries (for selective rebuild)
  * @param {{ ignore?: string[]; debounce?: number; reloadOnAnyChange?: boolean }} [opts]
- * @returns {{ broadcast: () => void; handleSSE: () => Response }}
+ * @returns {{
+ *   broadcast: () => void;
+ *   handleSSE: () => Response;
+ *   watcher: import("chokidar").FSWatcher;
+ * }}
  */
 export function createWatcher(root, builds, opts = {}) {
   const ignore = opts.ignore ?? DEFAULT_IGNORE;
@@ -132,5 +138,5 @@ export function createWatcher(root, builds, opts = {}) {
     }, debounceMs);
   });
 
-  return { broadcast, handleSSE };
+  return { broadcast, handleSSE, watcher };
 }