refactor: move project star state from localStorage to backend

src/components/sidebar/hooks/useSidebarController.ts

@@ -10,10 +10,10 @@ import type {
   SessionWithProvider,
 } from '../types/types';
 import {
+  clearLegacyStarredProjectIds,
   filterProjects,
   getAllSessions,
-  loadStarredProjects,
-  persistStarredProjects,
+  readLegacyStarredProjectIds,
   readProjectSortOrder,
   sortProjects,
 } from '../utils/utils';
@@ -108,7 +108,6 @@ export function useSidebarController({
   const [deleteConfirmation, setDeleteConfirmation] = useState<DeleteProjectConfirmation | null>(null);
   const [sessionDeleteConfirmation, setSessionDeleteConfirmation] = useState<SessionDeleteConfirmation | null>(null);
   const [showVersionModal, setShowVersionModal] = useState(false);
-  const [starredProjects, setStarredProjects] = useState<Set<string>>(() => loadStarredProjects());
   const [searchMode, setSearchMode] = useState<'projects' | 'conversations'>('projects');
   const [conversationResults, setConversationResults] = useState<ConversationSearchResults | null>(null);
   const [isSearching, setIsSearching] = useState(false);
@@ -185,6 +184,34 @@ export function useSidebarController({
     };
   }, []);
 
+  useEffect(() => {
+    const legacyStarredProjectIds = readLegacyStarredProjectIds();
+    if (legacyStarredProjectIds.length === 0) {
+      return;
+    }
+
+    let active = true;
+
+    const migrateLegacyStars = async () => {
+      try {
+        await api.migrateLegacyProjectStars(legacyStarredProjectIds);
+        if (active) {
+          await onRefresh();
+        }
+      } catch (error) {
+        console.error('[Sidebar] Failed to migrate legacy starred projects:', error);
+      } finally {
+        clearLegacyStarredProjectIds();
+      }
+    };
+
+    void migrateLegacyStars();
+
+    return () => {
+      active = false;
+    };
+  }, [onRefresh]);
+
   // Debounced conversation search with SSE streaming
   useEffect(() => {
     if (searchTimeoutRef.current) {
@@ -317,30 +344,39 @@ export function useSidebarController({
   );
 
   const toggleStarProject = useCallback((projectId: string) => {
-    setStarredProjects((prev) => {
-      const next = new Set(prev);
-      if (next.has(projectId)) {
-        next.delete(projectId);
-      } else {
-        next.add(projectId);
-      }
+    const updateStar = async () => {
+      try {
+        const response = await api.toggleProjectStar(projectId);
+        if (!response.ok) {
+          const payload = (await response.json()) as { error?: string | { message?: string } };
+          const errorPayload = payload.error;
+          const message =
+            typeof errorPayload === 'string'
+              ? errorPayload
+              : errorPayload && typeof errorPayload === 'object' && errorPayload.message
+                ? errorPayload.message
+                : t('messages.updateProjectError');
+          throw new Error(message);
+        }
 
-      persistStarredProjects(next);
-      return next;
-    });
-  }, []);
+        await onRefresh();
+      } catch (error) {
+        console.error('[Sidebar] Failed to toggle project star:', error);
+        alert(t('messages.updateProjectError'));
+      }
+    };
+
+    void updateStar();
+  }, [onRefresh, t]);
 
   const isProjectStarred = useCallback(
-    (projectId: string) => starredProjects.has(projectId),
-    [starredProjects],
+    (projectId: string) => projects.some((project) => project.projectId === projectId && Boolean(project.isStarred)),
+    [projects],
   );
 
   const getProjectSessions = useCallback((project: Project) => getAllSessions(project), []);
 
-  const sortedProjects = useMemo(
-    () => sortProjects(projects, projectSortOrder, starredProjects),
-    [projectSortOrder, projects, starredProjects],
-  );
+  const sortedProjects = useMemo(() => sortProjects(projects, projectSortOrder), [projectSortOrder, projects]);
 
   const filteredProjects = useMemo(
     () => filterProjects(sortedProjects, searchFilter),
@@ -550,7 +586,6 @@ export function useSidebarController({
     deleteConfirmation,
     sessionDeleteConfirmation,
     showVersionModal,
-    starredProjects,
     filteredProjects,
     toggleProject,
     handleSessionClick,

src/components/sidebar/utils/utils.ts

@@ -16,20 +16,39 @@ export const readProjectSortOrder = (): ProjectSortOrder => {
   }
 };
 
-export const loadStarredProjects = (): Set<string> => {
+const LEGACY_STARRED_PROJECTS_STORAGE_KEY = 'starredProjects';
+
+/**
+ * Reads legacy project stars from localStorage (used only for one-time migration to backend).
+ */
+export const readLegacyStarredProjectIds = (): string[] => {
   try {
-    const saved = localStorage.getItem('starredProjects');
-    return saved ? new Set<string>(JSON.parse(saved)) : new Set<string>();
+    const saved = localStorage.getItem(LEGACY_STARRED_PROJECTS_STORAGE_KEY);
+    if (!saved) {
+      return [];
+    }
+
+    const parsed = JSON.parse(saved) as unknown;
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+
+    return parsed
+      .map((value) => String(value).trim())
+      .filter((value) => value.length > 0);
   } catch {
-    return new Set<string>();
+    return [];
   }
 };
 
-export const persistStarredProjects = (starredProjects: Set<string>) => {
+/**
+ * Clears the legacy localStorage stars key after migration to backend completes.
+ */
+export const clearLegacyStarredProjectIds = () => {
   try {
-    localStorage.setItem('starredProjects', JSON.stringify([...starredProjects]));
+    localStorage.removeItem(LEGACY_STARRED_PROJECTS_STORAGE_KEY);
   } catch {
-    // Keep UI responsive even if storage fails.
+    // Keep UI responsive even if storage is unavailable.
   }
 };
 
@@ -133,14 +152,13 @@ export const getProjectLastActivity = (project: Project): Date => {
 export const sortProjects = (
   projects: Project[],
   projectSortOrder: ProjectSortOrder,
-  starredProjects: Set<string>,
 ): Project[] => {
   const byName = [...projects];
 
   byName.sort((projectA, projectB) => {
-    // Starred projects are tracked by `projectId` in localStorage.
-    const aStarred = starredProjects.has(projectA.projectId);
-    const bStarred = starredProjects.has(projectB.projectId);
+    // Star order now comes from backend `projects.isStarred`.
+    const aStarred = Boolean(projectA.isStarred);
+    const bStarred = Boolean(projectB.isStarred);
 
     if (aStarred && !bStarred) {
       return -1;

src/hooks/useProjectsState.ts

@@ -44,6 +44,7 @@ const projectsHaveChanges = (
       nextProject.projectId !== prevProject.projectId ||
       nextProject.displayName !== prevProject.displayName ||
       nextProject.fullPath !== prevProject.fullPath ||
+      Boolean(nextProject.isStarred) !== Boolean(prevProject.isStarred) ||
       serialize(nextProject.sessionMeta) !== serialize(prevProject.sessionMeta) ||
       serialize(nextProject.sessions) !== serialize(prevProject.sessions) ||
       serialize(nextProject.taskmaster) !== serialize(prevProject.taskmaster);

src/types/app.ts

@@ -41,6 +41,7 @@ export interface Project {
   displayName: string;
   fullPath: string;
   path?: string;
+  isStarred?: boolean;
   sessions?: ProjectSession[];
   cursorSessions?: ProjectSession[];
   codexSessions?: ProjectSession[];

src/utils/api.js

@@ -113,6 +113,15 @@ export const api = {
       method: 'POST',
       body: JSON.stringify(projectData),
     }),
+  migrateLegacyProjectStars: (projectIds) =>
+    authenticatedFetch('/api/projects/migrate-legacy-stars', {
+      method: 'POST',
+      body: JSON.stringify({ projectIds }),
+    }),
+  toggleProjectStar: (projectId) =>
+    authenticatedFetch(`/api/projects/${encodeURIComponent(projectId)}/toggle-star`, {
+      method: 'POST',
+    }),
   readFile: (projectId, filePath) =>
     authenticatedFetch(`/api/projects/${projectId}/file?filePath=${encodeURIComponent(filePath)}`),
   readFileBlob: (projectId, filePath) =>