jm2 0.1.0

package/src/ipc/protocol.js

@@ -0,0 +1,183 @@
+/**
+ * IPC protocol definitions for JM2
+ */
+
+export const MessageType = {
+  // Basic
+  PING: 'ping',
+  PONG: 'pong',
+  ERROR: 'error',
+  
+  // Job management
+  JOB_ADD: 'job:add',
+  JOB_ADDED: 'job:added',
+  JOB_LIST: 'job:list',
+  JOB_LIST_RESULT: 'job:list:result',
+  JOB_GET: 'job:get',
+  JOB_GET_RESULT: 'job:get:result',
+  JOB_REMOVE: 'job:remove',
+  JOB_REMOVED: 'job:removed',
+  JOB_UPDATE: 'job:update',
+  JOB_UPDATED: 'job:updated',
+  JOB_PAUSE: 'job:pause',
+  JOB_PAUSED: 'job:paused',
+  JOB_RESUME: 'job:resume',
+  JOB_RESUMED: 'job:resumed',
+  JOB_RUN: 'job:run',
+  JOB_RUN_RESULT: 'job:run:result',
+
+  // Flush/cleanup
+  FLUSH: 'flush',
+  FLUSH_RESULT: 'flush:result',
+
+  // Import/reload
+  RELOAD_JOBS: 'jobs:reload',
+  RELOAD_JOBS_RESULT: 'jobs:reload:result',
+};
+
+/**
+ * Create a job add response
+ * @param {object} job - Added job
+ * @returns {{ type: string, job: object }}
+ */
+export function createJobAddedResponse(job) {
+  return {
+    type: MessageType.JOB_ADDED,
+    job,
+  };
+}
+
+/**
+ * Create a job list response
+ * @param {Array} jobs - List of jobs
+ * @returns {{ type: string, jobs: Array }}
+ */
+export function createJobListResponse(jobs) {
+  return {
+    type: MessageType.JOB_LIST_RESULT,
+    jobs,
+  };
+}
+
+/**
+ * Create a job get response
+ * @param {object|null} job - Job or null if not found
+ * @returns {{ type: string, job: object|null }}
+ */
+export function createJobGetResponse(job) {
+  return {
+    type: MessageType.JOB_GET_RESULT,
+    job,
+  };
+}
+
+/**
+ * Create a job removed response
+ * @param {boolean} success - Whether removal was successful
+ * @returns {{ type: string, success: boolean }}
+ */
+export function createJobRemovedResponse(success) {
+  return {
+    type: MessageType.JOB_REMOVED,
+    success,
+  };
+}
+
+/**
+ * Create a job updated response
+ * @param {object|null} job - Updated job or null if not found
+ * @returns {{ type: string, job: object|null }}
+ */
+export function createJobUpdatedResponse(job) {
+  return {
+    type: MessageType.JOB_UPDATED,
+    job,
+  };
+}
+
+/**
+ * Create a job paused response
+ * @param {object|null} job - Paused job or null if not found
+ * @returns {{ type: string, job: object|null }}
+ */
+export function createJobPausedResponse(job) {
+  return {
+    type: MessageType.JOB_PAUSED,
+    job,
+  };
+}
+
+/**
+ * Create a job resumed response
+ * @param {object|null} job - Resumed job or null if not found
+ * @returns {{ type: string, job: object|null }}
+ */
+export function createJobResumedResponse(job) {
+  return {
+    type: MessageType.JOB_RESUMED,
+    job,
+  };
+}
+
+/**
+ * Create a job run response
+ * @param {object} result - Run result
+ * @returns {{ type: string, result: object }}
+ */
+export function createJobRunResponse(result) {
+  return {
+    type: MessageType.JOB_RUN_RESULT,
+    result,
+  };
+}
+
+/**
+ * Create a flush result response
+ * @param {object} result - Flush result with jobsRemoved, logsRemoved, historyRemoved
+ * @returns {{ type: string, jobsRemoved: number, logsRemoved: number, historyRemoved: number }}
+ */
+export function createFlushResultResponse(result) {
+  return {
+    type: MessageType.FLUSH_RESULT,
+    jobsRemoved: result.jobsRemoved || 0,
+    logsRemoved: result.logsRemoved || 0,
+    historyRemoved: result.historyRemoved || 0,
+  };
+}
+
+/**
+ * Create a standard error response
+ * @param {string} message - Error message
+ * @returns {{ type: string, message: string }}
+ */
+export function createErrorResponse(message) {
+  return {
+    type: MessageType.ERROR,
+    message,
+  };
+}
+
+/**
+ * Create a pong response
+ * @returns {{ type: string }}
+ */
+export function createPongResponse() {
+  return {
+    type: MessageType.PONG,
+  };
+}
+
+export default {
+  MessageType,
+  createErrorResponse,
+  createPongResponse,
+  createJobAddedResponse,
+  createJobListResponse,
+  createJobGetResponse,
+  createJobRemovedResponse,
+  createJobUpdatedResponse,
+  createJobPausedResponse,
+  createJobResumedResponse,
+  createJobRunResponse,
+  createFlushResultResponse,
+};

package/src/ipc/server.js

@@ -0,0 +1,92 @@
+/**
+ * IPC server for JM2 daemon
+ */
+
+import { createServer } from 'node:net';
+import { unlinkSync, existsSync } from 'node:fs';
+import { getSocketPath, ensureDataDir } from '../utils/paths.js';
+import { MessageType, createErrorResponse, createPongResponse } from './protocol.js';
+
+/**
+ * Start IPC server
+ * @param {object} options - Server options
+ * @param {function} options.onMessage - Handler for incoming messages
+ * @returns {import('node:net').Server}
+ */
+export function startIpcServer(options = {}) {
+  const { onMessage } = options;
+  const socketPath = getSocketPath();
+
+  if (process.platform !== 'win32' && existsSync(socketPath)) {
+    unlinkSync(socketPath);
+  }
+
+  ensureDataDir();
+
+  const server = createServer(socket => {
+    let buffer = '';
+
+    socket.on('data', data => {
+      buffer += data.toString();
+      let index;
+      while ((index = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) {
+          continue;
+        }
+
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch (error) {
+          socket.write(JSON.stringify(createErrorResponse('Invalid JSON')) + '\n');
+          continue;
+        }
+
+        if (!message?.type) {
+          socket.write(JSON.stringify(createErrorResponse('Missing message type')) + '\n');
+          continue;
+        }
+
+        if (message.type === MessageType.PING) {
+          socket.write(JSON.stringify(createPongResponse()) + '\n');
+          continue;
+        }
+
+        if (onMessage) {
+          Promise.resolve(onMessage(message))
+            .then(response => {
+              if (response) {
+                socket.write(JSON.stringify(response) + '\n');
+              }
+            })
+            .catch(err => {
+              socket.write(JSON.stringify(createErrorResponse(err.message)) + '\n');
+            });
+        } else {
+          socket.write(JSON.stringify(createErrorResponse('No handler configured')) + '\n');
+        }
+      }
+    });
+  });
+
+  server.listen(socketPath);
+  return server;
+}
+
+/**
+ * Stop IPC server
+ * @param {import('node:net').Server} server - IPC server instance
+ */
+export function stopIpcServer(server) {
+  if (!server) {
+    return;
+  }
+  server.close();
+}
+
+export default {
+  startIpcServer,
+  stopIpcServer,
+};

package/src/utils/cron.js

@@ -0,0 +1,205 @@
+/**
+ * Cron expression utilities for JM2
+ * Uses cron-parser library for parsing and calculating next run times
+ */
+
+import { CronExpressionParser } from 'cron-parser';
+
+/**
+ * Default options for cron parsing with UTC
+ */
+const DEFAULT_OPTIONS = {
+  utc: true,
+};
+
+/**
+ * Validate a cron expression
+ * @param {string} expression - Cron expression to validate
+ * @returns {{ valid: boolean, error?: string }} Validation result
+ */
+export function validateCronExpression(expression) {
+  if (!expression || typeof expression !== 'string') {
+    return { valid: false, error: 'Cron expression must be a non-empty string' };
+  }
+
+  const trimmed = expression.trim();
+  if (trimmed === '') {
+    return { valid: false, error: 'Cron expression cannot be empty' };
+  }
+
+  try {
+    CronExpressionParser.parse(trimmed, DEFAULT_OPTIONS);
+    return { valid: true };
+  } catch (error) {
+    return { valid: false, error: error.message };
+  }
+}
+
+/**
+ * Get the next run time for a cron expression
+ * @param {string} expression - Cron expression
+ * @param {Date} [fromDate] - Date to calculate from (default: now)
+ * @returns {Date|null} Next run time or null if invalid
+ */
+export function getNextRunTime(expression, fromDate = new Date()) {
+  try {
+    const interval = CronExpressionParser.parse(expression.trim(), {
+      ...DEFAULT_OPTIONS,
+      currentDate: fromDate,
+    });
+    return interval.next().toDate();
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Get multiple upcoming run times for a cron expression
+ * @param {string} expression - Cron expression
+ * @param {number} count - Number of run times to get (default: 5)
+ * @param {Date} [fromDate] - Date to calculate from (default: now)
+ * @returns {Date[]} Array of upcoming run times
+ */
+export function getUpcomingRunTimes(expression, count = 5, fromDate = new Date()) {
+  try {
+    const interval = CronExpressionParser.parse(expression.trim(), {
+      ...DEFAULT_OPTIONS,
+      currentDate: fromDate,
+    });
+
+    const times = [];
+    for (let i = 0; i < count; i++) {
+      times.push(interval.next().toDate());
+    }
+    return times;
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Check if a cron expression has a valid format
+ * @param {string} expression - Cron expression to check
+ * @returns {boolean} True if valid
+ */
+export function isValidCronExpression(expression) {
+  return validateCronExpression(expression).valid;
+}
+
+/**
+ * Get a human-readable description of a cron expression
+ * @param {string} expression - Cron expression
+ * @returns {string} Human-readable description or error message
+ */
+export function describeCronExpression(expression) {
+  const validation = validateCronExpression(expression);
+  if (!validation.valid) {
+    return `Invalid cron: ${validation.error}`;
+  }
+
+  try {
+    const interval = CronExpressionParser.parse(expression.trim(), DEFAULT_OPTIONS);
+    const fields = interval.fields;
+
+    // Build a simple description using the cron string itself
+    // and getting a sample next run time
+    const nextRun = interval.next().toDate();
+    const timeStr = nextRun.toISOString().slice(11, 16); // HH:MM
+    const dateStr = nextRun.toISOString().slice(0, 10); // YYYY-MM-DD
+
+    // Simple description based on the pattern
+    const parts = [];
+
+    // Check for common patterns
+    if (expression === '* * * * *') {
+      return 'Every minute';
+    }
+    if (expression === '0 * * * *') {
+      return 'Every hour at minute 0';
+    }
+    if (expression === '0 0 * * *') {
+      return 'Daily at midnight (00:00)';
+    }
+    if (expression === '0 0 * * 0') {
+      return 'Weekly on Sunday at midnight';
+    }
+    if (expression === '0 0 1 * *') {
+      return 'Monthly on the 1st at midnight';
+    }
+
+    // Generic description with next occurrence
+    return `Cron: ${expression.trim()} (next: ${dateStr} ${timeStr} UTC)`;
+  } catch (error) {
+    return `Invalid cron expression`;
+  }
+}
+
+/**
+ * Parse a cron expression and return the interval object
+ * @param {string} expression - Cron expression
+ * @param {Date} [fromDate] - Date to calculate from
+ * @returns {CronExpression|null} CronExpression object or null if invalid
+ */
+export function parseCronExpression(expression, fromDate = new Date()) {
+  try {
+    return CronExpressionParser.parse(expression.trim(), {
+      ...DEFAULT_OPTIONS,
+      currentDate: fromDate,
+    });
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if a job should run at a specific time
+ * @param {string} expression - Cron expression
+ * @param {Date} checkTime - Time to check
+ * @returns {boolean} True if job should run at checkTime
+ */
+export function shouldRunAt(expression, checkTime = new Date()) {
+  try {
+    const interval = CronExpressionParser.parse(expression.trim(), {
+      ...DEFAULT_OPTIONS,
+      currentDate: new Date(checkTime.getTime() - 60000), // 1 minute before
+    });
+    const nextRun = interval.next().toDate();
+
+    // Check if the next run is within the same minute as checkTime
+    const nextMinute = Math.floor(nextRun.getTime() / 60000);
+    const checkMinute = Math.floor(checkTime.getTime() / 60000);
+
+    return nextMinute === checkMinute;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Common cron expression presets
+ */
+export const CronPresets = {
+  EVERY_MINUTE: '* * * * *',
+  EVERY_5_MINUTES: '*/5 * * * *',
+  EVERY_15_MINUTES: '*/15 * * * *',
+  EVERY_30_MINUTES: '*/30 * * * *',
+  HOURLY: '0 * * * *',
+  EVERY_2_HOURS: '0 */2 * * *',
+  DAILY: '0 0 * * *',
+  WEEKLY: '0 0 * * 0',
+  MONTHLY: '0 0 1 * *',
+  YEARLY: '0 0 1 1 *',
+  WEEKDAYS: '0 0 * * 1-5',
+  WEEKENDS: '0 0 * * 0,6',
+};
+
+export default {
+  validateCronExpression,
+  getNextRunTime,
+  getUpcomingRunTimes,
+  isValidCronExpression,
+  describeCronExpression,
+  parseCronExpression,
+  shouldRunAt,
+  CronPresets,
+};

package/src/utils/datetime.js

@@ -0,0 +1,237 @@
+/**
+ * Datetime parsing utilities for JM2
+ * Handles parsing --at datetime strings and --in duration to datetime conversion
+ */
+
+import { parseDuration } from './duration.js';
+
+/**
+ * Parse a datetime string into a Date object
+ * Supports various formats including ISO 8601, and human-readable formats
+ * 
+ * @param {string} datetimeStr - Datetime string to parse
+ * @returns {Date} Parsed Date object
+ * @throws {Error} If the datetime string is invalid
+ * 
+ * @example
+ * parseDateTime('2026-01-31T10:00:00Z')    // ISO 8601
+ * parseDateTime('2026-01-31 10:00:00')     // Date and time
+ * parseDateTime('2026-01-31')              // Date only (time set to 00:00:00)
+ * parseDateTime('today 10:00')             // Today at specific time
+ * parseDateTime('tomorrow 14:30')          // Tomorrow at specific time
+ */
+export function parseDateTime(datetimeStr) {
+  if (typeof datetimeStr !== 'string') {
+    throw new Error('Datetime must be a string');
+  }
+
+  const trimmed = datetimeStr.trim();
+  
+  if (trimmed === '') {
+    throw new Error('Datetime cannot be empty');
+  }
+
+  const lower = trimmed.toLowerCase();
+  const now = new Date();
+
+  // Handle special keywords
+  if (lower === 'now') {
+    return new Date();
+  }
+
+  // Handle "today" and "tomorrow" with time
+  const todayTomorrowMatch = lower.match(/^(today|tomorrow)(?:\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?$/);
+  if (todayTomorrowMatch) {
+    const day = todayTomorrowMatch[1];
+    const hours = parseInt(todayTomorrowMatch[2] || '0', 10);
+    const minutes = parseInt(todayTomorrowMatch[3] || '0', 10);
+    const seconds = parseInt(todayTomorrowMatch[4] || '0', 10);
+
+    if (hours > 23 || minutes > 59 || seconds > 59) {
+      throw new Error(`Invalid time in datetime: "${datetimeStr}"`);
+    }
+
+    const date = new Date(now);
+    if (day === 'tomorrow') {
+      date.setDate(date.getDate() + 1);
+    }
+    date.setHours(hours, minutes, seconds, 0);
+    return date;
+  }
+
+  // Try parsing as ISO 8601 or standard Date format
+  const date = new Date(trimmed);
+  
+  if (!isNaN(date.getTime())) {
+    // Valid date parsed
+    return date;
+  }
+
+  throw new Error(
+    `Invalid datetime format: "${datetimeStr}". ` +
+    `Supported formats: ISO 8601 (2026-01-31T10:00:00Z), ` +
+    `date and time (2026-01-31 10:00:00), date only (2026-01-31), ` +
+    `today/tomorrow with time (today 10:00, tomorrow 14:30), or "now"`
+  );
+}
+
+/**
+ * Calculate a future datetime by adding a duration to now
+ * Used for --in option (e.g., --in 1h30m)
+ * 
+ * @param {string} durationStr - Duration string (e.g., "30s", "5m", "2h", "1d", "1h30m")
+ * @param {Date} [fromDate] - Starting date (default: now)
+ * @returns {Date} Future datetime
+ * @throws {Error} If the duration string is invalid
+ * 
+ * @example
+ * parseRunIn('1h30m')   // Returns Date for 1 hour 30 minutes from now
+ * parseRunIn('1d')      // Returns Date for 1 day from now
+ * parseRunIn('30m')     // Returns Date for 30 minutes from now
+ */
+export function parseRunIn(durationStr, fromDate = new Date()) {
+  if (typeof durationStr !== 'string') {
+    throw new Error('Duration must be a string');
+  }
+
+  const trimmed = durationStr.trim();
+  
+  if (trimmed === '') {
+    throw new Error('Duration cannot be empty');
+  }
+
+  // Parse the duration to get milliseconds
+  const durationMs = parseDuration(trimmed);
+  
+  // Calculate future datetime
+  return new Date(fromDate.getTime() + durationMs);
+}
+
+/**
+ * Convert a datetime option (either --at or --in) to an ISO datetime string
+ * This is the main entry point for job creation
+ * 
+ * @param {object} options - Options object with either 'at' or 'in' property
+ * @param {string} [options.at] - Datetime string for --at option
+ * @param {string} [options.in] - Duration string for --in option
+ * @returns {string} ISO 8601 datetime string
+ * @throws {Error} If neither or both options are provided, or if parsing fails
+ * 
+ * @example
+ * parseRunAtOption({ at: '2026-01-31T10:00:00Z' })  // Returns ISO string
+ * parseRunAtOption({ in: '1h30m' })                 // Returns ISO string for 1h30m from now
+ */
+export function parseRunAtOption(options) {
+  if (!options || typeof options !== 'object') {
+    throw new Error('Options must be an object');
+  }
+
+  const hasAt = options.at !== undefined && options.at !== null && options.at !== '';
+  const hasIn = options.in !== undefined && options.in !== null && options.in !== '';
+
+  if (!hasAt && !hasIn) {
+    throw new Error('Either "at" or "in" option must be provided');
+  }
+
+  if (hasAt && hasIn) {
+    throw new Error('Cannot specify both "at" and "in" options');
+  }
+
+  if (hasIn) {
+    const date = parseRunIn(options.in);
+    return date.toISOString();
+  }
+
+  if (hasAt) {
+    const date = parseDateTime(options.at);
+    return date.toISOString();
+  }
+
+  throw new Error('Unexpected error parsing datetime option');
+}
+
+/**
+ * Check if a datetime has passed (is in the past)
+ * 
+ * @param {Date|string} date - Date to check
+ * @param {Date} [referenceDate] - Reference date (default: now)
+ * @returns {boolean} True if the date is in the past
+ */
+export function isDateTimePast(date, referenceDate = new Date()) {
+  const checkDate = date instanceof Date ? date : new Date(date);
+  
+  if (isNaN(checkDate.getTime())) {
+    throw new Error('Invalid date provided');
+  }
+  
+  return checkDate.getTime() < referenceDate.getTime();
+}
+
+/**
+ * Format a date for display in CLI output
+ * 
+ * @param {Date|string} date - Date to format
+ * @returns {string} Formatted date string
+ */
+export function formatDateTime(date) {
+  const d = date instanceof Date ? date : new Date(date);
+  
+  if (isNaN(d.getTime())) {
+    return 'Invalid date';
+  }
+  
+  return d.toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+}
+
+/**
+ * Get relative time description (e.g., "in 5 minutes", "2 hours ago")
+ * 
+ * @param {Date|string} date - Date to describe
+ * @param {Date} [referenceDate] - Reference date (default: now)
+ * @returns {string} Relative time description
+ */
+export function getRelativeTimeDescription(date, referenceDate = new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  
+  if (isNaN(d.getTime())) {
+    return 'Invalid date';
+  }
+  
+  const diffMs = d.getTime() - referenceDate.getTime();
+  const diffSec = Math.round(diffMs / 1000);
+  const diffMin = Math.round(diffSec / 60);
+  const diffHour = Math.round(diffMin / 60);
+  const diffDay = Math.round(diffHour / 24);
+  
+  if (Math.abs(diffSec) < 60) {
+    return diffSec >= 0 ? 'in a few seconds' : 'just now';
+  }
+  
+  if (Math.abs(diffMin) < 60) {
+    return diffMin >= 0 
+      ? `in ${diffMin} minute${diffMin !== 1 ? 's' : ''}`
+      : `${Math.abs(diffMin)} minute${Math.abs(diffMin) !== 1 ? 's' : ''} ago`;
+  }
+  
+  if (Math.abs(diffHour) < 24) {
+    return diffHour >= 0
+      ? `in ${diffHour} hour${diffHour !== 1 ? 's' : ''}`
+      : `${Math.abs(diffHour)} hour${Math.abs(diffHour) !== 1 ? 's' : ''} ago`;
+  }
+  
+  if (Math.abs(diffDay) < 30) {
+    return diffDay >= 0
+      ? `in ${diffDay} day${diffDay !== 1 ? 's' : ''}`
+      : `${Math.abs(diffDay)} day${Math.abs(diffDay) !== 1 ? 's' : ''} ago`;
+  }
+  
+  return formatDateTime(d);
+}