memory-journal-mcp 6.1.2 → 6.2.1

package/src/handlers/tools/analytics.ts

@@ -1,346 +0,0 @@
-/**
- * Analytics Tool Group - 2 tools
- *
- * Tools: get_statistics, get_cross_project_insights
- */
-
-import { z } from 'zod'
-import type { ToolDefinition, ToolContext } from '../../types/index.js'
-import { formatHandlerError } from '../../utils/error-helpers.js'
-import {
-    DATE_FORMAT_REGEX,
-    DATE_FORMAT_MESSAGE,
-    TagOutputSchema,
-    relaxedNumber,
-} from './schemas.js'
-import { ErrorFieldsMixin } from './error-fields-mixin.js'
-
-// Named constants (magic value extraction)
-const INACTIVE_THRESHOLD_DAYS = 7
-const MS_PER_DAY = 86_400_000
-const MAX_TAGS_PER_PROJECT = 5
-
-// ============================================================================
-// Output Schemas
-// ============================================================================
-
-const StatisticsOutputSchema = z
-    .object({
-        groupBy: z.string().optional(),
-        totalEntries: z.number().optional(),
-        entriesByType: z.record(z.string(), z.number()).optional(),
-        entriesByPeriod: z
-            .array(
-                z.object({
-                    period: z.string(),
-                    count: z.number(),
-                })
-            )
-            .optional(),
-        decisionDensity: z
-            .array(
-                z.object({
-                    period: z.string(),
-                    significantCount: z.number(),
-                })
-            )
-            .optional(),
-        relationshipComplexity: z
-            .object({
-                totalRelationships: z.number(),
-                avgPerEntry: z.number(),
-            })
-            .optional(),
-        activityTrend: z
-            .object({
-                currentPeriod: z.string(),
-                previousPeriod: z.string(),
-                growthPercent: z.number().nullable(),
-            })
-            .optional(),
-        causalMetrics: z
-            .object({
-                blocked_by: z.number(),
-                resolved: z.number(),
-                caused: z.number(),
-            })
-            .optional(),
-        dateRange: z
-            .object({
-                startDate: z.string(),
-                endDate: z.string(),
-            })
-            .optional(),
-        projectBreakdown: z
-            .array(
-                z.object({
-                    project_number: z.number(),
-                    entry_count: z.number(),
-                })
-            )
-            .optional(),
-        success: z.boolean().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const ProjectSummaryOutputSchema = z
-    .object({
-        project_number: z.number(),
-        entry_count: z.number(),
-        first_entry: z.string(),
-        last_entry: z.string(),
-        active_days: z.number(),
-        top_tags: z.array(TagOutputSchema),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const CrossProjectInsightsOutputSchema = z
-    .object({
-        project_count: z.number().optional(),
-        total_entries: z.number().optional(),
-        projects: z.array(ProjectSummaryOutputSchema).optional(),
-        inactive_projects: z
-            .array(
-                z.object({
-                    project_number: z.number(),
-                    last_entry_date: z.string(),
-                })
-            )
-            .optional(),
-        inactiveThresholdDays: z.number().optional(),
-        time_distribution: z
-            .array(
-                z.object({
-                    project_number: z.number(),
-                    percentage: z.string(),
-                })
-            )
-            .optional(),
-        message: z.string().optional(),
-        success: z.boolean().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-// ============================================================================
-// Input Schemas
-// ============================================================================
-
-/** Strict schema — used inside handler for structured Zod errors */
-const GetStatisticsSchema = z.object({
-    group_by: z.enum(['day', 'week', 'month']).optional().default('week'),
-    start_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
-    end_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
-    project_breakdown: z.boolean().optional().default(false),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
-const GetStatisticsSchemaMcp = z.object({
-    group_by: z.string().optional().default('week'),
-    start_date: z.string().optional(),
-    end_date: z.string().optional(),
-    project_breakdown: z.boolean().optional().default(false),
-})
-
-/** Strict schema — used inside handler for structured Zod errors */
-const CrossProjectInsightsInputSchema = z.object({
-    start_date: z
-        .string()
-        .regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE)
-        .optional()
-        .describe('Start date (YYYY-MM-DD)'),
-    end_date: z
-        .string()
-        .regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE)
-        .optional()
-        .describe('End date (YYYY-MM-DD)'),
-    min_entries: z.number().optional().default(3).describe('Minimum entries to include project'),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
-const CrossProjectInsightsInputSchemaMcp = z.object({
-    start_date: z.string().optional().describe('Start date (YYYY-MM-DD)'),
-    end_date: z.string().optional().describe('End date (YYYY-MM-DD)'),
-    min_entries: relaxedNumber()
-        .optional()
-        .default(3)
-        .describe('Minimum entries to include project'),
-})
-
-// ============================================================================
-// Tool Definitions
-// ============================================================================
-
-export function getAnalyticsTools(context: ToolContext): ToolDefinition[] {
-    const { db } = context
-    return [
-        {
-            name: 'get_statistics',
-            title: 'Get Statistics',
-            description:
-                'Get journal statistics and analytics (Phase 2: includes project breakdown)',
-            group: 'analytics',
-            inputSchema: GetStatisticsSchemaMcp,
-            outputSchema: StatisticsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const { group_by, start_date, end_date, project_breakdown } =
-                        GetStatisticsSchema.parse(params)
-                    const stats = db.getStatistics(
-                        group_by,
-                        start_date,
-                        end_date,
-                        project_breakdown
-                    )
-                    return { ...(stats as object), groupBy: group_by }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'get_cross_project_insights',
-            title: 'Get Cross-Project Insights',
-            description: 'Analyze patterns across all GitHub Projects tracked in journal entries',
-            group: 'analytics',
-            inputSchema: CrossProjectInsightsInputSchemaMcp,
-            outputSchema: CrossProjectInsightsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const input = CrossProjectInsightsInputSchema.parse(params)
-
-                    // Build WHERE clause
-                    let where = 'WHERE deleted_at IS NULL AND project_number IS NOT NULL'
-                    const sqlParams: unknown[] = []
-
-                    if (input.start_date) {
-                        where += ' AND DATE(timestamp) >= DATE(?)'
-                        sqlParams.push(input.start_date)
-                    }
-                    if (input.end_date) {
-                        where += ' AND DATE(timestamp) <= DATE(?)'
-                        sqlParams.push(input.end_date)
-                    }
-
-                    // Get active projects with stats
-                    const projectsResult = db.executeRawQuery(
-                        `
-                        SELECT project_number, COUNT(*) as entry_count,
-                               MIN(DATE(timestamp)) as first_entry,
-                               MAX(DATE(timestamp)) as last_entry,
-                               COUNT(DISTINCT DATE(timestamp)) as active_days
-                        FROM memory_journal ${where}
-                        GROUP BY project_number
-                        HAVING entry_count >= ?
-                        ORDER BY entry_count DESC
-                    `,
-                        [...sqlParams, input.min_entries]
-                    )
-
-                    if (!projectsResult[0] || projectsResult[0].values.length === 0) {
-                        return {
-                            project_count: 0,
-                            total_entries: 0,
-                            projects: [],
-                            inactive_projects: [],
-                            inactiveThresholdDays: INACTIVE_THRESHOLD_DAYS,
-                            time_distribution: [],
-                            message: `No projects found with at least ${String(input.min_entries)} entries`,
-                        }
-                    }
-
-                    const columns = projectsResult[0].columns
-                    const projects = projectsResult[0].values.map((row: unknown[]) => {
-                        const obj: Record<string, unknown> = {}
-                        columns.forEach((col: string, i: number) => {
-                            obj[col] = row[i]
-                        })
-                        return obj
-                    })
-
-                    // Get top tags per project (batch query instead of N+1)
-                    const projectTags: Record<number, { name: string; count: number }[]> = {}
-                    const projectNumbers = projects.map((p) => p['project_number'] as number)
-                    if (projectNumbers.length > 0) {
-                        const tagPlaceholders = projectNumbers.map(() => '?').join(',')
-                        const allTagsResult = db.executeRawQuery(
-                            `
-                            SELECT m.project_number, t.name, COUNT(*) as count
-                            FROM tags t
-                            JOIN entry_tags et ON t.id = et.tag_id
-                            JOIN memory_journal m ON et.entry_id = m.id
-                            WHERE m.project_number IN (${tagPlaceholders}) AND m.deleted_at IS NULL
-                            GROUP BY m.project_number, t.name
-                            ORDER BY m.project_number, count DESC
-                            `,
-                            projectNumbers
-                        )
-                        if (allTagsResult[0]) {
-                            // Partition rows by project_number, keeping top 5 per project
-                            for (const row of allTagsResult[0].values) {
-                                const projNum = row[0] as number
-                                const tagEntry = { name: row[1] as string, count: row[2] as number }
-                                const existing = projectTags[projNum] ?? []
-                                if (existing.length < MAX_TAGS_PER_PROJECT) {
-                                    existing.push(tagEntry)
-                                    projectTags[projNum] = existing
-                                }
-                            }
-                        }
-                    }
-
-                    // Find inactive projects (last entry > threshold days ago)
-                    const cutoffDate = new Date(Date.now() - INACTIVE_THRESHOLD_DAYS * MS_PER_DAY)
-                        .toISOString()
-                        .split('T')[0]
-                    const inactiveResult = db.executeRawQuery(
-                        `
-                        SELECT project_number, MAX(DATE(timestamp)) as last_entry_date
-                        FROM memory_journal
-                        WHERE deleted_at IS NULL AND project_number IS NOT NULL
-                        GROUP BY project_number
-                        HAVING last_entry_date < ?
-                    `,
-                        [cutoffDate]
-                    )
-
-                    const inactiveProjects =
-                        inactiveResult[0]?.values.map((row: unknown[]) => ({
-                            project_number: row[0] as number,
-                            last_entry_date: row[1] as string,
-                        })) ?? []
-
-                    // Calculate time distribution
-                    const totalEntries = projects.reduce(
-                        (sum: number, p: Record<string, unknown>) =>
-                            sum + (p['entry_count'] as number),
-                        0
-                    )
-                    const distribution = projects.slice(0, 5).map((p: Record<string, unknown>) => ({
-                        project_number: p['project_number'] as number,
-                        percentage: (((p['entry_count'] as number) / totalEntries) * 100).toFixed(
-                            1
-                        ),
-                    }))
-
-                    return {
-                        project_count: projects.length,
-                        total_entries: totalEntries,
-                        projects: projects.map((p) => ({
-                            ...p,
-                            top_tags: projectTags[p['project_number'] as number] ?? [],
-                        })),
-                        inactive_projects: inactiveProjects,
-                        inactiveThresholdDays: INACTIVE_THRESHOLD_DAYS,
-                        time_distribution: distribution,
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-    ]
-}

package/src/handlers/tools/backup.ts

@@ -1,272 +0,0 @@
-/**
- * Backup Tool Group - 4 tools
- *
- * Tools: backup_journal, list_backups, restore_backup, cleanup_backups
- */
-
-import { z } from 'zod'
-import type { ToolDefinition, ToolContext } from '../../types/index.js'
-import { formatHandlerError } from '../../utils/error-helpers.js'
-import { sendProgress } from '../../utils/progress-utils.js'
-import { relaxedNumber } from './schemas.js'
-import { ErrorFieldsMixin } from './error-fields-mixin.js'
-import { logger } from '../../utils/logger.js'
-
-// ============================================================================
-// Output Schemas
-// ============================================================================
-
-const BackupResultOutputSchema = z
-    .object({
-        success: z.boolean(),
-        message: z.string().optional(),
-        filename: z.string().optional(),
-        path: z.string().optional(),
-        sizeBytes: z.number().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const BackupInfoSchema = z.object({
-    filename: z.string(),
-    path: z.string(),
-    sizeBytes: z.number(),
-    createdAt: z.string(),
-})
-
-const BackupsListOutputSchema = z
-    .object({
-        success: z.boolean().optional(),
-        backups: z.array(BackupInfoSchema).optional(),
-        total: z.number().optional(),
-        backupsDirectory: z.string().optional(),
-        hint: z.string().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const RestoreResultOutputSchema = z
-    .object({
-        success: z.boolean(),
-        message: z.string().optional(),
-        restoredFrom: z.string().optional(),
-        previousEntryCount: z.number().optional(),
-        newEntryCount: z.number().optional(),
-        warning: z.string().optional(),
-        revertedChanges: z
-            .object({
-                tagMerges: z.string().optional(),
-                entries: z.string().optional(),
-            })
-            .optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const CleanupBackupsOutputSchema = z
-    .object({
-        success: z.boolean(),
-        deleted: z.array(z.string()).optional(),
-        deletedCount: z.number().optional(),
-        keptCount: z.number().optional(),
-        message: z.string().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-// ============================================================================
-// Tool Definitions
-// ============================================================================
-
-export function getBackupTools(context: ToolContext): ToolDefinition[] {
-    const { db, progress } = context
-    return [
-        {
-            name: 'backup_journal',
-            title: 'Backup Journal Database',
-            description:
-                'Create a timestamped backup of the journal database. Backups are stored in the backups/ directory.',
-            group: 'backup',
-            inputSchema: z.object({
-                name: z
-                    .string()
-                    .optional()
-                    .describe('Custom backup name (optional, defaults to timestamp)'),
-            }),
-            outputSchema: BackupResultOutputSchema,
-            annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
-            handler: async (params: unknown) => {
-                try {
-                    const input = z
-                        .object({
-                            name: z.string().optional(),
-                        })
-                        .parse(params)
-                    const result = await db.exportToFile(input.name)
-                    return {
-                        success: true,
-                        message: `Backup created successfully`,
-                        filename: result.filename,
-                        path: result.path,
-                        sizeBytes: result.sizeBytes,
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'list_backups',
-            title: 'List Journal Backups',
-            description: 'List all available backup files with their sizes and creation dates',
-            group: 'backup',
-            inputSchema: z.object({}).strict(),
-            outputSchema: BackupsListOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (_params: unknown) => {
-                try {
-                    const backups = db.listBackups()
-                    return {
-                        backups,
-                        total: backups.length,
-                        backupsDirectory: db.getBackupsDir(),
-                        hint:
-                            backups.length === 0
-                                ? 'No backups found. Use backup_journal to create one.'
-                                : undefined,
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'restore_backup',
-            title: 'Restore Journal from Backup',
-            description:
-                'Restore the journal database from a backup file. WARNING: This replaces all current data. An automatic backup is created before restore.',
-            group: 'backup',
-            inputSchema: z.object({
-                filename: z
-                    .string()
-                    .describe('Backup filename to restore from (e.g., backup_2025-01-01.db)'),
-                confirm: z
-                    .boolean()
-                    .describe('Must be set to true to confirm the restore operation'),
-            }),
-            outputSchema: RestoreResultOutputSchema,
-            annotations: {
-                readOnlyHint: false,
-                idempotentHint: false,
-                destructiveHint: true,
-                openWorldHint: false,
-            },
-            handler: async (params: unknown) => {
-                try {
-                    const input = z
-                        .object({
-                            filename: z.string(),
-                            confirm: z.boolean(),
-                        })
-                        .parse(params)
-
-                    if (!input.confirm) {
-                        return {
-                            success: false,
-                            error: 'Restore requires confirm: true. This operation replaces all current data.',
-                            code: 'VALIDATION_ERROR',
-                            category: 'validation',
-                            suggestion: 'Set confirm: true to proceed with restore',
-                            recoverable: false,
-                        }
-                    }
-
-                    // Capture progress context values BEFORE any async operations
-                    const progressServer = progress?.server
-                    const progressTokenValue = progress?.progressToken
-
-                    await sendProgress(progress, 1, 3, 'Preparing restore...')
-                    await sendProgress(progress, 2, 3, 'Restoring database from backup...')
-                    const result = await db.restoreFromFile(input.filename)
-
-                    // Send directly using captured primitives (db.restoreFromFile reinitializes DB)
-                    if (progressServer !== undefined && progressTokenValue !== undefined) {
-                        try {
-                            await progressServer.notification({
-                                method: 'notifications/progress' as const,
-                                params: {
-                                    progressToken: progressTokenValue,
-                                    progress: 3,
-                                    total: 3,
-                                    message: 'Restore complete',
-                                },
-                            })
-                        } catch (error) {
-                            logger.debug('Failed to send restore progress notification', {
-                                module: 'TOOL',
-                                operation: 'restore-backup',
-                                error,
-                            })
-                        }
-                    }
-
-                    return {
-                        success: true,
-                        message: `Database restored from ${input.filename}`,
-                        restoredFrom: result.restoredFrom,
-                        previousEntryCount: result.previousEntryCount,
-                        newEntryCount: result.newEntryCount,
-                        warning:
-                            'A pre-restore backup was automatically created. Any changes made since this backup (including tag merges, new entries, and relationships) have been reverted.',
-                        revertedChanges: {
-                            tagMerges:
-                                'Any merge_tags operations since this backup are reverted. Previously merged tags will reappear as separate tags.',
-                            entries:
-                                result.previousEntryCount !== result.newEntryCount
-                                    ? `Entry count changed from ${String(result.previousEntryCount)} to ${String(result.newEntryCount)}`
-                                    : undefined,
-                        },
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'cleanup_backups',
-            title: 'Cleanup Old Backups',
-            description:
-                'Delete old backup files, keeping only the most recent N backups. Use list_backups to preview before cleanup.',
-            group: 'backup',
-            inputSchema: z.object({
-                keep_count: relaxedNumber()
-                    .default(5)
-                    .describe('Number of most recent backups to keep (default: 5)'),
-            }),
-            outputSchema: CleanupBackupsOutputSchema,
-            annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const { keep_count } = z
-                        .object({ keep_count: z.number().min(1).default(5) })
-                        .parse(params)
-
-                    const result = db.deleteOldBackups(keep_count)
-
-                    return {
-                        success: true,
-                        deleted: result.deleted,
-                        deletedCount: result.deleted.length,
-                        keptCount: result.kept,
-                        message:
-                            result.deleted.length > 0
-                                ? `Deleted ${String(result.deleted.length)} old backup(s), kept ${String(result.kept)}`
-                                : `No backups to delete. Currently have ${String(result.kept)} backup(s).`,
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-    ]
-}