@shipfox/client-onboarding 22.0.3 → 23.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-onboarding",
   "license": "MIT",
-  "version": "22.0.3",
+  "version": "23.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -18,10 +18,10 @@
   },
   "dependencies": {
     "@swc/helpers": "^0.5.17",
-    "@shipfox/client-agent": "22.0.3",
-    "@shipfox/client-integrations": "22.0.3",
-    "@shipfox/client-projects": "22.0.3",
-    "@shipfox/client-shell": "22.0.3"
+    "@shipfox/client-agent": "23.0.0",
+    "@shipfox/client-integrations": "23.0.0",
+    "@shipfox/client-projects": "23.0.0",
+    "@shipfox/client-shell": "23.0.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",
@@ -29,10 +29,15 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
+  "imports": {
+    "#*": "./dist/*"
+  },
   "scripts": {
     "build": "shipfox-swc",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "storybook": "storybook dev -p 6015",
+    "storybook:build": "storybook build -o storybook-static",
     "test": "shipfox-vitest-run",
     "type": "shipfox-tsc-check",
     "type:emit": "shipfox-tsc-emit"

package/src/core/integration-readiness.test.ts

@@ -0,0 +1,277 @@
+import type {
+  IntegrationCapability,
+  IntegrationConnection,
+  IntegrationProvider,
+} from '@shipfox/client-integrations';
+import {describe, expect, test} from '@shipfox/vitest/vi';
+import {deriveIntegrationReadiness} from './integration-readiness.js';
+
+function provider(
+  key: string,
+  capabilities: IntegrationCapability[] = [],
+  displayName = key,
+): IntegrationProvider {
+  return {provider: key, displayName, capabilities};
+}
+
+function connection(
+  providerKey: string,
+  overrides: Partial<IntegrationConnection> = {},
+): IntegrationConnection {
+  return {
+    id: `connection-${providerKey}`,
+    workspaceId: 'workspace',
+    provider: providerKey,
+    externalAccountId: 'account',
+    slug: `${providerKey}_account`,
+    displayName: providerKey,
+    lifecycleStatus: 'active',
+    capabilities: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+const GITHUB = provider('github', ['source_control', 'agent_tools'], 'GitHub');
+const LINEAR = provider('linear', ['agent_tools'], 'Linear');
+const WEBHOOK = provider('webhook', [], 'Webhook');
+
+describe('deriveIntegrationReadiness', () => {
+  test('reports a provider as connected when at least one connection is active', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR],
+      connections: [
+        connection('linear', {lifecycleStatus: 'active'}),
+        connection('linear', {id: 'other', lifecycleStatus: 'error'}),
+      ],
+    });
+
+    expect(readiness.providers).toEqual([
+      {
+        provider: 'linear',
+        displayName: 'Linear',
+        capabilities: ['agent_tools'],
+        connected: true,
+        attention: false,
+      },
+    ]);
+  });
+
+  test('reports a provider as needing attention when connections exist but none is active', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR],
+      connections: [
+        connection('linear', {lifecycleStatus: 'error'}),
+        connection('linear', {id: 'other', lifecycleStatus: 'disabled'}),
+      ],
+    });
+
+    expect(readiness.providers).toEqual([
+      {
+        provider: 'linear',
+        displayName: 'Linear',
+        capabilities: ['agent_tools'],
+        connected: false,
+        attention: true,
+      },
+    ]);
+    expect(readiness.attentionProviders).toEqual(['linear']);
+  });
+
+  test('reports a provider with no connections as neither connected nor in attention', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR, GITHUB],
+      connections: [connection('github', {lifecycleStatus: 'active'})],
+    });
+
+    expect(readiness.providers).toEqual([
+      {
+        provider: 'linear',
+        displayName: 'Linear',
+        capabilities: ['agent_tools'],
+        connected: false,
+        attention: false,
+      },
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+        capabilities: ['source_control', 'agent_tools'],
+        connected: true,
+        attention: false,
+      },
+    ]);
+  });
+
+  test('ignores connections for providers outside the catalog', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR],
+      connections: [connection('unknown', {lifecycleStatus: 'active'})],
+    });
+
+    expect(readiness.providers).toEqual([
+      {
+        provider: 'linear',
+        displayName: 'Linear',
+        capabilities: ['agent_tools'],
+        connected: false,
+        attention: false,
+      },
+    ]);
+    expect(readiness.hasToolIntegration).toBe(false);
+  });
+
+  test('orders attention providers by the most recent connection update first', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [GITHUB, LINEAR, WEBHOOK],
+      connections: [
+        connection('linear', {
+          lifecycleStatus: 'error',
+          updatedAt: '2026-03-01T00:00:00.000Z',
+        }),
+        connection('webhook', {
+          lifecycleStatus: 'error',
+          updatedAt: '2026-02-01T00:00:00.000Z',
+        }),
+        connection('github', {
+          lifecycleStatus: 'disabled',
+          updatedAt: '2026-01-01T00:00:00.000Z',
+        }),
+      ],
+    });
+
+    expect(readiness.attentionProviders).toEqual(['linear', 'webhook', 'github']);
+  });
+
+  test('uses the newest of several connections per provider for ordering', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR, WEBHOOK],
+      connections: [
+        connection('linear', {
+          id: 'stale',
+          lifecycleStatus: 'error',
+          updatedAt: '2026-01-01T00:00:00.000Z',
+        }),
+        connection('linear', {
+          id: 'fresh',
+          lifecycleStatus: 'disabled',
+          updatedAt: '2026-04-01T00:00:00.000Z',
+        }),
+        connection('webhook', {
+          lifecycleStatus: 'error',
+          updatedAt: '2026-03-01T00:00:00.000Z',
+        }),
+      ],
+    });
+
+    expect(readiness.attentionProviders).toEqual(['linear', 'webhook']);
+  });
+
+  test('keeps catalog order when attention providers updated at the same time', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [GITHUB, LINEAR, WEBHOOK],
+      connections: [
+        connection('linear', {lifecycleStatus: 'error'}),
+        connection('webhook', {lifecycleStatus: 'error'}),
+        connection('github', {lifecycleStatus: 'error'}),
+      ],
+    });
+
+    expect(readiness.attentionProviders).toEqual(['github', 'linear', 'webhook']);
+  });
+
+  test('skips connections with an unparsable updated_at when ordering', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [LINEAR, WEBHOOK],
+      connections: [
+        connection('linear', {lifecycleStatus: 'error', updatedAt: 'not-a-date'}),
+        connection('webhook', {lifecycleStatus: 'error', updatedAt: '2026-02-01T00:00:00.000Z'}),
+      ],
+    });
+
+    expect(readiness.attentionProviders).toEqual(['webhook', 'linear']);
+  });
+
+  test('reports no attention providers when no connection needs attention', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [GITHUB, LINEAR],
+      connections: [
+        connection('github', {lifecycleStatus: 'active'}),
+        connection('linear', {lifecycleStatus: 'active'}),
+      ],
+    });
+
+    expect(readiness.attentionProviders).toEqual([]);
+  });
+
+  test('reports hasSourceControl only for an active source-control connection', () => {
+    expect(
+      deriveIntegrationReadiness({
+        providers: [GITHUB],
+        connections: [connection('github', {lifecycleStatus: 'active'})],
+      }).hasSourceControl,
+    ).toBe(true);
+
+    expect(
+      deriveIntegrationReadiness({
+        providers: [GITHUB],
+        connections: [connection('github', {lifecycleStatus: 'error'})],
+      }).hasSourceControl,
+    ).toBe(false);
+
+    expect(
+      deriveIntegrationReadiness({
+        providers: [LINEAR],
+        connections: [connection('linear', {lifecycleStatus: 'active'})],
+      }).hasSourceControl,
+    ).toBe(false);
+  });
+
+  test('reports hasToolIntegration for an active connection without source_control', () => {
+    expect(
+      deriveIntegrationReadiness({
+        providers: [LINEAR],
+        connections: [connection('linear', {lifecycleStatus: 'active'})],
+      }).hasToolIntegration,
+    ).toBe(true);
+
+    expect(
+      deriveIntegrationReadiness({
+        providers: [WEBHOOK],
+        connections: [connection('webhook', {lifecycleStatus: 'active'})],
+      }).hasToolIntegration,
+    ).toBe(true);
+  });
+
+  test('GitHub never satisfies hasToolIntegration', () => {
+    expect(
+      deriveIntegrationReadiness({
+        providers: [GITHUB],
+        connections: [connection('github', {lifecycleStatus: 'active'})],
+      }).hasToolIntegration,
+    ).toBe(false);
+  });
+
+  test('an inactive tool connection does not satisfy hasToolIntegration', () => {
+    expect(
+      deriveIntegrationReadiness({
+        providers: [LINEAR],
+        connections: [connection('linear', {lifecycleStatus: 'error'})],
+      }).hasToolIntegration,
+    ).toBe(false);
+  });
+
+  test('combines providers in one readiness report', () => {
+    const readiness = deriveIntegrationReadiness({
+      providers: [GITHUB, LINEAR, WEBHOOK],
+      connections: [
+        connection('github', {lifecycleStatus: 'active'}),
+        connection('linear', {lifecycleStatus: 'error'}),
+      ],
+    });
+
+    expect(readiness.hasSourceControl).toBe(true);
+    expect(readiness.hasToolIntegration).toBe(false);
+    expect(readiness.attentionProviders).toEqual(['linear']);
+  });
+});

package/src/core/integration-readiness.ts

@@ -0,0 +1,93 @@
+import {
+  type IntegrationCapability,
+  type IntegrationConnection,
+  type IntegrationProvider,
+  isUsableConnection,
+} from '@shipfox/client-integrations';
+
+/**
+ * Per-provider connection state for the workspace setup readiness model.
+ * `connected` and `attention` are mutually exclusive: a provider with at
+ * least one active connection is connected, a provider whose connections
+ * exist but are all inactive needs attention, and a provider without
+ * connections is neither.
+ */
+export interface IntegrationProviderReadiness {
+  provider: string;
+  displayName: string;
+  capabilities: ReadonlyArray<IntegrationCapability>;
+  connected: boolean;
+  attention: boolean;
+}
+
+export interface WorkspaceIntegrationReadiness {
+  providers: ReadonlyArray<IntegrationProviderReadiness>;
+  /** Providers in attention, most recently updated connection first. */
+  attentionProviders: readonly string[];
+  /** At least one active connection to a source-control provider. */
+  hasSourceControl: boolean;
+  /** At least one active connection to a provider without `source_control`. */
+  hasToolIntegration: boolean;
+}
+
+export interface IntegrationReadinessInput {
+  providers: readonly IntegrationProvider[];
+  connections: readonly IntegrationConnection[];
+}
+
+/**
+ * Derives the workspace integration readiness from the provider catalog and
+ * the workspace's connections. The result is the shared input for the setup
+ * checklist and for the first-workflow spec's contextual "Connect X" prompt.
+ */
+export function deriveIntegrationReadiness({
+  providers,
+  connections,
+}: IntegrationReadinessInput): WorkspaceIntegrationReadiness {
+  const readiness = providers.map((provider) => {
+    const providerConnections = connections.filter(
+      (connection) => connection.provider === provider.provider,
+    );
+    const connected = providerConnections.some(isUsableConnection);
+    return {
+      provider: provider.provider,
+      displayName: provider.displayName,
+      capabilities: provider.capabilities,
+      connected,
+      attention: providerConnections.length > 0 && !connected,
+    };
+  });
+
+  const latestConnectionUpdate = latestConnectionUpdateByProvider(connections);
+
+  const attentionProviders = readiness
+    .filter((provider) => provider.attention)
+    .sort((a, b) => {
+      const aUpdate = latestConnectionUpdate.get(a.provider) ?? 0;
+      const bUpdate = latestConnectionUpdate.get(b.provider) ?? 0;
+      return bUpdate - aUpdate;
+    })
+    .map((provider) => provider.provider);
+
+  const hasSourceControl = readiness.some(
+    (provider) => provider.connected && provider.capabilities.includes('source_control'),
+  );
+  const hasToolIntegration = readiness.some(
+    (provider) => provider.connected && !provider.capabilities.includes('source_control'),
+  );
+
+  return {providers: readiness, attentionProviders, hasSourceControl, hasToolIntegration};
+}
+
+function latestConnectionUpdateByProvider(
+  connections: readonly IntegrationConnection[],
+): Map<string, number> {
+  const updates = new Map<string, number>();
+  for (const connection of connections) {
+    const timestamp = Date.parse(connection.updatedAt);
+    if (Number.isNaN(timestamp)) continue;
+    const current = updates.get(connection.provider) ?? 0;
+    if (timestamp > current) updates.set(connection.provider, timestamp);
+  }
+  return updates;
+}