@lunora/cli 0.0.0 → 1.0.0-alpha.10

package/skills/lunora-migration-helper/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: lunora-migration-helper
+description: Plans Lunora schema and data migrations with widen-migrate-narrow. Use for
+    breaking schema changes, backfills, table reshaping, online data migrations
+    (`defineMigration` + `lunora migrate up`), the `.global()` D1 SQL flow, and the
+    pre-deploy schema-drift gate.
+---
+
+# Lunora Migration Helper
+
+Safely change a Lunora schema and migrate data when making breaking changes.
+
+## When to Use
+
+- Adding required fields to existing tables.
+- Changing field types or structure.
+- Splitting/merging tables, renaming/removing fields.
+- Reshaping `.global()` (D1-backed) tables.
+
+## When Not to Use
+
+- Greenfield schema with no data at rest.
+- Adding **optional** fields that need no backfill.
+- Adding new tables or indexes with no correctness concern.
+
+## Two Storage Layers — Know Which You Are Migrating
+
+Lunora tables live in one of two backends, and they migrate differently:
+
+- **ShardDO SQLite (default `root`, and `.shardBy(key)` tables).** State lives in
+  the per-app / per-shard Durable Object. Data is reshaped with **online data
+  migrations** — `defineMigration` declarations run by `lunora migrate up`,
+  resumable per shard.
+- **`.global()` tables (D1).** Replicated to D1 for cross-region reads. Their
+  structural DDL gets versioned **SQL migrations** via `lunora migrate generate`,
+  applied by `@lunora/d1`'s runner at deploy time.
+
+A breaking change to a `.global()` table needs a generated SQL migration; a data
+backfill (either layer) is an online `defineMigration`. Both follow the same
+**widen → migrate → narrow** discipline.
+
+## Key Principle: Widen, Migrate, Narrow
+
+The schema-drift gate (and D1 itself) will not let a breaking change deploy
+without an accompanying migration. So every breaking change is staged:
+
+1. **Widen** — make the schema accept both old and new shapes (add the new field
+   as `v.optional`, keep the old one). Update reads to handle both; start writing
+   the new shape for new rows. Deploy.
+2. **Migrate** — backfill existing rows to the new shape (an online
+   `defineMigration` run with `lunora migrate up`; plus `lunora migrate generate`
+   for `.global()` structural DDL). Verify completeness with `lunora migrate
+status`.
+3. **Narrow** — make the field required / drop the old field, remove the
+   both-shapes read code. Deploy.
+
+### Prefer new fields over changing types
+
+When changing a field's shape, add a new field rather than mutating the existing
+one — safer transition, easier rollback.
+
+### Don't delete data prematurely
+
+Prefer deprecating: mark the old field `v.optional` with a `// deprecated:` code
+comment explaining why it existed. Delete only once you are sure nothing reads
+it.
+
+## Safe Changes (No Migration Needed)
+
+```ts
+// Adding an optional field — safe.
+users: defineTable({
+    name: v.string(),
+    bio: v.optional(v.string()),
+});
+
+// Adding a new table — safe.
+posts: defineTable({ userId: v.id("users"), title: v.string() }).index("by_user", ["userId"]);
+
+// Adding an index — safe.
+users: defineTable({ name: v.string(), email: v.string() }).index("by_email", ["email"]);
+```
+
+## Online Data Migrations (the backfill workhorse)
+
+For backfilling/reshaping rows, declare a migration with `defineMigration` from
+`@lunora/server`. It transforms one document at a time, runs **inside each
+shard's** Durable Object in keyset batches, and is **resumable** — per-shard
+progress is tracked in a reserved `__lunora_migrations` table, so an interrupted
+run resumes where it stopped. Codegen discovers declarations and emits them into
+the registry the DO and CLI look up by `id`.
+
+```ts
+// lunora/migrations/backfill-display-name.ts
+import { defineMigration } from "@lunora/server";
+
+export default defineMigration({
+    id: "backfill-display-name",
+    table: "users",
+    batchSize: 200, // optional; defaults to the runner's batch size
+    up: (doc) => {
+        if (typeof doc.displayName === "string") {
+            return; // already migrated — return undefined to skip (not counted as changed)
+        }
+        return { ...doc, displayName: doc.name ?? "Anonymous" };
+    },
+    // optional reverse transform applied by `lunora migrate down`
+    down: (doc) => {
+        const { displayName, ...rest } = doc as Record<string, unknown>;
+        return rest;
+    },
+});
+```
+
+The transform must preserve row identity — the runner always keeps the original
+`_id` / `_creationTime`, so do not change them.
+
+### Run it
+
+```bash
+lunora migrate create backfill-display-name   # scaffold the migration file
+lunora codegen                                 # discover + register it
+lunora migrate up backfill-display-name --dry-run   # preview, no rows rewritten
+lunora migrate up backfill-display-name        # run across shards (keyset batches)
+lunora migrate status backfill-display-name    # per-shard progress
+lunora migrate down backfill-display-name      # revert (if `down` defined)
+```
+
+Useful flags: `--batch-size <n>`, `--steps <n>` (cap batches this run), and
+`--prod --url <worker> --yes` to target production (with `LUNORA_ADMIN_TOKEN`).
+
+## `.global()` (D1) Structural Migration Flow
+
+```bash
+# 1. Edit lunora/schema.ts (widen: add the optional new field to the .global() table).
+lunora codegen
+
+# 2. Generate the SQL migration by diffing schema against the snapshot baseline.
+lunora migrate generate --name=add_user_status
+
+# Writes lunora/migrations/<timestamp>_add_user_status.sql and updates
+# lunora/migrations/.snapshot.json. Review the SQL before committing.
+
+# 3. Deploy — @lunora/d1's runner applies pending migrations.
+lunora deploy
+```
+
+`lunora migrate generate` only considers `.global()` tables (root/sharded tables
+are not D1-backed). Run it after each schema edit in the widen and narrow steps;
+backfill data with an online migration between them.
+
+## The Schema-Drift Gate
+
+`lunora deploy` (and `verify` / `prepare`) run a **pre-deploy schema-drift gate**:
+it compares the committed structural baseline (`lunora/.lunora-schema.json`)
+against the snapshot codegen produced this run. Breaking drift **without an
+accompanying data migration blocks the deploy**. The baseline is only re-blessed
+_after_ the deploy succeeds, so a failed deploy never advances it past a change
+that never shipped.
+
+If the gate blocks you: that is the signal to stage the change (widen first) or
+add the migration — not to bypass it.
+
+## Common Pitfalls
+
+1. **Making a field required before backfilling.** The drift gate / D1 rejects
+   the deploy because existing rows lack it. Widen first.
+2. **Reshaping rows by hand instead of `defineMigration`.** A hand-rolled
+   `internalMutation` that `.collect()`s a large table hits transaction limits
+   and is not resumable. Use `defineMigration` — it batches and tracks per-shard
+   progress.
+3. **Not writing the new shape during the migration window.** Rows created mid-
+   migration get missed, leaving unmigrated data after it "completes." Start
+   dual-writing in the widen step.
+4. **Skipping the dry run.** `lunora migrate up <id> --dry-run` validates the
+   transform before it touches real rows.
+5. **Deleting a field prematurely.** Deprecate with `v.optional` + a comment;
+   delete only once nothing references it.
+6. **Migrating the wrong layer.** A `.global()` structural change needs `lunora
+migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
+   table's `.global()` / `.shardBy()` modifier first.
+
+## Checklist
+
+- [ ] Identified the change and which layer it touches (ShardDO vs `.global()`).
+- [ ] Widened the schema to accept both shapes; `lunora codegen` clean.
+- [ ] Updated reads to handle both shapes; started writing the new shape.
+- [ ] Deployed the widened schema.
+- [ ] Authored a `defineMigration`; previewed with `lunora migrate up --dry-run`.
+- [ ] Ran `lunora migrate up`; `lunora migrate generate` + deploy for `.global()`
+      structural changes.
+- [ ] Verified completion with `lunora migrate status`.
+- [ ] Narrowed the schema (required / drop old field); removed both-shapes code.
+- [ ] Deployed the final schema; schema-drift gate passed.

package/skills/lunora-performance-audit/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: lunora-performance-audit
+description: Diagnoses and fixes Lunora performance problems — full-table scans, missing
+    indexes, OCC write conflicts, oversized subscriptions, and sharding/`.global()`
+    scaling. Use when queries are slow, mutations conflict, or `@lunora/advisor`
+    flags a table.
+---
+
+# Lunora Performance Audit
+
+Systematically diagnose Lunora performance issues, route to the right fix, and
+apply it across sibling functions consistently.
+
+## When to Use
+
+- Queries feel slow or read far more rows than they return.
+- Mutations retry or conflict under load (OCC).
+- Subscriptions fan out updates too broadly or re-run too often.
+- The Lunora Studio **Advisors** tab or `@lunora/advisor` flags a table.
+
+## When Not to Use
+
+- Scale is small, traffic is modest, and there is no measured problem — prefer
+  simpler code. Do not introduce sharding, digests, or splits on speculation.
+
+## Core Workflow
+
+1. **Scope** one concrete user flow with a clear entry and exit.
+2. **Trace** every `ctx.db` read and write in that flow.
+3. **Route** to the matching problem class below.
+4. **Fix siblings** consistently — every function touching the same table should
+   read it the same indexed way.
+5. **Verify** behavior is unchanged and the advisor finding clears.
+
+## Signal Gathering
+
+Start with the static advisors — they need no traffic:
+
+- **Lunora Studio → Advisors tab** surfaces `@lunora/advisor` findings live in
+  dev.
+- `@lunora/advisor` runs static lints over `defineSchema` + discovered query
+  reads / insert writes. Relevant performance/schema rules:
+    - `filter-without-index` — a query filters a table with no covering index.
+    - `unindexed-foreign-key` — a relation/FK column has no index.
+    - `duplicate-index` / `empty-index` — wasted or malformed indexes.
+    - `index-references-unknown-field`, `relation-references-unknown-field`,
+      `relation-references-unknown-table` — broken index/relation definitions.
+    - `table-without-insert` — a table is read but never written (often a
+      schema/typo signal).
+
+## Problem Class: Read Amplification (the common one)
+
+**Symptom:** a query reads the whole table to return a few rows;
+`filter-without-index` fires.
+
+**Fix:** read through an index, not `.filter()`. Declare the index on the table
+and use `.withIndex()` with an equality/range on the leading columns.
+
+```ts
+// Bad — scans every row, then filters in memory.
+const mine = (await ctx.db.query("documents").collect()).filter((d) => d.orgId === orgId);
+
+// Good — declare the index…
+documents: defineTable({ orgId: v.string(), createdAt: v.number() /* … */ }).index("by_org_created", ["orgId", "createdAt"]);
+
+// …and read through it.
+const mine = await ctx.db
+    .query("documents")
+    .withIndex("by_org_created", (q) => q.eq("orgId", orgId))
+    .collect();
+```
+
+Index columns are ordered: put equality columns first, then the range/sort
+column. Fix every sibling query on the table the same way.
+
+## Problem Class: Write Conflicts (OCC)
+
+**Symptom:** mutations on hot rows retry or fail under concurrency. ShardDO uses
+optimistic concurrency control — concurrent writes to the same DO that touch
+overlapping state conflict and retry.
+
+**Fixes, in order of preference:**
+
+1. **Narrow the write.** Patch only the fields that changed; avoid read-modify-
+   write over rows another mutation also touches.
+2. **Partition with `.shardBy(key)`.** Move per-user / per-tenant / per-room
+   state into its own DO so writes for different keys never contend. This is the
+   primary horizontal-scale lever — most write contention is a single-DO
+   hotspot.
+3. **Avoid unbounded counters/aggregates in the hot path.** Accumulate in a
+   sharded/append shape and fold lazily rather than serializing every writer
+   through one row.
+
+## Problem Class: Subscription Cost
+
+**Symptom:** a `useQuery` re-runs and re-pushes to many clients on unrelated
+writes.
+
+**Fixes:**
+
+- **Scope query args tightly** so a subscription only depends on the rows it
+  renders — a query keyed by `orgId` should not re-run for another org's write.
+- **Read through indexes** (above) so the reactive dependency is the narrow
+  index range, not the whole table.
+- ShardDO subscriptions are **hibernated WebSockets** — idle connections cost
+  nothing; the lever is _how many rows each live query depends on_, not raw
+  connection count.
+
+## Problem Class: Cross-Region Reads
+
+**Symptom:** read-heavy, rarely-written data is slow for far-away users.
+
+**Fix:** chain `.global()` on the table to replicate it to D1 for low-latency
+cross-region reads (with read-your-writes via the Sessions API). Reserve it for
+read-mostly tables — `.global()` adds the D1 migration flow (see the
+`lunora-migration-helper` skill) and write-path cost.
+
+### `.shardBy(key)` vs `.global()` — choose one per table
+
+- `.shardBy(key)`: partitions a table across Durable Objects by key — scales
+  _writes_ (e.g. messages per room). Reads are per-shard.
+- `.global()`: replicates a table to D1 — scales _cross-region reads_ with
+  read-your-writes (e.g. a mostly-read catalog).
+- They are not combined on the same table; the default (neither) is a single
+  root-scoped ShardDO.
+
+## Guardrails
+
+- Prefer simpler code when scale is small or the signal is weak.
+- Do not recommend structural changes (digest tables, document splitting,
+  sharding) without a measured signal or a known hot path.
+- When you change how one function reads/writes a table, change its siblings to
+  match — half-migrated access patterns are their own bug.
+
+## Checklist
+
+- [ ] Scoped one concrete flow; traced every `ctx.db` read/write.
+- [ ] Checked the Studio Advisors tab / `@lunora/advisor` findings.
+- [ ] Read amplification: replaced `.filter()` with an indexed `.withIndex()`.
+- [ ] Write conflicts: narrowed writes and/or partitioned with `.shardBy(key)`.
+- [ ] Subscription cost: scoped query args so live queries depend on few rows.
+- [ ] Cross-region: applied `.global()` only to read-mostly tables.
+- [ ] Fixed sibling functions consistently; verified behavior unchanged.

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.