xtralab 0.15.1 → 0.15.2

package/README.md

@@ -2,19 +2,18 @@
 
 An opinionated JupyterLab meta-package for coding agents.
 
-xtralab reshapes JupyterLab around terminal coding agents. It bundles a curated
-set of extensions, a path-first file browser, rich git diffs, an agent launcher,
-a Model Context Protocol server that lets agents drive the app, and a quieter
-set of defaults. It builds on [`ajlab`](https://github.com/jtpio/ajlab), the
-agent-ready JupyterLab base.
-
-![The xtralab workspace: path-first file browser, agent launcher, a side-by-side git diff, and a running Claude Code session](./images/hero.webp)
-
-The [documentation](https://jtpio.github.io/xtralab/) covers everything in
-detail: [installation](https://jtpio.github.io/xtralab/installation/), a
-[tour of the features](https://jtpio.github.io/xtralab/getting-started/),
-[connecting agents over MCP](https://jtpio.github.io/xtralab/agents/mcp/),
-[agent skills](https://jtpio.github.io/xtralab/agents/skills/), and the
+xtralab installs JupyterLab with a set of extensions and defaults for work
+with terminal coding agents: an agent launcher, side-by-side git diffs for
+text files and notebooks, prompts about selected code, and a Model Context
+Protocol server that lets agents drive the app. It builds on
+[`ajlab`](https://github.com/jtpio/ajlab), the agent-ready JupyterLab base.
+
+![The xtralab workspace: file browser, agent launcher, a side-by-side git diff, and a running Claude Code session](./images/hero.webp)
+
+See the [documentation](https://jtpio.github.io/xtralab/) for the
+[installation](https://jtpio.github.io/xtralab/installation/), a
+[getting started tutorial](https://jtpio.github.io/xtralab/getting-started/),
+the [features](https://jtpio.github.io/xtralab/features/launcher/), and the
 [desktop app](https://jtpio.github.io/xtralab/desktop/).
 
 ## Install
@@ -24,34 +23,60 @@ pip install xtralab
 jupyter lab
 ```
 
-To try it from any directory without setting up an environment first, uv can
-build a throwaway one:
+To run xtralab in any folder without installing it, use uv:
 
 ```bash
 uvx --from xtralab jupyter-lab
 ```
 
 The [installation docs](https://jtpio.github.io/xtralab/installation/) also
-cover installing xtralab on your PATH or adding it to a project.
+show how to install xtralab as a uv tool or add it to a project.
 
-A standalone desktop app (DMG on macOS, AppImage on Linux) ships with every
-tagged release on the
-[releases page](https://github.com/jtpio/xtralab/releases/latest). The macOS
-app is signed and notarized and keeps itself up to date; see the
-[desktop app docs](https://jtpio.github.io/xtralab/desktop/) for how it
-manages projects and kernels.
+The desktop app (DMG on macOS, AppImage on Linux) is on the
+[releases page](https://github.com/jtpio/xtralab/releases/latest). It
+includes its own Python runtime. See the
+[desktop app docs](https://jtpio.github.io/xtralab/desktop/).
 
 ## Highlights
 
-![The xtralab launcher](./images/launcher.webp)
+### Agent launcher
 
-The launcher starts any agent installed on your machine, with an optional
-prompt and a **Changes** list that jumps straight into a side-by-side git diff
-you can edit in place. Select code in an editor, a notebook, or a diff to send
-a prompt about it to a new or already-running agent, or queue prompts while
-you read. One omnibox searches files and commands, the Terminals panel shows
-which agent runs where, and quieter defaults keep the workspace calm. The
-[documentation](https://jtpio.github.io/xtralab/) walks through each of these.
+Start any coding agent installed on your machine, with an optional first
+prompt. The **Changes** list opens the diff of each changed file.
+[Read more](https://jtpio.github.io/xtralab/features/launcher/).
+
+<img src="./images/launcher.webp" width="720" alt="The launcher: a prompt box, one button per installed agent, the Open section, and the list of changed files" />
+
+### Git diffs
+
+Review changes side by side, for text files and for notebooks, and edit the
+working copy in the diff.
+[Read more](https://jtpio.github.io/xtralab/features/git-diffs/).
+
+<img src="./images/diff.webp" width="1000" alt="A side-by-side diff of a Python file, with removed lines on the left and added lines on the right" />
+
+### Ask an agent
+
+Select code, type an instruction, and send it to a new or running agent. The
+prompt includes the file path, the line range, and the selected code.
+[Read more](https://jtpio.github.io/xtralab/features/ask-agent/).
+
+<img src="./images/ask-agent.webp" width="796" alt="The prompt box below a selected function, with an instruction and one button per agent" />
+
+### Omnibox
+
+Search files and commands, or send a prompt to an agent, from one search box
+(<kbd>Cmd/Ctrl</kbd>+<kbd>K</kbd>).
+[Read more](https://jtpio.github.io/xtralab/features/omnibox/).
+
+<img src="./images/omnibox.webp" width="642" alt="The omnibox with matching commands, a matching file, and one Ask row per agent" />
+
+### Terminals panel
+
+See the agent in each terminal and its latest line of output.
+[Read more](https://jtpio.github.io/xtralab/features/terminals/).
+
+<img src="./images/terminals.webp" width="451" alt="The Terminals panel with three agent sessions and their latest output" />
 
 ## Connecting agents to JupyterLab (MCP)
 
@@ -64,9 +89,9 @@ xtralab:
 claude mcp add jupyter -- jupyter-server-mcp-proxy
 ```
 
-The launcher surfaces the matching command for every agent you have
-installed, and the [MCP docs page](https://jtpio.github.io/xtralab/agents/mcp/)
-covers the details.
+The launcher shows this command for each installed agent. See the
+[MCP docs](https://jtpio.github.io/xtralab/agents/mcp/) for Codex, GitHub
+Copilot, and other agents.
 
 [mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
 [mcp-spec]: https://modelcontextprotocol.io

package/lib/fileBrowser/commands.d.ts

@@ -11,6 +11,7 @@ import { IXtralabFileBrowser } from './widget';
 export declare namespace CommandIDs {
     const open = "xtralab:open";
     const openBrowserTab = "xtralab:open-browser-tab";
+    const openGitDiff = "xtralab:open-git-diff";
     const rename = "xtralab:rename";
     const del = "xtralab:delete";
     const duplicate = "xtralab:duplicate";

package/lib/fileBrowser/commands.js

@@ -1,8 +1,10 @@
 import { Clipboard, Dialog, InputDialog, showDialog, showErrorMessage } from '@jupyterlab/apputils';
 import { PageConfig, PathExt } from '@jupyterlab/coreutils';
 import { nullTranslator } from '@jupyterlab/translation';
-import { addIcon, closeIcon, collapseAllIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, filterIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
+import { addIcon, closeIcon, collapseAllIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, filterIcon, LabIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
+import { CommandIDs as GitCommandIDs } from '../git/commands';
 import { toCanonicalPath, toServerPath } from './contents';
+import { GIT_REPO_PATH } from './gitStatus';
 import { FILE_BROWSER_ID } from './widget';
 /**
  * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
@@ -13,6 +15,7 @@ export var CommandIDs;
 (function (CommandIDs) {
     CommandIDs.open = 'xtralab:open';
     CommandIDs.openBrowserTab = 'xtralab:open-browser-tab';
+    CommandIDs.openGitDiff = 'xtralab:open-git-diff';
     CommandIDs.rename = 'xtralab:rename';
     CommandIDs.del = 'xtralab:delete';
     CommandIDs.duplicate = 'xtralab:duplicate';
@@ -66,6 +69,19 @@ function getOpenPaths(app, browser) {
     }
     return candidates.filter(path => !path.endsWith('/'));
 }
+/**
+ * Git changes of the target file, at most one staged and one unstaged.
+ * Status paths are repo-relative; like the tree's git badges, this assumes
+ * the repo root is the server root.
+ */
+function getTargetChanges(app, browser) {
+    const targetPath = getTargetPath(app, browser);
+    if (targetPath === undefined) {
+        return [];
+    }
+    const serverPath = toServerPath(targetPath);
+    return browser.gitChanges.filter(change => change.path === serverPath);
+}
 function hasTarget(app, browser) {
     return getTargetPath(app, browser) !== undefined;
 }
@@ -148,6 +164,16 @@ function makeOpenWithUpdater(app, browser) {
             args: { factory: factory.name, label: factory.label || factory.name },
             command: CommandIDs.open
         }));
+        const changes = getTargetChanges(app, browser);
+        if (changes.length > 0) {
+            items.push(submenu.addItem({ type: 'separator' }));
+            for (const change of changes) {
+                items.push(submenu.addItem({
+                    args: { group: change.group },
+                    command: CommandIDs.openGitDiff
+                }));
+            }
+        }
     };
 }
 /**
@@ -204,6 +230,25 @@ export function registerCommands(opts) {
             });
         }
     });
+    commands.addCommand(CommandIDs.openGitDiff, {
+        label: args => args.group === 'staged'
+            ? trans.__('Git Diff (Staged)')
+            : trans.__('Git Diff (Working)'),
+        icon: LabIcon.resolve({ icon: 'git:diff' }).bindprops({
+            stylesheet: 'menuItem'
+        }),
+        execute: async (args) => {
+            const change = getTargetChanges(app, browser).find(candidate => candidate.group === args.group);
+            if (change === undefined) {
+                return;
+            }
+            const diffArgs = {
+                repoPath: GIT_REPO_PATH,
+                change
+            };
+            return commands.execute(GitCommandIDs.openDiff, diffArgs);
+        }
+    });
     commands.addCommand(CommandIDs.rename, {
         label: trans.__('Rename…'),
         icon: editIcon.bindprops({ stylesheet: 'menuItem' }),

package/lib/fileBrowser/fileBrowser.js

@@ -7,7 +7,7 @@ import { FileTree, useFileTree } from '@pierre/trees/react';
 import { ROOT_LOAD_KEY, listDirectory, parentOf, toServerPath } from './contents';
 import { computeDropMoves, computeRootDropMoves, createTreeDragAndDropConfig, useRootDropZone } from './dragAndDrop';
 import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
-import { loadGitStatusEntries } from './gitStatus';
+import { GIT_REPO_PATH, loadGitChanges, toGitStatusEntries } from './gitStatus';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
  * Git status poll cadence, aligned with the git panel's polling so both
@@ -21,11 +21,6 @@ const GIT_STATUS_POLL_MAX_MS = 300000;
  */
 const FILE_LISTING_REFRESH_INTERVAL_MS = 10000;
 const FILE_LISTING_REFRESH_MAX_MS = 300000;
-/**
- * Repo path for `/git/*` calls; empty means the server root, letting git
- * resolve the enclosing repo (same convention as the git panel).
- */
-const GIT_REPO_PATH = '';
 const FILE_TREE_TAG = 'file-tree-container';
 /**
  * Injected into the tree's shadow root, where outside CSS cannot reach.
@@ -103,11 +98,12 @@ export function FileBrowserComponent(props) {
             syncGitStatus();
         };
         const refreshGitStatus = async () => {
-            const next = await loadGitStatusEntries(GIT_REPO_PATH);
+            const changes = await loadGitChanges(GIT_REPO_PATH);
             if (cancelled) {
                 return;
             }
-            gitStatusEntries = next;
+            gitStatusEntries = toGitStatusEntries(changes);
+            widget === null || widget === void 0 ? void 0 : widget.updateGitChanges(changes);
             syncGitStatus();
         };
         const fetchDirectory = async (canonicalPath) => {

package/lib/fileBrowser/gitStatus.d.ts

@@ -1,8 +1,19 @@
 import type { GitStatusEntry } from '@pierre/trees';
+import type { IFileChange } from '../git/tokens';
 /**
- * Fetch the porcelain status for `repoPath` as `GitStatusEntry` values.
- * Any failure yields an empty array — the file browser must work without
- * git. A file both staged and unstaged gets one entry, the unstaged status
- * winning (mirrors what is on disk, matching VS Code).
+ * Repo path for `/git/*` calls; empty means the server root, letting git
+ * resolve the enclosing repo (same convention as the git panel).
  */
-export declare function loadGitStatusEntries(repoPath: string): Promise<GitStatusEntry[]>;
+export declare const GIT_REPO_PATH = "";
+/**
+ * Fetch the porcelain status for `repoPath`, one entry per staged or
+ * unstaged change. Any failure yields an empty array — the file browser
+ * must work without git.
+ */
+export declare function loadGitChanges(repoPath: string): Promise<IFileChange[]>;
+/**
+ * Collapse changes into the tree's `GitStatusEntry` values. A file both
+ * staged and unstaged gets one entry, the unstaged status winning (mirrors
+ * what is on disk, matching VS Code).
+ */
+export declare function toGitStatusEntries(changes: readonly IFileChange[]): GitStatusEntry[];

package/lib/fileBrowser/gitStatus.js

@@ -1,4 +1,9 @@
 import { expandStatusFiles, status } from '../git/api';
+/**
+ * Repo path for `/git/*` calls; empty means the server root, letting git
+ * resolve the enclosing repo (same convention as the git panel).
+ */
+export const GIT_REPO_PATH = '';
 /**
  * Translate a `jupyterlab_git` porcelain status into a `@pierre/trees`
  * `GitStatus`. The tree only supports the six common statuses, so the rare
@@ -20,31 +25,37 @@ function toTreeStatus(value) {
     }
 }
 /**
- * Fetch the porcelain status for `repoPath` as `GitStatusEntry` values.
- * Any failure yields an empty array — the file browser must work without
- * git. A file both staged and unstaged gets one entry, the unstaged status
- * winning (mirrors what is on disk, matching VS Code).
+ * Fetch the porcelain status for `repoPath`, one entry per staged or
+ * unstaged change. Any failure yields an empty array — the file browser
+ * must work without git.
  */
-export async function loadGitStatusEntries(repoPath) {
+export async function loadGitChanges(repoPath) {
     try {
         const result = await status(repoPath);
         if (result.code !== 0) {
             return [];
         }
-        const changes = expandStatusFiles(result.files);
-        const byPath = new Map();
-        for (const change of changes) {
-            if (change.group === 'unstaged' || !byPath.has(change.path)) {
-                byPath.set(change.path, change.status);
-            }
-        }
-        const entries = [];
-        byPath.forEach((value, path) => {
-            entries.push({ path, status: toTreeStatus(value) });
-        });
-        return entries;
+        return expandStatusFiles(result.files);
     }
     catch (_a) {
         return [];
     }
 }
+/**
+ * Collapse changes into the tree's `GitStatusEntry` values. A file both
+ * staged and unstaged gets one entry, the unstaged status winning (mirrors
+ * what is on disk, matching VS Code).
+ */
+export function toGitStatusEntries(changes) {
+    const byPath = new Map();
+    for (const change of changes) {
+        if (change.group === 'unstaged' || !byPath.has(change.path)) {
+            byPath.set(change.path, change.status);
+        }
+    }
+    const entries = [];
+    byPath.forEach((value, path) => {
+        entries.push({ path, status: toTreeStatus(value) });
+    });
+    return entries;
+}

package/lib/fileBrowser/widget.d.ts

@@ -5,6 +5,7 @@ import { ITranslator } from '@jupyterlab/translation';
 import { Toolbar } from '@jupyterlab/ui-components';
 import { ISignal } from '@lumino/signaling';
 import { AccordionPanel, Widget } from '@lumino/widgets';
+import type { IFileChange } from '../git/tokens';
 export declare const FILE_BROWSER_ID = "xtralab:file-browser";
 /**
  * The options used to create an {@link XtralabFileBrowser}.
@@ -51,6 +52,11 @@ export interface IXtralabFileBrowser {
      * Emits when the tree's selection changes.
      */
     readonly selectionChanged: ISignal<IXtralabFileBrowser, readonly string[]>;
+    /**
+     * Git changes from the latest status poll, one per staged or unstaged
+     * change; paths are repo-relative.
+     */
+    readonly gitChanges: readonly IFileChange[];
     /**
      * Emits when {@link refresh} is called.
      */
@@ -142,6 +148,10 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
      * A signal emitted when the tree's selection changes.
      */
     get selectionChanged(): ISignal<this, readonly string[]>;
+    /**
+     * Git changes from the latest status poll.
+     */
+    get gitChanges(): readonly IFileChange[];
     /**
      * A signal emitted when {@link refresh} is called.
      */
@@ -174,6 +184,10 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
      * Update the cached selection from the React tree.
      */
     updateSelection(paths: readonly string[]): void;
+    /**
+     * Update the cached git changes from the React tree's status poll.
+     */
+    updateGitChanges(changes: readonly IFileChange[]): void;
     /**
      * Trigger a refresh of every loaded directory in the tree.
      */
@@ -267,6 +281,7 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     private _translator;
     private _selectedPaths;
     private _selectionChanged;
+    private _gitChanges;
     private _refreshRequested;
     private _pathAdded;
     private _revealRequested;

package/lib/fileBrowser/widget.js

@@ -29,6 +29,7 @@ export class XtralabFileBrowser extends Widget {
         super();
         this._selectedPaths = [];
         this._selectionChanged = new Signal(this);
+        this._gitChanges = [];
         this._refreshRequested = new Signal(this);
         this._pathAdded = new Signal(this);
         this._revealRequested = new Signal(this);
@@ -92,6 +93,12 @@ export class XtralabFileBrowser extends Widget {
     get selectionChanged() {
         return this._selectionChanged;
     }
+    /**
+     * Git changes from the latest status poll.
+     */
+    get gitChanges() {
+        return this._gitChanges;
+    }
     /**
      * A signal emitted when {@link refresh} is called.
      */
@@ -141,6 +148,12 @@ export class XtralabFileBrowser extends Widget {
         this._selectedPaths = paths;
         this._selectionChanged.emit(paths);
     }
+    /**
+     * Update the cached git changes from the React tree's status poll.
+     */
+    updateGitChanges(changes) {
+        this._gitChanges = changes;
+    }
     /**
      * Trigger a refresh of every loaded directory in the tree.
      */

package/lib/git/commands.d.ts

@@ -5,6 +5,7 @@ import { Contents } from '@jupyterlab/services';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import { ISignal } from '@lumino/signaling';
 import type { IAskAgent } from '../askAgent/tokens';
+import type { IDiffPreferences } from './diffPreferences';
 import { XtralabDiffWidget } from './diffWidget';
 import { IFileChange } from './tokens';
 /**
@@ -94,6 +95,10 @@ interface IRegisterGitCommandsOptions {
      * Ask-agent popup for prompting an agent about diff lines; may be `null`.
      */
     askAgent: IAskAgent | null;
+    /**
+     * The display choices shared by all diff views.
+     */
+    preferences: IDiffPreferences;
     /**
      * Translation bundle for user-facing strings.
      */

package/lib/git/commands.js

@@ -76,9 +76,9 @@ export class DiffMainAreaWidget extends MainAreaWidget {
 }
 function createDiffWidget(options) {
     var _a;
-    const { repoPath, change, themeManager, contentsManager, rendermime, askAgent, trans } = options;
+    const { repoPath, change, themeManager, contentsManager, rendermime, askAgent, preferences, trans } = options;
     const pinned = options.pinned === true;
-    const content = new XtralabDiffWidget(fileChangeToDiffModel(repoPath, change), { contentsManager, rendermime, themeManager, askAgent, trans });
+    const content = new XtralabDiffWidget(fileChangeToDiffModel(repoPath, change), { contentsManager, rendermime, themeManager, askAgent, preferences, trans });
     const widget = new DiffMainAreaWidget({ content }, change, pinned, trans);
     widget.id = pinned ? pinnedDiffWidgetId(change) : PREVIEW_DIFF_WIDGET_ID;
     widget.title.label = formatTitle(change, trans);
@@ -145,7 +145,7 @@ function createDiffWidget(options) {
  * Register the launcher's git diff command.
  */
 export function registerGitCommands(options) {
-    const { app, themeManager, contentsManager, rendermime, askAgent, trans, trackDiff, findDiff, onPinned } = options;
+    const { app, themeManager, contentsManager, rendermime, askAgent, preferences, trans, trackDiff, findDiff, onPinned } = options;
     const { commands } = app;
     commands.addCommand(CommandIDs.openDiff, {
         label: trans.__('Open Git Diff'),
@@ -171,6 +171,7 @@ export function registerGitCommands(options) {
                 contentsManager,
                 rendermime,
                 askAgent,
+                preferences,
                 trans,
                 pinned: pin,
                 onPinned

package/lib/git/diffPreferences.d.ts

@@ -0,0 +1,90 @@
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import type { IStateDB } from '@jupyterlab/statedb';
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+export type DiffStyle = 'split' | 'unified';
+export type DiffStyleControlMode = 'buttons' | 'toggle';
+export type NotebookDiffViewMode = 'notebook' | 'json';
+export type ImageDiffViewMode = '2-up' | 'swipe' | 'onion';
+export declare const MIN_SPLIT_RATIO = 0.1;
+export declare const MAX_SPLIT_RATIO = 0.9;
+export declare const DEFAULT_SPLIT_RATIO = 0.5;
+/**
+ * Display choices shared by every diff view. The toggles live in the
+ * plugin settings; the split width lives in the state database.
+ */
+export interface IDiffPreferences {
+    /**
+     * The current values; a new object after each change.
+     */
+    readonly values: IDiffPreferences.IValues;
+    /**
+     * A signal emitted when any value changes.
+     */
+    readonly changed: ISignal<IDiffPreferences, void>;
+    /**
+     * Change some values and persist them.
+     */
+    update(values: Partial<IDiffPreferences.IValues>): void;
+}
+export declare namespace IDiffPreferences {
+    /**
+     * The diff display values.
+     */
+    interface IValues {
+        /**
+         * Split or unified layout for textual file diffs.
+         */
+        diffStyle: DiffStyle;
+        /**
+         * Two toolbar buttons for the layout, or one button that toggles it.
+         */
+        diffStyleControl: DiffStyleControlMode;
+        /**
+         * Whether long lines wrap instead of scrolling horizontally.
+         */
+        lineWrap: boolean;
+        /**
+         * Rendered or JSON view for notebook diffs.
+         */
+        notebookViewMode: NotebookDiffViewMode;
+        /**
+         * Comparison mode for image diffs.
+         */
+        imageViewMode: ImageDiffViewMode;
+        /**
+         * Width of the left pane in split view, as a fraction of the diff width.
+         */
+        splitRatio: number;
+    }
+}
+export declare const IDiffPreferences: Token<IDiffPreferences>;
+/**
+ * {@link IDiffPreferences} backed by the settings registry and the state
+ * database. Without them it keeps the values in memory only.
+ */
+export declare class DiffPreferences implements IDiffPreferences {
+    get values(): IDiffPreferences.IValues;
+    get changed(): ISignal<this, void>;
+    update(values: Partial<IDiffPreferences.IValues>): void;
+    /**
+     * Read the toggles from the plugin settings and follow their changes.
+     */
+    connectSettings(settings: ISettingRegistry.ISettings): void;
+    /**
+     * Restore the split width from the state database and save it there.
+     */
+    connectState(state: IStateDB): Promise<void>;
+    /**
+     * Merge values without persisting them; return whether one changed.
+     */
+    private _apply;
+    private _values;
+    private _changed;
+    private _settings;
+    private _state;
+}
+/**
+ * Re-render on every preference change and return the current values.
+ */
+export declare function useDiffPreferences(preferences: IDiffPreferences): IDiffPreferences.IValues;