xtralab 0.10.0 → 0.11.0

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;

package/src/omnibox/model.ts

@@ -0,0 +1,210 @@
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { fileIcon, LabIcon } from '@jupyterlab/ui-components';
+import { StringExt } from '@lumino/algorithm';
+import type { CommandRegistry } from '@lumino/commands';
+
+import type { IAgent } from '../launcher/agents';
+import { agentCommandId } from '../launcher/tokens';
+
+/** The source a result row came from, used to group rows under a header. */
+export type OmniboxItemKind = 'command' | 'file' | 'agent';
+
+/** A single result row, with the action it runs when chosen. */
+export interface IOmniboxItem {
+  kind: OmniboxItemKind;
+  /** Stable React key. */
+  key: string;
+  /** Primary text shown on the row. */
+  label: string;
+  /** Indices of matched characters in `label`, for highlighting. May be empty. */
+  matchIndices: readonly number[];
+  /** Optional secondary text shown trailing the label. */
+  caption?: string;
+  /** Optional leading icon. */
+  icon?: LabIcon;
+  /** Run the row's action. */
+  execute: () => void;
+}
+
+/** Results grouped by source; each group is already capped and sorted. */
+export interface IOmniboxSections {
+  commands: IOmniboxItem[];
+  files: IOmniboxItem[];
+  agents: IOmniboxItem[];
+}
+
+export interface IComputeOptions {
+  query: string;
+  commands: CommandRegistry;
+  docRegistry: DocumentRegistry;
+  agents: IAgent[];
+  files: string[];
+  trans: TranslationBundle;
+}
+
+const COMMAND_LIMIT = 7;
+const FILE_LIMIT = 10;
+
+/**
+ * Prefixes that narrow the search to a single source: a leading `>` to
+ * commands, a leading `/` to files (relative paths never start with `/`, so it
+ * is unambiguous). Without a prefix, every source is searched.
+ */
+const COMMAND_PREFIX = '>';
+const FILE_PREFIX = '/';
+
+type Mode = 'all' | 'commands' | 'files';
+
+/**
+ * Build the grouped result set for a query. A leading `>` searches only
+ * commands and a leading `/` only files; otherwise commands and files are
+ * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
+ * carrying the query as its prompt. An empty term yields no rows (the widget
+ * shows a hint instead).
+ */
+export function computeSections(options: IComputeOptions): IOmniboxSections {
+  const { query, commands, docRegistry, agents, files, trans } = options;
+  const trimmed = query.trim();
+
+  let mode: Mode = 'all';
+  let term = trimmed;
+  if (trimmed.startsWith(COMMAND_PREFIX)) {
+    mode = 'commands';
+    term = trimmed.slice(COMMAND_PREFIX.length).trim();
+  } else if (trimmed.startsWith(FILE_PREFIX)) {
+    mode = 'files';
+    term = trimmed.slice(FILE_PREFIX.length).trim();
+  }
+
+  if (!term) {
+    return { commands: [], files: [], agents: [] };
+  }
+
+  return {
+    commands: mode === 'files' ? [] : matchCommands(commands, term),
+    files:
+      mode === 'commands' ? [] : matchFiles(commands, docRegistry, files, term),
+    // Agents only in the unprefixed view; the prompt is the full typed query.
+    agents: mode === 'all' ? buildAgentItems(commands, agents, term, trans) : []
+  };
+}
+
+function matchCommands(
+  commands: CommandRegistry,
+  term: string
+): IOmniboxItem[] {
+  const query = term.toLowerCase();
+  const scored: Array<{ score: number; item: IOmniboxItem }> = [];
+  for (const id of commands.listCommands()) {
+    let label = '';
+    let visible = true;
+    let caption = '';
+    try {
+      // A command's accessors can throw if they assume a context (e.g. an
+      // active notebook) the omnibox doesn't provide; skip those.
+      label = commands.label(id);
+      visible = commands.isVisible(id);
+      caption = commands.caption(id);
+    } catch {
+      continue;
+    }
+    if (!label || !visible) {
+      continue;
+    }
+    const match = StringExt.matchSumOfSquares(label.toLowerCase(), query);
+    if (!match) {
+      continue;
+    }
+    scored.push({
+      score: match.score,
+      item: {
+        kind: 'command',
+        key: `command:${id}`,
+        label,
+        matchIndices: match.indices,
+        caption: caption || undefined,
+        execute: () => {
+          void commands.execute(id).catch(reason => {
+            console.error(`xtralab omnibox: command "${id}" failed`, reason);
+          });
+        }
+      }
+    });
+  }
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, COMMAND_LIMIT).map(entry => entry.item);
+}
+
+function matchFiles(
+  commands: CommandRegistry,
+  docRegistry: DocumentRegistry,
+  files: string[],
+  term: string
+): IOmniboxItem[] {
+  const query = term.toLowerCase();
+  const scored: Array<{ score: number; path: string; indices: number[] }> = [];
+  for (const path of files) {
+    const match = StringExt.matchSumOfSquares(path.toLowerCase(), query);
+    if (match) {
+      scored.push({ score: match.score, path, indices: match.indices });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, FILE_LIMIT).map(({ path, indices }) => ({
+    kind: 'file',
+    key: `file:${path}`,
+    label: path,
+    matchIndices: indices,
+    icon: fileIconForPath(docRegistry, path),
+    execute: () => {
+      void commands.execute('docmanager:open', { path }).catch(reason => {
+        console.error(`xtralab omnibox: failed to open "${path}"`, reason);
+      });
+    }
+  }));
+}
+
+function fileIconForPath(docRegistry: DocumentRegistry, path: string): LabIcon {
+  for (const fileType of docRegistry.getFileTypesForPath(path)) {
+    if (fileType.icon) {
+      return fileType.icon;
+    }
+  }
+  return fileIcon;
+}
+
+function buildAgentItems(
+  commands: CommandRegistry,
+  agents: IAgent[],
+  prompt: string,
+  trans: TranslationBundle
+): IOmniboxItem[] {
+  const items: IOmniboxItem[] = [];
+  for (const agent of agents) {
+    // Agents without `promptArgs` can't take an inline prompt (the launcher
+    // would drop it), so they don't belong in an "Ask …" row.
+    if (agent.promptArgs === undefined) {
+      continue;
+    }
+    items.push({
+      kind: 'agent',
+      key: `agent:${agent.id}`,
+      label: trans.__('Ask %1', agent.label),
+      matchIndices: [],
+      caption: trans.__('Run prompt in a new terminal'),
+      icon: agent.icon,
+      execute: () => {
+        void commands
+          .execute(agentCommandId(agent.id), { prompt })
+          .catch(reason => {
+            console.error(
+              `xtralab omnibox: failed to start agent "${agent.id}"`,
+              reason
+            );
+          });
+      }
+    });
+  }
+  return items;
+}

package/src/omnibox/tokens.ts

@@ -0,0 +1,29 @@
+import { Token } from '@lumino/coreutils';
+
+/**
+ * A launcher overlay that fuzzy-searches across multiple sources — workspace
+ * files, JupyterLab commands — and routes a typed prompt to one of the
+ * configured agents. Provided by `xtralab:omnibox` and consumed (optionally)
+ * by the top-bar command bar, which opens it on click.
+ */
+export interface IOmnibox {
+  /** Open the overlay, optionally seeding the input with `query`. */
+  open(query?: string): void;
+  /** Close the overlay if it is open. */
+  close(): void;
+}
+
+/**
+ * DI token for {@link IOmnibox}. Provided by `xtralab:omnibox`; consumed by
+ * `xtralab:command-bar` so the top-bar pill opens the omnibox.
+ */
+export const IOmnibox = new Token<IOmnibox>(
+  'xtralab:IOmnibox',
+  'Opens the omnibox overlay that searches files and commands and prompts agents.'
+);
+
+/**
+ * Command id that opens the omnibox (registered by `xtralab:omnibox`). Shared
+ * here so the command bar can look up its keybinding and show a shortcut hint.
+ */
+export const OMNIBOX_OPEN_COMMAND = 'xtralab:omnibox:open';