@stigmer/react 3.4.0 → 3.4.1

package/src/mcp-server/__tests__/McpServerDetailView.test.tsx

@@ -0,0 +1,345 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { createRouterTransport, ConnectError, Code } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import {
+  McpServerSpecSchema,
+  HttpServerConfigSchema,
+  ToolApprovalPolicySchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import {
+  McpServerStatusSchema,
+  DiscoveredCapabilitiesSchema,
+  DiscoveredToolSchema,
+  ValidationState,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { samples } from "../../test/samples";
+import { StigmerContext } from "../../context";
+import { McpServerDetailView } from "../McpServerDetailView";
+import type { UseMcpServerReturn } from "../useMcpServer";
+
+// The kebab menu and dialogs portal their content; without a StigmerProvider
+// the portal container is null — pin it to document.body like sibling tests.
+vi.mock("../../portal-container", () => ({
+  useStigmerPortalContainer: () => document.body,
+}));
+
+beforeAll(() => {
+  // happy-dom lacks ResizeObserver, which Base UI positioners observe.
+  if (!("ResizeObserver" in globalThis)) {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      };
+  }
+});
+
+afterEach(cleanup);
+
+const ORG = "acme";
+const SLUG = "order-management-api";
+
+/** Frozen discovery instant — fixtures must never read the real clock. */
+const DISCOVERED_AT = new Date("2026-07-20T09:30:00Z");
+
+/** The server as registered: HTTP transport, one secret env var, no tools. */
+function buildBaseServer(): McpServer {
+  const server = samples.mcpServer({ name: "Order Management API", org: ORG, slug: SLUG });
+  server.spec = create(McpServerSpecSchema, {
+    description: "REST API for order lookup, inventory, and return processing.",
+    serverType: {
+      case: "http",
+      value: create(HttpServerConfigSchema, { url: "https://api.acme.com/mcp" }),
+    },
+    env: {
+      API_TOKEN: create(EnvVarDeclarationSchema, {
+        isSecret: true,
+        description: "Bearer token for the Order Management API",
+      }),
+    },
+  });
+  return server;
+}
+
+/** The same server after Connect: 3 discovered tools, 1 classified policy. */
+function buildConnectedServer(): McpServer {
+  const server = buildBaseServer();
+  server.status = create(McpServerStatusSchema, {
+    validationState: ValidationState.valid,
+    discoveredCapabilities: create(DiscoveredCapabilitiesSchema, {
+      lastDiscoveredAt: timestampFromDate(DISCOVERED_AT),
+      tools: [
+        create(DiscoveredToolSchema, { name: "get_order", description: "Retrieve one order by ID." }),
+        create(DiscoveredToolSchema, { name: "list_orders", description: "List recent orders." }),
+        create(DiscoveredToolSchema, { name: "process_return", description: "Initiate a return and refund." }),
+      ],
+    }),
+    toolApprovals: [
+      create(ToolApprovalPolicySchema, {
+        toolName: "process_return",
+        message: "Process return for order '{{args.order_id}}'",
+      }),
+    ],
+  });
+  return server;
+}
+
+/** Hoisted-state bag in its settled, data-loaded shape. */
+function loadedState(server: McpServer): UseMcpServerReturn {
+  return { mcpServer: server, isLoading: false, isRefetching: false, error: null, refetch: vi.fn() };
+}
+
+/**
+ * Mounts the view against a real Connect router transport. RPCs the test
+ * does not register fall through to Connect's `unimplemented`, which the
+ * SDK hooks degrade from — the same contract the tours rely on.
+ */
+function renderView(
+  ui: ReactNode,
+  register: Parameters<typeof createRouterTransport>[0] = () => {},
+) {
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport(register),
+  });
+  return render(
+    <StigmerContext.Provider value={client}>{ui}</StigmerContext.Provider>,
+  );
+}
+
+describe("McpServerDetailView — hoisted mcpServerState", () => {
+  it("renders from injected state without issuing getByReference", async () => {
+    const getByReference = vi.fn(() => {
+      throw new ConnectError("must not fetch", Code.FailedPrecondition);
+    });
+
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildBaseServer())}
+      />,
+      (router) => {
+        router.service(McpServerQueryController, { getByReference });
+      },
+    );
+
+    // Content is on screen synchronously — no skeleton frame first.
+    expect(
+      screen.getByRole("heading", { name: "Order Management API" }),
+    ).toBeTruthy();
+    expect(screen.queryByLabelText("Loading MCP server details")).toBeNull();
+
+    // Let pending microtasks (credentials/permission fetches) settle, then
+    // confirm the resource fetch never fired.
+    await screen.findByRole("tab", { name: /Tools/ });
+    expect(getByReference).not.toHaveBeenCalled();
+  });
+
+  it("shows the loading skeleton while the injected state is loading", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={{
+          mcpServer: null,
+          isLoading: true,
+          isRefetching: false,
+          error: null,
+          refetch: vi.fn(),
+        }}
+      />,
+    );
+    expect(screen.getByLabelText("Loading MCP server details")).toBeTruthy();
+    // A loading owner must never read as a missing resource.
+    expect(screen.queryByText("MCP Server not found")).toBeNull();
+  });
+
+  it("routes the error state's Retry to the injected refetch", () => {
+    const refetch = vi.fn();
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={{
+          mcpServer: null,
+          isLoading: false,
+          isRefetching: false,
+          error: new ConnectError("backend down", Code.Unavailable),
+          refetch,
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /retry/i }));
+    expect(refetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders not-found when the injected state settles with no resource", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={{
+          mcpServer: null,
+          isLoading: false,
+          isRefetching: false,
+          error: null,
+          refetch: vi.fn(),
+        }}
+      />,
+    );
+    expect(screen.getByText("MCP Server not found")).toBeTruthy();
+  });
+});
+
+describe("McpServerDetailView — self-fetching mode (unchanged behaviour)", () => {
+  it("fetches by org/slug and renders the resolved server", async () => {
+    const getByReference = vi.fn(() => buildBaseServer());
+    renderView(<McpServerDetailView org={ORG} slug={SLUG} />, (router) => {
+      router.service(McpServerQueryController, { getByReference });
+    });
+
+    // First paint is the skeleton; content follows the fetch.
+    expect(screen.getByLabelText("Loading MCP server details")).toBeTruthy();
+    expect(
+      await screen.findByRole("heading", { name: "Order Management API" }),
+    ).toBeTruthy();
+    expect(getByReference).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders not-found when the fetch 404s", async () => {
+    renderView(<McpServerDetailView org={ORG} slug={SLUG} />, (router) => {
+      router.service(McpServerQueryController, {
+        getByReference: () => {
+          throw new ConnectError("no such server", Code.NotFound);
+        },
+      });
+    });
+    expect(await screen.findByText("MCP Server not found")).toBeTruthy();
+  });
+});
+
+describe("McpServerDetailView — connect bar and capability tabs", () => {
+  it("offers Connect with the not-connected status before discovery", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildBaseServer())}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /^Connect$/ })).toBeTruthy();
+    expect(screen.getByText("Not connected yet")).toBeTruthy();
+    expect(
+      screen.getByText("Connect to this MCP server to discover its available tools."),
+    ).toBeTruthy();
+  });
+
+  it("offers Reconnect with the connected status and discovery date after discovery", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildConnectedServer())}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /Reconnect/ })).toBeTruthy();
+    expect(screen.getByText("Connected")).toBeTruthy();
+    expect(screen.getByText("Valid")).toBeTruthy();
+    expect(screen.getByText(/Discovered/)).toBeTruthy();
+  });
+
+  it("lists the discovered tools with the count badge", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildConnectedServer())}
+      />,
+    );
+    const toolsTab = screen.getByRole("tab", { name: /Tools/ });
+    expect(toolsTab.textContent).toContain("3");
+    expect(screen.getByText("get_order")).toBeTruthy();
+    expect(screen.getByText("list_orders")).toBeTruthy();
+    expect(screen.getByText("process_return")).toBeTruthy();
+  });
+
+  it("groups the classified policy under Auto-classified with a badge of 1, not 3", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        defaultCapabilityTab="policies"
+        mcpServerState={loadedState(buildConnectedServer())}
+      />,
+    );
+    const policiesTab = screen.getByRole("tab", { name: /Policies/ });
+    expect(policiesTab.textContent).toContain("1");
+    expect(policiesTab.textContent).not.toContain("3");
+
+    const panel = screen.getByRole("tabpanel");
+    expect(within(panel).getByText(/Auto-classified/)).toBeTruthy();
+    expect(within(panel).getByText("process_return")).toBeTruthy();
+    expect(within(panel).getByText("requires approval")).toBeTruthy();
+  });
+});
+
+describe("McpServerDetailView — tour scroll anchors", () => {
+  it("marks the Connection and Capabilities sections as scroll targets", () => {
+    const { container } = renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildBaseServer())}
+      />,
+    );
+    expect(
+      container.querySelector('[data-scroll-target="mcp-connection"]'),
+    ).toBeTruthy();
+    expect(
+      container.querySelector('[data-scroll-target="mcp-capabilities"]'),
+    ).toBeTruthy();
+  });
+});
+
+describe("McpServerDetailView — credential form gating", () => {
+  it("opens the credential form for the declared missing variable when asked", async () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        defaultShowCredentialForm
+        mcpServerState={loadedState(buildBaseServer())}
+      />,
+    );
+    expect(await screen.findByText("Credentials Required")).toBeTruthy();
+    // Scope to the credential form — the Environment section also lists
+    // API_TOKEN as a declaration.
+    const form = screen.getByRole("form", {
+      name: /Configure Credentials Required/i,
+    });
+    // Anchored: the secret input's reveal button is labelled "Show API_TOKEN".
+    expect(within(form).getByLabelText(/^API_TOKEN/)).toBeTruthy();
+  });
+
+  it("keeps the form closed by default", () => {
+    renderView(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(buildBaseServer())}
+      />,
+    );
+    expect(screen.queryByText("Credentials Required")).toBeNull();
+  });
+});

package/src/mcp-server/index.ts

@@ -100,4 +100,17 @@ export type {
   McpServerCreationResult,
 } from "./McpServerCreationWizard.js";
 
+// Individual wizard steps are exported as presentational building blocks:
+// they are fully prop-driven (data, validationError, error, isCreating),
+// which lets platform builders and guided tours/demos render any wizard
+// state — including validation and submit failures — deterministically,
+// without driving the stateful McpServerCreationWizard through user events.
+export { IdentityTransportStep } from "./steps/IdentityTransportStep.js";
+export type { IdentityTransportStepProps } from "./steps/IdentityTransportStep.js";
+export { EnvironmentAuthStep } from "./steps/EnvironmentAuthStep.js";
+export type { EnvironmentAuthStepProps } from "./steps/EnvironmentAuthStep.js";
+export { ReviewStep } from "./steps/ReviewStep.js";
+export type { ReviewStepProps } from "./steps/ReviewStep.js";
+
+export { createInitialMcpServerWizardData } from "./steps/types.js";
 export type { McpServerWizardData } from "./steps/types.js";

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

@@ -16,6 +16,10 @@ export interface EnvironmentAuthStepProps {
  * Both sections are optional. Env vars start expanded if any exist;
  * auth starts collapsed unless already enabled. No validation gate —
  * the user can proceed with zero configuration.
+ *
+ * Fully presentational: form state lives in the `data` prop and edits
+ * flow out through `updateData`, so standalone consumers (embedded
+ * builders, guided tours) can render any configuration state from props.
  */
 export function EnvironmentAuthStep({
   data,

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

@@ -23,6 +23,12 @@ const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
  *
  * Transport type uses a radio group (mutually exclusive modes).
  * Conditional fields render based on the selected transport.
+ *
+ * Fully presentational: state lives in the `data` prop and every edit
+ * flows out through `updateData`. Inside `McpServerCreationWizard` that
+ * state comes from `useWizardState`; standalone consumers (embedded
+ * builders, guided tours) can render any form state — including a
+ * `validationError` — deterministically from props.
  */
 export function IdentityTransportStep({
   data,
@@ -195,7 +201,9 @@ export function IdentityTransportStep({
         </fieldset>
       </div>
 
-      <fieldset className="space-y-3">
+      {/* data-scroll-target: guided tours/demos scroll the transport config
+          (the step's decision point) into view within the wizard's scroll area. */}
+      <fieldset className="space-y-3" data-scroll-target="mcp-transport">
         <legend className="text-sm font-medium text-foreground">
           Transport <span className="text-destructive">*</span>
         </legend>

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { cn } from "@stigmer/theme";
 import { buildMcpServerProto, getUserMessage, serializeManifest } from "@stigmer/sdk";
 import type { McpServerInput } from "@stigmer/sdk";
@@ -20,6 +20,11 @@ export interface ReviewStepProps {
  * 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.
+ *
+ * Fully presentational: renders entirely from props, including the
+ * `isCreating` in-flight state and a submit `error`. Standalone
+ * consumers (embedded builders, guided tours) can therefore depict
+ * any review state — success preview or failure — deterministically.
  */
 export function ReviewStep({
   org,
@@ -27,6 +32,17 @@ export function ReviewStep({
   isCreating,
   error,
 }: ReviewStepProps) {
+  const errorRef = useRef<HTMLDivElement>(null);
+
+  // The error panel renders below the (tall) YAML preview inside the wizard's
+  // internal scroll area, so a failed create could otherwise report itself
+  // out of view. Bring it into view whenever a new error arrives.
+  useEffect(() => {
+    if (error) {
+      errorRef.current?.scrollIntoView({ block: "nearest" });
+    }
+  }, [error]);
+
   const mcpServerInput = useMemo(
     () => buildMcpServerInput(org, data),
     [org, data],
@@ -113,6 +129,7 @@ export function ReviewStep({
       {/* Error display */}
       {error && (
         <div
+          ref={errorRef}
           className="rounded-md border border-destructive bg-muted-faint px-4 py-3"
           role="alert"
         >

package/src/mcp-server/useMcpServerCount.ts

@@ -17,6 +17,8 @@ export interface UseMcpServerCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useMcpServerCount}. */

package/src/resource-creation/CreationPicker.tsx

@@ -140,6 +140,7 @@ export function CreationPicker<TData>({
           description={`Create a blank ${resourceLabel} and configure it step by step.`}
           icon={<BlankPageIcon />}
           onClick={() => onSelect({ kind: "scratch" })}
+          cursorTarget="creation-path-scratch"
         />
 
         {/* Browse templates */}
@@ -150,6 +151,7 @@ export function CreationPicker<TData>({
             icon={<GridIcon />}
             onClick={() => setView("gallery")}
             badge={`${templates.length} available`}
+            cursorTarget="creation-path-template"
           />
         )}
 
@@ -159,6 +161,7 @@ export function CreationPicker<TData>({
           description="Upload a YAML or JSON configuration file."
           icon={<UploadIcon />}
           onClick={() => onSelect({ kind: "import" })}
+          cursorTarget="creation-path-import"
         />
       </div>
     </div>
@@ -175,17 +178,21 @@ function OptionCard({
   icon,
   onClick,
   badge,
+  cursorTarget,
 }: {
   readonly title: string;
   readonly description: string;
   readonly icon: React.ReactNode;
   readonly onClick: () => void;
   readonly badge?: string;
+  /** `data-cursor-target` hook for guided tours and demo playbacks. */
+  readonly cursorTarget?: string;
 }) {
   return (
     <button
       type="button"
       onClick={onClick}
+      data-cursor-target={cursorTarget}
       className={cn(
         "group flex flex-col items-center gap-3 rounded-lg border border-border bg-card p-6 text-center",
         "transition-colors hover:border-primary hover:bg-accent",

package/src/resource-creation/WizardNav.tsx

@@ -90,6 +90,7 @@ export function WizardNav({
           type="button"
           onClick={onNext}
           disabled={nextDisabled || isSubmitting}
+          data-cursor-target="wizard-next"
           className={cn(
             "inline-flex items-center gap-1.5 rounded-md bg-primary px-4 py-1.5 text-sm font-medium text-primary-foreground transition-colors",
             "hover:bg-primary-hover",

package/src/resource-detail/Section.tsx

@@ -9,6 +9,13 @@ export interface SectionProps {
   /** Arbitrary action elements rendered in the header row (e.g. expand, share). */
   readonly headerActions?: ReactNode;
   readonly onEdit?: () => void;
+  /**
+   * Stable id emitted as `data-scroll-target` on the section element, so
+   * guided tours and demos can scroll the section into view by name (the
+   * same convention as `data-cursor-target`). Purely an annotation — no
+   * behavior attaches to it here.
+   */
+  readonly scrollTarget?: string;
   readonly children: ReactNode;
   readonly className?: string;
 }
@@ -26,11 +33,12 @@ export function Section({
   count,
   headerActions,
   onEdit,
+  scrollTarget,
   children,
   className,
 }: SectionProps) {
   return (
-    <section className={className}>
+    <section className={className} data-scroll-target={scrollTarget}>
       <div className="mb-2 flex items-center gap-2">
         <h3 className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
           {title}

package/src/resource-workbench/components/ResourceWorkbench.tsx

@@ -112,6 +112,17 @@ export interface ResourceWorkbenchProps<TData = SearchResult> {
   /** Extracts a unique ID from an item (for selection tracking). */
   readonly getItemId?: (item: TData) => string;
 
+  // --- Refresh -----------------------------------------------------------
+
+  /**
+   * Opaque token that forces a background refetch of the list whenever
+   * its value changes — the current view stays rendered with a refetch
+   * shimmer (no remount flash), and pagination and sort are preserved.
+   * Bump it after an out-of-band mutation (applying a manifest, deleting
+   * a row) so the change appears without a reload.
+   */
+  readonly refetchToken?: unknown;
+
   // --- Empty & error states ----------------------------------------------
 
   /** Icon for the empty state. */
@@ -210,6 +221,7 @@ export function ResourceWorkbench<TData = SearchResult>({
   onStateChange,
   enableSelection = false,
   getItemId = defaultGetId as (item: TData) => string,
+  refetchToken,
   emptyIcon,
   emptyTitle = "No resources found",
   emptyDescription = "Try adjusting your search or filters.",
@@ -255,6 +267,7 @@ export function ResourceWorkbench<TData = SearchResult>({
     onSortChange: filtersHook.setSort,
     columns: columns as WorkbenchColumnDef<TData>[],
     enableSelection,
+    refetchToken,
   });
 
   // --- Selection ---------------------------------------------------------

package/src/resource-workbench/hooks/useResourceCollection.ts

@@ -57,6 +57,15 @@ export interface UseResourceCollectionOptions<TData = SearchResult> {
   readonly columns?: readonly WorkbenchColumnDef<TData>[];
   /** Enable row selection state tracking. @default false */
   readonly enableSelection?: boolean;
+  /**
+   * Opaque token that forces a background refetch whenever its value
+   * changes. Use it to re-read the list after an out-of-band mutation
+   * (e.g. applying a manifest or deleting a row) without remounting:
+   * bump a counter and pass it here. The current page stays rendered
+   * with an `isRefetching` shimmer — no full-list flash. A change to
+   * this token alone never resets pagination or sort.
+   */
+  readonly refetchToken?: unknown;
 }
 
 // ---------------------------------------------------------------------------
@@ -148,6 +157,7 @@ export function useResourceCollection<TData = SearchResult>(
     onSortChange,
     columns = [],
     enableSelection = false,
+    refetchToken,
   } = options;
 
   // --- Data fetching via useFetch -----------------------------------------
@@ -169,7 +179,7 @@ export function useResourceCollection<TData = SearchResult>(
           };
         }
       : null,
-    [listFn, org, query, scope, page, pageSize],
+    [listFn, org, query, scope, page, pageSize, refetchToken],
     INITIAL_DATA,
   );
 

package/src/search/useResourceCount.ts

@@ -16,6 +16,13 @@ export interface UseResourceCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /**
+   * Opaque token that forces a recount whenever its value changes. Use
+   * it to refresh the count after an out-of-band mutation (e.g. applying
+   * a manifest) without remounting. Mirrors the `refetchToken` on
+   * {@link useResourceCollection}.
+   */
+  readonly refetchToken?: unknown;
 }
 
 export interface UseResourceCountReturn {
@@ -52,6 +59,7 @@ export function useResourceCount(
 ): UseResourceCountReturn {
   const query = options?.query;
   const scope = options?.scope ?? "org";
+  const refetchToken = options?.refetchToken;
 
   const { data: count, isLoading, isRefetching, error, refetch } = useFetch<number | undefined>(
     org
@@ -66,7 +74,7 @@ export function useResourceCount(
           return result.totalCount;
         }
       : null,
-    [listFn, org, query, scope],
+    [listFn, org, query, scope, refetchToken],
     undefined,
   );