@shipfox/client-onboarding 22.0.2 → 23.0.0

package/src/core/setup-checklist.test.ts

@@ -0,0 +1,342 @@
+import {describe, expect, test} from '@shipfox/vitest/vi';
+import {deriveIntegrationReadiness} from './integration-readiness.js';
+import {
+  deriveSetupChecklist,
+  type SetupChecklistInput,
+  type SetupChecklistItem,
+} from './setup-checklist.js';
+
+function readiness(overrides: Partial<ReturnType<typeof deriveIntegrationReadiness>> = {}) {
+  return {
+    ...deriveIntegrationReadiness({
+      providers: [
+        {
+          provider: 'github',
+          displayName: 'GitHub',
+          capabilities: ['source_control', 'agent_tools'],
+        },
+        {provider: 'linear', displayName: 'Linear', capabilities: ['agent_tools']},
+        {provider: 'webhook', displayName: 'Webhook', capabilities: []},
+      ],
+      connections: [],
+    }),
+    ...overrides,
+  };
+}
+
+function input(overrides: Partial<SetupChecklistInput> = {}): SetupChecklistInput {
+  return {
+    readiness: readiness(),
+    installationRunners: 'managed',
+    workspaceRunnerCapacity: false,
+    modelProvider: {installationProvided: true, configured: false},
+    membership: {memberCount: 1, pendingInvitationCount: 0},
+    ...overrides,
+  };
+}
+
+function itemIds(items: readonly SetupChecklistItem[]) {
+  return items.map((item) => item.id);
+}
+
+describe('deriveSetupChecklist', () => {
+  test('keeps rows in spec order', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(itemIds(checklist.items)).toEqual([
+      'source-control',
+      'project',
+      'tools',
+      'first-workflow',
+      'teammates',
+    ]);
+  });
+
+  test('renders the Cloud shape as 2 of 3 done', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.map((item) => [item.id, item.status])).toEqual([
+      ['source-control', 'done'],
+      ['project', 'done'],
+      ['tools', 'open'],
+      ['first-workflow', 'info'],
+      ['teammates', 'info'],
+    ]);
+    expect(checklist.trackedCount).toBe(3);
+    expect(checklist.openCount).toBe(1);
+    expect(checklist.complete).toBe(false);
+  });
+
+  test('completes on Cloud once a tool is connected', () => {
+    const checklist = deriveSetupChecklist(
+      input({readiness: readiness({hasToolIntegration: true})}),
+    );
+
+    expect(checklist.openCount).toBe(0);
+    expect(checklist.complete).toBe(true);
+    expect(checklist.items.find((item) => item.id === 'tools')?.status).toBe('done');
+  });
+
+  test('renders the bare self-host shape as 2 of 5 done', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        installationRunners: 'none',
+        modelProvider: {installationProvided: false, configured: false},
+      }),
+    );
+
+    expect(itemIds(checklist.items)).toEqual([
+      'source-control',
+      'project',
+      'tools',
+      'runner',
+      'model-provider',
+      'first-workflow',
+      'teammates',
+    ]);
+    expect(checklist.trackedCount).toBe(5);
+    expect(checklist.openCount).toBe(3);
+    expect(checklist.complete).toBe(false);
+  });
+
+  test('completes on a bare self-host only when tools, runner, and model provider are done', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({hasToolIntegration: true}),
+        installationRunners: 'none',
+        workspaceRunnerCapacity: true,
+        modelProvider: {installationProvided: false, configured: true},
+      }),
+    );
+
+    expect(checklist.openCount).toBe(0);
+    expect(checklist.complete).toBe(true);
+  });
+
+  test('keeps the checklist incomplete while any conditional row is open', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({hasToolIntegration: true}),
+        installationRunners: 'none',
+        workspaceRunnerCapacity: false,
+        modelProvider: {installationProvided: false, configured: true},
+      }),
+    );
+
+    expect(checklist.openCount).toBe(1);
+    expect(checklist.complete).toBe(false);
+  });
+
+  test('hides the runner row when the installation provides managed capacity', () => {
+    const checklist = deriveSetupChecklist(
+      input({installationRunners: 'managed', workspaceRunnerCapacity: false}),
+    );
+
+    expect(itemIds(checklist.items)).not.toContain('runner');
+  });
+
+  test('shows the runner row when the installation provides no capacity', () => {
+    const checklist = deriveSetupChecklist(
+      input({installationRunners: 'none', workspaceRunnerCapacity: false}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'runner')).toMatchObject({
+      status: 'open',
+      tracked: true,
+      action: {href: '/settings/runners'},
+    });
+  });
+
+  test('marks the runner row done when the workspace has capacity', () => {
+    const checklist = deriveSetupChecklist(
+      input({installationRunners: 'none', workspaceRunnerCapacity: true}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'runner')?.status).toBe('done');
+  });
+
+  test('hides the model-provider row when the installation provides inference', () => {
+    const checklist = deriveSetupChecklist(
+      input({modelProvider: {installationProvided: true, configured: false}}),
+    );
+
+    expect(itemIds(checklist.items)).not.toContain('model-provider');
+  });
+
+  test('shows the model-provider row only when the installation provides no inference', () => {
+    const checklist = deriveSetupChecklist(
+      input({modelProvider: {installationProvided: false, configured: false}}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'model-provider')).toMatchObject({
+      status: 'open',
+      tracked: true,
+      action: {href: '/settings/agents'},
+    });
+  });
+
+  test('marks the model-provider row done when a config exists', () => {
+    const checklist = deriveSetupChecklist(
+      input({modelProvider: {installationProvided: false, configured: true}}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'model-provider')?.status).toBe('done');
+  });
+
+  test('keeps source control and project rows always done', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.find((item) => item.id === 'source-control')?.status).toBe('done');
+    expect(checklist.items.find((item) => item.id === 'project')?.status).toBe('done');
+  });
+
+  test('names a single attention provider in the tools title', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({
+          attentionProviders: ['linear'],
+          hasToolIntegration: false,
+        }),
+      }),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'tools')).toMatchObject({
+      status: 'open',
+      title: 'Linear needs attention',
+    });
+  });
+
+  test('uses the provider display name for a key with brand capitalization', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({
+          providers: [
+            {
+              provider: 'github',
+              displayName: 'GitHub',
+              capabilities: ['agent_tools'],
+              connected: false,
+              attention: true,
+            },
+          ],
+          attentionProviders: ['github'],
+          hasToolIntegration: false,
+        }),
+      }),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'tools')?.title).toBe(
+      'GitHub needs attention',
+    );
+  });
+
+  test('does not name a source-control provider in the tools title', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({
+          attentionProviders: ['github'],
+          hasToolIntegration: false,
+        }),
+      }),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'tools')?.title).toBe('Connect your tools');
+  });
+
+  test('counts several attention providers in the tools title', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({
+          attentionProviders: ['linear', 'webhook'],
+          hasToolIntegration: false,
+        }),
+      }),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'tools')?.title).toBe(
+      '2 integrations need attention',
+    );
+  });
+
+  test('keeps the base tools title when nothing needs attention', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.find((item) => item.id === 'tools')?.title).toBe('Connect your tools');
+  });
+
+  test('keeps the base tools title when the tools row is done despite attention', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        readiness: readiness({
+          attentionProviders: ['linear'],
+          hasToolIntegration: true,
+        }),
+      }),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'tools')).toMatchObject({
+      status: 'done',
+      title: 'Connect your tools',
+    });
+  });
+
+  test('carries the tools purpose and settings link on the open row', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.find((item) => item.id === 'tools')).toMatchObject({
+      purpose:
+        'Connect issue tracking, messaging, observability, or any Shipfox integration so workflows can react to events and agents can use them',
+      action: {href: '/settings/integrations'},
+    });
+  });
+
+  test('treats the first-workflow row as a pointer that never counts', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.find((item) => item.id === 'first-workflow')).toMatchObject({
+      status: 'info',
+      tracked: false,
+      action: {href: '/docs/getting-started'},
+    });
+  });
+
+  test('treats the teammates row as a pointer that never counts', () => {
+    const checklist = deriveSetupChecklist(input());
+
+    expect(checklist.items.find((item) => item.id === 'teammates')).toMatchObject({
+      status: 'info',
+      tracked: false,
+      action: {href: '/settings/members'},
+    });
+  });
+
+  test('renders the teammates row done once a second member joined', () => {
+    const checklist = deriveSetupChecklist(
+      input({membership: {memberCount: 2, pendingInvitationCount: 0}}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'teammates')?.status).toBe('done');
+  });
+
+  test('renders the teammates row done once an invitation is pending', () => {
+    const checklist = deriveSetupChecklist(
+      input({membership: {memberCount: 1, pendingInvitationCount: 1}}),
+    );
+
+    expect(checklist.items.find((item) => item.id === 'teammates')?.status).toBe('done');
+  });
+
+  test('never counts pointers toward trackedCount or openCount', () => {
+    const checklist = deriveSetupChecklist(
+      input({
+        membership: {memberCount: 1, pendingInvitationCount: 0},
+        installationRunners: 'none',
+        modelProvider: {installationProvided: false, configured: false},
+      }),
+    );
+
+    expect(checklist.trackedCount).toBe(5);
+    expect(checklist.openCount).toBe(3);
+    expect(checklist.items.filter((item) => !item.tracked)).toHaveLength(2);
+  });
+});

package/src/core/setup-checklist.ts

@@ -0,0 +1,156 @@
+import type {WorkspaceIntegrationReadiness} from './integration-readiness.js';
+
+export type SetupChecklistItemStatus = 'done' | 'open' | 'info';
+
+export type SetupChecklistItemId =
+  | 'source-control'
+  | 'project'
+  | 'tools'
+  | 'runner'
+  | 'model-provider'
+  | 'first-workflow'
+  | 'teammates';
+
+export interface SetupChecklistAction {
+  label: string;
+  href: string;
+}
+
+export interface SetupChecklistItem {
+  id: SetupChecklistItemId;
+  title: string;
+  status: SetupChecklistItemStatus;
+  /** Tracked items count toward completion; pointers never do. */
+  tracked: boolean;
+  /** One line of purpose, rendered for open and pointer rows. */
+  purpose?: string;
+  /** Primary action, a link to the settings page where the work happens. */
+  action?: SetupChecklistAction;
+}
+
+export interface SetupChecklist {
+  /** Rows in spec order: done progress, activation asks, then pointers. */
+  items: readonly SetupChecklistItem[];
+  /** Open tracked rows. */
+  openCount: number;
+  /** Rows that count toward completion. */
+  trackedCount: number;
+  /** True when every tracked row is done. */
+  complete: boolean;
+}
+
+export interface SetupChecklistInput {
+  readiness: WorkspaceIntegrationReadiness;
+  installationRunners: 'managed' | 'none';
+  workspaceRunnerCapacity: boolean;
+  modelProvider: {installationProvided: boolean; configured: boolean};
+  membership: {memberCount: number; pendingInvitationCount: number};
+}
+
+const TOOLS_TITLE = 'Connect your tools';
+const TOOLS_PURPOSE =
+  'Connect issue tracking, messaging, observability, or any Shipfox integration so workflows can react to events and agents can use them';
+const RUNNER_PURPOSE = 'Jobs wait in `pending` until a runner is online';
+const MODEL_PROVIDER_PURPOSE = 'Agent steps need a model provider to run';
+const FIRST_WORKFLOW_PURPOSE =
+  'Add a workflow file under `.shipfox/workflows/` and Shipfox picks it up on the next push';
+const TEAMMATES_PURPOSE = 'Everyone in the workspace can edit workflows and see runs';
+
+/**
+ * Derives the workspace setup checklist from integration readiness and the
+ * runner, model-provider, and membership facts. Rows follow the spec order;
+ * the runner and model-provider rows exist only when the installation does
+ * not already provide the capability.
+ */
+export function deriveSetupChecklist({
+  readiness,
+  installationRunners,
+  workspaceRunnerCapacity,
+  modelProvider,
+  membership,
+}: SetupChecklistInput): SetupChecklist {
+  const items: SetupChecklistItem[] = [
+    {id: 'source-control', title: 'Connect source control', status: 'done', tracked: true},
+    {id: 'project', title: 'Create a project', status: 'done', tracked: true},
+    {
+      id: 'tools',
+      title: toolsTitle(readiness),
+      status: readiness.hasToolIntegration ? 'done' : 'open',
+      tracked: true,
+      purpose: TOOLS_PURPOSE,
+      action: {label: 'Connect', href: '/settings/integrations'},
+    },
+  ];
+
+  if (installationRunners === 'none') {
+    items.push({
+      id: 'runner',
+      title: 'Set up runner capacity',
+      status: workspaceRunnerCapacity ? 'done' : 'open',
+      tracked: true,
+      purpose: RUNNER_PURPOSE,
+      action: {label: 'Set up', href: '/settings/runners'},
+    });
+  }
+
+  if (!modelProvider.installationProvided) {
+    items.push({
+      id: 'model-provider',
+      title: 'Configure a model provider',
+      status: modelProvider.configured ? 'done' : 'open',
+      tracked: true,
+      purpose: MODEL_PROVIDER_PURPOSE,
+      action: {label: 'Configure', href: '/settings/agents'},
+    });
+  }
+
+  items.push(
+    {
+      id: 'first-workflow',
+      title: 'Push your first workflow',
+      status: 'info',
+      tracked: false,
+      purpose: FIRST_WORKFLOW_PURPOSE,
+      action: {label: 'Read the quickstart', href: '/docs/getting-started'},
+    },
+    {
+      id: 'teammates',
+      title: 'Invite your teammates',
+      status:
+        membership.memberCount >= 2 || membership.pendingInvitationCount >= 1 ? 'done' : 'info',
+      tracked: false,
+      purpose: TEAMMATES_PURPOSE,
+      action: {label: 'Invite', href: '/settings/members'},
+    },
+  );
+
+  const trackedItems = items.filter((item) => item.tracked);
+  const openCount = trackedItems.filter((item) => item.status === 'open').length;
+
+  return {
+    items,
+    openCount,
+    trackedCount: trackedItems.length,
+    complete: openCount === 0,
+  };
+}
+
+function toolsTitle(readiness: WorkspaceIntegrationReadiness): string {
+  if (!readiness.hasToolIntegration) {
+    const attentionToolProviders = readiness.attentionProviders
+      .map((providerKey) => readiness.providers.find(({provider}) => provider === providerKey))
+      .filter(
+        (provider) => provider !== undefined && !provider.capabilities.includes('source_control'),
+      );
+    if (attentionToolProviders.length === 1) {
+      const provider = attentionToolProviders[0];
+      if (provider !== undefined) {
+        return `${provider.displayName || provider.provider} needs attention`;
+      }
+    }
+    if (attentionToolProviders.length > 1) {
+      return `${attentionToolProviders.length} integrations need attention`;
+    }
+  }
+  return TOOLS_TITLE;
+}

package/src/index.ts

@@ -1,3 +1,18 @@
+export {
+  deriveIntegrationReadiness,
+  type IntegrationProviderReadiness,
+  type IntegrationReadinessInput,
+  type WorkspaceIntegrationReadiness,
+} from '#core/integration-readiness.js';
+export {
+  deriveSetupChecklist,
+  type SetupChecklist,
+  type SetupChecklistAction,
+  type SetupChecklistInput,
+  type SetupChecklistItem,
+  type SetupChecklistItemId,
+  type SetupChecklistItemStatus,
+} from '#core/setup-checklist.js';
 export {
   loadWorkspaceSetupRoute,
   type WorkspaceSetupRouteOptions,

package/src/workspace-setup-route.test.tsx

@@ -82,6 +82,7 @@ interface SetupFetchOptions {
   projectsFail?: boolean;
   connectionsFail?: boolean;
   providerConfigsFail?: boolean;
+  workspaceProviders?: 'enabled' | 'disabled';
   projectsPending?: boolean;
   workspaceStatus?: 'active' | 'suspended' | 'deleted';
 }
@@ -95,6 +96,7 @@ function setupFetch(options: SetupFetchOptions = {}) {
     projectsFail = false,
     connectionsFail = false,
     providerConfigsFail = false,
+    workspaceProviders,
     projectsPending = false,
     workspaceStatus = 'active',
   } = options;
@@ -140,6 +142,14 @@ function setupFetch(options: SetupFetchOptions = {}) {
         }),
       );
     }
+    if (url.endsWith('/agent/model-provider-catalog')) {
+      return Promise.resolve(
+        jsonResponse({
+          providers: [],
+          ...(workspaceProviders === undefined ? {} : {workspace_providers: workspaceProviders}),
+        }),
+      );
+    }
     return Promise.resolve(jsonResponse({}, {status: 404}));
   });
 }
@@ -353,6 +363,20 @@ describe('workspace setup route hook', () => {
     expect(screen.getByTestId('project-navigation')).toHaveTextContent('hidden');
   });
 
+  test('skips provider onboarding when workspace providers are managed by the instance', async () => {
+    const fetchImpl = setupFetch({
+      connections: [sourceConnection()],
+      providerConfigs: [],
+      defaultProviderId: null,
+      workspaceProviders: 'disabled',
+    });
+
+    renderSetupRoute(`/w/${WORKSPACE_SLUG}/integrations`, fetchImpl);
+
+    expect(await screen.findByText('Create project')).toBeInTheDocument();
+    expect(calledUrls(fetchImpl).some((url) => url.endsWith('/agent/model-providers'))).toBe(true);
+  });
+
   test('keeps the provider onboarding route available while provider setup is pending', async () => {
     renderSetupRoute(
       `/w/${WORKSPACE_SLUG}/model-provider`,

package/src/workspace-setup-route.ts

@@ -1,5 +1,6 @@
 import {
   isModelProviderOnboardingDismissed,
+  modelProviderCatalogQueryOptions,
   modelProviderConfigsQueryOptions,
 } from '@shipfox/client-agent';
 import {
@@ -140,14 +141,27 @@ async function hasHandledModelProviderOnboarding(
 ): Promise<boolean> {
   if (isModelProviderOnboardingDismissed(workspaceId)) return true;
 
-  const options = modelProviderConfigsQueryOptions(workspaceId);
-  try {
-    const configs = await queryClient.fetchQuery(options);
+  const catalogOptions = modelProviderCatalogQueryOptions();
+  const configOptions = modelProviderConfigsQueryOptions(workspaceId);
+  const [catalogResult, configsResult] = await Promise.allSettled([
+    queryClient.fetchQuery(catalogOptions),
+    queryClient.fetchQuery(configOptions),
+  ]);
+
+  if (
+    catalogResult.status === 'fulfilled' &&
+    catalogResult.value.workspaceProviders === 'disabled'
+  ) {
+    return true;
+  }
+
+  if (configsResult.status === 'fulfilled') {
+    const configs = configsResult.value;
     return configs.configs.length > 0;
-  } catch {
-    const cached = queryClient.getQueryData<{configs: unknown[]}>(options.queryKey);
-    return cached?.configs.length !== 0;
   }
+
+  const cached = queryClient.getQueryData<{configs: unknown[]}>(configOptions.queryKey);
+  return cached?.configs.length !== 0;
 }
 
 function normalizePath(pathname: string) {