@stigmer/react 0.4.8 → 0.5.1

package/src/mcp-server/steps/ReviewStep.tsx

@@ -0,0 +1,297 @@
+"use client";
+
+import { useMemo } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import type { McpServerInput } from "@stigmer/sdk";
+import { serializeMcpServerInputYaml } from "../../library/serialize-resource-yaml";
+import type { McpServerWizardData } from "./types";
+
+/** Props for {@link ReviewStep}. */
+export interface ReviewStepProps {
+  readonly org: string;
+  readonly data: McpServerWizardData;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+}
+
+/**
+ * Wizard step 3: Review and create.
+ *
+ * Shows a summary card with key configuration details and a full
+ * YAML preview of the MCP server that will be created. The "Create"
+ * action is in the WizardNav footer, not in this component.
+ */
+export function ReviewStep({
+  org,
+  data,
+  isCreating,
+  error,
+}: ReviewStepProps) {
+  const mcpServerInput = useMemo(
+    () => buildMcpServerInput(org, data),
+    [org, data],
+  );
+  const yamlPreview = useMemo(
+    () => serializeMcpServerInputYaml(mcpServerInput),
+    [mcpServerInput],
+  );
+
+  const transportSummary =
+    data.transportType === "http"
+      ? data.httpUrl || "(no URL)"
+      : `${data.stdioCommand}${data.stdioArgs ? ` ${data.stdioArgs}` : ""}` || "(no command)";
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h2 className="text-lg font-semibold text-foreground">
+          Review & Create
+        </h2>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Review the MCP server configuration below, then create it.
+        </p>
+      </div>
+
+      {/* Summary card */}
+      <div className="rounded-lg border border-border p-4">
+        <dl className="grid gap-x-6 gap-y-3 text-sm sm:grid-cols-2">
+          <SummaryItem label="Name" value={data.name} />
+          <SummaryItem label="Slug" value={data.slug} mono />
+          <SummaryItem label="Organization" value={org} mono />
+          <SummaryItem
+            label="Visibility"
+            value={data.visibility === "public" ? "Public" : "Private"}
+          />
+          <SummaryItem
+            label="Transport"
+            value={data.transportType === "http" ? "HTTP" : "Stdio"}
+          />
+          <SummaryItem
+            label={data.transportType === "http" ? "URL" : "Command"}
+            value={transportSummary}
+            mono
+          />
+          {data.description && (
+            <SummaryItem
+              label="Description"
+              value={data.description}
+              className="sm:col-span-2"
+            />
+          )}
+          {data.env.length > 0 && (
+            <SummaryItem
+              label="Env Variables"
+              value={`${data.env.length} declared`}
+            />
+          )}
+          {data.authEnabled && data.authOAuthAppSlug && (
+            <SummaryItem
+              label="OAuth"
+              value={
+                data.authOAuthAppOrg
+                  ? `${data.authOAuthAppOrg}/${data.authOAuthAppSlug}`
+                  : data.authOAuthAppSlug
+              }
+              mono
+            />
+          )}
+        </dl>
+      </div>
+
+      {/* YAML preview */}
+      <div className="space-y-2">
+        <h3 className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+          YAML Preview
+        </h3>
+        <div className="max-h-80 overflow-auto rounded-lg border border-border bg-muted-faint">
+          <pre className="p-4 font-mono text-xs leading-relaxed text-foreground">
+            {yamlPreview}
+          </pre>
+        </div>
+      </div>
+
+      {/* Error display */}
+      {error && (
+        <div
+          className="rounded-md border border-destructive bg-muted-faint px-4 py-3"
+          role="alert"
+        >
+          <p className="text-sm font-medium text-destructive">
+            Failed to create MCP server
+          </p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            {getUserMessage(error)}
+          </p>
+        </div>
+      )}
+
+      {/* Creating state */}
+      {isCreating && (
+        <p className="text-sm text-muted-foreground" aria-live="polite">
+          Creating MCP server…
+        </p>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Summary item
+// ---------------------------------------------------------------------------
+
+function SummaryItem({
+  label,
+  value,
+  mono,
+  className,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly mono?: boolean;
+  readonly className?: string;
+}) {
+  return (
+    <div className={className}>
+      <dt className="text-xs text-muted-foreground">{label}</dt>
+      <dd
+        className={cn(
+          "mt-0.5 text-sm text-foreground",
+          mono && "font-mono",
+        )}
+      >
+        {value}
+      </dd>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// buildMcpServerInput
+// ---------------------------------------------------------------------------
+
+/**
+ * Transforms wizard data into the SDK `McpServerInput` shape for submission.
+ * Exported for reuse by `McpServerCreationWizard`.
+ */
+export function buildMcpServerInput(
+  org: string,
+  data: McpServerWizardData,
+): McpServerInput {
+  const input: McpServerInput = {
+    name: data.name.trim(),
+    org,
+    ...(data.slug && { slug: data.slug }),
+    ...(data.description && { description: data.description.trim() }),
+    ...(data.iconUrl && { iconUrl: data.iconUrl.trim() }),
+  };
+
+  if (data.transportType === "http" && data.httpUrl) {
+    const http: McpServerInput["http"] = {
+      url: data.httpUrl.trim(),
+    };
+
+    const headers = buildHeadersMap(data.httpHeaders);
+    if (headers) {
+      http.headers = headers;
+    }
+
+    if (data.httpTimeoutSeconds > 0) {
+      http.timeoutSeconds = data.httpTimeoutSeconds;
+    }
+
+    input.http = http;
+  }
+
+  if (data.transportType === "stdio" && data.stdioCommand) {
+    const stdio: McpServerInput["stdio"] = {
+      command: data.stdioCommand.trim(),
+    };
+
+    const args = parseSpaceSeparated(data.stdioArgs);
+    if (args.length > 0) {
+      stdio.args = args;
+    }
+
+    if (data.stdioWorkingDir.trim()) {
+      stdio.workingDir = data.stdioWorkingDir.trim();
+    }
+
+    input.stdio = stdio;
+  }
+
+  if (data.env.length > 0) {
+    const env: NonNullable<McpServerInput["env"]> = {};
+    for (const entry of data.env) {
+      if (!entry.key) continue;
+      env[entry.key] = {
+        ...(entry.isSecret && { isSecret: true }),
+        ...(entry.description && { description: entry.description }),
+        ...(entry.optional && { optional: true }),
+      };
+    }
+    if (Object.keys(env).length > 0) {
+      input.env = env;
+    }
+  }
+
+  if (data.authEnabled) {
+    const auth: NonNullable<McpServerInput["auth"]> = {};
+
+    if (data.authOAuthAppSlug) {
+      auth.oauthAppRef = {
+        org: data.authOAuthAppOrg,
+        slug: data.authOAuthAppSlug,
+      };
+    }
+    if (data.authTargetEnvVar) {
+      auth.targetEnvVar = data.authTargetEnvVar;
+    }
+    if (data.authTokenLifetimeHint) {
+      auth.tokenLifetimeHint = data.authTokenLifetimeHint;
+    }
+    const scopes = parseCommaSeparated(data.authScopeHints);
+    if (scopes.length > 0) {
+      auth.scopeHints = scopes;
+    }
+    if (data.authDiscoveryUrl) {
+      auth.discoveryUrl = data.authDiscoveryUrl;
+    }
+
+    if (Object.keys(auth).length > 0) {
+      input.auth = auth;
+    }
+  }
+
+  return input;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildHeadersMap(
+  entries: readonly { key: string; value: string }[],
+): Record<string, string> | undefined {
+  const map: Record<string, string> = {};
+  for (const entry of entries) {
+    if (entry.key.trim()) {
+      map[entry.key.trim()] = entry.value;
+    }
+  }
+  return Object.keys(map).length > 0 ? map : undefined;
+}
+
+function parseSpaceSeparated(input: string): string[] {
+  return input
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function parseCommaSeparated(input: string): string[] {
+  return input
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}

package/src/mcp-server/steps/types.ts

@@ -0,0 +1,85 @@
+import type { EnvVarEntry, KeyValueEntry } from "../../resource-creation/types";
+
+export type { EnvVarEntry, KeyValueEntry } from "../../resource-creation/types";
+
+/**
+ * Accumulated form state for the MCP server creation wizard.
+ *
+ * Each field corresponds to a property on `McpServerInput`. The wizard
+ * builds this incrementally across steps, then transforms it into
+ * a `McpServerInput` for submission on the final step.
+ */
+export interface McpServerWizardData {
+  // --- Step 1: Identity & Transport ---
+  /** MCP server display name (required). */
+  readonly name: string;
+  /** URL-friendly slug (auto-derived from name, editable). */
+  readonly slug: string;
+  /** Whether the slug has been manually edited by the user. */
+  readonly slugTouched: boolean;
+  /** Short description (optional). */
+  readonly description: string;
+  /** Icon URL (optional). */
+  readonly iconUrl: string;
+  /** Resource visibility. */
+  readonly visibility: "private" | "public";
+  /** Selected transport type. */
+  readonly transportType: "http" | "stdio";
+  /** HTTP server URL. */
+  readonly httpUrl: string;
+  /** HTTP custom headers. */
+  readonly httpHeaders: KeyValueEntry[];
+  /** HTTP request timeout in seconds (0 = default). */
+  readonly httpTimeoutSeconds: number;
+  /** Stdio command to execute. */
+  readonly stdioCommand: string;
+  /** Stdio command arguments (space-separated string, split on submit). */
+  readonly stdioArgs: string;
+  /** Stdio working directory. */
+  readonly stdioWorkingDir: string;
+
+  // --- Step 2: Environment & Auth ---
+  /** Environment variable declarations. */
+  readonly env: EnvVarEntry[];
+  /** Whether OAuth auth configuration is enabled. */
+  readonly authEnabled: boolean;
+  /** OAuth app reference — organization slug. */
+  readonly authOAuthAppOrg: string;
+  /** OAuth app reference — app slug. */
+  readonly authOAuthAppSlug: string;
+  /** Env var that receives the OAuth token. */
+  readonly authTargetEnvVar: string;
+  /** Token lifetime hint (e.g. "1h", "never"). */
+  readonly authTokenLifetimeHint: string;
+  /** OAuth scope hints (comma-separated, split on submit). */
+  readonly authScopeHints: string;
+  /** OAuth discovery URL. */
+  readonly authDiscoveryUrl: string;
+}
+
+/** Creates the initial empty wizard data. */
+export function createInitialMcpServerWizardData(): McpServerWizardData {
+  return {
+    name: "",
+    slug: "",
+    slugTouched: false,
+    description: "",
+    iconUrl: "",
+    visibility: "private",
+    transportType: "http",
+    httpUrl: "",
+    httpHeaders: [],
+    httpTimeoutSeconds: 0,
+    stdioCommand: "",
+    stdioArgs: "",
+    stdioWorkingDir: "",
+    env: [],
+    authEnabled: false,
+    authOAuthAppOrg: "",
+    authOAuthAppSlug: "",
+    authTargetEnvVar: "",
+    authTokenLifetimeHint: "",
+    authScopeHints: "",
+    authDiscoveryUrl: "",
+  };
+}

package/src/mcp-server/useCreateMcpServer.ts

@@ -0,0 +1,76 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { McpServerInput } from "@stigmer/sdk";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreateMcpServer}. */
+export interface UseCreateMcpServerReturn {
+  /**
+   * Submit a {@link McpServerInput} to create (or upsert) an MCP server blueprint.
+   *
+   * Uses `stigmer.mcpServer.apply()` — the idempotent upsert operation.
+   * Resolves with the server-created/updated `McpServer` proto including
+   * populated metadata (id, slug, audit timestamps).
+   */
+  readonly create: (input: McpServerInput) => Promise<McpServer>;
+  /** `true` while the apply request is in flight. */
+  readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `mcpServer.apply()` with loading and error state.
+ *
+ * Creates an MCP server blueprint from a {@link McpServerInput}. Uses
+ * `apply()` (upsert) rather than `create()` so re-submissions are
+ * idempotent — matching the CLI's `stigmer apply` semantics.
+ *
+ * Follows the established SDK mutation hook pattern: `isCreating` flag,
+ * `error` state, `clearError` reset, result returned from the promise
+ * (not stored in hook state).
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error, clearError } = useCreateMcpServer();
+ *
+ * const server = await create({
+ *   name: "github",
+ *   org: "acme",
+ *   http: { url: "https://mcp.github.com/sse" },
+ *   env: { GITHUB_TOKEN: { isSecret: true, description: "GitHub PAT" } },
+ * });
+ * // server.metadata?.slug → "github"
+ * ```
+ */
+export function useCreateMcpServer(): UseCreateMcpServerReturn {
+  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: McpServerInput): Promise<McpServer> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.mcpServer.apply(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/mcp-server/useUpdateMcpServer.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServerInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useUpdateMcpServer}. */
+export interface UseUpdateMcpServerReturn {
+  /** Update an existing MCP server with a full input. Returns the updated resource. */
+  readonly update: (input: McpServerInput) => Promise<McpServer>;
+  /** `true` while the update RPC is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Clear the error state. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that updates an existing MCP Server resource.
+ *
+ * Wraps `stigmer.mcpServer.update(input)` with loading and error state.
+ * The caller must provide a **complete** `McpServerInput` — the backend
+ * performs full spec replacement. Use `mcpServerToInput()` to reconstruct
+ * the input from a fetched server, modify the desired field, and pass
+ * the result here.
+ */
+export function useUpdateMcpServer(): UseUpdateMcpServerReturn {
+  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: McpServerInput): Promise<McpServer> => {
+      setIsUpdating(true);
+      setError(null);
+
+      try {
+        return await stigmer.mcpServer.update(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { update, isUpdating, error, clearError };
+}

package/src/models/ModelRegistryContext.ts

@@ -8,6 +8,8 @@ export interface ModelRegistryState {
   readonly models: readonly ModelInfo[];
   readonly isLoading: boolean;
   readonly error: Error | null;
+  /** Retry fetching the model registry. No-op while a fetch is in flight. */
+  readonly refetch: () => void;
 }
 
 /**
@@ -21,6 +23,7 @@ export const ModelRegistryContext = createContext<ModelRegistryState>({
   models: [],
   isLoading: true,
   error: null,
+  refetch: () => {},
 });
 
 /**

package/src/models/ModelSelector.tsx

@@ -119,7 +119,7 @@ export function ModelSelector({
     }
   }, [initialHarness, isHarnessLocked]);
 
-  const { models, featured, defaultModel, getModel, byProvider } = useModelRegistry(
+  const { models, featured, defaultModel, getModel, byProvider, isLoading, error, refetch } = useModelRegistry(
     { harness: activeHarness },
   );
 
@@ -393,7 +393,30 @@ export function ModelSelector({
               aria-label="Available models"
               className="max-h-72 overflow-y-auto p-1"
             >
-              {visibleModels.length === 0 && (
+              {visibleModels.length === 0 && isLoading && (
+                <div className="flex items-center justify-center gap-2 px-2 py-3">
+                  <div className="size-3 animate-spin rounded-full border border-muted border-t-primary" />
+                  <span className="text-xs text-muted-foreground">Loading models…</span>
+                </div>
+              )}
+
+              {visibleModels.length === 0 && !isLoading && error != null && (
+                <div className="flex flex-col items-center gap-1.5 px-2 py-3">
+                  <span className="text-xs text-muted-foreground">Failed to load models</span>
+                  <button
+                    type="button"
+                    className={cn(
+                      "rounded-md border border-border bg-background px-2.5 py-1 text-xs text-foreground",
+                      "hover:bg-accent-hover transition-colors cursor-pointer",
+                    )}
+                    onClick={refetch}
+                  >
+                    Retry
+                  </button>
+                </div>
+              )}
+
+              {visibleModels.length === 0 && !isLoading && error == null && (
                 <div className="px-2 py-3 text-center text-xs text-muted-foreground">
                   No models found
                 </div>

package/src/models/__tests__/useModelRegistry.test.tsx

@@ -90,8 +90,10 @@ const TEST_REGISTRY_JSON = {
 
 const TEST_MODELS: readonly ModelInfo[] = parseRegistryJson(TEST_REGISTRY_JSON);
 
+const noopRefetch = () => {};
+
 function createWrapper(models: readonly ModelInfo[] = TEST_MODELS) {
-  const state: ModelRegistryState = { models, isLoading: false, error: null };
+  const state: ModelRegistryState = { models, isLoading: false, error: null, refetch: noopRefetch };
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
       <ModelRegistryContext.Provider value={state}>
@@ -285,7 +287,7 @@ describe("useModelRegistry", () => {
 
   describe("loading state", () => {
     it("exposes isLoading from context", () => {
-      const loadingState: ModelRegistryState = { models: [], isLoading: true, error: null };
+      const loadingState: ModelRegistryState = { models: [], isLoading: true, error: null, refetch: noopRefetch };
       const wrapper = ({ children }: { children: ReactNode }) => (
         <ModelRegistryContext.Provider value={loadingState}>
           {children}
@@ -298,7 +300,7 @@ describe("useModelRegistry", () => {
 
     it("exposes error from context", () => {
       const err = new Error("fetch failed");
-      const errorState: ModelRegistryState = { models: [], isLoading: false, error: err };
+      const errorState: ModelRegistryState = { models: [], isLoading: false, error: err, refetch: noopRefetch };
       const wrapper = ({ children }: { children: ReactNode }) => (
         <ModelRegistryContext.Provider value={errorState}>
           {children}

package/src/models/useModelRegistry.ts

@@ -55,6 +55,8 @@ export interface UseModelRegistryReturn {
   readonly isLoading: boolean;
   /** Non-null if the API fetch failed. Models will be empty in this case. */
   readonly error: Error | null;
+  /** Retry fetching the model registry. No-op while a fetch is in flight. */
+  readonly refetch: () => void;
 }
 
 /**
@@ -85,7 +87,7 @@ export interface UseModelRegistryReturn {
  */
 export function useModelRegistry(options?: UseModelRegistryOptions): UseModelRegistryReturn {
   const harness = options?.harness;
-  const { models: allModels, isLoading, error } = useModelRegistryContext();
+  const { models: allModels, isLoading, error, refetch } = useModelRegistryContext();
 
   return useMemo(() => {
     const isUnified = harness === undefined;
@@ -143,6 +145,7 @@ export function useModelRegistry(options?: UseModelRegistryOptions): UseModelReg
       getByKey: (key: string) => byCompoundKey.get(key),
       isLoading,
       error,
+      refetch,
     };
-  }, [harness, allModels, isLoading, error]);
+  }, [harness, allModels, isLoading, error, refetch]);
 }