@stigmer/react 0.0.36 → 0.0.40

package/src/github/useGitHubConnection.ts

@@ -0,0 +1,368 @@
+"use client";
+
+import { useCallback, useEffect, 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";
+
+const STORAGE_KEY_STATE = "stigmer:github:oauth-state";
+const GITHUB_USER_API = "https://api.github.com/user";
+const GITHUB_TOKEN_KEY = "GITHUB_TOKEN";
+
+/** Message type sent from the OAuth callback popup to the opener. */
+export const GITHUB_CALLBACK_MESSAGE_TYPE = "stigmer:github:callback-success";
+
+const POPUP_WIDTH = 600;
+const POPUP_HEIGHT = 700;
+const POPUP_CLOSE_POLL_MS = 500;
+
+/** Minimal GitHub user profile for display. */
+export interface GitHubUser {
+  readonly login: string;
+  readonly avatarUrl: string;
+  readonly name: string | null;
+}
+
+export interface GitHubConnectOptions {
+  /**
+   * When `true`, open the OAuth authorization page in a popup window
+   * instead of redirecting the current page. The callback page signals
+   * success via `postMessage` and the hook re-reconciles the token
+   * from the personal environment — keeping the user on the same page.
+   *
+   * Falls back to redirect if the popup is blocked by the browser.
+   *
+   * @default false
+   */
+  readonly popup?: boolean;
+}
+
+export interface UseGitHubConnectionReturn {
+  /** Whether a valid GitHub token exists. */
+  readonly isConnected: boolean;
+  /** Whether the connection state is being validated on mount. */
+  readonly isLoading: boolean;
+  /** Whether an OAuth popup is open and the flow is in progress. */
+  readonly isConnecting: boolean;
+  /**
+   * Whether the last popup `connect()` attempt was blocked by the
+   * browser. When `true`, the UI should prompt the user to allow
+   * popups or offer a redirect fallback (call `connect` without
+   * `{ popup: true }`).
+   */
+  readonly popupBlocked: boolean;
+  /** The connected GitHub user profile, if connected. */
+  readonly user: GitHubUser | null;
+  /** The current access token (null if not connected). */
+  readonly token: string | null;
+  /** Initiate the OAuth flow — redirect or popup based on options. */
+  readonly connect: (
+    redirectUri: string,
+    options?: GitHubConnectOptions,
+  ) => Promise<void>;
+  /** Handle the OAuth callback — exchange code for token. */
+  readonly handleCallback: (
+    code: string,
+    state: string,
+    redirectUri: string,
+  ) => Promise<void>;
+  /** Clear the stored token and user info. */
+  readonly disconnect: () => void;
+}
+
+async function fetchGitHubUser(token: string): Promise<GitHubUser | null> {
+  try {
+    const resp = await fetch(GITHUB_USER_API, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    return {
+      login: data.login,
+      avatarUrl: data.avatar_url,
+      name: data.name ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks whether the personal environment's redacted data contains a given key.
+ * The key is present even when the value is redacted (`***REDACTED***`).
+ */
+function personalEnvHasKey(
+  env: { spec?: { data?: Record<string, unknown> } } | null,
+  key: string,
+): boolean {
+  return env?.spec?.data != null && key in env.spec.data;
+}
+
+/**
+ * Behavior hook that manages the GitHub OAuth connection lifecycle.
+ *
+ * Handles the full OAuth flow: generating the authorize URL via the
+ * Stigmer backend, exchanging the code for a token, validating it,
+ * and persisting it in the user's server-side personal
+ * {@link Environment}.
+ *
+ * **Storage strategy:** The token is stored encrypted in the personal
+ * environment (server-side). On OAuth callback the token is written
+ * directly to the personal environment via `getOrCreate` /
+ * `addVariables`. On subsequent mounts the token is revealed from the
+ * personal environment and validated against the GitHub API.
+ *
+ * Pass `null` as `org` to disable server-side storage (the hook will
+ * report as not connected until org context is available).
+ *
+ * Platform builders who need custom GitHub integration UI use this
+ * hook directly. The styled `WorkspaceEditor` component accepts the
+ * return value as a prop.
+ *
+ * @param org - The active organization slug. Required for server-side
+ *   token storage. Pass `null` to skip all server operations.
+ */
+export function useGitHubConnection(
+  org: string | null,
+): UseGitHubConnectionReturn {
+  const stigmer = useStigmer();
+  const [token, setToken] = useState<string | null>(null);
+  const [user, setUser] = useState<GitHubUser | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [popupBlocked, setPopupBlocked] = useState(false);
+
+  const personalEnv = usePersonalEnvironment(org || null);
+
+  const personalEnvRef = useRef(personalEnv);
+  personalEnvRef.current = personalEnv;
+
+  const reconciled = useRef(false);
+  const popupRef = useRef<Window | null>(null);
+  const popupPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  // Synchronously reset loading state when org changes so callers
+  // (like the callback page) see the correct value in the same
+  // render — not deferred to the next render via an effect.
+  const [prevOrg, setPrevOrg] = useState(org);
+  if (org !== prevOrg) {
+    setPrevOrg(org);
+    setIsLoading(!!org);
+    reconciled.current = false;
+  }
+
+  // ── Server reconciliation ────────────────────────────────────────────
+  // Runs once after the personal environment finishes loading.
+  // If GITHUB_TOKEN exists in the personal env, reveals it and sets
+  // React state. If the revealed token is invalid, cleans it up.
+  // If no token exists, marks the hook as not connected.
+  useEffect(() => {
+    if (!org || personalEnv.isLoading) return;
+
+    if (reconciled.current) return;
+    reconciled.current = true;
+
+    const env = personalEnv.environment;
+    const hasServerToken = personalEnvHasKey(env, GITHUB_TOKEN_KEY);
+
+    if (!hasServerToken || !env) {
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+
+    async function reveal() {
+      try {
+        const result = await stigmer.environment.getSecretValue(
+          create(EnvironmentSecretValueInputSchema, {
+            environmentId: env!.metadata!.id,
+            key: GITHUB_TOKEN_KEY,
+          }),
+        );
+        if (cancelled) return;
+
+        const serverToken = result.value;
+        if (serverToken) {
+          const u = await fetchGitHubUser(serverToken);
+          if (cancelled) return;
+          if (u) {
+            setToken(serverToken);
+            setUser(u);
+          } else {
+            try {
+              await personalEnvRef.current.removeVariables([
+                GITHUB_TOKEN_KEY,
+              ]);
+            } catch {
+              // Best-effort cleanup.
+            }
+            setToken(null);
+            setUser(null);
+          }
+        }
+      } catch {
+        // getSecretValue failed — leave state as-is.
+      }
+
+      if (!cancelled) setIsLoading(false);
+    }
+
+    reveal();
+    return () => {
+      cancelled = true;
+    };
+  }, [org, personalEnv.isLoading, personalEnv.environment, stigmer]);
+
+  // ── Popup OAuth message listener ──────────────────────────────────────
+  // Listens for success signals from the OAuth callback page running
+  // in a popup window. On success, triggers re-reconciliation from the
+  // personal environment (where the popup already persisted the token).
+  useEffect(() => {
+    function handleMessage(event: MessageEvent) {
+      if (event.origin !== window.location.origin) return;
+      if (event.data?.type !== GITHUB_CALLBACK_MESSAGE_TYPE) return;
+
+      if (popupPollRef.current) {
+        clearInterval(popupPollRef.current);
+        popupPollRef.current = null;
+      }
+      popupRef.current = null;
+      setIsConnecting(false);
+
+      // Re-reconcile: the popup persisted the token server-side, so
+      // refetch the personal environment and let the reconciliation
+      // effect reveal and validate it.
+      setIsLoading(true);
+      reconciled.current = false;
+      personalEnvRef.current.refetch();
+    }
+
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, []);
+
+  // Clean up popup resources on unmount.
+  useEffect(() => {
+    return () => {
+      if (popupPollRef.current) {
+        clearInterval(popupPollRef.current);
+      }
+    };
+  }, []);
+
+  const connect = useCallback(
+    async (redirectUri: string, options?: GitHubConnectOptions) => {
+      const { authorizeUrl, state } =
+        await stigmer.github.getOAuthAuthorizeUrl({ redirectUri });
+
+      sessionStorage.setItem(STORAGE_KEY_STATE, state);
+
+      if (!options?.popup) {
+        window.location.href = authorizeUrl;
+        return;
+      }
+
+      // If a popup is already open, bring it to focus.
+      if (popupRef.current && !popupRef.current.closed) {
+        popupRef.current.focus();
+        return;
+      }
+
+      const left = window.screenX + (window.outerWidth - POPUP_WIDTH) / 2;
+      const top = window.screenY + (window.outerHeight - POPUP_HEIGHT) / 2;
+      const popup = window.open(
+        authorizeUrl,
+        "stigmer-github-auth",
+        `width=${POPUP_WIDTH},height=${POPUP_HEIGHT},left=${left},top=${top},popup=yes`,
+      );
+
+      if (!popup || popup.closed) {
+        setPopupBlocked(true);
+        return;
+      }
+      setPopupBlocked(false);
+
+      setIsConnecting(true);
+      popupRef.current = popup;
+
+      const pollId = setInterval(() => {
+        if (!popup.closed) return;
+        clearInterval(pollId);
+        if (popupPollRef.current === pollId) {
+          popupPollRef.current = null;
+          popupRef.current = null;
+          setIsConnecting(false);
+        }
+      }, POPUP_CLOSE_POLL_MS);
+      popupPollRef.current = pollId;
+    },
+    [stigmer],
+  );
+
+  const handleCallback = useCallback(
+    async (code: string, state: string, redirectUri: string) => {
+      const savedState = sessionStorage.getItem(STORAGE_KEY_STATE);
+      if (savedState && savedState !== state) {
+        throw new Error("OAuth state mismatch — possible CSRF attack");
+      }
+      sessionStorage.removeItem(STORAGE_KEY_STATE);
+
+      const { accessToken } = await stigmer.github.exchangeOAuthCode({
+        code,
+        state,
+        redirectUri,
+      });
+
+      const tokenVar = {
+        [GITHUB_TOKEN_KEY]: { value: accessToken, isSecret: true },
+      };
+      const env = await personalEnvRef.current.getOrCreate(tokenVar);
+      if (!personalEnvHasKey(env, GITHUB_TOKEN_KEY)) {
+        await personalEnvRef.current.addVariables(tokenVar);
+      }
+
+      setToken(accessToken);
+
+      const u = await fetchGitHubUser(accessToken);
+      setUser(u);
+    },
+    [stigmer],
+  );
+
+  const disconnect = useCallback(() => {
+    sessionStorage.removeItem(STORAGE_KEY_STATE);
+    setToken(null);
+    setUser(null);
+
+    if (popupRef.current && !popupRef.current.closed) {
+      popupRef.current.close();
+    }
+    popupRef.current = null;
+    if (popupPollRef.current) {
+      clearInterval(popupPollRef.current);
+      popupPollRef.current = null;
+    }
+    setIsConnecting(false);
+
+    const env = personalEnvRef.current.environment;
+    if (env && personalEnvHasKey(env, GITHUB_TOKEN_KEY)) {
+      personalEnvRef.current
+        .removeVariables([GITHUB_TOKEN_KEY])
+        .catch(() => {});
+    }
+  }, []);
+
+  return {
+    isConnected: token !== null,
+    isLoading,
+    isConnecting,
+    popupBlocked,
+    user,
+    token,
+    connect,
+    handleCallback,
+    disconnect,
+  };
+}

package/src/github/useGitHubRepos.ts

@@ -0,0 +1,197 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+const GITHUB_REPOS_API = "https://api.github.com/user/repos";
+const GITHUB_BRANCHES_API = "https://api.github.com/repos";
+const PER_PAGE = 100;
+
+/** A GitHub repository from the API. */
+export interface GitHubRepo {
+  readonly id: number;
+  readonly fullName: string;
+  readonly name: string;
+  readonly owner: string;
+  readonly ownerType: "User" | "Organization";
+  readonly htmlUrl: string;
+  readonly cloneUrl: string;
+  readonly defaultBranch: string;
+  readonly isPrivate: boolean;
+  readonly updatedAt: string;
+}
+
+/** A GitHub branch from the API. */
+export interface GitHubBranch {
+  readonly name: string;
+}
+
+export interface UseGitHubReposReturn {
+  readonly repos: readonly GitHubRepo[];
+  readonly isLoading: boolean;
+  /** True while additional pages are being fetched after the first page. */
+  readonly isBackgroundLoading: boolean;
+  readonly error: string | null;
+  readonly search: string;
+  readonly setSearch: (query: string) => void;
+  readonly hasMore: boolean;
+  /** @deprecated Background pagination loads all pages automatically. */
+  readonly loadMore: () => void;
+  readonly fetchBranches: (
+    owner: string,
+    repo: string,
+  ) => Promise<GitHubBranch[]>;
+}
+
+function parseRepoResponse(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 fetchRepoPage(
+  token: string,
+  page: number,
+): Promise<{ repos: GitHubRepo[]; hasMore: boolean }> {
+  const url = `${GITHUB_REPOS_API}?sort=pushed&direction=desc&per_page=${PER_PAGE}&page=${page}`;
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  if (!resp.ok) {
+    throw new Error(`GitHub API error: ${resp.status}`);
+  }
+
+  const data = await resp.json();
+  const repos = (data as Record<string, unknown>[]).map(parseRepoResponse);
+  return { repos, hasMore: repos.length === PER_PAGE };
+}
+
+/**
+ * Data hook that fetches the authenticated user's GitHub repositories.
+ *
+ * Loads the first page immediately, then eagerly background-fetches
+ * remaining pages so client-side search covers the full repo set.
+ * Provides client-side search filtering and branch fetching.
+ */
+export function useGitHubRepos(token: string | null): UseGitHubReposReturn {
+  const [allRepos, setAllRepos] = useState<GitHubRepo[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isBackgroundLoading, setIsBackgroundLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [search, setSearch] = useState("");
+  const [hasMore, setHasMore] = useState(true);
+
+  useEffect(() => {
+    if (!token) {
+      setAllRepos([]);
+      setIsLoading(false);
+      setIsBackgroundLoading(false);
+      setHasMore(false);
+      return;
+    }
+
+    const cancelled = { current: false };
+
+    async function fetchAll() {
+      setIsLoading(true);
+      setError(null);
+      setAllRepos([]);
+      setHasMore(true);
+
+      try {
+        const first = await fetchRepoPage(token!, 1);
+        if (cancelled.current) return;
+
+        setAllRepos(first.repos);
+        setIsLoading(false);
+
+        if (!first.hasMore) {
+          setHasMore(false);
+          return;
+        }
+
+        setIsBackgroundLoading(true);
+        let page = 2;
+        let more = true;
+
+        while (more && !cancelled.current) {
+          const result = await fetchRepoPage(token!, page);
+          if (cancelled.current) return;
+          setAllRepos((prev) => [...prev, ...result.repos]);
+          more = result.hasMore;
+          page++;
+        }
+
+        if (!cancelled.current) {
+          setHasMore(false);
+          setIsBackgroundLoading(false);
+        }
+      } catch (e) {
+        if (cancelled.current) return;
+        setError(e instanceof Error ? e.message : "Failed to fetch repos");
+        setIsLoading(false);
+        setIsBackgroundLoading(false);
+      }
+    }
+
+    fetchAll();
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [token]);
+
+  const loadMore = useCallback(() => {
+    // Retained for backwards compatibility. Background pagination
+    // fetches all pages automatically after the first page loads.
+  }, []);
+
+  const filtered = search
+    ? allRepos.filter((r) =>
+        r.fullName.toLowerCase().includes(search.toLowerCase()),
+      )
+    : allRepos;
+
+  const fetchBranches = useCallback(
+    async (owner: string, repo: string): Promise<GitHubBranch[]> => {
+      if (!token) return [];
+      try {
+        const resp = await fetch(
+          `${GITHUB_BRANCHES_API}/${owner}/${repo}/branches?per_page=100`,
+          { headers: { Authorization: `Bearer ${token}` } },
+        );
+        if (!resp.ok) return [];
+        const data = await resp.json();
+        return data.map((b: Record<string, unknown>) => ({
+          name: b.name as string,
+        }));
+      } catch {
+        return [];
+      }
+    },
+    [token],
+  );
+
+  return {
+    repos: filtered,
+    isLoading,
+    isBackgroundLoading,
+    error,
+    search,
+    setSearch,
+    hasMore,
+    loadMore,
+    fetchBranches,
+  };
+}