xtralab 0.1.2 → 0.3.0

package/lib/statusBar/widget.d.ts

@@ -0,0 +1,121 @@
+import type { MainAreaWidget } from '@jupyterlab/apputils';
+import type { ServiceManager } from '@jupyterlab/services';
+import type { ITerminal, ITerminalTracker } from '@jupyterlab/terminal';
+import { type TranslationBundle } from '@jupyterlab/translation';
+import { VDomModel, VDomRenderer } from '@jupyterlab/ui-components';
+import * as React from 'react';
+/**
+ * The widget shape every entry in `ITerminalTracker` takes — kept here
+ * so the registry's call sites read cleanly.
+ */
+export type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
+/**
+ * Source-of-truth model for the status bar. Each running terminal
+ * session known to the server is one entry; the registry caches the
+ * last `widget.title.label` we observed so the agent name (or any
+ * xterm-published title) survives the user closing the tab while the
+ * session continues running on the backend.
+ *
+ * Two upstream signals feed the model:
+ *   - `serviceManager.terminals.runningChanged` is the authoritative
+ *     list of live sessions; everything not in it has been shut down
+ *     server-side and we must drop it.
+ *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
+ *     `disposed` signals keep our label cache in sync with whatever
+ *     xterm/the launcher has set on the open tabs.
+ *
+ * `stateChanged` is reused for both kinds of update so consumers
+ * (the per-session status item, the plugin's add/remove sync) can
+ * subscribe once.
+ */
+export declare class SessionRegistry extends VDomModel {
+    constructor(serviceManager: ServiceManager.IManager, tracker: ITerminalTracker);
+    /**
+     * Names of all live sessions, ordered by their stable rank so the
+     * status bar items keep their slots as new sessions are added.
+     */
+    sessionNames(): string[];
+    /**
+     * True iff the named session is still on the server. Used by the
+     * per-session item to render `null` during the brief window between
+     * the session's shutdown and the plugin disposing the item.
+     */
+    has(name: string): boolean;
+    /**
+     * Display name for the session. The cache wins because it only
+     * holds "real" labels (the launcher's agent name or an xterm escape
+     * sequence — see `_cacheLabel` for the filter); reading it first
+     * prevents the transient `Terminal {name}` an XTerm widget shows
+     * during reconnect from flickering into the status bar. The live
+     * widget title is used when no cache exists, and the
+     * `Terminal {name}` fallback covers sessions we have never seen a
+     * widget for (e.g. surviving a lab reload).
+     */
+    labelFor(name: string): string;
+    /**
+     * Return the open widget for a session, if any. The status item
+     * uses this to switch behaviour between "activate existing tab"
+     * and "open a new tab connected to the live session".
+     */
+    widgetFor(name: string): TerminalWidget | null;
+    /**
+     * Stable per-session rank assigned in observation order. Reused
+     * across `registerStatusItem` calls so an item that is briefly
+     * unregistered (e.g. while a widget is being recreated) lands back
+     * in the same slot. Cleaned up when the session is shut down so the
+     * counter does not grow without bound across long sessions.
+     */
+    rankFor(name: string): number;
+    dispose(): void;
+    private _refreshLive;
+    private _onRunningChanged;
+    private _onWidgetAdded;
+    private _trackWidget;
+    private _untrackWidget;
+    private _onTitleChanged;
+    /**
+     * Update the cached label for a session, but only when the new
+     * label is "real" — non-empty and not one of the transient defaults
+     * the XTerm widget cycles through during reconnect (`'...'` while
+     * the websocket is opening, `'Terminal {name}'` once
+     * `_initialConnection` fires). Without the filter, briefly
+     * reopening a tab while an agent has yet to re-emit its xterm
+     * title escape sequence would clobber the cached agent name with
+     * `Terminal 1`, which is exactly the regression we are guarding
+     * against. Live widget titles still display whatever the widget
+     * currently holds because `labelFor` consults the widget first;
+     * the filter only affects what survives a tab close.
+     */
+    private _cacheLabel;
+    private _onWidgetDisposed;
+    private _terminals;
+    private _tracker;
+    private _labels;
+    private _ranks;
+    private _live;
+    private _nextRank;
+}
+/**
+ * One status bar item per live terminal session. Renders a terminal
+ * icon plus the session's label, with an inline shutdown button that
+ * appears on hover/focus. The item delegates click handling to the
+ * plugin so the lifecycle (create/dispose) and the user-facing
+ * behaviour (activate vs. reopen, shutdown) live in one place.
+ */
+export declare class TerminalSessionItem extends VDomRenderer<SessionRegistry> {
+    constructor(options: TerminalSessionItem.IOptions);
+    render(): React.ReactElement | null;
+    private _sessionName;
+    private _trans;
+    private _onActivate;
+    private _onShutdown;
+}
+export declare namespace TerminalSessionItem {
+    interface IOptions {
+        registry: SessionRegistry;
+        sessionName: string;
+        trans?: TranslationBundle;
+        onActivate: (sessionName: string) => void;
+        onShutdown: (sessionName: string) => void;
+    }
+}

package/lib/statusBar/widget.js

@@ -0,0 +1,237 @@
+import { nullTranslator } from '@jupyterlab/translation';
+import { closeIcon, terminalIcon, VDomModel, VDomRenderer } from '@jupyterlab/ui-components';
+import * as React from 'react';
+/**
+ * Source-of-truth model for the status bar. Each running terminal
+ * session known to the server is one entry; the registry caches the
+ * last `widget.title.label` we observed so the agent name (or any
+ * xterm-published title) survives the user closing the tab while the
+ * session continues running on the backend.
+ *
+ * Two upstream signals feed the model:
+ *   - `serviceManager.terminals.runningChanged` is the authoritative
+ *     list of live sessions; everything not in it has been shut down
+ *     server-side and we must drop it.
+ *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
+ *     `disposed` signals keep our label cache in sync with whatever
+ *     xterm/the launcher has set on the open tabs.
+ *
+ * `stateChanged` is reused for both kinds of update so consumers
+ * (the per-session status item, the plugin's add/remove sync) can
+ * subscribe once.
+ */
+export class SessionRegistry extends VDomModel {
+    constructor(serviceManager, tracker) {
+        super();
+        this._labels = new Map();
+        this._ranks = new Map();
+        this._live = new Set();
+        this._nextRank = 100;
+        this._terminals = serviceManager.terminals;
+        this._tracker = tracker;
+        this._terminals.runningChanged.connect(this._onRunningChanged, this);
+        this._tracker.widgetAdded.connect(this._onWidgetAdded, this);
+        this._tracker.forEach(widget => this._trackWidget(widget));
+        this._refreshLive();
+    }
+    /**
+     * Names of all live sessions, ordered by their stable rank so the
+     * status bar items keep their slots as new sessions are added.
+     */
+    sessionNames() {
+        const names = Array.from(this._live);
+        names.sort((a, b) => this.rankFor(a) - this.rankFor(b));
+        return names;
+    }
+    /**
+     * True iff the named session is still on the server. Used by the
+     * per-session item to render `null` during the brief window between
+     * the session's shutdown and the plugin disposing the item.
+     */
+    has(name) {
+        return this._live.has(name);
+    }
+    /**
+     * Display name for the session. The cache wins because it only
+     * holds "real" labels (the launcher's agent name or an xterm escape
+     * sequence — see `_cacheLabel` for the filter); reading it first
+     * prevents the transient `Terminal {name}` an XTerm widget shows
+     * during reconnect from flickering into the status bar. The live
+     * widget title is used when no cache exists, and the
+     * `Terminal {name}` fallback covers sessions we have never seen a
+     * widget for (e.g. surviving a lab reload).
+     */
+    labelFor(name) {
+        const cached = this._labels.get(name);
+        if (cached) {
+            return cached;
+        }
+        const widget = this.widgetFor(name);
+        if (widget && widget.title.label) {
+            return widget.title.label;
+        }
+        return `Terminal ${name}`;
+    }
+    /**
+     * Return the open widget for a session, if any. The status item
+     * uses this to switch behaviour between "activate existing tab"
+     * and "open a new tab connected to the live session".
+     */
+    widgetFor(name) {
+        var _a;
+        return ((_a = this._tracker.find(widget => widget.content.session.name === name)) !== null && _a !== void 0 ? _a : null);
+    }
+    /**
+     * Stable per-session rank assigned in observation order. Reused
+     * across `registerStatusItem` calls so an item that is briefly
+     * unregistered (e.g. while a widget is being recreated) lands back
+     * in the same slot. Cleaned up when the session is shut down so the
+     * counter does not grow without bound across long sessions.
+     */
+    rankFor(name) {
+        let rank = this._ranks.get(name);
+        if (rank === undefined) {
+            rank = this._nextRank++;
+            this._ranks.set(name, rank);
+        }
+        return rank;
+    }
+    dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        this._terminals.runningChanged.disconnect(this._onRunningChanged, this);
+        this._tracker.widgetAdded.disconnect(this._onWidgetAdded, this);
+        this._tracker.forEach(widget => this._untrackWidget(widget));
+        super.dispose();
+    }
+    _refreshLive() {
+        const next = new Set();
+        for (const model of this._terminals.running()) {
+            next.add(model.name);
+        }
+        this._live = next;
+        // Drop cache + rank entries for sessions that have been shut down
+        // server-side. Without this prune the rank counter would keep
+        // climbing across long-running labs as terminals come and go.
+        for (const name of Array.from(this._labels.keys())) {
+            if (!next.has(name)) {
+                this._labels.delete(name);
+            }
+        }
+        for (const name of Array.from(this._ranks.keys())) {
+            if (!next.has(name)) {
+                this._ranks.delete(name);
+            }
+        }
+    }
+    _onRunningChanged(_, sessions) {
+        this._live = new Set(sessions.map(model => model.name));
+        for (const name of Array.from(this._labels.keys())) {
+            if (!this._live.has(name)) {
+                this._labels.delete(name);
+            }
+        }
+        for (const name of Array.from(this._ranks.keys())) {
+            if (!this._live.has(name)) {
+                this._ranks.delete(name);
+            }
+        }
+        this.stateChanged.emit();
+    }
+    _onWidgetAdded(_, widget) {
+        this._trackWidget(widget);
+        this.stateChanged.emit();
+    }
+    _trackWidget(widget) {
+        const name = widget.content.session.name;
+        this._cacheLabel(name, widget.title.label);
+        widget.title.changed.connect(this._onTitleChanged, this);
+        widget.disposed.connect(this._onWidgetDisposed, this);
+    }
+    _untrackWidget(widget) {
+        widget.title.changed.disconnect(this._onTitleChanged, this);
+        widget.disposed.disconnect(this._onWidgetDisposed, this);
+    }
+    _onTitleChanged(title) {
+        var _a;
+        const owner = title.owner;
+        const session = (_a = owner.content) === null || _a === void 0 ? void 0 : _a.session;
+        if (!session) {
+            return;
+        }
+        this._cacheLabel(session.name, title.label);
+        this.stateChanged.emit();
+    }
+    /**
+     * Update the cached label for a session, but only when the new
+     * label is "real" — non-empty and not one of the transient defaults
+     * the XTerm widget cycles through during reconnect (`'...'` while
+     * the websocket is opening, `'Terminal {name}'` once
+     * `_initialConnection` fires). Without the filter, briefly
+     * reopening a tab while an agent has yet to re-emit its xterm
+     * title escape sequence would clobber the cached agent name with
+     * `Terminal 1`, which is exactly the regression we are guarding
+     * against. Live widget titles still display whatever the widget
+     * currently holds because `labelFor` consults the widget first;
+     * the filter only affects what survives a tab close.
+     */
+    _cacheLabel(name, label) {
+        if (!label) {
+            return;
+        }
+        if (label === '...' || label === `Terminal ${name}`) {
+            return;
+        }
+        this._labels.set(name, label);
+    }
+    _onWidgetDisposed(widget) {
+        // The widget is gone but the session may still be running on the
+        // server — keep the cached label so the status item keeps the
+        // agent's name when the user reopens the tab. We only clean up
+        // our subscriptions here; the cache is purged by `runningChanged`
+        // once the session itself goes away.
+        this._untrackWidget(widget);
+        this.stateChanged.emit();
+    }
+}
+/**
+ * One status bar item per live terminal session. Renders a terminal
+ * icon plus the session's label, with an inline shutdown button that
+ * appears on hover/focus. The item delegates click handling to the
+ * plugin so the lifecycle (create/dispose) and the user-facing
+ * behaviour (activate vs. reopen, shutdown) live in one place.
+ */
+export class TerminalSessionItem extends VDomRenderer {
+    constructor(options) {
+        var _a;
+        super(options.registry);
+        this._sessionName = options.sessionName;
+        this._trans = (_a = options.trans) !== null && _a !== void 0 ? _a : nullTranslator.load('jupyterlab');
+        this._onActivate = options.onActivate;
+        this._onShutdown = options.onShutdown;
+        this.addClass('jp-mod-highlighted');
+        this.addClass('jp-xtralab-StatusBar-Terminal');
+    }
+    render() {
+        if (!this.model || !this.model.has(this._sessionName)) {
+            return null;
+        }
+        const trans = this._trans;
+        const label = this.model.labelFor(this._sessionName);
+        const hasWidget = this.model.widgetFor(this._sessionName) !== null;
+        const tooltip = hasWidget
+            ? trans.__('Activate %1', label)
+            : trans.__('Reopen %1', label);
+        this.node.title = tooltip;
+        return (React.createElement("div", { className: "jp-xtralab-StatusBar-Terminal-Container" },
+            React.createElement("button", { type: "button", className: "jp-xtralab-StatusBar-Terminal-Activate", onClick: () => this._onActivate(this._sessionName), "aria-label": tooltip },
+                React.createElement(terminalIcon.react, { tag: "span", verticalAlign: "middle", stylesheet: "statusBar" }),
+                React.createElement("span", { className: "jp-xtralab-StatusBar-Terminal-Label" }, label)),
+            React.createElement("button", { type: "button", className: "jp-xtralab-StatusBar-Terminal-Close", onClick: event => {
+                    event.stopPropagation();
+                    this._onShutdown(this._sessionName);
+                }, title: trans.__('Shut down %1', label), "aria-label": trans.__('Shut down %1', label) },
+                React.createElement(closeIcon.react, { tag: "span", verticalAlign: "middle", stylesheet: "statusBar" }))));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.1.2",
+    "version": "0.3.0",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser and a VS Code-style git changes panel, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",
@@ -62,12 +62,18 @@
         "@jupyterlab/coreutils": "^6.6.0-alpha.5",
         "@jupyterlab/docmanager": "^4.6.0-alpha.5",
         "@jupyterlab/docregistry": "^4.6.0-alpha.5",
+        "@jupyterlab/launcher": "^4.6.0-alpha.5",
+        "@jupyterlab/mainmenu": "^4.6.0-alpha.5",
         "@jupyterlab/nbformat": "^4.6.0-alpha.5",
         "@jupyterlab/outputarea": "^4.6.0-alpha.5",
         "@jupyterlab/rendermime": "^4.6.0-alpha.5",
         "@jupyterlab/services": "^7.6.0-alpha.5",
         "@jupyterlab/settingregistry": "^4.6.0-alpha.5",
+        "@jupyterlab/statusbar": "^4.6.0-alpha.5",
+        "@jupyterlab/terminal": "^4.6.0-alpha.5",
+        "@jupyterlab/translation": "^4.6.0-alpha.5",
         "@jupyterlab/ui-components": "^4.6.0-alpha.5",
+        "@lumino/algorithm": "^2.0.0",
         "@lumino/coreutils": "^2.0.0",
         "@lumino/disposable": "^2.0.0",
         "@lumino/dragdrop": "^2.0.0",
@@ -76,6 +82,7 @@
         "@lumino/widgets": "^2.0.0",
         "@pierre/diffs": "^1.1.20",
         "@pierre/trees": "1.0.0-beta.3",
+        "ignore": "^5.3.2",
         "react": "^18.2.0",
         "react-dom": "^18.2.0"
     },
@@ -119,7 +126,8 @@
         "outputDir": "xtralab/labextension",
         "schemaDir": "schema",
         "disabledExtensions": [
-            "@jupyterlab/git"
+            "@jupyterlab/git",
+            "@jupyterlab/launcher-extension"
         ]
     },
     "eslintIgnore": [
@@ -137,12 +145,26 @@
         ],
         "parser": "@typescript-eslint/parser",
         "parserOptions": {
-            "project": "tsconfig.json",
+            "project": [
+                "tsconfig.json",
+                "desktop/tsconfig.json",
+                "desktop/tsconfig.forge.json"
+            ],
             "sourceType": "module"
         },
         "plugins": [
             "@typescript-eslint"
         ],
+        "overrides": [
+            {
+                "files": [
+                    "desktop/src/**/*.ts"
+                ],
+                "rules": {
+                    "@typescript-eslint/naming-convention": "off"
+                }
+            }
+        ],
         "rules": {
             "@typescript-eslint/naming-convention": [
                 "error",

package/schema/launcher.json

@@ -0,0 +1,70 @@
+{
+  "title": "xtralab launcher",
+  "description": "Settings for the xtralab agent launcher.",
+  "jupyter.lab.shortcuts": [],
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "agents": {
+      "title": "Agents",
+      "description": "Override or extend the built-in list of agents shown on the launcher. Each entry must include an `id`. When the id matches a built-in (claude, codex, gemini, copilot, goose, opencode, kiro, mistral-vibe), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define brand-new cards. Set `enabled: false` to hide a default. Set `requireAvailable: false` for shell aliases that should always show even though they aren't on PATH.",
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id"],
+        "properties": {
+          "id": {
+            "title": "ID",
+            "description": "Stable identifier. Match one of xtralab's defaults to override, or pick a new id to define a new card.",
+            "type": "string"
+          },
+          "label": {
+            "title": "Label",
+            "description": "Card title shown on the launcher.",
+            "type": "string"
+          },
+          "caption": {
+            "title": "Caption",
+            "description": "Short description shown beneath the card title.",
+            "type": "string"
+          },
+          "command": {
+            "title": "Command",
+            "description": "Literal string typed into the new terminal. Aliases work because shells expand them on interactive lines.",
+            "type": "string"
+          },
+          "iconSvg": {
+            "title": "Icon SVG",
+            "description": "Inline SVG for the card icon. Required only for new agents whose icon is not already shipped by xtralab.",
+            "type": "string"
+          },
+          "rank": {
+            "title": "Rank",
+            "description": "Sort order on the launcher (lower numbers come first).",
+            "type": "number"
+          },
+          "enabled": {
+            "title": "Enabled",
+            "description": "When false, hides the agent from the launcher and command palette.",
+            "type": "boolean",
+            "default": true
+          },
+          "requireAvailable": {
+            "title": "Require available",
+            "description": "When false, the launcher skips the availability check for this entry (useful for shell aliases that aren't on PATH but resolve in an interactive shell).",
+            "type": "boolean",
+            "default": true
+          },
+          "promptArgs": {
+            "title": "Prompt arguments",
+            "description": "How to splice an initial prompt from the launcher textarea into the agent's command line. Empty array (`[]`) appends the prompt as a positional argument. An array like `[\"-i\"]` or `[\"--prompt\"]` prefixes the prompt with that flag. Set to `null` to opt out of prompt support entirely (the agent's button is dimmed when the prompt textarea is non-empty).",
+            "type": ["array", "null"],
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/sidebar.json

@@ -0,0 +1,57 @@
+{
+  "title": "xtralab sidebar",
+  "description": "Visibility of selected JupyterLab sidebar tabs.",
+  "jupyter.lab.shortcuts": [],
+  "jupyter.lab.menus": {
+    "main": [
+      {
+        "id": "jp-mainmenu-view",
+        "items": [
+          {
+            "type": "submenu",
+            "rank": 1,
+            "submenu": {
+              "id": "jp-mainmenu-view-appearance",
+              "items": [
+                {
+                  "type": "submenu",
+                  "rank": 12.5,
+                  "submenu": {
+                    "id": "jp-mainmenu-view-appearance-left-sidebar",
+                    "label": "Left Sidebar",
+                    "items": [
+                      {
+                        "command": "xtralab:toggle-default-filebrowser",
+                        "rank": 1
+                      },
+                      {
+                        "command": "xtralab:toggle-running-sessions",
+                        "rank": 2
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "type": "object",
+  "properties": {
+    "showDefaultFileBrowser": {
+      "type": "boolean",
+      "title": "Show the default JupyterLab file browser",
+      "description": "When false, hides the default `filebrowser` tab from the left sidebar. The xtralab file browser is unaffected.",
+      "default": true
+    },
+    "showRunningSessions": {
+      "type": "boolean",
+      "title": "Show running terminals and kernels",
+      "description": "When false, hides the `jp-running-sessions` (Running Terminals and Kernels) tab from the left sidebar.",
+      "default": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/fileBrowser/commands.ts

@@ -27,7 +27,7 @@ import { toCanonicalPath, toServerPath } from './contents';
 import { IXtralabFileBrowser } from './widget';
 
 /**
- * Command identifiers exposed by the Xtralab browser. We deliberately namespace
+ * Command identifiers exposed by the xtralab browser. We deliberately namespace
  * these under `xtralab:` rather than reusing the `filebrowser:` ids
  * because the core `filebrowser:*` commands look up a `FileBrowser` instance
  * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
@@ -198,7 +198,7 @@ function makeOpenWithUpdater(
 }
 
 /**
- * Register every Xtralab command on the application command registry, attach
+ * Register every xtralab command on the application command registry, attach
  * the items to the application context menu, and wire up the dynamic
  * "Open With" submenu populator.
  *