@jxsuite/server 2.0.0 → 2.2.1

package/src/refactor/scan.ts

@@ -0,0 +1,70 @@
+/**
+ * Scan.ts — the project document sweep the refactor engines share.
+ *
+ * `applyRename` (write pass) and `findReferences` (read pass) walk exactly the same file set: every
+ * JSON document plus every extension the project's format registry claims, minus the vendored /
+ * build / agent directories. Keeping one definition of "the project's documents" is the point — a
+ * rename that rewrites a file the usage count never looked at is a lie in both directions.
+ */
+
+import { extname } from "node:path";
+import { readFile } from "node:fs/promises";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+
+/** Normalise a path to forward slashes (Windows `path` returns backslashes). */
+export const fwd = (p: string) => p.replaceAll("\\", "/");
+
+/** A parsed document plus the serializer that round-trips it back to disk (null when none). */
+export interface LoadedDoc {
+  doc: unknown;
+  serialize: ((doc: unknown) => Promise<string>) | null;
+}
+
+const isJsonPath = (p: string) => p.endsWith(".json");
+
+/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
+export function skipScanPath(match: string): boolean {
+  const f = fwd(match);
+  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+}
+
+/** Build the recursive glob covering JSON plus every registered document/content extension. */
+export function documentGlob(registry: FormatRegistry): Bun.Glob {
+  const exts = new Set(["json"]);
+  for (const ext of registry.documentExtensions()) {
+    exts.add(ext.replace(/^\./, ""));
+  }
+  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
+}
+
+/**
+ * Read + parse a file, returning the doc and a matching serializer (null when the format can parse
+ * but not serialize). Throws when no parser claims the extension.
+ */
+export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
+  const raw = await readFile(fp, "utf8");
+  if (isJsonPath(fp)) {
+    const trailingNewline = raw.endsWith("\n");
+    return {
+      doc: JSON.parse(raw) as unknown,
+      serialize: (doc) =>
+        Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
+    };
+  }
+  const ext = extname(fp);
+  const parseEntry = registry.byExtension(ext, "parse");
+  if (!parseEntry) {
+    throw new Error(`No parser for "${ext}"`);
+  }
+  const doc = await parseEntry.call("parse", raw);
+  const serializeEntry = registry.byExtension(ext, "serialize");
+  return {
+    doc,
+    serialize: serializeEntry
+      ? async (d) => {
+          const out = await serializeEntry.call("serialize", d);
+          return typeof out === "string" ? out : String(out);
+        }
+      : null,
+  };
+}

package/src/refactor/watcher.ts

@@ -8,6 +8,7 @@
 
 import { watch as chokidarWatch } from "chokidar";
 import { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+import { invalidateReferenceCache } from "./find-refs.ts";
 import type { FsEventPayload } from "./fs-events.ts";
 
 const IGNORE_SEGMENTS = ["node_modules", ".git", "dist", ".jx", ".direnv", ".devenv"];
@@ -45,6 +46,9 @@ export function createFsWatcher(
     if (!event) {
       return;
     }
+    // Any move under the root can change who references what, so the usage cache drops the whole
+    // Project rather than trying to derive which queries this one path could have affected.
+    invalidateReferenceCache(root);
     buffer = coalesceFsEvents(buffer, event);
     if (timer) {
       clearTimeout(timer);

package/src/resolve.ts

@@ -11,6 +11,7 @@ import { loadAssetMounts } from "@jxsuite/compiler/asset-mounts";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { DynamicClass } from "@jxsuite/runtime/types";
 import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
+import { problem } from "./problem.ts";
 
 interface ModuleNamespace {
   default?: Record<string, unknown>;
@@ -126,12 +127,12 @@ export async function handleResolve(
   try {
     body = (await req.json()) as ResolveBody;
   } catch {
-    return new Response("Invalid JSON body", { status: 400 });
+    return problem("invalidRequest", "Invalid JSON body");
   }
 
   const { $src, $prototype, $export: xport, $base, ...config } = body;
   if (!$src) {
-    return new Response("Missing $src", { status: 400 });
+    return problem("invalidRequest", "Missing $src");
   }
 
   let moduleAbsPath;
@@ -200,7 +201,7 @@ export async function handleResolve(
         // A trusted (bare-specifier) class file names its own sibling implementation; only a
         // Project-local relative $src is held to the root-escape guard.
         if (!trustedResolution && !isImportable(implPath, root, activeProjectRoot)) {
-          return new Response(`$implementation escapes the project root`, { status: 403 });
+          return problem("pathOutsideProject", "$implementation escapes the project root");
         }
         const exportName = xport ?? classDef.title ?? $prototype;
         const mod = (await import(implPath)) as ModuleNamespace;
@@ -236,7 +237,7 @@ export async function handleResolve(
             : instance;
       return Response.json(value);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -260,12 +261,12 @@ export async function handleServerFunction(req: Request, root: string) {
   try {
     body = (await req.json()) as ServerFunctionBody;
   } catch {
-    return new Response("Invalid JSON body", { status: 400 });
+    return problem("invalidRequest", "Invalid JSON body");
   }
 
   const { $src, $export: xport, $base, arguments: args = {} } = body;
   if (!$src || !xport) {
-    return new Response("Missing $src or $export", { status: 400 });
+    return problem("invalidRequest", "Missing $src or $export");
   }
 
   let moduleAbsPath;
@@ -278,9 +279,7 @@ export async function handleServerFunction(req: Request, root: string) {
       moduleAbsPath = resolve(root, $src);
     }
   } catch (error) {
-    return new Response(`Cannot resolve $src: ${errorMessage(error)}`, {
-      status: 400,
-    });
+    return problem("invalidRequest", `Cannot resolve $src: ${errorMessage(error)}`);
   }
 
   if (!isImportable(moduleAbsPath, root, null)) {
@@ -312,7 +311,7 @@ export async function handleServerFunction(req: Request, root: string) {
     );
     return Response.json(result ?? null);
   } catch (error) {
-    return Response.json({ error: errorMessage(error) }, { status: 500 });
+    return problem("internalError", errorMessage(error));
   }
 }
 

package/src/server.ts

@@ -34,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
@@ -255,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;
@@ -296,7 +309,7 @@ export async function createDevServer(options: {
 
       // SSE live reload
       if (handleSSE && path === "/__reload") {
-        return handleSSE();
+        return handleSSE(req);
       }
 
       /*
@@ -362,7 +375,9 @@ export async function createDevServer(options: {
             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 });
@@ -450,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 });
         }
       }
 
@@ -511,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();
+}