codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/packages/core/src/cron/specs/cron-spec-parser.ts

@@ -0,0 +1,489 @@
+import { createHash } from "node:crypto";
+import type {
+	CronEventSpec,
+	CronOneOffSpec,
+	CronScheduleSpec,
+	CronSpec,
+	CronSpecExtensionKind,
+	CronSpecMode,
+	CronSpecParseResult,
+	CronTriggerKind,
+} from "@cline/shared";
+import YAML from "yaml";
+import { ALL_DEFAULT_TOOL_NAMES } from "../../extensions/tools/constants";
+import { validateCronSchedule } from "../schedule/scheduler";
+
+/**
+ * Markdown frontmatter parser for `.cline/cron/*.md` automation specs.
+ *
+ * Lives in @cline/core because it depends on `yaml`. The spec types
+ * themselves live in @cline/shared so other packages can consume them
+ * without pulling in a YAML parser.
+ *
+ * The parser never throws for a single bad file — it produces a
+ * `CronSpecParseResult` with an `error` message so the reconciler can record
+ * `parse_status='invalid'` durably instead of dropping state.
+ */
+
+export function inferTriggerKindFromPath(
+	relativePath: string,
+): CronTriggerKind {
+	const normalized = relativePath.replace(/\\/g, "/");
+	if (normalized.startsWith("events/") && normalized.endsWith(".event.md")) {
+		return "event";
+	}
+	if (normalized.endsWith(".cron.md")) {
+		return "schedule";
+	}
+	return "one_off";
+}
+
+export function splitFrontmatter(raw: string): {
+	frontmatter: string | undefined;
+	body: string;
+} {
+	const text = raw.replace(/\r\n/g, "\n");
+	if (!text.startsWith("---\n")) {
+		return { frontmatter: undefined, body: raw };
+	}
+	const afterOpen = text.slice(4);
+	const closeIdx = afterOpen.indexOf("\n---");
+	if (closeIdx === -1) {
+		return { frontmatter: undefined, body: raw };
+	}
+	const frontmatter = afterOpen.slice(0, closeIdx);
+	let rest = afterOpen.slice(closeIdx + 4);
+	if (rest.startsWith("\n")) rest = rest.slice(1);
+	return { frontmatter, body: rest };
+}
+
+function trimOrUndefined(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeTags(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const tags = value
+		.map((item) => (typeof item === "string" ? item.trim() : ""))
+		.filter((item) => item.length > 0);
+	return tags.length > 0 ? tags : undefined;
+}
+
+function normalizeRecord(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return undefined;
+	}
+	return value as Record<string, unknown>;
+}
+
+function normalizeModelSelection(
+	value: unknown,
+): { providerId?: string; modelId?: string } | undefined {
+	const obj = normalizeRecord(value);
+	if (!obj) return undefined;
+	const providerId = trimOrUndefined(obj.providerId);
+	const modelId = trimOrUndefined(obj.modelId);
+	if (providerId === undefined && modelId === undefined) return undefined;
+	return { providerId, modelId };
+}
+
+function normalizeMode(value: unknown): CronSpecMode | undefined {
+	if (typeof value !== "string") return undefined;
+	const lower = value.trim().toLowerCase();
+	if (lower === "act" || lower === "plan" || lower === "yolo") return lower;
+	return undefined;
+}
+
+function normalizeStringList(
+	value: unknown,
+	options: { preserveEmptyArray?: boolean } = {},
+): string[] | undefined {
+	const raw = Array.isArray(value)
+		? value
+		: typeof value === "string"
+			? value.split(",")
+			: undefined;
+	if (!raw) return undefined;
+	const normalized = [
+		...new Set(
+			raw
+				.map((item) => (typeof item === "string" ? item.trim() : ""))
+				.filter((item) => item.length > 0),
+		),
+	];
+	if (Array.isArray(value) && options.preserveEmptyArray) {
+		return normalized;
+	}
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+const DEFAULT_TOOL_NAME_SET = new Set<string>(ALL_DEFAULT_TOOL_NAMES);
+
+function normalizeToolList(value: unknown): string[] | undefined {
+	const tools = normalizeStringList(value, { preserveEmptyArray: true });
+	if (!tools) return undefined;
+	const invalid = tools.filter((tool) => !DEFAULT_TOOL_NAME_SET.has(tool));
+	if (invalid.length > 0) {
+		throw new Error(`unknown tool(s): ${invalid.join(", ")}`);
+	}
+	return tools;
+}
+
+const CRON_EXTENSION_KINDS = new Set<CronSpecExtensionKind>([
+	"rules",
+	"skills",
+	"plugins",
+]);
+
+function normalizeExtensions(
+	value: unknown,
+): CronSpecExtensionKind[] | undefined {
+	const extensions = normalizeStringList(value, { preserveEmptyArray: true });
+	if (!extensions) return undefined;
+	const invalid = extensions.filter(
+		(extension) =>
+			!CRON_EXTENSION_KINDS.has(extension as CronSpecExtensionKind),
+	);
+	if (invalid.length > 0) {
+		throw new Error(`unknown extension(s): ${invalid.join(", ")}`);
+	}
+	return extensions as CronSpecExtensionKind[];
+}
+
+function asPositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+		return undefined;
+	}
+	return Math.floor(value);
+}
+
+function asNonNegativeInt(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		return undefined;
+	}
+	return Math.floor(value);
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object") {
+		return JSON.stringify(value ?? null);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	}
+	const entries = Object.entries(value as Record<string, unknown>).filter(
+		([, v]) => v !== undefined,
+	);
+	entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	return `{${entries
+		.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+		.join(",")}}`;
+}
+
+export function computeContentHash(
+	frontmatterJson: unknown,
+	body: string,
+): string {
+	const hash = createHash("sha256");
+	hash.update(stableStringify(frontmatterJson));
+	hash.update("\n");
+	hash.update(body);
+	return hash.digest("hex");
+}
+
+function filenameStem(relativePath: string): string {
+	const base = relativePath.split("/").pop() ?? relativePath;
+	return base
+		.replace(/\.event\.md$/, "")
+		.replace(/\.cron\.md$/, "")
+		.replace(/\.md$/, "");
+}
+
+const SCHEDULE_ONLY_FIELDS = ["schedule", "timezone"] as const;
+const EVENT_ONLY_FIELDS = [
+	"event",
+	"filters",
+	"debounceSeconds",
+	"dedupeWindowSeconds",
+	"cooldownSeconds",
+	"maxParallel",
+] as const;
+const REMOVED_FIELDS = ["cwd"] as const;
+
+export interface ParseCronSpecInput {
+	relativePath: string;
+	raw: string;
+}
+
+function invalid(
+	relativePath: string,
+	triggerKind: CronTriggerKind,
+	body: string,
+	frontmatter: Record<string, unknown>,
+	error: string,
+): CronSpecParseResult {
+	return {
+		externalId: relativePath,
+		relativePath,
+		triggerKind,
+		body,
+		contentHash: computeContentHash(frontmatter, body),
+		error,
+	};
+}
+
+function invalidWithHash(
+	externalId: string,
+	relativePath: string,
+	triggerKind: CronTriggerKind,
+	body: string,
+	contentHash: string,
+	error: string,
+): CronSpecParseResult {
+	return {
+		externalId,
+		relativePath,
+		triggerKind,
+		body,
+		contentHash,
+		error,
+	};
+}
+
+/**
+ * Parse a single cron spec file. Never throws; always returns a result.
+ */
+export function parseCronSpecFile(
+	input: ParseCronSpecInput,
+): CronSpecParseResult {
+	const relativePath = input.relativePath.replace(/\\/g, "/");
+	const triggerKind = inferTriggerKindFromPath(relativePath);
+	const { frontmatter, body } = splitFrontmatter(input.raw);
+
+	let frontmatterData: Record<string, unknown> = {};
+	if (frontmatter !== undefined && frontmatter.trim().length > 0) {
+		try {
+			const parsed = YAML.parse(frontmatter) as unknown;
+			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+				frontmatterData = parsed as Record<string, unknown>;
+			} else if (parsed !== null && parsed !== undefined) {
+				return invalid(
+					relativePath,
+					triggerKind,
+					body,
+					{},
+					"frontmatter must be a YAML mapping",
+				);
+			}
+		} catch (err) {
+			return invalid(
+				relativePath,
+				triggerKind,
+				body,
+				{},
+				err instanceof Error
+					? `failed to parse frontmatter: ${err.message}`
+					: "failed to parse frontmatter",
+			);
+		}
+	}
+
+	const contentHash = computeContentHash(frontmatterData, body);
+	const externalIdRaw = trimOrUndefined(frontmatterData.id);
+	const externalId = externalIdRaw ?? relativePath;
+
+	if (triggerKind !== "schedule") {
+		for (const key of SCHEDULE_ONLY_FIELDS) {
+			if (frontmatterData[key] !== undefined) {
+				return invalidWithHash(
+					externalId,
+					relativePath,
+					triggerKind,
+					body,
+					contentHash,
+					`field "${key}" is only allowed on *.cron.md specs`,
+				);
+			}
+		}
+	}
+	for (const key of REMOVED_FIELDS) {
+		if (frontmatterData[key] !== undefined) {
+			return invalidWithHash(
+				externalId,
+				relativePath,
+				triggerKind,
+				body,
+				contentHash,
+				`field "${key}" is no longer supported; cron specs use workspaceRoot as cwd`,
+			);
+		}
+	}
+	if (triggerKind !== "event") {
+		for (const key of EVENT_ONLY_FIELDS) {
+			if (frontmatterData[key] !== undefined) {
+				return invalidWithHash(
+					externalId,
+					relativePath,
+					triggerKind,
+					body,
+					contentHash,
+					`field "${key}" is only allowed on .event.md specs`,
+				);
+			}
+		}
+	}
+
+	const frontmatterPrompt = trimOrUndefined(frontmatterData.prompt);
+	const bodyTrimmed = body.trim();
+	const prompt =
+		frontmatterPrompt ?? (bodyTrimmed.length > 0 ? bodyTrimmed : undefined);
+	if (!prompt) {
+		return invalidWithHash(
+			externalId,
+			relativePath,
+			triggerKind,
+			body,
+			contentHash,
+			"prompt is required (frontmatter `prompt` or markdown body)",
+		);
+	}
+
+	const workspaceRoot = trimOrUndefined(frontmatterData.workspaceRoot);
+	if (!workspaceRoot) {
+		return invalidWithHash(
+			externalId,
+			relativePath,
+			triggerKind,
+			body,
+			contentHash,
+			"workspaceRoot is required",
+		);
+	}
+
+	let tools: string[] | undefined;
+	let extensions: CronSpecExtensionKind[] | undefined;
+	try {
+		tools = normalizeToolList(frontmatterData.tools);
+		extensions = normalizeExtensions(frontmatterData.extensions);
+	} catch (err) {
+		return invalidWithHash(
+			externalId,
+			relativePath,
+			triggerKind,
+			body,
+			contentHash,
+			err instanceof Error ? err.message : String(err),
+		);
+	}
+
+	const mode = normalizeMode(frontmatterData.mode);
+	if (frontmatterData.mode !== undefined && mode === undefined) {
+		return invalidWithHash(
+			externalId,
+			relativePath,
+			triggerKind,
+			body,
+			contentHash,
+			"mode must be one of: act, plan, yolo",
+		);
+	}
+
+	const common = {
+		id: externalIdRaw,
+		title:
+			trimOrUndefined(frontmatterData.title) ??
+			externalIdRaw ??
+			filenameStem(relativePath),
+		prompt,
+		workspaceRoot,
+		mode: mode ?? "yolo",
+		systemPrompt: trimOrUndefined(frontmatterData.systemPrompt),
+		modelSelection: normalizeModelSelection(frontmatterData.modelSelection),
+		maxIterations: asPositiveInt(frontmatterData.maxIterations),
+		timeoutSeconds: asPositiveInt(frontmatterData.timeoutSeconds),
+		tools,
+		notesDirectory: trimOrUndefined(frontmatterData.notesDirectory),
+		extensions,
+		source: trimOrUndefined(frontmatterData.source) ?? "user",
+		tags: normalizeTags(frontmatterData.tags),
+		enabled:
+			typeof frontmatterData.enabled === "boolean"
+				? frontmatterData.enabled
+				: true,
+		metadata: normalizeRecord(frontmatterData.metadata),
+	};
+
+	let spec: CronSpec;
+	if (triggerKind === "schedule") {
+		const schedule = trimOrUndefined(frontmatterData.schedule);
+		if (!schedule) {
+			return invalidWithHash(
+				externalId,
+				relativePath,
+				triggerKind,
+				body,
+				contentHash,
+				"schedule is required for *.cron.md specs",
+			);
+		}
+		const timezone = trimOrUndefined(frontmatterData.timezone);
+		try {
+			validateCronSchedule(schedule, timezone);
+		} catch (err) {
+			return invalidWithHash(
+				externalId,
+				relativePath,
+				triggerKind,
+				body,
+				contentHash,
+				err instanceof Error ? err.message : String(err),
+			);
+		}
+		const s: CronScheduleSpec = {
+			...common,
+			triggerKind: "schedule",
+			schedule,
+			timezone,
+		};
+		spec = s;
+	} else if (triggerKind === "event") {
+		const event = trimOrUndefined(frontmatterData.event);
+		if (!event) {
+			return invalidWithHash(
+				externalId,
+				relativePath,
+				triggerKind,
+				body,
+				contentHash,
+				"event is required for .event.md specs",
+			);
+		}
+		const e: CronEventSpec = {
+			...common,
+			triggerKind: "event",
+			event,
+			filters: normalizeRecord(frontmatterData.filters),
+			debounceSeconds: asNonNegativeInt(frontmatterData.debounceSeconds),
+			dedupeWindowSeconds: asNonNegativeInt(
+				frontmatterData.dedupeWindowSeconds,
+			),
+			cooldownSeconds: asNonNegativeInt(frontmatterData.cooldownSeconds),
+			maxParallel: asPositiveInt(frontmatterData.maxParallel),
+		};
+		spec = e;
+	} else {
+		const o: CronOneOffSpec = { ...common, triggerKind: "one_off" };
+		spec = o;
+	}
+
+	return {
+		externalId,
+		relativePath,
+		triggerKind,
+		body,
+		contentHash,
+		spec,
+	};
+}

codna/agent-core/vendor/cline/sdk/packages/core/src/cron/specs/cron-watcher.test.ts

@@ -0,0 +1,87 @@
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { CronMaterializer } from "../runner/cron-materializer";
+import { SqliteCronStore } from "../store/sqlite-cron-store";
+import { CronReconciler } from "./cron-reconciler";
+import { CronWatcher } from "./cron-watcher";
+
+describe("CronWatcher", () => {
+	let root: string;
+	let cronDir: string;
+	let store: SqliteCronStore;
+	let reconciler: CronReconciler;
+	let materializer: CronMaterializer;
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "cline-watcher-"));
+		cronDir = join(root, "cron-specs");
+		mkdirSync(cronDir, { recursive: true });
+		store = new SqliteCronStore({ dbPath: join(root, "cron.db") });
+		reconciler = new CronReconciler({
+			store,
+			specs: { cronSpecsDir: cronDir },
+		});
+		materializer = new CronMaterializer({ store });
+	});
+
+	afterEach(() => {
+		store.close();
+		rmSync(root, { recursive: true, force: true });
+	});
+
+	function requireValue<T>(value: T | undefined): T {
+		expect(value).toBeDefined();
+		if (value === undefined) {
+			throw new Error("Expected value to be defined");
+		}
+		return value;
+	}
+
+	it("materializes after a watched file reconcile", async () => {
+		const specPath = join(cronDir, "cleanup.md");
+		writeFileSync(
+			specPath,
+			`---\nid: cleanup\nworkspaceRoot: /ws\n---\nRemove stale files`,
+			"utf8",
+		);
+		let materialized = 0;
+		const watcher = new CronWatcher({
+			reconciler,
+			onReconciled: () => {
+				materialized += materializer.materializeAll().oneOffQueued;
+			},
+		});
+
+		await (
+			watcher as unknown as { reconcileNow(path: string): Promise<void> }
+		).reconcileNow("cleanup.md");
+
+		expect(materialized).toBe(1);
+		const spec = requireValue(store.listSpecs()[0]);
+		const runs = store.listRuns({ specId: spec.specId });
+		expect(runs).toHaveLength(1);
+		expect(runs[0]?.status).toBe("queued");
+	});
+
+	it("creates the cron directory before starting the watcher", () => {
+		const missingCronDir = join(root, "missing-cron-specs");
+		const watcherReconciler = new CronReconciler({
+			store,
+			specs: { cronSpecsDir: missingCronDir },
+		});
+		const watcher = new CronWatcher({ reconciler: watcherReconciler });
+
+		watcher.start();
+		watcher.stop();
+
+		expect(existsSync(missingCronDir)).toBe(true);
+	});
+});

codna/agent-core/vendor/cline/sdk/packages/core/src/cron/specs/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);
+		}
+	}
+}

codna/agent-core/vendor/cline/sdk/packages/core/src/cron/specs/index.ts

@@ -0,0 +1,3 @@
+export * from "./cron-reconciler";
+export * from "./cron-spec-parser";
+export * from "./cron-watcher";