@lunora/cli 0.0.0 → 1.0.0-alpha.2

package/skills/lunora-functions/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: lunora-functions
+description: Authoring rules for Lunora schema and functions. Use when writing or reviewing
+    `lunora/` code — `defineSchema`/`defineTable`, `v.*` validators, query vs
+    mutation vs action (and `internal*`), indexes & `withIndex`, the `ctx.db` API,
+    pagination, scheduling, and `httpAction`.
+---
+
+# Lunora Functions
+
+The core authoring rules for Lunora backend code. Read this before writing or
+changing anything under `lunora/`. After every edit, run `lunora codegen` — it
+regenerates `lunora/_generated/` and typechecks your schema + functions.
+
+## When to Use
+
+- Writing or editing schema, queries, mutations, or actions.
+- Reviewing `lunora/` code for correctness and idiom.
+- Deciding query vs mutation vs action, or public vs internal.
+
+## When Not to Use
+
+- Setting up a new project (`lunora-quickstart`) or auth (`lunora-setup-auth`).
+- Diagnosing a slow query or write conflict (`lunora-performance-audit`).
+- Changing an existing schema with data at rest (`lunora-migration-helper`).
+
+## Schema: `defineSchema` + `defineTable`
+
+`lunora/schema.ts` exports `defineSchema` as the default export. Every column is
+a `v.*` validator. Declare an index for every access pattern you query by.
+
+```ts
+import { defineSchema, defineTable, v } from "@lunora/server";
+
+export default defineSchema({
+    messages: defineTable({
+        channelId: v.id("channels"),
+        authorId: v.id("users"),
+        body: v.string(),
+        createdAt: v.number(),
+    }).index("by_channel", ["channelId", "createdAt"]),
+
+    channels: defineTable({
+        name: v.string(),
+    }),
+});
+```
+
+- Lunora injects `_id` and `_creationTime` on every row — do **not** declare
+  them.
+- `.index("name", ["a", "b"])` — columns are ordered; put equality columns
+  first, then the range/sort column.
+- `.shardBy("ownerId")` partitions the table across Durable Objects by key;
+  `.global()` replicates it to D1 for cross-region reads. Default (neither) is a
+  single root-scoped ShardDO. They are not combined on one table — for choosing
+  between them, see the side-by-side comparison in the `lunora-performance-audit`
+  skill.
+
+### Validators (`v.*`)
+
+`string`, `number`, `boolean`, `id("table")`, `null`, `any`, `bigint`, `bytes`,
+`literal(value)`, `array(item)`, `object({...})`, `record(key, value)`,
+`union(a, b, …)`, `optional(inner)`, plus the convenience types `date`,
+`timestamp`, and `storage` (an R2 object key). Use `v.optional(...)` for nullable
+fields — required is the default.
+
+## Functions: query / mutation / action
+
+Each function declares its inputs with `.input(...)` (a `v.*` map) and ends with a
+terminal `.query` / `.mutation` / `.action` handler. Export them as named
+consts from `lunora/*.ts`; codegen surfaces them as `api.<file>.<name>`.
+
+| Kind       | Reads `ctx.db`                    | Writes `ctx.db` | Side effects / `fetch` | Reactive |
+| ---------- | --------------------------------- | --------------- | ---------------------- | -------- |
+| `query`    | yes                               | no              | no                     | yes      |
+| `mutation` | yes                               | yes             | no                     | —        |
+| `action`   | no (use `runQuery`/`runMutation`) | no              | yes                    | —        |
+
+```ts
+import type { Id } from "@lunora/server";
+import { action, LunoraError, mutation, query, v } from "@lunora/server";
+
+// `api` / `internal` come from codegen:
+// import { api, internal } from "./_generated/api";
+
+export const listByChannel = query.input({ channelId: v.id("channels") }).query(async ({ ctx, args: { channelId } }) =>
+    ctx.db
+        .query("messages")
+        .withIndex("by_channel", (q) => q.eq("channelId", channelId))
+        .collect(),
+);
+
+export const send = mutation
+    .input({ channelId: v.id("channels"), body: v.string() })
+    .mutation(async ({ ctx, args: { channelId, body } }): Promise<Id<"messages">> => {
+        if (!ctx.auth.userId) {
+            throw new LunoraError("UNAUTHORIZED", "not signed in");
+        }
+        return ctx.db.insert("messages", {
+            channelId,
+            authorId: ctx.auth.userId as Id<"users">,
+            body,
+            createdAt: Date.now(),
+        });
+    });
+
+export const notifySlack = action.input({ messageId: v.id("messages") }).action(async ({ ctx, args: { messageId } }) => {
+    const message = await ctx.runQuery(api.messages.getById, { messageId });
+    await fetch(SLACK_WEBHOOK, { method: "POST", body: JSON.stringify(message) });
+});
+```
+
+- **Pick the right kind.** Reactive read → `query`. Transactional write →
+  `mutation`. External I/O (`fetch`, third-party SDKs, calling other functions)
+  → `action`. An action has no `ctx.db`; it reaches data via `ctx.runQuery` /
+  `ctx.runMutation`.
+- **`internal*` variants** (`internalQuery`, `internalMutation`,
+  `internalAction`) are not exposed to clients — use them for server-only logic
+  called from actions, crons, or other functions.
+- **Throw `LunoraError`** (`import { LunoraError } from "@lunora/server"`) with a
+  code + message for expected failures; it serializes cleanly to the client.
+
+## The `ctx.db` API
+
+Reads:
+
+```ts
+await ctx.db.get(id);                                  // one row by id (or null)
+ctx.db.query("t").withIndex("by_x", (q) => q.eq("x", v)); // indexed query
+  .collect();   // all matching rows
+  .first();     // first row or null
+  .unique();    // exactly one (throws if 0 or >1)
+  .take(n);     // first n rows
+  .order("asc" | "desc")  // sort by the index range
+  .paginate(opts);        // cursor page (pair with usePaginatedQuery)
+```
+
+Writes (mutations only):
+
+```ts
+await ctx.db.insert("t", { ...fields }); // returns the new Id
+await ctx.db.patch(id, { field: next }); // shallow-merge update
+await ctx.db.replace(id, { ...allFields }); // full overwrite
+await ctx.db.delete(id);
+```
+
+**Prefer `withIndex` over `.filter`.** A `.filter(...)` with no covering index
+scans the whole table — `@lunora/advisor` flags it as `filter-without-index`.
+Declare the index and constrain with `.withIndex`.
+
+## Other `ctx` capabilities
+
+`ctx.auth` (the resolved session: `ctx.auth.userId`), `ctx.scheduler`
+(`runAfter` / `runAt` for deferred work), `ctx.storage` (R2), `ctx.vectors`
+(Vectorize), and — when their packages are wired — `ctx.ai` and `ctx.containers`.
+
+## HTTP endpoints
+
+For webhooks or non-RPC HTTP, use `httpRouter` / `httpRoute` + `httpAction`:
+
+```ts
+import { httpAction, httpRouter } from "@lunora/server";
+
+export default httpRouter({
+    "/webhooks/stripe": httpAction(async (ctx, request) => {
+        const event = await request.json();
+        await ctx.runMutation(internal.billing.record, { event });
+        return new Response("ok");
+    }),
+});
+```
+
+## Checklist
+
+- [ ] Schema columns are `v.*` validators; `_id`/`_creationTime` not declared.
+- [ ] An index exists for every access pattern; queries use `withIndex`, not
+      `.filter`.
+- [ ] Right function kind: `query` (reactive read) / `mutation` (write) /
+      `action` (side effects via `runQuery`/`runMutation`).
+- [ ] Server-only logic uses `internal*`; expected failures throw `LunoraError`.
+- [ ] `ctx.db` writes only inside mutations; ids typed with `Id<"table">`.
+- [ ] Ran `lunora codegen`; typecheck is clean.

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.