@stigmer/react 0.0.68 → 0.0.69

package/src/environment/__tests__/systemEnvVars.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import {
+  toGrpcAddress,
+  buildSystemEnvVars,
+  SYSTEM_ENV_VAR_KEYS,
+} from "../systemEnvVars";
+
+// ---------------------------------------------------------------------------
+// toGrpcAddress
+// ---------------------------------------------------------------------------
+
+describe("toGrpcAddress", () => {
+  it("extracts host and explicit port from http URL", () => {
+    expect(toGrpcAddress("http://localhost:7234")).toBe("localhost:7234");
+  });
+
+  it("defaults to port 443 for https without explicit port", () => {
+    expect(toGrpcAddress("https://api.stigmer.ai")).toBe(
+      "api.stigmer.ai:443",
+    );
+  });
+
+  it("preserves explicit port on https URL", () => {
+    expect(toGrpcAddress("https://api.stigmer.ai:8443")).toBe(
+      "api.stigmer.ai:8443",
+    );
+  });
+
+  it("defaults to port 80 for http without explicit port", () => {
+    expect(toGrpcAddress("http://api.local")).toBe("api.local:80");
+  });
+
+  it("handles IPv6 localhost", () => {
+    expect(toGrpcAddress("http://[::1]:7234")).toBe("[::1]:7234");
+  });
+
+  it("returns input unchanged for non-URL strings", () => {
+    expect(toGrpcAddress("not-a-url")).toBe("not-a-url");
+  });
+
+  it("handles trailing slash", () => {
+    expect(toGrpcAddress("http://localhost:7234/")).toBe("localhost:7234");
+  });
+
+  it("strips path components", () => {
+    expect(toGrpcAddress("https://api.stigmer.ai/v1/rpc")).toBe(
+      "api.stigmer.ai:443",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildSystemEnvVars
+// ---------------------------------------------------------------------------
+
+describe("buildSystemEnvVars", () => {
+  it("returns both system env vars", () => {
+    const result = buildSystemEnvVars(
+      "http://localhost:7234",
+      "test-token",
+    );
+
+    expect(Object.keys(result)).toHaveLength(2);
+    expect(result).toHaveProperty("STIGMER_SERVER_ADDRESS");
+    expect(result).toHaveProperty("STIGMER_API_KEY");
+  });
+
+  it("derives gRPC address from baseUrl", () => {
+    const result = buildSystemEnvVars(
+      "https://api.stigmer.ai",
+      "tok",
+    );
+
+    expect(result.STIGMER_SERVER_ADDRESS.value).toBe(
+      "api.stigmer.ai:443",
+    );
+    expect(result.STIGMER_SERVER_ADDRESS.isSecret).toBe(false);
+  });
+
+  it("uses credential as API key value", () => {
+    const result = buildSystemEnvVars(
+      "http://localhost:7234",
+      "my-api-key",
+    );
+
+    expect(result.STIGMER_API_KEY.value).toBe("my-api-key");
+    expect(result.STIGMER_API_KEY.isSecret).toBe(true);
+  });
+
+  it('uses "unused" placeholder when credential is null', () => {
+    const result = buildSystemEnvVars("http://localhost:7234", null);
+
+    expect(result.STIGMER_API_KEY.value).toBe("unused");
+  });
+
+  it('uses "unused" placeholder when credential is empty string', () => {
+    const result = buildSystemEnvVars("http://localhost:7234", "");
+
+    expect(result.STIGMER_API_KEY.value).toBe("unused");
+  });
+
+  it("keys match SYSTEM_ENV_VAR_KEYS constant", () => {
+    const result = buildSystemEnvVars("http://localhost:7234", "tok");
+    const resultKeys = new Set(Object.keys(result));
+
+    expect(resultKeys).toEqual(SYSTEM_ENV_VAR_KEYS);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SYSTEM_ENV_VAR_KEYS
+// ---------------------------------------------------------------------------
+
+describe("SYSTEM_ENV_VAR_KEYS", () => {
+  it("contains exactly the two expected keys", () => {
+    expect(SYSTEM_ENV_VAR_KEYS.size).toBe(2);
+    expect(SYSTEM_ENV_VAR_KEYS.has("STIGMER_SERVER_ADDRESS")).toBe(true);
+    expect(SYSTEM_ENV_VAR_KEYS.has("STIGMER_API_KEY")).toBe(true);
+  });
+});

package/src/environment/index.ts

@@ -41,3 +41,9 @@ export type {
   SessionEnvPoolInput,
   UseSessionEnvPoolReturn,
 } from "./useSessionEnvPool";
+export {
+  SYSTEM_ENV_VAR_KEYS,
+  toGrpcAddress,
+  buildSystemEnvVars,
+  resolveSystemEnvVarValues,
+} from "./systemEnvVars";

package/src/environment/systemEnvVars.ts

@@ -0,0 +1,104 @@
+import type { EnvVarInput, Stigmer } from "@stigmer/sdk";
+
+// ---------------------------------------------------------------------------
+// Well-known Stigmer platform environment variable keys
+//
+// These env vars configure MCP server subprocesses (and agents) to
+// communicate back to the Stigmer backend. Because the SDK client
+// already knows the server address and auth credential, the setup
+// hooks can skip prompting users for these values and inject them
+// automatically at session creation time.
+// ---------------------------------------------------------------------------
+
+const STIGMER_SERVER_ADDRESS = "STIGMER_SERVER_ADDRESS";
+const STIGMER_API_KEY = "STIGMER_API_KEY";
+
+/**
+ * Environment variable keys that the SDK can resolve automatically
+ * from the current {@link Stigmer} client context.
+ *
+ * Used by setup hooks to exclude these keys from the "missing
+ * variables" prompt and by the session composer to inject their
+ * values into runtime env at submit time.
+ *
+ * Platform builders who manage setup hooks directly can use this
+ * set to extend their own `poolKeys`.
+ */
+export const SYSTEM_ENV_VAR_KEYS: ReadonlySet<string> = new Set([
+  STIGMER_SERVER_ADDRESS,
+  STIGMER_API_KEY,
+]);
+
+/**
+ * Convert an HTTP(S) base URL to a gRPC host:port address.
+ *
+ * The Stigmer server serves both gRPC and gRPC-Web on the same
+ * endpoint, so stripping the protocol and extracting host:port
+ * produces a valid gRPC dial target.
+ *
+ * @example
+ * ```ts
+ * toGrpcAddress("http://localhost:7234")   // "localhost:7234"
+ * toGrpcAddress("https://api.stigmer.ai")  // "api.stigmer.ai:443"
+ * toGrpcAddress("https://api.stigmer.ai:8443") // "api.stigmer.ai:8443"
+ * ```
+ */
+export function toGrpcAddress(httpUrl: string): string {
+  try {
+    const url = new URL(httpUrl);
+    const host = url.hostname;
+    const port =
+      url.port || (url.protocol === "https:" ? "443" : "80");
+    return `${host}:${port}`;
+  } catch {
+    return httpUrl;
+  }
+}
+
+/**
+ * Build system env var entries from raw connection parameters.
+ *
+ * Pure function — no side effects, no async. Suitable for unit
+ * testing without a live Stigmer client.
+ *
+ * @param baseUrl - The Stigmer client's base URL (HTTP).
+ * @param credential - Current auth credential, or `null` for
+ *   unauthenticated (OSS) backends. When `null`, a placeholder
+ *   value is used so the MCP server env var is always populated.
+ */
+export function buildSystemEnvVars(
+  baseUrl: string,
+  credential: string | null,
+): Record<string, EnvVarInput> {
+  return {
+    [STIGMER_SERVER_ADDRESS]: {
+      value: toGrpcAddress(baseUrl),
+      isSecret: false,
+      description:
+        "Auto-resolved from the current Stigmer connection.",
+    },
+    [STIGMER_API_KEY]: {
+      value: credential || "unused",
+      isSecret: true,
+      description:
+        "Auto-resolved from the current Stigmer auth context.",
+    },
+  };
+}
+
+/**
+ * Resolve system env var values from a live {@link Stigmer} client.
+ *
+ * Calls {@link Stigmer.getAuthCredential} to obtain the current
+ * credential, then delegates to {@link buildSystemEnvVars}.
+ *
+ * Intended for use at session submit time — the returned values
+ * are injected into `runtimeEnv` at the **lowest priority** so
+ * any user-provided values (personal env, manual secrets) win.
+ */
+export async function resolveSystemEnvVarValues(
+  stigmer: Stigmer,
+): Promise<Record<string, EnvVarInput>> {
+  const credential = await stigmer.getAuthCredential();
+  return buildSystemEnvVars(stigmer.baseUrl, credential);
+}

package/src/execution/ApprovalCard.tsx

@@ -173,6 +173,7 @@ export function ApprovalCard({
             isSubmitting={isSubmitting}
             onClick={handleAction}
             variant="approve"
+            cursorTarget="approve-button"
           />
           <ActionButton
             label="Skip"
@@ -207,6 +208,7 @@ function ActionButton({
   isSubmitting,
   onClick,
   variant,
+  cursorTarget,
 }: {
   label: string;
   action: ApprovalAction;
@@ -214,6 +216,7 @@ function ActionButton({
   isSubmitting: boolean;
   onClick: (action: ApprovalAction) => void;
   variant: "approve" | "skip" | "reject";
+  cursorTarget?: string;
 }) {
   const isActive = activeAction === action;
   const disabled = isSubmitting;
@@ -239,6 +242,7 @@ function ActionButton({
       disabled={disabled}
       onClick={() => onClick(action)}
       aria-label={label}
+      data-cursor-target={cursorTarget}
       className={cn(
         "inline-flex items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
         "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",

package/src/index.ts

@@ -327,7 +327,7 @@ export type {
   UseDefaultAgentReturn,
 } from "./agent";
 
-// Environment — data hooks, list hook, personal convenience hook, secret reveal, variable management, env var form, and styled components
+// Environment — data hooks, list hook, personal convenience hook, secret reveal, variable management, env var form, system env vars, and styled components
 export {
   useEnvironment,
   useEnvironmentList,
@@ -342,6 +342,10 @@ export {
   CreateEnvironmentForm,
   EnvVarForm,
   useSessionEnvPool,
+  SYSTEM_ENV_VAR_KEYS,
+  toGrpcAddress,
+  buildSystemEnvVars,
+  resolveSystemEnvVarValues,
 } from "./environment";
 export type {
   UseEnvironmentReturn,

package/src/internal/Tabs.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import { useCallback, useId, useRef, type KeyboardEvent, type ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+
+export interface TabItem {
+  /** Unique identifier for the tab, used as the `activeTab` value. */
+  readonly id: string;
+  /** Display label shown in the tab trigger. */
+  readonly label: string;
+  /** Optional numeric badge rendered next to the label (e.g. item count). */
+  readonly badge?: number;
+}
+
+export interface TabsProps {
+  /** Ordered list of tabs to render. Tabs with no matching content are still clickable. */
+  readonly tabs: readonly TabItem[];
+  /** The `id` of the currently active tab. */
+  readonly activeTab: string;
+  /** Called when the user selects a different tab. */
+  readonly onTabChange: (tabId: string) => void;
+  /**
+   * Content to render in the active tab panel.
+   * Typically a switch/map over `activeTab`.
+   */
+  readonly children: ReactNode;
+  /** Accessible label for the tab list (e.g. "Capability sections"). */
+  readonly "aria-label"?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Accessible tabbed panel with badge support.
+ *
+ * Implements the WAI-ARIA Tabs pattern:
+ * - `role="tablist"` / `role="tab"` / `role="tabpanel"`
+ * - Arrow-key navigation (Left/Right), Home/End to jump
+ * - `aria-selected`, `aria-controls`, `aria-labelledby` wiring
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * No external dependencies — safe for platform builder embedding.
+ *
+ * @internal — not yet part of the public `@stigmer/react` API.
+ */
+export function Tabs({
+  tabs,
+  activeTab,
+  onTabChange,
+  children,
+  "aria-label": ariaLabel,
+  className,
+}: TabsProps) {
+  const instanceId = useId();
+  const tabRefsMap = useRef<Map<string, HTMLButtonElement>>(new Map());
+
+  const tabId = (id: string) => `${instanceId}-tab-${id}`;
+  const panelId = (id: string) => `${instanceId}-panel-${id}`;
+
+  const focusTab = useCallback(
+    (id: string) => {
+      tabRefsMap.current.get(id)?.focus();
+      onTabChange(id);
+    },
+    [onTabChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const currentIndex = tabs.findIndex((t) => t.id === activeTab);
+      if (currentIndex === -1) return;
+
+      let nextIndex: number | null = null;
+
+      switch (e.key) {
+        case "ArrowRight":
+          nextIndex = (currentIndex + 1) % tabs.length;
+          break;
+        case "ArrowLeft":
+          nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+          break;
+        case "Home":
+          nextIndex = 0;
+          break;
+        case "End":
+          nextIndex = tabs.length - 1;
+          break;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      focusTab(tabs[nextIndex].id);
+    },
+    [tabs, activeTab, focusTab],
+  );
+
+  return (
+    <div className={cn("flex flex-col", className)}>
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        onKeyDown={handleKeyDown}
+        className="flex border-b border-border"
+      >
+        {tabs.map((tab) => {
+          const isActive = tab.id === activeTab;
+          return (
+            <button
+              key={tab.id}
+              ref={(el) => {
+                if (el) tabRefsMap.current.set(tab.id, el);
+                else tabRefsMap.current.delete(tab.id);
+              }}
+              id={tabId(tab.id)}
+              role="tab"
+              type="button"
+              aria-selected={isActive}
+              aria-controls={panelId(tab.id)}
+              tabIndex={isActive ? 0 : -1}
+              onClick={() => onTabChange(tab.id)}
+              data-cursor-target={`tab-${tab.id}`}
+              className={cn(
+                "relative inline-flex items-center gap-1.5 px-3 py-2 text-xs font-medium transition-colors",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+                isActive
+                  ? "text-foreground"
+                  : "text-muted-foreground hover:text-foreground",
+              )}
+            >
+              {tab.label}
+              {tab.badge != null && tab.badge > 0 && (
+                <span
+                  className={cn(
+                    "inline-flex min-w-[1.25rem] items-center justify-center rounded-full px-1 py-px text-[10px] font-medium leading-none",
+                    isActive
+                      ? "bg-primary/10 text-primary"
+                      : "bg-muted text-muted-foreground",
+                  )}
+                >
+                  {tab.badge}
+                </span>
+              )}
+              {isActive && (
+                <span
+                  className="absolute inset-x-0 -bottom-px h-0.5 bg-primary"
+                  aria-hidden="true"
+                />
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      <div
+        id={panelId(activeTab)}
+        role="tabpanel"
+        aria-labelledby={tabId(activeTab)}
+        tabIndex={0}
+        className="focus-visible:outline-none"
+      >
+        {children}
+      </div>
+    </div>
+  );
+}