@jxsuite/server 0.28.5 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.28.5",
+  "version": "0.30.1",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,7 @@
   "exports": {
     ".": "./src/server.ts",
     "./claude-session": "./src/claude-session.ts",
+    "./refactor": "./src/refactor/index.ts",
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts"
   },
@@ -27,13 +28,13 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.173",
-    "@anthropic-ai/sdk": "^0.104.1",
-    "@jxsuite/compiler": "^0.28.5",
-    "@jxsuite/create": "^0.28.5",
-    "@jxsuite/parser": "^0.28.5",
-    "@jxsuite/runtime": "^0.28.5",
-    "@jxsuite/schema": "^0.28.5",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.186",
+    "@anthropic-ai/sdk": "^0.105.0",
+    "@jxsuite/compiler": "^0.30.1",
+    "@jxsuite/create": "^0.30.1",
+    "@jxsuite/parser": "^0.30.1",
+    "@jxsuite/runtime": "^0.30.1",
+    "@jxsuite/schema": "^0.30.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chokidar": "^5.0.0",
     "zod": "^4.4.3"

package/src/claude-session.ts

@@ -136,7 +136,7 @@ export function createSession(
 
   const stream = query({ options: queryOpts, prompt: message });
   session.query = stream;
-  processStream(session, stream);
+  void processStream(session, stream);
 
   return { id };
 }
@@ -177,7 +177,7 @@ export function sendMessage(id: string, message: string) {
 
   const stream = query({ options: queryOpts, prompt: message });
   session.query = stream;
-  processStream(session, stream);
+  void processStream(session, stream);
 }
 
 /**

package/src/code-api.ts

@@ -21,6 +21,11 @@ interface OxcDiagnostic {
   [key: string]: unknown;
 }
 
+interface CodeApiBody {
+  code?: string;
+  args?: string[];
+}
+
 const OXLINT_BIN = resolve(
   import.meta.dir,
   "../../node_modules/.bin",
@@ -43,10 +48,10 @@ function unwrapFormatted(formatted: string) {
   const lines = formatted.split("\n");
   // Remove first line (function header) and last non-empty line (closing brace)
   let end = lines.length - 1;
-  while (end > 0 && lines[end].trim() === "") {
+  while (end > 0 && lines[end]!.trim() === "") {
     end -= 1;
   }
-  if (lines[end].trim() === "}") {
+  if (lines[end]!.trim() === "}") {
     end -= 1;
   }
   const bodyLines = lines.slice(1, end + 1);
@@ -90,9 +95,9 @@ export async function handleCodeApi(req: Request, url: URL) {
     return null;
   }
 
-  let body;
+  let body: CodeApiBody;
   try {
-    body = await req.json();
+    body = (await req.json()) as CodeApiBody;
   } catch {
     return new Response("Invalid JSON", { status: 400 });
   }
@@ -162,8 +167,8 @@ export async function handleCodeApi(req: Request, url: URL) {
       const output = await new Response(proc.stdout).text();
       await proc.exited;
 
-      const parsed = JSON.parse(output);
-      const adjusted = adjustDiagnostics(parsed.diagnostics || [], headerLen);
+      const parsed = JSON.parse(output) as { diagnostics?: OxcDiagnostic[] };
+      const adjusted = adjustDiagnostics(parsed.diagnostics ?? [], headerLen);
       return Response.json({ diagnostics: adjusted });
     } catch (error) {
       return Response.json({

package/src/refactor/apply.ts

@@ -0,0 +1,215 @@
+/**
+ * Apply.ts — IO orchestrator for rename-refactoring, shared by the dev-server endpoint
+ * (studio-api.ts) and the desktop project session.
+ *
+ * The caller performs the filesystem move first, then calls `applyRename`, which globs the
+ * project's document + content files, runs the pure engines from refs.ts against each, writes back
+ * only the files that changed, and returns a `RenameReport`. When the renamed file is a component,
+ * the tag is auto-derived from the new filename and renamed everywhere it is used (Pillar C).
+ */
+
+import { basename, dirname, extname, relative, resolve } from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { isUnder } from "./paths.ts";
+import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
+import type { RefChange } from "./refs.ts";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+
+/** Normalise a path to forward slashes. */
+const fwd = (p: string) => p.replaceAll("\\", "/");
+
+export interface FileChange {
+  path: string;
+  count: number;
+  changes: RefChange[];
+}
+
+export interface RenameReport {
+  ok: boolean;
+  from: string;
+  to: string;
+  isDir: boolean;
+  references: {
+    filesChanged: number;
+    refsUpdated: number;
+    files: FileChange[];
+  };
+  errors: { path: string; error: string }[];
+  tag?: { from: string; to: string; filesChanged: number; refsUpdated: number };
+  tagSkipped?: string;
+}
+
+export interface ApplyRenameOptions {
+  /** Absolute project root to scan. */
+  root: string;
+  /** Absolute path of the renamed file/dir, before the move. */
+  absFrom: string;
+  /** Absolute path of the renamed file/dir, after the move (already on disk). */
+  absTo: string;
+  /** Format registry for the project (parse/serialize of non-JSON documents). */
+  registry: FormatRegistry;
+}
+
+/** A parsed document plus the serializer that round-trips it back to disk. */
+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). */
+function skip(match: string): boolean {
+  const f = fwd(match);
+  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+}
+
+/** Derive a custom-element tag from a component filename (strips `.class.json` or the extension). */
+export function deriveTag(absPath: string): string {
+  const base = basename(absPath);
+  if (base.endsWith(".class.json")) {
+    return base.slice(0, -".class.json".length);
+  }
+  const ext = extname(base);
+  return ext ? base.slice(0, -ext.length) : base;
+}
+
+/** Read + parse a file, returning the doc and a matching serializer (null when none is available). */
+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,
+  };
+}
+
+/** Build the recursive glob covering JSON plus every registered document/content extension. */
+function documentGlob(registry: FormatRegistry) {
+  const exts = new Set(["json"]);
+  for (const ext of registry.documentExtensions()) {
+    exts.add(ext.replace(/^\./, ""));
+  }
+  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
+}
+
+/**
+ * Rewrite references (and, for components, the tag) across the project after a rename. The caller
+ * must have already moved the file on disk.
+ */
+export async function applyRename(opts: ApplyRenameOptions): Promise<RenameReport> {
+  const root = fwd(opts.root);
+  const absFrom = fwd(opts.absFrom);
+  const absTo = fwd(opts.absTo);
+
+  let isDir = false;
+  try {
+    const stats = await stat(absTo);
+    isDir = stats.isDirectory();
+  } catch {
+    isDir = false;
+  }
+
+  const report: RenameReport = {
+    errors: [],
+    from: fwd(relative(opts.root, opts.absFrom)),
+    isDir,
+    ok: true,
+    references: { files: [], filesChanged: 0, refsUpdated: 0 },
+    to: fwd(relative(opts.root, opts.absTo)),
+  };
+
+  // For a component file rename, derive the new tag from the new filename (Pillar C).
+  let tagRename: { from: string; to: string } | null = null;
+  if (!isDir) {
+    try {
+      const { doc } = await loadDoc(absTo, opts.registry);
+      const oldTag = (doc as { tagName?: unknown }).tagName;
+      const newTag = deriveTag(absTo);
+      if (typeof oldTag === "string" && oldTag.includes("-") && newTag !== oldTag) {
+        if (newTag.includes("-")) {
+          tagRename = { from: oldTag, to: newTag };
+        } else {
+          report.tagSkipped = `Tag "${oldTag}" left unchanged: "${newTag}" is not a valid custom-element name`;
+        }
+      }
+    } catch {
+      // Not a parseable component — skip tag derivation.
+    }
+  }
+
+  let tagFilesChanged = 0;
+  let tagRefsUpdated = 0;
+
+  for await (const match of documentGlob(opts.registry).scan({ cwd: opts.root, dot: false })) {
+    if (skip(match)) {
+      continue;
+    }
+    const fp = fwd(resolve(opts.root, match));
+    try {
+      const { doc, serialize } = await loadDoc(fp, opts.registry);
+      const docNewDir = dirname(fp);
+      const docOldDir = isUnder(fp, absTo) ? dirname(absFrom + fp.slice(absTo.length)) : docNewDir;
+
+      const { changes } = rewriteDocRefs(doc, {
+        docNewDir,
+        docOldDir,
+        newAbs: absTo,
+        oldAbs: absFrom,
+        root,
+      });
+      const tagCount = tagRename ? rewriteTagName(doc, tagRename.from, tagRename.to).count : 0;
+
+      if (changes.length === 0 && tagCount === 0) {
+        continue;
+      }
+      if (!serialize) {
+        report.errors.push({ error: `No serializer for "${match}"`, path: fwd(match) });
+        continue;
+      }
+      await writeFile(fp, await serialize(doc));
+
+      if (changes.length > 0) {
+        report.references.files.push({ changes, count: changes.length, path: fwd(match) });
+        report.references.filesChanged += 1;
+        report.references.refsUpdated += changes.length;
+      }
+      if (tagCount > 0) {
+        tagFilesChanged += 1;
+        tagRefsUpdated += tagCount;
+      }
+    } catch (error) {
+      report.errors.push({ error: errorMessage(error), path: fwd(match) });
+    }
+  }
+
+  if (tagRename) {
+    report.tag = {
+      filesChanged: tagFilesChanged,
+      from: tagRename.from,
+      refsUpdated: tagRefsUpdated,
+      to: tagRename.to,
+    };
+  }
+  return report;
+}

package/src/refactor/fs-events.ts

@@ -0,0 +1,71 @@
+/**
+ * Fs-events.ts — pure translation + coalescing of chokidar events into the wire payloads the studio
+ * sidebar consumes. No filesystem access (node:path.relative is a pure string op), so it is shared
+ * by the dev-server watcher (watch.ts) and the desktop project session, and unit-tests directly.
+ */
+
+import { relative } from "node:path";
+
+/** A filesystem change as broadcast to the studio shell (root-relative, forward-slashed path). */
+export interface FsEventPayload {
+  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
+  path: string;
+  isDir: boolean;
+}
+
+const VALID = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
+
+/**
+ * Map one chokidar event to a payload, or null for events we ignore (`ready`/`raw`/`error`) or
+ * paths that escape the root.
+ */
+export function toFsEvent(
+  eventType: string,
+  root: string,
+  changedPath: string,
+): FsEventPayload | null {
+  if (!VALID.has(eventType)) {
+    return null;
+  }
+  const path = relative(root, changedPath).replaceAll("\\", "/");
+  if (!path || path.startsWith("..")) {
+    return null;
+  }
+  return {
+    isDir: eventType === "addDir" || eventType === "unlinkDir",
+    path,
+    type: eventType as FsEventPayload["type"],
+  };
+}
+
+/**
+ * Fold one event into a buffer, collapsing redundant churn per path (last-write-wins, except
+ * add+unlink cancels, add+change stays add, and unlink+add becomes a re-add). Returns a new array.
+ */
+export function coalesceFsEvents(buffer: FsEventPayload[], next: FsEventPayload): FsEventPayload[] {
+  const prev = buffer.find((e) => e.path === next.path);
+  if (!prev) {
+    return [...buffer, next];
+  }
+  const index = buffer.indexOf(prev);
+  const out = [...buffer];
+  // A file (or dir) created then removed within the window is a no-op.
+  if (
+    (prev.type === "add" && next.type === "unlink") ||
+    (prev.type === "addDir" && next.type === "unlinkDir")
+  ) {
+    out.splice(index, 1);
+    return out;
+  }
+  // A content change after a create is still just a create.
+  if ((prev.type === "add" || prev.type === "addDir") && next.type === "change") {
+    return out;
+  }
+  // Removed then recreated → treat as a fresh add.
+  if (prev.type === "unlink" && next.type === "add") {
+    out[index] = next;
+    return out;
+  }
+  out[index] = next;
+  return out;
+}

package/src/refactor/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Public entrypoint for the rename-refactor engine (`@jxsuite/server/refactor`), shared by the
+ * dev-server endpoint and the desktop project session.
+ */
+
+export { applyRename, deriveTag } from "./apply.ts";
+export type { ApplyRenameOptions, FileChange, RenameReport } from "./apply.ts";
+export { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+export type { FsEventPayload } from "./fs-events.ts";
+export { createFsWatcher } from "./watcher.ts";
+export type { FsWatcherHandle } from "./watcher.ts";

package/src/refactor/paths.ts

@@ -0,0 +1,187 @@
+/**
+ * Paths.ts — pure, OS-independent path math for the rename-refactor engine.
+ *
+ * Everything here operates on forward-slash POSIX strings and never touches the filesystem, so it
+ * unit-tests deterministically. Callers (apply.ts) normalise real paths with `fwd()` before handing
+ * them in. The relative-path style mirrors `computeRelativePath` in the studio
+ * (packages/studio/src/files/components.ts): "./" for same-dir/descendant targets, "../"-chains
+ * otherwise.
+ */
+
+/** Classification of a reference string value. */
+export type RefClass =
+  | { kind: "none" }
+  | { kind: "state" }
+  | { kind: "external" }
+  | { kind: "path"; core: string; suffix: string; rooted: boolean };
+
+/** Split a trailing `?query` or `#fragment` off a path-like value. */
+export function splitQueryHash(value: string): { core: string; suffix: string } {
+  for (let i = 0; i < value.length; i += 1) {
+    const ch = value[i];
+    if (ch === "?" || ch === "#") {
+      return { core: value.slice(0, i), suffix: value.slice(i) };
+    }
+  }
+  return { core: value, suffix: "" };
+}
+
+/**
+ * Classify a reference value. State-scope refs (`#/state/…`, `$map/…`, `parent#…`, `window#…`,
+ * `document#…`) and external URLs (`http:`, `data:`, protocol-relative `//…`) are never file paths.
+ * Everything else is treated as a `path`; the resolve-and-compare gate in `rewriteRef` provides the
+ * actual precision, so bare npm specifiers (which never resolve to the renamed file) are simply
+ * never matched.
+ */
+export function classifyRef(value: unknown): RefClass {
+  if (typeof value !== "string" || value.length === 0) {
+    return { kind: "none" };
+  }
+  if (
+    value === "$map" ||
+    value.startsWith("#") ||
+    value.startsWith("$map/") ||
+    value.startsWith("parent#") ||
+    value.startsWith("window#") ||
+    value.startsWith("document#")
+  ) {
+    return { kind: "state" };
+  }
+  // Absolute URL with a scheme (http:, data:, mailto:) or protocol-relative (//host).
+  if (value.startsWith("//") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) {
+    return { kind: "external" };
+  }
+  const { core, suffix } = splitQueryHash(value);
+  if (core.length === 0) {
+    return { kind: "none" };
+  }
+  return { core, kind: "path", rooted: core.startsWith("/"), suffix };
+}
+
+/** Collapse `.`/`..` segments in a POSIX path. Absolute paths cannot escape above root. */
+export function normalizeSegments(path: string): string {
+  const isAbs = path.startsWith("/");
+  const out: string[] = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      if (out.length > 0 && out.at(-1) !== "..") {
+        out.pop();
+      } else if (!isAbs) {
+        out.push("..");
+      }
+      continue;
+    }
+    out.push(part);
+  }
+  return (isAbs ? "/" : "") + out.join("/");
+}
+
+/**
+ * Join `rel` onto an absolute POSIX `base` and normalise (a leading "/" on rel still joins to
+ * base).
+ */
+export function joinPosix(base: string, rel: string): string {
+  return normalizeSegments(`${base}/${rel}`);
+}
+
+/**
+ * Relative path from directory `fromDir` to `to` (both absolute POSIX). Returns a bare path for
+ * descendants ("a/b.json") and "../"-chains otherwise — without a leading "./" (callers add it to
+ * preserve author style).
+ */
+export function relativeChain(fromDir: string, to: string): string {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const toParts = to.split("/").filter(Boolean);
+  let common = 0;
+  while (
+    common < fromParts.length &&
+    common < toParts.length &&
+    fromParts[common] === toParts[common]
+  ) {
+    common += 1;
+  }
+  const ups = fromParts.length - common;
+  const remaining = toParts.slice(common);
+  return (ups > 0 ? "../".repeat(ups) : "") + remaining.join("/");
+}
+
+/** True when `p` is `dir` itself or nested under it. */
+export function isUnder(p: string, dir: string): boolean {
+  return p === dir || p.startsWith(`${dir}/`);
+}
+
+/**
+ * Remap a resolved absolute target across a rename. If the target is the renamed file (or under the
+ * renamed directory), re-root it onto the new location; otherwise it is unaffected.
+ */
+export function remapTarget(targetOld: string, oldAbs: string, newAbs: string): string {
+  if (targetOld === oldAbs) {
+    return newAbs;
+  }
+  if (isUnder(targetOld, oldAbs)) {
+    return newAbs + targetOld.slice(oldAbs.length);
+  }
+  return targetOld;
+}
+
+/** Context describing a single rename, shared by every reference rewrite within one document. */
+export interface RemapCtx {
+  /** Absolute POSIX project root. */
+  root: string;
+  /** Absolute POSIX path of the renamed file/dir, before the move. */
+  oldAbs: string;
+  /** Absolute POSIX path of the renamed file/dir, after the move. */
+  newAbs: string;
+  /** Directory the referencing document lived in before the move. */
+  docOldDir: string;
+  /**
+   * Directory the referencing document lives in after the move (differs from docOldDir only when
+   * the document itself is inside the moved subtree).
+   */
+  docNewDir: string;
+}
+
+/**
+ * Recompute a single path reference for a rename, preserving its original style. Returns the new
+ * string, or null when nothing changes.
+ *
+ * `rootRelativeBare` makes a bare value (no "./" or "../") resolve against the project root rather
+ * than the document directory — used for `$layout`, which the compiler resolves against projectRoot
+ * (layout-resolver.ts), and for site-relative conventions.
+ */
+export function rewriteRef(
+  cls: { core: string; suffix: string; rooted: boolean },
+  ctx: RemapCtx,
+  rootRelativeBare = false,
+): string | null {
+  const { core, rooted, suffix } = cls;
+  const startsRel = core.startsWith("./") || core.startsWith("../");
+  const useRoot = rooted || (rootRelativeBare && !startsRel);
+  const baseOld = useRoot ? ctx.root : ctx.docOldDir;
+  const baseNew = useRoot ? ctx.root : ctx.docNewDir;
+
+  const targetOld = joinPosix(useRoot ? ctx.root : baseOld, core);
+  const targetNew = remapTarget(targetOld, ctx.oldAbs, ctx.newAbs);
+  if (targetNew === targetOld && baseOld === baseNew) {
+    return null;
+  }
+
+  let out: string;
+  if (rooted) {
+    out = `/${relativeChain(ctx.root, targetNew)}`;
+  } else {
+    const rel = relativeChain(baseNew, targetNew);
+    if (rel.startsWith("..")) {
+      out = rel;
+    } else if (core.startsWith("./")) {
+      out = `./${rel}`;
+    } else {
+      out = rel;
+    }
+  }
+  out += suffix;
+  return out === core + suffix ? null : out;
+}