@jxsuite/server 6.0.1 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "6.0.1",
+  "version": "7.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -41,25 +41,25 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.39.5",
-    "@jxsuite/catalog": "^0.1.2",
-    "@jxsuite/collab": "^0.11.2",
-    "@jxsuite/compiler": "^6.0.2",
-    "@jxsuite/create": "^1.3.17",
-    "@jxsuite/import": "^0.40.13",
-    "@jxsuite/protocol": "^4.0.0",
-    "@jxsuite/runtime": "^5.1.0",
-    "@jxsuite/schema": "^4.0.0",
-    "@jxsuite/site": "^2.1.0",
-    "@jxsuite/starters": "^3.0.1",
-    "chokidar": "^5.0.0",
+    "@jxsuite/ai": "^0.41.0",
+    "@jxsuite/catalog": "^0.1.3",
+    "@jxsuite/collab": "^0.11.3",
+    "@jxsuite/compiler": "^7.0.0",
+    "@jxsuite/create": "^1.4.1",
+    "@jxsuite/import": "^0.41.1",
+    "@jxsuite/protocol": "^5.0.0",
+    "@jxsuite/runtime": "^6.0.0",
+    "@jxsuite/schema": "^4.1.0",
+    "@jxsuite/site": "^2.2.1",
+    "@jxsuite/starters": "^3.1.1",
+    "chokidar": "^6.0.0",
     "kysely": "^0.29.7",
-    "oxfmt": "^0.73.0",
+    "oxfmt": "^0.74.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.7.0",
-    "@jxsuite/connector": "^0.7.0",
-    "@jxsuite/parser": "^4.0.1"
+    "@jxsuite/auth": "^0.8.1",
+    "@jxsuite/connector": "^0.8.1",
+    "@jxsuite/parser": "^4.1.1"
   }
 }

package/src/dev.ts

@@ -13,7 +13,13 @@
  */
 
 import { existsSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join, normalize, resolve, sep } from "node:path";
+import { errorMessage } from "@jxsuite/schema/parse";
+import type { JsonObject } from "@jxsuite/schema/types";
+import { projectDevEnv } from "./dev-vars.ts";
+import { problem } from "./problem.ts";
+import { callServerExport } from "./resolve.ts";
 import { createDevServer } from "./server.ts";
 import { injectSSE } from "./watch.ts";
 
@@ -90,6 +96,84 @@ export function createDistMiddleware(
   };
 }
 
+/** One server entry the last build collected: the export, and where the site worker imports it from. */
+export interface ServerEntry {
+  exportName: string;
+  /** A `./` path from the project root, or a bare specifier, exactly as the worker bundle reads it. */
+  src: string;
+}
+
+/** The route every server function is served at, before the deployment base `server.ts` strips. */
+const SERVER_FUNCTION_ROUTE = "/_jx/server/";
+
+/**
+ * The arguments object a call posted. The worker reads its body the same way: anything that is not
+ * JSON is an empty argument object, so a function never sees the failure of a malformed request.
+ */
+async function readArguments(req: Request): Promise<JsonObject> {
+  try {
+    /* SAFETY: trust boundary. The body is whatever JSON the caller posted, and a compiled page posts
+       the entry's `arguments` object. The function receives it exactly as the worker passes it. */
+    return (await req.json()) as JsonObject;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Middleware that stands in for the site worker's server-function routes (server.md §2): answers
+ * `POST /_jx/server/<export>` for each entry the last build collected, and `null` for anything
+ * else, so the request falls through to the next middleware.
+ *
+ * It answers as the worker does, because a built page calls both the same way: the function's
+ * return value as JSON, `null` for `undefined`, and `{ ok: false, error }` with status 500 when it
+ * cannot be called. The function receives `env` as the extension mounts do (`projectDevEnv`:
+ * `process.env` under the project's `.dev.vars`), so it reads the same secrets in development.
+ *
+ * Each module is resolved as the worker bundle resolves it, from the project root: a `./` path
+ * against the root, any other specifier through the project's own `package.json`. It applies no
+ * containment check, because the module path comes from the build and never from the request;
+ * containment stays in the `/__jx_server__` proxy, where the request names the module.
+ *
+ * @param {string} root - Absolute project root
+ * @param {() => readonly ServerEntry[]} entries - The last build's collected entries, read per
+ *   request
+ * @returns {(req: Request, url: URL) => Promise<Response | null>}
+ */
+export function createServerFunctionMiddleware(
+  root: string,
+  entries: () => readonly ServerEntry[],
+): (req: Request, url: URL) => Promise<Response | null> {
+  const requireFromProject = createRequire(resolve(root, "package.json"));
+  return async (req, url) => {
+    if (req.method !== "POST" || !url.pathname.startsWith(SERVER_FUNCTION_ROUTE)) {
+      return null;
+    }
+    const name = url.pathname.slice(SERVER_FUNCTION_ROUTE.length);
+    const entry = entries().find((candidate) => candidate.exportName === name);
+    if (!entry) {
+      return problem("notFound", `The last build collected no server function "${name}"`);
+    }
+
+    let modulePath: string;
+    try {
+      modulePath =
+        entry.src.startsWith("./") || entry.src.startsWith("../")
+          ? resolve(root, entry.src)
+          : requireFromProject.resolve(entry.src);
+    } catch (error) {
+      return Response.json({ error: errorMessage(error), ok: false }, { status: 500 });
+    }
+
+    const args = await readArguments(req);
+    const result = await callServerExport(modulePath, entry.exportName, args, projectDevEnv(root));
+    if (result.ok) {
+      return Response.json(result.value ?? null);
+    }
+    return Response.json({ error: result.message, ok: false }, { status: 500 });
+  };
+}
+
 export interface DevServerHandle {
   port: number;
   stop: () => void;
@@ -106,10 +190,13 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
   const isSite = existsSync(join(root, "project.json"));
 
   let building = Promise.resolve();
+  // What the last build collected, which the server-function route answers from.
+  let serverEntries: readonly ServerEntry[] = [];
   const rebuild = () => {
     building = building.then(async () => {
       const { buildSite } = await import("@jxsuite/compiler/site");
       const result = await buildSite(root, { verbose: false });
+      ({ serverEntries } = result);
       if (result.errors.length > 0) {
         for (const err of result.errors) {
           console.error(`  build error: ${err}`);
@@ -124,6 +211,13 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
     await rebuild();
   }
 
+  // The built pages call the site worker's routes, and `jx dev` has no worker, so it answers them
+  // From the entries the last build collected, ahead of the built pages.
+  const serverFunctions = createServerFunctionMiddleware(root, () => serverEntries);
+  const distPages = createDistMiddleware(root);
+  const siteMiddleware = async (req: Request, url: URL) =>
+    (await serverFunctions(req, url)) ?? (await distPages(req, url));
+
   /* SAFETY: createDevServer always calls Bun.serve with a hostname and TCP port, never a unix
      socket, so the returned Server's `port` (typed `number | undefined` for the socket case) is a
      number; its promise-returning `stop()` satisfies `() => void`. */
@@ -131,7 +225,7 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
     port,
     root,
     ...(isSite && {
-      middleware: createDistMiddleware(root),
+      middleware: siteMiddleware,
       watch: { preReload: () => rebuild(), reloadOnAnyChange: true },
     }),
   })) as DevServerHandle;

package/src/resolve.ts

@@ -492,33 +492,68 @@ export async function handleServerFunction(req: Request, root: string, projectRo
     return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
   }
 
+  // Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev proxy
+  // Runs server-side, so its `env` is the extension mounts' own, `process.env` merged under the
+  // Project's `.dev.vars` plus `JX_PROJECT_ROOT` (server.md §3.3).
+  const result = await callServerExport(moduleAbsPath, xport, args, projectDevEnv(projectRoot));
+  if (result.ok) {
+    return Response.json(result.value ?? null);
+  }
+  if (result.stage === "import") {
+    return new Response(`Failed to import "${$src}": ${result.message}`, { status: 500 });
+  }
+  if (result.stage === "export") {
+    return new Response(`Export "${xport}" not found in "${$src}"`, { status: 500 });
+  }
+  return problem("internalError", result.message);
+}
+
+/** What {@link callServerExport} answers: the function's value, or the stage that failed and why. */
+export type ServerExportResult =
+  | { ok: true; value: ServerFunctionResult }
+  | { ok: false; stage: "import" | "export" | "call"; message: string };
+
+/**
+ * Import a module, read one export and call it as `fn(args, env)`, the contract a `timing:
+ * "server"` function has in production (compiler.md §6.3).
+ *
+ * The one place a dev host runs a server function, so the `/__jx_server__` proxy and the site
+ * worker's stand-in route in `jx dev` agree on what an export is (a named export, else a member of
+ * a default export) and on where each failure belongs. It decides nothing about WHICH module may
+ * run: the proxy's caller names one in a request and checks containment first, while the stand-in
+ * route's modules come from the build, so each does its own checking before it gets here.
+ *
+ * @param {string} modulePath - Absolute path of the module, or a specifier already resolved
+ * @param {string} exportName - The export to call
+ * @param {JsonObject} args - The function's first argument
+ * @param {ProjectDevEnv} env - The function's second argument: the platform environment
+ * @returns {Promise<ServerExportResult>}
+ */
+export async function callServerExport(
+  modulePath: string,
+  exportName: string,
+  args: JsonObject,
+  env: ProjectDevEnv,
+): Promise<ServerExportResult> {
   let mod: ModuleNamespace;
   try {
-    mod = await importModule(moduleAbsPath);
+    mod = await importModule(modulePath);
   } catch (error) {
-    return new Response(`Failed to import "${$src}": ${errorMessage(error)}`, {
-      status: 500,
-    });
+    return { message: errorMessage(error), ok: false, stage: "import" };
   }
 
-  const fn = mod[xport] ?? mod.default?.[xport];
+  const fn = mod[exportName] ?? mod.default?.[exportName];
   if (!isExportedFunction(fn)) {
-    return new Response(`Export "${xport}" not found in "${$src}"`, {
-      status: 500,
-    });
+    return { message: `Export "${exportName}" not found`, ok: false, stage: "export" };
   }
 
   try {
-    /* Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev
-       proxy runs server-side, so its `env` is the extension mounts' own, `process.env` merged under
-       the project's `.dev.vars` plus `JX_PROJECT_ROOT` (server.md §3.3). */
     /* SAFETY: trust boundary. A `timing: "server"` module exports its functions with the signature
        `fn(args, env)` and a JSON answer (spec.md §11.4); this one is a function, checked above. */
     const serverFn = fn as ServerFunction;
-    const result = await serverFn(args, projectDevEnv(projectRoot));
-    return Response.json(result ?? null);
+    return { ok: true, value: await serverFn(args, env) };
   } catch (error) {
-    return problem("internalError", errorMessage(error));
+    return { message: errorMessage(error), ok: false, stage: "call" };
   }
 }
 

package/src/studio-api.ts

@@ -11,9 +11,8 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve } from
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
 import {
   buildExtensionsPayload,
   buildProjectExtensionRegistry,
@@ -568,102 +567,6 @@ export async function handleStudioApi(
     }
   }
 
-  // Find a project directory by name — searches $HOME for the first matching directory with a
-  // Project.json. Dev-mode workaround for when showDirectoryPicker() can't provide absolute paths.
-  if (path === "/__studio/find-project" && req.method === "GET") {
-    const name = url.searchParams.get("name");
-    if (!name) {
-      return problem("invalidRequest", "Missing name");
-    }
-    try {
-      const home = process.env.HOME || process.env.USERPROFILE || "";
-      if (!home) {
-        return Response.json({ path: null });
-      }
-      const glob = new Bun.Glob(`**/${name}/project.json`);
-      try {
-        for await (const match of glob.scan({ cwd: home, dot: false })) {
-          if (match.includes("node_modules") || match.includes(".Trash")) {
-            continue;
-          }
-          const abs = resolve(home, dirname(match));
-          return Response.json({ path: abs });
-        }
-      } catch {}
-      return Response.json({ path: null });
-    } catch (error) {
-      return problem("internalError", errorMessage(error));
-    }
-  }
-
-  /*
-   * Recover the absolute path of a directory the browser picked with `showDirectoryPicker()`.
-   *
-   * A `FileSystemDirectoryHandle` exposes only `.name`, never a filesystem path (§8.2), and unlike
-   * /__studio/find-project there is no `project.json` to search for — the whole point is that the
-   * folder is empty. So the client tags the folder with a hidden LOCATION_ID_FILE holding a random
-   * id and asks us which directory carries that id.
-   *
-   * Identity lives in the file's CONTENTS, not its name: matching the id is exact where matching a
-   * path shape is only probable — two folders can share a basename, and a file left behind by a
-   * crashed session can still be on disk. A candidate whose contents do not equal `id` is skipped,
-   * so a stale tag can never redirect a create. The winning file is deleted here, the moment it has
-   * served its purpose, rather than being left for the client to tidy up.
-   */
-  if (path === "/__studio/locate-directory" && req.method === "GET") {
-    const name = url.searchParams.get("name");
-    const id = url.searchParams.get("id");
-    // `name` is interpolated into a glob; the id is only ever compared, never used as a pattern.
-    if (!name || !id || !/^[a-f0-9]{32}$/.test(id) || !/^[^/\\]+$/.test(name)) {
-      return problem("invalidRequest", "Missing or invalid name/id");
-    }
-    try {
-      const home = process.env.HOME || process.env.USERPROFILE || "";
-      if (!home) {
-        return Response.json({ path: null });
-      }
-      /** The tagged directory when this candidate holds our id, else null. */
-      const claim = (dir: string): string | null => {
-        const file = resolve(dir, LOCATION_ID_FILE);
-        try {
-          if (readFileSync(file, "utf8").trim() !== id) {
-            return null;
-          }
-        } catch {
-          return null;
-        }
-        try {
-          unlinkSync(file);
-        } catch {
-          // Read-only or already gone; the client's own cleanup is the backstop.
-        }
-        return dir;
-      };
-
-      // The home directory itself is a legitimate pick, and no `**/<name>/` glob can match it.
-      const atHome = claim(home);
-      if (atHome) {
-        return Response.json({ path: atHome });
-      }
-      // `dot: true` — the tag is a dotfile, so a dot-blind scan would never see it.
-      const glob = new Bun.Glob(`**/${name}/${LOCATION_ID_FILE}`);
-      try {
-        for await (const match of glob.scan({ cwd: home, dot: true })) {
-          if (match.includes("node_modules") || match.includes(".Trash")) {
-            continue;
-          }
-          const claimed = claim(resolve(home, dirname(match)));
-          if (claimed) {
-            return Response.json({ path: claimed });
-          }
-        }
-      } catch {}
-      return Response.json({ path: null });
-    } catch (error) {
-      return problem("internalError", errorMessage(error));
-    }
-  }
-
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
@@ -781,8 +684,7 @@ export async function handleStudioApi(
         await readFile(resolve(destPath, "project.json"), "utf8"),
       ) as ProjectConfig;
       // Root-relative while the project happens to sit under the server root (the historical
-      // Shape every caller already handles); absolute otherwise, which is the same shape
-      // /__studio/find-project returns for an external project.
+      // Shape every caller already handles); absolute otherwise.
       const inRoot = containedPath(destPath, root) !== null;
       opts.onProjectCreated?.(destPath);
       return Response.json({ config, root: inRoot ? fwd(relative(root, destPath)) : destPath });