@stigmer/react 0.0.53 → 0.0.55

package/src/github/index.ts

@@ -13,6 +13,11 @@ export {
   type UseGitHubReposReturn,
 } from "./useGitHubRepos";
 
+export {
+  useGitHubSearch,
+  type UseGitHubSearchReturn,
+} from "./useGitHubSearch";
+
 export {
   GitHubRepoPicker,
   type GitHubRepoPickerProps,

package/src/github/useGitHubSearch.ts

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { GitHubRepo } from "./useGitHubRepos";
+
+const GITHUB_SEARCH_API = "https://api.github.com/search/repositories";
+const DEBOUNCE_MS = 350;
+const PER_PAGE = 30;
+
+export interface UseGitHubSearchReturn {
+  readonly results: readonly GitHubRepo[];
+  readonly isSearching: boolean;
+  readonly error: string | null;
+  readonly query: string;
+  readonly setQuery: (query: string) => void;
+  readonly totalCount: number;
+  readonly hasMore: boolean;
+  readonly loadMore: () => void;
+}
+
+function parseSearchItem(r: Record<string, unknown>): GitHubRepo {
+  const ownerObj = r.owner as Record<string, unknown>;
+  return {
+    id: r.id as number,
+    fullName: r.full_name as string,
+    name: r.name as string,
+    owner: ownerObj.login as string,
+    ownerType:
+      (ownerObj.type as string) === "Organization" ? "Organization" : "User",
+    htmlUrl: r.html_url as string,
+    cloneUrl: r.clone_url as string,
+    defaultBranch: r.default_branch as string,
+    isPrivate: r.private as boolean,
+    updatedAt: r.updated_at as string,
+  };
+}
+
+async function searchRepos(
+  query: string,
+  page: number,
+  token: string | null,
+): Promise<{ repos: GitHubRepo[]; totalCount: number; hasMore: boolean }> {
+  const params = new URLSearchParams({
+    q: query,
+    sort: "stars",
+    order: "desc",
+    per_page: String(PER_PAGE),
+    page: String(page),
+  });
+
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const resp = await fetch(`${GITHUB_SEARCH_API}?${params}`, { headers });
+
+  if (!resp.ok) {
+    if (resp.status === 403) {
+      throw new Error("GitHub search rate limit exceeded. Try again shortly.");
+    }
+    throw new Error(`GitHub search error: ${resp.status}`);
+  }
+
+  const data = (await resp.json()) as {
+    total_count: number;
+    items: Record<string, unknown>[];
+  };
+
+  const repos = data.items.map(parseSearchItem);
+  const totalCount = data.total_count;
+  const hasMore = page * PER_PAGE < totalCount;
+
+  return { repos, totalCount, hasMore };
+}
+
+/**
+ * Data hook that searches GitHub's public repository index.
+ *
+ * Uses the GitHub Search API (`/search/repositories`) with debounced input.
+ * Finds repositories across all of GitHub, not just the user's own repos.
+ * Works with or without an auth token (auth: 30 req/min; unauth: 10 req/min).
+ */
+export function useGitHubSearch(
+  token: string | null,
+): UseGitHubSearchReturn {
+  const [query, setQuery] = useState("");
+  const [debouncedQuery, setDebouncedQuery] = useState("");
+  const [results, setResults] = useState<GitHubRepo[]>([]);
+  const [isSearching, setIsSearching] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [totalCount, setTotalCount] = useState(0);
+  const [hasMore, setHasMore] = useState(false);
+  const [page, setPage] = useState(1);
+  const debounceTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  useEffect(() => {
+    clearTimeout(debounceTimer.current);
+    if (!query.trim()) {
+      setDebouncedQuery("");
+      setResults([]);
+      setTotalCount(0);
+      setHasMore(false);
+      setError(null);
+      return;
+    }
+    debounceTimer.current = setTimeout(() => {
+      setDebouncedQuery(query.trim());
+      setPage(1);
+    }, DEBOUNCE_MS);
+    return () => clearTimeout(debounceTimer.current);
+  }, [query]);
+
+  useEffect(() => {
+    if (!debouncedQuery) return;
+
+    const cancelled = { current: false };
+
+    async function run() {
+      setIsSearching(true);
+      setError(null);
+      try {
+        const result = await searchRepos(debouncedQuery, page, token);
+        if (cancelled.current) return;
+        setResults((prev) =>
+          page === 1 ? result.repos : [...prev, ...result.repos],
+        );
+        setTotalCount(result.totalCount);
+        setHasMore(result.hasMore);
+      } catch (e) {
+        if (cancelled.current) return;
+        setError(e instanceof Error ? e.message : "Search failed");
+      } finally {
+        if (!cancelled.current) setIsSearching(false);
+      }
+    }
+
+    run();
+    return () => {
+      cancelled.current = true;
+    };
+  }, [debouncedQuery, page, token]);
+
+  const loadMore = useCallback(() => {
+    if (hasMore && !isSearching) {
+      setPage((prev) => prev + 1);
+    }
+  }, [hasMore, isSearching]);
+
+  return {
+    results,
+    isSearching,
+    error,
+    query,
+    setQuery,
+    totalCount,
+    hasMore,
+    loadMore,
+  };
+}

package/src/index.ts

@@ -52,6 +52,8 @@ export {
   useSessionList,
   useSessionExecutions,
   useSessionConversation,
+  useSessionArtifacts,
+  useSessionWriteBacks,
   useAgentRefFromSession,
   groupSessionsByTime,
   PENDING_SUBJECT,
@@ -68,6 +70,10 @@ export type {
   UseSessionExecutionsReturn,
   SendFollowUpOptions,
   UseSessionConversationReturn,
+  SessionArtifactEntry,
+  UseSessionArtifactsReturn,
+  SessionWriteBackEntry,
+  UseSessionWriteBacksReturn,
   UseAgentRefFromSessionReturn,
   SessionGroup,
 } from "./session";
@@ -100,6 +106,7 @@ export {
   ArtifactContentRenderer,
   ArtifactPreviewModal,
   ArtifactsWidget,
+  WriteBacksWidget,
   ToolArgsView,
   McpArgsView,
   McpMetadataRow,
@@ -112,6 +119,8 @@ export {
   SessionVariablesInput,
   useExecutionArtifacts,
   useArtifactContent,
+  useWorkspaceWriteBacks,
+  WriteBackCard,
   isTextArtifact,
   isArtifactExpired,
   formatArtifactSize,
@@ -145,6 +154,7 @@ export type {
   ArtifactRenderMode,
   ArtifactPreviewModalProps,
   ArtifactsWidgetProps,
+  WriteBacksWidgetProps,
   FilePathLinkProps,
   FilePathContextValue,
   PathClassification,
@@ -154,6 +164,8 @@ export type {
   SessionVariablesInputProps,
   UseExecutionArtifactsReturn,
   UseArtifactContentReturn,
+  UseWorkspaceWriteBacksReturn,
+  WriteBackCardProps,
 } from "./execution";
 
 // Execution — proto type re-exports for artifact consumers
@@ -257,6 +269,7 @@ export type {
 export {
   useGitHubConnection,
   useGitHubRepos,
+  useGitHubSearch,
   GitHubRepoPicker,
   GITHUB_CALLBACK_MESSAGE_TYPE,
 } from "./github";
@@ -267,6 +280,7 @@ export type {
   GitHubRepo,
   GitHubBranch,
   UseGitHubReposReturn,
+  UseGitHubSearchReturn,
   GitHubRepoPickerProps,
 } from "./github";
 

package/src/session/index.ts

@@ -26,6 +26,18 @@ export type {
   UseSessionConversationReturn,
 } from "./useSessionConversation";
 
+export { useSessionArtifacts } from "./useSessionArtifacts";
+export type {
+  SessionArtifactEntry,
+  UseSessionArtifactsReturn,
+} from "./useSessionArtifacts";
+
+export { useSessionWriteBacks } from "./useSessionWriteBacks";
+export type {
+  SessionWriteBackEntry,
+  UseSessionWriteBacksReturn,
+} from "./useSessionWriteBacks";
+
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
 

package/src/session/useSessionArtifacts.ts

@@ -0,0 +1,143 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "../execution/execution-phases";
+
+/**
+ * A single artifact entry enriched with the execution context needed
+ * for content fetching and Apply/Push gating.
+ *
+ * The `executionId` identifies which execution produced (or last
+ * updated) this artifact — required by {@link useArtifactContent} and
+ * {@link ArtifactPreviewModal}. `isTerminal` controls whether the
+ * Apply CTA is enabled in the preview modal.
+ */
+export interface SessionArtifactEntry {
+  readonly artifact: ExecutionArtifact;
+  /** ID of the execution that produced this artifact version. */
+  readonly executionId: string;
+  /** Whether the producing execution is in a terminal phase. */
+  readonly isTerminal: boolean;
+  /**
+   * `true` when another artifact in the deduplicated list shares the
+   * same display `name` but has a different `sandbox_path`. Consumers
+   * use this to render path context for disambiguation.
+   */
+  readonly hasNameCollision: boolean;
+}
+
+export interface UseSessionArtifactsReturn {
+  /** Deduplicated, alphabetically-sorted artifacts from all executions. */
+  readonly artifacts: readonly SessionArtifactEntry[];
+  /** `true` when there is at least one artifact across all executions. */
+  readonly hasArtifacts: boolean;
+  /** Total number of deduplicated artifacts. */
+  readonly artifactCount: number;
+}
+
+/**
+ * Returns the dedup key for an artifact. Uses `sandbox_path` when
+ * available (stable filesystem identity within the session sandbox),
+ * falling back to `name` for older artifacts that predate the field.
+ */
+function dedupKey(artifact: ExecutionArtifact): string {
+  return artifact.sandboxPath || artifact.name;
+}
+
+/**
+ * Pure derivation hook that aggregates artifacts across all executions
+ * in a session into a unified, deduplicated, alphabetically-sorted
+ * list — like a file explorer showing the conversation's output.
+ *
+ * Follows the same `useMemo`-based pattern as
+ * {@link useExecutionArtifacts}: no side effects, no data fetching.
+ *
+ * **Dedup semantics:** Artifacts are keyed by `sandbox_path` (the
+ * original filesystem path in the agent sandbox). When multiple
+ * executions produce an artifact at the same path, the latest
+ * execution's version wins — matching filesystem overwrite semantics.
+ *
+ * **Sorting:** Entries are sorted alphabetically by display `name`
+ * (case-insensitive). This matches the file-explorer mental model
+ * where users scan by filename, not by creation order.
+ *
+ * **Name collision detection:** When two artifacts share the same
+ * display `name` but differ in `sandbox_path`, both entries are
+ * flagged with `hasNameCollision: true` so consumers can render path
+ * context for disambiguation.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order (as returned by `listBySession`). Pass both completed and
+ *   active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { artifacts, hasArtifacts } = useSessionArtifacts(allExecutions);
+ * ```
+ *
+ * @see useExecutionArtifacts — single-execution artifact derivation
+ * @see ArtifactsWidget — styled component that renders this data
+ */
+export function useSessionArtifacts(
+  executions: readonly AgentExecution[],
+): UseSessionArtifactsReturn {
+  return useMemo(() => {
+    const entryMap = new Map<string, SessionArtifactEntry>();
+
+    for (const execution of executions) {
+      const executionId = execution.metadata?.id ?? "";
+      const phase =
+        execution.status?.phase ??
+        ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      const terminal = isTerminalPhase(phase);
+
+      for (const artifact of execution.status?.artifacts ?? []) {
+        const key = dedupKey(artifact);
+        entryMap.set(key, {
+          artifact,
+          executionId,
+          isTerminal: terminal,
+          hasNameCollision: false,
+        });
+      }
+    }
+
+    const entries = Array.from(entryMap.values());
+
+    entries.sort((a, b) =>
+      a.artifact.name.localeCompare(b.artifact.name, undefined, {
+        sensitivity: "base",
+      }),
+    );
+
+    // Detect name collisions: entries that share a display name but
+    // have different sandbox paths need path context for disambiguation.
+    const nameCount = new Map<string, number>();
+    for (const entry of entries) {
+      const lower = entry.artifact.name.toLowerCase();
+      nameCount.set(lower, (nameCount.get(lower) ?? 0) + 1);
+    }
+
+    const result: SessionArtifactEntry[] = entries.map((entry) => {
+      const lower = entry.artifact.name.toLowerCase();
+      if ((nameCount.get(lower) ?? 0) > 1) {
+        return { ...entry, hasNameCollision: true };
+      }
+      return entry;
+    });
+
+    return {
+      artifacts: result,
+      hasArtifacts: result.length > 0,
+      artifactCount: result.length,
+    };
+  }, [executions]);
+}

package/src/session/useSessionWriteBacks.ts

@@ -0,0 +1,94 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+/**
+ * A single write-back entry enriched with the execution context that
+ * produced it.
+ *
+ * The `executionId` links the write-back to its originating execution
+ * for traceability in the UI (e.g., tooltip or detail view).
+ */
+export interface SessionWriteBackEntry {
+  readonly writeBack: WorkspaceWriteBack;
+  /** ID of the execution that produced this write-back. */
+  readonly executionId: string;
+}
+
+export interface UseSessionWriteBacksReturn {
+  /** All write-backs from the session, ordered by workspace entry name. */
+  readonly writeBacks: readonly SessionWriteBackEntry[];
+  /** `true` when there is at least one write-back across all executions. */
+  readonly hasWriteBacks: boolean;
+  /** Total number of write-backs. */
+  readonly writeBackCount: number;
+}
+
+/**
+ * Pure derivation hook that aggregates workspace write-backs across all
+ * executions in a session into a flat, deduplicated list.
+ *
+ * Follows the same pattern as {@link useSessionArtifacts}: `useMemo`-based
+ * derivation, no side effects, no data fetching. Takes the same
+ * `executions` array input.
+ *
+ * **Dedup semantics:** Write-backs are keyed by `workspace_entry_name`.
+ * When multiple executions write back to the same workspace entry (e.g.,
+ * a follow-up execution on the same git repo), the latest execution's
+ * write-back wins — each execution creates its own branch/PR, and the
+ * most recent one is the one users care about.
+ *
+ * **Sorting:** Entries are sorted alphabetically by workspace entry name.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order. Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { writeBacks, hasWriteBacks } = useSessionWriteBacks(allExecutions);
+ * ```
+ *
+ * @see useWorkspaceWriteBacks — single-execution write-back derivation
+ * @see WriteBackCard — component that renders a single write-back
+ */
+export function useSessionWriteBacks(
+  executions: readonly AgentExecution[],
+): UseSessionWriteBacksReturn {
+  return useMemo(() => {
+    const entryMap = new Map<string, SessionWriteBackEntry>();
+
+    for (const execution of executions) {
+      const executionId = execution.metadata?.id ?? "";
+
+      for (const wb of execution.status?.workspaceWriteBacks ?? []) {
+        entryMap.set(wb.workspaceEntryName, {
+          writeBack: wb,
+          executionId,
+        });
+      }
+    }
+
+    const entries = Array.from(entryMap.values());
+
+    entries.sort((a, b) =>
+      a.writeBack.workspaceEntryName.localeCompare(
+        b.writeBack.workspaceEntryName,
+        undefined,
+        { sensitivity: "base" },
+      ),
+    );
+
+    return {
+      writeBacks: entries,
+      hasWriteBacks: entries.length > 0,
+      writeBackCount: entries.length,
+    };
+  }, [executions]);
+}