@jxsuite/server 0.23.1 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -13,8 +13,9 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/server.js",
-    "./claude-session": "./src/claude-session.js"
+    ".": "./src/server.ts",
+    "./claude-session": "./src/claude-session.ts",
+    "./types": "./src/types.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -25,11 +26,13 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.160",
     "@anthropic-ai/sdk": "^0.100.1",
-    "@jxsuite/compiler": "^0.23.1",
+    "@jxsuite/compiler": "^0.24.0",
     "@jxsuite/create": "^0.19.0",
-    "@jxsuite/parser": "^0.23.1",
+    "@jxsuite/parser": "^0.24.0",
+    "@jxsuite/runtime": "^0.24.0",
+    "@jxsuite/schema": "^0.24.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chokidar": "^5.0.0",
     "zod": "^4.4.3"

package/src/{build.js → build.ts}

@@ -10,7 +10,14 @@
  *   label?: string;
  * }[]} builds
  */
-export async function buildAll(builds) {
+export async function buildAll(
+  builds: {
+    entrypoints: string[];
+    outdir: string;
+    match?: ((path: string) => boolean) | RegExp;
+    label?: string;
+  }[],
+) {
   for (const entry of builds) {
     const { match: _match, label, ...opts } = entry;
     const result = await Bun.build({
@@ -36,7 +43,15 @@ export async function buildAll(builds) {
  * @param {string} changedFile
  * @returns {Promise<{ rebuilt: string[]; success: boolean }>}
  */
-export async function rebuild(builds, changedFile) {
+export async function rebuild(
+  builds: {
+    entrypoints: string[];
+    outdir: string;
+    match?: ((path: string) => boolean) | RegExp;
+    label?: string;
+  }[],
+  changedFile: string,
+) {
   const rebuilt = [];
   let ok = true;
   for (const entry of builds) {

package/src/{claude-session.js → claude-session.ts}

@@ -8,8 +8,19 @@
 
 import { query } from "@anthropic-ai/claude-agent-sdk";
 
-/** @typedef {import("@anthropic-ai/claude-agent-sdk").SDKMessage} SDKMessage */
-/** @typedef {import("@anthropic-ai/claude-agent-sdk").Options} AgentOptions */
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { Options as AgentOptions } from "@anthropic-ai/claude-agent-sdk";
+
+interface Session {
+  id: string;
+  sessionId: string | null;
+  projectRoot: string;
+  messages: SDKMessage[];
+  sseClients: Set<(event: string, data: unknown) => void>;
+  status: "active" | "idle" | "stopped";
+  abortController: AbortController | null;
+  query: AsyncGenerator | null;
+}
 
 /**
  * Build a clean env for SDK child processes. Strips session-specific vars from a parent Claude Code
@@ -28,21 +39,7 @@ function buildSdkEnv() {
   return env;
 }
 
-/**
- * @typedef {{
- *   id: string;
- *   sessionId: string | null;
- *   projectRoot: string;
- *   messages: SDKMessage[];
- *   sseClients: Set<(event: string, data: unknown) => void>;
- *   status: "active" | "idle" | "stopped";
- *   abortController: AbortController | null;
- *   query: AsyncGenerator | null;
- * }} Session
- */
-
-/** @type {Map<string, Session>} */
-const sessions = new Map();
+const sessions: Map<string, Session> = new Map();
 
 let idCounter = 0;
 
@@ -57,8 +54,8 @@ function genId() {
  * @param {string} event
  * @param {unknown} data
  */
-function broadcast(session, event, data) {
-  session.messages.push(/** @type {any} */ (data));
+function broadcast(session: Session, event: string, data: unknown) {
+  session.messages.push(data as SDKMessage);
   for (const send of session.sseClients) {
     send(event, data);
   }
@@ -70,18 +67,18 @@ function broadcast(session, event, data) {
  * @param {Session} session
  * @param {AsyncGenerator<SDKMessage>} stream
  */
-async function processStream(session, stream) {
+async function processStream(session: Session, stream: AsyncGenerator<SDKMessage>) {
   session.status = "active";
   try {
     for await (const message of stream) {
-      if (/** @type {string} */ (session.status) === "stopped") break;
+      if ((session.status as string) === "stopped") break;
       if (message.session_id && !session.sessionId) {
         session.sessionId = message.session_id;
       }
       broadcast(session, message.type, message);
     }
   } catch (err) {
-    if (/** @type {any} */ (err).name !== "AbortError") {
+    if (err instanceof Error && err.name !== "AbortError") {
       broadcast(session, "error", { type: "error", error: String(err) });
     }
   } finally {
@@ -100,12 +97,15 @@ async function processStream(session, stream) {
  * @param {{ systemPrompt?: string }} [opts]
  * @returns {{ id: string }}
  */
-export function createSession(projectRoot, message, opts = {}) {
+export function createSession(
+  projectRoot: string,
+  message: string,
+  opts: { systemPrompt?: string } = {},
+) {
   const id = genId();
   const abortController = new AbortController();
 
-  /** @type {Session} */
-  const session = {
+  const session: Session = {
     id,
     sessionId: null,
     projectRoot,
@@ -118,8 +118,7 @@ export function createSession(projectRoot, message, opts = {}) {
 
   sessions.set(id, session);
 
-  /** @type {AgentOptions} */
-  const queryOpts = {
+  const queryOpts: AgentOptions = {
     cwd: projectRoot,
     abortController,
     permissionMode: "acceptEdits",
@@ -147,7 +146,7 @@ export function createSession(projectRoot, message, opts = {}) {
  * @param {string} id
  * @param {string} message
  */
-export function sendMessage(id, message) {
+export function sendMessage(id: string, message: string) {
   const session = sessions.get(id);
   if (!session) throw new Error(`Session not found: ${id}`);
   if (session.status === "active") throw new Error("Session is still processing");
@@ -155,8 +154,7 @@ export function sendMessage(id, message) {
   const abortController = new AbortController();
   session.abortController = abortController;
 
-  /** @type {AgentOptions} */
-  const queryOpts = {
+  const queryOpts: AgentOptions = {
     cwd: session.projectRoot,
     abortController,
     permissionMode: "acceptEdits",
@@ -182,7 +180,7 @@ export function sendMessage(id, message) {
  *
  * @param {string} id
  */
-export function stopSession(id) {
+export function stopSession(id: string) {
   const session = sessions.get(id);
   if (!session) return;
   session.status = "stopped";
@@ -196,7 +194,7 @@ export function stopSession(id) {
  *
  * @param {string} id
  */
-export function deleteSession(id) {
+export function deleteSession(id: string) {
   stopSession(id);
   sessions.delete(id);
 }
@@ -207,19 +205,18 @@ export function deleteSession(id) {
  * @param {string} id
  * @returns {Response}
  */
-export function streamSession(id) {
+export function streamSession(id: string) {
   const session = sessions.get(id);
   if (!session) {
     return new Response("Session not found", { status: 404 });
   }
 
   const encoder = new TextEncoder();
-  /** @type {(event: string, data: unknown) => void} */
-  let sendRef = () => {};
+  let sendRef: (event: string, data: unknown) => void = () => {};
   const stream = new ReadableStream({
     start(controller) {
       /** @param {string} event @param {unknown} data */
-      sendRef = (event, data) => {
+      sendRef = (event: string, data: unknown) => {
         try {
           controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
         } catch {
@@ -230,7 +227,7 @@ export function streamSession(id) {
       session.sseClients.add(sendRef);
 
       for (const msg of session.messages) {
-        sendRef(/** @type {any} */ (msg).type || "message", msg);
+        sendRef(((msg as Record<string, unknown>).type as string) || "message", msg);
       }
 
       const heartbeat = setInterval(() => {
@@ -278,9 +275,13 @@ export async function getAuthStatus() {
 
     for await (const msg of testStream) {
       if (msg.type === "assistant") {
-        const content = /** @type {any} */ (msg).message?.content;
-        if (Array.isArray(content)) {
-          const text = content.find((b) => b.type === "text");
+        const content = (msg as Record<string, unknown>).message as
+          | { content?: unknown[] }
+          | undefined;
+        if (Array.isArray(content?.content)) {
+          const text = content.content.find((b: any) => b.type === "text") as
+            | { text?: string }
+            | undefined;
           if (text?.text?.toLowerCase().includes("error")) {
             clearTimeout(timeout);
             ctrl.abort();
@@ -292,11 +293,11 @@ export async function getAuthStatus() {
         return { authenticated: true };
       }
       if (msg.type === "result") {
-        const result = /** @type {any} */ (msg);
+        const result = msg as Record<string, unknown>;
         clearTimeout(timeout);
         ctrl.abort();
         if (result.is_error) {
-          return { authenticated: false, error: result.result || "API error" };
+          return { authenticated: false, error: (result.result as string) || "API error" };
         }
         return { authenticated: true };
       }
@@ -314,7 +315,7 @@ export async function getAuthStatus() {
  *
  * @param {string} id
  */
-export function getSession(id) {
+export function getSession(id: string) {
   const session = sessions.get(id);
   if (!session) return null;
   return { id: session.id, status: session.status, messageCount: session.messages.length };

package/src/{code-api.js → code-api.ts}

@@ -10,14 +10,15 @@ import { join, resolve } from "node:path";
 import { unlink } from "node:fs/promises";
 import { format } from "oxfmt";
 
-/**
- * @typedef {{
- *   span: { offset: number; line: number; [key: string]: unknown };
- *   [key: string]: unknown;
- * }} OxcLabel
- *
- * @typedef {{ labels?: OxcLabel[]; [key: string]: unknown }} OxcDiagnostic
- */
+interface OxcLabel {
+  span: { offset: number; line: number; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+interface OxcDiagnostic {
+  labels?: OxcLabel[];
+  [key: string]: unknown;
+}
 
 const OXLINT_BIN = resolve(
   import.meta.dir,
@@ -31,13 +32,13 @@ const OXLINT_BIN = resolve(
  * @param {string} body
  * @param {string[]} [args]
  */
-function wrapBody(body, args = ["state", "event"]) {
+function wrapBody(body: string, args: string[] = ["state", "event"]) {
   const params = args.join(", ");
   return `function __jx_fn__(${params}) {\n${body}\n}`;
 }
 
 /** @param {string} formatted */
-function unwrapFormatted(formatted) {
+function unwrapFormatted(formatted: string) {
   const lines = formatted.split("\n");
   // Remove first line (function header) and last non-empty line (closing brace)
   let end = lines.length - 1;
@@ -52,7 +53,7 @@ function unwrapFormatted(formatted) {
  * @param {OxcDiagnostic[]} diagnostics
  * @param {number} headerLen
  */
-function adjustDiagnostics(diagnostics, headerLen) {
+function adjustDiagnostics(diagnostics: OxcDiagnostic[], headerLen: number) {
   return diagnostics
     .filter((d) => {
       const line = d.labels?.[0]?.span?.line;
@@ -81,7 +82,7 @@ const minifier = new Bun.Transpiler({ minifyWhitespace: true });
  * @param {Request} req
  * @param {URL} url
  */
-export async function handleCodeApi(req, url) {
+export async function handleCodeApi(req: Request, url: URL) {
   const path = url.pathname;
   if (!path.startsWith("/__studio/code/") || req.method !== "POST") return null;
 
@@ -107,10 +108,10 @@ export async function handleCodeApi(req, url) {
         code: unwrapFormatted(result.code),
         errors: result.errors,
       });
-    } catch (/** @type {unknown} */ e) {
+    } catch (e) {
       return Response.json({
         code,
-        errors: [{ message: /** @type {{ message?: string }} */ (e).message }],
+        errors: [{ message: (e as Error).message }],
       });
     }
   }
@@ -124,8 +125,8 @@ export async function handleCodeApi(req, url) {
     try {
       const minified = minifier.transformSync(code).trim();
       return Response.json({ code: minified });
-    } catch (/** @type {unknown} */ e) {
-      return Response.json({ code, error: /** @type {{ message?: string }} */ (e).message });
+    } catch (e) {
+      return Response.json({ code, error: (e as Error).message });
     }
   }
 
@@ -154,10 +155,10 @@ export async function handleCodeApi(req, url) {
       const parsed = JSON.parse(output);
       const adjusted = adjustDiagnostics(parsed.diagnostics || [], headerLen);
       return Response.json({ diagnostics: adjusted });
-    } catch (/** @type {unknown} */ e) {
+    } catch (e) {
       return Response.json({
         diagnostics: [],
-        error: /** @type {{ message?: string }} */ (e).message,
+        error: (e as Error).message,
       });
     } finally {
       try {

package/src/{resolve.js → resolve.ts}

@@ -4,6 +4,8 @@ import { resolve, relative, dirname } from "node:path";
 import { readFileSync, existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { loadContentTypes } from "@jxsuite/compiler/content-loader";
+import type { DynamicClass } from "@jxsuite/runtime/types";
+import type { ClassJsonDef } from "./types.ts";
 
 /**
  * Lazy-load project context (project.json + content types) for class instantiation.
@@ -15,7 +17,7 @@ import { loadContentTypes } from "@jxsuite/compiler/content-loader";
  *   root: string;
  * } | null>}
  */
-async function loadProjectContext(projectRoot) {
+async function loadProjectContext(projectRoot: string) {
   const projectJsonPath = resolve(projectRoot, "project.json");
   if (!existsSync(projectJsonPath)) return null;
   try {
@@ -36,7 +38,11 @@ async function loadProjectContext(projectRoot) {
  * @param {string} root
  * @param {string | null} [activeProjectRoot]
  */
-export async function handleResolve(req, root, activeProjectRoot = null) {
+export async function handleResolve(
+  req: Request,
+  root: string,
+  activeProjectRoot: string | null = null,
+) {
   let body;
   try {
     body = await req.json();
@@ -69,11 +75,8 @@ export async function handleResolve(req, root, activeProjectRoot = null) {
         moduleAbsPath = serverRequire.resolve($src);
       }
     }
-  } catch (/** @type {unknown} */ e) {
-    return new Response(
-      `Cannot resolve $src "${$src}": ${/** @type {{ message?: string }} */ (e).message}`,
-      { status: 400 },
-    );
+  } catch (e) {
+    return new Response(`Cannot resolve $src "${$src}": ${(e as Error).message}`, { status: 400 });
   }
 
   // Rebase relative config paths from doc-relative to CWD-relative
@@ -125,9 +128,7 @@ export async function handleResolve(req, root, activeProjectRoot = null) {
 
       // Self-contained: construct class from schema
       const DynClass = classFromSchema(classDef);
-      const instance = /** @type {{ resolve?: () => unknown; value?: unknown }} */ (
-        new DynClass(config)
-      );
+      const instance = new DynClass(config) as { resolve?: () => unknown; value?: unknown };
       const value =
         typeof instance.resolve === "function"
           ? await instance.resolve()
@@ -135,11 +136,8 @@ export async function handleResolve(req, root, activeProjectRoot = null) {
             ? instance.value
             : instance;
       return Response.json(value);
-    } catch (/** @type {unknown} */ e) {
-      return Response.json(
-        { error: /** @type {{ message?: string }} */ (e).message },
-        { status: 500 },
-      );
+    } catch (e) {
+      return Response.json({ error: (e as Error).message }, { status: 500 });
     }
   }
 
@@ -158,7 +156,7 @@ export async function handleResolve(req, root, activeProjectRoot = null) {
  * @param {Request} req
  * @param {string} root
  */
-export async function handleServerFunction(req, root) {
+export async function handleServerFunction(req: Request, root: string) {
   let body;
   try {
     body = await req.json();
@@ -178,8 +176,8 @@ export async function handleServerFunction(req, root) {
     } else {
       moduleAbsPath = resolve(root, $src);
     }
-  } catch (/** @type {unknown} */ e) {
-    return new Response(`Cannot resolve $src: ${/** @type {{ message?: string }} */ (e).message}`, {
+  } catch (e) {
+    return new Response(`Cannot resolve $src: ${(e as Error).message}`, {
       status: 400,
     });
   }
@@ -187,11 +185,8 @@ export async function handleServerFunction(req, root) {
   let mod;
   try {
     mod = await import(moduleAbsPath);
-  } catch (/** @type {unknown} */ e) {
-    return new Response(
-      `Failed to import "${$src}": ${/** @type {{ message?: string }} */ (e).message}`,
-      { status: 500 },
-    );
+  } catch (e) {
+    return new Response(`Failed to import "${$src}": ${(e as Error).message}`, { status: 500 });
   }
 
   const fn = mod[xport] ?? mod.default?.[xport];
@@ -202,11 +197,8 @@ export async function handleServerFunction(req, root) {
   try {
     const result = await fn(args);
     return Response.json(result ?? null);
-  } catch (/** @type {unknown} */ e) {
-    return Response.json(
-      { error: /** @type {{ message?: string }} */ (e).message },
-      { status: 500 },
-    );
+  } catch (e) {
+    return Response.json({ error: (e as Error).message }, { status: 500 });
   }
 }
 
@@ -216,15 +208,15 @@ export async function handleServerFunction(req, root) {
  *
  * @param {ClassJsonDef} classDef
  */
-function classFromSchema(classDef) {
+function classFromSchema(classDef: ClassJsonDef) {
   const fields = classDef.$defs?.fields ?? {};
   const ctor = classDef.$defs?.constructor;
   const methods = classDef.$defs?.methods ?? {};
 
   class DynClass {
     constructor(config = {}) {
-      const self = /** @type {Record<string, unknown>} */ (this);
-      const cfg = /** @type {Record<string, unknown>} */ (config);
+      const self = this as Record<string, unknown>;
+      const cfg = config as Record<string, unknown>;
       for (const [key, field] of Object.entries(fields)) {
         const id = field.identifier ?? key;
         if (cfg[id] !== undefined) self[id] = cfg[id];
@@ -248,21 +240,17 @@ function classFromSchema(classDef) {
     const bodyStr = Array.isArray(method.body) ? method.body.join("\n") : (method.body ?? "");
 
     if (method.role === "accessor") {
-      /** @type {PropertyDescriptor} */
-      const descriptor = {};
-      if (method.getter)
-        descriptor.get = /** @type {() => unknown} */ (new Function(method.getter.body));
+      const descriptor: PropertyDescriptor = {};
+      if (method.getter) descriptor.get = new Function(method.getter.body) as () => unknown;
       if (method.setter) {
         const sp = (method.setter.parameters ?? []).map((p) => p.$ref?.split("/").pop() ?? "v");
-        descriptor.set = /** @type {(v: unknown) => void} */ (
-          new Function(...sp, method.setter.body)
-        );
+        descriptor.set = new Function(...sp, method.setter.body) as (v: unknown) => void;
       }
       Object.defineProperty(DynClass.prototype, name, { ...descriptor, configurable: true });
     } else if (method.scope === "static") {
-      /** @type {DynamicClass} */ (DynClass)[name] = new Function(...params, bodyStr);
+      (DynClass as DynamicClass)[name] = new Function(...params, bodyStr);
     } else {
-      /** @type {DynamicClass} */ (DynClass).prototype[name] = new Function(...params, bodyStr);
+      (DynClass as DynamicClass).prototype[name] = new Function(...params, bodyStr);
     }
   }
 

package/src/{server.js → server.ts}

@@ -14,11 +14,11 @@
  */
 
 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 { buildAll } from "./build.ts";
+import { createWatcher, injectSSE } from "./watch.ts";
+import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleStudioApi } from "./studio-api.ts";
+import { handleCodeApi } from "./code-api.ts";
 import { existsSync, readFileSync } from "node:fs";
 
 /**
@@ -30,7 +30,7 @@ import { existsSync, readFileSync } from "node:fs";
  * @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) {
+function resolveNpmPath(root: string, urlPath: string) {
   let segments = urlPath.split("/").filter(Boolean);
 
   // If "node_modules" appears in the path, use everything before it as a subdirectory
@@ -53,10 +53,8 @@ function resolveNpmPath(root, urlPath) {
     }
   }
 
-  /** @type {string} */
-  let pkgDir = "";
-  /** @type {string} */
-  let subpath = "";
+  let pkgDir: string = "";
+  let subpath: string = "";
 
   if (isScoped) {
     if (start < 0 || start + 1 >= segments.length) return null;
@@ -142,7 +140,19 @@ export { resolveNpmPath };
  * @param {Function} [options.middleware] - Custom route handler (req, url) => Response|null
  * @returns {Promise<object>} The Bun.serve server object
  */
-export async function createDevServer(options) {
+export async function createDevServer(options: {
+  root: string;
+  port?: number;
+  builds?: {
+    entrypoints: string[];
+    outdir: string;
+    match?: ((path: string) => boolean) | RegExp;
+    label?: string;
+  }[];
+  watch?: boolean | object;
+  studio?: boolean;
+  middleware?: (req: Request, url: URL) => Response | null | Promise<Response | null>;
+}) {
   const {
     root,
     port = 3000,
@@ -171,12 +181,10 @@ export async function createDevServer(options) {
   }
 
   // Bundle cache for npm packages (bare specifier → bundled JS)
-  /** @type {Map<string, string>} */
-  const bundleCache = new Map();
+  const bundleCache: Map<string, string> = new Map();
 
   // Active studio project root (set via /__studio/activate, used for static file fallback)
-  /** @type {string | null} */
-  let activeProjectRoot = null;
+  let activeProjectRoot: string | null = null;
 
   // ─── HTTP server ────────────────────────────────────────────────────────────
 
@@ -185,7 +193,7 @@ export async function createDevServer(options) {
 
     async fetch(req) {
       const url = new URL(req.url);
-      let path = url.pathname;
+      let path = decodeURIComponent(url.pathname);
       if (path.endsWith("/")) path += "index.html";
       else if (path === "") path = "/index.html";
 
@@ -270,7 +278,7 @@ export async function createDevServer(options) {
               if (result.success && result.outputs.length > 0) {
                 bundleCache.set(cacheKey, await result.outputs[0].text());
               }
-            } catch (/** @type {unknown} */ e) {
+            } catch (e) {
               console.error("Bundle failed for", resolved, e);
             }
           }