@claudetools/tools 0.3.8 → 0.4.0

package/dist/helpers/api-client.d.ts

@@ -48,3 +48,40 @@ export declare function injectContext(projectId: string, query: string, userId?:
         reason?: string;
     };
 }>;
+export interface CachedDoc {
+    library: string;
+    context7Id: string | null;
+    version: string | null;
+    fetchedAt: string;
+    size: number;
+    mode: 'code' | 'info';
+    content: string;
+    library_name?: string;
+}
+export interface DocsCacheListResponse {
+    libraries: {
+        library_id: string;
+        library_name: string;
+        topics?: string[];
+        cached_at: string;
+    }[];
+}
+/**
+ * List all cached documentation libraries (global cache)
+ */
+export declare function listCachedDocs(_projectId?: string): Promise<DocsCacheListResponse>;
+/**
+ * Get cached documentation for a specific library
+ */
+export declare function getCachedDocs(_projectId: string, // Unused - docs cache is global
+libraryId: string, topic?: string): Promise<CachedDoc | null>;
+/**
+ * Ensure documentation is cached (fetches from Context7 if needed)
+ */
+export declare function cacheDocs(_projectId: string, // Unused - docs cache is global
+libraryId: string, libraryName: string, _content?: string, // Unused - backend fetches from Context7
+topic?: string): Promise<{
+    success: boolean;
+    status?: string;
+    size?: number;
+}>;

package/dist/helpers/api-client.js

@@ -57,3 +57,66 @@ export async function injectContext(projectId, query, userId = DEFAULT_USER_ID)
     });
     return response.data;
 }
+/**
+ * List all cached documentation libraries (global cache)
+ */
+export async function listCachedDocs(_projectId // Unused - docs cache is global
+) {
+    try {
+        const response = await apiRequest('/api/v1/docs');
+        // Transform to expected format
+        return {
+            libraries: response.data.libraries.map(lib => ({
+                library_id: lib.library,
+                library_name: lib.library,
+                cached_at: new Date().toISOString(), // Not provided by list endpoint
+            })),
+        };
+    }
+    catch {
+        return { libraries: [] };
+    }
+}
+/**
+ * Get cached documentation for a specific library
+ */
+export async function getCachedDocs(_projectId, // Unused - docs cache is global
+libraryId, topic) {
+    try {
+        const modeParam = topic ? `?mode=info` : '';
+        const response = await apiRequest(`/api/v1/docs/${encodeURIComponent(libraryId)}${modeParam}`);
+        if (!response.success || !response.data) {
+            return null;
+        }
+        // Add compatibility alias
+        return {
+            ...response.data,
+            library_name: response.data.library,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure documentation is cached (fetches from Context7 if needed)
+ */
+export async function cacheDocs(_projectId, // Unused - docs cache is global
+libraryId, libraryName, _content, // Unused - backend fetches from Context7
+topic) {
+    try {
+        const response = await apiRequest('/api/v1/docs/ensure', 'POST', {
+            library: libraryName || libraryId,
+            mode: topic ? 'info' : 'code',
+            topic,
+        });
+        return {
+            success: response.success,
+            status: response.data?.status,
+            size: response.data?.size,
+        };
+    }
+    catch {
+        return { success: false };
+    }
+}

package/dist/helpers/config-manager.js

@@ -21,7 +21,7 @@ export const DEFAULT_CONFIG = {
     defaultProjectId: undefined,
     defaultUserId: 'default',
     // Context Injection
-    autoInjectContext: false, // Disabled by default for backward compatibility
+    autoInjectContext: true, // Enabled by default - this is the core value prop
     contextRelevanceThreshold: 0.5,
     maxContextFacts: 10,
     // Logging & Verbosity

package/dist/helpers/library-detection.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Context7-compatible library ID mappings
+ * Maps canonical names to context7 library IDs
+ */
+export declare const CONTEXT7_LIBRARY_IDS: Record<string, string>;
+export interface DetectedLibrary {
+    name: string;
+    context7Id?: string;
+    mentions: number;
+}
+/**
+ * Detect libraries mentioned in text
+ * @param text - Text to scan for library mentions
+ * @returns Array of detected libraries with mention counts
+ */
+export declare function detectLibraries(text: string): DetectedLibrary[];
+/**
+ * Detect libraries from goal and task descriptions
+ * @param goal - The epic/plan goal
+ * @param tasks - Array of task objects with title and description
+ * @returns Deduplicated list of detected libraries
+ */
+export declare function detectLibrariesFromPlan(goal: string, tasks: {
+    title: string;
+    description?: string;
+}[]): DetectedLibrary[];

package/dist/helpers/library-detection.js

@@ -0,0 +1,145 @@
+// =============================================================================
+// Library/Framework Detection for Task Planning
+// =============================================================================
+/**
+ * Common libraries and frameworks to detect in task descriptions
+ * Maps lowercase keywords to canonical library names
+ */
+const LIBRARY_KEYWORDS = {
+    // Frontend frameworks
+    'react': 'React',
+    'reactjs': 'React',
+    'react.js': 'React',
+    'next': 'Next.js',
+    'nextjs': 'Next.js',
+    'next.js': 'Next.js',
+    'vue': 'Vue.js',
+    'vuejs': 'Vue.js',
+    'vue.js': 'Vue.js',
+    'angular': 'Angular',
+    'svelte': 'Svelte',
+    'sveltekit': 'SvelteKit',
+    // Backend frameworks
+    'express': 'Express',
+    'expressjs': 'Express',
+    'fastify': 'Fastify',
+    'hono': 'Hono',
+    'koa': 'Koa',
+    'nest': 'NestJS',
+    'nestjs': 'NestJS',
+    // Databases & ORMs
+    'supabase': 'Supabase',
+    'firebase': 'Firebase',
+    'prisma': 'Prisma',
+    'drizzle': 'Drizzle',
+    'mongoose': 'Mongoose',
+    'mongodb': 'MongoDB',
+    'postgres': 'PostgreSQL',
+    'postgresql': 'PostgreSQL',
+    'mysql': 'MySQL',
+    'redis': 'Redis',
+    // State management
+    'redux': 'Redux',
+    'zustand': 'Zustand',
+    'jotai': 'Jotai',
+    'recoil': 'Recoil',
+    'tanstack': 'TanStack Query',
+    'react-query': 'TanStack Query',
+    'swr': 'SWR',
+    // UI libraries
+    'tailwind': 'Tailwind CSS',
+    'tailwindcss': 'Tailwind CSS',
+    'shadcn': 'shadcn/ui',
+    'radix': 'Radix UI',
+    'chakra': 'Chakra UI',
+    'mantine': 'Mantine',
+    'mui': 'Material UI',
+    'material-ui': 'Material UI',
+    // Testing
+    'jest': 'Jest',
+    'vitest': 'Vitest',
+    'playwright': 'Playwright',
+    'cypress': 'Cypress',
+    'testing-library': 'Testing Library',
+    // Build tools
+    'vite': 'Vite',
+    'webpack': 'Webpack',
+    'esbuild': 'esbuild',
+    'turbopack': 'Turbopack',
+    'turborepo': 'Turborepo',
+    // Auth & APIs
+    'auth': 'Authentication',
+    'oauth': 'OAuth',
+    'jwt': 'JWT',
+    'stripe': 'Stripe',
+    'openai': 'OpenAI',
+    'langchain': 'LangChain',
+    'vercel': 'Vercel',
+    // Other
+    'typescript': 'TypeScript',
+    'graphql': 'GraphQL',
+    'trpc': 'tRPC',
+    'zod': 'Zod',
+    'socket.io': 'Socket.IO',
+    'websocket': 'WebSocket',
+};
+/**
+ * Context7-compatible library ID mappings
+ * Maps canonical names to context7 library IDs
+ */
+export const CONTEXT7_LIBRARY_IDS = {
+    'React': '/facebook/react',
+    'Next.js': '/vercel/next.js',
+    'Vue.js': '/vuejs/vue',
+    'Supabase': '/supabase/supabase',
+    'Prisma': '/prisma/prisma',
+    'Tailwind CSS': '/tailwindlabs/tailwindcss',
+    'TypeScript': '/microsoft/typescript',
+    'Vitest': '/vitest-dev/vitest',
+    'Zod': '/colinhacks/zod',
+    'tRPC': '/trpc/trpc',
+    'TanStack Query': '/tanstack/query',
+};
+/**
+ * Detect libraries mentioned in text
+ * @param text - Text to scan for library mentions
+ * @returns Array of detected libraries with mention counts
+ */
+export function detectLibraries(text) {
+    const lowerText = text.toLowerCase();
+    const detected = new Map();
+    // Scan for each keyword
+    for (const [keyword, libraryName] of Object.entries(LIBRARY_KEYWORDS)) {
+        // Use word boundary matching to avoid partial matches
+        const regex = new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi');
+        const matches = lowerText.match(regex);
+        if (matches) {
+            const current = detected.get(libraryName) || 0;
+            detected.set(libraryName, current + matches.length);
+        }
+    }
+    // Convert to array and sort by mention count
+    const results = [];
+    for (const [name, mentions] of detected) {
+        results.push({
+            name,
+            context7Id: CONTEXT7_LIBRARY_IDS[name],
+            mentions,
+        });
+    }
+    return results.sort((a, b) => b.mentions - a.mentions);
+}
+/**
+ * Detect libraries from goal and task descriptions
+ * @param goal - The epic/plan goal
+ * @param tasks - Array of task objects with title and description
+ * @returns Deduplicated list of detected libraries
+ */
+export function detectLibrariesFromPlan(goal, tasks) {
+    // Combine all text
+    const allText = [
+        goal,
+        ...tasks.map(t => `${t.title} ${t.description || ''}`),
+    ].join(' ');
+    return detectLibraries(allText);
+}

package/dist/helpers/tasks-retry.d.ts

@@ -0,0 +1,49 @@
+import { type Task } from './tasks.js';
+export interface TimedOutTask {
+    task: Task;
+    lockExpiredAt: string;
+    timeSinceExpiry: number;
+}
+export interface RetryMetadata {
+    retryCount: number;
+    lastFailedAt: string;
+    lastError?: string;
+    failureHistory: Array<{
+        timestamp: string;
+        error?: string;
+    }>;
+}
+/**
+ * Detect tasks that have timed out (lock expired while in_progress)
+ * These are likely abandoned or failed tasks
+ */
+export declare function detectTimedOutTasks(userId: string, projectId: string): Promise<TimedOutTask[]>;
+/**
+ * Retry a failed or timed-out task
+ * Returns success: false if retry limit exceeded
+ */
+export declare function retryTask(userId: string, projectId: string, taskId: string, maxRetries?: number, errorContext?: string): Promise<{
+    success: boolean;
+    data?: {
+        task: Task;
+        retryCount: number;
+        retriesRemaining: number;
+    };
+    error?: string;
+}>;
+/**
+ * Mark a task as failed with context
+ */
+export declare function failTask(userId: string, projectId: string, taskId: string, errorContext: string, agentId?: string): Promise<{
+    success: boolean;
+    data: Task;
+}>;
+/**
+ * Auto-detect and handle timed-out tasks
+ * Returns tasks that were auto-retried
+ */
+export declare function autoRetryTimedOutTasks(userId: string, projectId: string, maxRetries?: number): Promise<{
+    timedOut: TimedOutTask[];
+    retried: Task[];
+    failed: Task[];
+}>;

package/dist/helpers/tasks-retry.js

@@ -0,0 +1,168 @@
+// =============================================================================
+// Task Failure Handling & Retry System
+// =============================================================================
+import { apiRequest } from './api-client.js';
+import { getTask, listTasks, updateTaskStatus, addTaskContext } from './tasks.js';
+/**
+ * Get retry metadata from task metadata
+ */
+function getRetryMetadata(task) {
+    const metadata = task.metadata || {};
+    return {
+        retryCount: metadata.retryCount || 0,
+        lastFailedAt: metadata.lastFailedAt || '',
+        lastError: metadata.lastError,
+        failureHistory: metadata.failureHistory || [],
+    };
+}
+/**
+ * Update retry metadata
+ */
+function updateRetryMetadata(metadata, error) {
+    const current = metadata;
+    const retryCount = (current.retryCount || 0) + 1;
+    const timestamp = new Date().toISOString();
+    const failureHistory = (current.failureHistory || []);
+    return {
+        ...metadata,
+        retryCount,
+        lastFailedAt: timestamp,
+        lastError: error,
+        failureHistory: [
+            ...failureHistory,
+            { timestamp, error },
+        ],
+    };
+}
+/**
+ * Detect tasks that have timed out (lock expired while in_progress)
+ * These are likely abandoned or failed tasks
+ */
+export async function detectTimedOutTasks(userId, projectId) {
+    // Get all in_progress tasks
+    const result = await listTasks(userId, projectId, {
+        status: 'in_progress',
+        limit: 100,
+    });
+    if (!result.success || !result.data.length) {
+        return [];
+    }
+    const now = new Date();
+    const timedOut = [];
+    for (const task of result.data) {
+        // Check if lock has expired
+        if (task.lock_expires_at) {
+            const lockExpires = new Date(task.lock_expires_at);
+            if (lockExpires < now) {
+                timedOut.push({
+                    task,
+                    lockExpiredAt: task.lock_expires_at,
+                    timeSinceExpiry: now.getTime() - lockExpires.getTime(),
+                });
+            }
+        }
+    }
+    return timedOut;
+}
+/**
+ * Retry a failed or timed-out task
+ * Returns success: false if retry limit exceeded
+ */
+export async function retryTask(userId, projectId, taskId, maxRetries = 3, errorContext) {
+    // Get current task
+    const taskResult = await getTask(userId, projectId, taskId);
+    if (!taskResult.success) {
+        return {
+            success: false,
+            error: 'Task not found',
+        };
+    }
+    const task = taskResult.data;
+    const retryMetadata = getRetryMetadata(task);
+    // Check retry limit
+    if (retryMetadata.retryCount >= maxRetries) {
+        // Mark as failed permanently
+        await updateTaskStatus(userId, projectId, taskId, 'failed');
+        // Add failure context
+        await addTaskContext(userId, projectId, taskId, 'work_log', `Task failed permanently after ${retryMetadata.retryCount} retries. Last error: ${errorContext || 'Unknown'}`, 'system');
+        return {
+            success: false,
+            error: `Retry limit exceeded (${maxRetries} retries)`,
+        };
+    }
+    // Update metadata with failure info
+    const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
+    // Update task with retry metadata and reset status
+    // Using the /api/v1/tasks/:userId/:projectId/:taskId endpoint with POST
+    await apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}`, 'POST', {
+        status: 'ready',
+        assigned_to: null,
+        locked_at: null,
+        lock_expires_at: null,
+        metadata: updatedMetadata,
+    });
+    // Add retry context
+    const newRetryCount = retryMetadata.retryCount + 1;
+    await addTaskContext(userId, projectId, taskId, 'work_log', `Task retry ${newRetryCount}/${maxRetries}. Previous failure: ${errorContext || 'Lock timeout'}`, 'system');
+    // Get updated task
+    const updatedResult = await getTask(userId, projectId, taskId);
+    const updatedTask = updatedResult.data;
+    return {
+        success: true,
+        data: {
+            task: updatedTask,
+            retryCount: newRetryCount,
+            retriesRemaining: maxRetries - newRetryCount,
+        },
+    };
+}
+/**
+ * Mark a task as failed with context
+ */
+export async function failTask(userId, projectId, taskId, errorContext, agentId) {
+    // Get current task to update metadata
+    const taskResult = await getTask(userId, projectId, taskId);
+    if (!taskResult.success) {
+        throw new Error('Task not found');
+    }
+    const task = taskResult.data;
+    const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
+    // Update to failed status with metadata
+    await apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}`, 'POST', {
+        status: 'failed',
+        metadata: updatedMetadata,
+        assigned_to: null,
+        locked_at: null,
+        lock_expires_at: null,
+    });
+    // Add failure context
+    await addTaskContext(userId, projectId, taskId, 'work_log', `Task failed: ${errorContext}`, agentId || 'system');
+    // Get updated task
+    const result = await getTask(userId, projectId, taskId);
+    return result;
+}
+/**
+ * Auto-detect and handle timed-out tasks
+ * Returns tasks that were auto-retried
+ */
+export async function autoRetryTimedOutTasks(userId, projectId, maxRetries = 3) {
+    const timedOut = await detectTimedOutTasks(userId, projectId);
+    const retried = [];
+    const failed = [];
+    for (const { task, timeSinceExpiry } of timedOut) {
+        const minutesSinceExpiry = Math.floor(timeSinceExpiry / 1000 / 60);
+        const errorContext = `Lock timeout: expired ${minutesSinceExpiry} minutes ago`;
+        const retryResult = await retryTask(userId, projectId, task.id, maxRetries, errorContext);
+        if (retryResult.success && retryResult.data) {
+            retried.push(retryResult.data.task);
+        }
+        else {
+            // Task failed permanently
+            const failResult = await getTask(userId, projectId, task.id);
+            if (failResult.success) {
+                failed.push(failResult.data);
+            }
+        }
+    }
+    return { timedOut, retried, failed };
+}

package/dist/helpers/tasks.d.ts

@@ -127,12 +127,23 @@ export declare function heartbeatTask(userId: string, projectId: string, taskId:
         new_expires_at: string;
     };
 }>;
+export declare const DEFAULT_MAX_PARALLEL = 5;
+/**
+ * Get count of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts
+ */
+export declare function getActiveTaskCount(userId: string, projectId: string, epicId?: string): Promise<{
+    inProgress: number;
+    claimed: number;
+    total: number;
+}>;
 /**
  * Get all tasks ready for parallel dispatch
  * - Filters for 'ready' status
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
+ * - Respects max parallel limit by considering currently active tasks
  */
 export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
 /**
@@ -147,6 +158,18 @@ export declare function getExecutionContext(userId: string, projectId: string, t
     siblingTasks?: Task[];
 }>;
 /**
- * Find newly unblocked tasks after a completion
+ * Find newly unblocked tasks after a completion and update their status to ready
  */
 export declare function resolveTaskDependencies(userId: string, projectId: string, completedTaskId: string, epicId?: string): Promise<Task[]>;
+/**
+ * Get epic status with progress tracking
+ * Auto-completes epic if all child tasks are done
+ */
+export declare function getEpicStatus(userId: string, projectId: string, epicId: string): Promise<{
+    epic: Task;
+    totalTasks: number;
+    byStatus: Record<string, number>;
+    percentComplete: number;
+    allComplete: boolean;
+    autoCompleted: boolean;
+}>;