emdash 0.0.0-a → 0.0.1

package/src/plugins/cron.ts

@@ -0,0 +1,361 @@
+/**
+ * Plugin Cron System
+ *
+ * Provides scheduled task execution for plugins:
+ * - CronExecutor: claims overdue tasks, invokes per-plugin cron hook, updates next run.
+ * - CronAccessImpl: per-plugin API for schedule/cancel/list.
+ *
+ */
+
+import { Cron } from "croner";
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+import { ulid } from "ulidx";
+
+import type { Database } from "../database/types.js";
+import type { CronAccess, CronEvent, CronTaskInfo } from "./types.js";
+
+/** Stale lock threshold in minutes */
+const STALE_LOCK_MINUTES = 10;
+
+/**
+ * Callback to invoke a plugin's cron hook.
+ * Provided by PluginManager so CronExecutor stays decoupled from the hook pipeline.
+ */
+export type InvokeCronHookFn = (pluginId: string, event: CronEvent) => Promise<void>;
+
+/**
+ * Callback to notify the scheduler that the next due time may have changed.
+ */
+export type RescheduleFn = () => void;
+
+// ─── CronExecutor ──────────────────────────────────────────────────────────
+
+/**
+ * Executes overdue cron tasks.
+ *
+ * Called by platform-specific schedulers (NodeCronScheduler, EmDashScheduler DO,
+ * PiggybackScheduler). Stateless — all state lives in the database.
+ */
+export class CronExecutor {
+	constructor(
+		private db: Kysely<Database>,
+		private invokeCronHook: InvokeCronHookFn,
+	) {}
+
+	/**
+	 * Process all overdue tasks.
+	 *
+	 * 1. Atomically claim tasks whose next_run_at <= now, status = idle, enabled = 1.
+	 * 2. For each claimed task, invoke the plugin's cron hook.
+	 * 3. On success: compute next_run_at and reset to idle, or delete one-shots.
+	 * 4. On failure: reset to idle (retry on next tick).
+	 */
+	async tick(): Promise<number> {
+		const now = new Date().toISOString();
+		let processed = 0;
+
+		// Claim overdue tasks atomically
+		const claimed = await sql<{
+			id: string;
+			plugin_id: string;
+			task_name: string;
+			schedule: string;
+			is_oneshot: number;
+			data: string | null;
+			next_run_at: string;
+		}>`
+			UPDATE _emdash_cron_tasks
+			SET status = 'running', locked_at = ${now}
+			WHERE id IN (
+				SELECT id FROM _emdash_cron_tasks
+				WHERE next_run_at <= ${now}
+				  AND status = 'idle'
+				  AND enabled = 1
+				ORDER BY next_run_at ASC
+				LIMIT 10
+			)
+			RETURNING id, plugin_id, task_name, schedule, is_oneshot, data, next_run_at
+		`.execute(this.db);
+
+		for (const task of claimed.rows) {
+			// Parse task data safely ��� malformed JSON must not crash the entire batch
+			let parsedData: Record<string, unknown> | undefined;
+			if (task.data) {
+				try {
+					parsedData = JSON.parse(task.data) as Record<string, unknown>;
+				} catch {
+					console.error(
+						`[cron] Invalid JSON data for ${task.plugin_id}:${task.task_name}, skipping`,
+					);
+					await sql`
+						UPDATE _emdash_cron_tasks
+						SET status = 'idle', locked_at = NULL
+						WHERE id = ${task.id}
+					`.execute(this.db);
+					continue;
+				}
+			}
+
+			const event: CronEvent = {
+				name: task.task_name,
+				data: parsedData,
+				scheduledAt: task.next_run_at,
+			};
+
+			let hookFailed = false;
+			try {
+				await this.invokeCronHook(task.plugin_id, event);
+			} catch (error) {
+				hookFailed = true;
+				console.error(`[cron] Hook failed for ${task.plugin_id}:${task.task_name}:`, error);
+			}
+
+			if (task.is_oneshot) {
+				if (hookFailed) {
+					// Keep the task for retry — reset to idle with a 1-minute backoff
+					const retryAt = new Date(Date.now() + 60_000).toISOString();
+					await sql`
+						UPDATE _emdash_cron_tasks
+						SET status = 'idle', locked_at = NULL, next_run_at = ${retryAt}
+						WHERE id = ${task.id}
+					`.execute(this.db);
+				} else {
+					// Success: delete the one-shot task
+					await sql`
+						DELETE FROM _emdash_cron_tasks WHERE id = ${task.id}
+					`.execute(this.db);
+				}
+			} else {
+				// Recurring: compute next run and reset
+				const nextRun = nextCronTime(task.schedule);
+				await sql`
+					UPDATE _emdash_cron_tasks
+					SET status = 'idle',
+						locked_at = NULL,
+						last_run_at = ${now},
+						next_run_at = ${nextRun}
+					WHERE id = ${task.id}
+				`.execute(this.db);
+			}
+
+			processed++;
+		}
+
+		return processed;
+	}
+
+	/**
+	 * Recover tasks stuck in 'running' for more than STALE_LOCK_MINUTES.
+	 * These likely crashed mid-execution.
+	 */
+	async recoverStaleLocks(): Promise<number> {
+		const cutoff = new Date(Date.now() - STALE_LOCK_MINUTES * 60 * 1000).toISOString();
+
+		const result = await sql`
+			UPDATE _emdash_cron_tasks
+			SET status = 'idle', locked_at = NULL
+			WHERE status = 'running'
+			  AND locked_at < ${cutoff}
+		`.execute(this.db);
+
+		return Number(result.numAffectedRows ?? 0);
+	}
+
+	/**
+	 * Get the next due time across all enabled tasks.
+	 * Returns null if no tasks are scheduled.
+	 */
+	async getNextDueTime(): Promise<string | null> {
+		const result = await sql<{ next: string | null }>`
+			SELECT MIN(next_run_at) as next
+			FROM _emdash_cron_tasks
+			WHERE status = 'idle' AND enabled = 1
+		`.execute(this.db);
+
+		return result.rows[0]?.next ?? null;
+	}
+}
+
+// ─── CronAccessImpl ────────────────────────────────────────────────────────
+
+/**
+ * Per-plugin cron API implementation.
+ * Scoped to a single plugin ID — plugins cannot see or modify other plugins' tasks.
+ */
+export class CronAccessImpl implements CronAccess {
+	constructor(
+		private db: Kysely<Database>,
+		private pluginId: string,
+		private reschedule: RescheduleFn,
+	) {}
+
+	async schedule(
+		name: string,
+		opts: { schedule: string; data?: Record<string, unknown> },
+	): Promise<void> {
+		validateTaskName(name);
+		validateSchedule(opts.schedule);
+
+		const oneshot = isOneShot(opts.schedule);
+		const nextRun = oneshot ? opts.schedule : nextCronTime(opts.schedule);
+		const dataJson = opts.data ? JSON.stringify(opts.data) : null;
+		const id = ulid();
+
+		// Upsert: if task already exists for this plugin+name, update it.
+		// Guard: don't clobber a task that is currently executing.
+		await sql`
+			INSERT INTO _emdash_cron_tasks (id, plugin_id, task_name, schedule, is_oneshot, data, next_run_at, status, enabled)
+			VALUES (${id}, ${this.pluginId}, ${name}, ${opts.schedule}, ${oneshot ? 1 : 0}, ${dataJson}, ${nextRun}, 'idle', 1)
+			ON CONFLICT (plugin_id, task_name) DO UPDATE SET
+				schedule = ${opts.schedule},
+				is_oneshot = ${oneshot ? 1 : 0},
+				data = ${dataJson},
+				next_run_at = ${nextRun},
+				status = CASE WHEN _emdash_cron_tasks.status = 'running' THEN 'running' ELSE 'idle' END,
+				locked_at = CASE WHEN _emdash_cron_tasks.status = 'running' THEN _emdash_cron_tasks.locked_at ELSE NULL END,
+				enabled = 1
+		`.execute(this.db);
+
+		this.reschedule();
+	}
+
+	async cancel(name: string): Promise<void> {
+		await sql`
+			DELETE FROM _emdash_cron_tasks
+			WHERE plugin_id = ${this.pluginId} AND task_name = ${name}
+		`.execute(this.db);
+
+		this.reschedule();
+	}
+
+	async list(): Promise<CronTaskInfo[]> {
+		const rows = await sql<{
+			task_name: string;
+			schedule: string;
+			next_run_at: string;
+			last_run_at: string | null;
+		}>`
+			SELECT task_name, schedule, next_run_at, last_run_at
+			FROM _emdash_cron_tasks
+			WHERE plugin_id = ${this.pluginId} AND enabled = 1
+			ORDER BY next_run_at ASC
+		`.execute(this.db);
+
+		return rows.rows.map((row) => ({
+			name: row.task_name,
+			schedule: row.schedule,
+			nextRunAt: row.next_run_at,
+			lastRunAt: row.last_run_at,
+		}));
+	}
+}
+
+// ─── Cron task lifecycle helpers ────────────────────────────────────────────
+
+/**
+ * Enable or disable all cron tasks for a plugin.
+ * Called by admin disable/enable endpoints and PluginManager lifecycle.
+ * Gracefully handles the cron table not existing yet (pre-migration).
+ */
+export async function setCronTasksEnabled(
+	db: Kysely<Database>,
+	pluginId: string,
+	enabled: boolean,
+): Promise<void> {
+	try {
+		await sql`
+			UPDATE _emdash_cron_tasks
+			SET enabled = ${enabled ? 1 : 0}
+			WHERE plugin_id = ${pluginId}
+		`.execute(db);
+	} catch {
+		// Cron table may not exist yet (pre-migration). Non-fatal.
+	}
+}
+
+// ─── Cron utilities ────────────────────────────────────────────────────────
+
+/**
+ * Compute the next fire time for a cron expression.
+ * Supports standard cron (5-field), extended (6-field with seconds), and
+ * aliases like @daily, @weekly, @hourly, @monthly, @yearly.
+ */
+export function nextCronTime(expression: string): string {
+	const job = new Cron(expression);
+	const next = job.nextRun();
+	if (!next) {
+		throw new Error(`Invalid cron expression or no future run: "${expression}"`);
+	}
+	return next.toISOString();
+}
+
+/**
+ * Check whether a string is a valid cron expression.
+ */
+function isCronExpression(schedule: string): boolean {
+	try {
+		// Cron constructor validates; we discard the instance immediately.
+		const _cron = new Cron(schedule);
+		void _cron;
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if a schedule string is a one-shot (ISO 8601 datetime) rather than
+ * a recurring cron expression.
+ *
+ * Tries to parse as a cron expression first. Only if that fails does it
+ * attempt Date.parse. This avoids misclassifying cron range expressions
+ * like "1-5 * * * *" which Date.parse accepts as valid dates.
+ */
+export function isOneShot(schedule: string): boolean {
+	if (schedule.startsWith("@")) return false;
+	if (isCronExpression(schedule)) return false;
+	return !isNaN(Date.parse(schedule));
+}
+
+/** Max length for a task name */
+const MAX_TASK_NAME_LENGTH = 128;
+/** Task name pattern: alphanumeric, dashes, underscores */
+const TASK_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+/**
+ * Validate a cron task name.
+ * Must be non-empty, ≤128 chars, alphanumeric with dashes/underscores.
+ */
+export function validateTaskName(name: string): void {
+	if (!name || name.length > MAX_TASK_NAME_LENGTH) {
+		throw new Error(
+			`Invalid task name: must be 1-${MAX_TASK_NAME_LENGTH} characters, got ${name.length}`,
+		);
+	}
+	if (!TASK_NAME_RE.test(name)) {
+		throw new Error(
+			`Invalid task name "${name}": must start with a letter and contain only letters, numbers, dashes, or underscores`,
+		);
+	}
+}
+
+/**
+ * Validate a schedule string at registration time.
+ * Must be a valid cron expression or a parseable ISO 8601 datetime.
+ */
+export function validateSchedule(schedule: string): void {
+	if (!schedule || schedule.length > 256) {
+		throw new Error(`Invalid schedule: must be 1-256 characters, got ${schedule.length}`);
+	}
+
+	// Try cron first
+	if (isCronExpression(schedule)) return;
+
+	const parsed = Date.parse(schedule);
+	if (isNaN(parsed)) {
+		throw new Error(
+			`Invalid schedule "${schedule}": must be a valid cron expression or ISO 8601 datetime`,
+		);
+	}
+}

package/src/plugins/define-plugin.ts

@@ -0,0 +1,259 @@
+/**
+ * definePlugin() Helper
+ *
+ * Creates a properly typed and normalized plugin definition.
+ * Supports two formats:
+ *
+ * 1. **Native format** -- full PluginDefinition with id, version, capabilities, etc.
+ *    Returns a ResolvedPlugin.
+ *
+ * 2. **Standard format** -- just { hooks, routes }. No id/version/capabilities.
+ *    Returns the same object (identity function for type inference).
+ *    Metadata comes from the descriptor at config time.
+ *
+ */
+
+import type {
+	PluginDefinition,
+	ResolvedPlugin,
+	PluginHooks,
+	ResolvedPluginHooks,
+	ResolvedHook,
+	HookConfig,
+	PluginStorageConfig,
+	StandardPluginDefinition,
+} from "./types.js";
+
+// Plugin ID validation patterns
+const SIMPLE_ID = /^[a-z0-9-]+$/;
+const SCOPED_ID = /^@[a-z0-9-]+\/[a-z0-9-]+$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
+
+/**
+ * Define an EmDash plugin.
+ *
+ * **Standard format** -- the canonical format for plugins that work in both
+ * trusted and sandboxed modes. No id/version -- those come from the descriptor.
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from "emdash";
+ *
+ * export default definePlugin({
+ *   hooks: {
+ *     "content:afterSave": {
+ *       handler: async (event, ctx) => {
+ *         await ctx.kv.set("lastSave", Date.now());
+ *       },
+ *     },
+ *   },
+ *   routes: {
+ *     status: {
+ *       handler: async (routeCtx, ctx) => ({ ok: true }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * **Native format** -- for plugins that need React admin, direct DB access,
+ * or other capabilities not available in the sandbox.
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from "emdash";
+ *
+ * export default definePlugin({
+ *   id: "my-plugin",
+ *   version: "1.0.0",
+ *   capabilities: ["read:content"],
+ *   hooks: {
+ *     "content:beforeSave": async (event, ctx) => {
+ *       ctx.log.info("Saving content", { collection: event.collection });
+ *       return event.content;
+ *     }
+ *   },
+ *   routes: {
+ *     "sync": {
+ *       handler: async (ctx) => {
+ *         return { status: "ok" };
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+// Native overload first -- PluginDefinition (with id+version) is more specific
+export function definePlugin<TStorage extends PluginStorageConfig>(
+	definition: PluginDefinition<TStorage>,
+): ResolvedPlugin<TStorage>;
+// Standard overload second -- catches { hooks, routes } without id/version
+export function definePlugin(definition: StandardPluginDefinition): StandardPluginDefinition;
+export function definePlugin<TStorage extends PluginStorageConfig>(
+	definition: PluginDefinition<TStorage> | StandardPluginDefinition,
+): ResolvedPlugin<TStorage> | StandardPluginDefinition {
+	// Standard format: has hooks/routes but no id/version
+	if (!("id" in definition) || !("version" in definition)) {
+		// Validate that the standard format has at least hooks or routes
+		if (!("hooks" in definition) && !("routes" in definition)) {
+			throw new Error(
+				"Standard plugin format requires at least `hooks` or `routes`. " +
+					"For native format, provide `id` and `version`.",
+			);
+		}
+		// Identity function -- return as-is for type inference.
+		// The adapter (adaptSandboxEntry) will convert this to a ResolvedPlugin at build time.
+		return definition;
+	}
+
+	return defineNativePlugin(definition);
+}
+
+/**
+ * Internal: define a native-format plugin with full validation and normalization.
+ */
+function defineNativePlugin<TStorage extends PluginStorageConfig>(
+	definition: PluginDefinition<TStorage>,
+): ResolvedPlugin<TStorage> {
+	const {
+		id,
+		version,
+		capabilities = [],
+		allowedHosts = [],
+		hooks = {},
+		routes = {},
+		admin = {},
+	} = definition;
+
+	// Default to empty object if no storage declared.
+	// The empty object satisfies PluginStorageConfig (Record<string, ...>).
+	// The cast is structurally safe because an empty record has no keys to conflict.
+	const storage = (definition.storage ?? {}) as TStorage;
+
+	// Validate id format: either simple (my-plugin) or scoped (@scope/my-plugin)
+	// Simple: lowercase alphanumeric with dashes
+	// Scoped: @scope/name where both parts are lowercase alphanumeric with dashes
+	if (!SIMPLE_ID.test(id) && !SCOPED_ID.test(id)) {
+		throw new Error(
+			`Invalid plugin id "${id}". Must be lowercase alphanumeric with dashes (e.g., "my-plugin" or "@scope/my-plugin").`,
+		);
+	}
+
+	// Validate version format (basic semver)
+	if (!SEMVER_PATTERN.test(version)) {
+		throw new Error(`Invalid plugin version "${version}". Must be semver format (e.g., "1.0.0").`);
+	}
+
+	// Validate capabilities
+	const validCapabilities = new Set([
+		"network:fetch",
+		"network:fetch:any",
+		"read:content",
+		"write:content",
+		"read:media",
+		"write:media",
+		"read:users",
+		"email:send",
+		"email:provide",
+		"email:intercept",
+		"page:inject",
+	]);
+	for (const cap of capabilities) {
+		if (!validCapabilities.has(cap)) {
+			throw new Error(`Invalid capability "${cap}" in plugin "${id}".`);
+		}
+	}
+
+	// Capability implications: broader capabilities imply narrower ones
+	const normalizedCapabilities = [...capabilities];
+	if (capabilities.includes("write:content") && !capabilities.includes("read:content")) {
+		normalizedCapabilities.push("read:content");
+	}
+	if (capabilities.includes("write:media") && !capabilities.includes("read:media")) {
+		normalizedCapabilities.push("read:media");
+	}
+	if (capabilities.includes("network:fetch:any") && !capabilities.includes("network:fetch")) {
+		normalizedCapabilities.push("network:fetch");
+	}
+
+	// Normalize hooks
+	const resolvedHooks = resolveHooks(hooks, id);
+
+	return {
+		id,
+		version,
+		capabilities: normalizedCapabilities,
+		allowedHosts,
+		storage,
+		hooks: resolvedHooks,
+		routes,
+		admin,
+	};
+}
+
+/**
+ * Resolve hooks to normalized format with defaults.
+ *
+ * PluginHooks and ResolvedPluginHooks share the same keys — each input value is
+ * `HookConfig<H> | H` and the output is `ResolvedHook<H>`.  TS can't narrow
+ * the handler type through a dynamic key, so we assert at the loop boundary.
+ */
+function resolveHooks(hooks: PluginHooks, pluginId: string): ResolvedPluginHooks {
+	const resolved: ResolvedPluginHooks = {};
+
+	for (const key of Object.keys(hooks) as Array<keyof PluginHooks>) {
+		const hook = hooks[key];
+		if (hook) {
+			(resolved as Record<string, unknown>)[key] = resolveHook(hook, pluginId);
+		}
+	}
+
+	return resolved;
+}
+
+/**
+ * Check if a hook value is a config object (has a `handler` property)
+ */
+function isHookConfig<THandler>(
+	hook: HookConfig<THandler> | THandler,
+): hook is HookConfig<THandler> {
+	return typeof hook === "object" && hook !== null && "handler" in hook;
+}
+
+/**
+ * Resolve a single hook to normalized format
+ */
+function resolveHook<THandler>(
+	hook: HookConfig<THandler> | THandler,
+	pluginId: string,
+): ResolvedHook<THandler> {
+	// If it's a config object with handler property
+	if (isHookConfig(hook)) {
+		if (hook.exclusive !== undefined && typeof hook.exclusive !== "boolean") {
+			throw new Error(
+				`Invalid "exclusive" value in hook config for plugin "${pluginId}". Must be boolean.`,
+			);
+		}
+		return {
+			priority: hook.priority ?? 100,
+			timeout: hook.timeout ?? 5000,
+			dependencies: hook.dependencies ?? [],
+			errorPolicy: hook.errorPolicy ?? "abort",
+			exclusive: hook.exclusive ?? false,
+			handler: hook.handler,
+			pluginId,
+		};
+	}
+
+	// It's just a handler function
+	return {
+		priority: 100,
+		timeout: 5000,
+		dependencies: [],
+		errorPolicy: "abort",
+		exclusive: false,
+		handler: hook,
+		pluginId,
+	};
+}
+
+export default definePlugin;

package/src/plugins/email-console.ts

@@ -0,0 +1,73 @@
+/**
+ * Dev Console Email Provider
+ *
+ * Built-in plugin that registers email:deliver as an exclusive hook.
+ * Logs emails to console and stores them in memory (capped at 100).
+ * Auto-activated when import.meta.env.DEV is true and no other provider is selected.
+ *
+ */
+
+import type { EmailDeliverEvent, EmailMessage, PluginContext } from "./types.js";
+
+/** Plugin ID for the dev console email provider */
+export const DEV_CONSOLE_EMAIL_PLUGIN_ID = "emdash-console-email";
+
+/** Maximum number of emails to keep in memory */
+const MAX_STORED_EMAILS = 100;
+
+/**
+ * Stored email record (in-memory only)
+ */
+export interface StoredEmail {
+	message: EmailMessage;
+	source: string;
+	sentAt: string;
+}
+
+/** In-memory store for dev emails */
+const storedEmails: StoredEmail[] = [];
+
+/**
+ * Get all stored dev emails (most recent first).
+ */
+export function getDevEmails(): StoredEmail[] {
+	return storedEmails.toReversed();
+}
+
+/**
+ * Clear all stored dev emails.
+ */
+export function clearDevEmails(): void {
+	storedEmails.length = 0;
+}
+
+/**
+ * The email:deliver handler for the dev console provider.
+ * Logs to console and stores in memory.
+ */
+export async function devConsoleEmailDeliver(
+	event: EmailDeliverEvent,
+	_ctx: PluginContext,
+): Promise<void> {
+	const { message, source } = event;
+
+	console.log(
+		`\n📧 [dev-email] Email sent\n` +
+			`   From: ${source}\n` +
+			`   To: ${message.to}\n` +
+			`   Subject: ${message.subject}\n` +
+			`   Text: ${message.text.slice(0, 200)}${message.text.length > 200 ? "..." : ""}\n`,
+	);
+
+	// Store the email
+	storedEmails.push({
+		message,
+		source,
+		sentAt: new Date().toISOString(),
+	});
+
+	// Cap at MAX_STORED_EMAILS
+	while (storedEmails.length > MAX_STORED_EMAILS) {
+		storedEmails.shift();
+	}
+}