@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/components/features/TaskSettings.test.js

@@ -109,6 +109,17 @@ describe('TaskSettings Component', () => {
         };
         return render(_jsx(TaskSettings, { ...props }));
     };
+    const openMcpSettings = async (user) => {
+        await user.click(screen.getByRole('button', { name: /MCP/i }));
+    };
+    const openCloudMcpSettings = async (user) => {
+        await openMcpSettings(user);
+        const cloudToggle = screen.queryByRole('button', { name: 'Cloud MCP' });
+        if (cloudToggle) {
+            await user.click(cloudToggle);
+        }
+        await screen.findByText('Cloud MCP Configuration');
+    };
     const originalFetch = global.fetch;
     it('4.1 Open settings - Renders correctly', () => {
         renderComponent();
@@ -859,7 +870,7 @@ describe('TaskSettings Component', () => {
             credentials: 'include'
         }));
     }, 10000);
-    it('4.21 Local authenticated runtime defaults MCP tab to cloud with toggle', async () => {
+    it('4.21 Local authenticated runtime defaults MCP tab to local with local-first toggle', async () => {
         const fetchCloudAuthApi = vi.fn(async () => ({
             ok: true,
             json: async () => ({ items: [] })
@@ -875,15 +886,17 @@ describe('TaskSettings Component', () => {
             }
         });
         await user.click(screen.getByRole('button', { name: /MCP/i }));
-        expect(await screen.findByRole('button', { name: 'Cloud MCP' })).toBeInTheDocument();
-        expect(screen.getByRole('button', { name: 'Local MCP' })).toBeInTheDocument();
-        expect(screen.getByText('Cloud MCP Configuration')).toBeInTheDocument();
-        expect(screen.getAllByText(/https:\/\/mcp\.taskforcehq\.ai\/mcp/).length).toBeGreaterThan(0);
-        expect(screen.queryByText('MCP Path Mapping (Host Root)')).not.toBeInTheDocument();
-        await user.click(screen.getByRole('button', { name: 'Local MCP' }));
+        const localButton = await screen.findByRole('button', { name: 'Local MCP' });
+        const cloudButton = screen.getByRole('button', { name: 'Cloud MCP' });
+        expect(localButton.compareDocumentPosition(cloudButton) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+        expect(screen.getByText('Local MCP Configuration')).toBeInTheDocument();
+        expect(screen.queryByText('Cloud MCP Configuration')).not.toBeInTheDocument();
         expect(screen.queryByText('MCP Path Mapping (Host Root)')).not.toBeInTheDocument();
         await user.click(screen.getByRole('button', { name: 'Advanced' }));
         expect(screen.getByText('MCP Path Mapping (Host Root)')).toBeInTheDocument();
+        await user.click(cloudButton);
+        expect(screen.getByText('Cloud MCP Configuration')).toBeInTheDocument();
+        expect(screen.getAllByText(/https:\/\/mcp\.taskforcehq\.ai\/mcp/).length).toBeGreaterThan(0);
         expect(fetchCloudAuthApi).toHaveBeenCalledWith('/api/taskforce/settings/mcp/tokens', expect.objectContaining({
             method: 'GET',
             credentials: 'include'
@@ -900,7 +913,7 @@ describe('TaskSettings Component', () => {
                             id: 'mcp-token-1',
                             name: 'Workspace Alpha MCP',
                             tokenPrefix: 'tfmcp_example',
-                            scopes: ['tasks:read', 'tasks:write'],
+                            scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
                             status: 'active',
                             createdAt: new Date().toISOString()
                         }
@@ -921,12 +934,19 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        await user.click(await screen.findByRole('button', { name: 'Generate Token' }));
+        await openCloudMcpSettings(user);
+        await user.click(screen.getByRole('button', { name: 'Generate Token' }));
         expect(fetchCloudAuthApi).toHaveBeenCalledWith('/api/taskforce/settings/mcp/tokens', expect.objectContaining({
             method: 'POST',
             credentials: 'include'
         }));
+        expect(fetchCloudAuthApi).toHaveBeenCalledWith('/api/taskforce/settings/mcp/tokens', expect.objectContaining({
+            body: JSON.stringify({
+                name: 'Workspace Alpha MCP',
+                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                expiresAt: null
+            })
+        }));
         expect((await screen.findAllByText('tfmcp_example_secret')).length).toBeGreaterThan(0);
     }, 10000);
     it('4.23c MCP token name defaults to the workspace name', async () => {
@@ -938,7 +958,7 @@ describe('TaskSettings Component', () => {
                 currentWorkspaceName: 'Workspace Alpha'
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         expect(await screen.findByDisplayValue('Workspace Alpha MCP')).toBeInTheDocument();
     });
     it('4.23d MCP test connection uses the provided cloud auth helper', async () => {
@@ -950,7 +970,8 @@ describe('TaskSettings Component', () => {
                         result: {
                             workspaceName: 'Workspace Alpha',
                             workspaceId: 'workspace-alpha',
-                            scopes: ['tasks:read', 'tasks:write']
+                            scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                            endpoint: 'https://performance-mcp.taskforcehq.ai/mcp'
                         }
                     })
                 };
@@ -969,7 +990,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.click(screen.getByRole('button', { name: 'Test Connection' }));
         await user.type(await screen.findByPlaceholderText('tfmcp_xxxxx_replace-me'), 'tfmcp_example_secret');
         await user.click(screen.getAllByRole('button', { name: 'Test Connection' })[1]);
@@ -978,7 +999,47 @@ describe('TaskSettings Component', () => {
             credentials: 'include'
         }));
         expect(await screen.findByText('Connection looks good for this workspace.')).toBeInTheDocument();
-        expect(screen.getByText(/Granted scopes: tasks:read, tasks:write/i)).toBeInTheDocument();
+        expect(screen.getByText(/Granted scopes: tasks:read, tasks:write, workspace:read/i)).toBeInTheDocument();
+        expect(screen.getByText(/Endpoint: https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/i)).toBeInTheDocument();
+    }, 10000);
+    it('4.23d2 MCP test connection shows a dedicated-host incident message when the endpoint returns a gateway failure', async () => {
+        const fetchCloudAuthApi = vi.fn(async (path) => {
+            if (path === '/api/taskforce/settings/mcp/test-connection') {
+                return {
+                    ok: false,
+                    json: async () => ({
+                        code: 'MCP_ENDPOINT_GATEWAY_ERROR',
+                        error: 'Cloud MCP endpoint https://performance-mcp.taskforcehq.ai/mcp returned 502.',
+                        details: {
+                            endpoint: 'https://performance-mcp.taskforcehq.ai/mcp',
+                            upstreamStatus: 502
+                        }
+                    })
+                };
+            }
+            return {
+                ok: true,
+                json: async () => ({ items: [] })
+            };
+        });
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: true,
+                currentWorkspaceName: 'Workspace Alpha',
+                cloudMcpBaseUrl: 'https://performance-mcp.taskforcehq.ai',
+                fetchCloudAuthApi
+            }
+        });
+        await openCloudMcpSettings(user);
+        await user.click(screen.getByRole('button', { name: 'Test Connection' }));
+        await user.type(await screen.findByPlaceholderText('tfmcp_xxxxx_replace-me'), 'tfmcp_example_secret');
+        await user.click(screen.getAllByRole('button', { name: 'Test Connection' })[1]);
+        expect(await screen.findByText('The dedicated MCP host is responding with a gateway error.')).toBeInTheDocument();
+        expect(screen.getByText(/Endpoint: https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/i)).toBeInTheDocument();
+        expect(screen.getByText(/Error code: MCP_ENDPOINT_GATEWAY_ERROR/i)).toBeInTheDocument();
+        expect(screen.getByText(/This usually means the cloud MCP service is degraded/i)).toBeInTheDocument();
     }, 10000);
     it('4.23e Antigravity uses serverUrl instead of transport in the cloud snippet', async () => {
         const fetchCloudAuthApi = vi.fn(async () => ({
@@ -995,7 +1056,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'antigravity');
         const snippetMatches = await screen.findAllByText(/serverUrl/);
         expect(snippetMatches.length).toBeGreaterThan(0);
@@ -1018,7 +1079,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         expect(await screen.findByText(/https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/)).toBeInTheDocument();
         expect(screen.queryByText(/https:\/\/performance-app\.taskforcehq\.ai\/mcp/)).not.toBeInTheDocument();
     }, 10000);
@@ -1038,7 +1099,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         expect(await screen.findByText(/https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/)).toBeInTheDocument();
         expect(screen.queryByText(/https:\/\/performance-app\.taskforcehq\.ai\/mcp/)).not.toBeInTheDocument();
     }, 10000);
@@ -1057,7 +1118,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         const urlMatches = await screen.findAllByText(/"url"/);
         expect(urlMatches.length).toBeGreaterThan(0);
         expect(screen.getAllByText(/https:\/\/mcp\.taskforcehq\.ai\/mcp/).length).toBeGreaterThan(0);
@@ -1079,7 +1140,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'cline');
         expect(await screen.findByText(/Cline Configuration Instructions/i)).toBeInTheDocument();
         expect(screen.getByText(/"type"/)).toBeInTheDocument();
@@ -1101,7 +1162,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'vscode');
         expect(await screen.findByText(/VS Code Configuration Instructions/i)).toBeInTheDocument();
         expect(screen.getByText(/"servers"/)).toBeInTheDocument();
@@ -1123,7 +1184,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'codex');
         expect((await screen.findAllByText(/\.codex\/config\.toml/i)).length).toBeGreaterThan(0);
         expect(screen.getByText(/\[mcp_servers\./)).toBeInTheDocument();
@@ -1145,7 +1206,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'claude-code');
         expect(await screen.findByText(/Claude Code Configuration Instructions/i)).toBeInTheDocument();
         expect(screen.getByText(/claude mcp add --transport http/i)).toBeInTheDocument();
@@ -1167,7 +1228,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'gemini-cli');
         expect(await screen.findByText(/Gemini CLI Configuration Instructions/i)).toBeInTheDocument();
         expect(screen.getByText(/gemini mcp add taskforce-/i)).toBeInTheDocument();
@@ -1190,7 +1251,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'openclaw');
         expect(await screen.findByText(/OpenClaw Configuration Instructions/i)).toBeInTheDocument();
         expect((await screen.findAllByText(/~\/\.openclaw\/openclaw\.json/i)).length).toBeGreaterThan(0);
@@ -1217,10 +1278,10 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         expect(screen.queryByRole('option', { name: /Claude Desktop/i })).not.toBeInTheDocument();
         expect(screen.queryByRole('option', { name: /ChatGPT Desktop/i })).not.toBeInTheDocument();
-        expect(await screen.findByText('Cursor Configuration Instructions')).toBeInTheDocument();
+        expect(await screen.findByText('General MCP Configuration Instructions')).toBeInTheDocument();
     }, 10000);
     it('4.23e4b Integrations tab shows ChatGPT and Claude connector management separately from PAT tokens', async () => {
         const fetchCloudAuthApi = vi.fn(async (path) => {
@@ -1294,8 +1355,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        expect(await screen.findByText('Cloud MCP Configuration')).toBeInTheDocument();
+        await openCloudMcpSettings(user);
         expect(screen.queryByText('ChatGPT Connector')).not.toBeInTheDocument();
         expect(screen.queryByText(/^Connectors$/)).not.toBeInTheDocument();
     }, 10000);
@@ -1309,8 +1369,7 @@ describe('TaskSettings Component', () => {
                 cloudMcpBaseUrl: 'https://mcp.taskforcehq.ai',
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        expect(await screen.findByText('Cloud MCP Configuration')).toBeInTheDocument();
+        await openCloudMcpSettings(user);
         expect(screen.getAllByRole('button', { name: /copy/i }).length).toBeGreaterThan(0);
     }, 10000);
     it('4.23g1 Cloud MCP copy warns before a token is generated', async () => {
@@ -1323,8 +1382,7 @@ describe('TaskSettings Component', () => {
                 cloudMcpBaseUrl: 'https://mcp.taskforcehq.ai',
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        await screen.findByText('Cloud MCP Configuration');
+        await openCloudMcpSettings(user);
         await user.click(screen.getByTitle('Copy full configuration file'));
         expect(screen.getByText('Generate a token before copying the Cloud MCP configuration.')).toBeInTheDocument();
     }, 10000);
@@ -1338,8 +1396,7 @@ describe('TaskSettings Component', () => {
                 cloudMcpBaseUrl: 'https://mcp.taskforcehq.ai',
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        await screen.findByText('Cloud MCP Configuration');
+        await openCloudMcpSettings(user);
         expect(screen.queryByText('Automation Identity (Optional)')).not.toBeInTheDocument();
         expect(screen.queryByRole('combobox', { name: 'Use existing AI profile' })).not.toBeInTheDocument();
     }, 10000);
@@ -1353,8 +1410,7 @@ describe('TaskSettings Component', () => {
                 cloudMcpBaseUrl: 'https://mcp.taskforcehq.ai',
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        await screen.findByText('Cloud MCP Configuration');
+        await openCloudMcpSettings(user);
         await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'codex');
         expect(screen.queryByText(/X-Taskforce-AI-Name/i)).not.toBeInTheDocument();
         expect(screen.queryByText(/X-Taskforce-AI-Profile-Token/i)).not.toBeInTheDocument();
@@ -1394,7 +1450,7 @@ describe('TaskSettings Component', () => {
                 fetchCloudAuthApi
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await openCloudMcpSettings(user);
         expect(await screen.findByText('Current Token')).toBeInTheDocument();
         expect(screen.getByText('Old Token')).toBeInTheDocument();
         const tokenLabels = screen.getAllByText(/^(Current Token|Old Token)$/);
@@ -1414,8 +1470,7 @@ describe('TaskSettings Component', () => {
                 cloudMcpBaseUrl: 'https://mcp.taskforcehq.ai',
             }
         });
-        await user.click(screen.getByRole('button', { name: /MCP/i }));
-        await screen.findByText('Cloud MCP Configuration');
+        await openCloudMcpSettings(user);
         const codeNodes = Array.from(document.querySelectorAll('code'));
         const snippetNode = codeNodes.find((node) => node.textContent?.includes('"mcpServers"'));
         expect(snippetNode).toBeTruthy();
@@ -1435,11 +1490,96 @@ describe('TaskSettings Component', () => {
         });
         await user.click(screen.getByRole('button', { name: /MCP/i }));
         expect(screen.getByText('Local MCP')).toBeInTheDocument();
-        expect(screen.getByText(/Claude Code CLI, Gemini CLI/i)).toBeInTheDocument();
+        expect(screen.getByRole('combobox', { name: 'MCP client' })).toHaveValue('general');
+        expect(screen.getByText('General MCP Configuration Instructions')).toBeInTheDocument();
         expect(screen.queryByText('MCP Path Mapping (Host Root)')).not.toBeInTheDocument();
         await user.click(screen.getByRole('button', { name: 'Advanced' }));
         expect(screen.getByText('MCP Path Mapping (Host Root)')).toBeInTheDocument();
         expect(screen.queryByText('Cloud MCP Configuration')).not.toBeInTheDocument();
         expect(screen.queryByRole('button', { name: 'Cloud MCP' })).not.toBeInTheDocument();
     });
+    it('4.24a Local MCP selector offers General first and keeps the rest alphabetical', async () => {
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: false
+            }
+        });
+        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        const options = screen.getAllByRole('option').map((option) => option.textContent);
+        expect(options).toEqual([
+            'General',
+            'Antigravity',
+            'Claude Code CLI',
+            'Cline',
+            'Codex',
+            'Cursor',
+            'Gemini CLI',
+            'OpenClaw',
+            'VS Code / Copilot',
+            'Windsurf'
+        ]);
+    });
+    it('4.24b Local Codex shows config.toml MCP output without token headers', async () => {
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: false,
+                projectRoot: '/Users/rossburke/projects/taskforce',
+                projectName: 'taskforce',
+                tenantId: 'tenant-alpha',
+                workspaceId: 'workspace-alpha',
+                mcpScriptPath: '/usr/local/bin/taskforce'
+            }
+        });
+        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'codex');
+        expect(await screen.findByText(/Codex Configuration Instructions/i)).toBeInTheDocument();
+        expect((await screen.findAllByText(/\.codex\/config\.toml/i)).length).toBeGreaterThan(0);
+        expect(screen.getByText(/\[mcp_servers\./)).toBeInTheDocument();
+        expect(screen.getByText(/command = "taskforce"/i)).toBeInTheDocument();
+        expect(screen.queryByText(/Authorization/i)).not.toBeInTheDocument();
+    });
+    it('4.24c Local VS Code uses stdio config under servers', async () => {
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: false,
+                projectRoot: '/Users/rossburke/projects/taskforce',
+                projectName: 'taskforce',
+                tenantId: 'tenant-alpha',
+                workspaceId: 'workspace-alpha',
+                mcpScriptPath: '/usr/local/bin/taskforce'
+            }
+        });
+        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'vscode');
+        expect(await screen.findByText(/VS Code Configuration Instructions/i)).toBeInTheDocument();
+        expect(screen.getByText(/"servers"/)).toBeInTheDocument();
+        expect(screen.getByText(/"type"/)).toBeInTheDocument();
+        expect(screen.getByText(/"stdio"/)).toBeInTheDocument();
+    });
+    it('4.24d Local Claude Code shows a stdio add command', async () => {
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: false,
+                projectRoot: '/Users/rossburke/projects/taskforce',
+                projectName: 'taskforce',
+                tenantId: 'tenant-alpha',
+                workspaceId: 'workspace-alpha',
+                mcpScriptPath: '/usr/local/bin/taskforce'
+            }
+        });
+        await user.click(screen.getByRole('button', { name: /MCP/i }));
+        await user.selectOptions(screen.getByRole('combobox', { name: 'MCP client' }), 'claude-code');
+        expect(await screen.findByText(/Claude Code Configuration Instructions/i)).toBeInTheDocument();
+        expect(screen.getByText(/claude mcp add taskforce-/i)).toBeInTheDocument();
+        expect(screen.getByText(/--env TASKFORCE_TENANT_ID=tenant-alpha/i)).toBeInTheDocument();
+        expect(screen.getByText(/-- taskforce mcp/i)).toBeInTheDocument();
+    });
 });

package/dist/components/features/documentWorkspaceModel.d.ts

@@ -0,0 +1,24 @@
+import type { DocumentAttachmentFilter, DocumentTypeFilter } from './documentWorkspaceFilters';
+export interface DocMeta {
+    id: string;
+    assetId?: string;
+    referenceNumber?: number | null;
+    referenceLabel?: string | null;
+    fsPath: string;
+    apiUrl: string;
+    taskId: string | null;
+    displayName: string;
+    originalFilename?: string | null;
+    title: string;
+    docType: 'implementation-plan' | 'review' | 'walkthrough' | 'planning' | 'other';
+    sizeBytes: number;
+    updatedAt: string | null;
+    editable?: boolean;
+    attachmentCount?: number;
+    attachmentState?: 'attached' | 'unattached' | 'standalone';
+}
+export declare function normalizeDocPath(value: string): string;
+export declare function docPathMatches(candidate: string, requested: string): boolean;
+export declare function extractAssetIdFromPath(value: string | null | undefined): string | null;
+export declare function getEffectiveAttachmentState(doc: Pick<DocMeta, 'attachmentState' | 'attachmentCount' | 'taskId'>): 'attached' | 'unattached';
+export declare function filterDocuments(documents: DocMeta[], searchQuery: string, typeFilters: DocumentTypeFilter[], attachmentFilters: DocumentAttachmentFilter[]): DocMeta[];

package/dist/components/features/documentWorkspaceModel.js

@@ -0,0 +1,57 @@
+import { getReadableDocumentName } from '../../utils/documentNames';
+export function normalizeDocPath(value) {
+    let decoded = value;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        decoded = value;
+    }
+    const normalized = decoded
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\/+/, '')
+        .replace(/^\.\//, '')
+        .replace(/^\.taskforce\//, '');
+    return normalized;
+}
+export function docPathMatches(candidate, requested) {
+    if (candidate === requested)
+        return true;
+    if (candidate.endsWith(`/${requested}`))
+        return true;
+    if (requested.endsWith(`/${candidate}`))
+        return true;
+    return false;
+}
+export function extractAssetIdFromPath(value) {
+    const normalized = normalizeDocPath(String(value || ''));
+    if (!normalized)
+        return null;
+    const match = normalized.match(/(^|\/)(asset-[a-f0-9]{32})(?=[^/]*$)/i);
+    return match?.[2] ? match[2].toLowerCase() : null;
+}
+export function getEffectiveAttachmentState(doc) {
+    if (doc.attachmentState === 'attached' || doc.attachmentState === 'unattached') {
+        return doc.attachmentState;
+    }
+    const attachmentCount = typeof doc.attachmentCount === 'number' && Number.isFinite(doc.attachmentCount)
+        ? doc.attachmentCount
+        : 0;
+    if (attachmentCount > 0 || !!doc.taskId) {
+        return 'attached';
+    }
+    return 'unattached';
+}
+export function filterDocuments(documents, searchQuery, typeFilters, attachmentFilters) {
+    const normalizedQuery = searchQuery.trim().toLowerCase();
+    return documents.filter((doc) => {
+        const readableName = getReadableDocumentName(doc);
+        const haystack = `${readableName} ${doc.originalFilename || ''}`.toLowerCase();
+        const matchesSearch = normalizedQuery.length === 0 || haystack.includes(normalizedQuery);
+        const matchesType = typeFilters.length === 0 || typeFilters.includes(doc.docType);
+        const attachmentState = getEffectiveAttachmentState(doc);
+        const matchesAttachment = attachmentFilters.length === 0 || attachmentFilters.includes(attachmentState);
+        return matchesSearch && matchesType && matchesAttachment;
+    });
+}

package/dist/components/features/useDocumentWorkspaceController.d.ts

@@ -0,0 +1,34 @@
+import { type DocumentAttachmentFilter, type DocumentTypeFilter } from './documentWorkspaceFilters';
+import { type DocMeta } from './documentWorkspaceModel';
+interface Options {
+    runtimeMode?: 'local' | 'cloud';
+    apiBaseUrl?: string;
+    cloudAuthBaseUrl?: string;
+    typeFilters?: DocumentTypeFilter[];
+    attachmentFilters?: DocumentAttachmentFilter[];
+    onTypeFiltersChange?: (values: DocumentTypeFilter[]) => void;
+    onAttachmentFiltersChange?: (values: DocumentAttachmentFilter[]) => void;
+    requestedDocPath?: string | null;
+    requestedDocAssetId?: string | null;
+    onRequestedDocHandled?: () => void;
+}
+interface Result {
+    documentApiBaseUrl: string;
+    documents: DocMeta[];
+    filteredDocs: DocMeta[];
+    loading: boolean;
+    error: string | null;
+    selectedDoc: DocMeta | null;
+    searchQuery: string;
+    typeFilters: DocumentTypeFilter[];
+    attachmentFilters: DocumentAttachmentFilter[];
+    hasActiveFilters: boolean;
+    setSearchQuery: (value: string) => void;
+    handleTypeFiltersChange: (values: DocumentTypeFilter[]) => void;
+    handleAttachmentFiltersChange: (values: DocumentAttachmentFilter[]) => void;
+    fetchDocuments: () => Promise<void>;
+    selectDoc: (doc: DocMeta | null) => void;
+    handleDeleteSelected: () => Promise<void>;
+}
+export declare function useDocumentWorkspaceController({ runtimeMode, apiBaseUrl, cloudAuthBaseUrl, typeFilters: controlledTypeFilters, attachmentFilters: controlledAttachmentFilters, onTypeFiltersChange, onAttachmentFiltersChange, requestedDocPath, requestedDocAssetId, onRequestedDocHandled, }: Options): Result;
+export {};

package/dist/components/features/useDocumentWorkspaceController.js

@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { fetchTaskforceApi } from '../../utils/taskforceApiClient';
+import { logDocumentManagerDebug, resolveDocumentManagerApiBase } from '../../utils/documentManagerApi';
+import { DOCUMENT_ATTACHMENT_FILTER_OPTIONS, DOCUMENT_TYPE_FILTER_OPTIONS, } from './documentWorkspaceFilters';
+import { docPathMatches, extractAssetIdFromPath, filterDocuments, normalizeDocPath, } from './documentWorkspaceModel';
+export function useDocumentWorkspaceController({ runtimeMode = 'local', apiBaseUrl = '', cloudAuthBaseUrl = '', typeFilters: controlledTypeFilters, attachmentFilters: controlledAttachmentFilters, onTypeFiltersChange, onAttachmentFiltersChange, requestedDocPath = null, requestedDocAssetId = null, onRequestedDocHandled, }) {
+    const [documents, setDocuments] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [selectedDocId, setSelectedDocId] = useState(null);
+    const [searchQuery, setSearchQuery] = useState('');
+    const [internalTypeFilters, setInternalTypeFilters] = useState(() => DOCUMENT_TYPE_FILTER_OPTIONS.map((option) => option.value));
+    const [internalAttachmentFilters, setInternalAttachmentFilters] = useState(() => DOCUMENT_ATTACHMENT_FILTER_OPTIONS.map((option) => option.value));
+    const documentApiBaseUrl = resolveDocumentManagerApiBase({
+        runtimeMode,
+        apiBaseUrl,
+        cloudAuthBaseUrl,
+    });
+    const typeFilters = controlledTypeFilters ?? internalTypeFilters;
+    const attachmentFilters = controlledAttachmentFilters ?? internalAttachmentFilters;
+    const handleTypeFiltersChange = onTypeFiltersChange ?? setInternalTypeFilters;
+    const handleAttachmentFiltersChange = onAttachmentFiltersChange ?? setInternalAttachmentFilters;
+    const fetchDocuments = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const res = await fetchTaskforceApi('/api/taskforce/documents', {
+                credentials: 'include',
+            }, documentApiBaseUrl);
+            if (!res.ok)
+                throw new Error(`Failed to load documents (${res.status})`);
+            const data = await res.json();
+            const nextDocuments = Array.isArray(data.documents) ? data.documents : [];
+            logDocumentManagerDebug('list.loaded', {
+                runtimeMode,
+                apiBaseUrl: documentApiBaseUrl || '(same-origin)',
+                count: nextDocuments.length,
+            });
+            setDocuments(nextDocuments);
+        }
+        catch (e) {
+            setError(e?.message || 'Failed to load documents');
+            logDocumentManagerDebug('list.error', {
+                runtimeMode,
+                apiBaseUrl: documentApiBaseUrl || '(same-origin)',
+                message: e?.message || 'Failed to load documents',
+            });
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [documentApiBaseUrl, runtimeMode]);
+    useEffect(() => {
+        void fetchDocuments();
+    }, [fetchDocuments]);
+    const filteredDocs = useMemo(() => filterDocuments(documents, searchQuery, typeFilters, attachmentFilters), [attachmentFilters, documents, searchQuery, typeFilters]);
+    const selectedDoc = useMemo(() => (selectedDocId ? documents.find((doc) => doc.id === selectedDocId) ?? null : null), [documents, selectedDocId]);
+    useEffect(() => {
+        if ((!requestedDocPath && !requestedDocAssetId) || documents.length === 0)
+            return;
+        const requested = requestedDocPath ? normalizeDocPath(requestedDocPath) : '';
+        const normalizedRequestedAssetId = String(requestedDocAssetId || '').trim().toLowerCase()
+            || extractAssetIdFromPath(requestedDocPath);
+        const matched = documents.find((doc) => {
+            const candidateAssetId = extractAssetIdFromPath(doc.fsPath) || String(doc.assetId || '').trim().toLowerCase() || null;
+            if (normalizedRequestedAssetId && candidateAssetId && candidateAssetId === normalizedRequestedAssetId)
+                return true;
+            if (!requested)
+                return false;
+            return docPathMatches(normalizeDocPath(doc.fsPath), requested);
+        });
+        if (!matched)
+            return;
+        setSelectedDocId(matched.id);
+        onRequestedDocHandled?.();
+    }, [documents, onRequestedDocHandled, requestedDocAssetId, requestedDocPath]);
+    useEffect(() => {
+        if ((requestedDocPath || requestedDocAssetId) && !selectedDoc)
+            return;
+        if (filteredDocs.length === 0) {
+            if (selectedDocId !== null) {
+                setSelectedDocId(null);
+            }
+            return;
+        }
+        if (selectedDoc && filteredDocs.some((doc) => doc.id === selectedDoc.id))
+            return;
+        setSelectedDocId(filteredDocs[0].id);
+    }, [filteredDocs, requestedDocAssetId, requestedDocPath, selectedDoc, selectedDocId]);
+    const handleDeleteSelected = useCallback(async () => {
+        setSelectedDocId(null);
+        await fetchDocuments();
+    }, [fetchDocuments]);
+    const hasActiveFilters = searchQuery.trim().length > 0 || typeFilters.length > 0 || attachmentFilters.length > 0;
+    return {
+        documentApiBaseUrl,
+        documents,
+        filteredDocs,
+        loading,
+        error,
+        selectedDoc,
+        searchQuery,
+        typeFilters,
+        attachmentFilters,
+        hasActiveFilters,
+        setSearchQuery,
+        handleTypeFiltersChange,
+        handleAttachmentFiltersChange,
+        fetchDocuments,
+        selectDoc: (doc) => setSelectedDocId(doc?.id ?? null),
+        handleDeleteSelected,
+    };
+}