Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(onboarding): granular ff controls for connectors (#5221)

teoc47f5986d1ab
diff --git a/apps/web/src/features/setup/flow/OnboardingFlow.tsx b/apps/web/src/features/setup/flow/OnboardingFlow.tsx
index 641829ce68..cfea1276fc 100644
--- a/apps/web/src/features/setup/flow/OnboardingFlow.tsx
+++ b/apps/web/src/features/setup/flow/OnboardingFlow.tsx
@@ -1,4 +1,5 @@
import { useAnalytics } from '@app/lib/analytics/analytics-context';
+import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { FEATURED_MCP_SERVERS } from '@core/component/AI/constant/mcpServers';
import LogoIcon from '@icon/macro-logo.svg';
import { authKeys } from '@queries/auth/keys';
@@ -26,6 +27,12 @@ import { BuildingStep } from './BuildingStep';
import { ConnectorStep } from './ConnectorStep';
import { createFlowFinish } from './createFlowFinish';
import { EmailStep } from './EmailStep';
+import {
+ ONBOARDING_CONNECTORS_FEATURE_FLAG,
+ type OnboardingConnectorServerName,
+ resolveOnboardingConnectorNames,
+ resolveOnboardingStepIndex,
+} from './onboardingConnectorConfig';
import { PlanStep } from './PlanStep';
import { SummaryStep } from './SummaryStep';
import {
@@ -110,12 +117,10 @@ const CONNECTOR_COPY: Record<string, ConnectorStepCopy> = {
},
};
-/** Connector steps, in spec order, dropping tools absent from this build
- * (Slack is dev-only in production FEATURED_MCP_SERVERS). */
-const CONNECTOR_STEP_NAMES = ['Linear', 'Notion', 'Slack', 'GitHub'];
-
-function buildSteps(): StepDef[] {
- const connectorSteps: StepDef[] = CONNECTOR_STEP_NAMES.flatMap((name) => {
+function buildSteps(
+ connectorNames: readonly OnboardingConnectorServerName[]
+): StepDef[] {
+ const connectorSteps: StepDef[] = connectorNames.flatMap((name) => {
const server = FEATURED_MCP_SERVERS.find(
(candidate) => candidate.server_name === name
);
@@ -231,10 +236,23 @@ function FlowContent() {
const serversQuery = useMcpServersQuery({ neverSuspend: true });
const analytics = useAnalytics();
- const steps = buildSteps();
+ const connectorConfig = useFeatureFlag(ONBOARDING_CONNECTORS_FEATURE_FLAG);
+ const steps = createMemo(() => {
+ const config = connectorConfig();
+ return buildSteps(
+ resolveOnboardingConnectorNames(config.enabled, config.payload)
+ );
+ });
- const [stepIndex, setStepIndex] = createSignal(0);
- const currentStep = createMemo(() => steps[stepIndex()]);
+ const [activeStepKey, setActiveStepKey] = createSignal('email');
+ const stepIndex = createMemo(() =>
+ resolveOnboardingStepIndex(
+ steps().map((step) => step.key),
+ activeStepKey()
+ )
+ );
+ const currentStep = createMemo(() => steps()[stepIndex()]);
+ const currentStepKey = createMemo(() => currentStep().key);
const userId = () => userInfoQuery.data?.userId;
// Resume where a full-page OAuth round-trip left off — only for the user
@@ -254,8 +272,7 @@ function FlowContent() {
sessionStorage.removeItem(FLOW_NEXT_STORAGE_KEY);
return;
}
- const index = steps.findIndex((step) => step.key === saved.step);
- if (index !== -1) setStepIndex(index);
+ setActiveStepKey(saved.step ?? 'email');
} catch {
sessionStorage.removeItem(FLOW_STEP_STORAGE_KEY);
}
@@ -271,14 +288,14 @@ function FlowContent() {
startedTracked = true;
analytics.track('onboarding_v4_started', {
signup_method: links.length > 0 ? 'google' : 'email_code',
- entry_step: currentStep().key,
+ entry_step: currentStepKey(),
});
});
createEffect(() => {
if (!needsOnboarding()) return;
analytics.track('onboarding_v4_step', {
- step: currentStep().key,
+ step: currentStepKey(),
index: stepIndex(),
state: 'viewed',
});
@@ -287,15 +304,16 @@ function FlowContent() {
// Forward-only: there is no back.
const advance = (state: 'completed' | 'skipped') => {
analytics.track('onboarding_v4_step', {
- step: currentStep().key,
+ step: currentStepKey(),
index: stepIndex(),
state,
});
- const index = Math.min(stepIndex() + 1, steps.length - 1);
- setStepIndex(index);
+ const index = Math.min(stepIndex() + 1, steps().length - 1);
+ const nextStep = steps()[index];
+ setActiveStepKey(nextStep.key);
sessionStorage.setItem(
FLOW_STEP_STORAGE_KEY,
- JSON.stringify({ user: userId(), step: steps[index].key })
+ JSON.stringify({ user: userId(), step: nextStep.key })
);
};
@@ -397,7 +415,7 @@ function FlowContent() {
</Show>
<Stepper step={stepIndex()} transition={Stepper.transitions.scale}>
- <For each={steps}>
+ <For each={steps()}>
{(step) => (
<Stepper.Step>
{/* Per-step boundary: a first-load query suspending
@@ -413,14 +431,14 @@ function FlowContent() {
<Show when={!currentStep().noDot}>
<div class="flex gap-1.5">
- <Index each={steps.filter((step) => !step.noDot)}>
+ <Index each={steps().filter((step) => !step.noDot)}>
{(step) => (
<div
class={cn(
'size-1.5 rounded-full transition-colors',
- stepIndex() === steps.indexOf(step())
+ stepIndex() === steps().indexOf(step())
? 'bg-accent'
- : stepIndex() > steps.indexOf(step())
+ : stepIndex() > steps().indexOf(step())
? 'bg-ink/40'
: 'bg-ink/15'
)}
diff --git a/apps/web/src/features/setup/flow/onboardingConnectorConfig.test.ts b/apps/web/src/features/setup/flow/onboardingConnectorConfig.test.ts
new file mode 100644
index 0000000000..1f5f6d63ec
--- /dev/null
+++ b/apps/web/src/features/setup/flow/onboardingConnectorConfig.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import {
+ ONBOARDING_CONNECTORS,
+ resolveOnboardingConnectorNames,
+ resolveOnboardingStepIndex,
+} from './onboardingConnectorConfig';
+
+const allConnectors = ONBOARDING_CONNECTORS.map(({ serverName }) => serverName);
+
+describe('resolveOnboardingConnectorNames', () => {
+ it('shows every connector when the feature flag is disabled', () => {
+ expect(
+ resolveOnboardingConnectorNames(false, {
+ linear: false,
+ notion: false,
+ slack: false,
+ github: false,
+ })
+ ).toEqual(allConnectors);
+ });
+
+ it('hides connectors explicitly disabled in the payload', () => {
+ expect(
+ resolveOnboardingConnectorNames(true, {
+ linear: false,
+ slack: false,
+ })
+ ).toEqual(['Notion', 'GitHub']);
+ });
+
+ it('can hide every connector', () => {
+ expect(
+ resolveOnboardingConnectorNames(true, {
+ linear: false,
+ notion: false,
+ slack: false,
+ github: false,
+ })
+ ).toEqual([]);
+ });
+
+ it('keeps connectors visible for missing or invalid values', () => {
+ expect(
+ resolveOnboardingConnectorNames(true, {
+ linear: 'false',
+ notion: null,
+ slack: 0,
+ })
+ ).toEqual(allConnectors);
+ });
+
+ it('shows every connector for malformed payloads', () => {
+ for (const payload of [undefined, null, [], 'invalid']) {
+ expect(resolveOnboardingConnectorNames(true, payload)).toEqual(
+ allConnectors
+ );
+ }
+ });
+});
+
+describe('resolveOnboardingStepIndex', () => {
+ const fullStepList = [
+ 'email',
+ 'connect-linear',
+ 'connect-notion',
+ 'connect-slack',
+ 'connect-github',
+ 'team',
+ 'building',
+ 'summary',
+ 'plan',
+ ];
+
+ it('preserves the active step when an earlier connector is hidden', () => {
+ const reducedStepList = fullStepList.filter(
+ (key) => key !== 'connect-notion'
+ );
+
+ expect(resolveOnboardingStepIndex(fullStepList, 'connect-slack')).toBe(3);
+ expect(resolveOnboardingStepIndex(reducedStepList, 'connect-slack')).toBe(
+ 2
+ );
+ });
+
+ it('falls forward when the active connector is hidden', () => {
+ const reducedStepList = fullStepList.filter(
+ (key) => key !== 'connect-notion'
+ );
+
+ expect(resolveOnboardingStepIndex(reducedStepList, 'connect-notion')).toBe(
+ 2
+ );
+ expect(reducedStepList[2]).toBe('connect-slack');
+ });
+
+ it('stays in bounds when several connectors disappear', () => {
+ const reducedStepList = ['email', 'team', 'building', 'summary', 'plan'];
+ const index = resolveOnboardingStepIndex(reducedStepList, 'connect-github');
+
+ expect(index).toBe(1);
+ expect(reducedStepList[index]).toBe('team');
+ });
+
+ it('falls back safely for an unknown saved step', () => {
+ expect(resolveOnboardingStepIndex(fullStepList, 'unknown')).toBe(0);
+ });
+});
diff --git a/apps/web/src/features/setup/flow/onboardingConnectorConfig.ts b/apps/web/src/features/setup/flow/onboardingConnectorConfig.ts
new file mode 100644
index 0000000000..c0c1187294
--- /dev/null
+++ b/apps/web/src/features/setup/flow/onboardingConnectorConfig.ts
@@ -0,0 +1,67 @@
+/** PostHog feature flag used to configure the connector steps in onboarding. */
+export const ONBOARDING_CONNECTORS_FEATURE_FLAG = 'onboarding-v4-connectors';
+
+export const ONBOARDING_CONNECTORS = [
+ { key: 'linear', serverName: 'Linear' },
+ { key: 'notion', serverName: 'Notion' },
+ { key: 'slack', serverName: 'Slack' },
+ { key: 'github', serverName: 'GitHub' },
+] as const;
+
+const ONBOARDING_STEP_ORDER = [
+ 'email',
+ ...ONBOARDING_CONNECTORS.map(({ key }) => `connect-${key}`),
+ 'team',
+ 'building',
+ 'summary',
+ 'plan',
+];
+
+export type OnboardingConnectorServerName =
+ (typeof ONBOARDING_CONNECTORS)[number]['serverName'];
+
+/**
+ * Resolves the connector steps from the PostHog flag payload.
+ *
+ * The supported payload is a JSON object with connector keys and boolean
+ * values, for example:
+ *
+ * `{ "linear": true, "notion": true, "slack": false, "github": true }`
+ *
+ * Existing behavior is fail-open: the flag must be enabled and a connector
+ * must be explicitly set to `false` to hide it.
+ */
+export function resolveOnboardingConnectorNames(
+ flagEnabled: boolean,
+ payload: unknown
+): OnboardingConnectorServerName[] {
+ if (!flagEnabled || !isObject(payload)) {
+ return ONBOARDING_CONNECTORS.map(({ serverName }) => serverName);
+ }
+
+ return ONBOARDING_CONNECTORS.filter(({ key }) => payload[key] !== false).map(
+ ({ serverName }) => serverName
+ );
+}
+
+/**
+ * Finds the active step in a feature-flag-filtered step list. If the active
+ * step was hidden, onboarding falls forward to the next visible step.
+ */
+export function resolveOnboardingStepIndex(
+ visibleStepKeys: readonly string[],
+ activeStepKey: string
+): number {
+ const activeOrder = Math.max(ONBOARDING_STEP_ORDER.indexOf(activeStepKey), 0);
+ const nextVisibleIndex = visibleStepKeys.findIndex(
+ (key) => ONBOARDING_STEP_ORDER.indexOf(key) >= activeOrder
+ );
+
+ return nextVisibleIndex === -1
+ ? Math.max(visibleStepKeys.length - 1, 0)
+ : nextVisibleIndex;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}