@jxsuite/server 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,7 @@
   "exports": {
     ".": "./src/server.ts",
     "./ai-api": "./src/ai-api.ts",
+    "./import-api": "./src/import-api.ts",
     "./packages": "./src/packages.ts",
     "./project-server": "./src/project-server.ts",
     "./refactor": "./src/refactor/index.ts",
@@ -30,11 +31,13 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/compiler": "^0.34.0",
-    "@jxsuite/create": "^0.34.0",
-    "@jxsuite/parser": "^0.34.0",
-    "@jxsuite/runtime": "^0.34.0",
+    "@jxsuite/compiler": "^0.34.1",
+    "@jxsuite/create": "^0.35.0",
+    "@jxsuite/import": "^0.35.0",
+    "@jxsuite/parser": "^0.35.0",
+    "@jxsuite/runtime": "^0.34.1",
     "@jxsuite/schema": "^0.34.0",
+    "@jxsuite/starters": "^0.35.0",
     "chokidar": "^5.0.0",
     "zod": "^4.4.3"
   }

package/src/import-api.ts

@@ -0,0 +1,202 @@
+/**
+ * Import-api.ts — the AI-guided site-import endpoint for Jx Studio.
+ *
+ * Handles POST /__studio/import-site: runs @jxsuite/import's importSite pipeline in the backend
+ * (headless Chrome + filesystem) and streams progress back as NDJSON lines over the POST response —
+ * the same streaming-fetch transport the AI chat proxy uses, so every platform (dev server,
+ * Electrobun services server, Chromium loopback server) can mount it unchanged.
+ *
+ * Stream protocol (one JSON object per line):
+ *   {"type":"progress","phase":"...","message":"...","current":n,"total":n}
+ *   {"type":"heartbeat"}                       — keep-alives during silent phases
+ *   {"type":"done","root":"...","config":{…}}  — terminal success
+ *   {"type":"error","error":"..."}             — terminal failure
+ *
+ * LLM key flow (matches ai-api.ts): X-Api-Key / Authorization: Bearer header, falling back to the
+ * OPENAI_API_KEY env var; base URL from X-Api-Base-URL / OPENAI_BASE_URL. When AI component naming
+ * is requested but no key resolves, the import proceeds without the AI pass and emits a warning
+ * line instead of failing.
+ *
+ * @license MIT
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export interface ImportApiOptions {
+  /**
+   * Validate and absolutize the request's destination directory. Must throw for paths the host does
+   * not allow (the endpoint writes files and drives a browser — never pass through unchecked).
+   */
+  resolveDest: (directory: string) => string;
+  /** Map the final absolute project dir onto the platform's project-root form (default identity). */
+  toRoot?: (destPath: string) => string;
+  /** Explicit browser binary for puppeteer (e.g. the desktop launcher's discovered Chromium). */
+  chromePath?: string;
+}
+
+interface ImportRequestBody {
+  url?: string;
+  directory?: string;
+  depth?: number;
+  maxPages?: number;
+  maxNodesPerPage?: number;
+  aiComponents?: boolean;
+  aiModel?: string;
+}
+
+/** Seconds between keep-alive lines while a phase is silent (browser launch is the longest gap). */
+const HEARTBEAT_INTERVAL_MS = 15_000;
+
+const MAX_DEPTH = 5;
+const MAX_PAGES = 100;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function getAiConfig(req: Request): { apiKey: string | null; baseUrl: string | undefined } {
+  const authHeader = req.headers.get("Authorization") || "";
+  const apiKeyHeader = req.headers.get("X-Api-Key") || "";
+  const baseUrlHeader = req.headers.get("X-Api-Base-URL") || "";
+
+  let apiKey: string | null = null;
+  if (authHeader.startsWith("Bearer ")) {
+    apiKey = authHeader.slice(7).trim();
+  }
+  if (apiKeyHeader) {
+    apiKey = apiKeyHeader.trim();
+  }
+  if (!apiKey && process.env.OPENAI_API_KEY) {
+    apiKey = process.env.OPENAI_API_KEY;
+  }
+
+  const baseUrl = baseUrlHeader || process.env.OPENAI_BASE_URL || undefined;
+  return { apiKey, baseUrl };
+}
+
+/** Handle POST /__studio/import-site — run the import pipeline, streaming NDJSON progress. */
+async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<Response> {
+  let body: ImportRequestBody;
+  try {
+    body = (await req.json()) as ImportRequestBody;
+  } catch {
+    return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const { url, directory } = body;
+  if (!url || !directory) {
+    return Response.json({ error: "url and directory are required" }, { status: 400 });
+  }
+  if (!url.startsWith("http://") && !url.startsWith("https://")) {
+    return Response.json({ error: "url must start with http:// or https://" }, { status: 400 });
+  }
+
+  let destPath: string;
+  try {
+    destPath = opts.resolveDest(directory);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Response.json({ error: message }, { status: 400 });
+  }
+
+  const depth = clamp(body.depth ?? 1, 0, MAX_DEPTH);
+  const maxPages = clamp(body.maxPages ?? 20, 1, MAX_PAGES);
+  const maxNodesPerPage = clamp(body.maxNodesPerPage ?? 5000, 100, 50_000);
+  const { apiKey, baseUrl } = getAiConfig(req);
+  const toRoot = opts.toRoot ?? ((p: string) => p);
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      let closed = false;
+      const writeLine = (obj: unknown) => {
+        if (closed) {
+          return;
+        }
+        try {
+          controller.enqueue(encoder.encode(`${JSON.stringify(obj)}\n`));
+        } catch {
+          closed = true;
+        }
+      };
+      const heartbeat = setInterval(() => writeLine({ type: "heartbeat" }), HEARTBEAT_INTERVAL_MS);
+
+      try {
+        // Loaded lazily so the server never pays for puppeteer unless an import runs.
+        const { importSite } = await import("@jxsuite/import/run");
+
+        let ai:
+          | false
+          | { apiKey: string; baseUrl?: string | undefined; model?: string | undefined } = false;
+        if (body.aiComponents) {
+          if (apiKey) {
+            ai = { apiKey, baseUrl, model: body.aiModel };
+          } else {
+            writeLine({
+              type: "progress",
+              phase: "ai",
+              message:
+                "⚠ AI component naming requested but no API key is configured — continuing with heuristic names",
+            });
+          }
+        }
+
+        const result = await importSite(
+          {
+            url,
+            outDir: destPath,
+            maxDepth: depth,
+            maxPages,
+            maxNodesPerPage,
+            ai,
+            signal: req.signal,
+            ...(opts.chromePath === undefined ? {} : { chromePath: opts.chromePath }),
+          },
+          (e) => writeLine({ type: "progress", ...e }),
+        );
+
+        const config = JSON.parse(
+          await readFile(resolve(result.outDir, "project.json"), "utf8"),
+        ) as Record<string, unknown>;
+        writeLine({ type: "done", root: toRoot(result.outDir), config });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeLine({ type: "error", error: message });
+      } finally {
+        clearInterval(heartbeat);
+        if (!closed) {
+          closed = true;
+          try {
+            controller.close();
+          } catch {
+            /* Already closed by a client abort. */
+          }
+        }
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "application/x-ndjson",
+      "Cache-Control": "no-cache",
+    },
+  });
+}
+
+/**
+ * Main handler for the import route.
+ *
+ * @returns Response if handled, null if the route doesn't match
+ */
+export async function handleImportApi(
+  req: Request,
+  url: URL,
+  opts: ImportApiOptions,
+): Promise<Response | null> {
+  if (url.pathname === "/__studio/import-site" && req.method === "POST") {
+    return handleImportSite(req, opts);
+  }
+  return null;
+}

package/src/project-server.ts

@@ -29,7 +29,9 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
+import { handleImportApi } from "./import-api.ts";
 import { resolveNpmPath } from "./server.ts";
+import type { ImportApiOptions } from "./import-api.ts";
 
 /** A resolved per-window session: its project root plus its RPC handler map. */
 export interface ProjectServerSession {
@@ -52,6 +54,11 @@ export interface CreateProjectServerOptions {
   hostname?: string;
   /** Bind port. Defaults to 0 (ephemeral). */
   port?: number;
+  /**
+   * Enable the AI-guided site-import endpoint (POST `/__studio__/import-site`). Absent disables the
+   * route. It writes to the filesystem, so it is gated with the rpcToken like `/__jx_resolve__`.
+   */
+  importApi?: ImportApiOptions;
 }
 
 export interface ProjectServerHandle {
@@ -273,6 +280,25 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         }
       }
 
+      // 2b. AI-guided site import — writes to the filesystem and drives a browser, so token +
+      //     Loopback Origin/Host are the hard gate (same as the RCE-capable routes below).
+      if (normPath === "/__studio__/import-site" && req.method === "POST") {
+        const { importApi } = options;
+        if (!importApi) {
+          return new Response("Not found", { status: 404 });
+        }
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        const importUrl = new URL(req.url);
+        importUrl.pathname = "/__studio/import-site";
+        const importRes = await handleImportApi(req, importUrl, importApi);
+        if (importRes) {
+          return importRes;
+        }
+      }
+
       // 3. Studio assets under the non-colliding /__studio__/ namespace.
       if (normPath.startsWith("/__studio__/")) {
         const assetRel = normPath.slice("/__studio__/".length);

package/src/server.ts

@@ -13,13 +13,14 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
-import { handleStudioApi } from "./studio-api.ts";
+import { assertAccessible, handleStudioApi } from "./studio-api.ts";
 import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
+import { handleImportApi } from "./import-api.ts";
 import { existsSync, readFileSync } from "node:fs";
 
 /**
@@ -267,6 +268,19 @@ export async function createDevServer(options: {
           return aiRes;
         }
 
+        // AI-guided site import (/__studio/import-site) — NDJSON progress stream
+        const importRes = await handleImportApi(req, url, {
+          resolveDest: (dir) => {
+            const dest = resolve(absRoot, dir);
+            assertAccessible(dest, absRoot, activeProjectRoot);
+            return dest;
+          },
+          toRoot: (dest) => relative(absRoot, dest).replaceAll("\\", "/"),
+        });
+        if (importRes) {
+          return importRes;
+        }
+
         const codeRes = await handleCodeApi(req, url);
         if (codeRes) {
           return codeRes;

package/src/studio-api.ts

@@ -22,6 +22,7 @@ import {
 } from "./packages.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ClassJsonDef } from "./types.ts";
+import type { DesignOptions } from "@jxsuite/create/generate";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
@@ -150,7 +151,7 @@ async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
  * @param {string} root
  * @param {string | null} activeProjectRoot
  */
-function assertAccessible(filePath: string, root: string, activeProjectRoot: string | null) {
+export function assertAccessible(filePath: string, root: string, activeProjectRoot: string | null) {
   const rel = relative(root, filePath);
   if (!rel.startsWith("..") && !rel.startsWith("/")) {
     return;
@@ -331,9 +332,21 @@ export async function handleStudioApi(
       return Response.json({ error: "Missing path param" }, { status: 400 });
     }
     try {
-      // Walk up from file's directory looking for project.json
-      const absFile = expandTilde(filePath);
-      let dir = dirname(absFile);
+      // Walk up looking for project.json. Accept a directory (e.g. the project root itself, as
+      // Deep links like ?project=/abs/my-site pass) by starting the walk AT the directory and
+      // Treating its project.json as the target file, so callers land on the home page.
+      let absFile = expandTilde(filePath);
+      let dir: string;
+      let isDir = false;
+      try {
+        isDir = statSync(absFile).isDirectory();
+      } catch {}
+      if (isDir) {
+        dir = absFile;
+        absFile = resolve(absFile, "project.json");
+      } else {
+        dir = dirname(absFile);
+      }
       while (dir) {
         const candidate = resolve(dir, "project.json");
         if (existsSync(candidate)) {
@@ -424,11 +437,27 @@ export async function handleStudioApi(
         url?: string;
         adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
         directory?: string;
+        starter?: string;
+        template?: string;
+        design?: DesignOptions;
       };
-      const { name, description, url: siteUrl, adapter, directory } = body;
+      const {
+        name,
+        description,
+        url: siteUrl,
+        adapter,
+        directory,
+        starter,
+        template,
+        design,
+      } = body;
       if (!name || !directory) {
         return Response.json({ error: "name and directory are required" }, { status: 400 });
       }
+      const { isTemplateId } = await import("@jxsuite/create/templates");
+      if (template !== undefined && !isTemplateId(template)) {
+        return Response.json({ error: `Unknown template: "${template}"` }, { status: 400 });
+      }
       const destPath = resolve(root, directory);
       assertAccessible(destPath, root, activeProjectRoot);
 
@@ -438,6 +467,9 @@ export async function handleStudioApi(
         ...(adapter !== undefined ? { adapter } : {}),
         ...(description !== undefined ? { description } : {}),
         ...(siteUrl !== undefined ? { url: siteUrl } : {}),
+        ...(starter !== undefined ? { starter } : {}),
+        ...(template !== undefined && isTemplateId(template) ? { template } : {}),
+        ...(design !== undefined ? { design } : {}),
       });
 
       const config = JSON.parse(
@@ -450,6 +482,16 @@ export async function handleStudioApi(
     }
   }
 
+  // List available starter templates (for the New Project picker)
+  if (path === "/__studio/starters" && req.method === "GET") {
+    try {
+      const { listStarters } = await import("@jxsuite/starters");
+      return Response.json(listStarters());
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   // List files
   if (path === "/__studio/files" && req.method === "GET") {
     const dir = url.searchParams.get("dir") || activeProjectRoot || root;