@jxsuite/server 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -39,22 +39,22 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.8.4",
-    "@jxsuite/compiler": "^3.0.0",
-    "@jxsuite/create": "^1.3.8",
-    "@jxsuite/import": "^0.40.0",
-    "@jxsuite/protocol": "^2.1.0",
-    "@jxsuite/runtime": "^3.0.0",
-    "@jxsuite/schema": "^2.0.0",
-    "@jxsuite/site": "^1.0.0",
-    "@jxsuite/starters": "^1.6.5",
+    "@jxsuite/collab": "^0.8.5",
+    "@jxsuite/compiler": "^3.1.0",
+    "@jxsuite/create": "^1.3.9",
+    "@jxsuite/import": "^0.40.1",
+    "@jxsuite/protocol": "^2.2.0",
+    "@jxsuite/runtime": "^3.1.0",
+    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/site": "^1.1.0",
+    "@jxsuite/starters": "^1.7.0",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.5",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.5.6",
-    "@jxsuite/connector": "^0.5.6",
-    "@jxsuite/parser": "^1.6.0"
+    "@jxsuite/auth": "^0.5.7",
+    "@jxsuite/connector": "^0.5.7",
+    "@jxsuite/parser": "^1.7.0"
   }
 }

package/src/refactor/apply.ts

@@ -122,7 +122,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
     }
     const fp = fwd(resolve(opts.root, match));
     try {
-      const { doc, serialize } = await loadDoc(fp, opts.registry);
+      const { doc, rewrite, serialize } = await loadDoc(fp, opts.registry);
       const docNewDir = dirname(fp);
       const docOldDir = isUnder(fp, absTo) ? dirname(absFrom + fp.slice(absTo.length)) : docNewDir;
 
@@ -139,11 +139,29 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
       if (changes.length === 0 && tagCount === 0) {
         continue;
       }
-      if (!serialize) {
+      /*
+       * Two ways to write a document back, and the narrower one is not a fallback for a broken
+       * format — it is the only honest promise a load-only format can make. A CSV collection has a
+       * parser and deliberately no serializer, so a reference living in one used to be COUNTED and
+       * then reported as a remainder the author had to repair by hand (issue 246). `rewrite`
+       * replaces the authored values in the file's own bytes and changes nothing else, which is all
+       * a rename ever needed.
+       *
+       * `serialize` still wins where it exists: a full round trip can express a change a list of
+       * value edits cannot. A TAG rename is exactly such a change, so a document carrying one and
+       * no serializer is still named in the report rather than half-written.
+       */
+      const written =
+        serialize === null
+          ? tagCount === 0 && rewrite !== null
+            ? await rewrite(changes)
+            : null
+          : await serialize(doc);
+      if (written === null) {
         report.errors.push({ error: `No serializer for "${match}"`, path: fwd(match) });
         continue;
       }
-      await writeFile(fp, await serialize(doc));
+      await writeFile(fp, written);
 
       if (changes.length > 0) {
         report.references.files.push({ changes, count: changes.length, path: fwd(match) });

package/src/refactor/mounts.ts

@@ -19,6 +19,14 @@
  * dropped: its files are not addressable by a project-relative path, so no rename can reach them
  * and no reference to them can be counted. `projectPathsForSiteUrl` declines the same case by
  * name.
+ *
+ * That drop is deliberate and is not the near half of a bug. A collection's `source` may point
+ * outside the project (site-architecture.md §9.3), and its media renders — the compiler and the dev
+ * server both publish it at the mount URL — but the editing host's file API is project-scoped by
+ * containment check, so no surface can list, open or ask about the file either. Nothing therefore
+ * reports a confident zero about it, which is the failure the lane math exists to prevent. Reaching
+ * such a file means giving it a mount-relative identity in that file API, not widening this filter;
+ * see §9.3, which records the decision (issue 244).
  */
 
 import { relative } from "node:path";

package/src/refactor/paths.ts

@@ -179,7 +179,7 @@ const FILE_SEGMENT_RE = /^[^.][^/]*\.[A-Za-z0-9]{0,7}[A-Za-z][A-Za-z0-9]{0,7}$/;
 /**
  * True when a string is shaped like a file a document could reference.
  *
- * The walker in refs.ts knows nine keys that carry references by name. The commonest media
+ * The walker in refs.ts knows eleven keys that carry references by name. The commonest media
  * reference in a real project is under none of them — a schema-typed component prop (`$props.bg`),
  * a content entry's frontmatter (`cover:`), `project.json`'s `defaults.layout` — so the walker
  * falls back to SHAPE for every other key, and this is the shape test.
@@ -210,6 +210,19 @@ export function looksLikeFileRef(value: string): boolean {
   return FILE_SEGMENT_RE.test(last);
 }
 
+/**
+ * Restore a trailing slash the path math dropped, when the author wrote one.
+ *
+ * `normalizeSegments` discards empty segments, so `./content/posts/` resolves and re-emits as
+ * `./content/posts`. For a file that is invisible; for a DIRECTORY reference — a content
+ * collection's `source` — it is a gratuitous edit to a line the rename had no business restyling,
+ * and `rewriteRef`'s contract is to preserve the authored style. A bare `/` is left alone: it is
+ * already only a slash.
+ */
+function keepTrailingSlash(out: string, core: string): string {
+  return core.endsWith("/") && core !== "/" && !out.endsWith("/") ? `${out}/` : out;
+}
+
 /** Context describing a single rename, shared by every reference rewrite within one document. */
 export interface RemapCtx {
   /** Absolute POSIX project root. */
@@ -269,7 +282,7 @@ export function rewriteRef(
   } else {
     out = rel;
   }
-  out += suffix;
+  out = keepTrailingSlash(out, core) + suffix;
   return out === core + suffix ? null : out;
 }
 
@@ -301,7 +314,7 @@ function rewriteSiteUrl(core: string, suffix: string, ctx: RemapCtx): string | n
     if (url === null) {
       continue;
     }
-    const out = url + suffix;
+    const out = keepTrailingSlash(url, core) + suffix;
     return out === core + suffix ? null : out;
   }
   return null;

package/src/refactor/refs.ts

@@ -14,6 +14,12 @@
  * `rewriteRef`'s resolve-and-compare gate in paths.ts: a reference is only rewritten (or counted as
  * a usage) when it actually resolves to the file in question.
  *
+ * **A reference is not always a value.** Three of the four visit helpers offer a value under a
+ * container-plus-position; {@link visitKeys} offers a map's KEYS, because `project.json`'s `copy`
+ * map names the files it copies there. Everything downstream is unchanged — a key is renamed by the
+ * same visitor returning the same kind of string — but the fourth shape had to exist before the
+ * walk could see the reference at all (issue 242).
+ *
  * The visitor seam is what stops the read side from being a second, drifting copy of the key list.
  * A new reference-bearing key added below is a key the usage count sees on the same commit.
  *
@@ -40,8 +46,10 @@ export interface RewriteResult {
  *
  * @param value — the raw authored reference, exactly as written.
  * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`,
- *   or `path` for a value matched by shape rather than by key name).
- * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
+ *   `source`, `copy` for a map KEY naming a copied file, or `path` for a value matched by shape
+ *   rather than by key name).
+ * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`,
+ *   `copy`).
  * @returns A replacement string to write back, or `null` to leave the document untouched.
  */
 export type RefVisitor = (
@@ -82,6 +90,41 @@ function visitScalar(
   }
 }
 
+/**
+ * Offer every KEY of a map to the visitor, renaming in place and preserving insertion order.
+ *
+ * The fourth visit helper, and the only one whose reference is not a value. `project.json`'s `copy`
+ * map names its sources in its keys (`{"assets/brochure.pdf": "brochure.pdf"}`), so a walk that
+ * only ever offered values could not see them at all — renaming a copied file reported zero
+ * references and rewrote nothing (issue 242).
+ *
+ * Order is preserved by rebuilding rather than by deleting one key and re-adding it: a plain
+ * `delete` + set moves the renamed entry to the end, which is a diff on a file nobody edited. When
+ * a rename collides with an existing key the later entry wins, exactly as an authored duplicate
+ * would.
+ */
+function visitKeys(
+  container: Record<string, unknown>,
+  refType: string,
+  visit: RefVisitor,
+  rootRelativeBare: boolean,
+): void {
+  const entries = Object.entries(container);
+  const renamed = entries.map(([key, value]): [string, unknown] => {
+    const out = visit(key, refType, rootRelativeBare);
+    return [out === null ? key : out, value];
+  });
+  if (renamed.every(([key], i) => key === entries[i]![0])) {
+    return;
+  }
+  for (const [key] of entries) {
+    delete container[key];
+  }
+  for (const [key, value] of renamed) {
+    container[key] = value;
+  }
+}
+
 /** Offer a string array member (e.g. an `$elements` entry) to the visitor. */
 function visitIndexed(arr: unknown[], index: number, refType: string, visit: RefVisitor): void {
   const value = arr[index];
@@ -203,6 +246,35 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
         walkStyle(value, visit);
         break;
       }
+      case "copy": {
+        /*
+         * `project.json`'s declarative copy map (site-architecture.md §5). Its KEYS are project
+         * files and its VALUES are destinations inside `outDir` — a directory the project does not
+         * contain and a rename can never move. So the key is visited and the value deliberately is
+         * not: offering the value to the shape fallback, which is what happened before, meant
+         * renaming a file at the project root could rewrite an unrelated copy DESTINATION that
+         * merely shared its name.
+         */
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          visitKeys(value as Record<string, unknown>, "copy", visit, true);
+        }
+        break;
+      }
+      case "source": {
+        /*
+         * A content collection's source (site-architecture.md §6), which may name a single file
+         * (`./content/listings.csv`) or a DIRECTORY (`./content/posts/`).
+         *
+         * Named rather than left to the shape fallback because a directory has no extension, and
+         * the extension test is exactly what keeps that fallback from admitting every route and
+         * bare word. Here the key is known and the value's shape is not diagnostic, so the value is
+         * offered unconditionally and precision stays where it always was — the caller's
+         * resolve-and-compare gate, which only matches a value resolving to the file or directory
+         * in question. A remote `https://…` source is filtered by `classifyRef` before that.
+         */
+        visitScalar(obj, key, "source", visit, false);
+        break;
+      }
       /*
        * Everything else, by SHAPE.
        *

package/src/refactor/scan.ts

@@ -14,10 +14,28 @@ 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). */
+/** One authored value to replace in a document's own source text. */
+export interface ValueEdit {
+  from: string;
+  to: string;
+}
+
+/** A parsed document and the two ways it might be written back. */
 export interface LoadedDoc {
   doc: unknown;
+  /** Round-trips the whole document. Null when the format declares no `serialize`. */
   serialize: ((doc: unknown) => Promise<string>) | null;
+  /**
+   * Replaces authored values in the file's own bytes, changing nothing else. Null when the format
+   * declares no `rewrite`.
+   *
+   * The narrower of the two, and the only one a load-only format can offer: a CSV collection is a
+   * data source entries are read FROM, so there is no document to serialize — but one cell's text
+   * can be changed without inventing a quoting style. `applyRename` prefers `serialize` where it
+   * exists, because a full round trip can express a change (a tag rename) that a list of value
+   * edits cannot.
+   */
+  rewrite: ((edits: readonly ValueEdit[]) => Promise<string>) | null;
 }
 
 const isJsonPath = (p: string) => p.endsWith(".json");
@@ -58,8 +76,8 @@ export function documentGlob(registry: FormatRegistry): Bun.Glob {
 }
 
 /**
- * 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.
+ * Read + parse a file, returning the doc and whichever write-back paths the format declares. Throws
+ * when no parser claims the extension.
  */
 export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
   const raw = await readFile(fp, "utf8");
@@ -67,6 +85,7 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
     const trailingNewline = raw.endsWith("\n");
     return {
       doc: JSON.parse(raw) as unknown,
+      rewrite: null,
       serialize: (doc) =>
         Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
     };
@@ -78,8 +97,15 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
   }
   const doc = await parseEntry.call("parse", raw);
   const serializeEntry = registry.byExtension(ext, "serialize");
+  const rewriteEntry = registry.byExtension(ext, "rewrite");
   return {
     doc,
+    rewrite: rewriteEntry
+      ? async (edits) => {
+          const out = await rewriteEntry.call("rewrite", raw, edits);
+          return typeof out === "string" ? out : String(out);
+        }
+      : null,
     serialize: serializeEntry
       ? async (d) => {
           const out = await serializeEntry.call("serialize", d);

package/src/resolve.ts

@@ -1,5 +1,6 @@
 /** 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 { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -99,6 +100,22 @@ async function loadProjectEntry(projectRoot: string) {
   }
 }
 
+/**
+ * The path a project says it is deployed under, or `""` for a site at an origin root.
+ *
+ * Read off `project.json`'s `url` (`@jxsuite/schema/asset-paths`), through the same mtime-keyed
+ * cache the asset mounts use — a second cache on the same file would be a second thing to
+ * invalidate, and this is asked on every request.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} A path with a leading slash and no trailing one, or `""`
+ */
+export async function projectSiteBase(projectRoot: string): Promise<string> {
+  const entry = await loadProjectEntry(projectRoot);
+  const config = entry?.context.config as ProjectConfig | undefined;
+  return siteBasePath(config?.url);
+}
+
 /**
  * Extension asset mounts for a project (specs/extensions.md §8.5) — the directories the dev server
  * serves at their site URLs, so content-relative images resolve exactly as they will once built.

package/src/server.ts

@@ -18,7 +18,12 @@ 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 {
+  handleResolve,
+  handleServerFunction,
+  projectAssetMounts,
+  projectSiteBase,
+} from "./resolve.ts";
 import {
   assertAccessible,
   assertCreatableParent,
@@ -301,6 +306,25 @@ export async function createDevServer(options: {
       }
       // Keep the un-collapsed decoded path: the static branch detects a POSIX-absolute "//abs" prefix.
       let { path } = decoded;
+
+      /*
+       * A subpath deployment's base, stripped once at the edge (site-architecture.md §5).
+       *
+       * A project whose `url` carries a path is SERVED from that path, and a build emits every URL
+       * under it — so a preview that only answered the bare path would exercise URLs the deployed
+       * site never uses, which is the class of bug that is only found in production. Stripping
+       * rather than moving the dev root means both spellings work: `localhost:3000/` is unchanged,
+       * and `localhost:3000/m/my-site/assets/x.js` resolves to the same file.
+       *
+       * `url` is mutated too, because everything downstream routes on it — the extension mounts
+       * match `url.pathname` against their own basePath, which is declared bare.
+       */
+      const siteBase = await projectSiteBase(activeProjectRoot ?? absRoot);
+      if (siteBase !== "" && (path === siteBase || path.startsWith(`${siteBase}/`))) {
+        path = path.slice(siteBase.length) || "/";
+        url.pathname = url.pathname.slice(siteBase.length) || "/";
+      }
+
       if (path.endsWith("/")) {
         path += "index.html";
       } else if (path === "") {