xtralab 0.1.1 → 0.2.0

package/README.md

@@ -35,6 +35,61 @@ override versions and Jupyter configuration in the usual ways.
   `jupyterlab-git` server REST API and `@pierre/diffs`. The bundled
   `@jupyterlab/git` frontend is disabled automatically so the two panels do
   not coexist.
+- An agent-focused launcher that replaces the stock JupyterLab launcher.
+  The launcher tab shows an optional initial-prompt textarea, a row of
+  agent buttons (Claude, Codex, Gemini, Copilot, Goose, OpenCode, Kiro,
+  and Mistral Vibe), and a collapsible list of changed files (each
+  clickable into the diff viewer) below them. Clicking an agent opens a
+  fresh terminal and runs the agent's CLI; if the prompt textarea is
+  non-empty, the prompt is shell-quoted and spliced into the launch line
+  for agents that accept one. Agents are filtered by a `which`-based
+  availability check at activation, so only the ones actually installed
+  on the machine show up.
+
+### Customizing the launcher
+
+The launcher reads `xtralab:launcher` settings from the JupyterLab settings
+registry. Open the Settings Editor (`Settings → Settings Editor → xtralab
+launcher`) and edit the `agents` array; xtralab merges your entries with
+the defaults by `id`.
+
+```jsonc
+{
+  "agents": [
+    // Hide an agent you never want to see, even if it's installed:
+    { "id": "kiro", "enabled": false },
+
+    // Override an agent's command — e.g. point Claude at a shell alias.
+    // `requireAvailable: false` keeps the card visible even though
+    // `which cl` returns nothing (interactive shells expand the alias).
+    { "id": "claude", "command": "cl", "requireAvailable": false },
+
+    // Add a brand-new agent. `iconSvg` is optional; without it the card
+    // falls back to a generic terminal icon. `promptArgs: []` means the
+    // launcher's prompt textarea is appended as a positional argument.
+    {
+      "id": "aider",
+      "label": "Aider",
+      "command": "aider",
+      "promptArgs": []
+    }
+  ]
+}
+```
+
+Field reference (every field except `id` is optional):
+
+| Field              | Effect                                                                                                                                                                                                                                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Built-in id to override, or a new id to define a new card.                                                                                                                                                                                                                                                                                         |
+| `label`            | Card title.                                                                                                                                                                                                                                                                                                                                        |
+| `caption`          | Subtitle shown beneath the title.                                                                                                                                                                                                                                                                                                                  |
+| `command`          | Literal text typed into the new terminal.                                                                                                                                                                                                                                                                                                          |
+| `iconSvg`          | Inline SVG for the card icon (only needed for new agents).                                                                                                                                                                                                                                                                                         |
+| `rank`             | Sort order on the launcher; lower comes first.                                                                                                                                                                                                                                                                                                     |
+| `enabled`          | `false` hides the card from the launcher and palette.                                                                                                                                                                                                                                                                                              |
+| `requireAvailable` | `false` skips the `which` check (use for shell aliases that aren't on PATH but expand at runtime).                                                                                                                                                                                                                                                 |
+| `promptArgs`       | How to splice the launcher's optional prompt into the command. `[]` appends it as a positional argument (`<command> 'PROMPT'`); `["-i"]` or `["--prompt"]` puts it after a flag. Set to `null` to opt out — the agent button is dimmed when the prompt textarea is non-empty so a typed prompt is never silently dropped. Defaults vary per agent. |
 
 ## Default settings
 
@@ -44,6 +99,12 @@ override versions and Jupyter configuration in the usual ways.
   news from the Jupyter news feed and does not check for application updates.
 - The Table of Contents, Debugger, and Notebook Tools panels are disabled so
   they do not show up in the right sidebar by default.
+- `dockPanelPadding` is off, so the main dock area is flush with the
+  surrounding chrome.
+- The terminal `fontFamily` defaults to `MesloLGS NF, ui-monospace, monospace`
+  so Powerline / Nerd Font glyphs (used by Oh My Zsh themes such as
+  `powerlevel10k`) render correctly when the font is installed; the
+  `ui-monospace, monospace` fallback keeps things readable when it is not.
 
 The JupyterLab frontend defaults are shipped as `labconfig/*.d/00-xtralab.json`
 fragments so downstream meta-packages can add their own Lab configuration
@@ -55,6 +116,31 @@ fragments without replacing `xtralab`'s files.
 pip install xtralab
 ```
 
+## Run as a desktop app
+
+`xtralab` ships a tiny launcher that opens JupyterLab in a dedicated Chrome
+window (via Chrome's `--app` mode), with an isolated user-data directory so it
+does not share cookies, extensions, or history with your normal browser.
+
+Requires Chrome or Chromium installed. macOS only for now; other platforms will be added later.
+
+The simplest way, no install needed:
+
+```bash
+uvx xtralab
+```
+
+Or, after `pip install xtralab` into an environment:
+
+```bash
+xtralab
+```
+
+The launcher starts a local Jupyter server on a random port with a fresh
+token, waits for it to come up, opens the app window, and shuts the server
+down when you close the window. `Ctrl-C` in the launching terminal also
+shuts everything down cleanly.
+
 ## Development
 
 ```bash

package/lib/fileBrowser/fileBrowser.js

@@ -4,6 +4,7 @@ import { MimeData, PromiseDelegate } from '@lumino/coreutils';
 import { Drag } from '@lumino/dragdrop';
 import { FileTree, useFileTree } from '@pierre/trees/react';
 import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
+import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
  * MIME types used by the dock panel and other JupyterLab drop targets.
@@ -41,11 +42,54 @@ export function FileBrowserComponent(props) {
         paths: [],
         initialExpansion: 'closed',
         search: true,
-        icons: FILE_BROWSER_ICONS
+        icons: FILE_BROWSER_ICONS,
+        itemHeight: 24
     });
     React.useEffect(() => {
         const knownDirs = new Map();
+        // Mirror of the canonical paths currently loaded into the tree. Kept in
+        // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
+        // re-test every loaded path against the gitignore matcher whenever
+        // either side changes — the model itself does not expose a
+        // path-iteration API.
+        const loadedPaths = new Set();
+        let gitignoreMatcher = null;
         let cancelled = false;
+        /**
+         * Recompute the `ignored` git status entries from the current
+         * gitignore matcher and the set of loaded paths, and push them into
+         * the tree. Safe to call at any time: when the matcher is `null`
+         * (no `.gitignore` or it failed to load) we send an empty list, which
+         * also clears any statuses that may have been applied previously.
+         */
+        const syncGitStatus = () => {
+            if (gitignoreMatcher === null) {
+                model.setGitStatus([]);
+                return;
+            }
+            const entries = buildIgnoredEntries(gitignoreMatcher, loadedPaths);
+            model.setGitStatus(entries);
+        };
+        /**
+         * Reload the workspace `.gitignore`, then re-apply the resulting
+         * ignored statuses. Called on initial mount and whenever the user
+         * triggers a refresh — the file may have been edited or created in
+         * between.
+         */
+        const refreshGitignoreMatcher = async () => {
+            let next = null;
+            try {
+                next = await loadGitignoreMatcher(contentsManager);
+            }
+            catch (err) {
+                console.error('xtralab: failed to load .gitignore', err);
+            }
+            if (cancelled) {
+                return;
+            }
+            gitignoreMatcher = next;
+            syncGitStatus();
+        };
         const fetchDirectory = async (canonicalPath) => {
             const current = knownDirs.get(canonicalPath);
             if (current === 'loading' || current === 'loaded') {
@@ -60,6 +104,10 @@ export function FileBrowserComponent(props) {
                 }
                 if (canonicalPath === ROOT_LOAD_KEY) {
                     model.resetPaths(paths);
+                    loadedPaths.clear();
+                    for (const path of paths) {
+                        loadedPaths.add(path);
+                    }
                 }
                 else {
                     // Filter out paths already in the model. The path-store throws
@@ -72,6 +120,14 @@ export function FileBrowserComponent(props) {
                     if (operations.length > 0) {
                         model.batch(operations);
                     }
+                    // Mirror every directory child into `loadedPaths` regardless of
+                    // whether it was just added or skipped above — paths skipped by
+                    // the filter are already in the model from a prior add and so
+                    // belong in the mirror too. `Set.add` is idempotent, so the
+                    // duplicate adds are a no-op.
+                    for (const path of paths) {
+                        loadedPaths.add(path);
+                    }
                 }
                 for (const subdir of subdirectories) {
                     if (!knownDirs.has(subdir)) {
@@ -79,6 +135,7 @@ export function FileBrowserComponent(props) {
                     }
                 }
                 knownDirs.set(canonicalPath, 'loaded');
+                syncGitStatus();
             }
             catch (err) {
                 console.error(`xtralab: failed to load directory "${canonicalPath}"`, err);
@@ -165,12 +222,22 @@ export function FileBrowserComponent(props) {
             // Reset the tree contents and restore the load-state map so future
             // expansions know which directories still need fetching.
             model.resetPaths(allPaths);
+            loadedPaths.clear();
+            for (const path of allPaths) {
+                loadedPaths.add(path);
+            }
             knownDirs.set(ROOT_LOAD_KEY, 'loaded');
             subdirsByParent.forEach(subdirs => {
                 for (const subdir of subdirs) {
                     knownDirs.set(subdir, expandedPaths.has(subdir) ? 'loaded' : 'unloaded');
                 }
             });
+            // Refresh the `.gitignore` matcher in case the file was edited
+            // since the last load, then re-apply the resulting statuses to the
+            // newly-loaded paths. The reload runs in parallel with the rest of
+            // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
+            // itself when it completes.
+            void refreshGitignoreMatcher();
             // Re-expand the directories that were expanded before the refresh.
             // We have to do this after `resetPaths` because the reset starts
             // every directory in its initial collapsed state.
@@ -196,12 +263,14 @@ export function FileBrowserComponent(props) {
                     return;
                 }
             }
+            loadedPaths.add(canonicalPath);
             if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
                 // The new directory has no children yet, so mark it as already
                 // loaded — there's nothing to fetch and we don't want a stale
                 // "unloaded" entry to trigger a fetch on the next expand.
                 knownDirs.set(canonicalPath, 'loaded');
             }
+            syncGitStatus();
             const parent = parentOf(canonicalPath);
             if (parent === ROOT_LOAD_KEY) {
                 return;
@@ -217,6 +286,7 @@ export function FileBrowserComponent(props) {
         };
         knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
         void fetchDirectory(ROOT_LOAD_KEY);
+        void refreshGitignoreMatcher();
         const unsubscribe = model.subscribe(() => {
             knownDirs.forEach((state, canonicalPath) => {
                 if (state !== 'unloaded') {

package/lib/fileBrowser/gitignore.d.ts

@@ -0,0 +1,29 @@
+import type { Ignore } from 'ignore';
+import { Contents } from '@jupyterlab/services';
+import type { GitStatusEntry } from '@pierre/trees';
+/**
+ * Load the workspace `.gitignore` and return an `ignore` matcher built from
+ * its contents. Returns `null` when the file is missing, empty, or fails to
+ * load — callers should treat any of those as "no ignored entries".
+ */
+export declare function loadGitignoreMatcher(contentsManager: Contents.IManager): Promise<Ignore | null>;
+/**
+ * Build `GitStatusEntry`s for the canonical paths that match the given
+ * gitignore matcher.
+ *
+ * `@pierre/trees` propagates the `ignored` style from a directory entry
+ * down to every descendant via its internal `ignoredDirectoryPaths` set, so
+ * we only emit one entry per ignored subtree root: emitting descendants
+ * would also pollute the library's `directoriesWithChanges` set, causing
+ * parent directories of nested ignored items to render a "contains git
+ * status items" dot.
+ *
+ * Paths are sorted lexicographically so a directory always precedes its
+ * descendants, allowing a simple ancestor-suppression check via
+ * `path.startsWith(dir)`. The trailing slash on canonical directory paths
+ * (required by `@pierre/trees`, also recognized by `ignore` as the
+ * "directory" indicator) keeps the prefix check from accidentally matching
+ * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
+ * vs `node_modules/`).
+ */
+export declare function buildIgnoredEntries(matcher: Ignore, canonicalPaths: Iterable<string>): GitStatusEntry[];

package/lib/fileBrowser/gitignore.js

@@ -0,0 +1,74 @@
+import ignore from 'ignore';
+/**
+ * The path of the workspace `.gitignore` file. Loaded relative to the
+ * Jupyter contents root, which matches the directory the gitignore patterns
+ * are evaluated against — patterns and tested paths share the same base.
+ */
+const GITIGNORE_PATH = '.gitignore';
+/**
+ * Load the workspace `.gitignore` and return an `ignore` matcher built from
+ * its contents. Returns `null` when the file is missing, empty, or fails to
+ * load — callers should treat any of those as "no ignored entries".
+ */
+export async function loadGitignoreMatcher(contentsManager) {
+    let model;
+    try {
+        model = await contentsManager.get(GITIGNORE_PATH, {
+            content: true,
+            format: 'text',
+            type: 'file'
+        });
+    }
+    catch (_a) {
+        // The most common failure here is `.gitignore` simply not existing.
+        // Other transient errors (permission denied, server unreachable) are
+        // also treated as "no matcher" so the file browser still works.
+        return null;
+    }
+    if (model.type !== 'file' || typeof model.content !== 'string') {
+        return null;
+    }
+    if (model.content.length === 0) {
+        return null;
+    }
+    return ignore().add(model.content);
+}
+/**
+ * Build `GitStatusEntry`s for the canonical paths that match the given
+ * gitignore matcher.
+ *
+ * `@pierre/trees` propagates the `ignored` style from a directory entry
+ * down to every descendant via its internal `ignoredDirectoryPaths` set, so
+ * we only emit one entry per ignored subtree root: emitting descendants
+ * would also pollute the library's `directoriesWithChanges` set, causing
+ * parent directories of nested ignored items to render a "contains git
+ * status items" dot.
+ *
+ * Paths are sorted lexicographically so a directory always precedes its
+ * descendants, allowing a simple ancestor-suppression check via
+ * `path.startsWith(dir)`. The trailing slash on canonical directory paths
+ * (required by `@pierre/trees`, also recognized by `ignore` as the
+ * "directory" indicator) keeps the prefix check from accidentally matching
+ * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
+ * vs `node_modules/`).
+ */
+export function buildIgnoredEntries(matcher, canonicalPaths) {
+    const sorted = Array.from(canonicalPaths).sort();
+    const emittedIgnoredDirs = [];
+    const entries = [];
+    for (const path of sorted) {
+        if (path.length === 0) {
+            continue;
+        }
+        if (emittedIgnoredDirs.some(dir => path.startsWith(dir))) {
+            continue;
+        }
+        if (matcher.ignores(path)) {
+            entries.push({ path, status: 'ignored' });
+            if (path.endsWith('/')) {
+                emittedIgnoredDirs.push(path);
+            }
+        }
+    }
+    return entries;
+}

package/lib/fileBrowser/index.js

@@ -22,7 +22,7 @@ const plugin = {
                 void app.commands.execute('docmanager:open', { path: serverPath });
             }
         });
-        app.shell.add(browser, 'left', { rank: 700 });
+        app.shell.add(browser, 'left', { rank: 50 });
         if (restorer) {
             restorer.add(browser, browser.id);
         }

package/lib/git/api.d.ts

@@ -28,6 +28,17 @@ export declare function reset(repoPath: string, filename: string): Promise<void>
 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>;
+/**
+ * Expand the porcelain `files` array into one entry per logical change.
+ * A single porcelain row may map to two `IFileChange` rows (a file that's
+ * both staged and modified again in the worktree); callers that just want
+ * a flat list of all changes — without any staged-vs-unstaged grouping —
+ * can use this helper.
+ *
+ * Provided as a manual concat rather than `Array.prototype.flatMap` so we
+ * don't pin our `tsconfig.lib` to ES2019.
+ */
+export declare function expandStatusFiles(files: IGitStatusFile[]): IFileChange[];
 /**
  * Translate one entry in the porcelain `files` array into the panel's
  * preferred shape. A single porcelain entry may represent up to two changes

package/lib/git/api.js

@@ -103,6 +103,25 @@ export async function checkout(repoPath, filename) {
         filename
     });
 }
+/**
+ * Expand the porcelain `files` array into one entry per logical change.
+ * A single porcelain row may map to two `IFileChange` rows (a file that's
+ * both staged and modified again in the worktree); callers that just want
+ * a flat list of all changes — without any staged-vs-unstaged grouping —
+ * can use this helper.
+ *
+ * Provided as a manual concat rather than `Array.prototype.flatMap` so we
+ * don't pin our `tsconfig.lib` to ES2019.
+ */
+export function expandStatusFiles(files) {
+    const result = [];
+    for (const file of files) {
+        for (const change of porcelainToFileChanges(file)) {
+            result.push(change);
+        }
+    }
+    return result;
+}
 /**
  * Translate one entry in the porcelain `files` array into the panel's
  * preferred shape. A single porcelain entry may represent up to two changes

package/lib/git/commands.d.ts

@@ -24,6 +24,7 @@ export declare namespace CommandArguments {
     interface IOpenDiff {
         repoPath: string;
         change: IFileChange;
+        pin?: boolean;
     }
 }
 export interface IRegisterGitCommandsOptions {
@@ -58,7 +59,8 @@ export interface IRegisterGitCommandsOptions {
      * 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;
+    findDiff(change: IFileChange, pin?: boolean): ReturnType<typeof createGitDiffWidget> | undefined;
+    onPinned(widget: ReturnType<typeof createGitDiffWidget>): void;
 }
 /**
  * Register the git commands on the application command registry. Returns

package/lib/git/commands.js

@@ -1,5 +1,5 @@
 import { refreshIcon } from '@jupyterlab/ui-components';
-import { createGitDiffWidget, diffWidgetId } from './diffWidget';
+import { createGitDiffWidget, diffWidgetId, updateGitDiffWidget } from './diffWidget';
 /**
  * Command IDs exposed by the git plugin. Both are registered in
  * {@link registerGitCommands} so other extensions, the command palette and
@@ -16,7 +16,7 @@ export var CommandIDs;
  * (the commands themselves stay registered for the lifetime of the plugin).
  */
 export function registerGitCommands(options) {
-    const { app, panel, themeManager, commandPalette, contentsManager, rendermime, onChanged, trackDiff, findDiff } = options;
+    const { app, panel, themeManager, commandPalette, contentsManager, rendermime, onChanged, trackDiff, findDiff, onPinned } = options;
     const { commands } = app;
     commands.addCommand(CommandIDs.refresh, {
         label: 'Refresh Git Changes',
@@ -34,8 +34,12 @@ export function registerGitCommands(options) {
             if ((typed === null || typed === void 0 ? void 0 : typed.change) === undefined) {
                 return;
             }
-            const existing = findDiff(typed.change);
+            const pin = typed.pin === true;
+            const existing = findDiff(typed.change, pin);
             if (existing !== undefined && !existing.isDisposed) {
+                if (!pin) {
+                    updateGitDiffWidget(existing, typed.change);
+                }
                 app.shell.activateById(existing.id);
                 return;
             }
@@ -45,7 +49,9 @@ export function registerGitCommands(options) {
                 themeManager,
                 contentsManager,
                 rendermime,
-                onChanged
+                onChanged,
+                pinned: pin,
+                onPinned
             });
             await trackDiff(widget);
             app.shell.add(widget, 'main', { mode: 'tab-after' });

package/lib/git/diffWidget.d.ts

@@ -10,6 +10,8 @@ import { GitReference, IFileChange } from './tokens';
  * style the embedded `@pierre/diffs` viewer hang off this class.
  */
 export declare const DIFF_WIDGET_CSS_CLASS = "jp-xtralab-DiffWidget";
+export declare const PREVIEW_DIFF_WIDGET_ID = "xtralab:diff:preview";
+export declare function pinnedDiffWidgetId(change: IFileChange): string;
 /**
  * View modes available for `.ipynb` diffs. `notebook` is the cell-by-cell
  * rendered view; `json` falls back to the raw nbformat JSON file diff so
@@ -58,6 +60,8 @@ export interface IGitDiffWidgetOptions {
      * would just be visual noise.
      */
     onEmpty?: () => void;
+    onPinned?: (widget: MainAreaWidget<DiffContentWidget>) => void;
+    pinned?: boolean;
 }
 /**
  * Build a `MainAreaWidget`-hosted diff viewer for a single file change.
@@ -67,6 +71,7 @@ export interface IGitDiffWidgetOptions {
  * read-only main-area widgets in the JupyterLab ecosystem.
  */
 export declare function createGitDiffWidget(options: IGitDiffWidgetOptions): MainAreaWidget<DiffContentWidget>;
+export declare function updateGitDiffWidget(widget: MainAreaWidget<DiffContentWidget>, change: IFileChange): void;
 /**
  * The actual React-rendered region of the diff viewer. Held in its own
  * `ReactWidget` so the surrounding `MainAreaWidget` can manage chrome
@@ -98,11 +103,17 @@ export declare class DiffContentWidget extends ReactWidget {
     setHasNotebookView(value: boolean): void;
     /** Emits whenever {@link hasNotebookView} changes. */
     get hasNotebookViewChanged(): ISignal<this, boolean>;
+    get pinned(): boolean;
+    pin(): void;
+    get pinnedChanged(): ISignal<this, boolean>;
+    setChange(change: IFileChange): void;
     protected render(): React.ReactElement;
     private _options;
     private _notebookViewMode;
     private _notebookViewModeChanged;
     private _hasNotebookView;
     private _hasNotebookViewChanged;
+    private _pinned;
+    private _pinnedChanged;
 }
 export {};