@claudetools/tools 0.8.4 → 0.8.6

package/dist/testing/test-runner.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Result of a single test execution
+ */
+export interface TestResult {
+    /** Test name/description */
+    name: string;
+    /** Whether the test passed */
+    passed: boolean;
+    /** Duration in milliseconds */
+    duration_ms: number;
+    /** Error details if test failed */
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Summary of test suite execution
+ */
+export interface TestSuiteSummary {
+    /** Total number of tests */
+    total: number;
+    /** Number of passed tests */
+    passed: number;
+    /** Number of failed tests */
+    failed: number;
+    /** Total duration in milliseconds */
+    total_duration_ms: number;
+    /** Average duration per test in milliseconds */
+    avg_duration_ms: number;
+    /** Pass rate as percentage (0-100) */
+    pass_rate: number;
+}
+/**
+ * Complete test suite results
+ */
+export interface TestSuite {
+    /** Suite name */
+    name: string;
+    /** Individual test results */
+    tests: TestResult[];
+    /** Aggregated summary */
+    summary: TestSuiteSummary;
+    /** Timestamp when suite started */
+    started_at: string;
+    /** Timestamp when suite completed */
+    completed_at: string;
+}
+/**
+ * Test function signature
+ */
+export type TestFunction = () => Promise<void> | void;
+/**
+ * Test definition
+ */
+export interface TestDefinition {
+    name: string;
+    fn: TestFunction;
+}
+/**
+ * Run a single test with timing and error handling
+ *
+ * @param name - Test name/description
+ * @param fn - Test function to execute
+ * @returns Test result with pass/fail, duration, and error details
+ *
+ * @example
+ * ```typescript
+ * const result = await runTest('should store and retrieve fact', async () => {
+ *   const fact = await storeFact('test', 'RELATES_TO', 'value');
+ *   assert(fact !== null);
+ * });
+ *
+ * if (!result.passed) {
+ *   console.error(`Test failed: ${result.error?.message}`);
+ * }
+ * ```
+ */
+export declare function runTest(name: string, fn: TestFunction): Promise<TestResult>;
+/**
+ * Run a suite of tests
+ *
+ * @param name - Suite name
+ * @param tests - Array of test definitions
+ * @returns Complete test suite results with summary
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('Memory Integration Tests', [
+ *   { name: 'should store fact', fn: async () => { ... } },
+ *   { name: 'should search facts', fn: async () => { ... } },
+ *   { name: 'should inject context', fn: async () => { ... } },
+ * ]);
+ *
+ * console.log(formatResults(suite));
+ *
+ * if (suite.summary.failed > 0) {
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function runSuite(name: string, tests: TestDefinition[]): Promise<TestSuite>;
+/**
+ * Format test suite results as human-readable text
+ *
+ * @param suite - Test suite results
+ * @returns Formatted string with test results and summary
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('My Tests', [...]);
+ * console.log(formatResults(suite));
+ * ```
+ *
+ * Output:
+ * ```
+ * ================================================================================
+ * Test Suite: My Tests
+ * ================================================================================
+ *
+ * ✓ should pass test 1 (45.32ms)
+ * ✗ should fail test 2 (12.18ms)
+ *   Error: Expected value to be true
+ *
+ * --------------------------------------------------------------------------------
+ * Summary
+ * --------------------------------------------------------------------------------
+ * Total:     2
+ * Passed:    1
+ * Failed:    1
+ * Pass Rate: 50.00%
+ * Duration:  57.50ms (avg: 28.75ms)
+ * ```
+ */
+export declare function formatResults(suite: TestSuite): string;
+/**
+ * Format test suite results as JSON
+ *
+ * @param suite - Test suite results
+ * @param pretty - Whether to pretty-print the JSON (default: true)
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('My Tests', [...]);
+ * const json = formatResultsJson(suite);
+ * await fs.writeFile('test-results.json', json);
+ * ```
+ *
+ * Output:
+ * ```json
+ * {
+ *   "name": "My Tests",
+ *   "started_at": "2025-01-01T12:00:00.000Z",
+ *   "completed_at": "2025-01-01T12:00:01.234Z",
+ *   "summary": {
+ *     "total": 5,
+ *     "passed": 4,
+ *     "failed": 1,
+ *     "pass_rate": 80.00,
+ *     "total_duration_ms": 1234.56,
+ *     "avg_duration_ms": 246.91
+ *   },
+ *   "tests": [...]
+ * }
+ * ```
+ */
+export declare function formatResultsJson(suite: TestSuite, pretty?: boolean): string;
+/**
+ * Create a simple assertion helper for tests
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if assertion fails
+ * @throws Error if condition is false
+ *
+ * @example
+ * ```typescript
+ * await runTest('should work', async () => {
+ *   const result = await someOperation();
+ *   assert(result !== null, 'Result should not be null');
+ *   assert(result.value === 'expected', 'Value should be expected');
+ * });
+ * ```
+ */
+export declare function assert(condition: boolean, message?: string): asserts condition;
+/**
+ * Deep equality assertion
+ *
+ * @param actual - Actual value
+ * @param expected - Expected value
+ * @param message - Error message if assertion fails
+ * @throws Error if values are not equal
+ *
+ * @example
+ * ```typescript
+ * await runTest('should match object', async () => {
+ *   const result = await getUser();
+ *   assertEqual(result, { id: '123', name: 'Test' });
+ * });
+ * ```
+ */
+export declare function assertEqual<T>(actual: T, expected: T, message?: string): void;
+/**
+ * Async error assertion helper
+ *
+ * @param fn - Function that should throw
+ * @param expectedMessage - Optional expected error message
+ * @throws Error if function doesn't throw
+ *
+ * @example
+ * ```typescript
+ * await runTest('should reject invalid input', async () => {
+ *   await assertThrows(
+ *     async () => await validateInput('invalid'),
+ *     'Invalid input format'
+ *   );
+ * });
+ * ```
+ */
+export declare function assertThrows(fn: () => Promise<void> | void, expectedMessage?: string): Promise<void>;

package/dist/testing/test-runner.js

@@ -0,0 +1,302 @@
+// =============================================================================
+// Agent-Based Integration Test Runner
+// =============================================================================
+//
+// Core test harness for running integration tests against the ClaudeTools
+// memory system. Provides result collection, timing, and reporting.
+//
+/**
+ * Run a single test with timing and error handling
+ *
+ * @param name - Test name/description
+ * @param fn - Test function to execute
+ * @returns Test result with pass/fail, duration, and error details
+ *
+ * @example
+ * ```typescript
+ * const result = await runTest('should store and retrieve fact', async () => {
+ *   const fact = await storeFact('test', 'RELATES_TO', 'value');
+ *   assert(fact !== null);
+ * });
+ *
+ * if (!result.passed) {
+ *   console.error(`Test failed: ${result.error?.message}`);
+ * }
+ * ```
+ */
+export async function runTest(name, fn) {
+    const startTime = performance.now();
+    try {
+        await fn();
+        const duration_ms = performance.now() - startTime;
+        return {
+            name,
+            passed: true,
+            duration_ms: Math.round(duration_ms * 100) / 100, // Round to 2 decimal places
+        };
+    }
+    catch (error) {
+        const duration_ms = performance.now() - startTime;
+        const err = error;
+        return {
+            name,
+            passed: false,
+            duration_ms: Math.round(duration_ms * 100) / 100,
+            error: {
+                message: err.message || String(error),
+                stack: err.stack,
+            },
+        };
+    }
+}
+/**
+ * Calculate summary statistics from test results
+ *
+ * @param tests - Array of test results
+ * @returns Aggregated summary with counts, duration, and pass rate
+ */
+function calculateSummary(tests) {
+    const total = tests.length;
+    const passed = tests.filter(t => t.passed).length;
+    const failed = total - passed;
+    const total_duration_ms = tests.reduce((sum, t) => sum + t.duration_ms, 0);
+    const avg_duration_ms = total > 0
+        ? Math.round((total_duration_ms / total) * 100) / 100
+        : 0;
+    const pass_rate = total > 0
+        ? Math.round((passed / total) * 10000) / 100 // Round to 2 decimal places
+        : 0;
+    return {
+        total,
+        passed,
+        failed,
+        total_duration_ms: Math.round(total_duration_ms * 100) / 100,
+        avg_duration_ms,
+        pass_rate,
+    };
+}
+/**
+ * Run a suite of tests
+ *
+ * @param name - Suite name
+ * @param tests - Array of test definitions
+ * @returns Complete test suite results with summary
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('Memory Integration Tests', [
+ *   { name: 'should store fact', fn: async () => { ... } },
+ *   { name: 'should search facts', fn: async () => { ... } },
+ *   { name: 'should inject context', fn: async () => { ... } },
+ * ]);
+ *
+ * console.log(formatResults(suite));
+ *
+ * if (suite.summary.failed > 0) {
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export async function runSuite(name, tests) {
+    const started_at = new Date().toISOString();
+    // Run all tests sequentially
+    const results = [];
+    for (const test of tests) {
+        const result = await runTest(test.name, test.fn);
+        results.push(result);
+    }
+    const completed_at = new Date().toISOString();
+    const summary = calculateSummary(results);
+    return {
+        name,
+        tests: results,
+        summary,
+        started_at,
+        completed_at,
+    };
+}
+/**
+ * Format test suite results as human-readable text
+ *
+ * @param suite - Test suite results
+ * @returns Formatted string with test results and summary
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('My Tests', [...]);
+ * console.log(formatResults(suite));
+ * ```
+ *
+ * Output:
+ * ```
+ * ================================================================================
+ * Test Suite: My Tests
+ * ================================================================================
+ *
+ * ✓ should pass test 1 (45.32ms)
+ * ✗ should fail test 2 (12.18ms)
+ *   Error: Expected value to be true
+ *
+ * --------------------------------------------------------------------------------
+ * Summary
+ * --------------------------------------------------------------------------------
+ * Total:     2
+ * Passed:    1
+ * Failed:    1
+ * Pass Rate: 50.00%
+ * Duration:  57.50ms (avg: 28.75ms)
+ * ```
+ */
+export function formatResults(suite) {
+    const lines = [];
+    // Header
+    lines.push('='.repeat(80));
+    lines.push(`Test Suite: ${suite.name}`);
+    lines.push('='.repeat(80));
+    lines.push('');
+    // Individual test results
+    for (const test of suite.tests) {
+        const icon = test.passed ? '✓' : '✗';
+        const status = test.passed ? 'PASS' : 'FAIL';
+        lines.push(`${icon} ${test.name} (${test.duration_ms}ms)`);
+        if (!test.passed && test.error) {
+            lines.push(`  Error: ${test.error.message}`);
+            if (test.error.stack) {
+                const stackLines = test.error.stack.split('\n').slice(1, 4); // First 3 stack frames
+                stackLines.forEach(line => lines.push(`  ${line.trim()}`));
+            }
+        }
+    }
+    // Summary
+    lines.push('');
+    lines.push('-'.repeat(80));
+    lines.push('Summary');
+    lines.push('-'.repeat(80));
+    lines.push(`Total:     ${suite.summary.total}`);
+    lines.push(`Passed:    ${suite.summary.passed}`);
+    lines.push(`Failed:    ${suite.summary.failed}`);
+    lines.push(`Pass Rate: ${suite.summary.pass_rate}%`);
+    lines.push(`Duration:  ${suite.summary.total_duration_ms}ms (avg: ${suite.summary.avg_duration_ms}ms)`);
+    lines.push('');
+    // Overall result
+    const overallStatus = suite.summary.failed === 0 ? 'PASSED ✓' : 'FAILED ✗';
+    lines.push(`Overall: ${overallStatus}`);
+    lines.push('='.repeat(80));
+    return lines.join('\n');
+}
+/**
+ * Format test suite results as JSON
+ *
+ * @param suite - Test suite results
+ * @param pretty - Whether to pretty-print the JSON (default: true)
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const suite = await runSuite('My Tests', [...]);
+ * const json = formatResultsJson(suite);
+ * await fs.writeFile('test-results.json', json);
+ * ```
+ *
+ * Output:
+ * ```json
+ * {
+ *   "name": "My Tests",
+ *   "started_at": "2025-01-01T12:00:00.000Z",
+ *   "completed_at": "2025-01-01T12:00:01.234Z",
+ *   "summary": {
+ *     "total": 5,
+ *     "passed": 4,
+ *     "failed": 1,
+ *     "pass_rate": 80.00,
+ *     "total_duration_ms": 1234.56,
+ *     "avg_duration_ms": 246.91
+ *   },
+ *   "tests": [...]
+ * }
+ * ```
+ */
+export function formatResultsJson(suite, pretty = true) {
+    return pretty
+        ? JSON.stringify(suite, null, 2)
+        : JSON.stringify(suite);
+}
+/**
+ * Create a simple assertion helper for tests
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if assertion fails
+ * @throws Error if condition is false
+ *
+ * @example
+ * ```typescript
+ * await runTest('should work', async () => {
+ *   const result = await someOperation();
+ *   assert(result !== null, 'Result should not be null');
+ *   assert(result.value === 'expected', 'Value should be expected');
+ * });
+ * ```
+ */
+export function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message || 'Assertion failed');
+    }
+}
+/**
+ * Deep equality assertion
+ *
+ * @param actual - Actual value
+ * @param expected - Expected value
+ * @param message - Error message if assertion fails
+ * @throws Error if values are not equal
+ *
+ * @example
+ * ```typescript
+ * await runTest('should match object', async () => {
+ *   const result = await getUser();
+ *   assertEqual(result, { id: '123', name: 'Test' });
+ * });
+ * ```
+ */
+export function assertEqual(actual, expected, message) {
+    const actualJson = JSON.stringify(actual);
+    const expectedJson = JSON.stringify(expected);
+    if (actualJson !== expectedJson) {
+        const msg = message || `Expected ${expectedJson} but got ${actualJson}`;
+        throw new Error(msg);
+    }
+}
+/**
+ * Async error assertion helper
+ *
+ * @param fn - Function that should throw
+ * @param expectedMessage - Optional expected error message
+ * @throws Error if function doesn't throw
+ *
+ * @example
+ * ```typescript
+ * await runTest('should reject invalid input', async () => {
+ *   await assertThrows(
+ *     async () => await validateInput('invalid'),
+ *     'Invalid input format'
+ *   );
+ * });
+ * ```
+ */
+export async function assertThrows(fn, expectedMessage) {
+    try {
+        await fn();
+        throw new Error('Expected function to throw an error');
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'Expected function to throw an error') {
+            throw error;
+        }
+        if (expectedMessage) {
+            const actualMessage = error instanceof Error ? error.message : String(error);
+            if (!actualMessage.includes(expectedMessage)) {
+                throw new Error(`Expected error message to include "${expectedMessage}" but got "${actualMessage}"`);
+            }
+        }
+    }
+}

package/dist/tools.js

@@ -465,6 +465,54 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['goal', 'epic_title', 'tasks'],
                 },
             },
+            {
+                name: 'task_plan_revise',
+                description: 'Modify an existing epic by adding new tasks, removing tasks, or updating task details. Enables iterative planning without recreating the entire plan.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'The ID of the epic to revise',
+                        },
+                        add_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                    domain: { type: 'string' },
+                                    blocked_by: { type: 'array', items: { type: 'string' } },
+                                },
+                                required: ['title'],
+                            },
+                            description: 'New tasks to add to the epic',
+                        },
+                        remove_task_ids: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Task IDs to cancel (sets status to cancelled)',
+                        },
+                        update_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    task_id: { type: 'string' },
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                },
+                                required: ['task_id'],
+                            },
+                            description: 'Tasks to update (adds context about changes)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             {
                 name: 'task_start',
                 description: 'PROACTIVE: When starting work on a task, claim it and get all context. Use this before beginning any task work.',
@@ -608,7 +656,16 @@ High hit rate memories (frequently fetched after being indexed) are good candida
             },
             {
                 name: 'task_claim',
-                description: 'Claim a task for working on it. Creates a lock preventing other agents from working on it.',
+                description: `Claim a task for working on it. Creates a lock preventing other agents from working on it.
+
+Lock duration is automatically scaled based on task effort:
+- xs: 15 minutes
+- s: 30 minutes (default if no effort specified)
+- m: 60 minutes (1 hour)
+- l: 120 minutes (2 hours)
+- xl: 240 minutes (4 hours)
+
+Explicit lock_duration_minutes parameter overrides the effort-based default.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -622,7 +679,7 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                         },
                         lock_duration_minutes: {
                             type: 'number',
-                            description: 'Lock duration in minutes (default: 30)',
+                            description: 'Optional: Override effort-based lock duration (in minutes)',
                         },
                     },
                     required: ['task_id', 'agent_id'],
@@ -739,6 +796,32 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['task_id', 'agent_id'],
                 },
             },
+            {
+                name: 'task_handoff',
+                description: 'Hand off a task to a different expert worker type during execution. Releases current lock, updates agent_type, and sets task back to ready status for re-dispatch.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_id: {
+                            type: 'string',
+                            description: 'The task ID to hand off',
+                        },
+                        new_worker_type: {
+                            type: 'string',
+                            description: 'Target worker type (e.g., "api-expert", "frontend-expert", "database-expert")',
+                        },
+                        reason: {
+                            type: 'string',
+                            description: 'Why the handoff is needed (e.g., "requires database expertise", "needs API integration")',
+                        },
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your agent identifier (default: claude-code)',
+                        },
+                    },
+                    required: ['task_id', 'new_worker_type', 'reason'],
+                },
+            },
             // =========================================================================
             // ORCHESTRATION TOOLS
             // =========================================================================
@@ -921,6 +1004,24 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['epic_id'],
                 },
             },
+            {
+                name: 'task_aggregate',
+                description: 'Aggregate work_log context from all sibling tasks under an epic for orchestrator synthesis. Returns structured summary of completed work across all tasks in the epic.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'Epic ID to aggregate from',
+                        },
+                        include_pending: {
+                            type: 'boolean',
+                            description: 'Include non-completed tasks (default: false)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             // =========================================================================
             // CODEBASE MAPPING TOOLS
             // =========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",