@jxsuite/studio 2.0.1 → 2.1.0

package/src/panels/git-panel.ts

@@ -7,50 +7,37 @@
 import { html, nothing } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { flushAllCollab } from "../collab/collab-session";
-import type {
-  GitBranchesResult,
-  GitDiffState,
-  GitFileStatus,
-  GitStatusResult,
-  StudioPlatform,
-} from "../types";
+import type { GitDiffState, GitFileStatus, StudioPlatform } from "../types";
 import { live } from "lit-html/directives/live.js";
 import { repeat } from "lit-html/directives/repeat.js";
 import { getPlatform } from "../platform";
+import { now } from "../services/clock";
 import { formatForPath } from "../format/format-host";
-import { projectState, renderOnly, updateUi } from "../store";
+import { projectState } from "../store";
 import { activeTab } from "../workspace/workspace";
-import { view } from "../view";
+import type { Tab } from "../tabs/tab";
+import { shell } from "../shell";
+import type { GitLogEntry } from "../shell";
 import { showConfirmDialog, showPromptDialog } from "../ui/layers";
-import { statusMessage } from "./statusbar";
-import { publishToGithub } from "../github/github-publish";
+import { POLL_GIT } from "../ui/timing";
+import { renderEmptyState } from "./empty-state";
+import { registerPanel } from "./panel-registry";
+import { notify } from "../services/notify";
+import { authenticateGithub } from "../github/github-auth";
+import { createGithubRepository } from "../github/github-publish";
 import { pullWithPackageSync } from "../packages/pull-package-sync";
-
-interface GitLogEntry {
-  hash: string;
-  message: string;
-  author: string;
-  date: string;
-}
+import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 type GitFileEntry = GitFileStatus;
 
-interface GitUiState {
-  gitStatus?: Partial<GitStatusResult> | null;
-  gitBranches?: Partial<GitBranchesResult> | null;
-  gitLoading?: boolean;
-  gitError?: string | null;
-  gitCommitMessage?: string;
-  gitLogEntries?: GitLogEntry[] | null;
-}
-
 export async function refreshGitStatus() {
   if (!projectState) {
     return;
   }
   const plat = getPlatform();
-  updateUi("gitLoading", true);
-  updateUi("gitError", null);
+  const { git } = shell;
+  git.loading = true;
+  git.error = null;
   try {
     // Settled independently, not Promise.all: outside a work tree `git branch` exits non-zero
     // While `git status` answers cleanly with isRepo:false. Letting the branch lookup reject the
@@ -58,10 +45,10 @@ export async function refreshGitStatus() {
     // Again, and span — a request per render for as long as the tab stayed open.
     const [status, branches] = await Promise.allSettled([plat.gitStatus(), plat.gitBranches()]);
     if (status.status === "fulfilled") {
-      updateUi("gitStatus", status.value);
+      git.status = status.value;
     }
     if (branches.status === "fulfilled") {
-      updateUi("gitBranches", branches.value);
+      git.branches = branches.value;
     }
     // A branch lookup that fails on a repo-less project is expected, not an error worth showing;
     // Anything else (including a failed status) surfaces.
@@ -72,14 +59,13 @@ export async function refreshGitStatus() {
           ? branches.reason
           : null;
     if (failure) {
-      updateUi("gitError", errorMessage(failure));
+      git.error = errorMessage(failure);
     }
-    _lastUpdated = new Date();
+    git.lastUpdated = now();
   } catch (error) {
-    updateUi("gitError", errorMessage(error));
+    git.error = errorMessage(error);
   } finally {
-    updateUi("gitLoading", false);
-    renderOnly("leftPanel");
+    git.loading = false;
   }
 }
 
@@ -91,7 +77,7 @@ export async function refreshGitStatus() {
 export async function cloneRepository(ctx: { openRecentProject: (root: string) => Promise<void> }) {
   const platform = getPlatform();
   if (!platform.gitClone) {
-    statusMessage("Clone not supported on this platform");
+    notify.warn("Cloning is not supported on this platform.", { source: "Source Control" });
     return;
   }
 
@@ -107,14 +93,18 @@ export async function cloneRepository(ctx: { openRecentProject: (root: string) =
   }
 
   try {
-    statusMessage("Cloning repository...");
+    notify.info("Cloning repository…", { key: "git.clone", source: "Source Control" });
     const result = await platform.gitClone(url);
     if (result?.root) {
-      statusMessage("Clone complete");
+      notify.success("Clone complete.", { key: "git.clone" });
       await ctx.openRecentProject(result.root);
     }
   } catch (error) {
-    statusMessage(`Clone failed: ${errorMessage(error)}`);
+    notify.error("Could not clone the repository.", {
+      detail: errorMessage(error),
+      key: "git.clone",
+      source: "Source Control",
+    });
   }
 }
 
@@ -123,6 +113,100 @@ export function platformSupportsClone() {
   return Boolean(getPlatform().gitClone);
 }
 
+/**
+ * One file's comparison against HEAD: the committed text and the working copy.
+ *
+ * **One definition site, because there are now two callers.** This panel's row click has always
+ * made this pair of reads; `workspace/pane-derive.ts`'s Diff lens needs the same answer for the
+ * document its source pane is showing, and it must not reach `shell.git.diffState` — that slot
+ * holds whatever THIS panel last opened, which is a different file (§18.4, finding 4). A second
+ * copy of these five lines is how the panel and the lens would come to disagree about what "the
+ * diff of this file" means, which is the rule {@link initRepository} is written under too.
+ *
+ * `A` (added) has no `HEAD` copy, so its original is the empty string rather than a `gitShow` that
+ * would throw. Callers narrow to `M`/`A` before asking.
+ *
+ * @param {string} path
+ * @param {string} fileStatus
+ * @returns {Promise<GitDiffState>}
+ */
+export async function readGitDiff(path: string, fileStatus: string): Promise<GitDiffState> {
+  const plat = getPlatform();
+  const [originalContent, currentContent] = await Promise.all([
+    fileStatus === "A" ? Promise.resolve("") : plat.gitShow({ path, ref: "HEAD" }),
+    plat.readFile(path),
+  ]);
+  return { currentContent, filePath: path, fileStatus, originalContent };
+}
+
+/**
+ * The Diff lens's reader: {@link readGitDiff}, with a failure the PANE can state.
+ *
+ * A rejection here is not an error the shell should raise — the author asked to see a comparison
+ * beside their page, and "could not read it" is a sentence the derived pane draws in its own empty
+ * state. `applyDerivation` turns the `null` into exactly that.
+ *
+ * @param {string} path
+ * @param {string} fileStatus
+ * @returns {Promise<GitDiffState | null>}
+ */
+export async function loadDiffForLens(
+  path: string,
+  fileStatus: string,
+): Promise<GitDiffState | null> {
+  try {
+    return await readGitDiff(path, fileStatus);
+  } catch (error) {
+    // Reported where it can be acted on — the pane says so — rather than as a toast over a
+    // Document the author did not ask about.
+    console.warn("loadDiffForLens:", errorMessage(error));
+    return null;
+  }
+}
+
+/**
+ * Start tracking this project with git.
+ *
+ * A function rather than an inline click handler because it is now also a command ({@link
+ * sourceControlCommands}) and the first step of the deploy checklist, and three call sites of the
+ * same three lines is how the panel and the palette come to disagree about what a verb does.
+ */
+export async function initRepository(): Promise<void> {
+  try {
+    notify.info("Initializing repository…", { key: "git.init" });
+    await getPlatform().gitInit();
+    notify.success("Repository initialized.", { key: "git.init" });
+  } catch (error) {
+    notify.error("Could not initialize the repository.", {
+      action: "git.init",
+      detail: errorMessage(error),
+      key: "git.init",
+      source: "Source Control",
+    });
+    return;
+  }
+  await refreshGitStatus();
+}
+
+/** Push the current branch. Same loading/error contract as every other panel verb. */
+export async function pushCurrentBranch(): Promise<void> {
+  await gitAction("gitPush");
+}
+
+/**
+ * Sign in to GitHub, or report why it could not.
+ *
+ * The report belongs to `github/github-auth.ts` — this only says what a SUCCESS was, which that
+ * module cannot, because it is also called mid-flow by "Create GitHub Repository" where a toast
+ * saying "Signed in" in front of a half-finished operation would be noise.
+ */
+export async function signInToGithub(): Promise<void> {
+  const token = await authenticateGithub();
+  if (token) {
+    notify.success("Signed in to GitHub.", { key: "github.auth" });
+  }
+}
+
 /**
  * @param {string} action
  * @param {unknown} [body]
@@ -130,87 +214,87 @@ export function platformSupportsClone() {
 async function gitAction(action: string, body?: unknown) {
   const plat = getPlatform() as Record<string, (...args: unknown[]) => Promise<unknown>> &
     StudioPlatform;
-  updateUi("gitLoading", true);
-  updateUi("gitError", null);
+  shell.git.loading = true;
+  shell.git.error = null;
   try {
     await plat[action]!(body);
     await refreshGitStatus();
   } catch (error) {
-    updateUi("gitError", errorMessage(error));
-    updateUi("gitLoading", false);
-    renderOnly("leftPanel");
+    shell.git.error = errorMessage(error);
+    shell.git.loading = false;
   }
 }
 
 /** Pull via the package-aware orchestrator; same loading/error contract as gitAction. */
 async function doPull() {
-  updateUi("gitLoading", true);
-  updateUi("gitError", null);
+  shell.git.loading = true;
+  shell.git.error = null;
   try {
     await pullWithPackageSync();
     await refreshGitStatus();
   } catch (error) {
-    updateUi("gitError", errorMessage(error));
-    updateUi("gitLoading", false);
-    renderOnly("leftPanel");
+    shell.git.error = errorMessage(error);
+    shell.git.loading = false;
   }
 }
 
+/**
+ * The background refresh handle. The interval itself is infrastructure, not state — the sub-tab and
+ * the "last updated" stamp it used to sit beside are on `shell.git`, so opening a second project no
+ * longer inherits the first one's History selection and timestamp.
+ */
 let _pollTimer = null as ReturnType<typeof setInterval> | null;
-let _lastUpdated = null as Date | null;
-let _gitSubTab = "changes";
 
 async function fetchGitLog() {
   const plat = getPlatform();
   try {
-    const entries = await plat.gitLog(30);
-    updateUi("gitLogEntries", entries);
-    renderOnly("leftPanel");
+    shell.git.logEntries = await plat.gitLog(30);
   } catch (error) {
-    updateUi("gitError", errorMessage(error));
-    renderOnly("leftPanel");
+    shell.git.error = errorMessage(error);
   }
 }
 
 /**
- * @param {{ ui: GitUiState }} S
+ * Render the Source Control panel.
+ *
+ * Takes no state argument: everything it reads is project-level and lives on `shell.git`, which is
+ * the whole point of the hoist — the panel renders identically with no document open.
+ *
  * @param {{
- *   setCanvasMode?: (mode: string) => void;
+ *   setCanvasMode?: (tab: Tab | null, mode: string) => void;
  *   setGitDiffState?: (state: GitDiffState | null) => void;
  *   cloneRepository?: () => void;
  * }} ctx
  */
-export function renderGitPanel(
-  S: { ui: GitUiState },
-  ctx: {
-    setCanvasMode?: (mode: string) => void;
-    setGitDiffState?: (state: GitDiffState | null) => void;
-    cloneRepository?: () => void;
-  },
-) {
+export function renderGitPanel(ctx: {
+  setCanvasMode?: (tab: Tab | null, mode: string) => void;
+  setGitDiffState?: (state: GitDiffState | null) => void;
+  cloneRepository?: () => void;
+}) {
   if (!projectState) {
     return html`<div class="git-panel git-panel-empty">
-      <div class="git-empty-state">
-        <p>Open a project to use source control.</p>
-        ${
-          platformSupportsClone()
-            ? html`<sp-action-button size="m" @click=${() => ctx.cloneRepository?.()}>
-                <sp-icon-download slot="icon"></sp-icon-download>
-                Clone Git Repository
-              </sp-action-button>`
-            : nothing
-        }
-      </div>
+      ${renderEmptyState({
+        actions: platformSupportsClone()
+          ? [
+              {
+                icon: html`<sp-icon-download slot="icon"></sp-icon-download>`,
+                label: "Clone Git Repository",
+                run: () => ctx.cloneRepository?.(),
+              },
+            ]
+          : [],
+        message:
+          "Source control keeps every version of a project, so any change can be undone. " +
+          "Open a project to see its history.",
+      })}
     </div>`;
   }
-  const status = S.ui.gitStatus;
-  const branches = S.ui.gitBranches;
-  const loading = S.ui.gitLoading;
+  const { branches, loading, status } = shell.git;
 
   // First paint kicks off the fetch. A refresh that already failed must NOT re-arm it here, or the
   // Render it triggers becomes the next render's reason to fetch again; the Refresh button and the
   // Poll timer are the ways back.
-  if (!status && !loading && !S.ui.gitError) {
+  if (!status && !loading && !shell.git.error) {
     void refreshGitStatus();
     return html`<div class="git-panel">
       <div class="git-loading">Loading...</div>
@@ -219,42 +303,38 @@ export function renderGitPanel(
 
   if (status && !status.isRepo) {
     return html`<div class="git-panel git-panel-empty">
-      <div class="git-empty-state">
-        <p>This project is not yet a git repository.</p>
-        <sp-action-button
-          size="m"
-          @click=${async () => {
-            statusMessage("Initializing repository…");
-            await getPlatform().gitInit();
-            statusMessage("Repository initialized");
-            await refreshGitStatus();
-          }}
-          ?disabled=${loading}
-        >
-          <sp-icon-add slot="icon"></sp-icon-add>
-          Initialize Repository
-        </sp-action-button>
-        <sp-action-button
-          size="m"
-          @click=${() =>
-            publishToGithub({
-              projectName: projectState?.name || "my-project",
-            })}
-          ?disabled=${loading}
-        >
-          <sp-icon-share slot="icon"></sp-icon-share>
-          Publish to GitHub
-        </sp-action-button>
-      </div>
+      ${renderEmptyState({
+        actions: [
+          {
+            disabled: Boolean(loading),
+            icon: html`<sp-icon-add slot="icon"></sp-icon-add>`,
+            label: "Initialize Repository",
+            run: () => {
+              void initRepository();
+            },
+          },
+          {
+            disabled: Boolean(loading),
+            icon: html`<sp-icon-share slot="icon"></sp-icon-share>`,
+            label: "Create GitHub repository",
+            run: () => {
+              void createGithubRepository({ projectName: projectState?.name || "my-project" });
+            },
+          },
+        ],
+        message:
+          "This project is not tracked by git yet. Start tracking it to keep a history " +
+          "of every change and to publish it anywhere.",
+      })}
     </div>`;
   }
 
   if (!_pollTimer) {
     _pollTimer = setInterval(() => {
-      if (view.leftTab === "git" && !S.ui.gitLoading) {
+      if (shell.leftTab === "git" && !shell.git.loading) {
         void refreshGitStatus();
       }
-    }, 30_000);
+    }, POLL_GIT);
   }
 
   const stagedFiles = status?.files?.filter((f: GitFileEntry) => f.staged) || [];
@@ -262,12 +342,11 @@ export function renderGitPanel(
   const totalChanges = status?.files?.length || 0;
 
   const doCommit = async () => {
-    const tab = activeTab.value;
-    const msg = tab?.session.ui.gitCommitMessage?.trim();
+    const msg = shell.git.commitMessage.trim();
     if (!msg) {
       return;
     }
-    updateUi("gitCommitMessage", "");
+    shell.git.commitMessage = "";
     // Fold co-editing sessions into the backend's tree first so the commit never misses
     // Trailing keystrokes (the mirror is debounced).
     await flushAllCollab();
@@ -275,14 +354,13 @@ export function renderGitPanel(
   };
 
   const doCommitAndSync = async () => {
-    const tab = activeTab.value;
-    const msg = tab?.session.ui.gitCommitMessage?.trim();
+    const msg = shell.git.commitMessage.trim();
     if (!msg) {
       return;
     }
-    updateUi("gitCommitMessage", "");
-    updateUi("gitLoading", true);
-    updateUi("gitError", null);
+    shell.git.commitMessage = "";
+    shell.git.loading = true;
+    shell.git.error = null;
     await flushAllCollab();
     const plat = getPlatform();
     try {
@@ -290,9 +368,8 @@ export function renderGitPanel(
       await plat.gitPush();
       await refreshGitStatus();
     } catch (error) {
-      updateUi("gitError", errorMessage(error));
-      updateUi("gitLoading", false);
-      renderOnly("leftPanel");
+      shell.git.error = errorMessage(error);
+      shell.git.loading = false;
     }
   };
 
@@ -301,8 +378,8 @@ export function renderGitPanel(
   const syncLabel = isUpToDate
     ? "Up to date"
     : `${status?.ahead ? `${status.ahead} ahead` : ""}${status?.ahead && status?.behind ? ", " : ""}${status?.behind ? `${status.behind} behind` : ""}`;
-  const lastUpdatedStr = _lastUpdated
-    ? _lastUpdated.toLocaleTimeString([], {
+  const lastUpdatedStr = shell.git.lastUpdated
+    ? new Date(shell.git.lastUpdated).toLocaleTimeString([], {
         hour: "2-digit",
         minute: "2-digit",
       })
@@ -341,7 +418,9 @@ export function renderGitPanel(
             </sp-action-button>
             <sp-action-button
               title="Pull${status?.behind ? ` (${status.behind} behind)` : ""}"
-              @click=${() => void doPull()}
+              @click=${() => {
+                void doPull();
+              }}
               ?disabled=${loading}
             >
               <sp-icon-arrow-down slot="icon" size="xs"></sp-icon-arrow-down>
@@ -374,13 +453,13 @@ export function renderGitPanel(
           <sp-action-button
             size="s"
             @click=${() =>
-              publishToGithub({
+              createGithubRepository({
                 projectName: projectState?.name || "my-project",
               })}
             ?disabled=${loading}
           >
             <sp-icon-share slot="icon"></sp-icon-share>
-            Publish to GitHub
+            Create GitHub repository
           </sp-action-button>
         </div>
       `;
@@ -445,23 +524,22 @@ export function renderGitPanel(
 
   // ─── 3. Tabs: Local Changes / History ────────────────────────────────────
   const switchTab = (tab: string) => {
-    _gitSubTab = tab;
-    if (tab === "history" && !S.ui.gitLogEntries) {
+    shell.git.subTab = tab;
+    if (tab === "history" && !shell.git.logEntries) {
       void fetchGitLog();
     }
-    renderOnly("leftPanel");
   };
 
   const tabsT = html`
     <div class="git-tabs">
       <button
-        class="git-tab ${_gitSubTab === "changes" ? "active" : ""}"
+        class="git-tab ${shell.git.subTab === "changes" ? "active" : ""}"
         @click=${() => switchTab("changes")}
       >
         Local Changes${totalChanges > 0 ? ` (${totalChanges})` : ""}
       </button>
       <button
-        class="git-tab ${_gitSubTab === "history" ? "active" : ""}"
+        class="git-tab ${shell.git.subTab === "history" ? "active" : ""}"
         @click=${() => switchTab("history")}
       >
         History
@@ -470,16 +548,21 @@ export function renderGitPanel(
   `;
 
   // ─── 4. Commit form ──────────────────────────────────────────────────────
+  // `navigator/panel:git/commit` is a HAND-STAMPED leaf: the panel host derives
+  // `navigator/panel:git`, but nothing derives the parts inside a panel body. Leaves are the one
+  // Category of region id that is authored, and they are counted for exactly that reason.
   const commitT = html`
-    <div class="git-commit-area">
+    <div class="git-commit-area" data-jx-region="navigator/panel:git/commit">
       <label class="git-commit-label">Please write a commit message</label>
       <sp-textfield
         size="s"
         multiline
         class="git-commit-input"
         placeholder="Describe your changes"
-        .value=${live(S.ui.gitCommitMessage || "")}
-        @input=${(e: Event) => updateUi("gitCommitMessage", (e.target as HTMLInputElement).value)}
+        .value=${live(shell.git.commitMessage)}
+        @input=${(e: Event) => {
+          shell.git.commitMessage = (e.target as HTMLInputElement).value;
+        }}
         @keydown=${(e: KeyboardEvent) => {
           if ((e.ctrlKey || e.metaKey) && e.key === "Enter") {
             e.preventDefault();
@@ -545,35 +628,22 @@ export function renderGitPanel(
       }
 
       try {
-        const plat = getPlatform();
-        updateUi("gitLoading", true);
+        shell.git.loading = true;
 
-        const [originalContent, currentContent] = await Promise.all([
-          file.status === "A"
-            ? Promise.resolve("")
-            : plat.gitShow({ path: file.path, ref: "HEAD" }),
-          plat.readFile(file.path),
-        ]);
+        const diffState = await readGitDiff(file.path, file.status);
 
-        const diffState = {
-          currentContent,
-          filePath: file.path,
-          fileStatus: file.status,
-          originalContent,
-        };
-
-        updateUi("gitDiffState", diffState);
+        shell.git.diffState = diffState;
 
         if (ctx?.setCanvasMode) {
           if (ctx.setGitDiffState) {
             ctx.setGitDiffState(diffState);
           }
-          ctx.setCanvasMode("git-diff");
+          ctx.setCanvasMode(activeTab.value, "git-diff");
         }
       } catch (error) {
-        updateUi("gitError", `Failed to load diff: ${errorMessage(error)}`);
+        shell.git.error = `Failed to load diff: ${errorMessage(error)}`;
       } finally {
-        updateUi("gitLoading", false);
+        shell.git.loading = false;
       }
     };
 
@@ -733,18 +803,24 @@ export function renderGitPanel(
                 `,
               )}
             `
-          : html`<div class="git-empty">No changes</div>`
+          : renderEmptyState({
+              compact: true,
+              message: "Nothing to commit. Files you edit and save show up here.",
+            })
       }
     </div>
   `;
 
   // ─── 6. History tab content ──────────────────────────────────────────────
-  const logEntries = S.ui.gitLogEntries || [];
+  const logEntries = shell.git.logEntries || [];
   const historyT = html`
     <div class="git-history">
       ${
         logEntries.length === 0
-          ? html`<div class="git-empty">No history</div>`
+          ? renderEmptyState({
+              compact: true,
+              message: "No commits yet. Each commit you make is a version you can come back to.",
+            })
           : repeat(
               logEntries,
               (e: GitLogEntry) => e.hash,
@@ -753,7 +829,7 @@ export function renderGitPanel(
                   <span class="git-history-hash">${entry.hash.slice(0, 7)}</span>
                   <span class="git-history-message">${entry.message}</span>
                   <span class="git-history-meta"
-                    >${entry.author} · ${_relativeDate(entry.date)}</span
+                    >${entry.author} · ${relativeDate(entry.date)}</span
                   >
                 </div>
               `,
@@ -765,18 +841,25 @@ export function renderGitPanel(
   return html`
     <div class="git-panel">
       ${syncBarT} ${branchSelectorT} ${tabsT}
-      ${_gitSubTab === "changes" ? html`${commitT}${changesT}` : historyT}
+      ${shell.git.subTab === "changes" ? html`${commitT}${changesT}` : historyT}
       ${loading ? html`<div class="git-loading">Loading...</div>` : nothing}
-      ${S.ui.gitError ? html`<div class="git-error">${S.ui.gitError}</div>` : nothing}
+      ${shell.git.error ? html`<div class="git-error">${shell.git.error}</div>` : nothing}
     </div>
   `;
 }
 
-/** @param {string} iso */
-function _relativeDate(iso: string) {
+/**
+ * A commit age, relative to {@link now}.
+ *
+ * Exported so it is testable at all: reading the wall clock inline meant "yesterday" and the
+ * locale-date fallback could only be asserted against an offset from the real present, and two
+ * captures minutes apart legitimately disagreed.
+ *
+ * @param {string} iso
+ */
+export function relativeDate(iso: string) {
   const d = new Date(iso);
-  const now = Date.now();
-  const diff = now - d.getTime();
+  const diff = now() - d.getTime();
   const mins = Math.floor(diff / 60_000);
   if (mins < 1) {
     return "just now";
@@ -795,9 +878,137 @@ function _relativeDate(iso: string) {
   return d.toLocaleDateString();
 }
 
+/**
+ * The `Source Control:` family — the four verbs that were only ever buttons.
+ *
+ * Every one of them was reachable from exactly one place: two from an empty state that disappears
+ * the moment the repository exists, one from a 20px icon with a `title` attribute, and the fourth —
+ * signing in to GitHub — from nowhere at all, because it only ever happened as a side effect of
+ * something else. That is why a failed sign-in had no Retry to name: there was no record to point
+ * at. Naming them here gives the palette, `__jxAutomation`, the assistant, the deploy checklist and
+ * every `notify` Retry the same four ids.
+ *
+ * `git.signInToGithub` is `application`-level and the other three are `project`-level, and the
+ * split is the credential's: a GitHub token is one per machine and is revoked in Preferences ›
+ * Accounts, while a branch, a remote and a push belong to one repository.
+ */
+export function sourceControlCommands(): AnyCommand[] {
+  return [
+    {
+      category: "Source Control",
+      id: "git.init",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "7_scm",
+      requires: "an open project that git is not already tracking",
+      when: (ctx) => ctx.project.open,
+      // `when` already asked about the project; an `enablement` that re-asks is the same rule
+      // Written twice, and the two places drift.
+      enablement: (ctx) => !ctx.project.isRepo,
+      aiTool: {
+        description:
+          "Run git init in the project root so the project has a history and can be pushed.",
+        name: "init_repository",
+      },
+      run: async () => {
+        await initRepository();
+      },
+      title: "Initialize Repository",
+    },
+    {
+      category: "Source Control",
+      id: "git.createGithubRepository",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "7_scm",
+      /* THE STRICTEST OF THE THREE, because it is the one that leaves something behind on a
+         server. It declared no `enablement` at all while `git.push` — which does strictly less —
+         required a tracked repository, so on an untracked project Push was correctly disabled and
+         this was fully live from the palette, the overflow, the deploy checklist and the
+         `create_github_repository` AI tool. Its flow creates the repository on GitHub BEFORE it
+         touches the local one, so `gitAddRemote` then throws and it reports "The repository was
+         created, but the remote could not be added." The refused verb leaves nothing behind; the
+         unrefused one leaves an empty repository on the user's account. */
+      requires: "a project tracked by git",
+      when: (ctx) => ctx.project.open,
+      enablement: (ctx) => ctx.project.isRepo,
+      aiTool: {
+        description:
+          "Create a new GitHub repository for this project, add it as the origin remote, and push. " +
+          "This creates a repository; it does not deploy a site — that is publish.setUp.",
+        name: "create_github_repository",
+      },
+      run: async () => {
+        await createGithubRepository({ projectName: projectState?.name || "my-project" });
+      },
+      title: "Create GitHub Repository",
+    },
+    {
+      category: "Source Control",
+      id: "git.push",
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      group: "7_scm",
+      requires: "a project tracked by git",
+      when: (ctx) => ctx.project.open,
+      enablement: (ctx) => ctx.project.isRepo,
+      aiTool: {
+        description: "Push the current branch to its remote.",
+        name: "git_push",
+      },
+      run: async () => {
+        await pushCurrentBranch();
+      },
+      title: "Push",
+    },
+    {
+      category: "Source Control",
+      id: "git.signInToGithub",
+      level: "application",
+      menus: ["palette"],
+      group: "7_scm",
+      run: async () => {
+        await signInToGithub();
+      },
+      title: "Sign In to GitHub",
+    },
+  ];
+}
+
+/** Register the `Source Control:` family. */
+export function registerSourceControlCommands(registry: CommandRegistry): void {
+  registry.registerAll(sourceControlCommands());
+}
+
+/** Stop the background refresh. Called on unmount and whenever a different project is opened. */
 export function cleanupGitPanel() {
   if (_pollTimer) {
     clearInterval(_pollTimer);
     _pollTimer = null;
   }
 }
+
+/**
+ * Contribute the Source Control panel.
+ *
+ * `level: "project"` — a branch, a working tree and a commit belong to the repository, not to
+ * whichever document happens to be focused. That is why the badge below reads `ctx.git.dirtyCount`
+ * (sourced from the hoisted `shell.git` record) and why this panel's render ignores `ctx.doc`
+ * entirely: the count used to come from `activeTab.session.ui.gitStatus`, so it vanished when the
+ * last tab closed and two tabs could disagree about the branch.
+ */
+export function registerGitPanel(): void {
+  registerPanel({
+    id: "git",
+    title: "Source Control",
+    level: "project",
+    dock: "navigator",
+    // A KEY into `activity-bar.ts`'s `tabIcon()` map, not a tag: this one resolves to
+    // `gitBranchIcon`, a hand-drawn inline SVG, because the workflow set has no Git family.
+    icon: "sp-icon-git-branch",
+    badge: (ctx) => ctx.git.dirtyCount || null,
+    // Through `deps`, not the local binding: `studio.ts` owns the wiring (the clone action and the
+    // Diff-state setter come from the bootstrap), and the Navigator has injected it all along.
+    render: (ctx) => ctx.deps.renderGitPanel(ctx.deps),
+  });
+}