sh3-core 0.13.4 → 0.14.3

package/dist/shell-shard/Terminal.svelte

@@ -9,8 +9,10 @@
   import { TenantFsClient } from './tenant-fs-client';
   import { ShellModeRegistry } from './modes/registry';
   import { registerBuiltinModes } from './modes/builtin';
-  import { resolveInitialMode, writeLastMode } from './modes/prefs';
+  import { readLastMode, resolveInitialMode, writeLastMode } from './modes/prefs';
   import type { ShellMode, ShellRole } from './modes/types';
+  import type { ContributionsApi } from '../contributions/types';
+  import { SHELL_MODE_CONTRIBUTION_POINT, type ShellModeDescriptor } from './contract';
   import { makeDispatch } from './dispatch';
   import { computeRelocate } from './auto-relocate';
   import { activeLayout } from '../layout/store.svelte';
@@ -20,32 +22,86 @@
   import ModeSlot from './toolbar/slots/ModeSlot.svelte';
   import FocusLockSlot from './toolbar/slots/FocusLockSlot.svelte';
   import TargetShardSlot from './toolbar/slots/TargetShardSlot.svelte';
+  import BusySlot from './toolbar/slots/BusySlot.svelte';
 
   interface Props {
     shell: ShellApi;
     wsUrl: string;
     userId: string;
     role: ShellRole;
+    contributions: ContributionsApi;
   }
-  let { shell, wsUrl, userId, role }: Props = $props();
+  let { shell, wsUrl, userId, role, contributions }: Props = $props();
 
   const scrollback = new Scrollback();
   const resolver = new VerbRegistry();
   const fs = new TenantFsClient();
 
-  // Mode registry
+  // Mode registry — holds builtins only. Contributed modes flow through
+  // the contributions API and are merged reactively below.
   const modeRegistry = new ShellModeRegistry();
   registerBuiltinModes(modeRegistry);
 
-  // Reactive current mode
+  // contributions.list() returns a plain array (not reactive). Mirror it
+  // into a $state cell and refresh on every onChange notification so the
+  // picker, verb listing, and active-mode fallback all react to shard
+  // hot-mount/unmount without polling.
+  let contributedModes = $state<ShellModeDescriptor[]>(
+    untrack(() => contributions.list<ShellModeDescriptor>(SHELL_MODE_CONTRIBUTION_POINT)),
+  );
+  $effect(() => {
+    const off = contributions.onChange(SHELL_MODE_CONTRIBUTION_POINT, () => {
+      contributedModes = contributions.list<ShellModeDescriptor>(SHELL_MODE_CONTRIBUTION_POINT);
+    });
+    return () => off();
+  });
+
+  /** Convert a descriptor to the internal ShellMode shape so the picker and
+   *  the dispatch path treat builtin and contributed modes uniformly. */
+  function descriptorToMode(d: ShellModeDescriptor): ShellMode {
+    return {
+      id: d.id,
+      label: d.label,
+      requiresRole: d.requiresRole,
+      transport: 'custom',
+      autoRelocate: d.autoRelocate ?? false,
+    };
+  }
+
+  let visibleModes = $derived<ShellMode[]>([
+    ...modeRegistry.list(role),
+    ...contributedModes
+      .filter((d) => !d.requiresRole || d.requiresRole === role)
+      .map(descriptorToMode),
+  ]);
+
+  // Resolve against the merged visible set so a persisted contributed-mode
+  // id is honored at boot when its shard activated before this view mounted.
+  // Async activations still land on the role default.
   let mode = $state<ShellMode>(
-    untrack(() => resolveInitialMode(modeRegistry, userId, role)),
+    untrack(() => {
+      const persisted = readLastMode(userId);
+      if (persisted) {
+        const initialVisible: ShellMode[] = [
+          ...modeRegistry.list(role),
+          ...contributedModes
+            .filter((d) => !d.requiresRole || d.requiresRole === role)
+            .map(descriptorToMode),
+        ];
+        const found = initialVisible.find((m) => m.id === persisted);
+        if (found) return found;
+      }
+      return resolveInitialMode(modeRegistry, userId, role);
+    }),
   );
 
   function setMode(id: string): void {
-    const next = modeRegistry.get(id);
+    const next = visibleModes.find((m) => m.id === id);
     if (!next) return;
     if (next.requiresRole && next.requiresRole !== role) return;
+    // Abort any in-flight custom-mode dispatch from the outgoing mode
+    // before flipping. Safe no-op if there's nothing running.
+    cancelDispatch();
     mode = next;
     writeLastMode(userId, id);
     if (next.transport !== 'ws') {
@@ -53,18 +109,85 @@
     }
   }
 
+  // If the active mode disappears (shard unloaded), fall back to sh3 — or
+  // the first available mode if even sh3 is gone.
+  $effect(() => {
+    if (!visibleModes.find((m) => m.id === mode.id)) {
+      const fallback = visibleModes.find((m) => m.id === 'sh3') ?? visibleModes[0];
+      if (fallback) {
+        const lostId = mode.id;
+        mode = fallback;
+        writeLastMode(userId, fallback.id);
+        scrollback.push({
+          kind: 'status',
+          text: `mode '${lostId}' is no longer available — switched to '${fallback.id}'`,
+          level: 'warn',
+          ts: Date.now(),
+        });
+      }
+    }
+  });
+
+  // Extend the shell prop with view-local mode switching so verbs (like
+  // `mode`) can drive the picker. Only this view knows the live registry
+  // and the setMode closure, so the wrapper happens here. The shell prop
+  // is stable for the view's lifetime, so capturing its initial value via
+  // untrack is intentional.
+  const shellWithModes: ShellApi = untrack(() => ({
+    ...shell,
+    setMode: (id: string) => {
+      const next = visibleModes.find((m) => m.id === id);
+      if (!next) return false;
+      if (next.requiresRole && next.requiresRole !== role) return false;
+      setMode(id);
+      return true;
+    },
+    listModes: () => visibleModes.map((m) => ({ id: m.id, label: m.label })),
+  }));
+
   // wsUrl is a prop read at construction only. untrack prevents Svelte 5's
   // "referenced outside a closure" warning; the URL never changes at runtime.
   const session = untrack(() => new SessionClient(wsUrl));
 
-  const dispatch = untrack(() => makeDispatch({
+  // Busy controller — feeds the toolbar spinner. Each call to acquireBusy(label)
+  // adds an entry to the map; the returned disposer removes it. The slot
+  // renders when the map is non-empty.
+  let busyCounter = 0;
+  let busyEntries = $state(new Map<number, string | undefined>());
+
+  function acquireBusy(label?: string): () => void {
+    const id = ++busyCounter;
+    busyEntries.set(id, label);
+    busyEntries = new Map(busyEntries);
+    let cleared = false;
+    return () => {
+      if (cleared) return;
+      cleared = true;
+      busyEntries.delete(id);
+      busyEntries = new Map(busyEntries);
+    };
+  }
+
+  let busyActive = $derived(busyEntries.size > 0);
+  let busyLabel = $derived.by<string | null>(() => {
+    if (busyEntries.size === 0) return null;
+    // Most-recent label wins (insertion-order Map).
+    let last: string | undefined;
+    for (const v of busyEntries.values()) last = v;
+    return last ?? null;
+  });
+
+  const { dispatch, cancel: cancelDispatch } = untrack(() => makeDispatch({
     mode: () => mode,
+    role: () => role,
     resolver,
     scrollback,
     session,
-    shell,
+    shell: shellWithModes,
     fs,
     cwd: () => session.cwd,
+    busy: acquireBusy,
+    customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,
   }));
 
   let locked = $state(false);
@@ -78,11 +201,15 @@
   let focusLocked = $state(false);
   let targetShard = $state<string | null>(null);
 
-  // Toolbar slot registry
+  // Toolbar slot registry. The 'busy' slot is always-visible at the registry
+  // level; the BusySlot component itself gates rendering on `active` so we
+  // don't have to invalidate the toolbar's `slots` derivation when the
+  // spinner toggles (the toolbar re-derives from ctx, not from busyActive).
   const toolbarRegistry = new ToolbarSlotRegistry();
+  toolbarRegistry.register({ id: 'busy', order: 5, visible: () => true, component: BusySlot });
   toolbarRegistry.register({ id: 'mode', order: 10, visible: () => true, component: ModeSlot });
-  toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'user', component: FocusLockSlot });
-  toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'user', component: TargetShardSlot });
+  toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'sh3', component: FocusLockSlot });
+  toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'sh3', component: TargetShardSlot });
 
   /** Walk the layout tree and return the viewId of the active tab in the first
    *  TabsNode found (breadth-first). Returns null if the layout contains no
@@ -194,7 +321,8 @@
     registry={toolbarRegistry}
     ctx={{ mode, role }}
     slotProps={{
-      mode: { mode, role, registry: modeRegistry, onSelect: setMode },
+      busy: { active: busyActive, label: busyLabel },
+      mode: { mode, modes: visibleModes, onSelect: setMode },
       'focus-lock': { locked: focusLocked, onToggle: () => (focusLocked = !focusLocked) },
       'target-shard': { target: targetShard },
     }}

package/dist/shell-shard/Terminal.svelte.d.ts

@@ -1,10 +1,12 @@
 import { type ShellApi } from './registry';
 import type { ShellRole } from './modes/types';
+import type { ContributionsApi } from '../contributions/types';
 interface Props {
     shell: ShellApi;
     wsUrl: string;
     userId: string;
     role: ShellRole;
+    contributions: ContributionsApi;
 }
 declare const Terminal: import("svelte").Component<Props, {}, "">;
 type Terminal = ReturnType<typeof Terminal>;

package/dist/shell-shard/contract.d.ts

@@ -0,0 +1,99 @@
+import type { Component } from 'svelte';
+/** Contribution-point id under which mode descriptors are registered. */
+export declare const SHELL_MODE_CONTRIBUTION_POINT = "sh3.shell.mode";
+/** Where the descriptor's dispatch handler executes. v1 only honors 'client'. */
+export type ShellModeRunsOn = 'client' | 'server';
+/** A single shell-mode contribution. */
+export interface ShellModeDescriptor {
+    /** Unique id, namespaced in practice (e.g. 'gemini', 'claude-code'). */
+    id: string;
+    /** Short label rendered in the segmented picker. */
+    label: string;
+    /** Optional segment icon. v1 picker ignores this; reserved for forward compat. */
+    icon?: string | Component;
+    /** Role gate. Same semantics as the builtin bash mode. */
+    requiresRole?: 'admin';
+    /** Where dispatch runs. v1 only honors 'client'. */
+    runsOn: ShellModeRunsOn;
+    /** Whether the shell auto-relocates cwd when a shard takes focus. */
+    autoRelocate?: boolean;
+    /** Brain: receives input and pushes output. */
+    dispatch: ShellModeDispatchHandler;
+    /** Optional lifecycle hook fired when the mode is selected. */
+    activate?: (ctx: unknown) => void | Promise<void>;
+    /** Optional lifecycle hook fired when the mode is deselected. */
+    deactivate?: (ctx: unknown) => void;
+}
+export interface ShellModeDispatchInput {
+    /** The raw line as submitted by the user. */
+    line: string;
+    /** Current working directory at submit time. */
+    cwd: string;
+    /**
+     * Aborts when the user switches mode, runs `clear`, or otherwise cancels
+     * the in-flight dispatch. Mode handlers MUST propagate this signal to
+     * any long-running work (e.g. pass to fetch).
+     */
+    signal: AbortSignal;
+}
+export type ShellModeDispatchHandler = (input: ShellModeDispatchInput, output: ShellModeOutput) => Promise<void>;
+export interface ShellModeOutput {
+    /** Push a text chunk to the scrollback. Consecutive same-stream chunks coalesce. */
+    text(stream: 'stdout' | 'stderr', chunk: string): void;
+    /** Push a status entry (info / warn / error). */
+    status(level: 'info' | 'warn' | 'error', msg: string): void;
+    /** Push a rich entry whose props can be patched later via the returned handle. */
+    rich(component: Component<any>, props: Record<string, unknown>): RichEntryHandle;
+    /**
+     * Push a streaming rich entry. Returns a handle the mode appends to as
+     * tokens arrive. The framework marks the entry mid-stream until `complete()`
+     * or `error()` is called so the renderer can show a loading affordance.
+     */
+    stream(component: Component<any>, initialProps: Record<string, unknown>): StreamHandle;
+    /**
+     * Show a spinner in the shell header for the duration of a long-running
+     * operation. The optional label is rendered next to the spinner; pass
+     * undefined for an unlabelled indicator. Returns a clear handle — call
+     * clear() exactly once when the operation completes (idempotent).
+     *
+     * The framework already auto-spawns a spinner while a dispatch is in
+     * flight. Use this method for work that runs *outside* a dispatch (e.g.
+     * during the descriptor's `activate()` lifecycle hook, or background
+     * pre-fetching).
+     */
+    busy(label?: string): BusyHandle;
+    /**
+     * Programmatically dispatch a line through another mode's resolution path.
+     *
+     * - `'sh3'` — full sh3 verb resolution (bypasses the mode-gating that
+     *   normally restricts sh3-domain verbs to sh3 mode).
+     * - `'bash'` — forward to the WS session. Lazy-connects on first use.
+     *   Resolves immediately on send (output streams asynchronously to the
+     *   scrollback via the WS protocol).
+     * - any other registered mode id — routes through that mode's `dispatch()`
+     *   handler. Output flows to the same scrollback.
+     *
+     * Throws synchronously on:
+     * - unknown mode id
+     * - role mismatch (e.g. a non-admin context targeting `'bash'`)
+     * - self-invocation (a mode invoking its own id — direct calls into the
+     *   mode's helpers should be used instead)
+     */
+    invoke(modeId: string, line: string): Promise<void>;
+}
+export interface RichEntryHandle {
+    /** Patch the entry's props. Triggers Svelte reactivity. */
+    update(patch: Record<string, unknown>): void;
+}
+export interface StreamHandle {
+    /** Patch props as new tokens arrive. */
+    append(patch: Record<string, unknown>): void;
+    /** Mark the stream finished cleanly. */
+    complete(): void;
+    /** Mark the stream finished with an error; renders an error status. */
+    error(err: unknown): void;
+}
+export interface BusyHandle {
+    /** Remove this busy indicator. Idempotent. */
+    clear(): void;
+}

package/dist/shell-shard/contract.js

@@ -0,0 +1,11 @@
+/*
+ * Public contract for shell-mode contributions. External shards register
+ * descriptors via `registerShellMode(ctx, descriptor)` (see registerShellMode.ts);
+ * the shell-shard's dispatch path looks them up by id when transport === 'custom'.
+ *
+ * v1 only implements `runsOn: 'client'`. Selecting a `runsOn: 'server'` mode
+ * is rejected at dispatch with a clear status — server-side execution is a
+ * future addition that will not change this contract.
+ */
+/** Contribution-point id under which mode descriptors are registered. */
+export const SHELL_MODE_CONTRIBUTION_POINT = 'sh3.shell.mode';

package/dist/shell-shard/dispatch-custom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/dispatch-custom.test.js

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+function makeStubDeps(mode, customMode) {
+    const pushed = [];
+    const scrollback = { push: (e) => pushed.push(e) };
+    const session = {
+        history: { push: vi.fn() },
+        send: () => { },
+        cwd: '/',
+    };
+    const shell = {};
+    const fs = {};
+    const resolver = {
+        resolve: (line) => ({ kind: 'forward', line }),
+    };
+    return {
+        deps: {
+            mode: () => mode,
+            role: () => 'user',
+            resolver,
+            scrollback,
+            session,
+            shell,
+            fs,
+            cwd: () => '/',
+            busy: () => () => { },
+            customMode,
+        },
+        pushed,
+    };
+}
+describe('dispatch — custom transport', () => {
+    it('routes the line to the descriptor.dispatch', async () => {
+        const handler = vi.fn(async () => { });
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: handler,
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hello');
+        expect(handler).toHaveBeenCalledWith(expect.objectContaining({ line: 'hello', cwd: '/' }), expect.objectContaining({ text: expect.any(Function) }));
+    });
+    it('rejects runsOn: server with a clear status', async () => {
+        const desc = { id: 'srv', label: 'Srv', runsOn: 'server', dispatch: async () => { } };
+        const mode = { id: 'srv', label: 'Srv', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/server-side modes are not yet supported/);
+    });
+    it('catches handler throws and renders an error status', async () => {
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async () => {
+                throw new Error('kaboom');
+            },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/kaboom/);
+    });
+    it('aborts in-flight dispatch when cancel() is called', async () => {
+        let aborted = false;
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async (input) => {
+                await new Promise((_resolve, reject) => {
+                    input.signal.addEventListener('abort', () => {
+                        aborted = true;
+                        reject(new DOMException('aborted', 'AbortError'));
+                    });
+                });
+            },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch, cancel } = makeDispatch(deps);
+        const promise = dispatch('hi');
+        cancel();
+        await promise;
+        expect(aborted).toBe(true);
+    });
+    it('emits an error if the descriptor has been unloaded', async () => {
+        const mode = { id: 'ghost', label: 'Ghost', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => null);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/no longer available/);
+    });
+});
+describe('dispatch — auto-spinner', () => {
+    it('acquires a busy slot for the duration of a custom-mode dispatch', async () => {
+        let active = 0;
+        let peak = 0;
+        const busy = () => {
+            active++;
+            peak = Math.max(peak, active);
+            return () => { active--; };
+        };
+        let resolveDispatch;
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: () => new Promise((resolve) => {
+                resolveDispatch = resolve;
+            }),
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        const promise = dispatch('hi');
+        // Yield once so the dispatch closure runs through to the await on desc.dispatch
+        await Promise.resolve();
+        expect(peak).toBe(1);
+        expect(active).toBe(1);
+        resolveDispatch();
+        await promise;
+        expect(active).toBe(0);
+    });
+    it('clears busy when the dispatch handler throws', async () => {
+        let active = 0;
+        const busy = () => { active++; return () => { active--; }; };
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async () => { throw new Error('kaboom'); },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        await dispatch('hi');
+        expect(active).toBe(0);
+    });
+});

package/dist/shell-shard/dispatch-gating.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/dispatch-gating.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+const appsVerb = { name: 'apps', summary: '', async run() { } };
+const clearVerb = {
+    name: 'clear',
+    summary: '',
+    globalVerb: true,
+    async run(ctx) {
+        ctx.scrollback.push({ kind: 'status', text: 'cleared', level: 'info', ts: 0 });
+    },
+};
+function scaffold(mode) {
+    const sent = [];
+    const pushed = [];
+    const scrollback = { push: (e) => pushed.push(e), clear: () => { } };
+    const session = { history: { push: vi.fn() }, send: (m) => sent.push(m), cwd: '/', connected: true, connect: vi.fn() };
+    const fs = {};
+    const shell = {};
+    // Real-shape resolver to exercise the new globalOnly path.
+    const resolver = {
+        resolve: (line, opts = {}) => {
+            const head = line.trim().split(/\s+/)[0];
+            const verb = head === 'apps' ? appsVerb : head === 'clear' ? clearVerb : null;
+            if (!verb)
+                return { kind: 'forward', line };
+            if (opts.globalOnly && !verb.globalVerb)
+                return { kind: 'forward', line };
+            return { kind: 'local', verb, args: [], line };
+        },
+    };
+    const { dispatch } = makeDispatch({
+        mode: () => mode,
+        role: () => (mode.requiresRole === 'admin' ? 'admin' : 'user'),
+        resolver,
+        scrollback,
+        session,
+        shell,
+        fs,
+        cwd: () => '/',
+        busy: () => () => { },
+    });
+    return { dispatch, sent, pushed };
+}
+describe('dispatch — mode-gated verb resolution', () => {
+    const sh3Mode = { id: 'sh3', label: 'SH3', transport: 'none', autoRelocate: true };
+    const bashMode = { id: 'bash', label: 'Bash', transport: 'ws', autoRelocate: false, requiresRole: 'admin' };
+    it('sh3 mode resolves sh3-domain verbs locally', async () => {
+        const { dispatch, sent } = scaffold(sh3Mode);
+        await dispatch('apps');
+        expect(sent).toEqual([]);
+    });
+    it('bash mode forwards sh3-domain verbs to ws', async () => {
+        const { dispatch, sent } = scaffold(bashMode);
+        await dispatch('apps');
+        expect(sent.some((m) => m.t === 'submit' && m.line === 'apps')).toBe(true);
+    });
+    it('bash mode runs globalVerb (clear) locally', async () => {
+        const { dispatch, sent, pushed } = scaffold(bashMode);
+        await dispatch('clear');
+        expect(sent.every((m) => m.t !== 'submit')).toBe(true);
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'cleared')).toBe(true);
+    });
+});

package/dist/shell-shard/dispatch-invoke.test.d.ts

@@ -0,0 +1 @@
+export {};