@jxsuite/protocol 1.0.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -14,8 +14,10 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./types": "./src/types.ts",
-    "./routes": "./src/routes.ts"
+    "./problem": "./src/problem.ts",
+    "./problems": "./src/problems.ts",
+    "./routes": "./src/routes.ts",
+    "./types": "./src/types.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -25,6 +27,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.5.0"
+    "@jxsuite/schema": "^1.8.0"
   }
 }

package/src/index.ts

@@ -6,5 +6,7 @@
  * @license MIT
  */
 
+export * from "./problem";
+export * from "./problems";
 export * from "./routes";
 export type * from "./types";

package/src/problem.ts

@@ -0,0 +1,125 @@
+/**
+ * RFC 9457 Problem Details — one failure shape for every Jx backend.
+ *
+ * Before this, each backend invented its own: `{error: "..."}` here, bare text there, a 200 with an
+ * `upstreamError` field somewhere else. The cost landed on the client, which grew a separate reader
+ * per shape, and on the user, who could get a failure with no detail at all because the reader that
+ * ran was not the one for the shape that arrived.
+ *
+ * A problem is **data about one occurrence of one problem type**, and the type is a URI. Two
+ * decisions follow from that and are worth stating, because both look arbitrary until they are
+ * explained:
+ *
+ * - **`type` is absolute.** RFC 9457 permits a relative reference, resolved against the request
+ *   URL — which on a dev server is `http://127.0.0.1:3000/problems/…` and serves nothing. An
+ *   absolute `https://jxsuite.com/problems/…` means the same thing everywhere, which is the whole
+ *   point of identifying a type by URI.
+ * - **`instance` is never emitted.** It identifies the specific occurrence, and Jx has no
+ *   per-occurrence resource to point at. A field whose only possible value is a fabricated URI is
+ *   noise that looks like information.
+ *
+ * @license MIT
+ */
+
+/** The media type a problem response carries (RFC 9457 §3). */
+export const PROBLEM_MEDIA_TYPE = "application/problem+json";
+
+/** The namespace every Jx problem type lives under. Absolute, for the reason in the module note. */
+export const PROBLEM_TYPE_BASE = "https://jxsuite.com/problems/";
+
+/**
+ * A problem document (RFC 9457 §3.1).
+ *
+ * `title` describes the **type** and must not vary between occurrences; `detail` describes **this**
+ * occurrence and is the one a human reads. Conflating them is the standard's most common misuse and
+ * the reason a client cannot group failures.
+ */
+export interface ProblemDetails {
+  /** Absolute URI identifying the problem type. */
+  type: string;
+  /** Short, human-readable summary of the TYPE. Stable across occurrences. */
+  title: string;
+  /** The HTTP status the origin generated, repeated so a stored problem stays self-describing. */
+  status: number;
+  /** Human-readable explanation of THIS occurrence. */
+  detail?: string;
+  /**
+   * Compatibility alias for `detail`, emitted for one release.
+   *
+   * Every existing Jx client reads `body.error`. Emitting both lets the server change shape without
+   * a synchronized client release across ~160 call sites: the server lands alone, the clients
+   * follow, and a third one-line change deletes this field. It is **not** part of RFC 9457 and no
+   * new reader should be written against it.
+   *
+   * @deprecated Read `detail`. This field is removed once every client has migrated.
+   */
+  error?: string;
+  /** Extension members (RFC 9457 §3.2) — anything the type documents. */
+  [extension: string]: unknown;
+}
+
+/** The slug identifying a Jx problem type, i.e. the last segment of its `type` URI. */
+export function problemSlug(type: unknown): string | null {
+  if (typeof type !== "string" || !type.startsWith(PROBLEM_TYPE_BASE)) {
+    return null;
+  }
+  const slug = type.slice(PROBLEM_TYPE_BASE.length);
+  return slug === "" ? null : slug;
+}
+
+/** True when the value has the shape of a problem document. */
+export function isProblemDetails(value: unknown): value is ProblemDetails {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value as Partial<ProblemDetails>;
+  return typeof candidate.type === "string" && typeof candidate.status === "number";
+}
+
+/**
+ * The one line a failure body carries, or null when it carries none.
+ *
+ * The order is most-specific-first: `detail` describes THIS occurrence, the legacy `error` is the
+ * same string under the pre-RFC-9457 name, and `title` describes the TYPE — useful, but the weaker
+ * answer whenever a `detail` exists.
+ *
+ * Null rather than a generic string, because a caller usually knows a better fallback than any
+ * generic one: "Failed to list connections" beats "Request failed (500)". Use {@link problemMessage}
+ * when there is no such context.
+ *
+ * @param {unknown} body - A parsed response body, whatever shape it turned out to be
+ * @returns {string | null}
+ */
+export function problemDetail(body: unknown): string | null {
+  if (typeof body === "string") {
+    return body.trim() === "" ? null : body;
+  }
+  if (!body || typeof body !== "object") {
+    return null;
+  }
+  const candidate = body as { detail?: unknown; error?: unknown; title?: unknown };
+  for (const value of [candidate.detail, candidate.error, candidate.title]) {
+    if (typeof value === "string" && value.trim() !== "") {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * The one line a human should be shown for a failure, from any shape a Jx backend has ever sent.
+ *
+ * This is the reader the client keeps — one, not five. It reads a problem's `detail`, then the
+ * legacy `{error}` body, then the type's `title`, and finally falls back to the status. The order
+ * is most-specific-first, because a `title` describes the type rather than the occurrence and is
+ * the less useful of the two whenever a `detail` exists.
+ *
+ * @param {unknown} body - A parsed response body, whatever shape it turned out to be
+ * @param {number} [status] - The response status, used only when the body says nothing
+ * @returns {string}
+ */
+export function problemMessage(body: unknown, status?: number): string {
+  return (
+    problemDetail(body) ?? (status === undefined ? "Request failed" : `Request failed (${status})`)
+  );
+}

package/src/problems.ts

@@ -0,0 +1,128 @@
+/**
+ * The Jx problem-type registry — the failure counterpart of `STUDIO_ROUTES`.
+ *
+ * A problem type is a URI a client can key on, and a URI nobody wrote down is a string each backend
+ * spells differently. So the types live here, in one table, in the same idiom as the route table:
+ * declared once, exported as data, rendered into the docs by the same generator, and checked by the
+ * same drift machinery.
+ *
+ * **What belongs here.** A type is a *class* of failure a client might handle differently — not a
+ * message. "The project root was refused" is a type; "root /x/y was refused" is a `detail`. If two
+ * entries would only ever differ in their wording, they are one type.
+ *
+ * @license MIT
+ */
+
+import { PROBLEM_TYPE_BASE } from "./problem.ts";
+import type { ProblemDetails } from "./problem.ts";
+
+/** One declared problem type: what it means, and the status it is generated with. */
+export interface ProblemType {
+  /** Absolute `type` URI. */
+  type: string;
+  /** Short, human-readable summary of the type. Stable across occurrences. */
+  title: string;
+  /** The HTTP status this type is generated with. */
+  status: number;
+  /** Extension members this type documents, if any. */
+  extensions?: readonly string[];
+}
+
+const problem = (
+  slug: string,
+  status: number,
+  title: string,
+  extensions?: readonly string[],
+): ProblemType => ({
+  status,
+  title,
+  type: `${PROBLEM_TYPE_BASE}${slug}`,
+  ...(extensions === undefined ? {} : { extensions }),
+});
+
+/**
+ * Every problem type a Jx backend may answer with, keyed by a stable name.
+ *
+ * Grouped by what went wrong rather than by which route emitted it: the same bad request is the
+ * same problem whether it arrived at `/__studio/files` or `/__studio/data/rows`, and a client that
+ * handles `invalid-request` handles both.
+ */
+export const PROBLEM_TYPES = {
+  // ─── The request ──────────────────────────────────────────────────────────
+  invalidRequest: problem("invalid-request", 400, "The request was malformed or incomplete"),
+  notFound: problem("not-found", 404, "The requested resource does not exist"),
+  methodNotAllowed: problem("method-not-allowed", 405, "That method is not allowed on this route"),
+  conflict: problem("conflict", 409, "The request conflicts with the current state", ["conflicts"]),
+  payloadTooLarge: problem("payload-too-large", 413, "The request body is too large"),
+
+  // ─── Access ───────────────────────────────────────────────────────────────
+  /*
+   * 401 and 403 are separate types because they ask the client for different things: 401 means
+   * "authenticate and try again", 403 means "no". Collapsing them would make a missing API key
+   * indistinguishable from a refused project root.
+   */
+  unauthorized: problem("unauthorized", 401, "Credentials are missing or not accepted"),
+  forbidden: problem("forbidden", 403, "The request was refused"),
+  /*
+   * Distinct from `forbidden` because the client does something different with it: it renders an
+   * install link. That is the test for whether a type earns its own entry.
+   */
+  needsInstallationAccess: problem(
+    "needs-installation-access",
+    403,
+    "The GitHub App is not installed for that account",
+    ["installUrl"],
+  ),
+  pathOutsideProject: problem(
+    "path-outside-project",
+    403,
+    "The path resolves outside the active project",
+  ),
+
+  // ─── Backend state ────────────────────────────────────────────────────────
+  noActiveProject: problem("no-active-project", 409, "No project is active on this backend"),
+  capabilityUnavailable: problem(
+    "capability-unavailable",
+    501,
+    "This backend does not provide that capability",
+  ),
+  upstreamFailure: problem("upstream-failure", 502, "An upstream service failed", ["upstream"]),
+  internalError: problem("internal-error", 500, "The backend failed to complete the request"),
+} as const satisfies Record<string, ProblemType>;
+
+/** A stable problem-type name in {@link PROBLEM_TYPES}. */
+export type ProblemTypeName = keyof typeof PROBLEM_TYPES;
+
+/**
+ * Build a problem document for one occurrence of a declared type.
+ *
+ * `detail` is duplicated into the deprecated `error` member so existing clients keep working while
+ * they migrate; see the note on {@link ProblemDetails.error}.
+ *
+ * @param {ProblemTypeName} name - A declared type
+ * @param {string} [detail] - What happened THIS time
+ * @param {Record<string, unknown>} [extensions] - Extension members this type documents
+ * @returns {ProblemDetails}
+ */
+export function problemDetails(
+  name: ProblemTypeName,
+  detail?: string,
+  extensions: Record<string, unknown> = {},
+): ProblemDetails {
+  const declared = PROBLEM_TYPES[name];
+  return {
+    ...extensions,
+    status: declared.status,
+    title: declared.title,
+    type: declared.type,
+    ...(detail === undefined || detail === "" ? {} : { detail, error: detail }),
+  };
+}
+
+/** The declared type a `type` URI names, or null when it is not one of ours. */
+export function problemTypeByUri(type: unknown): ProblemType | null {
+  if (typeof type !== "string") {
+    return null;
+  }
+  return Object.values(PROBLEM_TYPES).find((declared) => declared.type === type) ?? null;
+}

package/src/routes.ts

@@ -114,6 +114,15 @@ export const STUDIO_ROUTES = {
   fileDelete: route("DELETE", "/__studio/file", "Delete a file"),
   fileUpload: route("POST", "/__studio/file/upload", "Upload binary content to a path"),
   fileRename: route("POST", "/__studio/file/rename", "Rename/move (+ refactor report)"),
+  references: route(
+    "GET",
+    "/__studio/references",
+    "Where a file or a component tag is used (?path=&tag=, at least one) → ReferencesResult " +
+      "{files, filesReferencing, refsTotal} — the read side of the rename refactor's own walker, " +
+      "cached until the backend's watcher sees the tree move (backs findReferences)",
+    'Usage counts are hidden: no "Used on N pages" in the inspector, no Selection: Find Usages, ' +
+      "and delete/rename confirmations state no reference count.",
+  ),
   locate: route("POST", "/__studio/locate", "Find a file by name → {path | null}"),
   collab: route(
     "GET",
@@ -121,8 +130,11 @@ export const STUDIO_ROUTES = {
     "Realtime co-editing: a WebSocket upgrade speaking the @jxsuite/collab wire envelope (one " +
       "socket per project, documents multiplexed by path; y-protocols sync + project-level " +
       "awareness in lib0 binary frames — see @jxsuite/collab/envelope for the frame layout and " +
-      "the docEpoch/doc-reset lifecycle). A plain GET (no Upgrade) answers {collab: true, " +
-      "version} as the capability probe.",
+      "the docEpoch/doc-reset lifecycle). A plain GET (no Upgrade) answers {collab, protocols, " +
+      "version} as the capability probe, and `protocols` is the subprotocol negotiation: the " +
+      "client offers one of them as Sec-WebSocket-Protocol and the server echoes it, or the " +
+      "client offers none when the server advertises none, because RFC 6455 §4.1 fails a " +
+      "connection whose offer went unechoed.",
     "Realtime co-editing is unavailable; Studio edits solo with file-level saves",
   ),
 
@@ -183,6 +195,27 @@ export const STUDIO_ROUTES = {
     "Code editors show no lint markers.",
   ),
 
+  // ─── Site build ───────────────────────────────────────────────────────────
+  /**
+   * Build the site to its output directory, so what a reader opens is what the author sees.
+   *
+   * `View: Open in Browser` runs this first. Without it the reader gets whatever the last build
+   * left on disk — which for most projects is nothing, and for the rest is yesterday — while the
+   * canvas beside them shows today. A preview that silently shows stale output is worse than one
+   * that says it cannot open.
+   *
+   * The reply also names `url`, the ORIGIN the result is browsable at. It is not this server's:
+   * these paths mean the project's SOURCES, and a built page addresses its own OUTPUT by the same
+   * paths (`/components/x.js` is the formula module here and the custom element there), so a
+   * backend serves the built site somewhere of its own and says where.
+   */
+  buildSite: route(
+    "POST",
+    "/__studio/build",
+    "Build the site to its output directory → {routes, files, errors, url}",
+    "Open in Browser reports that this target cannot build a preview.",
+  ),
+
   // ─── Packages ─────────────────────────────────────────────────────────────
   packages: route("GET", "/__studio/packages", "List dependencies (PackageInfo[])"),
   packagesAdd: route("POST", "/__studio/packages/add", "Add a dependency"),

package/src/types.ts

@@ -18,7 +18,15 @@ export type JsonValue = SchemaJsonValue | undefined;
 
 // ─── Errors ──────────────────────────────────────────────────────────────────
 
-/** Message-level failure body every protocol route may return. */
+/**
+ * The pre-RFC-9457 failure body.
+ *
+ * Superseded by {@link ProblemDetails} in `./problem.ts`, and kept because it is still the shape a
+ * client may receive from a backend that has not migrated. A conforming backend answers
+ * `application/problem+json`; a reader written with `problemDetail` handles both.
+ *
+ * @deprecated Emit a problem document. Read this only through `problemDetail`.
+ */
 export interface ErrorBody {
   error: string;
   /** Machine-readable discriminator (e.g. "remote_moved", "cf_not_connected"). */
@@ -60,6 +68,48 @@ export interface RenameResult {
   error?: string;
 }
 
+/** One kind of reference in one file, with how many times it occurs there. */
+export interface ReferenceHit {
+  /**
+   * Which key carried it: `$ref`, `$layout`, `$src`, `attr`, `imports`, `$elements`, `url`,
+   * `tagName`.
+   */
+  refType: string;
+  /** The reference exactly as authored (`"./Card.json"`), or `"<my-card>"` for a tag instance. */
+  ref: string;
+  count: number;
+}
+
+/** Every reference to the queried target from one document. */
+export interface ReferenceFile {
+  /** Project-relative, forward-slashed. */
+  path: string;
+  /** Total references in this file (the sum of `refs[].count`). */
+  count: number;
+  refs: ReferenceHit[];
+}
+
+/**
+ * Where a file or a component tag is used — the answer behind "Used on N pages", Find Usages, and
+ * the reference count inside every delete and rename confirmation. Never includes the target file
+ * itself: a component's own definition declares the tag it is named by, and counting that would
+ * report an unused component as used once.
+ */
+export interface ReferencesResult {
+  /** The project-relative path queried, or null when only a tag was. */
+  path: string | null;
+  /** The tag queried — passed in, or derived from a component document at `path`. */
+  tagName: string | null;
+  /** Referencing files, sorted by path. */
+  files: ReferenceFile[];
+  /** `files.length`, carried on the wire so a caller can render a count without the list. */
+  filesReferencing: number;
+  /** Total references across every file. */
+  refsTotal: number;
+  /** Documents that could not be parsed. A non-empty list makes every count above a FLOOR. */
+  errors: { path: string; error: string }[];
+}
+
 // ─── Git ─────────────────────────────────────────────────────────────────────
 
 export interface GitFileStatus {