@shipfox/client-projects 12.0.1 → 13.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-projects",
   "license": "MIT",
-  "version": "12.0.1",
+  "version": "13.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,16 +27,17 @@
   "dependencies": {
     "@swc/helpers": "^0.5.17",
     "@tanstack/react-form": "^1.32.0",
-    "@shipfox/api-definitions-dto": "10.0.0",
-    "@shipfox/api-integration-core-dto": "9.0.2",
-    "@shipfox/api-projects-dto": "10.1.0",
-    "@shipfox/client-agent": "12.0.1",
+    "@shipfox/api-definitions-dto": "12.0.0",
+    "@shipfox/api-integration-core-dto": "12.0.0",
+    "@shipfox/api-projects-dto": "12.0.0",
+    "@shipfox/client-agent": "13.0.0",
     "@shipfox/client-api": "6.0.1",
-    "@shipfox/client-auth": "12.0.1",
-    "@shipfox/client-integrations": "12.0.1",
-    "@shipfox/client-shell": "12.0.1",
-    "@shipfox/client-ui": "6.0.2",
-    "@shipfox/react-ui": "0.3.7"
+    "@shipfox/client-auth": "13.0.0",
+    "@shipfox/client-integrations": "13.0.0",
+    "@shipfox/client-shell": "13.0.0",
+    "@shipfox/client-ui": "13.0.0",
+    "@shipfox/react-ui": "0.4.0",
+    "@shipfox/api-common-dto": "12.0.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",

package/src/chrome.tsx

@@ -3,29 +3,37 @@ import {
   useActiveWorkspace,
   useRouteParams,
 } from '@shipfox/client-shell/runtime';
-import {Outlet, useNavigate} from '@tanstack/react-router';
-import {useEffect} from 'react';
 import {ProjectCrumb} from '#components/project-crumb.js';
-import {useProjectQuery} from '#hooks/api/projects.js';
-import {projectRouteParams} from './routes/inputs.js';
+import {resolveProjectSlug, useProjectSlugQuery} from '#hooks/api/projects.js';
+
+export {resolveProjectSlug};
+
+export function useMaybeActiveProjectQuery() {
+  const workspace = useActiveWorkspace();
+  const {projectSlug} = useRouteParams(parseWorkspaceProjectParams);
+  return useProjectSlugQuery(workspace.id, projectSlug);
+}
+
+export function useMaybeActiveProject() {
+  return useMaybeActiveProjectQuery().data;
+}
+
+export function useActiveProject() {
+  const project = useMaybeActiveProject();
+  if (!project) throw new Error('No active project is available for this route.');
+  return project;
+}
 
 export function ProjectBreadcrumb() {
   const workspace = useActiveWorkspace();
-  const {pid} = useRouteParams(parseWorkspaceProjectParams);
-  const project = useProjectQuery(pid).data;
+  const project = useMaybeActiveProject();
   return (
-    <ProjectCrumb workspaceId={workspace.id} projectId={project?.id} projectName={project?.name} />
+    <ProjectCrumb
+      workspaceId={workspace.id}
+      workspaceSlug={workspace.slug}
+      projectId={project?.id}
+      projectSlug={project?.slug}
+      projectName={project?.name}
+    />
   );
 }
-
-export function ProjectLayoutGuard() {
-  const {wid, pid} = useRouteParams(projectRouteParams);
-  const navigate = useNavigate();
-  const project = useProjectQuery(pid).data;
-  useEffect(() => {
-    if (project && project.workspaceId !== wid)
-      void navigate({to: '/workspaces/$wid', params: {wid}, replace: true});
-  }, [navigate, project, wid]);
-  if (project && project.workspaceId !== wid) return null;
-  return <Outlet />;
-}

package/src/components/model-provider-reminder-banner.tsx

@@ -1,4 +1,5 @@
 import {useModelProviderConfigsQuery} from '@shipfox/client-agent';
+import {useActiveWorkspace} from '@shipfox/client-auth';
 import {createTypedBrowserStorage, sessionStorageOrUndefined} from '@shipfox/client-ui';
 import {
   Alert,
@@ -13,6 +14,7 @@ import {Link} from '@tanstack/react-router';
 import {useState} from 'react';
 
 export function ModelProviderReminderBanner({workspaceId}: {workspaceId: string}) {
+  const workspace = useActiveWorkspace();
   const configsQuery = useModelProviderConfigsQuery(workspaceId);
   const [dismissed, setDismissed] = useState(() => isReminderDismissed(workspaceId));
   const configs = configsQuery.data?.configs;
@@ -39,7 +41,7 @@ export function ModelProviderReminderBanner({workspaceId}: {workspaceId: string}
         </AlertDescription>
         <AlertActions>
           <Button asChild size="sm" variant="secondary">
-            <Link to="/workspaces/$wid/settings/agents" params={{wid: workspaceId}}>
+            <Link to="/w/$workspaceSlug/settings/agents" params={{workspaceSlug: workspace.slug}}>
               Agents
             </Link>
           </Button>

package/src/components/project-crumb.tsx

@@ -6,19 +6,27 @@ import {ProjectSwitcher} from './project-switcher.js';
 
 export interface ProjectCrumbProps {
   workspaceId: string;
+  workspaceSlug: string;
   projectId?: string | undefined;
+  projectSlug?: string | undefined;
   projectName?: string | undefined;
 }
 
-export function ProjectCrumb({workspaceId, projectId, projectName}: ProjectCrumbProps) {
+export function ProjectCrumb({
+  workspaceId,
+  workspaceSlug,
+  projectId,
+  projectSlug,
+  projectName,
+}: ProjectCrumbProps) {
   const [open, setOpen] = useState(false);
 
-  if (projectId && projectName) {
+  if (projectSlug && projectName) {
     return (
       <div className="flex items-center">
         <Link
-          to="/workspaces/$wid/projects/$pid"
-          params={{wid: workspaceId, pid: projectId}}
+          to="/w/$workspaceSlug/p/$projectSlug"
+          params={{workspaceSlug, projectSlug}}
           aria-current="page"
           className="text-md font-medium text-foreground-neutral-base px-6 py-4 rounded-6 hover:bg-background-components-hover transition-colors max-w-[240px] truncate"
         >
@@ -39,6 +47,7 @@ export function ProjectCrumb({workspaceId, projectId, projectName}: ProjectCrumb
           <PopoverContent className="w-[320px] p-0" align="start" sideOffset={8}>
             <ProjectSwitcher
               workspaceId={workspaceId}
+              workspaceSlug={workspaceSlug}
               activeProjectId={projectId}
               onSelect={() => setOpen(false)}
             />
@@ -63,7 +72,11 @@ export function ProjectCrumb({workspaceId, projectId, projectName}: ProjectCrumb
         </button>
       </PopoverTrigger>
       <PopoverContent className="w-[320px] p-0" align="start" sideOffset={8}>
-        <ProjectSwitcher workspaceId={workspaceId} onSelect={() => setOpen(false)} />
+        <ProjectSwitcher
+          workspaceId={workspaceId}
+          workspaceSlug={workspaceSlug}
+          onSelect={() => setOpen(false)}
+        />
       </PopoverContent>
     </Popover>
   );

package/src/components/project-switcher.test.tsx

@@ -57,16 +57,18 @@ function renderProjectSwitcher({
   const rootRoute = createRootRoute({component: Outlet});
   const workspaceRoute = createRoute({
     getParentRoute: () => rootRoute,
-    path: '/workspaces/$wid',
-    component: () => <ProjectSwitcher workspaceId={PROJECT_TEST_WID} onSelect={onSelect} />,
+    path: '/w/$workspaceSlug',
+    component: () => (
+      <ProjectSwitcher workspaceId={PROJECT_TEST_WID} workspaceSlug="acme" onSelect={onSelect} />
+    ),
   });
   const createProjectRoute = createRoute({
     getParentRoute: () => rootRoute,
-    path: '/workspaces/$wid/projects/new',
+    path: '/w/$workspaceSlug/projects/new',
     component: () => <div data-testid="create-project-route">Create project route</div>,
   });
   const router = createRouter({
-    history: createMemoryHistory({initialEntries: [`/workspaces/${PROJECT_TEST_WID}`]}),
+    history: createMemoryHistory({initialEntries: ['/w/acme']}),
     routeTree: rootRoute.addChildren([workspaceRoute, createProjectRoute]),
   });
 
@@ -82,6 +84,7 @@ function projectDto({id, name}: {id: string; name: string}) {
     id,
     workspace_id: PROJECT_TEST_WID,
     name,
+    slug: name.toLowerCase(),
     source: {
       connection_id: '33333333-3333-4333-8333-333333333333',
       external_repository_id: name.toLowerCase(),

package/src/components/project-switcher.tsx

@@ -14,11 +14,17 @@ import {useProjectsInfiniteQuery} from '#hooks/api/projects.js';
 
 export interface ProjectSwitcherProps {
   workspaceId: string;
+  workspaceSlug: string;
   activeProjectId?: string | undefined;
   onSelect?: () => void;
 }
 
-export function ProjectSwitcher({workspaceId, activeProjectId, onSelect}: ProjectSwitcherProps) {
+export function ProjectSwitcher({
+  workspaceId,
+  workspaceSlug,
+  activeProjectId,
+  onSelect,
+}: ProjectSwitcherProps) {
   const navigate = useNavigate();
   const [searchValue, setSearchValue] = useState('');
   const query = useProjectsInfiniteQuery(workspaceId);
@@ -33,20 +39,25 @@ export function ProjectSwitcher({workspaceId, activeProjectId, onSelect}: Projec
   }, [query.hasNextPage, query.isFetchingNextPage, query.fetchNextPage]);
 
   const handleSelect = (projectId: string) => {
+    const project = projects.find((candidate) => candidate.id === projectId);
+    if (!project) return;
     navigate({
-      to: '/workspaces/$wid/projects/$pid',
-      params: {wid: workspaceId, pid: projectId},
+      to: '/w/$workspaceSlug/p/$projectSlug',
+      params: {
+        workspaceSlug,
+        projectSlug: project.slug,
+      },
     });
     onSelect?.();
   };
 
   const handleSelectAll = () => {
-    navigate({to: '/workspaces/$wid', params: {wid: workspaceId}});
+    navigate({to: '/w/$workspaceSlug', params: {workspaceSlug}});
     onSelect?.();
   };
 
   const handleCreate = () => {
-    navigate({to: '/workspaces/$wid/projects/new', params: {wid: workspaceId}});
+    navigate({to: '/w/$workspaceSlug/projects/new', params: {workspaceSlug}});
     onSelect?.();
   };
 

package/src/core/definition.ts

@@ -22,6 +22,13 @@ export interface DefinitionSyncSummary {
   finishedAt: string | null;
   lastErrorCode: string | null;
   lastErrorMessage: string | null;
+  warnings: DefinitionSyncWarning[];
+}
+
+export interface DefinitionSyncWarning {
+  code: string;
+  message: string;
+  path?: string | undefined;
 }
 
 export interface DefinitionList {

package/src/core/project.ts

@@ -7,6 +7,7 @@ export interface Project {
   id: string;
   workspaceId: string;
   name: string;
+  slug: string;
   source: ProjectSource;
   createdAt: string;
   updatedAt: string;
@@ -20,9 +21,16 @@ export interface ProjectList {
 export interface CreateProjectCommand {
   workspaceId: string;
   name: string;
+  slug: string;
   source: ProjectSource;
 }
 
+export interface UpdateProjectCommand {
+  projectId: string;
+  name?: string;
+  slug?: string;
+}
+
 const REPOSITORY_NAME_SPLIT_RE = /[/-]/;
 
 export function projectNameFromRepository(repositoryId: string): string {

package/src/feature.ts

@@ -5,30 +5,52 @@ export const projectsNavigation = [
     id: 'nav.projects',
     scope: 'workspace',
     label: 'Projects',
-    to: '/workspaces/$wid',
+    to: '/w/$workspaceSlug',
     exact: true,
     order: 100,
   },
 ] as const satisfies readonly NavTabEntry[];
 
+export const projectSettingsSections = [
+  {
+    id: 'settings.project-general',
+    scope: 'project',
+    pathSegment: 'general',
+    label: 'General',
+    icon: 'settings3Line',
+    order: 50,
+  },
+] as const;
+
 export const projectsFeature = defineClientFeature({
   id: 'shipfox.projects',
   routes: [
     {
-      path: '/workspaces/$wid',
+      path: '/w/$workspaceSlug',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-projects/routes/home',
     },
     {
-      path: '/workspaces/$wid/projects/new',
+      path: '/w/$workspaceSlug/projects/new',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-projects/routes/create-project',
     },
     {
-      path: '/workspaces/$wid/projects/$pid',
+      path: '/w/$workspaceSlug/p/$projectSlug',
       parent: 'projectLayout',
       impl: '@shipfox/client-projects/routes/project-index',
     },
+    {
+      path: '/w/$workspaceSlug/p/$projectSlug/settings',
+      parent: 'projectSettings',
+      impl: '@shipfox/client-projects/routes/project-settings-index',
+    },
+    {
+      path: '/w/$workspaceSlug/p/$projectSlug/settings/general',
+      parent: 'projectSettings',
+      impl: '@shipfox/client-projects/routes/project-settings',
+    },
   ],
   navigation: projectsNavigation,
+  settingsSections: projectSettingsSections,
 });

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

@@ -0,0 +1,19 @@
+import {toDefinitionSyncSummary} from './mappers.js';
+
+describe('toDefinitionSyncSummary', () => {
+  it('preserves warnings without manufacturing a missing path', () => {
+    const summary = toDefinitionSyncSummary({
+      ref: 'main',
+      status: 'succeeded',
+      last_sync_at: '2026-05-07T01:00:00.000Z',
+      started_at: '2026-05-07T00:59:55.000Z',
+      finished_at: '2026-05-07T01:00:00.000Z',
+      last_error_code: null,
+      last_error_message: null,
+      warnings: [{code: 'warning-code', message: 'Warning without a path'}],
+    });
+
+    expect(summary.warnings).toEqual([{code: 'warning-code', message: 'Warning without a path'}]);
+    expect(summary.warnings[0]).not.toHaveProperty('path');
+  });
+});

package/src/hooks/api/mappers.ts

@@ -8,6 +8,7 @@ export function toProject(dto: ProjectResponseDto): Project {
     id: dto.id,
     workspaceId: dto.workspace_id,
     name: dto.name,
+    slug: dto.slug,
     source: {
       connectionId: dto.source.connection_id,
       externalRepositoryId: dto.source.external_repository_id,
@@ -51,6 +52,11 @@ export function toDefinitionSyncSummary(dto: DefinitionSyncSummaryDto): Definiti
     finishedAt: dto.finished_at,
     lastErrorCode: dto.last_error_code,
     lastErrorMessage: dto.last_error_message,
+    warnings: dto.warnings.map((warning) => ({
+      code: warning.code,
+      message: warning.message,
+      ...(warning.path === undefined ? {} : {path: warning.path}),
+    })),
   };
 }
 

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

@@ -1,5 +1,15 @@
 import {configureApiClient} from '@shipfox/client-api';
-import {createProject, listProjects} from './projects.js';
+import {QueryClient} from '@tanstack/react-query';
+import {
+  createProject,
+  isProjectSlugAvailable,
+  listProjects,
+  projectSlugQueryOptions,
+  projectsInfiniteQueryOptions,
+  projectsQueryKeys,
+  resolveProjectSlug,
+  updateProject,
+} from './projects.js';
 
 function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
   return new Response(JSON.stringify(body), {
@@ -49,6 +59,7 @@ describe('createProject', () => {
         id: '44444444-4444-4444-8444-444444444444',
         workspace_id: '11111111-1111-4111-8111-111111111111',
         name: 'Platform',
+        slug: 'platform',
         source: {
           connection_id: '33333333-3333-4333-8333-333333333333',
           external_repository_id: 'platform',
@@ -61,6 +72,7 @@ describe('createProject', () => {
     const body = {
       workspaceId: '11111111-1111-4111-8111-111111111111',
       name: 'Platform',
+      slug: 'platform',
       source: {
         connectionId: '33333333-3333-4333-8333-333333333333',
         externalRepositoryId: 'platform',
@@ -71,11 +83,13 @@ describe('createProject', () => {
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
     expect(result.name).toBe('Platform');
+    expect(result.slug).toBe('platform');
     expect(request.url).toBe('https://api.example.test/projects');
     expect(request.method).toBe('POST');
     expect(requestBody).toEqual({
       workspace_id: body.workspaceId,
       name: body.name,
+      slug: body.slug,
       source: {
         connection_id: body.source.connectionId,
         external_repository_id: body.source.externalRepositoryId,
@@ -83,3 +97,235 @@ describe('createProject', () => {
     });
   });
 });
+
+describe('updateProject', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('patches the project body', async () => {
+    let requestBody: unknown;
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      requestBody = await (input as Request).clone().json();
+      return jsonResponse(projectResponse('renamed-project'));
+    });
+    configureApiClient({fetchImpl});
+
+    const result = await updateProject({
+      projectId: '33333333-3333-4333-8333-333333333333',
+      name: 'Renamed project',
+      slug: 'renamed-project',
+    });
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(result.slug).toBe('renamed-project');
+    expect(request.url).toBe(
+      'https://api.example.test/projects/33333333-3333-4333-8333-333333333333',
+    );
+    expect(request.method).toBe('PATCH');
+    expect(requestBody).toEqual({name: 'Renamed project', slug: 'renamed-project'});
+  });
+});
+
+describe('isProjectSlugAvailable', () => {
+  test('uses cached project lists without making a request', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const queryClient = new QueryClient();
+    queryClient.setQueryData(projectsQueryKeys.list(workspaceId, 'taken'), {
+      pages: [
+        {
+          projects: [projectResponse('taken-project')],
+          nextCursor: null,
+        },
+      ],
+      pageParams: [undefined],
+    });
+
+    expect(isProjectSlugAvailable({queryClient, workspaceId, projectSlug: 'taken-project'})).toBe(
+      false,
+    );
+    expect(
+      isProjectSlugAvailable({
+        queryClient,
+        workspaceId,
+        projectSlug: 'taken-project',
+        currentProjectId: '33333333-3333-4333-8333-333333333333',
+      }),
+    ).toBe(true);
+    expect(isProjectSlugAvailable({queryClient, workspaceId, projectSlug: 'new-project'})).toBe(
+      true,
+    );
+  });
+});
+
+describe('resolveProjectSlug', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('refreshes the cached list once after an exhausted slug search', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const projectId = '44444444-4444-4444-8444-444444444444';
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('old-project')], next_cursor: null}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('new-project', projectId)], next_cursor: null}),
+      );
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await queryClient.fetchInfiniteQuery(projectsInfiniteQueryOptions(workspaceId));
+
+    await expect(
+      resolveProjectSlug({queryClient, workspaceId, projectSlug: 'new-project'}),
+    ).resolves.toBe(projectId);
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  test('revalidates a cached slug match before returning it', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const projectId = '44444444-4444-4444-8444-444444444444';
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('checkout-api', projectId)], next_cursor: null}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('renamed-api', projectId)], next_cursor: null}),
+      );
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await queryClient.fetchInfiniteQuery(projectsInfiniteQueryOptions(workspaceId));
+    queryClient.setQueryData(
+      projectsQueryKeys.list(workspaceId),
+      queryClient.getQueryData(projectsQueryKeys.list(workspaceId)),
+      {updatedAt: 0},
+    );
+
+    await expect(
+      resolveProjectSlug({queryClient, workspaceId, projectSlug: 'checkout-api'}),
+    ).resolves.toBeUndefined();
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  test('uses a fresh cached slug and hydrates the detail query', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const projectId = '44444444-4444-4444-8444-444444444444';
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('checkout-api', projectId)], next_cursor: null}),
+      );
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await queryClient.fetchInfiniteQuery(projectsInfiniteQueryOptions(workspaceId));
+
+    await expect(
+      resolveProjectSlug({queryClient, workspaceId, projectSlug: 'checkout-api'}),
+    ).resolves.toBe(projectId);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(queryClient.getQueryData(projectsQueryKeys.detail(projectId))).toMatchObject({
+      id: projectId,
+      slug: 'checkout-api',
+    });
+  });
+
+  test('paginates from the refreshed first page after a cached miss', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const projectId = '44444444-4444-4444-8444-444444444444';
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({
+          projects: [projectResponse('new-project', '55555555-5555-4555-8555-555555555555')],
+          next_cursor: 'cursor-1',
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('first-project')], next_cursor: 'cursor-1'}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('new-project', projectId)], next_cursor: null}),
+      );
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await queryClient.fetchInfiniteQuery(projectsInfiniteQueryOptions(workspaceId));
+    queryClient.setQueryData(
+      projectsQueryKeys.list(workspaceId),
+      queryClient.getQueryData(projectsQueryKeys.list(workspaceId)),
+      {updatedAt: 0},
+    );
+
+    await expect(
+      resolveProjectSlug({queryClient, workspaceId, projectSlug: 'new-project'}),
+    ).resolves.toBe(projectId);
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+  });
+
+  test('paginates slug search results until it finds the exact slug', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const projectId = '44444444-4444-4444-8444-444444444444';
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('old-project')], next_cursor: null}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('still-old')], next_cursor: 'cursor-1'}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('matching-name')], next_cursor: 'cursor-1'}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({projects: [projectResponse('target-project', projectId)], next_cursor: null}),
+      );
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await queryClient.fetchInfiniteQuery(projectsInfiniteQueryOptions(workspaceId));
+
+    await expect(
+      resolveProjectSlug({queryClient, workspaceId, projectSlug: 'target-project'}),
+    ).resolves.toBe(projectId);
+    expect(fetchImpl).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe('projectSlugQueryOptions', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('represents an unknown slug with null query data', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({projects: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+    const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+    await expect(
+      queryClient.fetchQuery(
+        projectSlugQueryOptions('11111111-1111-4111-8111-111111111111', 'missing-project'),
+      ),
+    ).resolves.toBeNull();
+  });
+});
+
+function projectResponse(slug: string, id = '33333333-3333-4333-8333-333333333333') {
+  return {
+    id,
+    workspace_id: '11111111-1111-4111-8111-111111111111',
+    name: slug,
+    slug,
+    source: {
+      connection_id: '22222222-2222-4222-8222-222222222222',
+      external_repository_id: slug,
+    },
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  };
+}