@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/hooks/useTaskData.d.ts

@@ -0,0 +1,35 @@
+import type { TaskItem } from '../types';
+interface UseTaskDataProps {
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+    setTasks: React.Dispatch<React.SetStateAction<TaskItem[]>>;
+    setArchivedTasks: React.Dispatch<React.SetStateAction<TaskItem[]>>;
+    setLoadingTasks: React.Dispatch<React.SetStateAction<boolean>>;
+    getCurrentWorkspaceId: () => string;
+    workspaceResetKey: string;
+    shouldDeferProtectedApiCalls: boolean;
+    shouldBlockProtectedApiCalls: boolean;
+    handleUnauthorized: () => void;
+    /** Only used to detect auth changes in the fetch dependency array */
+    authRequiredForApi: boolean;
+}
+export declare function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks, setLoadingTasks, getCurrentWorkspaceId, workspaceResetKey, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls, handleUnauthorized, authRequiredForApi }: UseTaskDataProps): {
+    tasksRef: import("react").RefObject<TaskItem[]>;
+    archivedTasksRef: import("react").RefObject<TaskItem[]>;
+    recentlyChangedTaskIds: string[];
+    markRecentlyChangedTasks: (taskIds: string[]) => void;
+    fetchTasks: (isSilent?: boolean, options?: {
+        ignoreAuthGuard?: boolean;
+    }) => Promise<void>;
+    fetchArchive: (isSilent?: boolean, options?: {
+        ignoreAuthGuard?: boolean;
+    }) => Promise<void>;
+    refreshTaskCollections: (options?: {
+        isSilent?: boolean;
+        ignoreAuthGuard?: boolean;
+    }) => Promise<void>;
+    refreshTaskCollectionsFromInvalidation: () => Promise<void>;
+    mergeTaskFromServer: (task: unknown) => void;
+    getTaskRevisionKey: (task: TaskItem) => string;
+};
+export {};

package/dist/hooks/useTaskData.js

@@ -0,0 +1,243 @@
+/**
+ * useTaskData
+ *
+ * Manages the task fetch lifecycle, recently-changed-task highlighting,
+ * and merge/coalesce helpers. Task and archive state arrays live in
+ * useTaskforce.ts (because they must be passed to useSyncOrchestrator),
+ * but all fetch and mutation helpers are encapsulated here.
+ *
+ * === SECTION MAP ===
+ *   === SECTION: Recently Changed ===       — recentlyChangedTaskIds, markRecentlyChangedTasks, timer cleanup
+ *   === SECTION: Fetch Functions ===        — fetchTasks, fetchArchive, refreshTaskCollections, refreshTaskCollectionsFromInvalidation
+ *   === SECTION: Revision Tracking ===      — getTaskRevisionKey, taskRevisionMapRef, hasFetchedTasksRef
+ *   === SECTION: Merge Helper ===           — mergeTaskFromServer
+ *
+ * Key return values:
+ *   - fetchTasks(isSilent?, options?) — refresh the active task list
+ *   - fetchArchive(isSilent?, options?) — refresh the archive
+ *   - refreshTaskCollections(options?) — refresh both in parallel
+ *   - refreshTaskCollectionsFromInvalidation() — coalesced refresh (for data-version polling)
+ *   - mergeTaskFromServer(task) — merge a single server response into both collections
+ *   - markRecentlyChangedTasks(ids) — flag task IDs for highlight animation
+ *   - recentlyChangedTaskIds — task IDs that changed in the last 4s
+ *   - getTaskRevisionKey(task) — stable revision string for change detection
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { normalizeTaskFromApi, mergeNormalizedTaskIntoCollections } from '../utils/taskNormalization.js';
+import { runCoalescedRefresh } from '../utils/coalescedRefresh';
+export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks, setLoadingTasks, getCurrentWorkspaceId, workspaceResetKey, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls, handleUnauthorized, authRequiredForApi }) {
+    // === SECTION: Revision Tracking ===
+    const taskRevisionMapRef = useRef(new Map());
+    const hasFetchedTasksRef = useRef(false);
+    // Stable refs for use inside closures that need the latest task arrays
+    const tasksRef = useRef([]);
+    const archivedTasksRef = useRef([]);
+    const dataVersionRefreshInFlightRef = useRef(false);
+    const pendingDataVersionRefreshRef = useRef(false);
+    const tasksAbortRef = useRef(null);
+    const archiveAbortRef = useRef(null);
+    useEffect(() => {
+        tasksRef.current = tasks;
+    }, [tasks]);
+    useEffect(() => {
+        archivedTasksRef.current = archivedTasks;
+    }, [archivedTasks]);
+    const getTaskRevisionKey = useCallback((task) => {
+        return `${task.updatedAt || task.createdAt || ''}|${task.status}|${task.priority}|${task.title}`;
+    }, []);
+    const isExpectedAbortFailure = useCallback((error, signal) => {
+        if (!signal.aborted)
+            return false;
+        if (error === signal.reason)
+            return true;
+        if (error instanceof DOMException) {
+            return error.name === 'AbortError';
+        }
+        return String(error?.name || '').toLowerCase() === 'aborterror';
+    }, []);
+    // === SECTION: Recently Changed ===
+    const [recentlyChangedTaskIds, setRecentlyChangedTaskIds] = useState([]);
+    const highlightTimersRef = useRef(new Map());
+    const markRecentlyChangedTasks = useCallback((taskIds) => {
+        if (!taskIds.length || typeof window === 'undefined')
+            return;
+        setRecentlyChangedTaskIds(prev => Array.from(new Set([...prev, ...taskIds])));
+        taskIds.forEach((taskId) => {
+            const existing = highlightTimersRef.current.get(taskId);
+            if (existing) {
+                window.clearTimeout(existing);
+            }
+            const timerId = window.setTimeout(() => {
+                highlightTimersRef.current.delete(taskId);
+                setRecentlyChangedTaskIds(prev => prev.filter(id => id !== taskId));
+            }, 4000);
+            highlightTimersRef.current.set(taskId, timerId);
+        });
+    }, []);
+    useEffect(() => {
+        return () => {
+            if (typeof window === 'undefined')
+                return;
+            highlightTimersRef.current.forEach((timerId) => window.clearTimeout(timerId));
+            highlightTimersRef.current.clear();
+        };
+    }, []);
+    useEffect(() => {
+        taskRevisionMapRef.current = new Map();
+        hasFetchedTasksRef.current = false;
+        dataVersionRefreshInFlightRef.current = false;
+        pendingDataVersionRefreshRef.current = false;
+        tasksAbortRef.current?.abort('workspace-reset');
+        tasksAbortRef.current = null;
+        archiveAbortRef.current?.abort('workspace-reset');
+        archiveAbortRef.current = null;
+        if (typeof window !== 'undefined') {
+            highlightTimersRef.current.forEach((timerId) => window.clearTimeout(timerId));
+            highlightTimersRef.current.clear();
+        }
+        setRecentlyChangedTaskIds([]);
+    }, [workspaceResetKey]);
+    // === SECTION: Fetch Functions ===
+    const fetchTasks = useCallback(async (isSilent = false, options) => {
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        if (!ignoreAuthGuard && (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls))
+            return;
+        if (!isSilent)
+            setLoadingTasks(true);
+        const requestWorkspaceId = String(getCurrentWorkspaceId() || '').trim();
+        tasksAbortRef.current?.abort('superseded');
+        const abortController = new AbortController();
+        tasksAbortRef.current = abortController;
+        try {
+            const res = await fetch('/api/taskforce/tasks', { signal: abortController.signal });
+            if (res.status === 401) {
+                handleUnauthorized();
+                setTasks([]);
+                if (!isSilent)
+                    setLoadingTasks(false);
+                return;
+            }
+            if (res.ok) {
+                const data = await res.json();
+                const sanitized = (data.tasks || []).map((t) => normalizeTaskFromApi(t));
+                const liveWorkspaceId = String(getCurrentWorkspaceId() || '').trim();
+                if (liveWorkspaceId !== requestWorkspaceId) {
+                    return;
+                }
+                const nextRevisionMap = new Map();
+                const changedTaskIds = [];
+                for (const task of sanitized) {
+                    const revision = getTaskRevisionKey(task);
+                    nextRevisionMap.set(task.id, revision);
+                    if (!hasFetchedTasksRef.current)
+                        continue;
+                    const previousRevision = taskRevisionMapRef.current.get(task.id);
+                    if (!previousRevision || previousRevision !== revision) {
+                        changedTaskIds.push(task.id);
+                    }
+                }
+                taskRevisionMapRef.current = nextRevisionMap;
+                if (hasFetchedTasksRef.current) {
+                    markRecentlyChangedTasks(changedTaskIds);
+                }
+                else {
+                    hasFetchedTasksRef.current = true;
+                }
+                setTasks(sanitized);
+            }
+        }
+        catch (err) {
+            if (isExpectedAbortFailure(err, abortController.signal))
+                return;
+            console.error('[Taskforce] Failed to fetch tasks:', err);
+        }
+        finally {
+            if (tasksAbortRef.current === abortController) {
+                tasksAbortRef.current = null;
+            }
+            if (!isSilent)
+                setLoadingTasks(false);
+        }
+    }, [
+        getTaskRevisionKey,
+        getCurrentWorkspaceId,
+        markRecentlyChangedTasks,
+        handleUnauthorized,
+        setTasks,
+        setLoadingTasks,
+        authRequiredForApi,
+        shouldDeferProtectedApiCalls,
+        shouldBlockProtectedApiCalls
+    ]);
+    const fetchArchive = useCallback(async (isSilent = false, options) => {
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        if (!ignoreAuthGuard && (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls))
+            return;
+        const requestWorkspaceId = String(getCurrentWorkspaceId() || '').trim();
+        archiveAbortRef.current?.abort('superseded');
+        const abortController = new AbortController();
+        archiveAbortRef.current = abortController;
+        try {
+            const res = await fetch('/api/taskforce/archive', { signal: abortController.signal });
+            if (res.ok) {
+                const data = await res.json();
+                const liveWorkspaceId = String(getCurrentWorkspaceId() || '').trim();
+                if (liveWorkspaceId !== requestWorkspaceId) {
+                    return;
+                }
+                const sanitized = (data.archived || []).map((t) => ({
+                    ...normalizeTaskFromApi(t),
+                    isArchived: true
+                }));
+                setArchivedTasks(sanitized);
+            }
+        }
+        catch (err) {
+            if (isExpectedAbortFailure(err, abortController.signal))
+                return;
+            console.error('[Taskforce] Failed to fetch archive:', err);
+        }
+        finally {
+            if (archiveAbortRef.current === abortController) {
+                archiveAbortRef.current = null;
+            }
+        }
+    }, [getCurrentWorkspaceId, isExpectedAbortFailure, setArchivedTasks, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls]);
+    const refreshTaskCollections = useCallback(async (options) => {
+        const isSilent = options?.isSilent !== false;
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        await Promise.all([
+            fetchTasks(isSilent, { ignoreAuthGuard }),
+            fetchArchive(isSilent, { ignoreAuthGuard })
+        ]);
+    }, [fetchArchive, fetchTasks]);
+    const refreshTaskCollectionsFromInvalidation = useCallback(async () => {
+        await runCoalescedRefresh(dataVersionRefreshInFlightRef, pendingDataVersionRefreshRef, async () => {
+            await refreshTaskCollections({ isSilent: true });
+        });
+    }, [refreshTaskCollections]);
+    // === SECTION: Merge Helper ===
+    const mergeTaskFromServer = useCallback((task) => {
+        const merged = mergeNormalizedTaskIntoCollections(task, tasksRef.current, archivedTasksRef.current);
+        tasksRef.current = merged.tasks;
+        archivedTasksRef.current = merged.archivedTasks;
+        setTasks(merged.tasks);
+        setArchivedTasks(merged.archivedTasks);
+    }, [setTasks, setArchivedTasks]);
+    return {
+        // Stable refs (for use inside closures)
+        tasksRef,
+        archivedTasksRef,
+        // Recently changed
+        recentlyChangedTaskIds,
+        markRecentlyChangedTasks,
+        // Fetch functions
+        fetchTasks,
+        fetchArchive,
+        refreshTaskCollections,
+        refreshTaskCollectionsFromInvalidation,
+        // Helpers
+        mergeTaskFromServer,
+        getTaskRevisionKey
+    };
+}

package/dist/hooks/useTaskData.test.d.ts

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

package/dist/hooks/useTaskData.test.js

@@ -0,0 +1,180 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useTaskData } from './useTaskData';
+function makeAbortableFetchResponse(payload) {
+    return {
+        ok: true,
+        status: 200,
+        json: async () => payload
+    };
+}
+function makeAbortableRequest(payload) {
+    let rejectRequest = null;
+    const promise = new Promise((resolve, reject) => {
+        rejectRequest = reject;
+        queueMicrotask(() => resolve(makeAbortableFetchResponse(payload)));
+    });
+    return {
+        promise,
+        attach(signal) {
+            signal?.addEventListener('abort', () => {
+                rejectRequest?.(new DOMException('Aborted', 'AbortError'));
+            }, { once: true });
+        }
+    };
+}
+function makeAbortableRequestRejectingWithReason(payload) {
+    let rejectRequest = null;
+    let resolveRequest = null;
+    const promise = new Promise((resolve, reject) => {
+        resolveRequest = resolve;
+        rejectRequest = reject;
+    });
+    return {
+        promise,
+        attach(signal) {
+            signal?.addEventListener('abort', () => {
+                rejectRequest?.(signal.reason);
+            }, { once: true });
+            queueMicrotask(() => {
+                if (!signal?.aborted) {
+                    resolveRequest?.(makeAbortableFetchResponse(payload));
+                }
+            });
+        }
+    };
+}
+describe('useTaskData', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.clearAllMocks();
+    });
+    it('aborts an in-flight tasks request when a replacement fetch starts', async () => {
+        const firstRequest = makeAbortableRequest({ tasks: [] });
+        const secondRequest = makeAbortableRequest({ tasks: [] });
+        const fetchMock = vi.mocked(fetch);
+        const requestSignals = [];
+        fetchMock.mockImplementation((_input, init) => {
+            const signal = init?.signal;
+            if (requestSignals.length === 0) {
+                requestSignals.push(signal);
+                firstRequest.attach(signal);
+                return firstRequest.promise;
+            }
+            requestSignals.push(signal);
+            secondRequest.attach(signal);
+            return secondRequest.promise;
+        });
+        const setTasks = vi.fn();
+        const setArchivedTasks = vi.fn();
+        const setLoadingTasks = vi.fn();
+        const { result } = renderHook(() => useTaskData({
+            tasks: [],
+            archivedTasks: [],
+            setTasks,
+            setArchivedTasks,
+            setLoadingTasks,
+            getCurrentWorkspaceId: () => 'workspace-1',
+            workspaceResetKey: 'workspace-1',
+            shouldDeferProtectedApiCalls: false,
+            shouldBlockProtectedApiCalls: false,
+            handleUnauthorized: vi.fn(),
+            authRequiredForApi: false
+        }));
+        let firstPromise;
+        let secondPromise;
+        await act(async () => {
+            firstPromise = result.current.fetchTasks(true);
+            secondPromise = result.current.fetchTasks(true);
+            await secondPromise;
+            await firstPromise;
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(requestSignals[0]?.aborted).toBe(true);
+        expect(requestSignals[1]?.aborted).toBe(false);
+    });
+    it('aborts an in-flight archive request when a replacement fetch starts', async () => {
+        const firstRequest = makeAbortableRequest({ archived: [] });
+        const secondRequest = makeAbortableRequest({ archived: [] });
+        const fetchMock = vi.mocked(fetch);
+        const requestSignals = [];
+        fetchMock.mockImplementation((_input, init) => {
+            const signal = init?.signal;
+            if (requestSignals.length === 0) {
+                requestSignals.push(signal);
+                firstRequest.attach(signal);
+                return firstRequest.promise;
+            }
+            requestSignals.push(signal);
+            secondRequest.attach(signal);
+            return secondRequest.promise;
+        });
+        const { result } = renderHook(() => useTaskData({
+            tasks: [],
+            archivedTasks: [],
+            setTasks: vi.fn(),
+            setArchivedTasks: vi.fn(),
+            setLoadingTasks: vi.fn(),
+            getCurrentWorkspaceId: () => 'workspace-1',
+            workspaceResetKey: 'workspace-1',
+            shouldDeferProtectedApiCalls: false,
+            shouldBlockProtectedApiCalls: false,
+            handleUnauthorized: vi.fn(),
+            authRequiredForApi: false
+        }));
+        let firstPromise;
+        let secondPromise;
+        await act(async () => {
+            firstPromise = result.current.fetchArchive(true);
+            secondPromise = result.current.fetchArchive(true);
+            await secondPromise;
+            await firstPromise;
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(requestSignals[0]?.aborted).toBe(true);
+        expect(requestSignals[1]?.aborted).toBe(false);
+    });
+    it('does not log an error when an archive request is aborted with a string reason', async () => {
+        const firstRequest = makeAbortableRequestRejectingWithReason({ archived: [] });
+        const secondRequest = makeAbortableRequestRejectingWithReason({ archived: [] });
+        const fetchMock = vi.mocked(fetch);
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        let requestCount = 0;
+        fetchMock.mockImplementation((_input, init) => {
+            const signal = init?.signal;
+            requestCount += 1;
+            if (requestCount === 1) {
+                firstRequest.attach(signal);
+                return firstRequest.promise;
+            }
+            secondRequest.attach(signal);
+            return secondRequest.promise;
+        });
+        const { result } = renderHook(() => useTaskData({
+            tasks: [],
+            archivedTasks: [],
+            setTasks: vi.fn(),
+            setArchivedTasks: vi.fn(),
+            setLoadingTasks: vi.fn(),
+            getCurrentWorkspaceId: () => 'workspace-1',
+            workspaceResetKey: 'workspace-1',
+            shouldDeferProtectedApiCalls: false,
+            shouldBlockProtectedApiCalls: false,
+            handleUnauthorized: vi.fn(),
+            authRequiredForApi: false
+        }));
+        let firstPromise;
+        let secondPromise;
+        await act(async () => {
+            firstPromise = result.current.fetchArchive(true);
+            secondPromise = result.current.fetchArchive(true);
+            await secondPromise;
+            await firstPromise;
+        });
+        expect(consoleErrorSpy).not.toHaveBeenCalledWith('[Taskforce] Failed to fetch archive:', 'superseded');
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+});

package/dist/hooks/useTaskMutations.d.ts

@@ -0,0 +1,46 @@
+import { MutableRefObject } from 'react';
+import type { DeletedTaskRecord, TaskItem } from '../types';
+import type { UiNoticeTone } from '../utils/uiNotice';
+export interface UseTaskMutationsProps {
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+    editingTaskId: string | null;
+    setTasks: React.Dispatch<React.SetStateAction<TaskItem[]>>;
+    setArchivedTasks: React.Dispatch<React.SetStateAction<TaskItem[]>>;
+    setDeletedTasks: React.Dispatch<React.SetStateAction<DeletedTaskRecord[]>>;
+    setError: (msg: string) => void;
+    resetForm: () => void;
+    setActiveTab: (tab: 'add' | 'tasks' | 'settings') => void;
+    fetchTasks: (force?: boolean) => Promise<void>;
+    fetchArchive: () => void;
+    fetchDeletedTasks: (isSilent?: boolean) => Promise<void>;
+    mergeTaskFromServer: (task: unknown) => void;
+    pushNotice: (msg: string, tone?: UiNoticeTone, ttlMs?: number) => void;
+    cloudAuthConfigured: boolean;
+    runtimeMode: string;
+    isAuthenticated: boolean;
+    workspaceCloudSyncEnabled: boolean;
+    buildWorkspaceSyncSignature: () => string;
+    pushWorkspaceChangesToCloud: (sig: string) => void;
+    workspacePendingSignatureRef: MutableRefObject<string | null>;
+    workspaceDeletedTaskIdsRef: MutableRefObject<Set<string>>;
+}
+export declare function useTaskMutations({ tasks, archivedTasks, editingTaskId, setTasks, setArchivedTasks, setDeletedTasks, setError, resetForm, setActiveTab, fetchTasks, fetchArchive, fetchDeletedTasks, mergeTaskFromServer, pushNotice, cloudAuthConfigured, runtimeMode, isAuthenticated, workspaceCloudSyncEnabled, buildWorkspaceSyncSignature, pushWorkspaceChangesToCloud, workspacePendingSignatureRef, workspaceDeletedTaskIdsRef, }: UseTaskMutationsProps): {
+    copiedId: string | null;
+    handleDelete: (id: string, archive?: boolean, options?: {
+        skipConfirm?: boolean;
+    }) => Promise<boolean>;
+    handleUpdateTask: (id: string, updates: Partial<TaskItem>) => Promise<void>;
+    handleToggleComplete: (task: TaskItem) => Promise<void>;
+    handleToggleCancel: (task: TaskItem) => Promise<void>;
+    handleToggleInProgress: (task: TaskItem) => Promise<void>;
+    handleToggleReview: (task: TaskItem) => Promise<void>;
+    handleArchiveTask: (task: TaskItem) => Promise<void>;
+    handleBulkArchive: () => Promise<void>;
+    handleUnarchive: (id: string) => Promise<void>;
+    handleRestoreDeletedTask: (id: string) => Promise<TaskItem | null>;
+    handlePermanentlyDeleteDeletedTask: (id: string) => Promise<boolean>;
+    handleEmptyDeletedTasks: () => Promise<number | null>;
+    handleCopyId: (e: React.MouseEvent, id: string) => void;
+    queueWorkspaceSyncFromAuthoritativeTaskState: (delayMs?: number) => void;
+};