@jxsuite/protocol 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @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:
+
+- `@jxsuite/protocol/types` — the request/response shapes (`DirEntry`,
+  `GitStatusResult`, `StarterInfo`, `AiModelsResponse`, `CfConnection`, …).
+  Environment-agnostic: no DOM, no node — 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
+
+| Backend                         | Transport                                                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@jxsuite/server` (dev server)  | The literal `/__studio/*` HTTP routes — the reference implementation                                      |
+| 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.
+
+## 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.
+
+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 —
+  a header-borne user token on the dev server, a vaulted OAuth token on cloud
+  platforms — and must never be persisted by stateless implementations.
+- **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:^`.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jxsuite/protocol",
+  "version": "0.1.0",
+  "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./routes": "./src/routes.ts"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * The Studio Backend Protocol package: wire types plus the canonical route
+ * table every Jx Studio backend implements. See README.md for the implementer
+ * guide.
+ *
+ * @license MIT
+ */
+
+export * from "./routes";
+export type * from "./types";

package/src/routes.ts

@@ -0,0 +1,206 @@
+/**
+ * Studio Backend Protocol — the canonical route table. The dev server
+ * (@jxsuite/server) is the reference implementation; every other backend
+ * (desktop RPC bridge, cloud platforms) serves the same shapes, either at
+ * these literal paths or through an equivalent transport. Optional routes
+ * back optional StudioPlatform members — Studio degrades without them, as
+ * described by each entry's `degradation`.
+ *
+ * @license MIT
+ */
+
+/** Bumped when a route's request/response shape changes incompatibly. */
+export const STUDIO_PROTOCOL_VERSION = 1;
+
+export type StudioRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+export interface StudioRoute {
+  path: string;
+  method: StudioRouteMethod;
+  /** True when a backend may omit the route (its PAL member is optional). */
+  optional: boolean;
+  /** One-line contract summary. */
+  summary: string;
+  /** What Studio does when an optional route is absent. */
+  degradation?: string;
+}
+
+const route = (
+  method: StudioRouteMethod,
+  path: string,
+  summary: string,
+  degradation?: string,
+): StudioRoute => ({
+  method,
+  path,
+  optional: degradation !== undefined,
+  summary,
+  ...(degradation === undefined ? {} : { degradation }),
+});
+
+/**
+ * Every protocol route, keyed by a stable name. Paths are the dev server's literal `/__studio/*`
+ * endpoints; transport-mapped backends (RPC, gateway prefixes) preserve the sub-path and shapes.
+ */
+export const STUDIO_ROUTES = {
+  // ─── Session / project ────────────────────────────────────────────────────
+  activate: route("POST", "/__studio/activate", "Bind the backend to a project root"),
+  project: route("GET", "/__studio/project", "Root project metadata {name, root}"),
+  projectInfo: route(
+    "GET",
+    "/__studio/project-info",
+    "Probe a directory: {isSiteProject, projectConfig?, directories?}",
+  ),
+  resolveSite: route(
+    "GET",
+    "/__studio/resolve-site",
+    "Resolve the owning site of a file path {sitePath, projectConfig?, fileRelPath?}",
+  ),
+  sites: route(
+    "GET",
+    "/__studio/sites",
+    "Enumerate site projects [{config, path}] (backs listProjects)",
+    "The welcome screen's Projects catalogue stays hidden.",
+  ),
+  findProject: route(
+    "GET",
+    "/__studio/find-project",
+    "Locate a project directory by name outside the root",
+    "openProject falls back to config-matching only.",
+  ),
+  createProject: route("POST", "/__studio/create-project", "Scaffold a project → {root, config}"),
+  starters: route(
+    "GET",
+    "/__studio/starters",
+    "Starter templates (StarterInfo[])",
+    "The New Project picker offers only blank/templates.",
+  ),
+
+  // ─── Filesystem ───────────────────────────────────────────────────────────
+  files: route("GET", "/__studio/files", "List a directory (DirEntry[])"),
+  fileRead: route("GET", "/__studio/file", "Read a file's text content"),
+  fileWrite: route("PUT", "/__studio/file", "Write a file's text content"),
+  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)"),
+  locate: route("POST", "/__studio/locate", "Find a file by name → {path | null}"),
+
+  // ─── Documents / components / formats ─────────────────────────────────────
+  components: route("GET", "/__studio/components", "Discover components (ComponentMeta[])"),
+  cem: route(
+    "GET",
+    "/__studio/cem",
+    "Custom-elements manifest of an npm dependency",
+    "Dependency components lose prop/slot metadata.",
+  ),
+  formats: route(
+    "GET",
+    "/__studio/formats",
+    "The project's format registry entries",
+    "Only .json documents open (backs listFormats).",
+  ),
+  format: route(
+    "POST",
+    "/__studio/format",
+    "Dispatch a format capability {format, action: parse|serialize, source?|doc?}",
+    "Non-JSON documents cannot be parsed/serialized (backs formatAction).",
+  ),
+  pluginSchema: route(
+    "GET",
+    "/__studio/plugin-schema",
+    "Extract a $studio schema from a class source",
+    "Plugin property panels fall back to generic JSON editing.",
+  ),
+
+  // ─── Packages ─────────────────────────────────────────────────────────────
+  packages: route("GET", "/__studio/packages", "List dependencies (PackageInfo[])"),
+  packagesAdd: route("POST", "/__studio/packages/add", "Add a dependency"),
+  packagesRemove: route("POST", "/__studio/packages/remove", "Remove a dependency"),
+  packagesInstall: route(
+    "POST",
+    "/__studio/packages/install",
+    "Run the package manager install",
+    "Install/reinstall affordances are hidden; manifest-only edits still work.",
+  ),
+  packagesNeedsInstall: route(
+    "GET",
+    "/__studio/packages/needs-install",
+    "Whether node_modules is stale",
+    "The install-on-open prompt never shows.",
+  ),
+  packagesOutdated: route(
+    "GET",
+    "/__studio/packages/outdated",
+    "Dependencies with newer versions (OutdatedInfo[])",
+    "The update affordances are hidden.",
+  ),
+  packagesSetVersions: route(
+    "POST",
+    "/__studio/packages/set-versions",
+    "Rewrite dependency ranges and install",
+    "Bulk version updates are hidden.",
+  ),
+
+  // ─── Git ──────────────────────────────────────────────────────────────────
+  gitStatus: route("GET", "/__studio/git/status", "Working-tree status (GitStatusResult)"),
+  gitBranches: route("GET", "/__studio/git/branches", "Branch list (GitBranchesResult)"),
+  gitLog: route("GET", "/__studio/git/log", "Recent commits (GitLogEntry[])"),
+  gitStage: route("POST", "/__studio/git/stage", "Stage files"),
+  gitUnstage: route("POST", "/__studio/git/unstage", "Unstage files"),
+  gitCommit: route("POST", "/__studio/git/commit", "Commit staged (else all dirty) files"),
+  gitPush: route("POST", "/__studio/git/push", "Push (cloud: sync check — commits land on push)"),
+  gitPull: route("POST", "/__studio/git/pull", "Pull/fast-forward; 409 {conflicts} on overlap"),
+  gitFetch: route("POST", "/__studio/git/fetch", "Refresh remote tracking state"),
+  gitCheckout: route("POST", "/__studio/git/checkout", "Switch branches"),
+  gitCreateBranch: route("POST", "/__studio/git/create-branch", "Create a branch"),
+  gitDiff: route("GET", "/__studio/git/diff", "Unified diff of dirty files (or one path)"),
+  gitShow: route("GET", "/__studio/git/show", "File content at a ref"),
+  gitDiscard: route("POST", "/__studio/git/discard", "Discard working changes"),
+  gitInit: route("POST", "/__studio/git/init", "Initialize a repository"),
+  gitAddRemote: route("POST", "/__studio/git/add-remote", "Add a remote"),
+  gitClone: route(
+    "POST",
+    "/__studio/git/clone",
+    "Clone a repository",
+    "The welcome screen hides Clone Git Repository.",
+  ),
+  gitPr: route(
+    "POST",
+    "/__studio/git/pr",
+    "Open a pull request → PullRequestInfo",
+    "Studio falls back to a direct GitHub API call with the user's token.",
+  ),
+
+  // ─── AI proxy ─────────────────────────────────────────────────────────────
+  aiChat: route(
+    "POST",
+    "/__studio/ai/chat",
+    "StreamEvent SSE chat proxy {messages, tools, systemPrompt, model}",
+  ),
+  aiModels: route("GET", "/__studio/ai/models", "Model catalogue (AiModelsResponse)"),
+
+  // ─── Cloudflare publish surface ───────────────────────────────────────────
+  cfProxy: route(
+    "POST",
+    "/__studio/cf/proxy",
+    "Allowlisted Cloudflare API passthrough {path, method?, body?} (backs cfApi)",
+    "The Publish panel explains the git-push publishing path instead.",
+  ),
+} as const satisfies Record<string, StudioRoute>;
+
+/** A stable route name in {@link STUDIO_ROUTES}. */
+export type StudioRouteName = keyof typeof STUDIO_ROUTES;
+
+/** 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,
+  );
+}
+
+/** Names of the optional routes (each backs an optional StudioPlatform member). */
+export function optionalRouteNames(): StudioRouteName[] {
+  return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
+    (name) => STUDIO_ROUTES[name].optional,
+  );
+}

package/src/types.ts

@@ -0,0 +1,253 @@
+/**
+ * Studio Backend Protocol — wire types. Every shape a Studio backend serves
+ * (or a `StudioPlatform` adapter consumes) lives here so client adapters and
+ * server implementations (the dev server, the desktop RPC bridge, cloud
+ * platforms) share one contract. Environment-agnostic: no DOM, no node —
+ * importable in browsers, Bun, and Cloudflare Workers alike.
+ *
+ * @license MIT
+ */
+
+import type { JsonValue as SchemaJsonValue, JxMutableNode } from "@jxsuite/schema/types";
+
+/**
+ * A JSON document value, or `undefined` to signal property removal in the mutators. Re-uses the
+ * schema's precise recursive JSON model.
+ */
+export type JsonValue = SchemaJsonValue | undefined;
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+/** Message-level failure body every protocol route may return. */
+export interface ErrorBody {
+  error: string;
+  /** Machine-readable discriminator (e.g. "remote_moved", "cf_not_connected"). */
+  code?: string;
+  detail?: unknown;
+}
+
+// ─── Filesystem ──────────────────────────────────────────────────────────────
+
+export interface DirEntry {
+  name: string;
+  path: string;
+  type: "file" | "directory";
+  size?: number;
+  modified?: string;
+}
+
+/** A filesystem change pushed from the backend (project-relative, forward-slashed path). */
+export interface FsEvent {
+  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
+  path: string;
+  isDir: boolean;
+}
+
+/** Result of a rename, including the references rewritten across the project (refactor report). */
+export interface RenameResult {
+  ok: boolean;
+  from: string;
+  to: string;
+  isDir?: boolean;
+  references?: {
+    filesChanged: number;
+    refsUpdated: number;
+    files: { path: string; count: number }[];
+  };
+  errors?: { path: string; error: string }[];
+  tag?: { from: string; to: string; filesChanged: number; refsUpdated: number };
+  tagSkipped?: string;
+  error?: string;
+}
+
+// ─── Git ─────────────────────────────────────────────────────────────────────
+
+export interface GitFileStatus {
+  status: string;
+  path: string;
+  staged?: boolean;
+}
+
+export interface GitStatusResult {
+  branch: string;
+  files: GitFileStatus[];
+  ahead: number;
+  behind: number;
+  isRepo: boolean;
+  remotes: string[];
+}
+
+export interface GitBranchesResult {
+  current: string;
+  branches: string[];
+}
+
+export interface GitLogEntry {
+  hash: string;
+  message: string;
+  author: string;
+  date: string;
+}
+
+/** Response of the pull-request route (see StudioPlatform.createPullRequest). */
+export interface PullRequestInfo {
+  url: string;
+  number: number;
+}
+
+// ─── Components ──────────────────────────────────────────────────────────────
+
+export interface ComponentSlotMeta {
+  name: string;
+  description?: string;
+  fallback?: (JxMutableNode | string)[];
+}
+
+export interface ComponentMeta {
+  tagName: string;
+  $id?: string | null;
+  path: string;
+  props?: { name: string; type?: string; default?: JsonValue; [k: string]: unknown }[];
+  slots?: ComponentSlotMeta[];
+  hasElements?: boolean;
+}
+
+// ─── Packages ────────────────────────────────────────────────────────────────
+
+export interface PackageInfo {
+  name: string;
+  version: string;
+  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
+  dev?: boolean;
+}
+
+/** A dependency with a newer version available, as reported by `bun outdated` / the npm registry. */
+export interface OutdatedInfo {
+  name: string;
+  /** The version range pinned in package.json (e.g. "^0.19.0"). */
+  current: string;
+  /** The newest published version. */
+  latest: string;
+  /** The newest version satisfying the current range, if known. */
+  wanted?: 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;
+}
+
+// ─── App / code services ─────────────────────────────────────────────────────
+
+/** Desktop app/build info surfaced in the About screen. */
+export interface AppInfo {
+  version: string;
+  channel: string;
+  hash: string;
+  /** Human-readable update status (e.g. "Up to date", "Update available"), if known. */
+  updateStatus?: string;
+}
+
+export interface CodeServiceResult {
+  code?: string;
+  diagnostics?: unknown[];
+  [key: string]: unknown;
+}
+
+// ─── Projects & starters ─────────────────────────────────────────────────────
+
+/** A starter template surfaced in the New Project picker (mirrors @jxsuite/starters StarterMeta). */
+export interface StarterInfo {
+  id: string;
+  name: string;
+  industry: string;
+  tagline: string;
+  description: string;
+  features: string[];
+  accent: string;
+  /** Preview image as a self-contained `data:` URI. */
+  thumbnail: string;
+}
+
+/** A recently-opened project, keyed by its re-openable `root` (platform-specific). */
+export interface RecentProjectEntry {
+  name: string;
+  root: string;
+  timestamp: number;
+}
+
+/** One entry in the platform's project catalogue (see StudioPlatform.listProjects). */
+export interface ProjectListEntry {
+  /** Display name (project.json name, repository name, ...). */
+  name: string;
+  /** Re-openable root key (server-relative path, owner/repo, absolute path). */
+  root: string;
+  /** Optional one-line descriptor shown under the name (path, permission, ...). */
+  description?: string | undefined;
+}
+
+// ─── Site import ─────────────────────────────────────────────────────────────
+
+/** A progress line from the AI-guided site import (mirrors @jxsuite/import ImportProgressEvent). */
+export interface ImportProgressEvent {
+  phase: string;
+  message: string;
+  current?: number;
+  total?: number;
+}
+
+/** Options for the import-site pipeline (StudioPlatform.importSite). */
+export interface ImportSiteOptions {
+  /** The live site to clone; must be http(s). */
+  url: string;
+  /** Display name for the new project. */
+  name: string;
+  /** Destination directory (platform-interpreted: project-relative on the dev server). */
+  directory: string;
+  /** Max crawl depth; 0 = single page. */
+  depth: number;
+  /** Max pages to capture. */
+  maxPages: number;
+  /** Refine component/prop names with the LLM (requires a key). */
+  aiComponents: boolean;
+  /** OpenAI-compatible credentials, from the user's AI settings. */
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+// ─── AI proxy ────────────────────────────────────────────────────────────────
+
+/** One entry of the AI proxy's model catalogue. */
+export interface AiModelInfo {
+  id: string;
+  name?: string;
+  contextWindow?: number;
+  /** Whether the model supports tool/function calling (agentic editing). */
+  toolSupport?: boolean;
+}
+
+/** Response of the AI proxy's models route (the chat route's sibling). */
+export interface AiModelsResponse {
+  models: AiModelInfo[];
+  /** True when the backend holds working credentials (env key, managed platform). */
+  configured: boolean;
+  /** True when the platform manages AI credentials itself (e.g. cloud Workers AI). */
+  managed?: boolean;
+  /** The backend's preferred model id, when it declares one. */
+  defaultModel?: string;
+  /** Set when the upstream provider was unreachable and defaults were returned. */
+  upstreamError?: number | string;
+}
+
+// ─── Cloudflare publish surface ──────────────────────────────────────────────
+
+/** Cloudflare connection state (see StudioPlatform.cfConnection). */
+export interface CfConnection {
+  connected: boolean;
+  accountId?: string | undefined;
+  accountName?: string | undefined;
+}