xtralab 0.1.0

package/src/git/panel.tsx

@@ -0,0 +1,56 @@
+import * as React from 'react';
+
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { Signal, ISignal } from '@lumino/signaling';
+
+import { gitIcon } from './icons';
+import { GitPanelComponent, IGitPanelHandlers } from './panelComponent';
+
+/**
+ * The id and CSS class used for the git panel widget. The id ends up as the
+ * sidebar tab id (so layout restoration can find the widget) and the CSS
+ * class lets per-panel styles attach without leaking to other widgets.
+ */
+export const GIT_PANEL_ID = 'xtralab:git-panel';
+export const GIT_PANEL_CSS_CLASS = 'jp-xtralab-GitPanel';
+
+/**
+ * The lumino host widget for the git changes panel. Owns the `refresh`
+ * signal that the React component listens to, and exposes a typed callback
+ * surface (`handlers`) the React component uses to react to user actions.
+ */
+export class GitPanel extends ReactWidget {
+  constructor(handlers: IGitPanelHandlers) {
+    super();
+    this.id = GIT_PANEL_ID;
+    this.title.icon = gitIcon;
+    this.title.caption = 'Git Changes';
+    this.addClass(GIT_PANEL_CSS_CLASS);
+    this._handlers = handlers;
+  }
+
+  /**
+   * Public refresh hook called by the plugin when something happened that
+   * invalidates the current view (the user clicked the toolbar refresh, the
+   * file browser refreshed, a focused notebook saved, …).
+   */
+  refresh(): void {
+    this._refreshRequested.emit();
+  }
+
+  get refreshRequested(): ISignal<this, void> {
+    return this._refreshRequested;
+  }
+
+  protected render(): React.ReactElement {
+    return (
+      <GitPanelComponent
+        handlers={this._handlers}
+        refreshSignal={this._refreshRequested}
+      />
+    );
+  }
+
+  private _handlers: IGitPanelHandlers;
+  private _refreshRequested = new Signal<this, void>(this);
+}

package/src/git/panelComponent.tsx

@@ -0,0 +1,558 @@
+import * as React from 'react';
+
+import { ISignal } from '@lumino/signaling';
+
+import {
+  add,
+  addAll,
+  checkout,
+  porcelainToFileChanges,
+  reset,
+  resetAll,
+  showTopLevel,
+  status
+} from './api';
+import { FileChangeStatus, IFileChange, IGitStatusResult } from './tokens';
+
+/**
+ * Callbacks the panel needs to delegate to (so the React component stays
+ * free of any JupyterLab application coupling). The plugin wires these up
+ * with the actual `JupyterFrontEnd` reference.
+ */
+export interface IGitPanelHandlers {
+  /** Open a diff viewer for the given file in the main area. */
+  openDiff(change: IFileChange): void;
+  /** Show a confirmation dialog. Returns true when the user accepted. */
+  confirm(title: string, body: string, accept: string): Promise<boolean>;
+  /** Show an error dialog. */
+  showError(title: string, error: Error): Promise<void>;
+}
+
+interface IPanelState {
+  /** True while the initial status request is in flight. */
+  loading: boolean;
+  /** The raw result of the last status call, or `null` if it hasn't completed yet. */
+  result: IGitStatusResult | null;
+  /** Set when the status request errored or the path is not in a repo. */
+  error: string | null;
+}
+
+/**
+ * The polling interval for the panel. We refresh the status periodically so
+ * out-of-band changes (e.g. the user runs `git add` from a terminal) become
+ * visible without requiring a manual refresh.
+ */
+const STATUS_POLL_INTERVAL_MS = 5000;
+
+/**
+ * Top-level React component rendered inside the {@link GitPanel} widget.
+ * Owns the polling + refresh wiring around the `/git/status` endpoint and
+ * the small bit of UI state that controls section collapse and the
+ * in-flight per-file action spinners.
+ */
+export function GitPanelComponent(props: {
+  handlers: IGitPanelHandlers;
+  refreshSignal: ISignal<unknown, void>;
+}): React.ReactElement {
+  const { handlers, refreshSignal } = props;
+
+  const [state, setState] = React.useState<IPanelState>({
+    loading: true,
+    result: null,
+    error: null
+  });
+  // The absolute filesystem path of the resolved git top-level. Used purely
+  // for display in the panel header.
+  const [topLevel, setTopLevel] = React.useState<string | null>(null);
+  // Per-action spinner gating: keyed by `${group}:${path}`, value is the
+  // action currently in flight. Lets the row render a disabled state on
+  // exactly the file that is being mutated, without locking the whole panel.
+  const [pendingActions, setPendingActions] = React.useState<
+    Record<string, string>
+  >({});
+  const [stagedCollapsed, setStagedCollapsed] = React.useState(false);
+  const [changesCollapsed, setChangesCollapsed] = React.useState(false);
+
+  // The repo path passed to every API call. We use the JupyterLab server's
+  // root (the empty string) and let `git` resolve the enclosing repo on the
+  // server side. This works as long as the server was started inside a git
+  // repo — the common case.
+  const repoPath = '';
+
+  const refresh = React.useCallback(async (): Promise<void> => {
+    try {
+      const [topLevelResult, statusResult] = await Promise.all([
+        showTopLevel(repoPath),
+        status(repoPath)
+      ]);
+      setTopLevel(topLevelResult);
+      if (statusResult.code !== 0) {
+        setState({
+          loading: false,
+          result: null,
+          error: statusResult.message ?? 'Failed to load git status'
+        });
+        return;
+      }
+      setState({ loading: false, result: statusResult, error: null });
+    } catch (err) {
+      setState({
+        loading: false,
+        result: null,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }, [repoPath]);
+
+  // Initial load + polling. `refresh` is stable for a given `repoPath`, so
+  // the polling interval is only re-created when the repo path changes.
+  React.useEffect(() => {
+    void refresh();
+    const interval = window.setInterval(
+      () => void refresh(),
+      STATUS_POLL_INTERVAL_MS
+    );
+    return () => {
+      window.clearInterval(interval);
+    };
+  }, [refresh]);
+
+  // External refresh triggers (toolbar button, plugin-level events).
+  React.useEffect(() => {
+    const handler = (): void => {
+      void refresh();
+    };
+    refreshSignal.connect(handler);
+    return () => {
+      refreshSignal.disconnect(handler);
+    };
+  }, [refresh, refreshSignal]);
+
+  const runAction = React.useCallback(
+    async (
+      change: IFileChange,
+      action: string,
+      run: () => Promise<void>
+    ): Promise<void> => {
+      const key = `${change.group}:${change.path}`;
+      setPendingActions(prev => ({ ...prev, [key]: action }));
+      try {
+        await run();
+        await refresh();
+      } catch (err) {
+        await handlers.showError(
+          'Git operation failed',
+          err instanceof Error ? err : new Error(String(err))
+        );
+      } finally {
+        setPendingActions(prev => {
+          const next = { ...prev };
+          delete next[key];
+          return next;
+        });
+      }
+    },
+    [handlers, refresh]
+  );
+
+  const onStage = React.useCallback(
+    (change: IFileChange) =>
+      runAction(change, 'stage', () => add(repoPath, change.path)),
+    [repoPath, runAction]
+  );
+
+  const onUnstage = React.useCallback(
+    (change: IFileChange) =>
+      runAction(change, 'unstage', () => reset(repoPath, change.path)),
+    [repoPath, runAction]
+  );
+
+  const onDiscard = React.useCallback(
+    async (change: IFileChange): Promise<void> => {
+      const verb = change.status === 'untracked' ? 'remove' : 'restore';
+      const accepted = await handlers.confirm(
+        verb === 'remove' ? 'Remove file' : 'Discard changes',
+        verb === 'remove'
+          ? `Permanently remove ${change.path}? This cannot be undone.`
+          : `Discard all changes to ${change.path}? This will revert the file to its last staged version and cannot be undone.`,
+        verb === 'remove' ? 'Remove' : 'Discard'
+      );
+      if (!accepted) {
+        return;
+      }
+      // The git extension's `checkout` endpoint without a branch reverts the
+      // working tree copy of the file to the index. For untracked files we
+      // can't checkout, so the user is told the action is unsupported and we
+      // bail out — they can delete the file via the file browser instead.
+      if (change.status === 'untracked') {
+        await handlers.showError(
+          'Cannot discard untracked file',
+          new Error(
+            'Untracked files cannot be discarded from the git panel — delete them from the file browser instead.'
+          )
+        );
+        return;
+      }
+      await runAction(change, 'discard', () => checkout(repoPath, change.path));
+    },
+    [handlers, repoPath, runAction]
+  );
+
+  const onStageAll = React.useCallback(async (): Promise<void> => {
+    try {
+      await addAll(repoPath);
+      await refresh();
+    } catch (err) {
+      await handlers.showError(
+        'Stage all failed',
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+  }, [handlers, refresh, repoPath]);
+
+  const onUnstageAll = React.useCallback(async (): Promise<void> => {
+    try {
+      await resetAll(repoPath);
+      await refresh();
+    } catch (err) {
+      await handlers.showError(
+        'Unstage all failed',
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+  }, [handlers, refresh, repoPath]);
+
+  // Categorize the porcelain entries into the two visible groups. Because
+  // `porcelainToFileChanges` may emit two changes per file (one staged, one
+  // unstaged), the same file can show up in both lists when it has been
+  // partially staged.
+  const { staged, unstaged } = React.useMemo(() => {
+    const stagedAcc: IFileChange[] = [];
+    const unstagedAcc: IFileChange[] = [];
+    if (state.result === null) {
+      return { staged: stagedAcc, unstaged: unstagedAcc };
+    }
+    for (const file of state.result.files) {
+      for (const change of porcelainToFileChanges(file)) {
+        if (change.group === 'staged') {
+          stagedAcc.push(change);
+        } else {
+          unstagedAcc.push(change);
+        }
+      }
+    }
+    stagedAcc.sort((a, b) => a.path.localeCompare(b.path));
+    unstagedAcc.sort((a, b) => a.path.localeCompare(b.path));
+    return { staged: stagedAcc, unstaged: unstagedAcc };
+  }, [state.result]);
+
+  return (
+    <div className="jp-xtralab-GitPanel-content">
+      <PanelHeader
+        topLevel={topLevel}
+        result={state.result}
+        loading={state.loading}
+        error={state.error}
+        onRefresh={() => void refresh()}
+      />
+      {state.error !== null ? (
+        <div className="jp-xtralab-GitPanel-error">{state.error}</div>
+      ) : (
+        <>
+          <ChangeSection
+            label="Staged Changes"
+            count={staged.length}
+            collapsed={stagedCollapsed}
+            onToggleCollapsed={() => setStagedCollapsed(c => !c)}
+            actions={
+              staged.length > 0
+                ? [
+                    {
+                      label: 'Unstage all changes',
+                      symbol: '−',
+                      onClick: onUnstageAll
+                    }
+                  ]
+                : undefined
+            }
+          >
+            {staged.map(change => (
+              <ChangeRow
+                key={`${change.group}:${change.path}`}
+                change={change}
+                pendingAction={pendingActions[`${change.group}:${change.path}`]}
+                onClick={() => handlers.openDiff(change)}
+                actions={[
+                  {
+                    label: 'Unstage changes',
+                    symbol: '−',
+                    onClick: () => void onUnstage(change)
+                  }
+                ]}
+              />
+            ))}
+          </ChangeSection>
+          <ChangeSection
+            label="Changes"
+            count={unstaged.length}
+            collapsed={changesCollapsed}
+            onToggleCollapsed={() => setChangesCollapsed(c => !c)}
+            actions={
+              unstaged.length > 0
+                ? [
+                    {
+                      label: 'Stage all changes',
+                      symbol: '+',
+                      onClick: onStageAll
+                    }
+                  ]
+                : undefined
+            }
+          >
+            {unstaged.map(change => (
+              <ChangeRow
+                key={`${change.group}:${change.path}`}
+                change={change}
+                pendingAction={pendingActions[`${change.group}:${change.path}`]}
+                onClick={() => handlers.openDiff(change)}
+                actions={[
+                  {
+                    label: 'Discard changes',
+                    symbol: '⟲',
+                    onClick: () => void onDiscard(change)
+                  },
+                  {
+                    label: 'Stage changes',
+                    symbol: '+',
+                    onClick: () => void onStage(change)
+                  }
+                ]}
+              />
+            ))}
+          </ChangeSection>
+          {staged.length === 0 && unstaged.length === 0 && !state.loading ? (
+            <div className="jp-xtralab-GitPanel-empty">
+              No changes detected.
+            </div>
+          ) : null}
+        </>
+      )}
+    </div>
+  );
+}
+
+interface IRowAction {
+  label: string;
+  symbol: string;
+  onClick: () => void;
+}
+
+function PanelHeader(props: {
+  topLevel: string | null;
+  result: IGitStatusResult | null;
+  loading: boolean;
+  error: string | null;
+  onRefresh: () => void;
+}): React.ReactElement {
+  const { topLevel, result, loading, error, onRefresh } = props;
+  const repoName =
+    topLevel !== null
+      ? (topLevel
+          .split('/')
+          .filter(s => s.length > 0)
+          .pop() ?? topLevel)
+      : null;
+  return (
+    <div className="jp-xtralab-GitPanel-header">
+      <div className="jp-xtralab-GitPanel-headerInfo">
+        <div className="jp-xtralab-GitPanel-title">Source Control</div>
+        {repoName !== null ? (
+          <div
+            className="jp-xtralab-GitPanel-repo"
+            title={topLevel ?? ''}
+          >
+            {repoName}
+          </div>
+        ) : null}
+        {result?.branch !== undefined && result?.branch !== null ? (
+          <div className="jp-xtralab-GitPanel-branch">
+            {result.branch}
+            {result.ahead > 0 ? <span> ↑{result.ahead}</span> : null}
+            {result.behind > 0 ? <span> ↓{result.behind}</span> : null}
+          </div>
+        ) : null}
+      </div>
+      <button
+        type="button"
+        className="jp-xtralab-GitPanel-iconButton"
+        title="Refresh"
+        disabled={loading && error === null}
+        onClick={onRefresh}
+      >
+        ⟳
+      </button>
+    </div>
+  );
+}
+
+function ChangeSection(props: {
+  label: string;
+  count: number;
+  collapsed: boolean;
+  onToggleCollapsed: () => void;
+  actions?: IRowAction[];
+  children: React.ReactNode;
+}): React.ReactElement {
+  const { label, count, collapsed, onToggleCollapsed, actions, children } =
+    props;
+  return (
+    <div className="jp-xtralab-GitPanel-section">
+      <div
+        className="jp-xtralab-GitPanel-sectionHeader"
+        onClick={onToggleCollapsed}
+      >
+        <span className="jp-xtralab-GitPanel-sectionChevron">
+          {collapsed ? '▸' : '▾'}
+        </span>
+        <span className="jp-xtralab-GitPanel-sectionLabel">
+          {label}
+        </span>
+        {actions !== undefined ? (
+          <span className="jp-xtralab-GitPanel-sectionActions">
+            {actions.map(action => (
+              <button
+                key={action.label}
+                type="button"
+                className="jp-xtralab-GitPanel-iconButton"
+                title={action.label}
+                onClick={event => {
+                  event.stopPropagation();
+                  action.onClick();
+                }}
+              >
+                {action.symbol}
+              </button>
+            ))}
+          </span>
+        ) : null}
+        <span className="jp-xtralab-GitPanel-sectionCount">
+          {count}
+        </span>
+      </div>
+      {!collapsed ? (
+        <div className="jp-xtralab-GitPanel-sectionBody">
+          {children}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function ChangeRow(props: {
+  change: IFileChange;
+  pendingAction: string | undefined;
+  onClick: () => void;
+  actions: IRowAction[];
+}): React.ReactElement {
+  const { change, pendingAction, onClick, actions } = props;
+  const filename = basename(change.path);
+  const dirname = dirnameOrEmpty(change.path);
+  return (
+    <div
+      className="jp-xtralab-GitPanel-row"
+      data-status={change.status}
+      title={
+        change.from !== undefined
+          ? `${change.from} → ${change.path}`
+          : change.path
+      }
+      onClick={onClick}
+    >
+      <span className="jp-xtralab-GitPanel-rowLabel">
+        <span className="jp-xtralab-GitPanel-rowName">{filename}</span>
+        {dirname !== '' ? (
+          <span className="jp-xtralab-GitPanel-rowPath">{dirname}</span>
+        ) : null}
+      </span>
+      <span
+        className="jp-xtralab-GitPanel-rowActions"
+        data-pending={pendingAction !== undefined}
+      >
+        {actions.map(action => (
+          <button
+            key={action.label}
+            type="button"
+            className="jp-xtralab-GitPanel-iconButton"
+            title={action.label}
+            disabled={pendingAction !== undefined}
+            onClick={event => {
+              event.stopPropagation();
+              action.onClick();
+            }}
+          >
+            {action.symbol}
+          </button>
+        ))}
+      </span>
+      <span
+        className="jp-xtralab-GitPanel-rowBadge"
+        data-status={change.status}
+        title={statusTooltip(change.status)}
+      >
+        {statusBadge(change.status)}
+      </span>
+    </div>
+  );
+}
+
+function statusBadge(status: FileChangeStatus): string {
+  switch (status) {
+    case 'modified':
+      return 'M';
+    case 'added':
+      return 'A';
+    case 'deleted':
+      return 'D';
+    case 'renamed':
+      return 'R';
+    case 'untracked':
+      return 'U';
+    case 'unmerged':
+      return '!';
+    case 'typechange':
+      return 'T';
+    default:
+      return '?';
+  }
+}
+
+function statusTooltip(status: FileChangeStatus): string {
+  switch (status) {
+    case 'modified':
+      return 'Modified';
+    case 'added':
+      return 'Added';
+    case 'deleted':
+      return 'Deleted';
+    case 'renamed':
+      return 'Renamed';
+    case 'untracked':
+      return 'Untracked';
+    case 'unmerged':
+      return 'Unmerged (conflict)';
+    case 'typechange':
+      return 'Type changed';
+    default:
+      return 'Unknown';
+  }
+}
+
+function basename(path: string): string {
+  const idx = path.lastIndexOf('/');
+  return idx < 0 ? path : path.slice(idx + 1);
+}
+
+function dirnameOrEmpty(path: string): string {
+  const idx = path.lastIndexOf('/');
+  return idx < 0 ? '' : path.slice(0, idx);
+}

package/src/git/tokens.ts

@@ -0,0 +1,91 @@
+/**
+ * Types shared by the git plugin. Mirror the response shapes returned by the
+ * `jupyterlab_git` server extension's REST API so the frontend can stay
+ * tightly coupled to a single version of those endpoints.
+ */
+
+/**
+ * A single entry in the `files` array returned by `POST /git/<path>/status`.
+ * `x` and `y` are the porcelain-format index/worktree status codes (see
+ * `git status --porcelain`); `to` is the file's current path relative to the
+ * git repository root, `from` is the source path for renames (and equal to
+ * `to` for any other status).
+ */
+export interface IGitStatusFile {
+  x: string;
+  y: string;
+  to: string;
+  from: string;
+  is_binary: boolean | null;
+}
+
+/** Response shape of `POST /git/<path>/status`. */
+export interface IGitStatusResult {
+  code: number;
+  branch: string | null;
+  remote: string | null;
+  ahead: number;
+  behind: number;
+  files: IGitStatusFile[];
+  state?: number;
+  message?: string;
+}
+
+/**
+ * Reference accepted by `POST /git/<path>/content` to identify which version
+ * of a file to fetch. `WORKING` is the on-disk copy, `INDEX` is the staged
+ * copy, and a `git` value is any commit-ish (`HEAD`, a SHA, …).
+ */
+export type GitReference =
+  | { special: 'WORKING' | 'INDEX' | 'BASE' }
+  | { git: string };
+
+/**
+ * Response shape of `POST /git/<path>/content`. The server only returns text
+ * content here; binary files are reported as binary in the status response,
+ * and we surface them in the UI without attempting to render their diff.
+ */
+export interface IGitContentResult {
+  code: number;
+  content: string;
+  message?: string;
+}
+
+/**
+ * Where a file's change lives relative to the index.
+ *
+ *   - `staged`   → present in the index, may differ from HEAD
+ *   - `unstaged` → present in the worktree, differs from the index
+ *
+ * A single file can appear in both groups when the worktree has further
+ * changes on top of an already-staged version. The panel models that as two
+ * separate entries, one per group.
+ */
+export type FileChangeGroup = 'staged' | 'unstaged';
+
+/**
+ * The user-facing status of a file change. Drives the single-letter badge
+ * (M/A/D/R/U/?) shown next to each entry in the panel.
+ */
+export type FileChangeStatus =
+  | 'modified'
+  | 'added'
+  | 'deleted'
+  | 'renamed'
+  | 'untracked'
+  | 'unmerged'
+  | 'typechange'
+  | 'unknown';
+
+/**
+ * One row in the changes panel. `path` is the file's path relative to the
+ * git repository root. `from` is non-`undefined` only for renames, in which
+ * case it carries the original path.
+ */
+export interface IFileChange {
+  path: string;
+  from?: string;
+  group: FileChangeGroup;
+  status: FileChangeStatus;
+  isBinary: boolean | null;
+}