@jxsuite/studio 4.0.0 → 5.0.0

package/src/platforms/cloud.ts

@@ -6,9 +6,9 @@
  * `/api/v1/ai/chat`. The session is pre-bound to one (repo, branch) — the shell picks the project
  * before Studio boots — while project-less mode (null) powers the /studio welcome screen.
  *
- * Cloud omissions (Studio degrades per @jxsuite/protocol's route table): pickDirectory/importSite,
- * package install/outdated/set-versions (package ops are manifest-only edits), multi-window,
- * gitClone, resolveClass, component discovery, code services.
+ * Cloud omissions (Studio degrades per @jxsuite/protocol's route table): pickDirectory, package
+ * install/outdated/set-versions (package ops are manifest-only edits), multi-window, gitClone,
+ * resolveClass, component discovery, code services.
  */
 
 import { negotiateCollab } from "@jxsuite/collab/negotiate";
@@ -16,16 +16,24 @@ import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
+import { streamImport } from "../services/import-client";
 import type {
   AccountStatus,
+  CfAccountSummary,
+  CfConnection,
+  CfConnectOutcome,
   ComponentMeta,
   CreateProjectDestination,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
   GitLogEntry,
   GitStatusResult,
+  ImportProgressEvent,
+  ImportReadyEvent,
+  ImportSiteOptions,
   PackageInfo,
   ProjectListEntry,
   SiteBuildResult,
@@ -53,6 +61,15 @@ interface ProjectInfoWire {
   projectConfig: Record<string, unknown> | null;
 }
 
+/** One row of the platform's project catalogue (`GET /api/v1/projects`). */
+interface ProjectListWire {
+  fullName: string;
+  owner: string;
+  name: string;
+  defaultBranch: string;
+  permission: string;
+}
+
 interface SessionEventWire {
   kind: "fs" | "git";
   events?: FsEvent[];
@@ -124,12 +141,16 @@ export function projectRootKey(project: CloudProject): string {
   return `${project.owner}/${project.repo}@${project.branch}`;
 }
 
-/** Current hosted Cloudflare connection; null when none is brokered yet. */
-async function fetchCfConnection(): Promise<{
-  connected: boolean;
-  accountId?: string | undefined;
-  accountName?: string | undefined;
-} | null> {
+/**
+ * Current hosted Cloudflare connection; null when none is brokered yet.
+ *
+ * A LAPSED row is not a healthy one. This reader used to answer `{connected: true}` for any body
+ * whose `connected` flag was set and drop `needsReconnect` on the floor, so a row whose grant had
+ * expired came back indistinguishable from one that works — which is how `cfConnect`'s poll came to
+ * close the popup the moment it opened, over a row from a previous session, while the user was
+ * still on Cloudflare's login page. Every diagnostic the broker sends now passes straight through.
+ */
+async function fetchCfConnection(): Promise<CfConnection | null> {
   const res = await fetch("/api/v1/cf/connection", { credentials: "include" });
   if (!res.ok) {
     return null;
@@ -138,7 +159,15 @@ async function fetchCfConnection(): Promise<{
     connected: boolean;
     accountId?: string | null;
     accountName?: string | null;
+    needsReconnect?: boolean;
+    needsAccount?: boolean;
+    code?: CfConnection["code"];
+    reason?: string;
+    hasRefreshToken?: boolean;
+    expiresAt?: number;
   };
+  /* Cloud never emits {connected: false} to the PAL — no brokered row at all is `null`, and a row
+     that cannot be used arrives as connected + needsReconnect. See CfConnection. */
   if (!body.connected) {
     return null;
   }
@@ -146,10 +175,131 @@ async function fetchCfConnection(): Promise<{
     connected: true,
     ...(body.accountId ? { accountId: body.accountId } : {}),
     ...(body.accountName ? { accountName: body.accountName } : {}),
+    ...(body.needsReconnect ? { needsReconnect: true } : {}),
+    ...(body.needsAccount ? { needsAccount: true } : {}),
+    ...(body.code ? { code: body.code } : {}),
+    ...(body.reason ? { reason: body.reason } : {}),
+    ...(body.hasRefreshToken === undefined ? {} : { hasRefreshToken: body.hasRefreshToken }),
+    ...(body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }),
   };
 }
 
-type CfConnectionInfo = Awaited<ReturnType<typeof fetchCfConnection>>;
+interface CfConnectFlow {
+  popup: Window | null;
+  promise: Promise<CfConnectOutcome | null>;
+}
+
+/**
+ * The connect flow currently running, or null.
+ *
+ * Module-level rather than per-platform because the popup's TARGET NAME ("cf-connect") is global to
+ * the browsing context: a second `window.open` on that name re-uses the first flow's popup, and the
+ * first flow's cleanup then closes it out from under the second — the user watches their half-typed
+ * Cloudflare login vanish. Joining the in-flight promise is the only answer that leaves both
+ * callers correct.
+ */
+let cfConnectFlow: CfConnectFlow | null = null;
+
+/**
+ * Drive one hosted OAuth connect to a {@link CfConnectOutcome}. See `cfConnect` for the semantics;
+ * this lives at module scope so the single-flight handle can too.
+ */
+async function runCfConnect(handle: CfConnectFlow): Promise<CfConnectOutcome | null> {
+  /* The baseline is read BEFORE the popup opens, and it is what keeps the poll honest: a row that
+     was already healthy proves nothing about THIS flow, so the poll must not settle on one. Reading
+     it after the popup opened would race the callback and could capture the new row as "old". */
+  const baseline = await fetchCfConnection().catch(() => null);
+  const healthyBaseline = Boolean(baseline?.connected && !baseline.needsReconnect);
+  const popup = window.open("/api/v1/cf/connect", "cf-connect", "width=980,height=780");
+  if (!popup) {
+    /* Popup blocked: the whole page is now navigating to the broker. Not a failure — the caller
+       must render nothing at all rather than an error it will never get to show. */
+    location.assign("/api/v1/cf/connect");
+    return { status: "redirect" };
+  }
+  handle.popup = popup;
+  const deadline = Date.now() + 180_000;
+  return new Promise<CfConnectOutcome>((resolve, reject) => {
+    let timer = 0;
+    const cleanup = () => {
+      window.removeEventListener("message", onMessage);
+      window.clearTimeout(timer);
+      if (!popup.closed) {
+        popup.close();
+      }
+    };
+    const settle = (outcome: CfConnectOutcome) => {
+      cleanup();
+      resolve(outcome);
+    };
+    const fail = (reason: string) => {
+      cleanup();
+      reject(new Error(reason));
+    };
+    /** A usable row: brokered, and its grant has not lapsed. */
+    const usable = (connection: CfConnection | null): connection is CfConnection =>
+      Boolean(connection?.connected && !connection.needsReconnect);
+    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;
+      }
+      /* Any other status — "connected", "pick-account", or one a shell of another vintage sends —
+         is a CLAIM that the callback ran, and the broker row is what adjudicates it. */
+      void fetchCfConnection().then(
+        (connection) => {
+          settle(usable(connection) ? { connection, status: "connected" } : { status: "timeout" });
+        },
+        /* This promise had no rejection handler, so one network blip left the listener installed,
+           the timer armed and the popup open forever. */
+        () => {
+          fail("Cloudflare connected, but the connection could not be confirmed");
+        },
+      );
+    };
+    window.addEventListener("message", onMessage);
+    const poll = async () => {
+      if (Date.now() > deadline) {
+        settle({ status: "timeout" });
+        return;
+      }
+      let connection: CfConnection | null = null;
+      let answered = true;
+      try {
+        connection = await fetchCfConnection();
+      } catch {
+        answered = false; // A blip is not an answer: re-arm and ask again.
+      }
+      /* The poll is a FALLBACK for shells whose postMessage never arrives, so it may only settle on
+         proof that THIS flow stored a fresh token: a usable row that was NOT already usable at the
+         baseline. For a reconnect, `needsReconnect` flipping false is that proof; for a connection
+         that was healthy all along nothing the poll can see is, so it must never settle — the relay
+         or the popup-closed path answers that case instead. */
+      if (answered && usable(connection) && !healthyBaseline) {
+        settle({ connection, status: "connected" });
+        return;
+      }
+      if (popup.closed) {
+        const final = await fetchCfConnection().catch(() => null);
+        settle(usable(final) ? { connection: final, status: "connected" } : { status: "canceled" });
+        return;
+      }
+      timer = window.setTimeout(() => {
+        void poll();
+      }, 1500);
+    };
+    timer = window.setTimeout(() => {
+      void poll();
+    }, 1500);
+  });
+}
 
 /** Parse an "owner/repo@branch" root key; null when malformed. */
 export function parseRootKey(root: string): CloudProject | null {
@@ -164,6 +314,35 @@ export function parseRootKey(root: string): CloudProject | null {
   return { owner, repo, branch };
 }
 
+/** Every project this account can open, straight off the wire; [] when the catalogue is unreachable. */
+async function fetchProjects(): Promise<ProjectListWire[]> {
+  const res = await fetch("/api/v1/projects", { credentials: "include" });
+  return res.ok ? ((await res.json()) as ProjectListWire[]) : [];
+}
+
+/**
+ * The project a root key names, for the two members that navigate by one.
+ *
+ * Tolerates the branchless "owner/repo" keys older studios wrote into Recent: they cannot say which
+ * branch they meant, so the catalogue's default branch answers for them — the same branch that
+ * project's Projects row opens. Null when the key is neither form, or names nothing this account
+ * can reach.
+ */
+export async function resolveRootKey(rootKey: string): Promise<CloudProject | null> {
+  const parsed = parseRootKey(rootKey);
+  if (parsed) {
+    return parsed;
+  }
+  const legacy = /^([^/@]+)\/([^/@]+)$/.exec(rootKey);
+  if (!legacy) {
+    return null;
+  }
+  const [, owner, repo] = legacy;
+  const catalogue = await fetchProjects().catch(() => []);
+  const match = catalogue.find((p) => p.owner === owner && p.name === repo);
+  return match ? { owner: match.owner, repo: match.name, branch: match.defaultBranch } : null;
+}
+
 /**
  * Bound mode (project non-null) drives one repo+branch session; project-less mode (null, the
  * /studio route) exposes only the catalogue surface — listProjects/listStarters/createProject and
@@ -171,7 +350,17 @@ export function parseRootKey(root: string): CloudProject | null {
  */
 export function createCloudPlatform(project: CloudProject | null): StudioPlatform {
   const base = project ? sessionBase(project) : "";
-  const root = project ? `${project.owner}/${project.repo}` : "";
+  /* The ROOT KEY, branch included — not a bare "owner/repo". This value is the project's identity
+     everywhere the shell keeps one: `probeRootProject` hands it to the recent-projects list, and
+     `setWindowProject` reopens a project by parsing it back with `parseRootKey`, which answers null
+     for a branchless key. So every Recent row a bound session had written was a click that did
+     nothing — no navigation, no error, and `deduped: true` telling the caller the open had been
+     handled — while the SAME project opened fine from the Projects catalogue, whose entries carry
+     the branch (`listProjects` below builds them with `projectRootKey`). Agreeing with the catalogue
+     also restores the welcome screen's dedupe (it matches the two lists by root, so the project
+     stopped appearing in both) and gives a branch its own Recent row, which is what a root key that
+     names a branch is for. */
+  const root = project ? projectRootKey(project) : "";
   /**
    * One multiplexed collab socket per session; per-doc handles come from openDoc. Memoized as a
    * promise so concurrent first opens share the connection instead of racing two sockets.
@@ -489,6 +678,45 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       }
     },
 
+    /**
+     * The extensions THIS WORKER bundles — not the shipped first-party catalogue.
+     *
+     * A Worker ships a fixed set of extension packages (specs/extensions.md §5.5), decided by the
+     * platform build rather than by this repository's `extensions/` tree, so the gateway is the
+     * only thing that knows. Everything it returns is therefore `bundled: true`: enabling one is a
+     * `project.json` write alone, and an extension the Worker does not bundle is dropped from the
+     * registry before composition — advertising it would promise a toggle that silently does
+     * nothing.
+     *
+     * `installed` here means DECLARED. Nothing resolves a module in a Worker: `addPackage` is a
+     * manifest edit and resolution happens later in Pages CI, so the manifest is the only fact this
+     * adapter has, and it is the one the reader is being asked about.
+     *
+     * Degrades to an EMPTY list, which is the whole contract: a session whose gateway predates this
+     * route must offer nothing rather than five extensions three of which it cannot load.
+     */
+    async listExtensionCatalog(): Promise<ExtensionCatalogEntry[]> {
+      try {
+        const res = await api("/catalog");
+        if (!res.ok) {
+          return [];
+        }
+        const entries = (await res.json()) as ExtensionCatalogEntry[];
+        const pkg = await readPackageJson();
+        const declared = new Set([
+          ...Object.keys((pkg["dependencies"] ?? {}) as Record<string, string>),
+          ...Object.keys((pkg["devDependencies"] ?? {}) as Record<string, string>),
+        ]);
+        for (const entry of entries) {
+          entry.bundled = true;
+          entry.installed = declared.has(entry.name);
+        }
+        return entries;
+      } catch {
+        return [];
+      }
+    },
+
     /**
      * The session's generated entry documents, composed server-side from the core schemas and each
      * enabled extension's fragments (extensions.md §5.2) and returned PRE-BUNDLED — Monaco and the
@@ -788,17 +1016,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     // ─── Project catalogue & navigation (Studio welcome / New Project UI) ──
 
     async listProjects(): Promise<ProjectListEntry[]> {
-      const res = await fetch("/api/v1/projects", { credentials: "include" });
-      if (!res.ok) {
-        return [];
-      }
-      const entries = (await res.json()) as {
-        fullName: string;
-        owner: string;
-        name: string;
-        defaultBranch: string;
-        permission: string;
-      }[];
+      const entries = await fetchProjects();
       return entries.map((p) => ({
         name: p.fullName,
         root: projectRootKey({ owner: p.owner, repo: p.name, branch: p.defaultBranch }),
@@ -816,8 +1034,15 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
 
     /** Welcome/recents open path: navigate this tab into the project's editor. */
     async setWindowProject(rootKey: string) {
-      const target = parseRootKey(rootKey);
-      if (target && typeof location !== "undefined") {
+      const target = await resolveRootKey(rootKey);
+      /* Throw rather than fall through: `deduped` tells the caller the open was handled, so an
+         unresolvable key answered "done" and left the user looking at the screen they clicked on.
+         The throw reaches `openRecentProject`'s catch, which reports the failure and drops the
+         entry — the right end for a row naming a project this account can no longer open. */
+      if (!target) {
+        throw new Error(`No project to open at ${rootKey}`);
+      }
+      if (typeof location !== "undefined") {
         location.assign(editUrl(target));
       }
       // Navigation unloads the page; deduped stops the caller's follow-up work.
@@ -825,8 +1050,13 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     },
 
     async openProjectInNewWindow(rootKey: string) {
-      const target = parseRootKey(rootKey);
-      if (target && typeof window !== "undefined") {
+      const target = await resolveRootKey(rootKey);
+      // Same contract as setWindowProject: the caller reports "Opened in another window" on any
+      // Resolved call, so a key that opens nothing has to fail rather than answer.
+      if (!target) {
+        throw new Error(`No project to open at ${rootKey}`);
+      }
+      if (typeof window !== "undefined") {
         window.open(editUrl(target), "_blank", "noopener");
       }
       // `_blank` always makes a tab; a browser tab already showing this project is not something
@@ -896,6 +1126,33 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       };
     },
 
+    /**
+     * AI-guided site import, streamed from the PLATFORM's import route rather than a session one.
+     *
+     * Deliberately not routed through `api()`: importing is how a cloud project comes into
+     * existence, so the one mode it has to work in is the project-less hub, where `api()` rejects
+     * before a request is ever made and `base` is "".
+     *
+     * The path is same-origin and relative, so `streamImport`'s plain `fetch` carries the session
+     * cookie under the default `same-origin` credentials mode — the same authority every
+     * `/api/v1/*` call here sends `credentials: "include"` for, with no cloud-shaped option added
+     * to the shared client. A bring-your-own-key run rides on the headers that client already sets,
+     * so the backend sees `X-Api-Key` / `X-Api-Base-URL` exactly as the OSS server does.
+     *
+     * `onReady` is forwarded and this backend never calls it, which is a difference worth naming:
+     * adopting the project mid-run would navigate this page to the editor and abort the request
+     * still writing the import, so the stream carries no `ready` line and the caller adopts on
+     * `done`. That is the same path a backend older than `ready` has always taken.
+     */
+    async importSite(
+      opts: ImportSiteOptions,
+      onProgress: (evt: ImportProgressEvent) => void,
+      signal?: AbortSignal,
+      onReady?: (evt: ImportReadyEvent) => void,
+    ) {
+      return await streamImport("/api/v1/import/site", opts, onProgress, signal, onReady);
+    },
+
     // ─── Identity & Cloudflare publish surface ──────────────────────────────
 
     async getUser() {
@@ -1001,71 +1258,75 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      * 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.
+     *
+     * Promise semantics, which are narrower than they look:
+     *
+     * - **Resolves `null`** only under the SSR guard, where there is no window to open.
+     * - **Resolves an outcome** for all four real endings — `connected`, `redirect` (popup blocked,
+     *   page navigating away), `canceled` (popup closed with nothing stored), `timeout` (180s).
+     * - **Rejects** only on a relayed OAuth error, or on a relayed success this platform could not
+     *   confirm against the broker.
+     *
+     * Concurrent calls JOIN the flow already running rather than starting a second one: both would
+     * open the same "cf-connect" target, and the first one's cleanup would then close the popup the
+     * second is waiting on.
      */
-    async cfConnect() {
+    cfConnect() {
       if (typeof window === "undefined" || typeof location === "undefined") {
-        return null;
+        return Promise.resolve(null);
       }
-      const popup = window.open("/api/v1/cf/connect", "cf-connect", "width=980,height=780");
-      if (!popup) {
-        location.assign("/api/v1/cf/connect");
-        return null;
+      const running = cfConnectFlow;
+      if (running) {
+        try {
+          running.popup?.focus();
+        } catch {
+          // A cross-origin popup may refuse focus; joining the flow is what mattered.
+        }
+        return running.promise;
       }
-      const deadline = Date.now() + 180_000;
-      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);
+      const handle: CfConnectFlow = { popup: null, promise: Promise.resolve(null) };
+      cfConnectFlow = handle;
+      handle.promise = runCfConnect(handle).finally(() => {
+        if (cfConnectFlow === handle) {
+          cfConnectFlow = null;
+        }
       });
+      return handle.promise;
+    },
+
+    /**
+     * Every Cloudflare account this connection can reach (the account picker's rows).
+     *
+     * A non-OK body is the broker's own unusable-connection payload — `{error, code}` naming a
+     * lapsed grant or a connection that never existed — so its sentence is the one worth showing.
+     */
+    async cfAccounts() {
+      const res = await fetch("/api/v1/cf/accounts", { credentials: "include" });
+      return okJson<CfAccountSummary[]>(res, "Failed to list Cloudflare accounts");
+    },
+
+    /** Store the chosen account on the brokered connection. */
+    async cfSelectAccount(account: { id: string; name?: string }) {
+      const res = await fetch("/api/v1/cf/select-account", {
+        body: JSON.stringify({ accountId: account.id, accountName: account.name }),
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, "Failed to select a Cloudflare account"));
+      }
+    },
+
+    /** Forget the brokered connection (the broker revokes its tokens upstream). */
+    async cfDisconnect() {
+      const res = await fetch("/api/v1/cf/connection", {
+        credentials: "include",
+        method: "DELETE",
+      });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, "Failed to disconnect Cloudflare"));
+      }
     },
 
     /** Allowlisted Cloudflare API passthrough (platform injects the OAuth token). */

package/src/platforms/devserver.ts

@@ -25,6 +25,7 @@ import type {
   DataRowsResult,
   DataRowUpdate,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   ImportProgressEvent,
@@ -745,6 +746,18 @@ export function createDevServerPlatform() {
       return body.extensions ?? [];
     },
 
+    /**
+     * What this backend can offer, enabled or not.
+     *
+     * Its own route rather than a field on `formats`: that one builds the project's registry and
+     * fails when a declared extension does not resolve, which is exactly when a reader needs the
+     * catalogue to repair it.
+     */
+    async listExtensionCatalog(): Promise<ExtensionCatalogEntry[]> {
+      const res = await fetch(`/__studio/catalog?dir=${encodeURIComponent(serverPath("."))}`);
+      return res.ok ? await readJson<ExtensionCatalogEntry[]>(res) : [];
+    },
+
     /** Pre-bundled per-project entry schemas for Monaco registration (empty when unavailable). */
     async fetchProjectSchemas(): Promise<ProjectSchemasResponse> {
       const res = await fetch(