@jxsuite/server 0.0.1

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@jxsuite/server",
+  "version": "0.0.1",
+  "description": "Jx development server with live reload, server-side proxy, and studio integration",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "scripts": {
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0"
+  }
+}

package/src/build.js

@@ -0,0 +1,67 @@
+/** Build.js — Configurable Bun.build pipeline */
+
+/**
+ * Build all entries with sensible defaults (browser target, ESM, linked sourcemaps).
+ *
+ * @param {{
+ *   entrypoints: string[];
+ *   outdir: string;
+ *   match?: Function | RegExp;
+ *   label?: string;
+ * }[]} builds
+ */
+export async function buildAll(builds) {
+  for (const entry of builds) {
+    const { match: _match, label, ...opts } = entry;
+    const result = await Bun.build({
+      target: "browser",
+      format: "esm",
+      sourcemap: "linked",
+      ...opts,
+    });
+    if (!result.success) result.logs.forEach((l) => console.error(l));
+    else console.log(`Built → ${entry.outdir}/${label ?? "bundle"}.js`);
+  }
+}
+
+/**
+ * Rebuild entries whose match function/regex matches the changed filename.
+ *
+ * @param {{
+ *   entrypoints: string[];
+ *   outdir: string;
+ *   match?: Function | RegExp;
+ *   label?: string;
+ * }[]} builds
+ * @param {string} changedFile
+ * @returns {Promise<{ rebuilt: string[]; success: boolean }>}
+ */
+export async function rebuild(builds, changedFile) {
+  const rebuilt = [];
+  let ok = true;
+  for (const entry of builds) {
+    if (!entry.match) continue;
+    const matches =
+      typeof entry.match === "function"
+        ? entry.match(changedFile)
+        : entry.match instanceof RegExp
+          ? entry.match.test(changedFile)
+          : false;
+    if (!matches) continue;
+    const { match: _match, label, ...opts } = entry;
+    const result = await Bun.build({
+      target: "browser",
+      format: "esm",
+      sourcemap: "linked",
+      ...opts,
+    });
+    if (result.success) {
+      rebuilt.push(label ?? entry.outdir);
+      console.log(`Rebuilt  → ${entry.outdir}/${label ?? "bundle"}.js  (${changedFile} changed)`);
+    } else {
+      result.logs.forEach((l) => console.error(l));
+      ok = false;
+    }
+  }
+  return { rebuilt, success: ok };
+}

package/src/code-api.js

@@ -0,0 +1,155 @@
+/**
+ * Code-api.js — OXC-powered code services for the studio function editor
+ *
+ * Endpoints under /__studio/code/* that provide formatting (oxfmt), minification (Bun.Transpiler),
+ * and linting (oxlint CLI) for JS snippets.
+ */
+
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { unlink } from "node:fs/promises";
+import { format } from "oxfmt";
+
+const OXLINT_BIN = resolve(
+  import.meta.dir,
+  "../../node_modules/.bin",
+  process.platform === "win32" ? "oxlint.exe" : "oxlint",
+);
+
+// ─── Wrapper utilities ───────────────────────────────────────────────────────
+
+/**
+ * @param {string} body
+ * @param {string[]} [args]
+ */
+function wrapBody(body, args = ["state", "event"]) {
+  const params = args.join(", ");
+  return `function __jx_fn__(${params}) {\n${body}\n}`;
+}
+
+/** @param {string} formatted */
+function unwrapFormatted(formatted) {
+  const lines = formatted.split("\n");
+  // Remove first line (function header) and last non-empty line (closing brace)
+  let end = lines.length - 1;
+  while (end > 0 && lines[end].trim() === "") end--;
+  if (lines[end].trim() === "}") end--;
+  const bodyLines = lines.slice(1, end + 1);
+  // Dedent by one tab (oxfmt uses the project's indentStyle)
+  return bodyLines.map((l) => (l.startsWith("\t") ? l.slice(1) : l)).join("\n");
+}
+
+/**
+ * @param {any[]} diagnostics
+ * @param {number} headerLen
+ */
+function adjustDiagnostics(diagnostics, headerLen) {
+  return diagnostics
+    .filter((d) => {
+      const line = d.labels?.[0]?.span?.line;
+      return line == null || line > 1;
+    })
+    .map((d) => ({
+      ...d,
+      labels: d.labels.map((/** @type {any} */ label) => ({
+        ...label,
+        span: {
+          ...label.span,
+          offset: label.span.offset - headerLen,
+          line: label.span.line - 1,
+        },
+      })),
+    }));
+}
+
+// ─── Reusable transpiler ─────────────────────────────────────────────────────
+
+const minifier = new Bun.Transpiler({ minifyWhitespace: true });
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+/**
+ * @param {Request} req
+ * @param {URL} url
+ */
+export async function handleCodeApi(req, url) {
+  const path = url.pathname;
+  if (!path.startsWith("/__studio/code/") || req.method !== "POST") return null;
+
+  let body;
+  try {
+    body = await req.json();
+  } catch {
+    return new Response("Invalid JSON", { status: 400 });
+  }
+
+  const action = path.slice("/__studio/code/".length);
+
+  // ── Format ─────────────────────────────────────────────────────────────────
+
+  if (action === "format") {
+    const { code, args } = body;
+    if (!code?.trim()) return Response.json({ code: "", errors: [] });
+
+    try {
+      const wrapped = wrapBody(code, args);
+      const result = await format("fn.js", wrapped, { useTabs: true });
+      return Response.json({
+        code: unwrapFormatted(result.code),
+        errors: result.errors,
+      });
+    } catch (/** @type {any} */ e) {
+      return Response.json({ code, errors: [{ message: e.message }] });
+    }
+  }
+
+  // ── Minify ─────────────────────────────────────────────────────────────────
+
+  if (action === "minify") {
+    const { code } = body;
+    if (!code?.trim()) return Response.json({ code: "" });
+
+    try {
+      const minified = minifier.transformSync(code).trim();
+      return Response.json({ code: minified });
+    } catch (/** @type {any} */ e) {
+      return Response.json({ code, error: e.message });
+    }
+  }
+
+  // ── Lint ───────────────────────────────────────────────────────────────────
+
+  if (action === "lint") {
+    const { code, args } = body;
+    if (!code?.trim()) return Response.json({ diagnostics: [] });
+
+    const wrapped = wrapBody(code, args);
+    const headerLen = wrapped.indexOf("\n") + 1;
+    const tmpFile = join(
+      tmpdir(),
+      `__jx_lint_${Date.now()}_${Math.random().toString(36).slice(2)}.js`,
+    );
+
+    try {
+      await Bun.write(tmpFile, wrapped);
+      const proc = Bun.spawn([OXLINT_BIN, "--format=json", "-A", "no-unused-vars", tmpFile], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const output = await new Response(proc.stdout).text();
+      await proc.exited;
+
+      const parsed = JSON.parse(output);
+      const adjusted = adjustDiagnostics(parsed.diagnostics || [], headerLen);
+      return Response.json({ diagnostics: adjusted });
+    } catch (/** @type {any} */ e) {
+      return Response.json({ diagnostics: [], error: e.message });
+    } finally {
+      try {
+        await unlink(tmpFile);
+      } catch {}
+    }
+  }
+
+  return null;
+}

package/src/resolve.js

@@ -0,0 +1,206 @@
+/** Resolve.js — Generic $src module proxy + timing: "server" function proxy */
+
+import { resolve, relative, dirname } from "node:path";
+import { readFileSync } from "node:fs";
+
+/**
+ * Handle POST /**jx_resolve** — proxy $prototype + $src entries.
+ *
+ * @param {Request} req
+ * @param {string} root
+ */
+export async function handleResolve(req, root) {
+  let body;
+  try {
+    body = await req.json();
+  } catch {
+    return new Response("Invalid JSON body", { status: 400 });
+  }
+
+  const { $src, $prototype, $export: xport, $base, ...config } = body;
+  if (!$src) return new Response("Missing $src", { status: 400 });
+
+  let moduleAbsPath;
+  try {
+    if ($base) {
+      const docUrlPath = new URL($base).pathname;
+      const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
+      moduleAbsPath = resolve(resolve(root, "." + docDir), $src);
+    } else {
+      moduleAbsPath = resolve(root, $src);
+    }
+  } catch (/** @type {any} */ e) {
+    return new Response(`Cannot resolve $src "${$src}": ${e.message}`, { status: 400 });
+  }
+
+  // Rebase relative config paths from doc-relative to CWD-relative
+  if ($base) {
+    const docUrlPath = new URL($base).pathname;
+    const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
+    const docAbsDir = resolve(root, "." + docDir);
+    for (const [k, v] of Object.entries(config)) {
+      if (typeof v === "string" && (v.startsWith("./") || v.startsWith("../"))) {
+        config[k] = "./" + relative(process.cwd(), resolve(docAbsDir, v));
+      }
+    }
+  }
+
+  // .class.json: read schema, follow $implementation to the real JS module
+  if (moduleAbsPath.endsWith(".class.json")) {
+    try {
+      const content = readFileSync(moduleAbsPath, "utf8");
+      const classDef = JSON.parse(content);
+
+      if (classDef.$implementation) {
+        // Hybrid mode: redirect to the JS implementation
+        const implPath = resolve(dirname(moduleAbsPath), classDef.$implementation);
+        const exportName = xport ?? classDef.title ?? $prototype;
+        const mod = await import(implPath);
+        const ExportedClass = mod[exportName] ?? mod.default?.[exportName];
+        if (typeof ExportedClass !== "function") {
+          return new Response(`Export "${exportName}" not found in "${classDef.$implementation}"`, {
+            status: 500,
+          });
+        }
+        const instance = new ExportedClass(config);
+        const value =
+          typeof instance.resolve === "function"
+            ? await instance.resolve()
+            : "value" in instance
+              ? instance.value
+              : instance;
+        return Response.json(value);
+      }
+
+      // Self-contained: construct class from schema
+      const DynClass = classFromSchema(classDef);
+      const instance = /** @type {any} */ (new DynClass(config));
+      const value =
+        typeof instance.resolve === "function"
+          ? await instance.resolve()
+          : "value" in instance
+            ? instance.value
+            : instance;
+      return Response.json(value);
+    } catch (/** @type {any} */ e) {
+      return Response.json({ error: e.message }, { status: 500 });
+    }
+  }
+
+  // Non-Function $prototype must use .class.json as entrypoint
+  return new Response(
+    `Non-Function $prototype "${$prototype}" requires a .class.json $src, got "${$src}". ` +
+      `Wrap the class in a .class.json schema with $implementation.`,
+    { status: 400 },
+  );
+}
+
+/**
+ * Handle POST /**jx_server** — proxy timing: "server" function calls. In dev mode, the runtime
+ * sends these instead of hitting the production Hono handler.
+ *
+ * @param {Request} req
+ * @param {string} root
+ */
+export async function handleServerFunction(req, root) {
+  let body;
+  try {
+    body = await req.json();
+  } catch {
+    return new Response("Invalid JSON body", { status: 400 });
+  }
+
+  const { $src, $export: xport, $base, arguments: args = {} } = body;
+  if (!$src || !xport) return new Response("Missing $src or $export", { status: 400 });
+
+  let moduleAbsPath;
+  try {
+    if ($base) {
+      const docUrlPath = new URL($base).pathname;
+      const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
+      moduleAbsPath = resolve(resolve(root, "." + docDir), $src);
+    } else {
+      moduleAbsPath = resolve(root, $src);
+    }
+  } catch (/** @type {any} */ e) {
+    return new Response(`Cannot resolve $src: ${e.message}`, { status: 400 });
+  }
+
+  let mod;
+  try {
+    mod = await import(moduleAbsPath);
+  } catch (/** @type {any} */ e) {
+    return new Response(`Failed to import "${$src}": ${e.message}`, { status: 500 });
+  }
+
+  const fn = mod[xport] ?? mod.default?.[xport];
+  if (typeof fn !== "function") {
+    return new Response(`Export "${xport}" not found in "${$src}"`, { status: 500 });
+  }
+
+  try {
+    const result = await fn(args);
+    return Response.json(result ?? null);
+  } catch (/** @type {any} */ e) {
+    return Response.json({ error: e.message }, { status: 500 });
+  }
+}
+
+/**
+ * Dynamically construct a class from a .class.json schema definition. Server-side variant — no
+ * private field limitations.
+ *
+ * @param {any} classDef
+ */
+function classFromSchema(classDef) {
+  const fields = classDef.$defs?.fields ?? {};
+  const ctor = classDef.$defs?.constructor;
+  const methods = classDef.$defs?.methods ?? {};
+
+  class DynClass {
+    constructor(config = {}) {
+      const self = /** @type {any} */ (this);
+      const cfg = /** @type {Record<string, any>} */ (config);
+      for (const [key, field] of Object.entries(fields)) {
+        const id = field.identifier ?? key;
+        if (cfg[id] !== undefined) self[id] = cfg[id];
+        else if (field.initializer !== undefined) self[id] = field.initializer;
+        else if (field.default !== undefined) self[id] = structuredClone(field.default);
+        else self[id] = null;
+      }
+      if (ctor?.body) {
+        const bodyStr = Array.isArray(ctor.body) ? ctor.body.join("\n") : ctor.body;
+        new Function("config", bodyStr).call(this, config);
+      }
+    }
+  }
+
+  for (const [key, method] of Object.entries(methods)) {
+    const name = method.identifier ?? key;
+    const params = (method.parameters ?? []).map((/** @type {any} */ p) => {
+      if (p.$ref) return p.$ref.split("/").pop();
+      return p.identifier ?? p.name ?? "arg";
+    });
+    const bodyStr = Array.isArray(method.body) ? method.body.join("\n") : (method.body ?? "");
+
+    if (method.role === "accessor") {
+      /** @type {any} */
+      const descriptor = {};
+      if (method.getter) descriptor.get = new Function(method.getter.body);
+      if (method.setter) {
+        const sp = (method.setter.parameters ?? []).map(
+          (/** @type {any} */ p) => p.$ref?.split("/").pop() ?? "v",
+        );
+        descriptor.set = new Function(...sp, method.setter.body);
+      }
+      Object.defineProperty(DynClass.prototype, name, { ...descriptor, configurable: true });
+    } else if (method.scope === "static") {
+      /** @type {any} */ (DynClass)[name] = new Function(...params, bodyStr);
+    } else {
+      /** @type {any} */ (DynClass.prototype)[name] = new Function(...params, bodyStr);
+    }
+  }
+
+  Object.defineProperty(DynClass, "name", { value: classDef.title, configurable: true });
+  return DynClass;
+}

package/src/server.js

@@ -0,0 +1,253 @@
+/**
+ * @example
+ *   import { createDevServer } from "@jxplatform/server";
+ *
+ *   await createDevServer({
+ *   root: import.meta.dir,
+ *   builds: [{ entrypoints: ["./src/app.js"], outdir: "./dist", match: /src/, label: "app" }],
+ *   });
+ *
+ *   jxplatform/server — Jx development server
+ *
+ *   Provides builds, live reload, $src module proxying, timing: "server" function
+ *   proxying, and studio filesystem integration as a single createDevServer() call.
+ */
+
+import { resolve, join } from "node:path";
+import { buildAll } from "./build.js";
+import { createWatcher, injectSSE } from "./watch.js";
+import { handleResolve, handleServerFunction } from "./resolve.js";
+import { handleStudioApi } from "./studio-api.js";
+import { handleCodeApi } from "./code-api.js";
+import { existsSync, readFileSync } from "node:fs";
+
+/**
+ * Resolve an npm-style bare specifier from a URL path via node_modules. Handles scoped packages
+ * (@scope/pkg/subpath) and respects package.json exports. Strips leading directory segments (e.g.
+ * /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")
+ * @returns {string | null} Absolute file path or null
+ */
+function resolveNpmPath(root, urlPath) {
+  let segments = urlPath.split("/").filter(Boolean);
+
+  // If "node_modules" appears in the path, use everything before it as a subdirectory
+  // prefix and everything after as the package specifier.
+  // e.g. /examples/demo/node_modules/@scope/pkg → root=root/examples/demo, pkg=@scope/pkg
+  const nmIdx = segments.indexOf("node_modules");
+  if (nmIdx >= 0) {
+    if (nmIdx > 0) root = join(root, ...segments.slice(0, nmIdx));
+    segments = segments.slice(nmIdx + 1);
+  }
+
+  // Find the package start — either @scope/pkg or unscoped pkg
+  let start = -1;
+  let isScoped = false;
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i].startsWith("@")) {
+      start = i;
+      isScoped = true;
+      break;
+    }
+  }
+
+  /** @type {string} */
+  let pkgDir = "";
+  /** @type {string} */
+  let subpath = "";
+
+  if (isScoped) {
+    if (start < 0 || start + 1 >= segments.length) return null;
+    const scope = segments[start];
+    const pkg = segments[start + 1];
+    subpath = segments.slice(start + 2).join("/");
+    pkgDir = join(root, "node_modules", scope, pkg);
+  } else {
+    // Unscoped: try each segment as a package name in node_modules
+    for (let i = 0; i < segments.length; i++) {
+      const candidate = join(root, "node_modules", segments[i]);
+      if (existsSync(join(candidate, "package.json"))) {
+        start = i;
+        pkgDir = candidate;
+        subpath = segments.slice(i + 1).join("/");
+        break;
+      }
+    }
+    if (start < 0) return null;
+  }
+
+  const pkgJsonPath = join(pkgDir, "package.json");
+  if (!existsSync(pkgJsonPath)) return null;
+
+  // If there's a subpath, check package.json exports first
+  if (subpath) {
+    try {
+      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+      const exportKey = `./${subpath}`;
+      if (pkgJson.exports && pkgJson.exports[exportKey]) {
+        const mapped = join(pkgDir, pkgJson.exports[exportKey]);
+        if (existsSync(mapped)) return mapped;
+      }
+    } catch {}
+    // Fall back to direct path
+    const direct = join(pkgDir, subpath);
+    if (existsSync(direct)) return direct;
+  }
+
+  // Bare package (no subpath): resolve entry point
+  try {
+    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    const exp = pkgJson.exports?.["."];
+    const entry =
+      (typeof exp === "object" ? (exp.import ?? exp.default) : exp) ??
+      pkgJson.module ??
+      pkgJson.main;
+    if (entry && typeof entry === "string") {
+      const resolved = join(pkgDir, entry);
+      if (existsSync(resolved)) return resolved;
+    }
+  } catch {}
+
+  return null;
+}
+
+/**
+ * Create and start a Jx development server.
+ *
+ * @param {object} options
+ * @param {string} options.root - Project root (absolute or relative)
+ * @param {number} [options.port] - Server port. Default is `3000`
+ * @param {{
+ *   entrypoints: string[];
+ *   outdir: string;
+ *   match?: Function | RegExp;
+ *   label?: string;
+ * }[]} [options.builds]
+ *   - Bun.build entries with optional match regex
+ * @param {boolean | object} [options.watch] - Watch config or false to disable. Default is `true`
+ * @param {boolean} [options.studio] - Enable /**studio/* endpoints. Default is `true`
+ * @param {Function} [options.middleware] - Custom route handler (req, url) => Response|null
+ * @returns {Promise<object>} The Bun.serve server object
+ */
+export async function createDevServer(options) {
+  const {
+    root,
+    port = 3000,
+    builds = [],
+    watch = true,
+    studio: enableStudio = true,
+    middleware,
+  } = options;
+
+  if (!root) throw new Error("@jxplatform/server: root is required");
+  const absRoot = resolve(root);
+
+  // ─── Build pipeline ─────────────────────────────────────────────────────────
+
+  if (builds.length > 0) {
+    await buildAll(builds);
+  }
+
+  // ─── File watcher + SSE ─────────────────────────────────────────────────────
+
+  let handleSSE = null;
+  if (watch !== false) {
+    const watchOpts = typeof watch === "object" ? watch : {};
+    const watcher = createWatcher(absRoot, builds, watchOpts);
+    handleSSE = watcher.handleSSE;
+  }
+
+  // Bundle cache for npm packages (bare specifier → bundled JS)
+  /** @type {Map<string, string>} */
+  const bundleCache = new Map();
+
+  // ─── HTTP server ────────────────────────────────────────────────────────────
+
+  const server = Bun.serve({
+    port,
+
+    async fetch(req) {
+      const url = new URL(req.url);
+      let path = url.pathname;
+      if (path.endsWith("/")) path += "index.html";
+      else if (path === "") path = "/index.html";
+
+      // SSE live reload
+      if (handleSSE && path === "/__reload") {
+        return handleSSE();
+      }
+
+      // $prototype + $src proxy
+      if (path === "/__jx_resolve__" && req.method === "POST") {
+        return handleResolve(req, absRoot);
+      }
+
+      // timing: "server" function proxy
+      if (path === "/__jx_server__" && req.method === "POST") {
+        return handleServerFunction(req, absRoot);
+      }
+
+      // Studio filesystem API
+      if (enableStudio && path.startsWith("/__studio/")) {
+        const codeRes = await handleCodeApi(req, url);
+        if (codeRes) return codeRes;
+
+        const res = await handleStudioApi(req, url, absRoot);
+        if (res) return res;
+      }
+
+      // Custom middleware
+      if (middleware) {
+        const res = await middleware(req, url);
+        if (res) return res;
+      }
+
+      // Static files
+      const file = Bun.file(resolve(absRoot, "." + path));
+      if (!(await file.exists())) {
+        // Resolve npm-style bare specifiers via node_modules.
+        // Bundle on-demand so internal bare specifiers (e.g. lit/...) resolve.
+        const resolved = resolveNpmPath(absRoot, path);
+        if (resolved) {
+          const cacheKey = resolved;
+          if (!bundleCache.has(cacheKey)) {
+            try {
+              const result = await Bun.build({
+                entrypoints: [resolved],
+                format: "esm",
+                minify: false,
+              });
+              if (result.success && result.outputs.length > 0) {
+                bundleCache.set(cacheKey, await result.outputs[0].text());
+              }
+            } catch (/** @type {any} */ e) {
+              console.error("Bundle failed for", resolved, e);
+            }
+          }
+          const bundled = bundleCache.get(cacheKey);
+          if (bundled) {
+            return new Response(bundled, {
+              headers: { "Content-Type": "application/javascript; charset=utf-8" },
+            });
+          }
+        }
+        return new Response("Not found", { status: 404 });
+      }
+
+      if (handleSSE && path.endsWith(".html")) {
+        const html = await file.text();
+        return new Response(injectSSE(html), {
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+
+      return new Response(file);
+    },
+  });
+
+  console.log(`\n@jxplatform/server listening on http://localhost:${server.port}`);
+
+  return server;
+}