kitcn 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",
@@ -31,6 +31,8 @@
     "./auth/start/server": "./dist/auth/start/server/index.js",
     "./crpc": "./dist/crpc/index.js",
     "./orm": "./dist/orm/index.js",
+    "./orm/aggregate-index": "./dist/orm/aggregate-index/index.js",
+    "./orm/migrations": "./dist/orm/migrations/index.js",
     "./plugins": "./dist/plugins/index.js",
     "./ratelimit": "./dist/ratelimit/index.js",
     "./ratelimit/react": "./dist/ratelimit/react/index.js",
@@ -73,7 +75,6 @@
     "jose": "^6.1.3",
     "picocolors": "^1.1.1",
     "remeda": "^2.33.6",
-    "svix": "^1.84.1",
     "typescript": "5.9.3",
     "type-fest": "^5.4.4"
   },

package/skills/kitcn/SKILL.md

@@ -171,10 +171,9 @@ Schema rules that matter:
 ### 2) Procedure Builders + Middleware
 
 ```ts
-import { getHeaders } from "kitcn/auth";
+import { getSession } from "kitcn/auth";
 import { CRPCError } from "kitcn/server";
-import { getAuth } from "../functions/generated/auth";
-import { initCRPC } from "../functions/generated/server";
+import { initCRPC, type QueryCtx } from "../functions/generated/server";
 
 const c = initCRPC
   .meta<{
@@ -190,40 +189,42 @@ function requireAuth<T>(user: T | null): T {
   }
   return user;
 }
+async function getSessionUser(ctx: QueryCtx) {
+  const session = await getSession(ctx);
+  if (!session) return null;
+  return await ctx.orm.query.user.findFirst({
+    where: { id: { eq: session.userId } },
+  });
+}
+
 export const publicQuery = c.query.meta({ auth: "optional" });
 export const authQuery = c.query
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   });
 export const authMutation = c.mutation
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 ```
 
 Builder rules that matter:
 
-1. Build `public`, `optional`, `auth`, and `private` procedure families once in `convex/lib/crpc.ts`.
+1. Build `public`, `optional`, `auth`, and `private` procedure families once in `convex/lib/crpc.ts`. Authenticated action builders live in `convex/lib/crpc-action.ts`, the only builder module that imports `getAuth`.
 2. `.meta(...)` is client-visible via generated API metadata. Never put secrets there.
 3. Middleware receives server-only `procedure` info. When procedures are built from your app `generated/server` helper, standard `export const` queries, mutations, and actions infer `module:function` automatically from file path + export name. Use `.name("module:function")` only to override or cover unusual export shapes.
 4. Resolve session/user once in middleware. Do not re-fetch auth state in every procedure.
+   Query/mutation middleware uses `getSession(ctx)` from `kitcn/auth`, which reads the session row
+   directly. Keep `getAuth(ctx)` out of `convex/lib/crpc.ts`: it pulls the whole Better Auth
+   definition and every auth plugin into the static import closure of every procedure module, and
+   Convex has no dynamic `import()` to escape it. Import `getAuth` only in the modules that call
+   `auth.api.*` — `convex/lib/crpc-action.ts`, HTTP routes, and organization/admin mutations.
 5. Shared `c.middleware()` chains preserve mutation writer types on mutation procedures. If the middleware itself performs writes, type it as mutation-only with `c.middleware<MutationCtx>(...)`.
 6. Keep deeper auth/runtime edge cases in `references/setup/server.md` and `references/features/auth*.md`.
 

package/skills/kitcn/references/features/aggregates.md

@@ -9,6 +9,27 @@ Canonical runtime rules:
 - Use `rankIndex` + `rank()` for rankings, random access, sorted pagination
 - `aggregateIndex` and `rankIndex` backfill automatically via `kitcn dev` — no manual trigger wiring needed
 
+## Setup
+
+Aggregate and rank indexes are an optional ORM subsystem. Register it where the ORM is created:
+
+```ts
+import { createOrm } from "kitcn/orm";
+import { aggregateCapability } from "kitcn/orm/aggregate-index";
+
+export const orm = createOrm({ schema, capabilities: [aggregateCapability()] });
+```
+
+`kitcn codegen` writes this into `<functionsDir>/generated/server.ts` for schemas that declare an
+`aggregateIndex` or `rankIndex`, and leaves it out otherwise. Convex bundles everything a module
+statically imports and has no dynamic `import()`, and every procedure module imports
+`generated/server.ts`, so an unused registration would put the aggregate btree in every Convex
+function of the app. Declare the index first, then rerun `kitcn codegen`.
+
+Without the capability, `aggregateIndex`/`rankIndex` schemas and filtered `count()` / `aggregate()`
+/ `groupBy()` / `rank()` / relation `_count` throw a setup error. Unfiltered `count()` and
+`aggregate({ _count: true })` are served by the native Convex count syscall and need nothing.
+
 ## ORM Scalar Metrics
 
 ### `aggregateIndex` Schema Declaration

package/skills/kitcn/references/features/auth-organizations.md

@@ -438,9 +438,9 @@ export const updateOrganization = authMutation
   });
 ```
 
-Use an `authAction` instead of an `authMutation` for any Better Auth endpoint
-that can run external plugin work such as Stripe, Polar, or email delivery.
-Convex mutations cannot call those SDKs.
+Use an `authAction` (from `../lib/crpc-action`) instead of an `authMutation` for
+any Better Auth endpoint that can run external plugin work such as Stripe,
+Polar, or email delivery. Convex mutations cannot call those SDKs.
 
 ### Delete Organization
 

package/skills/kitcn/references/features/auth-polar.md

@@ -435,7 +435,8 @@ export const updateUserPolarCustomerId = privateMutation
 import '../lib/polar-polyfills';
 import { CRPCError } from 'kitcn/server';
 import { z } from 'zod';
-import { authAction, privateMutation, privateQuery } from '../lib/crpc';
+import { privateMutation, privateQuery } from '../lib/crpc';
+import { authAction } from '../lib/crpc-action';
 import { getPolarClient } from '../lib/polar-client';
 import { createPolarSubscriptionCaller } from './generated/polarSubscription.runtime';
 

package/skills/kitcn/references/features/auth.md

@@ -15,7 +15,14 @@ Covers Better Auth integration with Convex: server setup, client hooks, triggers
 | Query/Mutation (`ctx.db`) | Direct DB | No `runQuery`/`runMutation` wrapper |
 | Action/HTTP | HTTP adapter | Uses `ctx.run*` APIs |
 
-**Entrypoint**: `getAuth(ctx)` everywhere (query, mutation, action, HTTP).
+**Entrypoints**:
+
+- `getSession(ctx)` from `kitcn/auth` in queries and mutations, including the shared cRPC auth
+  middleware. It reads the session row directly and keeps the Better Auth definition out of the
+  importing module's static closure.
+- `getAuth(ctx)` only where `auth.api.*` is actually called: `convex/lib/crpc-action.ts`, HTTP
+  routes, and organization/admin mutations. Convex has no dynamic `import()`, so every module that
+  names `getAuth` carries the whole auth definition and its plugins into its evaluation closure.
 
 ## Auth Flow
 

package/skills/kitcn/references/setup/auth.md

@@ -331,11 +331,10 @@ Again: printed payload only. You still need to set the env manually.
 After non-auth baseline is green, replace `convex/lib/crpc.ts` with this auth-aware variant:
 
 ```ts
-import { getHeaders } from "kitcn/auth";
+import { getSession } from "kitcn/auth";
 import { CRPCError } from "kitcn/server";
 
-import { getAuth } from "../functions/generated/auth";
-import { initCRPC } from "../functions/generated/server";
+import { initCRPC, type QueryCtx } from "../functions/generated/server";
 
 const c = initCRPC
   .meta<{
@@ -366,6 +365,14 @@ function requireAuth<T>(user: T | null): T {
   return user;
 }
 
+async function getSessionUser(ctx: QueryCtx) {
+  const session = await getSession(ctx);
+  if (!session) return null;
+  return await ctx.orm.query.user.findFirst({
+    where: { id: { eq: session.userId } },
+  });
+}
+
 export const publicQuery = c.query.meta({ auth: "optional" });
 export const publicAction = c.action;
 export const publicMutation = c.mutation;
@@ -377,28 +384,17 @@ export const privateAction = c.action.internal();
 export const optionalAuthQuery = c.query
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
 
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 
 export const authQuery = c.query
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   })
   .use(roleMiddleware);
@@ -406,43 +402,21 @@ export const authQuery = c.query
 export const optionalAuthMutation = c.mutation
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
 
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 
 export const authMutation = c.mutation
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   })
   .use(roleMiddleware);
 
-export const authAction = c.action
-  .meta({ auth: "required" })
-  .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
-    return next({ ctx: { ...ctx, user, userId: user.id } });
-  });
-
 export const publicRoute = c.httpAction;
 export const authRoute = c.httpAction.use(async ({ ctx, next }) => {
   const identity = await ctx.auth.getUserIdentity();
@@ -480,6 +454,42 @@ export const optionalAuthRoute = c.httpAction.use(async ({ ctx, next }) => {
 export const router = c.router;
 ```
 
+### 6.9.1 Authenticated action builders
+
+Authenticated actions live in their own module. Actions have no `ctx.db`, so they resolve the
+session through `auth.api.getSession` instead of `getSession(ctx)`. `getAuth` carries the whole
+Better Auth definition and every plugin into the static import closure of whatever imports it, and
+Convex has no dynamic `import()`, so it stays out of `convex/lib/crpc.ts` — the module every
+procedure imports.
+
+Skip this file if the app has no authenticated actions.
+
+**Create:** `convex/lib/crpc-action.ts`
+
+```ts
+import { getHeaders } from "kitcn/auth";
+import { CRPCError } from "kitcn/server";
+
+import { getAuth } from "../functions/generated/auth";
+import { publicAction } from "./crpc";
+
+export const authAction = publicAction
+  .meta({ auth: "required" })
+  .use(async ({ ctx, next }) => {
+    const auth = getAuth(ctx);
+    const session = await auth.api.getSession({
+      headers: await getHeaders(ctx),
+    });
+    const user = session?.user;
+    if (!user) {
+      throw new CRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
+    }
+    return next({ ctx: { ...ctx, user, userId: user.id } });
+  });
+```
+
+Import `authAction` from `../lib/crpc-action`. Every other builder comes from `../lib/crpc`.
+
 ### 6.10 Auth sign-in gate (required before Section 7+ and all optional modules/plugins)
 
 Do not continue until all checks below pass:

package/skills/kitcn/references/setup/index.md

@@ -755,7 +755,7 @@ domain depth: `orm.md`, `http.md`, `react.md`, `aggregates.md`,
 | HTTP calls fail but queries work                                                      | `.site` URL missing or wrong                                                                    | Set `NEXT_PUBLIC_CONVEX_SITE_URL` correctly                                                                                                                                                 |
 | Auth works locally but fails in prod                                                  | JWKS not pushed                                                                                 | Run `bunx kitcn env push --prod`                                                                                                                                                    |
 | Sign-in fails on `/auth` (loop, no session, or immediate sign-out)                    | Auth route/env/provider wiring mismatch                                                         | Recheck Sections 6.5-6.7 (`authMiddleware`, route registration, env push), verify provider credentials/URLs, then rerun Section 11.3                                                        |
-| `UNAUTHORIZED` on protected procedures                                                | auth middleware not attaching `userId`                                                          | Ensure `getAuth(ctx)` + `getHeaders(ctx)` session lookup is in middleware                                                                                                                   |
+| `UNAUTHORIZED` on protected procedures                                                | auth middleware not attaching `userId`                                                          | Ensure the `getSession(ctx)` session lookup is in middleware                                                                                                                   |
 | `ctx.orm` missing in handlers                                                         | Generated `initCRPC` not used                                                                   | Use `initCRPC` from `../functions/generated/server` — ORM context is pre-wired                                                                                                              |
 | `Property 'insert'/'update' does not exist on type 'OrmReader'`                       | Using query context for mutations                                                               | Ensure mutation handlers use `publicMutation` / `protectedMutation` builders                                                                                                                |
 | `useCRPC must be used within CRPCProvider`                                            | Provider chain not mounted around route tree                                                    | Wrap app with `AppConvexProvider` and verify `CRPCProvider` is inside QueryClientProvider (Section 7.4 / 8.A.4)                                                                          |

package/skills/kitcn/references/setup/server.md

@@ -175,7 +175,8 @@ export const router = c.router;
 Phase ordering rule:
 
 1. Keep this non-auth baseline until Section 11.2 fully passes.
-2. Only then replace this file with the auth-aware variant in Section 6.9.
+2. Only then replace this file with the auth-aware variant in Section 6.9, and add
+   `convex/lib/crpc-action.ts` from Section 6.9.1 if the app has authenticated actions.
 
 ### 5.4 Shared API/type helpers (generated)