xtralab 0.9.0 → 0.11.0

package/src/highlight/index.ts

@@ -0,0 +1,251 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { CodeMirrorEditor } from '@jupyterlab/codemirror';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { StateEffect, StateField } from '@codemirror/state';
+import { Decoration, DecorationSet, EditorView } from '@codemirror/view';
+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.
+ */
+const setHighlight = StateEffect.define<{
+  start: number;
+  end: number;
+} | 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.
+ */
+const highlightField = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update(decorations, transaction) {
+    // Keep decorations anchored as the user edits around them.
+    decorations = decorations.map(transaction.changes);
+    for (const effect of transaction.effects) {
+      if (!effect.is(setHighlight)) {
+        continue;
+      }
+      if (effect.value === null) {
+        decorations = Decoration.none;
+        continue;
+      }
+      const { doc } = transaction.state;
+      const lineDecoration = Decoration.line({ class: HIGHLIGHT_LINE_CLASS });
+      const start = Math.max(1, Math.min(effect.value.start, doc.lines));
+      const end = Math.max(start, Math.min(effect.value.end, doc.lines));
+      const ranges = [];
+      for (let line = start; line <= end; line++) {
+        ranges.push(lineDecoration.range(doc.line(line).from));
+      }
+      decorations = Decoration.set(ranges);
+    }
+    return decorations;
+  },
+  provide: field => EditorView.decorations.from(field)
+});
+
+/**
+ * Return the CodeMirror view backing a widget's editor, or `null` when the
+ * widget is not a CodeMirror-based text editor (a notebook, a terminal, the
+ * settings editor, …). Duck-typed on `content.editor` so the plugin does not
+ * depend on `@jupyterlab/fileeditor`.
+ */
+function viewForWidget(widget: Widget | null): EditorView | null {
+  const editor = (widget as { content?: { editor?: unknown } } | null)?.content
+    ?.editor;
+  return editor instanceof CodeMirrorEditor ? editor.editor : 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.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Highlight line ranges in text editors to guide walkthroughs.',
+  autoStart: true,
+  requires: [IDocumentManager],
+  optional: [ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    docManager: IDocumentManager,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): 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 => {
+      if (view.state.field(highlightField, false) === undefined) {
+        view.dispatch({ effects: StateEffect.appendConfig.of(highlightField) });
+      }
+    };
+
+    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.
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description:
+                'Path of the file to highlight in, relative to the server root. Opened if needed; defaults to the active editor when omitted.'
+            },
+            line: {
+              type: 'number',
+              description: 'First line to highlight (1-indexed). Defaults to 1.'
+            },
+            endLine: {
+              type: 'number',
+              description:
+                'Last line to highlight (1-indexed, inclusive). Defaults to `line` for a single line.'
+            },
+            reveal: {
+              type: 'boolean',
+              description:
+                'Whether to scroll the highlighted range into view. Defaults to true.'
+            }
+          }
+        }
+      },
+      execute: async args => {
+        const line = toLine(args['line'], 1);
+        const endLine = toLine(args['endLine'], line);
+        const path =
+          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.
+        let widget: Widget | null;
+        if (path) {
+          // Fail fast on a missing path instead of opening a phantom widget
+          // behind a blocking "file not found" dialog.
+          try {
+            await docManager.services.contents.get(path, { content: false });
+          } catch {
+            throw new Error(`xtralab: no file at "${path}"`);
+          }
+          const opened = docManager.openOrReveal(path);
+          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;
+        } else {
+          widget = shell.currentWidget;
+        }
+
+        const view = viewForWidget(widget);
+        if (!view) {
+          throw new Error(
+            path
+              ? `xtralab: "${path}" is not open in a text editor`
+              : 'xtralab: the active widget is not a text editor'
+          );
+        }
+
+        const start = Math.min(line, endLine);
+        const end = Math.max(line, endLine);
+        ensureField(view);
+
+        const lineCount = view.state.doc.lines;
+        const anchor = view.state.doc.line(
+          Math.max(1, Math.min(start, lineCount))
+        ).from;
+        const effects: StateEffect<unknown>[] = [
+          setHighlight.of({ start, end })
+        ];
+        if (reveal) {
+          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);
+          }
+        }
+        highlighted.add(view);
+
+        return start === end
+          ? trans.__('Highlighted line %1', start)
+          : trans.__('Highlighted lines %1-%2', start, end);
+      }
+    });
+
+    commands.addCommand(CLEAR_HIGHLIGHTS_COMMAND, {
+      label: trans.__('Clear Highlights'),
+      caption: trans.__('Remove all xtralab line highlights'),
+      execute: () => {
+        for (const view of highlighted) {
+          try {
+            if (view.state.field(highlightField, false) !== undefined) {
+              view.dispatch({ effects: setHighlight.of(null) });
+            }
+          } catch {
+            // The editor was disposed; nothing to clear.
+          }
+        }
+        highlighted.clear();
+      }
+    });
+
+    if (palette) {
+      const category = trans.__('Other');
+      palette.addItem({ command: HIGHLIGHT_LINES_COMMAND, category });
+      palette.addItem({ command: CLEAR_HIGHLIGHTS_COMMAND, category });
+    }
+  }
+};
+
+export default plugin;

package/src/index.ts

@@ -1,16 +1,23 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 
 import agentSessionsPlugin from './agentSessions';
+import commandBarPlugin from './commandBar';
 import fileBrowserPlugin from './fileBrowser';
 import fileTypeIconsPlugin from './fileTypeIcons';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
+import highlightPlugin from './highlight';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
+import omniboxPlugin from './omnibox';
+import searchReplacePlugin from './searchReplace';
+import showOutputPlugin from './showOutput';
 import sidebarPlugin from './sidebar';
+import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
+import walkthroughPlugin from './walkthrough';
 
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
@@ -23,16 +30,23 @@ import topBarPlugin from './topBar';
  */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   agentSessionsPlugin,
+  commandBarPlugin,
   editorBreadcrumbsPlugin,
   editorIndentPlugin,
   fileBrowserPlugin,
   fileTypeIconsPlugin,
   ...gitPlugins,
+  highlightPlugin,
   ...launcherPlugins,
   menusPlugin,
+  omniboxPlugin,
+  searchReplacePlugin,
+  showOutputPlugin,
   sidebarPlugin,
+  terminalNotificationsPlugin,
   terminalsPlugin,
-  topBarPlugin
+  topBarPlugin,
+  walkthroughPlugin
 ];
 
 export default plugins;

package/src/launcher/agents.ts

@@ -178,6 +178,31 @@ const DEFAULTS: IAgent[] = [
   }
 ];
 
+/**
+ * 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.
+ */
+export function defaultAgentSettings(): IAgentSettings[] {
+  return DEFAULTS.map(agent => {
+    const entry: IAgentSettings = {
+      id: agent.id,
+      label: agent.label,
+      caption: agent.caption,
+      command: agent.command,
+      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;
+    }
+    return entry;
+  });
+}
+
 function resolveIcon(id: string, iconSvg: string | undefined): LabIcon {
   if (iconSvg) {
     return new LabIcon({ name: `xtralab:agent-custom-${id}`, svgstr: iconSvg });

package/src/launcher/editorRegistry.ts

@@ -13,6 +13,10 @@ import {
   type IEditor,
   type IEditorSettings
 } from './editors';
+import {
+  LAUNCHER_PLUGIN_ID,
+  registerLauncherSchemaDefaults
+} from './schemaDefaults';
 
 /**
  * A read-only, observable view of the launcher's terminal editors: xtralab's
@@ -80,9 +84,6 @@ class EditorRegistry implements IEditorRegistry {
   private _changed = new Signal<IEditorRegistry, void>(this);
 }
 
-/** Schema id the `editors` setting lives under (shared with the launcher). */
-const LAUNCHER_SETTINGS_ID = 'xtralab:launcher';
-
 /**
  * Provides {@link IEditorRegistry}: merges xtralab's built-in editors with the
  * user's `editors` setting, probes the server's `$PATH` to resolve the launcher
@@ -124,8 +125,11 @@ export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
     };
 
     if (settingRegistry) {
+      // Must precede the first `load`: the schema defers loading until a
+      // transform is registered.
+      registerLauncherSchemaDefaults(settingRegistry);
       try {
-        const settings = await settingRegistry.load(LAUNCHER_SETTINGS_ID);
+        const settings = await settingRegistry.load(LAUNCHER_PLUGIN_ID);
         await apply(readOverrides(settings));
         settings.changed.connect(async () => {
           try {

package/src/launcher/editors.ts

@@ -88,6 +88,24 @@ const DEFAULTS: IEditor[] = [
   }
 ];
 
+/**
+ * The built-in editors projected into the JSON settings shape
+ * ({@link IEditorSettings}), dropping the runtime-only {@link LabIcon}. Mirrors
+ * {@link defaultAgentSettings}: {@link registerLauncherSchemaDefaults} injects
+ * this as the `editors` setting's schema default so the Settings Editor shows
+ * the shipped list.
+ */
+export function defaultEditorSettings(): IEditorSettings[] {
+  return DEFAULTS.map(editor => ({
+    id: editor.id,
+    label: editor.label,
+    caption: editor.caption,
+    command: editor.command,
+    rank: editor.rank,
+    requireAvailable: editor.requireAvailable
+  }));
+}
+
 function resolveEditorIcon(id: string, iconSvg: string | undefined): LabIcon {
   if (iconSvg) {
     return new LabIcon({

package/src/launcher/index.ts

@@ -19,6 +19,7 @@ import { CREATE_LAUNCHER_COMMAND, registerAgentCommands } from './commands';
 import { LauncherDashboard } from './dashboard';
 import { editorRegistryPlugin, IEditorRegistry } from './editorRegistry';
 import { AgentRegistry } from './registry';
+import { registerLauncherSchemaDefaults } from './schemaDefaults';
 import { IAgentRegistry } from './tokens';
 
 const PLUGIN_ID = 'xtralab:launcher';
@@ -110,6 +111,9 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
     };
 
     if (settingRegistry) {
+      // Must precede the first `load`: the schema defers loading until a
+      // transform is registered.
+      registerLauncherSchemaDefaults(settingRegistry);
       try {
         const settings = await settingRegistry.load(PLUGIN_ID);
         await applyAgents(readOverrides(settings));

package/src/launcher/schemaDefaults.ts

@@ -0,0 +1,53 @@
+import type { PartialJSONValue } from '@lumino/coreutils';
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { defaultAgentSettings } from './agents';
+import { defaultEditorSettings } from './editors';
+
+/** Schema id the launcher's `agents`/`editors` settings live under. */
+export const LAUNCHER_PLUGIN_ID = 'xtralab:launcher';
+
+/**
+ * Setting registries that already have the transform, so both callers skip
+ * re-registering (the registry rejects a duplicate transformer).
+ */
+const registered = new WeakSet<ISettingRegistry>();
+
+/**
+ * Register a `fetch` transform that injects xtralab's built-in agent and
+ * editor lists as the schema defaults for the `xtralab:launcher` settings, so
+ * the Settings Editor shows the shipped list.
+ *
+ * The schema declares `jupyter.lab.transform: true`, so the registry defers
+ * loading the plugin until a transform is registered: callers must invoke this
+ * before their first `settingRegistry.load(LAUNCHER_PLUGIN_ID)`. Idempotent, so
+ * the two plugins that load these settings can both call it regardless of
+ * activation order.
+ */
+export function registerLauncherSchemaDefaults(
+  settingRegistry: ISettingRegistry
+): void {
+  if (registered.has(settingRegistry)) {
+    return;
+  }
+  registered.add(settingRegistry);
+
+  settingRegistry.transform(LAUNCHER_PLUGIN_ID, {
+    fetch: plugin => {
+      const properties = plugin.schema.properties;
+      if (properties) {
+        // The settings shapes are plain JSON by construction, but their named
+        // interfaces lack an index signature, so cast at this TS→JSON boundary.
+        if (properties.agents) {
+          properties.agents.default =
+            defaultAgentSettings() as unknown as PartialJSONValue;
+        }
+        if (properties.editors) {
+          properties.editors.default =
+            defaultEditorSettings() as unknown as PartialJSONValue;
+        }
+      }
+      return plugin;
+    }
+  });
+}

package/src/omnibox/files.ts

@@ -0,0 +1,68 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+
+/**
+ * Shape of the `jupyterlab-quickopen` `api/files` response: a map from each
+ * directory (relative to the server root, `""` for the root itself) to the
+ * bare filenames it contains.
+ */
+interface IQuickOpenContents {
+  contents: { [dir: string]: string[] };
+}
+
+/**
+ * Fetch and flatten the workspace file list from `jupyterlab-quickopen`'s
+ * server endpoint (`GET {base}/jupyterlab-quickopen/api/files`).
+ *
+ * We reuse quickopen's endpoint rather than walking the contents API so the
+ * listing honors the same server-side `.gitignore` filtering quickopen does
+ * (xtralab ships `respectGitignore: true`) in a single request. The endpoint
+ * only exists when quickopen's server extension is installed and the server
+ * reads a local filesystem; callers treat a rejection as "no file results".
+ */
+async function fetchWorkspaceFiles(respectGitignore = true): Promise<string[]> {
+  const settings = ServerConnection.makeSettings();
+  const params = new URLSearchParams();
+  if (respectGitignore) {
+    params.append('respect_gitignore', '1');
+  }
+  // The handler requires a `path` argument; `""` scans from the root.
+  params.append('path', '');
+  const url =
+    URLExt.join(settings.baseUrl, 'jupyterlab-quickopen', 'api', 'files') +
+    `?${params.toString()}`;
+
+  const response = await ServerConnection.makeRequest(
+    url,
+    { method: 'GET' },
+    settings
+  );
+  if (response.status !== 200) {
+    throw new ServerConnection.ResponseError(response);
+  }
+  const data = (await response.json()) as IQuickOpenContents;
+  const paths: string[] = [];
+  for (const dir in data.contents) {
+    for (const name of data.contents[dir]) {
+      paths.push(dir ? `${dir}/${name}` : name);
+    }
+  }
+  return paths;
+}
+
+const CACHE_TTL_MS = 15_000;
+let cache: { at: number; files: Promise<string[]> } | null = null;
+
+/**
+ * The workspace file list, cached briefly so reopening the omnibox in quick
+ * succession reuses one scan. A failed fetch (e.g. quickopen's server
+ * extension is absent) resolves to an empty list so file search degrades to
+ * "no results" instead of surfacing an error.
+ */
+export function loadWorkspaceFiles(): Promise<string[]> {
+  const now = Date.now();
+  if (!cache || now - cache.at > CACHE_TTL_MS) {
+    cache = { at: now, files: fetchWorkspaceFiles().catch(() => []) };
+  }
+  return cache.files;
+}

package/src/omnibox/index.ts

@@ -0,0 +1,105 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { Widget } from '@lumino/widgets';
+
+import { IAgentRegistry } from '../launcher/tokens';
+
+import { IOmnibox, OMNIBOX_OPEN_COMMAND } from './tokens';
+import { OmniboxWidget } from './widget';
+
+const PLUGIN_ID = 'xtralab:omnibox';
+
+/**
+ * The omnibox: a single launcher overlay that fuzzy-searches workspace files
+ * (via jupyterlab-quickopen's gitignore-aware endpoint) and JupyterLab
+ * commands, and routes a typed prompt to one of the configured agents (running
+ * it in a fresh terminal through the launcher's `xtralab:start-agent:<id>`
+ * commands). It is opened by the top-bar command bar.
+ *
+ * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
+ * is disabled the omnibox still searches files and commands.
+ */
+const plugin: JupyterFrontEndPlugin<IOmnibox> = {
+  id: PLUGIN_ID,
+  description:
+    'A launcher overlay that searches files and commands and prompts agents.',
+  autoStart: true,
+  provides: IOmnibox,
+  optional: [IAgentRegistry, ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    agentRegistry: IAgentRegistry | null,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): IOmnibox => {
+    const { commands, docRegistry } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const placeholder = trans.__('Search files and commands, or ask an agent…');
+
+    let current: OmniboxWidget | null = null;
+
+    const close = (): void => {
+      const widget = current;
+      current = null;
+      widget?.dispose();
+    };
+
+    const open = (query?: string): void => {
+      // Reopen fresh each time so the input resets and the agent snapshot is
+      // current; the file list is cached separately (see files.ts).
+      close();
+      const widget = new OmniboxWidget({
+        commands,
+        docRegistry,
+        agents: agentRegistry ? agentRegistry.agents : [],
+        placeholder,
+        initialQuery: query ?? '',
+        trans,
+        onClose: close
+      });
+      current = widget;
+      widget.disposed.connect(() => {
+        if (current === widget) {
+          current = null;
+        }
+      });
+      Widget.attach(widget, document.body);
+    };
+
+    commands.addCommand(OMNIBOX_OPEN_COMMAND, {
+      label: trans.__('Search…'),
+      caption: trans.__('Search files and commands, or ask an agent'),
+      execute: args => {
+        // Toggle: a second press (e.g. of the keyboard shortcut) closes it.
+        if (current && !current.isDisposed) {
+          close();
+          return;
+        }
+        const query = args['query'];
+        open(typeof query === 'string' ? query : undefined);
+      }
+    });
+
+    // Open the omnibox with Cmd/Ctrl+K, the common "command center" chord.
+    commands.addKeyBinding({
+      command: OMNIBOX_OPEN_COMMAND,
+      keys: ['Accel K'],
+      selector: 'body'
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: OMNIBOX_OPEN_COMMAND,
+        category: trans.__('Other')
+      });
+    }
+
+    return { open, close };
+  }
+};
+
+export default plugin;