@stigmer/react 1.0.3 → 2.0.0

package/src/runner/__tests__/useStopRunner.test.tsx

@@ -1,154 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-import type { ReactNode } from "react";
-import { create } from "@bufbuild/protobuf";
-import {
-  RunnerSchema,
-  RunnerStatusSchema,
-  type Runner,
-} from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
-import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
-import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
-import type { Stigmer } from "@stigmer/sdk";
-import { StigmerContext } from "../../context";
-import { useStopRunner } from "../useStopRunner";
-
-function makeRunner(id: string, phase: RunnerPhase): Runner {
-  const runner = create(RunnerSchema);
-  runner.metadata = create(ApiResourceMetadataSchema);
-  runner.metadata.id = id;
-  runner.status = create(RunnerStatusSchema);
-  runner.status.phase = phase;
-  return runner;
-}
-
-function buildMockClient(overrides: {
-  stop?: ReturnType<typeof vi.fn>;
-} = {}) {
-  return {
-    runner: {
-      stop: overrides.stop ?? vi.fn(),
-    },
-  } as unknown as Stigmer;
-}
-
-function makeWrapper(client: Stigmer) {
-  return ({ children }: { children: ReactNode }) => (
-    <StigmerContext.Provider value={client}>
-      {children}
-    </StigmerContext.Provider>
-  );
-}
-
-describe("useStopRunner", () => {
-  let stopMock: ReturnType<typeof vi.fn>;
-  let client: Stigmer;
-
-  beforeEach(() => {
-    stopMock = vi.fn();
-    client = buildMockClient({ stop: stopMock });
-  });
-
-  it("calls runner.stop with correct proto message and returns the runner", async () => {
-    const stoppedRunner = makeRunner("rnr_1", RunnerPhase.STOPPED);
-    stopMock.mockResolvedValueOnce(stoppedRunner);
-
-    const { result } = renderHook(() => useStopRunner(), {
-      wrapper: makeWrapper(client),
-    });
-
-    expect(result.current.isStopping).toBe(false);
-    expect(result.current.error).toBeNull();
-
-    let returned: Runner;
-    await act(async () => {
-      returned = await result.current.stop({
-        runnerId: "rnr_1",
-        reason: "user requested",
-      });
-    });
-
-    expect(stopMock).toHaveBeenCalledOnce();
-    const protoArg = stopMock.mock.calls[0][0];
-    expect(protoArg.runnerId).toBe("rnr_1");
-    expect(protoArg.reason).toBe("user requested");
-
-    expect(returned!).toBe(stoppedRunner);
-    expect(result.current.isStopping).toBe(false);
-    expect(result.current.error).toBeNull();
-  });
-
-  it("defaults reason to empty string when omitted", async () => {
-    const stoppedRunner = makeRunner("rnr_2", RunnerPhase.STOPPED);
-    stopMock.mockResolvedValueOnce(stoppedRunner);
-
-    const { result } = renderHook(() => useStopRunner(), {
-      wrapper: makeWrapper(client),
-    });
-
-    await act(async () => {
-      await result.current.stop({ runnerId: "rnr_2" });
-    });
-
-    const protoArg = stopMock.mock.calls[0][0];
-    expect(protoArg.reason).toBe("");
-  });
-
-  it("sets error and rethrows on failure", async () => {
-    const rpcError = new Error("runner not found");
-    stopMock.mockRejectedValueOnce(rpcError);
-
-    const { result } = renderHook(() => useStopRunner(), {
-      wrapper: makeWrapper(client),
-    });
-
-    await act(async () => {
-      await expect(
-        result.current.stop({ runnerId: "rnr_missing" }),
-      ).rejects.toThrow("runner not found");
-    });
-
-    expect(result.current.error).toBeInstanceOf(Error);
-    expect(result.current.error!.message).toBe("runner not found");
-    expect(result.current.isStopping).toBe(false);
-  });
-
-  it("clears error via clearError", async () => {
-    stopMock.mockRejectedValueOnce(new Error("fail"));
-
-    const { result } = renderHook(() => useStopRunner(), {
-      wrapper: makeWrapper(client),
-    });
-
-    await act(async () => {
-      await result.current.stop({ runnerId: "rnr_1" }).catch(() => {});
-    });
-    expect(result.current.error).not.toBeNull();
-
-    act(() => {
-      result.current.clearError();
-    });
-    expect(result.current.error).toBeNull();
-  });
-
-  it("resets previous error on a new successful stop", async () => {
-    stopMock.mockRejectedValueOnce(new Error("first fail"));
-
-    const { result } = renderHook(() => useStopRunner(), {
-      wrapper: makeWrapper(client),
-    });
-
-    await act(async () => {
-      await result.current.stop({ runnerId: "rnr_1" }).catch(() => {});
-    });
-    expect(result.current.error).not.toBeNull();
-
-    const stoppedRunner = makeRunner("rnr_1", RunnerPhase.STOPPED);
-    stopMock.mockResolvedValueOnce(stoppedRunner);
-
-    await act(async () => {
-      await result.current.stop({ runnerId: "rnr_1" });
-    });
-    expect(result.current.error).toBeNull();
-  });
-});

package/src/runner/index.ts

@@ -1,65 +0,0 @@
-export { useRunner } from "./useRunner";
-export type {
-  UseRunnerReturn,
-  UseRunnerOptions,
-} from "./useRunner";
-
-export { RunnerDetailView } from "./RunnerDetailView";
-export type { RunnerDetailViewProps } from "./RunnerDetailView";
-
-export { useRunnerList } from "./useRunnerList";
-export type {
-  UseRunnerListOptions,
-  UseRunnerListReturn,
-} from "./useRunnerList";
-
-export { useLaunchLocalRunner } from "./useLaunchLocalRunner";
-export type {
-  UseLaunchLocalRunnerOptions,
-  UseLaunchLocalRunnerReturn,
-  LaunchLocalRunnerResult,
-} from "./useLaunchLocalRunner";
-
-export { useRunnerCredential } from "./useRunnerCredential";
-export type {
-  RunnerCredential,
-  UseRunnerCredentialReturn,
-} from "./useRunnerCredential";
-
-export { useStopRunner } from "./useStopRunner";
-export type {
-  StopRunnerInput,
-  UseStopRunnerReturn,
-} from "./useStopRunner";
-
-export { useDeleteRunner } from "./useDeleteRunner";
-export type { UseDeleteRunnerReturn } from "./useDeleteRunner";
-
-export { RunnerPicker } from "./RunnerPicker";
-export type { RunnerPickerProps } from "./RunnerPicker";
-
-export { RunnerFileBrowser } from "./RunnerFileBrowser";
-export type { RunnerFileBrowserProps } from "./RunnerFileBrowser";
-
-export { useRunnerFileBrowser } from "./useRunnerFileBrowser";
-export type {
-  UseRunnerFileBrowserReturn,
-  PathSegment,
-} from "./useRunnerFileBrowser";
-
-export { RunnerListPanel } from "./RunnerListPanel";
-export type { RunnerListPanelProps, RunnerSortKey } from "./RunnerListPanel";
-
-export { WorkspaceRunnerSelector } from "./WorkspaceRunnerSelector";
-export type { WorkspaceRunnerSelectorProps } from "./WorkspaceRunnerSelector";
-
-export {
-  phaseLabel,
-  phaseDotColor,
-  isActivePhase,
-  isTransitionalPhase,
-  PHASE_SORT_ORDER,
-} from "./phase";
-
-export { RunnerIcon, PhaseBadge, formatRelativeTime } from "./shared";
-export type { RunnerIconProps, PhaseBadgeProps } from "./shared";

package/src/runner/phase.ts

@@ -1,84 +0,0 @@
-import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
-
-/**
- * Sort order for runner phases — active phases first, then by severity.
- *
- * Used by both {@link RunnerPicker} and {@link RunnerListPanel} to present
- * runners in a consistent, predictable order across all UI surfaces.
- */
-export const PHASE_SORT_ORDER: Record<RunnerPhase, number> = {
-  [RunnerPhase.READY]: 0,
-  [RunnerPhase.BUSY]: 1,
-  [RunnerPhase.STARTING]: 2,
-  [RunnerPhase.PENDING]: 3,
-  [RunnerPhase.STOPPED]: 4,
-  [RunnerPhase.FAILED]: 5,
-  [RunnerPhase.UNSPECIFIED]: 6,
-};
-
-const LABELS: Record<RunnerPhase, string> = {
-  [RunnerPhase.READY]: "Ready",
-  [RunnerPhase.BUSY]: "Busy",
-  [RunnerPhase.STARTING]: "Starting",
-  [RunnerPhase.PENDING]: "Pending",
-  [RunnerPhase.STOPPED]: "Stopped",
-  [RunnerPhase.FAILED]: "Failed",
-  [RunnerPhase.UNSPECIFIED]: "Unknown",
-};
-
-/**
- * Human-readable label for a runner phase.
- *
- * Returns title-case labels suitable for both compact indicators
- * ("Ready") and full-row display ("Stopped").
- */
-export function phaseLabel(phase: RunnerPhase): string {
-  return LABELS[phase] ?? "Unknown";
-}
-
-/**
- * Tailwind `bg-*` class for the small colored dot indicator.
- *
- * - Ready    → `bg-success`  (green)
- * - Busy     → `bg-warning`  (amber)
- * - Starting → `bg-primary`  (blue)
- * - Others   → `bg-muted-foreground` (neutral)
- */
-export function phaseDotColor(phase: RunnerPhase): string {
-  switch (phase) {
-    case RunnerPhase.READY:
-      return "bg-success";
-    case RunnerPhase.BUSY:
-      return "bg-warning";
-    case RunnerPhase.STARTING:
-      return "bg-primary";
-    default:
-      return "bg-muted-foreground";
-  }
-}
-
-/**
- * Whether the runner is in an active (workload-accepting) phase.
- *
- * Active = `READY` or `BUSY`. Inactive = everything else.
- */
-export function isActivePhase(phase: RunnerPhase): boolean {
-  return phase === RunnerPhase.READY || phase === RunnerPhase.BUSY;
-}
-
-/**
- * Whether the runner is in a transitional phase whose status is
- * expected to change soon without user action.
- *
- * `PENDING` — resource created, no process launched yet.
- * `STARTING` — process launched, runtime bootstrapping in progress.
- *
- * This is distinct from {@link isActivePhase} (READY | BUSY) where
- * the runner is stable and accepting work.
- *
- * Useful for driving conditional polling: poll while transitional
- * runners exist, stop when all runners reach a stable state.
- */
-export function isTransitionalPhase(phase: RunnerPhase): boolean {
-  return phase === RunnerPhase.PENDING || phase === RunnerPhase.STARTING;
-}

package/src/runner/shared.tsx

@@ -1,124 +0,0 @@
-"use client";
-
-import { cn } from "@stigmer/theme";
-import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
-import { phaseLabel, phaseDotColor } from "./phase";
-
-// ---------------------------------------------------------------------------
-// RunnerIcon
-// ---------------------------------------------------------------------------
-
-/** Props for {@link RunnerIcon}. */
-export interface RunnerIconProps {
-  readonly size?: number;
-  readonly className?: string;
-}
-
-/**
- * CPU-chip icon representing a runner. Used across the runner list,
- * fleet section, and empty states.
- */
-export function RunnerIcon({ size = 14, className }: RunnerIconProps) {
-  return (
-    <svg
-      width={size}
-      height={size}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden="true"
-      className={cn("shrink-0 text-muted-foreground", className)}
-    >
-      <rect x="4" y="4" width="16" height="16" rx="2" />
-      <rect x="9" y="9" width="6" height="6" />
-      <path d="M15 2v2" />
-      <path d="M15 20v2" />
-      <path d="M2 15h2" />
-      <path d="M2 9h2" />
-      <path d="M20 15h2" />
-      <path d="M20 9h2" />
-      <path d="M9 2v2" />
-      <path d="M9 20v2" />
-    </svg>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// PhaseBadge
-// ---------------------------------------------------------------------------
-
-/** Props for {@link PhaseBadge}. */
-export interface PhaseBadgeProps {
-  readonly phase: RunnerPhase;
-}
-
-/**
- * Compact badge showing a colored dot indicator and label for a runner
- * phase. Renders a spinning indicator for the STARTING phase.
- */
-export function PhaseBadge({ phase }: PhaseBadgeProps) {
-  const starting = phase === RunnerPhase.STARTING;
-  return (
-    <span className="inline-flex shrink-0 items-center gap-1">
-      {starting ? (
-        <span
-          className="inline-block h-2.5 w-2.5 animate-spin rounded-full border border-primary border-t-transparent"
-          aria-hidden="true"
-        />
-      ) : (
-        <span
-          className={`inline-block h-1.5 w-1.5 rounded-full ${phaseDotColor(phase)}`}
-          aria-hidden="true"
-        />
-      )}
-      <span
-        className={cn(
-          "text-[0.65rem]",
-          starting ? "text-primary" : "text-muted-foreground",
-        )}
-      >
-        {phaseLabel(phase)}
-      </span>
-    </span>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// formatRelativeTime
-// ---------------------------------------------------------------------------
-
-/**
- * Formats a Date as a compact relative time string.
- *
- * - < 60s → "just now"
- * - < 60m → "5m ago"
- * - < 24h → "3h ago"
- * - < 30d → "12d ago"
- * - otherwise → locale short date
- */
-export function formatRelativeTime(date: Date): string {
-  const diffMs = Date.now() - date.getTime();
-
-  if (diffMs < 0) return "just now";
-
-  const seconds = Math.floor(diffMs / 1000);
-  if (seconds < 60) return "just now";
-
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-
-  const days = Math.floor(hours / 24);
-  if (days < 30) return `${days}d ago`;
-
-  return date.toLocaleDateString(undefined, {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-  });
-}

package/src/runner/useDeleteRunner.ts

@@ -1,67 +0,0 @@
-"use client";
-
-import { useCallback, useState } from "react";
-import type { Runner } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
-
-/** Return value of {@link useDeleteRunner}. */
-export interface UseDeleteRunnerReturn {
-  /**
-   * Delete a runner by its resource ID. Resolves with the deleted
-   * {@link Runner} for confirmation display.
-   *
-   * The deletion is permanent — any sessions bound to this runner will
-   * fall back to auto-provisioning on their next execution.
-   */
-  readonly deleteRunner: (id: string) => Promise<Runner>;
-  /** `true` while the delete request is in flight. */
-  readonly isDeleting: boolean;
-  /** Error from the last failed delete, or `null` when healthy. */
-  readonly error: Error | null;
-  /** Reset `error` to `null`. */
-  readonly clearError: () => void;
-}
-
-/**
- * Mutation hook that wraps `runner.delete()` with loading and error
- * state.
- *
- * Deletes a runner by its resource ID. Returns the deleted
- * {@link Runner} on success so callers can confirm which runner was
- * removed (e.g., in a toast or undo prompt).
- *
- * @example
- * ```tsx
- * const { deleteRunner, isDeleting, error } = useDeleteRunner();
- *
- * await deleteRunner("rnr_abc123");
- * refetch(); // refresh the runner list
- * ```
- */
-export function useDeleteRunner(): UseDeleteRunnerReturn {
-  const stigmer = useStigmer();
-  const [isDeleting, setIsDeleting] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  const clearError = useCallback(() => setError(null), []);
-
-  const deleteRunner = useCallback(
-    async (id: string): Promise<Runner> => {
-      setIsDeleting(true);
-      setError(null);
-
-      try {
-        return await stigmer.runner.delete(id);
-      } catch (err) {
-        setError(toError(err));
-        throw err;
-      } finally {
-        setIsDeleting(false);
-      }
-    },
-    [stigmer],
-  );
-
-  return { deleteRunner, isDeleting, error, clearError };
-}

package/src/runner/useLaunchLocalRunner.ts

@@ -1,156 +0,0 @@
-"use client";
-
-import { useCallback, useState } from "react";
-import { create } from "@bufbuild/protobuf";
-import { timestampDate } from "@bufbuild/protobuf/wkt";
-import { CreateLaunchTokenRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
-
-const LAUNCH_RUNNER_SCHEME = "stigmer://launch-runner";
-
-function defaultOpenUrl(url: string): void {
-  window.location.href = url;
-}
-
-/** Options for {@link useLaunchLocalRunner}. */
-export interface UseLaunchLocalRunnerOptions {
-  /**
-   * Custom handler for opening the `stigmer://` URL.
-   *
-   * Defaults to `window.location.href` assignment, which is the standard
-   * browser pattern for dispatching custom URL schemes to the OS. The
-   * browser does not navigate away — it hands the scheme to the OS and
-   * the page stays on screen.
-   *
-   * Override this when embedding in non-standard environments (Electron,
-   * iframe, React Native WebView) where the default browser mechanism
-   * does not apply.
-   */
-  readonly openUrl?: (url: string) => void;
-}
-
-/** Result returned by a successful {@link UseLaunchLocalRunnerReturn.launch} call. */
-export interface LaunchLocalRunnerResult {
-  /** The `stigmer://launch-runner?token=...` URL that was opened. */
-  readonly url: string;
-  /**
-   * Absolute expiry time of the launch token. The desktop app must
-   * exchange the token before this time (typically 60 seconds).
-   */
-  readonly expiresAt: Date | undefined;
-}
-
-/** Return value of {@link useLaunchLocalRunner}. */
-export interface UseLaunchLocalRunnerReturn {
-  /**
-   * Create a one-time launch token and open the `stigmer://` URL to
-   * trigger the desktop app (or CLI fallback) to start a local runner.
-   *
-   * Resolves with the constructed URL and token expiry on success.
-   * The caller cannot detect whether the desktop app received the URL —
-   * use {@link useRunnerList} with `refetch()` to poll for the runner
-   * appearing in the list.
-   */
-  readonly launch: (input: { org: string }) => Promise<LaunchLocalRunnerResult>;
-  /** `true` while the token creation and URL dispatch are in flight. */
-  readonly isLaunching: boolean;
-  /**
-   * Result from the most recent successful launch dispatch, or `null`
-   * when no launch has been dispatched (or after {@link clearError}).
-   *
-   * Consumers can use `lastLaunchResult.expiresAt` to implement
-   * timeout-based detection: if no runner appears before the token
-   * expires, the desktop app likely did not receive the deep link.
-   */
-  readonly lastLaunchResult: LaunchLocalRunnerResult | null;
-  /** Error from the last failed launch attempt, or `null` when healthy. */
-  readonly error: Error | null;
-  /** Reset `error` and `lastLaunchResult` to `null`. */
-  readonly clearError: () => void;
-}
-
-/**
- * Behavior hook that initiates a browser-to-desktop runner launch.
- *
- * Orchestrates two steps:
- * 1. Calls `stigmer.runner.createLaunchToken({ org })` to mint a
- *    one-time, 60-second token backed by the caller's credentials.
- * 2. Opens `stigmer://launch-runner?token={token}` so the OS dispatches
- *    to the Stigmer Desktop app (which exchanges the token for a JWT
- *    and starts a local runner via its CLI sidecar).
- *
- * The hook reports success when the URL is opened. It does **not**
- * detect whether the desktop app is installed or whether the runner
- * actually started — those are observable via `useRunnerList`.
- *
- * @example
- * ```tsx
- * function LaunchButton({ org }: { org: string }) {
- *   const { launch, isLaunching, error } = useLaunchLocalRunner();
- *
- *   return (
- *     <button onClick={() => launch({ org })} disabled={isLaunching}>
- *       {isLaunching ? "Launching…" : "Launch Local Runner"}
- *     </button>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Custom URL handler for non-browser environments
- * const { launch } = useLaunchLocalRunner({
- *   openUrl: (url) => nativeBridge.openExternal(url),
- * });
- * ```
- */
-export function useLaunchLocalRunner(
-  options?: UseLaunchLocalRunnerOptions,
-): UseLaunchLocalRunnerReturn {
-  const stigmer = useStigmer();
-  const [isLaunching, setIsLaunching] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [lastLaunchResult, setLastLaunchResult] =
-    useState<LaunchLocalRunnerResult | null>(null);
-
-  const openUrl = options?.openUrl ?? defaultOpenUrl;
-
-  const clearError = useCallback(() => {
-    setError(null);
-    setLastLaunchResult(null);
-  }, []);
-
-  const launch = useCallback(
-    async (input: { org: string }): Promise<LaunchLocalRunnerResult> => {
-      setIsLaunching(true);
-      setError(null);
-      setLastLaunchResult(null);
-
-      try {
-        const response = await stigmer.runner.createLaunchToken(
-          create(CreateLaunchTokenRequestSchema, { org: input.org }),
-        );
-
-        const url = `${LAUNCH_RUNNER_SCHEME}?token=${encodeURIComponent(response.token)}`;
-        const expiresAt = response.expiresAt
-          ? timestampDate(response.expiresAt)
-          : undefined;
-
-        openUrl(url);
-
-        const result: LaunchLocalRunnerResult = { url, expiresAt };
-        setLastLaunchResult(result);
-        return result;
-      } catch (err) {
-        setError(toError(err));
-        throw err;
-      } finally {
-        setIsLaunching(false);
-      }
-    },
-    [stigmer, openUrl],
-  );
-
-  return { launch, isLaunching, lastLaunchResult, error, clearError };
-}