@lunora/cli 1.0.0-alpha.36 → 1.0.0-alpha.360

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

@@ -9,8 +9,10 @@ description: Adds authentication to a Lunora app. Use for sign-up/sign-in, email
 
 Wire authentication into a Lunora app using the `auth` registry item, which is
 built on `@lunora/auth` (a thin wrapper over
-[better-auth](https://www.better-auth.com)) with sessions persisted in
-`SessionDO` and identity tables in D1.
+[better-auth](https://www.better-auth.com)) with identity **and session** tables
+in D1. (`SessionDO` is a standalone TTL'd token store `@lunora/auth` never
+calls — don't wire it for auth. The Durable Object option is `LunoraAuthDO` /
+`.auth({ namespace })`, which holds the whole better-auth schema.)
 
 ## When to Use
 
@@ -104,7 +106,9 @@ dependency). OAuth items need the provider's client id/secret added to
 The runtime resolves the session and exposes the user on every context:
 
 ```ts
-import { LunoraError, mutation, v } from "@lunora/server";
+import { LunoraError } from "lunorash/server";
+
+import { mutation, v } from "#lunora/_generated/server.js";
 
 export const createDocument = mutation.input({ title: v.string() }).mutation(async ({ ctx, args: { title } }) => {
     if (!ctx.auth.userId) {
@@ -119,22 +123,35 @@ call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
 
 ### In the UI (React)
 
+`useAuth()` returns exactly `{ setToken, status, token, user }` — there is no
+`signIn` / `signOut`. Lunora owns the **token**, not the sign-in flow: run the
+flow with the better-auth client (`authClient.signIn.email(...)`), then hand the
+resulting JWT to `setToken`. `setToken(null)` signs out.
+
 ```tsx
 import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
 
+import { authClient } from "./auth-client";
+
 function Account() {
-    const { user, signIn, signOut } = useAuth();
+    const { setToken, user } = useAuth();
+
+    const signIn = async () => {
+        const { data } = await authClient.signIn.email({ email, password });
+
+        setToken(data?.token ?? null);
+    };
 
     return (
         <>
             <Authenticated>
                 <span>Signed in as {user?.email}</span>
-                <button type="button" onClick={() => signOut()}>
+                <button type="button" onClick={() => setToken(null)}>
                     Sign out
                 </button>
             </Authenticated>
             <Unauthenticated>
-                <button type="button" onClick={() => signIn()}>
+                <button type="button" onClick={signIn}>
                     Sign in
                 </button>
             </Unauthenticated>
@@ -146,6 +163,16 @@ function Account() {
 `@lunora/react` also exports `AuthLoading` and `useAuthState` for the loading
 window before the session resolves.
 
+**Branch on `status`, never on `user === null`.** `status` is one of
+`"unauthenticated"`, `"loading"`, `"authenticated"` or `"unreachable"`, and the
+same four values back the gates in every adapter (`@lunora/vue`,
+`@lunora/solid`, `@lunora/svelte`, `@lunora/angular`). `"unreachable"` means the
+credential is held but the session endpoint could not be reached — an offline
+reload, or a transient 5xx. It gates as **authenticated**, so the app renders,
+but `user` may still be `null`; a UI that treats that `null` as signed out shows
+a signed-out screen to a signed-in user. The full contract is documented on
+`AuthStatus` in `@lunora/client/auth`.
+
 ## Common Pitfalls
 
 1. **Declaring better-auth tables in `lunora/schema.ts`.** They live in D1 and

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

@@ -92,24 +92,41 @@ that's a remote resource only `wrangler hyperdrive create` can mint. Importing
 lunora codegen
 ```
 
-When codegen sees `ctx.sql` used, it adds `sql: SqlClient` to **`ActionCtx`
-only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating the
-determinism/realtime caveat.
+When codegen sees `ctx.sql` used, it adds `readonly sql: SqlClient` to
+**`ActionCtx` only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating
+the determinism/realtime caveat, and emits a `.hyperdrive()` method on the
+generated app builder for you to supply the client (step 4).
 
-## Step 4: Use `ctx.sql` from an action
+## Step 4: Wire the client once, on the app builder
 
-```ts
+`ctx.sql` is `readonly` — assigning to it inside a handler is a `TS2540`.
+Codegen cannot build the client for you (turning a connection string into a
+`SqlClient` needs the driver you chose), so it emits a config thunk you fill in
+at the app level. It is called once per shard construction, not per request:
+
+```ts title="src/server/index.ts"
+import type { HyperdriveLike } from "@lunora/hyperdrive";
 import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
 import postgres from "postgres";
 
-import { action, v } from "@lunora/server";
+import { defineApp } from "../lunora/_generated/app.js";
+
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString)))
+    .build();
+
+export const ShardDO = app.ShardDO;
+```
+
+Then read it from any action:
 
-export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
+```ts
+import { action, v } from "@/lunora/_generated/server";
 
-    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
-});
+export const listLegacyOrders = action
+    .input({ orgId: v.string() })
+    .action(async ({ ctx, args: { orgId } }) => ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]));
 ```
 
 The package never rewrites SQL — use your driver's native placeholders (`$1` for
@@ -122,10 +139,13 @@ Postgres change. To make external data reactive, write a projection into a
 `defineSchema` table from the same action — that write _is_ tracked:
 
 ```ts
+import { api } from "@/lunora/_generated/api";
+
 const [row] = await ctx.sql.query<{ id: string; total: number }>("select id, total from orders where id = $1", [id]);
 
-// This write re-runs live queries reading `orders`:
-await ctx.runMutation("orders:upsert", { id: row.id, total: row.total });
+// This write re-runs live queries reading `orders`. Pass the generated
+// reference — `ctx.run*` takes a reference, not a "file:fn" string.
+await ctx.runMutation(api.orders.upsert, { id: row.id, total: row.total });
 ```
 
 ## Common Pitfalls

package/skills/lunora-setup-hyperdrive-global/SKILL.md

@@ -70,6 +70,11 @@ Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev
 }
 ```
 
+The binding is required, not optional: with no `hyperdrive` entry at all,
+`lunora dev` and `lunora deploy` both refuse to start. The NAME is yours — the
+validator only checks that some binding exists, because your `exec` selector is
+what picks it.
+
 > **Read-your-writes:** point the Hyperdrive config at the **primary** (or pin
 > writes to it) so a write then immediate read isn't served by a stale replica.
 

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

@@ -7,8 +7,9 @@ description: Adds transactional email to a Lunora app. Use for sending mail (ver
 
 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
+header-injection-safe address handling) and exposes a `sendEmail` `internalAction`
+plus a fire-and-forget `queueEmail` `internalAction` — server-only, because a
+client-callable general-purpose mailer is an open relay. In dev, every send is captured into the
 Studio Mail tab instead of going out.
 
 ## When to Use
@@ -21,14 +22,14 @@ Studio Mail tab instead of going out.
 
 - 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", …)`.
+  `ctx.runAction(internal.mail.sendEmail, …)` from a server handler.
 
 ## 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.
+4. Send mail from a server function; render a React template if needed.
 
 ## Step 1: Add the item
 
@@ -40,8 +41,8 @@ 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.
+2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail`
+   **`internalAction`s**) 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`.
@@ -71,24 +72,27 @@ verification and forgot-password mail — is intercepted and surfaced in the
 lunora codegen
 ```
 
-The functions surface in the generated `api` as `api.mail.sendEmail` and
-`api.mail.queueEmail`.
+The functions surface in the generated **`internal`** (server-only) namespace as
+`internal.mail.sendEmail` and `internal.mail.queueEmail` — they are deliberately
+**not** in the client-reachable `api`.
 
 ## 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:
+`sendEmail` is an **`internalAction`** (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 { internalMutation, v } from "#lunora/_generated/server.js";
 
-import { api } from "./_generated/api";
+import { internal } from "./_generated/internal";
 
-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, {
+export const inviteUser = internalMutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
+    // ...authenticate the caller and persist the invite, then send the mail as a
+    // follow-up action. The recipient is decided server-side — never forward a
+    // client-chosen `to`/`from`/`html` straight through.
+    await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
         to: email,
         subject: "You're invited",
         html: "<p>Click the link to join.</p>",
@@ -96,15 +100,15 @@ export const inviteUser = mutation.input({ email: v.string() }).mutation(async (
 });
 ```
 
-### From a client
+### Not from a client
 
-```ts
-await client.action("mail/sendEmail", {
-    to: "alice@example.com",
-    subject: "Welcome",
-    text: "Thanks for signing up!",
-});
-```
+There is no `client.action("mail/sendEmail", …)` path, and adding one is the
+mistake this item exists to prevent: a general-purpose mailer that lets the
+caller pick recipient, subject and body is an open relay for phishing through
+your verified domain. If you need a client-callable send, write a
+_purpose-specific_ public `action` that takes only safe business inputs (e.g.
+`{ orderId }`), checks `ctx.auth`/RBAC, derives the recipient server-side,
+rate-limits it (`@lunora/ratelimit`), and calls `internal.mail.sendEmail`.
 
 ### With a React email template
 
@@ -131,8 +135,10 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 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`.
+2. **Calling `sendEmail` from the client, or as a query/mutation.** It is an
+   `internalAction` — invoke it via `ctx.runAction` / `ctx.scheduler.runAfter`
+   from a server handler. A client `client.action("mail/sendEmail", …)` is not
+   reachable and answers `FUNCTION_NOT_FOUND`.
 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
@@ -145,7 +151,7 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 - [ ] `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", …)`).
+- [ ] `lunora codegen` run so `internal.mail.*` is generated.
+- [ ] Mail sent from a server function (`ctx.scheduler.runAfter` / `ctx.runAction`
+      with `internal.mail.sendEmail`) — never from the client.
 - [ ] Verified the send appears in the Studio Mail tab in dev.

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

@@ -31,31 +31,36 @@ which owns the alarm and durable storage.
 
 ## Deferred dispatch — `runAfter` / `runAt`
 
-Available on `ctx.scheduler` in any function. Target functions are passed by
-reference from the generated `api` / `internal` proxy:
+Available on `ctx.scheduler` in a **mutation or an action** — never a `query`,
+which is deterministic and re-runs. Target functions are passed by reference
+from the generated `api` / `internal` objects (a `"file:fn"` path string also
+works):
 
 ```ts
-import { mutation, v } from "@lunora/server";
+import { mutation, v } from "#lunora/_generated/server.js";
 
-import { internal } from "./_generated/api";
+import { internal } from "./_generated/internal";
 
 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 });
+    const jobId = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
 
-    return { jobId: id };
+    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)`;
+- `runAfter(delayMs, fnRef, args?)` — run after a delay (`delayMs` must be a
+  non-negative finite number). `runAt(timestampMs, fnRef, args?)` — run at an
+  epoch-ms timestamp.
+- Both resolve the job id. 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.
+- Those three arguments are the whole `ctx.scheduler` surface. Per-job
+  `RunOptions` — a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`), a
+  `shardKey` routing hint, `pool` — live on `@lunora/scheduler`'s own
+  `createScheduler(...)` client, which you construct yourself when you need them.
+  Jobs scheduled through `ctx.scheduler` take the DO defaults: 5 retries,
+  `backoff: "exponential"`, `baseMs: 30_000`. 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
@@ -79,7 +84,7 @@ project — both **yours** to edit. No extra DO binding is required.
 ```ts
 import { cronJobs } from "@lunora/server";
 
-import { internal } from "./_generated/api";
+import { internal } from "./_generated/internal";
 
 const crons = cronJobs();
 
@@ -93,8 +98,9 @@ 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.
+- `fnRef` must be a static property access on the generated object
+  (`internal.<…path>.<fn>` or `api.<…path>.<fn>`, one segment per folder and
+  file, e.g. `internal.crons.jobs.run`) 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).
@@ -120,7 +126,6 @@ import { createWorkpool } from "@lunora/scheduler";
 
 const pool = createWorkpool({
     namespace: env.SCHEDULER,
-    originUrl: "https://my-app.example.com",
     name: "imports",
     maxConcurrency: 3,
 });