@jxsuite/server 1.3.0 → 2.1.0

package/src/studio-api.ts

@@ -10,7 +10,9 @@
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
 import {
   buildExtensionsPayload,
   buildProjectExtensionRegistry,
@@ -18,7 +20,9 @@ import {
 import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
 import { handleDataApi } from "./data-api.ts";
 import { containedPath } from "./net-guard.ts";
+import { startSitePreview } from "./site-preview.ts";
 import { applyRename } from "./refactor/apply.ts";
+import { findReferences } from "./refactor/find-refs.ts";
 import {
   bunExecutable,
   dependenciesNeedInstall,
@@ -31,6 +35,7 @@ import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ClassJsonDef } from "./types.ts";
 import type { DesignOptions } from "@jxsuite/create/generate";
 import type { ProjectConfig } from "@jxsuite/schema/types";
+import { problem } from "./problem.ts";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -175,6 +180,57 @@ export function assertAccessible(filePath: string, root: string, activeProjectRo
   throw new Error("Path outside project root");
 }
 
+/**
+ * Check that a NEW project may be scaffolded under `parent` (specs/server.md §4.2).
+ *
+ * Deliberately wider than {@link assertAccessible}: a new project is normally created _outside_ the
+ * server root — the whole point of the modal's Location field — so root containment cannot apply.
+ * What it still refuses is a destination the user did not name (relative paths) and anything
+ * outside the places a person keeps projects: the server root, any configured `allowedRoots`, and
+ * the account's home directory. That keeps a hostile page on the loopback origin from scaffolding
+ * into system paths while leaving every realistic location reachable.
+ *
+ * @param {string} parent
+ * @param {string} root
+ * @param {string[]} allowedRoots
+ */
+export function assertCreatableParent(parent: string, root: string, allowedRoots: string[] = []) {
+  if (!parent || !isAbsolute(parent)) {
+    throw new Error("Destination folder must be an absolute path");
+  }
+  const bases = [root, ...allowedRoots, homedir()].filter(Boolean);
+  if (bases.some((base) => containedPath(parent, resolve(base)) !== null)) {
+    return;
+  }
+  throw new Error(
+    "Destination folder is outside the permitted roots (the server root, an allowed root, or your home directory)",
+  );
+}
+
+/**
+ * True when `dir` is a Jx project this account already owns: an absolute directory holding a
+ * `project.json`, somewhere under the user's home directory (specs/server.md §4.2).
+ *
+ * Existing projects live outside the server root as a matter of course — the dev server serving
+ * this monorepo is not where anyone keeps their sites — so root containment alone would leave
+ * `?project=/abs/path`, the Open Project picker, and the recent-projects list unable to activate
+ * anything but a project inside the checkout. This admits those without opening the filesystem API
+ * to arbitrary directories: a hostile page on the loopback origin still cannot bind the server to
+ * `/etc` or another account's files, only to a project the account already has on disk.
+ *
+ * @param {string} dir
+ */
+export function isOwnedProjectDir(dir: string): boolean {
+  const home = homedir();
+  if (!home || !dir || !isAbsolute(dir)) {
+    return false;
+  }
+  if (containedPath(dir, resolve(home)) === null) {
+    return false;
+  }
+  return existsSync(resolve(dir, "project.json"));
+}
+
 const statusMap: Record<string, string> = {
   A: "A",
   C: "C",
@@ -253,6 +309,18 @@ export function parseGitStatus(out: string) {
   return { ahead, behind, branch, files };
 }
 
+/** Host hooks for the routes that reach outside the server root (project creation). */
+export interface StudioApiOptions {
+  /** Extra roots a new project may be created under, mirroring `createDevServer.allowedRoots`. */
+  allowedRoots?: string[];
+  /**
+   * Called with the absolute root of a project this API just created, so the host can permit a
+   * subsequent `/__studio/activate` on it — a project created outside the server root is otherwise
+   * unreachable by the very request that made it.
+   */
+  onProjectCreated?: (projectRoot: string) => void;
+}
+
 /**
  * Handle /__studio/* requests.
  *
@@ -260,13 +328,38 @@ export function parseGitStatus(out: string) {
  * @param {URL} url
  * @param {string} root
  * @param {string | null} [activeProjectRoot]
+ * @param {StudioApiOptions} [opts]
  * @returns {Promise<Response | null>}
  */
+/**
+ * The paths git reported as conflicting, from a failed merge or pull's output.
+ *
+ * Parsed from the porcelain text because there is no machine-readable form of it: `git pull` writes
+ * `CONFLICT (content): Merge conflict in <path>` to stdout and exits non-zero, and the alternative
+ * — a second `git diff --name-only --diff-filter=U` — would be a separate command whose answer
+ * could already have changed. An empty result means the failure was not a conflict, and the caller
+ * rethrows rather than mislabelling it.
+ *
+ * @param {string} output - Combined git output from the failed command
+ * @returns {string[]} Conflicting paths, deduplicated, in the order git reported them
+ */
+function conflictingPaths(output: string): string[] {
+  const paths = new Set<string>();
+  for (const line of output.split("\n")) {
+    const match = /^CONFLICT \([^)]*\): Merge conflict in (.+)$/.exec(line.trim());
+    if (match?.[1]) {
+      paths.add(match[1].trim());
+    }
+  }
+  return [...paths];
+}
+
 export async function handleStudioApi(
   req: Request,
   url: URL,
   root: string,
   activeProjectRoot: string | null = null,
+  opts: StudioApiOptions = {},
 ) {
   const path = url.pathname;
 
@@ -297,7 +390,7 @@ export async function handleStudioApi(
     try {
       assertAccessible(absDir, root, activeProjectRoot);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
     try {
       const projectRoot = fwd(absDir);
@@ -337,7 +430,7 @@ export async function handleStudioApi(
         projectRoot,
       });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -345,7 +438,7 @@ export async function handleStudioApi(
   if (path === "/__studio/resolve-site" && req.method === "GET") {
     const filePath = url.searchParams.get("path");
     if (!filePath) {
-      return Response.json({ error: "Missing path param" }, { status: 400 });
+      return problem("invalidRequest", "Missing path param");
     }
     try {
       // Walk up looking for project.json. Accept a directory (e.g. the project root itself, as
@@ -384,7 +477,7 @@ export async function handleStudioApi(
       }
       return Response.json({ sitePath: null });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -393,7 +486,7 @@ export async function handleStudioApi(
   if (path === "/__studio/find-project" && req.method === "GET") {
     const name = url.searchParams.get("name");
     if (!name) {
-      return Response.json({ error: "Missing name" }, { status: 400 });
+      return problem("invalidRequest", "Missing name");
     }
     try {
       const home = process.env.HOME || process.env.USERPROFILE || "";
@@ -412,7 +505,75 @@ export async function handleStudioApi(
       } catch {}
       return Response.json({ path: null });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
+    }
+  }
+
+  /*
+   * Recover the absolute path of a directory the browser picked with `showDirectoryPicker()`.
+   *
+   * A `FileSystemDirectoryHandle` exposes only `.name`, never a filesystem path (§8.2), and unlike
+   * /__studio/find-project there is no `project.json` to search for — the whole point is that the
+   * folder is empty. So the client tags the folder with a hidden LOCATION_ID_FILE holding a random
+   * id and asks us which directory carries that id.
+   *
+   * Identity lives in the file's CONTENTS, not its name: matching the id is exact where matching a
+   * path shape is only probable — two folders can share a basename, and a file left behind by a
+   * crashed session can still be on disk. A candidate whose contents do not equal `id` is skipped,
+   * so a stale tag can never redirect a create. The winning file is deleted here, the moment it has
+   * served its purpose, rather than being left for the client to tidy up.
+   */
+  if (path === "/__studio/locate-directory" && req.method === "GET") {
+    const name = url.searchParams.get("name");
+    const id = url.searchParams.get("id");
+    // `name` is interpolated into a glob; the id is only ever compared, never used as a pattern.
+    if (!name || !id || !/^[a-f0-9]{32}$/.test(id) || !/^[^/\\]+$/.test(name)) {
+      return problem("invalidRequest", "Missing or invalid name/id");
+    }
+    try {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      if (!home) {
+        return Response.json({ path: null });
+      }
+      /** The tagged directory when this candidate holds our id, else null. */
+      const claim = (dir: string): string | null => {
+        const file = resolve(dir, LOCATION_ID_FILE);
+        try {
+          if (readFileSync(file, "utf8").trim() !== id) {
+            return null;
+          }
+        } catch {
+          return null;
+        }
+        try {
+          unlinkSync(file);
+        } catch {
+          // Read-only or already gone; the client's own cleanup is the backstop.
+        }
+        return dir;
+      };
+
+      // The home directory itself is a legitimate pick, and no `**/<name>/` glob can match it.
+      const atHome = claim(home);
+      if (atHome) {
+        return Response.json({ path: atHome });
+      }
+      // `dot: true` — the tag is a dotfile, so a dot-blind scan would never see it.
+      const glob = new Bun.Glob(`**/${name}/${LOCATION_ID_FILE}`);
+      try {
+        for await (const match of glob.scan({ cwd: home, dot: true })) {
+          if (match.includes("node_modules") || match.includes(".Trash")) {
+            continue;
+          }
+          const claimed = claim(resolve(home, dirname(match)));
+          if (claimed) {
+            return Response.json({ path: claimed });
+          }
+        }
+      } catch {}
+      return Response.json({ path: null });
+    } catch (error) {
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -440,7 +601,7 @@ export async function handleStudioApi(
       }
       return Response.json(sites);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -453,6 +614,7 @@ export async function handleStudioApi(
         url?: string;
         adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
         directory?: string;
+        destination?: { kind?: string; parent?: string };
         starter?: string;
         template?: string;
         design?: DesignOptions;
@@ -463,19 +625,37 @@ export async function handleStudioApi(
         url: siteUrl,
         adapter,
         directory,
+        destination,
         starter,
         template,
         design,
       } = body;
       if (!name || !directory) {
-        return Response.json({ error: "name and directory are required" }, { status: 400 });
+        return problem("invalidRequest", "name and directory are required");
+      }
+      // The destination is the user's to choose (specs/server.md §4.2). Without one the project
+      // Would silently land under the server root — which, when the dev server is the jx checkout,
+      // Means scaffolding into the monorepo. Refuse instead of guessing.
+      if (destination?.kind !== "path" || !destination.parent) {
+        return problem("invalidRequest", "A destination folder is required.");
+      }
+      // `directory` names the project FOLDER, not a path: a separator or dot-segment would walk out
+      // Of the parent that was just vetted below, which is exactly what the vetting is for.
+      if (/[/\\]/.test(directory) || directory === "." || directory === "..") {
+        return problem("invalidRequest", "Directory must be a folder name, not a path");
       }
       const { isTemplateId } = await import("@jxsuite/create/templates");
       if (template !== undefined && !isTemplateId(template)) {
-        return Response.json({ error: `Unknown template: "${template}"` }, { status: 400 });
+        return problem("invalidRequest", `Unknown template: "${template}"`);
       }
-      const destPath = resolve(root, directory);
-      assertAccessible(destPath, root, activeProjectRoot);
+      // A bad destination is client input, so answer 400 rather than letting the guard's throw fall
+      // Through to the catch-all 500 below.
+      try {
+        assertCreatableParent(destination.parent, root, opts.allowedRoots);
+      } catch (error) {
+        return problem("invalidRequest", errorMessage(error));
+      }
+      const destPath = resolve(destination.parent, directory);
 
       const { generateProject } = await import("@jxsuite/create/generate");
       await generateProject(destPath, {
@@ -491,10 +671,14 @@ export async function handleStudioApi(
       const config = JSON.parse(
         await readFile(resolve(destPath, "project.json"), "utf8"),
       ) as ProjectConfig;
-      const projectRoot = fwd(relative(root, destPath));
-      return Response.json({ config, root: projectRoot });
+      // Root-relative while the project happens to sit under the server root (the historical
+      // Shape every caller already handles); absolute otherwise, which is the same shape
+      // /__studio/find-project returns for an external project.
+      const inRoot = containedPath(destPath, root) !== null;
+      opts.onProjectCreated?.(destPath);
+      return Response.json({ config, root: inRoot ? fwd(relative(root, destPath)) : destPath });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -504,7 +688,7 @@ export async function handleStudioApi(
       const { listStarters } = await import("@jxsuite/starters");
       return Response.json(listStarters());
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -516,7 +700,7 @@ export async function handleStudioApi(
     try {
       assertAccessible(absDir, root, activeProjectRoot);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
 
     /** Report a path relative to the active project root (or server root as fallback). */
@@ -569,7 +753,7 @@ export async function handleStudioApi(
       }
       return Response.json(files);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -580,7 +764,7 @@ export async function handleStudioApi(
     try {
       assertAccessible(scanRoot, root, activeProjectRoot);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
     try {
       const registry = await getFormatRegistry(scanRoot);
@@ -721,7 +905,46 @@ export async function handleStudioApi(
 
       return Response.json(components);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
+    }
+  }
+
+  // ─── Site build ──────────────────────────────────────────────────────────────
+
+  /**
+   * Build the site, so `View: Open in Browser` opens what the author is looking at.
+   *
+   * The compiler is imported dynamically for the same reason `dev.ts` does it: the server depends
+   * on the compiler for this one call, and a static import would pull the whole build pipeline into
+   * every server process that never builds anything.
+   *
+   * Build errors come back in the payload rather than as a 500. A partial build still produced
+   * pages, and the author is better served by opening the page they asked for with the failures
+   * named beside it than by a preview that refuses and says only "500".
+   *
+   * The reply carries the ORIGIN to open the result at, not just the counts, because the built site
+   * is served on its own port ({@link file://./site-preview.ts}) rather than on this one — the
+   * caller has no way to know that port and no business guessing it.
+   */
+  if (path === "/__studio/build" && req.method === "POST") {
+    const dir = activeProjectRoot ?? root;
+    if (!existsSync(resolve(dir, "project.json"))) {
+      return problem("invalidRequest", "Not a site project");
+    }
+    try {
+      const { buildSite } = await import("@jxsuite/compiler/site");
+      // `clean: false` — this runs on the way to opening a page, and wiping the output directory
+      // First would mean every asset 404s for as long as the build takes.
+      const result = await buildSite(dir, { clean: false, verbose: false });
+      const preview = startSitePreview(dir);
+      return Response.json({
+        errors: result.errors,
+        files: result.files,
+        routes: result.routes,
+        ...(preview ? { url: preview.origin } : {}),
+      });
+    } catch (error) {
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -769,7 +992,7 @@ export async function handleStudioApi(
       }
       return Response.json(packages);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -777,7 +1000,7 @@ export async function handleStudioApi(
   if (path === "/__studio/cem" && req.method === "GET") {
     const pkg = url.searchParams.get("pkg");
     if (!pkg) {
-      return new Response("Missing pkg", { status: 400 });
+      return problem("invalidRequest", "Missing pkg");
     }
     const dir = url.searchParams.get("dir") || activeProjectRoot || root;
     const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
@@ -803,7 +1026,7 @@ export async function handleStudioApi(
       const cem = JSON.parse(await readFile(cemPath, "utf8")) as Cem;
       return Response.json({ cem });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -813,7 +1036,7 @@ export async function handleStudioApi(
       const body = (await req.json()) as { name?: string; dir?: string; dev?: boolean };
       const { name } = body;
       if (!name || typeof name !== "string") {
-        return Response.json({ error: "Missing name" }, { status: 400 });
+        return problem("invalidRequest", "Missing name");
       }
       const dir = body.dir || activeProjectRoot;
       const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
@@ -829,14 +1052,11 @@ export async function handleStudioApi(
       const exitCode = await proc.exited;
       if (exitCode !== 0) {
         const stderr = await new Response(proc.stderr).text();
-        return Response.json(
-          { error: stderr || `bun add exited with ${exitCode}` },
-          { status: 500 },
-        );
+        return problem("internalError", stderr || `bun add exited with ${exitCode}`);
       }
       return Response.json({ ok: true });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -846,7 +1066,7 @@ export async function handleStudioApi(
       const body = (await req.json()) as { name?: string; dir?: string };
       const { name } = body;
       if (!name || typeof name !== "string") {
-        return Response.json({ error: "Missing name" }, { status: 400 });
+        return problem("invalidRequest", "Missing name");
       }
       const dir = body.dir || activeProjectRoot;
       const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
@@ -858,14 +1078,11 @@ export async function handleStudioApi(
       const exitCode = await proc.exited;
       if (exitCode !== 0) {
         const stderr = await new Response(proc.stderr).text();
-        return Response.json(
-          { error: stderr || `bun remove exited with ${exitCode}` },
-          { status: 500 },
-        );
+        return problem("internalError", stderr || `bun remove exited with ${exitCode}`);
       }
       return Response.json({ ok: true });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -877,7 +1094,7 @@ export async function handleStudioApi(
       const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
       return Response.json(await installDependencies(scanRoot));
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -895,7 +1112,7 @@ export async function handleStudioApi(
       const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
       return Response.json(await outdatedPackages(scanRoot));
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -907,13 +1124,13 @@ export async function handleStudioApi(
         updates?: { name: string; version: string; dev?: boolean }[];
       };
       if (!Array.isArray(body.updates)) {
-        return Response.json({ error: "Missing updates" }, { status: 400 });
+        return problem("invalidRequest", "Missing updates");
       }
       const dir = body.dir || activeProjectRoot || root;
       const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
       return Response.json(await setPackageVersions(scanRoot, body.updates));
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -921,7 +1138,7 @@ export async function handleStudioApi(
   if (path === "/__studio/file" && req.method === "GET") {
     const fp = url.searchParams.get("path");
     if (!fp) {
-      return new Response("Missing path", { status: 400 });
+      return problem("invalidRequest", "Missing path");
     }
     const abs = expandTilde(fp);
     try {
@@ -939,8 +1156,8 @@ export async function handleStudioApi(
       );
     } catch (error) {
       return (error as NodeJS.ErrnoException).code === "ENOENT"
-        ? new Response("Not found", { status: 404 })
-        : Response.json({ error: errorMessage(error) }, { status: 500 });
+        ? problem("notFound", "Not found")
+        : problem("internalError", errorMessage(error));
     }
   }
 
@@ -948,7 +1165,7 @@ export async function handleStudioApi(
   if (path === "/__studio/file" && req.method === "PUT") {
     const fp = url.searchParams.get("path");
     if (!fp) {
-      return new Response("Missing path", { status: 400 });
+      return problem("invalidRequest", "Missing path");
     }
     const abs = resolve(root, fp);
     try {
@@ -961,7 +1178,7 @@ export async function handleStudioApi(
       await writeFile(abs, await req.text(), "utf8");
       return Response.json({ ok: true, path: fwd(relative(root, abs)) });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -969,7 +1186,7 @@ export async function handleStudioApi(
   if (path === "/__studio/file/upload" && req.method === "POST") {
     const fp = url.searchParams.get("path");
     if (!fp) {
-      return new Response("Missing path", { status: 400 });
+      return problem("invalidRequest", "Missing path");
     }
     const abs = resolve(root, fp);
     try {
@@ -983,7 +1200,7 @@ export async function handleStudioApi(
       await Bun.write(abs, new Uint8Array(buffer));
       return Response.json({ ok: true, path: fwd(relative(root, abs)) });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -991,7 +1208,7 @@ export async function handleStudioApi(
   if (path === "/__studio/file" && req.method === "DELETE") {
     const fp = url.searchParams.get("path");
     if (!fp) {
-      return new Response("Missing path", { status: 400 });
+      return problem("invalidRequest", "Missing path");
     }
     const abs = resolve(root, fp);
     try {
@@ -1004,8 +1221,8 @@ export async function handleStudioApi(
       return Response.json({ ok: true, path: fwd(relative(root, abs)) });
     } catch (error) {
       return (error as NodeJS.ErrnoException).code === "ENOENT"
-        ? new Response("Not found", { status: 404 })
-        : Response.json({ error: errorMessage(error) }, { status: 500 });
+        ? problem("notFound", "Not found")
+        : problem("internalError", errorMessage(error));
     }
   }
 
@@ -1015,11 +1232,11 @@ export async function handleStudioApi(
     try {
       body = (await req.json()) as { from?: string; to?: string };
     } catch {
-      return new Response("Invalid JSON", { status: 400 });
+      return problem("invalidRequest", "Invalid JSON");
     }
     const { from, to } = body;
     if (!from || !to) {
-      return new Response("Missing from or to", { status: 400 });
+      return problem("invalidRequest", "Missing from or to");
     }
     const absFrom = resolve(root, from);
     const absTo = resolve(root, to);
@@ -1033,7 +1250,7 @@ export async function handleStudioApi(
       await mkdir(dirname(absTo), { recursive: true });
       await rename(absFrom, absTo);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
     // Refactor pass: rewrite path references project-wide and, for a component, auto-rename its tag.
     // The move already succeeded, so a refactor failure is reported but never fails the rename.
@@ -1052,17 +1269,42 @@ export async function handleStudioApi(
     }
   }
 
+  // Where a file / component tag is used (the read side of the rename refactor's walker)
+  if (path === "/__studio/references" && req.method === "GET") {
+    const target = url.searchParams.get("path");
+    const tag = url.searchParams.get("tag");
+    if (!target && !tag) {
+      return problem("invalidRequest", "Missing path or tag");
+    }
+    const scanRoot = activeProjectRoot ?? root;
+    if (target) {
+      try {
+        assertAccessible(resolve(scanRoot, target), root, activeProjectRoot);
+      } catch (error) {
+        return new Response(errorMessage(error), { status: 400 });
+      }
+    }
+    try {
+      const registry = await getFormatRegistry(scanRoot);
+      return Response.json(
+        await findReferences({ path: target, registry, root: scanRoot, tagName: tag }),
+      );
+    } catch (error) {
+      return problem("internalError", errorMessage(error));
+    }
+  }
+
   // Locate a file by name within the project root
   if (path === "/__studio/locate" && req.method === "POST") {
     let body: { name?: string };
     try {
       body = (await req.json()) as { name?: string };
     } catch {
-      return new Response("Invalid JSON", { status: 400 });
+      return problem("invalidRequest", "Invalid JSON");
     }
     const { name } = body;
     if (!name) {
-      return new Response("Missing name", { status: 400 });
+      return problem("invalidRequest", "Missing name");
     }
 
     try {
@@ -1083,7 +1325,7 @@ export async function handleStudioApi(
         ...(matches.length > 1 ? { alternatives: matches } : {}),
       });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -1101,17 +1343,17 @@ export async function handleStudioApi(
     ];
     const cfToken = req.headers.get("X-CF-Token");
     if (!cfToken) {
-      return Response.json({ error: "Missing X-CF-Token header" }, { status: 401 });
+      return problem("unauthorized", "Missing X-CF-Token header");
     }
     let payload: { path?: string; method?: string; body?: unknown };
     try {
       payload = (await req.json()) as typeof payload;
     } catch {
-      return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+      return problem("invalidRequest", "Invalid JSON body");
     }
     const apiPath = payload.path ?? "";
     if (!CF_PROXY_ALLOWLIST.some((re) => re.test(apiPath))) {
-      return Response.json({ error: `Path not allowed: ${apiPath}` }, { status: 403 });
+      return problem("forbidden", `Path not allowed: ${apiPath}`);
     }
     const method = payload.method ?? "GET";
     const upstream = await fetch(`https://api.cloudflare.com/client/v4${apiPath}`, {
@@ -1146,18 +1388,15 @@ export async function handleStudioApi(
       assertAccessible(projectRoot, root, activeProjectRoot);
 
       if (!format || !action) {
-        return Response.json({ error: "Missing format or action" }, { status: 400 });
+        return problem("invalidRequest", "Missing format or action");
       }
       if (action !== "parse" && action !== "serialize") {
-        return Response.json({ error: `Unsupported action "${action}"` }, { status: 400 });
+        return problem("invalidRequest", `Unsupported action "${action}"`);
       }
       const registry = await getFormatRegistry(projectRoot);
       const entry = registry.byName(format);
       if (!entry) {
-        return Response.json(
-          { error: `Format "${format}" is not an imported format class` },
-          { status: 404 },
-        );
+        return problem("notFound", `Format "${format}" is not an imported format class`);
       }
       const result =
         action === "parse"
@@ -1165,7 +1404,7 @@ export async function handleStudioApi(
           : await entry.call("serialize", doc ?? {}, options);
       return Response.json({ result });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -1193,7 +1432,7 @@ export async function handleStudioApi(
         })),
       });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
   }
 
@@ -1206,13 +1445,13 @@ export async function handleStudioApi(
     try {
       assertAccessible(projectRoot, root, activeProjectRoot);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
     try {
       const { document, project } = await readBundledProjectSchemas(projectRoot);
       return Response.json({ document, project });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -1221,7 +1460,7 @@ export async function handleStudioApi(
     const prototype = url.searchParams.get("prototype");
     const base = url.searchParams.get("base");
     if (!src) {
-      return new Response("Missing src param", { status: 400 });
+      return problem("invalidRequest", "Missing src param");
     }
 
     let moduleAbsPath;
@@ -1326,7 +1565,17 @@ export async function handleStudioApi(
       const stdout = await new Response(proc.stdout).text();
       const stderr = await new Response(proc.stderr).text();
       if (exitCode !== 0) {
-        throw new Error(stderr || `git exited with ${exitCode}`);
+        /*
+         * Both streams, because git splits its failures across them and stderr alone loses the
+         * ones that matter most. A conflicting `git pull` writes every `CONFLICT (…)` line to
+         * STDOUT and leaves stderr empty — so the old `stderr || "git exited with 1"` turned the
+         * one failure this API publishes a shape for into a contentless message, and the 409 the
+         * route table promises could never be produced.
+         */
+        throw Object.assign(new Error(stderr || stdout || `git exited with ${exitCode}`), {
+          stderr,
+          stdout,
+        });
       }
       return stdout;
     };
@@ -1375,7 +1624,7 @@ export async function handleStudioApi(
           url?: string;
         };
         if (!name || !remoteUrl) {
-          return new Response("name and url required", { status: 400 });
+          return problem("invalidRequest", "name and url required");
         }
         await runGit(["remote", "add", name, remoteUrl]);
         return Response.json({ ok: true });
@@ -1415,11 +1664,11 @@ export async function handleStudioApi(
       if (gitCmd === "stage" && req.method === "POST") {
         const { files } = (await req.json()) as { files?: string[] };
         if (!Array.isArray(files) || files.length === 0) {
-          return Response.json({ error: "Missing files" }, { status: 400 });
+          return problem("invalidRequest", "Missing files");
         }
         for (const f of files) {
           if (f.includes("..")) {
-            return Response.json({ error: "Invalid path" }, { status: 400 });
+            return problem("invalidRequest", "Invalid path");
           }
         }
         await runGit(["add", "--", ...files]);
@@ -1429,7 +1678,7 @@ export async function handleStudioApi(
       if (gitCmd === "unstage" && req.method === "POST") {
         const { files } = (await req.json()) as { files?: string[] };
         if (!Array.isArray(files) || files.length === 0) {
-          return Response.json({ error: "Missing files" }, { status: 400 });
+          return problem("invalidRequest", "Missing files");
         }
         await runGit(["restore", "--staged", "--", ...files]);
         return Response.json({ ok: true });
@@ -1438,7 +1687,7 @@ export async function handleStudioApi(
       if (gitCmd === "commit" && req.method === "POST") {
         const { message } = (await req.json()) as { message?: string };
         if (!message || typeof message !== "string") {
-          return Response.json({ error: "Missing message" }, { status: 400 });
+          return problem("invalidRequest", "Missing message");
         }
         const statusOut = await runGit(["status", "--porcelain"]);
         const hasStaged = statusOut
@@ -1467,7 +1716,28 @@ export async function handleStudioApi(
       }
 
       if (gitCmd === "pull" && req.method === "POST") {
-        await runGit(["pull"]);
+        /*
+         * The one failure the route table has always published — `409 {conflicts}` — and never
+         * produced: a conflicting pull threw like any other git failure and reached the catch-all
+         * as a 500, so Studio told the user the backend broke rather than that their branch and
+         * the remote both touched the same files. The conflicting paths are the only thing that
+         * makes the message actionable, so they ride along as the extension member the type
+         * documents.
+         */
+        try {
+          await runGit(["pull"]);
+        } catch (error) {
+          const output = error as { stdout?: string; stderr?: string };
+          const conflicts = conflictingPaths(`${output.stdout ?? ""}\n${output.stderr ?? ""}`);
+          if (conflicts.length === 0) {
+            throw error;
+          }
+          return problem(
+            "conflict",
+            `Pull stopped: ${conflicts.length} file(s) changed on both sides.`,
+            { conflicts },
+          );
+        }
         return Response.json({ ok: true });
       }
 
@@ -1479,7 +1749,7 @@ export async function handleStudioApi(
       if (gitCmd === "checkout" && req.method === "POST") {
         const { branch } = (await req.json()) as { branch?: string };
         if (!branch || typeof branch !== "string") {
-          return Response.json({ error: "Missing branch" }, { status: 400 });
+          return problem("invalidRequest", "Missing branch");
         }
         await runGit(["checkout", branch]);
         return Response.json({ ok: true });
@@ -1488,7 +1758,7 @@ export async function handleStudioApi(
       if (gitCmd === "create-branch" && req.method === "POST") {
         const { name } = (await req.json()) as { name?: string };
         if (!name || typeof name !== "string") {
-          return Response.json({ error: "Missing name" }, { status: 400 });
+          return problem("invalidRequest", "Missing name");
         }
         await runGit(["checkout", "-b", name]);
         return Response.json({ ok: true });
@@ -1497,10 +1767,10 @@ export async function handleStudioApi(
       if (gitCmd === "diff" && req.method === "GET") {
         const fp = url.searchParams.get("path");
         if (!fp) {
-          return Response.json({ error: "Missing path" }, { status: 400 });
+          return problem("invalidRequest", "Missing path");
         }
         if (fp.includes("..")) {
-          return Response.json({ error: "Invalid path" }, { status: 400 });
+          return problem("invalidRequest", "Invalid path");
         }
         const diff = await runGit(["diff", "--", fp]);
         return Response.json({ diff });
@@ -1510,10 +1780,10 @@ export async function handleStudioApi(
         const fp = url.searchParams.get("path");
         const ref = url.searchParams.get("ref") || "HEAD";
         if (!fp) {
-          return Response.json({ error: "Missing path" }, { status: 400 });
+          return problem("invalidRequest", "Missing path");
         }
         if (fp.includes("..")) {
-          return Response.json({ error: "Invalid path" }, { status: 400 });
+          return problem("invalidRequest", "Invalid path");
         }
         const content = await runGit(["show", `${ref}:${fp}`]);
         return Response.json({ content });
@@ -1522,11 +1792,11 @@ export async function handleStudioApi(
       if (gitCmd === "discard" && req.method === "POST") {
         const { files } = (await req.json()) as { files?: string[] };
         if (!Array.isArray(files) || files.length === 0) {
-          return Response.json({ error: "Missing files" }, { status: 400 });
+          return problem("invalidRequest", "Missing files");
         }
         for (const f of files) {
           if (f.includes("..")) {
-            return Response.json({ error: "Invalid path" }, { status: 400 });
+            return problem("invalidRequest", "Invalid path");
           }
         }
         await runGit(["checkout", "--", ...files]);
@@ -1536,7 +1806,7 @@ export async function handleStudioApi(
       if (gitCmd === "clone" && req.method === "POST") {
         const { url: repoUrl } = (await req.json()) as { url?: string };
         if (!repoUrl || typeof repoUrl !== "string") {
-          return Response.json({ error: "Missing url" }, { status: 400 });
+          return problem("invalidRequest", "Missing url");
         }
         const repoName = basename(repoUrl.replace(/\.git$/, ""));
         const dest = resolve(cwd, repoName);
@@ -1553,7 +1823,7 @@ export async function handleStudioApi(
         return Response.json({ ok: true, root: dest });
       }
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }