mcp-memory-keeper 0.10.0

package/dist/__tests__/utils/migrationHealthCheck.test.js

@@ -0,0 +1,302 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const database_1 = require("../../utils/database");
+const migrationHealthCheck_1 = require("../../utils/migrationHealthCheck");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+(0, globals_1.describe)('MigrationHealthCheck', () => {
+    let tempDir;
+    let dbPath;
+    let dbManager;
+    let healthCheck;
+    (0, globals_1.beforeEach)(() => {
+        // Create temporary directory for test database
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-test-'));
+        dbPath = path.join(tempDir, 'test.db');
+    });
+    (0, globals_1.afterEach)(() => {
+        // Clean up
+        if (dbManager) {
+            dbManager.close();
+        }
+        // Remove temporary directory
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    (0, globals_1.describe)('Missing column detection', () => {
+        (0, globals_1.it)('should detect missing metadata column in context_items table', () => {
+            // Create a database with old schema (missing metadata column)
+            const db = new better_sqlite3_1.default(dbPath);
+            db.exec(`
+        CREATE TABLE sessions (
+          id TEXT PRIMARY KEY,
+          name TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+        
+        CREATE TABLE context_items (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          category TEXT,
+          priority TEXT DEFAULT 'normal',
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+        );
+      `);
+            // Create health check without initializing DatabaseManager to avoid auto-fix
+            const dbManager = new better_sqlite3_1.default(dbPath);
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck({ getDatabase: () => dbManager });
+            const result = healthCheck.runHealthCheck();
+            db.close();
+            dbManager.close();
+            // Should detect missing columns
+            (0, globals_1.expect)(result.issues.length).toBeGreaterThan(0);
+            const metadataIssue = result.issues.find(issue => issue.table === 'context_items' && issue.issue.includes('metadata'));
+            (0, globals_1.expect)(metadataIssue).toBeDefined();
+            (0, globals_1.expect)(metadataIssue?.severity).toBe('error');
+            (0, globals_1.expect)(metadataIssue?.fix).toContain('ALTER TABLE context_items ADD COLUMN metadata TEXT');
+        });
+        (0, globals_1.it)('should detect multiple missing columns', () => {
+            // Create a database with very old schema
+            const db = new better_sqlite3_1.default(dbPath);
+            db.exec(`
+        CREATE TABLE sessions (
+          id TEXT PRIMARY KEY,
+          name TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+        
+        CREATE TABLE context_items (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+        );
+      `);
+            // Create health check without initializing DatabaseManager
+            const dbManager = new better_sqlite3_1.default(dbPath);
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck({ getDatabase: () => dbManager });
+            const result = healthCheck.runHealthCheck();
+            db.close();
+            dbManager.close();
+            // Should detect multiple missing columns
+            const missingColumns = ['category', 'priority', 'metadata', 'size'];
+            for (const column of missingColumns) {
+                const issue = result.issues.find(i => i.table === 'context_items' && i.issue.includes(column));
+                (0, globals_1.expect)(issue).toBeDefined();
+            }
+            // updated_at might exist depending on schema version, check separately
+            const hasUpdatedAt = result.issues.some(i => i.table === 'context_items' && i.issue.includes('updated_at'));
+            if (hasUpdatedAt) {
+                (0, globals_1.expect)(result.issues.length).toBeGreaterThanOrEqual(missingColumns.length + 1);
+            }
+            else {
+                (0, globals_1.expect)(result.issues.length).toBeGreaterThanOrEqual(missingColumns.length);
+            }
+        });
+    });
+    (0, globals_1.describe)('Auto-fix functionality', () => {
+        (0, globals_1.it)('should successfully add missing columns', () => {
+            // Create a database with old schema
+            const db = new better_sqlite3_1.default(dbPath);
+            db.exec(`
+        CREATE TABLE sessions (
+          id TEXT PRIMARY KEY,
+          name TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+        
+        CREATE TABLE context_items (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          category TEXT,
+          priority TEXT DEFAULT 'normal',
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+        );
+      `);
+            db.close();
+            // Create proper DatabaseManager instance but prevent auto-fix during init
+            const testDb = new better_sqlite3_1.default(dbPath);
+            const mockDbManager = {
+                getDatabase: () => testDb,
+                close: () => testDb.close(),
+            };
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck(mockDbManager);
+            // First check what issues exist
+            const beforeFix = healthCheck.runHealthCheck();
+            (0, globals_1.expect)(beforeFix.issues.length).toBeGreaterThan(0);
+            (0, globals_1.expect)(beforeFix.canAutoFix).toBe(true);
+            // Apply auto-fix
+            const success = healthCheck.runAutoFix();
+            (0, globals_1.expect)(success).toBe(true);
+            // Verify fixes were applied
+            const afterFix = healthCheck.runHealthCheck();
+            (0, globals_1.expect)(afterFix.issues.length).toBe(0);
+            (0, globals_1.expect)(afterFix.summary).toContain('Database schema is healthy');
+            mockDbManager.close();
+        });
+        (0, globals_1.it)('should handle errors gracefully when fix fails', () => {
+            // Create a database with correct schema first
+            dbManager = new database_1.DatabaseManager({ filename: dbPath });
+            const db = dbManager.getDatabase();
+            // Drop a column to simulate missing column
+            db.exec(`
+        CREATE TABLE temp_context_items AS SELECT id, session_id, key, value, category, priority, created_at FROM context_items;
+        DROP TABLE context_items;
+        ALTER TABLE temp_context_items RENAME TO context_items;
+      `);
+            // Create health check instance
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck(dbManager);
+            const result = healthCheck.runHealthCheck();
+            (0, globals_1.expect)(result.issues.length).toBeGreaterThan(0);
+            // Mock exec to simulate failure
+            const originalExec = db.exec.bind(db);
+            db.exec = jest.fn().mockImplementation(() => {
+                throw new Error('Simulated database error');
+            });
+            // Try to auto-fix (should fail gracefully)
+            const { fixed, failed } = healthCheck.autoFixIssues(result.issues);
+            (0, globals_1.expect)(fixed.length).toBe(0);
+            (0, globals_1.expect)(failed.length).toBeGreaterThan(0);
+            // Restore original exec
+            db.exec = originalExec;
+        });
+    });
+    (0, globals_1.describe)('Schema discovery', () => {
+        (0, globals_1.it)('should correctly parse schema from database.ts file', () => {
+            // Create a new database with full schema
+            dbManager = new database_1.DatabaseManager({ filename: dbPath });
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck(dbManager);
+            // Run health check on a properly initialized database
+            const result = healthCheck.runHealthCheck();
+            // Should have no issues
+            (0, globals_1.expect)(result.issues.length).toBe(0);
+            (0, globals_1.expect)(result.summary).toContain('Database schema is healthy');
+        });
+        (0, globals_1.it)('should work with empty database (new user)', () => {
+            // Create completely empty database
+            const db = new better_sqlite3_1.default(dbPath);
+            db.close();
+            // Run health check
+            dbManager = new database_1.DatabaseManager({ filename: dbPath });
+            healthCheck = new migrationHealthCheck_1.MigrationHealthCheck(dbManager);
+            // Check should pass - tables will be created during initialization
+            const result = healthCheck.runHealthCheck();
+            (0, globals_1.expect)(result.summary).toContain('Database schema is healthy');
+        });
+    });
+    (0, globals_1.describe)('Integration with DatabaseManager', () => {
+        (0, globals_1.it)('should automatically fix issues on database initialization', () => {
+            // Create a database with old schema
+            const db = new better_sqlite3_1.default(dbPath);
+            db.exec(`
+        CREATE TABLE sessions (
+          id TEXT PRIMARY KEY,
+          name TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+        
+        CREATE TABLE context_items (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+      `);
+            db.close();
+            // Initialize DatabaseManager (should auto-fix)
+            dbManager = new database_1.DatabaseManager({ filename: dbPath });
+            // Verify columns were added
+            const db2 = dbManager.getDatabase();
+            const columns = db2.prepare('PRAGMA table_info(context_items)').all();
+            const columnNames = columns.map((col) => col.name);
+            (0, globals_1.expect)(columnNames).toContain('metadata');
+            (0, globals_1.expect)(columnNames).toContain('size');
+            (0, globals_1.expect)(columnNames).toContain('category');
+            (0, globals_1.expect)(columnNames).toContain('priority');
+            // Note: context_items table only has created_at, not updated_at
+        });
+        (0, globals_1.it)('should handle concurrent database access during migration', () => {
+            // Create a database with old schema
+            const db = new better_sqlite3_1.default(dbPath);
+            db.exec(`
+        CREATE TABLE sessions (
+          id TEXT PRIMARY KEY,
+          name TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+      `);
+            db.close();
+            // Initialize multiple DatabaseManager instances concurrently
+            const managers = [];
+            const promises = [];
+            for (let i = 0; i < 3; i++) {
+                promises.push(new Promise(resolve => {
+                    setTimeout(() => {
+                        const manager = new database_1.DatabaseManager({ filename: dbPath });
+                        managers.push(manager);
+                        resolve(manager);
+                    }, i * 10); // Stagger slightly
+                }));
+            }
+            return Promise.all(promises).then(() => {
+                // All should complete successfully
+                (0, globals_1.expect)(managers.length).toBe(3);
+                // Check that migrations were applied
+                const db = managers[0].getDatabase();
+                const tables = db
+                    .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+                    .all();
+                (0, globals_1.expect)(tables.length).toBeGreaterThan(10); // Should have all tables
+                // Clean up
+                managers.forEach(m => m.close());
+            });
+        });
+    });
+});

package/dist/__tests__/utils/project-directory-messages.test.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const simple_git_1 = require("simple-git");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+describe('Project Directory Messages and User Guidance', () => {
+    describe('Git commit without project directory', () => {
+        it('should generate helpful message for missing project directory', () => {
+            // This is the expected message when no project directory is set
+            const expectedMessage = `⚠️ No project directory set for git tracking!
+
+To track git changes in your project, please set your project directory using one of these methods:
+
+1. When starting a new session:
+   context_session_start with projectDir: "/path/to/your/project"
+
+2. For the current session:
+   context_set_project_dir with projectDir: "/path/to/your/project"
+
+This allows the MCP server to track git changes in your actual project directory.`;
+            // Verify the message format is correct
+            expect(expectedMessage).toContain('⚠️ No project directory set');
+            expect(expectedMessage).toContain('context_session_start with projectDir:');
+            expect(expectedMessage).toContain('context_set_project_dir with projectDir:');
+            expect(expectedMessage).toContain('track git changes in your actual project directory');
+        });
+    });
+    describe('Session start messages', () => {
+        it('should generate tip message when no project directory provided', () => {
+            const tipMessage = 'Tip: To enable git tracking, start with projectDir parameter or use context_set_project_dir';
+            expect(tipMessage).toContain('To enable git tracking');
+            expect(tipMessage).toContain('projectDir parameter');
+            expect(tipMessage).toContain('context_set_project_dir');
+        });
+        it('should include project directory info in session start message', () => {
+            const projectPath = '/Users/test/my-project';
+            const sessionMessage = `Session started: Test Session
+ID: abc-123
+Description: Testing project directory
+Branch: master
+Project directory: ${projectPath}
+Git detected: Yes`;
+            expect(sessionMessage).toContain(`Project directory: ${projectPath}`);
+            expect(sessionMessage).toContain('Git detected: Yes');
+        });
+    });
+    describe('Set project directory messages', () => {
+        it('should show success message with git detection', () => {
+            const projectPath = '/Users/test/my-project';
+            const successMessage = `Project directory set successfully!
+
+Path: ${projectPath}
+Git repository: ✓ Detected
+Current branch: main
+Status: Clean (no uncommitted changes)
+
+You can now use git-related features like context_git_commit.`;
+            expect(successMessage).toContain('Project directory set successfully!');
+            expect(successMessage).toContain(`Path: ${projectPath}`);
+            expect(successMessage).toContain('Git repository: ✓ Detected');
+            expect(successMessage).toContain('Current branch:');
+            expect(successMessage).toContain('context_git_commit');
+        });
+        it('should show message for non-git directory', () => {
+            const projectPath = '/Users/test/non-git-project';
+            const nonGitMessage = `Project directory set successfully!
+
+Path: ${projectPath}
+Git repository: ✗ Not found
+
+Tip: Initialize git with 'git init' to enable git tracking features.`;
+            expect(nonGitMessage).toContain('Project directory set successfully!');
+            expect(nonGitMessage).toContain('Git repository: ✗ Not found');
+            expect(nonGitMessage).toContain("Initialize git with 'git init'");
+        });
+        it('should show error for missing session', () => {
+            const errorMessage = 'No active session. Please start a session first with context_session_start.';
+            expect(errorMessage).toContain('No active session');
+            expect(errorMessage).toContain('context_session_start');
+        });
+    });
+    describe('Git status messages', () => {
+        let tempRepoPath;
+        let git;
+        beforeEach(async () => {
+            tempRepoPath = path.join(os.tmpdir(), `test-git-messages-${Date.now()}`);
+            fs.mkdirSync(tempRepoPath, { recursive: true });
+            git = (0, simple_git_1.simpleGit)(tempRepoPath);
+            await git.init();
+            await git.addConfig('user.name', 'Test User');
+            await git.addConfig('user.email', 'test@example.com');
+        });
+        afterEach(() => {
+            fs.rmSync(tempRepoPath, { recursive: true, force: true });
+        });
+        it('should format clean repository status', async () => {
+            fs.writeFileSync(path.join(tempRepoPath, 'README.md'), '# Test');
+            await git.add('.');
+            await git.commit('Initial commit');
+            const status = await git.status();
+            const statusMessage = `Status: ${status.isClean() ? 'Clean (no uncommitted changes)' : 'Has uncommitted changes'}`;
+            expect(statusMessage).toBe('Status: Clean (no uncommitted changes)');
+        });
+        it('should format dirty repository status', async () => {
+            fs.writeFileSync(path.join(tempRepoPath, 'README.md'), '# Test');
+            await git.add('.');
+            await git.commit('Initial commit');
+            // Make changes
+            fs.writeFileSync(path.join(tempRepoPath, 'new.txt'), 'new content');
+            const status = await git.status();
+            const statusMessage = `Status: ${status.isClean() ? 'Clean (no uncommitted changes)' : 'Has uncommitted changes'}`;
+            expect(statusMessage).toBe('Status: Has uncommitted changes');
+        });
+    });
+    describe('Checkpoint messages with git info', () => {
+        it('should include git info in checkpoint creation message', () => {
+            const checkpointMessage = `Created checkpoint: Feature Save
+ID: checkpoint-123
+Context items: 5
+Cached files: 3
+Git branch: feature/user-auth
+Git status: captured`;
+            expect(checkpointMessage).toContain('Git branch: feature/user-auth');
+            expect(checkpointMessage).toContain('Git status: captured');
+        });
+        it('should show none for git branch when no project directory', () => {
+            const checkpointMessage = `Created checkpoint: Quick Save
+ID: checkpoint-456
+Context items: 2
+Cached files: 0
+Git branch: none
+Git status: not captured`;
+            expect(checkpointMessage).toContain('Git branch: none');
+            expect(checkpointMessage).toContain('Git status: not captured');
+        });
+    });
+    describe('Error handling messages', () => {
+        it('should handle git command failures gracefully', () => {
+            const errorMessage = 'Git commit failed: No changes to commit';
+            expect(errorMessage).toContain('Git commit failed:');
+            expect(errorMessage).toContain('No changes to commit');
+        });
+        it('should handle invalid directory paths', () => {
+            const invalidPathMessage = `Project directory set successfully!
+
+Path: /invalid/path/that/does/not/exist
+Git repository: ✗ Not found
+
+Directory may not exist or may not be accessible.`;
+            expect(invalidPathMessage).toContain('Git repository: ✗ Not found');
+            expect(invalidPathMessage).toContain('Directory may not exist');
+        });
+    });
+});

package/dist/__tests__/utils/timezone-safe-dates.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Timezone-Safe Date Testing Utility
+ *
+ * This utility provides functions for creating timezone-agnostic test dates
+ * that ensure consistent behavior across all environments regardless of system timezone.
+ *
+ * PROBLEM: Tests that use `new Date()` or local timezone methods fail when run in
+ * different timezones (e.g., CI/CD running in UTC vs local development in PST/PDT).
+ *
+ * SOLUTION: Use fixed UTC reference dates and UTC-based date construction to ensure
+ * timeline grouping and date calculations work identically everywhere.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_BASE_DATE = void 0;
+exports.createUTCDate = createUTCDate;
+exports.createUTCDateByHours = createUTCDateByHours;
+exports.createUTCDateByMs = createUTCDateByMs;
+exports.createTimelineTestDates = createTimelineTestDates;
+exports.createDateRange = createDateRange;
+exports.validateTimezoneSafety = validateTimezoneSafety;
+/**
+ * Fixed reference date in UTC for consistent test behavior
+ * This date should be:
+ * - Fixed and not based on current time
+ * - In UTC timezone (ends with 'Z')
+ * - At noon to avoid midnight boundary issues
+ */
+exports.TEST_BASE_DATE = new Date('2025-06-20T12:00:00.000Z');
+/**
+ * Creates a UTC date offset by the specified number of days from the base date
+ * @param daysOffset Number of days to offset (negative for past dates)
+ * @param hour Hour in UTC (default: 12 for noon)
+ * @param minute Minute (default: 0)
+ * @param second Second (default: 0)
+ * @returns Date object in UTC
+ */
+function createUTCDate(daysOffset = 0, hour = 12, minute = 0, second = 0) {
+    return new Date(Date.UTC(exports.TEST_BASE_DATE.getUTCFullYear(), exports.TEST_BASE_DATE.getUTCMonth(), exports.TEST_BASE_DATE.getUTCDate() + daysOffset, hour, minute, second));
+}
+/**
+ * Creates a UTC date offset by the specified number of hours from the base date
+ * @param hoursOffset Number of hours to offset
+ * @returns Date object in UTC
+ */
+function createUTCDateByHours(hoursOffset) {
+    return new Date(exports.TEST_BASE_DATE.getTime() + hoursOffset * 60 * 60 * 1000);
+}
+/**
+ * Creates a UTC date offset by the specified number of milliseconds from the base date
+ * @param msOffset Number of milliseconds to offset
+ * @returns Date object in UTC
+ */
+function createUTCDateByMs(msOffset) {
+    return new Date(exports.TEST_BASE_DATE.getTime() + msOffset);
+}
+/**
+ * Creates a set of test dates for timeline testing
+ * @returns Object with commonly used test dates
+ */
+function createTimelineTestDates() {
+    return {
+        baseDate: exports.TEST_BASE_DATE,
+        today: createUTCDate(0), // 2025-06-20 12:00:00 UTC
+        yesterday: createUTCDate(-1), // 2025-06-19 12:00:00 UTC
+        threeDaysAgo: createUTCDate(-3), // 2025-06-17 12:00:00 UTC
+        fiveDaysAgo: createUTCDate(-5), // 2025-06-15 12:00:00 UTC
+        sevenDaysAgo: createUTCDate(-7), // 2025-06-13 12:00:00 UTC
+        oneWeekAgo: createUTCDate(-7),
+        oneMonthAgo: createUTCDate(-30),
+        oneYearAgo: createUTCDate(-365),
+    };
+}
+/**
+ * Creates a date range for testing
+ * @param startDaysOffset Days offset for start date
+ * @param endDaysOffset Days offset for end date (default: 0 = base date)
+ * @returns Object with start and end dates
+ */
+function createDateRange(startDaysOffset, endDaysOffset = 0) {
+    return {
+        startDate: createUTCDate(startDaysOffset),
+        endDate: createUTCDate(endDaysOffset),
+    };
+}
+/**
+ * Validates that the timezone-safe pattern is working correctly
+ * This function can be used in tests to verify consistent behavior
+ */
+function validateTimezoneSafety() {
+    const testDate = createUTCDate(0);
+    // Should always produce the same UTC string regardless of system timezone
+    const expectedISOString = '2025-06-20T12:00:00.000Z';
+    if (testDate.toISOString() !== expectedISOString) {
+        throw new Error(`Timezone safety validation failed. Expected: ${expectedISOString}, Got: ${testDate.toISOString()}`);
+    }
+    return true;
+}
+/**
+ * Example usage patterns for timezone-safe testing:
+ *
+ * // ✅ CORRECT - Timezone-safe pattern
+ * const { today, yesterday } = createTimelineTestDates();
+ * const items = [
+ *   { time: new Date(today.getTime() + 60 * 60 * 1000), data: 'test' },
+ *   { time: new Date(yesterday.getTime() + 60 * 60 * 1000), data: 'test' }
+ * ];
+ *
+ * // ✅ CORRECT - For date ranges
+ * const { startDate, endDate } = createDateRange(-10, 0);
+ *
+ * // ❌ WRONG - Timezone-dependent pattern
+ * const now = new Date();
+ * const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+ *
+ * // ❌ WRONG - System timezone dependent
+ * const yesterday = new Date();
+ * yesterday.setDate(yesterday.getDate() - 1);
+ */