@jxsuite/server 4.5.0 → 6.0.0

package/src/oauth-loopback.ts

@@ -28,6 +28,7 @@
  * string of its own and `Referrer-Policy: no-referrer`, so nothing carries it onward.
  */
 
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
 import { secretsMatch } from "./net-guard.ts";
 
 /** The loopback redirect path this server hosts. */
@@ -345,29 +346,33 @@ export async function exchangeCode(params: {
     headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
     method: "POST",
   });
-  const payload = (await response.json().catch(() => null)) as {
-    access_token?: unknown;
-    error?: unknown;
-    error_description?: unknown;
-    expires_in?: unknown;
-    refresh_token?: unknown;
-    scope?: unknown;
-    token_type?: unknown;
-  } | null;
+  // A body that is not JSON reads as no payload, and is reported by status below.
+  const payload: unknown = await response.json().catch(() => null);
+  const fields = isJsonObject(payload) ? payload : null;
 
-  if (payload && typeof payload.error === "string") {
-    const description =
-      typeof payload.error_description === "string" ? payload.error_description : payload.error;
+  if (fields && isString(fields.error)) {
+    const description = isString(fields.error_description)
+      ? fields.error_description
+      : fields.error;
     throw new Error(`The provider refused the sign-in: ${description}`);
   }
-  if (!response.ok || !payload || typeof payload.access_token !== "string") {
+  if (!response.ok || !fields || !isString(fields.access_token)) {
     throw new Error(`The token exchange failed (HTTP ${response.status}).`);
   }
+  // RFC 6749 §5.1 makes these optional; each is kept only when the provider sent the right type.
+  const optional: Pick<TokenResult, "expiresIn" | "refreshToken" | "scope"> = {};
+  if (isNumber(fields.expires_in)) {
+    optional.expiresIn = fields.expires_in;
+  }
+  if (isString(fields.refresh_token)) {
+    optional.refreshToken = fields.refresh_token;
+  }
+  if (isString(fields.scope)) {
+    optional.scope = fields.scope;
+  }
   return {
-    accessToken: payload.access_token,
-    ...(typeof payload.expires_in === "number" ? { expiresIn: payload.expires_in } : {}),
-    ...(typeof payload.refresh_token === "string" ? { refreshToken: payload.refresh_token } : {}),
-    ...(typeof payload.scope === "string" ? { scope: payload.scope } : {}),
-    tokenType: typeof payload.token_type === "string" ? payload.token_type : "bearer",
+    accessToken: fields.access_token,
+    ...optional,
+    tokenType: isString(fields.token_type) ? fields.token_type : "bearer",
   };
 }

package/src/packages.ts

@@ -8,42 +8,23 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-
-export interface PackageInfo {
-  name: string;
-  version: string;
-  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
-  dev?: boolean;
-}
-
-/**
- * A dependency's pinned range beside the newest version published for it on the registry.
- *
- * Every registry-range dependency gets a row, behind or not. Deciding whether a row is an upgrade
- * needs a semver comparison against the range's base, and the caller — which has to make that
- * comparison anyway to tell an upgrade from a project deliberately pinned ahead — is where it
- * belongs. A backend that filtered here could only describe an up-to-date package as an absence.
- */
-export interface PackageVersionInfo {
-  name: string;
-  /** The version range pinned in package.json (e.g. "^0.19.0"). */
-  current: string;
-  /** The newest version published for this package on the registry. */
-  latest: string;
-  dev?: boolean;
-}
-
-/** Result of a package mutation that runs `bun install` (install / set-versions). */
-export interface PackageOpResult {
-  ok: boolean;
-  /** Combined stdout/stderr from the bun invocation, surfaced to the user on failure. */
-  log?: string;
-}
-
+import type { PackageInfo, PackageOpResult, PackageVersionInfo } from "@jxsuite/protocol";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/* The package rows and operation result are the Studio wire contract (`packages*` routes), declared
+   once in @jxsuite/protocol; re-exported so this module's public names stay. Every
+   registry-range dependency gets a `PackageVersionInfo` row, behind or not: deciding whether a row
+   is an upgrade needs a semver comparison against the range's base, and the caller, which has to
+   make that comparison anyway to tell an upgrade from a project deliberately pinned ahead, is where
+   it belongs. A backend that filtered here could only describe an up-to-date package as an
+   absence. */
+export type { PackageInfo, PackageOpResult, PackageVersionInfo } from "@jxsuite/protocol";
+
+/** The manifest members this module edits; every other member is written back unchanged. */
 interface PackageJson {
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
-  [key: string]: unknown;
+  [key: string]: JsonValue | undefined;
 }
 
 /** Minimal fetch signature (injectable for tests; the global `fetch` satisfies it). */
@@ -72,6 +53,9 @@ async function readPackageJson(root: string): Promise<PackageJson | null> {
     return null;
   }
   try {
+    /* SAFETY: package.json is the npm manifest `bun install` reads, an object whose
+       `dependencies`/`devDependencies` map package names to version-spec strings; text that is
+       not JSON throws into the catch below. */
     return JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
   } catch {
     return null;
@@ -104,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 {
@@ -120,7 +104,11 @@ async function runBun(args: string[], cwd: string): Promise<PackageOpResult> {
     proc.exited,
   ]);
   const log = `${stdout}${stderr}`.trim();
-  return { ok: exitCode === 0, ...(log ? { log } : {}) };
+  const result: PackageOpResult = { ok: exitCode === 0 };
+  if (log) {
+    result.log = log;
+  }
+  return result;
 }
 
 /** Run `bun install` in the project root. */
@@ -165,6 +153,8 @@ export async function fetchLatestVersion(
     if (!res.ok) {
       return null;
     }
+    /* SAFETY: the registry's version endpoint answers that version's manifest, whose `version`
+       is a string; a body that is not JSON (or is `null`) throws into the catch, giving null. */
     const data = (await res.json()) as { version?: string };
     return data.version ?? null;
   } catch {
@@ -228,6 +218,7 @@ export async function setPackageVersions(
   }
   let pkg: PackageJson;
   try {
+    // SAFETY: same npm manifest contract as readPackageJson; unparseable text is caught below.
     pkg = JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
   } catch (error) {
     return { log: `Unparseable package.json: ${String(error)}`, ok: false };
@@ -239,8 +230,7 @@ export async function setPackageVersions(
       pkg.dependencies[update.name] = update.version;
     } else {
       const bucket = update.dev ? "devDependencies" : "dependencies";
-      pkg[bucket] = { ...(pkg[bucket] as Record<string, string> | undefined) };
-      (pkg[bucket] as Record<string, string>)[update.name] = update.version;
+      pkg[bucket] = { ...pkg[bucket], [update.name]: update.version };
     }
   }
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");

package/src/problem.ts

@@ -13,6 +13,7 @@
 
 import { PROBLEM_MEDIA_TYPE, problemDetails } from "@jxsuite/protocol";
 import type { ProblemTypeName } from "@jxsuite/protocol";
+import type { JsonObject } from "@jxsuite/schema/types";
 
 /**
  * A failure response for one occurrence of a declared problem type.
@@ -23,14 +24,10 @@ import type { ProblemTypeName } from "@jxsuite/protocol";
  *
  * @param {ProblemTypeName} name - A declared type from `PROBLEM_TYPES`
  * @param {string} [detail] - What happened this time; the line a human reads
- * @param {Record<string, unknown>} [extensions] - Extension members this type documents
+ * @param {JsonObject} [extensions] - Extension members this type documents
  * @returns {Response}
  */
-export function problem(
-  name: ProblemTypeName,
-  detail?: string,
-  extensions?: Record<string, unknown>,
-): Response {
+export function problem(name: ProblemTypeName, detail?: string, extensions?: JsonObject): Response {
   const body = problemDetails(name, detail, extensions);
   // The explicit Content-Type is the point: `Response.json` would send `application/json`, and
   // RFC 9457 §3 is what tells a client this body is a problem rather than a result.

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:
  *
@@ -43,18 +42,44 @@ import {
 import { problem } from "./problem.ts";
 import { createLoopbackAuthorizer, OAUTH_CALLBACK_PATH } from "./oauth-loopback.ts";
 import type { LoopbackAuthorizer } from "./oauth-loopback.ts";
+import type { FsEventBatch } from "./sse.ts";
+import type { JsonPrimitive, JsonValue } from "@jxsuite/schema/types";
+
+/**
+ * What a handler answers, sent as the reply frame's `result`: anything `JSON.stringify` encodes,
+ * with `undefined` sent as `null`. Objects are admitted by kind rather than by JSON shape because
+ * handlers answer with typed values, and TypeScript never treats an interface as a `JsonValue`.
+ */
+export type RpcResult = JsonPrimitive | object | undefined;
+
+/** One RPC method: the request frame's decoded `params` in, the reply's `result` out. */
+export type RpcHandler = (params: JsonValue | undefined) => Promise<RpcResult>;
+
+/**
+ * What an unsolicited push carries as its `params`: JSON, or the filesystem batch the sidebar
+ * consumes (the same batch the dev server sends as its SSE `fs` event).
+ */
+export type RpcPushParams = JsonValue | FsEventBatch;
+
+/** An RPC request frame as the shell sends it: the id the reply echoes, and what to dispatch. */
+export interface RpcRequestFrame {
+  id: number;
+  method: string;
+  params?: JsonValue;
+}
 
 /** A resolved per-window session: its project root plus its RPC handler map. */
 export interface ProjectServerSession {
   projectRoot: string | null;
-  handlers: Record<string, (params: unknown) => Promise<unknown>>;
+  handlers: Record<string, RpcHandler>;
 }
 
 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/. */
@@ -89,7 +114,7 @@ export interface ProjectServerHandle {
    * @param winId Deliver only to sockets stashed with this window id; omit for every socket.
    * @returns How many sockets the message reached — 0 means nothing is listening yet.
    */
-  push: (method: string, params?: unknown, winId?: string | null) => number;
+  push: (method: string, params?: RpcPushParams, winId?: string | null) => number;
   /**
    * The RFC 8252 loopback authorization host. The desktop launcher drives it: `begin()` for the URL
    * to open in the user's browser, then `await pending.code` and {@link exchangeCode}.
@@ -337,9 +362,14 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         sockets.delete(ws);
       },
       async message(ws, raw) {
-        let msg: { id: number; method: string; params?: unknown };
+        let msg: RpcRequestFrame;
         try {
-          msg = JSON.parse(raw as string) as { id: number; method: string; params?: unknown };
+          /* SAFETY: trust boundary. A binary frame decodes as UTF-8, exactly as JSON.parse's own
+             string coercion would, and the parse yields a JSON value. The only client on this
+             token-gated socket is the shell's RPC transport, which sends `{ id, method, params }`;
+             a frame that breaks that finds no handler under its `method` and is answered with an
+             error (a `null` frame throws in this callback, as it always has). */
+          msg = JSON.parse(raw.toString()) as RpcRequestFrame;
         } catch {
           ws.send(JSON.stringify({ error: "Invalid JSON", id: 0 }));
           return;

package/src/refactor/apply.ts

@@ -10,6 +10,7 @@
 
 import { basename, dirname, extname, relative, resolve } from "node:path";
 import { stat, writeFile } from "node:fs/promises";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { isUnder } from "./paths.ts";
 import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
@@ -99,9 +100,9 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
   if (!isDir) {
     try {
       const { doc } = await loadDoc(absTo, opts.registry);
-      const oldTag = (doc as { tagName?: unknown }).tagName;
+      const oldTag = isJsonObject(doc) ? doc.tagName : undefined;
       const newTag = deriveTag(absTo);
-      if (typeof oldTag === "string" && oldTag.includes("-") && newTag !== oldTag) {
+      if (isString(oldTag) && oldTag.includes("-") && newTag !== oldTag) {
         if (newTag.includes("-")) {
           tagRename = { from: oldTag, to: newTag };
         } else {

package/src/refactor/fs-events.ts

@@ -5,26 +5,25 @@
  */
 
 import { relative } from "node:path";
+import type { FsEvent } from "@jxsuite/protocol";
 
-/** A filesystem change as broadcast to the studio shell (root-relative, forward-slashed path). */
-export interface FsEventPayload {
-  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
-  path: string;
-  isDir: boolean;
-}
+/* A filesystem change as broadcast to the studio shell is the protocol's `FsEvent`, declared once
+   there; `FsEventPayload` stays this module's public name for it. */
+export type { FsEvent as FsEventPayload } from "@jxsuite/protocol";
+
+const VALID: ReadonlySet<string> = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
 
-const VALID = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
+/** Whether chokidar's `eventType` is one of the five changes the sidebar is told about. */
+function isFsEventType(eventType: string): eventType is FsEvent["type"] {
+  return VALID.has(eventType);
+}
 
 /**
  * Map one chokidar event to a payload, or null for events we ignore (`ready`/`raw`/`error`) or
  * paths that escape the root.
  */
-export function toFsEvent(
-  eventType: string,
-  root: string,
-  changedPath: string,
-): FsEventPayload | null {
-  if (!VALID.has(eventType)) {
+export function toFsEvent(eventType: string, root: string, changedPath: string): FsEvent | null {
+  if (!isFsEventType(eventType)) {
     return null;
   }
   const path = relative(root, changedPath).replaceAll("\\", "/");
@@ -34,7 +33,7 @@ export function toFsEvent(
   return {
     isDir: eventType === "addDir" || eventType === "unlinkDir",
     path,
-    type: eventType as FsEventPayload["type"],
+    type: eventType,
   };
 }
 
@@ -42,7 +41,7 @@ export function toFsEvent(
  * Fold one event into a buffer, collapsing redundant churn per path (last-write-wins, except
  * add+unlink cancels, add+change stays add, and unlink+add becomes a re-add). Returns a new array.
  */
-export function coalesceFsEvents(buffer: FsEventPayload[], next: FsEventPayload): FsEventPayload[] {
+export function coalesceFsEvents(buffer: FsEvent[], next: FsEvent): FsEvent[] {
   const prev = buffer.find((e) => e.path === next.path);
   if (!prev) {
     return [...buffer, next];

package/src/refactor/paths.ts

@@ -19,6 +19,8 @@
 
 import { BUILD_LANES, projectPathsForSiteUrl, siteUrlForPath } from "@jxsuite/schema/asset-paths";
 import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /**
  * The lanes a rewritten site URL is re-emitted through, most-publishable first.
@@ -43,6 +45,12 @@ const AUTHORED_LANES: readonly AssetLane[] = [...BUILD_LANES, "root"];
  */
 const READ_LANES: readonly AssetLane[] = ["mounts", "root", "public"];
 
+/** A path-like value split at its first `?` or `#`: the path itself, and what trails it. */
+export interface RefParts {
+  core: string;
+  suffix: string;
+}
+
 /** Classification of a reference string value. */
 export type RefClass =
   | { kind: "none" }
@@ -51,7 +59,7 @@ export type RefClass =
   | { kind: "path"; core: string; suffix: string; rooted: boolean };
 
 /** Split a trailing `?query` or `#fragment` off a path-like value. */
-export function splitQueryHash(value: string): { core: string; suffix: string } {
+export function splitQueryHash(value: string): RefParts {
   for (let i = 0; i < value.length; i += 1) {
     const ch = value[i];
     if (ch === "?" || ch === "#") {
@@ -68,8 +76,8 @@ export function splitQueryHash(value: string): { core: string; suffix: string }
  * actual precision, so bare npm specifiers (which never resolve to the renamed file) are simply
  * never matched.
  */
-export function classifyRef(value: unknown): RefClass {
-  if (typeof value !== "string" || value.length === 0) {
+export function classifyRef(value: JsonValue | undefined): RefClass {
+  if (!isString(value) || value.length === 0) {
     return { kind: "none" };
   }
   if (
@@ -249,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 },
@@ -262,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);