@jxsuite/studio 6.1.1 → 8.0.0

package/src/platforms/read-batcher.ts

@@ -21,6 +21,7 @@
 
 import { READ_FILES_MAX_PATHS } from "@jxsuite/protocol";
 import type { ReadFilesResult } from "@jxsuite/protocol";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 
 /**
  * What one batch request came back as.
@@ -57,14 +58,20 @@ export interface ReadBatcher {
 
 interface Waiter {
   resolve: (content: string) => void;
-  reject: (error: unknown) => void;
+  /** Rejects with whatever the transport or `fetchOne` rejected with, unchanged. */
+  reject: (cause: unknown) => void;
 }
 
 /** Path → every caller waiting on it. Same-path reads in one window share ONE request and result. */
 type Pending = Map<string, Waiter[]>;
 
-function isObject(value: unknown): value is object {
-  return typeof value === "object" && value !== null;
+/**
+ * A row's outcome as the batcher reads it. Every protocol outcome fits it, but the rows come off
+ * the wire unchecked, so `content` may be any value and either member may be missing.
+ */
+interface WireOutcome {
+  content?: unknown;
+  error?: { message?: string } | undefined;
 }
 
 /**
@@ -108,7 +115,7 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
           waiter.resolve(content);
         }
       },
-      (error: unknown) => {
+      (error) => {
         for (const waiter of waiters) {
           waiter.reject(error);
         }
@@ -182,7 +189,7 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
     }
     /* Anything that is not an object cannot be a ReadFilesResult (a `null` body, a bare string).
        The route did not answer this chunk, so it is served singly — the same as a failed call. */
-    if (answer === "retry-singly" || answer === "unsupported" || !isObject(answer)) {
+    if (answer === "retry-singly" || answer === "unsupported" || !isNonNullObject(answer)) {
       if (answer === "unsupported") {
         batching = false;
       }
@@ -213,14 +220,15 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
       }
       chunk.delete(path);
       answered += 1;
-      if (typeof (outcome as { content?: unknown } | undefined)?.content === "string") {
-        const { content } = outcome as { content: string };
+      const wire: WireOutcome | undefined = outcome;
+      const content = wire?.content;
+      if (isString(content)) {
         for (const waiter of waiters) {
           waiter.resolve(content);
         }
       } else {
         // Per path: one missing file (404), one binary file (415) fails ITS readers and no others.
-        const message = (outcome as { error?: { message?: string } } | undefined)?.error?.message;
+        const message = wire?.error?.message;
         const error = new Error(message || `Failed to read file: ${path}`);
         for (const waiter of waiters) {
           waiter.reject(error);

package/src/project-list.ts

@@ -3,6 +3,7 @@
  * member (dev server sites, cloud platforms). Hydrated once at boot (studio.ts) like the
  * recent-projects cache; the welcome screen reads it synchronously.
  */
+import { isFunction } from "@jxsuite/schema/guards";
 import { getPlatform, hasPlatform } from "./platform";
 import type { ProjectListEntry } from "./types";
 
@@ -10,7 +11,7 @@ let cache: ProjectListEntry[] = [];
 
 /** True when the active platform exposes a project catalogue. */
 export function platformListsProjects(): boolean {
-  return hasPlatform() && typeof getPlatform().listProjects === "function";
+  return hasPlatform() && isFunction(getPlatform().listProjects);
 }
 
 /** Refresh the cache from the platform; resolves to [] when unsupported or failing. */

package/src/publish/deploy-checklist.ts

@@ -75,7 +75,7 @@ export interface DeployStep {
 
 /** The active project's configuration, or null when no project is open. */
 function currentConfig(): ProjectConfig | null {
-  return (projectState?.projectConfig as ProjectConfig | undefined) ?? null;
+  return projectState?.projectConfig ?? null;
 }
 
 /**
@@ -152,6 +152,11 @@ function repoStep(): DeployStep {
       };
 }
 
+/** The remotes a host's git status actually carries: a host may omit the array altogether. */
+interface ReportedRemotes {
+  remotes?: string[] | undefined;
+}
+
 function remoteStep(): DeployStep {
   const { status } = shell.git;
   if (status === null || !status.isRepo) {
@@ -165,7 +170,8 @@ function remoteStep(): DeployStep {
   }
   // A GitStatus from a host that reports no remotes array is not a repo with remotes — it is a
   // Host that did not say. Reading through it took the whole status bar down with a TypeError.
-  if ((status.remotes ?? []).length === 0) {
+  const reported: ReportedRemotes = status;
+  if ((reported.remotes ?? []).length === 0) {
     return {
       command: "git.createGithubRepository",
       detail: "This repository is local only — nothing outside this machine can build it.",
@@ -313,17 +319,22 @@ export function deployStatusItem(): DeployStatusItem | null {
 
 // ─── 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: "?",
+/**
+ * The kit icon a link's state wears, and the state in words for a reader who cannot see it. Names
+ * from the kit's glyph manifest rather than text glyphs: a `·` or a `?` beside a sentence read as
+ * punctuation and said nothing to a screen reader.
+ */
+const STEP_ICON: Readonly<Record<DeployStepState, { icon: string; label: string }>> = {
+  done: { icon: "check", label: "Done" },
+  todo: { icon: "warning-circle", label: "To do" },
+  unknown: { icon: "question", label: "Not checked yet" },
 };
 
-/** One prerequisite, flattened for the document: a key, a state, a glyph and a sentence. */
+/** One prerequisite, flattened for the document: a key, a state, an icon and a sentence. */
 function stepView(step: DeployStep): DeployStepRowView {
   return {
-    icon: STEP_ICON[step.state],
+    icon: STEP_ICON[step.state].icon,
+    iconLabel: STEP_ICON[step.state].label,
     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

package/src/publish/pages-service.ts

@@ -10,15 +10,16 @@
  */
 
 import { updateWranglerConfig } from "@jxsuite/create/scaffold";
+import { isFunction } from "@jxsuite/schema/guards";
 import type { DeployConfig, ProjectConfig } from "@jxsuite/schema/types";
+import type { CfAccountSummary } from "../types";
 import { getPlatform } from "../platform";
 import { actIfRequired } from "../account/action-flow";
 import { updateSiteConfig } from "../site-context";
 
-export interface CfAccount {
-  id: string;
-  name: string;
-}
+/* A Cloudflare account the connected token can reach is the platform's `CfAccountSummary` row;
+   `CfAccount` stays this module's name for it. */
+export type { CfAccountSummary as CfAccount } from "../types";
 
 export interface PagesDeploymentInfo {
   id: string;
@@ -28,6 +29,12 @@ export interface PagesDeploymentInfo {
   stage: string;
   status: string;
   createdOn: string;
+  /**
+   * The branch the deployment was built from, when Cloudflare says (its trigger metadata). A
+   * preview's branch is what names it in Publish › Deploys; a production deployment usually carries
+   * the production branch.
+   */
+  branch?: string;
 }
 
 export interface ConnectOptions {
@@ -52,7 +59,7 @@ export function platformSupportsPublish(): boolean {
   // Publishing is not available yet. "Can this host publish?" has a truthful answer before the host
   // Exists, and it is no.
   try {
-    return typeof getPlatform().cfApi === "function";
+    return isFunction(getPlatform().cfApi);
   } catch {
     return false;
   }
@@ -69,6 +76,8 @@ async function cfApi<T>(path: string, init?: { method?: string; body?: unknown }
     throw new Error("This platform cannot reach the Cloudflare API");
   }
   try {
+    /* SAFETY: every adapter's cfApi resolves to the Cloudflare v4 envelope's `result`, unvalidated,
+       and each caller names the shape Cloudflare documents for the endpoint it calls. */
     return (await api(path, init)) as T;
   } catch (error) {
     void actIfRequired(error);
@@ -76,8 +85,8 @@ async function cfApi<T>(path: string, init?: { method?: string; body?: unknown }
   }
 }
 
-export async function listAccounts(): Promise<CfAccount[]> {
-  return cfApi<CfAccount[]>("/accounts");
+export async function listAccounts(): Promise<CfAccountSummary[]> {
+  return cfApi<CfAccountSummary[]>("/accounts");
 }
 
 interface PagesProjectWire {
@@ -104,16 +113,19 @@ export async function getPagesProject(
  * with an install hint.
  */
 export async function createPagesProject(opts: ConnectOptions): Promise<PagesProjectWire> {
+  const buildConfig: PagesBuildConfigWire = {
+    build_command: "bunx jx build",
+    destination_dir: "dist",
+  };
+  if (opts.rootDir) {
+    buildConfig.root_dir = opts.rootDir;
+  }
   return cfApi<PagesProjectWire>(`/accounts/${opts.accountId}/pages/projects`, {
     method: "POST",
     body: {
       name: opts.projectName,
       production_branch: opts.productionBranch,
-      build_config: {
-        build_command: "bunx jx build",
-        destination_dir: "dist",
-        ...(opts.rootDir ? { root_dir: opts.rootDir } : {}),
-      },
+      build_config: buildConfig,
       source: {
         type: "github",
         config: {
@@ -127,31 +139,56 @@ export async function createPagesProject(opts: ConnectOptions): Promise<PagesPro
   });
 }
 
+/** The `build_config` Cloudflare stores on a GitHub-connected Pages project. */
+interface PagesBuildConfigWire {
+  build_command: string;
+  destination_dir: string;
+  root_dir?: string;
+}
+
 interface DeploymentWire {
   id: string;
   url: string;
   environment: string;
   latest_stage?: { name?: string; status?: string };
   created_on: string;
+  deployment_trigger?: { metadata?: { branch?: string } };
 }
 
-/** The most recent deployment of the connected project, or null when none. */
-export async function latestDeployment(deploy: DeployConfig): Promise<PagesDeploymentInfo | null> {
+/** One wire row as the app reads it: the stage flattened, the branch kept only when it is said. */
+function deploymentInfo(row: DeploymentWire): PagesDeploymentInfo {
+  const info: PagesDeploymentInfo = {
+    id: row.id,
+    url: row.url,
+    environment: row.environment,
+    stage: row.latest_stage?.name ?? "unknown",
+    status: row.latest_stage?.status ?? "unknown",
+    createdOn: row.created_on,
+  };
+  const branch = row.deployment_trigger?.metadata?.branch;
+  if (branch) {
+    info.branch = branch;
+  }
+  return info;
+}
+
+/**
+ * Every deployment of the connected project Cloudflare returns, newest first, as it orders them.
+ *
+ * All of them, not the latest alone: Publish › Deploys draws the history and the branch previews
+ * from this one list (studio.md §22.8), and the latest is simply its first row.
+ */
+export async function listDeployments(deploy: DeployConfig): Promise<PagesDeploymentInfo[]> {
   const deployments = await cfApi<DeploymentWire[]>(
     `/accounts/${deploy.accountId}/pages/projects/${deploy.projectName}/deployments`,
   );
-  const [latest] = deployments;
-  if (!latest) {
-    return null;
-  }
-  return {
-    id: latest.id,
-    url: latest.url,
-    environment: latest.environment,
-    stage: latest.latest_stage?.name ?? "unknown",
-    status: latest.latest_stage?.status ?? "unknown",
-    createdOn: latest.created_on,
-  };
+  return deployments.map((row) => deploymentInfo(row));
+}
+
+/** The most recent deployment of the connected project, or null when none. */
+export async function latestDeployment(deploy: DeployConfig): Promise<PagesDeploymentInfo | null> {
+  const [latest] = await listDeployments(deploy);
+  return latest ?? null;
 }
 
 /**
@@ -205,8 +242,10 @@ export async function connectDeploy(
     provider: "cloudflare-pages",
     accountId: opts.accountId,
     projectName: opts.projectName,
-    ...(project.subdomain ? { productionUrl: `https://${project.subdomain}` } : {}),
   };
+  if (project.subdomain) {
+    deploy.productionUrl = `https://${project.subdomain}`;
+  }
   await writeDeployConfig(config, deploy);
   return deploy;
 }