@provos/ironcurtain 0.6.0 → 0.7.1

package/dist/cron/constitution-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constitution-generator.js","sourceRoot":"","sources":["../../src/cron/constitution-generator.ts"],"names":[],"mappings":"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"}

package/dist/cron/cron-scheduler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CronScheduler -- manages cron schedules for all enabled jobs.
+ *
+ * Uses a polling approach with 60-second intervals to check
+ * whether each job's cron expression matches the current time.
+ * When node-cron is available, the implementation can be swapped
+ * to use it for more efficient scheduling.
+ */
+import type { JobDefinition, JobId } from './types.js';
+/**
+ * Callback invoked when a scheduled job fires.
+ * The daemon implements this to create a session.
+ */
+export type JobTriggerCallback = (job: JobDefinition) => Promise<void>;
+/**
+ * Manages cron schedules for all enabled jobs.
+ *
+ * Invariant: at most one schedule exists per jobId at any time.
+ * Calling schedule() for an already-scheduled job replaces the
+ * previous schedule.
+ */
+export interface CronScheduler {
+    /**
+     * Registers a job's schedule. The callback fires at each
+     * scheduled time. Does not fire immediately.
+     *
+     * @throws InvalidCronExpressionError if the cron expression
+     * is syntactically invalid.
+     */
+    schedule(job: JobDefinition, onTrigger: JobTriggerCallback): void;
+    /** Removes a job's schedule. No-op if not scheduled. */
+    unschedule(jobId: JobId): void;
+    /** Removes all schedules. Called during shutdown. */
+    unscheduleAll(): void;
+    /**
+     * Returns the next scheduled fire time for a job, or undefined
+     * if the job is not scheduled.
+     */
+    getNextRun(jobId: JobId): Date | undefined;
+}
+/**
+ * Thrown when a cron expression cannot be parsed.
+ */
+export declare class InvalidCronExpressionError extends Error {
+    readonly expression: string;
+    constructor(expression: string, cause: unknown);
+}
+interface CronFields {
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    daysOfWeek: Set<number>;
+}
+declare function parseCronExpression(expression: string): CronFields;
+declare function cronMatchesTime(fields: CronFields, date: Date): boolean;
+/**
+ * Calculates the next time a cron expression would fire after the given date.
+ * Scans forward minute-by-minute (up to 366 days).
+ */
+declare function getNextFireTime(fields: CronFields, after: Date): Date;
+/** Creates a CronScheduler with built-in cron expression parsing. */
+export declare function createCronScheduler(): CronScheduler;
+export { parseCronExpression, cronMatchesTime, getNextFireTime };
+export type { CronFields };

package/dist/cron/cron-scheduler.js

@@ -0,0 +1,184 @@
+/**
+ * CronScheduler -- manages cron schedules for all enabled jobs.
+ *
+ * Uses a polling approach with 60-second intervals to check
+ * whether each job's cron expression matches the current time.
+ * When node-cron is available, the implementation can be swapped
+ * to use it for more efficient scheduling.
+ */
+import * as logger from '../logger.js';
+/**
+ * Thrown when a cron expression cannot be parsed.
+ */
+export class InvalidCronExpressionError extends Error {
+    expression;
+    constructor(expression, cause) {
+        super(`Invalid cron expression "${expression}": ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.expression = expression;
+        this.name = 'InvalidCronExpressionError';
+    }
+}
+function parseField(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(',')) {
+        const stepMatch = part.match(/^(.+)\/(\d+)$/);
+        const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+        if (stepMatch && (isNaN(step) || step < 1)) {
+            throw new Error(`Invalid step "${stepMatch[2]}" in "${part}" (expected integer >= 1)`);
+        }
+        const range = stepMatch ? stepMatch[1] : part;
+        if (range === '*') {
+            for (let i = min; i <= max; i += step)
+                values.add(i);
+        }
+        else if (range.includes('-')) {
+            const [startStr, endStr] = range.split('-');
+            const start = parseInt(startStr, 10);
+            const end = parseInt(endStr, 10);
+            if (isNaN(start) || isNaN(end) || start < min || end > max || start > end) {
+                throw new Error(`Invalid range "${range}" (expected ${min}-${max})`);
+            }
+            for (let i = start; i <= end; i += step)
+                values.add(i);
+        }
+        else {
+            const val = parseInt(range, 10);
+            if (isNaN(val) || val < min || val > max) {
+                throw new Error(`Invalid value "${range}" (expected ${min}-${max})`);
+            }
+            values.add(val);
+        }
+    }
+    return values;
+}
+function parseCronExpression(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`Expected 5 fields (min hour dom mon dow), got ${parts.length}`);
+    }
+    const daysOfWeek = parseField(parts[4], 0, 7); // 0 and 7 both mean Sunday
+    if (daysOfWeek.has(7)) {
+        daysOfWeek.add(0);
+        daysOfWeek.delete(7);
+    }
+    return {
+        minutes: parseField(parts[0], 0, 59),
+        hours: parseField(parts[1], 0, 23),
+        daysOfMonth: parseField(parts[2], 1, 31),
+        months: parseField(parts[3], 1, 12),
+        daysOfWeek,
+    };
+}
+function cronMatchesTime(fields, date) {
+    const minute = date.getMinutes();
+    const hour = date.getHours();
+    const dayOfMonth = date.getDate();
+    const month = date.getMonth() + 1; // 0-indexed -> 1-indexed
+    const dayOfWeek = date.getDay(); // 0 = Sunday
+    if (!fields.minutes.has(minute))
+        return false;
+    if (!fields.hours.has(hour))
+        return false;
+    if (!fields.months.has(month))
+        return false;
+    // Standard cron: if both dom and dow are restricted (not *), match either
+    const domIsWildcard = fields.daysOfMonth.size === 31;
+    const dowIsWildcard = fields.daysOfWeek.size === 7;
+    if (domIsWildcard && dowIsWildcard)
+        return true;
+    if (domIsWildcard)
+        return fields.daysOfWeek.has(dayOfWeek);
+    if (dowIsWildcard)
+        return fields.daysOfMonth.has(dayOfMonth);
+    // Both restricted: OR logic (standard cron behavior)
+    return fields.daysOfMonth.has(dayOfMonth) || fields.daysOfWeek.has(dayOfWeek);
+}
+/**
+ * Calculates the next time a cron expression would fire after the given date.
+ * Scans forward minute-by-minute (up to 366 days).
+ */
+function getNextFireTime(fields, after) {
+    const candidate = new Date(after);
+    // Start from the next minute
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1);
+    const maxIterations = 366 * 24 * 60; // One year of minutes
+    for (let i = 0; i < maxIterations; i++) {
+        if (cronMatchesTime(fields, candidate)) {
+            return candidate;
+        }
+        candidate.setMinutes(candidate.getMinutes() + 1);
+    }
+    // Should not happen for valid expressions, but return a far-future date
+    return new Date(after.getTime() + 366 * 24 * 60 * 60 * 1000);
+}
+/** Creates a CronScheduler with built-in cron expression parsing. */
+export function createCronScheduler() {
+    const jobs = new Map();
+    let pollInterval = null;
+    function startPolling() {
+        if (pollInterval)
+            return;
+        // Poll every 30 seconds (within the 60-second cron granularity)
+        pollInterval = setInterval(() => tick(), 30_000);
+        pollInterval.unref(); // Don't keep the process alive just for polling
+    }
+    function stopPolling() {
+        if (pollInterval) {
+            clearInterval(pollInterval);
+            pollInterval = null;
+        }
+    }
+    function tick() {
+        const now = new Date();
+        // Truncate to the current minute for comparison
+        now.setSeconds(0, 0);
+        for (const [jobId, scheduled] of jobs.entries()) {
+            if (scheduled.lastFired && scheduled.lastFired.getTime() === now.getTime()) {
+                continue; // Already fired this minute
+            }
+            if (cronMatchesTime(scheduled.fields, now)) {
+                scheduled.lastFired = now;
+                logger.info(`[CronScheduler] Firing job ${jobId} at ${now.toISOString()}`);
+                scheduled.callback(scheduled.job).catch((err) => {
+                    logger.warn(`[CronScheduler] Job ${jobId} callback failed: ${String(err)}`);
+                });
+            }
+        }
+    }
+    return {
+        schedule(job, onTrigger) {
+            let fields;
+            try {
+                fields = parseCronExpression(job.schedule);
+            }
+            catch (err) {
+                throw new InvalidCronExpressionError(job.schedule, err);
+            }
+            // Replace any existing schedule for this job
+            jobs.set(job.id, { job, fields, callback: onTrigger, lastFired: null });
+            if (jobs.size === 1) {
+                startPolling();
+            }
+        },
+        unschedule(jobId) {
+            jobs.delete(jobId);
+            if (jobs.size === 0) {
+                stopPolling();
+            }
+        },
+        unscheduleAll() {
+            jobs.clear();
+            stopPolling();
+        },
+        getNextRun(jobId) {
+            const scheduled = jobs.get(jobId);
+            if (!scheduled)
+                return undefined;
+            return getNextFireTime(scheduled.fields, new Date());
+        },
+    };
+}
+// Export for testing
+export { parseCronExpression, cronMatchesTime, getNextFireTime };
+//# sourceMappingURL=cron-scheduler.js.map

package/dist/cron/cron-scheduler.js.map

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

package/dist/cron/file-lock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Advisory file locking for the job store.
+ *
+ * Uses mkdir (atomic on POSIX) to create a lock directory next to the
+ * target file. The lock directory contains a metadata file with the
+ * owning PID and timestamp, enabling stale lock detection when a
+ * process crashes without releasing.
+ *
+ * This is designed for short-lived critical sections (read-modify-write),
+ * not long-held process-level locks. For process singleton enforcement,
+ * see src/escalation/listener-lock.ts.
+ */
+/**
+ * Releases an advisory lock. Safe to call even if the lock is not held.
+ */
+export declare function releaseLock(lockDir: string): void;
+/**
+ * Acquires an advisory lock, retrying until timeout.
+ *
+ * @param lockDir Path to the lock directory (typically `{target}.lock`)
+ * @param staleMs Time in ms after which an unreleased lock is considered stale
+ * @returns true if acquired, false if timed out
+ */
+export declare function acquireLock(lockDir: string, staleMs?: number): Promise<boolean>;
+/**
+ * Executes a function while holding an advisory file lock.
+ *
+ * Acquires the lock, runs the function, and releases the lock in a
+ * finally block. Throws if the lock cannot be acquired within the
+ * timeout period.
+ *
+ * @param lockDir Path to the lock directory
+ * @param fn The function to execute under lock
+ * @param staleMs Stale lock timeout (default 30s)
+ */
+export declare function withFileLock<T>(lockDir: string, fn: () => T | Promise<T>, staleMs?: number): Promise<T>;
+/**
+ * Returns the conventional lock directory path for a job directory.
+ * The lock is placed at `{jobDir}/job.json.lock/`.
+ */
+export declare function getJobLockDir(jobDir: string): string;

package/dist/cron/file-lock.js

@@ -0,0 +1,156 @@
+/**
+ * Advisory file locking for the job store.
+ *
+ * Uses mkdir (atomic on POSIX) to create a lock directory next to the
+ * target file. The lock directory contains a metadata file with the
+ * owning PID and timestamp, enabling stale lock detection when a
+ * process crashes without releasing.
+ *
+ * This is designed for short-lived critical sections (read-modify-write),
+ * not long-held process-level locks. For process singleton enforcement,
+ * see src/escalation/listener-lock.ts.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isPidAlive } from '../escalation/listener-lock.js';
+/** Default stale timeout: 30 seconds. */
+const DEFAULT_STALE_MS = 30_000;
+/** Retry interval when waiting for a lock. */
+const RETRY_INTERVAL_MS = 50;
+/** Maximum time to wait for a lock before giving up. */
+const MAX_WAIT_MS = 10_000;
+/**
+ * Attempts to acquire an advisory lock for the given path.
+ * Returns true if the lock was acquired, false otherwise.
+ *
+ * The lock is a directory at `{path}.lock/` containing a `meta.json`
+ * with the owning PID and creation timestamp.
+ */
+function tryAcquire(lockDir, staleMs) {
+    // Attempt atomic mkdir first — this is the authoritative lock acquisition.
+    // Only check for stale locks after EEXIST, avoiding a TOCTOU race.
+    try {
+        mkdirSync(lockDir);
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST') {
+            throw err;
+        }
+        // Lock dir exists — check if it's stale
+        if (isLockStale(lockDir, staleMs)) {
+            forceRelease(lockDir);
+            // Retry mkdir after releasing stale lock
+            try {
+                mkdirSync(lockDir);
+            }
+            catch (retryErr) {
+                if (retryErr.code === 'EEXIST') {
+                    return false; // Another process grabbed it
+                }
+                throw retryErr;
+            }
+        }
+        else {
+            return false;
+        }
+    }
+    // Write metadata for stale detection
+    const meta = { pid: process.pid, timestamp: Date.now() };
+    try {
+        writeFileSync(resolve(lockDir, 'meta.json'), JSON.stringify(meta));
+    }
+    catch {
+        // If we can't write metadata, release and fail
+        forceRelease(lockDir);
+        return false;
+    }
+    return true;
+}
+/**
+ * Checks whether an existing lock is stale (owner dead or timed out).
+ */
+function isLockStale(lockDir, staleMs) {
+    const metaPath = resolve(lockDir, 'meta.json');
+    try {
+        const raw = readFileSync(metaPath, 'utf-8');
+        const meta = JSON.parse(raw);
+        // Check if the owning process is still alive
+        if (!isPidAlive(meta.pid)) {
+            return true;
+        }
+        // Check if the lock has exceeded the stale timeout
+        if (Date.now() - meta.timestamp > staleMs) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        // No metadata or unreadable -- treat as stale
+        return true;
+    }
+}
+/**
+ * Force-removes a lock directory. Best-effort.
+ */
+function forceRelease(lockDir) {
+    try {
+        rmSync(lockDir, { recursive: true, force: true });
+    }
+    catch {
+        /* best effort */
+    }
+}
+/**
+ * Releases an advisory lock. Safe to call even if the lock is not held.
+ */
+export function releaseLock(lockDir) {
+    forceRelease(lockDir);
+}
+/**
+ * Acquires an advisory lock, retrying until timeout.
+ *
+ * @param lockDir Path to the lock directory (typically `{target}.lock`)
+ * @param staleMs Time in ms after which an unreleased lock is considered stale
+ * @returns true if acquired, false if timed out
+ */
+export async function acquireLock(lockDir, staleMs = DEFAULT_STALE_MS) {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    while (Date.now() < deadline) {
+        if (tryAcquire(lockDir, staleMs)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+    }
+    return false;
+}
+/**
+ * Executes a function while holding an advisory file lock.
+ *
+ * Acquires the lock, runs the function, and releases the lock in a
+ * finally block. Throws if the lock cannot be acquired within the
+ * timeout period.
+ *
+ * @param lockDir Path to the lock directory
+ * @param fn The function to execute under lock
+ * @param staleMs Stale lock timeout (default 30s)
+ */
+export async function withFileLock(lockDir, fn, staleMs = DEFAULT_STALE_MS) {
+    const acquired = await acquireLock(lockDir, staleMs);
+    if (!acquired) {
+        throw new Error(`Failed to acquire file lock: ${lockDir} (timed out after ${MAX_WAIT_MS}ms)`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock(lockDir);
+    }
+}
+/**
+ * Returns the conventional lock directory path for a job directory.
+ * The lock is placed at `{jobDir}/job.json.lock/`.
+ */
+export function getJobLockDir(jobDir) {
+    return resolve(jobDir, 'job.json.lock');
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/cron/file-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../../src/cron/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE5D,yCAAyC;AACzC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,8CAA8C;AAC9C,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,wDAAwD;AACxD,MAAM,WAAW,GAAG,MAAM,CAAC;AAO3B;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,OAAe,EAAE,OAAe;IAClD,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,wCAAwC;QACxC,IAAI,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,yCAAyC;YACzC,IAAI,CAAC;gBACH,SAAS,CAAC,OAAO,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,QAAiB,EAAE,CAAC;gBAC3B,IAAK,QAAkC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC1D,OAAO,KAAK,CAAC,CAAC,6BAA6B;gBAC7C,CAAC;gBACD,MAAM,QAAQ,CAAC;YACjB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,MAAM,IAAI,GAAiB,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACvE,IAAI,CAAC;QACH,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;QAC/C,YAAY,CAAC,OAAO,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,OAAe,EAAE,OAAe;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;QAE7C,6CAA6C;QAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mDAAmD;QACnD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,8CAA8C;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,CAAC;QACH,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,YAAY,CAAC,OAAO,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe,EAAE,UAAkB,gBAAgB;IACnF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC;IAE1C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,EAAwB,EACxB,UAAkB,gBAAgB;IAElC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,qBAAqB,WAAW,KAAK,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,WAAW,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,OAAO,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC"}

package/dist/cron/format-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Formatting utilities for cron job CLI output.
+ */
+/**
+ * Formats a duration in seconds as a compact string like "1d 2h 30m".
+ * Shows up to two units for brevity (e.g., "2h 15m" not "2h 15m 30s").
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Formats a date as a relative time string with an absolute time suffix.
+ * Examples: "in 2h 15m (Mar 5, 09:00)", "3h ago (Mar 5, 06:00)", "just now (Mar 5, 09:00)"
+ */
+export declare function formatRelativeTime(date: Date, now?: Date): string;
+/**
+ * Converts a 5-field cron expression into a human-readable English description.
+ * Covers common patterns well; exotic expressions get a best-effort description.
+ */
+export declare function describeCronExpression(expr: string): string;

package/dist/cron/format-utils.js

@@ -0,0 +1,145 @@
+/**
+ * Formatting utilities for cron job CLI output.
+ */
+import { parseCronExpression } from './cron-scheduler.js';
+// ---------------------------------------------------------------------------
+// Shared constants
+// ---------------------------------------------------------------------------
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+// ---------------------------------------------------------------------------
+// Duration and relative time display
+// ---------------------------------------------------------------------------
+/**
+ * Formats a duration in seconds as a compact string like "1d 2h 30m".
+ * Shows up to two units for brevity (e.g., "2h 15m" not "2h 15m 30s").
+ */
+export function formatDuration(seconds) {
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours % 24 > 0)
+        parts.push(`${hours % 24}h`);
+    if (minutes % 60 > 0 && days === 0)
+        parts.push(`${minutes % 60}m`);
+    if (parts.length === 0)
+        parts.push('0m');
+    return parts.join(' ');
+}
+/**
+ * Formats a date as a relative time string with an absolute time suffix.
+ * Examples: "in 2h 15m (Mar 5, 09:00)", "3h ago (Mar 5, 06:00)", "just now (Mar 5, 09:00)"
+ */
+export function formatRelativeTime(date, now = new Date()) {
+    const diffMs = date.getTime() - now.getTime();
+    const absDiffSec = Math.floor(Math.abs(diffMs) / 1000);
+    const absolute = formatAbsoluteTime(date);
+    if (absDiffSec < 60)
+        return `just now (${absolute})`;
+    const dur = formatDuration(absDiffSec);
+    const relative = diffMs >= 0 ? `in ${dur}` : `${dur} ago`;
+    return `${relative} (${absolute})`;
+}
+function formatAbsoluteTime(date) {
+    const month = MONTH_NAMES[date.getMonth()];
+    const day = date.getDate();
+    const hours = date.getHours().toString().padStart(2, '0');
+    const minutes = date.getMinutes().toString().padStart(2, '0');
+    return `${month} ${day}, ${hours}:${minutes}`;
+}
+// ---------------------------------------------------------------------------
+// Cron expression description
+// ---------------------------------------------------------------------------
+const DAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+/**
+ * Converts a 5-field cron expression into a human-readable English description.
+ * Covers common patterns well; exotic expressions get a best-effort description.
+ */
+export function describeCronExpression(expr) {
+    let fields;
+    try {
+        fields = parseCronExpression(expr);
+    }
+    catch {
+        return expr; // fallback to raw expression if unparseable
+    }
+    const parts = [];
+    // Time part
+    parts.push(describeTimePart(expr, fields));
+    // Day-of-week part
+    const dowPart = describeDaysOfWeek(fields);
+    if (dowPart)
+        parts.push(dowPart);
+    // Day-of-month part
+    const domPart = describeDaysOfMonth(fields);
+    if (domPart)
+        parts.push(domPart);
+    // Month part
+    const monthPart = describeMonths(fields);
+    if (monthPart)
+        parts.push(monthPart);
+    return parts.join(', ');
+}
+function describeTimePart(expr, fields) {
+    const rawParts = expr.trim().split(/\s+/);
+    const minField = rawParts[0];
+    const hourField = rawParts[1];
+    // Every N minutes
+    const minStep = minField.match(/^\*\/(\d+)$/);
+    if (minStep && hourField === '*') {
+        return `Every ${minStep[1]} minutes`;
+    }
+    // Every hour at specific minute
+    if (fields.minutes.size === 1 && hourField === '*') {
+        const min = [...fields.minutes][0];
+        return min === 0 ? 'Every hour' : `Every hour at :${min.toString().padStart(2, '0')}`;
+    }
+    // Every N hours
+    const hourStep = hourField.match(/^\*\/(\d+)$/);
+    if (hourStep && fields.minutes.size === 1) {
+        const min = [...fields.minutes][0];
+        return `Every ${hourStep[1]} hours at :${min.toString().padStart(2, '0')}`;
+    }
+    // Specific time(s)
+    if (fields.hours.size <= 3 && fields.minutes.size === 1) {
+        const min = [...fields.minutes][0];
+        const times = [...fields.hours]
+            .sort((a, b) => a - b)
+            .map((h) => `${h.toString().padStart(2, '0')}:${min.toString().padStart(2, '0')}`);
+        return `At ${times.join(', ')}`;
+    }
+    // Fallback: describe minutes and hours separately
+    return `At minute ${[...fields.minutes].sort((a, b) => a - b).join(',')} of hour ${[...fields.hours].sort((a, b) => a - b).join(',')}`;
+}
+function describeDaysOfWeek(fields) {
+    if (fields.daysOfWeek.size === 7)
+        return null; // wildcard
+    const days = [...fields.daysOfWeek].sort((a, b) => a - b);
+    // Check for contiguous range
+    if (days.length >= 2 && isContiguous(days)) {
+        return `${DAY_NAMES[days[0]]}--${DAY_NAMES[days[days.length - 1]]}`;
+    }
+    return days.map((d) => DAY_NAMES[d]).join(', ');
+}
+function describeDaysOfMonth(fields) {
+    if (fields.daysOfMonth.size === 31)
+        return null; // wildcard
+    const days = [...fields.daysOfMonth].sort((a, b) => a - b);
+    return `on day ${days.join(', ')} of the month`;
+}
+function describeMonths(fields) {
+    if (fields.months.size === 12)
+        return null; // wildcard
+    const months = [...fields.months].sort((a, b) => a - b);
+    return `in ${months.map((m) => MONTH_NAMES[m - 1]).join(', ')}`;
+}
+function isContiguous(sorted) {
+    for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i] !== sorted[i - 1] + 1)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=format-utils.js.map

package/dist/cron/format-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-utils.js","sourceRoot":"","sources":["../../src/cron/format-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAmB,MAAM,qBAAqB,CAAC;AAE3E,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEzG,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IAEpC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,GAAG,EAAE,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC;IACjD,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,IAAI,IAAI,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;IACnE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAU,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAE1C,IAAI,UAAU,GAAG,EAAE;QAAE,OAAO,aAAa,QAAQ,GAAG,CAAC;IAErD,MAAM,GAAG,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC;IAC1D,OAAO,GAAG,QAAQ,KAAK,QAAQ,GAAG,CAAC;AACrC,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAU;IACpC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,KAAK,IAAI,GAAG,KAAK,KAAK,IAAI,OAAO,EAAE,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,MAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,4CAA4C;IAC3D,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,YAAY;IACZ,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAE3C,mBAAmB;IACnB,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEjC,oBAAoB;IACpB,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEjC,aAAa;IACb,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAErC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAkB;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE9B,kBAAkB;IAClB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC9C,IAAI,OAAO,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;QACjC,OAAO,SAAS,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IACvC,CAAC;IAED,gCAAgC;IAChC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACxF,CAAC;IAED,gBAAgB;IAChB,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAChD,IAAI,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,OAAO,SAAS,QAAQ,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAC7E,CAAC;IAED,mBAAmB;IACnB,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;aAC5B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;aACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACrF,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAClC,CAAC;IAED,kDAAkD;IAClD,OAAO,aAAa,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACzI,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAkB;IAC5C,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,WAAW;IAE1D,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAE1D,6BAA6B;IAC7B,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAkB;IAC7C,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,WAAW;IAE5D,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC;AAClD,CAAC;AAED,SAAS,cAAc,CAAC,MAAkB;IACxC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,WAAW;IAEvD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,YAAY,CAAC,MAAgB;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}