xtralab 0.15.0 → 0.15.1

package/README.md

@@ -24,6 +24,16 @@ pip install xtralab
 jupyter lab
 ```
 
+To try it from any directory without setting up an environment first, uv can
+build a throwaway one:
+
+```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.
+
 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

package/lib/about/icons.d.ts

@@ -1,7 +1,2 @@
 import { LabIcon } from '@jupyterlab/ui-components';
-/**
- * The project logo mark — `logo.svg` at the repository root, the same file
- * the README and the docs site use. The labextension build inlines it as a
- * raw string, so the dialog always shows the current artwork.
- */
 export declare const aboutLogoIcon: LabIcon;

package/lib/about/icons.js

@@ -1,10 +1,5 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 import logoSvgstr from '../../logo.svg';
-/**
- * The project logo mark — `logo.svg` at the repository root, the same file
- * the README and the docs site use. The labextension build inlines it as a
- * raw string, so the dialog always shows the current artwork.
- */
 export const aboutLogoIcon = new LabIcon({
     name: 'xtralab:about-logo',
     svgstr: logoSvgstr

package/lib/about/index.d.ts

@@ -1,13 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
- *
- * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
- * `jupyterlab.disabledExtensions` (package.json), which removes both its
- * `help:about` command and its Help menu contribution; this plugin registers
- * the same command id and restores the menu entry through its own schema.
- * The dialog leads with the xtralab version and keeps the underlying
- * JupyterLab version visible underneath.
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one. The
+ * upstream plugin is disabled via `jupyterlab.disabledExtensions`, which also
+ * removes its Help menu entry; this plugin re-registers `help:about` and
+ * restores the menu entry through its own schema.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/about/index.js

@@ -4,24 +4,15 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import * as React from 'react';
 import { aboutLogoIcon } from './icons';
 const PLUGIN_ID = 'xtralab:about';
-/**
- * Upstream command id. Reusing it keeps the Help menu entry (contributed by
- * `schema/about.json` at the same rank as upstream), the command palette
- * muscle memory, and any external caller of `help:about` working.
- */
 const CommandIDs = {
     about: 'help:about'
 };
 const REPO_URL = 'https://github.com/jtpio/xtralab';
 /**
- * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
- *
- * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
- * `jupyterlab.disabledExtensions` (package.json), which removes both its
- * `help:about` command and its Help menu contribution; this plugin registers
- * the same command id and restores the menu entry through its own schema.
- * The dialog leads with the xtralab version and keeps the underlying
- * JupyterLab version visible underneath.
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one. The
+ * upstream plugin is disabled via `jupyterlab.disabledExtensions`, which also
+ * removes its Help menu entry; this plugin re-registers `help:about` and
+ * restores the menu entry through its own schema.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -41,10 +32,8 @@ const plugin = {
                 }
             },
             execute: async () => {
-                // The settings payload carries the version of the installed
-                // labextension (read server-side from its package.json), which is
-                // the release actually running — the page config only knows the
-                // JupyterLab version. 'N/A' is jupyterlab_server's not-found value.
+                // The settings payload carries the installed labextension's version
+                // (page config only knows JupyterLab's); 'N/A' is jupyterlab_server's not-found value.
                 const version = await settingRegistry
                     .load(PLUGIN_ID)
                     .then(settings => settings.version === 'N/A' ? '' : settings.version)

package/lib/agentSessions.d.ts

@@ -2,28 +2,14 @@ import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { Token } from '@lumino/coreutils';
 import { ISignal } from '@lumino/signaling';
 /**
- * A shared map from a terminal session name to the agent command it was
- * *launched* with (e.g. `claude`).
- *
- * This is the optimistic half of the running-agent badge: when the launcher
- * (or the terminals panel's `+` menu) starts an agent via a
- * `xtralab:start-agent:<id>` command, it records the session here so the
- * panel can show the agent's logo immediately, before the server-side
- * process detection has had a chance to confirm it. Server detection is the
- * authoritative source once it reports on a session; this tag only fills the
- * gap right after launch (and serves as a fallback if detection is
- * unavailable).
- *
- * It exists as its own token, provided by a tiny dependency-free plugin,
- * specifically so the launcher (the writer) and the terminals panel (the
- * reader) can share it without depending on each other — a direct
- * launcher↔terminals token pair would form an activation cycle.
+ * Shared map from terminal session name to the agent command it was launched
+ * with — the optimistic half of the running-agent badge, shown until server
+ * detection confirms. Its own token so the launcher (writer) and terminals
+ * panel (reader) can share it without an activation cycle.
  */
 export interface IAgentSessions {
     /**
-     * The agent command a session was launched with, or `null` if we never
-     * launched an agent into it (e.g. a plain terminal, or one started before
-     * this ran).
+     * The agent command a session was launched with, or `null` if unknown.
      */
     get(sessionName: string): string | null;
     /**
@@ -31,24 +17,18 @@ export interface IAgentSessions {
      */
     set(sessionName: string, command: string): void;
     /**
-     * Forget a session — called when it shuts down so the map stays bounded.
+     * Forget a session so the map stays bounded.
      */
     delete(sessionName: string): void;
     /**
-     * Emitted with the affected session name whenever a record is added or
-     * removed, so readers can re-render.
+     * Emitted with the session name whenever a record is added or removed.
      */
     readonly changed: ISignal<IAgentSessions, string>;
 }
-/**
- * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
- * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
- */
 export declare const IAgentSessions: Token<IAgentSessions>;
 /**
- * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
- * sit underneath both the launcher and the terminals panel without creating
- * a dependency cycle between them.
+ * Provides {@link IAgentSessions}; dependency-free so it can sit underneath
+ * both the launcher and the terminals panel.
  */
 declare const plugin: JupyterFrontEndPlugin<IAgentSessions>;
 export default plugin;

package/lib/agentSessions.js

@@ -1,9 +1,5 @@
 import { Token } from '@lumino/coreutils';
 import { Signal } from '@lumino/signaling';
-/**
- * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
- * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
- */
 export const IAgentSessions = new Token('xtralab:IAgentSessions', 'A shared map from terminal session name to the agent command it was launched with.');
 class AgentSessions {
     constructor() {
@@ -31,9 +27,8 @@ class AgentSessions {
     }
 }
 /**
- * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
- * sit underneath both the launcher and the terminals panel without creating
- * a dependency cycle between them.
+ * Provides {@link IAgentSessions}; dependency-free so it can sit underneath
+ * both the launcher and the terminals panel.
  */
 const plugin = {
     id: 'xtralab:agent-sessions',

package/lib/askAgent/editorSelection.d.ts

@@ -3,49 +3,43 @@ import type { EditorView } from '@codemirror/view';
 import type { Widget } from '@lumino/widgets';
 import type { IAskAgentRequest } from './tokens';
 /**
- * A CodeMirror view a selection can be asked about, plus the context needed
- * to describe it to an agent: the document path and, for notebooks, which
- * cell the view belongs to.
+ * A CodeMirror view a selection can be asked about, plus the document path
+ * and, for notebooks, the owning cell.
  */
 interface IEditorTarget {
+    /**
+     * The CodeMirror view holding the selection.
+     */
     view: EditorView;
+    /**
+     * The path of the document the view belongs to.
+     */
     path: string;
+    /**
+     * The index and type of the owning notebook cell; absent for file editors.
+     */
     cell?: {
         index: number;
         type: string;
     };
 }
 /**
- * Resolve the CodeMirror view a selection in `widget` would live in, or
- * `null` when the widget holds no such editor. Two widget shapes are
- * recognized:
- *
- * - a notebook panel, where the active cell carries the editor and
- *   `activeCellIndex` names its 0-based position in the nbformat `cells`
- *   array. A rendered markdown cell keeps its (hidden) editor, but a
- *   selection in the rendered HTML never passes {@link domSelectionInView},
- *   so no pill appears there; and
- * - a document widget whose content is a `FileEditor`. The wrapper is not
- *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
- *   not a core singleton, so another copy of the class could be in play.
- *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ * Resolve the CodeMirror view a selection in `widget` would live in — the
+ * active notebook cell or a `FileEditor` document — or `null`. The wrapper is
+ * duck-typed, not `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ * not a core singleton, unlike `FileEditor` and `NotebookPanel`.
  */
 export declare function resolveEditorTarget(widget: Widget | null): IEditorTarget | null;
 /**
- * Whether the current DOM selection lives inside `view`. Guards the
- * selection-change listener against selections made elsewhere (a terminal,
- * a sidebar, another notebook cell) while the widget owning `view` happens
- * to be the shell's current widget.
+ * Whether the current DOM selection lives inside `view`; guards against
+ * selections made elsewhere while the owning widget is current.
  */
 export declare function domSelectionInView(view: EditorView, selection: Selection): boolean;
 /**
  * Build an ask-agent request from the current selection in the shell's
- * current widget — a file editor or the active notebook cell — or return
- * `null` when that widget holds no CodeMirror document editor.
- *
- * With `allowEmpty`, a collapsed selection falls back to the cursor's line
- * (used by the command/shortcut path so it works without a mouse
- * selection); otherwise an empty selection yields `null`.
+ * current widget, or `null` when it holds no CodeMirror document editor.
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line;
+ * otherwise it yields `null`.
  */
 export declare function editorAskRequest(app: JupyterFrontEnd, options?: {
     allowEmpty?: boolean;

package/lib/askAgent/editorSelection.js

@@ -2,19 +2,10 @@ import { CodeMirrorEditor } from '@jupyterlab/codemirror';
 import { FileEditor } from '@jupyterlab/fileeditor';
 import { NotebookPanel } from '@jupyterlab/notebook';
 /**
- * Resolve the CodeMirror view a selection in `widget` would live in, or
- * `null` when the widget holds no such editor. Two widget shapes are
- * recognized:
- *
- * - a notebook panel, where the active cell carries the editor and
- *   `activeCellIndex` names its 0-based position in the nbformat `cells`
- *   array. A rendered markdown cell keeps its (hidden) editor, but a
- *   selection in the rendered HTML never passes {@link domSelectionInView},
- *   so no pill appears there; and
- * - a document widget whose content is a `FileEditor`. The wrapper is not
- *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
- *   not a core singleton, so another copy of the class could be in play.
- *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ * Resolve the CodeMirror view a selection in `widget` would live in — the
+ * active notebook cell or a `FileEditor` document — or `null`. The wrapper is
+ * duck-typed, not `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ * not a core singleton, unlike `FileEditor` and `NotebookPanel`.
  */
 export function resolveEditorTarget(widget) {
     if (widget instanceof NotebookPanel) {
@@ -36,10 +27,8 @@ export function resolveEditorTarget(widget) {
     return null;
 }
 /**
- * Whether the current DOM selection lives inside `view`. Guards the
- * selection-change listener against selections made elsewhere (a terminal,
- * a sidebar, another notebook cell) while the widget owning `view` happens
- * to be the shell's current widget.
+ * Whether the current DOM selection lives inside `view`; guards against
+ * selections made elsewhere while the owning widget is current.
  */
 export function domSelectionInView(view, selection) {
     var _a;
@@ -49,12 +38,9 @@ export function domSelectionInView(view, selection) {
 }
 /**
  * Build an ask-agent request from the current selection in the shell's
- * current widget — a file editor or the active notebook cell — or return
- * `null` when that widget holds no CodeMirror document editor.
- *
- * With `allowEmpty`, a collapsed selection falls back to the cursor's line
- * (used by the command/shortcut path so it works without a mouse
- * selection); otherwise an empty selection yields `null`.
+ * current widget, or `null` when it holds no CodeMirror document editor.
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line;
+ * otherwise it yields `null`.
  */
 export function editorAskRequest(app, options = {}) {
     const target = resolveEditorTarget(app.shell.currentWidget);
@@ -75,13 +61,12 @@ export function editorAskRequest(app, options = {}) {
         text = state.doc.lineAt(main.from).text;
     }
     else {
-        // A selection that ends exactly at the start of a line (the common
-        // "drag over whole lines" gesture) should not count that line.
+        // A selection ending exactly at a line start (the whole-line drag
+        // gesture) should not count that line.
         const endPos = main.to === state.doc.lineAt(main.to).from ? main.to - 1 : main.to;
         endLine = state.doc.lineAt(endPos).number;
         text = state.sliceDoc(main.from, main.to);
     }
-    // Anchor the popup at the selection head (where the cursor ended up).
     // `coordsAtPos` returns `null` for positions scrolled out of view.
     const coords = view.coordsAtPos(main.head);
     const anchor = coords

package/lib/askAgent/icons.d.ts

@@ -1,7 +1,6 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 /**
- * Four-point sparkle used by the ask-agent affordances (selection pill,
- * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
- * active theme recolor the glyph like other JupyterLab UI icons.
+ * Four-point sparkle used by the ask-agent affordances; the `jp-icon3`
+ * class lets the active theme recolor the glyph.
  */
 export declare const askAgentIcon: LabIcon;

package/lib/askAgent/icons.js

@@ -1,8 +1,7 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 /**
- * Four-point sparkle used by the ask-agent affordances (selection pill,
- * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
- * active theme recolor the glyph like other JupyterLab UI icons.
+ * Four-point sparkle used by the ask-agent affordances; the `jp-icon3`
+ * class lets the active theme recolor the glyph.
  */
 export const askAgentIcon = new LabIcon({
     name: 'xtralab:ask-agent',

package/lib/askAgent/index.d.ts

@@ -1,32 +1,10 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { IAskAgent } from './tokens';
 /**
- * Select code in a file editor (or pick diff lines) and prompt a coding
- * agent about it.
- *
- * The plugin watches the document selection: a non-empty selection inside a
- * CodeMirror file editor or notebook cell grows a small floating "Ask agent"
- * pill next to the selection. Clicking it (or running `xtralab:ask-agent`,
- * bound to Accel+. in editors and notebooks) opens a popup where the user
- * types an instruction, picks one of the launcher's agents and picks where
- * the prompt goes; submitting either starts that agent in a fresh terminal
- * via `xtralab:start-agent:<id>`, or pastes the prompt into an agent already
- * running in one of the open terminal sessions (via `IAgentTerminals`; the
- * agent CLIs queue prompts that arrive while they are busy). Sends to a
- * running agent stay in the background — focus never leaves the editor, and
- * a success toast offers to open the terminal. Either way the prompt embeds
- * the file path, cell index for notebooks, line range and selected snippet.
- *
- * The popup's Queue button (or Accel+Enter) defers the send instead: the
- * comment lands in a persistent queue, stamped with the popup's selected
- * destination — every queued prompt is independent and may aim at a
- * different agent or session. A right-sidebar panel reviews the queue
- * (edit, retarget, remove) and flushes it in one go, combining prompts that
- * share a destination into a single numbered message. The queue survives
- * page reloads.
- *
- * The same popup is provided on the `IAskAgent` token so the git diff
- * viewers can open it for a selected diff line range.
+ * Prompt a coding agent about selected code: a pill/popup over editor,
+ * notebook-cell and git-diff selections sends the instruction to a fresh
+ * agent terminal or into a running one, or defers it into a persistent
+ * queue reviewed in a right-sidebar panel and flushed as one batch.
  */
 declare const plugin: JupyterFrontEndPlugin<IAskAgent>;
 export default plugin;