@jxsuite/server 8.2.1 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "8.2.1",
+  "version": "8.4.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
   "exports": {
     ".": "./src/server.ts",
     "./dev": "./src/dev.ts",
+    "./convert": "./src/convert.ts",
     "./ai-api": "./src/ai-api.ts",
     "./data": "./src/data-api.ts",
     "./import-api": "./src/import-api.ts",
@@ -54,17 +55,17 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.42.1",
-    "@jxsuite/catalog": "^0.1.7",
-    "@jxsuite/collab": "^0.11.5",
-    "@jxsuite/compiler": "^8.1.0",
-    "@jxsuite/create": "^1.5.3",
-    "@jxsuite/import": "^0.42.3",
-    "@jxsuite/protocol": "^6.2.1",
-    "@jxsuite/runtime": "^6.0.2",
-    "@jxsuite/schema": "^5.1.0",
-    "@jxsuite/site": "^2.3.0",
-    "@jxsuite/starters": "^3.2.0",
+    "@jxsuite/ai": "^0.43.1",
+    "@jxsuite/catalog": "^0.1.9",
+    "@jxsuite/collab": "^0.11.7",
+    "@jxsuite/compiler": "^8.3.0",
+    "@jxsuite/create": "^1.5.5",
+    "@jxsuite/import": "^0.42.5",
+    "@jxsuite/protocol": "^6.2.3",
+    "@jxsuite/runtime": "^6.2.0",
+    "@jxsuite/schema": "^5.3.0",
+    "@jxsuite/site": "^2.4.0",
+    "@jxsuite/starters": "^3.3.1",
     "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.8",
@@ -74,9 +75,9 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.3",
-    "@jxsuite/connector": "^0.8.3",
-    "@jxsuite/parser": "^4.2.0",
+    "@jxsuite/auth": "^0.8.5",
+    "@jxsuite/connector": "^0.8.5",
+    "@jxsuite/parser": "^4.3.1",
     "@jxsuite/test-support": "^0.0.0",
     "@types/npm-package-arg": "^6.1.4",
     "@types/npmcli__arborist": "^6.3.3",

package/src/convert.ts

@@ -0,0 +1,254 @@
+/**
+ * `jx convert`: move a document between `.json` and `.jxn`, with every reference repaired.
+ *
+ * It is a rename, because that is what makes it safe: writing a new file beside the old one would
+ * leave every `$ref` to it dangling, and the refactor pass is what repairs them. This runs under
+ * Bun for the same reason `jx dev` does, so `@jxsuite/compiler`'s CLI resolves it from the project
+ * and spawns it.
+ *
+ * @docs framework/build/cli
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
+import { loadProjectConfig } from "@jxsuite/compiler/site-loader";
+import { countJxnComments, parseJxn, serializeJxn } from "@jxsuite/schema/jxn";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+import { applyRename } from "./refactor/index.ts";
+
+/** The formats a document can move between. */
+export type ConvertTarget = "json" | "jxn";
+
+/** What was asked. */
+export interface ConvertOptions {
+  /** Convert a `.jxn` file that has comments, which `.json` has nowhere to keep. */
+  dropComments: boolean;
+  /** Say what would happen, and change nothing. */
+  dryRun: boolean;
+  to: ConvertTarget;
+}
+
+/** What happened to one file. */
+export interface ConvertRow {
+  from: string;
+  /** Other files whose references to this one were repaired. */
+  references: number;
+  /** Why it was left alone, or what is still wrong after moving it. */
+  problem: string | null;
+  to: string;
+}
+
+/** The directories that hold documents, which are conventions the build hard-codes. */
+const DOCUMENT_ROOTS = ["components/", "layouts/", "pages/"];
+
+/**
+ * Where each content collection's files are, project-relative: the part of its `source` before any
+ * `{locale}` or glob. Only a collection reaching into a document root can matter here.
+ */
+function collectionRoots(config: ProjectConfig): string[] {
+  const content = isJsonObject(config.content) ? Object.values(config.content) : [];
+  return content.flatMap((definition) => {
+    const source = isJsonObject(definition) ? definition.source : null;
+    if (!isString(source)) {
+      return [];
+    }
+    const [fixed = ""] = /^[^{*]*/u.exec(source) ?? [];
+    return [fixed.replace(/^\.\//u, "").replace(/\/+$/u, "")];
+  });
+}
+
+/** Every convertible file a path names: itself, or what is under it. */
+function expand(path: string): string[] {
+  // A path that is not there comes through as itself, so `refusal` can say so.
+  if (!existsSync(path) || !statSync(path).isDirectory()) {
+    return [path];
+  }
+  return readdirSync(path, { withFileTypes: true }).flatMap((entry) => {
+    const child = join(path, entry.name);
+    if (entry.isDirectory()) {
+      return expand(child);
+    }
+    return /\.(?:json|jxn)$/iu.test(entry.name) && !entry.name.endsWith(".class.json")
+      ? [child]
+      : [];
+  });
+}
+
+/** Why a file cannot be converted, or null when it can. */
+async function refusal(
+  root: string,
+  path: string,
+  options: ConvertOptions,
+  sources: readonly string[],
+): Promise<string | null> {
+  if (!existsSync(path)) {
+    return "there is no such file";
+  }
+  const name = relative(root, path).replaceAll("\\", "/");
+  if (!DOCUMENT_ROOTS.some((prefix) => name.startsWith(prefix))) {
+    return `only ${DOCUMENT_ROOTS.join(", ")} hold documents`;
+  }
+  const ext = extname(path).toLowerCase();
+  if (ext !== ".json" && ext !== ".jxn") {
+    return `${ext || "this file"} is not a native document format`;
+  }
+  if (path.endsWith(".class.json")) {
+    return "a class descriptor stays JSON";
+  }
+  if (ext === `.${options.to}`) {
+    return `already .${options.to}`;
+  }
+  if (sources.some((source) => name === source || name.startsWith(`${source}/`))) {
+    // Both directions: an entry would drop out of its glob, and a neighbour would be enlisted.
+    return "a content collection's file keeps its collection's format";
+  }
+  if (existsSync(targetOf(path, options.to))) {
+    return `${basename(targetOf(path, options.to))} already exists`;
+  }
+  if (ext === ".jxn" && !options.dropComments) {
+    const comments = countJxnComments(await readFile(path, "utf8"));
+    if (comments > 0) {
+      return `it has ${comments} comment(s), and .json has nowhere to keep them. --drop-comments converts it anyway`;
+    }
+  }
+  return null;
+}
+
+/** The path a file has once converted. */
+function targetOf(path: string, to: ConvertTarget): string {
+  return join(dirname(path), `${basename(path, extname(path))}.${to}`);
+}
+
+/** The file's text in the other format. */
+async function converted(path: string, to: ConvertTarget): Promise<string> {
+  const text = await readFile(path, "utf8");
+  return to === "jxn"
+    ? serializeJxn(parseJxDocument(text, path))
+    : `${JSON.stringify(parseJxn(text, path), null, 2)}\n`;
+}
+
+/**
+ * Convert documents in a project.
+ *
+ * @param root The project root.
+ * @param paths Files and directories, relative to the root.
+ * @param options What was asked.
+ */
+export async function convertDocuments(
+  root: string,
+  paths: readonly string[],
+  options: ConvertOptions,
+): Promise<ConvertRow[]> {
+  const { config } = loadProjectConfig(root);
+  const sources = collectionRoots(config);
+  const { formats } = await buildProjectExtensionRegistry(root, config);
+  const rows: ConvertRow[] = [];
+  for (const path of paths.flatMap((item) => expand(resolve(root, item)))) {
+    const from = relative(root, path);
+    const target = targetOf(path, options.to);
+    const row: ConvertRow = { from, references: 0, problem: null, to: relative(root, target) };
+    rows.push(row);
+    row.problem = await refusal(root, path, options, sources);
+    if (row.problem !== null) {
+      continue;
+    }
+    try {
+      const text = await converted(path, options.to);
+      if (options.dryRun) {
+        continue;
+      }
+      /* In place and then renamed, so a failure writing leaves the old name holding the old text or
+         the new, and nothing beside it to be mistaken for the document. */
+      await writeFile(path, text);
+      await rename(path, target);
+      const report = await applyRename({ absFrom: path, absTo: target, registry: formats, root });
+      row.references = report.references.filesChanged;
+      if (report.errors.length > 0) {
+        const unread = report.errors.map((item) => item.path).join(", ");
+        row.problem = `converted, and ${unread} could not be read, so a reference in it may still name the old path`;
+      }
+    } catch (error) {
+      row.problem = errorMessage(error);
+    }
+  }
+  return rows;
+}
+
+/** What `jx convert` was given. */
+export interface ConvertArgs extends ConvertOptions {
+  paths: string[];
+  root: string;
+}
+
+/**
+ * Read `jx convert`'s arguments.
+ *
+ * @param argv The arguments after the command.
+ * @returns What was asked, or null when it does not say.
+ */
+export function parseConvertArgs(argv: readonly string[]): ConvertArgs | null {
+  const paths: string[] = [];
+  let to: string | undefined;
+  let root = process.cwd();
+  const flags = new Set<string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    if (arg === "--to") {
+      index += 1;
+      to = argv[index];
+    } else if (arg === "--root") {
+      index += 1;
+      root = resolve(argv[index] ?? root);
+    } else if (arg.startsWith("--")) {
+      flags.add(arg);
+    } else {
+      paths.push(arg);
+    }
+  }
+  if ((to !== "json" && to !== "jxn") || paths.length === 0) {
+    return null;
+  }
+  return {
+    dropComments: flags.has("--drop-comments"),
+    dryRun: flags.has("--dry-run"),
+    paths,
+    root,
+    to,
+  };
+}
+
+/**
+ * Run `jx convert`.
+ *
+ * @param argv The arguments after the command.
+ * @param print Where the report goes.
+ * @returns The exit code: 1 when anything was left unconverted.
+ */
+export async function runConvert(
+  argv: readonly string[],
+  print: (line: string) => void = console.log,
+): Promise<number> {
+  const args = parseConvertArgs(argv);
+  if (!args) {
+    print("Usage: jx convert <paths…> --to jxn|json [--dry-run] [--drop-comments]");
+    return 2;
+  }
+  const rows = await convertDocuments(args.root, args.paths, args);
+  for (const row of rows) {
+    if (row.problem !== null) {
+      print(`${row.from}: ${row.problem}`);
+    } else if (args.dryRun) {
+      print(`${row.from} would become ${row.to}`);
+    } else {
+      print(`${row.from} → ${row.to} (${row.references} file(s) repaired)`);
+    }
+  }
+  return rows.some((row) => row.problem !== null) ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await runConvert(process.argv.slice(2));
+}

package/src/data-api.ts

@@ -53,6 +53,7 @@ import type {
   SecretsSetResponse,
 } from "@jxsuite/protocol";
 import { problem, problemTypeForStatus } from "./problem.ts";
+import { projectFilePath, readProjectFile } from "@jxsuite/schema/project-file/node";
 
 // ─── Local section shapes (structural — the connector owns the full types) ───
 
@@ -135,16 +136,17 @@ export function resetDataApi(): void {
 
 /** Read the project's config + connector-owned sections; 404 when there is no project.json. */
 function getProject(projectRoot: string): ProjectSections {
-  const path = resolve(projectRoot, "project.json");
-  let config: ProjectConfig;
-  try {
-    /* SAFETY: trust boundary. project.json is the project's own config, held to its per-project
-       schema by the editor and `jx validate`; the connections and data sections are narrowed
-       below, and unreadable or non-JSON text answers the 404 in the catch. */
-    config = JSON.parse(readFileSync(path, "utf8")) as ProjectConfig;
-  } catch (error) {
-    throw new ApiError(404, `No project.json under "${projectRoot}"`, { cause: error });
+  const read = readProjectFile(projectRoot);
+  if (!read) {
+    throw new ApiError(404, `No project.json under "${projectRoot}"`);
+  }
+  if ("error" in read) {
+    throw new ApiError(
+      404,
+      `The project.json under "${projectRoot}" does not parse: ${read.error}`,
+    );
   }
+  const { config } = read;
   /* Section keys are the connector's host wire contract (the same literals jx-mounts passes to
      the Data mount's options.sections) — JSON introspection, not a connector import.
      SAFETY: `connections` and `data` are the connector extension's sections, which its
@@ -158,7 +160,7 @@ function getProject(projectRoot: string): ProjectSections {
 
 /** Build (or reuse) the project's extension registry, keyed on project.json's mtime. */
 function getRegistry(projectRoot: string, config: ProjectConfig): Promise<ExtensionRegistry> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
+  const projectJsonPath = projectFilePath(projectRoot);
   const mtime = statSync(projectJsonPath).mtimeMs;
   const cached = registryCache.get(projectRoot);
   if (cached && cached.mtime === mtime) {

package/src/dev.ts

@@ -22,6 +22,7 @@ import { problem } from "./problem.ts";
 import { callServerExport } from "./resolve.ts";
 import { createDevServer } from "./server.ts";
 import { injectSSE } from "./watch.ts";
+import { hasProjectFile } from "@jxsuite/schema/project-file/node";
 
 export interface DevArgs {
   port: number;
@@ -187,7 +188,7 @@ export interface DevServerHandle {
  * @returns {Promise<DevServerHandle>} The listening server
  */
 export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle> {
-  const isSite = existsSync(join(root, "project.json"));
+  const isSite = hasProjectFile(root);
 
   let building = Promise.resolve();
   // What the last build collected, which the server-function route answers from.
@@ -195,7 +196,8 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
   const rebuild = () => {
     building = building.then(async () => {
       const { buildSite } = await import("@jxsuite/compiler/site");
-      const result = await buildSite(root, { verbose: false });
+      // A dev server shows authors their work, so entries a project holds back stay in it.
+      const result = await buildSite(root, { includeHeld: true, verbose: false });
       ({ serverEntries } = result);
       if (result.errors.length > 0) {
         for (const err of result.errors) {

package/src/extension-catalog.ts

@@ -31,6 +31,7 @@ import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { createNodeFormatIO, probeExtension } from "@jxsuite/compiler/format-host";
 import type { ExtensionCatalogEntry, ExtensionSectionInfo } from "@jxsuite/protocol";
 import type { JsonValue } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 interface PackageJson {
   dependencies?: Record<string, string>;
@@ -91,7 +92,7 @@ async function loadEntry(
     const registry = await buildExtensionRegistry(
       [name],
       createNodeFormatIO(projectRoot),
-      resolve(projectRoot, "project.json"),
+      projectFilePath(projectRoot),
     );
     const [info] = registry.extensions;
     if (!info) {

package/src/import-api.ts

@@ -30,7 +30,6 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
 import { problem } from "./problem.ts";
 import type { BreakpointPolicy, BreakpointRounding } from "@jxsuite/import/breakpoint-plan";
 import type { ImportProgressEvent } from "@jxsuite/import/pipeline";
@@ -38,6 +37,7 @@ import type { ImportSiteOptions, ImportSiteResult } from "@jxsuite/import/run";
 import { IMPORT_MAX_PAGES } from "@jxsuite/protocol";
 import type { ImportBreakpointPolicy } from "@jxsuite/protocol";
 import type { JsonObject } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 export interface ImportApiOptions {
   /**
@@ -301,7 +301,7 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
         /* SAFETY: importSite's emit phase has just written project.json as a Jx project config,
            which is a JSON object; text that is not JSON throws into the error line below. */
         const config = JSON.parse(
-          await readFile(resolve(result.outDir, "project.json"), "utf8"),
+          await readFile(projectFilePath(result.outDir), "utf8"),
         ) as JsonObject;
         /*
          * The result travels with the `done` line. It used to be discarded here: the pipeline had

package/src/jx-mounts.ts

@@ -17,7 +17,6 @@
  */
 
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 import { isString } from "@jxsuite/schema/guards";
 import { projectDevEnv } from "./dev-vars.ts";
@@ -25,6 +24,7 @@ import type { ProjectDevEnv } from "./dev-vars.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { ImplementationExport, MountHandler } from "@jxsuite/schema/format-registry";
 import type { JxDocumentValue, ProjectConfig } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 interface MountRuntime {
   handlers: { basePath: string; handler: MountHandler }[];
@@ -81,7 +81,7 @@ export async function handleJxMounts(
 
 /** Load (or reuse) the mount runtime for a project root. */
 function getRuntime(projectRoot: string): Promise<MountRuntime | null> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
+  const projectJsonPath = projectFilePath(projectRoot);
   if (!existsSync(projectJsonPath)) {
     return Promise.resolve(null);
   }

package/src/refactor/scan.ts

@@ -10,7 +10,10 @@
 import { extname } from "node:path";
 import { readFile } from "node:fs/promises";
 import type { FormatRegistry, ValueEdit } from "@jxsuite/schema/format-registry";
-import type { JsonValue } from "@jxsuite/schema/types";
+import { isJsonObject } from "@jxsuite/schema/guards";
+import { rewriteJson } from "@jxsuite/schema/json-layout";
+import { isJxnPath, parseJxn, serializeJxn } from "@jxsuite/schema/jxn";
+import type { JsonValue, JxDocument } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -77,13 +80,23 @@ export function documentGlob(registry: FormatRegistry): string {
 export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
   const raw = await readFile(fp, "utf8");
   if (isJsonPath(fp)) {
-    const trailingNewline = raw.endsWith("\n");
     return {
       // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
       doc: JSON.parse(raw) as JsonValue,
       rewrite: null,
-      serialize: (doc) =>
-        Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
+      // Over the text it replaces, so a rename changes the references and not the formatting.
+      serialize: (doc) => Promise.resolve(rewriteJson(doc, raw)),
+    };
+  }
+  if (isJxnPath(fp)) {
+    /* The one format whose writer can be told what it is replacing, so repairing a reference in a
+       `.jxn` file changes that reference and leaves its comments where they were. */
+    const document = parseJxn(raw);
+    return {
+      doc: isJsonObject(document) ? document : null,
+      rewrite: null,
+      // SAFETY: the document this just read, with reference values replaced by reference values.
+      serialize: (doc) => Promise.resolve(serializeJxn(doc as JxDocument, raw)),
     };
   }
   const ext = extname(fp);

package/src/resolve.ts

@@ -25,6 +25,7 @@ import type {
 } from "@jxsuite/schema/types";
 import type { ProjectDevEnv } from "./dev-vars.ts";
 import { problem } from "./problem.ts";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 /**
  * Any value a module exports, as the proxies see it before they check it. Nothing about an export
@@ -208,7 +209,9 @@ async function loadProjectContext(projectRoot: string): Promise<ProjectContext |
   if (!entry) {
     return null;
   }
+  // This host draws the canvas and Preview, so entries a project holds back stay visible to authors.
   entry.context ??= loadProjectSections(projectRoot, entry.config, entry.registry, {
+    includeHeld: true,
     lazy: true,
   }).then((sections) => ({ config: entry.config, root: projectRoot, ...sections }));
   try {
@@ -253,7 +256,7 @@ async function completeSections(context: ProjectContext): Promise<void> {
 
 /** 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");
+  const projectJsonPath = projectFilePath(projectRoot);
   const mtime = statSync(projectJsonPath, { throwIfNoEntry: false })?.mtimeMs;
   if (mtime === undefined) {
     return null;
@@ -342,20 +345,16 @@ export async function handleResolve(
   }
 
   let moduleAbsPath;
+  let docDir: string | null = null;
   // A bare specifier resolves through Node's module resolution (an installed package), so the
   // Class file — and the `$implementation` sibling it names — are as trusted as the package's own
   // Code. The root-escape guard only binds a caller-supplied relative `$src`/`$base`.
   let trustedResolution = false;
   try {
+    docDir = $base ? baseDirectory($base, root, activeProjectRoot || root) : null;
     if ($src.startsWith("./") || $src.startsWith("../")) {
       // Relative path
-      if ($base) {
-        const docUrlPath = new URL($base).pathname;
-        const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
-        moduleAbsPath = resolve(resolve(root, `.${docDir}`), $src);
-      } else {
-        moduleAbsPath = resolve(activeProjectRoot || root, $src);
-      }
+      moduleAbsPath = resolve(docDir ?? (activeProjectRoot || root), $src);
       if (!isImportable(moduleAbsPath, root, activeProjectRoot)) {
         return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
       }
@@ -371,13 +370,10 @@ export async function handleResolve(
   }
 
   // Rebase relative config paths from doc-relative to CWD-relative
-  if ($base) {
-    const docUrlPath = new URL($base).pathname;
-    const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
-    const docAbsDir = resolve(root, `.${docDir}`);
+  if (docDir) {
     for (const [k, v] of Object.entries(config)) {
       if (isString(v) && (v.startsWith("./") || v.startsWith("../"))) {
-        config[k] = `./${relative(process.cwd(), resolve(docAbsDir, v)).split("\\").join("/")}`;
+        config[k] = `./${relative(process.cwd(), resolve(docDir, v)).split("\\").join("/")}`;
       }
     }
   }

package/src/server.ts

@@ -169,7 +169,8 @@ export async function createDevServer(options: {
   const NO_CACHE = { "Cache-Control": "no-cache" };
   /*
    * `Bun.file` already infers a type from the extension, and for almost everything it is right. The
-   * exceptions are the two RFCs Jx has an opinion about: `.md` comes back as bare `text/markdown`
+   * exceptions are the two RFCs Jx has an opinion about, and `.jxn`, which Bun has never heard of:
+   * `.md` comes back as bare `text/markdown`
    * with no `variant`, and `.yaml` comes back as `text/yaml`, the spelling RFC 9512 §5 asks
    * implementations to stop using. `mediaTypeForPath` answers null everywhere else, so the
    * inference stays in charge of the ordinary cases.

package/src/site-output.ts

@@ -33,6 +33,7 @@ import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import type { JsonValue } from "@jxsuite/schema/types";
 
 import { serveContained } from "./net-guard.ts";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 /** What `project.json` says the build writes to, cached per root against its mtime. */
 const outDirCache = new Map<string, { mtime: number; outDir: string | null }>();
@@ -51,7 +52,7 @@ export function resetSiteOutput(): void {
  * file read.
  */
 export function siteOutDir(projectRoot: string): string | null {
-  const configPath = resolve(projectRoot, "project.json");
+  const configPath = projectFilePath(projectRoot);
   if (!existsSync(configPath)) {
     return null;
   }

package/src/studio-api.ts

@@ -20,6 +20,7 @@ import {
   missingExtensionsNotice,
 } from "@jxsuite/compiler/format-host";
 import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
+import { projectCommitArgs, projectRelativePath, readGitPrefix } from "@jxsuite/protocol/git-scope";
 import { handleDataApi } from "./data-api.ts";
 import { containedPath } from "./net-guard.ts";
 import { startSitePreview } from "./site-preview.ts";
@@ -47,6 +48,12 @@ import type { JsonObject, JsonPrimitive, JsonValue, ProjectConfig } from "@jxsui
 import { isFunction, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { problem } from "./problem.ts";
 import { scanFiles } from "./fs-glob.ts";
+import { PROJECT_FILE_NAME, classifyProjectFile } from "@jxsuite/schema/project-file";
+import {
+  findEnclosingProjectOnDisk,
+  hasProjectFile,
+  projectFilePath,
+} from "@jxsuite/schema/project-file/node";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -114,7 +121,7 @@ const extensionRegistryCache = new Map<
  * @returns {Promise<ExtensionRegistry>}
  */
 async function getExtensionRegistry(projectRoot: string): Promise<ExtensionRegistry> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
+  const projectJsonPath = projectFilePath(projectRoot);
   let mtime = 0;
   let projectConfig: ProjectConfig | undefined;
   try {
@@ -210,7 +217,7 @@ export function isOwnedProjectDir(dir: string): boolean {
   if (containedPath(dir, resolve(home)) === null) {
     return false;
   }
-  return existsSync(resolve(dir, "project.json"));
+  return hasProjectFile(dir);
 }
 
 /**
@@ -509,11 +516,10 @@ export async function handleStudioApi(
       let isSiteProject = false;
       let projectConfig: ProjectConfig | null = null;
       try {
+        const text = await readFile(projectFilePath(absDir), "utf8");
         // SAFETY: JSON.parse without a reviver only ever produces JSON values.
-        const raw = JSON.parse(
-          await readFile(resolve(absDir, "project.json"), "utf8"),
-        ) as JsonValue;
-        if (isJsonObject(raw)) {
+        const raw = JSON.parse(text) as JsonValue;
+        if (classifyProjectFile(text) === "project" && isJsonObject(raw)) {
           isSiteProject = true;
           /* SAFETY: `raw` is a JSON object and every ProjectConfig member is optional; the config
              is only relayed to the client here, never interpreted. */
@@ -550,30 +556,22 @@ export async function handleStudioApi(
       } catch {}
       if (isDir) {
         dir = absFile;
-        absFile = resolve(absFile, "project.json");
+        absFile = projectFilePath(absFile);
       } else {
         dir = dirname(absFile);
       }
-      while (dir) {
-        const candidate = resolve(dir, "project.json");
-        if (existsSync(candidate)) {
-          /* SAFETY: the config is relayed to the client verbatim and not interpreted here, so its
-             member types are the client's to check; malformed JSON throws into the catch below. */
-          const config = JSON.parse(readFileSync(candidate, "utf8")) as ProjectConfig;
-          const relPath = fwd(dir);
-          const fileRelPath = fwd(relative(dir, absFile));
-          return Response.json({
-            fileRelPath,
-            projectConfig: config,
-            relPath,
-            sitePath: dir,
-          });
-        }
-        const parent = dirname(dir);
-        if (parent === dir) {
-          break;
-        }
-        dir = parent;
+      // A page named project.json is not a project, and neither is Nx's file of that name.
+      const found = findEnclosingProjectOnDisk(dir);
+      if (found) {
+        /* SAFETY: the config is relayed to the client verbatim and not interpreted here, so its
+           member types are the client's to check; malformed JSON throws into the catch below. */
+        const config = JSON.parse(readFileSync(found.projectFile, "utf8")) as ProjectConfig;
+        return Response.json({
+          fileRelPath: fwd(relative(found.root, absFile)),
+          projectConfig: config,
+          relPath: fwd(found.root),
+          sitePath: found.root,
+        });
       }
       return Response.json({ sitePath: null });
     } catch (error) {
@@ -585,7 +583,7 @@ export async function handleStudioApi(
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
       const sites = [];
-      for await (const match of scanFiles("**/project.json", root)) {
+      for await (const match of scanFiles(`**/${PROJECT_FILE_NAME}`, root)) {
         if (
           match.includes("node_modules") ||
           fwd(match).includes("dist/") ||
@@ -595,9 +593,10 @@ export async function handleStudioApi(
         }
         const fp = resolve(root, match);
         try {
+          const text = await readFile(fp, "utf8");
           // SAFETY: JSON.parse without a reviver only ever produces JSON values.
-          const raw = JSON.parse(await readFile(fp, "utf8")) as JsonValue;
-          if (isJsonObject(raw)) {
+          const raw = JSON.parse(text) as JsonValue;
+          if (classifyProjectFile(text) === "project" && isJsonObject(raw)) {
             const projectDir = fwd(dirname(fp));
             /* SAFETY: `raw` is a JSON object and every ProjectConfig member is optional; the site
                list only relays the config to the client. */
@@ -693,9 +692,7 @@ export async function handleStudioApi(
 
       /* SAFETY: generateProject just wrote this project.json from its own template, so it is a
          project config; it is relayed to the client, not interpreted here. */
-      const config = JSON.parse(
-        await readFile(resolve(destPath, "project.json"), "utf8"),
-      ) as ProjectConfig;
+      const config = JSON.parse(await readFile(projectFilePath(destPath), "utf8")) as ProjectConfig;
       // Root-relative while the project happens to sit under the server root (the historical
       // Shape every caller already handles); absolute otherwise.
       const inRoot = containedPath(destPath, root) !== null;
@@ -938,7 +935,7 @@ export async function handleStudioApi(
    */
   if (path === "/__studio/build" && req.method === "POST") {
     const dir = activeProjectRoot ?? root;
-    if (!existsSync(resolve(dir, "project.json"))) {
+    if (!hasProjectFile(dir)) {
       return problem("invalidRequest", "Not a site project");
     }
     try {
@@ -970,7 +967,7 @@ export async function handleStudioApi(
    */
   if (path === "/__studio/preview" && req.method === "POST") {
     const dir = activeProjectRoot ?? root;
-    if (!existsSync(resolve(dir, "project.json"))) {
+    if (!hasProjectFile(dir)) {
       return problem("invalidRequest", "Not a site project");
     }
     let body: { route?: string };
@@ -1792,12 +1789,26 @@ 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", "-z", "--untracked-files=all"]),
+           count jumped to the real one the moment staging expanded them (studio.md §22.8).
+           `-- .` and the prefix: the project's changes only, in the coordinates every other verb
+           reads. Porcelain prints from the repository root whatever the cwd is (git-scope.ts). */
+        const [out, remotesOut, prefix] = await Promise.all([
+          runGit([
+            "status",
+            "--porcelain=v2",
+            "--branch",
+            "-z",
+            "--untracked-files=all",
+            "--",
+            ".",
+          ]),
           runGit(["remote"]),
+          readGitPrefix(runGit),
         ]);
         const status = parseGitStatus(out);
+        for (const file of status.files) {
+          file.path = projectRelativePath(prefix, file.path);
+        }
         const fullStatus = {
           ...status,
           isRepo: true,
@@ -1908,12 +1919,7 @@ export async function handleStudioApi(
         if (!message || !isString(message)) {
           return problem("invalidRequest", "Missing message");
         }
-        const statusOut = await runGit(["status", "--porcelain"]);
-        const hasStaged = statusOut
-          .split("\n")
-          .some((l) => l.length > 0 && l[0] !== " " && l[0] !== "?");
-        const args = hasStaged ? ["commit", "-m", message] : ["commit", "-a", "-m", message];
-        const out = await runGit(args);
+        const out = await runGit(await projectCommitArgs(runGit, message));
         const hashMatch = out.match(/\[[\w/]+ ([a-f0-9]+)\]/);
         return Response.json({ hash: hashMatch?.[1] || "", ok: true });
       }
@@ -1947,13 +1953,15 @@ export async function handleStudioApi(
         try {
           await runGit(["pull"]);
         } catch (error) {
-          const conflicts =
+          const conflicting =
             error instanceof GitCommandError
               ? conflictingPaths(`${error.stdout}\n${error.stderr}`)
               : [];
-          if (conflicts.length === 0) {
+          if (conflicting.length === 0) {
             throw error;
           }
+          const prefix = await readGitPrefix(runGit);
+          const conflicts = conflicting.map((conflict) => projectRelativePath(prefix, conflict));
           return problem(
             "conflict",
             `Pull stopped: ${conflicts.length} file(s) changed on both sides.`,
@@ -2010,9 +2018,9 @@ export async function handleStudioApi(
           return problem("invalidRequest", "Invalid path");
         }
         /* `./` IS LOAD-BEARING. `git show <rev>:<path>` resolves <path> from the REPOSITORY ROOT,
-           whatever the cwd is; only a `./` prefix makes it relative to the cwd. Every other verb
-           here — status, diff, checkout — is cwd-relative, and so is the `readFile` the studio
-           pairs this with, so without it a project nested inside its repo compared two DIFFERENT
+           whatever the cwd is; only a `./` prefix makes it relative to the cwd. The paths this API
+           answers and accepts are project-relative, and so is the `readFile` the studio pairs this
+           with, so without it a project nested inside its repo compared two DIFFERENT
            FILES: the working copy of `examples/package.json` against the committed root
            `package.json`, with no error anywhere and a plausible-looking diff. */
         const content = await runGit(["show", `${ref}:./${fp}`]);