xtralab 0.5.0 → 0.7.0

package/lib/launcher/commands.js

@@ -1,16 +1,10 @@
 import { DisposableSet } from '@lumino/disposable';
 import { buildAgentInvocation } from './invocation';
+import { agentCommandId } from './tokens';
 /**
  * The command id for opening the launcher.
  */
 export const CREATE_LAUNCHER_COMMAND = 'launcher:create';
-/**
- * Build a JupyterLab command id for a given agent. Centralised so the
- * plugin and the launcher both use the same names.
- */
-export function agentCommandId(agentId) {
-    return `xtralab:start-agent:${agentId}`;
-}
 /**
  * Register a JupyterLab command per agent. Each command opens a new
  * terminal via `terminal:create-new` and feeds the agent's shell command
@@ -19,8 +13,13 @@ export function agentCommandId(agentId) {
  * 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).
  */
-export function registerAgentCommands(app, agents) {
+export function registerAgentCommands(app, agents, agentSessions = null) {
     const disposables = new DisposableSet();
     for (const agent of agents) {
         const disposable = app.commands.addCommand(agentCommandId(agent.id), {
@@ -32,58 +31,83 @@ export function registerAgentCommands(app, agents) {
                 const promptArg = args['prompt'];
                 const prompt = typeof promptArg === 'string' ? promptArg : '';
                 const invocation = buildAgentInvocation(agent, prompt);
-                const main = (await app.commands.execute('terminal:create-new', {
-                    cwd
-                }));
-                // `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.
-                await main.revealed;
-                const session = main.content.session;
-                const sendCommand = () => {
-                    session.send({
-                        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 `applyAgentLabel` 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.
-                    applyAgentLabel();
-                };
-                const applyAgentLabel = () => {
-                    if (main.isDisposed || main.content.isDisposed) {
-                        return;
-                    }
-                    main.content.title.label = agent.label;
-                };
-                // 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 agent command silently disappears.
-                if (session.connectionStatus === 'connected') {
-                    sendCommand();
-                }
-                else {
-                    const onStatus = () => {
-                        if (session.connectionStatus === 'connected') {
-                            session.connectionStatusChanged.disconnect(onStatus);
-                            sendCommand();
-                        }
-                    };
-                    session.connectionStatusChanged.connect(onStatus);
-                }
-                return main;
+                return launchInTerminal(app.commands, {
+                    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.
+                    onSession: name => agentSessions === null || agentSessions === void 0 ? void 0 : agentSessions.set(name, agent.command)
+                });
             }
         });
         disposables.add(disposable);
     }
     return disposables;
 }
+/**
+ * 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.
+ */
+export async function launchInTerminal(commands, options) {
+    const { cwd, invocation, label, onSession } = options;
+    const main = (await commands.execute('terminal:create-new', {
+        cwd
+    }));
+    // `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.
+    await main.revealed;
+    const session = main.content.session;
+    onSession === null || onSession === void 0 ? void 0 : onSession(session.name);
+    const applyLabel = () => {
+        if (main.isDisposed || main.content.isDisposed) {
+            return;
+        }
+        main.content.title.label = label;
+    };
+    const sendCommand = () => {
+        session.send({
+            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.
+        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.
+    if (session.connectionStatus === 'connected') {
+        sendCommand();
+    }
+    else {
+        const onStatus = () => {
+            if (session.connectionStatus === 'connected') {
+                session.connectionStatusChanged.disconnect(onStatus);
+                sendCommand();
+            }
+        };
+        session.connectionStatusChanged.connect(onStatus);
+    }
+    return main;
+}

package/lib/launcher/dashboard.d.ts

@@ -2,7 +2,9 @@ import * as React from 'react';
 import type { CommandRegistry } from '@lumino/commands';
 import { ReactWidget } from '@jupyterlab/ui-components';
 import type { Widget } from '@lumino/widgets';
+import type { IAgentSessions } from '../agentSessions';
 import type { IAgent } from './agents';
+import type { IEditor } from './editors';
 /**
  * Public construction options for the launcher dashboard widget. The
  * plugin supplies an `onAgentLaunch` callback that performs the same
@@ -17,6 +19,19 @@ export interface ILauncherDashboardOptions {
      * rank; the widget renders them as-is.
      */
     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.
+     */
+    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.
+     */
+    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.

package/lib/launcher/dashboard.js

@@ -3,7 +3,8 @@ import { Poll } from '@lumino/polling';
 import { LabIcon, ReactWidget, consoleIcon, notebookIcon, refreshIcon, terminalIcon } from '@jupyterlab/ui-components';
 import { expandStatusFiles, status } from '../git/api';
 import { CommandIDs as GitCommandIDs } from '../git/commands';
-import { agentCommandId } from './commands';
+import { launchInTerminal } from './commands';
+import { agentCommandId } from './tokens';
 /**
  * Lumino host for the React-based launcher dashboard. Mirrors the
  * `ReactWidget` pattern used by the git panel so the rest of the plugin
@@ -32,7 +33,7 @@ const CHANGES_POLL_INTERVAL_MS = 8000;
  */
 const CHANGES_POLL_MAX_MS = 300000;
 function LauncherDashboardComponent(props) {
-    const { commands, agents, onAgentLaunch, repoPath, cwd } = props;
+    const { commands, agents, editor, agentSessions, onAgentLaunch, repoPath, cwd } = props;
     const [prompt, setPrompt] = React.useState('');
     const [git, setGit] = React.useState({
         loading: true,
@@ -90,13 +91,28 @@ function LauncherDashboardComponent(props) {
         }
     }, [commands, cwd, onAgentLaunch]);
     const launchNotebook = React.useCallback(async () => {
-        // No `kernelName` — let the notebook extension fall back to the default
-        // kernel or prompt the user, matching the stock launcher's notebook
-        // tile behavior.
-        const result = (await commands.execute('notebook:create-new', {
-            cwd
+        // 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.
+        const file = (await commands.execute('docmanager:new-untitled', {
+            path: cwd,
+            type: 'notebook'
+        }));
+        if (!file) {
+            return;
+        }
+        const result = (await commands.execute('docmanager:open', {
+            path: file.path,
+            factory: 'Notebook',
+            kernelPreference: { shouldStart: false, canStart: true }
         }));
         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.
+            result.isUntitled = true;
             onAgentLaunch(result);
         }
     }, [commands, cwd, onAgentLaunch]);
@@ -108,13 +124,30 @@ function LauncherDashboardComponent(props) {
             onAgentLaunch(result);
         }
     }, [commands, cwd, onAgentLaunch]);
+    const launchEditor = React.useCallback(async () => {
+        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,
+            label: editor.label,
+            onSession: name => agentSessions === null || agentSessions === void 0 ? void 0 : agentSessions.set(name, editor.command)
+        });
+        onAgentLaunch(result);
+    }, [commands, cwd, editor, agentSessions, onAgentLaunch]);
     const openDiff = React.useCallback((change) => {
         const args = { repoPath, change };
         void commands.execute(GitCommandIDs.openDiff, args);
     }, [commands, repoPath]);
     return (React.createElement("div", { className: "jp-xtralab-Launcher-body" },
         React.createElement(AgentSection, { agents: agents, prompt: prompt, onPromptChange: setPrompt, onLaunch: launch }),
-        React.createElement(OpenSection, { onLaunchTerminal: launchTerminal, onLaunchNotebook: launchNotebook, onLaunchConsole: launchConsole }),
+        React.createElement(McpSection, { agents: agents }),
+        React.createElement(OpenSection, { editor: editor, onLaunchTerminal: launchTerminal, onLaunchNotebook: launchNotebook, onLaunchConsole: launchConsole, onLaunchEditor: launchEditor }),
         React.createElement(ChangesSection, { git: git, onOpen: openDiff, onRefresh: () => void refresh() })));
 }
 function ChangesSection(props) {
@@ -202,15 +235,108 @@ function AgentSection(props) {
                 React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, agent.label)));
         }))));
 }
+/**
+ * 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.
+ */
+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.
+ */
+function legacyCopy(text) {
+    try {
+        const textarea = document.createElement('textarea');
+        textarea.value = text;
+        textarea.setAttribute('readonly', '');
+        textarea.style.position = 'fixed';
+        textarea.style.top = '-1000px';
+        textarea.style.opacity = '0';
+        document.body.appendChild(textarea);
+        textarea.select();
+        const ok = document.execCommand('copy');
+        document.body.removeChild(textarea);
+        return ok;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 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`.
+ */
+function McpSection(props) {
+    const [copiedId, setCopiedId] = React.useState(null);
+    const registerable = props.agents.filter(agent => MCP_ADD_AGENT_IDS.has(agent.id));
+    if (registerable.length === 0) {
+        return null;
+    }
+    const flagCopied = (id) => {
+        setCopiedId(id);
+        window.setTimeout(() => setCopiedId(current => (current === id ? null : current)), 1500);
+    };
+    const copy = (command, id) => {
+        // 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(() => flagCopied(id), () => {
+                if (legacyCopy(command)) {
+                    flagCopied(id);
+                }
+            });
+        }
+        else if (legacyCopy(command)) {
+            flagCopied(id);
+        }
+    };
+    return (React.createElement("details", { className: "jp-xtralab-Launcher-section jp-xtralab-Launcher-mcp-section" },
+        React.createElement("summary", { className: "jp-xtralab-Launcher-section-summary" },
+            React.createElement("span", { className: "jp-xtralab-Launcher-section-title" }, "Connect agents to JupyterLab (MCP)")),
+        React.createElement("div", { className: "jp-xtralab-Launcher-section-body" },
+            React.createElement("p", { className: "jp-xtralab-Launcher-agent-hint" }, "Run once per agent to let it drive this JupyterLab over MCP. No port needed \u2014 the proxy finds this server on its own."),
+            React.createElement("ul", { className: "jp-xtralab-Launcher-mcp-list" }, registerable.map(agent => {
+                const command = `${agent.command} mcp add jupyter -- ${MCP_PROXY_COMMAND}`;
+                return (React.createElement("li", { key: agent.id, className: "jp-xtralab-Launcher-mcp-item" },
+                    React.createElement("code", { className: "jp-xtralab-Launcher-mcp-command" }, command),
+                    React.createElement("button", { type: "button", className: copiedId === agent.id
+                            ? 'jp-xtralab-Launcher-mcp-copy jp-mod-copied'
+                            : 'jp-xtralab-Launcher-mcp-copy', "aria-label": `Copy the ${agent.label} command`, onClick: () => copy(command, agent.id) }, copiedId === agent.id ? 'Copied!' : 'Copy')));
+            })),
+            React.createElement("p", { className: "jp-xtralab-Launcher-mcp-note" },
+                "Other agents (Goose, OpenCode, Kiro, Mistral Vibe, Antigravity) register MCP through their own config \u2014 point them at the same",
+                ' ',
+                React.createElement("code", null, MCP_PROXY_COMMAND),
+                " command."))));
+}
 /**
  * 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.
  */
 function OpenSection(props) {
-    const { onLaunchTerminal, onLaunchNotebook, onLaunchConsole } = props;
+    const { editor, onLaunchTerminal, onLaunchNotebook, onLaunchConsole, onLaunchEditor } = props;
     return (React.createElement("section", { className: "jp-xtralab-Launcher-section" },
         React.createElement("h2", { className: "jp-xtralab-Launcher-section-title" }, "Open"),
         React.createElement("div", { className: "jp-xtralab-Launcher-agents" },
@@ -222,5 +348,8 @@ function OpenSection(props) {
                 React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, "Notebook")),
             React.createElement("button", { type: "button", className: "jp-xtralab-Launcher-agent", title: "Create a new console.", "aria-label": "Create a new console", onClick: onLaunchConsole },
                 React.createElement(LabIcon.resolveReact, { icon: consoleIcon, tag: "span", className: "jp-xtralab-Launcher-agent-icon" }),
-                React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, "Console")))));
+                React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, "Console")),
+            editor && (React.createElement("button", { type: "button", className: "jp-xtralab-Launcher-agent", title: editor.caption, "aria-label": editor.caption, onClick: onLaunchEditor },
+                React.createElement(LabIcon.resolveReact, { icon: editor.icon, tag: "span", className: "jp-xtralab-Launcher-agent-icon" }),
+                React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, editor.label))))));
 }

package/lib/launcher/editorRegistry.d.ts

@@ -0,0 +1,43 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+import { type IEditor } from './editors';
+/**
+ * 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.
+ */
+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.
+     */
+    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.
+     */
+    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.
+     */
+    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 declare const IEditorRegistry: Token<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.
+ */
+export declare const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry>;

package/lib/launcher/editorRegistry.js

@@ -0,0 +1,96 @@
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { Token } from '@lumino/coreutils';
+import { Signal } from '@lumino/signaling';
+import { fetchAvailableCommands } from './availability';
+import { mergeEditors, resolveEditor } from './editors';
+/**
+ * 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('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.');
+/**
+ * Concrete {@link IEditorRegistry}. The provider plugin is the only writer, so
+ * the write side ({@link set}) is kept off the shared token.
+ */
+class EditorRegistry {
+    constructor() {
+        this._editors = [];
+        this._current = null;
+        this._changed = new Signal(this);
+    }
+    get editors() {
+        return this._editors;
+    }
+    get current() {
+        return this._current;
+    }
+    get changed() {
+        return this._changed;
+    }
+    /** Replace both lists (recomputed together) and notify observers. */
+    set(editors, current) {
+        this._editors = editors;
+        this._current = current;
+        this._changed.emit();
+    }
+}
+/** 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
+ * 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.
+ */
+export const editorRegistryPlugin = {
+    id: 'xtralab:editor-registry',
+    description: "Provides the launcher's terminal-editor list (Neovim, Vim, or user-configured), resolved against the server PATH.",
+    autoStart: true,
+    provides: IEditorRegistry,
+    optional: [ISettingRegistry],
+    activate: async (app, settingRegistry) => {
+        const registry = new EditorRegistry();
+        const apply = async (overrides) => {
+            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 = editors
+                .filter(editor => editor.requireAvailable)
+                .map(editor => editor.command);
+            const available = await fetchAvailableCommands(probe);
+            registry.set(editors, resolveEditor(editors, available));
+        };
+        const readOverrides = (settings) => {
+            const raw = settings.composite.editors;
+            return Array.isArray(raw) ? raw : [];
+        };
+        if (settingRegistry) {
+            try {
+                const settings = await settingRegistry.load(LAUNCHER_SETTINGS_ID);
+                await apply(readOverrides(settings));
+                settings.changed.connect(async () => {
+                    try {
+                        await apply(readOverrides(settings));
+                    }
+                    catch (reason) {
+                        console.error('xtralab: failed to reapply editor settings', reason);
+                    }
+                });
+            }
+            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 {
+            await apply([]);
+        }
+        return registry;
+    }
+};

package/lib/launcher/editors.d.ts

@@ -0,0 +1,78 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * A terminal text editor surfaced on the launcher's "Open" section. An editor
+ * takes no initial prompt and is launched by typing its command into a fresh
+ * terminal (e.g. `nvim`). The launcher shows a single editor tile (the first
+ * available candidate; see {@link resolveEditor}); the full list is shared with
+ * the terminals panel to badge running editors.
+ */
+export interface IEditor {
+    /** Stable id; also the default `$PATH` command probed for availability. */
+    id: string;
+    /** Tile label, e.g. "Neovim". */
+    label: string;
+    /** Tile tooltip. */
+    caption: string;
+    /** The literal command typed into the new terminal, e.g. `nvim`. */
+    command: string;
+    /** Brand icon for the tile. */
+    icon: LabIcon;
+    /**
+     * Preference order for the single launcher tile: the first candidate, by
+     * ascending rank, that qualifies wins (Neovim before Vim by default).
+     */
+    rank: number;
+    /**
+     * When false, the launcher skips the `which`-based availability check for
+     * this entry — useful for a shell alias or function that isn't on PATH but
+     * still resolves when typed in a real terminal. Defaults to true.
+     */
+    requireAvailable: boolean;
+}
+/**
+ * The settings-side shape: every field except `id` is optional, so a user can
+ * override a single field on a built-in editor (e.g. swap `vim`'s command for
+ * a wrapper) without restating the whole entry. New ids define brand-new
+ * editors. Mirrors `IAgentSettings` minus `promptArgs`.
+ */
+export interface IEditorSettings {
+    id: string;
+    label?: string;
+    caption?: string;
+    command?: string;
+    /**
+     * Inline SVG for a custom editor's icon. Required for new ids whose icon
+     * isn't shipped with xtralab; ignored for built-in ids unless explicitly
+     * set (in which case it overrides the built-in).
+     */
+    iconSvg?: string;
+    rank?: number;
+    /**
+     * When false, the editor is hidden from the launcher's Open section (and no
+     * longer recognised by the terminals panel). Disable both built-ins to drop
+     * the editor tile entirely. Defaults to true.
+     */
+    enabled?: boolean;
+    /** See {@link IEditor.requireAvailable}. */
+    requireAvailable?: boolean;
+}
+/**
+ * Merge xtralab's built-in editors with the user's `editors` settings. Built-in
+ * entries keep their 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 re-check the flag). The result is sorted by rank, which
+ * is also the launcher's tile-preference order. Mirrors `mergeAgents`.
+ */
+export declare function mergeEditors(overrides: IEditorSettings[]): IEditor[];
+/**
+ * Pick the single editor tile to show, given the merged editor list and the
+ * set of commands known to be on `$PATH` (from the launcher's availability
+ * probe). Returns the first candidate, by rank, that is either available or
+ * opts out of the check (`requireAvailable: false`) — Neovim before Vim by
+ * default — or `null` when none qualifies.
+ *
+ * When `available` is `null` (the endpoint couldn't be reached), a
+ * `requireAvailable` editor is not shown; an entry with
+ * `requireAvailable: false` is shown regardless.
+ */
+export declare function resolveEditor(editors: IEditor[], available: Set<string> | null): IEditor | null;