xtralab 0.15.0 → 0.15.2

package/src/git/tokens.ts

@@ -1,21 +1,33 @@
 /**
- * Types shared by the git plugin. Mirror the response shapes returned by the
- * `jupyterlab_git` server extension's REST API so the frontend can stay
- * tightly coupled to a single version of those endpoints.
+ * Types shared by the git plugin, mirroring the response shapes of the
+ * `jupyterlab_git` server extension's REST API.
  */
 
 /**
- * A single entry in the `files` array returned by `POST /git/<path>/status`.
- * `x` and `y` are the porcelain-format index/worktree status codes (see
- * `git status --porcelain`); `to` is the file's current path relative to the
- * git repository root, `from` is the source path for renames (and equal to
- * `to` for any other status).
+ * One entry of the `files` array from `POST /git/<path>/status`. `x`/`y` are
+ * the porcelain index/worktree codes; `to` is the current repo-relative path
+ * and `from` the rename source (equal to `to` for any other status).
  */
 export interface IGitStatusFile {
+  /**
+   * The porcelain status code for the index side.
+   */
   x: string;
+  /**
+   * The porcelain status code for the worktree side.
+   */
   y: string;
+  /**
+   * The current repo-relative path of the file.
+   */
   to: string;
+  /**
+   * The rename source path; equal to `to` for any other status.
+   */
   from: string;
+  /**
+   * Whether the file content is binary; `null` when undetermined.
+   */
   is_binary: boolean | null;
 }
 
@@ -23,52 +35,68 @@ export interface IGitStatusFile {
  * Response shape of `POST /git/<path>/status`.
  */
 export interface IGitStatusResult {
+  /**
+   * The return code of the git command.
+   */
   code: number;
+  /**
+   * The current branch name; `null` when it is not available.
+   */
   branch: string | null;
+  /**
+   * The upstream remote branch; `null` when none is set.
+   */
   remote: string | null;
+  /**
+   * The number of commits ahead of the upstream branch.
+   */
   ahead: number;
+  /**
+   * The number of commits behind the upstream branch.
+   */
   behind: number;
+  /**
+   * The changed files reported by `git status`.
+   */
   files: IGitStatusFile[];
+  /**
+   * The in-progress repository state (merge, rebase, ...), when reported.
+   */
   state?: number;
+  /**
+   * An error message, present when the command fails.
+   */
   message?: string;
 }
 
 /**
- * Reference accepted by `POST /git/<path>/content` to identify which version
- * of a file to fetch. `WORKING` is the on-disk copy, `INDEX` is the staged
- * copy, and a `git` value is any commit-ish (`HEAD`, a SHA, …).
+ * Reference accepted by `POST /git/<path>/content`: `WORKING` is the on-disk
+ * copy, `INDEX` the staged copy, `git` any commit-ish.
  */
 export type GitReference =
   | { special: 'WORKING' | 'INDEX' | 'BASE' }
   | { git: string };
 
 /**
- * Response shape of `POST /git/<path>/content`. The server only returns text
- * content here; binary files are reported as binary in the status response,
- * and we surface them in the UI without attempting to render their diff.
+ * Response shape of `POST /git/<path>/content`.
  */
 export interface IGitContentResult {
+  /**
+   * The return code of the git command.
+   */
   code: number;
+  /**
+   * The file content at the requested reference.
+   */
   content: string;
+  /**
+   * An error message, present when the command fails.
+   */
   message?: string;
 }
 
-/**
- * Where a file's change lives relative to the index.
- *
- *   - `staged`   → present in the index, may differ from HEAD
- *   - `unstaged` → present in the worktree, differs from the index
- *
- * A single file can appear in both groups when the worktree has further
- * changes on top of an already-staged version. The panel models that as two
- * separate entries, one per group.
- */
 type FileChangeGroup = 'staged' | 'unstaged';
 
-/**
- * The user-facing status of a file change. Drives the single-letter badge
- * (M/A/D/R/U/?) shown next to each entry in the panel.
- */
 export type FileChangeStatus =
   | 'modified'
   | 'added'
@@ -80,14 +108,28 @@ export type FileChangeStatus =
   | 'unknown';
 
 /**
- * One row in the changes panel. `path` is the file's path relative to the
- * git repository root. `from` is non-`undefined` only for renames, in which
- * case it carries the original path.
+ * One row in the changes panel. `path` is repo-relative; `from` is set only
+ * for renames and carries the original path.
  */
 export interface IFileChange {
+  /**
+   * The repo-relative path of the file.
+   */
   path: string;
+  /**
+   * The rename source path, set only for renames.
+   */
   from?: string;
+  /**
+   * Whether the change is staged or unstaged.
+   */
   group: FileChangeGroup;
+  /**
+   * The change status derived from the porcelain codes.
+   */
   status: FileChangeStatus;
+  /**
+   * Whether the file content is binary; `null` when undetermined.
+   */
   isBinary: boolean | null;
 }

package/src/highlight/index.ts

@@ -13,22 +13,13 @@ import type { Widget } from '@lumino/widgets';
 
 const PLUGIN_ID = 'xtralab:highlight';
 
-/**
- * Highlight a contiguous range of lines, or clear every highlight. These are
- * the only two commands the plugin contributes; both are designed to be driven
- * by a coding agent over the MCP command bridge to walk a user through code.
- */
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 const CLEAR_HIGHLIGHTS_COMMAND = 'xtralab:clear-highlights';
 
-/**
- * CodeMirror line-decoration class; styled in style/highlight.css.
- */
 const HIGHLIGHT_LINE_CLASS = 'jp-xtralab-highlightLine';
 
 /**
- * A CodeMirror effect carrying the 1-indexed, inclusive line range to
- * highlight, or `null` to clear the editor's highlights.
+ * Carries the 1-indexed inclusive line range to highlight, or `null` to clear.
  */
 const setHighlight = StateEffect.define<{
   start: number;
@@ -36,9 +27,8 @@ const setHighlight = StateEffect.define<{
 } | null>();
 
 /**
- * Holds the highlight decorations for one editor. It is injected lazily (the
- * first time an editor is highlighted) via `StateEffect.appendConfig`, so
- * editors that are never highlighted pay nothing.
+ * Highlight decorations for one editor; injected lazily via
+ * `StateEffect.appendConfig` so editors never highlighted pay nothing.
  */
 const highlightField = StateField.define<DecorationSet>({
   create: () => Decoration.none,
@@ -68,11 +58,6 @@ const highlightField = StateField.define<DecorationSet>({
   provide: field => EditorView.decorations.from(field)
 });
 
-/**
- * Return the CodeMirror view backing a widget's file editor, or `null` when
- * the widget is not a CodeMirror-based text editor (a notebook, a terminal,
- * the settings editor, …).
- */
 function viewForWidget(widget: Widget | null): EditorView | null {
   const content = (widget as { content?: unknown } | null)?.content;
   return content instanceof FileEditor &&
@@ -81,26 +66,16 @@ function viewForWidget(widget: Widget | null): EditorView | null {
     : null;
 }
 
-/**
- * Coerce a JSON command argument to a positive integer line number, falling
- * back to `fallback` when it is missing or not a finite number.
- */
 function toLine(value: unknown, fallback: number): number {
   const n = Math.trunc(Number(value));
   return Number.isFinite(n) && n >= 1 ? n : fallback;
 }
 
 /**
- * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
- *
- * The built-in command surface can open a file (`docmanager:open`) and move
- * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
- * highlight a span of lines — `documentsearch:start` only marks text matches
- * and hijacks the find box. This plugin fills that gap with a CodeMirror line
- * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
- * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
- * scrolls the range into view, and replaces any previous highlight in that
- * editor; `xtralab:clear-highlights` removes every highlight.
+ * Contributes `xtralab:highlight-lines` and `xtralab:clear-highlights`,
+ * filling the persistent span-highlight gap in the core command surface
+ * (`documentsearch:start` only marks text matches and hijacks the find box)
+ * so an agent can point at lines while narrating a walkthrough.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -117,8 +92,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const { commands, shell } = app;
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
-    // Editors that currently carry a highlight, so a single clear can reach
-    // them all. Disposed editors are dropped on the next clear.
     const highlighted = new Set<EditorView>();
 
     const ensureField = (view: EditorView): void => {
@@ -130,8 +103,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
     commands.addCommand(HIGHLIGHT_LINES_COMMAND, {
       label: trans.__('Highlight Lines'),
       caption: trans.__('Highlight a range of lines in a text editor'),
-      // Advertise the argument shape so agents listing commands over the MCP
-      // bridge can see how to call it, the same way core commands do.
+      // Advertise the argument shape to agents listing commands over the MCP bridge.
       describedBy: {
         args: {
           type: 'object',
@@ -165,9 +137,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
           typeof args['path'] === 'string' ? args['path'] : undefined;
         const reveal = args['reveal'] !== false;
 
-        // With a path, bind strictly to that document: never fall back to the
-        // active widget, or an explicit path could silently highlight an
-        // unrelated editor that happens to be focused.
+        // With a path, bind strictly to that document — falling back to the
+        // active widget could silently highlight an unrelated editor.
         let widget: Widget | null;
         if (path) {
           // Fail fast on a missing path instead of opening a phantom widget
@@ -181,7 +152,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
           if (!opened) {
             throw new Error(`xtralab: could not open "${path}"`);
           }
-          // Wait for the model and the editor view to be ready.
           await opened.context.ready;
           await opened.revealed;
           widget = opened;
@@ -213,7 +183,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
           effects.push(EditorView.scrollIntoView(anchor, { y: 'center' }));
         }
         view.dispatch({ effects });
-        // Forget editors that have since been closed before tracking this one.
         for (const tracked of highlighted) {
           if (!tracked.dom.isConnected) {
             highlighted.delete(tracked);

package/src/index.ts

@@ -23,15 +23,6 @@ import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
 import walkthroughPlugin from './walkthrough';
 
-/**
- * Every plugin contributed by `xtralab`. The entry point of the
- * labextension is an array because the package bundles several independent
- * enhancements (file browser, git diff providers, …) — JupyterLab activates
- * each plugin individually and only the ones whose required tokens are
- * available end up running. `gitPlugins` and `launcherPlugins` are themselves
- * arrays (the git diff providers; the launcher plus its editor registry), so
- * they are spread in.
- */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   aboutPlugin,
   agentSessionsPlugin,

package/src/launcher/agents.ts

@@ -3,92 +3,98 @@ import { LabIcon, terminalIcon } from '@jupyterlab/ui-components';
 import { BUILTIN_AGENT_ICONS } from './icons';
 
 /**
- * The shape of an agent card on the launcher. The `command` is the literal
- * text typed into the new terminal session — interactive shells expand
- * aliases, so users can point at `claude`, `cl`, or whatever runs their
- * preferred wrapper.
+ * An agent card on the launcher. `command` is the literal text typed into the
+ * new terminal, so interactive-shell aliases resolve.
  */
 export interface IAgent {
+  /**
+   * Stable id; keys the settings merge and the per-agent launch command.
+   */
   id: string;
+  /**
+   * Card label, e.g. "Claude".
+   */
   label: string;
+  /**
+   * Card tooltip; also the palette command caption.
+   */
   caption: string;
+  /**
+   * The literal command typed into the new terminal.
+   */
   command: string;
+  /**
+   * Brand icon for the card.
+   */
   icon: LabIcon;
+  /**
+   * Sort position among the launcher's agent cards.
+   */
   rank: number;
   /**
-   * When false, the launcher skips the `which`-based availability check for
-   * this entry — useful for aliases or shell functions that aren't on PATH
-   * but still resolve when typed in a real terminal. Defaults to true.
+   * When false, skip the `which`-based availability check — for aliases or
+   * shell functions not on PATH. Defaults to true.
    */
   requireAvailable: boolean;
   /**
-   * Argv tokens spliced between `command` and a shell-quoted prompt when
-   * the user types one into the launcher's prompt box. The semantics:
-   *
-   *   - `[]` → prompt is appended as a positional argument:
-   *     `<command> 'PROMPT'`. (Used by claude, codex, vibe, pi.)
-   *   - `['-i']` / `['--prompt']` → the prompt is preceded by a flag:
-   *     `<command> -i 'PROMPT'`. (Used by copilot, opencode.)
-   *   - `undefined` → the agent does not accept an initial prompt. The
-   *     launcher dims the agent's button while the prompt textarea is
-   *     non-empty, so the user gets a clear signal rather than a silently
-   *     dropped prompt.
-   *
-   * The prompt itself is always single-quoted with embedded single quotes
-   * escaped, so multi-line prompts and shell metacharacters are safe.
+   * Argv tokens spliced between `command` and the shell-quoted prompt:
+   * `[]` appends the prompt positionally, `['-i']` prefixes a flag, and
+   * `undefined` means no prompt support (the launcher dims the button).
    */
   promptArgs?: string[];
 }
 
 /**
- * The settings-side shape: every field except `id` is optional, so a user
- * can override a single field on a default agent (e.g. swap the command for
- * an alias) without restating the whole entry. New ids define brand-new
- * agent cards.
+ * The settings-side shape: every field except `id` is optional so a user can
+ * override a single field on a default agent; new ids define new agent cards.
  */
 export interface IAgentSettings {
+  /**
+   * Id of the agent to override; a new id defines a new card.
+   */
   id: string;
+  /**
+   * See `IAgent.label`.
+   */
   label?: string;
+  /**
+   * See `IAgent.caption`.
+   */
   caption?: string;
+  /**
+   * See `IAgent.command`.
+   */
   command?: string;
   /**
-   * Inline SVG for a custom agent's icon. Required for new ids whose icon
-   * isn't shipped with xtralab; ignored for default ids unless explicitly
-   * set (in which case it overrides the built-in).
+   * Inline SVG icon. Required for new ids; overrides the built-in when set on
+   * a default id.
    */
   iconSvg?: string;
+  /**
+   * See `IAgent.rank`.
+   */
   rank?: number;
   /**
-   * When false, the agent is hidden from the launcher and the command
-   * palette. Defaults to true.
+   * When false, hides the agent from the launcher and the command palette.
    */
   enabled?: boolean;
   /**
-   * See `IAgent.requireAvailable`. Defaults to true for a built-in agent that
-   * still uses its shipped command, and to false once you override the
-   * `command` (a user-chosen command — often a shell alias — is trusted and
-   * always shown). Set it explicitly to force the check on or off.
+   * See `IAgent.requireAvailable`. Defaults to true, but flips to false once
+   * `command` is overridden (a user-chosen alias is trusted).
    */
   requireAvailable?: boolean;
   /**
-   * See `IAgent.promptArgs`. Pass an empty array to mark the agent as
-   * accepting a positional prompt; pass an array like `["-p"]` to use a
-   * flag. Pass `null` to explicitly turn off prompt support for an agent
-   * that has it on by default.
+   * See `IAgent.promptArgs`. `null` explicitly turns off an agent's default
+   * prompt support.
    */
   promptArgs?: string[] | null;
 }
 
 /**
- * Default agent cards shipped with xtralab. Seven of these (Claude, Codex,
- * Copilot, Goose, OpenCode, Kiro, Mistral Vibe) mirror first-class personas
- * in `jupyter-ai-contrib/jupyter-ai-acp-client` (which is also where their
- * icons come from), but use the bare CLI names a user would type in a
- * terminal rather than the ACP wrapper binaries that project spawns.
- * Antigravity (Google's agent-first IDE/CLI, `agy`) is the Google agent.
- * Pi (https://pi.dev, `earendil-works/pi`) is a minimal extensible coding
- * agent; its mark comes straight from its site. Anything not on the user's
- * `$PATH` is filtered out at activation time, so the wider list is harmless.
+ * Default agent cards. Most mirror `jupyter-ai-contrib/jupyter-ai-acp-client`
+ * personas but use the bare CLI names a user would type, not the ACP wrappers.
+ * Anything not on `$PATH` is filtered out at activation, so the wide list is
+ * harmless.
  */
 const DEFAULTS: IAgent[] = [
   {
@@ -119,13 +125,8 @@ const DEFAULTS: IAgent[] = [
     icon: BUILTIN_AGENT_ICONS.antigravity,
     rank: 2,
     requireAvailable: true
-    // `agy` is the Antigravity launcher binary — a VS Code-derived editor
-    // CLI that opens the Agent Manager / workspace, not a terminal REPL.
-    // Its positional args are file/folder paths, so there is no inline
-    // natural-language prompt form; like goose/kiro we omit promptArgs so a
-    // typed prompt dims the button instead of being mangled into a path.
-    // The command stays the bare binary (no `agy .`) so the server-side
-    // `shutil.which` availability check still resolves it.
+    // `agy` opens the Antigravity editor; its positional args are paths, not
+    // prompts, and the bare binary keeps the server-side `which` check working.
   },
   {
     id: 'copilot',
@@ -135,8 +136,7 @@ const DEFAULTS: IAgent[] = [
     icon: BUILTIN_AGENT_ICONS.copilot,
     rank: 3,
     requireAvailable: true,
-    // `-i "PROMPT"` is the documented way to start interactive mode and
-    // auto-execute the prompt; `-p` exits after responding (non-interactive).
+    // `-i` starts interactive mode with the prompt; `-p` exits after responding.
     promptArgs: ['-i']
   },
   {
@@ -147,8 +147,7 @@ const DEFAULTS: IAgent[] = [
     icon: BUILTIN_AGENT_ICONS.goose,
     rank: 4,
     requireAvailable: true
-    // `goose` does not accept an inline interactive prompt; users would
-    // need to type the prompt after `goose session` starts.
+    // `goose` takes no inline prompt; it must be typed after `goose session`.
   },
   {
     id: 'opencode',
@@ -168,8 +167,7 @@ const DEFAULTS: IAgent[] = [
     icon: BUILTIN_AGENT_ICONS.kiro,
     rank: 6,
     requireAvailable: true
-    // The Kiro chat session only takes initial prompts via the in-session
-    // `/chat new <prompt>` slash command, not a CLI argument.
+    // Kiro only takes initial prompts via the in-session `/chat new` command.
   },
   {
     id: 'mistral-vibe',
@@ -189,17 +187,13 @@ const DEFAULTS: IAgent[] = [
     icon: BUILTIN_AGENT_ICONS.pi,
     rank: 8,
     requireAvailable: true,
-    // `pi [messages...]` starts the interactive TUI and sends the messages
-    // as the first user prompt, so the positional form applies.
     promptArgs: []
   }
 ];
 
 /**
- * The built-in agents projected into the JSON settings shape
- * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
- * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
- * schema default so the Settings Editor shows the shipped list.
+ * The built-in agents projected into the settings shape (no runtime LabIcon),
+ * injected as the `agents` schema default so the Settings Editor shows them.
  */
 export function defaultAgentSettings(): IAgentSettings[] {
   return DEFAULTS.map(agent => {
@@ -211,8 +205,6 @@ export function defaultAgentSettings(): IAgentSettings[] {
       rank: agent.rank,
       requireAvailable: agent.requireAvailable
     };
-    // Omit `promptArgs` for agents that don't take an inline prompt, so the
-    // default doesn't show a prompt form they lack.
     if (agent.promptArgs !== undefined) {
       entry.promptArgs = agent.promptArgs;
     }
@@ -228,15 +220,10 @@ function resolveIcon(id: string, iconSvg: string | undefined): LabIcon {
 }
 
 /**
- * Merge xtralab's defaults with the user's settings. Default entries keep
- * their built-in fields unless explicitly overridden; user-only entries are
- * appended. `enabled: false` filters an entry out of the result entirely
- * (so callers don't need to check the flag again).
- *
- * Overriding a built-in agent's `command` also turns its `requireAvailable`
- * off, so the card survives the launcher's `which`-based availability filter
- * even when the new command is a shell alias the server can't resolve. See the
- * built-in branch below for the rationale.
+ * Merge xtralab's defaults with the user's settings: defaults keep their
+ * fields unless overridden, user-only ids are appended, and `enabled: false`
+ * removes an entry entirely. Overriding a built-in's `command` also turns
+ * `requireAvailable` off so an aliased command survives the `which` filter.
  */
 export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
   const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
@@ -262,24 +249,10 @@ export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
         ? resolveIcon(base.id, override.iconSvg)
         : base.icon,
       rank: override.rank ?? base.rank,
-      // The availability filter exists to prune xtralab's *built-in* command
-      // from the launcher when it isn't installed. Once the user points the
-      // agent at their own command — e.g. the `ccm` alias wrapping `claude
-      // --effort=max …` — the server's `shutil.which` probe can't see it
-      // (aliases and shell functions only exist inside an interactive shell),
-      // so keeping the check on would wrongly hide the card. We therefore only
-      // require availability while the command is still xtralab's default; a
-      // user-chosen command is trusted and always shown. An explicit
-      // `requireAvailable` still applies to the unchanged default command, so a
-      // user can alias `claude` itself and set `requireAvailable: false` (or
-      // force the check back on).
       requireAvailable:
         command === base.command
           ? (override.requireAvailable ?? base.requireAvailable)
           : false,
-      // `null` is the explicit way to opt out of an agent's default prompt
-      // support; an absent key keeps the default. `undefined` from `??` is
-      // pruned below.
       promptArgs:
         override.promptArgs === null
           ? undefined
@@ -287,10 +260,6 @@ export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
     });
   }
 
-  // What remains in `overrideById` are entries with ids that don't match a
-  // default — treat them as new agents the user is adding. Skip silently
-  // when a required field is missing rather than throwing; the settings
-  // schema validates the shape, so this is just a defensive fallback.
   let nextRank =
     merged.reduce((max, agent) => Math.max(max, agent.rank), -1) + 1;
   for (const entry of overrideById.values()) {

package/src/launcher/availability.ts

@@ -2,15 +2,9 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 
 /**
- * Hit the xtralab server extension's `which`-proxy endpoint and turn the
- * response into a Set of commands that resolved to a real binary on the
- * server's `$PATH`. The frontend uses this set to filter the launcher's
- * agent cards.
- *
- * On any failure (server extension not loaded, network error, malformed
- * response) the returned Set is `null` — callers should treat that as
- * "availability unknown" and either fall back to showing all agents or
- * surface the error, depending on context.
+ * Ask the server extension's `which`-proxy endpoint which commands resolve on
+ * its `$PATH`. Returns `null` on any failure — callers should treat that as
+ * "availability unknown", not as "nothing available".
  */
 export async function fetchAvailableCommands(
   commands: string[]