@stigmer/react 3.10.0 → 3.11.1-dev.20260812192248

package/src/mcp-server/__tests__/VendorApprovalBlocked.surfaces.test.tsx

@@ -0,0 +1,321 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { createRouterTransport } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { GetOAuthGrantStatusOutputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import {
+  McpServerSpecSchema,
+  McpServerAuthSchema,
+  HttpServerConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import {
+  McpServerStatusSchema,
+  OAuthStatusSchema,
+  OAuthAppSource,
+  ValidationState,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { VendorApprovalStatus } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { samples } from "../../test/samples";
+import { StigmerContext } from "../../context";
+import { McpServerConnectDialog } from "../McpServerConnectDialog";
+import { McpServerDetailView } from "../McpServerDetailView";
+import { McpServerConfigPanel } from "../McpServerConfigPanel";
+import type { UseMcpServerReturn } from "../useMcpServer";
+
+/**
+ * Pins the oauth_only + vendor-approval-blocked combination across the three
+ * connect surfaces (stigmer/stigmer#412). Before the shared notice, this
+ * state was a silent dead end in the connect dialog (disabled button, no
+ * reason, no way forward) and two surfaces recommended manual token entry on
+ * servers whose endpoint rejects static tokens.
+ */
+
+// happy-dom does not implement the native dialog show/close methods.
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(cleanup);
+
+const ORG = "acme";
+const SLUG = "vendor-crm";
+const DOCS_URL = "https://vendor.example.com/oauth-docs";
+
+/**
+ * An oauth_only vendor-OAuth server whose platform OAuth app is blocked.
+ * `withAppRef` controls the BYOA arm: with a ref and a platform-sourced
+ * effective app, `canBringOwnApp` is true.
+ */
+function buildBlockedOAuthOnlyServer(options: {
+  status: VendorApprovalStatus;
+  withAppRef: boolean;
+}): McpServer {
+  const server = samples.mcpServer({ name: "Vendor CRM", org: ORG, slug: SLUG });
+  server.spec = create(McpServerSpecSchema, {
+    description: "CRM tools over the vendor's hosted MCP endpoint.",
+    serverType: {
+      case: "http",
+      value: create(HttpServerConfigSchema, { url: "https://mcp.vendor.example.com" }),
+    },
+    auth: create(McpServerAuthSchema, {
+      targetEnvVar: "VENDOR_ACCESS_TOKEN",
+      oauthOnly: true,
+      ...(options.withAppRef
+        ? {
+            oauthAppRef: {
+              org: "stigmer",
+              kind: ApiResourceKind.oauth_app,
+              slug: "vendor-oauth",
+            },
+          }
+        : {}),
+    }),
+  });
+  server.status = create(McpServerStatusSchema, {
+    validationState: ValidationState.valid,
+    oauthStatus: create(OAuthStatusSchema, {
+      vendorApprovalStatus: options.status,
+      vendorApprovalDocsUrl: DOCS_URL,
+      effectiveOauthSource: OAuthAppSource.OAUTH_APP_SOURCE_PLATFORM,
+    }),
+  });
+  return server;
+}
+
+function noGrant() {
+  return create(GetOAuthGrantStatusOutputSchema, { connected: false });
+}
+
+function renderWithTransport(
+  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>,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Surface 1: McpServerConnectDialog — the surface that was a silent dead end
+// ---------------------------------------------------------------------------
+
+describe("McpServerConnectDialog — oauth_only + vendor-blocked", () => {
+  function renderDialog(server: McpServer, onOpenDetails?: () => void) {
+    return renderWithTransport(
+      <McpServerConnectDialog
+        org={ORG}
+        slug={SLUG}
+        open
+        onClose={() => {}}
+        onOpenDetails={onOpenDetails}
+      />,
+      (router) => {
+        router.service(McpServerQueryController, {
+          getByReference: () => server,
+          getOAuthGrantStatus: noGrant,
+        });
+      },
+    );
+  }
+
+  it("explains the blocked state instead of showing only a disabled button", async () => {
+    renderDialog(
+      buildBlockedOAuthOnlyServer({
+        status: VendorApprovalStatus.PENDING,
+        withAppRef: true,
+      }),
+    );
+
+    const signIn = await screen.findByRole("button", {
+      name: "Sign in with OAuth",
+    });
+    expect((signIn as HTMLButtonElement).disabled).toBe(true);
+    // The reason is always visible — this was the oss#412 dead end.
+    expect(screen.getByText(/is awaiting vendor approval/)).toBeTruthy();
+  });
+
+  it("never offers manual entry on an oauth_only server", async () => {
+    renderDialog(
+      buildBlockedOAuthOnlyServer({
+        status: VendorApprovalStatus.PENDING,
+        withAppRef: true,
+      }),
+    );
+
+    await screen.findByRole("button", { name: "Sign in with OAuth" });
+    // OAuthRequiredNotice legitimately says tokens are *rejected*; what must
+    // never appear is a recommendation to enter one.
+    expect(screen.queryByText(/enter (a|your) token manually/i)).toBeNull();
+    expect(
+      screen.queryByRole("button", { name: "Enter token manually" }),
+    ).toBeNull();
+  });
+
+  it("routes the BYOA escape hatch to onOpenDetails", async () => {
+    const onOpenDetails = vi.fn();
+    renderDialog(
+      buildBlockedOAuthOnlyServer({
+        status: VendorApprovalStatus.PENDING,
+        withAppRef: true,
+      }),
+      onOpenDetails,
+    );
+
+    fireEvent.click(
+      await screen.findByRole("button", { name: "Use your own OAuth app" }),
+    );
+    expect(onOpenDetails).toHaveBeenCalledTimes(1);
+  });
+
+  it("is honest about rejection and falls back to the docs link without BYOA", async () => {
+    renderDialog(
+      buildBlockedOAuthOnlyServer({
+        status: VendorApprovalStatus.REJECTED,
+        withAppRef: false,
+      }),
+    );
+
+    expect(
+      await screen.findByText(/was not approved by the vendor/),
+    ).toBeTruthy();
+    expect(screen.queryByText(/awaiting vendor approval/)).toBeNull();
+    const docs = screen.getByRole("link", {
+      name: /Learn how to bring your own token/,
+    });
+    expect(docs.getAttribute("href")).toBe(DOCS_URL);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Surface 2: McpServerDetailView — the banner that recommended a dead path
+// ---------------------------------------------------------------------------
+
+describe("McpServerDetailView — oauth_only + vendor-blocked", () => {
+  function loadedState(server: McpServer): UseMcpServerReturn {
+    return {
+      mcpServer: server,
+      isLoading: false,
+      isRefetching: false,
+      error: null,
+      refetch: vi.fn(),
+    };
+  }
+
+  it("offers BYOA without recommending manual entry, and keeps the tour's CTA marker", async () => {
+    renderWithTransport(
+      <McpServerDetailView
+        org={ORG}
+        slug={SLUG}
+        mcpServerState={loadedState(
+          buildBlockedOAuthOnlyServer({
+            status: VendorApprovalStatus.PENDING,
+            withAppRef: true,
+          }),
+        )}
+      />,
+      (router) => {
+        router.service(McpServerQueryController, {
+          getOAuthGrantStatus: noGrant,
+        });
+      },
+    );
+
+    expect(
+      await screen.findByText(
+        "The platform's OAuth app is awaiting vendor approval. You can use your own OAuth app.",
+      ),
+    ).toBeTruthy();
+    // OAuthRequiredNotice legitimately says tokens are *rejected*; what must
+    // never appear is a recommendation to enter one.
+    expect(screen.queryByText(/enter (a|your) token manually/i)).toBeNull();
+    expect(
+      screen.queryByRole("button", { name: "Enter token manually" }),
+    ).toBeNull();
+
+    const cta = screen.getByRole("button", { name: "Use your own OAuth app" });
+    // The byoa-setup docs tour targets this marker; it must survive the
+    // extraction into the shared notice.
+    expect(cta.getAttribute("data-cursor-target")).toBe("byoa-cta-button");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Surface 3: McpServerConfigPanel — the session-setup inline sign-in
+// ---------------------------------------------------------------------------
+
+describe("McpServerConfigPanel — oauth_only + vendor-blocked", () => {
+  function renderPanel(
+    oauthSignInOverrides: Record<string, unknown> = {},
+    panelOverrides: Record<string, unknown> = {},
+  ) {
+    const server = buildBlockedOAuthOnlyServer({
+      status: VendorApprovalStatus.PENDING,
+      withAppRef: true,
+    });
+    return renderWithTransport(
+      <McpServerConfigPanel
+        mcpServer={server}
+        oauthSignIn={{
+          onSignIn: () => {},
+          phase: "idle",
+          isConnected: false,
+          error: null,
+          onClearError: () => {},
+          isVendorApprovalPending: true,
+          isVendorApprovalBlocked: true,
+          vendorApprovalDocsUrl: DOCS_URL,
+          ...oauthSignInOverrides,
+        }}
+        discoveredTools={[]}
+        toolApprovals={[]}
+        enabledTools={[]}
+        onEnabledToolsChange={() => {}}
+        onBack={() => {}}
+        error={null}
+        {...panelOverrides}
+      />,
+    );
+  }
+
+  it("never claims manual entry when the affordance is not wired (oauth_only)", () => {
+    renderPanel();
+    expect(screen.getByText(/is awaiting vendor approval/)).toBeTruthy();
+    expect(screen.queryByText(/manually/)).toBeNull();
+  });
+
+  it("explicit manualEntrySupported=false wins even if a switch handler leaks through", () => {
+    renderPanel(
+      { manualEntrySupported: false },
+      { onSwitchToManual: () => {} },
+    );
+    expect(screen.getByText(/is awaiting vendor approval/)).toBeTruthy();
+    expect(
+      screen.getByText(/OAuth sign-in is temporarily unavailable for this server/),
+    ).toBeTruthy();
+    expect(
+      screen.queryByText(/You can use your own OAuth app or enter a token manually/),
+    ).toBeNull();
+  });
+
+  it("mentions manual entry when the panel actually offers it (legacy fallback)", () => {
+    renderPanel({}, { onSwitchToManual: () => {} });
+    expect(
+      screen.getByText(/You can still connect by entering your own token manually/),
+    ).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { VendorApprovalBlockedNotice } from "../VendorApprovalBlockedNotice";
+
+afterEach(cleanup);
+
+/**
+ * The copy contract for the vendor-approval-blocked state lives here.
+ *
+ * The invariant under test (stigmer/stigmer#412): the notice must never
+ * recommend a path that does not exist. "Enter a token manually" may only
+ * appear when the endpoint accepts static tokens; "use your own OAuth app"
+ * only when BYOA is relevant; and when neither exists the notice must still
+ * explain the state — a disabled button is never the only signal.
+ */
+
+const DOCS_URL = "https://vendor.example.com/oauth-docs";
+
+function renderNotice(
+  overrides: Partial<Parameters<typeof VendorApprovalBlockedNotice>[0]> = {},
+) {
+  return render(
+    <VendorApprovalBlockedNotice
+      blocked
+      pending
+      manualEntrySupported
+      canBringOwnApp={false}
+      docsUrl={null}
+      {...overrides}
+    />,
+  );
+}
+
+describe("VendorApprovalBlockedNotice — self-gating", () => {
+  it("renders nothing when not blocked", () => {
+    const { container } = renderNotice({ blocked: false });
+    expect(container.innerHTML).toBe("");
+  });
+});
+
+describe("VendorApprovalBlockedNotice — status sentence honesty", () => {
+  it("says awaiting approval for a PENDING app", () => {
+    renderNotice({ pending: true });
+    expect(
+      screen.getByText(/is awaiting vendor approval/),
+    ).toBeTruthy();
+  });
+
+  it("says not approved for a REJECTED app — never 'pending'", () => {
+    renderNotice({ pending: false });
+    expect(
+      screen.getByText(/was not approved by the vendor/),
+    ).toBeTruthy();
+    expect(screen.queryByText(/awaiting vendor approval/)).toBeNull();
+    expect(screen.queryByText(/pending/i)).toBeNull();
+  });
+});
+
+describe("VendorApprovalBlockedNotice — alternative-path matrix", () => {
+  it("BYOA + manual: offers both (the copy depicted in the byoa-setup tour, byte-stable)", () => {
+    renderNotice({ canBringOwnApp: true, manualEntrySupported: true });
+    expect(
+      screen.getByText(
+        "The platform's OAuth app is awaiting vendor approval. You can use your own OAuth app or enter a token manually.",
+      ),
+    ).toBeTruthy();
+  });
+
+  it("BYOA + oauth_only: offers BYOA and never mentions manual entry", () => {
+    renderNotice({ canBringOwnApp: true, manualEntrySupported: false });
+    expect(screen.getByText(/You can use your own OAuth app\./)).toBeTruthy();
+    expect(screen.queryByText(/manually/)).toBeNull();
+  });
+
+  it("no BYOA + manual: offers manual entry", () => {
+    renderNotice({ canBringOwnApp: false, manualEntrySupported: true });
+    expect(
+      screen.getByText(/You can still connect by entering your own token manually\./),
+    ).toBeTruthy();
+  });
+
+  it("no BYOA + oauth_only: still explains itself with no false path", () => {
+    renderNotice({ canBringOwnApp: false, manualEntrySupported: false });
+    expect(
+      screen.getByText(/OAuth sign-in is temporarily unavailable for this server\./),
+    ).toBeTruthy();
+    expect(screen.queryByText(/manually/)).toBeNull();
+    expect(screen.queryByText(/your own OAuth app/)).toBeNull();
+  });
+});
+
+describe("VendorApprovalBlockedNotice — affordances", () => {
+  it("renders the BYOA call-to-action and routes clicks", () => {
+    const onBringOwnApp = vi.fn();
+    renderNotice({ canBringOwnApp: true, onBringOwnApp });
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Use your own OAuth app" }),
+    );
+    expect(onBringOwnApp).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits the BYOA call-to-action when no action is wired, keeping the copy", () => {
+    renderNotice({ canBringOwnApp: true });
+    expect(
+      screen.queryByRole("button", { name: "Use your own OAuth app" }),
+    ).toBeNull();
+    expect(screen.getByText(/You can use your own OAuth app/)).toBeTruthy();
+  });
+
+  it("links the docs when BYOA is not offered inline", () => {
+    renderNotice({ canBringOwnApp: false, docsUrl: DOCS_URL });
+    const link = screen.getByRole("link", {
+      name: /Learn how to bring your own token/,
+    });
+    expect(link.getAttribute("href")).toBe(DOCS_URL);
+    expect(link.getAttribute("target")).toBe("_blank");
+  });
+
+  it("suppresses the docs link when the BYOA form (which carries it) is one click away", () => {
+    renderNotice({ canBringOwnApp: true, docsUrl: DOCS_URL, onBringOwnApp: vi.fn() });
+    expect(
+      screen.queryByRole("link", { name: /Learn how to bring your own token/ }),
+    ).toBeNull();
+  });
+
+  it("no-alternative floor: docs link is the way forward when present", () => {
+    renderNotice({
+      canBringOwnApp: false,
+      manualEntrySupported: false,
+      docsUrl: DOCS_URL,
+    });
+    expect(
+      screen.getByRole("link", { name: /Learn how to bring your own token/ }),
+    ).toBeTruthy();
+  });
+});
+
+describe("VendorApprovalBlockedNotice — compact variant", () => {
+  it("carries the same copy contract at the dense size", () => {
+    renderNotice({
+      compact: true,
+      pending: false,
+      canBringOwnApp: true,
+      manualEntrySupported: false,
+      onBringOwnApp: vi.fn(),
+    });
+    expect(screen.getByText(/was not approved by the vendor/)).toBeTruthy();
+    expect(screen.queryByText(/manually/)).toBeNull();
+    expect(
+      screen.getByRole("button", { name: "Use your own OAuth app" }),
+    ).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { createRouterTransport, ConnectError, Code } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import {
+  InitiateOAuthConnectOutputSchema,
+  CompleteOAuthConnectOutputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { StigmerContext } from "../../context";
+import {
+  useMcpServerOAuthConnect,
+  getOAuthConnectErrorMessage,
+} from "../useMcpServerOAuthConnect";
+
+// The popup machinery is window-dependent (window.open, postMessage,
+// BroadcastChannel); tests drive the RPC chain, so replace it with a
+// deterministic callback handshake.
+vi.mock("../../internal/oauthPopup.js", () => ({
+  openOAuthPopup: vi.fn(() => ({ location: { href: "" }, closed: false })),
+  popupBlockedError: vi.fn(
+    () => new Error("Popup was blocked by the browser."),
+  ),
+  waitForOAuthCallback: vi.fn(async () => ({
+    code: "auth-code",
+    state: "state-1",
+  })),
+  closeOAuthPopup: vi.fn(),
+  OAUTH_CALLBACK_MESSAGE_TYPE: "stigmer:oauth:callback",
+  OAUTH_BROADCAST_CHANNEL: "stigmer:oauth:broadcast",
+}));
+
+afterEach(cleanup);
+
+const SERVER_ID = "mcps_01test";
+const ORG = "acme";
+
+function renderOAuthHook(
+  register: Parameters<typeof createRouterTransport>[0],
+) {
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport(register),
+  });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+  );
+  return renderHook(() => useMcpServerOAuthConnect(), { wrapper });
+}
+
+/** initiate + complete succeed — the failure point is chosen per test. */
+function happyOAuthLegs() {
+  return {
+    initiateOAuthConnect: () =>
+      create(InitiateOAuthConnectOutputSchema, {
+        authorizationUrl: "https://vendor.example/authorize",
+        state: "state-1",
+      }),
+    completeOAuthConnect: () =>
+      create(CompleteOAuthConnectOutputSchema, { connected: true }),
+  };
+}
+
+describe("useMcpServerOAuthConnect — failedPhase", () => {
+  it("records 'connecting' when only the chained discovery fails (sign-in succeeded)", async () => {
+    const { result } = renderOAuthHook((router) => {
+      router.service(McpServerCommandController, {
+        ...happyOAuthLegs(),
+        connect: () => {
+          throw new ConnectError("discovery workflow failed", Code.Internal);
+        },
+      });
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.startOAuth(SERVER_ID, ORG),
+      ).rejects.toThrow();
+    });
+
+    expect(result.current.error).toBeTruthy();
+    expect(result.current.failedPhase).toBe("connecting");
+    expect(result.current.phase).toBe("idle");
+  });
+
+  it("records 'completing' when the token exchange itself fails", async () => {
+    const { result } = renderOAuthHook((router) => {
+      router.service(McpServerCommandController, {
+        initiateOAuthConnect: happyOAuthLegs().initiateOAuthConnect,
+        completeOAuthConnect: () => {
+          throw new ConnectError("token exchange failed", Code.Unavailable);
+        },
+      });
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.startOAuth(SERVER_ID, ORG),
+      ).rejects.toThrow();
+    });
+
+    expect(result.current.failedPhase).toBe("completing");
+  });
+
+  it("clears failedPhase on clearError and on a fresh startOAuth", async () => {
+    let failConnect = true;
+    const { result } = renderOAuthHook((router) => {
+      router.service(McpServerCommandController, {
+        ...happyOAuthLegs(),
+        connect: () => {
+          if (failConnect) {
+            throw new ConnectError("discovery workflow failed", Code.Internal);
+          }
+          return {};
+        },
+      });
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.startOAuth(SERVER_ID, ORG),
+      ).rejects.toThrow();
+    });
+    expect(result.current.failedPhase).toBe("connecting");
+
+    act(() => result.current.clearError());
+    expect(result.current.failedPhase).toBeNull();
+    expect(result.current.error).toBeNull();
+
+    failConnect = false;
+    await act(async () => {
+      await result.current.startOAuth(SERVER_ID, ORG);
+    });
+    expect(result.current.failedPhase).toBeNull();
+    expect(result.current.phase).toBe("done");
+  });
+});
+
+describe("getOAuthConnectErrorMessage", () => {
+  it("leads with the sign-in-succeeded fact for discovery-leg failures", () => {
+    const error = new ConnectError("workflow timed out", Code.Internal);
+    expect(getOAuthConnectErrorMessage(error, "connecting")).toBe(
+      "Signed in successfully, but tool discovery failed: workflow timed out",
+    );
+  });
+
+  it("passes other phases through unprefixed", () => {
+    const error = new ConnectError("token exchange failed", Code.Unavailable);
+    expect(getOAuthConnectErrorMessage(error, "completing")).toBe(
+      "token exchange failed",
+    );
+    expect(getOAuthConnectErrorMessage(error, null)).toBe(
+      "token exchange failed",
+    );
+  });
+});

package/src/mcp-server/index.ts

@@ -65,7 +65,10 @@ export type {
 export { useMcpServerConnect } from "./useMcpServerConnect.js";
 export type { UseMcpServerConnectReturn } from "./useMcpServerConnect.js";
 
-export { useMcpServerOAuthConnect } from "./useMcpServerOAuthConnect.js";
+export {
+  useMcpServerOAuthConnect,
+  getOAuthConnectErrorMessage,
+} from "./useMcpServerOAuthConnect.js";
 export type {
   UseMcpServerOAuthConnectReturn,
   OAuthConnectPhase,