@jxsuite/server 4.4.4 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "4.4.4",
+  "version": "4.5.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -44,22 +44,22 @@
     "@jxsuite/ai": "^0.39.3",
     "@jxsuite/catalog": "^0.1.0",
     "@jxsuite/collab": "^0.11.1",
-    "@jxsuite/compiler": "^5.1.0",
-    "@jxsuite/create": "^1.3.13",
-    "@jxsuite/import": "^0.40.7",
+    "@jxsuite/compiler": "^5.1.2",
+    "@jxsuite/create": "^1.3.14",
+    "@jxsuite/import": "^0.40.9",
     "@jxsuite/protocol": "^2.6.1",
-    "@jxsuite/runtime": "^4.0.3",
+    "@jxsuite/runtime": "^4.1.0",
     "@jxsuite/schema": "^3.0.0",
-    "@jxsuite/site": "^2.0.3",
-    "@jxsuite/starters": "^2.0.0",
+    "@jxsuite/site": "^2.0.4",
+    "@jxsuite/starters": "^2.0.1",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.6",
-    "oxfmt": "^0.70.0",
+    "oxfmt": "^0.72.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@jxsuite/auth": "^0.6.2",
     "@jxsuite/connector": "^0.6.2",
-    "@jxsuite/parser": "^2.0.0"
+    "@jxsuite/parser": "^2.0.1"
   }
 }

package/src/dev-vars.ts

@@ -2,7 +2,8 @@
  * Dev-vars — `<project>/.dev.vars` parsing (wrangler convention, specs/extensions.md §13).
  *
  * Secret VALUES never enter project.json; locally they live in the git-ignored .dev.vars file and
- * the dev server merges them over process.env when constructing mount environments. The format is
+ * the dev server merges them over process.env when constructing the `env` it hands project code:
+ * the extension mounts' and the server-function proxy's (`projectDevEnv`). The format is
  * dotenv-shaped: KEY=VALUE lines, `#` comments, optional single/double quotes. The compiler CLI
  * keeps its own tiny copy (db-push.ts) — the compiler cannot depend on this package.
  */
@@ -59,3 +60,16 @@ export function loadDevVars(projectRoot: string): Record<string, string> {
     return {};
   }
 }
+
+/**
+ * The `env` a development host hands project code that runs server-side: `process.env` merged under
+ * the project's `.dev.vars`, plus `JX_PROJECT_ROOT`. The extension mounts (server.md §3) and the
+ * server-function proxy (server.md §3.3) both build theirs here, so a server function reads the
+ * same secrets a mount does.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {Record<string, string | undefined>}
+ */
+export function projectDevEnv(root: string): Record<string, string | undefined> {
+  return { ...process.env, ...loadDevVars(root), JX_PROJECT_ROOT: root };
+}

package/src/jx-mounts.ts

@@ -7,7 +7,8 @@
  *
  * Dev conveniences over the production worker:
  *
- * - `env` is process.env merged under the project's `.dev.vars` plus `JX_PROJECT_ROOT`;
+ * - `env` is process.env merged under the project's `.dev.vars` plus `JX_PROJECT_ROOT`
+ *   (`projectDevEnv`, which the server-function proxy shares);
  * - Connector classes with `local: "<provider>"` are stood in by the registry's class for that
  *   provider (e.g. D1 → sqlite at `<project>/.jx/data/<connection>.sqlite`);
  * - Mount options set `autoSync: true`, so table schemas sync additively on first touch.
@@ -18,7 +19,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
-import { loadDevVars } from "./dev-vars.ts";
+import { projectDevEnv } from "./dev-vars.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatEntry } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
@@ -121,11 +122,7 @@ async function buildRuntime(
   }
 
   const connectors = await resolveConnectorStandins(registry);
-  const env: Record<string, unknown> = {
-    ...process.env,
-    ...loadDevVars(projectRoot),
-    JX_PROJECT_ROOT: projectRoot,
-  };
+  const env: Record<string, unknown> = projectDevEnv(projectRoot);
 
   // One shared mutable context, passed to every mount in order (specs/extensions.md §11).
   const ctx: Record<string, unknown> = {};

package/src/resolve.ts

@@ -1,10 +1,11 @@
 /** Resolve.js — Generic $src module proxy + timing: "server" function proxy */
 
 import { siteBasePath } from "@jxsuite/schema/asset-paths";
-import { dirname, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
+import { projectDevEnv } from "./dev-vars.ts";
 import { containedPath } from "./net-guard.ts";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 import { loadProjectSections } from "@jxsuite/compiler/project-sections";
@@ -56,6 +57,41 @@ function isImportable(p: string, root: string, activeProjectRoot: string | null)
   return false;
 }
 
+/**
+ * The directory holding the document a `$base` names, which a relative `$src` resolves against.
+ *
+ * Hosts spell a base two ways. A page served at a site URL (`jx dev`, the live preview) names a
+ * path under `root`, and a single leading slash always means that, even when the path would also
+ * read as an absolute one: a root `/app` may hold a site directory `app/`. Studio's canvas
+ * addresses a project by its absolute filesystem path instead (`documentBase` in
+ * `packages/studio`), so its base arrives as `//abs/project/pages/x.json`, or
+ * `/C:/project/pages/x.json` on Windows: the spelling the static file lanes map back to the file
+ * (`serveProjectFile`). A `file:` URL's path is a filesystem path too. Those spellings name the
+ * path itself only when it lies under `root` or the active project, so any other path keeps meaning
+ * a site URL. The pathname is percent-decoded first, because a URL encodes a space in a directory
+ * name and the filesystem does not.
+ *
+ * @param {string} $base - The document URL the runtime sent
+ * @param {string} root - The root a site URL names a path under
+ * @param {string} projectRoot - The active project, which may sit outside `root`
+ * @returns {string} An absolute directory
+ */
+function baseDirectory($base: string, root: string, projectRoot: string): string {
+  const url = new URL($base);
+  const pathname = decodeURIComponent(url.pathname);
+  const urlDir = pathname.slice(0, pathname.lastIndexOf("/") + 1);
+  const spellsPath = urlDir.startsWith("//") || /^\/[A-Za-z]:/.test(urlDir);
+  const fsDir = spellsPath ? urlDir.slice(1) : url.protocol === "file:" ? urlDir : null;
+  if (
+    fsDir !== null &&
+    isAbsolute(fsDir) &&
+    (containedPath(fsDir, root) !== null || containedPath(fsDir, projectRoot) !== null)
+  ) {
+    return resolve(fsDir);
+  }
+  return resolve(root, `.${urlDir}`);
+}
+
 /** Per-project context cache, invalidated when project.json changes on disk. */
 const projectContextCache = new Map<
   string,
@@ -267,13 +303,20 @@ export async function handleResolve(
 }
 
 /**
- * Handle POST /**jx_server** — proxy timing: "server" function calls. In dev mode, the runtime
- * sends these instead of hitting the production Hono handler.
+ * Handle POST `/__jx_server__` — proxy timing: "server" function calls. It is the only way an
+ * interpreting runtime calls a server function (spec.md §11.4): the runtime never imports the
+ * module in the browser, it posts the call here, and the function runs server-side with `env`.
+ *
+ * A relative `$src` resolves against the directory of the document `$base` names (`baseDirectory`):
+ * a site URL's path under `root`, or the absolute path Studio's canvas sends. The imported module
+ * stays cached for as long as the host runs, so an edit to it takes effect when the host restarts.
  *
  * @param {Request} req
- * @param {string} root
+ * @param {string} root - The root a site-URL `$base`, or a `$src` without one, resolves under
+ * @param {string} [projectRoot] - The active project: the function's `env` carries its `.dev.vars`,
+ *   and a module under it is importable as one under `root` is. `root` when omitted
  */
-export async function handleServerFunction(req: Request, root: string) {
+export async function handleServerFunction(req: Request, root: string, projectRoot = root) {
   let body: ServerFunctionBody;
   try {
     body = (await req.json()) as ServerFunctionBody;
@@ -288,18 +331,14 @@ export async function handleServerFunction(req: Request, root: string) {
 
   let moduleAbsPath;
   try {
-    if ($base) {
-      const docUrlPath = new URL($base).pathname;
-      const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
-      moduleAbsPath = resolve(resolve(root, `.${docDir}`), $src);
-    } else {
-      moduleAbsPath = resolve(root, $src);
-    }
+    moduleAbsPath = $base
+      ? resolve(baseDirectory($base, root, projectRoot), $src)
+      : resolve(root, $src);
   } catch (error) {
     return problem("invalidRequest", `Cannot resolve $src: ${errorMessage(error)}`);
   }
 
-  if (!isImportable(moduleAbsPath, root, null)) {
+  if (!isImportable(moduleAbsPath, root, projectRoot)) {
     return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
   }
 
@@ -320,11 +359,12 @@ export async function handleServerFunction(req: Request, root: string) {
   }
 
   try {
-    // Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev
-    // Proxy runs server-side, so `process.env` is the analogous environment binding.
+    /* 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 (fn as (args: Record<string, unknown>, env: unknown) => unknown)(
       args,
-      process.env,
+      projectDevEnv(projectRoot),
     );
     return Response.json(result ?? null);
   } catch (error) {

package/src/server.ts

@@ -359,9 +359,11 @@ export async function createDevServer(options: {
         return handleResolve(req, absRoot, activeProjectRoot);
       }
 
-      // Timing: "server" function proxy
+      /* Timing: "server" function proxy. Its `env` carries the active project's `.dev.vars`, as the
+         extension mounts' does below, and a module under that project imports even when it sits
+         outside absRoot, as the static lanes below serve it. */
       if (path === "/__jx_server__" && req.method === "POST") {
-        return handleServerFunction(req, absRoot);
+        return handleServerFunction(req, absRoot, activeProjectRoot ?? absRoot);
       }
 
       // Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as the