@lunora/cli 0.0.0 → 1.0.0-alpha.10

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

@@ -0,0 +1,151 @@
+---
+name: lunora-setup-mail
+description: Adds transactional email to a Lunora app. Use for sending mail (verification, password reset, invites, notifications) via `lunora registry add mail`, the `sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend, React email templates, and the dev mail catcher.
+---
+
+# Lunora Setup Mail
+
+Wire transactional email into a Lunora app using the `mail` registry item, which
+is built on `@lunora/mail` (a Cloudflare Email Workers transport with
+header-injection-safe address handling) and exposes a `sendEmail` action plus a
+fire-and-forget `queueEmail` action. In dev, every send is captured into the
+Studio Mail tab instead of going out.
+
+## When to Use
+
+- Sending app→user mail: invites, notifications, receipts.
+- Delivering verification / password-reset mail from `@lunora/auth`.
+- Using a React (`react-email`) template or a hosted provider (Resend).
+
+## When Not to Use
+
+- The project has no Lunora backend yet — use `lunora-quickstart` first.
+- Mail is already installed and you just want to send — call
+  `ctx.runAction(api.mail.sendEmail, …)` or `client.action("mail/sendEmail", …)`.
+
+## Workflow
+
+1. Add the `mail` item.
+2. Configure the `SEND_EMAIL` binding (or a provider) and `MAIL_FROM`.
+3. Regenerate types with `lunora codegen`.
+4. Send mail from a function (or the client); render a React template if needed.
+
+## Step 1: Add the item
+
+```bash
+lunora registry add mail
+```
+
+This:
+
+1. Adds `@lunora/mail` and `@lunora/server` to `package.json` (run
+   `pnpm install` afterwards).
+2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail` actions) into
+   your project — it is **yours** to edit.
+3. Adds a `send_email` binding (`SEND_EMAIL`, with a `destination_address`
+   placeholder) to `wrangler.jsonc` and scaffolds `MAIL_FROM` (the default
+   sender) into `.dev.vars`.
+
+## Step 2: Configure delivery
+
+| Name             | Where                                | Notes                                                                             |
+| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
+| `SEND_EMAIL`     | `wrangler.jsonc` → `send_email[]`    | Cloudflare Email Workers binding. Single-recipient; only verified destinations.   |
+| `MAIL_FROM`      | var (`.dev.vars` / `wrangler.jsonc`) | Default sender address.                                                           |
+| `RESEND_API_KEY` | secret (optional)                    | Use a hosted provider instead — pass `apiKey` to `createMailer` in `lunora/mail`. |
+
+For production with Cloudflare Email Workers, set up
+[Email Routing](https://developers.cloudflare.com/email-routing/): verify a
+destination address and replace the `REPLACE_ME@example.com` placeholder. Prefer
+Resend? Pass `apiKey` (or a custom `transport`) to `createMailer` in your copied
+`lunora/mail/index.ts`.
+
+In `lunora dev` (`WORKER_ENV=development`) the scaffold swaps in `@lunora/mail`'s
+**capture transport** automatically: every send — including `@lunora/auth`'s
+verification and forgot-password mail — is intercepted and surfaced in the
+**Studio Mail tab**. Nothing leaves your machine and no provider setup is needed.
+
+## Step 3: Regenerate types
+
+```bash
+lunora codegen
+```
+
+The functions surface in the generated `api` as `api.mail.sendEmail` and
+`api.mail.queueEmail`.
+
+## Step 4: Send mail
+
+### From another function
+
+`sendEmail` is an **action** (sending is non-transactional network I/O). From a
+mutation, schedule it as a follow-up so the request is not blocked:
+
+```ts
+import { mutation, v } from "@lunora/server";
+
+import { api } from "./_generated/api";
+
+export const inviteUser = mutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
+    // ...persist the invite, then send the mail as a follow-up action
+    await ctx.scheduler.runAfter(0, api.mail.sendEmail, {
+        to: email,
+        subject: "You're invited",
+        html: "<p>Click the link to join.</p>",
+    });
+});
+```
+
+### From a client
+
+```ts
+await client.action("mail/sendEmail", {
+    to: "alice@example.com",
+    subject: "Welcome",
+    text: "Thanks for signing up!",
+});
+```
+
+### With a React email template
+
+React elements are not JSON-serializable across the RPC boundary, so the
+`sendEmail` args take `html` / `text`. To use a `react-email` template, render it
+where you call the mailer — edit `lunora/mail/index.ts` to pass `react` straight
+into `mailer.send`:
+
+```ts
+import { createMailer } from "@lunora/mail";
+import { env } from "cloudflare:workers";
+
+import { WelcomeEmail } from "./emails/Welcome";
+
+await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM as string }).send({
+    to: "alice@example.com",
+    subject: "Welcome",
+    react: <WelcomeEmail name="Alice" />,
+});
+```
+
+## Common Pitfalls
+
+1. **Expecting prod email to "just work".** Dev captures into the Studio;
+   production needs the `SEND_EMAIL` binding (a verified destination) or
+   `RESEND_API_KEY`.
+2. **Calling `sendEmail` as a query/mutation.** It is an action — invoke it via
+   `ctx.runAction` / `ctx.scheduler.runAfter` / `client.action`, never `ctx.db`.
+3. **Using `queueEmail` without a Queue binding.** It requires a Cloudflare
+   Queue producer binding; until you add one, `@lunora/mail` throws
+   `` `queue` binding is required for mailer.queue() ``. The item does not add
+   the Queue for you — see the `mail` README's "Queueing" section.
+4. **Passing a React element through the action args.** Render it inside the
+   mailer (`mailer.send({ react })`), not across the RPC boundary.
+
+## Checklist
+
+- [ ] `lunora registry add mail` run, `pnpm install` done.
+- [ ] `SEND_EMAIL` binding configured (verified destination) or
+      `RESEND_API_KEY` set; `MAIL_FROM` set.
+- [ ] `lunora codegen` run so `api.mail.*` is generated.
+- [ ] Mail sent from a function (`ctx.scheduler.runAfter`/`ctx.runAction` with
+      `api.mail.sendEmail`) or the client (`client.action("mail/sendEmail", …)`).
+- [ ] Verified the send appears in the Studio Mail tab in dev.

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

@@ -0,0 +1,157 @@
+---
+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.
+---
+
+# Lunora Setup Scheduler
+
+Schedule work in Lunora two ways, both backed by `@lunora/scheduler` (re-exported
+from `@lunora/server`):
+
+- **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`.
+
+Both run jobs through the `SchedulerDO` Durable Object (binding `SCHEDULER`),
+which owns the alarm and durable storage.
+
+## When to Use
+
+- 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).
+
+## When Not to Use
+
+- 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.
+
+## Deferred dispatch — `runAfter` / `runAt`
+
+Available on `ctx.scheduler` in any function. Target functions are passed by
+reference from the generated `api` / `internal` proxy:
+
+```ts
+import { mutation, v } from "@lunora/server";
+
+import { internal } from "./_generated/api";
+
+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 });
+
+    return { jobId: id };
+});
+```
+
+- `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
+
+### Step 1: Add the starter
+
+```bash
+lunora registry add crons
+```
+
+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.
+
+### Step 2: Declare jobs
+
+```ts
+import { cronJobs } from "@lunora/server";
+
+import { internal } from "./_generated/api";
+
+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
+
+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).
+
+### Step 3: Regenerate types and the schedule
+
+```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.
+
+## 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):
+
+```ts
+import { createWorkpool } from "@lunora/scheduler";
+
+const pool = createWorkpool({
+    namespace: env.SCHEDULER,
+    originUrl: "https://my-app.example.com",
+    name: "imports",
+    maxConcurrency: 3,
+});
+
+await pool.enqueue(internal.imports.processRow, { rowId });
+```
+
+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.
+
+## 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.

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

@@ -0,0 +1,158 @@
+---
+name: lunora-setup-storage
+description: Adds R2-backed file storage to a Lunora app. Use for uploads/downloads via `lunora registry add storage`, signed PUT/GET URLs, the `UPLOADS` R2 bucket binding, `STORAGE_SIGNING_SECRET`, per-tenant key scoping, and verifying downloads in the Worker.
+---
+
+# Lunora Setup Storage
+
+Wire R2-backed file storage into a Lunora app using the `storage` registry item,
+which is built on `@lunora/storage` (an R2 adapter plus HMAC signed-URL helpers)
+and exposes idiomatic Lunora functions for direct browser uploads, gated
+downloads, delete, and list — so the bytes never proxy through your Worker.
+
+## When to Use
+
+- Uploading user files (avatars, attachments) straight to R2.
+- Serving private/gated downloads via short-lived signed URLs.
+- Listing or deleting a caller's stored objects.
+
+## When Not to Use
+
+- The project has no Lunora backend yet — use `lunora-quickstart` first.
+- Storage is already installed and you just want to upload — call
+  `client.action("storage/generateUploadUrl", …)` and `PUT` to the returned URL.
+
+## Workflow
+
+1. Add the `storage` item.
+2. Configure the `UPLOADS` R2 bucket binding and the signing secret.
+3. Regenerate types with `lunora codegen`.
+4. Verify signed downloads in the Worker's `GET /storage/:key` route.
+5. Upload/download from the client.
+
+## Step 1: Add the item
+
+```bash
+lunora registry add storage
+```
+
+This:
+
+1. Adds `@lunora/storage` and `@lunora/server` to `package.json` (run
+   `pnpm install` afterwards).
+2. Adds an R2 bucket binding to `wrangler.jsonc` (`r2_buckets`, binding
+   **`UPLOADS`**, `bucket_name: "replace-me-uploads"` — rename it to a real
+   bucket). It **merges** into any existing `r2_buckets`.
+3. Scaffolds `STORAGE_SIGNING_SECRET` (a secret) and `STORAGE_PUBLIC_BASE_URL`
+   into `.dev.vars`.
+4. Copies `lunora/storage/index.ts` (the `generateUploadUrl` /
+   `getDownloadUrl` / `deleteObject` / `listObjects` functions) into your
+   project — it is **yours** to edit.
+
+## Step 2: Configure the binding + secrets
+
+| Name                      | Where                                | Notes                                                                    |
+| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------ |
+| `UPLOADS`                 | `wrangler.jsonc` → `r2_buckets[]`    | The R2 bucket binding. Point `bucket_name` at a real bucket.             |
+| `STORAGE_SIGNING_SECRET`  | secret (`.dev.vars` / `secret put`)  | HMAC secret for signed URLs. Min 32 chars; never share across buckets.   |
+| `STORAGE_PUBLIC_BASE_URL` | var (`.dev.vars` / `wrangler.jsonc`) | Public host/route that fronts the bucket and serves `GET /storage/:key`. |
+
+Generate a real signing secret with `openssl rand -base64 32` and write it with
+`wrangler secret put STORAGE_SIGNING_SECRET` for production.
+
+## Step 3: Regenerate types
+
+```bash
+lunora codegen
+```
+
+The functions surface in the generated `api` as `api.storage.generateUploadUrl`,
+`api.storage.getDownloadUrl`, `api.storage.deleteObject`, and
+`api.storage.listObjects`.
+
+## Step 4: Verify downloads in the Worker
+
+Signed URLs are only as safe as the route that checks them. Gate
+`GET /storage/:key` with `verifySignedUrl` before streaming the R2 body
+(`@lunora/server` also ships `serveStorageObject` to do this):
+
+```ts
+import { verifySignedUrl } from "@lunora/storage";
+
+export default {
+    async fetch(request: Request, env: Env): Promise<Response> {
+        const url = new URL(request.url);
+
+        if (url.pathname.startsWith("/storage/")) {
+            const result = await verifySignedUrl(url, env.STORAGE_SIGNING_SECRET);
+
+            if (!result.valid || result.key === undefined) {
+                // Expose only `valid` — a precise reason is a signing oracle.
+                return new Response("forbidden", { status: 403 });
+            }
+
+            const object = await env.UPLOADS.get(result.key);
+
+            if (!object) {
+                return new Response("not found", { status: 404 });
+            }
+
+            return new Response(object.body, {
+                headers: { "content-type": object.httpMetadata?.contentType ?? "application/octet-stream" },
+            });
+        }
+
+        // ... your Lunora handler
+        return new Response("not found", { status: 404 });
+    },
+};
+```
+
+`verifySignedUrl` checks expiry, then the HMAC. On a host-rewrite / CDN topology
+pass `{ expectedHost }` (the `STORAGE_PUBLIC_BASE_URL` host) so the signature
+canonicalizes against the host it was minted for.
+
+## Step 5: Upload / download from the client
+
+```ts
+// 1. ask the server for a signed PUT URL
+const { key, url } = await client.action("storage/generateUploadUrl", {
+    key: "avatar.png",
+    contentType: file.type,
+});
+
+// 2. upload straight to R2 (no Worker proxy)
+await fetch(url, { method: "PUT", headers: { "content-type": file.type }, body: file });
+
+// 3. later, get a signed GET URL to display it
+const { url: downloadUrl } = await client.action("storage/getDownloadUrl", { key: "avatar.png" });
+```
+
+Every key is scoped per-tenant with `scopeKey(tenantPrefix(ctx.auth.userId),
+key)`, so a client-supplied key can never address another user's data. The
+functions return the **scoped** key (`<userId>/avatar.png`) alongside the URL;
+persist that, and pass the bare key back in — the component re-scopes it.
+
+## Common Pitfalls
+
+1. **Skipping `verifySignedUrl` on the download route.** Without it, anyone can
+   read any key. Always verify before streaming.
+2. **Placeholder bucket name.** `lunora init` and `lunora add storage` prompt for
+   the bucket name (or take `--bucket <name>`), but the low-level
+   `lunora registry add storage` writes the placeholder
+   `bucket_name: "replace-me-uploads"` — rename it to a real R2 bucket. (R2 names
+   are lowercase alphanumeric + hyphens, 3–63 chars; wrangler rejects anything
+   else on `dev`/`deploy`.)
+3. **Short / shared signing secret.** Use ≥32 chars and a distinct secret per
+   bucket; reusing it lets one bucket's URLs sign for another.
+4. **Proxying bytes through the Worker.** The design uploads/downloads directly
+   to R2 via signed URLs — don't re-route the file body through a function.
+
+## Checklist
+
+- [ ] `lunora registry add storage` run, `pnpm install` done.
+- [ ] `UPLOADS` bucket bound to a real bucket; `STORAGE_SIGNING_SECRET` (≥32
+      chars) and `STORAGE_PUBLIC_BASE_URL` set.
+- [ ] `lunora codegen` run so `api.storage.*` is generated.
+- [ ] `GET /storage/:key` route verifies signed URLs before streaming.
+- [ ] Verified a client upload → signed download round-trip.