lsh-framework 0.5.4

package/dist/lib/base-command-registrar.js

@@ -0,0 +1,286 @@
+/**
+ * Base Command Registrar
+ *
+ * Abstract base class for command registration to eliminate duplication in:
+ * - Command setup patterns
+ * - Error handling
+ * - Daemon client management
+ * - Output formatting
+ *
+ * Usage:
+ * ```typescript
+ * class MyCommandRegistrar extends BaseCommandRegistrar {
+ *   constructor() {
+ *     super('MyService');
+ *   }
+ *
+ *   async register(program: Command): Promise<void> {
+ *     const cmd = this.createCommand(program, 'mycommand', 'My command description');
+ *
+ *     this.addSubcommand(cmd, {
+ *       name: 'list',
+ *       description: 'List items',
+ *       action: async () => {
+ *         await this.withDaemonAction(async (client) => {
+ *           const items = await client.listItems();
+ *           this.logSuccess('Items:', items);
+ *         });
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+import CronJobManager from './cron-job-manager.js';
+import { createLogger } from './logger.js';
+import { withDaemonClient, withDaemonClientForUser, isDaemonRunning } from './daemon-client-helper.js';
+/**
+ * Base class for command registrars
+ */
+export class BaseCommandRegistrar {
+    logger;
+    serviceName;
+    constructor(serviceName) {
+        this.serviceName = serviceName;
+        this.logger = createLogger(serviceName);
+    }
+    /**
+     * Create a top-level command
+     */
+    createCommand(program, name, description) {
+        return program
+            .command(name)
+            .description(description);
+    }
+    /**
+     * Add a subcommand with automatic error handling
+     */
+    addSubcommand(parent, config) {
+        let cmd = parent.command(config.name).description(config.description);
+        // Add arguments
+        if (config.arguments) {
+            config.arguments.forEach(arg => {
+                const argStr = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+                if (arg.description) {
+                    cmd = cmd.argument(argStr, arg.description);
+                }
+                else {
+                    cmd = cmd.argument(argStr);
+                }
+            });
+        }
+        // Add options
+        if (config.options) {
+            config.options.forEach(opt => {
+                if (opt.defaultValue !== undefined) {
+                    cmd = cmd.option(opt.flags, opt.description, opt.defaultValue);
+                }
+                else {
+                    cmd = cmd.option(opt.flags, opt.description);
+                }
+            });
+        }
+        // Wrap action with error handling
+        cmd.action(async (...args) => {
+            try {
+                await config.action(...args);
+            }
+            catch (error) {
+                this.logError('Command failed', error);
+                process.exit(1);
+            }
+        });
+        return cmd;
+    }
+    /**
+     * Execute an action with daemon client
+     */
+    async withDaemonAction(action, config = {}) {
+        const { requireRunning = true, exitOnError = true, forUser = false } = config;
+        const helper = forUser ? withDaemonClientForUser : withDaemonClient;
+        return await helper(action, { requireRunning, exitOnError });
+    }
+    /**
+     * Execute an action with CronJobManager
+     */
+    async withCronManager(action, config = {}) {
+        const { requireRunning = true } = config;
+        const manager = new CronJobManager();
+        if (requireRunning && !manager.isDaemonRunning()) {
+            this.logError('Daemon is not running. Start it with: lsh daemon start');
+            process.exit(1);
+        }
+        try {
+            await manager.connect();
+            const result = await action(manager);
+            manager.disconnect();
+            return result;
+        }
+        catch (error) {
+            manager.disconnect();
+            throw error;
+        }
+    }
+    /**
+     * Check if daemon is running
+     */
+    isDaemonRunning() {
+        return isDaemonRunning();
+    }
+    /**
+     * Log success message
+     */
+    logSuccess(message, data) {
+        this.logger.info(message);
+        if (data !== undefined) {
+            if (typeof data === 'object' && !Array.isArray(data)) {
+                Object.entries(data).forEach(([key, value]) => {
+                    this.logger.info(`  ${key}: ${value}`);
+                });
+            }
+            else if (Array.isArray(data)) {
+                data.forEach(item => {
+                    if (typeof item === 'object') {
+                        this.logger.info(`  ${JSON.stringify(item, null, 2)}`);
+                    }
+                    else {
+                        this.logger.info(`  ${item}`);
+                    }
+                });
+            }
+            else {
+                this.logger.info(`  ${data}`);
+            }
+        }
+    }
+    /**
+     * Log error message
+     */
+    logError(message, error) {
+        if (error instanceof Error) {
+            this.logger.error(message, error);
+        }
+        else if (error) {
+            this.logger.error(`${message}: ${error}`);
+        }
+        else {
+            this.logger.error(message);
+        }
+    }
+    /**
+     * Log info message
+     */
+    logInfo(message) {
+        this.logger.info(message);
+    }
+    /**
+     * Log warning message
+     */
+    logWarning(message) {
+        this.logger.warn(message);
+    }
+    /**
+     * Parse JSON from string with error handling
+     */
+    parseJSON(jsonString, context = 'JSON') {
+        try {
+            return JSON.parse(jsonString);
+        }
+        catch (error) {
+            throw new Error(`Invalid ${context}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Parse comma-separated tags
+     */
+    parseTags(tagsString) {
+        return tagsString.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    }
+    /**
+     * Format job schedule for display
+     */
+    formatSchedule(schedule) {
+        if (schedule?.cron) {
+            return schedule.cron;
+        }
+        if (schedule?.interval) {
+            return `${schedule.interval}ms interval`;
+        }
+        return 'No schedule';
+    }
+    /**
+     * Validate required options
+     */
+    validateRequired(options, required, commandName = 'command') {
+        const missing = required.filter(key => !options[key]);
+        if (missing.length > 0) {
+            throw new Error(`Missing required options for ${commandName}: ${missing.map(k => `--${k}`).join(', ')}`);
+        }
+    }
+    /**
+     * Create a standardized job specification from options
+     */
+    createJobSpec(options) {
+        return {
+            id: options.id || `job_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            name: options.name,
+            description: options.description,
+            command: options.command,
+            schedule: {
+                cron: options.schedule,
+                interval: options.interval ? parseInt(options.interval) : undefined,
+            },
+            workingDirectory: options.workingDir,
+            environment: options.env ? this.parseJSON(options.env, 'environment variables') : {},
+            tags: options.tags ? this.parseTags(options.tags) : [],
+            priority: options.priority ? parseInt(options.priority) : 5,
+            maxRetries: options.maxRetries ? parseInt(options.maxRetries) : 3,
+            timeout: options.timeout ? parseInt(options.timeout) : 0,
+            databaseSync: options.databaseSync !== false,
+        };
+    }
+    /**
+     * Display job information
+     */
+    displayJob(job) {
+        this.logInfo(`  ${job.id}: ${job.name}`);
+        this.logInfo(`    Command: ${job.command}`);
+        this.logInfo(`    Schedule: ${this.formatSchedule(job.schedule)}`);
+        this.logInfo(`    Status: ${job.status}`);
+        this.logInfo(`    Priority: ${job.priority}`);
+        if (job.tags && job.tags.length > 0) {
+            this.logInfo(`    Tags: ${job.tags.join(', ')}`);
+        }
+    }
+    /**
+     * Display multiple jobs
+     */
+    displayJobs(jobs) {
+        this.logInfo(`Jobs (${jobs.length} total):`);
+        jobs.forEach(job => {
+            this.displayJob(job);
+            this.logInfo('');
+        });
+    }
+    /**
+     * Display job report
+     */
+    displayJobReport(report) {
+        this.logInfo(`Job Report: ${report.jobId || 'N/A'}`);
+        this.logInfo(`  Executions: ${report.executions}`);
+        this.logInfo(`  Successes: ${report.successes}`);
+        this.logInfo(`  Failures: ${report.failures}`);
+        this.logInfo(`  Success Rate: ${report.successRate.toFixed(1)}%`);
+        this.logInfo(`  Average Duration: ${Math.round(report.averageDuration)}ms`);
+        this.logInfo(`  Last Execution: ${report.lastExecution?.toISOString() || 'Never'}`);
+        this.logInfo(`  Last Success: ${report.lastSuccess?.toISOString() || 'Never'}`);
+        this.logInfo(`  Last Failure: ${report.lastFailure?.toISOString() || 'Never'}`);
+        if (report.commonErrors && report.commonErrors.length > 0) {
+            this.logInfo('\n  Common Errors:');
+            report.commonErrors.forEach((error) => {
+                this.logInfo(`    - ${error.error} (${error.count} times)`);
+            });
+        }
+    }
+}
+export default BaseCommandRegistrar;

package/dist/lib/base-job-manager.js

@@ -0,0 +1,293 @@
+/**
+ * Base Job Manager
+ * Abstract base class for all job management systems to eliminate duplication in:
+ * - Job lifecycle management (create, start, stop, pause, resume, remove)
+ * - Job status tracking and updates
+ * - Event emission and handling
+ * - Statistics and reporting
+ * - Storage abstraction
+ *
+ * Subclasses implement storage-specific operations (memory, database, filesystem)
+ */
+import { EventEmitter } from 'events';
+import { createLogger } from './logger.js';
+/**
+ * Abstract base class for job managers
+ */
+export class BaseJobManager extends EventEmitter {
+    logger;
+    storage;
+    jobs = new Map();
+    constructor(storage, loggerName = 'JobManager') {
+        super();
+        this.storage = storage;
+        this.logger = createLogger(loggerName);
+    }
+    /**
+     * Generate unique job ID
+     */
+    generateJobId(prefix = 'job') {
+        return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Validate job specification
+     */
+    validateJobSpec(spec) {
+        if (!spec.name) {
+            throw new Error('Job name is required');
+        }
+        if (!spec.command) {
+            throw new Error('Job command is required');
+        }
+    }
+    /**
+     * Create a new job
+     */
+    async createJob(spec) {
+        this.validateJobSpec(spec);
+        const job = {
+            id: spec.id || this.generateJobId(),
+            name: spec.name,
+            command: spec.command,
+            args: spec.args,
+            status: 'created',
+            createdAt: new Date(),
+            env: spec.env,
+            cwd: spec.cwd || process.cwd(),
+            user: spec.user || process.env.USER,
+            schedule: spec.schedule,
+            tags: spec.tags || [],
+            description: spec.description,
+            priority: spec.priority ?? 5,
+            timeout: spec.timeout,
+            maxRetries: spec.maxRetries ?? 3,
+            retryCount: 0,
+            databaseSync: spec.databaseSync !== false,
+        };
+        await this.storage.save(job);
+        this.jobs.set(job.id, job);
+        this.emit('job:created', job);
+        this.logger.info(`Job created: ${job.id} (${job.name})`);
+        return job;
+    }
+    /**
+     * Get job by ID
+     */
+    async getJob(jobId) {
+        // Check memory cache first
+        const job = this.jobs.get(jobId);
+        if (job) {
+            return job;
+        }
+        // Check storage
+        const storedJob = await this.storage.get(jobId);
+        if (storedJob) {
+            this.jobs.set(jobId, storedJob);
+            return storedJob;
+        }
+        return null;
+    }
+    /**
+     * List jobs with optional filtering
+     */
+    async listJobs(filter) {
+        let jobs = await this.storage.list(filter);
+        // Apply additional filters
+        if (filter) {
+            jobs = this.applyFilters(jobs, filter);
+        }
+        return jobs;
+    }
+    /**
+     * Apply filters to job list
+     */
+    applyFilters(jobs, filter) {
+        return jobs.filter(job => {
+            // Status filter
+            if (filter.status) {
+                const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+                if (!statuses.includes(job.status)) {
+                    return false;
+                }
+            }
+            // Tags filter
+            if (filter.tags && filter.tags.length > 0) {
+                const hasTag = filter.tags.some(tag => job.tags?.includes(tag));
+                if (!hasTag) {
+                    return false;
+                }
+            }
+            // User filter
+            if (filter.user && job.user !== filter.user) {
+                return false;
+            }
+            // Name pattern filter
+            if (filter.namePattern) {
+                const pattern = typeof filter.namePattern === 'string'
+                    ? new RegExp(filter.namePattern)
+                    : filter.namePattern;
+                if (!pattern.test(job.name)) {
+                    return false;
+                }
+            }
+            // Date filters
+            if (filter.createdAfter && job.createdAt < filter.createdAfter) {
+                return false;
+            }
+            if (filter.createdBefore && job.createdAt > filter.createdBefore) {
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Update job
+     */
+    async updateJob(jobId, updates) {
+        const job = await this.getJob(jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        // Apply updates
+        if (updates.name)
+            job.name = updates.name;
+        if (updates.description)
+            job.description = updates.description;
+        if (updates.priority !== undefined)
+            job.priority = updates.priority;
+        if (updates.tags)
+            job.tags = updates.tags;
+        if (updates.schedule)
+            job.schedule = updates.schedule;
+        if (updates.env)
+            job.env = { ...job.env, ...updates.env };
+        if (updates.timeout !== undefined)
+            job.timeout = updates.timeout;
+        if (updates.maxRetries !== undefined)
+            job.maxRetries = updates.maxRetries;
+        await this.storage.update(jobId, job);
+        this.jobs.set(jobId, job);
+        this.emit('job:updated', job);
+        this.logger.info(`Job updated: ${jobId}`);
+        return job;
+    }
+    /**
+     * Update job status
+     */
+    async updateJobStatus(jobId, status, additionalUpdates) {
+        const job = await this.getJob(jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        job.status = status;
+        // Apply additional updates
+        if (additionalUpdates) {
+            Object.assign(job, additionalUpdates);
+        }
+        // Update timestamps
+        if (status === 'running' && !job.startedAt) {
+            job.startedAt = new Date();
+        }
+        if (status === 'completed' || status === 'failed' || status === 'killed') {
+            job.completedAt = new Date();
+        }
+        await this.storage.update(jobId, job);
+        this.jobs.set(jobId, job);
+        this.emit(`job:${status}`, job);
+        this.logger.info(`Job ${status}: ${jobId}`);
+        return job;
+    }
+    /**
+     * Remove job
+     */
+    async removeJob(jobId, force = false) {
+        const job = await this.getJob(jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        // Check if job is running
+        if (job.status === 'running' && !force) {
+            throw new Error(`Job ${jobId} is running. Use force=true to remove.`);
+        }
+        // Stop job if running
+        if (job.status === 'running') {
+            await this.stopJob(jobId);
+        }
+        await this.storage.delete(jobId);
+        this.jobs.delete(jobId);
+        this.emit('job:removed', job);
+        this.logger.info(`Job removed: ${jobId}`);
+        return true;
+    }
+    /**
+     * Get job execution history
+     */
+    async getJobHistory(jobId, limit = 50) {
+        return await this.storage.getExecutions(jobId, limit);
+    }
+    /**
+     * Calculate job statistics
+     */
+    async getJobStatistics(jobId) {
+        const executions = await this.getJobHistory(jobId);
+        const job = await this.getJob(jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        const totalExecutions = executions.length;
+        const successfulExecutions = executions.filter(e => e.status === 'completed').length;
+        const failedExecutions = executions.filter(e => e.status === 'failed').length;
+        const completedExecutions = executions.filter(e => e.duration);
+        const averageDuration = completedExecutions.length > 0
+            ? completedExecutions.reduce((sum, e) => sum + (e.duration || 0), 0) / completedExecutions.length
+            : 0;
+        const lastExecution = executions[0]?.startTime;
+        const lastSuccess = executions.find(e => e.status === 'completed')?.startTime;
+        const lastFailure = executions.find(e => e.status === 'failed')?.startTime;
+        return {
+            jobId: job.id,
+            jobName: job.name,
+            totalExecutions,
+            successfulExecutions,
+            failedExecutions,
+            successRate: totalExecutions > 0 ? (successfulExecutions / totalExecutions) * 100 : 0,
+            averageDuration,
+            lastExecution,
+            lastSuccess,
+            lastFailure,
+        };
+    }
+    /**
+     * Record job execution
+     */
+    async recordExecution(job, status, details = {}) {
+        const execution = {
+            executionId: this.generateJobId('exec'),
+            jobId: job.id,
+            jobName: job.name,
+            command: job.command,
+            startTime: details.startTime || new Date(),
+            endTime: details.endTime,
+            duration: details.duration,
+            status,
+            exitCode: details.exitCode,
+            stdout: details.stdout,
+            stderr: details.stderr,
+            errorMessage: details.errorMessage,
+        };
+        await this.storage.saveExecution(execution);
+        this.emit('job:execution', execution);
+        return execution;
+    }
+    /**
+     * Cleanup - optional override
+     */
+    async cleanup() {
+        if (this.storage.cleanup) {
+            await this.storage.cleanup();
+        }
+        this.jobs.clear();
+        this.removeAllListeners();
+    }
+}
+export default BaseJobManager;