@jxsuite/studio 2.0.1 → 2.1.0

package/src/publish/deploy-checklist.ts

@@ -0,0 +1,383 @@
+/// <reference lib="dom" />
+/**
+ * Deploy-checklist.ts — what is MISSING before this project can ship, as an ordered list.
+ *
+ * What this replaces: a Cloudflare form that opened asking for a GitHub owner and repository on a
+ * project that had never been `git init`-ed, failed with a Cloudflare API error naming neither
+ * fact, and offered no way forward. Publishing is a CHAIN — the repository exists, it has a remote
+ * and the remote is current, a provider is connected, a deployment happened — and every link is a
+ * different command owned by a different module. Nothing in Studio held the chain, so no surface
+ * could say which link was missing.
+ *
+ * This module is the chain (plan §9.5):
+ *
+ * - {@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 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 ⑫).
+ *
+ * **A step it cannot answer says `unknown`.** `services/references.ts` established the rule and it
+ * matters more here: "no deployment" and "we have not asked Cloudflare" look identical from inside
+ * the app, and a checklist that renders the second as the first tells the user to redo a deploy
+ * that already succeeded. The observation cache ({@link noteDeployment}) is written by the code
+ * that actually asked — the Publish panel's load and {@link import("./publish-commands").runDeploy}
+ * — and by nothing else.
+ *
+ * **No secret reaches this module.** A provider is connected or it is not; the token that proves it
+ * is read by `platforms/devserver.ts` on its way to the same-origin proxy and by nothing that
+ * 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 { shell } from "../shell";
+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;
+
+export type DeployStepId = (typeof DEPLOY_STEP_IDS)[number];
+
+/**
+ * Whether a link is forged.
+ *
+ * `unknown` is not a third kind of "no": it is the honest answer when the fact lives on a server
+ * nobody has asked. It blocks like a `todo` and it READS differently, which is the whole point.
+ */
+export type DeployStepState = "done" | "todo" | "unknown";
+
+/** One prerequisite. */
+export interface DeployStep {
+  readonly id: DeployStepId;
+  /** Imperative, and short enough to be a 24px status-bar label. */
+  readonly label: string;
+  readonly state: DeployStepState;
+  /** One sentence: what is true now, or what satisfying it buys. Never a secret. */
+  readonly detail: string;
+  /** The command that satisfies it — an id, so the row inherits title, chord and refusal. */
+  readonly command: string;
+}
+
+/** The active project's configuration, or null when no project is open. */
+function currentConfig(): ProjectConfig | null {
+  return (projectState?.projectConfig as ProjectConfig | undefined) ?? null;
+}
+
+/**
+ * The connected provider block, or `undefined`.
+ *
+ * Exported because the Publish panel asks the same question and P6's lesson was that two copies of
+ * one derivation drift apart in silence — there is one reader of `build.deploy` in the app.
+ */
+export function currentDeploy(): DeployConfig | undefined {
+  return currentConfig()?.build?.deploy;
+}
+
+/**
+ * The last deployment anybody actually observed, or null when nobody has asked.
+ *
+ * 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.
+ */
+let _observed: PagesDeploymentInfo | null = null;
+
+/** Whether anybody has asked at all — the difference between `todo` and `unknown`. */
+let _asked = false;
+
+/** Record what Cloudflare answered. `null` means "asked, and there are none". */
+export function noteDeployment(info: PagesDeploymentInfo | null): void {
+  _observed = info;
+  _asked = true;
+}
+
+/** The observed deployment, or null. */
+export function observedDeployment(): PagesDeploymentInfo | null {
+  return _observed;
+}
+
+/** Forget the observation — project close, and every test that asserts the `unknown` branch. */
+export function forgetDeployment(): void {
+  _observed = null;
+  _asked = false;
+}
+
+function repoStep(): DeployStep {
+  const { status } = shell.git;
+  if (status === null) {
+    return {
+      command: "git.init",
+      detail: "Source control has not reported on this project yet.",
+      id: "repo",
+      label: "Track this project with git",
+      state: "unknown",
+    };
+  }
+  return status.isRepo
+    ? {
+        command: "git.init",
+        detail: `Tracked${status.branch ? ` — on branch ${status.branch}` : ""}.`,
+        id: "repo",
+        label: "Track this project with git",
+        state: "done",
+      }
+    : {
+        command: "git.init",
+        detail: "A deploy ships what the repository holds, so the repository comes first.",
+        id: "repo",
+        label: "Track this project with git",
+        state: "todo",
+      };
+}
+
+function remoteStep(): DeployStep {
+  const { status } = shell.git;
+  if (status === null || !status.isRepo) {
+    return {
+      command: "git.createGithubRepository",
+      detail: "A remote is where the provider builds from.",
+      id: "remote",
+      label: "Push to a remote",
+      state: status === null ? "unknown" : "todo",
+    };
+  }
+  // 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) {
+    return {
+      command: "git.createGithubRepository",
+      detail: "This repository is local only — nothing outside this machine can build it.",
+      id: "remote",
+      label: "Push to a remote",
+      state: "todo",
+    };
+  }
+  return status.ahead > 0
+    ? {
+        command: "git.push",
+        detail: `${status.ahead} commit(s) are not on ${status.remotes[0]} yet, so a build would ship the older tree.`,
+        id: "remote",
+        label: "Push to a remote",
+        state: "todo",
+      }
+    : {
+        command: "git.push",
+        detail: `Up to date with ${status.remotes[0]}.`,
+        id: "remote",
+        label: "Push to a remote",
+        state: "done",
+      };
+}
+
+function providerStep(): DeployStep {
+  const deploy = currentDeploy();
+  if (deploy) {
+    return {
+      command: "publish.setUp",
+      detail: `Cloudflare Pages project ${deploy.projectName}.`,
+      id: "provider",
+      label: "Connect a deploy provider",
+      state: "done",
+    };
+  }
+  return platformSupportsPublish()
+    ? {
+        command: "publish.setUp",
+        detail: "Connecting one makes every commit build and publish on its own.",
+        id: "provider",
+        label: "Connect a deploy provider",
+        state: "todo",
+      }
+    : {
+        command: "publish.setUp",
+        detail:
+          "This platform cannot reach the Cloudflare API. Commit and push instead — your host " +
+          "runs bunx jx build and serves dist/.",
+        id: "provider",
+        label: "Connect a deploy provider",
+        state: "unknown",
+      };
+}
+
+function deployedStep(): DeployStep {
+  if (!currentDeploy()) {
+    return {
+      command: "publish.deploy",
+      detail: "Nothing has been deployed, because no provider is connected.",
+      id: "deployed",
+      label: "Deploy",
+      state: "todo",
+    };
+  }
+  if (!_asked) {
+    return {
+      command: "publish.deploy",
+      detail: "Cloudflare has not been asked yet, so this is not a claim that nothing shipped.",
+      id: "deployed",
+      label: "Deploy",
+      state: "unknown",
+    };
+  }
+  if (_observed === null) {
+    return {
+      command: "publish.deploy",
+      detail: "Cloudflare reports no deployments for this project.",
+      id: "deployed",
+      label: "Deploy",
+      state: "todo",
+    };
+  }
+  return _observed.status === "success"
+    ? {
+        command: "publish.deploy",
+        detail: `${_observed.environment} — ${_observed.url}`,
+        id: "deployed",
+        label: "Deploy",
+        state: "done",
+      }
+    : {
+        command: "publish.deploy",
+        detail: `Last deployment ${_observed.stage}: ${_observed.status}.`,
+        id: "deployed",
+        label: "Deploy",
+        state: "todo",
+      };
+}
+
+/** The four prerequisites, in order. */
+export function deployChecklist(): DeployStep[] {
+  return [repoStep(), remoteStep(), providerStep(), deployedStep()];
+}
+
+/**
+ * The first link that is not forged, or null when the chain is whole.
+ *
+ * `unknown` counts as not forged: the app may not claim a step is done on the strength of not
+ * having asked.
+ */
+export function nextDeployStep(): DeployStep | null {
+  return deployChecklist().find((step) => step.state !== "done") ?? null;
+}
+
+/** What the status bar's project field shows. `null` when there is no project to deploy. */
+export interface DeployStatusItem {
+  readonly command: string;
+  readonly label: string;
+  readonly title: string;
+}
+
+/**
+ * The status-bar item — ambient state, never a transient message.
+ *
+ * Its LABEL is the next blocking prerequisite, so the item explains itself: a reader who does not
+ * know what is missing learns it from the same 24px string that fixes it.
+ */
+export function deployStatusItem(): DeployStatusItem | null {
+  if (!projectState) {
+    return null;
+  }
+  const next = nextDeployStep();
+  if (next) {
+    return { command: next.command, label: next.label, title: next.detail };
+  }
+  const url = currentDeploy()?.productionUrl;
+  return {
+    command: "publish.openDashboard",
+    label: "Deployed",
+    title: url ?? "Everything this project needs to ship is in place.",
+  };
+}
+
+// ─── 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",
+};
+
+const STEP_ICON: Readonly<Record<DeployStepState, string>> = {
+  done: "✓",
+  todo: "·",
+  unknown: "?",
+};
+
+/**
+ * The next action, as a button — 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.
+ */
+function actionTpl(step: DeployStep | null): TemplateResult | typeof nothing {
+  if (!step) {
+    return nothing;
+  }
+  const registry = activeRegistry();
+  const command = registry?.get(step.command);
+  if (!registry || !command || !registry.isVisible(step.command)) {
+    return nothing;
+  }
+  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
+  >`;
+}
+
+/**
+ * The checklist, as the Activity tab draws it — or nothing, 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.
+ */
+export function renderDeployChecklist(): TemplateResult | typeof nothing {
+  if (!projectState) {
+    return nothing;
+  }
+  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>
+  `;
+}

package/src/publish/pages-service.ts

@@ -40,7 +40,16 @@ export interface ConnectOptions {
 
 /** True when the active platform can reach the Cloudflare API. */
 export function platformSupportsPublish(): boolean {
-  return typeof getPlatform().cfApi === "function";
+  // Answers false before a platform is registered rather than throwing. This is read by ambient
+  // Surfaces — the status bar's deploy item, the Activity tab's checklist — which paint during boot
+  // And in tests that register no platform, and neither has any business crashing because
+  // 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";
+  } catch {
+    return false;
+  }
 }
 
 async function cfApi<T>(path: string, init?: { method?: string; body?: unknown }): Promise<T> {

package/src/publish/publish-commands.ts

@@ -0,0 +1,218 @@
+/**
+ * Publish-commands.ts — the `Publish:` family (plan §9.5), defined beside the deploy it drives.
+ *
+ * Two unrelated operations were called "Publish" and neither was a command. `publishToGithub`
+ * created a git repository; `openPublishPanel` connected Cloudflare Pages — and it had **zero call
+ * sites in `src/`**, reachable only through the screenshot runner's seed, so the one flow that
+ * ships a site was, in the shipped app, unreachable. The toolbar's Publish button had already gone
+ * with the toolbar, and nothing replaced it.
+ *
+ * Three records, always reachable, each disabled with the one sentence that says why:
+ *
+ * | id                      | what it does                                              |
+ * | ----------------------- | --------------------------------------------------------- |
+ * | `publish.setUp`         | opens the provider connection flow                        |
+ * | `publish.deploy`        | pushes the branch and asks Cloudflare what it did with it |
+ * | `publish.openDashboard` | opens the connected Pages project on Cloudflare           |
+ *
+ * **`runDeploy` is an Activity, not a toast.** A deploy pushes a branch and then waits on a build
+ * that is happening somewhere else; that is the definition of the long operation §7.3 gave the
+ * Activity tab, and `fail()` raises the Problem so the failure outlives the run and carries a
+ * Retry. The caller therefore never also notifies (§16).
+ *
+ * **No credential is read here.** Whether a provider is reachable is a capability question, and
+ * whether one is connected is a `project.json` question; the token that proves it is read only by
+ * `platforms/devserver.ts` on its way to the same-origin proxy (`studio.md` §15 rule 1).
+ *
+ * **The panel is imported lazily** so this module carries no DOM at import time: `commands/
+ * app-commands.ts` is loaded by three CI checks in a bare Bun process, and a module that opens a
+ * modal at import would break all three.
+ */
+
+import { getPlatform } from "../platform";
+import { beginActivity } from "../panels/activity-panel";
+import { currentDeploy, noteDeployment } from "./deploy-checklist";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { latestDeployment, platformSupportsPublish } from "./pages-service";
+import type { AnyCommand, CommandRegistry } from "../commands/registry";
+
+/**
+ * How long the deploy waits for Cloudflare to admit the push happened.
+ *
+ * Six attempts five seconds apart: a Pages build takes minutes, so this is not "wait for the build"
+ * — it is "wait for the deployment RECORD", which appears within seconds of the push. The activity
+ * says which of the two it is waiting for, because a progress line that implies the former and
+ * delivers the latter is the dishonesty §7.3 exists to end.
+ */
+export const DEPLOY_POLL = { attempts: 6, delayMs: 5000 } as const;
+
+/** Cloudflare's dashboard, for a connected project. */
+export function dashboardUrl(accountId: string, projectName: string): string {
+  return `https://dash.cloudflare.com/${accountId}/pages/view/${projectName}`;
+}
+
+async function sleep(ms: number): Promise<void> {
+  if (ms > 0) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+}
+
+/**
+ * Push the current branch and report what Cloudflare made of it.
+ *
+ * @param options Poll shape, so a test does not wait 30 real seconds.
+ * @returns Whether the push succeeded — NOT whether the build did, which is Cloudflare's to say.
+ */
+export async function runDeploy(
+  options: { attempts?: number; delayMs?: number } = {},
+): Promise<boolean> {
+  const deploy = currentDeploy();
+  let cancelled = false;
+  const activity = beginActivity({
+    cancel: () => {
+      cancelled = true;
+    },
+    source: "Publish",
+    status: "Starting…",
+    steps: ["Push to the remote", "Ask Cloudflare for the deployment"],
+    title: "Deploy",
+  });
+
+  activity.step("Push to the remote");
+  try {
+    await getPlatform().gitPush({ setUpstream: true });
+    activity.log("Pushed the current branch.");
+  } catch (error) {
+    // Logged BEFORE the failure: `fail()` snapshots the log into the Problem's `detail`, so a line
+    // Appended afterwards would be visible in the Activity row and absent from the report of it.
+    activity.log(errorMessage(error));
+    activity.fail("Could not push to the remote.", { action: "git.push" });
+    return false;
+  }
+
+  if (!deploy) {
+    // Reachable when `enablement` was true at click time and the config changed underneath — a
+    // Push is still a real outcome, so this ends as a success that says exactly what it did.
+    activity.done("Pushed. No provider is connected, so nothing was asked to build it.");
+    return true;
+  }
+
+  activity.step("Ask Cloudflare for the deployment");
+  const attempts = options.attempts ?? DEPLOY_POLL.attempts;
+  const delayMs = options.delayMs ?? DEPLOY_POLL.delayMs;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (cancelled) {
+      return false;
+    }
+    let info;
+    try {
+      info = await latestDeployment(deploy);
+    } catch (error) {
+      activity.log(errorMessage(error));
+      activity.fail("Cloudflare did not answer.", { action: "publish.deploy" });
+      return false;
+    }
+    if (info) {
+      noteDeployment(info);
+      activity.log(`${info.stage}: ${info.status} — ${info.url}`);
+      activity.done(`${info.stage}: ${info.status}`);
+      return true;
+    }
+    await sleep(delayMs);
+  }
+  if (cancelled) {
+    return false;
+  }
+  noteDeployment(null);
+  activity.done("Pushed. Cloudflare has not reported a deployment yet.");
+  return true;
+}
+
+/**
+ * The three records.
+ *
+ * `enablement` reads `platformSupportsPublish()` rather than a `capability.*` key because there is
+ * no `publish` capability yet — adding one is a `commands/context.ts` + `commands/live-context.ts`
+ * change, and §5.2 is explicit that PAL differences belong there. Until it exists this is the one
+ * `if (platform.x)` the family carries, in the one place a reader looks for it.
+ */
+export function publishCommands(): AnyCommand[] {
+  return [
+    {
+      category: "Publish",
+      id: "publish.setUp",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "8_publish",
+      /* THE CAPABILITY TERM BELONGS TO THE WHOLE FAMILY, not to its first member. All three of
+         these reach Cloudflare, and only this one asked whether the host can: `currentDeploy()`
+         reads config stored IN THE PROJECT, so a repository cloned or scaffolded with a deploy
+         already configured carries it onto a host whose PAL has no `cfApi`. In that state Set Up
+         Publishing was correctly disabled while Deploy was enabled and ran — pushing the branch,
+         then failing at `latestDeployment` with "Cloudflare did not answer" after the push had
+         already gone out. The refusal that was meant to protect the family guarded one third. */
+      requires: "an open project on a platform that can reach the Cloudflare API",
+      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",
+      },
+      run: async () => {
+        const { openPublishPanel } = await import("./publish-panel");
+        openPublishPanel();
+      },
+      title: "Set Up Publishing",
+    },
+    {
+      category: "Publish",
+      id: "publish.deploy",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "8_publish",
+      requires:
+        "a repository with a remote and a connected deploy provider, on a platform that can " +
+        "reach the Cloudflare API",
+      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",
+      },
+      run: async () => {
+        await runDeploy();
+      },
+      title: "Deploy",
+    },
+    {
+      category: "Publish",
+      id: "publish.openDashboard",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "8_publish",
+      requires: "a connected deploy provider, on a platform that can reach the Cloudflare API",
+      when: (ctx) => ctx.project.open,
+      enablement: () => currentDeploy() !== undefined && platformSupportsPublish(),
+      run: () => {
+        const deploy = currentDeploy();
+        if (deploy) {
+          window.open(dashboardUrl(deploy.accountId, deploy.projectName), "_blank", "noopener");
+        }
+      },
+      title: "Open Deployment Dashboard",
+    },
+  ];
+}
+
+/** Register the `Publish:` family. */
+export function registerPublishCommands(registry: CommandRegistry): void {
+  registry.registerAll(publishCommands());
+}