@jxsuite/studio 0.37.0 → 1.0.0

package/src/panels/welcome-screen.ts

@@ -5,6 +5,8 @@
  */
 
 import { html, render as litRender, nothing } from "lit-html";
+import { getAccountStatus, needsAppInstall } from "../account-status";
+import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
 import { getProjectList } from "../project-list";
 import { clearRecentProjects, getRecentProjects, removeRecentProject } from "../recent-projects";
 import { renderOnly } from "../store";
@@ -15,6 +17,7 @@ interface WelcomeCtx {
   openRecentProject: (root: string) => void;
   openNewProject: () => void;
   cloneRepository: () => void;
+  addExistingRepo: () => void;
 }
 
 let _ctx: WelcomeCtx | null = null;
@@ -31,6 +34,7 @@ export function renderWelcome(host: HTMLElement) {
   // Catalogue entries already in Recent stay in that section only.
   const catalogue = getProjectList().filter((p) => !recent.some((r) => r.root === p.root));
   const showClone = platformSupportsClone();
+  const showAddRepo = platformSupportsAddRepo();
 
   litRender(
     html`
@@ -85,8 +89,54 @@ export function renderWelcome(host: HTMLElement) {
                   Clone Git Repository...
                 </button>`
               : nothing}
+            ${showAddRepo
+              ? html`<button class="welcome-action" @click=${() => ctx.addExistingRepo()}>
+                  <svg
+                    class="welcome-action-icon"
+                    width="16"
+                    height="16"
+                    viewBox="0 0 16 16"
+                    fill="currentColor"
+                  >
+                    <path
+                      d="M2 2.5A2.5 2.5 0 0 1 4.5 0h8.75a.75.75 0 0 1 .75.75v12.5a.75.75 0 0 1-.75.75h-2.5a.75.75 0 0 1 0-1.5h1.75v-2h-8a1 1 0 0 0-.714 1.7.75.75 0 1 1-1.072 1.05A2.495 2.495 0 0 1 2 11.5Zm10.5-1h-8a1 1 0 0 0-1 1v6.708A2.5 2.5 0 0 1 4.5 9h8ZM5 12.25a.25.25 0 0 1 .25-.25h3.5a.25.25 0 0 1 .25.25v3.25a.25.25 0 0 1-.4.2l-1.45-1.087a.25.25 0 0 0-.3 0L5.4 15.7a.25.25 0 0 1-.4-.2Z"
+                    />
+                  </svg>
+                  Add Existing Repository...
+                </button>`
+              : nothing}
           </div>
 
+          ${needsAppInstall()
+            ? html`
+                <div class="welcome-section">
+                  <h2 class="welcome-section-title">Repository access</h2>
+                  <a
+                    class="welcome-action"
+                    href=${getAccountStatus()?.appInstallUrl ?? "#"}
+                    target="_blank"
+                    rel="noreferrer"
+                  >
+                    <svg
+                      class="welcome-action-icon"
+                      width="16"
+                      height="16"
+                      viewBox="0 0 16 16"
+                      fill="currentColor"
+                    >
+                      <path
+                        d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"
+                      />
+                    </svg>
+                    Install the Jx Suite GitHub App
+                  </a>
+                  <p class="welcome-install-note">
+                    Grants repository access so you can create and open projects — choose “All
+                    repositories”.
+                  </p>
+                </div>
+              `
+            : nothing}
           ${catalogue.length > 0
             ? html`
                 <div class="welcome-section">

package/src/platform-errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Structured platform errors. Backend routes attach machine-readable fields to failures (e.g.
+ * project creation blocked by missing GitHub App installation access → `code:
+ * "needs_installation_access"` + `installUrl`); adapters preserve them on the thrown Error via
+ * `Object.assign`, and UI surfaces recover them here to render actions (an install link) instead of
+ * plain text.
+ */
+
+export interface PlatformErrorInfo {
+  code?: string;
+  installUrl?: string;
+}
+
+/** Machine-readable fields carried by a thrown platform error (empty object when none). */
+export function platformErrorInfo(error: unknown): PlatformErrorInfo {
+  if (!error || typeof error !== "object") {
+    return {};
+  }
+  const { code, installUrl } = error as { code?: unknown; installUrl?: unknown };
+  return {
+    ...(typeof code === "string" ? { code } : {}),
+    ...(typeof installUrl === "string" ? { installUrl } : {}),
+  };
+}
+
+/** The GitHub-App install link when the error is the structured needs-installation 403. */
+export function installUrlOf(error: unknown): string | null {
+  const info = platformErrorInfo(error);
+  return info.code === "needs_installation_access" && info.installUrl ? info.installUrl : null;
+}

package/src/platforms/cloud.ts

@@ -11,15 +11,11 @@
  * gitClone, resolveClass, component discovery, code services.
  */
 
-/* Import the browser-safe primitives directly (NOT the Markdown class —
-   its node-only discover/load chain drags glob/node:fs into the bundle). */
-import { transpileJxMarkdown } from "@jxsuite/parser/transpile";
-import { serializeJxMarkdown } from "@jxsuite/parser/serialize";
-import markdownClassDef from "@jxsuite/parser/Markdown.class.json";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
-import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
+import type { ProjectConfig } from "@jxsuite/schema/types";
 import type {
   DirEntry,
+  ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
   GitLogEntry,
@@ -27,6 +23,7 @@ import type {
   PackageInfo,
   ProjectListEntry,
   RenameResult,
+  RepoInfo,
   StarterInfo,
   StudioPlatform,
 } from "../types";
@@ -74,47 +71,6 @@ async function okJson<T>(res: Response, fallback: string): Promise<T> {
   return (await res.json()) as T;
 }
 
-/**
- * Formats the cloud can execute: browser-safe built-ins only (parse/serialize run IN the editor
- * page via @jxsuite/parser — the platform never executes project JS). The registry entry mirrors
- * the devserver's `GET /__studio/formats` shape, sourced from the canonical class descriptor.
- * Unlike the devserver we register Markdown regardless of project.json imports — the compiler still
- * requires the import for `jx build`, but the editor should never strand a .md file unopenable.
- */
-interface MarkdownClassDef {
-  format: {
-    extensions: string[];
-    mediaType: string;
-    documentKinds: string[];
-    exportTarget: boolean;
-    remote: boolean;
-  };
-  $studio: Record<string, unknown>;
-}
-
-function builtinFormats(config: ProjectConfig | null): Record<string, unknown>[] {
-  const def = markdownClassDef as unknown as MarkdownClassDef;
-  const imports = (config?.imports ?? {}) as Record<string, string>;
-  const importedName = Object.keys(imports).find((name) =>
-    imports[name]?.includes("Markdown.class.json"),
-  );
-  return [
-    {
-      name: importedName ?? "Markdown",
-      extensions: def.format.extensions,
-      mediaType: def.format.mediaType,
-      documentKinds: def.format.documentKinds,
-      exportTarget: def.format.exportTarget,
-      remote: def.format.remote,
-      studio: def.$studio,
-      capabilities: {
-        parse: { identifier: "parse", timing: ["compiler", "server", "client"] },
-        serialize: { identifier: "serialize", timing: ["compiler", "server", "client"] },
-      },
-    },
-  ];
-}
-
 /** Editor URL for a project session (mirrors the shell's route). */
 export function editUrl(project: CloudProject): string {
   return `/edit/${project.owner}/${project.repo}@${encodeURIComponent(project.branch)}`;
@@ -177,6 +133,8 @@ async function fetchCfConnection(): Promise<{
   };
 }
 
+type CfConnectionInfo = Awaited<ReturnType<typeof fetchCfConnection>>;
+
 /** Parse an "owner/repo@branch" root key; null when malformed. */
 export function parseRootKey(root: string): CloudProject | null {
   const match = /^([^/@]+)\/([^/@]+)@(.+)$/.exec(root);
@@ -247,8 +205,6 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     }
   }
 
-  let cachedConfig: ProjectConfig | null = null;
-
   const platform: StudioPlatform = {
     id: "cloud",
     projectRoot: root,
@@ -415,34 +371,59 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       };
     },
 
-    // ─── Formats (browser-safe built-ins, executed in-page) ───────────────
+    // ─── Formats (session backend registry, mirroring the dev-server seam) ─
 
+    /**
+     * The project's format registry, served by the session gateway (the dev server's `GET
+     * /__studio/formats` under this session's base path). Part-4 cleanup: the cloud ProjectSession
+     * does not serve the route yet, so this degrades to an empty registry (only .json documents
+     * open) until the backend lands it.
+     */
     async listFormats() {
-      if (cachedConfig === null) {
-        try {
-          const info = await projectInfo();
-          cachedConfig = (info.projectConfig as ProjectConfig | null) ?? null;
-        } catch {
-          cachedConfig = null;
+      try {
+        const res = await api("/formats");
+        if (!res.ok) {
+          return [];
         }
+        const body = (await res.json()) as { formats?: Record<string, unknown>[] };
+        return body.formats ?? [];
+      } catch {
+        return [];
       }
-      return builtinFormats(cachedConfig);
     },
 
-    async formatAction(payload: Record<string, unknown>) {
-      const { action, source, doc, options } = payload as {
-        action: string;
-        source?: string;
-        doc?: Record<string, unknown>;
-        options?: Record<string, unknown>;
-      };
-      if (action === "parse") {
-        return transpileJxMarkdown(source ?? "");
+    /** The extensions payload riding beside `formats` on the same route. */
+    async listExtensions(): Promise<ExtensionsInfo[]> {
+      try {
+        const res = await api("/formats");
+        if (!res.ok) {
+          return [];
+        }
+        const body = (await res.json()) as { extensions?: ExtensionsInfo[] };
+        return body.extensions ?? [];
+      } catch {
+        return [];
       }
-      if (action === "serialize") {
-        return serializeJxMarkdown((doc ?? {}) as JxDocument, options);
+    },
+
+    /**
+     * Invoke a format capability (parse/serialize) on the session backend — the dev server's `POST
+     * /__studio/format` seam. In-page execution left with the core → @jxsuite/parser dependency, so
+     * backends without the route surface the error below instead of silently mangling format
+     * documents.
+     */
+    async formatAction(payload: Record<string, unknown>) {
+      const res = await postJson("/format", payload);
+      if (!res.ok) {
+        throw new Error(
+          await errorMessage(
+            res,
+            "This cloud session cannot run format actions yet (the backend serves no format route)",
+          ),
+        );
       }
-      throw new Error(`Unsupported format action: ${action}`);
+      const data = (await res.json()) as { result?: unknown };
+      return data.result;
     },
 
     // ─── Components / code services (cloud: static-only posture) ──────────
@@ -692,10 +673,18 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
           starter: opts.starter,
         }),
       });
-      const created = await okJson<{ owner: string; name: string; defaultBranch: string }>(
-        res,
-        "Failed to create project",
-      );
+      if (!res.ok) {
+        // Preserve the structured 403 (needs_installation_access + installUrl) so the New
+        // Project modal can render an install link instead of flattened text.
+        const body = (await res.json().catch(() => null)) as
+          | (ErrorBody & { installUrl?: string })
+          | null;
+        throw Object.assign(new Error(body?.error ?? "Failed to create project"), {
+          ...(body?.code ? { code: body.code } : {}),
+          ...(body?.installUrl ? { installUrl: body.installUrl } : {}),
+        });
+      }
+      const created = (await res.json()) as { owner: string; name: string; defaultBranch: string };
       return {
         root: projectRootKey({
           owner: created.owner,
@@ -726,6 +715,61 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       };
     },
 
+    /** Repositories reachable through the user's Jx Suite App installations (user + org). */
+    async listRepos(): Promise<RepoInfo[]> {
+      const res = await fetch("/api/v1/repos", { credentials: "include" });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, "Failed to list repositories"));
+      }
+      const entries = (await res.json()) as (RepoInfo & { repoId: number })[];
+      return entries.map((r) => ({
+        owner: r.owner,
+        name: r.name,
+        fullName: r.fullName,
+        private: r.private,
+        defaultBranch: r.defaultBranch,
+        permission: r.permission,
+        isJxProject: r.isJxProject,
+      }));
+    },
+
+    /** Adopt an existing repo as a Jx project; resolves to its catalogue root key. */
+    async importProject(opts: { owner: string; name: string }) {
+      const res = await fetch("/api/v1/projects/import", {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(opts),
+      });
+      const imported = await okJson<{ owner: string; name: string; defaultBranch: string }>(
+        res,
+        "Failed to import repository",
+      );
+      return {
+        root: projectRootKey({
+          owner: imported.owner,
+          repo: imported.name,
+          branch: imported.defaultBranch,
+        }),
+      };
+    },
+
+    /** GitHub-App installation coverage from /me — powers the welcome install prompt. */
+    async getAccountStatus() {
+      const res = await fetch("/api/v1/me", { credentials: "include" });
+      if (!res.ok) {
+        return null;
+      }
+      const me = (await res.json()) as {
+        installations?: { id: number; account: string | null }[];
+        appInstallUrl?: string;
+      };
+      return {
+        installations: me.installations ?? [],
+        ...(me.appInstallUrl ? { appInstallUrl: me.appInstallUrl } : {}),
+      };
+    },
+
     /** Open a PR from this session's branch (ProjectSession /git/pr). */
     async createPullRequest(opts: { title: string; body?: string; head?: string; base?: string }) {
       return okJson<{ url: string; number: number }>(
@@ -739,8 +783,11 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     },
 
     /**
-     * Hosted OAuth connect: open the broker flow in a popup and poll until the connection lands (or
-     * the popup closes / times out). Popup-blocked browsers fall back to a full-page redirect.
+     * Hosted OAuth connect: open the broker flow in a popup. The home shell relays the callback's
+     * result back via postMessage {source: "jx-cf"} and closes the popup, so success resolves and
+     * OAuth errors (denial, invalid_scope misregistration) REJECT with the real reason instead of
+     * timing out. A 1.5s poll remains as fallback for older shells / blocked message delivery, and
+     * popup-blocked browsers fall back to a full-page redirect.
      */
     async cfConnect() {
       if (typeof window === "undefined" || typeof location === "undefined") {
@@ -752,20 +799,56 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
         return null;
       }
       const deadline = Date.now() + 180_000;
-      while (Date.now() < deadline) {
-        await new Promise((resolve) => {
-          setTimeout(resolve, 1500);
-        });
-        const connection = await fetchCfConnection();
-        if (connection) {
-          popup.close();
-          return connection;
-        }
-        if (popup.closed) {
-          return fetchCfConnection();
-        }
-      }
-      return null;
+      return new Promise<CfConnectionInfo>((resolve, reject) => {
+        let timer = 0;
+        const cleanup = () => {
+          window.removeEventListener("message", onMessage);
+          window.clearTimeout(timer);
+          if (!popup.closed) {
+            popup.close();
+          }
+        };
+        const settle = (connection: CfConnectionInfo) => {
+          cleanup();
+          resolve(connection);
+        };
+        const fail = (reason: string) => {
+          cleanup();
+          reject(new Error(reason));
+        };
+        const onMessage = (event: MessageEvent) => {
+          if (event.origin !== location.origin) {
+            return;
+          }
+          const data = event.data as { source?: string; status?: string; reason?: string | null };
+          if (!data || data.source !== "jx-cf") {
+            return;
+          }
+          if (data.status === "error") {
+            fail(data.reason ?? "Cloudflare authorization failed");
+            return;
+          }
+          void fetchCfConnection().then(settle);
+        };
+        window.addEventListener("message", onMessage);
+        const poll = async () => {
+          if (Date.now() > deadline) {
+            settle(null);
+            return;
+          }
+          const connection = await fetchCfConnection();
+          if (connection) {
+            settle(connection);
+            return;
+          }
+          if (popup.closed) {
+            settle(await fetchCfConnection());
+            return;
+          }
+          timer = window.setTimeout(() => void poll(), 1500);
+        };
+        timer = window.setTimeout(() => void poll(), 1500);
+      });
     },
 
     /** Allowlisted Cloudflare API passthrough (platform injects the OAuth token). */

package/src/platforms/devserver.ts

@@ -12,11 +12,23 @@ import { streamImport } from "../services/import-client";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import type {
+  DataConnectionsResponse,
+  DataConnectionTestResult,
+  DataPushResult,
+  DataRowDelete,
+  DataRowInsert,
+  DataRowsQuery,
+  DataRowsResult,
+  DataRowUpdate,
   DirEntry,
+  ExtensionsInfo,
   FsEvent,
   ImportProgressEvent,
   ImportSiteOptions,
+  ProjectSchemasResponse,
   RenameResult,
+  SecretsSetRequest,
+  SecretsSetResponse,
   StarterInfo,
 } from "../types";
 
@@ -613,6 +625,166 @@ export function createDevServerPlatform() {
       return body.formats ?? [];
     },
 
+    /** The extensions payload riding beside `formats` on the same route. */
+    async listExtensions(): Promise<ExtensionsInfo[]> {
+      const res = await fetch(`/__studio/formats?dir=${encodeURIComponent(serverPath("."))}`);
+      if (!res.ok) {
+        return [];
+      }
+      const body = await readJson<{ extensions?: ExtensionsInfo[] }>(res);
+      return body.extensions ?? [];
+    },
+
+    /** Pre-bundled per-project entry schemas for Monaco registration (empty when unavailable). */
+    async fetchProjectSchemas(): Promise<ProjectSchemasResponse> {
+      const res = await fetch(
+        `/__studio/project-schemas?dir=${encodeURIComponent(serverPath("."))}`,
+      );
+      if (!res.ok) {
+        return {};
+      }
+      return await readJson<ProjectSchemasResponse>(res);
+    },
+
+    // ─── Data surface + secrets (owner console over /__studio/data/* + /__studio/secrets) ──
+
+    /** Connector connections with configured state, table names, and provider metadata. */
+    async dataConnections(): Promise<DataConnectionsResponse> {
+      const res = await fetch(
+        `/__studio/data/connections?dir=${encodeURIComponent(serverPath("."))}`,
+      );
+      if (!res.ok) {
+        const data = await readJson<ErrorBody>(res);
+        throw new Error(data.error || "Failed to list connections");
+      }
+      return await readJson<DataConnectionsResponse>(res);
+    },
+
+    /** Probe one connection through the backend's connector registry. */
+    async dataConnectionTest(connection: string): Promise<DataConnectionTestResult> {
+      const res = await fetch(
+        `/__studio/data/connections/test?dir=${encodeURIComponent(serverPath("."))}`,
+        {
+          body: JSON.stringify({ connection }),
+          headers: { "Content-Type": "application/json" },
+          method: "POST",
+        },
+      );
+      const data = await readJson<DataConnectionTestResult & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Connection test failed");
+      }
+      return data;
+    },
+
+    /** Additive schema push; `dryRun` compiles the plan without applying it. */
+    async dataPush(opts?: { connection?: string; dryRun?: boolean }): Promise<DataPushResult> {
+      const res = await fetch(`/__studio/data/push?dir=${encodeURIComponent(serverPath("."))}`, {
+        body: JSON.stringify(opts ?? {}),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      const data = await readJson<DataPushResult & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Schema push failed");
+      }
+      return data;
+    },
+
+    /** Page a table's rows with introspected column metadata. */
+    async dataRows(query: DataRowsQuery): Promise<DataRowsResult> {
+      const params = new URLSearchParams({ dir: serverPath("."), table: query.table });
+      if (query.connection) {
+        params.set("connection", query.connection);
+      }
+      if (query.limit !== undefined) {
+        params.set("limit", String(query.limit));
+      }
+      if (query.offset !== undefined) {
+        params.set("offset", String(query.offset));
+      }
+      if (query.orderBy !== undefined) {
+        params.set("orderBy", query.orderBy);
+      }
+      if (query.dir !== undefined) {
+        params.set("dir", query.dir);
+      }
+      const res = await fetch(`/__studio/data/rows?${params}`);
+      const data = await readJson<DataRowsResult & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Failed to load rows");
+      }
+      return data;
+    },
+
+    async dataInsertRow(req: DataRowInsert): Promise<{ row: Record<string, unknown> }> {
+      const res = await fetch(`/__studio/data/rows?dir=${encodeURIComponent(serverPath("."))}`, {
+        body: JSON.stringify(req),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Insert failed");
+      }
+      return data;
+    },
+
+    async dataUpdateRow(req: DataRowUpdate): Promise<{ row: Record<string, unknown> }> {
+      const res = await fetch(`/__studio/data/rows?dir=${encodeURIComponent(serverPath("."))}`, {
+        body: JSON.stringify(req),
+        headers: { "Content-Type": "application/json" },
+        method: "PUT",
+      });
+      const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Update failed");
+      }
+      return data;
+    },
+
+    async dataDeleteRow(req: DataRowDelete): Promise<{ ok: boolean }> {
+      const params = new URLSearchParams({
+        dir: serverPath("."),
+        pk: String(req.pk),
+        table: req.table,
+      });
+      if (req.connection) {
+        params.set("connection", req.connection);
+      }
+      const res = await fetch(`/__studio/data/rows?${params}`, { method: "DELETE" });
+      const data = await readJson<{ ok: boolean } & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Delete failed");
+      }
+      return data;
+    },
+
+    /** Configured secret env-var NAMES — never values. */
+    async listSecrets(): Promise<string[]> {
+      const res = await fetch(`/__studio/secrets?dir=${encodeURIComponent(serverPath("."))}`);
+      if (!res.ok) {
+        const data = await readJson<ErrorBody>(res);
+        throw new Error(data.error || "Failed to list secrets");
+      }
+      const data = await readJson<{ names: string[] }>(res);
+      return data.names;
+    },
+
+    /** Write/remove secrets in the dev server's .dev.vars; names-only response. */
+    async setSecrets(req: SecretsSetRequest): Promise<SecretsSetResponse> {
+      const res = await fetch(`/__studio/secrets?dir=${encodeURIComponent(serverPath("."))}`, {
+        body: JSON.stringify(req),
+        headers: { "Content-Type": "application/json" },
+        method: "PUT",
+      });
+      const data = await readJson<SecretsSetResponse & ErrorBody>(res);
+      if (!res.ok) {
+        throw new Error(data.error || "Failed to write secrets");
+      }
+      return data;
+    },
+
     /**
      * Invoke a format capability (parse/serialize) server-side.
      *