@lunora/cli 1.0.0-alpha.361 → 1.0.0-alpha.363

package/skills/lunora-functions/SKILL.md

@@ -1,16 +1,26 @@
 ---
 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`.
+description: Authoring rules for Lunora schema and server functions under `lunora/` —
+    `defineSchema`/`defineTable`, `v.*` validators, the generated
+    `query`/`mutation`/`action` builders (and `internal*`), indexes and
+    `withIndex`, the `ctx.db` API, pagination, `ctx.db.related`, opt-in `ctx.*`
+    capabilities, topics, modules, services, and `httpAction`. Use when writing or
+    reviewing files in `lunora/` (`schema.ts`, function files, `http.ts`,
+    `queues.ts`), when asked to "add a query/mutation/action", "add an index",
+    "call one function from another", or "add a webhook endpoint", or when
+    `lunora codegen` reports an error in a function.
 ---
 
 # 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.
+The core authoring rules for Lunora backend code. The verify loop after every
+edit:
+
+1. `lunora codegen` — regenerates `lunora/_generated/` and prints advisor
+   findings (it does not run `tsc`).
+2. `lunora verify` — codegen dry-run plus `tsc --noEmit`, no files written. The
+   type-check needs a `tsconfig.json` (without one it warns and skips) and is
+   off under `--no-typecheck`.
 
 ## When to Use
 
@@ -30,7 +40,7 @@ regenerates `lunora/_generated/` and typechecks your schema + functions.
 a `v.*` validator. Declare an index for every access pattern you query by.
 
 ```ts
-import { defineSchema, defineTable, v } from "@lunora/server";
+import { defineSchema, defineTable, v } from "lunorash/server";
 
 export default defineSchema({
     messages: defineTable({
@@ -46,8 +56,9 @@ export default defineSchema({
 });
 ```
 
-- Lunora injects `_id` and `_creationTime` on every row — do **not** declare
-  them.
+- Lunora injects `_id` and `_creationTime` on every row, so don't declare them.
+- `lunorash/*` is the umbrella package templates install; `@lunora/server` is
+  the same module if the project depends on it directly.
 - `.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;
@@ -60,15 +71,26 @@ export default defineSchema({
 
 `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.
+`union(a, b, …)`, `optional(inner)`, `partial({...})`, `geoPoint()`, the
+convenience types `date`, `timestamp`, and `storage` (an R2 object key), and
+`v.from(schema)` to adopt any Standard Schema v1 validator (Zod, Valibot, …).
+
+- Required is the default. `v.optional(x)` means the field may be absent;
+  `x.nullable()` means it may be `null`. They are different.
+- Refinements chain on the validator and are enforced at the trust boundary:
+  `v.string().min(1).max(4096)`, `.email()`, `.url()`, `.pattern(re)`;
+  `v.number().int().min(0)`, `.positive()`; `v.array(x).max(n)`. Bound every
+  client-supplied string and array — templates cap text at `.max(4096)`.
 
 ## 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>`.
+Each function declares its inputs with `.input(...)` (a `v.*` map), optionally
+adds `.use(middleware)` (rate limiting, RLS, masking) and `.output(validator)`,
+and ends with a terminal `.query` / `.mutation` / `.action` taking a
+`({ ctx, args }) => …` handler. Export them as named consts from `lunora/*.ts`.
+Codegen nests references by path: `lunora/messages.ts` → `api.messages.<fn>`,
+`lunora/billing/invoices.ts` → `api.billing.invoices.<fn>`. Public functions
+land in `_generated/api.ts`, `internal*` ones in `_generated/internal.ts`.
 
 | Kind       | Reads `ctx.db` | Writes `ctx.db`     | Side effects / `fetch` | Reactive |
 | ---------- | -------------- | ------------------- | ---------------------- | -------- |
@@ -76,26 +98,24 @@ consts from `lunora/*.ts`; codegen surfaces them as `api.<file>.<name>`.
 | `mutation` | yes            | yes, transactional  | no                     | —        |
 | `action`   | yes            | yes, autocommitting | yes                    | —        |
 
-The builders are **generated**, not imported from `@lunora/server`: codegen binds
-them to your schema, so `ctx.db`, `v.id("channels")`, and index names are all
-typed. `@lunora/server` exports the schema/HTTP/validator surface and
+Import the builders from `_generated/server`, not from `lunorash/server`: codegen
+binds them to your schema, which is what types `ctx.db`, `v.id("channels")`, and
+index names. `lunorash/server` exports the schema/HTTP/validator surface and
 `LunoraError`, never `query` / `mutation` / `action`.
 
 ```ts
+// lunora/messages.ts
 import { LunoraError } from "lunorash/server";
 
-import type { Id } from "#lunora/_generated/server.js";
-import { action, mutation, query, v } from "#lunora/_generated/server.js";
+import { api } from "./_generated/api.js";
+import type { Doc, Id } from "./_generated/server.js";
+import { action, mutation, query, v } from "./_generated/server.js";
 
-// `api` / `internal` come from codegen:
-// import { api } from "./_generated/api";
-// import { internal } from "./_generated/internal";
-
-export const listByChannel = query.input({ channelId: v.id("channels") }).query(async ({ ctx, args: { channelId } }) =>
+export const listByChannel = query.input({ channelId: v.id("channels") }).query(async ({ ctx, args: { channelId } }): Promise<Doc<"messages">[]> =>
     ctx.db
         .query("messages")
         .withIndex("by_channel", (q) => q.eq("channelId", channelId))
-        .collect(),
+        .take(100),
 );
 
 export const send = mutation
@@ -112,25 +132,37 @@ export const send = mutation
         });
     });
 
-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) });
+export const notifySlack = action.input({ channelId: v.id("channels") }).action(async ({ ctx, args: { channelId } }) => {
+    // A public action is callable by anyone: gate it like a mutation (and check
+    // channel access too, if your app has per-channel membership).
+    if (!ctx.auth.userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+    const messages = await ctx.runQuery(api.messages.listByChannel, { channelId });
+    const response = await fetch(String(ctx.env?.SLACK_WEBHOOK_URL), { method: "POST", body: JSON.stringify(messages) });
+    if (!response.ok) {
+        throw new Error(`Slack webhook failed: ${String(response.status)}`); // fetch resolves on 4xx/5xx
+    }
 });
 ```
 
+Templates also map `#lunora/*` to `./lunora/*` in `package.json` `imports`, so
+`#lunora/_generated/server.js` works from anywhere in the project.
+
 - **Pick the right kind.** Reactive read → `query`. Transactional write →
   `mutation`. External I/O (`fetch`, third-party SDKs, calling other functions)
   → `action`. An action has a `ctx.db`, but its own writes are not
   transactional: each autocommits as it runs, so a later throw rolls nothing
   back. Reach data through `ctx.runQuery` / `ctx.runMutation` — a mutation
   called that way runs in the same all-or-nothing transaction a top-level one
-  gets, so put every write that has to land together in ONE mutation rather
+  gets, so put every write that has to land together in one mutation rather
   than sequencing several from the action.
 - **`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.
+- **Throw `LunoraError(code, message?, options?)`** from `lunorash/server` for
+  expected failures (`"UNAUTHORIZED"`, `"NOT_FOUND"`, …); it serializes with its
+  code to the client, where `isUnauthorizedError` and friends branch on it.
 
 ## The `ctx.db` API
 
@@ -139,15 +171,16 @@ 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
+  .order("asc" | "desc")  // by the active index (or _creationTime)
+  .filter((doc) => …)     // JS predicate, applied after the index range
   .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)
+  .first();     // first row or null
+  .unique();    // the one match, null if none; throws if more than one
+  .paginate({ numItems, cursor }); // { page, isDone, continueCursor }
 ```
 
-Writes (mutations only):
+Writes (mutations, and autocommitting in actions):
 
 ```ts
 await ctx.db.insert("t", { ...fields }); // returns the new Id
@@ -156,9 +189,32 @@ 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`.
+Prefer `withIndex` over `.filter`: a `.filter(...)` without a covering index
+scans the whole table (advisor: `filter_without_index`), and a bare `.collect()`
+grows with the table and with every subscriber's payload (`unbounded_collect`).
+Constrain with `.withIndex`, cap with `.take(n)`, or paginate.
+
+### Pagination
+
+A paginated query takes a `paginationOpts` arg and returns `.paginate(...)`
+as-is; the client hook (`usePaginatedQuery`, see `lunora-realtime`) supplies it:
+
+```ts
+// `v.any()` would type the arg `unknown`, which `.paginate()` rejects. The hook
+// also sends `endCursor`; an undeclared key is stripped, so declare it. Bound
+// `numItems` too: it is caller input and sets the read limit.
+const cursor = v.optional(v.union(v.string(), v.null()));
+
+export const page = query
+    .input({ channelId: v.id("channels"), paginationOpts: v.object({ cursor, endCursor: cursor, numItems: v.number().int().min(1).max(100) }) })
+    .query(async ({ ctx, args: { channelId, paginationOpts } }) =>
+        ctx.db
+            .query("messages")
+            .withIndex("by_channel", (q) => q.eq("channelId", channelId))
+            .order("desc")
+            .paginate(paginationOpts),
+    );
+```
 
 ### Following foreign keys: `ctx.db.related`
 
@@ -183,14 +239,14 @@ for (const node of nodes) {
 ```
 
 - **Edge names are `"<table>.<column>"`.** `edges` restricts the walk to the
-  named ones; a name the schema does not declare is **refused**, not ignored.
+  named ones; a name the schema does not declare is refused, not ignored.
 - **`direction`** — `"out"` follows the ids this row holds, `"in"` the rows that
   point at it, `"both"` (the default) does both.
 - **`depth`** defaults to `1`, max `4`. **`limit`** defaults to `50`, max `200`.
-  Both caps **refuse rather than clamp**, so do not probe for the ceiling.
+  Both caps refuse rather than clamp, so a probe for the ceiling just errors.
 - **Only a column is an edge**: a bare `v.id(...)`, `v.optional(v.id(...))` or
   `v.array(v.id(...))`. An id nested in a `v.object` / `v.union` / `v.record` is
-  not. An array FK is followed **outward only**.
+  not. An array FK is followed outward only.
 - **It is an ordinary read** — RLS, column masks, soft delete, `.global()`
   routing and reactivity all apply, because every hop goes back through
   `ctx.db`. Under a `.rls("required")` schema each hop gets exactly the verdict a
@@ -204,35 +260,40 @@ for (const node of nodes) {
 
 Always available:
 
-- `ctx.auth` — the resolved session (`ctx.auth.userId`).
-- `ctx.scheduler` — `runAfter` / `runAt` for deferred work.
+- `ctx.auth` — the resolved session (`ctx.auth.userId`, `null` when anonymous).
 - `ctx.secrets` — Cloudflare Secrets Store.
-- `ctx.span` / `ctx.trace` — the current span and a scoped tracing helper for
-  wide events.
-
-Added by their package when wired. **A dependency in `package.json` is not
-enough** — codegen scans the `lunora/` source set and flips a capability on only
-when a file there imports the `@lunora/*` package or reads its `ctx.*` helper.
-So write the call first, then run `lunora codegen` to surface the typed context:
-
-| `ctx.*`                                                                                   | Package                       |
-| ----------------------------------------------------------------------------------------- | ----------------------------- |
-| `ctx.storage`                                                                             | `@lunora/storage` (R2)        |
-| `ctx.ai`                                                                                  | `@lunora/ai` (Workers AI)     |
-| `ctx.flags`                                                                               | `@lunora/flags` (OpenFeature) |
-| `ctx.queues.<name>`                                                                       | `@lunora/queue`               |
-| `ctx.topics.<name>` (pub/sub, see below)                                                  | `@lunora/queue`               |
-| `ctx.workflows` / `ctx.runStep`                                                           | `@lunora/workflow`            |
-| `ctx.containers`                                                                          | `@lunora/container`           |
-| `ctx.browser` (action-only)                                                               | `@lunora/browser`             |
-| `ctx.sql` (action-only)                                                                   | `@lunora/hyperdrive`          |
-| `ctx.kv` / `ctx.images` / `ctx.analytics` / `ctx.pipelines` / `ctx.vectors` / `ctx.r2sql` | `@lunora/bindings` subpaths   |
-
-Two exceptions to the usage scan, and one extra requirement:
+- `ctx.ip` — the caller's `CF-Connecting-IP`; `undefined` off Cloudflare.
+- `ctx.runQuery` (all kinds), `ctx.runMutation` (mutations, actions),
+  `ctx.runAction` (actions) — call another function by its `api.*` /
+  `internal.*` reference.
+- `ctx.log`, `ctx.metrics`, `ctx.span` / `ctx.trace` — logging, metrics, the
+  current wide-event span and a scoped tracing helper.
+
+Wired by codegen on use. A dependency in `package.json` is not enough: codegen
+scans the `lunora/` source set and turns a capability on only when a file there
+imports its `@lunora/*` package or reads its `ctx.*` helper. Write the call
+first, then run `lunora codegen` to wire the binding and typed context:
+
+| `ctx.*`                                                             | Package                       |
+| ------------------------------------------------------------------- | ----------------------------- |
+| `ctx.scheduler` (mutations + actions; see `lunora-setup-scheduler`) | `@lunora/scheduler`           |
+| `ctx.storage` (R2; see `lunora-setup-storage`)                      | `@lunora/storage`             |
+| `ctx.ai`                                                            | `@lunora/ai` (Workers AI)     |
+| `ctx.flags`                                                         | `@lunora/flags` (OpenFeature) |
+| `ctx.queues.<name>`                                                 | `@lunora/queue`               |
+| `ctx.topics.<name>` (pub/sub, see below)                            | `@lunora/queue`               |
+| `ctx.workflows` / `ctx.runStep`                                     | `@lunora/workflow`            |
+| `ctx.containers`                                                    | `@lunora/container`           |
+| `ctx.browser` (action-only)                                         | `@lunora/browser`             |
+| `ctx.sql` (action-only)                                             | `@lunora/hyperdrive`          |
+| `ctx.kv` / `ctx.images` / `ctx.analytics`                           | `@lunora/bindings` subpaths   |
+| `ctx.pipelines` / `ctx.vectors` / `ctx.r2sql`                       | `@lunora/bindings` subpaths   |
+
+One exception to the usage scan, and one extra requirement:
 
 - **`ctx.flags` gates on a declaration file**, not on usage — codegen wires it
-  only when `lunora/flags.ts` exists (`vis generate lunora-flags` creates it).
-  `ctx.notify` / `ctx.push` work the same way via `lunora/notify.ts`.
+  only when `lunora/flags.ts` exists. `ctx.notify` / `ctx.push` work the same
+  way via `lunora/notify.ts`.
 - **`ctx.sql` also needs the real resource.** Codegen types the field, but the
   connection needs a `HYPERDRIVE` binding (`wrangler hyperdrive create`) and an
   explicit `createHyperdrive(ctx.env.HYPERDRIVE)` + driver adapter in the
@@ -255,7 +316,7 @@ dead-letter queue.
 // lunora/queues.ts
 import { defineSubscription, defineTopic } from "@lunora/queue";
 
-import { internal } from "./_generated/internal";
+import { internal } from "./_generated/internal.js";
 
 export const signups = defineTopic<{ userId: string }>();
 
@@ -291,7 +352,7 @@ that drive the Studio **Architecture** view, OpenAPI tags, and table ownership:
 
 ```ts
 // lunora/billing/module.ts
-import { defineModule } from "@lunora/server";
+import { defineModule } from "lunorash/server";
 
 export default defineModule({ description: "Invoices and payments", tables: ["invoices"] });
 ```
@@ -350,37 +411,77 @@ never mount.
 
 ```ts
 // lunora/http.ts
-import { httpAction, httpRouter } from "@lunora/server";
+import { httpRouter } from "lunorash/server";
 
-import { internal } from "./_generated/internal";
+import { internal } from "./_generated/internal.js";
 
 const app = httpRouter();
+const encoder = new TextEncoder();
 
-app.post(
-    "/webhooks/stripe",
-    httpAction(async (ctx, request) => {
-        const event = await request.json();
+// Stripe's scheme: `stripe-signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`.
+// The Stripe SDK's `stripe.webhooks.constructEventAsync` does the same check.
+const verifyStripe = async (secret: string, header: string | undefined, payload: string): Promise<boolean> => {
+    const fields = header?.split(",").map((part) => part.split("=", 2)) ?? [];
+    const t = fields.find(([k]) => k === "t")?.[1];
+    // While a secret is being rolled Stripe sends one `v1` per secret; accept any.
+    const v1s = fields.filter(([k, value]) => k === "v1" && /^[\da-f]{64}$/.test(value ?? "")).map(([, value]) => value ?? "");
 
-        await ctx.runMutation(internal.billing.record, { event });
+    if (!t || v1s.length === 0 || Math.abs(Date.now() / 1000 - Number(t)) > 300) {
+        return false; // missing, malformed, or outside the 5-minute replay window
+    }
 
-        return new Response("ok");
-    }),
-);
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const signed = encoder.encode(`${t}.${payload}`);
+
+    for (const v1 of v1s) {
+        const signature = Uint8Array.from(v1.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16));
+
+        if (await crypto.subtle.verify("HMAC", key, signature, signed)) {
+            return true; // constant-time compare
+        }
+    }
+
+    return false;
+};
+
+// A plain Hono handler, not `httpAction`: the action ctx (`c.var.lunora`) has
+// no env, while `c.env` is the Worker env.
+app.post("/webhooks/stripe", async (c) => {
+    const secret = c.env.STRIPE_WEBHOOK_SECRET;
+
+    if (typeof secret !== "string") {
+        throw new Error("STRIPE_WEBHOOK_SECRET is not set");
+    }
+
+    const payload = await c.req.text(); // the raw bytes the signature covers
+
+    if (!(await verifyStripe(secret, c.req.header("stripe-signature"), payload))) {
+        return c.text("invalid signature", 401);
+    }
+
+    await c.var.lunora.runMutation(internal.billing.record, { event: JSON.parse(payload) as unknown });
+
+    return c.text("ok");
+});
 
 export default app;
 ```
 
+A webhook route is public: verify the provider's signature over the raw body
+before any write, or anyone can forge events into `internal.*` functions.
+
 ## Checklist
 
 - [ ] Schema columns are `v.*` validators; `_id`/`_creationTime` not declared.
 - [ ] An index exists for every access pattern; queries use `withIndex`, not
-      `.filter`.
+      `.filter`, and are bounded (`.take(n)` / `.paginate`).
+- [ ] Client-supplied strings and arrays carry a `.max(...)`.
 - [ ] 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">`.
+- [ ] Writes that must land together sit in one mutation; ids typed `Id<"table">`.
 - [ ] Any `ctx.db.related` walk is narrowed with `edges` / `direction`, and its
       foreign keys are indexed.
 - [ ] Writes to a module- or component-owned table go through the owner's
       functions (`cross_module_table_write` is clean).
-- [ ] Ran `lunora codegen`; typecheck is clean.
+- [ ] `lunora codegen` shows no new advisor findings; `lunora verify` is clean.