kitcn 0.0.1 → 0.12.0

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

@@ -0,0 +1,473 @@
+## 5. Core Backend
+
+For production bootstrap, start in the CLI Registry: use `bunx kitcn init -t <next|vite> --yes` for the shortest fresh local path, `bunx kitcn init --yes` to adopt the current app and finish the first local Convex bootstrap in one command, and `bunx kitcn add <plugin>` for feature layers. This file is the manual backend wiring reference.
+
+### 5.1 Define schema and relations
+
+**Create:** `convex/functions/schema.ts`
+
+```ts
+import {
+  boolean,
+  convexTable,
+  defineSchema,
+  index,
+  text,
+  timestamp,
+} from "kitcn/orm";
+
+export const user = convexTable(
+  "user",
+  {
+    name: text().notNull(),
+    email: text().notNull(),
+    emailVerified: boolean().notNull(),
+    image: text(),
+    createdAt: timestamp().notNull().defaultNow(),
+    updatedAt: timestamp().notNull(),
+    role: text(),
+    banned: boolean(),
+    banReason: text(),
+    banExpires: timestamp(),
+  },
+  (t) => [index("email").on(t.email)]
+);
+
+export const session = convexTable(
+  "session",
+  {
+    token: text().notNull(),
+    userId: text()
+      .references(() => user.id, { onDelete: "cascade" })
+      .notNull(),
+    expiresAt: timestamp().notNull(),
+    createdAt: timestamp().notNull().defaultNow(),
+    updatedAt: timestamp().notNull(),
+    ipAddress: text(),
+    userAgent: text(),
+    impersonatedBy: text(),
+  },
+  (t) => [index("token").on(t.token), index("userId").on(t.userId)]
+);
+
+export const account = convexTable(
+  "account",
+  {
+    accountId: text().notNull(),
+    providerId: text().notNull(),
+    userId: text()
+      .references(() => user.id, { onDelete: "cascade" })
+      .notNull(),
+    accessToken: text(),
+    refreshToken: text(),
+    idToken: text(),
+    accessTokenExpiresAt: timestamp(),
+    refreshTokenExpiresAt: timestamp(),
+    scope: text(),
+    password: text(),
+    createdAt: timestamp().notNull().defaultNow(),
+    updatedAt: timestamp().notNull(),
+  },
+  (t) => [index("accountId").on(t.accountId), index("userId").on(t.userId)]
+);
+
+export const verification = convexTable(
+  "verification",
+  {
+    identifier: text().notNull(),
+    value: text().notNull(),
+    expiresAt: timestamp().notNull(),
+    createdAt: timestamp().notNull().defaultNow(),
+    updatedAt: timestamp().notNull(),
+  },
+  (t) => [index("identifier").on(t.identifier)]
+);
+
+export const jwks = convexTable("jwks", {
+  publicKey: text().notNull(),
+  privateKey: text().notNull(),
+  createdAt: timestamp().notNull().defaultNow(),
+});
+
+export const project = convexTable(
+  "project",
+  {
+    name: text().notNull(),
+    ownerId: text()
+      .references(() => user.id, { onDelete: "cascade" })
+      .notNull(),
+    createdAt: timestamp().notNull().defaultNow(),
+    updatedAt: timestamp().notNull(),
+  },
+  (t) => [index("ownerId_updatedAt").on(t.ownerId, t.updatedAt)]
+);
+
+export const tables = { user, session, account, verification, jwks, project };
+
+export default defineSchema(tables, {
+  strict: false,
+}).relations((r) => ({
+  user: {
+    projects: r.many.project(),
+    sessions: r.many.session(),
+    accounts: r.many.account(),
+  },
+  project: {
+    owner: r.one.user({ from: r.project.ownerId, to: r.user.id }),
+  },
+  session: {
+    user: r.one.user({ from: r.session.userId, to: r.user.id }),
+  },
+  account: {
+    user: r.one.user({ from: r.account.userId, to: r.user.id }),
+  },
+}));
+```
+
+### 5.1.1 Reserved index fields (important)
+
+Do not index `createdAt` directly in kitcn ORM examples.
+`createdAt` maps to Convex internal `_creationTime`, and explicit indexes on it can fail.
+Prefer `updatedAt` (or a dedicated sortable field) for custom index definitions.
+
+### 5.2 Attach ORM once (`ctx.orm`)
+
+Do **not** create `convex/lib/orm.ts`.
+`convex/functions/generated/` directory is generated and is the canonical server contract.
+It includes `initCRPC` (from `generated/server`) and ORM helpers when schema relations metadata exists.
+If you are not using codegen, use manual `initCRPC` from `kitcn/server` with `.dataModel()` and optional `.context()`.
+
+Why this shape:
+
+1. `orm.with(ctx)` preserves query vs mutation capabilities in type space.
+2. It avoids common setup-time type failures like missing `insert`/`update` on `ctx.orm` in mutation handlers.
+
+### 5.3 Initialize cRPC and procedure builders
+
+**Create:** `convex/lib/crpc.ts`
+
+```ts
+import { initCRPC } from "../functions/generated/server";
+
+const c = initCRPC
+  .meta<{
+    // Reserved for auth phase; do not implement auth logic yet.
+    auth?: "optional" | "required";
+    role?: "admin";
+    ratelimit?: string;
+  }>()
+  .create();
+
+// Phase 1 baseline: public + private only.
+// Do not add auth-aware builders until Section 6.9 and Section 11.3 pass.
+export const publicQuery = c.query;
+export const publicAction = c.action;
+export const publicMutation = c.mutation;
+
+export const privateQuery = c.query.internal();
+export const privateMutation = c.mutation.internal();
+export const privateAction = c.action.internal();
+
+export const publicRoute = c.httpAction;
+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.
+
+### 5.4 Shared API/type helpers (generated)
+
+Do **not** create `convex/shared/api.ts` manually.
+It is generated by `kitcn dev`.
+
+Generated exports include:
+
+1. `api` (typed procedure leaves + metadata)
+2. `Api`, `ApiInputs`, `ApiOutputs`
+3. `TableName`, `Select`, `Insert` (when `schema.ts` exports `tables`)
+
+Consume these from `@convex/api` on app/client side.
+Within Convex backend files, import server context/ORM helpers from `../functions/generated/server`.
+
+### 5.5 Start dev/codegen
+
+Run:
+
+```bash
+bunx kitcn dev
+```
+
+If this requires interactive Convex setup, let `bunx kitcn dev` drive it first. Use `bunx convex init` only when you need to resolve deployment targeting separately.
+Do not fake generated files.
+
+Automation/non-interactive path:
+
+1. Run `bunx kitcn init --yes` when you want scaffold or adoption plus the one-shot local Convex bootstrap in one command.
+2. Run `bunx kitcn verify` when you want a non-interactive local runtime proof in the current app. It reuses an existing local deployment when one is already configured, and only falls back to anonymous fresh-local setup when it has to.
+3. Confirm the generated runtime exists in `convex/functions/generated/server.ts`.
+4. Then run `bunx kitcn dev` for ongoing codegen/API refresh.
+
+Local deployment storage: New local and anonymous deployments store state under `.convex/` in the project root.
+
+This generates:
+
+- `convex/functions/_generated/*`
+- `convex/functions/generated/` directory
+- `convex/shared/api.ts`
+
+Agent command policy:
+
+1. Default to `bunx kitcn dev`.
+2. `kitcn dev` already runs codegen/API generation.
+3. Do not run `bunx kitcn codegen` as a separate default step.
+4. Use `bunx kitcn verify` for one-shot local runtime proof in CI or agent runs.
+5. Use manual `bunx kitcn codegen` only as fallback when `kitcn dev` cannot be run and backend is already active.
+6. Use `bunx kitcn insights` for cloud-deployment debugging; it forwards to the upstream Convex insights CLI.
+
+One-time codegen (optional; use only when `kitcn dev` is not running):
+
+```bash
+bunx kitcn codegen
+```
+
+Codegen runtime rule:
+
+1. `kitcn codegen` still requires a configured Convex deployment.
+2. If you need a runtime proof without a long-running dev session, use `bunx kitcn verify`.
+3. If you see `Local backend isn't running`, use `bunx kitcn verify` instead of hand-holding a second terminal.
+
+### 5.6 Import rules (hard requirement)
+
+Never use lazy imports (`await import(...)`) in Convex code.
+
+Rules:
+
+1. Convex files (`convex/functions/**`, `convex/lib/**`, `convex/routers/**`) must use static imports only.
+2. If generated modules are missing (`_generated/*`, `@convex/api`), stop and run `bunx kitcn dev` first.
+3. Do not work around missing generated files with dynamic imports.
+
+## 9. Optional Modules Setup (Feature Gates)
+
+Enable only selected modules.
+
+### 9.0 Component composition rule (`convex/functions/convex.config.ts`)
+
+When components are enabled, register them in one `defineApp()` file:
+
+```ts
+import { defineApp } from "convex/server";
+import myComponent from "some-component/convex.config";
+
+const app = defineApp();
+
+app.use(myComponent);
+
+export default app;
+```
+
+### 9.1 RLS gate
+
+Use `rlsPolicy` on ORM tables, evaluate through ORM context:
+
+```ts
+import { convexTable, id, rlsPolicy, text, eq } from "kitcn/orm";
+
+export const secret = convexTable.withRLS(
+  "secret",
+  {
+    ownerId: id("user").notNull(),
+    value: text().notNull(),
+  },
+  (t) => [
+    rlsPolicy("read_own", {
+      for: "select",
+      using: (ctx) => eq(t.ownerId, ctx.viewerId),
+    }),
+  ]
+);
+```
+
+### 9.2 Schema triggers gate
+
+```ts
+import { convexTable, defineTriggers, text } from "kitcn/orm";
+
+const triggers = defineTriggers(relations, {
+  post: {
+    change: async (change, ctx) => {
+      if (change.operation === "delete") return;
+      // side effects here
+    },
+  },
+});
+```
+
+Trigger guardrails:
+
+1. Keep trigger work bounded and idempotent.
+2. Avoid trigger chains that re-query/rewrite the same hot table rows during seed/init flows.
+3. If `internal.seed.seed` or `internal.init.default` hangs, move counter/invariant sync into explicit mutation helpers and seed reconciliation.
+
+### 9.3 Aggregates gate
+
+Declare `aggregateIndex` and/or `rankIndex` in table definitions. Backfill runs automatically via `kitcn dev`.
+
+```ts
+// convex/functions/schema.ts
+const postLikes = convexTable(
+  "postLikes",
+  { postId: text().notNull(), userId: text().notNull() },
+  (t) => [aggregateIndex("by_post").on(t.postId)]
+);
+
+const scores = convexTable(
+  "scores",
+  { gameId: text().notNull(), score: integer().notNull() },
+  (t) => [
+    rankIndex("leaderboard")
+      .partitionBy(t.gameId)
+      .orderBy({ column: t.score, direction: "desc" }),
+  ]
+);
+```
+
+No trigger wiring needed — `aggregateIndex` and `rankIndex` are maintained automatically by the ORM.
+
+If Aggregates are **disabled**, remove `aggregateIndex`/`rankIndex` declarations from table definitions and re-run `bunx kitcn verify`.
+
+### 9.4 Rate limiting gate
+
+Use the built-in package module (no component registration):
+
+```bash
+bun add kitcn
+```
+
+`aggregateExtension` and `migrationExtension` are builtin in `defineSchema`.
+Rate limiting is opt-in: scaffold the full starter once.
+
+```bash
+bunx kitcn add ratelimit
+```
+
+This creates `convex/lib/plugins/ratelimit/schema.ts`, `convex/lib/plugins/ratelimit/plugin.ts`, and registers `ratelimitExtension()` in `convex/functions/schema.ts`.
+
+```ts
+import { defineSchema } from "kitcn/orm";
+import { ratelimitExtension } from "../lib/plugins/ratelimit/schema";
+
+export default defineSchema(tables).extend(ratelimitExtension());
+```
+
+Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes and reserve `.meta({ ratelimit: ... })` for named overrides.
+
+Use `RatelimitPlugin` from `kitcn/ratelimit`:
+
+```ts
+import { getSessionNetworkSignals } from "kitcn/auth";
+import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
+import type { MutationCtx } from "../../../functions/generated/server";
+import type { Select } from "../../../shared/api";
+
+const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
+
+export const ratelimitBuckets = {
+  default: {
+    public: fixed(30),
+    free: fixed(60),
+    premium: fixed(200),
+  },
+} as const;
+
+type RatelimitTier = keyof (typeof ratelimitBuckets)["default"];
+export type RatelimitBucket = keyof typeof ratelimitBuckets;
+
+type RatelimitUser = {
+  id: string;
+  isAdmin?: boolean;
+  plan?: "premium" | "team" | null;
+  session?: Select<"session"> | null;
+};
+
+type RatelimitCtx = MutationCtx & {
+  user?: RatelimitUser | null;
+};
+
+type RatelimitMeta = {
+  ratelimit?: RatelimitBucket;
+};
+
+export function getUserTier(user: RatelimitUser | null): RatelimitTier {
+  if (!user) return "public";
+  if (user.isAdmin || user.plan) return "premium";
+  return "free";
+}
+
+export const ratelimit = RatelimitPlugin.configure({
+  buckets: ratelimitBuckets,
+  getBucket: ({ meta }: { meta: RatelimitMeta }) => meta.ratelimit ?? "default",
+  getUser: ({ ctx }: { ctx: RatelimitCtx }) => ctx.user ?? null,
+  getIdentifier: ({ user }: { user: RatelimitUser | null }) =>
+    user?.id ?? "anonymous",
+  getTier: getUserTier,
+  getSignals: ({
+    ctx,
+    user,
+  }: {
+    ctx: RatelimitCtx;
+    user: RatelimitUser | null;
+  }) => getSessionNetworkSignals(ctx, user?.session ?? null),
+  prefix: ({ bucket, tier }) => `ratelimit:${bucket}:${tier}`,
+  failureMode: "closed",
+  enableProtection: true,
+  denyListThreshold: 30,
+});
+```
+
+### 9.5 Scheduling gate
+
+Create `convex/functions/crons.ts` with `cronJobs()` and use `caller.schedule.now/after/at` in mutations/actions for delayed procedure jobs (`ctx.scheduler.*` only for raw `internal.*` functions).
+
+### 9.6 HTTP router gate
+
+If REST endpoints are needed, add cRPC route builders and register routers in `convex/functions/http.ts`; consume via `crpc.http.*` client proxies.
+
+### 9.7 Email + Resend gate
+
+Install packages:
+
+```bash
+bun add @kitcn/resend
+```
+
+`kitcn add resend` scaffolds `convex/lib/plugins/resend/schema.ts` and registers `resendExtension()` in `convex/functions/schema.ts`.
+
+If `paths.env` is missing, the add flow also bootstraps `convex/lib/get-env.ts`, writes `paths.env` into `kitcn.json`, and adds resend env fields there. The schema keeps `RESEND_API_KEY` optional for local dev flow, and the add command reminds you to set it in `convex/.env` before sending email. Webhook secret and default sender stay optional.
+
+```ts
+import { resendExtension } from "../lib/plugins/resend/schema";
+
+export default defineSchema(tables).extend(resendExtension());
+```
+
+Scaffold resend runtime + helpers:
+
+```bash
+bunx kitcn add resend
+```
+
+Recommended files for this gate:
+
+- `convex/functions/plugins/resend.ts`
+- `convex/functions/plugins/email.tsx`
+- `convex/lib/plugins/resend/plugin.ts`
+- `convex/lib/plugins/resend/webhook.ts`
+- `convex/lib/plugins/resend/crons.ts`
+
+If `plugins/email.tsx` is selected, install React Email deps:
+
+```bash
+bun add @react-email/components @react-email/render react-email react react-dom
+```

package/skills/convex/references/setup/start.md

@@ -0,0 +1,67 @@
+## 8.B TanStack Start
+
+Explicit exception: current docs still use `@convex-dev/better-auth/*` helpers for TanStack Start integration.
+
+### 8.B.1 Auth client + auth server helpers
+
+**Create:** `src/lib/convex/auth/auth-client.ts`
+
+```ts
+import type { Auth } from "@convex/auth-shared";
+import { convexClient } from "@convex-dev/better-auth/client/plugins";
+import { adminClient, inferAdditionalFields } from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
+
+export const authClient = createAuthClient({
+  baseURL:
+    typeof window === "undefined"
+      ? (import.meta.env.VITE_SITE_URL as string | undefined)
+      : window.location.origin,
+  sessionOptions: { refetchOnWindowFocus: false },
+  plugins: [inferAdditionalFields<Auth>(), adminClient(), convexClient()],
+});
+```
+
+**Create:** `src/lib/convex/auth/auth-server.ts`
+
+```ts
+import { convexBetterAuthReactStart } from "@convex-dev/better-auth/react-start";
+
+export const {
+  handler,
+  getToken,
+  fetchAuthQuery,
+  fetchAuthMutation,
+  fetchAuthAction,
+} = convexBetterAuthReactStart({
+  convexUrl: process.env.VITE_CONVEX_URL!,
+  convexSiteUrl: process.env.VITE_CONVEX_SITE_URL!,
+});
+```
+
+### 8.B.2 Auth API endpoint
+
+**Create:** `src/routes/api/auth/$.ts`
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+import { handler } from "@/lib/convex/auth/auth-server";
+
+export const Route = createFileRoute("/api/auth/$")({
+  server: {
+    handlers: {
+      GET: ({ request }) => handler(request),
+      POST: ({ request }) => handler(request),
+    },
+  },
+});
+```
+
+### 8.B.3 Caller/context and providers
+
+Use docs pattern from `tanstack-start.mdx` for:
+
+- `createCallerFactory` + `runServerCall`
+- router context values (`convex`, `queryClient`, `convexQueryClient`)
+- provider wrapping with `ConvexAuthProvider` and `initialToken`
+

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-zbeyens
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

package/dist/index.d.mts

@@ -1,5 +0,0 @@
-//#region src/index.d.ts
-declare const hello: () => string;
-//#endregion
-export { hello };
-//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";cAAa"}

package/dist/index.mjs

@@ -1,6 +0,0 @@
-//#region src/index.ts
-const hello = () => "hello";
-
-//#endregion
-export { hello };
-//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export const hello = () => 'hello';\n"],"mappings":";AAAA,MAAa,cAAc"}