@jxsuite/protocol 2.1.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.1.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.0.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
@@ -576,7 +643,11 @@ export interface ImportSiteOptions {
   url: string;
   /** Display name for the new project. */
   name: string;
-  /** Destination directory (platform-interpreted: project-relative on the dev server). */
+  /**
+   * Where the project goes, interpreted by the platform that receives it: an absolute path on
+   * desktop, project-relative on the dev server, `owner/repo` on a host whose projects are
+   * repositories. Never a path the caller assumes a filesystem for.
+   */
   directory: string;
   /** Max crawl depth; 0 = single page. */
   depth: number;
@@ -701,9 +772,61 @@ export interface AiModelsResponse {
 
 // ─── Cloudflare publish surface ──────────────────────────────────────────────
 
-/** Cloudflare connection state (see StudioPlatform.cfConnection). */
+/**
+ * Cloudflare connection state (see StudioPlatform.cfConnection).
+ *
+ * Three answers, not two, and a reader tells them apart by SHAPE:
+ *
+ * - `null` — no credential and no row exists at all; nothing was ever connected here.
+ * - `{connected: false}` — a credential exists but the provider rejected it. That is the dev server's
+ *   stored-token-invalid case, and the publish panel's "Replace token" branch keys on it.
+ * - `{connected: true, needsReconnect: true}` — a brokered row exists whose OAuth grant has lapsed.
+ *   Its access token is gone or unrenewable, so every Cloudflare call will fail until the user goes
+ *   back through the hosted flow.
+ *
+ * Each platform emits a strict subset: **cloud never emits `{connected: false}`** (a broker row it
+ * cannot use is a reconnect, not a bad token) and **the dev server never emits `needsReconnect`**
+ * (it holds a pasted token, not a grant, so there is nothing to lapse). Collapsing the lapsed case
+ * into a healthy one is precisely the defect that let the connect popup close over a dead row while
+ * the user was still typing their Cloudflare password.
+ */
 export interface CfConnection {
   connected: boolean;
   accountId?: string | undefined;
   accountName?: string | undefined;
+  /** A broker row exists but its grant has lapsed — reconnect before any Cloudflare call. */
+  needsReconnect?: boolean | undefined;
+  /** Connected and usable, but no account has been chosen yet (multi-account connect). */
+  needsAccount?: boolean | undefined;
+  code?: "cf_reconnect_required" | "cf_account_required" | undefined;
+  reason?: string | undefined;
+  /**
+   * Whether the broker holds a refresh token for this row. Diagnostic: without one the connection
+   * dies at the access token's expiry and cannot renew itself silently, which is a degraded state
+   * worth naming on screen rather than discovering an hour later.
+   */
+  hasRefreshToken?: boolean | undefined;
+  /** Unix seconds at which the current access token expires (after any silent refresh). */
+  expiresAt?: number | undefined;
+}
+
+/** One Cloudflare account the connected grant can reach (the account picker's row). */
+export interface CfAccountSummary {
+  id: string;
+  name: string;
 }
+
+/**
+ * How an interactive `cfConnect` ended.
+ *
+ * A connect flow has four endings and only one of them is a failure, so they are a union rather
+ * than a nullable connection: `redirect` means the page is already navigating away and the caller
+ * must render nothing, `timeout` means the deadline passed with no confirmation, and `canceled`
+ * means the user closed the popup. Returning `null` for all three made "the user changed their
+ * mind" indistinguishable from "this browser blocked the popup", and the UI apologised for both.
+ */
+export type CfConnectOutcome =
+  | { status: "connected"; connection: CfConnection }
+  | { status: "redirect" }
+  | { status: "timeout" }
+  | { status: "canceled" };