@shipfox/client-projects 0.2.0

package/src/components/workspace-setup-guard.tsx

@@ -0,0 +1,185 @@
+import type {ListIntegrationConnectionsResponseDto} from '@shipfox/api-integration-core-dto';
+import type {ListProjectsResponseDto} from '@shipfox/api-projects-dto';
+import {
+  isModelProviderOnboardingDismissed,
+  listModelProviderConfigs,
+  modelProviderQueryKeys,
+} from '@shipfox/client-agent';
+import {integrationsQueryKeys, listSourceConnections} from '@shipfox/client-integrations';
+import {WorkspaceSetupLoadError, type WorkspaceSetupState} from '@shipfox/client-shell/runtime';
+import type {QueryClient} from '@tanstack/react-query';
+import {redirect} from '@tanstack/react-router';
+import {listProjects, projectsQueryKeys} from '#hooks/api/projects.js';
+
+const TRAILING_SLASHES_RE = /\/+$/u;
+const PROJECT_EXISTENCE_STALE_TIME_MS = 30_000;
+type ListModelProviderConfigsResponseDto = Awaited<ReturnType<typeof listModelProviderConfigs>>;
+
+export interface WorkspaceSetupRouteOptions {
+  queryClient: QueryClient;
+  workspaceId: string;
+  pathname: string;
+}
+
+export async function loadWorkspaceSetupRoute({
+  queryClient,
+  workspaceId,
+  pathname,
+}: WorkspaceSetupRouteOptions): Promise<WorkspaceSetupState> {
+  const projects = await fetchWorkspaceProjectExistence(queryClient, workspaceId);
+  const normalizedPathname = normalizePath(pathname);
+  const hasProject = projects.projects.length > 0;
+
+  if (hasProject) {
+    if (isIntegrationsIndexPath(normalizedPathname, workspaceId)) {
+      throw redirect({
+        to: '/workspaces/$wid/settings/integrations',
+        params: {wid: workspaceId},
+        replace: true,
+      });
+    }
+
+    return {hideProjectNavigation: false};
+  }
+
+  const sourceConnections = await fetchWorkspaceSourceConnections(queryClient, workspaceId);
+  const hasSourceConnection = sourceConnections.connections.length > 0;
+
+  if (!hasSourceConnection) {
+    if (isIntegrationSetupPath(normalizedPathname, workspaceId)) {
+      return {hideProjectNavigation: true};
+    }
+
+    throw redirect({
+      to: '/workspaces/$wid/integrations',
+      params: {wid: workspaceId},
+      replace: true,
+    });
+  }
+
+  if (isAgentSettingsPath(normalizedPathname, workspaceId)) {
+    return {hideProjectNavigation: true};
+  }
+
+  const providerHandled = await hasHandledModelProviderOnboarding(queryClient, workspaceId);
+  if (!providerHandled) {
+    if (isModelProviderOnboardingPath(normalizedPathname, workspaceId)) {
+      return {hideProjectNavigation: true};
+    }
+
+    throw redirect({
+      to: '/workspaces/$wid/model-provider',
+      params: {wid: workspaceId},
+      replace: true,
+    });
+  }
+
+  if (isProjectCreationPath(normalizedPathname, workspaceId)) {
+    return {hideProjectNavigation: true};
+  }
+
+  throw redirect({
+    to: '/workspaces/$wid/projects/new',
+    params: {wid: workspaceId},
+    replace: true,
+  });
+}
+
+async function fetchWorkspaceProjectExistence(queryClient: QueryClient, workspaceId: string) {
+  const queryKey = projectsQueryKeys.exists(workspaceId);
+
+  try {
+    return await queryClient.fetchQuery({
+      queryKey,
+      queryFn: ({signal}) => listProjects({workspaceId, limit: 1, signal}),
+      // beforeLoad runs for every in-workspace navigation. Use a short
+      // freshness window to avoid hot-path refetches while still detecting
+      // project creation from another tab or actor.
+      staleTime: PROJECT_EXISTENCE_STALE_TIME_MS,
+    });
+  } catch (error) {
+    const cached = queryClient.getQueryData<ListProjectsResponseDto>(queryKey);
+    if (cached !== undefined) return cached;
+    throw new WorkspaceSetupLoadError(error);
+  }
+}
+
+async function fetchWorkspaceSourceConnections(queryClient: QueryClient, workspaceId: string) {
+  const queryKey = integrationsQueryKeys.sourceConnections(workspaceId);
+
+  try {
+    // Onboarding-only path: kept fresh (no staleTime) because some install
+    // flows connect a source without invalidating this key, and a stale
+    // "no connection" read would trap the user in the onboarding redirect.
+    return await queryClient.fetchQuery({
+      queryKey,
+      queryFn: ({signal}) => listSourceConnections({workspaceId, signal}),
+    });
+  } catch (error) {
+    const cached = queryClient.getQueryData<ListIntegrationConnectionsResponseDto>(queryKey);
+    if (cached !== undefined) return cached;
+    throw new WorkspaceSetupLoadError(error);
+  }
+}
+
+async function hasHandledModelProviderOnboarding(
+  queryClient: QueryClient,
+  workspaceId: string,
+): Promise<boolean> {
+  if (isModelProviderOnboardingDismissed(workspaceId)) return true;
+
+  const configs = await fetchWorkspaceModelProviderConfigs(queryClient, workspaceId);
+  return configs === null || configs.configs.length > 0;
+}
+
+async function fetchWorkspaceModelProviderConfigs(
+  queryClient: QueryClient,
+  workspaceId: string,
+): Promise<ListModelProviderConfigsResponseDto | null> {
+  const queryKey = modelProviderQueryKeys.configs(workspaceId);
+
+  try {
+    return await queryClient.fetchQuery({
+      queryKey,
+      queryFn: ({signal}) => listModelProviderConfigs({workspaceId, signal}),
+    });
+  } catch {
+    const cached = queryClient.getQueryData<ListModelProviderConfigsResponseDto>(queryKey);
+    if (cached !== undefined) return cached;
+    return null;
+  }
+}
+
+function normalizePath(pathname: string) {
+  if (pathname === '/') return pathname;
+  return pathname.replace(TRAILING_SLASHES_RE, '');
+}
+
+function workspacePath(workspaceId: string, suffix: string) {
+  return `/workspaces/${workspaceId}${suffix}`;
+}
+
+function isIntegrationsIndexPath(pathname: string, workspaceId: string) {
+  return pathname === workspacePath(workspaceId, '/integrations');
+}
+
+function isIntegrationSetupPath(pathname: string, workspaceId: string) {
+  const basePath = workspacePath(workspaceId, '/integrations');
+  return (
+    pathname === basePath ||
+    pathname.startsWith(`${basePath}/`) ||
+    pathname === workspacePath(workspaceId, '/settings/integrations')
+  );
+}
+
+function isProjectCreationPath(pathname: string, workspaceId: string) {
+  return pathname === workspacePath(workspaceId, '/projects/new');
+}
+
+function isModelProviderOnboardingPath(pathname: string, workspaceId: string) {
+  return pathname === workspacePath(workspaceId, '/model-provider');
+}
+
+function isAgentSettingsPath(pathname: string, workspaceId: string) {
+  return pathname === workspacePath(workspaceId, '/settings/agents');
+}

package/src/feature.ts

@@ -0,0 +1,44 @@
+import {defineClientFeature} from '@shipfox/client-shell';
+
+export const projectsFeature = defineClientFeature({
+  id: 'shipfox.projects',
+  routes: [
+    {
+      path: '/workspaces/$wid',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-projects/routes/home',
+    },
+    {
+      path: '/workspaces/$wid/projects/new',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-projects/routes/create-project',
+    },
+    {
+      path: '/workspaces/$wid/projects/$pid',
+      parent: 'projectLayout',
+      impl: '@shipfox/client-projects/routes/project-index',
+    },
+    {
+      path: '/workspaces/$wid/projects/$pid/workflows',
+      parent: 'projectLayout',
+      impl: '@shipfox/client-projects/routes/workflows',
+    },
+  ],
+  navigation: [
+    {
+      id: 'nav.projects',
+      scope: 'workspace',
+      label: 'Projects',
+      to: '/workspaces/$wid',
+      exact: true,
+      order: 100,
+    },
+    {
+      id: 'nav.workflows',
+      scope: 'project',
+      label: 'Workflows',
+      to: '/workspaces/$wid/projects/$pid/workflows',
+      order: 200,
+    },
+  ],
+});

package/src/hooks/api/definitions.ts

@@ -0,0 +1,50 @@
+import type {DefinitionListResponseDto} from '@shipfox/api-definitions-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {keepPreviousData, useInfiniteQuery, useQuery} from '@tanstack/react-query';
+
+export const definitionsQueryKeys = {
+  all: ['definitions'] as const,
+  list: (projectId: string) => [...definitionsQueryKeys.all, 'list', projectId] as const,
+};
+
+export async function listDefinitions({
+  projectId,
+  limit = 50,
+  cursor,
+  signal,
+}: {
+  projectId: string;
+  limit?: number;
+  cursor?: string | undefined;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams({project_id: projectId, limit: String(limit)});
+  if (cursor) params.set('cursor', cursor);
+  return await apiRequest<DefinitionListResponseDto>(`/definitions?${params.toString()}`, {
+    signal,
+  });
+}
+
+export function useDefinitionsInfiniteQuery(projectId: string | undefined, limit = 50) {
+  return useInfiniteQuery({
+    queryKey: projectId
+      ? definitionsQueryKeys.list(projectId)
+      : [...definitionsQueryKeys.all, 'list'],
+    enabled: Boolean(projectId),
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) =>
+      listDefinitions({projectId: projectId ?? '', limit, cursor: pageParam, signal}),
+    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useDefinitionsQuery(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectId
+      ? definitionsQueryKeys.list(projectId)
+      : [...definitionsQueryKeys.all, 'list'],
+    enabled: Boolean(projectId),
+    queryFn: ({signal}) => listDefinitions({projectId: projectId ?? '', signal}),
+  });
+}

package/src/hooks/api/projects.test.ts

@@ -0,0 +1,78 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {createProject, listProjects} from './projects.js';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {'content-type': 'application/json'},
+    status: 200,
+    ...init,
+  });
+}
+
+describe('listProjects', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('includes workspace, limit, cursor, and search params', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({projects: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+
+    const result = await listProjects({
+      workspaceId: '11111111-1111-4111-8111-111111111111',
+      limit: 25,
+      cursor: 'cursor-1',
+      search: 'platform api',
+    });
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    const url = new URL(request.url);
+    expect(result.projects).toEqual([]);
+    expect(url.pathname).toBe('/projects');
+    expect(url.searchParams.get('workspace_id')).toBe('11111111-1111-4111-8111-111111111111');
+    expect(url.searchParams.get('limit')).toBe('25');
+    expect(url.searchParams.get('cursor')).toBe('cursor-1');
+    expect(url.searchParams.get('search')).toBe('platform api');
+  });
+});
+
+describe('createProject', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('posts the project body', async () => {
+    let requestBody: unknown;
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      requestBody = await (input as Request).clone().json();
+      return jsonResponse({
+        id: '44444444-4444-4444-8444-444444444444',
+        workspace_id: '11111111-1111-4111-8111-111111111111',
+        name: 'Platform',
+        source: {
+          connection_id: '33333333-3333-4333-8333-333333333333',
+          external_repository_id: 'platform',
+        },
+        created_at: '2026-05-07T01:00:00.000Z',
+        updated_at: '2026-05-07T01:00:00.000Z',
+      });
+    });
+    configureApiClient({fetchImpl});
+    const body = {
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+      name: 'Platform',
+      source: {
+        connection_id: '33333333-3333-4333-8333-333333333333',
+        external_repository_id: 'platform',
+      },
+    };
+
+    const result = await createProject(body);
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(result.name).toBe('Platform');
+    expect(request.url).toBe('https://api.example.test/projects');
+    expect(request.method).toBe('POST');
+    expect(requestBody).toEqual(body);
+  });
+});

package/src/hooks/api/projects.ts

@@ -0,0 +1,75 @@
+import type {
+  CreateProjectBodyDto,
+  ListProjectsResponseDto,
+  ProjectResponseDto,
+} from '@shipfox/api-projects-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {keepPreviousData, useInfiniteQuery, useMutation, useQuery} from '@tanstack/react-query';
+
+export const projectsQueryKeys = {
+  all: ['projects'] as const,
+  list: (workspaceId: string, search?: string) =>
+    [...projectsQueryKeys.all, 'list', workspaceId, search ?? ''] as const,
+  exists: (workspaceId: string) => [...projectsQueryKeys.all, 'exists', workspaceId] as const,
+  detail: (projectId: string) => [...projectsQueryKeys.all, 'detail', projectId] as const,
+};
+
+export async function listProjects({
+  workspaceId,
+  limit = 50,
+  cursor,
+  search,
+  signal,
+}: {
+  workspaceId: string;
+  limit?: number;
+  cursor?: string | undefined;
+  search?: string | undefined;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams({workspace_id: workspaceId, limit: String(limit)});
+  if (cursor) params.set('cursor', cursor);
+  if (search) params.set('search', search);
+
+  return await apiRequest<ListProjectsResponseDto>(`/projects?${params.toString()}`, {signal});
+}
+
+export async function getProject(projectId: string) {
+  return await apiRequest<ProjectResponseDto>(`/projects/${projectId}`);
+}
+
+export async function createProject(body: CreateProjectBodyDto) {
+  return await apiRequest<ProjectResponseDto>('/projects', {method: 'POST', body});
+}
+
+export function useProjectsInfiniteQuery(
+  workspaceId: string | undefined,
+  search?: string,
+  limit = 50,
+) {
+  return useInfiniteQuery({
+    queryKey: workspaceId
+      ? projectsQueryKeys.list(workspaceId, search)
+      : [...projectsQueryKeys.all, 'list'],
+    enabled: Boolean(workspaceId),
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) =>
+      listProjects({workspaceId: workspaceId ?? '', limit, cursor: pageParam, search, signal}),
+    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useProjectQuery(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectId
+      ? projectsQueryKeys.detail(projectId)
+      : [...projectsQueryKeys.all, 'detail'],
+    enabled: Boolean(projectId),
+    queryFn: () => getProject(projectId ?? ''),
+  });
+}
+
+export function useCreateProjectMutation() {
+  return useMutation({mutationFn: createProject});
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export type {WorkspaceSetupState} from '@shipfox/client-shell/runtime';
+export {ProjectBreadcrumb, ProjectLayoutGuard} from './chrome.js';
+export {ProjectCrumb, type ProjectCrumbProps} from './components/project-crumb.js';
+export {ProjectSwitcher, type ProjectSwitcherProps} from './components/project-switcher.js';
+export {
+  loadWorkspaceSetupRoute,
+  type WorkspaceSetupRouteOptions,
+} from './components/workspace-setup-guard.js';
+export * from './hooks/api/definitions.js';
+export * from './hooks/api/projects.js';
+export * from './pages/create-project-page.js';
+export * from './pages/home-router.js';
+export * from './pages/project-workflows-page.js';
+export * from './pages/projects-hub-page.js';
+export * from './project-error.js';