@jxsuite/protocol 0.1.0 → 0.4.0

package/README.md

@@ -62,4 +62,6 @@ doc?, options? }` through the project's format registry; without it only
 
 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:^`.
+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": "0.1.0",
+  "version": "0.4.0",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -18,13 +18,13 @@
     "./routes": "./src/routes.ts"
   },
   "publishConfig": {
-    "provenance": false
+    "provenance": true
   },
   "scripts": {
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "workspace:^"
+    "@jxsuite/schema": "^1.0.0"
   }
 }

package/src/routes.ts

@@ -84,6 +84,16 @@ export const STUDIO_ROUTES = {
   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}"),
+  collab: route(
+    "GET",
+    "/__studio/collab",
+    "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.",
+    "Realtime co-editing is unavailable; Studio edits solo with file-level saves",
+  ),
 
   // ─── Documents / components / formats ─────────────────────────────────────
   components: route("GET", "/__studio/components", "Discover components (ComponentMeta[])"),
@@ -96,8 +106,20 @@ export const STUDIO_ROUTES = {
   formats: route(
     "GET",
     "/__studio/formats",
-    "The project's format registry entries",
-    "Only .json documents open (backs listFormats).",
+    "The project's format registry entries plus a sibling `extensions` array — per enabled " +
+      "extension its manifest identity and project-section contributions (ExtensionsInfo[]; " +
+      "backs listFormats and listExtensions).",
+    "Only .json documents open (backs listFormats); descriptor-contributed settings sections " +
+      "do not appear.",
+  ),
+  projectSchemas: route(
+    "GET",
+    "/__studio/project-schemas",
+    "The project's generated entry documents (project.schema.json / document.schema.json), " +
+      "PRE-BUNDLED into self-contained schemas — {project, document} (backs fetchProjectSchemas). " +
+      "Regenerated on demand when missing or older than project.json.",
+    "The JSON editor falls back to the bundled core schemas (extension sections get no " +
+      "editor validation/completion).",
   ),
   format: route(
     "POST",
@@ -171,6 +193,72 @@ export const STUDIO_ROUTES = {
     "Studio falls back to a direct GitHub API call with the user's token.",
   ),
 
+  // ─── Data surface (connector domain owner console) ───────────────────────
+  // These routes intentionally bypass table permission rules — the backend boundary
+  // (dev-server loopback/token, cloud collaboration permission) is the gate
+  // (specs/extensions.md §13). Secret VALUES never ride them; env-var NAMES only.
+  dataConnections: route(
+    "GET",
+    "/__studio/data/connections",
+    "Connector connections with configured/missingSecrets/isDefault state, reachable table " +
+      "names, and registry-descriptor provider metadata (DataConnectionsResponse; backs " +
+      "dataConnections)",
+    "The connections settings section shows no status, and data-domain actions stay hidden.",
+  ),
+  dataConnectionTest: route(
+    "POST",
+    "/__studio/data/connections/test",
+    "Probe a connection {connection} → DataConnectionTestResult (backs dataConnectionTest)",
+    "The Test Connection action is hidden.",
+  ),
+  dataPush: route(
+    "POST",
+    "/__studio/data/push",
+    "Additive schema push {connection?, dryRun?} → DataPushResult (plan of DataPushStep[], " +
+      "applied, warnings/errors; backs dataPush)",
+    "The Push Schema action is hidden; schemas deploy via `jx db push` instead.",
+  ),
+  dataRows: route(
+    "GET",
+    "/__studio/data/rows",
+    "Page a table (DataRowsQuery params) → DataRowsResult {rows, total, columns} (backs dataRows)",
+    "The data grid is unavailable.",
+  ),
+  dataInsertRow: route(
+    "POST",
+    "/__studio/data/rows",
+    "Insert a row {table, connection?, values} → {row} (backs dataInsertRow)",
+    "The data grid hides its add-row footer.",
+  ),
+  dataUpdateRow: route(
+    "PUT",
+    "/__studio/data/rows",
+    "Update a row keyed on its primary key {table, connection?, pk, set} → {row} (backs " +
+      "dataUpdateRow)",
+    "Data grid cells are read-only.",
+  ),
+  dataDeleteRow: route(
+    "DELETE",
+    "/__studio/data/rows",
+    "Delete a row (?table=&pk=&connection=) → {ok} (backs dataDeleteRow)",
+    "The data grid hides row deletion.",
+  ),
+
+  // ─── Secrets (names only) ─────────────────────────────────────────────────
+  secretsList: route(
+    "GET",
+    "/__studio/secrets",
+    "Configured secret env-var NAMES, never values (SecretsListResponse; backs listSecrets)",
+    "Secret fields cannot show set/unset state.",
+  ),
+  secretsSet: route(
+    "PUT",
+    "/__studio/secrets",
+    "Write/remove secrets in the backend store (.dev.vars locally) {set?, remove?} → names " +
+      "(backs setSecrets)",
+    "The secret form control renders disabled; secrets are edited in .dev.vars by hand.",
+  ),
+
   // ─── AI proxy ─────────────────────────────────────────────────────────────
   aiChat: route(
     "POST",

package/src/types.ts

@@ -112,6 +112,233 @@ export interface ComponentMeta {
   hasElements?: boolean;
 }
 
+// ─── 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;
+}
+
+/** 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;
+  /** The class descriptor's `$studio` block (settings-section vocabulary), when declared. */
+  studio?: Record<string, unknown> | 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).
+   */
+  entrySchema?: Record<string, unknown> | null;
+}
+
+/**
+ * One enabled extension package on the wire — the `extensions` sibling of the formats route's
+ * `formats` array (additive; the `formats` shape is unchanged).
+ */
+export interface ExtensionsInfo {
+  /** The project.json `extensions` entry that produced this extension. */
+  specifier: string;
+  /** The manifest's package name. */
+  name: string;
+  title?: string;
+  description?: string;
+  /** Project-section contributions, in class declaration order. */
+  contributions: ExtensionContributionInfo[];
+  /**
+   * Every manifest class of the extension with its backend-resolved descriptor path, in declaration
+   * order. Optional (additive): older backends omit it, and consumers needing a class `$src` fall
+   * back to their historical literals. Plain state classes (no admission blocks) carry `state:
+   * true` plus their `$studio.stateDefaults` hint, seeding studio-created defs.
+   */
+  classes?: {
+    name: string;
+    path: string;
+    state?: boolean;
+    stateDefaults?: Record<string, unknown>;
+  }[];
+}
+
+/**
+ * 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
+ * editors can register them without resolving relative `$ref`s.
+ */
+export interface ProjectSchemasResponse {
+  project?: Record<string, unknown> | null;
+  document?: Record<string, unknown> | null;
+}
+
+// ─── Data surface (connector domain; specs/extensions.md §13) ───────────────
+/* The /__studio/data/* routes are the project owner's admin console over the connector
+   extension's connections and tables. They intentionally bypass table permission rules —
+   the backend's own boundary (dev-server loopback/token, cloud collaboration permission)
+   is the gate. Secret VALUES never ride these shapes; env-var NAMES only. */
+
+/** Connector-provider metadata resolved from the extension registry's class descriptors. */
+export interface DataConnectorInfo {
+  /** Backing-service identifier (`d1`, `supabase`, `sqlite`, ...). */
+  provider: string;
+  /** SQL dialect family (`"sqlite"` | `"postgres"`). */
+  kind?: string;
+  /** Dev-server stand-in provider (specs/extensions.md §12), when the class declares one. */
+  local?: string;
+  /** The descriptor's human description, when present. */
+  description?: string;
+}
+
+/** One project connection with its configuration state (identifiers and env NAMES only). */
+export interface DataConnectionInfo {
+  /** The `connections` section key. */
+  name: string;
+  provider: string;
+  /** The connection's project.json value — identifiers and env-var names, never secrets. */
+  settings: Record<string, unknown>;
+  /** 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. */
+  missingSecrets: string[];
+  /** True for the first-declared connection (the console's default pick). */
+  isDefault: boolean;
+  /**
+   * Table names reachable on this connection: tables declared in project.json plus tables
+   * discovered by introspection (e.g. auth system tables). Best-effort — introspection is skipped
+   * when the connection is missing secrets or unreachable.
+   */
+  tables: string[];
+  /** Provider metadata from the registry descriptor, when the provider class is resolvable. */
+  connector?: DataConnectorInfo | null;
+}
+
+/** Response of the data-connections route. */
+export interface DataConnectionsResponse {
+  connections: DataConnectionInfo[];
+}
+
+/** Result of the connection-test route (mirrors the connector's testConnection capability). */
+export interface DataConnectionTestResult {
+  ok: boolean;
+  error?: string;
+}
+
+/**
+ * A push-plan step kind. Open string union: connector DDL kinds today, and future push-step
+ * contributors (e.g. `"auth"` migration steps) extend it without a protocol bump.
+ */
+export type DataPushStepKind =
+  | "createTable"
+  | "addColumn"
+  | "index"
+  | "junction"
+  | "auth"
+  | (string & Record<never, never>);
+
+/** One step of a schema-push plan. */
+export interface DataPushStep {
+  kind: DataPushStepKind;
+  /** Affected table, when derivable from the statement. */
+  table?: string;
+  /** One-line human description of the step. */
+  summary: string;
+  /** The compiled SQL statement, when the step is SQL-backed. */
+  sql?: string;
+  /** The connection the step applies to. */
+  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;
+}
+
+/** Result of the data-push route. */
+export interface DataPushResult {
+  plan: DataPushStep[];
+  /** True when the plan was executed (never on dryRun or after an error). */
+  applied: boolean;
+  /** Drift/orphan warnings from the additive-only sync. */
+  warnings?: string[];
+  errors?: string[];
+}
+
+/** Query of the data-rows route (wire form: query params). */
+export interface DataRowsQuery {
+  table: string;
+  /** Connection to resolve undeclared (system) tables against; default = first declared. */
+  connection?: string;
+  /** Page size; default 50. */
+  limit?: number;
+  offset?: number;
+  /** Column to order by (must exist on the table). */
+  orderBy?: string;
+  dir?: "asc" | "desc";
+}
+
+/** Column metadata from backend introspection. */
+export interface DataColumnMeta {
+  name: string;
+  type: string;
+  pk?: boolean;
+  nullable?: boolean;
+}
+
+/** Result of the data-rows route. */
+export interface DataRowsResult {
+  rows: Record<string, unknown>[];
+  /** Total row count of the table (for pagination). */
+  total: number;
+  columns: DataColumnMeta[];
+}
+
+/** Body of the row-insert route. */
+export interface DataRowInsert {
+  table: string;
+  connection?: string;
+  values: Record<string, unknown>;
+}
+
+/** Body of the row-update route (keyed on the introspected primary key). */
+export interface DataRowUpdate {
+  table: string;
+  connection?: string;
+  pk: string | number;
+  set: Record<string, unknown>;
+}
+
+/** Parameters of the row-delete route. */
+export interface DataRowDelete {
+  table: string;
+  connection?: string;
+  pk: string | number;
+}
+
+// ─── Secrets (names only; specs/extensions.md §13) ──────────────────────────
+
+/** Response of the secrets-list route — env-var NAMES only, never values. */
+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[];
+}
+
 // ─── Packages ────────────────────────────────────────────────────────────────
 
 export interface PackageInfo {