xtralab 0.1.1 → 0.2.0

package/src/launcher/index.ts

@@ -0,0 +1,228 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette, MainAreaWidget } from '@jupyterlab/apputils';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { launcherIcon } from '@jupyterlab/ui-components';
+import { find } from '@lumino/algorithm';
+import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
+import type { IDisposable } from '@lumino/disposable';
+import type { Widget } from '@lumino/widgets';
+
+import { mergeAgents, type IAgent, type IAgentSettings } from './agents';
+import { fetchAvailableCommands } from './availability';
+import { CREATE_LAUNCHER_COMMAND, registerAgentCommands } from './commands';
+import { LauncherDashboard } from './dashboard';
+
+const PLUGIN_ID = 'xtralab:launcher';
+
+/**
+ * The xtralab launcher plugin. Replaces the stock JupyterLab launcher
+ * (which is disabled via `package.json`'s `jupyterlab.disabledExtensions`)
+ * with an agent-focused dashboard: an optional initial prompt, a row of
+ * agent buttons (Claude, Codex, Gemini, …), and a collapsible list of
+ * changed files (clickable into the diff viewer) below them. Clicking an
+ * agent opens a fresh terminal and pipes the agent's command into it; if
+ * the prompt textarea is non-empty, the prompt is shell-quoted and
+ * spliced into the launch line per the agent's `promptArgs` recipe.
+ *
+ * The agent list is the merge of xtralab's defaults with the user's
+ * `xtralab:launcher` settings, then filtered by a server-side `which`
+ * check so users only see agents that are actually installed. Agents with
+ * `requireAvailable: false` (e.g. shell aliases) skip the filter.
+ *
+ * The plugin deliberately does NOT provide the `ILauncher` token: other
+ * extensions register notebook/console/terminal cards on it as a side
+ * effect, which would defeat the point of the agent-only launcher. If an
+ * extension needs to surface itself, we'll add it here explicitly.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'An agent-focused launcher that replaces the default JupyterLab launcher.',
+  autoStart: true,
+  optional: [ILabShell, ICommandPalette, ISettingRegistry, ITranslator],
+  activate: async (
+    app: JupyterFrontEnd,
+    labShell: ILabShell | null,
+    palette: ICommandPalette | null,
+    settingRegistry: ISettingRegistry | null,
+    translator: ITranslator | null
+  ): Promise<void> => {
+    const { commands, shell } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    // The currently active agent list. Updated whenever settings change so
+    // every freshly-created launcher widget renders the latest list.
+    let currentAgents: IAgent[] = [];
+
+    // Track command registrations so a settings change can wipe them
+    // before re-registering — without this the command palette would
+    // accumulate stale entries when the agent list shrinks.
+    let registered: IDisposable | null = null;
+
+    const applyAgents = async (overrides: IAgentSettings[]): Promise<void> => {
+      const agents = mergeAgents(overrides);
+      const filtered = await filterByAvailability(agents);
+
+      registered?.dispose();
+      registered = registerAgentCommands(app, filtered);
+      currentAgents = filtered;
+    };
+
+    const readOverrides = (
+      settings: ISettingRegistry.ISettings
+    ): IAgentSettings[] => {
+      const raw = settings.composite.agents;
+      return Array.isArray(raw) ? (raw as IAgentSettings[]) : [];
+    };
+
+    if (settingRegistry) {
+      try {
+        const settings = await settingRegistry.load(PLUGIN_ID);
+        await applyAgents(readOverrides(settings));
+        settings.changed.connect(async () => {
+          try {
+            await applyAgents(readOverrides(settings));
+          } catch (reason) {
+            console.error(
+              'xtralab: failed to reapply launcher settings',
+              reason
+            );
+          }
+        });
+      } catch (reason) {
+        console.error('xtralab: failed to load launcher settings', reason);
+        // Settings load failed — fall back to defaults so the launcher
+        // still has cards instead of going silent.
+        await applyAgents([]);
+      }
+    } else {
+      await applyAgents([]);
+    }
+
+    commands.addCommand(CREATE_LAUNCHER_COMMAND, {
+      label: trans.__('New Launcher'),
+      execute: (args: ReadonlyPartialJSONObject) => {
+        const id = Private.nextId();
+        const onAgentLaunch = (item: Widget): void => {
+          // When an agent command returns a Widget that ends up in the main
+          // area, slot it where this launcher used to sit so opening an
+          // agent feels like the launcher transformed into the terminal.
+          // Disposing the inner ReactWidget cascades to the MainAreaWidget
+          // host via its `content.disposed` connection.
+          if (find(shell.widgets('main'), w => w === item)) {
+            shell.add(item, 'main', { ref: id });
+            launcher.dispose();
+          }
+        };
+        const launcher = new LauncherDashboard({
+          commands,
+          agents: currentAgents,
+          onAgentLaunch,
+          // Empty repoPath/cwd matches the JupyterLab convention used by
+          // the git panel and the stock launcher: let the server resolve
+          // the working tree from its root directory.
+          repoPath: '',
+          cwd: ''
+        });
+        launcher.title.icon = launcherIcon;
+        launcher.title.label = trans.__('Launcher');
+
+        const main = new MainAreaWidget({ content: launcher });
+        // Hide the close button when the launcher is the only thing in the
+        // main area: closing it would leave the user staring at an empty
+        // shell with no way back.
+        main.title.closable = !!Array.from(shell.widgets('main')).length;
+        main.id = id;
+
+        shell.add(main, 'main', {
+          activate: args['activate'] as boolean,
+          ref: args['ref'] as string
+        });
+
+        if (labShell) {
+          labShell.layoutModified.connect(() => {
+            main.title.closable =
+              Array.from(labShell.widgets('main')).length > 1;
+          }, main);
+        }
+
+        return main;
+      }
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: CREATE_LAUNCHER_COMMAND,
+        category: trans.__('Launcher')
+      });
+    }
+
+    if (labShell) {
+      void app.restored.then(() => {
+        const maybeCreate = (): void => {
+          if (labShell.isEmpty('main')) {
+            void commands.execute(CREATE_LAUNCHER_COMMAND);
+          }
+        };
+        labShell.layoutModified.connect(() => {
+          maybeCreate();
+        });
+        // Layout has settled by the time `app.restored` resolves; if it's
+        // empty (fresh start, no restored widgets) the connect above won't
+        // fire on its own — kick it off here.
+        maybeCreate();
+      });
+
+      labShell.addButtonEnabled = true;
+      labShell.addRequested.connect((sender, arg) => {
+        const ref =
+          arg.currentTitle?.owner.id ||
+          arg.titles[arg.titles.length - 1].owner.id;
+        return commands.execute(CREATE_LAUNCHER_COMMAND, { ref });
+      });
+    }
+  }
+};
+
+/**
+ * Drop agents whose command isn't on `$PATH`, except for entries that
+ * explicitly opt out of the check via `requireAvailable: false` (typical
+ * use case: shell aliases the user wants surfaced regardless).
+ *
+ * If the availability endpoint can't be reached we fail open and return
+ * the input unchanged — better to show an unreachable agent than to hide
+ * the entire launcher because the server extension didn't load.
+ */
+async function filterByAvailability(agents: IAgent[]): Promise<IAgent[]> {
+  const commands = agents
+    .filter(agent => agent.requireAvailable)
+    .map(agent => agent.command);
+  if (commands.length === 0) {
+    return agents;
+  }
+  const available = await fetchAvailableCommands(commands);
+  if (!available) {
+    return agents;
+  }
+  return agents.filter(
+    agent => !agent.requireAvailable || available.has(agent.command)
+  );
+}
+
+namespace Private {
+  let counter = 0;
+
+  /**
+   * Returns the next unique launcher widget id.
+   */
+  export function nextId(): string {
+    return `launcher-${counter++}`;
+  }
+}
+
+export default plugin;

package/src/launcher/invocation.ts

@@ -0,0 +1,45 @@
+import type { IAgent } from './agents';
+
+/**
+ * Quote a string so it can be safely passed as a single argument on a
+ * bash/zsh command line that is *typed into an interactive terminal* —
+ * not the usual file-parsing context.
+ *
+ * The distinction matters: an actual newline byte (0x0A) sent into a PTY
+ * is interpreted by the line discipline as Enter regardless of whether
+ * it sits inside `'...'` quotes, so the shell never sees the closing
+ * quote. We therefore use ANSI-C `$'...'` quoting and emit `\n` (and
+ * `\r`) as their two-character escape sequences; the shell expands them
+ * to real newlines after the line is submitted, when readline is no
+ * longer involved. Backslashes and single quotes are escaped first so
+ * the source text round-trips unchanged.
+ */
+export function shellQuote(value: string): string {
+  const escaped = value
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+  return `$'${escaped}'`;
+}
+
+/**
+ * Compose the literal command line typed into a fresh terminal for `agent`.
+ * When `prompt` is empty (or whitespace-only), this is just `agent.command`.
+ * When non-empty, the prompt is shell-quoted and spliced in using the
+ * agent's `promptArgs` recipe — see `IAgent.promptArgs` for the encoding.
+ *
+ * Returns `agent.command` unchanged when the agent declares no prompt
+ * support (`promptArgs === undefined`), so a stray prompt typed into the
+ * launcher does not silently mutate the launch line for that agent. The
+ * launcher UI separately prevents the click in that case so the dropped
+ * prompt is never surprising to the user.
+ */
+export function buildAgentInvocation(agent: IAgent, prompt: string): string {
+  const trimmed = prompt.trim();
+  if (trimmed.length === 0 || agent.promptArgs === undefined) {
+    return agent.command;
+  }
+  const tokens = [agent.command, ...agent.promptArgs, shellQuote(trimmed)];
+  return tokens.filter(token => token.length > 0).join(' ');
+}

package/src/menus/index.ts

@@ -0,0 +1,124 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { IMainMenu } from '@jupyterlab/mainmenu';
+import type { IRankedMenu } from '@jupyterlab/ui-components';
+import type { Menu, MenuBar, Widget } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:menus';
+
+/**
+ * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
+ * is open in the main area. The agent-first launcher does not use kernels,
+ * so showing those menus on a fresh workspace surfaces commands the user
+ * cannot meaningfully invoke; remove them until a notebook or console is
+ * opened, then restore them at their original ranks.
+ *
+ * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
+ * both expose it, which avoids pulling in `@jupyterlab/notebook` and
+ * `@jupyterlab/console` just to identify their widgets.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Toggle the Run and Kernel main menus based on whether any kernel-using widget is open.',
+  autoStart: true,
+  requires: [IMainMenu, ILabShell],
+  activate: (
+    app: JupyterFrontEnd,
+    mainMenu: IMainMenu,
+    labShell: ILabShell
+  ): void => {
+    // The interface types (IRunMenu, IKernelMenu) extend IRankedMenu, but
+    // the concrete instances are RankedMenu/Menu — cast so we can hand them
+    // to MenuBar.removeMenu and IMainMenu.addMenu, which expect a `Menu`.
+    const menuBar = mainMenu as unknown as MenuBar;
+    const runMenu = mainMenu.runMenu as unknown as Menu;
+    const kernelMenu = mainMenu.kernelMenu as unknown as Menu;
+
+    // Capture the schema-assigned ranks so the menus reappear in their
+    // original slots between View (rank 3) and Tabs (rank 500). Falling
+    // back to the hard-coded defaults from `MainMenu` keeps things sane
+    // if the schema ever omits the rank.
+    const runRank = mainMenu.runMenu.rank ?? 4;
+    const kernelRank = mainMenu.kernelMenu.rank ?? 5;
+
+    const isPresent = (menu: Menu): boolean =>
+      Array.from(menuBar.menus).indexOf(menu) > -1;
+
+    const update = (): void => {
+      const show = hasKernelWidget(labShell);
+      if (show) {
+        // Don't go through `mainMenu.addMenu`: it picks the insertion index
+        // from a private `_items` array that `removeMenu` doesn't update,
+        // so re-adding lands the menu at the wrong position. Insert
+        // directly on the MenuBar by walking current menus and finding
+        // the first sibling with a higher rank.
+        if (!isPresent(runMenu)) {
+          insertByRank(menuBar, runMenu, runRank);
+        }
+        if (!isPresent(kernelMenu)) {
+          insertByRank(menuBar, kernelMenu, kernelRank);
+        }
+      } else {
+        if (isPresent(runMenu)) {
+          menuBar.removeMenu(runMenu);
+        }
+        if (isPresent(kernelMenu)) {
+          menuBar.removeMenu(kernelMenu);
+        }
+      }
+    };
+
+    void app.restored.then(() => {
+      update();
+      labShell.layoutModified.connect(update);
+    });
+  }
+};
+
+/**
+ * True iff any widget in the main area exposes a `sessionContext` — the
+ * shared marker for NotebookPanel, ConsolePanel, and kernel-attached file
+ * editors. We don't import their concrete types because that would drag
+ * `@jupyterlab/notebook` and `@jupyterlab/console` into xtralab's bundle
+ * just to do an `instanceof` check.
+ */
+function hasKernelWidget(labShell: ILabShell): boolean {
+  for (const widget of labShell.widgets('main')) {
+    if (hasSessionContext(widget)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasSessionContext(widget: Widget): boolean {
+  const candidate = widget as unknown as { sessionContext?: unknown };
+  return (
+    candidate.sessionContext !== null && candidate.sessionContext !== undefined
+  );
+}
+
+/**
+ * Insert `menu` into `menuBar` at the position dictated by `rank`, using
+ * the existing menus' ranks to find the slot. Menus without a numeric
+ * rank are treated as +Infinity so they sink to the end (matching the
+ * convention in `MenuFactory.createMenus`).
+ */
+function insertByRank(menuBar: MenuBar, menu: Menu, rank: number): void {
+  const menus = menuBar.menus;
+  for (let i = 0; i < menus.length; i++) {
+    const r = (menus[i] as unknown as IRankedMenu).rank;
+    const otherRank = typeof r === 'number' ? r : Number.POSITIVE_INFINITY;
+    if (otherRank > rank) {
+      menuBar.insertMenu(i, menu);
+      return;
+    }
+  }
+  menuBar.addMenu(menu);
+}
+
+export default plugin;

package/src/sidebar/index.ts

@@ -0,0 +1,195 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import type { Widget } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:sidebar';
+
+/**
+ * Each entry pairs an upstream sidebar widget id with the rank it was
+ * originally added at. The ranks come from the upstream extensions —
+ * `filebrowser-extension` adds the default browser at rank 100 and
+ * `running-extension` adds the running panel at rank 200 — and we reuse
+ * them when re-adding so the tab lands back in its usual position.
+ */
+interface ITarget {
+  id: string;
+  rank: number;
+  settingKey: 'showDefaultFileBrowser' | 'showRunningSessions';
+  command: string;
+  label: (trans: ReturnType<ITranslator['load']>) => string;
+}
+
+const TARGETS: ITarget[] = [
+  {
+    id: 'filebrowser',
+    rank: 100,
+    settingKey: 'showDefaultFileBrowser',
+    command: 'xtralab:toggle-default-filebrowser',
+    label: trans => trans.__('Default File Browser')
+  },
+  {
+    id: 'jp-running-sessions',
+    rank: 200,
+    settingKey: 'showRunningSessions',
+    command: 'xtralab:toggle-running-sessions',
+    label: trans => trans.__('Running Terminals and Kernels')
+  }
+];
+
+/**
+ * Lets the user toggle individual left-sidebar tabs from
+ * View > Appearance > Left Sidebar. Removing a widget from a `LabShell`
+ * side area is done by setting `widget.parent = null`: the StackedPanel
+ * emits `widgetRemoved`, which the SideBarHandler responds to by removing
+ * the matching tab. The widget instance is preserved, so we can re-add it
+ * later via `labShell.add` with its original rank.
+ *
+ * The menu placement is contributed declaratively in
+ * `schema/sidebar.json`, so this plugin only registers commands and
+ * applies state — it does not touch `IMainMenu` directly.
+ *
+ * The preference is persisted to `xtralab:sidebar` settings so the choice
+ * survives reloads.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Toggle visibility of selected sidebar tabs (default file browser, running sessions) from the View menu.',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [ISettingRegistry, ITranslator],
+  activate: async (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    settingRegistry: ISettingRegistry | null,
+    translator: ITranslator | null
+  ): Promise<void> => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const { commands } = app;
+
+    // Cache widget instances so we can re-add them after `widget.parent =
+    // null` has detached them from the sidebar. The widget is no longer
+    // reachable through `labShell.widgets('left')` once removed, so a
+    // missing cache entry would leave us unable to bring the tab back.
+    const widgetCache = new Map<string, Widget>();
+
+    const findInSidebar = (id: string): Widget | null => {
+      for (const w of labShell.widgets('left')) {
+        if (w.id === id) {
+          return w;
+        }
+      }
+      return null;
+    };
+
+    const captureWidget = (id: string): Widget | null => {
+      const cached = widgetCache.get(id);
+      if (cached && !cached.isDisposed) {
+        return cached;
+      }
+      const found = findInSidebar(id);
+      if (found) {
+        widgetCache.set(id, found);
+      }
+      return found;
+    };
+
+    let settings: ISettingRegistry.ISettings | null = null;
+
+    const readPreference = (target: ITarget): boolean => {
+      if (!settings) {
+        return true;
+      }
+      const value = settings.composite[target.settingKey];
+      return typeof value === 'boolean' ? value : true;
+    };
+
+    const apply = (target: ITarget): void => {
+      const widget = captureWidget(target.id);
+      if (!widget) {
+        // The upstream widget hasn't been added yet (or the extension is
+        // disabled). Nothing to do — the next time `apply` runs and finds
+        // it, the preference will take effect.
+        return;
+      }
+      const present = findInSidebar(target.id) !== null;
+      const wantPresent = readPreference(target);
+      if (wantPresent && !present) {
+        labShell.add(widget, 'left', { rank: target.rank });
+      } else if (!wantPresent && present) {
+        // Setting `parent = null` triggers SideBarHandler's
+        // `_onWidgetRemoved`, which strips the tab while leaving the
+        // widget instance alive for a later re-add.
+        widget.parent = null;
+      }
+    };
+
+    const applyAll = (): void => {
+      for (const target of TARGETS) {
+        apply(target);
+      }
+    };
+
+    for (const target of TARGETS) {
+      commands.addCommand(target.command, {
+        label: target.label(trans),
+        isToggled: () => readPreference(target),
+        execute: async () => {
+          const next = !readPreference(target);
+          if (settings) {
+            try {
+              await settings.set(target.settingKey, next);
+              // `settings.changed` will fire and drive `apply` + the
+              // command-state refresh. Returning here keeps the toggle's
+              // single source of truth in the settings registry.
+              return;
+            } catch (reason) {
+              console.error(
+                `xtralab: failed to persist ${target.settingKey}`,
+                reason
+              );
+            }
+          }
+          // No settings registry available (or the write failed): fall
+          // back to applying the change in-memory so the toggle still
+          // works for the current session.
+          apply(target);
+          commands.notifyCommandChanged(target.command);
+        }
+      });
+    }
+
+    if (settingRegistry) {
+      try {
+        settings = await settingRegistry.load(PLUGIN_ID);
+        settings.changed.connect(() => {
+          applyAll();
+          for (const target of TARGETS) {
+            commands.notifyCommandChanged(target.command);
+          }
+        });
+      } catch (reason) {
+        console.error('xtralab: failed to load sidebar settings', reason);
+      }
+    }
+
+    void app.restored.then(() => {
+      // Capture references first so a hidden-on-startup widget is still
+      // recoverable later. `apply` would also do the lookup, but only on
+      // the targets that need to stay visible — by capturing every target
+      // here we keep the cache populated for both directions of the
+      // toggle.
+      for (const target of TARGETS) {
+        captureWidget(target.id);
+      }
+      applyAll();
+    });
+  }
+};
+
+export default plugin;