@jxsuite/studio 4.1.0 → 5.0.0

package/src/platforms/cloud.ts

@@ -25,6 +25,7 @@ import type {
   ComponentMeta,
   CreateProjectDestination,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -60,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[];
@@ -304,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
@@ -311,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.
@@ -629,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
@@ -928,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 }),
@@ -956,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.
@@ -965,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

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(

package/src/publish/deploy-checklist.ts

@@ -13,11 +13,12 @@
  *
  * - {@link deployChecklist} is the ordered prerequisite list, each step carrying **the command that
  *   satisfies it** rather than a sentence telling the reader to go and find one;
- * - {@link renderDeployChecklist} is its rendering, and it lives in the Bottom dock's **Activity**
- *   tab because a deploy is a long operation with a log and the dock cap is four (§2 principle 9).
- *   It draws in the Activity vocabulary — `activity-row`, `activity-steps`, `activity-step--done` —
- *   for the same reason: a fifth visual idiom for "an ordered list of stages that finish" would be
- *   a second design of a thing the tab already has;
+ * - {@link deployChecklistView} is its projection and {@link syncDeployChecklist} mounts the document
+ *   that draws it (`surfaces/panel-deploy-checklist.json`), in the Bottom dock's **Activity** tab
+ *   because a deploy is a long operation with a log and the dock cap is four (§2 principle 9). It
+ *   draws in the Activity tab's vocabulary — the same row, the same ordered steps, the same glyphs
+ *   — for the same reason: a fifth visual idiom for "an ordered list of stages that finish" would
+ *   be a second design of a thing the tab already has;
  * - {@link deployStatusItem} is the status bar's project-field item, whose **label is the next
  *   blocking prerequisite** — the shortcut and the explanation in one 24px item, and ambient state
  *   rather than a transient message, which is the only thing that bar carries (§3.2 ⑫).
@@ -34,14 +35,18 @@
  * renders (`studio.md` §15 rule 1).
  */
 
-import { html, nothing } from "lit-html";
 import { activeRegistry } from "../commands/active-registry";
 import { platformSupportsPublish } from "./pages-service";
 import { projectState } from "../store";
+import { shallowReactive } from "../reactivity";
 import { shell } from "../shell";
+import {
+  disposeDeployChecklistSurface,
+  mountDeployChecklistSurface,
+} from "../surfaces/panel-deploy-checklist";
+import type { DeployChecklistView, DeployStepRowView } from "../surfaces/panel-deploy-checklist";
 import type { DeployConfig, ProjectConfig } from "@jxsuite/schema/types";
 import type { PagesDeploymentInfo } from "./pages-service";
-import type { TemplateResult } from "lit-html";
 
 /** The chain, in the order the links must be forged. */
 export const DEPLOY_STEP_IDS = ["repo", "remote", "provider", "deployed"] as const;
@@ -84,32 +89,38 @@ export function currentDeploy(): DeployConfig | undefined {
 }
 
 /**
- * The last deployment anybody actually observed, or null when nobody has asked.
+ * The last deployment anybody actually observed, and whether anybody has asked at all.
  *
  * Module state rather than a field on the config: a deployment is a fact about Cloudflare, not
  * about this repository, and writing it into `project.json` would commit a timestamp that is stale
  * the moment it is pushed.
+ *
+ * Reactive, because the checklist is a document now and follows its inputs rather than being
+ * repainted by whatever else the dock was drawing: a deploy that finishes writes here, and the row
+ * moves off `unknown` with nothing subscribing by hand. `shallowReactive` and not `reactive`, so
+ * {@link observedDeployment} hands back the record Cloudflare answered with rather than a proxy of
+ * it — `asked` is the flag anything tracks, and the info is read whole or not at all.
  */
-let _observed: PagesDeploymentInfo | null = null;
-
-/** Whether anybody has asked at all — the difference between `todo` and `unknown`. */
-let _asked = false;
+const _seen = shallowReactive<{ asked: boolean; observed: PagesDeploymentInfo | null }>({
+  asked: false,
+  observed: null,
+});
 
 /** Record what Cloudflare answered. `null` means "asked, and there are none". */
 export function noteDeployment(info: PagesDeploymentInfo | null): void {
-  _observed = info;
-  _asked = true;
+  _seen.observed = info;
+  _seen.asked = true;
 }
 
 /** The observed deployment, or null. */
 export function observedDeployment(): PagesDeploymentInfo | null {
-  return _observed;
+  return _seen.observed;
 }
 
 /** Forget the observation — project close, and every test that asserts the `unknown` branch. */
 export function forgetDeployment(): void {
-  _observed = null;
-  _asked = false;
+  _seen.observed = null;
+  _seen.asked = false;
 }
 
 function repoStep(): DeployStep {
@@ -219,7 +230,7 @@ function deployedStep(): DeployStep {
       state: "todo",
     };
   }
-  if (!_asked) {
+  if (!_seen.asked) {
     return {
       command: "publish.deploy",
       detail: "Cloudflare has not been asked yet, so this is not a claim that nothing shipped.",
@@ -228,7 +239,7 @@ function deployedStep(): DeployStep {
       state: "unknown",
     };
   }
-  if (_observed === null) {
+  if (_seen.observed === null) {
     return {
       command: "publish.deploy",
       detail: "Cloudflare reports no deployments for this project.",
@@ -237,17 +248,18 @@ function deployedStep(): DeployStep {
       state: "todo",
     };
   }
-  return _observed.status === "success"
+  const { observed } = _seen;
+  return observed.status === "success"
     ? {
         command: "publish.deploy",
-        detail: `${_observed.environment} — ${_observed.url}`,
+        detail: `${observed.environment} — ${observed.url}`,
         id: "deployed",
         label: "Deploy",
         state: "done",
       }
     : {
         command: "publish.deploy",
-        detail: `Last deployment ${_observed.stage}: ${_observed.status}.`,
+        detail: `Last deployment ${observed.stage}: ${observed.status}.`,
         id: "deployed",
         label: "Deploy",
         state: "todo",
@@ -298,86 +310,120 @@ export function deployStatusItem(): DeployStatusItem | null {
   };
 }
 
-// ─── Rendering ────────────────────────────────────────────────────────────────
-
-/** Checklist state → the Activity tab's step classes, so one vocabulary draws both. */
-const STEP_CLASS: Readonly<Record<DeployStepState, string>> = {
-  done: "done",
-  todo: "pending",
-  unknown: "pending",
-};
+// ─── The surface ──────────────────────────────────────────────────────────────
 
+/** Which glyph a link's state wears. One character, so it fits the row it labels. */
 const STEP_ICON: Readonly<Record<DeployStepState, string>> = {
   done: "✓",
   todo: "·",
   unknown: "?",
 };
 
+/** One prerequisite, flattened for the document: a key, a state, a glyph and a sentence. */
+function stepView(step: DeployStep): DeployStepRowView {
+  return {
+    icon: STEP_ICON[step.state],
+    id: step.id,
+    state: step.state,
+    /* The detail is dropped once the link is forged: what a done step buys you is not news, and
+       four sentences about things that are fine bury the one about the thing that is not. */
+    text: step.state === "done" ? step.label : `${step.label} — ${step.detail}`,
+  };
+}
+
 /**
- * The next action, as a button — or nothing.
+ * The next action, as the document reads it — or nothing.
  *
- * A command the registry does not have, or whose `when` is false, renders NOTHING rather than a
- * dead label. The status bar's `itemTpl` takes the same position for the same reason: a surface may
- * choose whether to show a command, never whether it exists.
+ * A command the registry does not have, or whose `when` is false, draws NOTHING rather than a dead
+ * label. The status bar's projection takes the same position for the same reason: a surface may
+ * choose whether to show a command, never whether it exists (§12.4).
  */
-function actionTpl(step: DeployStep | null): TemplateResult | typeof nothing {
+function actionView(
+  step: DeployStep | null,
+): Pick<DeployChecklistView, "actionDisabled" | "actionLabel" | "actionTitle" | "hasAction"> {
+  const none = { actionDisabled: false, actionLabel: "", actionTitle: "", hasAction: false };
   if (!step) {
-    return nothing;
+    return none;
   }
   const registry = activeRegistry();
   const command = registry?.get(step.command);
   if (!registry || !command || !registry.isVisible(step.command)) {
-    return nothing;
+    return none;
   }
   const reason = registry.disabledReason(step.command);
-  return html`<sp-action-button
-    size="s"
-    ?disabled=${reason !== undefined}
-    title=${reason ? `${command.title} — requires ${reason}` : command.title}
-    @click=${() => {
-      void registry.run(step.command);
-    }}
-    >${command.title}</sp-action-button
-  >`;
+  return {
+    actionDisabled: reason !== undefined,
+    actionLabel: command.title,
+    actionTitle: reason ? `${command.title} — requires ${reason}` : command.title,
+    hasAction: true,
+  };
 }
 
 /**
- * The checklist, as the Activity tab draws it — or nothing, when no project is open.
+ * The checklist as the document draws it — or an empty row set, when no project is open.
  *
- * Rendered ABOVE the operation list rather than as an entry in it: an activity is something that
- * happened, and this is something that has not. It carries no `data-jx-region` stamp — the region
- * is `dock.bottom/panel:activity`, which the dock derives, and a hand-stamped leaf is a committed
- * budget (§13.2) that this does not need to spend.
+ * Read from inside the surface's own effect, so every reactive record it touches on the way (source
+ * control's status, the project config, the observation above, the active registry) is tracked and
+ * the row follows them.
  */
-export function renderDeployChecklist(): TemplateResult | typeof nothing {
+export function deployChecklistView(): DeployChecklistView {
   if (!projectState) {
-    return nothing;
+    return {
+      actionDisabled: false,
+      actionLabel: "",
+      actionTitle: "",
+      hasAction: false,
+      hasProject: false,
+      rowIcon: "",
+      rowState: "running",
+      steps: [],
+      summary: "",
+    };
   }
   const steps = deployChecklist();
   const next = steps.find((step) => step.state !== "done") ?? null;
-  return html`
-    <ul class="activity-list">
-      <li class="activity-row ${next ? "activity-row--running" : "activity-row--done"}">
-        <span class="activity-icon" aria-hidden="true">${next ? "⋯" : "✓"}</span>
-        <div class="activity-body">
-          <div class="activity-head">
-            <span class="activity-title">Deploy checklist</span>
-            <span class="activity-source">Publish</span>
-          </div>
-          <div class="activity-status">
-            ${next ? next.detail : "Everything this project needs to ship is in place."}
-          </div>
-          <ol class="activity-steps">
-            ${steps.map(
-              (step) => html`<li class="activity-step activity-step--${STEP_CLASS[step.state]}">
-                <span class="activity-step-icon" aria-hidden="true">${STEP_ICON[step.state]}</span>
-                ${step.label}${step.state === "done" ? "" : ` — ${step.detail}`}
-              </li>`,
-            )}
-          </ol>
-          ${actionTpl(next)}
-        </div>
-      </li>
-    </ul>
-  `;
+  return {
+    ...actionView(next),
+    hasProject: true,
+    rowIcon: next ? "⋯" : "✓",
+    rowState: next ? "running" : "done",
+    steps: steps.map((entry) => stepView(entry)),
+    summary: next ? next.detail : "Everything this project needs to ship is in place.",
+  };
+}
+
+/** Run the next blocking step's command, if the registry has one it will run. */
+function runNextStep(): void {
+  const next = nextDeployStep();
+  if (!next) {
+    return;
+  }
+  void activeRegistry()?.run(next.command);
+}
+
+/** What the surface asks this module for: the projection, and the one decision a click makes. */
+const CHECKLIST_SURFACE = { project: deployChecklistView, runAction: runNextStep };
+
+/**
+ * Mount the checklist into the container the Activity tab just painted, or take it down.
+ *
+ * The tab's `afterRender`, so it runs against the DOM lit has committed — and it runs on every
+ * paint of the dock, including the ones where another tab is showing. No container means this tab
+ * is not on screen, and the document standing in DOM that lit has already thrown away is disposed
+ * rather than left holding an effect.
+ *
+ * Rendered ABOVE the operation feed rather than as an entry in it: an activity is something that
+ * happened, and this is something that has not. It carries no `data-jx-region` stamp — the region
+ * is `dock.bottom/panel:activity`, which the dock derives, and a hand-stamped leaf is a committed
+ * budget (§13.2) that this does not need to spend.
+ *
+ * @param host The dock body element the tab was rendered into.
+ */
+export function syncDeployChecklist(host: HTMLElement): void {
+  const container = host.querySelector<HTMLElement>("[data-deploy-checklist]");
+  if (!container) {
+    disposeDeployChecklistSurface();
+    return;
+  }
+  mountDeployChecklistSurface(container, CHECKLIST_SURFACE);
 }

package/src/publish/publish-commands.ts

@@ -157,12 +157,8 @@ export function publishCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       // `when` already asked about the project.
       enablement: () => platformSupportsPublish(),
-      aiTool: {
-        description:
-          "Open the publishing set-up flow, which connects this project to a Cloudflare Pages " +
-          "project that rebuilds on every push.",
-        name: "set_up_publishing",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: an auth flow that waits on a person, with
+         credentials. */
       run: async () => {
         const { openPublishPanel } = await import("./publish-panel");
         openPublishPanel();
@@ -181,12 +177,8 @@ export function publishCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       enablement: (ctx) =>
         ctx.project.isRepo && currentDeploy() !== undefined && platformSupportsPublish(),
-      aiTool: {
-        description:
-          "Push the current branch so the connected provider builds it, then report the " +
-          "deployment. Does not commit — commit first if there are unsaved changes.",
-        name: "deploy_site",
-      },
+      /* No `aiTool`, by §12.4's third deletion rule: remote and irreversible, the same class as
+         `packages.remove`. */
       run: async () => {
         await runDeploy();
       },