@clinebot/core 0.0.37 → 0.0.38

package/src/cron/cron-event-ingress.ts

@@ -1,357 +0,0 @@
-import type { AutomationEventEnvelope, BasicLogger } from "@clinebot/shared";
-import type {
-	CronEventLogRecord,
-	CronRunRecord,
-	CronSpecRecord,
-	SqliteCronStore,
-} from "./sqlite-cron-store";
-
-/**
- * Durable ingress for normalized automation events.
- *
- * This layer persists the incoming event before matching, then materializes
- * queued `cron_runs` for matching event specs. It deliberately does not
- * execute agents; the normal runner claim loop owns execution.
- */
-
-export interface CronEventIngressOptions {
-	store: SqliteCronStore;
-	now?: () => number;
-	logger?: BasicLogger;
-}
-
-export type CronEventSuppressionReason =
-	| "duplicate_event"
-	| "filter_mismatch"
-	| "dedupe_window"
-	| "cooldown";
-
-export interface CronEventSuppression {
-	specId?: string;
-	externalId?: string;
-	reason: CronEventSuppressionReason;
-	dedupeKey?: string;
-}
-
-export interface CronEventIngressResult {
-	event: CronEventLogRecord;
-	duplicate: boolean;
-	matchedSpecs: CronSpecRecord[];
-	queuedRuns: CronRunRecord[];
-	suppressions: CronEventSuppression[];
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function trimOrUndefined(value: string | undefined): string | undefined {
-	const trimmed = value?.trim();
-	return trimmed ? trimmed : undefined;
-}
-
-function normalizeIso(value: string | undefined, fallback: string): string {
-	const candidate = value?.trim();
-	if (!candidate) return fallback;
-	const ms = Date.parse(candidate);
-	if (!Number.isFinite(ms)) return fallback;
-	return new Date(ms).toISOString();
-}
-
-function addSeconds(iso: string, seconds: number): string {
-	return new Date(
-		new Date(iso).getTime() + Math.max(0, Math.floor(seconds)) * 1000,
-	).toISOString();
-}
-
-function subtractSeconds(iso: string, seconds: number): string {
-	return new Date(
-		new Date(iso).getTime() - Math.max(0, Math.floor(seconds)) * 1000,
-	).toISOString();
-}
-
-function maxIso(a: string | undefined, b: string): string {
-	if (!a) return b;
-	return new Date(a).getTime() >= new Date(b).getTime() ? a : b;
-}
-
-function normalizeEvent(
-	event: AutomationEventEnvelope,
-	receivedAt: string,
-): AutomationEventEnvelope {
-	const eventId = event.eventId.trim();
-	const eventType = event.eventType.trim();
-	const source = event.source.trim();
-	const subject = trimOrUndefined(event.subject);
-	const dedupeKey =
-		trimOrUndefined(event.dedupeKey) ??
-		`${eventType}:${source}:${subject ?? eventId}`;
-	return {
-		eventId,
-		eventType,
-		source,
-		subject,
-		occurredAt: normalizeIso(event.occurredAt, receivedAt),
-		workspaceRoot: trimOrUndefined(event.workspaceRoot),
-		payload: isRecord(event.payload) ? event.payload : undefined,
-		attributes: isRecord(event.attributes) ? event.attributes : undefined,
-		dedupeKey,
-	};
-}
-
-function getPath(value: unknown, path: string): unknown {
-	if (!path) return undefined;
-	const parts = path.split(".");
-	let current: unknown = value;
-	for (const part of parts) {
-		if (!isRecord(current)) return undefined;
-		current = current[part];
-	}
-	return current;
-}
-
-function resolveFilterValue(
-	event: AutomationEventEnvelope,
-	filterKey: string,
-): unknown {
-	if (event.attributes && Object.hasOwn(event.attributes, filterKey)) {
-		return event.attributes[filterKey];
-	}
-	if (event.payload && Object.hasOwn(event.payload, filterKey)) {
-		return event.payload[filterKey];
-	}
-	const candidate = {
-		eventId: event.eventId,
-		eventType: event.eventType,
-		source: event.source,
-		subject: event.subject,
-		occurredAt: event.occurredAt,
-		workspaceRoot: event.workspaceRoot,
-		dedupeKey: event.dedupeKey,
-		attributes: event.attributes,
-		payload: event.payload,
-	};
-	const direct = getPath(candidate, filterKey);
-	if (direct !== undefined) return direct;
-	if (event.attributes) {
-		const fromAttributes = getPath(event.attributes, filterKey);
-		if (fromAttributes !== undefined) return fromAttributes;
-	}
-	if (event.payload) {
-		return getPath(event.payload, filterKey);
-	}
-	return undefined;
-}
-
-function matchesExpected(actual: unknown, expected: unknown): boolean {
-	if (Array.isArray(expected)) {
-		return expected.some((item) => matchesExpected(actual, item));
-	}
-	if (Array.isArray(actual)) {
-		return actual.some((item) => matchesExpected(item, expected));
-	}
-	if (isRecord(expected)) {
-		if (!isRecord(actual)) return false;
-		return Object.entries(expected).every(([key, value]) =>
-			matchesExpected(actual[key], value),
-		);
-	}
-	return Object.is(actual, expected);
-}
-
-export function automationEventMatchesFilters(
-	event: AutomationEventEnvelope,
-	filters: Record<string, unknown> | undefined,
-): boolean {
-	if (!filters || Object.keys(filters).length === 0) return true;
-	return Object.entries(filters).every(([key, expected]) =>
-		matchesExpected(resolveFilterValue(event, key), expected),
-	);
-}
-
-export class CronEventIngress {
-	private readonly store: SqliteCronStore;
-	private readonly nowFn: () => number;
-	private readonly logger?: BasicLogger;
-
-	constructor(options: CronEventIngressOptions) {
-		this.store = options.store;
-		this.nowFn = options.now ?? (() => Date.now());
-		this.logger = options.logger;
-	}
-
-	public ingestEvent(event: AutomationEventEnvelope): CronEventIngressResult {
-		const receivedAt = new Date(this.nowFn()).toISOString();
-		const normalized = normalizeEvent(event, receivedAt);
-		const inserted = this.store.insertEventLog(normalized, {
-			receivedAtIso: receivedAt,
-		});
-		if (!inserted.created) {
-			this.logger?.debug("cron.event.duplicate", {
-				eventId: inserted.record.eventId,
-				eventType: inserted.record.eventType,
-				source: inserted.record.source,
-			});
-			return {
-				event: inserted.record,
-				duplicate: true,
-				matchedSpecs: [],
-				queuedRuns: [],
-				suppressions: [
-					{
-						reason: "duplicate_event",
-						dedupeKey: inserted.record.dedupeKey,
-					},
-				],
-			};
-		}
-
-		try {
-			const allCandidateSpecs = this.store.listEventSpecsForType(
-				normalized.eventType,
-			);
-			const suppressions: CronEventSuppression[] = [];
-			const matchedSpecs: CronSpecRecord[] = [];
-			const queuedRuns: CronRunRecord[] = [];
-
-			for (const spec of allCandidateSpecs) {
-				if (!automationEventMatchesFilters(normalized, spec.filters)) {
-					suppressions.push({
-						specId: spec.specId,
-						externalId: spec.externalId,
-						reason: "filter_mismatch",
-						dedupeKey: normalized.dedupeKey,
-					});
-					continue;
-				}
-				matchedSpecs.push(spec);
-				const run = this.materializeForSpec(
-					spec,
-					normalized,
-					inserted.record.receivedAt,
-				);
-				if (run.run) {
-					queuedRuns.push(run.run);
-				} else {
-					suppressions.push({
-						specId: spec.specId,
-						externalId: spec.externalId,
-						reason: run.reason,
-						dedupeKey: normalized.dedupeKey,
-					});
-				}
-			}
-
-			const status =
-				matchedSpecs.length === 0
-					? "unmatched"
-					: queuedRuns.length > 0
-						? "queued"
-						: "suppressed";
-			this.store.updateEventLogProcessing(inserted.record.eventId, {
-				status,
-				matchedSpecCount: matchedSpecs.length,
-				queuedRunCount: queuedRuns.length,
-				suppressedCount: suppressions.filter(
-					(s) => s.reason !== "filter_mismatch",
-				).length,
-			});
-			const updated = this.store.getEventLog(inserted.record.eventId);
-			this.logger?.debug("cron.event.processed", {
-				eventId: inserted.record.eventId,
-				eventType: inserted.record.eventType,
-				status,
-				matchedSpecCount: matchedSpecs.length,
-				queuedRunCount: queuedRuns.length,
-			});
-			return {
-				event: updated ?? inserted.record,
-				duplicate: false,
-				matchedSpecs,
-				queuedRuns,
-				suppressions,
-			};
-		} catch (err) {
-			this.store.updateEventLogProcessing(inserted.record.eventId, {
-				status: "failed",
-				error: err instanceof Error ? err.message : String(err),
-			});
-			if (this.logger?.error) {
-				this.logger.error("cron.event.failed", {
-					eventId: inserted.record.eventId,
-					eventType: inserted.record.eventType,
-					error: err,
-				});
-			}
-			throw err;
-		}
-	}
-
-	private materializeForSpec(
-		spec: CronSpecRecord,
-		event: AutomationEventEnvelope,
-		receivedAt: string,
-	): {
-		run?: CronRunRecord;
-		reason: Exclude<
-			CronEventSuppressionReason,
-			"duplicate_event" | "filter_mismatch"
-		>;
-	} {
-		const dedupeKey = event.dedupeKey ?? event.eventId;
-		const debounceSeconds = spec.debounceSeconds ?? 0;
-		if (debounceSeconds > 0) {
-			const existing = this.store.findQueuedEventRunForDedupe({
-				specId: spec.specId,
-				dedupeKey,
-			});
-			if (existing) {
-				const scheduledFor = maxIso(
-					existing.scheduledFor,
-					addSeconds(receivedAt, debounceSeconds),
-				);
-				const updated = this.store.updateQueuedEventRunForDebounce({
-					runId: existing.runId,
-					triggerEventId: event.eventId,
-					scheduledFor,
-				});
-				if (updated) return { run: updated, reason: "dedupe_window" };
-			}
-		}
-
-		const dedupeWindowSeconds = spec.dedupeWindowSeconds ?? 0;
-		if (
-			dedupeWindowSeconds > 0 &&
-			this.store.hasRecentEventRunForDedupe({
-				specId: spec.specId,
-				dedupeKey,
-				sinceIso: subtractSeconds(receivedAt, dedupeWindowSeconds),
-			})
-		) {
-			return { reason: "dedupe_window" };
-		}
-
-		const cooldownSeconds = spec.cooldownSeconds ?? 0;
-		if (
-			cooldownSeconds > 0 &&
-			this.store.hasRecentEventRunForSpec({
-				specId: spec.specId,
-				sinceIso: subtractSeconds(receivedAt, cooldownSeconds),
-			})
-		) {
-			return { reason: "cooldown" };
-		}
-
-		const run = this.store.enqueueRun({
-			specId: spec.specId,
-			specRevision: spec.revision,
-			triggerKind: "event",
-			triggerEventId: event.eventId,
-			scheduledFor:
-				debounceSeconds > 0
-					? addSeconds(receivedAt, debounceSeconds)
-					: receivedAt,
-		});
-		return { run, reason: "dedupe_window" };
-	}
-}

package/src/cron/cron-materializer.ts

@@ -1,97 +0,0 @@
-import type { CronSpecRecord, SqliteCronStore } from "./sqlite-cron-store";
-
-/**
- * Queue materialization rules shared between the reconciler, watcher, and
- * periodic runner tick. Execution stays trigger-agnostic once a row is
- * queued; this module is the only place that decides when to create a row.
- */
-
-export interface CronMaterializerOptions {
-	store: SqliteCronStore;
-	now?: () => number;
-}
-
-export interface MaterializeSummary {
-	oneOffQueued: number;
-	scheduleQueued: number;
-}
-
-export class CronMaterializer {
-	private readonly store: SqliteCronStore;
-	private readonly nowFn: () => number;
-
-	constructor(options: CronMaterializerOptions) {
-		this.store = options.store;
-		this.nowFn = options.now ?? (() => Date.now());
-	}
-
-	/**
-	 * Run materialization for every valid/enabled spec. Typically called at
-	 * startup (after reconciliation) and on each runner tick.
-	 */
-	public materializeAll(): MaterializeSummary {
-		const summary: MaterializeSummary = {
-			oneOffQueued: 0,
-			scheduleQueued: 0,
-		};
-
-		const oneOffs = this.store.listSpecs({
-			triggerKind: "one_off",
-			enabled: true,
-			parseStatus: "valid",
-		});
-		for (const spec of oneOffs) {
-			if (this.materializeOneOff(spec)) summary.oneOffQueued += 1;
-		}
-
-		const schedules = this.store.listSpecs({
-			triggerKind: "schedule",
-			enabled: true,
-			parseStatus: "valid",
-		});
-		for (const spec of schedules) {
-			try {
-				if (this.materializeSchedule(spec)) summary.scheduleQueued += 1;
-			} catch {
-				// Keep one stale/invalid persisted schedule from blocking other specs.
-			}
-		}
-
-		return summary;
-	}
-
-	/**
-	 * Ensure a single one-off spec has exactly one run record for its current
-	 * revision unless an explicit rerun path creates a different trigger kind.
-	 * Returns true if a new queued run was created.
-	 */
-	public materializeOneOff(spec: CronSpecRecord): boolean {
-		if (spec.triggerKind !== "one_off") return false;
-		if (!spec.enabled || spec.removed) return false;
-		if (this.store.hasOneOffRunForRevision(spec.specId, spec.revision)) {
-			return false;
-		}
-		this.store.enqueueRun({
-			specId: spec.specId,
-			specRevision: spec.revision,
-			triggerKind: "one_off",
-			scheduledFor: new Date(this.nowFn()).toISOString(),
-		});
-		return true;
-	}
-
-	/**
-	 * Materialize schedule runs. Implements the "one overdue catch-up on
-	 * startup, then advance" policy described in PLAN.md.
-	 */
-	public materializeSchedule(spec: CronSpecRecord): boolean {
-		if (spec.triggerKind !== "schedule") return false;
-		if (!spec.enabled || spec.removed) return false;
-		if (!spec.scheduleExpr) return false;
-
-		return this.store.materializeDueScheduleRun({
-			specId: spec.specId,
-			nowMs: this.nowFn(),
-		}).queued;
-	}
-}

package/src/cron/cron-reconciler.ts

@@ -1,241 +0,0 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { relative } from "node:path";
-import type { CronSpecParseResult } from "@clinebot/shared";
-import {
-	type ResolveCronSpecsDirOptions,
-	resolveCronSpecsDir,
-} from "@clinebot/shared/storage";
-import { type ParseCronSpecInput, parseCronSpecFile } from "./cron-spec-parser";
-import { getNextCronTime } from "./scheduler";
-import type {
-	CronSpecRecord,
-	SqliteCronStore,
-	UpsertSpecResult,
-} from "./sqlite-cron-store";
-
-/**
- * Scan the configured cron specs directory on disk, parse every file, and
- * upsert spec state into the cron DB. This is the startup source of truth:
- * watcher events are triggers to re-run reconciliation for one file, not a
- * replacement.
- */
-
-export interface CronReconcilerOptions {
-	store: SqliteCronStore;
-	/**
-	 * Cron spec source location. Defaults to global `~/.cline/cron`.
-	 * Pass `{ scope: "workspace", workspaceRoot }` later to enable
-	 * workspace-level cron sources without changing reconciler internals.
-	 */
-	specs?: ResolveCronSpecsDirOptions;
-	/** @deprecated Use `specs: { scope: "workspace", workspaceRoot }`. */
-	workspaceRoot?: string;
-}
-
-export interface ReconcileChange {
-	relativePath: string;
-	result: UpsertSpecResult;
-	parse: CronSpecParseResult;
-}
-
-export interface ReconcileSummary {
-	scanned: number;
-	upserted: number;
-	invalidParses: number;
-	removed: number;
-	changes: ReconcileChange[];
-}
-
-function toPosixRelative(fromDir: string, absolutePath: string): string {
-	return relative(fromDir, absolutePath).replace(/\\/g, "/");
-}
-
-function walk(dir: string): string[] {
-	if (!existsSync(dir)) return [];
-	const result: string[] = [];
-	const stack: string[] = [dir];
-	while (stack.length > 0) {
-		const current = stack.pop();
-		if (!current) continue;
-		let entries: import("node:fs").Dirent[];
-		try {
-			entries = readdirSync(current, { withFileTypes: true });
-		} catch {
-			continue;
-		}
-		for (const entry of entries) {
-			const full = `${current}/${entry.name}`;
-			if (entry.isDirectory()) {
-				// Skip the generated reports subdirectory — not spec sources.
-				if (entry.name === "reports") continue;
-				stack.push(full);
-				continue;
-			}
-			if (!entry.isFile()) continue;
-			if (!entry.name.endsWith(".md")) continue;
-			result.push(full);
-		}
-	}
-	return result;
-}
-
-export class CronReconciler {
-	private readonly store: SqliteCronStore;
-	private readonly cronDir: string;
-
-	constructor(options: CronReconcilerOptions) {
-		this.store = options.store;
-		this.cronDir = resolveCronSpecsDir(
-			options.specs ??
-				(options.workspaceRoot
-					? { scope: "workspace", workspaceRoot: options.workspaceRoot }
-					: undefined),
-		);
-	}
-
-	public getCronDir(): string {
-		return this.cronDir;
-	}
-
-	/**
-	 * Reconcile every file under the cron specs directory into the DB and mark specs
-	 * whose source files no longer exist as `removed=1`.
-	 */
-	public async reconcileAll(): Promise<ReconcileSummary> {
-		const summary: ReconcileSummary = {
-			scanned: 0,
-			upserted: 0,
-			invalidParses: 0,
-			removed: 0,
-			changes: [],
-		};
-
-		const files = walk(this.cronDir);
-		const seenPaths = new Set<string>();
-
-		for (const abs of files) {
-			const rel = toPosixRelative(this.cronDir, abs);
-			seenPaths.add(rel);
-			summary.scanned += 1;
-			const change = await this.reconcileFile(rel, abs);
-			if (change) {
-				summary.changes.push(change);
-				summary.upserted += 1;
-				if (change.parse.error) summary.invalidParses += 1;
-			}
-		}
-
-		const existing = this.store.listSpecs({
-			includeRemoved: false,
-			limit: 10_000,
-		});
-		for (const spec of existing) {
-			if (!seenPaths.has(spec.sourcePath)) {
-				this.handleFileDeleted(spec);
-				summary.removed += 1;
-			}
-		}
-
-		this.refreshScheduleNextRunAt();
-
-		return summary;
-	}
-
-	/**
-	 * Reconcile a single file (absolute path). `relativePath` is expected to
-	 * be POSIX-relative to the cron specs directory. Returns the reconciliation change
-	 * or undefined if the file could not be read.
-	 */
-	public async reconcileFile(
-		relativePath: string,
-		absolutePath: string,
-	): Promise<ReconcileChange | undefined> {
-		const existing = this.store.getSpecBySourcePath(relativePath);
-		let raw: string;
-		let mtimeMs: number | undefined;
-		try {
-			raw = readFileSync(absolutePath, "utf8");
-			mtimeMs = statSync(absolutePath).mtimeMs;
-		} catch {
-			return undefined;
-		}
-		const input: ParseCronSpecInput = { relativePath, raw };
-		const parse = parseCronSpecFile(input);
-		const result = this.store.upsertSpec({
-			externalId: parse.externalId,
-			sourcePath: relativePath,
-			triggerKind: parse.triggerKind,
-			sourceMtimeMs: mtimeMs,
-			sourceHash: parse.contentHash,
-			parseStatus: parse.error ? "invalid" : "valid",
-			parseError: parse.error,
-			spec: parse.spec,
-		});
-
-		// For valid schedule specs, compute next_run_at if missing or reset
-		// when schedule_expr changed.
-		if (
-			!parse.error &&
-			parse.triggerKind === "schedule" &&
-			result.record.enabled
-		) {
-			this.applyScheduleNextRunAt(result.record, {
-				forceReset:
-					!existing ||
-					existing.removed ||
-					!existing.enabled ||
-					existing.scheduleExpr !== result.record.scheduleExpr ||
-					existing.timezone !== result.record.timezone,
-			});
-		}
-
-		return { relativePath, result, parse };
-	}
-
-	/**
-	 * Handle a file that disappeared from disk between reconciliations.
-	 * Marks the spec as removed and cancels any queued runs for it.
-	 */
-	public handleFileDeleted(spec: CronSpecRecord): void {
-		this.store.markSpecRemoved(spec.specId);
-		this.store.cancelQueuedRunsForSpec(spec.specId);
-	}
-
-	/**
-	 * Refresh next_run_at for every enabled schedule spec.
-	 * Used at startup to handle the "one overdue catch-up on startup then
-	 * advance to next slot" policy.
-	 */
-	public refreshScheduleNextRunAt(): void {
-		const schedules = this.store.listSpecs({
-			triggerKind: "schedule",
-			enabled: true,
-			parseStatus: "valid",
-		});
-		for (const spec of schedules) {
-			this.applyScheduleNextRunAt(spec, { forceReset: false });
-		}
-	}
-
-	private applyScheduleNextRunAt(
-		spec: CronSpecRecord,
-		options: { forceReset: boolean },
-	): void {
-		if (!spec.scheduleExpr) return;
-		if (!options.forceReset && spec.nextRunAt) return;
-		try {
-			const now = Date.now();
-			const base = spec.lastRunAt
-				? Math.max(now, new Date(spec.lastRunAt).getTime())
-				: now;
-			const nextMs = getNextCronTime(spec.scheduleExpr, base, spec.timezone);
-			const nextIso = new Date(nextMs).toISOString();
-			if (spec.nextRunAt !== nextIso) {
-				this.store.updateSpecNextRunAt(spec.specId, nextIso);
-			}
-		} catch {
-			// Invalid cron pattern — leave next_run_at as is; the upsert's
-			// parse_status already reflects the spec correctness.
-		}
-	}
-}