@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/hooks/sync/useRecentSyncEvents.d.ts

@@ -0,0 +1,21 @@
+import { type SyncEventRecord } from '../../utils/syncEventPresentation';
+interface UseRecentSyncEventsInput {
+    isOpen: boolean;
+    workspaceId: string;
+    refreshKeys: ReadonlyArray<string | null | undefined>;
+}
+export interface PendingSyncEventsScrollRestore {
+    scrollTop: number;
+    scrollHeight: number;
+}
+interface UseRecentSyncEventsResult {
+    syncRecentEvents: SyncEventRecord[];
+    syncRecentEventsLoading: boolean;
+    syncRecentEventsError: string | null;
+    syncEventsListRef: React.RefObject<HTMLDivElement | null>;
+    loadRecentSyncEvents: () => Promise<SyncEventRecord[]>;
+}
+export declare function useRecentSyncEvents({ isOpen, workspaceId, refreshKeys, }: UseRecentSyncEventsInput): UseRecentSyncEventsResult;
+export declare function capturePendingSyncEventsScrollRestore(listEl: HTMLDivElement | null): PendingSyncEventsScrollRestore | null;
+export declare function restorePendingSyncEventsScrollRestore(listEl: HTMLDivElement | null, pendingRestore: PendingSyncEventsScrollRestore | null): null;
+export {};

package/dist/hooks/sync/useRecentSyncEvents.js

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { areSyncEventListsEqual, mergeRecentSyncEvents, } from '../../utils/syncEventPresentation';
+export function useRecentSyncEvents({ isOpen, workspaceId, refreshKeys, }) {
+    const [syncRecentEvents, setSyncRecentEvents] = useState([]);
+    const [syncRecentEventsLoading, setSyncRecentEventsLoading] = useState(false);
+    const [syncRecentEventsError, setSyncRecentEventsError] = useState(null);
+    const syncEventsListRef = useRef(null);
+    const pendingSyncEventsScrollRestoreRef = useRef(null);
+    useLayoutEffect(() => {
+        pendingSyncEventsScrollRestoreRef.current = restorePendingSyncEventsScrollRestore(syncEventsListRef.current, pendingSyncEventsScrollRestoreRef.current);
+    }, [syncRecentEvents]);
+    const loadRecentSyncEvents = useCallback(async () => {
+        const res = await fetch(`/api/taskforce/sync/events?workspace_id=${encodeURIComponent(workspaceId)}&limit=15`, {
+            method: 'GET',
+            credentials: 'include'
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to load sync events (${res.status})`);
+        }
+        const data = await res.json().catch(() => ({}));
+        return Array.isArray(data?.events)
+            ? data.events.filter((event) => event && typeof event === 'object')
+            : [];
+    }, [workspaceId]);
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        let cancelled = false;
+        const isInitialLoad = syncRecentEvents.length === 0;
+        if (isInitialLoad) {
+            setSyncRecentEventsLoading(true);
+        }
+        void loadRecentSyncEvents()
+            .then((events) => {
+            if (cancelled)
+                return;
+            pendingSyncEventsScrollRestoreRef.current = capturePendingSyncEventsScrollRestore(syncEventsListRef.current);
+            setSyncRecentEvents((current) => {
+                const next = current.length === 0 ? events : mergeRecentSyncEvents(current, events, 15);
+                return areSyncEventListsEqual(current, next) ? current : next;
+            });
+            setSyncRecentEventsError(null);
+        })
+            .catch((error) => {
+            if (cancelled)
+                return;
+            const message = error instanceof Error && error.message.trim().length > 0
+                ? error.message.trim()
+                : 'Unable to load recent sync events.';
+            setSyncRecentEventsError(message);
+            if (isInitialLoad) {
+                setSyncRecentEvents([]);
+            }
+        })
+            .finally(() => {
+            if (cancelled)
+                return;
+            if (isInitialLoad) {
+                setSyncRecentEventsLoading(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        isOpen,
+        loadRecentSyncEvents,
+        ...refreshKeys,
+    ]);
+    return {
+        syncRecentEvents,
+        syncRecentEventsLoading,
+        syncRecentEventsError,
+        syncEventsListRef,
+        loadRecentSyncEvents,
+    };
+}
+export function capturePendingSyncEventsScrollRestore(listEl) {
+    return listEl && listEl.scrollTop > 8
+        ? {
+            scrollTop: listEl.scrollTop,
+            scrollHeight: listEl.scrollHeight
+        }
+        : null;
+}
+export function restorePendingSyncEventsScrollRestore(listEl, pendingRestore) {
+    if (!pendingRestore || !listEl)
+        return null;
+    const delta = listEl.scrollHeight - pendingRestore.scrollHeight;
+    listEl.scrollTop = pendingRestore.scrollTop + Math.max(0, delta);
+    return null;
+}

package/dist/hooks/sync/useRecentSyncEvents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/sync/useRecentSyncEvents.test.js

@@ -0,0 +1,124 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { capturePendingSyncEventsScrollRestore, restorePendingSyncEventsScrollRestore, useRecentSyncEvents, } from './useRecentSyncEvents';
+describe('useRecentSyncEvents', () => {
+    const fetchMock = vi.fn();
+    beforeEach(() => {
+        fetchMock.mockReset();
+        vi.stubGlobal('fetch', fetchMock);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it('does not fetch recent sync events while the modal is closed', () => {
+        renderHook(() => useRecentSyncEvents({
+            isOpen: false,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['a'],
+        }));
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it('loads recent sync events when the modal opens', async () => {
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 1,
+                        occurredAt: '2026-04-18T12:00:00.000Z',
+                        eventType: 'pull',
+                        status: 'success',
+                    }],
+            }),
+        });
+        const { result } = renderHook(() => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['2026-04-18T12:00:00.000Z'],
+        }));
+        await waitFor(() => {
+            expect(result.current.syncRecentEventsLoading).toBe(false);
+            expect(result.current.syncRecentEvents).toHaveLength(1);
+        });
+        expect(fetchMock).toHaveBeenCalledWith('/api/taskforce/sync/events?workspace_id=workspace-1&limit=15', expect.objectContaining({
+            method: 'GET',
+            credentials: 'include',
+        }));
+        expect(result.current.syncRecentEventsError).toBeNull();
+    });
+    it('stores a readable error when the fetch fails', async () => {
+        fetchMock.mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: async () => ({}),
+        });
+        const { result } = renderHook(() => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['2026-04-18T12:00:00.000Z'],
+        }));
+        await waitFor(() => {
+            expect(result.current.syncRecentEventsLoading).toBe(false);
+            expect(result.current.syncRecentEventsError).toBe('Failed to load sync events (503)');
+        });
+        expect(result.current.syncRecentEvents).toEqual([]);
+    });
+    it('merges refreshed events into the recent event list', async () => {
+        fetchMock
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 1,
+                        occurredAt: '2026-04-18T12:00:00.000Z',
+                        eventType: 'pull',
+                        status: 'success',
+                    }],
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 2,
+                        occurredAt: '2026-04-18T12:01:00.000Z',
+                        eventType: 'push',
+                        status: 'success',
+                    }],
+            }),
+        });
+        const { result, rerender } = renderHook(({ refreshKey }) => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: [refreshKey],
+        }), {
+            initialProps: { refreshKey: 'first' },
+        });
+        await waitFor(() => {
+            expect(result.current.syncRecentEvents).toHaveLength(1);
+        });
+        rerender({ refreshKey: 'second' });
+        await waitFor(() => {
+            expect(result.current.syncRecentEvents).toHaveLength(2);
+        });
+    });
+    it('captures and restores list scroll offset when the event list grows', () => {
+        let scrollHeight = 100;
+        const listEl = document.createElement('div');
+        Object.defineProperty(listEl, 'scrollTop', {
+            value: 24,
+            writable: true,
+        });
+        Object.defineProperty(listEl, 'scrollHeight', {
+            get: () => scrollHeight,
+        });
+        const pendingRestore = capturePendingSyncEventsScrollRestore(listEl);
+        expect(pendingRestore).toEqual({
+            scrollTop: 24,
+            scrollHeight: 100,
+        });
+        scrollHeight = 140;
+        const result = restorePendingSyncEventsScrollRestore(listEl, pendingRestore);
+        expect(result).toBeNull();
+        expect(listEl.scrollTop).toBe(64);
+    });
+});

package/dist/hooks/sync/useSyncStatusActions.d.ts

@@ -0,0 +1,30 @@
+import { type WorkspaceSyncDiagnosticsPresentation } from '../../utils/syncStatusPresentation';
+import type { SyncEventRecord } from '../../utils/syncEventPresentation';
+interface UseSyncStatusActionsInput {
+    currentWorkspaceId: string;
+    syncStatusLabel: string;
+    workspaceSyncSummary: string;
+    workspaceSyncRecommendedAction: string;
+    formattedLastSyncTime: string;
+    formattedLastPullTime: string;
+    formattedLastPushTime: string;
+    workspaceSyncDiagnostics: WorkspaceSyncDiagnosticsPresentation;
+    workspaceSyncPendingChanges: string | number;
+    syncLastError: string;
+    workspaceSyncPhase: string;
+    referenceMismatchCount: number;
+    syncRecentEvents: SyncEventRecord[];
+    loadRecentSyncEvents: () => Promise<SyncEventRecord[]>;
+    pushNotice: (message: string, tone: 'success' | 'error') => void;
+    resetWorkspaceSyncCursorAndPull: () => Promise<void>;
+    workspaceSyncBusy: boolean;
+}
+interface UseSyncStatusActionsResult {
+    workspaceSyncRepairBusy: boolean;
+    workspaceSyncRepairQueued: boolean;
+    workspaceSyncCopied: boolean;
+    handleCopySyncDetails: () => Promise<void>;
+    handleQueueOrRunRepairSync: () => void;
+}
+export declare function useSyncStatusActions({ currentWorkspaceId, syncStatusLabel, workspaceSyncSummary, workspaceSyncRecommendedAction, formattedLastSyncTime, formattedLastPullTime, formattedLastPushTime, workspaceSyncDiagnostics, workspaceSyncPendingChanges, syncLastError, workspaceSyncPhase, referenceMismatchCount, syncRecentEvents, loadRecentSyncEvents, pushNotice, resetWorkspaceSyncCursorAndPull, workspaceSyncBusy, }: UseSyncStatusActionsInput): UseSyncStatusActionsResult;
+export {};

package/dist/hooks/sync/useSyncStatusActions.js

@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useState } from 'react';
+import { buildCopySyncDetailsText, resolveSyncStageLabel, } from '../../utils/syncStatusPresentation';
+export function useSyncStatusActions({ currentWorkspaceId, syncStatusLabel, workspaceSyncSummary, workspaceSyncRecommendedAction, formattedLastSyncTime, formattedLastPullTime, formattedLastPushTime, workspaceSyncDiagnostics, workspaceSyncPendingChanges, syncLastError, workspaceSyncPhase, referenceMismatchCount, syncRecentEvents, loadRecentSyncEvents, pushNotice, resetWorkspaceSyncCursorAndPull, workspaceSyncBusy, }) {
+    const [workspaceSyncRepairBusy, setWorkspaceSyncRepairBusy] = useState(false);
+    const [workspaceSyncRepairQueued, setWorkspaceSyncRepairQueued] = useState(false);
+    const [workspaceSyncCopied, setWorkspaceSyncCopied] = useState(false);
+    const handleCopySyncDetails = useCallback(async () => {
+        try {
+            const events = syncRecentEvents.length > 0 ? syncRecentEvents : await loadRecentSyncEvents();
+            const copyText = buildCopySyncDetailsText({
+                currentWorkspaceId,
+                syncStatusLabel,
+                workspaceSyncSummary,
+                workspaceSyncRecommendedAction,
+                formattedLastSyncTime,
+                formattedLastPullTime,
+                formattedLastPushTime,
+                workspaceSyncDiagnostics,
+                workspaceSyncPendingChanges,
+                syncLastError,
+                syncStageLabel: resolveSyncStageLabel(workspaceSyncPhase, workspaceSyncRepairBusy, workspaceSyncBusy),
+                referenceMismatchCount,
+                syncRecentEvents: events
+            });
+            await navigator.clipboard.writeText(copyText);
+            setWorkspaceSyncCopied(true);
+            window.setTimeout(() => {
+                setWorkspaceSyncCopied(false);
+            }, 1800);
+            pushNotice('Sync details copied to clipboard.', 'success');
+        }
+        catch {
+            setWorkspaceSyncCopied(false);
+            pushNotice('Failed to copy sync details.', 'error');
+        }
+    }, [
+        currentWorkspaceId,
+        formattedLastPullTime,
+        formattedLastPushTime,
+        formattedLastSyncTime,
+        loadRecentSyncEvents,
+        pushNotice,
+        referenceMismatchCount,
+        syncLastError,
+        syncRecentEvents,
+        syncStatusLabel,
+        workspaceSyncDiagnostics,
+        workspaceSyncPhase,
+        workspaceSyncPendingChanges,
+        workspaceSyncRecommendedAction,
+        workspaceSyncSummary,
+        workspaceSyncBusy,
+        workspaceSyncRepairBusy,
+    ]);
+    const handleRepairSync = useCallback(async () => {
+        setWorkspaceSyncRepairQueued(false);
+        setWorkspaceSyncRepairBusy(true);
+        try {
+            await resetWorkspaceSyncCursorAndPull();
+        }
+        finally {
+            setWorkspaceSyncRepairBusy(false);
+        }
+    }, [resetWorkspaceSyncCursorAndPull]);
+    const handleQueueOrRunRepairSync = useCallback(() => {
+        if (workspaceSyncRepairBusy)
+            return;
+        if (workspaceSyncBusy) {
+            setWorkspaceSyncRepairQueued(true);
+            return;
+        }
+        void handleRepairSync();
+    }, [handleRepairSync, workspaceSyncBusy, workspaceSyncRepairBusy]);
+    useEffect(() => {
+        if (!workspaceSyncRepairQueued)
+            return;
+        if (workspaceSyncBusy || workspaceSyncRepairBusy)
+            return;
+        void handleRepairSync();
+    }, [handleRepairSync, workspaceSyncBusy, workspaceSyncRepairBusy, workspaceSyncRepairQueued]);
+    return {
+        workspaceSyncRepairBusy,
+        workspaceSyncRepairQueued,
+        workspaceSyncCopied,
+        handleCopySyncDetails,
+        handleQueueOrRunRepairSync,
+    };
+}

package/dist/hooks/sync/useSyncStatusActions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/sync/useSyncStatusActions.test.js

@@ -0,0 +1,133 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useSyncStatusActions } from './useSyncStatusActions';
+function makeInput(overrides) {
+    return {
+        currentWorkspaceId: 'workspace-1',
+        syncStatusLabel: 'Healthy',
+        workspaceSyncSummary: 'Sync is healthy.',
+        workspaceSyncRecommendedAction: 'No action needed.',
+        formattedLastSyncTime: '4/17/2026, 10:32:47 PM',
+        formattedLastPullTime: '4/17/2026, 10:32:47 PM',
+        formattedLastPushTime: '4/17/2026, 10:31:45 PM',
+        workspaceSyncDiagnostics: {
+            aiProfileSnapshotCount: 1,
+            aiProfileSnapshotRawCount: 1,
+            lastPushedAiProfileCount: 1,
+            lastPushedAiProfileWatermarkCount: 1,
+            documentSnapshotCount: 2,
+            assetSnapshotCount: 3,
+            forceFullAiProfilePushQueued: false,
+        },
+        workspaceSyncPendingChanges: 4,
+        syncLastError: 'None',
+        workspaceSyncPhase: 'active',
+        referenceMismatchCount: 0,
+        syncRecentEvents: [],
+        loadRecentSyncEvents: vi.fn(async () => [{
+                occurredAt: '2026-04-18T01:33:06.044Z',
+                eventType: 'apply',
+                status: 'success',
+                changeCount: 200,
+                requestMs: 167,
+                statusCode: 0,
+            }]),
+        pushNotice: vi.fn(),
+        resetWorkspaceSyncCursorAndPull: vi.fn(async () => undefined),
+        workspaceSyncBusy: false,
+        ...overrides,
+    };
+}
+describe('useSyncStatusActions', () => {
+    beforeEach(() => {
+        vi.stubGlobal('navigator', {
+            clipboard: {
+                writeText: vi.fn(async () => undefined),
+            },
+        });
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+    });
+    it('copies the sync report using freshly loaded events when needed', async () => {
+        vi.useFakeTimers();
+        const input = makeInput();
+        const { result } = renderHook(() => useSyncStatusActions(input));
+        await act(async () => {
+            await result.current.handleCopySyncDetails();
+        });
+        expect(input.loadRecentSyncEvents).toHaveBeenCalledTimes(1);
+        expect(navigator.clipboard.writeText).toHaveBeenCalledWith(expect.stringContaining('Taskforce Sync Manager'));
+        expect(input.pushNotice).toHaveBeenCalledWith('Sync details copied to clipboard.', 'success');
+        expect(result.current.workspaceSyncCopied).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(1800);
+        });
+        expect(result.current.workspaceSyncCopied).toBe(false);
+    });
+    it('uses the current in-memory events instead of reloading when available', async () => {
+        const input = makeInput({
+            syncRecentEvents: [{
+                    occurredAt: '2026-04-18T01:33:18.371Z',
+                    eventType: 'apply',
+                    status: 'success',
+                    changeCount: 200,
+                    requestMs: 87,
+                    statusCode: 0,
+                }],
+        });
+        const { result } = renderHook(() => useSyncStatusActions(input));
+        await act(async () => {
+            await result.current.handleCopySyncDetails();
+        });
+        expect(input.loadRecentSyncEvents).not.toHaveBeenCalled();
+        expect(navigator.clipboard.writeText).toHaveBeenCalledWith(expect.stringContaining('2026-04-18T01:33:18.371Z apply succeeded'));
+    });
+    it('surfaces copy failures as an error notice', async () => {
+        const writeText = vi.fn(async () => {
+            throw new Error('clipboard unavailable');
+        });
+        vi.stubGlobal('navigator', {
+            clipboard: { writeText },
+        });
+        const input = makeInput();
+        const { result } = renderHook(() => useSyncStatusActions(input));
+        await act(async () => {
+            await result.current.handleCopySyncDetails();
+        });
+        expect(result.current.workspaceSyncCopied).toBe(false);
+        expect(input.pushNotice).toHaveBeenCalledWith('Failed to copy sync details.', 'error');
+    });
+    it('queues repair while sync is busy and runs it once the workspace becomes idle', async () => {
+        const input = makeInput({
+            workspaceSyncBusy: true,
+        });
+        const { result, rerender } = renderHook((props) => useSyncStatusActions(props), {
+            initialProps: input,
+        });
+        act(() => {
+            result.current.handleQueueOrRunRepairSync();
+        });
+        expect(result.current.workspaceSyncRepairQueued).toBe(true);
+        expect(input.resetWorkspaceSyncCursorAndPull).not.toHaveBeenCalled();
+        rerender({
+            ...input,
+            workspaceSyncBusy: false,
+        });
+        await waitFor(() => {
+            expect(input.resetWorkspaceSyncCursorAndPull).toHaveBeenCalledTimes(1);
+        });
+        expect(result.current.workspaceSyncRepairQueued).toBe(false);
+    });
+    it('runs repair immediately when the workspace is already idle', async () => {
+        const input = makeInput();
+        const { result } = renderHook(() => useSyncStatusActions(input));
+        act(() => {
+            result.current.handleQueueOrRunRepairSync();
+        });
+        await waitFor(() => {
+            expect(input.resetWorkspaceSyncCursorAndPull).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/hooks/sync/useSyncStatusControls.d.ts

@@ -0,0 +1,25 @@
+interface SaveWorkspaceCloudSyncSettingsResult {
+    success: boolean;
+    error?: string | null;
+}
+interface UseSyncStatusControlsInput {
+    canManageWorkspaceSync: boolean;
+    workspaceCloudSyncEnabled: boolean;
+    saveWorkspaceCloudSyncSettings: (input: {
+        enabled: boolean;
+    }) => Promise<SaveWorkspaceCloudSyncSettingsResult>;
+}
+interface UseSyncStatusControlsResult {
+    showSyncStatusModal: boolean;
+    showSyncEnableWarning: boolean;
+    workspaceSyncToggleBusy: boolean;
+    workspaceSyncError: string | null;
+    syncControlBusy: boolean;
+    openSyncStatusModal: () => void;
+    closeSyncStatusModal: () => void;
+    handleWorkspaceSyncToggle: (enabled: boolean) => Promise<void>;
+    cancelSyncEnableWarning: () => void;
+    confirmSyncEnableWarning: () => void;
+}
+export declare function useSyncStatusControls({ canManageWorkspaceSync, workspaceCloudSyncEnabled, saveWorkspaceCloudSyncSettings, }: UseSyncStatusControlsInput): UseSyncStatusControlsResult;
+export {};

package/dist/hooks/sync/useSyncStatusControls.js

@@ -0,0 +1,60 @@
+import { useCallback, useState } from 'react';
+export function useSyncStatusControls({ canManageWorkspaceSync, workspaceCloudSyncEnabled, saveWorkspaceCloudSyncSettings, }) {
+    const [showSyncStatusModal, setShowSyncStatusModal] = useState(false);
+    const [showSyncEnableWarning, setShowSyncEnableWarning] = useState(false);
+    const [workspaceSyncToggleBusy, setWorkspaceSyncToggleBusy] = useState(false);
+    const [workspaceSyncError, setWorkspaceSyncError] = useState(null);
+    const persistWorkspaceSyncToggle = useCallback(async (enabled) => {
+        if (!canManageWorkspaceSync)
+            return;
+        setWorkspaceSyncError(null);
+        setWorkspaceSyncToggleBusy(true);
+        try {
+            const result = await saveWorkspaceCloudSyncSettings({ enabled });
+            if (!result.success) {
+                setWorkspaceSyncError(result.error || (enabled ? 'Failed to enable sync.' : 'Failed to disable sync.'));
+            }
+        }
+        finally {
+            setWorkspaceSyncToggleBusy(false);
+        }
+    }, [
+        canManageWorkspaceSync,
+        saveWorkspaceCloudSyncSettings
+    ]);
+    const handleWorkspaceSyncToggle = useCallback(async (enabled) => {
+        if (enabled && !workspaceCloudSyncEnabled) {
+            setShowSyncEnableWarning(true);
+            return;
+        }
+        await persistWorkspaceSyncToggle(enabled);
+    }, [
+        persistWorkspaceSyncToggle,
+        workspaceCloudSyncEnabled
+    ]);
+    const cancelSyncEnableWarning = useCallback(() => {
+        setShowSyncEnableWarning(false);
+    }, []);
+    const confirmSyncEnableWarning = useCallback(() => {
+        setShowSyncEnableWarning(false);
+        void persistWorkspaceSyncToggle(true);
+    }, [persistWorkspaceSyncToggle]);
+    const openSyncStatusModal = useCallback(() => {
+        setShowSyncStatusModal(true);
+    }, []);
+    const closeSyncStatusModal = useCallback(() => {
+        setShowSyncStatusModal(false);
+    }, []);
+    return {
+        showSyncStatusModal,
+        showSyncEnableWarning,
+        workspaceSyncToggleBusy,
+        workspaceSyncError,
+        syncControlBusy: workspaceSyncToggleBusy,
+        openSyncStatusModal,
+        closeSyncStatusModal,
+        handleWorkspaceSyncToggle,
+        cancelSyncEnableWarning,
+        confirmSyncEnableWarning,
+    };
+}

package/dist/hooks/sync/useSyncStatusControls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/sync/useSyncStatusControls.test.js

@@ -0,0 +1,88 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { useSyncStatusControls } from './useSyncStatusControls';
+function makeInput(overrides) {
+    return {
+        canManageWorkspaceSync: true,
+        workspaceCloudSyncEnabled: false,
+        saveWorkspaceCloudSyncSettings: vi.fn(async () => ({ success: true })),
+        ...overrides,
+    };
+}
+describe('useSyncStatusControls', () => {
+    it('opens and closes the sync status modal', () => {
+        const { result } = renderHook(() => useSyncStatusControls(makeInput()));
+        act(() => {
+            result.current.openSyncStatusModal();
+        });
+        expect(result.current.showSyncStatusModal).toBe(true);
+        act(() => {
+            result.current.closeSyncStatusModal();
+        });
+        expect(result.current.showSyncStatusModal).toBe(false);
+    });
+    it('shows the warning before enabling sync from a local-only workspace', async () => {
+        const input = makeInput({
+            workspaceCloudSyncEnabled: false,
+        });
+        const { result } = renderHook(() => useSyncStatusControls(input));
+        await act(async () => {
+            await result.current.handleWorkspaceSyncToggle(true);
+        });
+        expect(result.current.showSyncEnableWarning).toBe(true);
+        expect(input.saveWorkspaceCloudSyncSettings).not.toHaveBeenCalled();
+    });
+    it('confirms the warning and then persists enabling sync', async () => {
+        const input = makeInput({
+            workspaceCloudSyncEnabled: false,
+        });
+        const { result } = renderHook(() => useSyncStatusControls(input));
+        await act(async () => {
+            await result.current.handleWorkspaceSyncToggle(true);
+        });
+        act(() => {
+            result.current.confirmSyncEnableWarning();
+        });
+        await waitFor(() => {
+            expect(input.saveWorkspaceCloudSyncSettings).toHaveBeenCalledWith({ enabled: true });
+        });
+        expect(result.current.showSyncEnableWarning).toBe(false);
+    });
+    it('disables sync immediately without showing the warning', async () => {
+        const input = makeInput({
+            workspaceCloudSyncEnabled: true,
+        });
+        const { result } = renderHook(() => useSyncStatusControls(input));
+        await act(async () => {
+            await result.current.handleWorkspaceSyncToggle(false);
+        });
+        expect(result.current.showSyncEnableWarning).toBe(false);
+        expect(input.saveWorkspaceCloudSyncSettings).toHaveBeenCalledWith({ enabled: false });
+    });
+    it('stores toggle errors from failed sync setting updates', async () => {
+        const input = makeInput({
+            workspaceCloudSyncEnabled: true,
+            saveWorkspaceCloudSyncSettings: vi.fn(async () => ({
+                success: false,
+                error: 'Cloud sync settings could not be updated.',
+            })),
+        });
+        const { result } = renderHook(() => useSyncStatusControls(input));
+        await act(async () => {
+            await result.current.handleWorkspaceSyncToggle(false);
+        });
+        expect(result.current.workspaceSyncError).toBe('Cloud sync settings could not be updated.');
+        expect(result.current.syncControlBusy).toBe(false);
+    });
+    it('does not persist sync settings when sync controls are unavailable', async () => {
+        const input = makeInput({
+            canManageWorkspaceSync: false,
+            workspaceCloudSyncEnabled: true,
+        });
+        const { result } = renderHook(() => useSyncStatusControls(input));
+        await act(async () => {
+            await result.current.handleWorkspaceSyncToggle(false);
+        });
+        expect(input.saveWorkspaceCloudSyncSettings).not.toHaveBeenCalled();
+    });
+});