@jxsuite/server 1.3.0 → 2.1.0

package/src/server.ts

@@ -13,13 +13,18 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
-import { assertAccessible, handleStudioApi } from "./studio-api.ts";
+import {
+  assertAccessible,
+  assertCreatableParent,
+  handleStudioApi,
+  isOwnedProjectDir,
+} from "./studio-api.ts";
 import {
   containedPath,
   decodeAndNormalizePath,
@@ -29,7 +34,9 @@ import {
 import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
+import { mediaTypeForPath } from "@jxsuite/schema/media-type";
 import { existsSync, readFileSync } from "node:fs";
+import { problem } from "./problem.ts";
 
 /**
  * Resolve an npm-style bare specifier from a URL path via node_modules. Handles scoped packages
@@ -217,6 +224,14 @@ export async function createDevServer(options: {
   }
   const absRoot = resolve(root);
 
+  /**
+   * Projects created through Studio's New Project modal, which land wherever the user pointed the
+   * Location field — normally outside `absRoot`. Remembering them lets the very next
+   * `/__studio/activate` open what was just created without widening the filesystem API to
+   * arbitrary directories.
+   */
+  const createdRoots: string[] = [];
+
   // ─── Build pipeline ─────────────────────────────────────────────────────────
 
   if (builds.length > 0) {
@@ -242,8 +257,19 @@ export async function createDevServer(options: {
   // Studio.js/canvas bundle — which shows up as half-updated UI after a rebuild (the iframe assets
   // Are query-cache-busted per mount, the parent bundle is not).
   const NO_CACHE = { "Cache-Control": "no-cache" };
-  const fileResponse = (file: ReturnType<typeof Bun.file>) =>
-    new Response(file, { headers: NO_CACHE });
+  /*
+   * `Bun.file` already infers a type from the extension, and for almost everything it is right. The
+   * exceptions are the two RFCs Jx has an opinion about: `.md` comes back as bare `text/markdown`
+   * with no `variant`, and `.yaml` comes back as `text/yaml`, the spelling RFC 9512 §5 asks
+   * implementations to stop using. `mediaTypeForPath` answers null everywhere else, so the
+   * inference stays in charge of the ordinary cases.
+   */
+  const fileResponse = (file: ReturnType<typeof Bun.file>) => {
+    const corrected = file.name === undefined ? null : mediaTypeForPath(file.name);
+    return new Response(file, {
+      headers: corrected === null ? NO_CACHE : { ...NO_CACHE, "Content-Type": corrected },
+    });
+  };
 
   // Active studio project root (set via /__studio/activate, used for static file fallback)
   let activeProjectRoot: string | null = null;
@@ -283,7 +309,7 @@ export async function createDevServer(options: {
 
       // SSE live reload
       if (handleSSE && path === "/__reload") {
-        return handleSSE();
+        return handleSSE(req);
       }
 
       /*
@@ -331,8 +357,10 @@ export async function createDevServer(options: {
         }
 
         // Activate project — tells the server which project root to use for static file fallback.
-        // Contain the requested root: it must be under absRoot or an explicitly allowed root, so a
-        // Hostile activate cannot widen the filesystem API to arbitrary directories.
+        // Contain the requested root: it must be under absRoot, an explicitly allowed root, a
+        // Project this server just created, or an existing project of the account's own
+        // (`isOwnedProjectDir`), so a hostile activate cannot widen the filesystem API to arbitrary
+        // Directories.
         if (path === "/__studio/activate" && req.method === "POST") {
           const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
@@ -343,9 +371,13 @@ export async function createDevServer(options: {
           const requested = resolve(absRoot, raw);
           const permitted =
             containedPath(requested, absRoot) !== null ||
-            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null);
+            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null) ||
+            createdRoots.some((created) => containedPath(requested, created) !== null) ||
+            isOwnedProjectDir(requested);
           if (!permitted) {
-            return Response.json({ ok: false, error: "root not permitted" }, { status: 403 });
+            // `ok: false` rides along as an extension member: the Studio client branches on it,
+            // And RFC 9457 §3.2 exists precisely so a problem can carry what a type documents.
+            return problem("forbidden", "root not permitted", { ok: false });
           }
           activeProjectRoot = requested;
           return Response.json({ ok: true, root: activeProjectRoot });
@@ -357,14 +389,26 @@ export async function createDevServer(options: {
           return aiRes;
         }
 
-        // AI-guided site import (/__studio/import-site) — NDJSON progress stream
+        // AI-guided site import (/__studio/import-site) — NDJSON progress stream. An ABSOLUTE
+        // Directory is a destination the user chose in the New Project modal, so it is vetted the
+        // Same way a create is (specs/server.md §4.2). A RELATIVE one predates that field and stays
+        // Contained to the server root — resolving it there and then widening the check to the
+        // Creatable roots would let "../escape" out.
         const importRes = await handleImportApi(req, url, {
           resolveDest: (dir) => {
+            if (isAbsolute(dir)) {
+              assertCreatableParent(dirname(dir), absRoot, allowedRoots);
+              createdRoots.push(dir);
+              return dir;
+            }
             const dest = resolve(absRoot, dir);
             assertAccessible(dest, absRoot, activeProjectRoot);
             return dest;
           },
-          toRoot: (dest) => relative(absRoot, dest).replaceAll("\\", "/"),
+          toRoot: (dest) =>
+            containedPath(dest, absRoot) === null
+              ? dest
+              : relative(absRoot, dest).replaceAll("\\", "/"),
         });
         if (importRes) {
           return importRes;
@@ -375,7 +419,10 @@ export async function createDevServer(options: {
           return codeRes;
         }
 
-        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot);
+        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot, {
+          allowedRoots,
+          onProjectCreated: (created) => createdRoots.push(created),
+        });
         if (res) {
           return res;
         }
@@ -418,7 +465,15 @@ export async function createDevServer(options: {
           await projectAssetMounts(activeProjectRoot),
         );
         if (mountRes) {
-          return new Response(mountRes.body, { headers: NO_CACHE });
+          // Carry the resolved response's own headers over. Re-wrapping just the BODY discards the
+          // Content-Type Bun inferred from the file, and a JavaScript file that arrives without one
+          // Is refused outright by strict MIME checking the moment a page loads it as a MODULE — so
+          // A previewed site kept its styles (link elements sniff) and silently lost its scripts.
+          const headers = new Headers(mountRes.headers);
+          for (const [name, value] of Object.entries(NO_CACHE)) {
+            headers.set(name, value);
+          }
+          return new Response(mountRes.body, { headers });
         }
       }
 
@@ -479,7 +534,14 @@ export async function createDevServer(options: {
             });
           }
         }
-        return new Response("Not found", { status: 404 });
+        /* The project's BUILT SITE is deliberately NOT served here, at any position in this chain.
+           This server's URL space means the project's SOURCES — that is what the canvas reads —
+           and a built page addresses the same paths meaning its own output
+           (`/components/fetch-demo.js` is the formulas here and the custom element there). Filling
+           404s from the output looked like it worked and handed the reader whichever of the two
+           happened to be missing. `site-preview.ts` gives the built site its own origin instead,
+           where every path has exactly one meaning. */
+        return problem("notFound", "Not found");
       }
 
       // Inject the live-reload script into served HTML — but NOT into the Studio editor.

package/src/site-output.ts

@@ -0,0 +1,111 @@
+/**
+ * Serve a project's BUILT output at the routes the built pages actually reference.
+ *
+ * A built page is written for its published origin: `dist/basics/counter/index.html` links to
+ * `/basics/counter` and pulls `/components/fetch-demo.css`, both root-absolute. Studio's `View:
+ * Open in Browser` used to hand the browser `…/dist/basics/counter/index.html` — the file's path
+ * rather than the page's URL — and the consequences were exactly what those two absolutes predict:
+ * the HTML arrived, every stylesheet and script 404'd against the server root, and the first link
+ * the reader clicked left the built site entirely. The page loaded and nothing else worked.
+ *
+ * So the fix is not in the URL alone. A site is only "as if published" when it is served AT A ROOT,
+ * which is what this module does for whichever project a server is showing: `/basics/counter` and
+ * `/basics/counter/` both resolve to `<outDir>/basics/counter/index.html`, `/` to
+ * `<outDir>/index.html`, and every asset the page names resolves the same way it will in
+ * production.
+ *
+ * **It is a LAST resort, deliberately.** `serveProjectFile` tries the mounts, the absolute path,
+ * the root-relative source file and `public/` before it gets here, so this step can only answer
+ * requests that were already going to 404 — it can never shadow a source file that resolves today.
+ * That property is what makes it safe to mount for every project on every server rather than behind
+ * a flag.
+ *
+ * `jx dev`'s own `createDistMiddleware` is a different thing and stays: it runs BEFORE the source
+ * files (a site project's dev server is showing the built site, not its sources) and it injects the
+ * live-reload client. This one is the fallback for the servers that are showing a project's sources
+ * — the monorepo dev server and the desktop's project server — where the built site is something a
+ * reader is visiting, not the thing being edited.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { serveContained } from "./net-guard.ts";
+
+/** What `project.json` says the build writes to, cached per root against its mtime. */
+const outDirCache = new Map<string, { mtime: number; outDir: string | null }>();
+
+/** Reset the output-directory cache (test hook). */
+export function resetSiteOutput(): void {
+  outDirCache.clear();
+}
+
+/**
+ * The project's absolute output directory, or `null` when it is not a site project.
+ *
+ * Read from `project.json` rather than assumed to be `dist`, because `build.outDir` is a documented
+ * setting and a project that moved it would otherwise be served its stale old output for ever. The
+ * mtime guard is the same idiom `jx-mounts.ts` uses: a config edit is picked up, a request is not a
+ * file read.
+ */
+export function siteOutDir(projectRoot: string): string | null {
+  const configPath = resolve(projectRoot, "project.json");
+  if (!existsSync(configPath)) {
+    return null;
+  }
+  const { mtimeMs } = statSync(configPath);
+  const cached = outDirCache.get(projectRoot);
+  if (cached && cached.mtime === mtimeMs) {
+    return cached.outDir;
+  }
+  let outDir: string | null = null;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8")) as {
+      build?: { outDir?: unknown };
+    };
+    const declared = config.build?.outDir;
+    outDir = resolve(projectRoot, typeof declared === "string" && declared ? declared : "dist");
+  } catch {
+    // An unparseable project.json is the editor's problem to report, not this server's to guess
+    // At. No output directory means this fallback simply declines, and the request 404s as before.
+    outDir = null;
+  }
+  outDirCache.set(projectRoot, { mtime: mtimeMs, outDir });
+  return outDir;
+}
+
+/**
+ * Serve `decodedPath` from the project's built output, or `null` when it names nothing there.
+ *
+ * The mapping is the compiler's own, read backwards: a request for a route gets that route's
+ * `index.html` whether or not the reader typed the trailing slash, because a built site is browsed
+ * by its routes and a reader does not know which spelling the `trailingSlash` setting produced.
+ * `<route>.html` is tried too, which is what `trailingSlash: "never"` writes.
+ */
+export async function serveSiteOutput(
+  decodedPath: string,
+  projectRoot: string,
+): Promise<Response | null> {
+  const outDir = siteOutDir(projectRoot);
+  if (!outDir || !existsSync(outDir)) {
+    return null;
+  }
+  const rel = decodedPath.replace(/^\/+/, "");
+  const direct = resolve(outDir, `./${rel}`);
+
+  // A file (an asset, or a page under `trailingSlash: "never"`).
+  if (existsSync(direct) && statSync(direct).isFile()) {
+    return serveContained(direct, outDir);
+  }
+  // A route: its directory's index.html, with or without the trailing slash the reader typed.
+  const asIndex = join(direct, "index.html");
+  if (existsSync(asIndex)) {
+    return serveContained(asIndex, outDir);
+  }
+  // `trailingSlash: "never"` writes `<route>.html` beside its siblings.
+  const asHtml = `${direct.replace(/\/+$/, "")}.html`;
+  if (rel !== "" && existsSync(asHtml)) {
+    return serveContained(asHtml, outDir);
+  }
+  return null;
+}

package/src/site-preview.ts

@@ -0,0 +1,106 @@
+/**
+ * The built site on its own origin — what `View: Open in Browser` opens.
+ *
+ * A built page is written for its published origin and addresses everything ROOT-absolutely:
+ * `dist/basics/fetch/index.html` links to `/basics/counter` and loads `/components/fetch-demo.js`.
+ * So it is only browsable when those paths resolve against the OUTPUT — and on the editor's server
+ * they resolve against the project's SOURCES, because that is the editor's whole job. The two are
+ * the same URLs holding different bytes: `/components/fetch-demo.js` is the module of formulas the
+ * compiler reads in the sources, and the custom-element definition the page needs in the output.
+ *
+ * Serving the output as a 404 fallback on the editor's server looks like it works — the page and
+ * the assets that exist in only one of the two spaces arrive — and then the reader gets the source
+ * module for anything that exists in both. Measured: the page rendered, `customElements.get(...)`
+ * was null, and nothing on it did anything. No ordering fixes that; one origin cannot hold two
+ * meanings for one path.
+ *
+ * Hence a second server, rooted AT the output directory, where every path has exactly the meaning
+ * the published site gives it. Nothing is injected — no live-reload client, no rewriting — because
+ * the point is to hand the reader the bytes that will be deployed. `View: Open in Browser` builds,
+ * then opens a URL here.
+ *
+ * It is bound to loopback and serves only files under the output directory, which is the artefact
+ * the author is about to publish; it carries none of the editor's privileged routes and needs no
+ * token. Servers are reused per project root — opening ten pages opens one port — and they live for
+ * the life of the process: the map is keyed by root and two windows on one project share an origin,
+ * so no single window's teardown may close it.
+ */
+
+import { serveSiteOutput, siteOutDir } from "./site-output.ts";
+import { problem } from "./problem.ts";
+
+/** A running preview server for one project. */
+export interface SitePreview {
+  /** Origin to prefix a route with, e.g. `http://127.0.0.1:41234`. */
+  origin: string;
+  port: number;
+}
+
+interface Running extends SitePreview {
+  server: { stop: (closeActiveConnections?: boolean) => void };
+}
+
+/** One server per project root — a second `Open in Browser` reuses the first one's port. */
+const running = new Map<string, Running>();
+
+/**
+ * Start (or reuse) the preview server for `projectRoot`, or `null` when there is nothing to serve:
+ * not a site project, or a site nobody has built yet. A caller that has just built gets a server;
+ * one that has not gets the honest answer rather than a port that 404s everything.
+ */
+export function startSitePreview(projectRoot: string): SitePreview | null {
+  const outDir = siteOutDir(projectRoot);
+  if (!outDir) {
+    return null;
+  }
+  const existing = running.get(projectRoot);
+  if (existing) {
+    return { origin: existing.origin, port: existing.port };
+  }
+  const server = Bun.serve({
+    fetch: async (req: Request) => {
+      const url = new URL(req.url);
+      let decoded: string;
+      try {
+        decoded = decodeURIComponent(url.pathname);
+      } catch {
+        return problem("invalidRequest", "Bad request");
+      }
+      const res = await serveSiteOutput(decoded, projectRoot);
+      if (res) {
+        return res;
+      }
+      /* The site's OWN 404 page when it has one, at the status the published site would send.
+         A generated `404.html` is a page the author wrote; showing it is more faithful than
+         showing this server's opinion, and it is how the static hosts serve it. */
+      const notFound = await serveSiteOutput("/404.html", projectRoot);
+      return notFound
+        ? new Response(notFound.body, { headers: notFound.headers, status: 404 })
+        : problem("notFound", "Not found");
+    },
+    hostname: "127.0.0.1",
+    port: 0,
+  });
+  // `server.url` rather than `server.port`: the origin is the thing being handed to a browser, and
+  // Reading it from the server that is actually listening cannot disagree with it.
+  const entry: Running = {
+    origin: server.url.origin,
+    port: Number(server.url.port),
+    server,
+  };
+  running.set(projectRoot, entry);
+  return { origin: entry.origin, port: entry.port };
+}
+
+/** The origin already serving `projectRoot`, without starting one. */
+export function sitePreviewOrigin(projectRoot: string): string | null {
+  return running.get(projectRoot)?.origin ?? null;
+}
+
+/** Stop every preview server (process teardown, and the hook tests close their ports with). */
+export function stopSitePreviews(): void {
+  for (const entry of running.values()) {
+    entry.server.stop(true);
+  }
+  running.clear();
+}