@stigmer/react 0.0.36 → 0.0.39

package/src/environment/diffEnvSpec.ts

@@ -0,0 +1,50 @@
+import type { EnvVarFormVariable } from "./EnvVarForm";
+
+/**
+ * Computes the list of environment variables a resource requires that
+ * the user has not yet provided.
+ *
+ * Compares a resource's declared `env_spec.data` keys against a set of
+ * keys already present in the user's personal environment **and** an
+ * optional session-level env pool (manual secrets, one-time env vars
+ * from other components). Variables whose keys are missing from both
+ * sources are returned as {@link EnvVarFormVariable} entries suitable
+ * for rendering in {@link EnvVarForm}.
+ *
+ * Works with any resource that declares an `EnvironmentSpec` — Agents,
+ * MCP servers, or future resource types.
+ *
+ * This is a pure function with no side effects — it can be unit-tested
+ * independently of hooks, providers, or API calls.
+ *
+ * @param envSpecData - The resource's `spec.envSpec.data` record.
+ *   Each entry declares a variable the resource needs, with `isSecret`
+ *   and an optional `description`.
+ * @param existingKeys - Keys already present in the user's personal
+ *   environment (or any environment being checked against).
+ * @param poolKeys - Optional additional keys from the session env pool
+ *   (manual secrets, one-time env vars from other agents/MCP servers).
+ *   When provided, variables satisfied by the pool are also excluded
+ *   from the "missing" list.
+ * @returns Variables from `envSpecData` not found in either key set.
+ */
+export function diffEnvSpec(
+  envSpecData: Record<string, { isSecret: boolean; description?: string }>,
+  existingKeys: Set<string>,
+  poolKeys?: Set<string>,
+): EnvVarFormVariable[] {
+  const missing: EnvVarFormVariable[] = [];
+
+  for (const [key, value] of Object.entries(envSpecData)) {
+    if (existingKeys.has(key)) continue;
+    if (poolKeys?.has(key)) continue;
+
+    missing.push({
+      key,
+      isSecret: value.isSecret,
+      ...(value.description && { description: value.description }),
+    });
+  }
+
+  return missing;
+}

package/src/environment/index.ts

@@ -0,0 +1,43 @@
+export { useCreateEnvironment } from "./useCreateEnvironment";
+export type { UseCreateEnvironmentReturn } from "./useCreateEnvironment";
+export { useEnvironment } from "./useEnvironment";
+export type { UseEnvironmentReturn } from "./useEnvironment";
+export { useEnvironmentList } from "./useEnvironmentList";
+export type { UseEnvironmentListReturn } from "./useEnvironmentList";
+export { usePersonalEnvironment } from "./usePersonalEnvironment";
+export type { UsePersonalEnvironmentReturn } from "./usePersonalEnvironment";
+export { useRevealSecretValue } from "./useRevealSecretValue";
+export type {
+  UseRevealSecretValueOptions,
+  UseRevealSecretValueReturn,
+} from "./useRevealSecretValue";
+export { useRemoveEnvironmentVariables } from "./useRemoveEnvironmentVariables";
+export type {
+  RemoveEnvironmentVariablesInput,
+  UseRemoveEnvironmentVariablesReturn,
+} from "./useRemoveEnvironmentVariables";
+export { useUpdateEnvironment } from "./useUpdateEnvironment";
+export type { UseUpdateEnvironmentReturn } from "./useUpdateEnvironment";
+export { useUpdateEnvironmentVariables } from "./useUpdateEnvironmentVariables";
+export type {
+  UpdateEnvironmentVariablesInput,
+  UseUpdateEnvironmentVariablesReturn,
+} from "./useUpdateEnvironmentVariables";
+export { EnvironmentVariableEditor } from "./EnvironmentVariableEditor";
+export type { EnvironmentVariableEditorProps } from "./EnvironmentVariableEditor";
+export { EnvironmentListPanel } from "./EnvironmentListPanel";
+export type { EnvironmentListPanelProps } from "./EnvironmentListPanel";
+export { CreateEnvironmentForm } from "./CreateEnvironmentForm";
+export type { CreateEnvironmentFormProps } from "./CreateEnvironmentForm";
+export { EnvVarForm } from "./EnvVarForm";
+export type {
+  EnvVarFormProps,
+  EnvVarFormVariable,
+  EnvVarFormSubmitOptions,
+} from "./EnvVarForm";
+export { diffEnvSpec } from "./diffEnvSpec";
+export { useSessionEnvPool } from "./useSessionEnvPool";
+export type {
+  SessionEnvPoolInput,
+  UseSessionEnvPoolReturn,
+} from "./useSessionEnvPool";

package/src/environment/useCreateEnvironment.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 UseCreateEnvironmentReturn {
+  readonly create: (input: EnvironmentInput) => Promise<Environment>;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `environment.create()` with loading/error
+ * state.
+ *
+ * Creates an Environment resource — a named collection of
+ * configuration values and secrets. The caller provides an
+ * {@link EnvironmentInput} with `name`, `org`, and optionally
+ * `description` and `data` (key-value pairs).
+ *
+ * Returns the full {@link Environment} proto including
+ * server-generated metadata (id, version, timestamps) so callers
+ * can immediately reference the created resource.
+ *
+ * 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 { create, isCreating, error } = useCreateEnvironment();
+ *
+ * const env = await create({
+ *   name: "prod-credentials",
+ *   org: "acme",
+ *   description: "Production API keys",
+ *   data: {
+ *     API_KEY: { value: "sk-...", isSecret: true },
+ *   },
+ * });
+ * ```
+ */
+export function useCreateEnvironment(): UseCreateEnvironmentReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: EnvironmentInput): Promise<Environment> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.environment.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/environment/useEnvironment.ts

@@ -0,0 +1,89 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import type { ResourceRef } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseEnvironmentReturn {
+  readonly environment: Environment | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single Environment by resource reference.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the reference
+ * fields change, the previous in-flight request is discarded and a
+ * fresh fetch begins. Call `refetch()` to re-query after mutating the
+ * environment through a separate hook or API call.
+ *
+ * Returns the full proto {@link Environment} resource so consumers
+ * have access to metadata, spec (including `data` key-value pairs),
+ * and status without additional calls.
+ *
+ * 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}. For ephemeral per-execution secrets,
+ * see the Execution Flow via {@link useCreateAgentExecution} with
+ * `runtimeEnv`.
+ *
+ * @example
+ * ```tsx
+ * const { environment, isLoading, error } = useEnvironment({
+ *   org: "acme",
+ *   slug: "prod-env",
+ * });
+ * ```
+ */
+export function useEnvironment(
+  ref: ResourceRef | null,
+): UseEnvironmentReturn {
+  const stigmer = useStigmer();
+  const [environment, setEnvironment] = useState<Environment | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  const org = ref?.org;
+  const slug = ref?.slug;
+  const version = ref?.version;
+
+  useEffect(() => {
+    if (!org || !slug) {
+      setEnvironment(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.environment.getByReference({ org, slug, version }).then(
+      (result) => {
+        if (cancelled.current) return;
+        setEnvironment(result);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(toError(err));
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, slug, version, stigmer, fetchKey]);
+
+  return { environment, isLoading, error, refetch };
+}

package/src/environment/useEnvironmentList.ts

@@ -0,0 +1,112 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ListEnvironmentsRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseEnvironmentListReturn {
+  readonly environments: readonly Environment[];
+  readonly totalCount: number;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a paginated list of {@link Environment} entries
+ * for a given organization, with optional label filtering.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op). When the org
+ * or labels change, the previous in-flight request is discarded and a
+ * fresh fetch begins. Call `refetch()` to re-query after mutations.
+ *
+ * Secret values in returned environments are redacted server-side.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**.
+ * For the managed "personal environment" convenience, see
+ * {@link usePersonalEnvironment}.
+ *
+ * @example
+ * ```tsx
+ * const { environments, isLoading } = useEnvironmentList("acme", {
+ *   "stigmer.ai/personal": "true",
+ * });
+ * ```
+ */
+export function useEnvironmentList(
+  org: string | null,
+  labels?: Record<string, string>,
+): UseEnvironmentListReturn {
+  const stigmer = useStigmer();
+  const [environments, setEnvironments] = useState<Environment[]>([]);
+  const [totalCount, setTotalCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(!!org);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  // Synchronously reset loading state when org changes so that
+  // downstream hooks see isLoading=true in the SAME render —
+  // not deferred to the next render via an effect.
+  const [prevOrg, setPrevOrg] = useState(org);
+  if (org !== prevOrg) {
+    setPrevOrg(org);
+    if (org) {
+      setIsLoading(true);
+      setEnvironments([]);
+      setTotalCount(0);
+      setError(null);
+    } else {
+      setIsLoading(false);
+      setEnvironments([]);
+      setTotalCount(0);
+      setError(null);
+    }
+  }
+
+  const labelsRef = useRef(labels);
+  if (
+    labels !== labelsRef.current &&
+    JSON.stringify(labels) !== JSON.stringify(labelsRef.current)
+  ) {
+    labelsRef.current = labels;
+  }
+  const stableLabels = labelsRef.current;
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) return;
+
+    const cancelled = { current: false };
+
+    stigmer.environment
+      .list(
+        create(ListEnvironmentsRequestSchema, {
+          org,
+          labels: stableLabels ?? {},
+        }),
+      )
+      .then(
+        (result) => {
+          if (cancelled.current) return;
+          setEnvironments(result.items);
+          setTotalCount(result.totalCount);
+          setIsLoading(false);
+        },
+        (err) => {
+          if (cancelled.current) return;
+          setError(toError(err));
+          setIsLoading(false);
+        },
+      );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, stableLabels, stigmer, fetchKey]);
+
+  return { environments, totalCount, isLoading, error, refetch };
+}

package/src/environment/usePersonalEnvironment.ts

@@ -0,0 +1,285 @@
+"use client";
+
+import { useCallback, useMemo, useRef, 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,
+  RemoveEnvironmentVariablesRequestSchema,
+} 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 { generateSlugSuffix } from "../internal/slug";
+import { toError } from "../internal/toError";
+import { useEnvironmentList } from "./useEnvironmentList";
+
+const PERSONAL_LABELS: Record<string, string> = {
+  "stigmer.ai/personal": "true",
+};
+
+export interface UsePersonalEnvironmentReturn {
+  /** The caller's personal environment, or `null` if not yet created or still loading. */
+  readonly environment: Environment | null;
+  /** `true` while the initial list query is in-flight. */
+  readonly isLoading: boolean;
+  /** Error message from the most recent failed operation (fetch or mutation), or `null`. */
+  readonly error: Error | null;
+  /** Re-query the personal environment from the server. */
+  readonly refetch: () => void;
+
+  /**
+   * Ensure a personal environment exists for this org.
+   *
+   * If one already exists, returns it immediately without a network call.
+   * Otherwise, creates a new environment with a unique slug and
+   * label `stigmer.ai/personal: "true"`, optionally seeded with initial data.
+   *
+   * **Preconditions:** `org` must be non-null and {@link isLoading} must be
+   * `false`. Calling while `isLoading` is `true` throws — the list query
+   * has not completed, so `getOrCreate` cannot determine whether the
+   * environment already exists and would risk creating a duplicate.
+   *
+   * @param initialData - Key-value pairs to include on creation. Ignored
+   *   if the personal environment already exists. Use {@link addVariables}
+   *   to merge variables into an existing environment.
+   * @returns The personal environment (existing or newly created).
+   * @throws If `org` is null or the environment list is still loading.
+   */
+  readonly getOrCreate: (
+    initialData?: Record<string, EnvVarInput>,
+  ) => Promise<Environment>;
+
+  /**
+   * Add or update variables in the personal environment via server-side merge.
+   *
+   * Only the supplied keys are affected — existing variables not mentioned
+   * are preserved unchanged. Secret values are encrypted server-side.
+   *
+   * Requires the personal environment to exist. Call {@link getOrCreate}
+   * first if it may not.
+   *
+   * @param variables - Variables to add or update.
+   * @returns The updated environment (secrets redacted).
+   */
+  readonly addVariables: (
+    variables: Record<string, EnvVarInput>,
+  ) => Promise<Environment>;
+
+  /**
+   * Remove variables from the personal environment by key.
+   *
+   * Keys that do not exist are silently ignored. Variables not mentioned
+   * are preserved unchanged.
+   *
+   * Requires the personal environment to exist. Call {@link getOrCreate}
+   * first if it may not.
+   *
+   * @param keys - Keys to remove from the environment's data.
+   * @returns The updated environment (secrets redacted).
+   */
+  readonly removeVariables: (keys: string[]) => Promise<Environment>;
+
+  /** `true` while any mutation (`getOrCreate`, `addVariables`, `removeVariables`) is in-flight. */
+  readonly isMutating: boolean;
+}
+
+/**
+ * Layer 2 orchestration hook that manages the caller's personal
+ * {@link Environment} for a given organization.
+ *
+ * Encapsulates the "personal environment" convention: label
+ * (`stigmer.ai/personal: "true"`), unique slug per user, and
+ * the get-or-create lifecycle. Composes {@link useEnvironmentList}
+ * for declarative reading and the SDK client directly for mutations.
+ *
+ * Pass `null` as `org` to skip all operations (stable no-op).
+ *
+ * This is a Layer 2 **Environment Flow** hook. It provides the managed
+ * "personal environment" experience used by the Stigmer Console and
+ * any app that wants automatic credential storage. Callers who manage
+ * environments programmatically should use the Layer 1 building-block
+ * hooks instead:
+ * - {@link useCreateEnvironment} — create any environment
+ * - {@link useUpdateEnvironmentVariables} — incremental variable merge
+ * - {@link useRemoveEnvironmentVariables} — remove variables by key
+ *
+ * @example
+ * ```tsx
+ * // Basic usage — read the personal environment
+ * const { environment, isLoading } = usePersonalEnvironment("acme");
+ *
+ * // Get-or-create with initial data on first use
+ * const { getOrCreate, addVariables, isMutating } =
+ *   usePersonalEnvironment("acme");
+ *
+ * const env = await getOrCreate({
+ *   GITHUB_TOKEN: { value: "ghp_...", isSecret: true },
+ * });
+ *
+ * // Add variables to an existing personal environment
+ * await addVariables({
+ *   SLACK_TOKEN: { value: "xoxb-...", isSecret: true },
+ * });
+ * ```
+ */
+export function usePersonalEnvironment(
+  org: string | null,
+): UsePersonalEnvironmentReturn {
+  const stigmer = useStigmer();
+  const { environments, isLoading, error: listError, refetch } =
+    useEnvironmentList(org, PERSONAL_LABELS);
+
+  const environment = useMemo(
+    () => environments[0] ?? null,
+    [environments],
+  );
+
+  const [isMutating, setIsMutating] = useState(false);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+
+  const environmentRef = useRef(environment);
+  environmentRef.current = environment;
+
+  const isLoadingRef = useRef(isLoading);
+  isLoadingRef.current = isLoading;
+
+  const error = mutationError ?? listError;
+
+  const getOrCreate = useCallback(
+    async (
+      initialData?: Record<string, EnvVarInput>,
+    ): Promise<Environment> => {
+      if (environmentRef.current) return environmentRef.current;
+
+      if (!org) {
+        throw new Error(
+          "usePersonalEnvironment: cannot call getOrCreate when org is null.",
+        );
+      }
+
+      if (isLoadingRef.current) {
+        throw new Error(
+          "usePersonalEnvironment: cannot call getOrCreate while the " +
+            "environment list is loading. Wait for isLoading to become " +
+            "false before calling getOrCreate().",
+        );
+      }
+
+      setIsMutating(true);
+      setMutationError(null);
+
+      try {
+        let data: Record<string, EnvVarInput> | undefined;
+        if (initialData && Object.keys(initialData).length > 0) {
+          data = initialData;
+        }
+
+        const created = await stigmer.environment.create({
+          name: "Personal Environment",
+          slug: `env-personal-${generateSlugSuffix()}`,
+          org,
+          labels: PERSONAL_LABELS,
+          data,
+        });
+
+        refetch();
+        return created;
+      } catch (err) {
+        setMutationError(toError(err));
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [org, stigmer, refetch],
+  );
+
+  const addVariables = useCallback(
+    async (
+      variables: Record<string, EnvVarInput>,
+    ): Promise<Environment> => {
+      const env = environmentRef.current;
+      if (!env) {
+        throw new Error(
+          "usePersonalEnvironment: personal environment does not exist. " +
+            "Call getOrCreate() before addVariables().",
+        );
+      }
+
+      setIsMutating(true);
+      setMutationError(null);
+
+      try {
+        const protoVars = Object.fromEntries(
+          Object.entries(variables).map(([k, v]) => [
+            k,
+            create(EnvironmentValueSchema, {
+              value: v.value,
+              isSecret: v.isSecret,
+              description: v.description,
+            }),
+          ]),
+        );
+
+        const request = create(UpdateEnvironmentVariablesRequestSchema, {
+          environmentId: env.metadata!.id,
+          variables: protoVars,
+        });
+
+        const updated = await stigmer.environment.updateVariables(request);
+        refetch();
+        return updated;
+      } catch (err) {
+        setMutationError(toError(err));
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [stigmer, refetch],
+  );
+
+  const removeVariables = useCallback(
+    async (keys: string[]): Promise<Environment> => {
+      const env = environmentRef.current;
+      if (!env) {
+        throw new Error(
+          "usePersonalEnvironment: personal environment does not exist. " +
+            "Call getOrCreate() before removeVariables().",
+        );
+      }
+
+      setIsMutating(true);
+      setMutationError(null);
+
+      try {
+        const request = create(RemoveEnvironmentVariablesRequestSchema, {
+          environmentId: env.metadata!.id,
+          keys,
+        });
+
+        const updated = await stigmer.environment.removeVariables(request);
+        refetch();
+        return updated;
+      } catch (err) {
+        setMutationError(toError(err));
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [stigmer, refetch],
+  );
+
+  return {
+    environment,
+    isLoading,
+    error,
+    refetch,
+    getOrCreate,
+    addVariables,
+    removeVariables,
+    isMutating,
+  };
+}