@doist/todoist-ai 2.0.0 → 2.1.0

package/dist/utils/duration-parser.js

@@ -0,0 +1,96 @@
+/**
+ * Duration parser utility for converting human-readable duration strings
+ * to minutes using a restricted, language-neutral syntax.
+ *
+ * Supported formats:
+ * - "2h" (hours only)
+ * - "90m" (minutes only)
+ * - "2h30m" (hours + minutes)
+ * - "1.5h" (decimal hours)
+ * - Supports optional spaces: "2h 30m"
+ */
+export class DurationParseError extends Error {
+    constructor(input, reason) {
+        super(`Invalid duration format "${input}": ${reason}`);
+        this.name = 'DurationParseError';
+    }
+}
+/**
+ * Parses duration string in restricted syntax to minutes.
+ * Max duration: 1440 minutes (24 hours)
+ *
+ * @param durationStr - Duration string like "2h30m", "45m", "1.5h"
+ * @returns Parsed duration in minutes
+ * @throws DurationParseError for invalid formats
+ */
+export function parseDuration(durationStr) {
+    if (!durationStr || typeof durationStr !== 'string') {
+        throw new DurationParseError(durationStr, 'Duration must be a non-empty string');
+    }
+    // Remove all spaces and convert to lowercase
+    const normalized = durationStr.trim().toLowerCase().replace(/\s+/g, '');
+    // Check for empty string after trimming
+    if (!normalized) {
+        throw new DurationParseError(durationStr, 'Duration must be a non-empty string');
+    }
+    // Validate format with strict ordering: hours must come before minutes
+    // This regex ensures: optional hours followed by optional minutes, no duplicates
+    const match = normalized.match(/^(?:(\d+(?:\.\d+)?)h)?(?:(\d+(?:\.\d+)?)m)?$/);
+    if (!match || (!match[1] && !match[2])) {
+        throw new DurationParseError(durationStr, 'Use format like "2h", "30m", "2h30m", or "1.5h"');
+    }
+    let totalMinutes = 0;
+    const [, hoursStr, minutesStr] = match;
+    // Parse hours if present
+    if (hoursStr) {
+        const hours = Number.parseFloat(hoursStr);
+        if (Number.isNaN(hours) || hours < 0) {
+            throw new DurationParseError(durationStr, 'Hours must be a positive number');
+        }
+        totalMinutes += hours * 60;
+    }
+    // Parse minutes if present
+    if (minutesStr) {
+        const minutes = Number.parseFloat(minutesStr);
+        if (Number.isNaN(minutes) || minutes < 0) {
+            throw new DurationParseError(durationStr, 'Minutes must be a positive number');
+        }
+        // Don't allow decimal minutes
+        if (minutes % 1 !== 0) {
+            throw new DurationParseError(durationStr, 'Minutes must be a whole number (use decimal hours instead)');
+        }
+        totalMinutes += minutes;
+    }
+    // The regex already ensures at least one unit is present
+    // Round to nearest minute (handles decimal hours)
+    totalMinutes = Math.round(totalMinutes);
+    // Validate minimum duration
+    if (totalMinutes === 0) {
+        throw new DurationParseError(durationStr, 'Duration must be greater than 0 minutes');
+    }
+    // Validate maximum duration (24 hours = 1440 minutes)
+    if (totalMinutes > 1440) {
+        throw new DurationParseError(durationStr, 'Duration cannot exceed 24 hours (1440 minutes)');
+    }
+    return { minutes: totalMinutes };
+}
+/**
+ * Formats minutes back to a human-readable duration string.
+ * Used when returning task data to LLMs.
+ *
+ * @param minutes - Duration in minutes
+ * @returns Formatted duration string like "2h30m" or "45m"
+ */
+export function formatDuration(minutes) {
+    if (minutes <= 0)
+        return '0m';
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    if (hours === 0) {
+        return `${remainingMinutes}m`;
+    }
+    if (remainingMinutes === 0) {
+        return `${hours}h`;
+    }
+    return `${hours}h${remainingMinutes}m`;
+}

package/dist/utils/duration-parser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=duration-parser.test.d.ts.map

package/dist/utils/duration-parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration-parser.test.d.ts","sourceRoot":"","sources":["../../src/utils/duration-parser.test.ts"],"names":[],"mappings":""}

package/dist/utils/duration-parser.test.js

@@ -0,0 +1,147 @@
+import { DurationParseError, formatDuration, parseDuration } from './duration-parser.js';
+describe('parseDuration', () => {
+    describe('valid formats', () => {
+        it('should parse hours only', () => {
+            expect(parseDuration('2h')).toEqual({ minutes: 120 });
+            expect(parseDuration('1h')).toEqual({ minutes: 60 });
+            expect(parseDuration('24h')).toEqual({ minutes: 1440 });
+        });
+        it('should parse minutes only', () => {
+            expect(parseDuration('90m')).toEqual({ minutes: 90 });
+            expect(parseDuration('45m')).toEqual({ minutes: 45 });
+            expect(parseDuration('1m')).toEqual({ minutes: 1 });
+            expect(parseDuration('1440m')).toEqual({ minutes: 1440 });
+        });
+        it('should parse hours and minutes combined', () => {
+            expect(parseDuration('2h30m')).toEqual({ minutes: 150 });
+            expect(parseDuration('1h45m')).toEqual({ minutes: 105 });
+            expect(parseDuration('0h30m')).toEqual({ minutes: 30 });
+            expect(parseDuration('23h59m')).toEqual({ minutes: 1439 });
+        });
+        it('should parse decimal hours', () => {
+            expect(parseDuration('1.5h')).toEqual({ minutes: 90 });
+            expect(parseDuration('2.25h')).toEqual({ minutes: 135 });
+            expect(parseDuration('0.5h')).toEqual({ minutes: 30 });
+            expect(parseDuration('0.75h')).toEqual({ minutes: 45 });
+        });
+        it('should handle spaces in input', () => {
+            expect(parseDuration('2h 30m')).toEqual({ minutes: 150 });
+            expect(parseDuration(' 1h45m ')).toEqual({ minutes: 105 });
+            expect(parseDuration('  2h  ')).toEqual({ minutes: 120 });
+            expect(parseDuration(' 90m ')).toEqual({ minutes: 90 });
+        });
+        it('should handle case insensitive input', () => {
+            expect(parseDuration('2H')).toEqual({ minutes: 120 });
+            expect(parseDuration('90M')).toEqual({ minutes: 90 });
+            expect(parseDuration('2H30M')).toEqual({ minutes: 150 });
+            expect(parseDuration('1.5H')).toEqual({ minutes: 90 });
+        });
+        it('should round decimal minutes from decimal hours', () => {
+            expect(parseDuration('1.33h')).toEqual({ minutes: 80 }); // 1.33 * 60 = 79.8 -> 80
+            expect(parseDuration('1.67h')).toEqual({ minutes: 100 }); // 1.67 * 60 = 100.2 -> 100
+        });
+    });
+    describe('invalid formats', () => {
+        it('should throw error for empty or null input', () => {
+            expect(() => parseDuration('')).toThrow(DurationParseError);
+            expect(() => parseDuration('   ')).toThrow('Duration must be a non-empty string');
+            // biome-ignore lint/suspicious/noExplicitAny: Testing error cases with invalid types
+            expect(() => parseDuration(null)).toThrow('Duration must be a non-empty string');
+            // biome-ignore lint/suspicious/noExplicitAny: Testing error cases with invalid types
+            expect(() => parseDuration(undefined)).toThrow('Duration must be a non-empty string');
+        });
+        it('should throw error for invalid format', () => {
+            expect(() => parseDuration('2')).toThrow('Use format like "2h", "30m", "2h30m", or "1.5h"');
+            expect(() => parseDuration('2hours')).toThrow('Use format like');
+            expect(() => parseDuration('2h30')).toThrow('Use format like');
+            expect(() => parseDuration('h30m')).toThrow('Use format like');
+            expect(() => parseDuration('2x30m')).toThrow('Use format like');
+            expect(() => parseDuration('2h30s')).toThrow('Use format like');
+        });
+        it('should throw error for decimal minutes', () => {
+            expect(() => parseDuration('90.5m')).toThrow('Minutes must be a whole number');
+            expect(() => parseDuration('1h30.5m')).toThrow('Minutes must be a whole number');
+        });
+        it('should throw error for negative values', () => {
+            expect(() => parseDuration('-2h')).toThrow('Use format like');
+            expect(() => parseDuration('-30m')).toThrow('Use format like');
+            expect(() => parseDuration('2h-30m')).toThrow('Use format like');
+        });
+        it('should throw error for zero duration', () => {
+            expect(() => parseDuration('0h')).toThrow('Duration must be greater than 0 minutes');
+            expect(() => parseDuration('0m')).toThrow('Duration must be greater than 0 minutes');
+            expect(() => parseDuration('0h0m')).toThrow('Duration must be greater than 0 minutes');
+        });
+        it('should throw error for duration exceeding 24 hours', () => {
+            expect(() => parseDuration('25h')).toThrow('Duration cannot exceed 24 hours (1440 minutes)');
+            expect(() => parseDuration('1441m')).toThrow('Duration cannot exceed 24 hours (1440 minutes)');
+            expect(() => parseDuration('24h1m')).toThrow('Duration cannot exceed 24 hours (1440 minutes)');
+            expect(() => parseDuration('24.1h')).toThrow('Duration cannot exceed 24 hours (1440 minutes)');
+        });
+        it('should throw error for malformed numbers', () => {
+            expect(() => parseDuration('2.h')).toThrow('Use format like');
+            expect(() => parseDuration('2h.m')).toThrow('Use format like');
+            expect(() => parseDuration('2..5h')).toThrow('Use format like');
+        });
+        it('should throw error for duplicate units', () => {
+            expect(() => parseDuration('2h3h')).toThrow('Use format like');
+            expect(() => parseDuration('30m45m')).toThrow('Use format like');
+        });
+        it('should throw error for wrong order (minutes before hours)', () => {
+            expect(() => parseDuration('30m2h')).toThrow('Use format like');
+            expect(() => parseDuration('45m1h')).toThrow('Use format like');
+        });
+        it('should throw error for invalid mixed formats with correct order', () => {
+            expect(() => parseDuration('2h30m15h')).toThrow('Use format like');
+            expect(() => parseDuration('1h2h30m')).toThrow('Use format like');
+        });
+    });
+    describe('edge cases', () => {
+        it('should handle maximum allowed duration', () => {
+            expect(parseDuration('24h')).toEqual({ minutes: 1440 });
+            expect(parseDuration('1440m')).toEqual({ minutes: 1440 });
+            expect(parseDuration('23h60m')).toEqual({ minutes: 1440 });
+        });
+        it('should handle minimum allowed duration', () => {
+            expect(parseDuration('1m')).toEqual({ minutes: 1 });
+            expect(parseDuration('0.017h')).toEqual({ minutes: 1 }); // 0.017 * 60 = 1.02 -> 1
+        });
+    });
+});
+describe('formatDuration', () => {
+    it('should format minutes only', () => {
+        expect(formatDuration(45)).toBe('45m');
+        expect(formatDuration(1)).toBe('1m');
+        expect(formatDuration(59)).toBe('59m');
+    });
+    it('should format hours only', () => {
+        expect(formatDuration(60)).toBe('1h');
+        expect(formatDuration(120)).toBe('2h');
+        expect(formatDuration(1440)).toBe('24h');
+    });
+    it('should format hours and minutes combined', () => {
+        expect(formatDuration(90)).toBe('1h30m');
+        expect(formatDuration(150)).toBe('2h30m');
+        expect(formatDuration(105)).toBe('1h45m');
+        expect(formatDuration(1439)).toBe('23h59m');
+    });
+    it('should handle edge cases', () => {
+        expect(formatDuration(0)).toBe('0m');
+        expect(formatDuration(-5)).toBe('0m');
+    });
+});
+describe('round trip parsing and formatting', () => {
+    const testCases = [
+        { input: '2h', expectedMinutes: 120, expectedFormat: '2h' },
+        { input: '45m', expectedMinutes: 45, expectedFormat: '45m' },
+        { input: '2h30m', expectedMinutes: 150, expectedFormat: '2h30m' },
+        { input: '1.5h', expectedMinutes: 90, expectedFormat: '1h30m' },
+    ];
+    for (const { input, expectedMinutes, expectedFormat } of testCases) {
+        it(`should parse "${input}" and format back consistently`, () => {
+            const parsed = parseDuration(input);
+            expect(parsed.minutes).toBe(expectedMinutes);
+            expect(formatDuration(parsed.minutes)).toBe(expectedFormat);
+        });
+    }
+});

package/package.json

@@ -1,10 +1,12 @@
 {
     "name": "@doist/todoist-ai",
-    "version": "2.0.0",
+    "version": "2.1.0",
+    "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "files": [
         "dist",
+        "scripts",
         "package.json",
         "LICENSE.txt",
         "README.md"
@@ -23,8 +25,10 @@
     "scripts": {
         "test": "jest",
         "build": "rimraf dist && npx tsc --project tsconfig.json",
-        "dev": "concurrently \"npx tsc --watch\" \"nodemon --watch dist --ext js --exec 'npx -y @modelcontextprotocol/inspector npx node dist/main.js\"",
+        "start": "npm run build && npx @modelcontextprotocol/inspector node dist/main.js",
+        "dev": "concurrently \"npx tsc --watch\" \"nodemon --watch dist --ext js --exec 'npx @modelcontextprotocol/inspector node dist/main.js'\"",
         "setup": "cp .env.example .env && npm install && npm run build",
+        "test:executable": "npm run build && node scripts/test-executable.cjs",
         "type-check": "npx tsc --noEmit",
         "biome:sort-imports": "biome check --formatter-enabled=false --linter-enabled=false --organize-imports-enabled=true --write .",
         "lint:check": "biome lint",

package/scripts/test-executable.cjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+const { spawn } = require('node:child_process')
+const path = require('node:path')
+
+console.log('Testing MCP server executable...')
+
+const mainJs = path.join(__dirname, '..', 'dist', 'main.js')
+const child = spawn('node', [mainJs], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+})
+
+let _stdoutOutput = ''
+let stderrOutput = ''
+let hasError = false
+
+child.stdout.on('data', (data) => {
+    _stdoutOutput += data.toString()
+})
+
+child.stderr.on('data', (data) => {
+    const output = data.toString()
+    stderrOutput += output
+
+    // Only consider it an error if it's not related to graceful shutdown
+    if (output.includes('Error:') && !output.includes('SIGTERM') && !output.includes('SIGKILL')) {
+        console.error('Server startup error detected:', output)
+        hasError = true
+    }
+})
+
+child.on('error', (error) => {
+    console.error('Failed to start MCP server:', error.message)
+    hasError = true
+    process.exit(1)
+})
+
+child.on('exit', (code, signal) => {
+    // Expected signals when we kill the process
+    if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+        return // This is expected
+    }
+
+    // Unexpected exit codes during startup
+    if (code !== null && code !== 0) {
+        console.error(`Server exited unexpectedly with code ${code}`)
+        hasError = true
+    }
+})
+
+// Kill the process after 2 seconds (MCP server should start successfully)
+setTimeout(() => {
+    if (hasError) {
+        console.error('❌ MCP server failed to start properly')
+        if (stderrOutput.trim()) {
+            console.error('Error output:', stderrOutput.trim())
+        }
+        process.exit(1)
+    }
+
+    // Gracefully terminate
+    child.kill('SIGTERM')
+
+    setTimeout(() => {
+        console.log('✅ MCP server executable test passed')
+        console.log('Server started successfully and is ready to accept connections')
+        process.exit(0)
+    }, 200) // Give it a moment to clean up
+}, 2000)