@jxsuite/server 2.0.0 → 2.1.0

package/src/studio-api.ts

@@ -20,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,
@@ -33,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("\\", "/");
@@ -328,6 +331,29 @@ export interface StudioApiOptions {
  * @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,
@@ -364,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);
@@ -404,7 +430,7 @@ export async function handleStudioApi(
         projectRoot,
       });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -412,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
@@ -451,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));
     }
   }
 
@@ -460,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 || "";
@@ -479,7 +505,7 @@ 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));
     }
   }
 
@@ -502,7 +528,7 @@ export async function handleStudioApi(
     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 Response.json({ error: "Missing or invalid name/id" }, { status: 400 });
+      return problem("invalidRequest", "Missing or invalid name/id");
     }
     try {
       const home = process.env.HOME || process.env.USERPROFILE || "";
@@ -547,7 +573,7 @@ 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));
     }
   }
 
@@ -575,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));
     }
   }
 
@@ -605,32 +631,29 @@ export async function handleStudioApi(
         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 Response.json({ error: "A destination folder is required." }, { status: 400 });
+        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 Response.json(
-          { error: "Directory must be a folder name, not a path" },
-          { status: 400 },
-        );
+        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}"`);
       }
       // 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 Response.json({ error: errorMessage(error) }, { status: 400 });
+        return problem("invalidRequest", errorMessage(error));
       }
       const destPath = resolve(destination.parent, directory);
 
@@ -655,7 +678,7 @@ export async function handleStudioApi(
       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));
     }
   }
 
@@ -665,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));
     }
   }
 
@@ -677,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). */
@@ -730,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));
     }
   }
 
@@ -741,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);
@@ -882,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));
     }
   }
 
@@ -930,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));
     }
   }
 
@@ -938,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);
@@ -964,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));
     }
   }
 
@@ -974,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;
@@ -990,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));
     }
   }
 
@@ -1007,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;
@@ -1019,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));
     }
   }
 
@@ -1038,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));
     }
   }
 
@@ -1056,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));
     }
   }
 
@@ -1068,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));
     }
   }
 
@@ -1082,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 {
@@ -1100,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));
     }
   }
 
@@ -1109,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 {
@@ -1122,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));
     }
   }
 
@@ -1130,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 {
@@ -1144,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));
     }
   }
 
@@ -1152,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 {
@@ -1165,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));
     }
   }
 
@@ -1176,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);
@@ -1194,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.
@@ -1213,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 {
@@ -1244,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));
     }
   }
 
@@ -1262,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}`, {
@@ -1307,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"
@@ -1326,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));
     }
   }
 
@@ -1354,7 +1432,7 @@ export async function handleStudioApi(
         })),
       });
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 400 });
+      return problem("invalidRequest", errorMessage(error));
     }
   }
 
@@ -1367,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));
     }
   }
 
@@ -1382,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;
@@ -1487,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;
     };
@@ -1536,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 });
@@ -1576,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]);
@@ -1590,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 });
@@ -1599,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
@@ -1628,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 });
       }
 
@@ -1640,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 });
@@ -1649,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 });
@@ -1658,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 });
@@ -1671,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 });
@@ -1683,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]);
@@ -1697,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);
@@ -1714,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));
     }
   }