@jxsuite/protocol 2.6.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.6.1",
+  "version": "3.0.0",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^3.0.0"
+    "@jxsuite/schema": "^4.0.0"
   }
 }

package/src/index.ts

@@ -10,4 +10,4 @@ export * from "./problems";
 export * from "./routes";
 export type * from "./types";
 // The one runtime value types.ts carries: the batch-read limit a backend and a client both size to.
-export { READ_FILES_MAX_PATHS } from "./types";
+export { IMPORT_MAX_BREAKPOINTS, IMPORT_MAX_PAGES, READ_FILES_MAX_PATHS } from "./types";

package/src/problem.ts

@@ -10,10 +10,10 @@
  * 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.
+ * - **`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.
@@ -21,6 +21,8 @@
  * @license MIT
  */
 
+import type { JsonValue } from "@jxsuite/schema/types";
+
 /** The media type a problem response carries (RFC 9457 §3). */
 export const PROBLEM_MEDIA_TYPE = "application/problem+json";
 
@@ -54,13 +56,58 @@ export interface ProblemDetails {
    * @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;
+  /**
+   * Extension members (RFC 9457 §3.2) — anything the type documents. A problem is a JSON document,
+   * so every member is a JSON value.
+   */
+  [extension: string]: JsonValue | undefined;
 }
 
-/** 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)) {
+/**
+ * The members of a failure body {@link problemDetail} consults, in the order it consults them.
+ *
+ * Each is untrusted: the body arrived from a backend of unknown vintage, so a member may hold any
+ * JSON value, and only a non-blank string counts as an answer.
+ */
+export interface FailureBodyText {
+  detail?: JsonValue;
+  error?: JsonValue;
+  title?: JsonValue;
+}
+
+/**
+ * A parsed failure body, whatever shape it turned out to be: a bare text body, any other JSON
+ * value, or a typed body carrying (or lacking) the {@link FailureBodyText} members.
+ */
+export type FailureBody = JsonValue | FailureBodyText | undefined;
+
+/*
+ * The two narrowings the readers below make on wire data. They are local rather than imported from
+ * `@jxsuite/schema/guards` because this module is part of the AI gateway's worker graph, which
+ * `packages/ai/tests/worker-safety.test.ts` freezes to the protocol's two problem modules.
+ */
+
+/** True when a wire value is a string — blank or not; the caller decides what blank means. */
+function isText(value: FailureBody): value is string {
+  return typeof value === "string";
+}
+
+/**
+ * True when a failure body is an object, whose text members may or may not be present; false for
+ * null and every primitive. An array passes and simply carries none of the members.
+ */
+function isFailureBodyText(body: FailureBody): body is FailureBodyText {
+  return typeof body === "object" && body !== null;
+}
+
+/**
+ * The slug identifying a Jx problem type, i.e. the last segment of its `type` URI.
+ *
+ * @param {JsonValue | undefined} type - A body's `type` member, as parsed off the wire
+ * @returns {string | null}
+ */
+export function problemSlug(type: JsonValue | undefined): string | null {
+  if (!isText(type) || !type.startsWith(PROBLEM_TYPE_BASE)) {
     return null;
   }
   const slug = type.slice(PROBLEM_TYPE_BASE.length);
@@ -72,8 +119,12 @@ 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";
+  return (
+    "type" in value &&
+    typeof value.type === "string" &&
+    "status" in value &&
+    typeof value.status === "number"
+  );
 }
 
 /**
@@ -87,19 +138,18 @@ export function isProblemDetails(value: unknown): value is ProblemDetails {
  * 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
+ * @param {FailureBody} 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") {
+export function problemDetail(body: FailureBody): string | null {
+  if (isText(body)) {
     return body.trim() === "" ? null : body;
   }
-  if (!body || typeof body !== "object") {
+  if (!isFailureBodyText(body)) {
     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() !== "") {
+  for (const value of [body.detail, body.error, body.title]) {
+    if (isText(value) && value.trim() !== "") {
       return value;
     }
   }
@@ -114,11 +164,11 @@ export function problemDetail(body: unknown): string | null {
  * 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 {FailureBody} 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 {
+export function problemMessage(body: FailureBody, status?: number): string {
   return (
     problemDetail(body) ?? (status === undefined ? "Request failed" : `Request failed (${status})`)
   );

package/src/problems.ts

@@ -13,6 +13,7 @@
  * @license MIT
  */
 
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import { PROBLEM_TYPE_BASE } from "./problem.ts";
 import type { ProblemDetails } from "./problem.ts";
 
@@ -33,12 +34,13 @@ const problem = (
   status: number,
   title: string,
   extensions?: readonly string[],
-): ProblemType => ({
-  status,
-  title,
-  type: `${PROBLEM_TYPE_BASE}${slug}`,
-  ...(extensions === undefined ? {} : { extensions }),
-});
+): ProblemType => {
+  const declared: ProblemType = { status, title, type: `${PROBLEM_TYPE_BASE}${slug}` };
+  if (extensions !== undefined) {
+    declared.extensions = extensions;
+  }
+  return declared;
+};
 
 /**
  * Every problem type a Jx backend may answer with, keyed by a stable name.
@@ -112,28 +114,39 @@ export type ProblemTypeName = keyof typeof PROBLEM_TYPES;
  *
  * @param {ProblemTypeName} name - A declared type
  * @param {string} [detail] - What happened THIS time
- * @param {Record<string, unknown>} [extensions] - Extension members this type documents
+ * @param {JsonObject} [extensions] - Extension members this type documents
  * @returns {ProblemDetails}
  */
 export function problemDetails(
   name: ProblemTypeName,
   detail?: string,
-  extensions: Record<string, unknown> = {},
+  extensions: JsonObject = {},
 ): ProblemDetails {
   const declared = PROBLEM_TYPES[name];
-  return {
+  const body: ProblemDetails = {
     ...extensions,
     status: declared.status,
     title: declared.title,
     type: declared.type,
-    ...(detail === undefined || detail === "" ? {} : { detail, error: detail }),
   };
+  if (detail !== undefined && detail !== "") {
+    /*
+     * The one place the deprecated `error` alias is written (see ProblemDetails.error). Its
+     * deprecation addresses readers; the writer owes it to every unmigrated client for one release,
+     * and deleting the alias is deleting `error: detail` here.
+     */
+    Object.assign(body, { detail, error: detail });
+  }
+  return body;
 }
 
-/** 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;
-  }
+/**
+ * The declared type a `type` URI names, or null when it is not one of ours.
+ *
+ * @param {JsonValue | undefined} type - A body's `type` member, as parsed off the wire
+ * @returns {ProblemType | null}
+ */
+export function problemTypeByUri(type: JsonValue | undefined): ProblemType | null {
+  // Every declared `type` is a string, so a non-string member matches nothing and answers null.
   return Object.values(PROBLEM_TYPES).find((declared) => declared.type === type) ?? null;
 }

package/src/routes.ts

@@ -44,13 +44,18 @@ const route = (
   path: string,
   summary: string,
   degradation?: string,
-): StudioRoute => ({
-  method,
-  path,
-  optional: degradation !== undefined,
-  summary,
-  ...(degradation === undefined ? {} : { degradation }),
-});
+): StudioRoute => {
+  const declared: StudioRoute = {
+    method,
+    path,
+    optional: degradation !== undefined,
+    summary,
+  };
+  if (degradation !== undefined) {
+    declared.degradation = degradation;
+  }
+  return declared;
+};
 
 /**
  * Every protocol route, keyed by a stable name. Paths are the dev server's literal `/__studio/*`
@@ -496,11 +501,19 @@ export const STUDIO_ROUTES = {
 /** A stable route name in {@link STUDIO_ROUTES}. */
 export type StudioRouteName = keyof typeof STUDIO_ROUTES;
 
+/** Every route name, in declaration order. */
+function routeNames(): StudioRouteName[] {
+  /*
+   * SAFETY: StudioRouteName is derived from this very literal (`keyof typeof STUDIO_ROUTES`), its
+   * members are readonly under `as const`, and nothing in the protocol adds keys at runtime, so its
+   * own enumerable string keys are exactly the StudioRouteName members.
+   */
+  return Object.keys(STUDIO_ROUTES) as StudioRouteName[];
+}
+
 /** Names of every route a minimal (core) backend must implement. */
 export function coreRouteNames(): StudioRouteName[] {
-  return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
-    (name) => !STUDIO_ROUTES[name].optional,
-  );
+  return routeNames().filter((name) => !STUDIO_ROUTES[name].optional);
 }
 
 /**
@@ -508,7 +521,5 @@ export function coreRouteNames(): StudioRouteName[] {
  * optimisation with a fallback).
  */
 export function optionalRouteNames(): StudioRouteName[] {
-  return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
-    (name) => STUDIO_ROUTES[name].optional,
-  );
+  return routeNames().filter((name) => STUDIO_ROUTES[name].optional);
 }

package/src/types.ts

@@ -7,7 +7,12 @@
  * @license MIT
  */
 
-import type { JsonValue as SchemaJsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { ProjectBlock, StudioHints } from "@jxsuite/schema/format-registry";
+import type {
+  JsonObject,
+  JsonValue as SchemaJsonValue,
+  JxMutableNode,
+} from "@jxsuite/schema/types";
 
 /**
  * A JSON document value, or `undefined` to signal property removal in the mutators. Re-uses the
@@ -30,7 +35,7 @@ export interface ErrorBody {
   error: string;
   /** Machine-readable discriminator (e.g. "remote_moved", "cf_not_connected"). */
   code?: string;
-  detail?: unknown;
+  detail?: SchemaJsonValue;
 }
 
 // ─── Filesystem ──────────────────────────────────────────────────────────────
@@ -95,11 +100,12 @@ export interface UploadResult {
 
 /**
  * The most paths one `filesRead` request may name. A backend answers at most this many and lists
- * the rest under {@link ReadFilesResult.omitted}, so a client that sends more is not refused — it is
- * answered in part, and asks again.
+ * the rest under {@link ReadFilesResult.omitted}, so a client that sends more is not refused — it
+ * is answered in part, and asks again.
  *
- * The one runtime value in this file: a client sizes its batches to it, so it has to exist at
- * runtime rather than only in a summary string.
+ * One of this file's three runtime values (with {@link IMPORT_MAX_PAGES} and
+ * {@link IMPORT_MAX_BREAKPOINTS}): a client sizes its batches to it, so it has to exist at runtime
+ * rather than only in a summary string.
  */
 export const READ_FILES_MAX_PATHS = 200;
 
@@ -154,7 +160,7 @@ export interface AssetCapabilities {
 export interface ReferenceHit {
   /**
    * Which key carried it: `$ref`, `$layout`, `$src`, `attr`, `imports`, `$elements`, `url`,
-   * `tagName`.
+   * `source`, `copy`, `tagName`.
    */
   refType: string;
   /** The reference exactly as authored (`"./Card.json"`), or `"<my-card>"` for a tag instance. */
@@ -195,8 +201,13 @@ export interface ReferencesResult {
 // ─── Git ─────────────────────────────────────────────────────────────────────
 
 export interface GitFileStatus {
+  /**
+   * One porcelain letter — `M`, `A`, `D`, `R`, `U` — never a word and never the raw two-column
+   * code.
+   */
   status: string;
   path: string;
+  /** Whether this change is in the index. Absent reads as unstaged. */
   staged?: boolean;
 }
 
@@ -239,34 +250,32 @@ export interface ComponentMeta {
   tagName: string;
   $id?: string | null;
   path: string;
-  props?: { name: string; type?: string; default?: JsonValue; [k: string]: unknown }[];
+  props?: { name: string; type?: string; default?: JsonValue; [k: string]: JsonValue }[];
   slots?: ComponentSlotMeta[];
   hasElements?: boolean;
+  /** The custom-element tags the component's own tree renders (`componentMetaFrom`'s `uses`). */
+  uses?: string[];
 }
 
 // ─── Extensions (specs/extensions.md §9/§9.1) ────────────────────────────────
 
-/** The `project` admission block of a section-owning extension class. */
-export interface ExtensionProjectBlock {
-  /** The project.json top-level property the class owns. */
-  key: string;
-  title?: string;
-  description?: string;
-  referenceable?: boolean;
-}
+/* The `project` admission block of a section-owning extension class: the descriptor's own block,
+   declared once in @jxsuite/schema and served here unchanged. */
+export type { ProjectBlock as ExtensionProjectBlock } from "@jxsuite/schema/format-registry";
 
 /** One project-section contribution of an extension class, as served on the formats route. */
 export interface ExtensionContributionInfo {
   /** The $prototype-visible class name declaring the `project` block. */
   className: string;
-  project: ExtensionProjectBlock;
+  project: ProjectBlock;
   /** The class descriptor's `$studio` block (settings-section vocabulary), when declared. */
-  studio?: Record<string, unknown> | null;
+  studio?: StudioHints | null;
   /**
-   * The section's value schema — `properties[<key>]` of the extension's shipped project fragment —
-   * resolved backend-side; null when the extension ships no fragment (or it lacks the key).
+   * The section's value schema — `properties[<key>]` of the extension's shipped project fragment,
+   * which JSON Schema lets be a boolean as well as an object — resolved backend-side; null when the
+   * extension ships no fragment (or it lacks the key).
    */
-  entrySchema?: Record<string, unknown> | null;
+  entrySchema?: SchemaJsonValue;
 }
 
 /**
@@ -292,7 +301,7 @@ export interface ExtensionsInfo {
     name: string;
     path: string;
     state?: boolean;
-    stateDefaults?: Record<string, unknown>;
+    stateDefaults?: JsonObject;
   }[];
 }
 
@@ -369,8 +378,8 @@ export interface ExtensionCatalogEntry {
  * editors can register them without resolving relative `$ref`s.
  */
 export interface ProjectSchemasResponse {
-  project?: Record<string, unknown> | null;
-  document?: Record<string, unknown> | null;
+  project?: JsonObject | null;
+  document?: JsonObject | null;
 }
 
 // ─── Data surface (connector domain; specs/extensions.md §13) ───────────────
@@ -397,7 +406,7 @@ export interface DataConnectionInfo {
   name: string;
   provider: string;
   /** The connection's project.json value — identifiers and env-var names, never secrets. */
-  settings: Record<string, unknown>;
+  settings: JsonObject;
   /** True when every env-var name the connection references resolves in the backend env. */
   configured: boolean;
   /** Referenced env-var NAMES with no value in the backend environment. */
@@ -419,11 +428,9 @@ export interface DataConnectionsResponse {
   connections: DataConnectionInfo[];
 }
 
-/** Result of the connection-test route (mirrors the connector's testConnection capability). */
-export interface DataConnectionTestResult {
-  ok: boolean;
-  error?: string;
-}
+/* Result of the connection-test route: the connector `testConnection` capability's own result,
+   declared once in @jxsuite/schema and relayed unchanged. */
+export type { TestConnectionResult as DataConnectionTestResult } from "@jxsuite/schema/format-registry";
 
 /**
  * A push-plan step kind. Open string union: connector DDL kinds today, and future push-step
@@ -450,13 +457,9 @@ export interface DataPushStep {
   connection?: string;
 }
 
-/** Request body of the data-push route. */
-export interface DataPushRequest {
-  /** Restrict the push to one connection; omitted = every declared connection. */
-  connection?: string;
-  /** Compile the plan without executing it. */
-  dryRun?: boolean;
-}
+/* Request body of the data-push route: the same request `jx db push` takes, declared once in
+   @jxsuite/schema. */
+export type { DataPushRequest } from "@jxsuite/schema/format-registry";
 
 /** Result of the data-push route. */
 export interface DataPushResult {
@@ -491,7 +494,7 @@ export interface DataColumnMeta {
 
 /** Result of the data-rows route. */
 export interface DataRowsResult {
-  rows: Record<string, unknown>[];
+  rows: JsonObject[];
   /** Total row count of the table (for pagination). */
   total: number;
   columns: DataColumnMeta[];
@@ -501,7 +504,7 @@ export interface DataRowsResult {
 export interface DataRowInsert {
   table: string;
   connection?: string;
-  values: Record<string, unknown>;
+  values: JsonObject;
 }
 
 /** Body of the row-update route (keyed on the introspected primary key). */
@@ -509,7 +512,7 @@ export interface DataRowUpdate {
   table: string;
   connection?: string;
   pk: string | number;
-  set: Record<string, unknown>;
+  set: JsonObject;
 }
 
 /** Parameters of the row-delete route. */
@@ -526,36 +529,35 @@ export interface SecretsListResponse {
   names: string[];
 }
 
-/** Request body of the secrets-set route (values flow in, never back out). */
-export interface SecretsSetRequest {
-  set?: Record<string, string>;
-  remove?: string[];
-}
-
 /** Response of the secrets-set route — the resulting NAMES, never values. */
 export interface SecretsSetResponse {
   ok: boolean;
   names: string[];
 }
 
-// ─── User settings (desktop launchers; specs/desktop.md §3.1) ───────────────
+// ─── Key-value patches (secrets and user settings) ──────────────────────────
 
 /**
- * A set of changes to the user-level settings store.
+ * A set of changes to a string-valued key store: the request body of the secrets-set route (values
+ * flow in, never back out; specs/extensions.md §13), and the patch the desktop launchers apply to
+ * the user-level settings store (specs/desktop.md §3.1).
  *
- * A patch rather than the whole map, and for the same reason {@link SecretsSetRequest} is one: a key
- * named by neither `set` nor `remove` must be left exactly as it was found. Writing the whole map
- * let any window overwrite the shared store with its own view of it — and on the chromium launcher
- * every window is a separate process with a separate browser profile, so a window holding no
- * settings could clear the credentials another had just stored.
+ * A patch rather than the whole map: a key named by neither `set` nor `remove` must be left exactly
+ * as it was found. Writing the whole settings map let any window overwrite the shared store with
+ * its own view of it — and on the chromium launcher every window is a separate process with a
+ * separate browser profile, so a window holding no settings could clear the credentials another had
+ * just stored.
  */
-export interface SettingsPatch {
+export interface KeyValuePatch {
   /** Keys to store, with their new values. */
   set?: Record<string, string>;
   /** Keys to forget. */
   remove?: string[];
 }
 
+/** The former published names of {@link KeyValuePatch}, kept for existing importers. */
+export type { KeyValuePatch as SecretsSetRequest, KeyValuePatch as SettingsPatch };
+
 // ─── Packages ────────────────────────────────────────────────────────────────
 
 export interface PackageInfo {
@@ -602,22 +604,32 @@ export interface AppInfo {
 
 export interface CodeServiceResult {
   code?: string;
-  diagnostics?: unknown[];
-  [key: string]: unknown;
+  diagnostics?: SchemaJsonValue[];
+  [key: string]: JsonValue;
 }
 
 // ─── Projects & starters ─────────────────────────────────────────────────────
 
-/** A starter template surfaced in the New Project picker (mirrors @jxsuite/starters StarterMeta). */
+/**
+ * A starter template surfaced in the New Project picker: one entry of `@jxsuite/starters`'
+ * `registry.json`, everything the picker needs to render a template card.
+ */
 export interface StarterInfo {
+  /** Stable id; also the directory name under `sites/` and the value threaded as `starter`. */
   id: string;
+  /** Human-facing display name, e.g. "Bistro & Café". */
   name: string;
+  /** Industry archetype label, e.g. "Restaurant & Food". */
   industry: string;
+  /** One-line summary shown under the name. */
   tagline: string;
+  /** Longer description for the showcase / tooltip. */
   description: string;
+  /** Short bullets naming the Jx features the starter demonstrates. */
   features: string[];
+  /** Accent colour (hex), mirroring the site's primary token; used for card theming. */
   accent: string;
-  /** Preview image as a self-contained `data:` URI. */
+  /** Small preview image as a self-contained `data:` URI so the picker needs no extra plumbing. */
   thumbnail: string;
 }
 
@@ -682,6 +694,18 @@ export interface ImportReadyEvent {
   root: string;
 }
 
+/**
+ * The most pages one site import may capture. A backend clamps {@link ImportSiteOptions.maxPages} to
+ * it, and a client that builds the options clamps to the same bound before it asks.
+ */
+export const IMPORT_MAX_PAGES = 100;
+
+/**
+ * The most breakpoints one site import may be asked to keep; past it, a "limit" policy is not
+ * limiting. `@jxsuite/import`'s planner clamps to it, and a client offers no larger count.
+ */
+export const IMPORT_MAX_BREAKPOINTS = 12;
+
 /** Options for the import-site pipeline (StudioPlatform.importSite). */
 export interface ImportSiteOptions {
   /** The live site to clone; must be http(s). */