tlc-claude-code 1.4.4 → 1.4.6

package/dashboard/dist/api/safeFetch.js

@@ -0,0 +1,135 @@
+/**
+ * Self-healing error boundary utilities for fetch operations.
+ * Provides consistent error handling, timeout support, and typed responses.
+ */
+/**
+ * Maps error conditions to user-friendly error info
+ */
+function categorizeError(error, url) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return {
+            type: 'timeout',
+            message: 'Request timed out',
+        };
+    }
+    if (error instanceof TypeError) {
+        // Network errors like failed to fetch
+        return {
+            type: 'network',
+            message: 'Cannot reach the server',
+            original: error,
+        };
+    }
+    if (error instanceof SyntaxError) {
+        return {
+            type: 'parse',
+            message: 'Invalid response from server',
+            original: error,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            type: 'unknown',
+            message: error.message,
+            original: error,
+        };
+    }
+    return {
+        type: 'unknown',
+        message: String(error),
+    };
+}
+/**
+ * Safe fetch wrapper that never throws.
+ * Always returns a FetchResult with either data or error.
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options plus optional timeout (default 10s)
+ * @returns Promise<FetchResult<T>> - Always resolves, never rejects
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await safeFetch<RouterData>('/api/router');
+ * if (error) {
+ *   // Handle error - render error state
+ *   return <ErrorState error={error} onRetry={() => refresh()} />;
+ * }
+ * // Use data safely
+ * ```
+ */
+export async function safeFetch(url, options = {}) {
+    const { timeout = 10000, ...fetchOptions } = options;
+    try {
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        const response = await fetch(url, {
+            ...fetchOptions,
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return {
+                data: null,
+                error: {
+                    type: 'http',
+                    code: response.status,
+                    message: `HTTP ${response.status}: ${response.statusText}`,
+                },
+                status: 'error',
+            };
+        }
+        const data = await response.json();
+        return {
+            data: data,
+            error: null,
+            status: 'success',
+        };
+    }
+    catch (err) {
+        console.error(`Fetch error for ${url}:`, err);
+        return {
+            data: null,
+            error: categorizeError(err, url),
+            status: 'error',
+        };
+    }
+}
+/**
+ * POST helper with JSON body
+ */
+export async function safePost(url, body, options = {}) {
+    return safeFetch(url, {
+        ...options,
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        },
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * PUT helper with JSON body
+ */
+export async function safePut(url, body, options = {}) {
+    return safeFetch(url, {
+        ...options,
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        },
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * DELETE helper
+ */
+export async function safeDelete(url, options = {}) {
+    return safeFetch(url, {
+        ...options,
+        method: 'DELETE',
+    });
+}
+export default safeFetch;

package/dashboard/dist/api/safeFetch.test.d.ts

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

package/dashboard/dist/api/safeFetch.test.js

@@ -0,0 +1,215 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { safeFetch, safePost, safePut, safeDelete } from './safeFetch.js';
+describe('safeFetch', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    describe('successful requests', () => {
+        it('returns data on successful response', async () => {
+            const mockData = { message: 'success' };
+            vi.mocked(fetch).mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(mockData),
+            });
+            const result = await safeFetch('/api/test');
+            expect(result.status).toBe('success');
+            expect(result.data).toEqual(mockData);
+            expect(result.error).toBeNull();
+        });
+        it('passes through fetch options', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({}),
+            });
+            await safeFetch('/api/test', {
+                method: 'POST',
+                headers: { 'X-Custom': 'value' },
+            });
+            expect(fetch).toHaveBeenCalledWith('/api/test', expect.objectContaining({
+                method: 'POST',
+                headers: { 'X-Custom': 'value' },
+            }));
+        });
+    });
+    describe('HTTP errors', () => {
+        it('handles 404 errors', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: false,
+                status: 404,
+                statusText: 'Not Found',
+            });
+            const result = await safeFetch('/api/missing');
+            expect(result.status).toBe('error');
+            expect(result.data).toBeNull();
+            expect(result.error).toEqual({
+                type: 'http',
+                code: 404,
+                message: 'HTTP 404: Not Found',
+            });
+        });
+        it('handles 500 errors', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: false,
+                status: 500,
+                statusText: 'Internal Server Error',
+            });
+            const result = await safeFetch('/api/broken');
+            expect(result.status).toBe('error');
+            expect(result.error?.type).toBe('http');
+            expect(result.error?.code).toBe(500);
+        });
+        it('handles 401 unauthorized', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: false,
+                status: 401,
+                statusText: 'Unauthorized',
+            });
+            const result = await safeFetch('/api/protected');
+            expect(result.error?.type).toBe('http');
+            expect(result.error?.code).toBe(401);
+        });
+    });
+    describe('network errors', () => {
+        it('handles network failures', async () => {
+            vi.mocked(fetch).mockRejectedValue(new TypeError('Failed to fetch'));
+            const result = await safeFetch('/api/unreachable');
+            expect(result.status).toBe('error');
+            expect(result.error?.type).toBe('network');
+            expect(result.error?.message).toBe('Cannot reach the server');
+        });
+    });
+    describe('timeout handling', () => {
+        it('times out after specified duration', async () => {
+            // Use AbortError to simulate timeout
+            vi.mocked(fetch).mockImplementation(() => {
+                const error = new DOMException('Aborted', 'AbortError');
+                return Promise.reject(error);
+            });
+            const result = await safeFetch('/api/slow', { timeout: 100 });
+            expect(result.status).toBe('error');
+            expect(result.error?.type).toBe('timeout');
+            expect(result.error?.message).toBe('Request timed out');
+        });
+        it('uses 10s default timeout', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({}),
+            });
+            await safeFetch('/api/test');
+            // Signal should be passed
+            expect(fetch).toHaveBeenCalledWith('/api/test', expect.objectContaining({
+                signal: expect.any(AbortSignal),
+            }));
+        });
+    });
+    describe('parse errors', () => {
+        it('handles invalid JSON response', async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                ok: true,
+                json: () => Promise.reject(new SyntaxError('Unexpected token')),
+            });
+            const result = await safeFetch('/api/bad-json');
+            expect(result.status).toBe('error');
+            expect(result.error?.type).toBe('parse');
+            expect(result.error?.message).toBe('Invalid response from server');
+        });
+    });
+    describe('never throws', () => {
+        it('always returns FetchResult, never throws', async () => {
+            // Various error types
+            const errorCases = [
+                new Error('Generic error'),
+                new TypeError('Type error'),
+                'String error',
+                undefined,
+                null,
+            ];
+            for (const error of errorCases) {
+                vi.mocked(fetch).mockRejectedValue(error);
+                // Should not throw
+                const result = await safeFetch('/api/test');
+                expect(result).toBeDefined();
+                expect(result.status).toBe('error');
+                expect(result.data).toBeNull();
+                expect(result.error).not.toBeNull();
+            }
+        });
+    });
+});
+describe('safePost', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it('sends POST request with JSON body', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ id: 1 }),
+        });
+        const body = { name: 'test' };
+        await safePost('/api/items', body);
+        expect(fetch).toHaveBeenCalledWith('/api/items', expect.objectContaining({
+            method: 'POST',
+            headers: expect.objectContaining({
+                'Content-Type': 'application/json',
+            }),
+            body: JSON.stringify(body),
+        }));
+    });
+    it('merges custom headers', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({}),
+        });
+        await safePost('/api/items', {}, { headers: { Authorization: 'Bearer token' } });
+        expect(fetch).toHaveBeenCalledWith('/api/items', expect.objectContaining({
+            headers: expect.objectContaining({
+                'Content-Type': 'application/json',
+                Authorization: 'Bearer token',
+            }),
+        }));
+    });
+});
+describe('safePut', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it('sends PUT request with JSON body', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ updated: true }),
+        });
+        const body = { name: 'updated' };
+        await safePut('/api/items/1', body);
+        expect(fetch).toHaveBeenCalledWith('/api/items/1', expect.objectContaining({
+            method: 'PUT',
+            body: JSON.stringify(body),
+        }));
+    });
+});
+describe('safeDelete', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it('sends DELETE request', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ deleted: true }),
+        });
+        await safeDelete('/api/items/1');
+        expect(fetch).toHaveBeenCalledWith('/api/items/1', expect.objectContaining({
+            method: 'DELETE',
+        }));
+    });
+});

package/dashboard/dist/api/tasks-api.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tasks API - Returns tasks from PLAN.md files in flat array format
+ */
+import type { Dirent } from 'fs';
+export interface Task {
+    id: string;
+    title: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    owner: string | null;
+    phase: number;
+}
+export interface FileSystem {
+    existsSync: (path: string) => boolean;
+    readdir: (path: string, options: {
+        withFileTypes: true;
+    }) => Promise<Dirent[]>;
+    readFile: (path: string, encoding: BufferEncoding) => Promise<string>;
+}
+/**
+ * Get all tasks from all PLAN.md files in the planning directory
+ * @param projectPath - Root path of the project
+ * @param fs - File system implementation (for testing)
+ * @returns Array of tasks in flat format, sorted by phase then task number
+ */
+export declare function getTasks(projectPath: string, fs?: FileSystem): Promise<Task[]>;
+/**
+ * Parse tasks from PLAN.md content
+ * @param content - Content of the PLAN.md file
+ * @param phaseNum - Phase number for task ID generation
+ * @returns Array of tasks parsed from the content
+ */
+export declare function parseTasksFromPlan(content: string, phaseNum: number): Task[];

package/dashboard/dist/api/tasks-api.js

@@ -0,0 +1,98 @@
+/**
+ * Tasks API - Returns tasks from PLAN.md files in flat array format
+ */
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+// Default file system implementation
+const defaultFs = {
+    existsSync,
+    readdir: (path, options) => readdir(path, options),
+    readFile: (path, encoding) => readFile(path, encoding),
+};
+/**
+ * Get all tasks from all PLAN.md files in the planning directory
+ * @param projectPath - Root path of the project
+ * @param fs - File system implementation (for testing)
+ * @returns Array of tasks in flat format, sorted by phase then task number
+ */
+export async function getTasks(projectPath, fs = defaultFs) {
+    const phasesDir = join(projectPath, '.planning', 'phases');
+    if (!fs.existsSync(phasesDir)) {
+        return [];
+    }
+    const tasks = [];
+    try {
+        const entries = await fs.readdir(phasesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                // Extract phase number from directory name (e.g., "39-fix-api" -> 39)
+                const dirMatch = entry.name.match(/^(\d+)/);
+                if (dirMatch) {
+                    const phaseNum = parseInt(dirMatch[1], 10);
+                    const planPath = join(phasesDir, entry.name, `${dirMatch[1]}-PLAN.md`);
+                    if (fs.existsSync(planPath)) {
+                        try {
+                            const content = await fs.readFile(planPath, 'utf-8');
+                            const phaseTasks = parseTasksFromPlan(content, phaseNum);
+                            tasks.push(...phaseTasks);
+                        }
+                        catch {
+                            // Skip unreadable files
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Return empty if can't read directory
+        return [];
+    }
+    // Sort by phase number, then by task number
+    tasks.sort((a, b) => {
+        if (a.phase !== b.phase) {
+            return a.phase - b.phase;
+        }
+        // Extract task number from id (e.g., "39-1" -> 1)
+        const aTaskNum = parseInt(a.id.split('-')[1], 10);
+        const bTaskNum = parseInt(b.id.split('-')[1], 10);
+        return aTaskNum - bTaskNum;
+    });
+    return tasks;
+}
+/**
+ * Parse tasks from PLAN.md content
+ * @param content - Content of the PLAN.md file
+ * @param phaseNum - Phase number for task ID generation
+ * @returns Array of tasks parsed from the content
+ */
+export function parseTasksFromPlan(content, phaseNum) {
+    const tasks = [];
+    const lines = content.split('\n');
+    for (const line of lines) {
+        // Match task headers like:
+        // "### Task 1: Setup Project [x@alice]"
+        // "### Task 1: Setup Project [>]"
+        // "### Task 1: Setup Project [ ]"
+        // "### Task 1: Name [x]"
+        // Requires colon after task number
+        const taskMatch = line.match(/^###\s*Task\s+(\d+):\s*(.+?)\s*\[([x> ]?)(?:@(\w+))?\]\s*$/i);
+        if (taskMatch) {
+            const taskNum = parseInt(taskMatch[1], 10);
+            const title = taskMatch[2].trim();
+            const statusChar = taskMatch[3].trim();
+            const owner = taskMatch[4] || null;
+            const status = statusChar === 'x' ? 'completed' :
+                statusChar === '>' ? 'in_progress' : 'pending';
+            tasks.push({
+                id: `${phaseNum}-${taskNum}`,
+                title,
+                status,
+                owner,
+                phase: phaseNum,
+            });
+        }
+    }
+    return tasks;
+}

package/dashboard/dist/api/tasks-api.test.d.ts

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