@cueloop/client 0.1.0-alpha.89 → 0.1.0-alpha.90

package/src/client-extension-registry.ts

@@ -0,0 +1,159 @@
+import { pathToFileURL } from "node:url";
+import * as React from "react";
+import { useKeyboard } from "@opentui/react";
+import * as v from "valibot";
+import { discoverInstalledExtensionPackages } from "@cueloop/extension-api/installed-packages";
+import type {
+  ClientExtensionAPI,
+  ClientExtensionFactory,
+  ExtensionUIDisposable,
+  ThreadHeaderAction,
+  ThreadSidebarSection,
+  WorkspacePanelView,
+} from "@cueloop/extension-api/client";
+
+interface OwnedContribution<T> {
+  key: string;
+  value: T;
+}
+
+/** A stable snapshot lets React subscribe without rebuilding contribution arrays on every render. */
+export interface ClientExtensionSnapshot {
+  sections: readonly OwnedContribution<ThreadSidebarSection>[];
+  actions: readonly OwnedContribution<ThreadHeaderAction>[];
+  views: readonly OwnedContribution<WorkspacePanelView>[];
+  lastError: string | null;
+}
+
+/** Client extension registrations are isolated by package and disposed on load failure. */
+export class ClientExtensionRegistry {
+  private readonly listeners = new Set<() => void>();
+  private readonly sections = new Map<string, ThreadSidebarSection>();
+  private readonly actions = new Map<string, ThreadHeaderAction>();
+  private readonly views = new Map<string, WorkspacePanelView>();
+  private current: ClientExtensionSnapshot = {
+    sections: [],
+    actions: [],
+    views: [],
+    lastError: null,
+  };
+  readonly errors: string[] = [];
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => this.listeners.delete(listener);
+  };
+
+  readonly snapshot = (): ClientExtensionSnapshot => this.current;
+
+  private changed(): void {
+    this.current = {
+      sections: [...this.sections].map(([key, value]) => ({ key, value })),
+      actions: [...this.actions].map(([key, value]) => ({ key, value })),
+      views: [...this.views].map(([key, value]) => ({ key, value })),
+      lastError: this.errors.at(-1) ?? null,
+    };
+    for (const listener of this.listeners) listener();
+  }
+
+  private add<T extends { id: string; zone: string }>(
+    map: Map<string, T>,
+    owner: string,
+    contribution: T,
+    zone: string,
+  ): ExtensionUIDisposable {
+    if (!/^[a-z][a-z0-9-]*$/.test(contribution.id))
+      throw new Error(`Client extension invalid contribution ID: ${contribution.id}`);
+    if (contribution.zone !== zone)
+      throw new Error(`Client extension ${owner}:${contribution.id} must use zone ${zone}`);
+    const key = `${owner}:${contribution.id}`;
+
+    if (this.sections.has(key) || this.actions.has(key) || this.views.has(key))
+      throw new Error(`Client extension duplicate contribution: ${key}`);
+    map.set(key, contribution);
+    this.changed();
+
+    return {
+      dispose: () => {
+        if (map.get(key) === contribution) {
+          map.delete(key);
+          this.changed();
+        }
+      },
+    };
+  }
+
+  reportError(message: string): void {
+    this.errors.push(message);
+    this.changed();
+  }
+
+  /** Load one client factory and remove all of its registrations if it fails. */
+  async load(owner: string, factory: ClientExtensionFactory): Promise<ExtensionUIDisposable> {
+    const registrations: ExtensionUIDisposable[] = [];
+    const api: ClientExtensionAPI = {
+      react: React,
+      useKeyboard,
+      registerSection: (section) => {
+        const registration = this.add(this.sections, owner, section, "threads.sidebar");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+      registerAction: (action) => {
+        const registration = this.add(this.actions, owner, action, "thread.header");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+      registerView: (view) => {
+        const registration = this.add(this.views, owner, view, "workspace.panels");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+    };
+
+    try {
+      await factory(api);
+    } catch (error) {
+      for (const registration of registrations) registration.dispose();
+      this.reportError(`Client extension ${owner}: ${String(error)}`);
+    }
+
+    return {
+      dispose: () => {
+        for (const registration of registrations) registration.dispose();
+      },
+    };
+  }
+}
+
+/** Import only the client entry points of installed extension packages. */
+export async function loadInstalledClientExtensions(
+  registry: ClientExtensionRegistry,
+  installRoot?: string,
+): Promise<void> {
+  const discovery = discoverInstalledExtensionPackages(installRoot);
+
+  for (const error of discovery.errors) registry.reportError(error);
+  for (const extension of discovery.packages) {
+    if (!extension.clientEntry) continue;
+
+    try {
+      const module: unknown = await import(pathToFileURL(extension.clientEntry).href);
+      const parsed = v.safeParse(v.object({ default: v.function() }), module);
+
+      if (!parsed.success) throw new Error("client entry point must export a default factory");
+      await registry.load(extension.name, async (api) => {
+        await parsed.output.default(api);
+      });
+    } catch (error) {
+      registry.reportError(`Client extension ${extension.name}: ${String(error)}`);
+    }
+  }
+}

package/src/components/AppShell.extensions.test.tsx

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import {
+  ClientExtensionRegistry,
+  loadInstalledClientExtensions,
+} from "../client-extension-registry";
+import { settle } from "../test-support";
+import { AppShell } from "./AppShell";
+
+function shell(
+  registry?: ClientExtensionRegistry,
+  onExtensionError?: (message: string) => void,
+): React.ReactNode {
+  return (
+    <AppShell
+      sidebarOpen
+      onToggleSidebar={() => {}}
+      onOpenMenu={() => {}}
+      threadsPanel={<text>threads list</text>}
+      threadTitle="Thread"
+      threadPanel={<text>thread body</text>}
+      changesOpen={false}
+      projectOpen
+      onToggleChanges={() => {}}
+      onToggleProject={() => {}}
+      onToggleRight={() => {}}
+      projectMode="tree"
+      focusedPane="project"
+      projectPanel={<text>project files</text>}
+      extensionRegistry={registry}
+      extensionContext={{ workspace: "/repo", threadId: "thread-1" }}
+      onExtensionError={onExtensionError}
+    />
+  );
+}
+
+describe("app shell extension zones", () => {
+  test("an empty registry preserves the built-in shell frame", async () => {
+    const plain = await testRender(shell(), { width: 100, height: 16 });
+    const extended = await testRender(shell(new ClientExtensionRegistry()), {
+      width: 100,
+      height: 16,
+    });
+
+    await settle(plain);
+    await settle(extended);
+    expect(extended.captureCharFrame()).toBe(plain.captureCharFrame());
+    plain.renderer.destroy();
+    extended.renderer.destroy();
+  });
+
+  test("renders a sidebar section and workspace tab without replacing built-in content", async () => {
+    const registry = new ClientExtensionRegistry();
+
+    await registry.load("example", (api) => {
+      api.registerSection({
+        id: "summary",
+        zone: "threads.sidebar",
+        title: "Summary",
+        Component: () => <text>extension summary</text>,
+      });
+      api.registerView({
+        id: "details",
+        zone: "workspace.panels",
+        title: "Details",
+        Component: () => <text>extension details</text>,
+      });
+    });
+    const setup = await testRender(shell(registry), { width: 100, height: 16 });
+
+    await settle(setup);
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("extension summary");
+    expect(frame).toContain("Details");
+    expect(frame).toContain("project files");
+    setup.mockInput.pressKey("]");
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("extension details");
+    expect(setup.captureCharFrame()).not.toContain("project files");
+    setup.mockInput.pressKey("[");
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("project files");
+    setup.renderer.destroy();
+  });
+
+  test("an installed client entry can use the host React hooks", async () => {
+    const root = mkdtempSync(join(tmpdir(), "cueloop-client-extension-test-"));
+    const packageRoot = join(root, "node_modules", "example-client");
+
+    try {
+      mkdirSync(packageRoot, { recursive: true });
+      writeFileSync(
+        join(root, "package.json"),
+        JSON.stringify({ dependencies: { "example-client": "1.0.0" } }),
+      );
+      writeFileSync(
+        join(packageRoot, "package.json"),
+        JSON.stringify({ cueloop: { client: "./client.js" } }),
+      );
+      writeFileSync(
+        join(packageRoot, "client.js"),
+        `export default (api) => {
+        const React = api.react;
+        api.registerSection({ id: "hook", zone: "threads.sidebar", title: "Host hook",
+          Component: () => { const [count] = React.useState(1); return React.createElement("text", null, String(count)); }
+        });
+      };`,
+      );
+      const registry = new ClientExtensionRegistry();
+
+      await loadInstalledClientExtensions(registry, root);
+      const setup = await testRender(shell(registry), { width: 100, height: 16 });
+
+      await settle(setup);
+      expect(registry.errors).toEqual([]);
+      expect(setup.captureCharFrame()).toContain("Host hook");
+      expect(setup.captureCharFrame()).toContain("1");
+      setup.renderer.destroy();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("reports a failed client entry through the host error callback", async () => {
+    const registry = new ClientExtensionRegistry();
+    const errors: string[] = [];
+    const setup = await testRender(
+      shell(registry, (message) => errors.push(message)),
+      { width: 100, height: 16 },
+    );
+
+    registry.reportError("Client extension example: failed to load");
+    await settle(setup);
+    expect(errors).toEqual(["Client extension example: failed to load"]);
+    setup.renderer.destroy();
+  });
+
+  test("reports failed visibility callbacks for each UI zone", async () => {
+    const registry = new ClientExtensionRegistry();
+    const errors: string[] = [];
+    const when = () => {
+      throw new Error("visibility broke");
+    };
+
+    await registry.load("broken", (api) => {
+      api.registerSection({
+        id: "section",
+        zone: "threads.sidebar",
+        title: "Hidden section",
+        Component: () => <text>section body</text>,
+        when,
+      });
+      api.registerAction({
+        id: "action",
+        zone: "thread.header",
+        label: "Hidden action",
+        onPress() {},
+        when,
+      });
+      api.registerView({
+        id: "view",
+        zone: "workspace.panels",
+        title: "Hidden view",
+        Component: () => <text>view body</text>,
+        when,
+      });
+    });
+    const setup = await testRender(
+      shell(registry, (message) => errors.push(message)),
+      {
+        width: 100,
+        height: 16,
+      },
+    );
+
+    await settle(setup);
+    expect(errors).toEqual([
+      "Extension broken:section visibility failed: Error: visibility broke",
+      "Extension broken:action visibility failed: Error: visibility broke",
+      "Extension broken:view visibility failed: Error: visibility broke",
+    ]);
+    expect(setup.captureCharFrame()).not.toContain("Hidden section");
+    expect(setup.captureCharFrame()).not.toContain("Hidden view");
+    setup.renderer.destroy();
+  });
+});

package/src/components/AppShell.tsx

@@ -5,7 +5,7 @@
 // always present when the region is on, Changes rides on top of it, and a thin rail holds the sidebar
 // toggle when the region is closed. Each pane owns its own header controls; the thread header never does.
 
-import React, { useRef } from "react";
+import React, { useEffect, useRef } from "react";
 import { useTerminalDimensions } from "@opentui/react";
 import type { BoxRenderable } from "@opentui/core";
 import { DARK, type Theme } from "../theme";
@@ -16,6 +16,28 @@ import { IconButton } from "./primitives/IconButton";
 import { NERD, HEADER_UNDERLINE_CHARS } from "./primitives/icons";
 import { TooltipProvider } from "./Tooltip";
 import { RootOverlayProvider } from "./RootOverlay";
+import type { ExtensionUIContext } from "@cueloop/extension-api/client";
+import { ClientExtensionRegistry } from "../client-extension-registry";
+import { ExtensionZone, useClientExtensionSnapshot } from "./ExtensionZone";
+import { WorkspacePanels } from "./WorkspacePanels";
+
+const EMPTY_EXTENSION_REGISTRY = new ClientExtensionRegistry();
+const EMPTY_EXTENSION_CONTEXT: ExtensionUIContext = { workspace: null, threadId: null };
+
+interface ExtensionInputs {
+  registry: ClientExtensionRegistry;
+  context: ExtensionUIContext;
+}
+
+function extensionInputs(
+  registry?: ClientExtensionRegistry,
+  context?: ExtensionUIContext,
+): ExtensionInputs {
+  return {
+    registry: registry ?? EMPTY_EXTENSION_REGISTRY,
+    context: context ?? EMPTY_EXTENSION_CONTEXT,
+  };
+}
 
 export type ProjectPanelMode = "changes" | "tree";
 
@@ -70,6 +92,10 @@ export interface AppShellProps {
   threadsWidth?: number;
   projectWidth?: number;
   onFocusPane?: (pane: FocusPane) => void;
+  focusedPane?: FocusPane;
+  extensionRegistry?: ClientExtensionRegistry;
+  extensionContext?: ExtensionUIContext;
+  onExtensionError?: (message: string) => void;
 }
 
 export type FocusPane = "threads" | "thread" | "changes" | "project";
@@ -126,7 +152,17 @@ export function AppShell({
   threadsWidth = 30,
   projectWidth = 32,
   onFocusPane,
+  focusedPane,
+  extensionRegistry,
+  extensionContext,
+  onExtensionError,
 }: AppShellProps): React.ReactNode {
+  const { registry, context } = extensionInputs(extensionRegistry, extensionContext);
+  const extensionSnapshot = useClientExtensionSnapshot(registry);
+  useEffect(() => {
+    if (extensionSnapshot.lastError) onExtensionError?.(extensionSnapshot.lastError);
+  }, [extensionSnapshot.lastError, onExtensionError]);
+
   const tokens = theme ?? DARK;
   const { width: terminalWidth } = useTerminalDimensions();
   // with both panels closed the right region collapses to nothing: the reopen toggle
@@ -165,31 +201,6 @@ export function AppShell({
     </box>
   );
 
-  const projectToggles = (
-    <box style={{ flexDirection: "row", flexShrink: 0, alignItems: "center" }}>
-      <IconButton
-        glyph="changes"
-        active={projectMode === "changes"}
-        onPress={onToggleChanges}
-        marginRight={2}
-        theme={tokens}
-      />
-      <IconButton
-        glyph="project"
-        active={projectMode === "tree"}
-        onPress={onToggleProject}
-        marginRight={2}
-        theme={tokens}
-      />
-      <IconButton
-        glyph={NERD.sidebarRight}
-        onPress={onToggleRight}
-        tip="Toggle Sidebar"
-        theme={tokens}
-      />
-    </box>
-  );
-
   // the reopen control - a divider tick then the toggle - shared by the collapsed
   // rail and, when the rail is suppressed, the thread header
   const reopenRightControl = (
@@ -226,6 +237,12 @@ export function AppShell({
                 theme={tokens}
               >
                 {threadsPanel}
+                <ExtensionZone
+                  zone="threads.sidebar"
+                  registry={registry}
+                  context={context}
+                  onError={onExtensionError}
+                />
               </PanelColumn>
             ) : null}
             {!zoomHideThread ? (
@@ -243,7 +260,19 @@ export function AppShell({
                 }
                 // with the region closed, the reopen toggle rides the thread header instead of an empty column
                 headerRight={threadHeaderRight(
-                  threadActions,
+                  extensionSnapshot.actions.length > 0 ? (
+                    <box style={{ flexDirection: "row", alignItems: "center" }}>
+                      {threadActions}
+                      <ExtensionZone
+                        zone="thread.header"
+                        registry={registry}
+                        context={context}
+                        onError={onExtensionError}
+                      />
+                    </box>
+                  ) : (
+                    threadActions
+                  ),
                   reopenRightControl,
                   rightRegionClosed,
                 )}
@@ -273,16 +302,20 @@ export function AppShell({
               </box>
             ) : null}
             {projectOpen ? (
-              <PanelColumn
+              <WorkspacePanels
                 width={projectWidth}
-                border="left"
-                header={null}
-                headerRight={projectToggles}
+                projectMode={projectMode}
+                projectPanel={projectPanel}
+                onToggleChanges={onToggleChanges}
+                onToggleProject={onToggleProject}
+                onToggleRight={onToggleRight}
                 onFocus={() => onFocusPane?.("project")}
+                focused={focusedPane === "project"}
+                registry={registry}
+                context={context}
                 theme={tokens}
-              >
-                {projectPanel}
-              </PanelColumn>
+                onExtensionError={onExtensionError}
+              />
             ) : rightRegionClosed ? null : (
               // Changes open but Project closed: a divider tick above the continuous header underline holds the reopen toggle;
               // the rule lives in the header only, never running the pane's full height. The extra column

package/src/components/ExtensionZone.stories.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import { ClientExtensionRegistry } from "../client-extension-registry";
+import type { Story, StoryMeta } from "./story";
+import { ExtensionZone } from "./ExtensionZone";
+
+export const meta: StoryMeta = { title: "Extensions/ExtensionZone" };
+
+const registry = new ClientExtensionRegistry();
+
+void registry.load("example", (api) => {
+  api.registerSection({
+    id: "summary",
+    zone: "threads.sidebar",
+    title: "Summary",
+    Component: () => <text>Two pending Threads</text>,
+  });
+});
+
+export const SidebarSection: Story = {
+  render: () => (
+    <ExtensionZone
+      zone="threads.sidebar"
+      registry={registry}
+      context={{ workspace: "/repo", threadId: null }}
+    />
+  ),
+  size: { width: 32, height: 8 },
+};

package/src/components/ExtensionZone.tsx

@@ -0,0 +1,145 @@
+import React, { useEffect, useMemo, useSyncExternalStore } from "react";
+import type { ExtensionUIContext } from "@cueloop/extension-api/client";
+import type {
+  ClientExtensionRegistry,
+  ClientExtensionSnapshot,
+} from "../client-extension-registry";
+import { useComponentTheme } from "./theme-context";
+import { IconButton } from "./primitives/IconButton";
+import { NERD } from "./primitives/icons";
+
+/** Subscribe to the client extension registry without coupling extensions to React state. */
+export function useClientExtensionSnapshot(
+  registry: ClientExtensionRegistry,
+): ClientExtensionSnapshot {
+  return useSyncExternalStore(registry.subscribe, registry.snapshot, registry.snapshot);
+}
+
+interface VisibleContributions<T> {
+  items: T[];
+  errors: string[];
+}
+
+/** Evaluate visibility without letting one extension remove another's UI. */
+export function visibleContributions<
+  T extends {
+    key: string;
+    value: { when?: (context: ExtensionUIContext) => boolean };
+  },
+>(contributions: readonly T[], context: ExtensionUIContext): VisibleContributions<T> {
+  const items: T[] = [];
+  const errors: string[] = [];
+
+  for (const contribution of contributions) {
+    try {
+      if (!contribution.value.when || contribution.value.when(context)) items.push(contribution);
+    } catch (error) {
+      errors.push(`Extension ${contribution.key} visibility failed: ${String(error)}`);
+    }
+  }
+
+  return { items, errors };
+}
+
+type VisibilityContribution = {
+  key: string;
+  value: { when?: (context: ExtensionUIContext) => boolean };
+};
+
+class ExtensionRenderBoundary extends React.Component<
+  { children: React.ReactNode; onError?: (message: string) => void },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    console.error("Client extension rendering failed", error);
+    this.props.onError?.(`Extension rendering failed: ${error.message}`);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.failed) return <text>Extension failed</text>;
+
+    return this.props.children;
+  }
+}
+
+/** Render host-framed sections, host buttons, or the selected workspace view. */
+export function ExtensionZone(props: {
+  zone: "threads.sidebar" | "thread.header" | "workspace.panels";
+  registry: ClientExtensionRegistry;
+  context: ExtensionUIContext;
+  selectedViewId?: string | null;
+  onError?: (message: string) => void;
+}): React.ReactNode {
+  const { zone, registry, context, selectedViewId, onError } = props;
+  const snapshot = useClientExtensionSnapshot(registry);
+  const theme = useComponentTheme();
+  const { workspace, threadId } = context;
+  const visibility = useMemo(() => {
+    const contributions: readonly VisibilityContribution[] =
+      zone === "threads.sidebar"
+        ? snapshot.sections
+        : zone === "thread.header"
+          ? snapshot.actions
+          : [];
+
+    return visibleContributions(contributions, { workspace, threadId });
+  }, [zone, snapshot, workspace, threadId]);
+
+  useEffect(() => {
+    for (const error of visibility.errors) onError?.(error);
+  }, [visibility, onError]);
+
+  const visibleKeys = new Set(visibility.items.map(({ key }) => key));
+
+  if (zone === "threads.sidebar") {
+    return snapshot.sections
+      .filter(({ key }) => visibleKeys.has(key))
+      .map(({ key, value }) => (
+        <box key={key} style={{ flexDirection: "column", maxHeight: 8, flexShrink: 0 }}>
+          <text fg={theme.textDim}>{value.title}</text>
+          <ExtensionRenderBoundary onError={onError}>
+            {React.createElement(value.Component, { context })}
+          </ExtensionRenderBoundary>
+        </box>
+      ));
+  }
+
+  if (zone === "thread.header") {
+    return snapshot.actions
+      .filter(({ key }) => visibleKeys.has(key))
+      .map(({ key, value }) => (
+        <IconButton
+          key={key}
+          glyph={value.glyph ?? NERD.kebab}
+          tip={value.label}
+          onPress={() => {
+            try {
+              void Promise.resolve(value.onPress(context)).catch((error) => {
+                console.error(`Client extension action failed: ${key}`, error);
+                onError?.(`Extension action failed: ${value.label}`);
+              });
+            } catch (error) {
+              console.error(`Client extension action failed: ${key}`, error);
+              onError?.(`Extension action failed: ${value.label}`);
+            }
+          }}
+          marginRight={1}
+          theme={theme}
+        />
+      ));
+  }
+
+  const selected = snapshot.views.find(({ key }) => key === selectedViewId);
+
+  return selected ? (
+    <ExtensionRenderBoundary key={selected.key} onError={onError}>
+      {React.createElement(selected.value.Component, { context })}
+    </ExtensionRenderBoundary>
+  ) : null;
+}