xtralab 0.1.0

package/src/fileBrowser/icons.ts

@@ -0,0 +1,172 @@
+import { LabIcon, fileIcon } from '@jupyterlab/ui-components';
+import {
+  createFileTreeIconResolver,
+  getBuiltInFileIconColor,
+  getBuiltInSpriteSheet
+} from '@pierre/trees';
+import type { FileTreeIconConfig } from '@pierre/trees';
+
+/**
+ * The glyph used as the Xtralab file browser's sidebar tab icon. Defined as a
+ * `LabIcon` (rather than the default `folderIcon` from
+ * `@jupyterlab/ui-components`) so the Xtralab browser is visually distinguishable
+ * from JupyterLab's built-in file browser, which also lives in the left
+ * sidebar.
+ *
+ * Source: `file-tree` from SVG Repo (https://www.svgrepo.com/svg/371275/file-tree).
+ * The original `fill="#444"` is replaced with `fill="currentColor"` and the
+ * root element is given the `jp-icon3` class so the icon picks up JupyterLab's
+ * theme color and the sidebar's inverse-color painting automatically.
+ */
+export const xtralabFileBrowserIcon = new LabIcon({
+  name: 'xtralab:file-browser',
+  svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="jp-icon3" fill="currentColor">
+  <path d="M16 10v-4h-11v1h-2v-3h9v-4h-12v4h2v10h3v2h11v-4h-11v1h-2v-5h2v2z"/>
+</svg>`
+});
+
+/**
+ * Sprite sheet injected into the `@pierre/trees` shadow DOM. Contains a single
+ * `<symbol>` for the Jupyter notebook icon, drawn from the JupyterLab core
+ * notebook icon (`@jupyterlab/ui-components/style/icons/filetype/notebook.svg`).
+ *
+ * `@pierre/trees` does not ship a Jupyter token, so `.ipynb` files would
+ * otherwise fall through to the generic file icon. The symbol id below is
+ * referenced from `byFileExtension` in {@link FILE_BROWSER_ICONS}.
+ *
+ * The orange `#EF6C00` fill is set as a presentation attribute on the inner
+ * `<g>` so it survives the `fill: currentColor` rule the tree applies on the
+ * icon container — the inherited color does not override a presentation
+ * attribute set directly on a child.
+ */
+const JUPYTER_NOTEBOOK_SPRITE_SHEET = `<svg data-icon-sprite aria-hidden="true" width="0" height="0">
+  <symbol id="jupyter-notebook" viewBox="0 0 22 22">
+    <g fill="#EF6C00">
+      <path d="M18.7 3.3v15.4H3.3V3.3zm1.5-1.5H1.8v18.3h18.3z"/>
+      <path d="m16.5 16.5-5.4-4.3-5.6 4.3v-11h11z"/>
+    </g>
+  </symbol>
+</svg>`;
+
+/**
+ * Icon configuration for the Xtralab file browser. Keeps the default `complete`
+ * built-in icon set (the colored language icons) and layers a Jupyter notebook
+ * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
+ *
+ * `set` must be set explicitly: when a config object includes any custom
+ * overrides without `set`, `@pierre/trees` defaults `set` to `'none'`, which
+ * disables the built-in icons entirely.
+ */
+export const FILE_BROWSER_ICONS: FileTreeIconConfig = {
+  set: 'complete',
+  colored: true,
+  spriteSheet: JUPYTER_NOTEBOOK_SPRITE_SHEET,
+  byFileExtension: {
+    ipynb: 'jupyter-notebook'
+  }
+};
+
+/**
+ * Concatenated sprite-sheet text. Combines the built-in sheet for the active
+ * icon set with our custom Jupyter notebook sheet so {@link extractSymbol}
+ * can find the body of any symbol the tree itself can render.
+ */
+const COMBINED_SPRITE_SHEETS = [
+  getBuiltInSpriteSheet(FILE_BROWSER_ICONS.set ?? 'complete'),
+  JUPYTER_NOTEBOOK_SPRITE_SHEET
+].join('\n');
+
+/**
+ * Resolver instance reused across calls to {@link getTreeIcon}. The resolver
+ * is pure relative to the icon config, so building it once at module load
+ * avoids re-walking the icon rules on every diff that opens.
+ */
+const treeIconResolver = createFileTreeIconResolver(FILE_BROWSER_ICONS);
+
+/**
+ * Cache of LabIcons keyed by the resolved sprite symbol id (e.g.
+ * `file-tree-builtin-python`). All Python files share the same icon, so
+ * caching by symbol id prevents repeated LabIcon registration warnings and
+ * keeps the JupyterLab icon registry small.
+ */
+const TREE_ICON_CACHE = new Map<string, LabIcon>();
+
+/**
+ * Extract the inner SVG markup and viewBox of the `<symbol>` with the given
+ * id from {@link COMBINED_SPRITE_SHEETS}. Returns `null` if no matching
+ * symbol exists, in which case the caller falls back to JupyterLab's default
+ * file icon.
+ */
+function extractSymbol(
+  symbolId: string
+): { viewBox: string; inner: string } | null {
+  // Match a `<symbol>` whose `id` attribute equals `symbolId` (allowing other
+  // attributes in any order). The `[\s\S]*?` body is non-greedy so we stop
+  // at the first matching `</symbol>` even when multiple symbols sit
+  // back-to-back in the sheet.
+  const escaped = symbolId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const symbolRegex = new RegExp(
+    `<symbol\\b[^>]*\\bid="${escaped}"[^>]*>([\\s\\S]*?)</symbol>`,
+    'i'
+  );
+  const match = symbolRegex.exec(COMBINED_SPRITE_SHEETS);
+  if (match === null) {
+    return null;
+  }
+  const viewBoxMatch = /\bviewBox="([^"]*)"/i.exec(match[0]);
+  return {
+    viewBox: viewBoxMatch?.[1] ?? '0 0 16 16',
+    inner: match[1]
+  };
+}
+
+/**
+ * Return a JupyterLab `LabIcon` matching the icon the Xtralab file tree would
+ * render for the given file path. Used by other plugins (e.g. the git diff
+ * viewer) that want their main-area widget tabs to display the same per-file
+ * glyph the tree shows in the sidebar.
+ *
+ * Resolves the symbol via the same `@pierre/trees` resolver the tree itself
+ * uses, then inlines the symbol's body into a self-contained SVG so the icon
+ * works outside the tree's shadow DOM. Falls back to JupyterLab's default
+ * `fileIcon` when the sprite cannot be located in either sheet.
+ */
+export function getTreeIcon(filePath: string): LabIcon {
+  const resolved = treeIconResolver.resolveIcon(
+    'file-tree-icon-file',
+    filePath
+  );
+  const cached = TREE_ICON_CACHE.get(resolved.name);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const symbol = extractSymbol(resolved.name);
+  if (symbol === null) {
+    return fileIcon;
+  }
+  // Built-in language icons paint with `fill="currentColor"` so the colored
+  // tier of the tree can recolor them by setting `color` on the host
+  // element. Reproduce that here by setting the same color value as an
+  // inline `style="color: …"` on the outer `<svg>`. `getBuiltInFileIconColor`
+  // returns a `var(--trees-…)` chain that bottoms out in `light-dark(…)`,
+  // which respects the page's `color-scheme` declaration so dark themes pick
+  // up the brighter variants automatically.
+  const colored = FILE_BROWSER_ICONS.colored === true;
+  const color =
+    colored && resolved.token !== undefined
+      ? getBuiltInFileIconColor(resolved.token)
+      : undefined;
+  const styleAttr = color !== undefined ? ` style="color: ${color};"` : '';
+  // Prefer a viewBox the resolver supplies (custom sprite overrides may set
+  // one), then fall back to the symbol's own viewBox so 22x22 sprites like
+  // the Jupyter notebook glyph render at the right scale rather than being
+  // cropped to a 16x16 box.
+  const viewBox = resolved.viewBox ?? symbol.viewBox;
+  const svgstr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}"${styleAttr}>${symbol.inner}</svg>`;
+  const icon = new LabIcon({
+    name: `xtralab:tree-icon-${resolved.name}`,
+    svgstr
+  });
+  TREE_ICON_CACHE.set(resolved.name, icon);
+  return icon;
+}

package/src/fileBrowser/index.ts

@@ -0,0 +1,56 @@
+import {
+  ILayoutRestorer,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+
+import { IDocumentManager } from '@jupyterlab/docmanager';
+
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { populateToolbar, registerCommands } from './commands';
+import { XtralabFileBrowser } from './widget';
+
+const PLUGIN_ID = 'xtralab:plugin';
+
+/**
+ * The file browser plugin. Adds a `@pierre/trees`-powered file browser to the
+ * JupyterLab left sidebar.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'A path-first file browser for JupyterLab built on @pierre/trees.',
+  autoStart: true,
+  requires: [IDocumentManager],
+  optional: [ILayoutRestorer, ISettingRegistry],
+  activate: (
+    app: JupyterFrontEnd,
+    docManager: IDocumentManager,
+    restorer: ILayoutRestorer | null,
+    settingRegistry: ISettingRegistry | null
+  ): void => {
+    const browser = new XtralabFileBrowser({
+      contentsManager: app.serviceManager.contents,
+      docManager,
+      onOpenFile: (serverPath: string) => {
+        void app.commands.execute('docmanager:open', { path: serverPath });
+      }
+    });
+    app.shell.add(browser, 'left', { rank: 700 });
+    if (restorer) {
+      restorer.add(browser, browser.id);
+    }
+
+    registerCommands({ app, browser });
+    populateToolbar({ app, browser });
+
+    if (settingRegistry) {
+      settingRegistry.load(PLUGIN_ID).catch(reason => {
+        console.error('Failed to load settings for xtralab.', reason);
+      });
+    }
+  }
+};
+
+export default plugin;

package/src/fileBrowser/widget.tsx

@@ -0,0 +1,202 @@
+import * as React from 'react';
+
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { Contents } from '@jupyterlab/services';
+import { ReactWidget, Toolbar } from '@jupyterlab/ui-components';
+import { Signal, ISignal } from '@lumino/signaling';
+import { PanelLayout, Widget } from '@lumino/widgets';
+
+import { FileBrowserComponent } from './fileBrowser';
+import { xtralabFileBrowserIcon } from './icons';
+
+export const FILE_BROWSER_ID = 'xtralab:file-browser';
+
+/**
+ * The CSS class added to the Xtralab file browser widget. The selectors that
+ * bind application context menu items hang off this class, so it must remain
+ * specific enough not to clash with other browsers (such as the default
+ * `jp-FileBrowser`).
+ */
+export const FILE_BROWSER_CSS_CLASS = 'jp-xtralab-FileBrowser';
+
+const TOOLBAR_CSS_CLASS = 'jp-xtralab-FileBrowser-toolbar';
+const CONTENT_CSS_CLASS = 'jp-xtralab-FileBrowser-content';
+
+export interface IXtralabFileBrowserOptions {
+  contentsManager: Contents.IManager;
+  docManager: IDocumentManager;
+  onOpenFile?: (serverPath: string) => void;
+}
+
+/**
+ * Public API of the Xtralab file browser used by command handlers and other
+ * collaborators. Kept narrow on purpose so the React component stays free to
+ * evolve the underlying tree integration.
+ */
+export interface IXtralabFileBrowser {
+  /**
+   * The contents manager backing the tree. Exposed so command handlers can
+   * issue contents operations (rename, delete, copy, …) against the same
+   * drive the tree was loaded from.
+   */
+  readonly contentsManager: Contents.IManager;
+
+  /**
+   * The toolbar shown above the tree. Plugin code populates it with command
+   * buttons after the widget is constructed.
+   */
+  readonly toolbar: Toolbar;
+
+  /**
+   * Canonical paths of the items currently selected in the tree. Folder
+   * paths carry a trailing slash; file paths do not.
+   */
+  readonly selectedPaths: readonly string[];
+
+  /**
+   * Emits when the tree's selection changes. Commands that have an
+   * `isVisible` / `isEnabled` predicate should listen so they re-evaluate.
+   */
+  readonly selectionChanged: ISignal<IXtralabFileBrowser, readonly string[]>;
+
+  /**
+   * Emits when {@link refresh} is called. The React component listens and
+   * re-fetches the directories that were previously loaded so the tree
+   * matches the contents on disk again.
+   */
+  readonly refreshRequested: ISignal<IXtralabFileBrowser, void>;
+
+  /**
+   * Emits when the widget is asked to surface a newly-created path
+   * (for example, after the toolbar's "new folder" command). The React
+   * component listens and inserts the path into the model so the user
+   * sees the new item without a full refresh.
+   */
+  readonly pathAdded: ISignal<IXtralabFileBrowser, string>;
+
+  /** Trigger a refresh of every loaded directory in the tree. */
+  refresh(): void;
+
+  /**
+   * Notify the React component that a new path was created and should
+   * appear in the tree. `canonicalPath` follows the `@pierre/trees`
+   * convention: directories carry a trailing slash, files do not.
+   */
+  notifyPathAdded(canonicalPath: string): void;
+}
+
+/**
+ * Lumino widget that hosts the React-based `@pierre/trees` file browser.
+ * The widget is laid out with a JupyterLab `Toolbar` on top and the tree
+ * filling the remaining space.
+ */
+export class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
+  constructor(options: IXtralabFileBrowserOptions) {
+    super();
+    const layout = (this.layout = new PanelLayout());
+
+    this._contentsManager = options.contentsManager;
+    this._docManager = options.docManager;
+    this._onOpenFile = options.onOpenFile;
+    this.id = FILE_BROWSER_ID;
+    this.title.icon = xtralabFileBrowserIcon;
+    this.title.caption = 'Xtralab File Browser';
+    this.addClass(FILE_BROWSER_CSS_CLASS);
+
+    this._toolbar = new Toolbar();
+    this._toolbar.addClass(TOOLBAR_CSS_CLASS);
+    this._toolbar.node.setAttribute('aria-label', 'file browser');
+    layout.addWidget(this._toolbar);
+
+    this._content = new XtralabFileTreeContent({
+      contentsManager: this._contentsManager,
+      docManager: this._docManager,
+      onOpenFile: this._onOpenFile,
+      browser: this
+    });
+    this._content.addClass(CONTENT_CSS_CLASS);
+    layout.addWidget(this._content);
+  }
+
+  get contentsManager(): Contents.IManager {
+    return this._contentsManager;
+  }
+
+  get toolbar(): Toolbar {
+    return this._toolbar;
+  }
+
+  get selectedPaths(): readonly string[] {
+    return this._selectedPaths;
+  }
+
+  get selectionChanged(): ISignal<this, readonly string[]> {
+    return this._selectionChanged;
+  }
+
+  get refreshRequested(): ISignal<this, void> {
+    return this._refreshRequested;
+  }
+
+  get pathAdded(): ISignal<this, string> {
+    return this._pathAdded;
+  }
+
+  /**
+   * Update the cached selection. Called from the React tree when the
+   * underlying `@pierre/trees` model emits a selection change.
+   */
+  updateSelection(paths: readonly string[]): void {
+    this._selectedPaths = paths;
+    this._selectionChanged.emit(paths);
+  }
+
+  refresh(): void {
+    this._refreshRequested.emit();
+  }
+
+  notifyPathAdded(canonicalPath: string): void {
+    this._pathAdded.emit(canonicalPath);
+  }
+
+  private _contentsManager: Contents.IManager;
+  private _docManager: IDocumentManager;
+  private _onOpenFile: ((serverPath: string) => void) | undefined;
+  private _selectedPaths: readonly string[] = [];
+  private _selectionChanged = new Signal<this, readonly string[]>(this);
+  private _refreshRequested = new Signal<this, void>(this);
+  private _pathAdded = new Signal<this, string>(this);
+  private _toolbar: Toolbar;
+  private _content: XtralabFileTreeContent;
+}
+
+interface IFileTreeContentOptions {
+  contentsManager: Contents.IManager;
+  docManager: IDocumentManager;
+  onOpenFile?: (serverPath: string) => void;
+  browser: XtralabFileBrowser;
+}
+
+/**
+ * The React-rendered region of the file browser. Lives inside the host
+ * widget below the toolbar and renders the actual tree.
+ */
+class XtralabFileTreeContent extends ReactWidget {
+  constructor(options: IFileTreeContentOptions) {
+    super();
+    this._options = options;
+  }
+
+  protected render(): React.ReactElement {
+    return (
+      <FileBrowserComponent
+        contentsManager={this._options.contentsManager}
+        docManager={this._options.docManager}
+        onOpenFile={this._options.onOpenFile}
+        widget={this._options.browser}
+      />
+    );
+  }
+
+  private _options: IFileTreeContentOptions;
+}

package/src/git/api.ts

@@ -0,0 +1,207 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+
+import {
+  GitReference,
+  IFileChange,
+  IGitContentResult,
+  IGitStatusFile,
+  IGitStatusResult
+} from './tokens';
+
+/**
+ * Root URL segment used by the `jupyterlab_git` server extension. Every
+ * endpoint hangs off this prefix; the `<repoPath>` between it and the
+ * endpoint suffix is the JupyterLab server-relative path of the git
+ * repository (URL-encoded). For an empty `repoPath` the URL collapses to
+ * `/git/<endpoint>` — a shape git's URL routing also accepts.
+ */
+const GIT_NAMESPACE = 'git';
+
+/**
+ * Issue a `POST` against a `jupyterlab_git` endpoint that takes a `<path>`
+ * prefix (e.g. `/git/<path>/status`). The response body is decoded as JSON;
+ * non-2xx responses are surfaced via the JupyterLab `ServerConnection`
+ * machinery so callers can show their `message` field as-is.
+ */
+async function postWithPath<T>(
+  endpoint: string,
+  repoPath: string,
+  body: unknown
+): Promise<T> {
+  const settings = ServerConnection.makeSettings();
+  // `URLExt.encodeParts` encodes each path segment but preserves slashes
+  // between them — the server expects the path to look like a posix path.
+  const encodedPath = repoPath.length > 0 ? URLExt.encodeParts(repoPath) : '';
+  const url = URLExt.join(
+    settings.baseUrl,
+    GIT_NAMESPACE,
+    encodedPath,
+    endpoint
+  );
+  const init: RequestInit = {
+    method: 'POST',
+    body: JSON.stringify(body ?? {})
+  };
+  const response = await ServerConnection.makeRequest(url, init, settings);
+  const text = await response.text();
+  let data: T | undefined;
+  if (text.length > 0) {
+    try {
+      data = JSON.parse(text) as T;
+    } catch (_err) {
+      // Fall through into the error handling below.
+    }
+  }
+  if (!response.ok) {
+    const message =
+      (data as { message?: string } | undefined)?.message ?? text ?? '';
+    throw new ServerConnection.ResponseError(response, message);
+  }
+  return (data ?? ({} as T)) as T;
+}
+
+/**
+ * Fetch the absolute filesystem path of the git top-level for the given
+ * server-relative path. Returns `null` when the path is not in a git
+ * repository — the server returns a non-zero `code` (or `path: null`) in
+ * that case, which is expected and not a fatal error.
+ */
+export async function showTopLevel(repoPath: string): Promise<string | null> {
+  interface IShowTopLevelResult {
+    code: number;
+    path?: string | null;
+    message?: string;
+  }
+  let result: IShowTopLevelResult;
+  try {
+    result = await postWithPath<IShowTopLevelResult>(
+      'show_top_level',
+      repoPath,
+      {}
+    );
+  } catch (err) {
+    return null;
+  }
+  if (result.code !== 0 || !result.path) {
+    return null;
+  }
+  return result.path;
+}
+
+/**
+ * Fetch `git status --porcelain` for the repository the server resolves at
+ * `repoPath`. When `repoPath` is the empty string, git resolves the repo
+ * from the JupyterLab server's root directory.
+ */
+export async function status(repoPath: string): Promise<IGitStatusResult> {
+  return postWithPath<IGitStatusResult>('status', repoPath, {});
+}
+
+/**
+ * Fetch a file's contents at a particular git reference. `filename` is the
+ * file's path relative to the git repository root (matching the `to` field
+ * of {@link status}'s response).
+ */
+export async function content(
+  repoPath: string,
+  filename: string,
+  reference: GitReference
+): Promise<IGitContentResult> {
+  return postWithPath<IGitContentResult>('content', repoPath, {
+    filename,
+    reference
+  });
+}
+
+/** Stage a single file. */
+export async function add(repoPath: string, filename: string): Promise<void> {
+  await postWithPath('add', repoPath, { add_all: false, filename });
+}
+
+/** Stage every changed file (including untracked). */
+export async function addAll(repoPath: string): Promise<void> {
+  await postWithPath('add', repoPath, { add_all: true });
+}
+
+/** Unstage a single file. */
+export async function reset(repoPath: string, filename: string): Promise<void> {
+  await postWithPath('reset', repoPath, { reset_all: false, filename });
+}
+
+/** Unstage every file. */
+export async function resetAll(repoPath: string): Promise<void> {
+  await postWithPath('reset', repoPath, { reset_all: true });
+}
+
+/** Restore a single file to the version in the index (i.e. discard worktree changes). */
+export async function checkout(
+  repoPath: string,
+  filename: string
+): Promise<void> {
+  await postWithPath('checkout', repoPath, {
+    checkout_branch: false,
+    filename
+  });
+}
+
+/**
+ * Translate one entry in the porcelain `files` array into the panel's
+ * preferred shape. A single porcelain entry may represent up to two changes
+ * (one in the index, one in the worktree); we emit one {@link IFileChange}
+ * per non-empty side, so a "modified-staged-and-then-modified-again" file
+ * shows up twice in the panel — once under "Staged Changes" and once under
+ * "Changes" — matching the layout the user sees in VS Code.
+ */
+export function porcelainToFileChanges(file: IGitStatusFile): IFileChange[] {
+  const result: IFileChange[] = [];
+  // Untracked files are reported with `??` and only appear under "Changes".
+  if (file.x === '?' && file.y === '?') {
+    return [
+      {
+        path: file.to,
+        group: 'unstaged',
+        status: 'untracked',
+        isBinary: file.is_binary
+      }
+    ];
+  }
+  if (file.x !== ' ' && file.x !== '?') {
+    result.push({
+      path: file.to,
+      from: file.from === file.to ? undefined : file.from,
+      group: 'staged',
+      status: porcelainCodeToStatus(file.x),
+      isBinary: file.is_binary
+    });
+  }
+  if (file.y !== ' ' && file.y !== '?') {
+    result.push({
+      path: file.to,
+      from: file.from === file.to ? undefined : file.from,
+      group: 'unstaged',
+      status: porcelainCodeToStatus(file.y),
+      isBinary: file.is_binary
+    });
+  }
+  return result;
+}
+
+function porcelainCodeToStatus(code: string): IFileChange['status'] {
+  switch (code) {
+    case 'M':
+      return 'modified';
+    case 'A':
+      return 'added';
+    case 'D':
+      return 'deleted';
+    case 'R':
+      return 'renamed';
+    case 'U':
+      return 'unmerged';
+    case 'T':
+      return 'typechange';
+    default:
+      return 'unknown';
+  }
+}