@qodalis/cli-server-plugin-jobs 1.0.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Qodalis Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @qodalis/cli-server-plugin-jobs
+
+Background job scheduling plugin for [Qodalis CLI Server (Node.js)](https://github.com/qodalis-solutions/cli-server-node). Provides cron and interval-based job scheduling, execution history, retry policies, and a REST API for management.
+
+## Install
+
+```bash
+npm install @qodalis/cli-server-plugin-jobs
+```
+
+## Quick Start
+
+1. Implement `ICliJob`:
+
+```typescript
+import { ICliJob, ICliJobExecutionContext } from '@qodalis/cli-server-abstractions';
+
+export class HealthCheckJob implements ICliJob {
+    async executeAsync(context: ICliJobExecutionContext, signal: AbortSignal): Promise<void> {
+        context.logger.info('Running health check...');
+        // your logic here
+        context.logger.info('Health check passed');
+    }
+}
+```
+
+2. Build the plugin and mount it:
+
+```typescript
+import { CliJobsBuilder } from '@qodalis/cli-server-plugin-jobs';
+
+const jobsPlugin = new CliJobsBuilder()
+    .addJob(new HealthCheckJob(), {
+        name: 'health-check',
+        description: 'Periodic health check',
+        group: 'monitoring',
+        interval: '30s',
+    })
+    .build((msg) => eventSocketManager.broadcastMessage(msg));
+
+app.use('/api/v1/qcli/jobs', jobsPlugin.router);
+await jobsPlugin.scheduler.start();
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string?` | Class name | Job display name |
+| `description` | `string?` | Name | Human-readable description |
+| `group` | `string?` | — | Logical grouping |
+| `schedule` | `string?` | — | Cron expression (5-field) |
+| `interval` | `string?` | — | Fixed interval (`30s`, `5m`, `1h`, `1d`) |
+| `enabled` | `boolean` | `true` | Whether the job starts active |
+| `maxRetries` | `number` | `0` | Retry count on failure |
+| `timeout` | `string?` | — | Max execution duration (same format as interval) |
+| `overlapPolicy` | `string` | `skip` | `skip`, `queue`, or `cancel` |
+
+## REST API
+
+All endpoints are mounted at the path you choose (typically `/api/v1/qcli/jobs`).
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/` | List all jobs |
+| GET | `/:id` | Get job details |
+| POST | `/:id/trigger` | Trigger immediate execution |
+| POST | `/:id/pause` | Pause scheduled execution |
+| POST | `/:id/resume` | Resume a paused job |
+| POST | `/:id/stop` | Stop job and cancel if running |
+| POST | `/:id/cancel` | Cancel current execution only |
+| PUT | `/:id` | Update job options |
+| GET | `/:id/history` | Paginated execution history |
+| GET | `/:id/history/:execId` | Execution detail with logs |
+
+## Custom Storage
+
+By default, execution history is stored in memory. Provide a custom `ICliJobStorageProvider` for persistence:
+
+```typescript
+const plugin = new CliJobsBuilder()
+    .setStorageProvider(new MyDatabaseStorageProvider())
+    .addJob(new HealthCheckJob(), { name: 'health-check', interval: '30s' })
+    .build();
+```
+
+## License
+
+MIT

package/dist/cli-job-execution-context.d.ts

@@ -0,0 +1,8 @@
+import { ICliJobExecutionContext, ICliJobLogger } from '@qodalis/cli-server-abstractions';
+export declare class CliJobExecutionContext implements ICliJobExecutionContext {
+    readonly logger: ICliJobLogger;
+    private readonly _jobLogger;
+    constructor();
+    get logEntries(): import("@qodalis/cli-server-abstractions").JobLogEntry[];
+}
+//# sourceMappingURL=cli-job-execution-context.d.ts.map

package/dist/cli-job-execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-job-execution-context.d.ts","sourceRoot":"","sources":["../cli-job-execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAG1F,qBAAa,sBAAuB,YAAW,uBAAuB;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;;IAO1C,IAAI,UAAU,6DAEb;CACJ"}

package/dist/cli-job-execution-context.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliJobExecutionContext = void 0;
+const cli_job_logger_1 = require("./cli-job-logger");
+class CliJobExecutionContext {
+    logger;
+    _jobLogger;
+    constructor() {
+        this._jobLogger = new cli_job_logger_1.CliJobLogger();
+        this.logger = this._jobLogger;
+    }
+    get logEntries() {
+        return this._jobLogger.entries;
+    }
+}
+exports.CliJobExecutionContext = CliJobExecutionContext;
+//# sourceMappingURL=cli-job-execution-context.js.map

package/dist/cli-job-execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-job-execution-context.js","sourceRoot":"","sources":["../cli-job-execution-context.ts"],"names":[],"mappings":";;;AACA,qDAAgD;AAEhD,MAAa,sBAAsB;IACtB,MAAM,CAAgB;IAEd,UAAU,CAAe;IAE1C;QACI,IAAI,CAAC,UAAU,GAAG,IAAI,6BAAY,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;IACnC,CAAC;CACJ;AAbD,wDAaC"}

package/dist/cli-job-logger.d.ts

@@ -0,0 +1,11 @@
+import { ICliJobLogger, JobLogEntry } from '@qodalis/cli-server-abstractions';
+export declare class CliJobLogger implements ICliJobLogger {
+    private readonly _entries;
+    debug(message: string): void;
+    info(message: string): void;
+    warning(message: string): void;
+    error(message: string): void;
+    get entries(): JobLogEntry[];
+    private _log;
+}
+//# sourceMappingURL=cli-job-logger.d.ts.map

package/dist/cli-job-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-job-logger.d.ts","sourceRoot":"","sources":["../cli-job-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAe,MAAM,kCAAkC,CAAC;AAE3F,qBAAa,YAAa,YAAW,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,OAAO,IAAI,WAAW,EAAE,CAE3B;IAED,OAAO,CAAC,IAAI;CAOf"}

package/dist/cli-job-logger.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliJobLogger = void 0;
+class CliJobLogger {
+    _entries = [];
+    debug(message) {
+        this._log('debug', message);
+    }
+    info(message) {
+        this._log('info', message);
+    }
+    warning(message) {
+        this._log('warning', message);
+    }
+    error(message) {
+        this._log('error', message);
+    }
+    get entries() {
+        return this._entries;
+    }
+    _log(level, message) {
+        this._entries.push({
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+        });
+    }
+}
+exports.CliJobLogger = CliJobLogger;
+//# sourceMappingURL=cli-job-logger.js.map

package/dist/cli-job-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-job-logger.js","sourceRoot":"","sources":["../cli-job-logger.ts"],"names":[],"mappings":";;;AAEA,MAAa,YAAY;IACJ,QAAQ,GAAkB,EAAE,CAAC;IAE9C,KAAK,CAAC,OAAe;QACjB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,OAAe;QAChB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,CAAC,OAAe;QACnB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe;QACjB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,OAAO;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAEO,IAAI,CAAC,KAAkB,EAAE,OAAe;QAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK;YACL,OAAO;SACV,CAAC,CAAC;IACP,CAAC;CACJ;AA9BD,oCA8BC"}

package/dist/cli-job-scheduler.d.ts

@@ -0,0 +1,77 @@
+import { ICliJob, CliJobOptions, ICliJobStorageProvider, JobStatus } from '@qodalis/cli-server-abstractions';
+export interface JobRegistration {
+    id: string;
+    job: ICliJob;
+    options: CliJobOptions;
+    status: JobStatus;
+    currentExecutionId?: string;
+    currentAbortController?: AbortController;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastRunStatus?: string;
+    lastRunDuration?: number;
+    timer?: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>;
+    timerType?: 'cron' | 'interval';
+    /** Queued executions for overlap policy 'queue' */
+    queue: Array<{
+        resolve: () => void;
+    }>;
+}
+export interface JobDto {
+    id: string;
+    name: string;
+    description: string;
+    group?: string;
+    status: JobStatus;
+    schedule?: string;
+    interval?: string;
+    enabled: boolean;
+    maxRetries: number;
+    retryDelay: string;
+    retryStrategy: string;
+    timeout?: string;
+    overlapPolicy: string;
+    currentExecutionId?: string;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastRunStatus?: string;
+    lastRunDuration?: number;
+}
+type BroadcastFn = (message: Record<string, unknown>) => void;
+export declare class CliJobScheduler {
+    private readonly _registrations;
+    private readonly _storage;
+    private _broadcastFn;
+    private _running;
+    constructor(storage: ICliJobStorageProvider);
+    setBroadcastFn(fn: BroadcastFn): void;
+    register(job: ICliJob, options: CliJobOptions): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getAll(): JobDto[];
+    get(id: string): JobDto | undefined;
+    getRegistration(id: string): JobRegistration | undefined;
+    triggerAsync(id: string): Promise<void>;
+    pauseAsync(id: string): Promise<void>;
+    resumeAsync(id: string): Promise<void>;
+    stopJobAsync(id: string): Promise<void>;
+    cancelCurrentAsync(id: string): Promise<void>;
+    updateOptionsAsync(id: string, updates: Partial<Pick<CliJobOptions, 'description' | 'group' | 'schedule' | 'interval' | 'maxRetries' | 'retryDelay' | 'retryStrategy' | 'timeout' | 'overlapPolicy'>>): Promise<void>;
+    get storage(): ICliJobStorageProvider;
+    private _toDto;
+    private _startTimer;
+    private _startCronTimer;
+    private _startIntervalTimer;
+    private _handleTimerFire;
+    private _executeJobAsync;
+    private _stopTimer;
+    private _persistState;
+    private _broadcast;
+}
+export declare class JobError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+}
+export {};
+//# sourceMappingURL=cli-job-scheduler.d.ts.map

package/dist/cli-job-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-job-scheduler.d.ts","sourceRoot":"","sources":["../cli-job-scheduler.ts"],"names":[],"mappings":"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"}