@stigmer/react 3.1.1 → 3.1.3

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

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, cleanup } from "@testing-library/react";
+import { useWorkspaceFileSearch } from "../useWorkspaceFileSearch";
+import { __clearWorkspaceListingCache } from "../workspaceListingCache";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type { WorkspaceFileEntry, WorkspaceFileLister } from "../WorkspaceFileLister";
+
+let entryIdCounter = 0;
+
+function makeEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: `ws-${++entryIdCounter}`,
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+const FILES_A: WorkspaceFileEntry[] = [
+  { path: "src/index.ts", isDirectory: false },
+  { path: "src/button.tsx", isDirectory: false },
+  { path: "README.md", isDirectory: false },
+];
+
+const FILES_B: WorkspaceFileEntry[] = [
+  { path: "lib/button.ts", isDirectory: false },
+  { path: "lib/util.ts", isDirectory: false },
+];
+
+describe("useWorkspaceFileSearch", () => {
+  beforeEach(() => {
+    __clearWorkspaceListingCache();
+  });
+  afterEach(cleanup);
+
+  it("is unsupported and never fetches when no lister is injected", () => {
+    const lister = vi.fn();
+    const entries = [makeEntry()];
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries, lister: undefined, query: "x" }),
+    );
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.groups).toEqual([]);
+    expect(lister).not.toHaveBeenCalled();
+  });
+
+  it("aggregates ranked matches across multiple entries", async () => {
+    const entryA = makeEntry();
+    const entryB = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async (e) =>
+      e.id === entryA.id ? FILES_A : FILES_B,
+    );
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entryA, entryB], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.totalMatches).toBe(2);
+    const groupPaths = result.current.groups.map((g) => ({
+      id: g.entry.id,
+      paths: g.matches.map((m) => m.path),
+    }));
+    expect(groupPaths).toEqual([
+      { id: entryA.id, paths: ["src/button.tsx"] },
+      { id: entryB.id, paths: ["lib/button.ts"] },
+    ]);
+  });
+
+  it("reuses the shared cache — no refetch when warm", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => FILES_A);
+
+    const first = renderHook(
+      ({ q }) => useWorkspaceFileSearch({ entries: [entry], lister, query: q }),
+      { initialProps: { q: "button" } },
+    );
+    await waitFor(() => expect(first.result.current.isLoading).toBe(false));
+    expect(lister).toHaveBeenCalledTimes(1);
+    first.unmount();
+
+    // Remount (re-enter Search) with the same entry → served from cache.
+    const second = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "index" }),
+    );
+    await waitFor(() => expect(second.result.current.isLoading).toBe(false));
+    expect(lister).toHaveBeenCalledTimes(1);
+    expect(second.result.current.groups[0].matches.map((m) => m.path)).toEqual([
+      "src/index.ts",
+    ]);
+  });
+
+  it("isolates a per-entry error while other entries still resolve", async () => {
+    const good = makeEntry();
+    const bad = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async (e) => {
+      if (e.id === bad.id) throw new Error("network down");
+      return FILES_A;
+    });
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [good, bad], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const goodGroup = result.current.groups.find((g) => g.entry.id === good.id);
+    const badGroup = result.current.groups.find((g) => g.entry.id === bad.id);
+    expect(goodGroup?.matches.map((m) => m.path)).toEqual(["src/button.tsx"]);
+    expect(badGroup?.error?.message).toBe("network down");
+    expect(result.current.error?.message).toBe("network down");
+  });
+
+  it("surfaces per-group truncated from a notice entry", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => [
+      { path: "src/button.tsx", isDirectory: false },
+      { path: "... truncated", isDirectory: false, notice: true as const },
+    ]);
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.groups[0].truncated).toBe(true);
+    expect(result.current.groups[0].matches.map((m) => m.path)).toEqual([
+      "src/button.tsx",
+    ]);
+  });
+
+  it("reports isUnsupported when every entry's substrate returns null", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => null);
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "x" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.groups).toEqual([]);
+  });
+
+  it("keeps a stable return reference across rerenders with an unchanged query", async () => {
+    const entry = makeEntry();
+    const entries = [entry];
+    const lister: WorkspaceFileLister = vi.fn(async () => FILES_A);
+
+    const { result, rerender } = renderHook(() =>
+      useWorkspaceFileSearch({ entries, lister, query: "button" }),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const before = result.current;
+    rerender();
+    expect(result.current).toBe(before);
+  });
+});

package/src/workspace/findChangeForSelection.ts

@@ -0,0 +1,61 @@
+// Correlate an open workspace-file selection with the session file change that
+// touched it, so the read-only Viewer can default a changed file to its diff
+// (Slice 4). This is the change-side peer of `resolveWorkspaceFileSelection`.
+//
+// The hard part is again PATH FORM, and — critically — ENTRY IDENTITY. A
+// `FileChange` carries a capture-side path (`path` is workspace-root-relative,
+// falling back to `absolutePath`), while the selection is the reader's
+// `{ entryId, path }`. Matching by a bare `/`-boundary suffix (as the
+// presentation-only `changeForRowPath` does) is deliberately NOT used here: in
+// a multi-repo session it would happily match `repoA/src/a.ts` to a change in
+// `repoB/src/a.ts` and render the wrong file's diff.
+//
+// Instead we route each change's path through the SAME correlation-grade
+// resolver (`resolveWorkspaceFileSelection`) the tree and transcript use to
+// open files, with the SAME `entries` and `sandboxWorkspaceRoot`. A change is
+// the open file's change iff it resolves to the exact `{ entryId, path }`
+// currently selected. Single-entry sessions match exactly; ambiguous
+// multi-entry / absolute paths degrade to "no match" (never a wrong match),
+// inheriting DD-08's honesty. One resolver, one truth.
+
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import { resolveWorkspaceFileSelection } from "./resolveWorkspaceFileSelection.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+
+/**
+ * The session {@link FileChange} that touched the currently-open file, or
+ * `null` when the open file was not changed this session (or cannot be
+ * correlated with certainty).
+ *
+ * @param selection - The open file, keyed by `entryId` + repo/root-relative `path`.
+ * @param fileChanges - Net-per-file session changes (from `useSessionFileChanges`).
+ * @param entries - The client workspace entries — the SAME list the tree and
+ *   transcript resolve against (`flow.workspace.entries`), so the returned
+ *   `entryId` is directly comparable. Do not pass the proto `workspaceEntries`.
+ * @param sandboxWorkspaceRoot - The sandbox root for git sessions (strips
+ *   cloud-absolute change paths), identical to the transcript resolver's input.
+ * @returns The matching change, or `null`.
+ */
+export function findChangeForSelection(
+  selection: SelectedWorkspaceFile,
+  fileChanges: readonly FileChange[],
+  entries: readonly WorkspaceEntry[],
+  sandboxWorkspaceRoot?: string,
+): FileChange | null {
+  for (const change of fileChanges) {
+    const resolved = resolveWorkspaceFileSelection(
+      change.path || change.absolutePath,
+      entries,
+      sandboxWorkspaceRoot,
+    );
+    if (
+      resolved !== null &&
+      resolved.entryId === selection.entryId &&
+      resolved.path === selection.path
+    ) {
+      return change;
+    }
+  }
+  return null;
+}

package/src/workspace/index.ts

@@ -7,13 +7,67 @@ export type {
   WorkspaceFileEntry,
   WorkspaceFileLister,
 } from "./WorkspaceFileLister.js";
+export { MAX_WORKSPACE_FILE_READ_BYTES } from "./WorkspaceFileReader.js";
+export type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "./WorkspaceFileReader.js";
 export { useWorkspaceFiles } from "./useWorkspaceFiles.js";
 export type {
   UseWorkspaceFilesOptions,
   UseWorkspaceFilesReturn,
 } from "./useWorkspaceFiles.js";
-export { WorkspaceEntryFiles } from "./WorkspaceEntryFiles.js";
-export type { WorkspaceEntryFilesProps } from "./WorkspaceEntryFiles.js";
+export { useWorkspaceFileContent } from "./useWorkspaceFileContent.js";
+export type {
+  UseWorkspaceFileContentOptions,
+  UseWorkspaceFileContentReturn,
+} from "./useWorkspaceFileContent.js";
+export { useWorkspaceFileSearch } from "./useWorkspaceFileSearch.js";
+export type {
+  UseWorkspaceFileSearchOptions,
+  UseWorkspaceFileSearchReturn,
+  WorkspaceFileSearchGroup,
+} from "./useWorkspaceFileSearch.js";
+// The match type is part of the public search return; the matcher itself stays @internal.
+export type { WorkspaceFileMatch } from "./matchWorkspaceFiles.js";
+export { WorkspaceFileSearch } from "./WorkspaceFileSearch.js";
+export type { WorkspaceFileSearchProps } from "./WorkspaceFileSearch.js";
+export type {
+  WorkspaceContentMatch,
+  WorkspaceContentSearchResult,
+  WorkspaceContentSearcher,
+} from "./WorkspaceContentSearcher.js";
+export { useWorkspaceContentSearch } from "./useWorkspaceContentSearch.js";
+export type {
+  UseWorkspaceContentSearchOptions,
+  UseWorkspaceContentSearchReturn,
+  WorkspaceContentSearchGroup,
+} from "./useWorkspaceContentSearch.js";
+export { WorkspaceContentSearch } from "./WorkspaceContentSearch.js";
+export type { WorkspaceContentSearchProps } from "./WorkspaceContentSearch.js";
+// The highlight helper (findHighlightRanges) stays @internal, like matchWorkspaceFiles.
+export { FileViewer } from "./FileViewer.js";
+export type { FileViewerProps, FileViewerHandle } from "./FileViewer.js";
+export { WorkspaceSurface } from "./WorkspaceSurface.js";
+export type {
+  WorkspaceSurfaceProps,
+  SurfaceRailView,
+  SurfaceVirtualDocument,
+} from "./WorkspaceSurface.js";
+// Virtual-document identity helpers: hosts mint collision-proof entry ids for
+// SurfaceVirtualDocument tabs and detect them in file-only code paths.
+export { virtualEntryId, isVirtualEntryId } from "../internal/store/index.js";
+export { ExplorerTree } from "./ExplorerTree.js";
+export type { ExplorerTreeProps } from "./ExplorerTree.js";
+// The open-editor tab shape + open-file options are part of the public
+// WorkspaceSurface API.
+export type { OpenEditor, OpenFileOptions } from "../internal/store/index.js";
+// The jump-to-line reveal target rides on FileViewer / WorkspaceSurface /
+// ArtifactContentRenderer props; export the shape (the hook stays @internal).
+export type { RevealTarget } from "../internal/useRevealLine.js";
+// The viewer's selection shape is part of the public FileViewer API; re-export
+// the type (not the store) so consumers can construct/inspect a selection.
+export type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
 export { WorkspaceEditor } from "./WorkspaceEditor.js";
 export type { WorkspaceEditorProps } from "./WorkspaceEditor.js";
 export { WorkspaceSummary } from "./WorkspaceSummary.js";

package/src/workspace/matchContentPreview.ts

@@ -0,0 +1,51 @@
+// Pure highlight helper behind content search. Kept separate from the hook and
+// component so the offset math is exhaustively unit-testable in isolation (no
+// React, no async).
+//
+// The backend returns each hit's `preview` line but no column offset (a
+// cross-language byte/UTF-16 offset would be brittle — see WorkspaceContentMatch).
+// Since matching is case-insensitive substring, the client re-derives the
+// highlight span(s) from the preview text itself, identically to how
+// `matchWorkspaceFiles` derives the filename highlight range. `@internal`.
+
+/**
+ * A half-open `[start, end)` range of code-unit offsets into a preview string,
+ * marking one occurrence of the query to emphasize.
+ */
+export interface HighlightRange {
+  /** Inclusive start offset within the preview. */
+  readonly start: number;
+  /** Exclusive end offset within the preview. */
+  readonly end: number;
+}
+
+/**
+ * Finds every case-insensitive occurrence of `query` within `preview`,
+ * best-effort for rendering emphasis.
+ *
+ * - Empty/whitespace query → `[]` (nothing to highlight).
+ * - Overlapping matches cannot occur (search advances past each match end).
+ * - Offsets are JS string code units, so a consumer highlights with
+ *   `preview.slice(start, end)`.
+ */
+export function findHighlightRanges(
+  preview: string,
+  query: string,
+): HighlightRange[] {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) return [];
+
+  const haystack = preview.toLowerCase();
+  const ranges: HighlightRange[] = [];
+
+  let from = 0;
+  for (;;) {
+    const start = haystack.indexOf(needle, from);
+    if (start === -1) break;
+    const end = start + needle.length;
+    ranges.push({ start, end });
+    from = end;
+  }
+
+  return ranges;
+}

package/src/workspace/matchWorkspaceFiles.ts

@@ -0,0 +1,86 @@
+// Pure ranking function behind workspace search. Kept separate from the hook and
+// component so the matching/ranking rules are exhaustively unit-testable in
+// isolation (no React, no async).
+//
+// Match semantics intentionally mirror `internal/file-tree/filterFileTree` —
+// case-insensitive substring — but widened from a node's basename to the full
+// relative path, so `foo/bar` is findable and directory context is searchable
+// (DD-10). The trivial predicate is not extracted into a shared micro-module; a
+// cross-reference comment is the lower-coupling, honest choice.
+
+import type { WorkspaceFileEntry } from "./WorkspaceFileLister.js";
+
+/**
+ * A workspace file that matched a search query.
+ *
+ * `matchStart`/`matchEnd` are code-unit offsets into `path` (a half-open
+ * `[start, end)` range) for the single contiguous substring hit, so a consumer
+ * can highlight exactly the matched span with `path.slice(...)`.
+ */
+export interface WorkspaceFileMatch {
+  /** Repo-relative (git) or root-relative (local) path of the matched file. */
+  readonly path: string;
+  /** Inclusive start offset of the matched substring within `path`. */
+  readonly matchStart: number;
+  /** Exclusive end offset of the matched substring within `path`. */
+  readonly matchEnd: number;
+}
+
+/** A match plus the ranking signal used only for sorting. */
+interface RankedMatch extends WorkspaceFileMatch {
+  /** `true` when the hit falls within the basename (after the last `/`). */
+  readonly isBasenameHit: boolean;
+}
+
+/**
+ * Ranks a flat listing against a query, returning matched files best-first.
+ *
+ * - Case-insensitive substring on the full relative path.
+ * - Directories and advisory `notice` entries are never matched (a defensive
+ *   guard even though the shared cache already strips notices — DD-11).
+ * - Empty/whitespace query returns `[]` (search shows a hint, not everything).
+ *
+ * Ranking, in order: a basename hit outranks a path-only hit; then an earlier
+ * match offset; then a shorter path; then lexicographic path for a stable,
+ * deterministic order.
+ */
+export function matchWorkspaceFiles(
+  files: readonly WorkspaceFileEntry[],
+  query: string,
+): WorkspaceFileMatch[] {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return [];
+
+  const needle = trimmed.toLowerCase();
+  const ranked: RankedMatch[] = [];
+
+  for (const file of files) {
+    if (file.isDirectory || file.notice) continue;
+
+    const matchStart = file.path.toLowerCase().indexOf(needle);
+    if (matchStart === -1) continue;
+
+    const lastSlash = file.path.lastIndexOf("/");
+    ranked.push({
+      path: file.path,
+      matchStart,
+      matchEnd: matchStart + needle.length,
+      isBasenameHit: matchStart >= lastSlash + 1,
+    });
+  }
+
+  ranked.sort(compareMatches);
+
+  return ranked.map(({ path, matchStart, matchEnd }) => ({
+    path,
+    matchStart,
+    matchEnd,
+  }));
+}
+
+function compareMatches(a: RankedMatch, b: RankedMatch): number {
+  if (a.isBasenameHit !== b.isBasenameHit) return a.isBasenameHit ? -1 : 1;
+  if (a.matchStart !== b.matchStart) return a.matchStart - b.matchStart;
+  if (a.path.length !== b.path.length) return a.path.length - b.path.length;
+  return a.path.localeCompare(b.path);
+}

package/src/workspace/resolveWorkspaceFileSelection.ts

@@ -0,0 +1,119 @@
+// Resolve a transcript tool-call file path to an openable workspace-file
+// selection. This is the seam that lets a click on a path in the message thread
+// route to the same read-only Viewer a file-tree click drives (Slice 3).
+//
+// The hard part is NOT identity ("which entry") but PATH FORM. The reader and
+// lister contracts are strict: `WorkspaceFileReader` / the GitHub Trees lister
+// speak repo-root-relative (git) or root-relative (local) paths — the exact
+// strings a file-tree node carries. Transcript tool-call paths are not
+// guaranteed to be in that form: depending on harness and workspace layout they
+// arrive workspace-relative, subdir-prefixed, or absolute (see
+// `execution/file-review-status.ts` `changeForRowPath`, which documents the
+// same variance and treats path matching as presentation-only).
+//
+// Rather than fuzzy-match, this resolver normalizes deterministically using only
+// anchors the client already holds, grounded in how the runner provisions the
+// workspace (`backend/.../workspace/provisioner.ts`):
+//   - Single entry  -> cloned at the workspace root, so a (humanized) tool-call
+//                      path is already repo/root-relative. Identity transform.
+//   - Multiple git  -> each cloned into `<root>/<entry.name>/`, so the path is
+//                      prefixed by the subdir name; strip it.
+//   - Local (desktop) -> the native reader joins `entry.localPath` + a
+//                      root-relative path; local tool paths may be absolute, so
+//                      strip the known `entry.localPath` prefix.
+//   - Cloud absolute -> strip the known `sandboxWorkspaceRoot` first.
+// Anything that does not resolve to a definite relative path returns `null` so
+// the caller keeps its existing copy/GitHub-link behavior — a wrong file can
+// never open. Extending this to arbitrary/absolute paths belongs to a later
+// slice that resolves against the authoritative file-tree index.
+
+import { classifyPath } from "../execution/file-path-resolver.js";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+
+/** Forward-slash-normalize and drop any leading slashes for prefix comparison. */
+function normalize(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+
+/**
+ * Returns the portion of `path` beneath `anchor`, or `null` when `path` does
+ * not sit under `anchor`. An exact match (the anchor itself, a directory) yields
+ * `""` — the caller rejects it, since a directory is not a viewable file.
+ */
+function relativeTo(path: string, anchor: string): string | null {
+  if (!anchor) return null;
+  if (path === anchor) return "";
+  if (path.startsWith(anchor + "/")) return path.slice(anchor.length + 1);
+  return null;
+}
+
+/**
+ * Resolves a transcript tool-call file path to the {@link SelectedWorkspaceFile}
+ * that opens it in the read-only Viewer, or `null` when it cannot be resolved to
+ * a definite repo/root-relative file (caller keeps copy/GitHub-link fallback).
+ *
+ * `entries` are the client-side workspace entries (`useWorkspaceEntries`), the
+ * same list the Viewer resolves against, so the returned `entryId` is directly
+ * usable. `sandboxWorkspaceRoot` (when the session has git-repo entries, e.g.
+ * `/home/daytona/workspace`) is stripped first so cloud-absolute paths reduce to
+ * workspace-relative before per-entry anchoring.
+ *
+ * The result `path` is guaranteed to match what the file tree / lister emits for
+ * the same file, so opening from the transcript and from the tree produce an
+ * identical selection (and hit the same content fetch/cache).
+ */
+export function resolveWorkspaceFileSelection(
+  path: string,
+  entries: readonly WorkspaceEntry[],
+  sandboxWorkspaceRoot?: string,
+): SelectedWorkspaceFile | null {
+  if (!path || entries.length === 0) return null;
+
+  // 1. Reduce a cloud-absolute path to workspace-relative using the known root.
+  let work = normalize(path);
+  if (sandboxWorkspaceRoot) {
+    const root = normalize(sandboxWorkspaceRoot);
+    const relToRoot = relativeTo(work, root);
+    if (relToRoot !== null) work = relToRoot;
+  }
+  // The bare workspace root ("" after stripping, or the humanized ".") is not a
+  // file.
+  if (!work || work === ".") return null;
+
+  // 2. The platform mount (`.stigmer/…`) is a virtual namespace, not a workspace
+  //    file — checked after the root strip so an absolute `<root>/.stigmer/…`
+  //    is caught too. Keep copy behavior for it.
+  if (classifyPath(work).kind === "platform") return null;
+
+  // 3. Anchor on the exact per-entry roots the client holds. Local entries
+  //    anchor on their absolute `localPath`; multi-entry git repos anchor on the
+  //    provisioning subdir (`entry.name`). A single git entry is cloned at the
+  //    root, so it falls through to step 4.
+  const isMulti = entries.length > 1;
+  for (const entry of entries) {
+    let anchor: string | null = null;
+    if (entry.type === "local" && entry.localPath) {
+      anchor = normalize(entry.localPath);
+    } else if (entry.type === "git" && isMulti) {
+      anchor = normalize(entry.name);
+    }
+    if (anchor === null) continue;
+
+    const rel = relativeTo(work, anchor);
+    // Exact match is the entry's own root directory, not a viewable file — stop
+    // rather than fall through to the single-entry fallback (which would return
+    // the raw root path).
+    if (rel === "") return null;
+    if (rel) return { entryId: entry.id, path: rel };
+  }
+
+  // 4. A single entry whose anchor did not apply (e.g. a git repo at the root, or
+  //    a local path already root-relative): the path is already repo/root-relative.
+  if (entries.length === 1) {
+    return { entryId: entries[0].id, path: work };
+  }
+
+  // 5. Multi-entry with no anchor match: refuse to guess which entry owns it.
+  return null;
+}