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

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,94 @@
+# @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));
+
+// Using createCliServer:
+mountPlugin(jobsPlugin);
+
+// Or on an existing Express app:
+app.use(jobsPlugin.prefix, 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 plugin's built-in prefix (`/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,10 @@
+import { ICliJobExecutionContext, ICliJobLogger } from '@qodalis/cli-server-abstractions';
+/** Concrete execution context provided to each job run, wrapping a logger for capturing output. */
+export declare class CliJobExecutionContext implements ICliJobExecutionContext {
+    readonly logger: ICliJobLogger;
+    private readonly _jobLogger;
+    constructor();
+    /** Returns the collected log entries from the job execution. */
+    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,mGAAmG;AACnG,qBAAa,sBAAuB,YAAW,uBAAuB;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;;IAO1C,gEAAgE;IAChE,IAAI,UAAU,6DAEb;CACJ"}

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

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliJobExecutionContext = void 0;
+const cli_job_logger_1 = require("./cli-job-logger");
+/** Concrete execution context provided to each job run, wrapping a logger for capturing output. */
+class CliJobExecutionContext {
+    logger;
+    _jobLogger;
+    constructor() {
+        this._jobLogger = new cli_job_logger_1.CliJobLogger();
+        this.logger = this._jobLogger;
+    }
+    /** Returns the collected log entries from the job execution. */
+    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,mGAAmG;AACnG,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,gEAAgE;IAChE,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;IACnC,CAAC;CACJ;AAdD,wDAcC"}

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

@@ -0,0 +1,13 @@
+import { ICliJobLogger, JobLogEntry } from '@qodalis/cli-server-abstractions';
+/** In-memory logger that collects structured log entries during a job execution. */
+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;
+    /** Returns all log entries captured so far. */
+    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,oFAAoF;AACpF,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,+CAA+C;IAC/C,IAAI,OAAO,IAAI,WAAW,EAAE,CAE3B;IAED,OAAO,CAAC,IAAI;CAOf"}

package/dist/cli-job-logger.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliJobLogger = void 0;
+/** In-memory logger that collects structured log entries during a job execution. */
+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);
+    }
+    /** Returns all log entries captured so far. */
+    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,oFAAoF;AACpF,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,+CAA+C;IAC/C,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;AA/BD,oCA+BC"}

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

@@ -0,0 +1,107 @@
+import { ICliJob, CliJobOptions, ICliJobStorageProvider, JobStatus } from '@qodalis/cli-server-abstractions';
+/** Internal state for a registered job, including timers and execution queue. */
+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;
+    }>;
+}
+/** Data transfer object exposing job metadata and current state to API consumers. */
+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;
+/**
+ * Manages job registration, scheduling (cron / interval), execution with
+ * retry logic, overlap policies, and state persistence.
+ */
+export declare class CliJobScheduler {
+    private readonly _registrations;
+    private readonly _storage;
+    private _broadcastFn;
+    private _running;
+    constructor(storage: ICliJobStorageProvider);
+    /** Set the function used to broadcast job lifecycle events (e.g. via WebSocket). */
+    setBroadcastFn(fn: BroadcastFn): void;
+    /**
+     * Register a job with the scheduler.
+     *
+     * @param job - The job implementation.
+     * @param options - Scheduling and retry configuration.
+     * @returns The generated job ID.
+     */
+    register(job: ICliJob, options: CliJobOptions): string;
+    /** Load persisted job states and start timers for all active jobs. */
+    start(): Promise<void>;
+    /** Stop all timers, cancel running executions, and persist final states. */
+    stop(): Promise<void>;
+    /** Return DTOs for all registered jobs. */
+    getAll(): JobDto[];
+    /** Return the DTO for a single job, or `undefined` if not found. */
+    get(id: string): JobDto | undefined;
+    /** Return the internal registration for a job (used by the controller for history lookups). */
+    getRegistration(id: string): JobRegistration | undefined;
+    /**
+     * Trigger an immediate execution of a job, respecting the configured overlap policy.
+     *
+     * @throws {JobError} If the job is not found or is already running with a 'skip' policy.
+     */
+    triggerAsync(id: string): Promise<void>;
+    /** Pause a running job's schedule without cancelling the current execution. */
+    pauseAsync(id: string): Promise<void>;
+    /** Resume a paused job, restarting its schedule timer. */
+    resumeAsync(id: string): Promise<void>;
+    /** Stop a job entirely, cancelling any running execution and clearing its timer. */
+    stopJobAsync(id: string): Promise<void>;
+    /** Cancel the currently running execution of a job without changing its schedule. */
+    cancelCurrentAsync(id: string): Promise<void>;
+    /** Update mutable job options (schedule, retry policy, etc.) and restart timers if active. */
+    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;
+}
+/** Typed error thrown by the scheduler, carrying an error code and HTTP status. */
+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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"}