feat(connections-setup): add ConnectionsSetup component

[viktormarinho]

Summary

Adds a ConnectionsSetup component — a context-agnostic React component that guides users through installing, authenticating, and configuring a declared set of MCP connections. Designed for onboarding flows (project templates) and marketplace agent installs.

• All slots rendered vertically — no multi-step wizard navigation
• Satisfied slots collapse to a done card with a change button
• Fires onComplete(Record<slotId, connectionId>) when all slots are satisfied

Usage

import { ConnectionsSetup } from "@/web/components/connections-setup";

<ConnectionsSetup
  slots={{
    model: { label: "AI Model", registry: "official", item_id: "openai" },
    email: { label: "Email", registry: "official", item_id: "resend" },
  }}
  onComplete={({ model, email }) => wireToAgent(agentId, { model, email })}
/>

What's included

• slot-resolution.ts — pure phase determination logic (5 unit tests)
• use-slot-resolution.ts — fetches registry item + checks existing connections by metadata.registry_item_id
• use-connection-poller.ts — polls COLLECTION_CONNECTIONS_GET every 2s until status === "active" or 15s timeout
• slot-done.tsx — collapsed done card
• slot-install-form.tsx — install form pre-filled via extractConnectionData
• slot-auth-oauth.tsx — OAuth authorize flow (mirrors connection detail page)
• slot-auth-token.tsx — API token input form
• slot-card.tsx — per-slot state machine: loading → picker/install → polling → auth-oauth/auth-token → done
• connections-setup.tsx — root component
• Two new query keys: KEYS.registryItem, KEYS.connectionPoll

Test plan

• bun test apps/mesh/src/web/components/connections-setup/ — 5 passing
• bun run check — clean
• bun run lint — 0 warnings, 0 errors
• Manual: render with a known registry item, verify install → polling → auth → done flow

🤖 Generated with Claude Code

---

Summary by cubic

Adds a context-agnostic ConnectionsSetup component to install, authenticate (OAuth or token), and verify required MCP connections. Integrates a Quick Setup dialog and ensures fresh auth checks to avoid marking connections as done too early.

• New Features

  • Quick Setup dialog on the org connections page using ConnectionsSetup (OpenRouter, GitHub, Gmail).
  • Per-slot state machine with pure transition helpers and tests; phases: loading → picker/install → polling → auth-oauth/auth-token → done.
  • use-slot-resolution matches by metadata.registry_item_id; use-connection-poller checks status every 2s with a 15s timeout.

• Bug Fixes

  • Always run an auth check after the poller reports active; resolveAuthPhase uses oauth_config + hasOAuthToken or 401+WWW-Authenticate.
  • Auth status query no longer uses staleTime: Infinity, ensuring fresh results after install/auth and preventing premature “done”.
  • onComplete fires once per connection; auth falls back to authCheckId if the entity isn’t fetched; poller resets its timer on connectionId changes.
  • extractConnectionData sets metadata.registry_item_id from appName or server.name (fallback to item.id) for reliable registry matching.

^{Written for commit 5e4a3b6. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Should a new version be published when this PR is merged?

React with an emoji to vote on the release type:

Reaction	Type	Next Version
👍	Prerelease	2.113.2-alpha.1
🎉	Patch	2.113.2
❤️	Minor	2.114.0
🚀	Major	3.0.0

Current version: 2.113.1

Deployment

• Deploy to production (triggers ArgoCD sync after Docker image is published)

[cubic-dev-ai]

5 issues found across 14 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/web/components/connections-setup/use-connection-poller.ts">

<violation number="1" location="apps/mesh/src/web/components/connections-setup/use-connection-poller.ts:25">
P2: Reset the poll start time when the connectionId changes, otherwise a new connection can inherit the previous start time and time out immediately.</violation>
</file>

<file name="apps/mesh/src/web/components/connections-setup/connections-setup.tsx">

<violation number="1" location="apps/mesh/src/web/components/connections-setup/connections-setup.tsx:13">
P2: `handleSlotComplete` derives `next` from a potentially stale `completed` closure. If multiple slot completions happen quickly, later updates can clobber earlier ones and `onComplete` can receive incomplete data. Use the functional `setCompleted` updater to ensure you always merge from the latest state.</violation>
</file>

<file name="apps/mesh/src/web/components/connections-setup/slot-card.tsx">

<violation number="1" location="apps/mesh/src/web/components/connections-setup/slot-card.tsx:36">
P1: Side effect during render: `onComplete()` is called inside the render body. React's rules require render to be pure — calling parent callbacks that trigger state updates elsewhere is a side effect. Move this block into a `useEffect` that reacts to `poller.isActive`.</violation>

<violation number="2" location="apps/mesh/src/web/components/connections-setup/slot-card.tsx:50">
P2: If the poller times out without ever fetching connection data (`poller.connection` is null), `selectedConnection` remains null while the phase transitions to `auth-oauth`/`auth-token`. Both auth component render guards require `selectedConnection && ...`, so neither renders — leaving the user in a stuck state with no way to proceed or retry.</violation>

<violation number="3" location="apps/mesh/src/web/components/connections-setup/slot-card.tsx:54">
P1: Async network request fired during render: `isConnectionAuthenticated(...)` is an async side effect invoked in the render body with no cleanup. This violates React's purity rules for render and risks setting state on an unmounted component. Move this logic into a `useEffect` with a stale/abort guard (e.g., `let cancelled = false` in the effect, checked in `.then()`).</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/web/components/connections-setup/connections-setup.tsx">

<violation number="1" location="apps/mesh/src/web/components/connections-setup/connections-setup.tsx:30">
P2: Calling `onComplete` during render introduces a side effect and can trigger render loops if the callback updates state. Move this into a `useEffect` that runs when `allDone` transitions to true.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Calling onComplete during render introduces a side effect and can trigger render loops if the callback updates state. Move this into a useEffect that runs when allDone transitions to true.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/connections-setup/connections-setup.tsx, line 30:

<comment>Calling `onComplete` during render introduces a side effect and can trigger render loops if the callback updates state. Move this into a `useEffect` that runs when `allDone` transitions to true.</comment>

<file context>
@@ -9,22 +9,31 @@ export interface ConnectionsSetupProps {
+  const allDone =
+    allSlotIds.length > 0 && allSlotIds.every((id) => completed[id]);
+
+  if (allDone && !wasAllDoneRef.current) {
+    wasAllDoneRef.current = true;
+    onComplete(completed);
</file context>

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts">

<violation number="1" location="apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts:78">
P2: `resolveAuthPhase` returns `auth-token` on timeout even when the auth check reports `isAuthenticated: true`, which represents a working connection. This will incorrectly prompt users for token auth after a late but successful auth check. Treat any `isAuthenticated` result as `done` regardless of timeout source.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: resolveAuthPhase returns auth-token on timeout even when the auth check reports isAuthenticated: true, which represents a working connection. This will incorrectly prompt users for token auth after a late but successful auth check. Treat any isAuthenticated result as done regardless of timeout source.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts, line 78:

<comment>`resolveAuthPhase` returns `auth-token` on timeout even when the auth check reports `isAuthenticated: true`, which represents a working connection. This will incorrectly prompt users for token auth after a late but successful auth check. Treat any `isAuthenticated` result as `done` regardless of timeout source.</comment>

<file context>
@@ -48,22 +48,35 @@ export function onPollerTimeout(
+    (!authStatus.isAuthenticated && authStatus.supportsOAuth);
+
+  if (needsOAuth) return "auth-oauth";
+  if (source === "active" && authStatus.isAuthenticated) return "done";
+  return "auth-token";
 }
</file context>

Suggested change

	if (source === "active" && authStatus.isAuthenticated) return "done";
	if (authStatus.isAuthenticated) return "done";