@dcrays/scheduled-task 0.1.0

package/src/cron.d.ts

@@ -0,0 +1,24 @@
+export declare const MIN_CRON_INTERVAL_SECONDS = 600;
+interface CronField {
+    readonly values: ReadonlySet<number>;
+    readonly wildcard: boolean;
+}
+export interface ParsedCronExpression {
+    readonly expression: string;
+    readonly minutes: CronField;
+    readonly hours: CronField;
+    readonly daysOfMonth: CronField;
+    readonly months: CronField;
+    readonly daysOfWeek: CronField;
+}
+export declare class CronExpressionError extends Error {
+    constructor(message: string);
+}
+export declare function validTimeZone(timeZone: string): boolean;
+/** Parse a standard five-field minute/hour/day-of-month/month/day-of-week cron expression. */
+export declare function parseCronExpression(value: string): ParsedCronExpression;
+/** Enforce the system-wide minimum cadence for recurring cron schedules. */
+export declare function assertMinimumCronInterval(cron: string | ParsedCronExpression, minimumSeconds?: number): ParsedCronExpression;
+/** Return the first cron occurrence strictly after the supplied instant. */
+export declare function nextCronOccurrence(afterEpochMs: number, cron: string | ParsedCronExpression, timeZone: string): number;
+export {};

package/src/cron.js

@@ -0,0 +1,211 @@
+const FIELD_COUNT = 5;
+const MAX_SEARCH_DAYS = 366 * 8;
+const GREGORIAN_CYCLE_DAYS = 146_097;
+export const MIN_CRON_INTERVAL_SECONDS = 600;
+export class CronExpressionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CronExpressionError";
+    }
+}
+export function validTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseInteger(value, label) {
+    if (!/^\d+$/.test(value))
+        throw new CronExpressionError(`${label} contains a non-integer value`);
+    return Number(value);
+}
+function parseField(raw, min, max, label, normalize) {
+    const values = new Set();
+    const wildcard = raw === "*" || raw.startsWith("*/");
+    if (raw.length === 0)
+        throw new CronExpressionError(`${label} is empty`);
+    for (const segment of raw.split(",")) {
+        if (segment.length === 0)
+            throw new CronExpressionError(`${label} contains an empty list item`);
+        const slash = segment.split("/");
+        if (slash.length > 2)
+            throw new CronExpressionError(`${label} contains an invalid step`);
+        const base = slash[0] ?? "";
+        const step = slash[1] === undefined ? 1 : parseInteger(slash[1], label);
+        if (step < 1)
+            throw new CronExpressionError(`${label} step must be positive`);
+        let start;
+        let end;
+        if (base === "*") {
+            start = min;
+            end = max;
+        }
+        else if (base.includes("-")) {
+            const range = base.split("-");
+            if (range.length !== 2)
+                throw new CronExpressionError(`${label} contains an invalid range`);
+            start = parseInteger(range[0] ?? "", label);
+            end = parseInteger(range[1] ?? "", label);
+        }
+        else {
+            start = parseInteger(base, label);
+            end = slash[1] === undefined ? start : max;
+        }
+        if (start < min || start > max || end < min || end > max || start > end) {
+            throw new CronExpressionError(`${label} must stay within ${min}-${max}`);
+        }
+        for (let value = start; value <= end; value += step)
+            values.add(normalize?.(value) ?? value);
+    }
+    if (values.size === 0)
+        throw new CronExpressionError(`${label} selects no values`);
+    return { values, wildcard };
+}
+/** Parse a standard five-field minute/hour/day-of-month/month/day-of-week cron expression. */
+export function parseCronExpression(value) {
+    if (value.trim() !== value || value.length === 0)
+        throw new CronExpressionError("cron expression must not have surrounding whitespace");
+    const fields = value.split(/\s+/);
+    if (fields.length !== FIELD_COUNT)
+        throw new CronExpressionError("cron expression must contain exactly five fields");
+    return {
+        expression: fields.join(" "),
+        minutes: parseField(fields[0] ?? "", 0, 59, "minute"),
+        hours: parseField(fields[1] ?? "", 0, 23, "hour"),
+        daysOfMonth: parseField(fields[2] ?? "", 1, 31, "day-of-month"),
+        months: parseField(fields[3] ?? "", 1, 12, "month"),
+        daysOfWeek: parseField(fields[4] ?? "", 0, 7, "day-of-week", (day) => day === 7 ? 0 : day)
+    };
+}
+function formatter(timeZone) {
+    return new Intl.DateTimeFormat("en-CA-u-ca-iso8601-nu-latn", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "longOffset"
+    });
+}
+function projectedParts(format, epochMs) {
+    const values = Object.fromEntries(format.formatToParts(epochMs).map((part) => [part.type, part.value]));
+    const match = /^GMT(?:(?<sign>[+-])(?<hour>\d{2}):(?<minute>\d{2}))?$/.exec(values.timeZoneName ?? "");
+    if (!match?.groups)
+        throw new CronExpressionError("time zone did not expose a usable UTC offset");
+    const direction = match.groups.sign === "-" ? -1 : 1;
+    const offset = match.groups.sign === undefined
+        ? 0
+        : direction * (Number(match.groups.hour) * 60 + Number(match.groups.minute)) * 60_000;
+    return {
+        year: Number(values.year),
+        month: Number(values.month),
+        day: Number(values.day),
+        hour: Number(values.hour),
+        minute: Number(values.minute),
+        second: Number(values.second),
+        offset
+    };
+}
+function localToEpoch(parts, format) {
+    const localEpoch = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0);
+    const offsets = new Set();
+    for (const delta of [-86_400_000, 0, 86_400_000])
+        offsets.add(projectedParts(format, localEpoch + delta).offset);
+    const candidates = [];
+    for (const offset of offsets) {
+        const candidate = localEpoch - offset;
+        const projected = projectedParts(format, candidate);
+        if (projected.year === parts.year && projected.month === parts.month && projected.day === parts.day && projected.hour === parts.hour && projected.minute === parts.minute) {
+            candidates.push(candidate);
+        }
+    }
+    return [...new Set(candidates)].sort((left, right) => left - right);
+}
+function dateMatches(parsed, year, month, day) {
+    if (!parsed.months.values.has(month))
+        return false;
+    const dayOfWeek = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+    const dom = parsed.daysOfMonth.values.has(day);
+    const dow = parsed.daysOfWeek.values.has(dayOfWeek);
+    if (parsed.daysOfMonth.wildcard && parsed.daysOfWeek.wildcard)
+        return true;
+    if (parsed.daysOfMonth.wildcard)
+        return dow;
+    if (parsed.daysOfWeek.wildcard)
+        return dom;
+    return dom || dow;
+}
+function canMatchConsecutiveDays(parsed) {
+    let date = Date.UTC(2000, 0, 1);
+    let previousMatched = false;
+    for (let offset = 0; offset < GREGORIAN_CYCLE_DAYS; offset += 1) {
+        const calendar = new Date(date);
+        const matched = dateMatches(parsed, calendar.getUTCFullYear(), calendar.getUTCMonth() + 1, calendar.getUTCDate());
+        if (matched && previousMatched)
+            return true;
+        previousMatched = matched;
+        date += 86_400_000;
+    }
+    return false;
+}
+/** Enforce the system-wide minimum cadence for recurring cron schedules. */
+export function assertMinimumCronInterval(cron, minimumSeconds = MIN_CRON_INTERVAL_SECONDS) {
+    const parsed = typeof cron === "string" ? parseCronExpression(cron) : cron;
+    const slots = [...parsed.hours.values]
+        .flatMap((hour) => [...parsed.minutes.values].map((minute) => hour * 60 + minute))
+        .sort((left, right) => left - right);
+    const minimumMinutes = Math.ceil(minimumSeconds / 60);
+    for (let index = 1; index < slots.length; index += 1) {
+        if ((slots[index] ?? 0) - (slots[index - 1] ?? 0) < minimumMinutes) {
+            throw new CronExpressionError(`cron interval must be at least ${minimumSeconds} seconds (${minimumMinutes} minutes)`);
+        }
+    }
+    const first = slots[0];
+    const last = slots.at(-1);
+    if (first !== undefined
+        && last !== undefined
+        && first + 1_440 - last < minimumMinutes
+        && canMatchConsecutiveDays(parsed)) {
+        throw new CronExpressionError(`cron interval must be at least ${minimumSeconds} seconds (${minimumMinutes} minutes)`);
+    }
+    return parsed;
+}
+/** Return the first cron occurrence strictly after the supplied instant. */
+export function nextCronOccurrence(afterEpochMs, cron, timeZone) {
+    if (!validTimeZone(timeZone))
+        throw new CronExpressionError("timezone must be a valid IANA time zone");
+    const parsed = typeof cron === "string" ? parseCronExpression(cron) : cron;
+    const format = formatter(timeZone);
+    const start = projectedParts(format, afterEpochMs);
+    const hours = [...parsed.hours.values].sort((left, right) => left - right);
+    const minutes = [...parsed.minutes.values].sort((left, right) => left - right);
+    let date = Date.UTC(start.year, start.month - 1, start.day);
+    for (let offset = 0; offset < MAX_SEARCH_DAYS; offset += 1) {
+        const calendar = new Date(date);
+        const year = calendar.getUTCFullYear();
+        const month = calendar.getUTCMonth() + 1;
+        const day = calendar.getUTCDate();
+        if (dateMatches(parsed, year, month, day)) {
+            let earliest;
+            for (const hour of hours) {
+                for (const minute of minutes) {
+                    const candidates = localToEpoch({ year, month, day, hour, minute }, format);
+                    for (const candidate of candidates) {
+                        if (candidate > afterEpochMs && (earliest === undefined || candidate < earliest))
+                            earliest = candidate;
+                    }
+                }
+            }
+            if (earliest !== undefined)
+                return earliest;
+        }
+        date = Date.UTC(year, month - 1, day + 1);
+    }
+    throw new CronExpressionError("cron expression has no occurrence within the next eight years");
+}

package/src/manager.d.ts

@@ -0,0 +1,51 @@
+import type { CronCreateEnvelope } from './protocol.js';
+import { CronAutomationRepository, type StoredCronAutomation } from './repository.js';
+export interface CronAutomationManagerOptions {
+    maxPromptChars: number;
+    now?: () => number;
+    deliver(job: StoredCronAutomation, occurrenceAt: string): boolean | Promise<boolean>;
+    onError?(error: unknown): void;
+    onCreated?(job: StoredCronAutomation): void;
+    onChanged?(job: StoredCronAutomation): void;
+    onDispatched?(job: StoredCronAutomation, occurrenceAt: string): void;
+}
+export interface CronAutomationPatch {
+    enabled?: boolean;
+    name?: string;
+    prompt?: string;
+    cron?: string;
+    timezone?: string;
+    sessionKey?: string;
+    agentId?: string;
+    dshSessionId?: string;
+}
+export type CronRunStatus = 'dispatched' | 'not_found' | 'already_running' | 'delivery_unavailable';
+export declare class CronAutomationManager {
+    private readonly repository;
+    private readonly options;
+    private readonly jobs;
+    private readonly blockedAgents;
+    private readonly now;
+    private started?;
+    private tail;
+    private timer;
+    private stopping;
+    constructor(repository: CronAutomationRepository, options: CronAutomationManagerOptions);
+    start(): Promise<void>;
+    private initialize;
+    stop(): Promise<void>;
+    create(agentId: string, envelope: CronCreateEnvelope): Promise<StoredCronAutomation>;
+    update(jobId: string, patch: CronAutomationPatch): Promise<StoredCronAutomation | undefined>;
+    delete(jobId: string): Promise<boolean>;
+    runOnceStatus(jobId: string): Promise<CronRunStatus>;
+    runOnce(jobId: string): Promise<boolean>;
+    list(agentId?: string): Promise<StoredCronAutomation[]>;
+    notifyAgentAvailable(agentId: string): void;
+    /** Import each source job once. Existing ids win so DSH bindings stay intact. */
+    importFrom(source: string, incoming: readonly StoredCronAutomation[]): Promise<StoredCronAutomation[]>;
+    private deliver;
+    private enqueue;
+    private requestDispatch;
+    private arm;
+    private dispatchDue;
+}