memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/tools/backup.ts

@@ -0,0 +1,242 @@
+/**
+ * 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'
+
+// ============================================================================
+// 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(),
+})
+
+const BackupInfoSchema = z.object({
+    filename: 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(),
+})
+
+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(),
+})
+
+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(),
+})
+
+// ============================================================================
+// 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: true },
+            handler: (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            name: z.string().optional(),
+                        })
+                        .parse(params)
+                    const result = 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({}),
+            outputSchema: BackupsListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            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
+                    .literal(true)
+                    .describe('Must be set to true to confirm the restore operation'),
+            }),
+            outputSchema: RestoreResultOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            filename: z.string(),
+                            confirm: z.literal(true),
+                        })
+                        .parse(params)
+
+                    // 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 {
+                            // Best-effort notification
+                        }
+                    }
+
+                    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: z
+                    .number()
+                    .min(1)
+                    .default(5)
+                    .describe('Number of most recent backups to keep (default: 5)'),
+            }),
+            outputSchema: CleanupBackupsOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: 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)
+                }
+            },
+        },
+    ]
+}

package/src/handlers/tools/core.ts

@@ -0,0 +1,350 @@
+/**
+ * Core Tool Group - 6 tools
+ *
+ * Tools: create_entry, get_entry_by_id, get_recent_entries,
+ *        create_entry_minimal, test_simple, list_tags
+ */
+
+import { z } from 'zod'
+import { execFileSync } from 'node:child_process'
+import type { ToolDefinition, ToolContext } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import {
+    ENTRY_TYPES,
+    SIGNIFICANCE_TYPES,
+    EntryOutputSchema,
+    EntriesListOutputSchema,
+    RelationshipOutputSchema,
+    ImportanceBreakdownSchema,
+    TagOutputSchema,
+} from './schemas.js'
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const CreateEntrySchema = z.object({
+    content: z.string().min(1).max(50000),
+    entry_type: z.enum(ENTRY_TYPES).optional().default('personal_reflection'),
+    tags: z.array(z.string()).optional().default([]),
+    is_personal: z.boolean().optional().default(true),
+    significance_type: z.enum(SIGNIFICANCE_TYPES).optional(),
+    auto_context: z.boolean().optional().default(true),
+    project_number: z.number().optional(),
+    project_owner: z.string().optional(),
+    issue_number: z.number().optional(),
+    issue_url: z.string().optional(),
+    pr_number: z.number().optional(),
+    pr_url: z.string().optional(),
+    pr_status: z.enum(['draft', 'open', 'merged', 'closed']).optional(),
+    workflow_run_id: z.number().optional(),
+    workflow_name: z.string().optional(),
+    workflow_status: z.enum(['queued', 'in_progress', 'completed']).optional(),
+    share_with_team: z.boolean().optional().default(false),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod enum errors reach the handler */
+const CreateEntrySchemaMcp = z.object({
+    content: z.string().min(1).max(50000),
+    entry_type: z.string().optional().default('personal_reflection'),
+    tags: z.array(z.string()).optional().default([]),
+    is_personal: z.boolean().optional().default(true),
+    significance_type: z.string().optional(),
+    auto_context: z.boolean().optional().default(true),
+    project_number: z.number().optional(),
+    project_owner: z.string().optional(),
+    issue_number: z.number().optional(),
+    issue_url: z.string().optional(),
+    pr_number: z.number().optional(),
+    pr_url: z.string().optional(),
+    pr_status: z.string().optional(),
+    workflow_run_id: z.number().optional(),
+    workflow_name: z.string().optional(),
+    workflow_status: z.string().optional(),
+    share_with_team: z.boolean().optional().default(false),
+})
+
+const GetEntryByIdSchema = z.object({
+    entry_id: z.number(),
+    include_relationships: z.boolean().optional().default(true),
+})
+
+const GetRecentEntriesSchema = z.object({
+    limit: z.number().max(500).optional().default(5),
+    is_personal: z.boolean().optional(),
+})
+
+const CreateEntryMinimalSchema = z.object({
+    content: z.string().min(1).max(50000),
+})
+
+const TestSimpleSchema = z.object({
+    message: z.string().optional().default('Hello'),
+})
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const CreateEntryOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entry: EntryOutputSchema.optional(),
+    sharedWithTeam: z.boolean().optional(),
+    author: z.string().optional(),
+    error: z.string().optional(),
+})
+
+const EntryByIdOutputSchema = z.object({
+    entry: EntryOutputSchema.optional(),
+    relationships: z.array(RelationshipOutputSchema).optional(),
+    importance: z.number().nullable().optional(),
+    importanceBreakdown: ImportanceBreakdownSchema.optional(),
+    error: z.string().optional(),
+})
+
+const TestSimpleOutputSchema = z.object({
+    message: z.string(),
+})
+
+const TagsListOutputSchema = z.object({
+    tags: z.array(TagOutputSchema).optional(),
+    count: z.number().optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Resolve the author name for team-shared entries */
+function resolveTeamAuthor(): string {
+    const envAuthor = process.env['TEAM_AUTHOR']?.trim().replace(/"/g, '')
+    if (envAuthor) return envAuthor
+    try {
+        const gitUser = execFileSync('git', ['config', 'user.name'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+        })
+            .trim()
+            .replace(/"/g, '')
+        if (gitUser) return gitUser
+    } catch {
+        // Git not available
+    }
+    return 'unknown'
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getCoreTools(context: ToolContext): ToolDefinition[] {
+    const { db, teamDb, vectorManager, github } = context
+    return [
+        {
+            name: 'create_entry',
+            title: 'Create Journal Entry',
+            description:
+                'Create a new journal entry with context and tags (v2.1.0: GitHub Actions support)',
+            group: 'core',
+            inputSchema: CreateEntrySchemaMcp,
+            outputSchema: CreateEntryOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    const input = CreateEntrySchema.parse(params)
+
+                    // Auto-populate issueUrl if issue_number provided without issueUrl
+                    let resolvedIssueUrl = input.issue_url
+                    if (input.issue_number !== undefined && !input.issue_url && github) {
+                        const cachedRepo = github.getCachedRepoInfo()
+                        if (cachedRepo?.owner && cachedRepo?.repo) {
+                            resolvedIssueUrl = `https://github.com/${cachedRepo.owner}/${cachedRepo.repo}/issues/${String(input.issue_number)}`
+                        }
+                    }
+
+                    const entry = db.createEntry({
+                        content: input.content,
+                        entryType: input.entry_type,
+                        tags: input.tags,
+                        isPersonal: input.is_personal,
+                        significanceType: input.significance_type ?? null,
+                        projectNumber: input.project_number,
+                        projectOwner: input.project_owner,
+                        issueNumber: input.issue_number,
+                        issueUrl: resolvedIssueUrl,
+                        prNumber: input.pr_number,
+                        prUrl: input.pr_url,
+                        prStatus: input.pr_status,
+                        workflowRunId: input.workflow_run_id,
+                        workflowName: input.workflow_name,
+                        workflowStatus: input.workflow_status,
+                    })
+
+                    // Auto-index to vector store for semantic search (fire-and-forget)
+                    if (vectorManager) {
+                        vectorManager.addEntry(entry.id, entry.content).catch(() => {
+                            // Non-critical failure, entry already saved to DB
+                        })
+                    }
+
+                    // Share with team if requested
+                    let sharedWithTeam = false
+                    let author: string | undefined
+                    if (input.share_with_team && teamDb) {
+                        try {
+                            author = resolveTeamAuthor()
+                            const teamEntry = teamDb.createEntry({
+                                content: input.content,
+                                entryType: input.entry_type,
+                                tags: input.tags,
+                                isPersonal: false,
+                                significanceType: input.significance_type ?? null,
+                                autoContext: JSON.stringify({ author }),
+                                projectNumber: input.project_number,
+                                projectOwner: input.project_owner,
+                                issueNumber: input.issue_number,
+                                issueUrl: resolvedIssueUrl,
+                                prNumber: input.pr_number,
+                                prUrl: input.pr_url,
+                                prStatus: input.pr_status,
+                                workflowRunId: input.workflow_run_id,
+                                workflowName: input.workflow_name,
+                                workflowStatus: input.workflow_status,
+                            })
+                            const rawTeamDb = teamDb.getRawDb()
+                            rawTeamDb.run('UPDATE memory_journal SET author = ? WHERE id = ?', [
+                                author,
+                                teamEntry.id,
+                            ])
+                            teamDb.flushSave()
+                            sharedWithTeam = true
+                        } catch {
+                            // Team share failed — entry still saved to personal DB
+                        }
+                    }
+
+                    return {
+                        success: true,
+                        entry,
+                        ...(sharedWithTeam ? { sharedWithTeam: true, author } : {}),
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_entry_by_id',
+            title: 'Get Entry by ID',
+            description: 'Get a specific journal entry by ID with full details',
+            group: 'core',
+            inputSchema: GetEntryByIdSchema,
+            outputSchema: EntryByIdOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const { entry_id, include_relationships } = GetEntryByIdSchema.parse(params)
+                    const entry = db.getEntryById(entry_id)
+                    if (!entry) {
+                        return { success: false, error: `Entry ${String(entry_id)} not found` }
+                    }
+                    const { score: importance, breakdown: importanceBreakdown } =
+                        db.calculateImportance(entry_id)
+                    const result: Record<string, unknown> = {
+                        entry,
+                        importance,
+                        importanceBreakdown,
+                    }
+                    if (include_relationships) {
+                        result['relationships'] = db.getRelationships(entry_id)
+                    }
+                    return result
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_recent_entries',
+            title: 'Get Recent Entries',
+            description: 'Get recent journal entries',
+            group: 'core',
+            inputSchema: GetRecentEntriesSchema,
+            outputSchema: EntriesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const { limit, is_personal } = GetRecentEntriesSchema.parse(params)
+                    const entries = db.getRecentEntries(limit, is_personal)
+                    return { entries, count: entries.length }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'create_entry_minimal',
+            title: 'Create Entry (Minimal)',
+            description: 'Minimal entry creation without context or tags',
+            group: 'core',
+            inputSchema: CreateEntryMinimalSchema,
+            outputSchema: CreateEntryOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    const { content } = CreateEntryMinimalSchema.parse(params)
+                    const entry = db.createEntry({ content })
+
+                    // Auto-index to vector store for semantic search (fire-and-forget)
+                    if (vectorManager) {
+                        vectorManager.addEntry(entry.id, entry.content).catch(() => {
+                            // Non-critical failure, entry already saved to DB
+                        })
+                    }
+
+                    return { success: true, entry }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'test_simple',
+            title: 'Test Simple',
+            description: 'Simple test tool that just returns a message',
+            group: 'core',
+            inputSchema: TestSimpleSchema,
+            outputSchema: TestSimpleOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const { message } = TestSimpleSchema.parse(params)
+                    return { message: `Test response: ${message}` }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'list_tags',
+            title: 'List Tags',
+            description: 'List all available tags',
+            group: 'core',
+            inputSchema: z.object({}),
+            outputSchema: TagsListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (_params: unknown) => {
+                try {
+                    const rawTags = db.listTags()
+                    const tags = rawTags.map((t) => ({ name: t.name, count: t.usageCount }))
+                    return { tags, count: tags.length }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}