@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/utils/taskDraftDefaults.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { resolveDraftDefaultsForGrouping } from './taskDraftDefaults';
+describe('resolveDraftDefaultsForGrouping', () => {
+    const categories = [
+        { value: 'default', label: 'General' },
+        { value: 'bugs', label: 'Bug' }
+    ];
+    const approaches = [
+        { value: 'default', label: 'General' },
+        { value: 'plan', label: 'Plan' }
+    ];
+    it('maps status completed column to done draft status', () => {
+        expect(resolveDraftDefaultsForGrouping('status', 'completed', { categories, approaches })).toEqual({
+            status: 'done'
+        });
+    });
+    it('maps assignee columns directly', () => {
+        expect(resolveDraftDefaultsForGrouping('assignee', 'member-1', { categories, approaches })).toEqual({
+            assignee: 'member-1'
+        });
+    });
+    it('maps schedule day columns but skips backlog', () => {
+        expect(resolveDraftDefaultsForGrouping('schedule', '2026-03-07', { categories, approaches })).toEqual({
+            scheduledDate: '2026-03-07'
+        });
+        expect(resolveDraftDefaultsForGrouping('schedule', 'backlog', { categories, approaches })).toEqual({});
+    });
+    it('maps approach into both approach and taxonomy approach defaults', () => {
+        expect(resolveDraftDefaultsForGrouping('approach', 'plan', { categories, approaches })).toEqual({
+            approach: 'plan',
+            taxonomyApproach: 'plan'
+        });
+    });
+});

package/dist/utils/taskNormalization.d.ts

@@ -0,0 +1,25 @@
+import type { CategoryConfig, PriorityDefinition, TaskItem } from '../types';
+export interface NormalizedPriorityDefinition {
+    value: number;
+    label: string;
+    color?: string;
+    icon?: string;
+}
+export declare const DEFAULT_PRIORITY_DEFINITIONS: NormalizedPriorityDefinition[];
+export declare function resolvePriorityValue(priority: unknown): number;
+export declare function normalizePriorityValue(priority: unknown): number;
+export declare function normalizePriorityDefinitions(priorities: PriorityDefinition[]): {
+    priorities: NormalizedPriorityDefinition[];
+    changed: boolean;
+};
+export declare function getPriorityClass(priority: string | number, fallbackLabel: string): string;
+export declare function normalizeTaskFromApi(task: any): TaskItem;
+export declare function mergeNormalizedTaskIntoCollections(task: unknown, tasks: TaskItem[], archivedTasks: TaskItem[]): {
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+};
+export declare function normalizePriorityFilterValues(filterPriorities: Array<string | number>, priorities: Array<{
+    value: number;
+}>): number[];
+export declare function matchesPriorityFilter(taskPriority: string | number | null | undefined, filterPriorities: Array<string | number>): boolean;
+export declare function normalizeCategoryFilters(filterCategories: string[], activeCategories: CategoryConfig[]): string[];

package/dist/utils/taskNormalization.js

@@ -0,0 +1,161 @@
+import { cloneDefaultPriorityDefinitions } from '../shared/taxonomyDefaults.js';
+import { formatTaskReference } from './taskReferences.js';
+export const DEFAULT_PRIORITY_DEFINITIONS = cloneDefaultPriorityDefinitions();
+const PRIORITY_VALUE_BY_LABEL = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+    'on-hold': 1,
+};
+const PRIORITY_CLASS_MAP = {
+    '1': 'low',
+    '2': 'medium',
+    '3': 'high',
+    '4': 'critical',
+    '5': 'critical',
+};
+function normalizeTaskStatus(status) {
+    const normalized = String(status || '').trim().toLowerCase();
+    if (normalized === 'blocked' || normalized === 'on hold' || normalized === 'on-hold')
+        return 'on-hold';
+    if (normalized === 'task'
+        || normalized === 'on-hold'
+        || normalized === 'in-progress'
+        || normalized === 'review'
+        || normalized === 'done'
+        || normalized === 'cancelled') {
+        return normalized;
+    }
+    return 'task';
+}
+export function resolvePriorityValue(priority) {
+    if (typeof priority === 'number' && Number.isFinite(priority)) {
+        return Math.max(1, Math.round(priority));
+    }
+    const numeric = Number(priority);
+    if (Number.isFinite(numeric)) {
+        return Math.max(1, Math.round(numeric));
+    }
+    return PRIORITY_VALUE_BY_LABEL[String(priority || '').trim().toLowerCase()] ?? 2;
+}
+export function normalizePriorityValue(priority) {
+    return resolvePriorityValue(priority);
+}
+export function normalizePriorityDefinitions(priorities) {
+    if (!Array.isArray(priorities) || priorities.length === 0) {
+        return { priorities: cloneDefaultPriorityDefinitions(), changed: true };
+    }
+    let changed = false;
+    const byValue = new Map();
+    for (const priority of priorities) {
+        const nextValue = normalizePriorityValue(priority.value);
+        if (nextValue !== priority.value)
+            changed = true;
+        if (byValue.has(nextValue)) {
+            changed = true;
+            continue;
+        }
+        byValue.set(nextValue, { ...priority, value: nextValue });
+    }
+    if (byValue.size === 0) {
+        return { priorities: cloneDefaultPriorityDefinitions(), changed: true };
+    }
+    return {
+        priorities: Array.from(byValue.values()).sort((a, b) => Number(a.value) - Number(b.value)),
+        changed
+    };
+}
+export function getPriorityClass(priority, fallbackLabel) {
+    return PRIORITY_CLASS_MAP[String(priority)] || fallbackLabel;
+}
+export function normalizeTaskFromApi(task) {
+    const referenceNumber = typeof task.referenceNumber === 'number'
+        ? task.referenceNumber
+        : Number.isFinite(Number(task.referenceNumber))
+            ? Number(task.referenceNumber)
+            : null;
+    return {
+        ...task,
+        referenceNumber: referenceNumber && referenceNumber > 0 ? Math.floor(referenceNumber) : null,
+        referenceLabel: typeof task.referenceLabel === 'string' && task.referenceLabel.trim().length > 0
+            ? task.referenceLabel.trim()
+            : formatTaskReference(referenceNumber),
+        assignee: (() => {
+            const raw = String(task.assignee || '').trim();
+            const normalized = raw.toLowerCase();
+            if (normalized === 'agent' || normalized === 'ai')
+                return 'agent';
+            if (!raw || normalized === 'user' || normalized === 'human' || normalized === 'unassigned' || normalized === 'none' || normalized === 'null') {
+                return 'unassigned';
+            }
+            return raw;
+        })(),
+        category: typeof task.category === 'string' ? task.category : task.category?.value || 'default',
+        type: (typeof task.type === 'string' ? task.type : task.type?.label || 'task').toLowerCase(),
+        priority: resolvePriorityValue(task.priority),
+        complexity: typeof task.complexity === 'number' ? task.complexity : 3,
+        status: normalizeTaskStatus(task.status)
+    };
+}
+export function mergeNormalizedTaskIntoCollections(task, tasks, archivedTasks) {
+    if (!task || typeof task !== 'object') {
+        return { tasks, archivedTasks };
+    }
+    const normalizedTask = normalizeTaskFromApi(task);
+    const taskId = String(normalizedTask.id || '').trim();
+    if (!taskId) {
+        return { tasks, archivedTasks };
+    }
+    const shouldArchive = Boolean(normalizedTask.isArchived);
+    const nextTask = shouldArchive
+        ? { ...normalizedTask, isArchived: true }
+        : { ...normalizedTask, isArchived: false };
+    const sortCollection = (items) => {
+        return [...items].sort((a, b) => {
+            const aTimestamp = Date.parse(String(a.updatedAt || a.createdAt || ''));
+            const bTimestamp = Date.parse(String(b.updatedAt || b.createdAt || ''));
+            if (Number.isFinite(aTimestamp) && Number.isFinite(bTimestamp) && aTimestamp !== bTimestamp) {
+                return bTimestamp - aTimestamp;
+            }
+            if (Number.isFinite(aTimestamp) !== Number.isFinite(bTimestamp)) {
+                return Number.isFinite(bTimestamp) ? 1 : -1;
+            }
+            const createdDelta = Date.parse(String(b.createdAt || '')) - Date.parse(String(a.createdAt || ''));
+            if (Number.isFinite(createdDelta) && createdDelta !== 0)
+                return createdDelta;
+            return String(a.id).localeCompare(String(b.id));
+        });
+    };
+    const nextTasks = tasks.filter((item) => item.id !== taskId);
+    const nextArchivedTasks = archivedTasks.filter((item) => item.id !== taskId);
+    if (shouldArchive) {
+        nextArchivedTasks.push(nextTask);
+    }
+    else {
+        nextTasks.push(nextTask);
+    }
+    return {
+        tasks: sortCollection(nextTasks),
+        archivedTasks: sortCollection(nextArchivedTasks)
+    };
+}
+export function normalizePriorityFilterValues(filterPriorities, priorities) {
+    if (!priorities.length || !filterPriorities.length)
+        return [];
+    const available = new Set(priorities.map((priority) => Number(priority.value)));
+    const normalized = Array.from(new Set(filterPriorities
+        .map((priority) => Number(priority))
+        .filter((priority) => Number.isFinite(priority) && available.has(priority))));
+    return normalized.length > 0 ? normalized : priorities.map((priority) => Number(priority.value));
+}
+export function matchesPriorityFilter(taskPriority, filterPriorities) {
+    return filterPriorities.some((filterPriority) => String(filterPriority) === String(taskPriority));
+}
+export function normalizeCategoryFilters(filterCategories, activeCategories) {
+    if (!filterCategories.length || !activeCategories.length)
+        return filterCategories;
+    const allowed = new Set(activeCategories.map((category) => category.value));
+    const normalized = Array.from(new Set(filterCategories.filter((filterCategory) => allowed.has(filterCategory))));
+    return normalized.length > 0 ? normalized : activeCategories.map((category) => category.value);
+}

package/dist/utils/taskNormalization.test.d.ts

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

package/dist/utils/taskNormalization.test.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+import { mergeNormalizedTaskIntoCollections, normalizeCategoryFilters, normalizePriorityDefinitions, resolvePriorityValue } from './taskNormalization';
+describe('normalizePriorityDefinitions', () => {
+    it('deduplicates while preserving the workspace-defined scale', () => {
+        const input = [
+            { value: 1, label: 'Low' },
+            { value: 2, label: 'Medium' },
+            { value: 3, label: 'High' },
+            { value: 4, label: 'Critical' },
+            { value: 4, label: 'Urgent' }
+        ];
+        const result = normalizePriorityDefinitions(input);
+        expect(result.changed).toBe(true);
+        expect(result.priorities.map((priority) => priority.value)).toEqual([1, 2, 3, 4]);
+        expect(result.priorities.find((priority) => priority.value === 4)?.label).toBe('Critical');
+    });
+    it('returns the emergency fallback when input is empty', () => {
+        const result = normalizePriorityDefinitions([]);
+        expect(result.changed).toBe(true);
+        expect(result.priorities.map((priority) => priority.value)).toEqual([2]);
+        expect(result.priorities.map((priority) => priority.label)).toEqual(['Medium']);
+    });
+    it('normalizes out-of-range values without forcing a canonical scale length', () => {
+        const input = [
+            { value: -1, label: 'Too Low' },
+            { value: 9, label: 'Too High' }
+        ];
+        const result = normalizePriorityDefinitions(input);
+        expect(result.changed).toBe(true);
+        expect(result.priorities.map((priority) => priority.value)).toEqual([1, 9]);
+    });
+    it('preserves smaller custom scales', () => {
+        const input = [
+            { value: 1, label: 'Normal' },
+            { value: 2, label: 'Urgent' }
+        ];
+        const result = normalizePriorityDefinitions(input);
+        expect(result.changed).toBe(false);
+        expect(result.priorities.map((priority) => priority.value)).toEqual([1, 2]);
+        expect(result.priorities.map((priority) => priority.label)).toEqual(['Normal', 'Urgent']);
+    });
+});
+describe('resolvePriorityValue', () => {
+    it('preserves a critical priority value of 4', () => {
+        expect(resolvePriorityValue(4)).toBe(4);
+        expect(resolvePriorityValue('4')).toBe(4);
+        expect(resolvePriorityValue('critical')).toBe(4);
+    });
+});
+describe('mergeNormalizedTaskIntoCollections', () => {
+    it('replaces the matching active task with the normalized server task', () => {
+        const activeTask = {
+            id: 'task-1',
+            title: 'Local task',
+            category: 'general',
+            type: 'feature',
+            priority: 2,
+            complexity: 3,
+            status: 'task',
+            createdAt: '2026-03-15T10:00:00.000Z',
+            updatedAt: '2026-03-15T10:00:00.000Z'
+        };
+        const result = mergeNormalizedTaskIntoCollections({
+            ...activeTask,
+            status: 'in-progress',
+            updatedAt: '2026-03-15T10:05:00.000Z'
+        }, [activeTask], []);
+        expect(result.tasks).toHaveLength(1);
+        expect(result.tasks[0].status).toBe('in-progress');
+        expect(result.tasks[0].updatedAt).toBe('2026-03-15T10:05:00.000Z');
+    });
+    it('replaces the matching archived task without mutating other entries', () => {
+        const archivedTask = {
+            id: 'task-2',
+            title: 'Archived task',
+            category: 'general',
+            type: 'feature',
+            priority: 2,
+            complexity: 3,
+            status: 'review',
+            isArchived: true,
+            createdAt: '2026-03-15T11:00:00.000Z',
+            updatedAt: '2026-03-15T11:00:00.000Z'
+        };
+        const untouchedTask = {
+            id: 'task-3',
+            title: 'Untouched',
+            category: 'general',
+            type: 'feature',
+            priority: 2,
+            complexity: 3,
+            status: 'task',
+            createdAt: '2026-03-15T11:10:00.000Z',
+            updatedAt: '2026-03-15T11:10:00.000Z'
+        };
+        const result = mergeNormalizedTaskIntoCollections({
+            ...archivedTask,
+            updatedAt: '2026-03-15T11:15:00.000Z',
+            status: 'review'
+        }, [untouchedTask], [archivedTask]);
+        expect(result.tasks[0]).toEqual(untouchedTask);
+        expect(result.archivedTasks[0].updatedAt).toBe('2026-03-15T11:15:00.000Z');
+    });
+    it('normalizes a missing task insert without legacy child-task fields', () => {
+        const result = mergeNormalizedTaskIntoCollections({
+            id: 'task-new',
+            title: 'New task',
+            category: 'general',
+            type: 'feature',
+            priority: 2,
+            complexity: 3,
+            status: 'review',
+            createdAt: '2026-03-15T12:00:00.000Z',
+            updatedAt: '2026-03-15T12:05:00.000Z'
+        }, [], []);
+        expect(result.tasks).toHaveLength(1);
+        expect(result.tasks[0].id).toBe('task-new');
+        expect(result.tasks[0].status).toBe('review');
+        expect(result.archivedTasks).toEqual([]);
+    });
+    it('moves archived tasks back into the active collection when the server clears isArchived', () => {
+        const archivedTask = {
+            id: 'task-archived',
+            title: 'Archived task',
+            category: 'general',
+            type: 'feature',
+            priority: 2,
+            complexity: 3,
+            status: 'done',
+            isArchived: true,
+            createdAt: '2026-03-15T11:00:00.000Z',
+            updatedAt: '2026-03-15T11:00:00.000Z'
+        };
+        const result = mergeNormalizedTaskIntoCollections({
+            ...archivedTask,
+            status: 'in-progress',
+            isArchived: false,
+            updatedAt: '2026-03-15T11:15:00.000Z'
+        }, [], [archivedTask]);
+        expect(result.tasks).toHaveLength(1);
+        expect(result.tasks[0].status).toBe('in-progress');
+        expect(result.tasks[0].isArchived).toBe(false);
+        expect(result.archivedTasks).toEqual([]);
+    });
+});
+describe('normalizeCategoryFilters', () => {
+    const activeCategories = [
+        { value: 'default', label: 'Default' },
+        { value: 'product', label: 'Product' },
+        { value: 'ops', label: 'Ops' }
+    ];
+    it('keeps a valid persisted category selection', () => {
+        expect(normalizeCategoryFilters(['product'], activeCategories)).toEqual(['product']);
+    });
+    it('falls back to all categories when the persisted selection no longer exists', () => {
+        expect(normalizeCategoryFilters(['missing-category'], activeCategories)).toEqual(['default', 'product', 'ops']);
+    });
+});

package/dist/utils/taskReferences.d.ts

@@ -0,0 +1,5 @@
+import type { TaskItem } from '../types';
+export declare const TASK_REFERENCE_PREFIX = "T-";
+export declare function formatTaskReference(value: number | Pick<TaskItem, 'referenceNumber'> | null | undefined): string;
+export declare function parseTaskReference(value: string | null | undefined): number | null;
+export declare function getTaskReferenceLabel(task: Pick<TaskItem, 'referenceNumber' | 'referenceLabel'> | null | undefined): string;

package/dist/utils/taskReferences.js

@@ -0,0 +1,11 @@
+import { formatEntityReference, getEntityReferenceLabel, parseEntityReference, } from './entityReferences.js';
+export const TASK_REFERENCE_PREFIX = 'T-';
+export function formatTaskReference(value) {
+    return formatEntityReference(TASK_REFERENCE_PREFIX, value);
+}
+export function parseTaskReference(value) {
+    return parseEntityReference(TASK_REFERENCE_PREFIX, value);
+}
+export function getTaskReferenceLabel(task) {
+    return getEntityReferenceLabel(TASK_REFERENCE_PREFIX, task);
+}

package/dist/utils/taskforceApiClient.d.ts

@@ -1,3 +1,5 @@
+export declare function persistLocalMutationActorUserId(userId?: string | null): void;
+export declare function readLocalMutationActorUserId(): string;
 export declare function resolveTaskforceApiUrl(path: string, apiBaseUrl?: string): string;
 /**
  * Fetches Taskforce API endpoints with a resilient fallback:

package/dist/utils/taskforceApiClient.js

@@ -1,6 +1,64 @@
+import { logBootstrapDebug } from '../hooks/workspace/workspaceLocalState';
+const LOCAL_MUTATION_ACTOR_STORAGE_KEY = 'taskforce.localMutationActorUserId.v1';
 function normalizeApiBaseUrl(apiBaseUrl) {
     return typeof apiBaseUrl === 'string' ? apiBaseUrl.trim().replace(/\/+$/, '') : '';
 }
+function isLoopbackOrigin(hostname) {
+    const normalized = String(hostname || '').trim().toLowerCase();
+    return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1' || normalized === '[::1]';
+}
+export function persistLocalMutationActorUserId(userId) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const normalized = String(userId || '').trim();
+        if (!normalized || normalized === 'anonymous') {
+            window.sessionStorage.removeItem(LOCAL_MUTATION_ACTOR_STORAGE_KEY);
+            return;
+        }
+        window.sessionStorage.setItem(LOCAL_MUTATION_ACTOR_STORAGE_KEY, normalized);
+    }
+    catch {
+        // best-effort only
+    }
+}
+export function readLocalMutationActorUserId() {
+    if (typeof window === 'undefined')
+        return '';
+    try {
+        return String(window.sessionStorage.getItem(LOCAL_MUTATION_ACTOR_STORAGE_KEY) || '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function shouldAttachLocalMutationActor(path, resolvedUrl) {
+    if (typeof window === 'undefined')
+        return false;
+    if (!path.startsWith('/api/taskforce/'))
+        return false;
+    if (!isLoopbackOrigin(window.location.hostname))
+        return false;
+    try {
+        const url = new URL(resolvedUrl, window.location.origin);
+        return url.origin === window.location.origin;
+    }
+    catch {
+        return path.startsWith('/');
+    }
+}
+function withLocalMutationActorHeader(path, resolvedUrl, init) {
+    if (!shouldAttachLocalMutationActor(path, resolvedUrl))
+        return init;
+    const actorUserId = readLocalMutationActorUserId();
+    if (!actorUserId)
+        return init;
+    const headers = new Headers(init?.headers || undefined);
+    if (!headers.has('x-taskforce-user-id')) {
+        headers.set('x-taskforce-user-id', actorUserId);
+    }
+    return { ...init, headers };
+}
 export function resolveTaskforceApiUrl(path, apiBaseUrl) {
     if (!path.startsWith('/'))
         return path;
@@ -17,8 +75,10 @@ export function resolveTaskforceApiUrl(path, apiBaseUrl) {
 export async function fetchTaskforceApi(path, init, apiBaseUrl) {
     const primaryUrl = resolveTaskforceApiUrl(path, apiBaseUrl);
     const hasConfiguredBase = normalizeApiBaseUrl(apiBaseUrl).length > 0;
+    const requestInit = withLocalMutationActorHeader(path, primaryUrl, init);
+    const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
     try {
-        const primaryResponse = await fetch(primaryUrl, init);
+        const primaryResponse = await fetch(primaryUrl, requestInit);
         const shouldRetryAuthFallback = hasConfiguredBase
             && primaryUrl !== path
             && path.startsWith('/api/taskforce/')
@@ -26,10 +86,33 @@ export async function fetchTaskforceApi(path, init, apiBaseUrl) {
         if (!shouldRetryAuthFallback) {
             return primaryResponse;
         }
+        logBootstrapDebug('taskforce_api_auth_fallback_retry', {
+            path,
+            primaryUrl,
+            fallbackUrl: path,
+            status: primaryResponse.status,
+            durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt),
+        });
         try {
-            return await fetch(path, init);
+            const fallbackResponse = await fetch(path, requestInit);
+            logBootstrapDebug('taskforce_api_auth_fallback_completed', {
+                path,
+                primaryUrl,
+                fallbackUrl: path,
+                primaryStatus: primaryResponse.status,
+                fallbackStatus: fallbackResponse.status,
+                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt),
+            });
+            return fallbackResponse;
         }
         catch {
+            logBootstrapDebug('taskforce_api_auth_fallback_failed', {
+                path,
+                primaryUrl,
+                fallbackUrl: path,
+                status: primaryResponse.status,
+                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt),
+            });
             return primaryResponse;
         }
     }
@@ -37,6 +120,21 @@ export async function fetchTaskforceApi(path, init, apiBaseUrl) {
         if (!hasConfiguredBase || !path.startsWith('/')) {
             throw primaryError;
         }
-        return fetch(path, init);
+        logBootstrapDebug('taskforce_api_network_fallback_retry', {
+            path,
+            primaryUrl,
+            fallbackUrl: path,
+            durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt),
+            error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+        });
+        const fallbackResponse = await fetch(path, requestInit);
+        logBootstrapDebug('taskforce_api_network_fallback_completed', {
+            path,
+            primaryUrl,
+            fallbackUrl: path,
+            fallbackStatus: fallbackResponse.status,
+            durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt),
+        });
+        return fallbackResponse;
     }
 }

package/dist/utils/taskforceApiClient.test.d.ts

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

package/dist/utils/taskforceApiClient.test.js

@@ -0,0 +1,44 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fetchTaskforceApi, persistLocalMutationActorUserId, readLocalMutationActorUserId, } from './taskforceApiClient';
+describe('taskforceApiClient local mutation actor header', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        persistLocalMutationActorUserId(null);
+        window.history.replaceState({}, '', '/');
+    });
+    afterEach(() => {
+        persistLocalMutationActorUserId(null);
+    });
+    it('adds the local mutation actor header on same-origin taskforce api requests', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        persistLocalMutationActorUserId('user-test-06');
+        await fetchTaskforceApi('/api/taskforce/annotated-attachments/sessions', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: '{}',
+        });
+        expect(readLocalMutationActorUserId()).toBe('user-test-06');
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [, init] = fetchMock.mock.calls[0];
+        const headers = new Headers(init.headers);
+        expect(headers.get('x-taskforce-user-id')).toBe('user-test-06');
+        expect(headers.get('content-type')).toBe('application/json');
+    });
+    it('does not override an explicit user id header', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        persistLocalMutationActorUserId('user-test-06');
+        await fetchTaskforceApi('/api/taskforce/annotated-attachments/sessions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-taskforce-user-id': 'user-explicit',
+            },
+            body: '{}',
+        });
+        const [, init] = fetchMock.mock.calls[0];
+        const headers = new Headers(init.headers);
+        expect(headers.get('x-taskforce-user-id')).toBe('user-explicit');
+    });
+});

package/dist/utils/taxonomyFilterOptions.d.ts

@@ -0,0 +1,2 @@
+import type { TaskItem, TaxonomyDefinition, TaxonomyOption } from '../types';
+export declare function getFilterVisibleTaxonomyOptions(taxonomy: TaxonomyDefinition, tasks: TaskItem[]): TaxonomyOption[];

package/dist/utils/taxonomyFilterOptions.js

@@ -0,0 +1,17 @@
+function taskUsesTaxonomyOption(task, taxonomyId, optionValue) {
+    const taskValue = task.taxonomies?.[taxonomyId];
+    if (taskValue === undefined || taskValue === null || taskValue === '')
+        return false;
+    if (Array.isArray(taskValue)) {
+        return taskValue.some((value) => String(value) === String(optionValue));
+    }
+    return String(taskValue) === String(optionValue);
+}
+export function getFilterVisibleTaxonomyOptions(taxonomy, tasks) {
+    const activeOptions = taxonomy.options.filter((option) => option.status !== 'retired');
+    const retiredOptionsInUse = taxonomy.options.filter((option) => (option.status === 'retired' && tasks.some((task) => taskUsesTaxonomyOption(task, taxonomy.id, option.value))));
+    return [
+        ...activeOptions,
+        ...retiredOptionsInUse.filter((option) => !activeOptions.some((active) => String(active.value) === String(option.value)))
+    ];
+}

package/dist/utils/taxonomyFormDefaults.d.ts

@@ -0,0 +1,3 @@
+import type { TaxonomyDefinition } from '../types';
+export declare function buildDefaultFormTaxonomies(taxonomies: TaxonomyDefinition[]): Record<string, string | number | string[] | number[]>;
+export declare function getVisibleTaskFormTaxonomies(taxonomies: TaxonomyDefinition[], formTaxonomies: Record<string, string | number | string[] | number[]>): TaxonomyDefinition[];

package/dist/utils/taxonomyFormDefaults.js

@@ -0,0 +1,28 @@
+export function buildDefaultFormTaxonomies(taxonomies) {
+    const defaults = {};
+    taxonomies.forEach((taxonomy) => {
+        const defaultValue = taxonomy.defaultValue;
+        if (defaultValue === undefined || defaultValue === null)
+            return;
+        if (Array.isArray(defaultValue)) {
+            if (defaultValue.length > 0) {
+                defaults[taxonomy.id] = defaultValue.map((value) => (typeof value === 'number' ? value : String(value)));
+            }
+            return;
+        }
+        defaults[taxonomy.id] = typeof defaultValue === 'number' ? defaultValue : String(defaultValue);
+    });
+    return defaults;
+}
+export function getVisibleTaskFormTaxonomies(taxonomies, formTaxonomies) {
+    return taxonomies.filter((taxonomy) => {
+        const currentValue = formTaxonomies[taxonomy.id];
+        const hasSelectedValue = Array.isArray(currentValue)
+            ? currentValue.length > 0
+            : currentValue !== undefined && currentValue !== null && currentValue !== '';
+        const isRetired = taxonomy.status === 'retired';
+        if (isRetired && !hasSelectedValue)
+            return false;
+        return taxonomy.formEnabled !== false || taxonomy.isRequired === true || hasSelectedValue;
+    });
+}

package/dist/utils/taxonomyFormDefaults.test.d.ts

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