@stigmer/react 3.1.0 → 3.1.2

package/src/execution/useExecutionStream.ts

@@ -12,23 +12,23 @@ import {
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { isTransientStreamError } from "@stigmer/sdk";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
-import { useStreamRate } from "../internal/dev";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { useStreamRate } from "../internal/dev/index.js";
 import {
   StreamController,
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_SLOW_THRESHOLD_MS,
   type StreamControllerSink,
-} from "../internal/stream-controller";
+} from "../internal/stream-controller.js";
 import {
   computeBackoffDelay,
   sleep,
   DEFAULT_RECONNECT_MAX_ATTEMPTS,
   type BackoffOptions,
-} from "../internal/backoff";
-import { ConversationStore } from "../internal/store";
-import { isTerminalPhase } from "./execution-phases";
+} from "../internal/backoff.js";
+import { ConversationStore } from "../internal/store/index.js";
+import { isTerminalPhase } from "./execution-phases.js";
 
 /** Return value of {@link useExecutionStream}. */
 export interface UseExecutionStreamReturn {

package/src/execution/useFileChangeContent.ts

@@ -5,8 +5,8 @@ import type {
   FileChange,
   FileContent,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { useArtifactContent } from "./useArtifactContent";
-import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl";
+import { useArtifactContent } from "./useArtifactContent.js";
+import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl.js";
 
 /** Return value of {@link useFileChangeContent}. */
 export interface UseFileChangeContentReturn {

package/src/execution/useFileReview.ts

@@ -7,8 +7,8 @@ import {
   FileDecisionScope,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { SubmitFileDecisionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
 
 /** Options narrowing a file decision to a single file and binding its digest. */
 export interface FileDecisionOptions {

package/src/execution/useSubmitApproval.ts

@@ -4,9 +4,9 @@ import { useCallback, useMemo, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
-import { useKeyedSubmission } from "../internal/useKeyedSubmission";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission.js";
 
 /** Return value of {@link useSubmitApproval}. */
 export interface UseSubmitApprovalReturn {

package/src/execution/useThreadSelection.ts

@@ -1,8 +1,8 @@
 "use client";
 
 import { useCallback, useContext, useSyncExternalStore } from "react";
-import type { SelectedThreadItem } from "../internal/store/selection-store";
-import { ThreadSelectionContext } from "./ThreadSelectionContext";
+import type { SelectedThreadItem } from "../internal/store/selection-store.js";
+import { ThreadSelectionContext } from "./ThreadSelectionContext.js";
 
 /**
  * Return value of {@link useThreadSelection} when a provider is present.

package/src/execution/useToolOutputContent.ts

@@ -2,8 +2,8 @@
 
 import { useMemo } from "react";
 import type { ToolCallOutputRef } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { useArtifactContent } from "./useArtifactContent";
-import { execIdFromStorageKey } from "./useFileChangeContent";
+import { useArtifactContent } from "./useArtifactContent.js";
+import { execIdFromStorageKey } from "./useFileChangeContent.js";
 
 /** Return value of {@link useToolOutputContent}. */
 export interface UseToolOutputContentReturn {

package/src/execution-target-context.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { createContext, useContext } from "react";
-import type { ExecutionTargetOption } from "./session/execution-target";
+import type { ExecutionTargetOption } from "./session/execution-target.js";
 
 /**
  * React context for the app-level execution target.

package/src/feedback/StigmerToaster.tsx

@@ -1,8 +1,8 @@
 "use client";
 
 import { Toaster } from "sonner";
-import { useColorMode } from "../color-mode";
-import type { StigmerToasterProps } from "./types";
+import { useColorMode } from "../color-mode.js";
+import type { StigmerToasterProps } from "./types.js";
 
 /**
  * Themed toast container for Stigmer SDK components.

package/src/feedback/index.ts

@@ -1,3 +1,3 @@
-export { StigmerToaster } from "./StigmerToaster";
-export { toast } from "./toast";
-export type { StigmerToasterProps } from "./types";
+export { StigmerToaster } from "./StigmerToaster.js";
+export { toast } from "./toast.js";
+export type { StigmerToasterProps } from "./types.js";

package/src/file-reference/index.ts

@@ -1,2 +1,2 @@
-export { useFileReferences, type UseFileReferencesReturn } from "./useFileReferences";
-export { FileReferenceChipList, type FileReferenceChipListProps } from "./FileReferenceChipList";
+export { useFileReferences, type UseFileReferencesReturn } from "./useFileReferences.js";
+export { FileReferenceChipList, type FileReferenceChipListProps } from "./FileReferenceChipList.js";

package/src/github/GitHubRepoPicker.tsx

@@ -8,8 +8,8 @@ import {
   useMemo,
   type KeyboardEvent,
 } from "react";
-import { useGitHubRepos, type GitHubRepo, type GitHubBranch } from "./useGitHubRepos";
-import { useGitHubSearch } from "./useGitHubSearch";
+import { useGitHubRepos, type GitHubRepo, type GitHubBranch } from "./useGitHubRepos.js";
+import { useGitHubSearch } from "./useGitHubSearch.js";
 
 /** Props for {@link GitHubRepoPicker}. */
 export interface GitHubRepoPickerProps {

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

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import {
+  base64ToBytes,
+  detectBinary,
+  bytesToText,
+  normalizeGitHubContent,
+} from "../decodeGitHubContent";
+import { MAX_WORKSPACE_FILE_READ_BYTES } from "../../workspace/WorkspaceFileReader";
+
+function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+describe("base64ToBytes", () => {
+  it("decodes plain base64 to bytes", () => {
+    expect(bytesToText(base64ToBytes("SGVsbG8gV29ybGQh"))).toBe("Hello World!");
+  });
+
+  it("strips the newlines GitHub inserts every 60 chars", () => {
+    // GitHub's Contents API line-wraps its base64; atob would otherwise reject it.
+    const wrapped = "SGVsbG8g\nV29ybGQh\n";
+    expect(bytesToText(base64ToBytes(wrapped))).toBe("Hello World!");
+  });
+});
+
+describe("detectBinary", () => {
+  it("flags a buffer containing a NUL byte", () => {
+    expect(detectBinary(new Uint8Array([0x48, 0x00, 0x49]))).toBe(true);
+  });
+
+  it("treats NUL-free text as non-binary", () => {
+    expect(detectBinary(utf8("just some text"))).toBe(false);
+  });
+
+  it("only sniffs the head — a NUL past the sniff window is not detected", () => {
+    const bytes = new Uint8Array(9000).fill(0x61); // non-zero baseline
+    bytes[8500] = 0; // beyond the 8000-byte sniff window
+    expect(detectBinary(bytes)).toBe(false);
+  });
+});
+
+describe("bytesToText", () => {
+  it("decodes valid UTF-8", () => {
+    expect(bytesToText(utf8("héllo — 世界"))).toBe("héllo — 世界");
+  });
+
+  it("returns null for invalid UTF-8", () => {
+    // 0xFF is never a valid UTF-8 lead byte; the fatal decoder throws → null.
+    expect(bytesToText(new Uint8Array([0xff]))).toBeNull();
+  });
+});
+
+describe("normalizeGitHubContent", () => {
+  it("maps clean text to a utf-8 content record with the full size", () => {
+    const bytes = utf8("hello");
+    expect(normalizeGitHubContent(bytes, bytes.length)).toEqual({
+      text: "hello",
+      isBinary: false,
+      size: bytes.length,
+      encoding: "utf-8",
+    });
+  });
+
+  it("reports binary content with text null", () => {
+    const result = normalizeGitHubContent(new Uint8Array([0x00, 0x01, 0x02]), 3);
+    expect(result).toEqual({
+      text: null,
+      isBinary: true,
+      size: 3,
+      encoding: "base64",
+    });
+  });
+
+  it("marks undecodable (non-binary) bytes as unknown encoding", () => {
+    // 0xC0 is an invalid UTF-8 lead byte but not a NUL, so it is not "binary".
+    const result = normalizeGitHubContent(new Uint8Array([0xc0, 0x41]), 2);
+    expect(result).toEqual({
+      text: null,
+      isBinary: false,
+      size: 2,
+      encoding: "unknown",
+    });
+  });
+
+  it("truncates at the 1 MB cap and flags it, while size reports the full length", () => {
+    const total = MAX_WORKSPACE_FILE_READ_BYTES + 500;
+    const bytes = new Uint8Array(total).fill(0x61); // 'a'
+    const result = normalizeGitHubContent(bytes, total);
+
+    expect(result.truncated).toBe(true);
+    expect(result.size).toBe(total);
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+    expect(result.encoding).toBe("utf-8");
+  });
+
+  it("does not set truncated when exactly at the cap", () => {
+    const bytes = new Uint8Array(MAX_WORKSPACE_FILE_READ_BYTES).fill(0x61);
+    const result = normalizeGitHubContent(bytes, bytes.length);
+    expect(result.truncated).toBeUndefined();
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+  });
+});

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

@@ -5,24 +5,25 @@ export {
   type GitHubConnectOptions,
   type UseGitHubConnectionConfig,
   type UseGitHubConnectionReturn,
-} from "./useGitHubConnection";
+} from "./useGitHubConnection.js";
 
 export {
   useGitHubRepos,
   type GitHubRepo,
   type GitHubBranch,
   type UseGitHubReposReturn,
-} from "./useGitHubRepos";
+} from "./useGitHubRepos.js";
 
 export {
   useGitHubSearch,
   type UseGitHubSearchReturn,
-} from "./useGitHubSearch";
+} from "./useGitHubSearch.js";
 
 export {
   GitHubRepoPicker,
   type GitHubRepoPickerProps,
-} from "./GitHubRepoPicker";
+} from "./GitHubRepoPicker.js";
 
-export { useGitHubTreeLister } from "./useGitHubTreeLister";
-export { parseGitUrl, type ParsedGitRepo } from "./parseGitUrl";
+export { useGitHubTreeLister } from "./useGitHubTreeLister.js";
+export { useGitHubFileReader } from "./useGitHubFileReader.js";
+export { parseGitUrl, type ParsedGitRepo } from "./parseGitUrl.js";

package/src/github/useGitHubConnection.ts

@@ -3,8 +3,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { EnvironmentSecretValueInputSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
+import { useStigmer } from "../hooks.js";
+import { usePersonalEnvironment } from "../environment/usePersonalEnvironment.js";
 
 const STORAGE_KEY_STATE = "stigmer:github:oauth-state";
 const GITHUB_USER_API = "https://api.github.com/user";