@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/hooks/useTaskforce.d.ts

@@ -1,4 +1,39 @@
-import type { TaskforceConfig, TaskforceTheme, Comment, AttachmentItem, CategoryConfig, TaskItem, TaxonomyDefinition, Environment, TaskAssignee, TaskStatus, DeletedTaskRecord, InitiativeItem, WorkstreamItem, ChecklistItem } from '../types';
+/**
+ * useTaskforce
+ *
+ * Central React hook for the Taskforce task-management system.
+ * Orchestrates all application state: runtime config, auth, workspace,
+ * bootstrap, task data, filtering/sorting, form editing, settings,
+ * sync, and UI notices.
+ *
+ * SECTION MAP (use Ctrl+F on the === markers to jump):
+ *   === SECTION: Runtime Config ===         Line ~189  — URL resolution, cloud/local mode detection
+ *   === SECTION: Settings State ===         Line ~388  — Theme, shortcut, locale, feature flags
+ *   === SECTION: Workspace Storage ===      Line ~415  — workspaceStorageScope, project root/name
+ *   === SECTION: Auth State ===             Line ~426  — isAuthenticated, authBlocked, userId, beta access
+ *   === SECTION: Bootstrap State ===        Line ~442  — bootstrapPhase, setupState, runtimeCapabilities
+ *   === SECTION: Fetch Intercept ===        Line ~490  — window.fetch patch for cloud API routing
+ *   === SECTION: Workflow Templates ===     Line ~577  — fetchWorkflows, fetchInitiativeTemplates
+ *   === SECTION: Export State ===           Line ~678  — exportEnvironment, exportWorkflowsPath
+ *   === SECTION: Task State ===             Line ~1065 — tasks, archivedTasks, editingTaskId
+ *   === SECTION: Filter & Sort State ===    Line ~1394 — searchQuery, filterCategories, sortBy, sortOrder
+ *   === SECTION: UI State ===               Line ~1469 — uiStateReady, persisted UI preferences
+ *   === SECTION: Config Fetch ===           Line ~1578 — fetchConfig (the main bootstrap loader)
+ *   === SECTION: Workspace Actions ===      Line ~1855 — fetchWorkspaces, switchWorkspace, createWorkspace
+ *   === SECTION: Auth Actions ===           Line ~2210 — loginWithCredentials, logout, invite flows
+ *   === SECTION: Task Fetch ===             Line ~2158 — fetchTasks, fetchArchive, refreshTaskCollections
+ *   === SECTION: Bootstrap Effects ===      Line ~2641 — initialization useEffects
+ *   === SECTION: Filtering Logic ===        Line ~3068 — filteredTasks, searchAgnosticTasks, filteredArchive
+ *   === SECTION: Navigation ===             Line ~3410 — setActiveTab, handleNavigation
+ *   === SECTION: Form ===                   Line ~3489 — resetForm, handleEdit, handleSubmit, saveTask
+ *   === SECTION: Task CRUD ===              Line ~3691 — handleDelete, handleUpdateTask, handleToggle*
+ *   === SECTION: Planning Links ===         Line ~4129 — workstream and initiative link handlers
+ *   === SECTION: Category/Type Mgmt ===     Line ~4462 — handleSaveCategory, handleRemoveCategory
+ *   === SECTION: Settings Model ===         Line ~4625 — settingsModel object
+ *   === SECTION: Return Value ===           Line ~4817 — final return object (public API shape)
+ */
+import { type Dispatch, type SetStateAction } from 'react';
+import type { TaskforceConfig, TaskforceTheme, Comment, AttachmentItem, CategoryConfig, TaskItem, TaxonomyDefinition, Environment, TaskAssignee, TaskStatus, DeletedTaskRecord, InitiativeItem, WorkstreamItem, ChecklistItem, PlanningBootstrapWorkstreamTaskSummary } from '../types';
 import { type FirstClassTaxonomyDisplayLabels } from '../shared/taxonomyState.js';
 import type { UiNotice } from '../utils/uiNotice';
 import type { TaskAssigneeOption } from '../utils/assignees';
@@ -37,6 +72,27 @@ interface RuntimeCapabilities {
     supportsAdminManagedSetupOverrides: boolean;
     supportsPackageScriptSetupOverrides: boolean;
 }
+interface BootstrapStateSnapshot {
+    phase: BootstrapPhase;
+    auth: {
+        resolved: boolean;
+        pending: boolean;
+    };
+    config: {
+        loaded: boolean;
+    };
+    workspace: {
+        pending: boolean;
+    };
+    pending: boolean;
+    authPending: boolean;
+    appPending: boolean;
+    ready: boolean;
+    stalled: boolean;
+    subtitle: string;
+    error: string | null;
+    startedAt: number | null;
+}
 interface WorkspaceSummary {
     id: string;
     slug?: string | null;
@@ -85,31 +141,31 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         showTaskCardStatusLabel: boolean;
     };
     isOpen: boolean;
-    setIsOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setIsOpen: Dispatch<SetStateAction<boolean>>;
     activeTab: "tasks" | "settings" | "add";
     setActiveTab: (tab: "add" | "tasks" | "settings") => void;
     currentTheme: "light" | "dawn" | "dark" | "midnight";
-    setCurrentTheme: import("react").Dispatch<import("react").SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
+    setCurrentTheme: Dispatch<SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
     configLoaded: boolean;
     storagePath: string;
     saveSettings: () => Promise<boolean>;
     pathSaved: boolean;
     keyShortcut: string;
-    setKeyShortcut: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setKeyShortcut: Dispatch<SetStateAction<string>>;
     globalWeekStartsOn: WeekStartsOn;
     locale: "en-US" | "es-419" | "pt-BR";
     supportedLocales: ("en-US" | "es-419" | "pt-BR")[];
     saveLocale: (nextLocale: string) => Promise<boolean>;
     jsonBackupEnabled: boolean;
-    setJsonBackupEnabled: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setJsonBackupEnabled: Dispatch<SetStateAction<boolean>>;
     manualComplexityEnabled: boolean;
     checklistDropdownEnabled: boolean;
     showTaskCardStatusLabel: boolean;
-    setManualComplexityEnabled: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setManualComplexityEnabled: Dispatch<SetStateAction<boolean>>;
     mcpHostRoot: string;
-    setMcpHostRoot: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setMcpHostRoot: Dispatch<SetStateAction<string>>;
     settingsSection: "mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null;
-    setSettingsSection: import("react").Dispatch<import("react").SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null>>;
+    setSettingsSection: Dispatch<SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null>>;
     runtimeMode: "local" | "cloud";
     workspaceMode: "single-local" | "multi-cloud";
     workspaceSwitchingEnabled: boolean;
@@ -122,7 +178,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     authUserDisplayName: string;
     authUserAvatarUrl: string;
     authWorkspaceId: string;
-    userGlobalSyncStatus: "error" | "idle" | "disconnected" | "syncing";
+    userGlobalSyncStatus: "error" | "idle" | "syncing" | "disconnected";
     workspaceLastPullAt: string | null;
     workspaceLastPushAt: string | null;
     workspaceLastErrorAt: string | null;
@@ -152,6 +208,13 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         pendingChanges: number;
         lastErrorMessage: string | null;
         recommendedAction: string;
+        pushBlockedReason: import("./sync/controlPlane").WorkspaceSyncBlockedReason | null;
+        pullBlockedReason: import("./sync/controlPlane").WorkspaceSyncBlockedReason | null;
+        retryBlockedReason: import("./sync/controlPlane").WorkspaceSyncBlockedReason | null;
+        repairActive: boolean;
+        pushInFlight: boolean;
+        pullInFlight: boolean;
+        retryPending: boolean;
         documentSnapshotCount: number;
         aiProfileSnapshotCount: number;
         aiProfileSnapshotRawCount: number;
@@ -185,6 +248,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         enabled: boolean;
         phase?: import("../sync/workspaceSyncState").WorkspaceSyncPhase | null;
     }) => void>[0]) => void;
+    bootstrapState: BootstrapStateSnapshot;
     authSessionResolved: boolean;
     workspaceBootstrapPending: boolean;
     bootstrapPhase: BootstrapPhase;
@@ -242,6 +306,31 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         code?: string;
         workspaceSetupRequired?: boolean;
     }>;
+    beginOAuthLogin: (provider: string, returnTo?: string, inviteToken?: string) => void;
+    availableAuthProviders: string[];
+    fetchLoginMethods: () => Promise<{
+        success: boolean;
+        error?: string;
+        methods?: Array<{
+            provider: string;
+            providerEmail: string | null;
+            displayNameSnapshot: string | null;
+            avatarUrlSnapshot: string | null;
+            linkedAt: string | null;
+            lastLoginAt: string | null;
+        }>;
+    }>;
+    unlinkLoginMethod: (provider: string) => Promise<{
+        success: boolean;
+        error?: string;
+        code?: string;
+    }>;
+    addPasswordToAccount: (password: string) => Promise<{
+        success: boolean;
+        error?: string;
+        code?: string;
+    }>;
+    beginOAuthLink: (provider: string, returnTo?: string) => void;
     registerWithCredentials: (email: string, password: string, options?: {
         displayName?: string | null;
         planId?: string | null;
@@ -312,6 +401,8 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         workspaceId?: string;
         inviteeKind?: "existing_user" | "new_user";
         passwordRequired?: boolean;
+        inviteeState?: "pending_setup" | "existing_account";
+        availableMethods?: string[];
     }>;
     acceptInviteWithToken: (token: string, password: string) => Promise<{
         success: boolean;
@@ -327,7 +418,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     }>;
     logout: () => Promise<void>;
     showFolderBrowser: boolean;
-    setShowFolderBrowser: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowFolderBrowser: Dispatch<SetStateAction<boolean>>;
     folders: string[];
     files: string[];
     currentBrowsePath: string;
@@ -336,16 +427,16 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         type: "category";
         value: string;
     } | null;
-    setBrowserTarget: import("react").Dispatch<import("react").SetStateAction<"storage" | {
+    setBrowserTarget: Dispatch<SetStateAction<"storage" | {
         type: "category";
         value: string;
     } | null>>;
     groupBy: "category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule";
-    setGroupBy: import("react").Dispatch<import("react").SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule">>;
+    setGroupBy: Dispatch<SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule">>;
     activeWorkspaceModule: WorkspaceModuleId;
-    setActiveWorkspaceModule: import("react").Dispatch<import("react").SetStateAction<WorkspaceModuleId>>;
+    setActiveWorkspaceModule: Dispatch<SetStateAction<WorkspaceModuleId>>;
     emptyColumnMode: "show" | "collapse" | "hide";
-    setEmptyColumnMode: import("react").Dispatch<import("react").SetStateAction<"show" | "collapse" | "hide">>;
+    setEmptyColumnMode: Dispatch<SetStateAction<"show" | "collapse" | "hide">>;
     zenMode: boolean;
     setZenMode: () => Promise<void>;
     handleSelectPath: (path: string) => void;
@@ -356,6 +447,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     archivedTasks: TaskItem[];
     initiatives: InitiativeItem[];
     workstreams: WorkstreamItem[];
+    planningBootstrapTaskSummaries: PlanningBootstrapWorkstreamTaskSummary[];
     deletedTasks: DeletedTaskRecord[];
     activeCategories: CategoryConfig[];
     activeTypes: {
@@ -381,35 +473,36 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     }[];
     taxonomies: TaxonomyDefinition[];
     searchQuery: string;
-    setSearchQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setSearchQuery: Dispatch<SetStateAction<string>>;
     filterCategories: string[];
-    setFilterCategories: import("react").Dispatch<import("react").SetStateAction<string[]>>;
+    setFilterCategories: Dispatch<SetStateAction<string[]>>;
     filterTypes: string[];
-    setFilterTypes: import("react").Dispatch<import("react").SetStateAction<string[]>>;
+    setFilterTypes: Dispatch<SetStateAction<string[]>>;
     filterPriorities: (string | number)[];
-    setFilterPriorities: import("react").Dispatch<import("react").SetStateAction<(string | number)[]>>;
+    setFilterPriorities: Dispatch<SetStateAction<(string | number)[]>>;
     filterStatus: (string | number)[];
-    setFilterStatus: import("react").Dispatch<import("react").SetStateAction<(string | number)[]>>;
+    setFilterStatus: Dispatch<SetStateAction<(string | number)[]>>;
     filterAssignees: string[];
     setFilterAssignees: (nextValues: TaskAssignee[] | ((prev: TaskAssignee[]) => TaskAssignee[])) => void;
     filterTaxonomies: Record<string, (string | number)[]>;
-    setFilterTaxonomies: import("react").Dispatch<import("react").SetStateAction<Record<string, (string | number)[]>>>;
+    setFilterTaxonomies: Dispatch<SetStateAction<Record<string, (string | number)[]>>>;
+    hasInitedFilters: boolean;
     sortBy: import("../utils/taxonomySorting").TaskSortKey;
-    setSortBy: import("react").Dispatch<import("react").SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
+    setSortBy: Dispatch<SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
     sortOrder: "asc" | "desc";
-    setSortOrder: import("react").Dispatch<import("react").SetStateAction<"asc" | "desc">>;
+    setSortOrder: Dispatch<SetStateAction<"asc" | "desc">>;
     toggleSortOrder: () => void;
     showArchive: boolean;
-    setShowArchive: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowArchive: Dispatch<SetStateAction<boolean>>;
     taskScope: TaskScope;
-    setTaskScope: import("react").Dispatch<import("react").SetStateAction<TaskScope>>;
+    setTaskScope: Dispatch<SetStateAction<TaskScope>>;
     clearFilters: () => void;
     filteredTasks: TaskItem[];
     searchAgnosticTasks: TaskItem[];
     filteredArchive: TaskItem[];
     groupedTasks: Record<string, TaskItem[]>;
     collapsedCategories: Record<string, boolean>;
-    setCollapsedCategories: import("react").Dispatch<import("react").SetStateAction<Record<string, boolean>>>;
+    setCollapsedCategories: Dispatch<SetStateAction<Record<string, boolean>>>;
     fetchTasks: (isSilent?: boolean, options?: {
         ignoreAuthGuard?: boolean;
     }) => Promise<void>;
@@ -456,50 +549,50 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     loading: boolean;
     error: string;
     title: string;
-    setTitle: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setTitle: Dispatch<SetStateAction<string>>;
     description: string;
-    setDescription: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDescription: Dispatch<SetStateAction<string>>;
     checklistItems: ChecklistItem[];
-    setChecklistItems: import("react").Dispatch<import("react").SetStateAction<ChecklistItem[]>>;
+    setChecklistItems: Dispatch<SetStateAction<ChecklistItem[]>>;
     category: string;
-    setCategory: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setCategory: Dispatch<SetStateAction<string>>;
     type: string;
-    setType: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setType: Dispatch<SetStateAction<string>>;
     priority: string | number;
-    setPriority: import("react").Dispatch<import("react").SetStateAction<string | number>>;
+    setPriority: Dispatch<SetStateAction<string | number>>;
     complexity: string | number;
-    setComplexity: import("react").Dispatch<import("react").SetStateAction<string | number>>;
+    setComplexity: Dispatch<SetStateAction<string | number>>;
     status: TaskStatus;
-    setStatus: import("react").Dispatch<import("react").SetStateAction<TaskStatus>>;
+    setStatus: Dispatch<SetStateAction<TaskStatus>>;
     approach: string;
-    setApproach: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setApproach: Dispatch<SetStateAction<string>>;
     assignee: string;
-    setAssignee: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setAssignee: Dispatch<SetStateAction<string>>;
     scheduledDate: string;
-    setScheduledDate: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setScheduledDate: Dispatch<SetStateAction<string>>;
     dueDate: string;
-    setDueDate: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDueDate: Dispatch<SetStateAction<string>>;
     workstreamInput: string;
-    setWorkstreamInput: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setWorkstreamInput: Dispatch<SetStateAction<string>>;
     formTaxonomies: Record<string, string | number | string[] | number[]>;
-    setFormTaxonomies: import("react").Dispatch<import("react").SetStateAction<Record<string, string | number | string[] | number[]>>>;
+    setFormTaxonomies: Dispatch<SetStateAction<Record<string, string | number | string[] | number[]>>>;
     comments: Comment[];
     newCommentText: string;
-    setNewCommentText: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setNewCommentText: Dispatch<SetStateAction<string>>;
     attachments: (string | AttachmentItem)[];
-    setAttachments: import("react").Dispatch<import("react").SetStateAction<(string | AttachmentItem)[]>>;
+    setAttachments: Dispatch<SetStateAction<(string | AttachmentItem)[]>>;
     attachmentsDirty: boolean;
-    setAttachmentsDirty: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setAttachmentsDirty: Dispatch<SetStateAction<boolean>>;
     descriptionFocused: boolean;
-    setDescriptionFocused: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setDescriptionFocused: Dispatch<SetStateAction<boolean>>;
     showMarkdownHelp: boolean;
-    setShowMarkdownHelp: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowMarkdownHelp: Dispatch<SetStateAction<boolean>>;
     showChecklist: boolean;
-    setShowChecklist: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowChecklist: Dispatch<SetStateAction<boolean>>;
     showComments: boolean;
-    setShowComments: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowComments: Dispatch<SetStateAction<boolean>>;
     isCapturingScreenshot: boolean;
-    setIsCapturingScreenshot: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setIsCapturingScreenshot: Dispatch<SetStateAction<boolean>>;
     handleSubmit: (event: React.FormEvent) => Promise<void>;
     resetForm: () => void;
     handleAddComment: (text: string) => Promise<void>;
@@ -508,7 +601,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     returnToPreviousTask: () => boolean;
     autoSaveState: import("./tasks/useTaskFormActions").TaskAutoSaveState;
     unsavedModalOpen: boolean;
-    setUnsavedModalOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setUnsavedModalOpen: Dispatch<SetStateAction<boolean>>;
     pendingNavigation: (() => void) | null;
     handleNavigation: (action: () => void) => void;
     handleClose: () => void;
@@ -530,11 +623,11 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     confirmScheduleWarning: () => Promise<void>;
     cancelScheduleWarning: () => void;
     tasksScrollRef: import("react").RefObject<HTMLDivElement | null>;
-    setTasksScrollPos: import("react").Dispatch<import("react").SetStateAction<number>>;
+    setTasksScrollPos: Dispatch<SetStateAction<number>>;
     exportEnvironment: string;
-    setExportEnvironment: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setExportEnvironment: Dispatch<SetStateAction<string>>;
     exportWorkflowsPath: string;
-    setExportWorkflowsPath: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setExportWorkflowsPath: Dispatch<SetStateAction<string>>;
     exportResult: {
         type: "success" | "error";
         message: string;
@@ -569,7 +662,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     validatePaths: (paths: string[]) => Promise<void>;
     getCategoryPaths: (cat: CategoryConfig) => string[];
     customCategories: CategoryConfig[];
-    setCustomCategories: import("react").Dispatch<import("react").SetStateAction<CategoryConfig[]>>;
+    setCustomCategories: Dispatch<SetStateAction<CategoryConfig[]>>;
     projectRoot: string;
     projectName: string;
     mcpScriptPath: string;