@stigmer/react 0.0.36 → 0.0.40

package/src/environment/useRemoveEnvironmentVariables.ts

@@ -0,0 +1,86 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { RemoveEnvironmentVariablesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/**
+ * Input for removing specific variables from an environment by key.
+ *
+ * Keys that do not exist in the environment are silently ignored.
+ */
+export interface RemoveEnvironmentVariablesInput {
+  /** The environment resource ID. */
+  readonly environmentId: string;
+  /** Keys to remove from the environment's `spec.data`. */
+  readonly keys: string[];
+}
+
+export interface UseRemoveEnvironmentVariablesReturn {
+  readonly removeVariables: (
+    input: RemoveEnvironmentVariablesInput,
+  ) => Promise<Environment>;
+  readonly isRemovingVariables: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `environment.removeVariables()` with
+ * loading/error state.
+ *
+ * Removes the specified keys from the environment's `spec.data`.
+ * Keys that do not exist are silently ignored. Variables not
+ * mentioned in the request are preserved unchanged.
+ *
+ * Returns the full {@link Environment} proto (with secrets redacted)
+ * so callers can immediately reference the latest state.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**
+ * — delete individual variables without a full-resource update cycle.
+ *
+ * @example
+ * ```tsx
+ * const { removeVariables, isRemovingVariables, error } =
+ *   useRemoveEnvironmentVariables();
+ *
+ * const env = await removeVariables({
+ *   environmentId: "env-abc123",
+ *   keys: ["DEPRECATED_KEY", "OLD_TOKEN"],
+ * });
+ * ```
+ */
+export function useRemoveEnvironmentVariables(): UseRemoveEnvironmentVariablesReturn {
+  const stigmer = useStigmer();
+  const [isRemovingVariables, setIsRemovingVariables] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const removeVariables = useCallback(
+    async (input: RemoveEnvironmentVariablesInput): Promise<Environment> => {
+      setIsRemovingVariables(true);
+      setError(null);
+
+      try {
+        const request = create(RemoveEnvironmentVariablesRequestSchema, {
+          environmentId: input.environmentId,
+          keys: input.keys,
+        });
+
+        return await stigmer.environment.removeVariables(request);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsRemovingVariables(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { removeVariables, isRemovingVariables, error, clearError };
+}

package/src/environment/useRevealSecretValue.ts

@@ -0,0 +1,141 @@
+"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 { toError } from "../internal/toError";
+
+export interface UseRevealSecretValueOptions {
+  /**
+   * Milliseconds after which the revealed value is automatically cleared
+   * from component state. Prevents sensitive values from lingering in memory.
+   *
+   * - Default: `30_000` (30 seconds) — enough time to copy a value.
+   * - Set to `0` to disable auto-clear (caller is responsible for clearing).
+   */
+  readonly autoClearMs?: number;
+}
+
+export interface UseRevealSecretValueReturn {
+  /**
+   * Fetch and reveal a single secret value from an environment.
+   * Replaces any previously revealed value. Resets error state.
+   *
+   * @param environmentId - The environment resource ID.
+   * @param key - The key within `spec.data` to reveal.
+   */
+  readonly reveal: (environmentId: string, key: string) => Promise<void>;
+
+  /** The decrypted value, or `null` when not yet revealed or cleared. */
+  readonly revealedValue: string | null;
+
+  /** `true` while the reveal request is in-flight. */
+  readonly isRevealing: boolean;
+
+  /** Error message from the last failed reveal attempt, or `null`. */
+  readonly error: Error | null;
+
+  /** Immediately clear the revealed value and cancel any pending auto-clear timer. */
+  readonly clearRevealedValue: () => void;
+}
+
+const DEFAULT_AUTO_CLEAR_MS = 30_000;
+
+/**
+ * Behavior hook that encapsulates the "reveal secret" interaction.
+ *
+ * Fetches a single unredacted secret value via
+ * `stigmer.environment.getSecretValue()`, holds the decrypted value in
+ * state, and auto-clears it after a configurable timeout.
+ *
+ * This is an **imperative** hook (call `reveal()` on user action),
+ * not a declarative data hook (no auto-fetch on mount). It pairs with
+ * a "reveal" / "show" button in the UI — the canonical pattern for
+ * sensitive credential display (AWS, GitHub, 1Password).
+ *
+ * Follows the headless-first pattern: pure behavior, zero rendering.
+ * Platform builders compose this hook with their own UI.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**.
+ *
+ * @example
+ * ```tsx
+ * function SecretField({ envId, secretKey }: Props) {
+ *   const { reveal, revealedValue, isRevealing, clearRevealedValue } =
+ *     useRevealSecretValue();
+ *
+ *   return revealedValue ? (
+ *     <div>
+ *       <code>{revealedValue}</code>
+ *       <button onClick={clearRevealedValue}>Hide</button>
+ *     </div>
+ *   ) : (
+ *     <button onClick={() => reveal(envId, secretKey)} disabled={isRevealing}>
+ *       {isRevealing ? "Revealing…" : "Reveal"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useRevealSecretValue(
+  options?: UseRevealSecretValueOptions,
+): UseRevealSecretValueReturn {
+  const stigmer = useStigmer();
+  const [revealedValue, setRevealedValue] = useState<string | null>(null);
+  const [isRevealing, setIsRevealing] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const autoClearMs = options?.autoClearMs ?? DEFAULT_AUTO_CLEAR_MS;
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const clearRevealedValue = useCallback(() => {
+    cancelTimer();
+    setRevealedValue(null);
+  }, [cancelTimer]);
+
+  // Clean up timer and clear value on unmount
+  useEffect(() => {
+    return () => {
+      cancelTimer();
+      setRevealedValue(null);
+    };
+  }, [cancelTimer]);
+
+  const reveal = useCallback(
+    async (environmentId: string, key: string): Promise<void> => {
+      cancelTimer();
+      setIsRevealing(true);
+      setError(null);
+
+      try {
+        const result = await stigmer.environment.getSecretValue(
+          create(EnvironmentSecretValueInputSchema, { environmentId, key }),
+        );
+        setRevealedValue(result.value ?? null);
+
+        if (autoClearMs > 0) {
+          timerRef.current = setTimeout(() => {
+            setRevealedValue(null);
+            timerRef.current = null;
+          }, autoClearMs);
+        }
+      } catch (err) {
+        setError(toError(err));
+        setRevealedValue(null);
+      } finally {
+        setIsRevealing(false);
+      }
+    },
+    [stigmer, autoClearMs, cancelTimer],
+  );
+
+  return { reveal, revealedValue, isRevealing, error, clearRevealedValue };
+}

package/src/environment/useSessionEnvPool.ts

@@ -0,0 +1,151 @@
+"use client";
+
+import { useMemo } from "react";
+import type { EnvVarInput } from "@stigmer/sdk";
+import type { SessionVariableEntry } from "../execution/useSessionVariables";
+
+/**
+ * Inputs to the session env pool from all env-var sources.
+ *
+ * The pool aggregates keys and values from personal environment,
+ * manual session variables, agent one-time env vars, and MCP server
+ * pending runtime env. Any source can be omitted — the pool
+ * gracefully handles `undefined` inputs.
+ */
+export interface SessionEnvPoolInput {
+  /** Keys already saved in the user's personal environment. */
+  readonly personalEnvKeys?: Set<string>;
+  /** Manual session variable entries from {@link useSessionVariables}. */
+  readonly manualSecrets?: readonly SessionVariableEntry[];
+  /** Agent one-time runtime env (when resolution mode is `"oneTime"`). */
+  readonly agentRuntimeEnv?: Readonly<Record<string, EnvVarInput>>;
+  /** MCP server pending runtime env (accumulated one-time values). */
+  readonly mcpRuntimeEnv?: Readonly<Record<string, EnvVarInput>>;
+}
+
+export interface UseSessionEnvPoolReturn {
+  /**
+   * All env var keys currently available from any source.
+   *
+   * Includes keys from personal environment, valid manual secrets,
+   * agent one-time env, and MCP pending env. Reactive — recomputes
+   * when any source changes.
+   */
+  readonly availableKeys: Set<string>;
+
+  /**
+   * Look up a value by key from the pool.
+   *
+   * Priority order (last-write-wins, matching submit merge order):
+   * 1. Personal env keys (no values available — returns sentinel)
+   * 2. Agent one-time runtime env
+   * 3. MCP server pending runtime env
+   * 4. Manual session variables (highest priority)
+   *
+   * Returns `undefined` if the key is not in the pool.
+   */
+  readonly getAvailableValue: (key: string) => EnvVarInput | undefined;
+
+  /**
+   * Check if a key is satisfied by any source in the pool.
+   *
+   * Equivalent to `availableKeys.has(key)` but provided for
+   * semantic clarity.
+   */
+  readonly isKeySatisfied: (key: string) => boolean;
+}
+
+/**
+ * Reactive computation hook that aggregates environment variable
+ * availability from all session-level sources.
+ *
+ * The pool enables cross-referencing between the session variables
+ * panel, agent env form, and MCP server env form — so a variable
+ * entered in one place is recognized as "already provided" by the
+ * others. This eliminates duplicate credential prompting.
+ *
+ * Pure computation — no side effects, no API calls. Recomputes
+ * via `useMemo` when any input source changes.
+ *
+ * Platform builders who use individual setup hooks can pass the
+ * pool's `availableKeys` to `useMcpServerSetup` and `useAgentSetup`
+ * via their `poolKeys` parameter for cross-referencing.
+ *
+ * @example
+ * ```tsx
+ * const sessionVars = useSessionVariables();
+ * const personalEnv = usePersonalEnvironment(org);
+ *
+ * const pool = useSessionEnvPool({
+ *   personalEnvKeys: new Set(Object.keys(personalEnv.environment?.spec?.data ?? {})),
+ *   manualSecrets: sessionVars.entries,
+ * });
+ *
+ * // pool.isKeySatisfied("GITHUB_TOKEN") → true if entered anywhere
+ * ```
+ */
+export function useSessionEnvPool(
+  input: SessionEnvPoolInput,
+): UseSessionEnvPoolReturn {
+  const {
+    personalEnvKeys,
+    manualSecrets,
+    agentRuntimeEnv,
+    mcpRuntimeEnv,
+  } = input;
+
+  const valueMap = useMemo(() => {
+    const map = new Map<string, EnvVarInput>();
+
+    if (agentRuntimeEnv) {
+      for (const [key, value] of Object.entries(agentRuntimeEnv)) {
+        map.set(key, value);
+      }
+    }
+
+    if (mcpRuntimeEnv) {
+      for (const [key, value] of Object.entries(mcpRuntimeEnv)) {
+        map.set(key, value);
+      }
+    }
+
+    if (manualSecrets) {
+      for (const entry of manualSecrets) {
+        const k = entry.key.trim();
+        if (k !== "" && entry.value.trim() !== "") {
+          map.set(k, { value: entry.value, isSecret: entry.isSecret });
+        }
+      }
+    }
+
+    return map;
+  }, [manualSecrets, agentRuntimeEnv, mcpRuntimeEnv]);
+
+  const availableKeys = useMemo(() => {
+    const keys = new Set<string>();
+
+    if (personalEnvKeys) {
+      for (const key of personalEnvKeys) {
+        keys.add(key);
+      }
+    }
+
+    for (const key of valueMap.keys()) {
+      keys.add(key);
+    }
+
+    return keys;
+  }, [personalEnvKeys, valueMap]);
+
+  const getAvailableValue = useMemo(
+    () => (key: string): EnvVarInput | undefined => valueMap.get(key),
+    [valueMap],
+  );
+
+  const isKeySatisfied = useMemo(
+    () => (key: string): boolean => availableKeys.has(key),
+    [availableKeys],
+  );
+
+  return { availableKeys, getAvailableValue, isKeySatisfied };
+}

package/src/environment/useUpdateEnvironment.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { EnvironmentInput } from "@stigmer/sdk";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseUpdateEnvironmentReturn {
+  readonly update: (input: EnvironmentInput) => Promise<Environment>;
+  readonly isUpdating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `environment.update()` with loading/error
+ * state.
+ *
+ * Updates an existing Environment resource. The caller provides a
+ * full {@link EnvironmentInput} including the environment's `name`
+ * and `org` (used by the backend to identify the resource) and all
+ * spec fields.
+ *
+ * Returns the full {@link Environment} proto including
+ * server-updated metadata (version, timestamps) so callers can
+ * immediately reference the latest state.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**
+ * — persistent credential storage via Environment resources. For the
+ * managed "personal environment" convenience, see
+ * {@link usePersonalEnvironment} which composes this hook with
+ * deterministic naming and label conventions.
+ *
+ * @example
+ * ```tsx
+ * const { update, isUpdating, error } = useUpdateEnvironment();
+ *
+ * const env = await update({
+ *   name: "prod-credentials",
+ *   org: "acme",
+ *   description: "Production API keys",
+ *   data: {
+ *     API_KEY: { value: "sk-new-...", isSecret: true },
+ *   },
+ * });
+ * ```
+ */
+export function useUpdateEnvironment(): UseUpdateEnvironmentReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const update = useCallback(
+    async (input: EnvironmentInput): Promise<Environment> => {
+      setIsUpdating(true);
+      setError(null);
+
+      try {
+        return await stigmer.environment.update(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { update, isUpdating, error, clearError };
+}

package/src/environment/useUpdateEnvironmentVariables.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { EnvVarInput } from "@stigmer/sdk";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { UpdateEnvironmentVariablesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import { EnvironmentValueSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/**
+ * Input for adding or updating specific variables in an environment.
+ *
+ * Only the variables included in this request are affected — existing
+ * variables not mentioned are preserved unchanged. This avoids the
+ * read-modify-write pattern that destroys redacted secrets.
+ */
+export interface UpdateEnvironmentVariablesInput {
+  /** The environment resource ID. */
+  readonly environmentId: string;
+  /** Variables to add or update. Keys that already exist are overwritten. */
+  readonly variables: Record<string, EnvVarInput>;
+}
+
+export interface UseUpdateEnvironmentVariablesReturn {
+  readonly updateVariables: (
+    input: UpdateEnvironmentVariablesInput,
+  ) => Promise<Environment>;
+  readonly isUpdatingVariables: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `environment.updateVariables()` with
+ * loading/error state.
+ *
+ * Performs a server-side merge of the supplied variables into the
+ * environment's `spec.data`. Only the keys included in the request
+ * are affected — existing variables not mentioned are preserved.
+ * Secret values are encrypted server-side before persistence.
+ *
+ * Returns the full {@link Environment} proto (with secrets redacted)
+ * so callers can immediately reference the latest state.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**
+ * — incremental variable management without a full-resource update
+ * cycle.
+ *
+ * @example
+ * ```tsx
+ * const { updateVariables, isUpdatingVariables, error } =
+ *   useUpdateEnvironmentVariables();
+ *
+ * const env = await updateVariables({
+ *   environmentId: "env-abc123",
+ *   variables: {
+ *     API_KEY: { value: "sk-new-...", isSecret: true },
+ *     APP_NAME: { value: "my-app" },
+ *   },
+ * });
+ * ```
+ */
+export function useUpdateEnvironmentVariables(): UseUpdateEnvironmentVariablesReturn {
+  const stigmer = useStigmer();
+  const [isUpdatingVariables, setIsUpdatingVariables] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const updateVariables = useCallback(
+    async (input: UpdateEnvironmentVariablesInput): Promise<Environment> => {
+      setIsUpdatingVariables(true);
+      setError(null);
+
+      try {
+        const variables = Object.fromEntries(
+          Object.entries(input.variables).map(([k, v]) => [
+            k,
+            create(EnvironmentValueSchema, {
+              value: v.value,
+              isSecret: v.isSecret,
+              description: v.description,
+            }),
+          ]),
+        );
+
+        const request = create(UpdateEnvironmentVariablesRequestSchema, {
+          environmentId: input.environmentId,
+          variables,
+        });
+
+        return await stigmer.environment.updateVariables(request);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdatingVariables(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { updateVariables, isUpdatingVariables, error, clearError };
+}