@jxsuite/server 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,8 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/server.js"
+    ".": "./src/server.js",
+    "./claude-session": "./src/claude-session.js"
   },
   "publishConfig": {
     "provenance": true
@@ -22,6 +23,12 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "chokidar": "^5.0.0"
+    "@anthropic-ai/claude-agent-sdk": "^0.3.152",
+    "@anthropic-ai/sdk": "^0.99.0",
+    "@jxsuite/create": "^0.19.0",
+    "@jxsuite/parser": "^0.20.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chokidar": "^5.0.0",
+    "zod": "^4.4.3"
   }
 }

package/src/claude-session.js

@@ -0,0 +1,321 @@
+/**
+ * Claude-session.js — Claude Agent SDK session manager
+ *
+ * Manages Claude Code sessions via @anthropic-ai/claude-agent-sdk, providing: - Session creation
+ * with streaming output - Follow-up messages via session resume - SSE broadcasting to connected
+ * frontend clients - Session interruption and cleanup
+ */
+
+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 */
+
+/**
+ * Build a clean env for SDK child processes. Strips session-specific vars from a parent Claude Code
+ * instance that would override the SDK's own credential resolution (OAuth from ~/.claude/).
+ */
+function buildSdkEnv() {
+  const env = { ...process.env };
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  delete env.ANTHROPIC_BASE_URL;
+  delete env.CLAUDE_CODE_ENTRYPOINT;
+  delete env.CLAUDE_CODE_EXECPATH;
+  delete env.CLAUDE_AGENT_SDK_VERSION;
+  delete env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC;
+  delete env.CLAUDECODE;
+  env.CLAUDE_AGENT_SDK_CLIENT_APP = "jx-studio/0.17.0";
+  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();
+
+let idCounter = 0;
+
+function genId() {
+  return `ai_${Date.now().toString(36)}_${(++idCounter).toString(36)}`;
+}
+
+/**
+ * Broadcast an SSE event to all connected clients for a session.
+ *
+ * @param {Session} session
+ * @param {string} event
+ * @param {unknown} data
+ */
+function broadcast(session, event, data) {
+  session.messages.push(/** @type {any} */ (data));
+  for (const send of session.sseClients) {
+    send(event, data);
+  }
+}
+
+/**
+ * Process the async message stream from a query.
+ *
+ * @param {Session} session
+ * @param {AsyncGenerator<SDKMessage>} stream
+ */
+async function processStream(session, stream) {
+  session.status = "active";
+  try {
+    for await (const message of stream) {
+      if (/** @type {string} */ (session.status) === "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") {
+      broadcast(session, "error", { type: "error", error: String(err) });
+    }
+  } finally {
+    session.status = "idle";
+    session.query = null;
+    session.abortController = null;
+    broadcast(session, "done", { type: "done" });
+  }
+}
+
+/**
+ * Create a new AI session and begin streaming.
+ *
+ * @param {string} projectRoot
+ * @param {string} message
+ * @param {{ systemPrompt?: string }} [opts]
+ * @returns {{ id: string }}
+ */
+export function createSession(projectRoot, message, opts = {}) {
+  const id = genId();
+  const abortController = new AbortController();
+
+  /** @type {Session} */
+  const session = {
+    id,
+    sessionId: null,
+    projectRoot,
+    messages: [],
+    sseClients: new Set(),
+    status: "active",
+    abortController,
+    query: null,
+  };
+
+  sessions.set(id, session);
+
+  /** @type {AgentOptions} */
+  const queryOpts = {
+    cwd: projectRoot,
+    abortController,
+    permissionMode: "acceptEdits",
+    allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
+    maxTurns: 30,
+    includePartialMessages: true,
+    persistSession: true,
+    env: buildSdkEnv(),
+  };
+
+  if (opts.systemPrompt) {
+    queryOpts.systemPrompt = opts.systemPrompt;
+  }
+
+  const stream = query({ prompt: message, options: queryOpts });
+  session.query = stream;
+  processStream(session, stream);
+
+  return { id };
+}
+
+/**
+ * Send a follow-up message to an existing session.
+ *
+ * @param {string} id
+ * @param {string} message
+ */
+export function sendMessage(id, message) {
+  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");
+
+  const abortController = new AbortController();
+  session.abortController = abortController;
+
+  /** @type {AgentOptions} */
+  const queryOpts = {
+    cwd: session.projectRoot,
+    abortController,
+    permissionMode: "acceptEdits",
+    allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
+    maxTurns: 30,
+    includePartialMessages: true,
+    continue: true,
+    env: buildSdkEnv(),
+  };
+
+  if (session.sessionId) {
+    queryOpts.resume = session.sessionId;
+    delete queryOpts.continue;
+  }
+
+  const stream = query({ prompt: message, options: queryOpts });
+  session.query = stream;
+  processStream(session, stream);
+}
+
+/**
+ * Stop a running session (interrupt the current query).
+ *
+ * @param {string} id
+ */
+export function stopSession(id) {
+  const session = sessions.get(id);
+  if (!session) return;
+  session.status = "stopped";
+  if (session.abortController) {
+    session.abortController.abort();
+  }
+}
+
+/**
+ * Remove a session entirely.
+ *
+ * @param {string} id
+ */
+export function deleteSession(id) {
+  stopSession(id);
+  sessions.delete(id);
+}
+
+/**
+ * Get an SSE Response stream for a session.
+ *
+ * @param {string} id
+ * @returns {Response}
+ */
+export function streamSession(id) {
+  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 = () => {};
+  const stream = new ReadableStream({
+    start(controller) {
+      /** @param {string} event @param {unknown} data */
+      sendRef = (event, data) => {
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+        } catch {
+          // Stream closed
+        }
+      };
+
+      session.sseClients.add(sendRef);
+
+      for (const msg of session.messages) {
+        sendRef(/** @type {any} */ (msg).type || "message", msg);
+      }
+
+      const heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": heartbeat\n\n"));
+        } catch {
+          clearInterval(heartbeat);
+          session.sseClients.delete(sendRef);
+        }
+      }, 15000);
+    },
+    cancel() {
+      session.sseClients.delete(sendRef);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    },
+  });
+}
+
+/**
+ * Check if the claude agent SDK can authenticate.
+ *
+ * @returns {Promise<{ authenticated: boolean; error?: string }>}
+ */
+export async function getAuthStatus() {
+  try {
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), 15000);
+    const testStream = query({
+      prompt: "Say OK",
+      options: {
+        abortController: ctrl,
+        maxTurns: 1,
+        persistSession: false,
+        includePartialMessages: true,
+        env: buildSdkEnv(),
+      },
+    });
+
+    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");
+          if (text?.text?.toLowerCase().includes("error")) {
+            clearTimeout(timeout);
+            ctrl.abort();
+            return { authenticated: false, error: text.text };
+          }
+        }
+        clearTimeout(timeout);
+        ctrl.abort();
+        return { authenticated: true };
+      }
+      if (msg.type === "result") {
+        const result = /** @type {any} */ (msg);
+        clearTimeout(timeout);
+        ctrl.abort();
+        if (result.is_error) {
+          return { authenticated: false, error: result.result || "API error" };
+        }
+        return { authenticated: true };
+      }
+    }
+
+    clearTimeout(timeout);
+    return { authenticated: true };
+  } catch (err) {
+    return { authenticated: false, error: String(err) };
+  }
+}
+
+/**
+ * Get session info.
+ *
+ * @param {string} id
+ */
+export function getSession(id) {
+  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

@@ -10,6 +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
+ */
+
 const OXLINT_BIN = resolve(
   import.meta.dir,
   "../../node_modules/.bin",
@@ -40,7 +49,7 @@ function unwrapFormatted(formatted) {
 }
 
 /**
- * @param {any[]} diagnostics
+ * @param {OxcDiagnostic[]} diagnostics
  * @param {number} headerLen
  */
 function adjustDiagnostics(diagnostics, headerLen) {
@@ -51,7 +60,7 @@ function adjustDiagnostics(diagnostics, headerLen) {
     })
     .map((d) => ({
       ...d,
-      labels: d.labels.map((/** @type {any} */ label) => ({
+      labels: d.labels?.map((label) => ({
         ...label,
         span: {
           ...label.span,
@@ -98,8 +107,11 @@ export async function handleCodeApi(req, url) {
         code: unwrapFormatted(result.code),
         errors: result.errors,
       });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ code, errors: [{ message: e.message }] });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json({
+        code,
+        errors: [{ message: /** @type {{ message?: string }} */ (e).message }],
+      });
     }
   }
 
@@ -112,8 +124,8 @@ export async function handleCodeApi(req, url) {
     try {
       const minified = minifier.transformSync(code).trim();
       return Response.json({ code: minified });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ code, error: e.message });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json({ code, error: /** @type {{ message?: string }} */ (e).message });
     }
   }
 
@@ -142,8 +154,11 @@ export async function handleCodeApi(req, url) {
       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 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json({
+        diagnostics: [],
+        error: /** @type {{ message?: string }} */ (e).message,
+      });
     } finally {
       try {
         await unlink(tmpFile);

package/src/resolve.js

@@ -29,8 +29,11 @@ export async function handleResolve(req, root) {
     } else {
       moduleAbsPath = resolve(root, $src);
     }
-  } catch (/** @type {any} */ e) {
-    return new Response(`Cannot resolve $src "${$src}": ${e.message}`, { status: 400 });
+  } catch (/** @type {unknown} */ e) {
+    return new Response(
+      `Cannot resolve $src "${$src}": ${/** @type {{ message?: string }} */ (e).message}`,
+      { status: 400 },
+    );
   }
 
   // Rebase relative config paths from doc-relative to CWD-relative
@@ -74,7 +77,9 @@ export async function handleResolve(req, root) {
 
       // Self-contained: construct class from schema
       const DynClass = classFromSchema(classDef);
-      const instance = /** @type {any} */ (new DynClass(config));
+      const instance = /** @type {{ resolve?: () => unknown; value?: unknown }} */ (
+        new DynClass(config)
+      );
       const value =
         typeof instance.resolve === "function"
           ? await instance.resolve()
@@ -82,8 +87,11 @@ export async function handleResolve(req, root) {
             ? instance.value
             : instance;
       return Response.json(value);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -122,15 +130,20 @@ export async function handleServerFunction(req, root) {
     } else {
       moduleAbsPath = resolve(root, $src);
     }
-  } catch (/** @type {any} */ e) {
-    return new Response(`Cannot resolve $src: ${e.message}`, { status: 400 });
+  } catch (/** @type {unknown} */ e) {
+    return new Response(`Cannot resolve $src: ${/** @type {{ message?: string }} */ (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 });
+  } catch (/** @type {unknown} */ e) {
+    return new Response(
+      `Failed to import "${$src}": ${/** @type {{ message?: string }} */ (e).message}`,
+      { status: 500 },
+    );
   }
 
   const fn = mod[xport] ?? mod.default?.[xport];
@@ -141,8 +154,11 @@ export async function handleServerFunction(req, root) {
   try {
     const result = await fn(args);
     return Response.json(result ?? null);
-  } catch (/** @type {any} */ e) {
-    return Response.json({ error: e.message }, { status: 500 });
+  } catch (/** @type {unknown} */ e) {
+    return Response.json(
+      { error: /** @type {{ message?: string }} */ (e).message },
+      { status: 500 },
+    );
   }
 }
 
@@ -150,7 +166,7 @@ export async function handleServerFunction(req, root) {
  * Dynamically construct a class from a .class.json schema definition. Server-side variant — no
  * private field limitations.
  *
- * @param {any} classDef
+ * @param {ClassJsonDef} classDef
  */
 function classFromSchema(classDef) {
   const fields = classDef.$defs?.fields ?? {};
@@ -159,8 +175,8 @@ function classFromSchema(classDef) {
 
   class DynClass {
     constructor(config = {}) {
-      const self = /** @type {any} */ (this);
-      const cfg = /** @type {Record<string, any>} */ (config);
+      const self = /** @type {Record<string, unknown>} */ (this);
+      const cfg = /** @type {Record<string, unknown>} */ (config);
       for (const [key, field] of Object.entries(fields)) {
         const id = field.identifier ?? key;
         if (cfg[id] !== undefined) self[id] = cfg[id];
@@ -177,27 +193,28 @@ function classFromSchema(classDef) {
 
   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();
+    const params = (method.parameters ?? []).map((p) => {
+      if (p.$ref) return p.$ref.split("/").pop() ?? "arg";
       return p.identifier ?? p.name ?? "arg";
     });
     const bodyStr = Array.isArray(method.body) ? method.body.join("\n") : (method.body ?? "");
 
     if (method.role === "accessor") {
-      /** @type {any} */
+      /** @type {PropertyDescriptor} */
       const descriptor = {};
-      if (method.getter) descriptor.get = new Function(method.getter.body);
+      if (method.getter)
+        descriptor.get = /** @type {() => unknown} */ (new Function(method.getter.body));
       if (method.setter) {
-        const sp = (method.setter.parameters ?? []).map(
-          (/** @type {any} */ p) => p.$ref?.split("/").pop() ?? "v",
+        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);
       }
       Object.defineProperty(DynClass.prototype, name, { ...descriptor, configurable: true });
     } else if (method.scope === "static") {
-      /** @type {any} */ (DynClass)[name] = new Function(...params, bodyStr);
+      /** @type {DynamicClass} */ (DynClass)[name] = new Function(...params, bodyStr);
     } else {
-      /** @type {any} */ (DynClass.prototype)[name] = new Function(...params, bodyStr);
+      /** @type {DynamicClass} */ (DynClass).prototype[name] = new Function(...params, bodyStr);
     }
   }
 

package/src/server.js

@@ -270,7 +270,7 @@ export async function createDevServer(options) {
               if (result.success && result.outputs.length > 0) {
                 bundleCache.set(cacheKey, await result.outputs[0].text());
               }
-            } catch (/** @type {any} */ e) {
+            } catch (/** @type {unknown} */ e) {
               console.error("Bundle failed for", resolved, e);
             }
           }

package/src/studio-api.js

@@ -11,6 +11,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";
+import * as claude from "./claude-session.js";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (/** @type {string} */ p) => p.replaceAll("\\", "/");
@@ -40,6 +41,14 @@ const statusMap = { M: "M", T: "T", A: "A", D: "D", R: "R", C: "C", U: "U" };
  * Parse raw `git status --porcelain=v2 --branch` output into structured data.
  *
  * @param {string} out
+ * @returns {{
+ *   branch: string;
+ *   ahead: number;
+ *   behind: number;
+ *   files: { path: string; status: string; staged: boolean }[];
+ *   isRepo?: boolean;
+ *   remotes?: string[];
+ * }}
  */
 export function parseGitStatus(out) {
   let branch = "";
@@ -97,6 +106,7 @@ export function parseGitStatus(out) {
  * @param {URL} url
  * @param {string} root
  * @param {string | null} [activeProjectRoot]
+ * @returns {Promise<Response | null>}
  */
 export async function handleStudioApi(req, url, root, activeProjectRoot = null) {
   const path = url.pathname;
@@ -121,8 +131,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     const absDir = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
       assertAccessible(absDir, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 400 },
+      );
     }
     try {
       const projectRoot = fwd(absDir);
@@ -154,8 +167,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       } catch {}
 
       return Response.json({ isSiteProject, projectConfig, directories, projectRoot });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -189,8 +205,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         dir = parent;
       }
       return Response.json({ sitePath: null });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -211,8 +230,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         }
       } catch {}
       return Response.json({ path: null });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -238,8 +260,36 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         } catch {}
       }
       return Response.json(sites);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
+    }
+  }
+
+  // Create a new project
+  if (path === "/__studio/create-project" && req.method === "POST") {
+    try {
+      const body = await req.json();
+      const { name, description, url: siteUrl, adapter, directory } = body;
+      if (!name || !directory) {
+        return Response.json({ error: "name and directory are required" }, { status: 400 });
+      }
+      const destPath = resolve(root, directory);
+      assertAccessible(destPath, root, activeProjectRoot);
+
+      const { generateProject } = await import("@jxsuite/create/generate");
+      await generateProject(destPath, { name, description, url: siteUrl, adapter });
+
+      const config = JSON.parse(await readFile(resolve(destPath, "project.json"), "utf8"));
+      const projectRoot = fwd(relative(root, destPath));
+      return Response.json({ root: projectRoot, config });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -250,8 +300,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     const absDir = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
       assertAccessible(absDir, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 400 },
+      );
     }
 
     /** Report a path relative to the active project root (or server root as fallback). */
@@ -299,8 +352,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         });
       }
       return Response.json(files);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -310,8 +366,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     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 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 400 },
+      );
     }
     try {
       const glob = new Bun.Glob("**/*.{json,md}");
@@ -325,7 +384,6 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
           continue;
         const fp = resolve(scanRoot, match);
         try {
-          /** @type {any} */
           let content;
           if (match.endsWith(".md")) {
             const source = await readFile(fp, "utf8");
@@ -406,14 +464,17 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
                       source: "npm",
                       package: name,
                       description: decl.description || null,
-                      props: (decl.attributes || []).map((/** @type {any} */ a) => ({
-                        name: a.name,
-                        type: a.type?.text,
-                        default: a.default,
-                        description: a.description || null,
-                      })),
+                      props: (decl.attributes || []).map(
+                        (/** @type {Record<string, unknown>} */ a) => ({
+                          name: a.name,
+                          type: /** @type {Record<string, unknown> | undefined} */ (a.type)?.text,
+                          default: a.default,
+                          description: a.description || null,
+                        }),
+                      ),
                       members: (decl.members || []).filter(
-                        (/** @type {any} */ m) => m.kind === "field" && m.privacy !== "private",
+                        (/** @type {Record<string, unknown>} */ m) =>
+                          m.kind === "field" && m.privacy !== "private",
                       ),
                       slots: decl.slots || [],
                       events: decl.events || [],
@@ -429,8 +490,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       } catch {} // skip if no project package.json
 
       return Response.json(components);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -445,7 +509,14 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       if (!existsSync(pkgPath)) return Response.json([]);
       const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      /** @type {any[]} */
+      /**
+       * @type {{
+       *   name: string;
+       *   version: string;
+       *   hasCem: boolean;
+       *   customElementsPath: string | null;
+       * }[]}
+       */
       const packages = [];
       for (const [name, version] of Object.entries(deps)) {
         const depPkgPath = resolve(scanRoot, "node_modules", ...name.split("/"), "package.json");
@@ -467,8 +538,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         } catch {}
       }
       return Response.json(packages);
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -493,8 +567,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       if (!existsSync(cemPath)) return Response.json({ cem: null });
       const cem = JSON.parse(await readFile(cemPath, "utf8"));
       return Response.json({ cem });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -519,8 +596,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         );
       }
       return Response.json({ ok: true });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -543,8 +623,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         );
       }
       return Response.json({ ok: true });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -555,18 +638,21 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     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 });
+    } catch (/** @type {unknown} */ e) {
+      return new Response(/** @type {{ message?: string }} */ (e).message, { status: 400 });
     }
     try {
       return Response.json({
         content: await readFile(abs, "utf8"),
         path: fp,
       });
-    } catch (/** @type {any} */ e) {
-      return e.code === "ENOENT"
+    } catch (/** @type {unknown} */ e) {
+      return /** @type {{ code?: string }} */ (e).code === "ENOENT"
         ? new Response("Not found", { status: 404 })
-        : Response.json({ error: e.message }, { status: 500 });
+        : Response.json(
+            { error: /** @type {{ message?: string }} */ (e).message },
+            { status: 500 },
+          );
     }
   }
 
@@ -577,15 +663,18 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     const abs = resolve(root, fp);
     try {
       assertAccessible(abs, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return new Response(e.message, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return new Response(/** @type {{ message?: string }} */ (e).message, { status: 400 });
     }
     try {
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, await req.text(), "utf8");
       return Response.json({ ok: true, path: fwd(relative(root, abs)) });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -596,16 +685,19 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     const abs = resolve(root, fp);
     try {
       assertAccessible(abs, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return new Response(e.message, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return new Response(/** @type {{ message?: string }} */ (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 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -616,16 +708,19 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     const abs = resolve(root, fp);
     try {
       assertAccessible(abs, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return new Response(e.message, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return new Response(/** @type {{ message?: string }} */ (e).message, { status: 400 });
     }
     try {
       await unlink(abs);
       return Response.json({ ok: true, path: fwd(relative(root, abs)) });
-    } catch (/** @type {any} */ e) {
-      return e.code === "ENOENT"
+    } catch (/** @type {unknown} */ e) {
+      return /** @type {{ code?: string }} */ (e).code === "ENOENT"
         ? new Response("Not found", { status: 404 })
-        : Response.json({ error: e.message }, { status: 500 });
+        : Response.json(
+            { error: /** @type {{ message?: string }} */ (e).message },
+            { status: 500 },
+          );
     }
   }
 
@@ -644,8 +739,8 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
     try {
       assertAccessible(absFrom, root, activeProjectRoot);
       assertAccessible(absTo, root, activeProjectRoot);
-    } catch (/** @type {any} */ e) {
-      return new Response(e.message, { status: 400 });
+    } catch (/** @type {unknown} */ e) {
+      return new Response(/** @type {{ message?: string }} */ (e).message, { status: 400 });
     }
     try {
       await mkdir(dirname(absTo), { recursive: true });
@@ -655,8 +750,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         from: fwd(relative(root, absFrom)),
         to: fwd(relative(root, absTo)),
       });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -684,8 +782,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         path: matches[0],
         ...(matches.length > 1 ? { alternatives: matches } : {}),
       });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ error: e.message }, { status: 500 });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
     }
   }
 
@@ -705,8 +806,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       } else {
         moduleAbsPath = resolve(root, src);
       }
-    } catch (/** @type {any} */ e) {
-      return Response.json({ schema: null, error: e.message });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json({
+        schema: null,
+        error: /** @type {{ message?: string }} */ (e).message,
+      });
     }
 
     // .class.json: read and extract schema directly
@@ -715,8 +819,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         const content = readFileSync(moduleAbsPath, "utf8");
         const classDef = JSON.parse(content);
         return Response.json({ schema: extractStudioSchema(classDef, moduleAbsPath) });
-      } catch (/** @type {any} */ e) {
-        return Response.json({ schema: null, error: e.message });
+      } catch (/** @type {unknown} */ e) {
+        return Response.json({
+          schema: null,
+          error: /** @type {{ message?: string }} */ (e).message,
+        });
       }
     }
 
@@ -741,8 +848,11 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         return Response.json({ schema: null, error: `Export "${exportName}" not found` });
       }
       return Response.json({ schema: ExportedClass.schema ?? null });
-    } catch (/** @type {any} */ e) {
-      return Response.json({ schema: null, error: e.message });
+    } catch (/** @type {unknown} */ e) {
+      return Response.json({
+        schema: null,
+        error: /** @type {{ message?: string }} */ (e).message,
+      });
     }
   }
 
@@ -763,8 +873,44 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
 
     try {
       if (gitCmd === "status" && req.method === "GET") {
-        const out = await runGit(["status", "--porcelain=v2", "--branch"]);
-        return Response.json(parseGitStatus(out));
+        // Check if we're in a git repo first
+        const checkProc = Bun.spawn(["git", "rev-parse", "--is-inside-work-tree"], {
+          cwd,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const checkExit = await checkProc.exited;
+        if (checkExit !== 0) {
+          return Response.json({
+            isRepo: false,
+            branch: "",
+            files: [],
+            ahead: 0,
+            behind: 0,
+            remotes: [],
+          });
+        }
+
+        const [out, remotesOut] = await Promise.all([
+          runGit(["status", "--porcelain=v2", "--branch"]),
+          runGit(["remote"]),
+        ]);
+        const status = parseGitStatus(out);
+        status.isRepo = true;
+        status.remotes = remotesOut.trim().split("\n").filter(Boolean);
+        return Response.json(status);
+      }
+
+      if (gitCmd === "init" && req.method === "POST") {
+        await runGit(["init"]);
+        return Response.json({ ok: true });
+      }
+
+      if (gitCmd === "add-remote" && req.method === "POST") {
+        const { name, url: remoteUrl } = await req.json();
+        if (!name || !remoteUrl) return new Response("name and url required", { status: 400 });
+        await runGit(["remote", "add", name, remoteUrl]);
+        return Response.json({ ok: true });
       }
 
       if (gitCmd === "branches" && req.method === "GET") {
@@ -828,7 +974,17 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
       }
 
       if (gitCmd === "push" && req.method === "POST") {
-        await runGit(["push"]);
+        let body = {};
+        try {
+          body = await req.json();
+        } catch {}
+        const { setUpstream } = /** @type {{ setUpstream?: boolean }} */ (body);
+        if (setUpstream) {
+          const branch = (await runGit(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+          await runGit(["push", "-u", "origin", branch]);
+        } else {
+          await runGit(["push"]);
+        }
         return Response.json({ ok: true });
       }
 
@@ -885,11 +1041,94 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
         await runGit(["checkout", "--", ...files]);
         return Response.json({ ok: true });
       }
+
+      if (gitCmd === "clone" && req.method === "POST") {
+        const { url } = await req.json();
+        if (!url || typeof url !== "string")
+          return Response.json({ error: "Missing url" }, { status: 400 });
+        const repoName = basename(url.replace(/\.git$/, ""));
+        const dest = resolve(cwd, repoName);
+        const proc = Bun.spawn(["git", "clone", url, dest], {
+          cwd,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const exitCode = await proc.exited;
+        const stderr = await new Response(proc.stderr).text();
+        if (exitCode !== 0) throw new Error(stderr || `git clone exited with ${exitCode}`);
+        return Response.json({ ok: true, root: dest });
+      }
+    } catch (/** @type {unknown} */ e) {
+      return Response.json(
+        { error: /** @type {{ message?: string }} */ (e).message },
+        { status: 500 },
+      );
+    }
+  }
+
+  // ─── AI Assistant ─────────────────────────────────────────────────────────
+
+  if (path === "/__studio/ai/auth-status" && req.method === "GET") {
+    const status = await claude.getAuthStatus();
+    return Response.json(status);
+  }
+
+  if (path === "/__studio/ai/session" && req.method === "POST") {
+    try {
+      const body = await req.json();
+      const projectDir = activeProjectRoot || root;
+      const result = claude.createSession(projectDir, body.message, {
+        systemPrompt: body.systemPrompt,
+      });
+      return Response.json(result);
+    } catch (/** @type {any} */ e) {
+      return Response.json({ error: e.message }, { status: 500 });
+    }
+  }
+
+  if (
+    path.startsWith("/__studio/ai/session/") &&
+    path.endsWith("/stream") &&
+    req.method === "GET"
+  ) {
+    const id = path.split("/")[4];
+    return claude.streamSession(id);
+  }
+
+  if (
+    path.startsWith("/__studio/ai/session/") &&
+    path.endsWith("/message") &&
+    req.method === "POST"
+  ) {
+    try {
+      const id = path.split("/")[4];
+      const body = await req.json();
+      claude.sendMessage(id, body.message);
+      return Response.json({ ok: true });
     } catch (/** @type {any} */ e) {
       return Response.json({ error: e.message }, { status: 500 });
     }
   }
 
+  if (path.startsWith("/__studio/ai/session/") && path.endsWith("/stop") && req.method === "POST") {
+    const id = path.split("/")[4];
+    claude.stopSession(id);
+    return Response.json({ ok: true });
+  }
+
+  if (path.startsWith("/__studio/ai/session/") && req.method === "DELETE") {
+    const id = path.split("/")[4];
+    claude.deleteSession(id);
+    return Response.json({ ok: true });
+  }
+
+  if (path.startsWith("/__studio/ai/session/") && req.method === "GET") {
+    const id = path.split("/")[4];
+    const info = claude.getSession(id);
+    if (!info) return Response.json({ error: "Not found" }, { status: 404 });
+    return Response.json(info);
+  }
+
   return null;
 }
 
@@ -898,9 +1137,13 @@ export async function handleStudioApi(req, url, root, activeProjectRoot = null)
  * $defs.fields into the flat { description, properties, required } shape that renderSchemaFields()
  * in the studio already consumes.
  *
- * @param {any} classDef
+ * @param {ClassJsonDef} classDef
  * @param {string} classJsonPath
- * @returns {{ description: any; properties: Record<string, any>; required: string[] }}
+ * @returns {{
+ *   description: string | undefined;
+ *   properties: Record<string, Record<string, unknown>>;
+ *   required: string[];
+ * }}
  */
 function extractStudioSchema(classDef, classJsonPath) {
   // If extends.$ref points to a parent, recursively merge
@@ -918,7 +1161,7 @@ function extractStudioSchema(classDef, classJsonPath) {
 
   const params = classDef.$defs?.parameters ?? {};
   const fields = classDef.$defs?.fields ?? {};
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, Record<string, unknown>>} */
   const properties = {};
   /** @type {string[]} */
   const required = [];
@@ -934,6 +1177,7 @@ function extractStudioSchema(classDef, classJsonPath) {
   // Build properties from parameters (constructor config surface)
   for (const [key, param] of Object.entries(params)) {
     const id = param.identifier ?? key;
+    /** @type {Record<string, unknown>} */
     const prop = {};
     if (param.type && typeof param.type === "object") Object.assign(prop, param.type);
     if (param.description) prop.description = param.description;
@@ -947,6 +1191,7 @@ function extractStudioSchema(classDef, classJsonPath) {
     if (field.role !== "field") continue;
     if (field.access === "private") continue;
     const id = field.identifier ?? key;
+    /** @type {Record<string, unknown>} */
     const prop = {};
     if (field.type && typeof field.type === "object") Object.assign(prop, field.type);
     if (field.description) prop.description = field.description;

package/src/watch.js

@@ -55,7 +55,7 @@ export function injectSSE(html) {
  * Create the file watcher + SSE system.
  *
  * @param {string} root - Absolute path to watch
- * @param {any[]} builds - Build entries (for selective rebuild)
+ * @param {BuildEntry[]} builds - Build entries (for selective rebuild)
  * @param {{ ignore?: string[]; debounce?: number; reloadOnAnyChange?: boolean }} [opts]
  * @returns {{
  *   broadcast: () => void;
@@ -77,7 +77,7 @@ export function createWatcher(root, builds, opts = {}) {
   }
 
   function handleSSE() {
-    /** @type {any} */
+    /** @type {((msg: string) => void) | undefined} */
     let send;
     const stream = new ReadableStream({
       start(c) {
@@ -96,7 +96,7 @@ export function createWatcher(root, builds, opts = {}) {
         }, 15_000);
       },
       cancel() {
-        clients.delete(send);
+        if (send) clients.delete(send);
       },
     });
     return new Response(stream, {
@@ -108,7 +108,7 @@ export function createWatcher(root, builds, opts = {}) {
     });
   }
 
-  /** @type {any} */
+  /** @type {ReturnType<typeof setTimeout> | null} */
   let timer = null;
   const watcher = chokidar.watch(root, {
     ignored: (watchedPath) => shouldIgnore(watchedPath, ignore),
@@ -123,7 +123,7 @@ export function createWatcher(root, builds, opts = {}) {
   watcher.on("all", (_, changedPath) => {
     const filename = relative(root, changedPath);
     if (!filename || filename.startsWith("..")) return;
-    clearTimeout(timer);
+    clearTimeout(timer ?? undefined);
     timer = setTimeout(async () => {
       if (builds.length > 0) {
         const result = await rebuild(builds, filename);