@lunora/cli 0.0.0 → 1.0.0-alpha.2

package/skills/lunora-quickstart/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: lunora-quickstart
+description: Creates or adds Lunora to an app. Use for new Lunora projects, `lunora init`,
+    framework/provider wiring, the first `lunora dev` run, env vars, or writing
+    the first schema + query/mutation round-trip.
+---
+
+# Lunora Quickstart
+
+Set up a working Lunora project as fast as possible.
+
+## When to Use
+
+- Starting a brand new project with Lunora.
+- Adding Lunora to an existing Vite, Next.js, Astro, Nuxt, SvelteKit, or
+  TanStack Start app.
+- Scaffolding a Lunora app for prototyping.
+
+## When Not to Use
+
+- The project already has Lunora installed and `lunora/` exists — just build,
+  and run `lunora codegen` after schema/function edits.
+- You only need to add auth to an existing Lunora app — use the
+  `lunora-setup-auth` skill.
+
+## Workflow
+
+1. Determine the starting point: new project or existing app.
+2. New project: scaffold with `lunora init` and pick a template.
+3. Existing app: run `lunora init --here` to patch the Vite config and wire
+   Lunora into the current project.
+4. Run `lunora codegen` to generate `lunora/_generated/` and typecheck the
+   schema + functions. This is the agent's feedback loop.
+5. Start the dev loop with `lunora dev` (ask the user to run it locally, or
+   start it in the background for cloud/headless agents — it is long-running and
+   does not exit).
+6. Verify a query/mutation round-trip works end to end.
+
+## Path 1: New Project (Recommended)
+
+`lunora init` fetches a whole-project template (frontend + worker entry + Vite
+plugin + `lunora/` already wired together).
+
+```bash
+lunora init my-app --template vite
+cd my-app
+pnpm install
+```
+
+### Pick a template
+
+| Template               | Stack                                          |
+| ---------------------- | ---------------------------------------------- |
+| `vite`                 | React + Vite (the simplest full-stack starter) |
+| `standalone`           | Worker-only Lunora backend, no frontend        |
+| `astro`                | Astro integration                              |
+| `nuxt`                 | Nuxt (Vue)                                     |
+| `sveltekit`            | SvelteKit                                      |
+| `tanstack-start-react` | TanStack Start (React)                         |
+| `tanstack-start-solid` | TanStack Start (Solid)                         |
+
+If the user has not specified a preference, default to `vite`. Pass `--template`
+explicitly to avoid the interactive prompt. Templates are fetched remotely (via
+`giget`) from `gh:anolilab/lunora/templates/<type>`; pass `--from <dir>` to use a
+local template directory offline.
+
+### Generate types and push the first run
+
+Run this yourself — it is one-shot and exits cleanly:
+
+```bash
+lunora codegen
+```
+
+It writes `lunora/_generated/` and typechecks your schema + functions. Read its
+output to find out whether the code you just wrote is valid.
+
+### Start the dev loop
+
+```bash
+lunora dev
+```
+
+`lunora dev` runs the Vite dev server with the Cloudflare Worker on the same
+origin, plus codegen-on-save and the Lunora Studio. It is long-running and does
+not exit, so:
+
+- **Local development (user at the keyboard):** ask the user to run `lunora dev`
+  in a terminal.
+- **Cloud or headless agents:** start `lunora dev` in the background.
+
+Vite serves on `http://localhost:5173` by default; the Worker is served on the
+same origin via `@cloudflare/vite-plugin`.
+
+## Path 2: Add Lunora to an Existing App
+
+Use this when the user already has a Vite-based frontend and wants Lunora as the
+backend.
+
+```bash
+lunora init --here
+```
+
+This finds the existing `vite.config.*` (or creates a minimal one), patches in
+the Lunora Vite plugin, and scaffolds a starter `lunora/`. Then run
+`lunora codegen` and `lunora dev` as above.
+
+### Wire up the client provider
+
+Create the `LunoraClient` once at module scope (never inside a component) and
+wrap the app with the framework provider. React example:
+
+```tsx
+// src/client/main.tsx
+import { LunoraClient } from "@lunora/client";
+import { LunoraProvider } from "@lunora/react";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App";
+
+// @cloudflare/vite-plugin serves the Worker on the same origin as Vite.
+const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
+const client = new LunoraClient({ url });
+
+createRoot(document.querySelector("#root")!).render(
+    <StrictMode>
+        <LunoraProvider client={client}>
+            <App />
+        </LunoraProvider>
+    </StrictMode>,
+);
+```
+
+Vue, Solid, and Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
+and `@lunora/svelte`. `VITE_LUNORA_URL` is optional — it defaults to
+`location.origin`, which is correct for the single-origin dev setup.
+
+## Writing Your First Function
+
+Create a schema and a query/mutation to verify the full loop.
+
+`lunora/schema.ts`:
+
+```ts
+import { defineSchema, defineTable, v } from "@lunora/server";
+
+export default defineSchema({
+    todos: defineTable({
+        text: v.string(),
+        done: v.boolean(),
+        createdAt: v.number(),
+    }).index("by_creation", ["createdAt"]),
+});
+```
+
+`lunora/todos.ts`:
+
+```ts
+import type { Id } from "@lunora/server";
+import { mutation, query, v } from "@lunora/server";
+
+export const list = query.query(async ({ ctx }) => ctx.db.query("todos").withIndex("by_creation").collect());
+
+export const add = mutation
+    .input({ text: v.string() })
+    .mutation(async ({ ctx, args: { text } }): Promise<Id<"todos">> => ctx.db.insert("todos", { text, done: false, createdAt: Date.now() }));
+```
+
+Run `lunora codegen`, then use it in a component. The `api` object and `Doc` /
+`Id` types come from `lunora/_generated/`:
+
+```tsx
+import { useMutation, useQuery } from "@lunora/react";
+
+import { api } from "../../lunora/_generated/api";
+import type { Doc } from "../../lunora/_generated/dataModel";
+
+function Todos() {
+    const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
+    const { mutate: add, pending } = useMutation(api.todos.add);
+
+    return (
+        <div>
+            <button disabled={pending} onClick={() => add({ text: "New todo" })}>
+                Add
+            </button>
+            {todos?.map((t) => (
+                <div key={t._id}>{t.text}</div>
+            ))}
+        </div>
+    );
+}
+```
+
+`useQuery` opens a live subscription: the list re-renders the instant any
+mutation changes the queried rows.
+
+## Development vs Production
+
+Use `lunora dev` during development. When ready to ship:
+
+```bash
+lunora deploy
+```
+
+`lunora deploy` runs codegen, the schema-drift gate, and `wrangler deploy`. Do
+not use it during day-to-day development.
+
+Before deploying, run the preflight:
+
+```bash
+lunora doctor
+```
+
+It checks `wrangler.jsonc` (the `SHARD` durable-object binding), D1 placeholder
+ids, `.dev.vars` secrets, and container exports.
+
+## Next Steps
+
+- Add authentication: use the `lunora-setup-auth` skill.
+- Add a prebuilt capability (mail, presence, storage, rate limit, crons):
+  `lunora registry add <item>` (see `lunora registry list`). For capabilities
+  with a dedicated skill, use it: `lunora-setup-mail`, `lunora-setup-storage`,
+  `lunora-setup-scheduler`. See the `lunora` router's capability entry for the
+  full routing.
+- Build your own reusable capability: use the `lunora-create-package` skill.
+- Plan a schema change: use the `lunora-migration-helper` skill.
+- Scaffold more functions: `vis generate lunora-query --name=listMessages`,
+  `lunora-mutation`, `lunora-action`, `lunora-table`, `lunora-cron` (always use
+  the `--name=value` form).
+
+## Checklist
+
+- [ ] Determined starting point: new project or existing app.
+- [ ] New project: scaffolded with `lunora init --template <t>`.
+- [ ] Existing app: ran `lunora init --here` and wired `LunoraProvider`.
+- [ ] Ran `lunora codegen`: `lunora/_generated/` exists and typecheck is clean.
+- [ ] `lunora dev` is running — user terminal, or background for cloud agents.
+- [ ] Verified a query/mutation round-trip re-renders the client live.

package/skills/lunora-realtime/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: lunora-realtime
+description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
+    reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
+    pagination, connection status, the React/Vue/Solid/Svelte adapters, and the
+    `@lunora/db` TanStack binding.
+---
+
+# Lunora Realtime
+
+Consume Lunora functions reactively from the client. Queries are live
+subscriptions over WebSocket — a `useQuery` re-renders the instant a mutation
+changes the rows it reads — and mutations can paint optimistically with
+automatic rollback.
+
+## When to Use
+
+- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
+- Adding optimistic updates, pagination, or presence to the UI.
+- Choosing between live hooks and the `@lunora/db` collection layer.
+
+## When Not to Use
+
+- Writing the server functions themselves — that's `lunora-functions`.
+- Initial project/provider scaffolding — that's `lunora-quickstart`.
+
+## Provider Setup
+
+Create the `LunoraClient` once at module scope and wrap the app. The client owns
+the WebSocket, the optimistic cache, and the offline queue.
+
+```tsx
+import { LunoraClient } from "@lunora/client";
+import { LunoraProvider } from "@lunora/react";
+
+const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
+const client = new LunoraClient({ url });
+
+// <LunoraProvider client={client}>…</LunoraProvider>
+```
+
+Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
+`@lunora/svelte`; the hook names and semantics below mirror across them.
+
+## Live Queries
+
+`useQuery(reference, args)` opens a subscription and returns the value, or
+`undefined` while it loads. The reference comes from codegen
+(`api.<file>.<name>`).
+
+```tsx
+import { useQuery } from "@lunora/react";
+
+import { api } from "../../lunora/_generated/api";
+import type { Doc } from "../../lunora/_generated/dataModel";
+
+const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
+```
+
+- `undefined` means "loading" — render a skeleton/spinner for it.
+- The subscription tears down on unmount and re-runs only when `args` change or
+  the underlying rows change. Keep `args` narrow so a write elsewhere doesn't
+  re-push unrelated data (see `lunora-performance-audit`).
+- `useSubscription` is the lower-level primitive for streaming subscriptions;
+  `usePreloadedQuery` + `lunoraQueryOptions` support SSR/preload handoff via
+  `@lunora/react/server`.
+
+## Authorization & Live Queries
+
+Subscriptions re-run the query handler **server-side under anonymous
+identity**. The one-shot `fetch` RPC behind the initial load carries the
+caller's identity, but the live WebSocket channel (the subscription seed and
+every write-driven refresh) does not — it evaluates as anonymous.
+
+This matters for any query that authorizes or filters on the authenticated
+user:
+
+- A query guarded by `.use(rls(...))` or one that reads `ctx.auth.userId`
+  directly returns the user's rows on the **initial** HTTP fetch, but its
+  **live** updates evaluate anonymously and may resolve to an empty/denied
+  set.
+- This **fails closed** — the live channel shows _less_ data, never another
+  user's data, so there is no leak. But it is a correctness caveat: the
+  initial render and the live updates can disagree.
+
+The supported pattern today is to scope per-user data **outside** of
+`ctx.auth` inside a subscribed query:
+
+- Partition the data by shard with `.shardBy(userId)` (or tenant/room), so the
+  subscription is already scoped to the right state, or
+- Pass the identifier as an **explicit query arg**
+  (`useQuery(api.todos.list, { userId })`) and filter on the arg rather than on
+  `ctx.auth`.
+
+Reserve `rls()` / `ctx.auth`-based filtering for non-subscribed reads (one-shot
+actions/queries) where identity is always present.
+
+## Mutations + Optimistic Updates
+
+`useMutation(reference)` returns `{ mutate, pending }`. Pass an `optimistic`
+callback to paint the next state immediately; if the server rejects the call the
+runtime rolls the cache back automatically.
+
+```tsx
+import { useMutation } from "@lunora/react";
+
+import type { Doc, Id } from "../../lunora/_generated/dataModel";
+
+const { mutate: add, pending } = useMutation(api.todos.add);
+
+await add(
+    { text },
+    {
+        optimistic: (current) => {
+            const list = (current as Doc<"todos">[] | undefined) ?? [];
+            const provisional: Doc<"todos"> = {
+                _id: `optimistic_${Date.now()}` as Id<"todos">,
+                _creationTime: Date.now(),
+                text,
+                done: false,
+                createdAt: Date.now(),
+            };
+            return [provisional, ...list];
+        },
+    },
+);
+```
+
+- The `optimistic` callback receives the current cached value and returns the
+  provisional one. When the server delta arrives it replaces the optimistic
+  entry; on failure the cache reverts.
+- `pending` is `true` while the call is in flight — disable the submit button
+  with it.
+- **Offline queue:** mutations made while disconnected are queued by
+  `LunoraClient` and replayed on reconnect (client-id-keyed, so they aren't
+  double-applied).
+
+## Pagination, Connection, Presence
+
+- `usePaginatedQuery` / `useInfiniteQuery` — cursor pagination over a query that
+  ends in `.paginate(...)` on the server.
+- `useConnectionStatus` — live socket state for an offline/reconnecting banner.
+- `usePresence` — who's-here + heartbeat (pairs with the `presence` registry
+  item).
+- `useAuth` + the `Authenticated` / `Unauthenticated` / `AuthLoading` gates —
+  see `lunora-setup-auth`.
+
+## `@lunora/db` — TanStack DB Collections
+
+For richer client state (indexed local collections, cross-query joins, a durable
+offline-transactions outbox), use `@lunora/db` instead of raw hooks. Scaffold
+with `vis generate lunora-collections` (wires `defineCollections` from your
+schema + functions into live TanStack DB collections). Reach for it when the app
+needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery`
+/`useMutation` are enough for straightforward live lists.
+
+## Common Pitfalls
+
+1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
+   render — create it once at module scope.
+2. **Treating `undefined` as empty.** `undefined` is "loading", `[]` is "loaded,
+   empty" — branch on both.
+3. **Broad query args.** A subscription keyed too broadly re-renders on
+   unrelated writes; scope `args` to what the component shows.
+4. **Optimistic shape drift.** The provisional value must match the query's
+   element shape (including `_id`/`_creationTime`) or the UI flickers when the
+   real delta lands.
+
+## Checklist
+
+- [ ] `LunoraClient` created once at module scope; app wrapped in the provider.
+- [ ] Live reads use `useQuery`; `undefined` handled as loading.
+- [ ] Writes use `useMutation`; `pending` disables submit; `optimistic` matches
+      the row shape.
+- [ ] Query `args` scoped narrowly to avoid over-broad re-renders.
+- [ ] Pagination via `usePaginatedQuery`/`useInfiniteQuery` over `.paginate`.
+- [ ] Considered `@lunora/db` if the app needs local indexes/joins or an outbox.

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

@@ -0,0 +1,170 @@
+---
+name: lunora-setup-auth
+description: Adds authentication to a Lunora app. Use for sign-up/sign-in, email/password,
+    OAuth (Clerk, Auth0), magic link, or email OTP via `lunora registry add auth`,
+    wiring the auth handler into the Worker, and gating functions on the session.
+---
+
+# Lunora Setup Auth
+
+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.
+
+## When to Use
+
+- Adding sign-up / sign-in to a Lunora app.
+- Adding an OAuth/OIDC provider (Clerk, Auth0), magic link, or email OTP.
+- Gating queries/mutations on the signed-in user.
+
+## When Not to Use
+
+- The project has no Lunora backend yet — use `lunora-quickstart` first.
+- You only need to read `ctx.auth.userId` in a function and auth is already
+  installed — just use it.
+
+## Workflow
+
+1. Add the base `auth` item.
+2. Mount the auth request handler in the Worker entry.
+3. Configure env vars and the D1 database.
+4. (Optional) Layer a provider item (Clerk / Auth0 / magic link / OTP) on top.
+5. Gate functions on `ctx.auth.userId`; gate UI with the auth gates/hooks.
+
+## Step 1: Add the base item
+
+```bash
+lunora registry add auth
+```
+
+This:
+
+1. Adds `@lunora/auth`, `@lunora/mail`, and `@lunora/server` to `package.json`
+   (run `pnpm install` afterwards).
+2. Copies `lunora/auth/index.ts` — the auth instance (`buildAuth` / `getAuth`)
+   and the `/api/auth/*` request handler (`mountAuth`) — into your project. It is
+   **yours** to edit.
+3. Adds a D1 `DB` binding to `wrangler.jsonc` (better-auth persists
+   users/sessions there).
+4. Scaffolds `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and `MAIL_FROM` into
+   `.dev.vars`.
+
+## Step 2: Mount the handler
+
+In your Worker entry, route `/api/auth/*` to the scaffolded handler (see the
+generated `lunora/auth/index.ts` README block). `createWorker` handles the rest
+of the RPC surface; the auth handler owns the better-auth endpoints.
+
+## Step 3: Env vars and the D1 database
+
+| Var                  | Secret | Notes                                                               |
+| -------------------- | ------ | ------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | yes    | Encryption secret, min 32 chars. `openssl rand -base64 32`.         |
+| `BETTER_AUTH_URL`    | no     | Public base URL, e.g. `http://localhost:8787` in dev, your domain.  |
+| `MAIL_FROM`          | no     | Sender for verification / reset mail. Captured in the dev Mail tab. |
+
+Create the D1 database and paste its id into the `DB` binding in
+`wrangler.jsonc`:
+
+```bash
+wrangler d1 create my-app-db
+```
+
+The better-auth schema (user/session/account/verification tables) is **not**
+declared in `lunora/schema.ts` — it is managed by better-auth in D1. In dev,
+`ensureMigrated(auth)` auto-applies it; in production prefer
+`compileMigrationsSql(auth.options)` piped to `wrangler d1 execute`. Run
+`lunora doctor` to confirm the `DB` binding has a real `database_id` (not a
+placeholder).
+
+Verification and password-reset emails are **captured into the Lunora Studio
+Mail tab** in dev with zero email setup. For real delivery, `lunora registry add
+mail` (adds the `SEND_EMAIL` binding) or set `RESEND_API_KEY`.
+
+## Step 4: Add a provider (optional)
+
+Each provider item builds on the base `auth` item (`requires: ["auth"]`):
+
+```bash
+lunora registry add auth-clerk        # Clerk via better-auth genericOAuth
+lunora registry add auth-auth0        # Auth0 via better-auth genericOAuth
+lunora registry add auth-magic-link   # passwordless magic-link (mail)
+lunora registry add auth-otp          # passwordless email one-time-password
+```
+
+Add the base `auth` item first (or let the registry resolve the `requires`
+dependency). OAuth items need the provider's client id/secret added to
+`.dev.vars`.
+
+## Step 5: Use the session
+
+### In functions
+
+The runtime resolves the session and exposes the user on every context:
+
+```ts
+import { LunoraError, mutation, v } from "@lunora/server";
+
+export const createDocument = mutation.input({ title: v.string() }).mutation(async ({ ctx, args: { title } }) => {
+    if (!ctx.auth.userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+    return ctx.db.insert("documents", { ownerId: ctx.auth.userId, title, createdAt: Date.now() });
+});
+```
+
+For richer checks (org membership, roles), compose `withAuthPlugins(auth)` and
+call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
+
+### In the UI (React)
+
+```tsx
+import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
+
+function Account() {
+    const { user, signIn, signOut } = useAuth();
+
+    return (
+        <>
+            <Authenticated>
+                <span>Signed in as {user?.email}</span>
+                <button type="button" onClick={() => signOut()}>
+                    Sign out
+                </button>
+            </Authenticated>
+            <Unauthenticated>
+                <button type="button" onClick={() => signIn()}>
+                    Sign in
+                </button>
+            </Unauthenticated>
+        </>
+    );
+}
+```
+
+`@lunora/react` also exports `AuthLoading` and `useAuthState` for the loading
+window before the session resolves.
+
+## Common Pitfalls
+
+1. **Declaring better-auth tables in `lunora/schema.ts`.** They live in D1 and
+   are managed by better-auth — do not add them to `defineSchema`.
+2. **Placeholder `database_id`.** The `DB` binding ships with a placeholder;
+   `wrangler d1 create` + paste the id, then `lunora doctor` to confirm.
+3. **Missing/short `BETTER_AUTH_SECRET`.** better-auth needs ≥32 chars;
+   `@lunora/auth` surfaces a clear error when it is absent.
+4. **Expecting prod email to "just work".** Dev captures mail into the Studio;
+   production needs `mail` (the `SEND_EMAIL` binding) or `RESEND_API_KEY` and a
+   verified sender domain.
+
+## Checklist
+
+- [ ] `lunora registry add auth` run, `pnpm install` done.
+- [ ] Auth handler mounted in the Worker entry.
+- [ ] `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` / `MAIL_FROM` set in `.dev.vars`.
+- [ ] D1 database created and its id pasted into the `DB` binding (`lunora
+doctor` clean).
+- [ ] Provider item added if needed (Clerk / Auth0 / magic link / OTP).
+- [ ] Functions gate on `ctx.auth.userId`; UI uses the auth gates/`useAuth`.
+- [ ] Verified sign-in → session → an authenticated query round-trip.