@jxsuite/server 4.5.1 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "4.5.1",
+  "version": "6.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -41,25 +41,25 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.39.3",
-    "@jxsuite/catalog": "^0.1.0",
-    "@jxsuite/collab": "^0.11.1",
-    "@jxsuite/compiler": "^5.1.3",
-    "@jxsuite/create": "^1.3.14",
-    "@jxsuite/import": "^0.40.10",
-    "@jxsuite/protocol": "^2.6.1",
-    "@jxsuite/runtime": "^4.1.0",
-    "@jxsuite/schema": "^3.0.0",
-    "@jxsuite/site": "^2.0.4",
-    "@jxsuite/starters": "^2.0.1",
+    "@jxsuite/ai": "^0.39.5",
+    "@jxsuite/catalog": "^0.1.2",
+    "@jxsuite/collab": "^0.11.2",
+    "@jxsuite/compiler": "^6.0.1",
+    "@jxsuite/create": "^1.3.16",
+    "@jxsuite/import": "^0.40.12",
+    "@jxsuite/protocol": "^4.0.0",
+    "@jxsuite/runtime": "^5.0.0",
+    "@jxsuite/schema": "^4.0.0",
+    "@jxsuite/site": "^2.0.5",
+    "@jxsuite/starters": "^3.0.0",
     "chokidar": "^5.0.0",
-    "kysely": "^0.29.6",
+    "kysely": "^0.29.7",
     "oxfmt": "^0.73.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.6.2",
-    "@jxsuite/connector": "^0.6.2",
-    "@jxsuite/parser": "^2.0.1"
+    "@jxsuite/auth": "^0.6.3",
+    "@jxsuite/connector": "^0.6.3",
+    "@jxsuite/parser": "^4.0.0"
   }
 }

package/src/import-api.ts

@@ -4,7 +4,7 @@
  * Handles POST /__studio/import-site: runs @jxsuite/import's importSite pipeline in the backend
  * (headless Chrome + filesystem) and streams progress back as NDJSON lines over the POST response —
  * the same streaming-fetch transport the AI chat proxy uses, so every platform (dev server,
- * Electrobun services server, Chromium loopback server) can mount it unchanged.
+ * Electron hub's loopback servers, Chromium loopback server) can mount it unchanged.
  *
  * Stream protocol (one JSON object per line):
  *

package/src/packages.ts

@@ -88,8 +88,8 @@ export function dependenciesNeedInstall(root: string): boolean {
 
 /**
  * Path to the bun executable. Uses the bun running the current process (`process.execPath`) so a
- * packaged desktop app spawns the bun bundled with its Electrobun distribution rather than relying
- * on a system-wide `bun` in `$PATH` (which end users may not have). Falls back to a PATH lookup if
+ * packaged desktop app spawns the bun bundled with its Electron distribution rather than relying on
+ * a system-wide `bun` in `$PATH` (which end users may not have). Falls back to a PATH lookup if
  * `execPath` is somehow unset.
  */
 export function bunExecutable(): string {

package/src/project-server.ts

@@ -1,7 +1,6 @@
 /**
  * Shared project server factory. Generalizes the chromium variant's ad-hoc in-process Bun.serve
- * into one createProjectServer() used by the chromium desktop launcher (and, in Phase 7,
- * electrobun).
+ * into one createProjectServer() used by the chromium desktop launcher and the Electron hub.
  *
  * It serves three surfaces from a single loopback-bound Bun.serve:
  *
@@ -77,9 +76,10 @@ export interface ProjectServerSession {
 
 export interface CreateProjectServerOptions {
   /**
-   * Resolve the session for a given window id (the `win` query param / stashed socket data).
-   * chromium passes `() => defaultSession`; electrobun (Phase 7) swaps it for a per-window lookup.
-   * A missing/unknown window returns `null`, which the routes treat as a 404 fail-closed.
+   * Resolve the session for a given window id (the `win` query param / stashed socket data). the
+   * single-window launcher passes `() => defaultSession`; the Electron hub swaps it for a
+   * per-window lookup. A missing/unknown window returns `null`, which the routes treat as a 404
+   * fail-closed.
    */
   resolveSession: (winId: string | null) => ProjectServerSession | null;
   /** Absolute dir holding the studio shell + canvas.html + dist/. */

package/src/refactor/paths.ts

@@ -257,9 +257,12 @@ export interface RemapCtx {
  * 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.
+ * `rootRelativeBare` makes the value resolve against the project root rather than the document
+ * directory, in every spelling: `./layouts/base.json` in `pages/blog/[slug].json` names
+ * `layouts/base.json`, because the compiler resolves `$layout` with `resolve(projectRoot, ref)`
+ * (layout-resolver.ts). Treating a `./` value as document-relative there missed every page's own
+ * `$layout`, so a renamed layout left them pointing at the old name. Used for `$layout` and for
+ * `build.copy` keys, which are project paths too.
  */
 export function rewriteRef(
   cls: { core: string; suffix: string; rooted: boolean },
@@ -270,10 +273,8 @@ export function rewriteRef(
   if (rooted) {
     return rewriteSiteUrl(core, suffix, ctx);
   }
-  const startsRel = core.startsWith("./") || core.startsWith("../");
-  const useRoot = rootRelativeBare && !startsRel;
-  const baseOld = useRoot ? ctx.root : ctx.docOldDir;
-  const baseNew = useRoot ? ctx.root : ctx.docNewDir;
+  const baseOld = rootRelativeBare ? ctx.root : ctx.docOldDir;
+  const baseNew = rootRelativeBare ? ctx.root : ctx.docNewDir;
 
   const targetOld = joinPosix(baseOld, core);
   const targetNew = remapTarget(targetOld, ctx.oldAbs, ctx.newAbs);

package/src/resolve.ts

@@ -4,7 +4,7 @@ import { siteBasePath } from "@jxsuite/schema/asset-paths";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { projectDevEnv } from "./dev-vars.ts";
 import { containedPath } from "./net-guard.ts";
@@ -14,6 +14,7 @@ import { loadAssetMounts } from "@jxsuite/compiler/asset-mounts";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { DynamicMethod } from "@jxsuite/runtime/types";
 import type { ProjectSections } from "@jxsuite/compiler/project-sections";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type {
   JsonObject,
   JsonPrimitive,
@@ -64,11 +65,18 @@ interface ModuleNamespace extends ExportedObject {
  */
 type ProjectContext = ProjectSections & { config: ProjectConfig; root: string };
 
-/** A cached project context, its extension asset mounts, and the `project.json` mtime it is for. */
+/**
+ * One `project.json` generation: its config, extension registry and asset mounts, loaded together
+ * because they are cheap, and the extension-loaded sections, loaded only when a class asks for
+ * them.
+ */
 interface ProjectEntry {
   mtime: number;
-  context: ProjectContext;
+  config: ProjectConfig;
+  registry: ExtensionRegistry;
   mounts: AssetMount[];
+  /** The full `_project` context, started by the first {@link loadProjectContext} and shared. */
+  context?: Promise<ProjectContext> | undefined;
 }
 
 /** A value the resolve proxy hands a class constructor under one config key. */
@@ -173,8 +181,19 @@ function baseDirectory($base: string, root: string, projectRoot: string): string
   return resolve(root, `.${urlDir}`);
 }
 
-/** Per-project context cache, invalidated when project.json changes on disk. */
-const projectContextCache = new Map<string, ProjectEntry>();
+/**
+ * Per-project cache, invalidated when project.json changes on disk. It holds the PROMISE, keyed by
+ * the mtime it was started for, so concurrent requests on a cold cache share one load.
+ *
+ * Both halves of that are load-bearing. Every project file the canvas fetches asks for the asset
+ * mounts, and the canvas fetches a document's `$elements` in parallel: before the promise was
+ * cached, each of them started its own load, so a page with 25 components ran 25 at once. And the
+ * sections are not part of it: a content section loads every entry of every collection, which for a
+ * 910-entry knowledge base is ten seconds of parsing, so serving a JSON file next to it waited ten
+ * seconds for data it never reads. Both together put a component fetch past the canvas's register
+ * timeout on every cold open.
+ */
+const projectEntryCache = new Map<string, { mtime: number; entry: Promise<ProjectEntry | null> }>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -186,32 +205,82 @@ const projectContextCache = new Map<string, ProjectEntry>();
  */
 async function loadProjectContext(projectRoot: string): Promise<ProjectContext | null> {
   const entry = await loadProjectEntry(projectRoot);
-  return entry?.context ?? null;
+  if (!entry) {
+    return null;
+  }
+  entry.context ??= loadProjectSections(projectRoot, entry.config, entry.registry, {
+    lazy: true,
+  }).then((sections) => ({ config: entry.config, root: projectRoot, ...sections }));
+  try {
+    return await entry.context;
+  } catch {
+    // A failed load is not remembered: the next class to ask tries again.
+    entry.context = undefined;
+    return null;
+  }
+}
+
+/**
+ * Whether a class reads `_project` through its sections' on-demand methods, by declaring `static
+ * projectOnDemand = true` (specs/extensions.md §8). The sections here are loaded lazily, so a class
+ * that reads one synchronously (a `content.get(type)`) would find nothing it had not loaded; such a
+ * class is handed every section whole instead, exactly what it was always given.
+ */
+function readsProjectOnDemand(ExportedClass: ExportedFunction | ExportedConstructor): boolean {
+  return "projectOnDemand" in ExportedClass && ExportedClass.projectOnDemand === true;
 }
 
-/** Load (or reuse) the cached project context plus its extension asset mounts. */
+/** A section an owner loaded on demand: `complete()` makes it whole (extensions.md §8). */
+interface OnDemandSection {
+  complete: () => Promise<void>;
+}
+
+/** Whether a project-context value is a section loaded on demand, by its `complete` method. */
+function isOnDemandSection(
+  value: ProjectContext[string],
+): value is ProjectContext[string] & OnDemandSection {
+  return isNonNullObject(value) && "complete" in value && isFunction(value.complete);
+}
+
+/** Make every section of a project context whole, for a class that reads them synchronously. */
+async function completeSections(context: ProjectContext): Promise<void> {
+  for (const value of Object.values(context)) {
+    if (isOnDemandSection(value)) {
+      await value.complete();
+    }
+  }
+}
+
+/** Load (or reuse) the cached project config, extension registry and asset mounts. */
 async function loadProjectEntry(projectRoot: string): Promise<ProjectEntry | null> {
   const projectJsonPath = resolve(projectRoot, "project.json");
-  if (!existsSync(projectJsonPath)) {
+  const mtime = statSync(projectJsonPath, { throwIfNoEntry: false })?.mtimeMs;
+  if (mtime === undefined) {
     return null;
   }
+  const cached = projectEntryCache.get(projectRoot);
+  if (cached && cached.mtime === mtime) {
+    return cached.entry;
+  }
+  const entry = readProjectEntry(projectRoot, projectJsonPath, mtime);
+  projectEntryCache.set(projectRoot, { entry, mtime });
+  return entry;
+}
+
+/** Read one `project.json` generation. Never rejects: any failure answers "no project context". */
+async function readProjectEntry(
+  projectRoot: string,
+  projectJsonPath: string,
+  mtime: number,
+): Promise<ProjectEntry | null> {
   try {
-    const { mtimeMs } = statSync(projectJsonPath);
-    const cached = projectContextCache.get(projectRoot);
-    if (cached && cached.mtime === mtimeMs) {
-      return cached;
-    }
     /* SAFETY: trust boundary. project.json is the project's own config file, which the editor
        and `jx validate` hold to its per-project schema. Any failure reading it below is caught
        here and answers "no project context". */
     const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
     const registry = await buildProjectExtensionRegistry(projectRoot, config);
-    const sections = await loadProjectSections(projectRoot, config, registry);
     const { mounts } = await loadAssetMounts(registry, config, projectRoot);
-    const context: ProjectContext = { config, root: projectRoot, ...sections };
-    const entry: ProjectEntry = { context, mounts, mtime: mtimeMs };
-    projectContextCache.set(projectRoot, entry);
-    return entry;
+    return { config, mounts, mtime, registry };
   } catch {
     return null;
   }
@@ -229,7 +298,7 @@ async function loadProjectEntry(projectRoot: string): Promise<ProjectEntry | nul
  */
 export async function projectSiteBase(projectRoot: string): Promise<string> {
   const entry = await loadProjectEntry(projectRoot);
-  return siteBasePath(entry?.context.config.url);
+  return siteBasePath(entry?.config.url);
 }
 
 /**
@@ -349,6 +418,9 @@ export async function handleResolve(
             status: 500,
           });
         }
+        if (config._project && !readsProjectOnDemand(ExportedClass)) {
+          await completeSections(config._project);
+        }
         /* SAFETY: trust boundary. A class file's `$implementation` names the module exporting the
            class it describes, whose constructor takes one config object (spec.md §12.3, §12.4).
            It is a function, checked above; one that is not constructible throws here, inside the
@@ -357,7 +429,10 @@ export async function handleResolve(
         return Response.json(await instanceResult(new ClassCtor(config)));
       }
 
-      // Self-contained: construct class from schema
+      // Self-contained: construct class from schema. Its JSON bodies cannot await a section.
+      if (config._project) {
+        await completeSections(config._project);
+      }
       const DynClass = classFromSchema(classDef);
       return Response.json(await instanceResult(new DynClass(config)));
     } catch (error) {

package/src/server.ts

@@ -554,7 +554,11 @@ export async function createDevServer(options: {
 
         // Resolve npm-style bare specifiers via node_modules.
         // Bundle on-demand so internal bare specifiers (e.g. lit/...) resolve.
-        const resolved = resolveNpmPath(absRoot, path);
+        /* The open project's own packages first: it pins the versions its pages are built with,
+           and a project outside the served root has no other way to reach them. */
+        const resolved =
+          (activeProjectRoot ? resolveNpmPath(activeProjectRoot, path) : null) ??
+          resolveNpmPath(absRoot, path);
         if (resolved) {
           const cacheKey = resolved;
           if (!bundleCache.has(cacheKey)) {

package/src/studio-api.ts

@@ -10,7 +10,7 @@
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
@@ -200,9 +200,43 @@ export function isOwnedProjectDir(dir: string): boolean {
   return existsSync(resolve(dir, "project.json"));
 }
 
+/**
+ * Whether the project at `dir` is under version control of its own, rather than a stranger inside
+ * somebody else's checkout.
+ *
+ * `git` answers for the nearest enclosing work tree, which is not the same question. A project
+ * copied into a folder another repository IGNORES (a scratch copy under a monorepo's `.cache/`, a
+ * download into a dotfiles repo's ignored `tmp/`) is "inside a work tree" by git's account, yet
+ * none of its files can ever be committed there: Publish would list the enclosing repository's
+ * branches and commits, and opening the project would fetch and pull a repository the user never
+ * chose. Such a project is therefore not a repository, and offers to initialise one. A project that
+ * is a TRACKED subfolder of a larger repository (a site inside a monorepo) still is one.
+ *
+ * @param {string} dir - The project root
+ * @returns {Promise<boolean>}
+ */
+export async function projectHasRepository(dir: string): Promise<boolean> {
+  const exitOf = async (args: string[]) => {
+    const proc = Bun.spawn(["git", ...args], { cwd: dir, stderr: "ignore", stdout: "ignore" });
+    return await proc.exited;
+  };
+  if ((await exitOf(["rev-parse", "--is-inside-work-tree"])) !== 0) {
+    return false;
+  }
+  // `check-ignore` exits 0 when the path IS ignored, 1 when it is not.
+  return (await exitOf(["check-ignore", "-q", "."])) !== 0;
+}
+
 /**
  * Parse raw `git status --porcelain=v2 --branch` output into structured data.
  *
+ * The route runs it with `-z`, and that is the form that matters: without `-z` git C-quotes every
+ * path holding a byte outside printable ASCII (`72” Grapple.md` arrives as `"72\342\200\235
+ * Grapple.md"`), so Studio listed octal escapes inside stray quotes and asked git to stage a file
+ * that does not exist. With `-z` each record ends in NUL and every path is verbatim; a rename's
+ * original path is the record after it, which is skipped. Newline-separated output is still read,
+ * for callers and tests that hand it plain text.
+ *
  * @param {string} out
  * @returns {{
  *   branch: string;
@@ -220,7 +254,10 @@ export function parseGitStatus(out: string) {
   /** @type {{ path: string; status: string; staged: boolean }[]} */
   const files = [];
 
-  for (const line of out.split("\n")) {
+  const nulTerminated = out.includes("\0");
+  const records = out.split(nulTerminated ? "\0" : "\n");
+  for (let index = 0; index < records.length; index += 1) {
+    const line = records[index]!;
     if (!line) {
       continue;
     }
@@ -239,7 +276,11 @@ export function parseGitStatus(out: string) {
       const stagedCode = xy[0]!;
       const unstagedCode = xy[1]!;
       let filePath;
-      if (line.startsWith("2 ")) {
+      if (line.startsWith("2 ") && nulTerminated) {
+        // `2 XY sub mH mI mW hH hI Xscore path`, then the original path as its own record.
+        filePath = parts.slice(9).join(" ");
+        index += 1;
+      } else if (line.startsWith("2 ")) {
         const tabIdx = line.indexOf("\t");
         const pathPart = line.slice(tabIdx + 1);
         filePath = pathPart.split("\t").pop() || "";
@@ -771,16 +812,15 @@ export async function handleStudioApi(
       return problem("invalidRequest", errorMessage(error));
     }
 
-    /** Report a path relative to the active project root (or server root as fallback). */
-    const reportRelative = (fp: string) => {
-      if (activeProjectRoot) {
-        const rel = relative(activeProjectRoot, fp);
-        if (!rel.startsWith("..")) {
-          return fwd(rel);
-        }
-      }
-      return fwd(relative(root, fp));
-    };
+    /*
+     * Every path out is relative to the active project root (§4.1), a path BESIDE the project
+     * included: `../../docs/start`, not `docs/start`. A collection may live outside its project
+     * (`sites/jxsuite.com` declares `content.docs.source: "../../docs"`), and a server-root-relative
+     * reply for it reads as project-relative to the client, which resolves it against the server
+     * root again on the next call and names a directory nobody has. A recursive walk of that
+     * collection stopped at its first level, with a 500 for every subdirectory.
+     */
+    const reportRelative = (fp: string) => fwd(relative(activeProjectRoot ?? root, fp));
 
     try {
       if (pattern) {
@@ -821,7 +861,11 @@ export async function handleStudioApi(
       }
       return Response.json(byPathOrder(files));
     } catch (error) {
-      return problem("internalError", errorMessage(error));
+      // A directory that does not exist is a 404, not a server fault: a client probing whether a
+      // Folder exists yet (Add new's collision check) asks exactly this.
+      return isNotFound(error)
+        ? problem("notFound", errorMessage(error))
+        : problem("internalError", errorMessage(error));
     }
   }
 
@@ -1296,9 +1340,18 @@ export async function handleStudioApi(
         { headers: { "Cache-Control": "public, max-age=5" } },
       );
     } catch (error) {
-      return isNotFound(error)
-        ? problem("notFound", "Not found")
-        : problem("internalError", errorMessage(error));
+      if (!isNotFound(error)) {
+        return problem("internalError", errorMessage(error));
+      }
+      /* `optional=1`: the caller is asking whether the file is there, and "no" is an ordinary
+         answer rather than a failure — the same reasoning that makes a missing directory's listing
+         a 404 instead of a 500, one step further. A per-directory `.gitignore` probe is the case
+         that needs it: a listing hides dotfiles, so the only way to learn a directory has none is
+         to ask, and a 404 per directory lands in the browser console as a failed request. Never
+         cached, so a file created a moment later is read rather than remembered as absent. */
+      return url.searchParams.get("optional") === "1"
+        ? Response.json({ content: null, path: fp }, { headers: { "Cache-Control": "no-store" } })
+        : problem("notFound", "Not found");
     }
   }
 
@@ -1344,7 +1397,7 @@ export async function handleStudioApi(
     try {
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, await req.text(), "utf8");
-      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
+      return Response.json({ ok: true, path: fwd(relative(activeProjectRoot ?? root, abs)) });
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -1366,7 +1419,7 @@ export async function handleStudioApi(
       await mkdir(dirname(abs), { recursive: true });
       const buffer = await req.arrayBuffer();
       await Bun.write(abs, new Uint8Array(buffer));
-      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
+      return Response.json({ ok: true, path: fwd(relative(activeProjectRoot ?? root, abs)) });
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -1385,11 +1438,17 @@ export async function handleStudioApi(
       return new Response(errorMessage(error), { status: 400 });
     }
     try {
-      await unlink(abs);
-      return Response.json({ ok: true, path: fwd(relative(root, abs)) });
+      /* A directory is removed only when it is EMPTY (`rmdir`), never recursively: a folder of
+         files is a decision about every file in it, which the client makes one file at a time. */
+      const entry = await stat(abs);
+      await (entry.isDirectory() ? rmdir(abs) : unlink(abs));
+      return Response.json({ ok: true, path: fwd(relative(activeProjectRoot ?? root, abs)) });
     } catch (error) {
-      return isNotFound(error)
-        ? problem("notFound", "Not found")
+      if (isNotFound(error)) {
+        return problem("notFound", "Not found");
+      }
+      return isNonNullObject(error) && "code" in error && error.code === "ENOTEMPTY"
+        ? problem("conflict", "The folder is not empty.")
         : problem("internalError", errorMessage(error));
     }
   }
@@ -1774,7 +1833,24 @@ export async function handleStudioApi(
   // ── Git endpoints ──────────────────────────────────────────────────────────
 
   if (path.startsWith("/__studio/git/")) {
-    const cwd = activeProjectRoot || root;
+    /* THE REPOSITORY IS THE REQUEST'S, NOT THE SERVER'S. One dev server serves every Studio tab
+       pointed at it, and `activeProjectRoot` is whichever project was activated last. Read from it
+       alone, two sessions on two projects ran each other's git: Initialize Repository in one
+       initialised the other. Every git call names its project with `?dir=`, as the file routes do,
+       under the same access rule; the fallback is for a caller that names none (no project open). */
+    const named = url.searchParams.get("dir");
+    const cwd = named
+      ? isAbsolute(named)
+        ? named
+        : resolve(root, named)
+      : activeProjectRoot || root;
+    if (named) {
+      try {
+        assertAccessible(cwd, root, activeProjectRoot);
+      } catch (error) {
+        return problem("invalidRequest", errorMessage(error));
+      }
+    }
     const gitCmd = path.slice("/__studio/git/".length);
 
     const runGit = async (args: string[]) => {
@@ -1804,15 +1880,13 @@ export async function handleStudioApi(
     };
 
     try {
+      /* Every command but the two that make a repository acts on THE PROJECT'S repository, so one
+         that has none of its own is refused rather than handed to whatever checkout encloses it
+         (see `projectHasRepository`). */
+      const makesRepository = gitCmd === "init" || gitCmd === "clone";
+      const hasRepository = makesRepository || (await projectHasRepository(cwd));
       if (gitCmd === "status" && req.method === "GET") {
-        // Check if we're in a git repo first
-        const checkProc = Bun.spawn(["git", "rev-parse", "--is-inside-work-tree"], {
-          cwd,
-          stderr: "pipe",
-          stdout: "pipe",
-        });
-        const checkExit = await checkProc.exited;
-        if (checkExit !== 0) {
+        if (!hasRepository) {
           return Response.json({
             ahead: 0,
             behind: 0,
@@ -1823,8 +1897,12 @@ export async function handleStudioApi(
           });
         }
 
+        /* `--untracked-files=all`: every untracked FILE, not its collapsed folder. By default git
+           reports a wholly untracked `content/` as one entry, so a fresh repository listed a
+           handful of folders that no group, comparison or checkbox could treat as a file, and the
+           count jumped to the real one the moment staging expanded them (studio.md §22.8). */
         const [out, remotesOut] = await Promise.all([
-          runGit(["status", "--porcelain=v2", "--branch"]),
+          runGit(["status", "--porcelain=v2", "--branch", "-z", "--untracked-files=all"]),
           runGit(["remote"]),
         ]);
         const status = parseGitStatus(out);
@@ -1836,6 +1914,13 @@ export async function handleStudioApi(
         return Response.json(fullStatus);
       }
 
+      if (!hasRepository) {
+        return problem(
+          "conflict",
+          "This project is not a git repository of its own. Initialize one to use source control.",
+        );
+      }
+
       if (gitCmd === "init" && req.method === "POST") {
         await runGit(["init"]);
         return Response.json({ ok: true });
@@ -1875,6 +1960,16 @@ export async function handleStudioApi(
 
       if (gitCmd === "log" && req.method === "GET") {
         const limit = url.searchParams.get("limit") || "20";
+        /* A repository with no commits yet has no history, which is an empty list, not a failure:
+           `git log` exits 128 on an unborn HEAD, and that 500 was the first console error every
+           freshly initialized project showed (studio.md §22.8). */
+        const hasHead = await runGit(["rev-parse", "--verify", "--quiet", "HEAD"]).then(
+          () => true,
+          () => false,
+        );
+        if (!hasHead) {
+          return Response.json([]);
+        }
         const out = await runGit(["log", `--max-count=${limit}`, "--format=%H\t%s\t%an\t%aI"]);
         const entries = out
           .trim()