xtralab 0.15.0 → 0.15.2

package/src/launcher/commands.ts

@@ -9,24 +9,13 @@ import type { IAgent } from './agents';
 import { buildAgentInvocation } from './invocation';
 import { agentCommandId } from './tokens';
 
-/**
- * The command id for opening the launcher.
- */
 export const CREATE_LAUNCHER_COMMAND = 'launcher:create';
 
 /**
- * Register a JupyterLab command per agent. Each command opens a new
- * terminal via `terminal:create-new` and feeds the agent's shell command
- * into the fresh session as if the user had typed it.
- *
- * Returns a single disposable that tears down every registered command —
- * the launcher disposes the previous set before re-registering on settings
- * changes so the command palette stays in sync with the configured agents.
- *
- * When an `agentSessions` registry is supplied, each launch tags its terminal
- * session with the agent's command, so the terminals panel can badge the row
- * with the agent's logo immediately (before server-side detection confirms
- * it).
+ * Register a JupyterLab command per agent that opens a new terminal and types
+ * the agent's shell command into it. Returns one disposable tearing down every
+ * command, so a settings change can re-register without stale palette entries.
+ * `agentSessions`, when given, launch-tags each session for the terminals panel.
  */
 export function registerAgentCommands(
   app: JupyterFrontEnd,
@@ -48,9 +37,7 @@ export function registerAgentCommands(
           cwd,
           invocation,
           label: agent.label,
-          // Optimistically tag the session with this agent so the terminals
-          // panel can show its logo right away; server-side detection takes
-          // over as the source of truth on its next poll.
+          // Optimistic tag; server-side detection takes over on its next poll.
           onSession: name => agentSessions?.set(name, agent.command)
         });
       }
@@ -62,29 +49,15 @@ export function registerAgentCommands(
 
 /**
  * Open a fresh terminal, type `invocation` into it as if the user had, and
- * label the tab. Shared by the per-agent launch commands and the launcher's
- * editor tile so the fiddly "wait for the websocket, then write stdin"
- * sequence lives in one place.
- *
- * `onSession`, when given, is called once with the new session's name right
- * after the terminal is revealed. Callers use it to optimistically tag the
- * session so the terminals panel can badge it with the agent's (or editor's)
- * logo before server-side detection confirms the running process.
- *
- * Resolves with the host `MainAreaWidget` so the caller can place it — the
- * launcher swaps it into its own tab.
+ * label the tab. `onSession` receives the new session's name so callers can
+ * launch-tag it for the terminals panel. Resolves with the host
+ * `MainAreaWidget` so the caller can place it.
  */
 export async function launchInTerminal(
   commands: CommandRegistry,
   options: {
     cwd?: string;
-    /**
-     * The literal command line typed into the fresh terminal.
-     */
     invocation: string;
-    /**
-     * Tab/title label applied once the command is sent.
-     */
     label: string;
     onSession?: (sessionName: string) => void;
   }
@@ -93,10 +66,8 @@ export async function launchInTerminal(
   const main = (await commands.execute('terminal:create-new', {
     cwd
   })) as MainAreaWidget<ITerminal.ITerminal>;
-  // `MainAreaWidget.revealed` chains off the `reveal` promise the terminal
-  // extension passes in (the xterm.js widget's own `ready` promise), so
-  // awaiting it guarantees the Terminal widget has finished its constructor
-  // and connected its session listeners.
+  // `revealed` chains off the terminal's `ready` promise, so awaiting it
+  // guarantees the widget finished construction and connected its listeners.
   await main.revealed;
 
   const session = main.content.session;
@@ -114,21 +85,13 @@ export async function launchInTerminal(
       type: 'stdin',
       content: [invocation + '\r']
     });
-    // Give the tab and the status-bar list a meaningful default label. The
-    // XTerm widget's `_initialConnection` listener overwrites the title with
-    // `Terminal {N}` when the WebSocket first reports `connected`; we connect
-    // *after* that listener (and call `applyLabel` after `sendCommand`), so by
-    // the time we run the upstream listener has already had its turn. Programs
-    // that publish a real xterm title escape sequence still win —
-    // `XTerm.onTitleChange` resets the label whenever it fires.
+    // XTerm's `_initialConnection` resets the title on first connect; we run
+    // after it, so this label survives. A title escape still wins (`onTitleChange`).
     applyLabel();
   };
 
-  // Match how the Terminal widget itself sends its `initialCommand`: either
-  // fire immediately if the session is already connected, or wait for the next
-  // `connectionStatusChanged` that flips it to `connected`. Without this the
-  // stdin write races the websocket handshake and the command silently
-  // disappears.
+  // Without waiting for `connected` the stdin write races the websocket
+  // handshake and the command silently disappears.
   if (session.connectionStatus === 'connected') {
     sendCommand();
   } else {

package/src/launcher/dashboard.tsx

@@ -33,46 +33,40 @@ import type { IEditor } from './editors';
 import { agentCommandId } from './tokens';
 
 /**
- * Public construction options for the launcher dashboard widget. The
- * plugin supplies an `onAgentLaunch` callback that performs the same
- * shell placement the stock JupyterLab launcher does (swap the launcher
- * tab for the freshly created terminal). Keeping it as an opaque
- * callback means the widget itself does not import `app.shell`.
+ * Construction options for the launcher dashboard. `onAgentLaunch` is an
+ * opaque callback so the widget itself never imports `app.shell`.
  */
 interface ILauncherDashboardOptions {
+  /**
+   * The application command registry, used to launch terminals and run git
+   * commands.
+   */
   commands: CommandRegistry;
   /**
-   * The agent list to render. Already filtered by availability + sorted by
-   * rank; the widget renders them as-is.
+   * Agent list to render, already filtered by availability and sorted by rank.
    */
   agents: IAgent[];
   /**
-   * The terminal editor to offer in the "Open" section (Neovim preferred over
-   * Vim), or `null` when neither is installed. Resolved by the plugin from the
-   * same availability probe that filters the agents.
+   * Terminal editor for the "Open" section, or `null` when none is installed.
    */
   editor: IEditor | null;
   /**
-   * Shared launch-tag registry. When the editor tile launches, it records the
-   * session here so the terminals panel badges it with the editor's logo right
-   * away, the same as agent launches do. `null` when the provider plugin is
-   * unavailable.
+   * Launch-tag registry so the terminals panel badges editor launches right
+   * away; `null` when the provider plugin is unavailable.
    */
   agentSessions: IAgentSessions | null;
   /**
-   * Called after an agent command has returned its top-level widget. The
-   * plugin uses this to swap the new terminal into the launcher's tab.
+   * Called with the launched widget; the plugin swaps it into the launcher's tab.
    */
   onAgentLaunch: (item: Widget) => void;
   /**
-   * The git server-relative repo path used by the changes section. Empty
-   * string means "use the JupyterLab server's root and let git resolve the
-   * enclosing repo" — same convention as the git panel.
+   * Repo path for the changes section. Empty string lets git resolve the
+   * enclosing repo from the server root — same convention as the git panel.
    */
   repoPath: string;
   /**
-   * The cwd forwarded to `terminal:create-new` when an agent is launched.
-   * Empty string lets the terminal extension default to the server root.
+   * Cwd forwarded to `terminal:create-new`. Empty string defaults to the
+   * server root.
    */
   cwd: string;
   /**
@@ -83,9 +77,7 @@ interface ILauncherDashboardOptions {
 }
 
 /**
- * Lumino host for the React-based launcher dashboard. Mirrors the
- * `ReactWidget` pattern used by the git panel so the rest of the plugin
- * (layout placement, signals, lifecycle) stays consistent.
+ * Lumino host for the React-based launcher dashboard.
  */
 export class LauncherDashboard extends ReactWidget {
   constructor(options: ILauncherDashboardOptions) {
@@ -94,6 +86,9 @@ export class LauncherDashboard extends ReactWidget {
     this._options = options;
   }
 
+  /**
+   * Render the launcher dashboard component.
+   */
   protected render(): React.ReactElement {
     return <LauncherDashboardComponent {...this._options} />;
   }
@@ -101,24 +96,31 @@ export class LauncherDashboard extends ReactWidget {
   private _options: ILauncherDashboardOptions;
 }
 
+/**
+ * State of the changes-section git status fetch.
+ */
 interface IGitState {
+  /**
+   * Whether the initial status fetch is still pending.
+   */
   loading: boolean;
+  /**
+   * The latest status result, or `null` before the first success or after a
+   * failure.
+   */
   result: IGitStatusResult | null;
+  /**
+   * The latest fetch error message, or `null` when the last fetch succeeded.
+   */
   error: string | null;
 }
 
 /**
- * Refresh interval for the changes list. A bit slower than the git panel
- * (which sits in the sidebar and is always visible) — the launcher tab is
- * only opened intentionally, and the grid does not need to be live.
+ * Changes-list refresh interval; slower than the git panel since the launcher
+ * tab is only opened intentionally.
  */
 const CHANGES_POLL_INTERVAL_MS = 8000;
 
-/**
- * Upper bound on the exponential backoff when the status request fails
- * repeatedly. Matches the rest of the plugin's polls so behavior is
- * consistent across the dashboard, the git panel, and the file tree.
- */
 const CHANGES_POLL_MAX_MS = 300_000;
 
 function LauncherDashboardComponent(
@@ -154,9 +156,6 @@ function LauncherDashboardComponent(
     }
   }, [repoPath]);
 
-  // Driven by a Lumino `Poll` so the dashboard stops hitting the git
-  // endpoint while the JupyterLab tab is hidden, and so repeated
-  // failures back off exponentially instead of pegging the 8s cadence.
   React.useEffect(() => {
     const poll = new Poll({
       name: '@xtralab/launcher:gitChanges',
@@ -201,12 +200,8 @@ function LauncherDashboardComponent(
   }, [commands, cwd, onAgentLaunch]);
 
   const launchNotebook = React.useCallback(async () => {
-    // Open a fresh notebook with no kernel attached — equivalent to clicking
-    // "No Kernel" in the Select Kernel dialog. `notebook:create-new` always
-    // routes through that dialog when no kernelName is given, so drive the
-    // underlying docmanager steps directly and pass `shouldStart: false` to
-    // suppress kernel selection. The user picks a kernel from the notebook
-    // toolbar when they're ready.
+    // `notebook:create-new` always opens the Select Kernel dialog when no
+    // kernelName is given, so drive docmanager directly with `shouldStart: false`.
     const file = (await commands.execute('docmanager:new-untitled', {
       path: cwd,
       type: 'notebook'
@@ -220,8 +215,7 @@ function LauncherDashboardComponent(
       kernelPreference: { shouldStart: false, canStart: true }
     })) as IDocumentWidget | undefined;
     if (result) {
-      // Match `notebook:create-new`'s post-open marker so the first manual
-      // save offers a rename instead of overwriting the auto-generated name.
+      // Match `notebook:create-new`'s marker so the first save offers a rename.
       result.isUntitled = true;
       onAgentLaunch(result);
     }
@@ -240,10 +234,6 @@ function LauncherDashboardComponent(
     if (!editor) {
       return;
     }
-    // An editor is "open a terminal and type its command" — the agent launch
-    // minus the prompt — so it shares `launchInTerminal` rather than the native
-    // `terminal:create-new` call the tiles above use, and tags the session the
-    // same way so the terminals panel badges it with the editor's logo.
     const result = await launchInTerminal(commands, {
       cwd,
       invocation: editor.command,
@@ -301,10 +291,6 @@ function ChangesSection(props: {
   const { git, onOpen, onRefresh, trans } = props;
   const files = git.result ? expandStatusFiles(git.result.files) : [];
 
-  // Native `<details>` rather than a hand-rolled toggle: we get the
-  // disclosure triangle, keyboard handling, and aria-expanded semantics
-  // for free, and the user's open/closed choice is tab-local state that
-  // we don't need to persist.
   return (
     <details
       className="jp-xtralab-Launcher-section jp-xtralab-Launcher-changes-section"
@@ -330,8 +316,7 @@ function ChangesSection(props: {
           type="button"
           className="jp-xtralab-Launcher-section-action"
           aria-label={trans.__('Refresh changes')}
-          // Stop the click from toggling the surrounding `<details>` —
-          // refreshing while the section is open shouldn't collapse it.
+          // Keep the click from toggling the surrounding `<details>`.
           onClick={event => {
             event.preventDefault();
             event.stopPropagation();
@@ -417,9 +402,6 @@ function AgentSection(props: {
   const { agents, prompt, onPromptChange, onLaunch, trans } = props;
   const trimmed = prompt.trim();
   const promptActive = trimmed.length > 0;
-  // The first prompt-capable agent is what Cmd/Ctrl+Enter fires; the hint
-  // text below the textarea names it so the keyboard shortcut target
-  // isn't a mystery.
   const primaryAgent = agents.find(agent => agent.promptArgs !== undefined);
   const hintId = 'jp-xtralab-Launcher-agent-hint';
 
@@ -501,24 +483,17 @@ function AgentSection(props: {
 }
 
 /**
- * Launcher agents whose CLI has a clean, non-interactive `mcp add` that takes
- * `<name> -- <command>`. The other agents (Goose, OpenCode, Kiro, Mistral
- * Vibe, Antigravity) register MCP through their own config files or UI, so
- * there is no one-line command to surface for them.
+ * Agents whose CLI has a non-interactive `mcp add <name> -- <command>`; the
+ * other agents register MCP through their own config, so no one-liner exists.
  */
 const MCP_ADD_AGENT_IDS = new Set(['claude', 'codex', 'copilot']);
 
-/**
- * The stdio proxy console script that bridges an agent to the MCP server.
- */
 const MCP_PROXY_COMMAND = 'jupyter-server-mcp-proxy';
 
 /**
- * Copy `text` to the clipboard via a hidden, selected `<textarea>` and the
- * legacy `execCommand('copy')`. Deprecated, but still the most reliable path
- * under a user gesture when the async Clipboard API is unavailable or blocked
- * (the desktop app's Electron window can deny clipboard writes by policy).
- * Returns whether the copy succeeded.
+ * Copy via a hidden `<textarea>` and the legacy `execCommand('copy')`:
+ * deprecated, but the reliable fallback when the async Clipboard API is
+ * missing or blocked (Electron can deny it by policy). Returns success.
  */
 function legacyCopy(text: string): boolean {
   try {
@@ -539,13 +514,10 @@ function legacyCopy(text: string): boolean {
 }
 
 /**
- * A collapsed-by-default hint listing the one-line command that registers
- * xtralab's running Jupyter MCP server with each installed agent that
- * supports `mcp add`. Copy-only: the user runs it in their own terminal,
- * where the server is reachable with no port to configure — the desktop
- * supervisor exports `JUPYTER_SERVER_MCP_URL`, and `pip` installs let the
- * proxy discover the server from its runtime file. Renders nothing when none
- * of those agents are on `$PATH`.
+ * Collapsed-by-default hint listing the `mcp add` one-liner per installed
+ * agent. Copy-only: run in the user's own terminal, where the proxy finds the
+ * server with no port (desktop exports `JUPYTER_SERVER_MCP_URL`; pip installs
+ * discover it from the runtime file). Renders nothing when no agent qualifies.
  */
 function McpSection(props: {
   agents: IAgent[];
@@ -569,9 +541,6 @@ function McpSection(props: {
   };
 
   const copy = (command: string, id: string): void => {
-    // Prefer the async Clipboard API; fall back to `legacyCopy` when it's
-    // missing or rejects (Electron can block it by policy). Flag "Copied" only
-    // once a copy actually succeeds.
     const clipboard = navigator.clipboard;
     if (clipboard) {
       void clipboard.writeText(command).then(
@@ -638,16 +607,8 @@ function McpSection(props: {
 }
 
 /**
- * The non-agent launch tiles — a plain terminal, a new notebook, and a
- * new console. They sit in a separate section below the agent grid so
- * they don't compete with the AI agents visually, and they're always
- * available regardless of the agent prompt textarea (which doesn't
- * apply to them).
- *
- * A terminal editor (Neovim, else Vim) joins the row when one is installed —
- * it opens in a terminal like the agents do, so it lives here rather than in
- * the agent grid. When neither is on `$PATH`, `editor` is `null` and no tile
- * renders.
+ * The non-agent launch tiles: terminal, notebook, and console, plus the
+ * terminal editor tile when one is installed (`editor` is `null` otherwise).
  */
 function OpenSection(props: {
   editor: IEditor | null;

package/src/launcher/editorRegistry.ts

@@ -19,37 +19,28 @@ import {
 } from './schemaDefaults';
 
 /**
- * A read-only, observable view of the launcher's terminal editors: xtralab's
- * built-ins (Neovim, Vim) merged with the user's `editors` setting, sorted by
- * rank, with disabled entries removed.
+ * A read-only, observable view of the launcher's terminal editors: the
+ * built-ins merged with the user's `editors` setting.
  */
 export interface IEditorRegistry {
   /**
-   * The full merged editor list (disabled entries already removed). The
-   * terminals panel uses it to badge a row for any configured editor that is
-   * running, and to tell the server which editor commands to detect.
+   * The merged editor list (disabled entries removed); the terminals panel
+   * uses it to badge running editors.
    */
   readonly editors: IEditor[];
 
   /**
-   * The single editor tile the launcher shows: the first editor, by rank, whose
-   * command is on `$PATH` (Neovim before Vim by default), or `null` when none
-   * qualifies.
+   * The single launcher tile: the first editor, by rank, whose command is on
+   * `$PATH`, or `null` when none qualifies.
    */
   readonly current: IEditor | null;
 
   /**
-   * Emitted whenever {@link editors} or {@link current} changes (the user
-   * edited the `editors` setting). Consumers that read on demand can ignore it.
+   * Emitted whenever {@link editors} or {@link current} changes.
    */
   readonly changed: ISignal<IEditorRegistry, void>;
 }
 
-/**
- * DI token for {@link IEditorRegistry}. Provided by `xtralab:editor-registry`
- * and consumed — optionally — by `xtralab:launcher` (for its tile) and
- * `xtralab:terminals` (to badge running editors with their logo).
- */
 export const IEditorRegistry = new Token<IEditorRegistry>(
   'xtralab:IEditorRegistry',
   'A read-only, observable view of the launcher terminal editors, shared so the launcher tile and the terminals panel agree on the list and icons.'
@@ -57,23 +48,32 @@ export const IEditorRegistry = new Token<IEditorRegistry>(
 
 /**
  * Concrete {@link IEditorRegistry}. The provider plugin is the only writer, so
- * the write side ({@link set}) is kept off the shared token.
+ * {@link set} is kept off the shared token.
  */
 class EditorRegistry implements IEditorRegistry {
+  /**
+   * The merged editor list (disabled entries removed).
+   */
   get editors(): IEditor[] {
     return this._editors;
   }
 
+  /**
+   * The launcher-tile editor, or `null` when none qualifies.
+   */
   get current(): IEditor | null {
     return this._current;
   }
 
+  /**
+   * Emitted whenever {@link editors} or {@link current} changes.
+   */
   get changed(): ISignal<IEditorRegistry, void> {
     return this._changed;
   }
 
   /**
-   * Replace both lists (recomputed together) and notify observers.
+   * Replace both lists and notify observers.
    */
   set(editors: IEditor[], current: IEditor | null): void {
     this._editors = editors;
@@ -87,12 +87,9 @@ class EditorRegistry implements IEditorRegistry {
 }
 
 /**
- * Provides {@link IEditorRegistry}: merges xtralab's built-in editors with the
- * user's `editors` setting, probes the server's `$PATH` to resolve the launcher
- * tile, and re-runs both on a settings change.
- *
- * `activate` awaits the first probe before returning, so a consumer reading
- * {@link IEditorRegistry.current} on activation sees a resolved tile.
+ * Provides {@link IEditorRegistry}: merges the built-in editors with the
+ * `editors` setting and probes the server's `$PATH`. `activate` awaits the
+ * first probe, so consumers see a resolved tile on activation.
  */
 export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
   id: 'xtralab:editor-registry',
@@ -109,9 +106,6 @@ export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
 
     const apply = async (overrides: IEditorSettings[]): Promise<void> => {
       const editors = mergeEditors(overrides);
-      // Probe only the editors that opt into the availability check; entries
-      // with `requireAvailable: false` (e.g. a shell alias) are shown
-      // regardless and don't need a `which` lookup.
       const probe = Array.from(
         new Set(
           editors
@@ -146,8 +140,6 @@ export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
         });
       } catch (reason) {
         console.error('xtralab: failed to load editor settings', reason);
-        // Settings load failed — fall back to the built-in editors so the
-        // launcher tile still resolves instead of going silent.
         await apply([]);
       }
     } else {