@lunora/cli 1.0.0-alpha.37 → 1.0.0-alpha.370

package/skills/lunora-setup-scheduler/SKILL.md

@@ -1,157 +1,193 @@
 ---
 name: lunora-setup-scheduler
-description: Schedules deferred and recurring work in a Lunora app. Use for `ctx.scheduler.runAfter` / `runAt` (delayed function dispatch), cron jobs via `lunora registry add crons` (the `cronJobs()` builder), the `SchedulerDO` / `SCHEDULER` binding, retries, and the workpool for bounded concurrency.
+description: Schedules deferred and recurring work in a Lunora app. Covers `ctx.scheduler.runAfter` / `runAt` (delayed dispatch of a function or workflow), cron jobs in `lunora/crons.ts` via `lunora registry add crons` and the `cronJobs()` builder, the `SchedulerDO` / `SCHEDULER` binding and `LUNORA_ORIGIN_URL`, retries and dead-lettering, and `createWorkpool` for bounded concurrency. Use when the user wants to "run this later", "send a reminder in 3 days", "run every night / every 5 minutes", add a cron, cancel a scheduled job, or sees `ORIGIN_NOT_CONFIGURED` or a missing `SchedulerDO` export.
 ---
 
 # Lunora Setup Scheduler
 
-Schedule work in Lunora two ways, both backed by `@lunora/scheduler` (re-exported
-from `@lunora/server`):
+Lunora schedules work in two ways, both implemented in `@lunora/scheduler`:
 
-- **Deferred dispatch** — `ctx.scheduler.runAfter` / `runAt` from any function,
-  to run a function later. Built into the runtime; **no registry install**.
-- **Recurring jobs (crons)** — declare them in `lunora/crons.ts` with
-  `cronJobs()`. Add the starter with `lunora registry add crons`.
+- **Deferred dispatch**: `ctx.scheduler.runAfter` / `runAt` run a function (or
+  start a workflow) later. Jobs are stored in the `SchedulerDO` Durable Object
+  (binding `SCHEDULER`), which owns the alarm, the retries and the dead-letter list.
+- **Recurring jobs (crons)**: declared in `lunora/crons.ts` with `cronJobs()`.
+  Codegen compiles them into Cloudflare Cron Triggers, and the Worker's
+  `scheduled()` handler dispatches them directly. They don't go through the
+  `SchedulerDO`.
 
-Both run jobs through the `SchedulerDO` Durable Object (binding `SCHEDULER`),
-which owns the alarm and durable storage.
+## When Not to Use
 
-## When to Use
+- The project has no Lunora backend yet: use `lunora-quickstart` first.
+- You only need to react to data changes: use a reactive `query` /
+  subscription (`lunora-realtime`).
+- Multi-step orchestration with sleeps and waits belongs in a durable workflow.
+  A scheduler or cron can start one, but don't build step logic on top of jobs.
 
-- Running a function after a delay or at a specific time
-  (`runAfter` / `runAt`).
-- Declaring recurring jobs (sweep, digest, report) on a cron schedule.
-- Bounding concurrency for many enqueued jobs (a workpool).
+## Deferred dispatch: `runAfter` / `runAt`
 
-## When Not to Use
+### Wire it once
 
-- The project has no Lunora backend yet — use `lunora-quickstart` first.
-- You just need to react to live data changes — use a reactive `query` /
-  subscription (`lunora-realtime`), not a scheduled job.
+```bash
+pnpm add @lunora/scheduler
+lunora codegen
+```
 
-## Deferred dispatch — `runAfter` / `runAt`
+Codegen needs `@lunora/scheduler` installed as soon as `ctx.scheduler` is used,
+because the generated `_generated/app.ts` imports `createScheduler`. Once the
+dependency is present, codegen emits `_generated/scheduler.ts` (re-exporting
+`SchedulerDO`) and a `.scheduler()` method on the app builder.
 
-Available on `ctx.scheduler` in any function. Target functions are passed by
-reference from the generated `api` / `internal` proxy:
+- **Vite-first apps** (generated worker entry): the plugin forwards
+  `SchedulerDO` and calls `.scheduler()` for you.
+- **Hand-written worker entry** (`src/server.ts` with `defineApp`): wire it yourself.
+  `wrangler.jsonc`'s `SCHEDULER` binding is reconciled from this export:
 
 ```ts
-import { mutation, v } from "@lunora/server";
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .scheduler({ namespace: (env) => env.SCHEDULER })
+    .build();
+
+export const ShardDO = app.ShardDO;
+export { SchedulerDO } from "../lunora/_generated/scheduler.js";
+```
+
+The `SchedulerDO` calls back into the Worker at `LUNORA_ORIGIN_URL`. It reads
+that value from its own env and never from the request, so a caller can't point
+dispatch at an arbitrary URL. Without it, every `runAfter`/`runAt` fails with
+`ORIGIN_NOT_CONFIGURED`, and nothing provisions it for you:
 
-import { internal } from "./_generated/api";
+- dev: `LUNORA_ORIGIN_URL="http://localhost:5173"` in `.dev.vars` (your dev
+  server's URL)
+- prod: `vars.LUNORA_ORIGIN_URL` in `wrangler.jsonc`, or
+  `wrangler secret put LUNORA_ORIGIN_URL` (per `--env`)
 
-export const startTrial = mutation.input({ userId: v.string() }).mutation(async ({ ctx, args: { userId } }) => {
-    // run an internal action 14 days from now
-    const { id } = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
+`lunora doctor` warns when the scheduler binding exists and the variable is unset.
 
-    return { jobId: id };
+### Schedule from a mutation or action
+
+```ts
+import { LunoraError } from "lunorash/server";
+
+import { internal } from "#lunora/_generated/internal.js";
+import { mutation } from "#lunora/_generated/server.js";
+
+export const startTrial = mutation.mutation(async ({ ctx }) => {
+    // the caller's own id, never one the client passes in
+    const { userId } = ctx.auth;
+    if (!userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+    // run an internal action 14 days from now; the id is a plain string
+    const jobId = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
+
+    return { jobId };
 });
 ```
 
-- `runAfter(delayMs, fnRef, args, options?)` — run after a delay (`delayMs` must
-  be a non-negative finite number). `runAt(date, fnRef, args, options?)` — run at
-  a `Date` or epoch-ms timestamp.
-- Both return `{ id, scheduledFor }`. Cancel with `ctx.scheduler.cancel(id)`;
-  inspect with `ctx.scheduler.get(id)` / `ctx.scheduler.list()`.
-- `options` accepts a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`;
-  DO defaults: `maxAttempts: 5`, `backoff: "exponential"`, `baseMs: 30_000`) and
-  a `shardKey` routing hint. On retry exhaustion the job is dead-lettered, never
-  silently dropped.
-- The `SchedulerDO` binding (`SCHEDULER`) is **auto-inferred and reconciled**
-  into `wrangler.jsonc` by `@lunora/config` once `@lunora/scheduler` is in use —
-  run `lunora codegen` / `lunora doctor` to confirm. Scheduled jobs run with no
-  end-user identity, so target **internal** functions (`internal.*`).
-
-## Recurring jobs — crons
+- The full `ctx.scheduler` surface is `runAfter(delayMs, target, args?)`,
+  `runAt(timestampMs, target, args?)` (epoch ms), `cancel(id)`, `get(id)`, and `list()`.
+  It is not available in a `query`, because queries are deterministic and re-run.
+- `target` is a generated `internal.*` / `api.*` mutation or action reference, a
+  `"file:fn"` string, or a `workflows.<name>` / `agents.<name>` reference.
+  A workflow or agent reference starts a fresh instance when the job fires, with
+  `args` as its params. Scheduled jobs run with no end-user identity, so target
+  `internal.*` functions.
+- **Inside a mutation, scheduling is transactional.** The call is buffered and
+  dispatched only after the mutation commits. If the mutation rolls back (OCC
+  conflict, validation error), the job is dropped too. The returned id is final
+  immediately, so you can store it on the row you're writing and `cancel` it later.
+- Retries use the DO defaults: 5 retries, exponential backoff from 30 s. A job
+  that exhausts them is dead-lettered (visible in the studio), not dropped. To set
+  a per-job `retry` policy (`{ maxAttempts, backoff: "exponential" | "linear",
+baseMs, maxMs }`) or a `shardKey`, build your own client with
+  `createScheduler({ namespace })` from `@lunora/scheduler`. Its `runAfter`/`runAt`
+  take a fourth `RunOptions` argument and add `dead()` / `deadRetry(id)`.
+
+## Recurring jobs: crons
 
 ### Step 1: Add the starter
 
 ```bash
 lunora registry add crons
+pnpm install
 ```
 
-This adds `@lunora/server` to `package.json` (run `pnpm install`) and copies
-`lunora/crons.ts` (a `cronJobs()` registry with one illustrative job) and
-`lunora/crons/jobs.ts` (the example `run` internal mutation it fires) into your
-project — both **yours** to edit. No extra DO binding is required.
+This adds `@lunora/server` + `@lunora/scheduler` to `package.json` and copies two
+files you own: `lunora/crons.ts` (a `cronJobs()` registry) and
+`lunora/crons/jobs.ts` (an example `internalMutation`, `internal.crons.jobs.run`).
 
 ### Step 2: Declare jobs
 
 ```ts
 import { cronJobs } from "@lunora/server";
 
-import { internal } from "./_generated/api";
+import { internal } from "#lunora/_generated/internal.js";
 
 const crons = cronJobs();
 
 crons.interval("sweep presence", { minutes: 5 }, internal.presence.sweep, { roomId: "lobby" });
-crons.daily("digest", { hourUTC: 9, minuteUTC: 0 }, internal.email.digest, {});
-crons.weekly("report", { dayOfWeek: "monday", hourUTC: 8, minuteUTC: 0 }, internal.reports.weekly, {});
-crons.monthly("invoice", { day: 1, hourUTC: 0, minuteUTC: 0 }, internal.billing.invoice, {});
-crons.cron("custom", "0 */6 * * *", internal.foo.bar, {}); // raw cron escape hatch
+crons.hourly("rollup", { minuteUTC: 17 }, internal.stats.rollup);
+crons.daily("digest", { hourUTC: 9, minuteUTC: 0 }, internal.email.digest);
+crons.weekly("report", { dayOfWeek: "monday", hourUTC: 8, minuteUTC: 0 }, internal.reports.weekly);
+crons.monthly("invoice", { day: 1, hourUTC: 0, minuteUTC: 0 }, internal.billing.invoice);
+crons.cron("custom", "0 */6 * * *", internal.foo.bar); // raw cron escape hatch
 
 export default crons;
 ```
 
-- `name` must be a non-empty **string literal**, unique across the project.
-- `fnRef` must be a static two-segment access on the proxy
-  (`internal.<file>.<fn>` or `api.<file>.<fn>`) so codegen can discover it.
-  Cron targets must be **internal** functions — a client can never invoke them.
-- All schedules are UTC and validated at definition time
-  (`hourUTC: 25` throws immediately).
+- Names must be non-empty string literals, unique across the project.
+- Targets must be static property accesses (`internal.<…path>.<fn>`, one segment
+  per folder and file, e.g. `internal.crons.jobs.run`) or a `workflows.<name>` /
+  `agents.<name>` reference. Codegen resolves them from the AST, so a computed
+  reference fails codegen. `args` is optional and must be a literal.
+- Schedules are UTC and validated when the job is defined. `interval` takes exactly one of
+  `{ minutes }` (must divide 60) or `{ hours }` (must divide 24). `{ seconds }`
+  is rejected because Cron Triggers have a one-minute floor. For sub-minute work,
+  use `runAfter`.
+- Use `hourly` with an offset minute to spread jobs away from `:00`.
 
-### Step 3: Regenerate types and the schedule
+### Step 3: Regenerate
 
 ```bash
 lunora codegen
 ```
 
-Codegen discovers each registration by AST, compiles the schedule to a cron
-expression, and emits `lunora/_generated/crons.ts` (the dispatcher the Worker's
-`scheduled()` handler consumes) plus the matching `triggers.crons` entry in
-`wrangler.jsonc`. You never hand-edit the wrangler schedule array.
+Codegen emits `lunora/_generated/crons.ts` (`LUNORA_CRON_TRIGGERS` plus the
+`LUNORA_CRONS` dispatcher map, which `defineApp` wires into `scheduled()`) and
+syncs `triggers.crons` in `wrangler.jsonc`. Don't hand-edit that array.
+
+**Verify:** the studio's scheduled-jobs view lists each cron and has a "Run now"
+action, which calls the same dispatch path as a real tick.
 
-## Bounded concurrency — workpool (optional)
+## Bounded concurrency: workpool (optional)
 
-For many enqueued jobs that must not all run at once, use a workpool — a named
-logical pool inside the same `SchedulerDO` (no extra binding):
+A workpool is a named pool inside the same `SchedulerDO`. It needs no extra
+binding. Build it in Worker code that has the raw `env`:
 
 ```ts
 import { createWorkpool } from "@lunora/scheduler";
 
-const pool = createWorkpool({
-    namespace: env.SCHEDULER,
-    originUrl: "https://my-app.example.com",
-    name: "imports",
-    maxConcurrency: 3,
-});
+const pool = createWorkpool({ namespace: env.SCHEDULER, name: "imports", maxConcurrency: 3 });
 
-await pool.enqueue(internal.imports.processRow, { rowId });
+await pool.enqueue(internal.imports.processRow, { rowId }, { retry: { maxAttempts: 3 } });
+// pool.cancel(id), pool.status() → { inFlight, queued, maxConcurrency }
 ```
 
-The DO caps simultaneous dispatch at `maxConcurrency` and queues the rest
-durably. A Cloudflare-Queues-backed variant (`createQueueWorkpool`) leans on
-queue config for concurrency/retries instead — reach for the DO workpool when you
-need per-job cancel / status.
+The DO dispatches at most `maxConcurrency` jobs at once and queues the rest
+durably. One alarm drain keeps at most six dispatches in flight (the DO connection limit),
+so a long-running job holds a slot for its whole duration. For individually long jobs
+(LLM calls, exports), prefer `createQueueWorkpool`, which is backed by Cloudflare Queues.
+You give up the hard cap, per-job cancel and per-job status in exchange.
 
 ## Common Pitfalls
 
-1. **Targeting a non-internal function from a job/cron.** Scheduled dispatch has
-   no end-user identity — target `internal.*` functions.
-2. **Non-static `fnRef` or `name` in `cronJobs()`.** Codegen discovers them by
-   AST; a dynamic reference or computed name can't be found.
-3. **Forgetting `lunora codegen` after editing crons.** The `triggers.crons`
-   array and the dispatcher map are codegen output — re-run it.
-4. **Non-idempotent job handlers.** A missed tick may be retried and a slow tick
-   can overlap the next — make handlers idempotent.
-
-## Checklist
-
-- [ ] Deferred work uses `ctx.scheduler.runAfter` / `runAt` against
-      `internal.*` functions.
-- [ ] `SCHEDULER` (SchedulerDO) binding present in `wrangler.jsonc`
-      (`lunora doctor` clean) when using the scheduler.
-- [ ] Recurring jobs declared in `lunora/crons.ts` via `cronJobs()` (after
-      `lunora registry add crons`).
-- [ ] `lunora codegen` run so `_generated/crons.ts` + `triggers.crons` are
-      synced.
-- [ ] Job handlers are idempotent.
+1. **`ORIGIN_NOT_CONFIGURED`**: `LUNORA_ORIGIN_URL` is unset for the `SchedulerDO`
+   (see above).
+2. **`SchedulerDO` not exported** from a hand-written worker entry: wrangler
+   only binds classes the entry exports, so `SCHEDULER` is never provisioned.
+3. **Dynamic `name` or target in `cronJobs()`**: codegen cannot discover it.
+4. **Editing crons without re-running `lunora codegen`**: `triggers.crons` and the
+   dispatcher map are generated output and go stale.
+5. **Non-idempotent handlers**: a failed job is retried, and a slow cron tick
+   can overlap the next one.