@jxsuite/protocol 2.2.0 → 2.3.0

package/README.md

@@ -1,17 +1,9 @@
 # @jxsuite/protocol
 
-The **Studio Backend Protocol**: the wire types and canonical route table that
-every Jx Studio backend implements. Jx Studio is backend-agnostic. The editor
-talks to whatever registered a `StudioPlatform` adapter (see
-`@jxsuite/studio/platform`), and every adapter ultimately speaks the contract
-defined here. This package is the single source of truth for that contract:
+The **Studio Backend Protocol**: the wire types and canonical route table that every Jx Studio backend implements. Jx Studio is backend-agnostic. The editor talks to whatever registered a `StudioPlatform` adapter (see `@jxsuite/studio/platform`), and every adapter ultimately speaks the contract defined here. This package is the single source of truth for that contract:
 
-- `@jxsuite/protocol/types`: the request/response shapes (`DirEntry`,
-  `GitStatusResult`, `StarterInfo`, `AiModelsResponse`, `CfConnection`, …).
-  Environment-agnostic, with no DOM and no node, so the types are importable
-  in browsers, Bun, and Cloudflare Workers alike.
-- `@jxsuite/protocol/routes`: `STUDIO_ROUTES`, the canonical endpoint table
-  with methods, one-line contract summaries, and per-route optionality.
+- `@jxsuite/protocol/types`: the request/response shapes (`DirEntry`, `GitStatusResult`, `StarterInfo`, `AiModelsResponse`, `CfConnection`, …). Environment-agnostic, with no DOM and no node, so the types are importable in browsers, Bun, and Cloudflare Workers alike.
+- `@jxsuite/protocol/routes`: `STUDIO_ROUTES`, the canonical endpoint table with methods, one-line contract summaries, and per-route optionality.
 
 ## Who implements this
 
@@ -21,48 +13,21 @@ defined here. This package is the single source of truth for that contract:
 | Desktop (Electrobun / Chromium) | Typed RPC / WebSocket JSON-RPC dispatching into the same handlers                                         |
 | Cloud platforms                 | HTTP behind a session gateway (e.g. `/api/v1/p/:owner/:repo/:branch/studio/*`), same sub-paths and shapes |
 
-A backend is free to change the transport and path prefix; the **sub-path,
-method, and body shapes are the contract**. `STUDIO_PROTOCOL_VERSION` bumps
-when any shape changes incompatibly.
+A backend is free to change the transport and path prefix; the **sub-path, method, and body shapes are the contract**. `STUDIO_PROTOCOL_VERSION` bumps when any shape changes incompatibly.
 
 ## Core vs optional
 
-Optional routes back optional `StudioPlatform` members. Omitting one is not an
-error. Studio degrades exactly as each entry's `degradation` describes (the
-starter picker empties, the Projects catalogue hides, the Publish panel
-explains git-push publishing, and so on). `coreRouteNames()` /
-`optionalRouteNames()` split the table programmatically; a conformance test
-for a new backend can iterate `STUDIO_ROUTES` and assert every core route is
-served.
+Optional routes back optional `StudioPlatform` members. Omitting one is not an error. Studio degrades exactly as each entry's `degradation` describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). `coreRouteNames()` / `optionalRouteNames()` split the table programmatically; a conformance test for a new backend can iterate `STUDIO_ROUTES` and assert every core route is served.
 
 Highlights an implementer should know:
 
-- **`git/commit`** commits the staged files if any are staged, otherwise all
-  dirty files. Cloud backends may make commit+push atomic and treat
-  `git/push` as a sync check (`ahead` stays 0).
-- **`git/pull`** returns `409 { code: "pull_conflict", conflicts: [paths] }`
-  when local dirty files overlap remote changes.
-- **`format`** dispatches `{ format, action: "parse" | "serialize", source? |
-doc?, options? }` through the project's format registry; without it only
-  `.json` documents open.
-- **`ai/chat`** accepts `{ messages, tools, systemPrompt, model }` and streams
-  the normalized `StreamEvent` SSE defined by `@jxsuite/ai/streaming-client`.
-  `ai/models` returns `AiModelsResponse`; report `configured: true` when the
-  backend holds credentials (Studio then unlocks the assistant without a
-  locally stored key) and `managed: true` when the platform brokers them.
-- **`cf/proxy`** is an allowlisted Cloudflare API passthrough (accounts and
-  Pages projects/deployments only). Credentials are injected by the backend
-  and must never be persisted by stateless implementations. On the dev server
-  the credential is a header-borne user token, and on cloud platforms a
-  vaulted OAuth token.
-- **Errors** are `{ error, code?, detail? }` (`ErrorBody`) with a meaningful
-  HTTP status; `code` is the machine-readable discriminator Studio switches
-  on (e.g. `remote_moved`, `cf_not_connected`, `needs_installation_access`).
+- **`git/commit`** commits the staged files if any are staged, otherwise all dirty files. Cloud backends may make commit+push atomic and treat `git/push` as a sync check (`ahead` stays 0).
+- **`git/pull`** returns `409 { code: "pull_conflict", conflicts: [paths] }` when local dirty files overlap remote changes.
+- **`format`** dispatches `{ format, action: "parse" | "serialize", source? | doc?, options? }` through the project's format registry; without it only `.json` documents open.
+- **`ai/chat`** accepts `{ messages, tools, systemPrompt, model }` and streams the normalized `StreamEvent` SSE defined by `@jxsuite/ai/streaming-client`. `ai/models` returns `AiModelsResponse`; report `configured: true` when the backend holds credentials (Studio then unlocks the assistant without a locally stored key) and `managed: true` when the platform brokers them.
+- **`cf/proxy`** is an allowlisted Cloudflare API passthrough (accounts and Pages projects/deployments only). Credentials are injected by the backend and must never be persisted by stateless implementations. On the dev server the credential is a header-borne user token, and on cloud platforms a vaulted OAuth token.
+- **Errors** are `{ error, code?, detail? }` (`ErrorBody`) with a meaningful HTTP status; `code` is the machine-readable discriminator Studio switches on (e.g. `remote_moved`, `cf_not_connected`, `needs_installation_access`).
 
 ## Versioning
 
-The types are published as TypeScript source (like every `@jxsuite` package)
-and follow the monorepo's release train. Within the monorepo, packages depend
-on it via `workspace:^`. Consumers install `@jxsuite/protocol` and import its
-`/types` and `/routes` entrypoints; its only runtime dependency is
-`@jxsuite/schema`.
+The types are published as TypeScript source (like every `@jxsuite` package) and follow the monorepo's release train. Within the monorepo, packages depend on it via `workspace:^`. Consumers install `@jxsuite/protocol` and import its `/types` and `/routes` entrypoints; its only runtime dependency is `@jxsuite/schema`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.2.0",
+  "version": "2.3.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": "^2.1.0"
+    "@jxsuite/schema": "^2.2.0"
   }
 }

package/src/routes.ts

@@ -190,6 +190,16 @@ export const STUDIO_ROUTES = {
     "Only .json documents open (backs listFormats); descriptor-contributed settings sections " +
       "do not appear.",
   ),
+  extensionCatalog: route(
+    "GET",
+    "/__studio/catalog",
+    "Extensions this backend can OFFER (ExtensionCatalogEntry[]) — the shipped first-party " +
+      "catalogue plus any package in the project's own dependencies exporting a jx-extension.json, " +
+      "each marked with whether the host resolves it without a project install and whether the " +
+      "project has it installed. A capability rather than a constant: a Worker ships a fixed set " +
+      "of extension packages (specs/extensions.md §5.5). Backs listExtensionCatalog.",
+    "The Extensions section offers no catalogue; adding an extension stays a typed package name.",
+  ),
   projectSchemas: route(
     "GET",
     "/__studio/project-schemas",

package/src/types.ts

@@ -251,6 +251,73 @@ export interface ExtensionsInfo {
   }[];
 }
 
+// ─── Extension catalogue ─────────────────────────────────────────────────────
+/* The AVAILABLE half of the pair whose ENABLED half is ExtensionsInfo above. A backend answers it
+   for itself rather than serving a constant, because not every host can run every extension: a
+   Worker ships a fixed set of extension packages (specs/extensions.md §5.5), and one it does not
+   bundle is dropped from the registry before composition. Offering such an extension would promise
+   an action the host would refuse. */
+
+/** One `project.json` section an extension's classes claim (specs/extensions.md §9). */
+export interface ExtensionSectionInfo {
+  /** The `project.json` top-level property, e.g. "content". */
+  key: string;
+  /** The owning class's `project.title`, e.g. "Content Types". */
+  title?: string;
+}
+
+/** One extension a backend can offer a project, whether or not the project enables it. */
+export interface ExtensionCatalogEntry {
+  /** Package name: the identity, and the `bun add` argument. */
+  name: string;
+  /**
+   * The string that goes in `project.json` `extensions[]`. Usually `name`, but a linked or
+   * path-installed package enables under a different specifier — the same distinction
+   * {@link ExtensionsInfo} draws between `specifier` and `name`. Absent means they agree.
+   */
+  specifier?: string;
+  title?: string;
+  description?: string;
+  /**
+   * The sections enabling it makes legal.
+   *
+   * The one field a client cannot compute for itself: `listExtensions` describes only extensions
+   * already enabled, which is the state the reader is trying to leave. It is also what lets a
+   * surface warn before disabling something whose sections the project still uses.
+   */
+  sections: ExtensionSectionInfo[];
+  /** File extensions its format classes claim (".md", ".csv"), when it claims any. */
+  formats?: string[];
+  /** Other catalogue members it depends on — auth needs connector. */
+  requires?: string[];
+  /**
+   * THIS host resolves the package without a project install, so enabling it is a config write
+   * alone. Probed per host, never declared: what a desktop build stages and what a Worker bundles
+   * are different facts, and neither is knowable from the package list.
+   */
+  bundled?: boolean;
+  /**
+   * The PROJECT resolves it.
+   *
+   * Answered here rather than derived from `listPackages`, because that member does not mean one
+   * thing across backends: the dev server drops a declared dependency it cannot resolve, while the
+   * desktop reads the manifest and keeps it. A host with no module resolution at all degrades this
+   * to "declared in package.json" and says so in its own documentation.
+   */
+  installed?: boolean;
+  /** The shipped catalogue, or a package discovered in this project's own dependencies. */
+  source: "first-party" | "project";
+  /** Documentation deep link. */
+  docs?: string;
+  /**
+   * Why this entry cannot be enabled as it stands, as one sentence for a disabled control.
+   *
+   * Set rather than dropped: a package the reader installed on purpose vanishing with no
+   * explanation is worse than a row that says what is wrong with it.
+   */
+  problem?: string;
+}
+
 /**
  * Response of the project-schemas route: the project's generated entry documents
  * (project.schema.json / document.schema.json), PRE-BUNDLED into self-contained compound schemas so