@stigmer/react 1.0.4 → 2.0.0

package/src/workspace/__tests__/useWorkspaceSources.test.tsx

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ExecutionTargetContext } from "../../execution-target-context";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { useWorkspaceSources } from "../useWorkspaceSources";
+import type { ExecutionTargetOption } from "../../session/execution-target";
+import type { DeploymentMode } from "@stigmer/sdk";
+
+function wrapper({
+  executionTarget,
+  deploymentMode = "cloud",
+}: {
+  executionTarget?: ExecutionTargetOption;
+  deploymentMode?: DeploymentMode;
+}) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <DeploymentModeContext.Provider value={deploymentMode}>
+        <ExecutionTargetContext.Provider value={executionTarget}>
+          {children}
+        </ExecutionTargetContext.Provider>
+      </DeploymentModeContext.Provider>
+    );
+  };
+}
+
+describe("useWorkspaceSources", () => {
+  // -----------------------------------------------------------------------
+  // Cloud execution target
+  // -----------------------------------------------------------------------
+
+  it("returns GitHub only when execution target is cloud", () => {
+    const { result } = renderHook(() => useWorkspaceSources(), {
+      wrapper: wrapper({ executionTarget: "cloud" }),
+    });
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: false,
+    });
+  });
+
+  it("returns GitHub only when execution target is cloud, even with hasLocalPicker", () => {
+    const { result } = renderHook(
+      () => useWorkspaceSources({ hasLocalPicker: true }),
+      { wrapper: wrapper({ executionTarget: "cloud" }) },
+    );
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: false,
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Local execution target
+  // -----------------------------------------------------------------------
+
+  it("returns local only when execution target is local and hasLocalPicker", () => {
+    const { result } = renderHook(
+      () => useWorkspaceSources({ hasLocalPicker: true }),
+      { wrapper: wrapper({ executionTarget: "local" }) },
+    );
+
+    expect(result.current).toEqual({
+      enableGitHub: false,
+      enableLocal: true,
+    });
+  });
+
+  it("returns both (GitHub fallback) when execution target is local and no local picker", () => {
+    const { result } = renderHook(() => useWorkspaceSources(), {
+      wrapper: wrapper({ executionTarget: "local" }),
+    });
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: true,
+    });
+  });
+
+  it("returns both (GitHub fallback) when execution target is local and hasLocalPicker is false", () => {
+    const { result } = renderHook(
+      () => useWorkspaceSources({ hasLocalPicker: false }),
+      { wrapper: wrapper({ executionTarget: "local" }) },
+    );
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: true,
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // No explicit execution target — falls back to deployment mode
+  // -----------------------------------------------------------------------
+
+  it("falls back to cloud deployment mode when no execution target is set", () => {
+    const { result } = renderHook(() => useWorkspaceSources(), {
+      wrapper: wrapper({ executionTarget: undefined, deploymentMode: "cloud" }),
+    });
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: false,
+    });
+  });
+
+  it("falls back to local deployment mode when no execution target is set", () => {
+    const { result } = renderHook(() => useWorkspaceSources(), {
+      wrapper: wrapper({ executionTarget: undefined, deploymentMode: "local" }),
+    });
+
+    expect(result.current).toEqual({
+      enableGitHub: true,
+      enableLocal: true,
+    });
+  });
+
+  it("falls back to local deployment mode with hasLocalPicker", () => {
+    const { result } = renderHook(
+      () => useWorkspaceSources({ hasLocalPicker: true }),
+      { wrapper: wrapper({ executionTarget: undefined, deploymentMode: "local" }) },
+    );
+
+    expect(result.current).toEqual({
+      enableGitHub: false,
+      enableLocal: true,
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Reference stability
+  // -----------------------------------------------------------------------
+
+  it("returns the same object reference across re-renders when inputs are unchanged", () => {
+    const { result, rerender } = renderHook(() => useWorkspaceSources(), {
+      wrapper: wrapper({ executionTarget: "cloud" }),
+    });
+
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/workspace/index.ts

@@ -3,6 +3,17 @@ export type {
   WorkspaceEntry,
   UseWorkspaceEntriesReturn,
 } from "./useWorkspaceEntries";
+export type {
+  WorkspaceFileEntry,
+  WorkspaceFileLister,
+} from "./WorkspaceFileLister";
+export { useWorkspaceFiles } from "./useWorkspaceFiles";
+export type {
+  UseWorkspaceFilesOptions,
+  UseWorkspaceFilesReturn,
+} from "./useWorkspaceFiles";
+export { WorkspaceEntryFiles } from "./WorkspaceEntryFiles";
+export type { WorkspaceEntryFilesProps } from "./WorkspaceEntryFiles";
 export { WorkspaceEditor } from "./WorkspaceEditor";
 export type { WorkspaceEditorProps } from "./WorkspaceEditor";
 export { WorkspaceSummary } from "./WorkspaceSummary";
@@ -12,3 +23,8 @@ export type {
   RecentWorkspace,
   UseRecentWorkspacesReturn,
 } from "./useRecentWorkspaces";
+export { useWorkspaceSources } from "./useWorkspaceSources";
+export type {
+  UseWorkspaceSourcesOptions,
+  UseWorkspaceSourcesReturn,
+} from "./useWorkspaceSources";

package/src/workspace/useRecentWorkspaces.ts

@@ -5,9 +5,9 @@ import { useCallback, useSyncExternalStore } from "react";
 const STORAGE_KEY_PREFIX = "stigmer:recent-workspaces:";
 const MAX_RECENT = 8;
 
-/** A recently used or favorited workspace path for a specific runner. */
+/** A recently used or favorited workspace path. */
 export interface RecentWorkspace {
-  /** Absolute path on the runner's filesystem. */
+  /** Absolute path on the filesystem. */
   readonly path: string;
   /** Whether the user pinned this path as a favorite. */
   readonly pinned: boolean;
@@ -27,13 +27,13 @@ export interface UseRecentWorkspacesReturn {
   readonly remove: (path: string) => void;
 }
 
-function storageKey(runnerId: string): string {
-  return `${STORAGE_KEY_PREFIX}${runnerId}`;
+function storageKey(scopeId: string): string {
+  return `${STORAGE_KEY_PREFIX}${scopeId}`;
 }
 
-function readEntries(runnerId: string): RecentWorkspace[] {
+function readEntries(scopeId: string): RecentWorkspace[] {
   try {
-    const raw = localStorage.getItem(storageKey(runnerId));
+    const raw = localStorage.getItem(storageKey(scopeId));
     if (!raw) return [];
     return JSON.parse(raw) as RecentWorkspace[];
   } catch {
@@ -41,9 +41,9 @@ function readEntries(runnerId: string): RecentWorkspace[] {
   }
 }
 
-function writeEntries(runnerId: string, entries: RecentWorkspace[]): void {
+function writeEntries(scopeId: string, entries: RecentWorkspace[]): void {
   try {
-    localStorage.setItem(storageKey(runnerId), JSON.stringify(entries));
+    localStorage.setItem(storageKey(scopeId), JSON.stringify(entries));
   } catch {
     // localStorage full or unavailable — silently degrade.
   }
@@ -71,43 +71,43 @@ function subscribe(callback: () => void): () => void {
 
 const EMPTY: readonly RecentWorkspace[] = [];
 
-let cachedRunnerId: string | null = null;
+let cachedScopeId: string | null = null;
 let cachedVersion = -1;
 let cachedResult: readonly RecentWorkspace[] = EMPTY;
 
-function getSnapshot(runnerId: string | null): readonly RecentWorkspace[] {
-  if (!runnerId) return EMPTY;
-  if (runnerId === cachedRunnerId && snapshotVersion === cachedVersion) {
+function getSnapshot(scopeId: string | null): readonly RecentWorkspace[] {
+  if (!scopeId) return EMPTY;
+  if (scopeId === cachedScopeId && snapshotVersion === cachedVersion) {
     return cachedResult;
   }
-  cachedRunnerId = runnerId;
+  cachedScopeId = scopeId;
   cachedVersion = snapshotVersion;
-  cachedResult = sortEntries(readEntries(runnerId));
+  cachedResult = sortEntries(readEntries(scopeId));
   return cachedResult;
 }
 
 /**
- * Manages recently used workspace paths for a specific runner,
- * persisted in `localStorage`.
+ * Manages recently used workspace paths, persisted in `localStorage`.
  *
- * Entries are keyed by `runner_id` so each runner maintains its own
- * history. Pinned paths appear first, then by most-recently-used.
+ * Entries are keyed by `scopeId` (e.g. a session ID or machine identifier)
+ * so each scope maintains its own history. Pinned paths appear first,
+ * then by most-recently-used.
  *
- * @param runnerId - Runner to scope the history to. When `null`, returns empty.
+ * @param scopeId - Scope to key the history to. When `null`, returns empty.
  */
 export function useRecentWorkspaces(
-  runnerId: string | null,
+  scopeId: string | null,
 ): UseRecentWorkspacesReturn {
   const entries = useSyncExternalStore(
     subscribe,
-    () => getSnapshot(runnerId),
+    () => getSnapshot(scopeId),
     () => EMPTY,
   );
 
   const recordSelection = useCallback(
     (path: string) => {
-      if (!runnerId) return;
-      const existing = readEntries(runnerId);
+      if (!scopeId) return;
+      const existing = readEntries(scopeId);
       const idx = existing.findIndex((e) => e.path === path);
       const now = Date.now();
 
@@ -128,34 +128,34 @@ export function useRecentWorkspaces(
         }
       }
 
-      writeEntries(runnerId, updated);
+      writeEntries(scopeId, updated);
       notifyListeners();
     },
-    [runnerId],
+    [scopeId],
   );
 
   const togglePin = useCallback(
     (path: string) => {
-      if (!runnerId) return;
-      const existing = readEntries(runnerId);
+      if (!scopeId) return;
+      const existing = readEntries(scopeId);
       const idx = existing.findIndex((e) => e.path === path);
       if (idx < 0) return;
       const updated = [...existing];
       updated[idx] = { ...updated[idx], pinned: !updated[idx].pinned };
-      writeEntries(runnerId, updated);
+      writeEntries(scopeId, updated);
       notifyListeners();
     },
-    [runnerId],
+    [scopeId],
   );
 
   const remove = useCallback(
     (path: string) => {
-      if (!runnerId) return;
-      const updated = readEntries(runnerId).filter((e) => e.path !== path);
-      writeEntries(runnerId, updated);
+      if (!scopeId) return;
+      const updated = readEntries(scopeId).filter((e) => e.path !== path);
+      writeEntries(scopeId, updated);
       notifyListeners();
     },
-    [runnerId],
+    [scopeId],
   );
 
   return { entries, recordSelection, togglePin, remove };

package/src/workspace/useWorkspaceEntries.ts

@@ -49,13 +49,7 @@ export interface UseWorkspaceEntriesReturn {
   readonly remove: (id: string) => void;
   /** Remove all entries. */
   readonly clear: () => void;
-  /**
-   * Remove all local folder entries, keeping git entries intact.
-   *
-   * Used when the user switches runners — local paths from the previous
-   * runner are invalid on the new runner, but git repos are
-   * runner-independent and can stay.
-   */
+  /** Remove all local folder entries, keeping git entries intact. */
   readonly clearLocal: () => void;
   /** Convert entries to the `WorkspaceEntryInput[]` shape required by the SDK. */
   readonly toInput: () => WorkspaceEntryInput[];
@@ -78,7 +72,18 @@ function deriveNameFromGitUrl(url: string): string {
 }
 
 function deriveNameFromPath(path: string): string {
-  return path.replace(/[/\\]+$/, "") || path;
+  const cleaned = path.replace(/[/\\]+$/, "");
+  if (!cleaned) return path;
+
+  const segments = cleaned.split(/[/\\]/);
+  const last = segments[segments.length - 1];
+
+  if (segments.length >= 2) {
+    const parent = segments[segments.length - 2];
+    return `${parent}/${last}`;
+  }
+
+  return last || path;
 }
 
 /**

package/src/workspace/useWorkspaceFiles.ts

@@ -0,0 +1,136 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { buildFileTree, type TreeNode } from "../internal/file-tree";
+import { toError } from "../internal/toError";
+import type { WorkspaceEntry } from "./useWorkspaceEntries";
+import type { WorkspaceFileEntry, WorkspaceFileLister } from "./WorkspaceFileLister";
+
+/** Options for {@link useWorkspaceFiles}. */
+export interface UseWorkspaceFilesOptions {
+  /** The workspace entry to list files for (`null` when nothing is selected). */
+  readonly entry: WorkspaceEntry | null;
+  /** Platform-injected lister callback. `undefined` when the host app does not support file listing. */
+  readonly lister: WorkspaceFileLister | undefined;
+}
+
+/** Return value of {@link useWorkspaceFiles}. */
+export interface UseWorkspaceFilesReturn {
+  /** Hierarchical tree built from the file listing, ready for `FileTreeNode`. */
+  readonly tree: readonly TreeNode[];
+  /** `true` while the lister is being called. */
+  readonly isLoading: boolean;
+  /** Error from the lister, if any. */
+  readonly error: Error | null;
+  /** Re-fetch the file listing for the current entry (cache-bust). */
+  readonly refresh: () => void;
+}
+
+interface CacheEntry {
+  files: WorkspaceFileEntry[];
+  tree: TreeNode[];
+}
+
+const EMPTY_TREE: readonly TreeNode[] = [];
+
+/**
+ * Module-level cache shared across all component instances. This ensures
+ * that switching between tabs (e.g., Workspace tab unmount/remount) doesn't
+ * re-fetch file listings that were already loaded. Entries are keyed by
+ * the workspace entry's stable ID.
+ */
+const sharedCache = new Map<string, CacheEntry>();
+
+/**
+ * Behavior hook that fetches and caches a file listing for a single
+ * workspace entry, converting it into a {@link TreeNode} hierarchy.
+ *
+ * - Calls the platform-injected `lister` when the entry changes.
+ * - Caches results per `entry.id` so tab switches and re-expands
+ *   are instant without re-fetching.
+ * - Returns an empty tree and skips the call when `lister` is
+ *   `undefined` (graceful degradation — DD-011 opt-in).
+ * - Memoizes the return value for referential stability (DD-010).
+ *
+ * @example
+ * ```tsx
+ * const { tree, isLoading, error, refresh } = useWorkspaceFiles({
+ *   entry: selectedEntry,
+ *   lister: workspaceFileLister,
+ * });
+ * ```
+ */
+export function useWorkspaceFiles({
+  entry,
+  lister,
+}: UseWorkspaceFilesOptions): UseWorkspaceFilesReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [tree, setTree] = useState<readonly TreeNode[]>(EMPTY_TREE);
+
+  const fetchIdRef = useRef(0);
+
+  const fetchFiles = useCallback(
+    async (target: WorkspaceEntry, bustCache: boolean) => {
+      if (!lister) return;
+
+      if (!bustCache) {
+        const cached = sharedCache.get(target.id);
+        if (cached) {
+          setTree(cached.tree);
+          setError(null);
+          setIsLoading(false);
+          return;
+        }
+      }
+
+      const id = ++fetchIdRef.current;
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const files = await lister(target);
+
+        if (fetchIdRef.current !== id) return;
+
+        if (files === null) {
+          setTree(EMPTY_TREE);
+          setIsLoading(false);
+          return;
+        }
+
+        const built = buildFileTree(files.filter((f) => !f.isDirectory));
+        sharedCache.set(target.id, { files, tree: built });
+        setTree(built);
+        setIsLoading(false);
+      } catch (err) {
+        if (fetchIdRef.current !== id) return;
+        setError(toError(err));
+        setTree(EMPTY_TREE);
+        setIsLoading(false);
+      }
+    },
+    [lister],
+  );
+
+  useEffect(() => {
+    if (!entry || !lister) {
+      setTree(EMPTY_TREE);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+    fetchFiles(entry, false);
+  }, [entry, lister, fetchFiles]);
+
+  const refresh = useCallback(() => {
+    if (entry && lister) {
+      fetchFiles(entry, true);
+    }
+  }, [entry, lister, fetchFiles]);
+
+  return useMemo(
+    () => ({ tree, isLoading, error, refresh }),
+    [tree, isLoading, error, refresh],
+  );
+}

package/src/workspace/useWorkspaceSources.ts

@@ -0,0 +1,83 @@
+"use client";
+
+import { useMemo } from "react";
+import { useExecutionTarget } from "../execution-target-context";
+import { useDeploymentMode } from "../deployment-mode";
+
+/** Options for {@link useWorkspaceSources}. */
+export interface UseWorkspaceSourcesOptions {
+  /**
+   * Whether the host environment can open a native folder picker.
+   *
+   * Desktop apps set this to `true` (they supply `onBrowseLocalFolder`
+   * via Tauri's dialog plugin). Web apps omit it or pass `false`.
+   *
+   * When the effective execution target is `"local"` and no local
+   * picker is available, the hook keeps GitHub enabled as a fallback
+   * so the user always has at least one way to add a workspace.
+   *
+   * @default false
+   */
+  readonly hasLocalPicker?: boolean;
+}
+
+/** Return value of {@link useWorkspaceSources}. */
+export interface UseWorkspaceSourcesReturn {
+  /** Whether to show the "Connect GitHub" action in the workspace editor. */
+  readonly enableGitHub: boolean;
+  /** Whether to show the "Browse Folder" action in the workspace editor. */
+  readonly enableLocal: boolean;
+}
+
+/**
+ * Derives which workspace source options to present based on the
+ * app-level execution target.
+ *
+ * Reads `executionTarget` from `StigmerProvider` context and falls
+ * back to `deploymentMode` when no explicit target is set:
+ *
+ * - **Cloud execution** -> GitHub only (`enableGitHub: true`, `enableLocal: false`).
+ * - **Local execution with native picker** -> local folder only
+ *   (`enableGitHub: false`, `enableLocal: true`).
+ * - **Local execution without native picker** -> GitHub fallback
+ *   (`enableGitHub: true`, `enableLocal: true`) so the user is
+ *   never left with zero workspace sources.
+ *
+ * This hook centralises the policy so all consumer sites (launcher
+ * and session page, across desktop and web) stay in lockstep without
+ * duplicating conditional logic (DD-016).
+ *
+ * @example
+ * ```tsx
+ * // Desktop app (has native folder picker via Tauri)
+ * const sources = useWorkspaceSources({ hasLocalPicker: true });
+ * // -> { enableGitHub: false, enableLocal: true }
+ *
+ * // Web app (cloud deployment, no native picker)
+ * const sources = useWorkspaceSources();
+ * // -> { enableGitHub: true, enableLocal: false }
+ * ```
+ */
+export function useWorkspaceSources(
+  options?: UseWorkspaceSourcesOptions,
+): UseWorkspaceSourcesReturn {
+  const executionTarget = useExecutionTarget();
+  const deploymentMode = useDeploymentMode();
+  const hasLocalPicker = options?.hasLocalPicker ?? false;
+
+  return useMemo(() => {
+    const effectiveTarget =
+      executionTarget ?? (deploymentMode === "local" ? "local" : "cloud");
+
+    if (effectiveTarget === "cloud") {
+      return { enableGitHub: true, enableLocal: false };
+    }
+
+    // Local execution: prefer the native picker when available.
+    // Fall back to GitHub when no picker exists (e.g. web-local OSS).
+    return {
+      enableGitHub: !hasLocalPicker,
+      enableLocal: true,
+    };
+  }, [executionTarget, deploymentMode, hasLocalPicker]);
+}