xtralab 0.1.0

package/lib/fileBrowser/icons.js

@@ -0,0 +1,153 @@
+var _a;
+import { LabIcon, fileIcon } from '@jupyterlab/ui-components';
+import { createFileTreeIconResolver, getBuiltInFileIconColor, getBuiltInSpriteSheet } 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 = {
+    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((_a = FILE_BROWSER_ICONS.set) !== null && _a !== void 0 ? _a : '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();
+/**
+ * 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) {
+    var _a;
+    // 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: (_a = viewBoxMatch === null || viewBoxMatch === void 0 ? void 0 : viewBoxMatch[1]) !== null && _a !== void 0 ? _a : '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) {
+    var _a;
+    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 = (_a = resolved.viewBox) !== null && _a !== void 0 ? _a : 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/lib/fileBrowser/index.d.ts

@@ -0,0 +1,7 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * The file browser plugin. Adds a `@pierre/trees`-powered file browser to the
+ * JupyterLab left sidebar.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/fileBrowser/index.js

@@ -0,0 +1,38 @@
+import { ILayoutRestorer } 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 = {
+    id: PLUGIN_ID,
+    description: 'A path-first file browser for JupyterLab built on @pierre/trees.',
+    autoStart: true,
+    requires: [IDocumentManager],
+    optional: [ILayoutRestorer, ISettingRegistry],
+    activate: (app, docManager, restorer, settingRegistry) => {
+        const browser = new XtralabFileBrowser({
+            contentsManager: app.serviceManager.contents,
+            docManager,
+            onOpenFile: (serverPath) => {
+                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/lib/fileBrowser/widget.d.ts

@@ -0,0 +1,97 @@
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { Contents } from '@jupyterlab/services';
+import { Toolbar } from '@jupyterlab/ui-components';
+import { ISignal } from '@lumino/signaling';
+import { Widget } from '@lumino/widgets';
+export declare 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 declare const FILE_BROWSER_CSS_CLASS = "jp-xtralab-FileBrowser";
+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 declare class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
+    constructor(options: IXtralabFileBrowserOptions);
+    get contentsManager(): Contents.IManager;
+    get toolbar(): Toolbar;
+    get selectedPaths(): readonly string[];
+    get selectionChanged(): ISignal<this, readonly string[]>;
+    get refreshRequested(): ISignal<this, void>;
+    get pathAdded(): ISignal<this, string>;
+    /**
+     * Update the cached selection. Called from the React tree when the
+     * underlying `@pierre/trees` model emits a selection change.
+     */
+    updateSelection(paths: readonly string[]): void;
+    refresh(): void;
+    notifyPathAdded(canonicalPath: string): void;
+    private _contentsManager;
+    private _docManager;
+    private _onOpenFile;
+    private _selectedPaths;
+    private _selectionChanged;
+    private _refreshRequested;
+    private _pathAdded;
+    private _toolbar;
+    private _content;
+}

package/lib/fileBrowser/widget.js

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import { ReactWidget, Toolbar } from '@jupyterlab/ui-components';
+import { Signal } 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';
+/**
+ * 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 {
+    constructor(options) {
+        super();
+        this._selectedPaths = [];
+        this._selectionChanged = new Signal(this);
+        this._refreshRequested = new Signal(this);
+        this._pathAdded = new Signal(this);
+        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() {
+        return this._contentsManager;
+    }
+    get toolbar() {
+        return this._toolbar;
+    }
+    get selectedPaths() {
+        return this._selectedPaths;
+    }
+    get selectionChanged() {
+        return this._selectionChanged;
+    }
+    get refreshRequested() {
+        return this._refreshRequested;
+    }
+    get pathAdded() {
+        return this._pathAdded;
+    }
+    /**
+     * Update the cached selection. Called from the React tree when the
+     * underlying `@pierre/trees` model emits a selection change.
+     */
+    updateSelection(paths) {
+        this._selectedPaths = paths;
+        this._selectionChanged.emit(paths);
+    }
+    refresh() {
+        this._refreshRequested.emit();
+    }
+    notifyPathAdded(canonicalPath) {
+        this._pathAdded.emit(canonicalPath);
+    }
+}
+/**
+ * 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) {
+        super();
+        this._options = options;
+    }
+    render() {
+        return (React.createElement(FileBrowserComponent, { contentsManager: this._options.contentsManager, docManager: this._options.docManager, onOpenFile: this._options.onOpenFile, widget: this._options.browser }));
+    }
+}

package/lib/git/api.d.ts

@@ -0,0 +1,39 @@
+import { GitReference, IFileChange, IGitContentResult, IGitStatusFile, IGitStatusResult } from './tokens';
+/**
+ * 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 declare function showTopLevel(repoPath: string): Promise<string | null>;
+/**
+ * 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 declare function status(repoPath: string): Promise<IGitStatusResult>;
+/**
+ * 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 declare function content(repoPath: string, filename: string, reference: GitReference): Promise<IGitContentResult>;
+/** Stage a single file. */
+export declare function add(repoPath: string, filename: string): Promise<void>;
+/** Stage every changed file (including untracked). */
+export declare function addAll(repoPath: string): Promise<void>;
+/** Unstage a single file. */
+export declare function reset(repoPath: string, filename: string): Promise<void>;
+/** Unstage every file. */
+export declare function resetAll(repoPath: string): Promise<void>;
+/** Restore a single file to the version in the index (i.e. discard worktree changes). */
+export declare function checkout(repoPath: string, filename: string): Promise<void>;
+/**
+ * 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 declare function porcelainToFileChanges(file: IGitStatusFile): IFileChange[];

package/lib/git/api.js

@@ -0,0 +1,164 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * 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(endpoint, repoPath, body) {
+    var _a, _b;
+    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 = {
+        method: 'POST',
+        body: JSON.stringify(body !== null && body !== void 0 ? body : {})
+    };
+    const response = await ServerConnection.makeRequest(url, init, settings);
+    const text = await response.text();
+    let data;
+    if (text.length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch (_err) {
+            // Fall through into the error handling below.
+        }
+    }
+    if (!response.ok) {
+        const message = (_b = (_a = data === null || data === void 0 ? void 0 : data.message) !== null && _a !== void 0 ? _a : text) !== null && _b !== void 0 ? _b : '';
+        throw new ServerConnection.ResponseError(response, message);
+    }
+    return (data !== null && data !== void 0 ? data : {});
+}
+/**
+ * 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) {
+    let result;
+    try {
+        result = await postWithPath('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) {
+    return postWithPath('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, filename, reference) {
+    return postWithPath('content', repoPath, {
+        filename,
+        reference
+    });
+}
+/** Stage a single file. */
+export async function add(repoPath, filename) {
+    await postWithPath('add', repoPath, { add_all: false, filename });
+}
+/** Stage every changed file (including untracked). */
+export async function addAll(repoPath) {
+    await postWithPath('add', repoPath, { add_all: true });
+}
+/** Unstage a single file. */
+export async function reset(repoPath, filename) {
+    await postWithPath('reset', repoPath, { reset_all: false, filename });
+}
+/** Unstage every file. */
+export async function resetAll(repoPath) {
+    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, filename) {
+    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) {
+    const result = [];
+    // 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) {
+    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';
+    }
+}

package/lib/git/commands.d.ts

@@ -0,0 +1,69 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { ICommandPalette, IThemeManager } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { Contents } from '@jupyterlab/services';
+import { createGitDiffWidget, diffWidgetId } from './diffWidget';
+import { GitPanel } from './panel';
+import { IFileChange } from './tokens';
+/**
+ * Command IDs exposed by the git plugin. Both are registered in
+ * {@link registerGitCommands} so other extensions, the command palette and
+ * keybindings can drive the panel without going through the React internals.
+ */
+export declare namespace CommandIDs {
+    const refresh = "xtralab:git:refresh";
+    const openDiff = "xtralab:git:open-diff";
+}
+/**
+ * Argument shapes used by {@link CommandIDs.openDiff}. Cast to this type
+ * inside the execute callback for type safety; the registry itself takes
+ * `ReadonlyPartialJSONObject` because Lumino does not know about our
+ * extension-specific shapes.
+ */
+export declare namespace CommandArguments {
+    interface IOpenDiff {
+        repoPath: string;
+        change: IFileChange;
+    }
+}
+export interface IRegisterGitCommandsOptions {
+    app: JupyterFrontEnd;
+    panel: GitPanel;
+    themeManager: IThemeManager | null;
+    commandPalette: ICommandPalette | null;
+    /**
+     * Contents manager used by the diff widget to write hunk-discard
+     * results back to the working tree.
+     */
+    contentsManager: Contents.IManager;
+    /**
+     * Rendermime registry used by the notebook diff to render outputs and
+     * markdown cells with their actual mime-type renderers (images as
+     * images, HTML as HTML, etc.). May be `null` in stripped-down hosts —
+     * the notebook diff falls back to a text representation in that case.
+     */
+    rendermime: IRenderMimeRegistry | null;
+    /**
+     * Called whenever the diff widget mutates the working tree (e.g. after
+     * a hunk discard) so the plugin can refresh the changes panel.
+     */
+    onChanged: () => void;
+    /**
+     * Called for every diff widget created via the {@link CommandIDs.openDiff}
+     * command, before the widget is added to the shell. Lets the plugin track
+     * the widget for layout restoration and reveal-on-reuse.
+     */
+    trackDiff(widget: ReturnType<typeof createGitDiffWidget>): Promise<void>;
+    /**
+     * Look up an already-open diff widget for a given file change. Returns
+     * `undefined` when none is open.
+     */
+    findDiff(change: IFileChange): ReturnType<typeof createGitDiffWidget> | undefined;
+}
+/**
+ * Register the git commands on the application command registry. Returns
+ * a disposer that clears the command palette items the registration created
+ * (the commands themselves stay registered for the lifetime of the plugin).
+ */
+export declare function registerGitCommands(options: IRegisterGitCommandsOptions): () => void;
+export { diffWidgetId };