@clinebot/core 0.0.36 → 0.0.37

package/src/cron/cron-watcher.ts

@@ -0,0 +1,102 @@
+import type { FSWatcher } from "node:fs";
+import { existsSync, mkdirSync, watch } from "node:fs";
+import { relative, resolve } from "node:path";
+import type { CronReconciler } from "./cron-reconciler";
+
+/**
+ * Filesystem watcher for the configured cron specs directory.
+ *
+ * Uses `node:fs` `watch` with `{ recursive: true }`. Emits a re-reconcile
+ * request for each change, debounced per path, so rapid save bursts from
+ * editors don't cause redundant DB churn.
+ */
+
+const DEFAULT_DEBOUNCE_MS = 250;
+
+export interface CronWatcherOptions {
+	reconciler: CronReconciler;
+	debounceMs?: number;
+	onError?: (error: unknown) => void;
+	onReconciled?: () => void | Promise<void>;
+}
+
+export class CronWatcher {
+	private readonly reconciler: CronReconciler;
+	private readonly debounceMs: number;
+	private readonly onError: (error: unknown) => void;
+	private readonly onReconciled: () => void | Promise<void>;
+	private watcher?: FSWatcher;
+	private readonly pending = new Map<string, ReturnType<typeof setTimeout>>();
+	private disposed = false;
+
+	constructor(options: CronWatcherOptions) {
+		this.reconciler = options.reconciler;
+		this.debounceMs = Math.max(0, options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+		this.onError = options.onError ?? (() => {});
+		this.onReconciled = options.onReconciled ?? (() => {});
+	}
+
+	public start(): void {
+		if (this.disposed) throw new Error("CronWatcher disposed");
+		if (this.watcher) return;
+		const dir = this.reconciler.getCronDir();
+		try {
+			mkdirSync(dir, { recursive: true });
+			this.watcher = watch(dir, { recursive: true }, (_eventType, filename) => {
+				if (!filename) return;
+				const rel = String(filename).replace(/\\/g, "/");
+				if (!rel.endsWith(".md")) return;
+				if (rel.startsWith("reports/")) return;
+				this.scheduleReconcile(rel);
+			});
+			this.watcher.on("error", this.onError);
+		} catch (err) {
+			this.onError(err);
+		}
+	}
+
+	public stop(): void {
+		for (const timer of this.pending.values()) clearTimeout(timer);
+		this.pending.clear();
+		this.watcher?.close();
+		this.watcher = undefined;
+	}
+
+	public dispose(): void {
+		this.disposed = true;
+		this.stop();
+	}
+
+	private scheduleReconcile(relativePath: string): void {
+		const existing = this.pending.get(relativePath);
+		if (existing) clearTimeout(existing);
+		const timer = setTimeout(() => {
+			this.pending.delete(relativePath);
+			void this.reconcileNow(relativePath);
+		}, this.debounceMs);
+		this.pending.set(relativePath, timer);
+	}
+
+	private async reconcileNow(relativePath: string): Promise<void> {
+		try {
+			const abs = resolve(this.reconciler.getCronDir(), relativePath);
+			if (!existsSync(abs)) {
+				// File was deleted — force a full reconcile to catch the
+				// missing source and mark the spec removed.
+				await this.reconciler.reconcileAll();
+				await this.onReconciled();
+				return;
+			}
+			// Normalize relative path through the reconciler dir to defend
+			// against a watcher emitting an unexpected format.
+			const normalizedRel = relative(this.reconciler.getCronDir(), abs).replace(
+				/\\/g,
+				"/",
+			);
+			await this.reconciler.reconcileFile(normalizedRel, abs);
+			await this.onReconciled();
+		} catch (err) {
+			this.onError(err);
+		}
+	}
+}

package/src/cron/index.ts

@@ -1,5 +1,15 @@
+export * from "./cron-event-ingress";
+export * from "./cron-materializer";
+export * from "./cron-reconciler";
+export * from "./cron-report-writer";
+export * from "./cron-runner";
+export * from "./cron-schema";
+export * from "./cron-service";
+export * from "./cron-spec-parser";
+export * from "./cron-watcher";
 export * from "./resource-limiter";
 export * from "./schedule-command-service";
 export * from "./schedule-service";
 export * from "./scheduler";
+export * from "./sqlite-cron-store";
 export * from "./sqlite-schedule-store";

package/src/cron/scheduler.ts

@@ -60,6 +60,9 @@ function parseCronField(
 					from = resolveValue(rangePart);
 				}
 			}
+			if (from > to) {
+				throw new Error(`Invalid cron range "${rangePart}"`);
+			}
 			for (let value = from; value <= to; value += step) {
 				results.add(value);
 			}
@@ -70,6 +73,9 @@ function parseCronField(
 		if (dashIndex !== -1) {
 			const from = resolveValue(part.slice(0, dashIndex));
 			const to = resolveValue(part.slice(dashIndex + 1));
+			if (from > to) {
+				throw new Error(`Invalid cron range "${part}"`);
+			}
 			for (let value = from; value <= to; value += 1) {
 				results.add(value);
 			}
@@ -107,6 +113,14 @@ export interface ParsedCron {
 	daysOfWeek: number[];
 }
 
+interface CronDateParts {
+	month: number;
+	dayOfMonth: number;
+	dayOfWeek: number;
+	hour: number;
+	minute: number;
+}
+
 function getRequiredField(
 	fields: readonly string[],
 	index: number,
@@ -159,7 +173,131 @@ export function validateCronPattern(pattern: string): void {
 	parseCron(pattern);
 }
 
-export function getNextCronTime(pattern: string, after: number): number {
+export function validateCronSchedule(
+	pattern: string,
+	timezone?: string,
+	after: number = Date.now(),
+): void {
+	getNextCronTime(pattern, after, timezone);
+}
+
+const TIMEZONE_FORMATTERS = new Map<string, Intl.DateTimeFormat>();
+const DOW_BY_SHORT_NAME = new Map(
+	DOW_NAMES.map((name, index) => [name, index] as const),
+);
+
+function normalizeTimezone(timezone: string | undefined): string | undefined {
+	const trimmed = timezone?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+function getTimezoneFormatter(timezone: string): Intl.DateTimeFormat {
+	const existing = TIMEZONE_FORMATTERS.get(timezone);
+	if (existing) return existing;
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone: timezone,
+		calendar: "gregory",
+		numberingSystem: "latn",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		weekday: "short",
+		hour: "2-digit",
+		minute: "2-digit",
+		hourCycle: "h23",
+	});
+	TIMEZONE_FORMATTERS.set(timezone, formatter);
+	return formatter;
+}
+
+export function validateTimezone(timezone: string | undefined): void {
+	const normalized = normalizeTimezone(timezone);
+	if (!normalized) return;
+	getTimezoneFormatter(normalized).format(new Date());
+}
+
+function getZonedCronDateParts(
+	timestampMs: number,
+	timezone: string,
+): CronDateParts {
+	const parts = getTimezoneFormatter(timezone).formatToParts(
+		new Date(timestampMs),
+	);
+	const byType = new Map(parts.map((part) => [part.type, part.value]));
+	const weekdayRaw = byType.get("weekday")?.toLowerCase().slice(0, 3) ?? "";
+	const dayOfWeek = DOW_BY_SHORT_NAME.get(
+		weekdayRaw as (typeof DOW_NAMES)[number],
+	);
+	if (dayOfWeek === undefined) {
+		throw new Error(`Unable to resolve weekday for timezone "${timezone}"`);
+	}
+	return {
+		month: Number(byType.get("month")),
+		dayOfMonth: Number(byType.get("day")),
+		dayOfWeek,
+		hour: Number(byType.get("hour")),
+		minute: Number(byType.get("minute")),
+	};
+}
+
+function getLocalCronDateParts(timestampMs: number): CronDateParts {
+	const date = new Date(timestampMs);
+	return {
+		month: date.getMonth() + 1,
+		dayOfMonth: date.getDate(),
+		dayOfWeek: date.getDay(),
+		hour: date.getHours(),
+		minute: date.getMinutes(),
+	};
+}
+
+function cronMatchesParts(cron: ParsedCron, parts: CronDateParts): boolean {
+	return (
+		cron.months.includes(parts.month) &&
+		cron.daysOfMonth.includes(parts.dayOfMonth) &&
+		cron.daysOfWeek.includes(parts.dayOfWeek) &&
+		cron.hours.includes(parts.hour) &&
+		cron.minutes.includes(parts.minute)
+	);
+}
+
+function getNextCronTimeByMinuteScan(
+	pattern: string,
+	after: number,
+	timezone: string,
+): number {
+	const cron = parseCron(pattern);
+	const next = new Date(after);
+	next.setSeconds(0, 0);
+	let nextMs = next.getTime() + 60_000;
+
+	const limit = new Date(after);
+	limit.setFullYear(limit.getFullYear() + 4);
+	const limitMs = limit.getTime();
+
+	while (nextMs <= limitMs) {
+		if (cronMatchesParts(cron, getZonedCronDateParts(nextMs, timezone))) {
+			return nextMs;
+		}
+		nextMs += 60_000;
+	}
+
+	throw new Error(
+		`No cron occurrence found within 4 years for pattern "${pattern}" in timezone "${timezone}"`,
+	);
+}
+
+export function getNextCronTime(
+	pattern: string,
+	after: number,
+	timezone?: string,
+): number {
+	const normalizedTimezone = normalizeTimezone(timezone);
+	if (normalizedTimezone) {
+		validateTimezone(normalizedTimezone);
+		return getNextCronTimeByMinuteScan(pattern, after, normalizedTimezone);
+	}
+
 	const cron = parseCron(pattern);
 	let next = new Date(after);
 	next.setSeconds(0, 0);
@@ -169,11 +307,8 @@ export function getNextCronTime(pattern: string, after: number): number {
 	limit.setFullYear(limit.getFullYear() + 4);
 
 	while (next <= limit) {
-		const month = next.getMonth() + 1;
-		const dayOfMonth = next.getDate();
-		const dayOfWeek = next.getDay();
-		const hour = next.getHours();
-		const minute = next.getMinutes();
+		const { month, dayOfMonth, dayOfWeek, hour, minute } =
+			getLocalCronDateParts(next.getTime());
 
 		if (!cron.months.includes(month)) {
 			const targetMonth =