@stigmer/react 3.1.0 → 3.1.2

package/src/workspace/useWorkspaceFileContent.ts

@@ -0,0 +1,129 @@
+"use client";
+
+import { useMemo } from "react";
+import { useFetch } from "../internal/useFetch.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "./WorkspaceFileReader.js";
+
+/** Options for {@link useWorkspaceFileContent}. */
+export interface UseWorkspaceFileContentOptions {
+  /** The workspace entry that owns the file, or `null` when nothing is open. */
+  readonly entry: WorkspaceEntry | null;
+  /** Repo-relative (git) or root-relative (local) path, or `null` when nothing is open. */
+  readonly path: string | null;
+  /**
+   * Platform-injected content reader. `undefined` when the host app injects
+   * no reader at all (e.g. web with no GitHub token) — surfaced as
+   * {@link UseWorkspaceFileContentReturn.isUnsupported}, not an error.
+   */
+  readonly reader: WorkspaceFileReader | undefined;
+}
+
+/** Return value of {@link useWorkspaceFileContent}. */
+export interface UseWorkspaceFileContentReturn {
+  /**
+   * The decoded file content (+ metadata), or `null` while the request is
+   * in-flight, skipped, failed, or the substrate is unsupported. A present
+   * object with `text === null` is a real file that is binary, too large, or
+   * undecodable — distinct from `isUnsupported`.
+   */
+  readonly content: WorkspaceFileContent | null;
+  /** `true` only on the first load, before any content has arrived. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale content is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed read (a reader throw), or `null` when healthy. */
+  readonly error: Error | null;
+  /**
+   * `true` when no reader can serve this file — either no reader was injected
+   * or the reader reported the entry's substrate as unsupported (git-on-desktop,
+   * local-on-web, missing token). This is the honest "not available here" state,
+   * never an error.
+   */
+  readonly isUnsupported: boolean;
+  /** Imperatively re-read the current file. Stale content stays visible. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Wrapping the resolved `WorkspaceFileContent | null` in an object lets
+ * `useFetch` distinguish "resolved to unsupported" (`content: null`) from its
+ * own `initialData` sentinel without the two colliding — the object reference
+ * is always present after a completed fetch.
+ */
+interface FileContentData {
+  readonly content: WorkspaceFileContent | null;
+}
+
+const EMPTY_CONTENT: FileContentData = { content: null };
+
+/**
+ * Behavior hook that reads a single workspace file's content on demand.
+ *
+ * The byte-reading peer of {@link useWorkspaceFiles}
+ * (which lists the tree), built on the same {@link useFetch} engine as the
+ * content-fetch family ({@link useArtifactContent},
+ * `useToolOutputContent`, `useFileChangeContent`) so it inherits their
+ * stale-while-revalidate, cancellation, and `refetch` semantics for free.
+ *
+ * Deliberately passes **no** `cacheKey`: file bodies (up to
+ * {@link MAX_WORKSPACE_FILE_READ_BYTES})
+ * do not belong in the cross-mount metadata cache, which is sized for small,
+ * hot resources. Re-opening a file re-reads it — the correct trade for a
+ * read-only viewer.
+ *
+ * Maps the reader's two failure axes onto distinct states:
+ * - reader resolves `null` (unsupported substrate) -> {@link UseWorkspaceFileContentReturn.isUnsupported}
+ * - reader **throws** (404, network, unreadable) -> {@link UseWorkspaceFileContentReturn.error}
+ *
+ * Pass `null` for `entry`/`path` (or an `undefined` reader) to stay idle —
+ * the established `useFetch` convention.
+ *
+ * @example
+ * ```tsx
+ * const { content, isLoading, error, isUnsupported } = useWorkspaceFileContent({
+ *   entry,
+ *   path: "src/index.ts",
+ *   reader: workspaceFileReader,
+ * });
+ * ```
+ */
+export function useWorkspaceFileContent({
+  entry,
+  path,
+  reader,
+}: UseWorkspaceFileContentOptions): UseWorkspaceFileContentReturn {
+  // The fetch runs only when a reader, an entry, and a path are all present.
+  const enabled = !!(reader && entry && path);
+
+  const { data, isLoading, isRefetching, error, refetch } =
+    useFetch<FileContentData>(
+      enabled
+        ? () => reader(entry, path).then((c) => ({ content: c }))
+        : null,
+      // Identity deps: a change to any of these is a different file to read.
+      [entry?.id ?? null, path ?? null, reader],
+      EMPTY_CONTENT,
+    );
+
+  // Unsupported = no reader at all, or a completed fetch that resolved to null
+  // (the reader's "this substrate isn't mine" signal). In-flight and error
+  // states are excluded so the viewer shows loading/error, not "unavailable".
+  const isUnsupported =
+    !reader || (enabled && !isLoading && !error && data.content === null);
+
+  return useMemo(
+    () => ({
+      content: data.content,
+      isLoading,
+      isRefetching,
+      error,
+      isUnsupported,
+      refetch,
+    }),
+    [data.content, isLoading, isRefetching, error, isUnsupported, refetch],
+  );
+}

package/src/workspace/useWorkspaceFileSearch.ts

@@ -0,0 +1,184 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { toError } from "../internal/toError.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type { WorkspaceFileLister } from "./WorkspaceFileLister.js";
+import { loadEntryFiles, type WorkspaceListing } from "./workspaceListingCache.js";
+import { matchWorkspaceFiles, type WorkspaceFileMatch } from "./matchWorkspaceFiles.js";
+
+/** Options for {@link useWorkspaceFileSearch}. */
+export interface UseWorkspaceFileSearchOptions {
+  /** All workspace entries to search across. */
+  readonly entries: readonly WorkspaceEntry[];
+  /** Platform-injected file lister. `undefined` → nothing is searchable. */
+  readonly lister: WorkspaceFileLister | undefined;
+  /** Current search query. Empty/whitespace yields no matches (search shows a hint). */
+  readonly query: string;
+}
+
+/** Matches (and per-entry status) for one workspace entry. */
+export interface WorkspaceFileSearchGroup {
+  /** The workspace entry these matches belong to. */
+  readonly entry: WorkspaceEntry;
+  /** Ranked matches within this entry, best-first. */
+  readonly matches: readonly WorkspaceFileMatch[];
+  /** `true` when this entry's listing was truncated (repository too large). */
+  readonly truncated: boolean;
+  /** Listing error for this entry, if any (isolated — other entries still resolve). */
+  readonly error: Error | null;
+}
+
+/** Return value of {@link useWorkspaceFileSearch}. */
+export interface UseWorkspaceFileSearchReturn {
+  /** Entries with something to show (matches, an error, or a truncation notice). */
+  readonly groups: readonly WorkspaceFileSearchGroup[];
+  /** Total matches across all groups (for a "showing N of M" affordance). */
+  readonly totalMatches: number;
+  /** `true` while any entry's listing is still loading. */
+  readonly isLoading: boolean;
+  /** `true` when no substrate can be searched (no lister, or every entry unsupported). */
+  readonly isUnsupported: boolean;
+  /** First per-entry error, for a top-level fallback message. `null` when none. */
+  readonly error: Error | null;
+}
+
+/** Per-entry listing status held while the hook loads across entries. */
+interface EntryListingState {
+  readonly status: "loading" | "ready" | "error" | "unsupported";
+  readonly listing?: WorkspaceListing;
+  readonly error?: Error;
+}
+
+const EMPTY_GROUPS: readonly WorkspaceFileSearchGroup[] = [];
+
+/**
+ * Behavior hook powering workspace-wide filename/path search.
+ *
+ * Loads each entry's listing through the shared
+ * {@link loadEntryFiles} cache (warm from
+ * Files browsing → usually free), then ranks matches per entry with the pure
+ * {@link matchWorkspaceFiles}. Fetching is keyed by the set of entry ids, so a
+ * query change re-ranks the already-loaded listings without re-fetching. Errors
+ * are isolated per entry (one failing repo never blanks the rest), and a stale
+ * generation's late resolutions are ignored.
+ *
+ * Meant to be consumed by a component mounted only while Search is active
+ * (`WorkspaceFileSearch`), so the Files view incurs no search fetching.
+ *
+ * @example
+ * ```tsx
+ * const { groups, totalMatches, isLoading } = useWorkspaceFileSearch({
+ *   entries: workspace.entries,
+ *   lister: workspaceFileLister,
+ *   query,
+ * });
+ * ```
+ */
+export function useWorkspaceFileSearch({
+  entries,
+  lister,
+  query,
+}: UseWorkspaceFileSearchOptions): UseWorkspaceFileSearchReturn {
+  const [states, setStates] = useState<Record<string, EntryListingState>>({});
+
+  // Latest entries read inside the effect without widening its dependency to the
+  // (possibly per-render) array identity — the effect keys on the id set instead.
+  const entriesRef = useRef(entries);
+  entriesRef.current = entries;
+  const entriesKey = entries.map((entry) => entry.id).join("\u0000");
+
+  // Ignore resolutions from a superseded entry set (id set or lister changed).
+  const generationRef = useRef(0);
+
+  useEffect(() => {
+    if (!lister) {
+      setStates({});
+      return;
+    }
+
+    const currentEntries = entriesRef.current;
+    const generation = ++generationRef.current;
+
+    // Seed loading for not-yet-known entries; drop states for removed ones.
+    setStates((prev) => {
+      const next: Record<string, EntryListingState> = {};
+      for (const entry of currentEntries) {
+        next[entry.id] = prev[entry.id] ?? { status: "loading" };
+      }
+      return next;
+    });
+
+    for (const entry of currentEntries) {
+      loadEntryFiles(entry, lister)
+        .then((listing) => {
+          if (generationRef.current !== generation) return;
+          setStates((prev) => ({
+            ...prev,
+            [entry.id]:
+              listing === null
+                ? { status: "unsupported" }
+                : { status: "ready", listing },
+          }));
+        })
+        .catch((err) => {
+          if (generationRef.current !== generation) return;
+          setStates((prev) => ({
+            ...prev,
+            [entry.id]: { status: "error", error: toError(err) },
+          }));
+        });
+    }
+  }, [entriesKey, lister]);
+
+  return useMemo<UseWorkspaceFileSearchReturn>(() => {
+    if (!lister) {
+      return {
+        groups: EMPTY_GROUPS,
+        totalMatches: 0,
+        isLoading: false,
+        isUnsupported: true,
+        error: null,
+      };
+    }
+
+    const groups: WorkspaceFileSearchGroup[] = [];
+    let totalMatches = 0;
+    let isLoading = false;
+    let firstError: Error | null = null;
+    let unsupportedCount = 0;
+
+    for (const entry of entries) {
+      const state = states[entry.id];
+
+      if (!state || state.status === "loading") {
+        isLoading = true;
+        continue;
+      }
+      if (state.status === "unsupported") {
+        unsupportedCount += 1;
+        continue;
+      }
+
+      const error = state.status === "error" ? state.error ?? null : null;
+      if (error && !firstError) firstError = error;
+
+      const truncated = state.listing?.truncated ?? false;
+      const matches = state.listing
+        ? matchWorkspaceFiles(state.listing.files, query)
+        : [];
+      totalMatches += matches.length;
+
+      // A group is worth showing only when it carries matches, an error, or a
+      // truncation notice — otherwise it is silent.
+      if (matches.length > 0 || error || truncated) {
+        groups.push({ entry, matches, truncated, error });
+      }
+    }
+
+    const isUnsupported =
+      entries.length > 0 && unsupportedCount === entries.length;
+
+    return { groups, totalMatches, isLoading, isUnsupported, error: firstError };
+  }, [entries, states, query, lister]);
+}

package/src/workspace/useWorkspaceFiles.ts

@@ -1,10 +1,11 @@
 "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";
+import type { TreeNode } from "../internal/file-tree/index.js";
+import { toError } from "../internal/toError.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type { WorkspaceFileLister } from "./WorkspaceFileLister.js";
+import { loadEntryFiles, peekEntryListing } from "./workspaceListingCache.js";
 
 /** Options for {@link useWorkspaceFiles}. */
 export interface UseWorkspaceFilesOptions {
@@ -22,39 +23,34 @@ export interface UseWorkspaceFilesReturn {
   readonly isLoading: boolean;
   /** Error from the lister, if any. */
   readonly error: Error | null;
+  /**
+   * `true` when the listing was truncated by the backend (repository too large).
+   * The advisory entry is excluded from `tree`; callers render an incomplete-results
+   * banner from this flag instead (DD-11).
+   */
+  readonly truncated: boolean;
   /** 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.
+ * - Calls the platform-injected `lister` (via the shared
+ *   {@link loadEntryFiles} cache) when the
+ *   entry changes.
+ * - Reads the shared listing cache so tab switches, re-expands, and the search
+ *   surface are instant without re-fetching (one cache, keyed by `entry.id`).
  * - 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({
+ * const { tree, isLoading, error, truncated, refresh } = useWorkspaceFiles({
  *   entry: selectedEntry,
  *   lister: workspaceFileLister,
  * });
@@ -67,6 +63,7 @@ export function useWorkspaceFiles({
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
   const [tree, setTree] = useState<readonly TreeNode[]>(EMPTY_TREE);
+  const [truncated, setTruncated] = useState(false);
 
   const fetchIdRef = useRef(0);
 
@@ -75,9 +72,10 @@ export function useWorkspaceFiles({
       if (!lister) return;
 
       if (!bustCache) {
-        const cached = sharedCache.get(target.id);
+        const cached = peekEntryListing(target.id);
         if (cached) {
           setTree(cached.tree);
+          setTruncated(cached.truncated);
           setError(null);
           setIsLoading(false);
           return;
@@ -89,24 +87,25 @@ export function useWorkspaceFiles({
       setError(null);
 
       try {
-        const files = await lister(target);
+        const listing = await loadEntryFiles(target, lister, { bustCache });
 
         if (fetchIdRef.current !== id) return;
 
-        if (files === null) {
+        if (listing === null) {
           setTree(EMPTY_TREE);
+          setTruncated(false);
           setIsLoading(false);
           return;
         }
 
-        const built = buildFileTree(files.filter((f) => !f.isDirectory));
-        sharedCache.set(target.id, { files, tree: built });
-        setTree(built);
+        setTree(listing.tree);
+        setTruncated(listing.truncated);
         setIsLoading(false);
       } catch (err) {
         if (fetchIdRef.current !== id) return;
         setError(toError(err));
         setTree(EMPTY_TREE);
+        setTruncated(false);
         setIsLoading(false);
       }
     },
@@ -116,6 +115,7 @@ export function useWorkspaceFiles({
   useEffect(() => {
     if (!entry || !lister) {
       setTree(EMPTY_TREE);
+      setTruncated(false);
       setIsLoading(false);
       setError(null);
       return;
@@ -130,7 +130,7 @@ export function useWorkspaceFiles({
   }, [entry, lister, fetchFiles]);
 
   return useMemo(
-    () => ({ tree, isLoading, error, refresh }),
-    [tree, isLoading, error, refresh],
+    () => ({ tree, isLoading, error, truncated, refresh }),
+    [tree, isLoading, error, truncated, refresh],
   );
 }

package/src/workspace/useWorkspaceSources.ts

@@ -1,8 +1,8 @@
 "use client";
 
 import { useMemo } from "react";
-import { useExecutionTarget } from "../execution-target-context";
-import { useDeploymentMode } from "../deployment-mode";
+import { useExecutionTarget } from "../execution-target-context.js";
+import { useDeploymentMode } from "../deployment-mode.js";
 
 /** Options for {@link useWorkspaceSources}. */
 export interface UseWorkspaceSourcesOptions {

package/src/workspace/workspaceListingCache.ts

@@ -0,0 +1,93 @@
+// Single source of truth for a workspace entry's file listing.
+//
+// Both surfaces that need a listing read through here: the Files accordion
+// (`useWorkspaceFiles`, one entry) and workspace search (`useWorkspaceFileSearch`,
+// many entries). Keeping one module-level cache — keyed by the stable-within-page
+// `entry.id` — guarantees the two never double-fetch or drift, and lets one fetch
+// produce every shape a consumer needs (flat files for search, a tree for the
+// accordion, and the truncation flag for the banner).
+
+import { buildFileTree, type TreeNode } from "../internal/file-tree/index.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type {
+  WorkspaceFileEntry,
+  WorkspaceFileLister,
+} from "./WorkspaceFileLister.js";
+
+/**
+ * A processed listing for one workspace entry.
+ *
+ * Advisory `notice` entries (e.g. GitHub's "tree truncated" marker) are removed
+ * from {@link WorkspaceListing.files} and never enter {@link WorkspaceListing.tree};
+ * their presence is collapsed into {@link WorkspaceListing.truncated} so both the
+ * accordion and search render one honest "results may be incomplete" banner
+ * instead of a fake, clickable row (DD-11).
+ */
+export interface WorkspaceListing {
+  /** Openable entries (files and directories); advisory notices removed. */
+  readonly files: readonly WorkspaceFileEntry[];
+  /** Hierarchy of the openable files (directories excluded), ready for `FileTreeNode`. */
+  readonly tree: readonly TreeNode[];
+  /** `true` when the lister signalled the listing was incomplete (too many files). */
+  readonly truncated: boolean;
+}
+
+/** Options for {@link loadEntryFiles}. */
+export interface LoadEntryFilesOptions {
+  /** Skip the cache and re-call the lister (the accordion's Refresh action). */
+  readonly bustCache?: boolean;
+}
+
+const sharedCache = new Map<string, WorkspaceListing>();
+
+/**
+ * Returns a cached {@link WorkspaceListing} for an entry synchronously, or
+ * `undefined` when nothing is cached. Lets a consumer render a warm listing
+ * instantly (no loading flash) before deciding whether to fetch.
+ */
+export function peekEntryListing(entryId: string): WorkspaceListing | undefined {
+  return sharedCache.get(entryId);
+}
+
+/**
+ * Loads and caches the processed listing for a single workspace entry.
+ *
+ * Returns the cached listing when present (unless `bustCache`), otherwise calls
+ * the platform-injected `lister`, processes the raw entries once, and caches the
+ * result. Returns `null` when the lister returns `null` (substrate unsupported
+ * for this entry) — the honest "unavailable here" signal, not cached.
+ */
+export async function loadEntryFiles(
+  entry: WorkspaceEntry,
+  lister: WorkspaceFileLister,
+  options: LoadEntryFilesOptions = {},
+): Promise<WorkspaceListing | null> {
+  if (!options.bustCache) {
+    const cached = sharedCache.get(entry.id);
+    if (cached) return cached;
+  }
+
+  const raw = await lister(entry);
+  if (raw === null) return null;
+
+  const listing = buildListing(raw);
+  sharedCache.set(entry.id, listing);
+  return listing;
+}
+
+/** Processes a raw lister result into a {@link WorkspaceListing}. */
+function buildListing(raw: readonly WorkspaceFileEntry[]): WorkspaceListing {
+  const truncated = raw.some((entry) => entry.notice === true);
+  const files = raw.filter((entry) => !entry.notice);
+  const tree = buildFileTree(files.filter((entry) => !entry.isDirectory));
+  return { files, tree, truncated };
+}
+
+/**
+ * Clears the shared cache. Test-only seam for deterministic isolation.
+ *
+ * @internal
+ */
+export function __clearWorkspaceListingCache(): void {
+  sharedCache.clear();
+}