@jxsuite/server 8.4.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -55,17 +55,17 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@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",
+    "@jxsuite/ai": "^0.43.2",
+    "@jxsuite/catalog": "^0.1.10",
+    "@jxsuite/collab": "^0.11.8",
+    "@jxsuite/compiler": "^8.4.0",
+    "@jxsuite/create": "^1.6.0",
+    "@jxsuite/import": "^0.43.0",
+    "@jxsuite/protocol": "^6.2.4",
+    "@jxsuite/runtime": "^6.2.1",
+    "@jxsuite/schema": "^5.4.0",
+    "@jxsuite/site": "^2.5.0",
+    "@jxsuite/starters": "^3.3.2",
     "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.8",
@@ -75,9 +75,9 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.5",
-    "@jxsuite/connector": "^0.8.5",
-    "@jxsuite/parser": "^4.3.1",
+    "@jxsuite/auth": "^0.8.6",
+    "@jxsuite/connector": "^0.8.6",
+    "@jxsuite/parser": "^4.3.2",
     "@jxsuite/test-support": "^0.0.0",
     "@types/npm-package-arg": "^6.1.4",
     "@types/npmcli__arborist": "^6.3.3",

package/src/convert.ts

@@ -1,10 +1,12 @@
 /**
- * `jx convert`: move a document between `.json` and `.jxn`, with every reference repaired.
+ * `jx convert`: move a document between `.json` and `.jxn`, with every reference repaired, and the
+ * project file between `project.json` and `project.jxn` (site-architecture.md §2.3).
  *
  * 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.
+ * leave every `$ref` to it dangling, and the refactor pass is what repairs them. A project file is
+ * named by nothing, so it needs no repair, and writing it beside the old one would leave a folder
+ * holding both, which every host refuses. 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
  */
@@ -16,6 +18,11 @@ 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 {
+  isProjectFileName,
+  parseProjectSource,
+  serializeProjectFile,
+} from "@jxsuite/schema/project-file";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { applyRename } from "./refactor/index.ts";
 
@@ -77,6 +84,34 @@ function expand(path: string): string[] {
   });
 }
 
+/** Whether a path is the project's own file, which is the one root file that converts. */
+function isProjectFileAt(root: string, path: string): boolean {
+  return isProjectFileName(relative(root, path));
+}
+
+/**
+ * Why the project file cannot be converted, or null when it can. The other name already being there
+ * needs no check here: the folder then holds both, and loading the project has refused it.
+ */
+async function projectFileRefusal(path: string, options: ConvertOptions): Promise<string | null> {
+  const ext = extname(path).toLowerCase();
+  if (ext === `.${options.to}`) {
+    return `already .${options.to}`;
+  }
+  return ext === ".jxn" ? commentRefusal(path, options) : null;
+}
+
+/** Why a `.jxn` file's comments keep it from becoming `.json`, or null when nothing would be lost. */
+async function commentRefusal(path: string, options: ConvertOptions): Promise<string | null> {
+  if (options.dropComments) {
+    return null;
+  }
+  const comments = countJxnComments(await readFile(path, "utf8"));
+  return comments > 0
+    ? `it has ${comments} comment(s), and .json has nowhere to keep them. --drop-comments converts it anyway`
+    : null;
+}
+
 /** Why a file cannot be converted, or null when it can. */
 async function refusal(
   root: string,
@@ -87,6 +122,9 @@ async function refusal(
   if (!existsSync(path)) {
     return "there is no such file";
   }
+  if (isProjectFileAt(root, path)) {
+    return projectFileRefusal(path, options);
+  }
   const name = relative(root, path).replaceAll("\\", "/");
   if (!DOCUMENT_ROOTS.some((prefix) => name.startsWith(prefix))) {
     return `only ${DOCUMENT_ROOTS.join(", ")} hold documents`;
@@ -108,13 +146,7 @@ async function refusal(
   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;
+  return ext === ".jxn" ? commentRefusal(path, options) : null;
 }
 
 /** The path a file has once converted. */
@@ -123,8 +155,12 @@ function targetOf(path: string, to: ConvertTarget): string {
 }
 
 /** The file's text in the other format. */
-async function converted(path: string, to: ConvertTarget): Promise<string> {
+async function converted(root: string, path: string, to: ConvertTarget): Promise<string> {
   const text = await readFile(path, "utf8");
+  if (isProjectFileAt(root, path)) {
+    // Canonical form: the comments a `.jxn` had are what `--drop-comments` agreed to lose.
+    return serializeProjectFile(parseProjectSource(text, path), null, targetOf(path, to));
+  }
   return to === "jxn"
     ? serializeJxn(parseJxDocument(text, path))
     : `${JSON.stringify(parseJxn(text, path), null, 2)}\n`;
@@ -156,7 +192,7 @@ export async function convertDocuments(
       continue;
     }
     try {
-      const text = await converted(path, options.to);
+      const text = await converted(root, path, options.to);
       if (options.dryRun) {
         continue;
       }
@@ -164,6 +200,9 @@ export async function convertDocuments(
          the new, and nothing beside it to be mistaken for the document. */
       await writeFile(path, text);
       await rename(path, target);
+      if (isProjectFileAt(root, path)) {
+        continue;
+      }
       const report = await applyRename({ absFrom: path, absTo: target, registry: formats, root });
       row.references = report.references.filesChanged;
       if (report.errors.length > 0) {
@@ -236,7 +275,14 @@ export async function runConvert(
     print("Usage: jx convert <paths…> --to jxn|json [--dry-run] [--drop-comments]");
     return 2;
   }
-  const rows = await convertDocuments(args.root, args.paths, args);
+  let rows: ConvertRow[];
+  try {
+    rows = await convertDocuments(args.root, args.paths, args);
+  } catch (error) {
+    // The project itself does not load, so there is nothing to convert in it.
+    print(errorMessage(error));
+    return 1;
+  }
   for (const row of rows) {
     if (row.problem !== null) {
       print(`${row.from}: ${row.problem}`);

package/src/data-api.ts

@@ -16,7 +16,7 @@
  * (kind "auth") after the connector plan inside {@link pushDataSchema}.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { Kysely, sql } from "kysely";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
@@ -53,7 +53,7 @@ import type {
   SecretsSetResponse,
 } from "@jxsuite/protocol";
 import { problem, problemTypeForStatus } from "./problem.ts";
-import { projectFilePath, readProjectFile } from "@jxsuite/schema/project-file/node";
+import { isSameStamp, projectFileStamp, readProjectFile } from "@jxsuite/schema/project-file/node";
 
 // ─── Local section shapes (structural — the connector owns the full types) ───
 
@@ -126,24 +126,27 @@ class ApiError extends Error {
 
 // ─── Project + registry resolution ───────────────────────────────────────────
 
-/** Per-project registry cache, invalidated when project.json's mtime moves. */
-const registryCache = new Map<string, { mtime: number; registry: Promise<ExtensionRegistry> }>();
+/** Per-project registry cache, invalidated when the project file moves or changes. */
+const registryCache = new Map<
+  string,
+  { mtime: number; path: string; registry: Promise<ExtensionRegistry> }
+>();
 
 /** Reset the registry cache (test hook). */
 export function resetDataApi(): void {
   registryCache.clear();
 }
 
-/** Read the project's config + connector-owned sections; 404 when there is no project.json. */
+/** Read the project's config + connector-owned sections; 404 when there is no project file. */
 function getProject(projectRoot: string): ProjectSections {
   const read = readProjectFile(projectRoot);
   if (!read) {
-    throw new ApiError(404, `No project.json under "${projectRoot}"`);
+    throw new ApiError(404, `No project file under "${projectRoot}"`);
   }
   if ("error" in read) {
     throw new ApiError(
       404,
-      `The project.json under "${projectRoot}" does not parse: ${read.error}`,
+      `The project file under "${projectRoot}" does not parse: ${read.error}`,
     );
   }
   const { config } = read;
@@ -158,16 +161,17 @@ function getProject(projectRoot: string): ProjectSections {
   return { config, connections, tables };
 }
 
-/** Build (or reuse) the project's extension registry, keyed on project.json's mtime. */
+/** Build (or reuse) the project's extension registry, keyed on the project file's stamp. */
 function getRegistry(projectRoot: string, config: ProjectConfig): Promise<ExtensionRegistry> {
-  const projectJsonPath = projectFilePath(projectRoot);
-  const mtime = statSync(projectJsonPath).mtimeMs;
+  const stamp = projectFileStamp(projectRoot);
   const cached = registryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime) {
+  if (stamp && cached && isSameStamp(cached, stamp)) {
     return cached.registry;
   }
   const registry = buildProjectExtensionRegistry(projectRoot, config);
-  registryCache.set(projectRoot, { mtime, registry });
+  if (stamp) {
+    registryCache.set(projectRoot, { ...stamp, registry });
+  }
   return registry;
 }
 

package/src/import-api.ts

@@ -36,7 +36,8 @@ import type { ImportProgressEvent } from "@jxsuite/import/pipeline";
 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 type { ProjectConfig } from "@jxsuite/schema/types";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
 import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 export interface ImportApiOptions {
@@ -86,7 +87,7 @@ type ImportStreamLine =
   | { type: "heartbeat" }
   | { type: "ready"; root: string }
   | ({ type: "progress" } & Omit<ImportProgressEvent, "root">)
-  | { type: "done"; root: string; config: JsonObject; result: ImportDoneSummary }
+  | { type: "done"; root: string; config: ProjectConfig; result: ImportDoneSummary }
   | { type: "error"; error: string };
 
 /** The AI pass's credentials, resolved from the request headers or the environment. */
@@ -298,11 +299,10 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
           writeLine({ type: "progress", ...progress });
         });
 
-        /* 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(projectFilePath(result.outDir), "utf8"),
-        ) as JsonObject;
+        // The import's emit phase has just written it; text that does not read throws into the
+        // Error line below.
+        const configPath = projectFilePath(result.outDir);
+        const config = parseProjectSource(await readFile(configPath, "utf8"), configPath);
         /*
          * The result travels with the `done` line. It used to be discarded here: the pipeline had
          * computed the page list, the file count, the warnings and (with verify) a per-page

package/src/jx-mounts.ts

@@ -16,15 +16,16 @@
  * The runtime is cached per project root and invalidated when project.json changes on disk.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 import { isString } from "@jxsuite/schema/guards";
 import { projectDevEnv } from "./dev-vars.ts";
 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";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } from "@jxsuite/schema/project-file/node";
 
 interface MountRuntime {
   handlers: { basePath: string; handler: MountHandler }[];
@@ -32,7 +33,10 @@ interface MountRuntime {
 }
 
 /** Per-project runtime cache, invalidated when project.json's mtime moves. */
-const runtimeCache = new Map<string, { mtime: number; runtime: Promise<MountRuntime | null> }>();
+const runtimeCache = new Map<
+  string,
+  { mtime: number; path: string; runtime: Promise<MountRuntime | null> }
+>();
 
 /** Reset the runtime cache (test hook). */
 export function resetJxMounts(): void {
@@ -81,35 +85,34 @@ export async function handleJxMounts(
 
 /** Load (or reuse) the mount runtime for a project root. */
 function getRuntime(projectRoot: string): Promise<MountRuntime | null> {
-  const projectJsonPath = projectFilePath(projectRoot);
-  if (!existsSync(projectJsonPath)) {
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return Promise.resolve(null);
   }
-  const { mtimeMs } = statSync(projectJsonPath);
   const cached = runtimeCache.get(projectRoot);
-  if (cached && cached.mtime === mtimeMs) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.runtime;
   }
-  const runtime = buildRuntime(projectRoot, projectJsonPath).catch((error) => {
+  const runtime = buildRuntime(projectRoot, stamp.path).catch((error) => {
     console.warn(
       `jx-mounts: failed to build extension mounts for ${projectRoot}:`,
       error instanceof Error ? error.message : String(error),
     );
     return null;
   });
-  runtimeCache.set(projectRoot, { mtime: mtimeMs, runtime });
+  runtimeCache.set(projectRoot, { ...stamp, runtime });
   return runtime;
 }
 
 /** Build the runtime: registry, sections, connector stand-ins, and the ordered mount handlers. */
 async function buildRuntime(
   projectRoot: string,
-  projectJsonPath: string,
+  projectFile: string,
 ): Promise<MountRuntime | null> {
-  /* SAFETY: trust boundary. project.json is the project's own config, held to its per-project
-     schema by the editor and `jx validate`; the sections are only relayed to the mounts that own
-     them, and any throw lands in getRuntime's catch, which disables the mounts with a warning. */
-  const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
+  /* Trust boundary. The project file is the project's own config, held to its per-project schema
+     by the editor and `jx validate`; the sections are only relayed to the mounts that own them,
+     and any throw lands in getRuntime's catch, which disables the mounts with a warning. */
+  const config = parseProjectSource(readFileSync(projectFile, "utf8"), projectFile);
   const registry = await buildProjectExtensionRegistry(projectRoot, config);
   const mounts = registry.serverMounts();
   if (mounts.length === 0) {

package/src/refactor/scan.ts

@@ -7,13 +7,20 @@
  * rename that rewrites a file the usage count never looked at is a lie in both directions.
  */
 
-import { extname } from "node:path";
+import { basename, extname } from "node:path";
 import { readFile } from "node:fs/promises";
 import type { FormatRegistry, ValueEdit } from "@jxsuite/schema/format-registry";
 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";
+import {
+  classifyJxn,
+  isJxnPath,
+  parseJxn,
+  parseProject,
+  serializeJxn,
+  serializeProject,
+} from "@jxsuite/schema/jxn";
+import type { JsonValue, JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -88,6 +95,18 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
       serialize: (doc) => Promise.resolve(rewriteJson(doc, raw)),
     };
   }
+  if (basename(fp) === "project.jxn" && classifyJxn(raw) === "project") {
+    /* The project file, in its own grammar (`site-architecture.md` §2.3): a rename repairs the
+       references it holds, `defaults.layout` among them, and the merge keeps its comments. A page
+       named `project.jxn` declares no project, and is read as the document it is below. */
+    const config: unknown = parseProject(raw, fp);
+    return {
+      doc: isJsonObject(config) ? config : null,
+      rewrite: null,
+      // SAFETY: the configuration this just read, with reference values replaced by reference values.
+      serialize: (doc) => Promise.resolve(serializeProject(doc as ProjectConfig, 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. */

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 { readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { projectDevEnv } from "./dev-vars.ts";
 import { containedPath } from "./net-guard.ts";
@@ -25,7 +25,8 @@ 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";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } from "@jxsuite/schema/project-file/node";
 
 /**
  * Any value a module exports, as the proxies see it before they check it. Nothing about an export
@@ -194,7 +195,10 @@ function baseDirectory($base: string, root: string, projectRoot: string): string
  * 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> }>();
+const projectEntryCache = new Map<
+  string,
+  { mtime: number; path: string; entry: Promise<ProjectEntry | null> }
+>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -256,31 +260,30 @@ 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 = projectFilePath(projectRoot);
-  const mtime = statSync(projectJsonPath, { throwIfNoEntry: false })?.mtimeMs;
-  if (mtime === undefined) {
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return null;
   }
   const cached = projectEntryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.entry;
   }
-  const entry = readProjectEntry(projectRoot, projectJsonPath, mtime);
-  projectEntryCache.set(projectRoot, { entry, mtime });
+  const entry = readProjectEntry(projectRoot, stamp.path, stamp.mtime);
+  projectEntryCache.set(projectRoot, { ...stamp, entry });
   return entry;
 }
 
-/** Read one `project.json` generation. Never rejects: any failure answers "no project context". */
+/** Read one project file generation. Never rejects: any failure answers "no project context". */
 async function readProjectEntry(
   projectRoot: string,
-  projectJsonPath: string,
+  projectFile: string,
   mtime: number,
 ): Promise<ProjectEntry | null> {
   try {
-    /* 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;
+    /* Trust boundary. The project file is the project's own config, 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 = parseProjectSource(readFileSync(projectFile, "utf8"), projectFile);
     const registry = await buildProjectExtensionRegistry(projectRoot, config);
     const { mounts } = await loadAssetMounts(registry, config, projectRoot);
     return { config, mounts, mtime, registry };

package/src/server.ts

@@ -42,6 +42,8 @@ import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
 import { mediaTypeForPath } from "@jxsuite/schema/media-type";
+import { isJxnPath } from "@jxsuite/schema/jxn";
+import { jxnAsJson } from "@jxsuite/site/serve";
 import { problem } from "./problem.ts";
 
 import { resolveNpmPath } from "./npm-path.ts";
@@ -175,7 +177,15 @@ export async function createDevServer(options: {
    * implementations to stop using. `mediaTypeForPath` answers null everywhere else, so the
    * inference stays in charge of the ordinary cases.
    */
-  const fileResponse = (file: ReturnType<typeof Bun.file>) => {
+  const fileResponse = async (file: ReturnType<typeof Bun.file>) => {
+    if (file.name !== undefined && isJxnPath(file.name)) {
+      /* The canvas runtime fetches a `$ref` and reads it as JSON, as a site origin answers it
+         (`@jxsuite/site` `serve.ts`); Studio reads a file's text through `/__studio/file`. */
+      return jxnAsJson(await file.bytes(), file.name, (type) => ({
+        ...NO_CACHE,
+        "Content-Type": type,
+      }));
+    }
     const corrected = file.name === undefined ? null : mediaTypeForPath(file.name);
     return new Response(file, {
       headers: corrected === null ? NO_CACHE : { ...NO_CACHE, "Content-Type": corrected },

package/src/site-output.ts

@@ -30,13 +30,13 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 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";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } 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 }>();
+const outDirCache = new Map<string, { mtime: number; outDir: string | null; path: string }>();
 
 /** Reset the output-directory cache (test hook). */
 export function resetSiteOutput(): void {
@@ -52,32 +52,27 @@ export function resetSiteOutput(): void {
  * file read.
  */
 export function siteOutDir(projectRoot: string): string | null {
-  const configPath = projectFilePath(projectRoot);
-  if (!existsSync(configPath)) {
+  // Both project files is no project until the editor's report is acted on, so this declines.
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return null;
   }
-  const { mtimeMs } = statSync(configPath);
   const cached = outDirCache.get(projectRoot);
-  if (cached && cached.mtime === mtimeMs) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.outDir;
   }
   let outDir: string | null = null;
   try {
-    // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
-    const config = JSON.parse(readFileSync(configPath, "utf8")) as JsonValue;
+    const config: unknown = parseProjectSource(readFileSync(stamp.path, "utf8"), stamp.path);
     const build = isJsonObject(config) ? config.build : undefined;
     const declared = isJsonObject(build) ? build.outDir : undefined;
-    // A `null` document has no settings to read at all, so it declines like an unparseable one.
-    outDir =
-      config === null
-        ? null
-        : resolve(projectRoot, isString(declared) && declared ? declared : "dist");
+    outDir = resolve(projectRoot, isString(declared) && declared ? declared : "dist");
   } catch {
-    // An unparseable project.json is the editor's problem to report, not this server's to guess
+    // An unparseable project file is the editor's problem to report, not this server's to guess
     // At. No output directory means this fallback simply declines, and the request 404s as before.
     outDir = null;
   }
-  outDirCache.set(projectRoot, { mtime: mtimeMs, outDir });
+  outDirCache.set(projectRoot, { ...stamp, outDir });
   return outDir;
 }
 

package/src/studio-api.ts

@@ -48,11 +48,20 @@ 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 {
+  PROJECT_FILE_NAMES,
+  classifyProjectFile,
+  parseProjectFile,
+  parseProjectSource,
+  projectFileConflict,
+} from "@jxsuite/schema/project-file";
 import {
   findEnclosingProjectOnDisk,
   hasProjectFile,
+  isSameStamp,
   projectFilePath,
+  projectFileStamp,
+  readProjectFile,
 } from "@jxsuite/schema/project-file/node";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
@@ -102,11 +111,11 @@ interface Cem {
   modules?: CemModule[];
 }
 
-// ─── Extension registry (per project root, invalidated on project.json change) ──
+// ─── Extension registry (per project root, invalidated on a project file change) ──
 
 const extensionRegistryCache = new Map<
   string,
-  { mtime: number; missing: string[]; registry: ExtensionRegistry }
+  { mtime: number; missing: string[]; path: string; registry: ExtensionRegistry }
 >();
 
 /**
@@ -121,26 +130,23 @@ const extensionRegistryCache = new Map<
  * @returns {Promise<ExtensionRegistry>}
  */
 async function getExtensionRegistry(projectRoot: string): Promise<ExtensionRegistry> {
-  const projectJsonPath = projectFilePath(projectRoot);
-  let mtime = 0;
+  const stamp = projectFileStamp(projectRoot) ?? { mtime: 0, path: "" };
   let projectConfig: ProjectConfig | undefined;
   try {
-    mtime = statSync(projectJsonPath).mtimeMs;
-    /* SAFETY: buildProjectExtensionRegistry reads only `projectConfig?.extensions` and validates
-       that list itself; every other ProjectConfig member is optional and unread on this path. */
-    projectConfig = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
+    // The registry reads only `projectConfig?.extensions`, and checks that list itself.
+    projectConfig = parseProjectSource(readFileSync(stamp.path, "utf8"), stamp.path);
   } catch {
     projectConfig = undefined;
   }
   const cached = extensionRegistryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime && !anyNowInstalled(projectRoot, cached.missing)) {
+  if (cached && isSameStamp(cached, stamp) && !anyNowInstalled(projectRoot, cached.missing)) {
     return cached.registry;
   }
   const { missing, registry } = await buildInstalledExtensionRegistry(projectRoot, projectConfig);
   if (missing.length > 0 && missing.join("\n") !== cached?.missing.join("\n")) {
     console.warn(`[studio] ${missingExtensionsNotice(missing)}`);
   }
-  extensionRegistryCache.set(projectRoot, { missing, mtime, registry });
+  extensionRegistryCache.set(projectRoot, { ...stamp, missing, registry });
   return registry;
 }
 
@@ -515,22 +521,26 @@ 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(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. */
-          projectConfig = raw as ProjectConfig;
-        }
-      } catch {}
+      let projectProblem: string | null = null;
+      const read = readProjectFile(absDir);
+      const verdict = read ? classifyProjectFile(read.text, read.path) : null;
+      if (read && "config" in read && verdict === "project") {
+        isSiteProject = true;
+        // Relayed to the client here, never interpreted.
+        projectConfig = read.config;
+      } else if (read && "error" in read && verdict !== "other" && read.text !== "") {
+        /* A file that does not read is believed, as the walk believes it (desktop.md §4.6), and
+           opened with no configuration so the client can show it as text. A folder holding both
+           files has no text to show, and stays what it was. */
+        isSiteProject = true;
+        projectProblem = read.error;
+      }
 
       return Response.json({
         directories,
         isSiteProject,
         projectConfig,
+        ...(projectProblem !== null && { projectProblem }),
         projectRoot,
       });
     } catch (error) {
@@ -548,27 +558,27 @@ export async function handleStudioApi(
       // Walk up looking for project.json. Accept a directory (e.g. the project root itself, as
       // Deep links like ?project=/abs/my-site pass) by starting the walk AT the directory and
       // Treating its project.json as the target file, so callers land on the home page.
-      let absFile = expandTilde(filePath);
-      let dir: string;
+      const absFile = expandTilde(filePath);
       let isDir = false;
       try {
         isDir = statSync(absFile).isDirectory();
       } catch {}
-      if (isDir) {
-        dir = absFile;
-        absFile = projectFilePath(absFile);
-      } else {
-        dir = dirname(absFile);
-      }
       // A page named project.json is not a project, and neither is Nx's file of that name.
-      const found = findEnclosingProjectOnDisk(dir);
+      const found = findEnclosingProjectOnDisk(isDir ? absFile : dirname(absFile));
+      if (found?.verdict === "conflict") {
+        return problem("conflict", projectFileConflict(found.root));
+      }
       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;
+        /* Relayed to the client and not interpreted here. A file that does not read is still the
+           project's (site-architecture.md §2.3): the client opens it with no configuration, says
+           where the file fails and shows it as text, rather than finding no project at all. */
+        const read = parseProjectFile(found.projectFile, readFileSync(found.projectFile, "utf8"));
+        // A folder is asked for as its project file, which the client reads as "go home".
+        const asked = isDir ? join(absFile, basename(found.projectFile)) : absFile;
         return Response.json({
-          fileRelPath: fwd(relative(found.root, absFile)),
-          projectConfig: config,
+          fileRelPath: fwd(relative(found.root, asked)),
+          projectConfig: "config" in read ? read.config : null,
+          ...("error" in read && { projectProblem: read.error }),
           relPath: fwd(found.root),
           sitePath: found.root,
         });
@@ -582,8 +592,8 @@ export async function handleStudioApi(
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
-      const sites = [];
-      for await (const match of scanFiles(`**/${PROJECT_FILE_NAME}`, root)) {
+      const sites: { config: ProjectConfig; path: string; problem?: string }[] = [];
+      for await (const match of scanFiles(`**/{${PROJECT_FILE_NAMES.join(",")}}`, root)) {
         if (
           match.includes("node_modules") ||
           fwd(match).includes("dist/") ||
@@ -594,13 +604,17 @@ 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(text) as JsonValue;
-          if (classifyProjectFile(text) === "project" && isJsonObject(raw)) {
+          if (classifyProjectFile(text, fp) === "project") {
             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. */
-            sites.push({ config: raw as ProjectConfig, path: projectDir });
+            // The site list only relays the config to the client.
+            const config = parseProjectSource(text, fp);
+            const twin = sites.find((site) => site.path === projectDir);
+            if (twin) {
+              // Neither file is the project's, so the list says so rather than choosing.
+              twin.problem = projectFileConflict(projectDir);
+            } else {
+              sites.push({ config, path: projectDir });
+            }
           }
         } catch {}
       }
@@ -690,9 +704,9 @@ export async function handleStudioApi(
       }
       await generateProject(destPath, projectOptions);
 
-      /* 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(projectFilePath(destPath), "utf8")) as ProjectConfig;
+      // It was just written by generateProject, and is relayed to the client, not interpreted.
+      const configPath = projectFilePath(destPath);
+      const config = parseProjectSource(await readFile(configPath, "utf8"), configPath);
       // 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;