@stigmer/react 3.1.1 → 3.1.3

package/src/github/__tests__/useGitHubFileReader.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useGitHubFileReader } from "../useGitHubFileReader";
+import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function localEntry(): WorkspaceEntry {
+  return {
+    id: "ws-2",
+    name: "/Users/dev/project",
+    type: "local",
+    localPath: "/Users/dev/project",
+  };
+}
+
+function b64(s: string): string {
+  return Buffer.from(s, "utf-8").toString("base64");
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status });
+}
+
+describe("useGitHubFileReader", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns undefined when token is null", () => {
+    const { result } = renderHook(() => useGitHubFileReader(null));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns a reader function when a token is provided", () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    expect(typeof result.current).toBe("function");
+  });
+
+  it("returns null for non-git entries without fetching", async () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(localEntry(), "src/index.ts");
+    expect(content).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns null for non-GitHub git URLs", async () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(
+      gitEntry({ gitUrl: "https://gitlab.com/acme/api" }),
+      "src/index.ts",
+    );
+    expect(content).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("decodes a base64 text file from the Contents API", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 12, content: b64("Hello World!"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "src/index.ts");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.github.com/repos/acme/api/contents/src/index.ts?ref=main",
+      { headers: { Authorization: "Bearer ghp_abc" } },
+    );
+    expect(content).toEqual({
+      text: "Hello World!",
+      isBinary: false,
+      size: 12,
+      encoding: "utf-8",
+    });
+  });
+
+  it("encodes the path per segment and the branch", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(
+      gitEntry({ gitBranch: "feat/my branch" }),
+      "src/a b/c#d.ts",
+    );
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.github.com/repos/acme/api/contents/src/a%20b/c%23d.ts?ref=feat%2Fmy%20branch",
+      expect.anything(),
+    );
+  });
+
+  it("defaults to the main branch when gitBranch is undefined", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: undefined }), "f.ts");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("?ref=main"),
+      expect.anything(),
+    );
+  });
+
+  it("throws on a non-OK response (404 = failed to load, not unsupported)", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(new Response("nope", { status: 404 }));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow("HTTP 404");
+  });
+
+  it("throws when the path is a directory (Contents API returns an array)", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(jsonResponse([{ name: "index.ts" }]));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await expect(result.current!(gitEntry(), "src")).rejects.toThrow("is a directory");
+  });
+
+  it("falls back to the Blob API when Contents returns encoding:none", async () => {
+    const big = "x".repeat(2_000_000); // > 1 MB, ≤ 10 MB ceiling
+    vi.mocked(globalThis.fetch)
+      .mockResolvedValueOnce(
+        jsonResponse({ encoding: "none", size: big.length, content: "", sha: "blobsha" }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({ encoding: "base64", size: big.length, content: b64(big) }),
+      );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "big.txt");
+
+    expect(vi.mocked(globalThis.fetch).mock.calls[1][0]).toBe(
+      "https://api.github.com/repos/acme/api/git/blobs/blobsha",
+    );
+    expect(content!.size).toBe(big.length);
+    expect(content!.truncated).toBe(true);
+    expect(content!.text).toHaveLength(1_048_576);
+  });
+
+  it("reports files above the blob ceiling as too-large without downloading", async () => {
+    const hugeSize = 50 * 1024 * 1024; // 50 MB > 10 MB ceiling
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "none", size: hugeSize, content: "", sha: "blobsha" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "huge.bin");
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1); // no blob download
+    expect(content).toEqual({
+      text: null,
+      isBinary: false,
+      size: hugeSize,
+      encoding: "none",
+      truncated: true,
+    });
+  });
+
+  it("returns a stable reader reference across renders", () => {
+    const { result, rerender } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/github/decodeGitHubContent.ts

@@ -0,0 +1,83 @@
+// Pure byte/text decode helpers for the GitHub file reader.
+// Kept free of React and fetch so the Slice 0 spike behavior (base64 decode,
+// binary detection, the 1 MB cap) is unit-testable in isolation.
+
+import {
+  MAX_WORKSPACE_FILE_READ_BYTES,
+  type WorkspaceFileContent,
+} from "../workspace/WorkspaceFileReader.js";
+
+// Scan only the head for a NUL byte — git uses the first 8000 bytes as its
+// text/binary heuristic, and scanning the whole buffer buys nothing.
+const BINARY_SNIFF_BYTES = 8000;
+
+/**
+ * Decode a GitHub base64 payload to raw bytes.
+ *
+ * GitHub's Contents API line-wraps its base64 with `\n` every 60 chars, and
+ * `atob` rejects embedded newlines in some engines — strip all ASCII
+ * whitespace first.
+ */
+export function base64ToBytes(b64: string): Uint8Array {
+  const clean = b64.replace(/\s/g, "");
+  const binary = atob(clean);
+  return Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+}
+
+/** Detect binary content via a NUL byte in the head of the buffer. */
+export function detectBinary(bytes: Uint8Array): boolean {
+  const limit = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < limit; i++) {
+    if (bytes[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Decode bytes as strict UTF-8, returning `null` when the sequence is invalid.
+ * `{ fatal: true }` makes `TextDecoder` throw rather than emit replacement
+ * characters, so undecodable files degrade to the binary/unknown fallback
+ * instead of silently rendering mojibake.
+ */
+export function bytesToText(bytes: Uint8Array): string | null {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Turn decoded bytes into a {@link WorkspaceFileContent}, applying binary
+ * detection and the shared 1 MB display cap.
+ *
+ * @param bytes    the full decoded bytes as delivered by GitHub
+ * @param fullSize the file's true size in bytes (GitHub's `size` field), which
+ *                 may exceed `bytes.length` when the caller has already capped
+ *                 the download — reported verbatim as `size`.
+ */
+export function normalizeGitHubContent(
+  bytes: Uint8Array,
+  fullSize: number,
+): WorkspaceFileContent {
+  if (detectBinary(bytes)) {
+    return { text: null, isBinary: true, size: fullSize, encoding: "base64" };
+  }
+
+  // Decode the full buffer, then cap the resulting *string* — capping the bytes
+  // first could split a multibyte char at the boundary and make the fatal
+  // decoder reject an otherwise-valid file.
+  const text = bytesToText(bytes);
+  if (text === null) {
+    return { text: null, isBinary: false, size: fullSize, encoding: "unknown" };
+  }
+
+  const truncated = bytes.length > MAX_WORKSPACE_FILE_READ_BYTES;
+  return {
+    text: truncated ? text.slice(0, MAX_WORKSPACE_FILE_READ_BYTES) : text,
+    isBinary: false,
+    size: fullSize,
+    encoding: "utf-8",
+    ...(truncated ? { truncated: true } : {}),
+  };
+}

package/src/github/index.ts

@@ -25,4 +25,5 @@ export {
 } from "./GitHubRepoPicker.js";
 
 export { useGitHubTreeLister } from "./useGitHubTreeLister.js";
+export { useGitHubFileReader } from "./useGitHubFileReader.js";
 export { parseGitUrl, type ParsedGitRepo } from "./parseGitUrl.js";

package/src/github/useGitHubFileReader.ts

@@ -0,0 +1,152 @@
+"use client";
+
+import { useCallback } from "react";
+import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
+import type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "../workspace/WorkspaceFileReader.js";
+import { base64ToBytes, normalizeGitHubContent } from "./decodeGitHubContent.js";
+import { parseGitUrl } from "./parseGitUrl.js";
+
+const GITHUB_API = "https://api.github.com/repos";
+
+/**
+ * Upper bound on files we will pull through the Blob API (Gate 1, Option B).
+ *
+ * The Contents API caps at ~1 MB and signals larger files with
+ * `encoding: "none"`; the Blob API then serves them in full (up to GitHub's own
+ * ~100 MB blob limit). Since we only ever display the first ~1 MB, downloading
+ * a 90 MB blob to show 1 MB is wasteful — so above this ceiling we report the
+ * file as too-large
+ * (`text: null`, `truncated: true`) using the size GitHub already told us,
+ * without downloading anything.
+ */
+const BLOB_FETCH_CEILING_BYTES = 10 * 1024 * 1024; // 10 MiB
+
+/** Single-file shape of `GET /repos/{o}/{r}/contents/{path}`. */
+interface GitHubContentsFile {
+  readonly encoding: "base64" | "none";
+  readonly size: number;
+  readonly content: string;
+  readonly sha: string;
+}
+
+/** Shape of `GET /repos/{o}/{r}/git/blobs/{sha}`. */
+interface GitHubBlob {
+  readonly encoding: "base64";
+  readonly size: number;
+  readonly content: string;
+}
+
+/** Encode a repo-relative path per segment, preserving the slashes. */
+function encodePath(path: string): string {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+
+/**
+ * Creates a {@link WorkspaceFileReader} backed by the GitHub Contents API,
+ * with a Blob-API fallback for files above the Contents 1 MB cap.
+ *
+ * Uses the same client-side OAuth token as {@link useGitHubTreeLister}
+ * (`Authorization: Bearer`), inheriting its private-repo scope. Returns
+ * `undefined` when no token is present, mirroring the tree lister so callers
+ * can treat "no reader" and "no lister" identically.
+ *
+ * The reader itself:
+ * - Returns `null` when the entry is not a readable GitHub git repo
+ *   (non-git entry, missing/unparseable URL) — the "unsupported here" state.
+ * - **Throws** on a real failure: a non-OK response, or a directory path
+ *   (which the Contents API returns as a JSON array). Consumers surface these
+ *   as an error, distinct from the null "unsupported" state.
+ *
+ * @example
+ * ```tsx
+ * const gitHubConnection = useGitHubConnection(org);
+ * const fileReader = useGitHubFileReader(gitHubConnection.token);
+ * <SessionViewer workspaceFileReader={fileReader} />
+ * ```
+ */
+export function useGitHubFileReader(
+  token: string | null,
+): WorkspaceFileReader | undefined {
+  const reader = useCallback(
+    async (
+      entry: WorkspaceEntry,
+      path: string,
+    ): Promise<WorkspaceFileContent | null> => {
+      if (entry.type !== "git" || !entry.gitUrl || !token) return null;
+
+      const parsed = parseGitUrl(entry.gitUrl);
+      if (!parsed) return null;
+
+      const branch = entry.gitBranch || "main";
+      const url =
+        `${GITHUB_API}/${parsed.owner}/${parsed.repo}/contents/${encodePath(path)}` +
+        `?ref=${encodeURIComponent(branch)}`;
+
+      const resp = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!resp.ok) {
+        throw new Error(
+          `GitHub content fetch failed for ${path} (HTTP ${resp.status})`,
+        );
+      }
+
+      const data: unknown = await resp.json();
+      // The Contents API returns an array for a directory — a misdirected read,
+      // not an unsupported substrate, so fail loudly rather than return null.
+      if (Array.isArray(data)) {
+        throw new Error(`Cannot read "${path}": path is a directory`);
+      }
+
+      const file = data as GitHubContentsFile;
+      if (file.encoding === "base64") {
+        return normalizeGitHubContent(base64ToBytes(file.content), file.size);
+      }
+
+      // encoding: "none" is GitHub's signal that the file exceeds the Contents
+      // API's ~1 MB cap; the bytes live only behind the Blob API.
+      return readViaBlob(parsed, file, token);
+    },
+    [token],
+  );
+
+  if (!token) return undefined;
+  return reader;
+}
+
+/**
+ * Gate 1 / Option B — size-gated blob fetch for files the Contents API refused
+ * (`encoding: "none"`). Isolated so the large-file policy can change without
+ * touching the reader's control flow.
+ */
+async function readViaBlob(
+  parsed: { owner: string; repo: string },
+  file: GitHubContentsFile,
+  token: string,
+): Promise<WorkspaceFileContent> {
+  // Above the ceiling we never download — GitHub already told us the size, so
+  // report it as too-large-to-preview without spending the bandwidth.
+  if (file.size > BLOB_FETCH_CEILING_BYTES) {
+    return {
+      text: null,
+      isBinary: false,
+      size: file.size,
+      encoding: "none",
+      truncated: true,
+    };
+  }
+
+  const url = `${GITHUB_API}/${parsed.owner}/${parsed.repo}/git/blobs/${file.sha}`;
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!resp.ok) {
+    throw new Error(`GitHub blob fetch failed for ${file.sha} (HTTP ${resp.status})`);
+  }
+
+  const blob: GitHubBlob = await resp.json();
+  return normalizeGitHubContent(base64ToBytes(blob.content), blob.size);
+}

package/src/github/useGitHubTreeLister.ts

@@ -22,12 +22,16 @@ interface GitHubTreeResponse {
 }
 
 /**
- * Sentinel entry appended to the listing when the GitHub API indicates
- * that the tree was truncated (repository exceeds the API's entry limit).
+ * Advisory entry appended to the listing when the GitHub API indicates that the
+ * tree was truncated (repository exceeds the API's entry limit). Flagged with
+ * `notice: true` so generic consumers treat it as a "results incomplete" banner
+ * rather than an openable file (see `workspaceListingCache`) — never a tree leaf,
+ * never a search hit.
  */
 const TRUNCATION_MARKER: WorkspaceFileEntry = {
   path: "... (tree truncated by GitHub — repository has too many files)",
   isDirectory: false,
+  notice: true,
 };
 
 /**

package/src/index.ts

@@ -66,23 +66,58 @@ export type {
 export {
   useWorkspaceEntries,
   useWorkspaceFiles,
+  useWorkspaceFileContent,
+  useWorkspaceFileSearch,
+  useWorkspaceContentSearch,
   useWorkspaceSources,
+  MAX_WORKSPACE_FILE_READ_BYTES,
   WorkspaceEditor,
-  WorkspaceEntryFiles,
+  WorkspaceFileSearch,
+  WorkspaceContentSearch,
   WorkspaceSummary,
+  FileViewer,
+  WorkspaceSurface,
+  ExplorerTree,
+  virtualEntryId,
+  isVirtualEntryId,
 } from "./workspace/index.js";
 export type {
   WorkspaceEntry,
   WorkspaceFileEntry,
   WorkspaceFileLister,
+  WorkspaceFileContent,
+  WorkspaceFileReader,
   UseWorkspaceEntriesReturn,
   UseWorkspaceFilesOptions,
   UseWorkspaceFilesReturn,
-  WorkspaceEntryFilesProps,
+  UseWorkspaceFileContentOptions,
+  UseWorkspaceFileContentReturn,
+  UseWorkspaceFileSearchOptions,
+  UseWorkspaceFileSearchReturn,
+  WorkspaceFileSearchGroup,
+  WorkspaceFileMatch,
+  WorkspaceFileSearchProps,
+  WorkspaceContentMatch,
+  WorkspaceContentSearchResult,
+  WorkspaceContentSearcher,
+  UseWorkspaceContentSearchOptions,
+  UseWorkspaceContentSearchReturn,
+  WorkspaceContentSearchGroup,
+  WorkspaceContentSearchProps,
+  FileViewerProps,
+  FileViewerHandle,
+  SelectedWorkspaceFile,
   UseWorkspaceSourcesOptions,
   UseWorkspaceSourcesReturn,
   WorkspaceEditorProps,
   WorkspaceSummaryProps,
+  WorkspaceSurfaceProps,
+  SurfaceRailView,
+  SurfaceVirtualDocument,
+  ExplorerTreeProps,
+  OpenEditor,
+  OpenFileOptions,
+  RevealTarget,
 } from "./workspace/index.js";
 
 // Session — data hooks, behavior hooks, utilities (Session aggregate + conversation lifecycle)
@@ -112,9 +147,13 @@ export {
   resolvedSubject,
   SessionViewer,
   NewSessionViewer,
-  SessionInspector,
-  useSessionInspector,
-  buildVisibleTabs,
+  useSessionPanel,
+  usePlanDraft,
+  planDraftKey,
+  PlanEditor,
+  PlanStreamingDocument,
+  PLAN_DOCUMENT_ENTRY_ID,
+  PLAN_DOCUMENT_PATH,
   SetupTab,
 } from "./session/index.js";
 export type {
@@ -152,13 +191,14 @@ export type {
   SearchResultGroup,
   SessionViewerProps,
   NewSessionViewerProps,
+  SessionPanelController,
+  UseSessionPanelOptions,
+  PlanDraftController,
+  PlanEditorProps,
+  PlanStreamingDocumentProps,
   ExecutionTargetOption,
   RuntimeEnvProvider,
   SessionAudience,
-  SessionInspectorProps,
-  SessionInspectorTabId,
-  UseSessionInspectorOptions,
-  UseSessionInspectorReturn,
   SetupTabProps,
   SetupTabMutationCallbacks,
   SelectedThreadItem,
@@ -208,6 +248,9 @@ export {
   SummarizationBadge,
   SummarizationCard,
   PlanCompletionCard,
+  PlanArtifactCard,
+  PlanStreamingCard,
+  PlanDocumentMessage,
   useContextWindow,
   formatCost,
   formatTokenCount,
@@ -224,6 +267,7 @@ export {
   resolveToolCategoryFromKind,
   toolKindToCategoryInfo,
   defaultDisclosureForCategory,
+  extractPrimaryArg,
   McpToolDetail,
   parseMcpResult,
   formatDuration,
@@ -239,6 +283,7 @@ export {
   ApprovalCardBody,
   FileReviewCard,
   FileReviewDock,
+  FileChangeProgressBar,
   ApprovalContext,
   useApproval,
   FileReviewContext,
@@ -263,6 +308,7 @@ export {
   useArtifactContent,
   useArtifactDownloadUrl,
   useArtifactDownload,
+  useArtifactCopy,
   useToolOutputContent,
   useFileChangeContent,
   execIdFromStorageKey,
@@ -302,6 +348,9 @@ export type {
   SummarizationBadgeProps,
   SummarizationCardProps,
   PlanCompletionCardProps,
+  PlanArtifactCardProps,
+  PlanStreamingCardProps,
+  PlanDocumentMessageProps,
   ContextHealth,
   SummarizationEventView,
   UseContextWindowReturn,
@@ -320,6 +369,7 @@ export type {
   SubAgentSectionProps,
   MessageEntryProps,
   MessageThreadProps,
+  ThreadContentColumn,
   ThreadSkeletonProps,
   FollowUpInputProps,
   ApprovalCardProps,
@@ -327,6 +377,7 @@ export type {
   ApprovalCardBodyProps,
   FileReviewCardProps,
   FileReviewDockProps,
+  FileChangeProgressBarProps,
   ApprovalContextValue,
   UseApprovalResult,
   FileReviewContextValue,
@@ -349,6 +400,7 @@ export type {
   UseArtifactDownloadUrlReturn,
   UseArtifactDownloadUrlOptions,
   UseArtifactDownloadReturn,
+  UseArtifactCopyReturn,
   UseToolOutputContentReturn,
   ToolOutputRefLike,
   UseFileChangeContentReturn,
@@ -519,6 +571,7 @@ export {
   useGitHubRepos,
   useGitHubSearch,
   useGitHubTreeLister,
+  useGitHubFileReader,
   parseGitUrl,
   GitHubRepoPicker,
   GITHUB_CALLBACK_MESSAGE_TYPE,
@@ -931,7 +984,12 @@ export {
   detectSkillPackage,
   useDetectSkillPackage,
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
+  findLatestSessionPlan,
+  findStreamingPlan,
+  PLAN_ARTIFACT_NAME,
+  PLAN_ARTIFACT_SUFFIX,
   parseResourceYaml,
   serializeAgentYaml,
   serializeMcpServerYaml,
@@ -954,6 +1012,8 @@ export type {
   StigmerResourceKind,
   StigmerResourceDetection,
   SkillPackageDetection,
+  SessionPlan,
+  StreamingPlan,
   UseDetectSkillPackageReturn,
   ParsedResource,
   UseApplyResourceReturn,