feat(plugins): cron surface — declarations + scheduled() handler (Phase 4)

[lane711]

Summary

Adds the plugin cron surface on top of the foundation (#841). Plugins declare scheduled work as data; a scheduled() handler fans fired Cron Triggers out to the matching plugins.

Stacked on #841 (base = lane711/plugin-system-issues). Review/merge that first.

Infrastructure only — no consumer change yet. Like the other foundation phases, this is live-but-inert: no plugin declares crons yet, and the scheduled export isn't wired into the consumer Worker.

What's here

• plugins/cron.ts:
  • CronDeclaration { schedule, hookFamily } + structural CronablePlugin (crons[] + async onCronTick).
  • collectCrons() / collectCronSchedules() — flatten declarations (for wrangler-trigger sync + diagnostics).
  • dispatchCronTick() — matches a fired expression to the plugins that declared it, tags each onCronTick with the matched hookFamily (one call per matching declaration), error-isolated.
  • createScheduledHandler({ plugins, getHooks, disabled }) — returns a Cloudflare scheduled(controller, env, ctx) handler that reaches services via the env-independent singletons (cron has no c.env), passes Worker env through, and waitUntils the work.

Design note

Matches Payload's jobs model: declaring a schedule runs nothing by itself — the execution mechanism is the Cloudflare Cron Trigger delivered to scheduled(). The consumer still lists the expressions in wrangler.toml [triggers]; the plugin crons[] are the source of truth for which plugin owns which expression.

Tests

cron.test.ts (12): collect/flatten + malformed-entry skipping, match-only-fired-cron, well-formed event, unmatched reporting, multi-cron fan-out (one call per declaration), error isolation, and the scheduled handler (dispatch + waitUntil + env passthrough + lazy list + disabled no-op).

• Full core suite: 1552 passed, 0 failed
• tsc --noEmit: clean

Deferred

Wiring scheduled into the consumer Worker export (export default { fetch, scheduled }) + starter template + wrangler.toml trigger generation — bundled with definePlugin()/docs (Phase 5/7).

🤖 Generated with Claude Code