@stigmer/react 0.2.0 → 0.2.1

package/src/runner/RunnerFileBrowser.tsx

@@ -0,0 +1,384 @@
+"use client";
+
+import { useMemo } from "react";
+import { getUserMessage } from "@stigmer/sdk";
+import { useRunnerFileBrowser } from "./useRunnerFileBrowser";
+
+/** Props for {@link RunnerFileBrowser}. */
+export interface RunnerFileBrowserProps {
+  /** ID of the runner whose filesystem to browse. */
+  readonly runnerId: string;
+  /** Called when the user confirms the current directory as workspace. */
+  readonly onSelect: (absolutePath: string) => void;
+  /** Called when the user dismisses the browser. */
+  readonly onCancel: () => void;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Styled component for browsing a runner's filesystem and selecting
+ * a project directory as a workspace entry.
+ *
+ * Uses the runner's `ListDirectory` command (via `sendCommand`) to
+ * fetch directory listings over the bidi stream. The user navigates
+ * with breadcrumbs, shortcut buttons (Home, CWD), and click-to-enter
+ * for directories.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * <RunnerFileBrowser
+ *   runnerId="runner-abc123"
+ *   onSelect={(path) => workspace.addLocalPath(path)}
+ *   onCancel={() => setShowBrowser(false)}
+ * />
+ * ```
+ */
+export function RunnerFileBrowser({
+  runnerId,
+  onSelect,
+  onCancel,
+  className,
+}: RunnerFileBrowserProps) {
+  const browser = useRunnerFileBrowser(runnerId);
+
+  const visibleEntries = useMemo(
+    () =>
+      browser.showHidden
+        ? browser.entries
+        : browser.entries.filter((e) => !e.isHidden),
+    [browser.entries, browser.showHidden],
+  );
+
+  const directories = useMemo(
+    () => visibleEntries.filter((e) => e.isDirectory),
+    [visibleEntries],
+  );
+
+  const files = useMemo(
+    () => visibleEntries.filter((e) => !e.isDirectory),
+    [visibleEntries],
+  );
+
+  // --- Error state ---
+  if (browser.error && !browser.currentPath) {
+    return (
+      <div className={["space-y-3", className].filter(Boolean).join(" ")}>
+        <ErrorDisplay
+          error={browser.error}
+          onRetry={browser.retry}
+          onCancel={onCancel}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+      {/* Navigation bar: shortcuts + breadcrumb */}
+      <div className="space-y-1.5">
+        {/* Shortcut buttons */}
+        <div className="flex items-center gap-1">
+          <ShortcutButton
+            label="Home"
+            icon={<HomeIcon />}
+            onClick={browser.navigateHome}
+            disabled={browser.isLoading}
+          />
+          {browser.currentDirectory && (
+            <ShortcutButton
+              label="CWD"
+              icon={<TerminalIcon />}
+              onClick={browser.navigateCwd}
+              disabled={browser.isLoading}
+            />
+          )}
+          {!browser.isAtRoot && (
+            <ShortcutButton
+              label="Up"
+              icon={<ChevronUpIcon />}
+              onClick={browser.navigateUp}
+              disabled={browser.isLoading}
+            />
+          )}
+
+          <div className="ml-auto flex items-center gap-1">
+            <button
+              type="button"
+              onClick={browser.toggleHidden}
+              className={[
+                "rounded px-1.5 py-0.5 text-[0.6rem] transition-colors",
+                browser.showHidden
+                  ? "bg-accent text-foreground"
+                  : "text-muted-foreground hover:text-foreground hover:bg-accent-hover",
+              ].join(" ")}
+              title={browser.showHidden ? "Hide hidden files" : "Show hidden files"}
+            >
+              {browser.showHidden ? "Hide dotfiles" : "Show dotfiles"}
+            </button>
+          </div>
+        </div>
+
+        {/* Breadcrumb path bar */}
+        {browser.segments.length > 0 && (
+          <div className="flex items-center gap-0.5 overflow-x-auto text-[0.65rem] scrollbar-none">
+            {browser.segments.map((seg, i) => {
+              const isLast = i === browser.segments.length - 1;
+              return (
+                <span key={seg.path} className="flex shrink-0 items-center gap-0.5">
+                  {i > 0 && (
+                    <ChevronRightIcon />
+                  )}
+                  {isLast ? (
+                    <span className="rounded px-1 py-0.5 font-medium text-foreground">
+                      {seg.name}
+                    </span>
+                  ) : (
+                    <button
+                      type="button"
+                      onClick={() => browser.navigateToPath(seg.path)}
+                      disabled={browser.isLoading}
+                      className="rounded px-1 py-0.5 text-muted-foreground hover:text-foreground hover:bg-accent-hover transition-colors disabled:pointer-events-none"
+                    >
+                      {seg.name}
+                    </button>
+                  )}
+                </span>
+              );
+            })}
+          </div>
+        )}
+      </div>
+
+      {/* Inline error banner (when we already have a current path) */}
+      {browser.error && browser.currentPath && (
+        <div className="flex items-center gap-2 rounded-md bg-destructive-subtle px-2.5 py-1.5 text-xs text-destructive">
+          <span className="min-w-0 flex-1 truncate">
+            {getUserMessage(browser.error)}
+          </span>
+          <button
+            type="button"
+            onClick={browser.retry}
+            className="shrink-0 text-[0.6rem] font-medium hover:underline"
+          >
+            Retry
+          </button>
+        </div>
+      )}
+
+      {/* Directory listing */}
+      <div
+        className="max-h-56 overflow-y-auto rounded-md border border-border"
+        role="listbox"
+        aria-label="Directory contents"
+      >
+        {browser.isLoading ? (
+          <LoadingSkeleton />
+        ) : visibleEntries.length === 0 ? (
+          <div className="py-6 text-center text-xs text-muted-foreground">
+            This directory is empty
+          </div>
+        ) : (
+          <>
+            {directories.map((entry) => (
+              <button
+                key={entry.name}
+                type="button"
+                onClick={() => browser.navigateTo(entry.name)}
+                className="flex w-full items-center gap-2 px-2.5 py-1.5 text-left text-xs text-foreground transition-colors hover:bg-accent-hover"
+                role="option"
+                aria-selected={false}
+              >
+                <FolderIcon />
+                <span className="min-w-0 flex-1 truncate">{entry.name}</span>
+              </button>
+            ))}
+            {files.map((entry) => (
+              <div
+                key={entry.name}
+                className="flex items-center gap-2 px-2.5 py-1.5 text-xs text-muted-foreground"
+              >
+                <FileIcon />
+                <span className="min-w-0 flex-1 truncate">{entry.name}</span>
+              </div>
+            ))}
+          </>
+        )}
+      </div>
+
+      {/* Actions: Select + Cancel */}
+      <div className="flex items-center justify-between">
+        <span
+          className="min-w-0 flex-1 truncate text-[0.6rem] text-muted-foreground [direction:rtl] text-left"
+          title={browser.currentPath}
+        >
+          <bdi>{browser.currentPath}</bdi>
+        </span>
+        <div className="flex shrink-0 gap-2">
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={() => onSelect(browser.currentPath)}
+            disabled={!browser.currentPath || browser.isLoading}
+            className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground hover:bg-primary-hover transition-colors disabled:opacity-40"
+          >
+            Select
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Error display (initial load failure)
+// ---------------------------------------------------------------------------
+
+function ErrorDisplay({
+  error,
+  onRetry,
+  onCancel,
+}: {
+  error: Error;
+  onRetry: () => void;
+  onCancel: () => void;
+}) {
+  return (
+    <div className="space-y-3 py-2 text-center">
+      <div className="space-y-1">
+        <p className="text-xs font-medium text-destructive">
+          Could not browse runner filesystem
+        </p>
+        <p className="text-[0.65rem] text-muted-foreground">
+          {getUserMessage(error)}
+        </p>
+      </div>
+      <div className="flex justify-center gap-2">
+        <button
+          type="button"
+          onClick={onCancel}
+          className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          onClick={onRetry}
+          className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground hover:bg-primary-hover transition-colors"
+        >
+          Retry
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Shortcut button
+// ---------------------------------------------------------------------------
+
+function ShortcutButton({
+  label,
+  icon,
+  onClick,
+  disabled,
+}: {
+  label: string;
+  icon: React.ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className="inline-flex items-center gap-1 rounded-md px-1.5 py-1 text-[0.65rem] text-muted-foreground hover:text-foreground hover:bg-accent-hover transition-colors disabled:pointer-events-none disabled:opacity-50"
+      title={label}
+    >
+      {icon}
+      <span className="max-sm:hidden">{label}</span>
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Loading skeleton
+// ---------------------------------------------------------------------------
+
+function LoadingSkeleton() {
+  return (
+    <div className="space-y-0.5 p-1">
+      {[60, 45, 72, 38, 55, 50].map((w, i) => (
+        <div key={i} className="flex items-center gap-2 px-2 py-1.5">
+          <div className="h-3.5 w-3.5 shrink-0 rounded bg-muted animate-pulse" />
+          <div
+            className="h-3 rounded bg-muted animate-pulse"
+            style={{ width: `${w}%` }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons (inline SVG, consistent with existing SDK icon patterns)
+// ---------------------------------------------------------------------------
+
+function HomeIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M2 5.5L6 2L10 5.5V10a.5.5 0 01-.5.5h-2V8a.5.5 0 00-.5-.5H5a.5.5 0 00-.5.5v2.5h-2A.5.5 0 012 10V5.5z" />
+    </svg>
+  );
+}
+
+function TerminalIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M2.5 3.5L5 6L2.5 8.5M6.5 8.5H9.5" />
+    </svg>
+  );
+}
+
+function ChevronUpIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M3 7.5L6 4.5L9 7.5" />
+    </svg>
+  );
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg width="8" height="8" viewBox="0 0 8 8" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="text-border">
+      <path d="M3 1.5L5.5 4L3 6.5" />
+    </svg>
+  );
+}
+
+function FolderIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="shrink-0">
+      <path d="M1.5 3.5V11a1 1 0 001 1h9a1 1 0 001-1V5.5a1 1 0 00-1-1H7L5.5 3H2.5a1 1 0 00-1 .5z" />
+    </svg>
+  );
+}
+
+function FileIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="shrink-0">
+      <path d="M8 1.5H4a1 1 0 00-1 1v9a1 1 0 001 1h6a1 1 0 001-1V4.5L8 1.5z" />
+      <path d="M8 1.5V4.5H11" />
+    </svg>
+  );
+}

package/src/runner/__tests__/useRunnerFileBrowser.test.tsx

@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useRunnerFileBrowser } from "../useRunnerFileBrowser";
+
+function buildListDirectoryResponse(
+  resolvedPath: string,
+  entries: Array<{ name: string; isDirectory: boolean; isHidden: boolean }>,
+  homeDirectory = "/home/user",
+  currentDirectory = "/home/user/projects",
+) {
+  return {
+    requestId: "req-1",
+    result: {
+      case: "listDirectory" as const,
+      value: {
+        resolvedPath,
+        entries: entries.map((e) => ({
+          name: e.name,
+          isDirectory: e.isDirectory,
+          isHidden: e.isHidden,
+          $typeName: "ai.stigmer.agentic.runner.v1.DirectoryEntry",
+        })),
+        homeDirectory,
+        currentDirectory,
+        $typeName: "ai.stigmer.agentic.runner.v1.ListDirectoryResponse",
+      },
+    },
+    $typeName: "ai.stigmer.agentic.runner.v1.RunnerCommandResponse",
+  };
+}
+
+function buildErrorResponse(message: string) {
+  return {
+    requestId: "req-1",
+    result: {
+      case: "error" as const,
+      value: {
+        message,
+        $typeName: "ai.stigmer.agentic.runner.v1.RunnerCommandError",
+      },
+    },
+    $typeName: "ai.stigmer.agentic.runner.v1.RunnerCommandResponse",
+  };
+}
+
+function buildMockClient(sendCommand: ReturnType<typeof vi.fn>) {
+  return {
+    runner: { sendCommand },
+  } as unknown as Stigmer;
+}
+
+function makeWrapper(client: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+describe("useRunnerFileBrowser", () => {
+  let sendCommandMock: ReturnType<typeof vi.fn>;
+  let client: Stigmer;
+
+  beforeEach(() => {
+    sendCommandMock = vi.fn();
+    client = buildMockClient(sendCommandMock);
+  });
+
+  it("fetches home directory on initial mount with runnerId", async () => {
+    sendCommandMock.mockResolvedValueOnce(
+      buildListDirectoryResponse("/home/user", [
+        { name: "projects", isDirectory: true, isHidden: false },
+        { name: ".config", isDirectory: true, isHidden: true },
+        { name: ".bashrc", isDirectory: false, isHidden: true },
+      ]),
+    );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(sendCommandMock).toHaveBeenCalledOnce();
+    expect(result.current.currentPath).toBe("/home/user");
+    expect(result.current.entries).toHaveLength(3);
+    expect(result.current.homeDirectory).toBe("/home/user");
+    expect(result.current.currentDirectory).toBe("/home/user/projects");
+    expect(result.current.segments).toHaveLength(3);
+    expect(result.current.segments[0].name).toBe("/");
+    expect(result.current.segments[2].name).toBe("user");
+  });
+
+  it("does not fetch when runnerId is null", () => {
+    renderHook(() => useRunnerFileBrowser(null), {
+      wrapper: makeWrapper(client),
+    });
+
+    expect(sendCommandMock).not.toHaveBeenCalled();
+  });
+
+  it("navigates into a child directory", async () => {
+    sendCommandMock
+      .mockResolvedValueOnce(
+        buildListDirectoryResponse("/home/user", [
+          { name: "projects", isDirectory: true, isHidden: false },
+        ]),
+      )
+      .mockResolvedValueOnce(
+        buildListDirectoryResponse("/home/user/projects", [
+          { name: "my-app", isDirectory: true, isHidden: false },
+        ]),
+      );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      result.current.navigateTo("projects");
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.currentPath).toBe("/home/user/projects");
+    expect(result.current.entries).toHaveLength(1);
+    expect(result.current.entries[0].name).toBe("my-app");
+  });
+
+  it("navigates up to parent directory", async () => {
+    sendCommandMock
+      .mockResolvedValueOnce(
+        buildListDirectoryResponse("/home/user/projects", []),
+      )
+      .mockResolvedValueOnce(
+        buildListDirectoryResponse("/home/user", [
+          { name: "projects", isDirectory: true, isHidden: false },
+        ]),
+      );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      result.current.navigateUp();
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.currentPath).toBe("/home/user");
+  });
+
+  it("handles runner error responses", async () => {
+    sendCommandMock.mockResolvedValueOnce(
+      buildErrorResponse("permission denied: /root"),
+    );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.error).not.toBeNull();
+    expect(result.current.error!.message).toBe("permission denied: /root");
+  });
+
+  it("handles network errors", async () => {
+    sendCommandMock.mockRejectedValueOnce(new Error("runner unavailable"));
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.error).not.toBeNull();
+    expect(result.current.error!.message).toBe("runner unavailable");
+  });
+
+  it("toggles hidden files", async () => {
+    sendCommandMock.mockResolvedValueOnce(
+      buildListDirectoryResponse("/home/user", []),
+    );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.showHidden).toBe(false);
+
+    act(() => {
+      result.current.toggleHidden();
+    });
+
+    expect(result.current.showHidden).toBe(true);
+
+    act(() => {
+      result.current.toggleHidden();
+    });
+
+    expect(result.current.showHidden).toBe(false);
+  });
+
+  it("retries the last failed request", async () => {
+    sendCommandMock
+      .mockRejectedValueOnce(new Error("timeout"))
+      .mockResolvedValueOnce(
+        buildListDirectoryResponse("/home/user", []),
+      );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+
+    await act(async () => {
+      result.current.retry();
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.error).toBeNull();
+    expect(result.current.currentPath).toBe("/home/user");
+    expect(sendCommandMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("reports isAtRoot correctly", async () => {
+    sendCommandMock.mockResolvedValueOnce(
+      buildListDirectoryResponse("/", [
+        { name: "home", isDirectory: true, isHidden: false },
+      ]),
+    );
+
+    const { result } = renderHook(() => useRunnerFileBrowser("rnr_1"), {
+      wrapper: makeWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isAtRoot).toBe(true);
+  });
+});

package/src/runner/index.ts

@@ -29,6 +29,15 @@ export type { UseDeleteRunnerReturn } from "./useDeleteRunner";
 export { RunnerPicker } from "./RunnerPicker";
 export type { RunnerPickerProps } from "./RunnerPicker";
 
+export { RunnerFileBrowser } from "./RunnerFileBrowser";
+export type { RunnerFileBrowserProps } from "./RunnerFileBrowser";
+
+export { useRunnerFileBrowser } from "./useRunnerFileBrowser";
+export type {
+  UseRunnerFileBrowserReturn,
+  PathSegment,
+} from "./useRunnerFileBrowser";
+
 export { RunnerListPanel } from "./RunnerListPanel";
 export type { RunnerListPanelProps } from "./RunnerListPanel";