create-m5kdev 0.21.3 → 0.21.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m5kdev",
-  "version": "0.21.3",
+  "version": "0.21.5",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

package/templates/minimal-app/.cursor/rules/module-module-guide.mdc

@@ -18,7 +18,7 @@ apps/<app>/server/src/modules/<module>/<module>.module.ts
 - Extend `BaseModule<Deps, Tables, Repositories, Services, Routers>` from `@m5kdev/backend/modules/base/base.module`.
 - Declare local type aliases for each generic slot (`*ModuleDeps`, `*ModuleTables`, `*ModuleRepositories`, `*ModuleServices`, `*ModuleRouters`).
 - Set `readonly id` to match the module directory name (e.g. `readonly id = "posts"`).
-- Declare `dependsOn` as a `readonly` tuple with `as const`. App modules typically depend on framework modules like `AuthModule`.
+- Declare `dbDependsOn` or `dependsOn` as a `readonly` tuple with `as const`. App modules that reference auth tables typically use `dbDependsOn: ["auth"]`.
 - Override only the hooks the module actually needs; omit the rest.
 - Keep hook bodies as pure wiring — no business logic.
 - Use `createBackendRouterMap(namespace, router)` from `@m5kdev/backend/app` in the `trpc()` hook.
@@ -117,35 +117,33 @@ export const postsModule = new PostsModule();
 
 ## Registration
 
-Register the module in `apps/<app>/server/src/modules.ts`:
+Register the module in `apps/<app>/server/src/app.ts`:
 
 ```typescript
-import { defineBackendModules } from "@m5kdev/backend/app";
+import { createBackendApp } from "@m5kdev/backend/app";
 import { PostsModule } from "./modules/posts/posts.module";
 
-export const postsBackendModule = new PostsModule();
-
-export const backendModules = defineBackendModules([
-  emailBackendModule,
-  authBackendModule,
-  workflowBackendModule,
-  notificationBackendModule,
-  postsBackendModule,
-] as const);
+export const builtBackendApp = createBackendApp(
+  {
+    // db, express, schema, app, email, auth, ...
+  },
+  [
+    new EmailModule(templates),
+    new AuthModule(),
+    new WorkflowModule({ /* ... */ }),
+    new NotificationModule(),
+    new PostsModule(),
+  ] as const
+);
 ```
 
-Then chain `.use(postsBackendModule)` in `apps/<app>/server/src/app.ts`.
-
 ## Accessing Module Output
 
-After building, module repositories and services are re-exported from composition root files:
+After building, module repositories and services are available on `builtBackendApp.modules`:
 
 ```typescript
-// apps/<app>/server/src/repository.ts
-export const postsRepository = builtBackendApp.modules.posts.repositories.posts;
-
-// apps/<app>/server/src/service.ts
-export const postsService = builtBackendApp.modules.posts.services.posts;
+const postsService = builtBackendApp.modules.posts.services.posts;
+const postsRepository = builtBackendApp.modules.posts.repositories.posts;
 ```
 
 ## Patterns

package/templates/minimal-app/AGENTS.md.tpl

@@ -15,9 +15,9 @@
 
 ## Backend Conventions
 
-- Keep repository, service, and transport layers separate.
-- Instantiate repositories in `apps/server/src/repository.ts`.
-- Instantiate services in `apps/server/src/service.ts`.
+- Keep repository, service, and transport layers separate inside each module.
+- Register modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`.
+- Use `BaseModule` subclasses for app modules; the kernel wires repositories, services, and tRPC.
 - Keep tRPC files focused on input/output wiring and delegate logic to services.
 - Do not create Drizzle migrations by hand. Use the scaffolded config and your project migration workflow later if you need generated migrations.
 
@@ -25,5 +25,6 @@
 
 - Keep the app shell shape: `NuqsAdapter` + `BrowserRouter` + `Providers`.
 - Compose global providers only in `apps/webapp/src/Providers.tsx`.
+- Use `AppConfigProvider` and `AppTrpcQueryProvider` from `@m5kdev/frontend`; use `@m5kdev/web-ui` for web-only UI.
 - Use `nuqs` for URL state, React Router for routing, HeroUI for UI primitives, and Tailwind v4 for styling.
 - Prefer shared framework utilities from `@m5kdev/frontend` and `@m5kdev/web-ui` before adding local duplicates.

package/templates/minimal-app/apps/email/src/emails/accountDeletionEmail.tsx.tpl

@@ -16,10 +16,14 @@ export default function AccountDeletionEmail({
       ctaLabel="Review deletion"
       ctaUrl={url}
       body={
-        <Text style={{ margin: "0" }}>
-          We received a request to delete your {{APP_NAME}} account. If that was you, use the link
-          below to confirm the action.
-        </Text>
+        <>
+          <Text style={{ margin: "0" }}>
+            We received a request to delete your {{APP_NAME}} account.
+          </Text>
+          <Text style={{ margin: "0" }}>
+            If that was you, use the link below to confirm the action.
+          </Text>
+        </>
       }
     />
   );

package/templates/minimal-app/apps/server/AGENTS.md.tpl

@@ -19,7 +19,8 @@ apps/server/src/modules/<module>/
 ├── <module>.db.ts
 ├── <module>.repository.ts
 ├── <module>.service.ts
-└── <module>.trpc.ts
+├── <module>.trpc.ts
+└── <module>.module.ts
 ```
 
 ## Layer Boundaries
@@ -27,12 +28,12 @@ apps/server/src/modules/<module>/
 - Repositories own persistence and query construction.
 - Services own business rules, orchestration, and context-aware defaults.
 - tRPC files own transport only and must delegate to services.
-- Keep composition explicit in `db.ts`, `repository.ts`, `service.ts`, and `trpc.ts`.
+- Register modules in `apps/server/src/app.ts`; use `db.ts` and `lib/auth.ts` only for scripts that need direct DB or auth access.
 
 ## Workflow, Redis, and push notifications
 
-- `workflow.ts` wires BullMQ via **Redis** (`REDIS_URL`). Start Redis locally before `pnpm dev` on the server, or jobs will not run.
-- `index.ts` calls `workflowRegistry.registerService(notificationService)` and `await workflowRegistry.start()` before listening.
-- After changing Drizzle tables (including `notification_*` tables merged in `db.ts`), run your project’s **Drizzle generate / migrate** command — do not hand-edit SQL migrations in this repo.
+- `WorkflowModule` and `NotificationModule` are registered in `app.ts`. Start **Redis** locally (`REDIS_URL`) before `pnpm dev` on the server, or background jobs will not run.
+- `index.ts` calls `builtBackendApp.start()` before listening and `builtBackendApp.shutdown()` on exit.
+- After changing Drizzle tables, run `pnpm --filter ./apps/server sync` — do not hand-edit SQL migrations in this repo.
 
 Push-related server env vars are documented in `apps/shared/.env.example`.

package/templates/minimal-app/apps/server/drizzle/generate-schema.ts.tpl

@@ -1,9 +1,5 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import * as authTables from "@m5kdev/backend/modules/auth/auth.db";
-import * as notificationTables from "@m5kdev/backend/modules/notification/notification.db";
-import * as workflowTables from "@m5kdev/backend/modules/workflow/workflow.db";
-import * as postsTables from "../src/modules/posts/posts.db";
 
 export async function generateSchema(): Promise<void> {
   const outputDirectory = path.resolve(process.cwd(), "src/generated");
@@ -24,7 +20,7 @@ export async function generateSchema(): Promise<void> {
     "",
     "export type AppDbSchema = typeof schema;",
     "",
-  ].join("\n");
+  ].join("\r\n");
 
   await fs.mkdir(outputDirectory, { recursive: true });
   await fs.writeFile(outputPath, source, "utf8");

package/templates/minimal-app/apps/server/drizzle/seed.ts.tpl

@@ -1,10 +1,13 @@
+import { hashPassword } from "better-auth/crypto";
 import { eq } from "drizzle-orm";
+import { v4 as uuidv4 } from "uuid";
 import { orm, schema } from "../src/db";
-import { auth } from "../src/lib/auth";
 import { syncDatabase } from "./sync";
 
 const DEMO_EMAIL = "admin@{{APP_SLUG}}.local";
 const DEMO_PASSWORD = "password1234";
+const ORGANIZATION_ID = "{{APP_SLUG}}-org";
+const TEAM_ID = "{{APP_SLUG}}-team";
 
 async function ensureDemoUser() {
   const [existingUser] = await orm
@@ -17,26 +20,103 @@ async function ensureDemoUser() {
     return existingUser;
   }
 
-  await auth.api.createUser({
-    body: {
+  const userId = uuidv4();
+  const [user] = await orm
+    .insert(schema.users)
+    .values({
+      id: userId,
       name: "Demo Editor",
       email: DEMO_EMAIL,
-      password: DEMO_PASSWORD,
+      emailVerified: true,
       role: "admin",
-    },
-  } as never);
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .returning();
+
+  if (!user) {
+    throw new Error("Failed to create demo user.");
+  }
+
+  await orm.insert(schema.accounts).values({
+    id: uuidv4(),
+    accountId: user.id,
+    providerId: "credential",
+    userId: user.id,
+    password: await hashPassword(DEMO_PASSWORD),
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  });
 
-  const [createdUser] = await orm
+  return user;
+}
+
+async function ensureOrganization(userId: string) {
+  const [existingOrganization] = await orm
     .select()
-    .from(schema.users)
-    .where(eq(schema.users.email, DEMO_EMAIL))
+    .from(schema.organizations)
+    .where(eq(schema.organizations.id, ORGANIZATION_ID))
     .limit(1);
 
-  if (!createdUser) {
-    throw new Error("Failed to create demo user.");
+  if (!existingOrganization) {
+    await orm.insert(schema.organizations).values({
+      id: ORGANIZATION_ID,
+      name: "{{APP_NAME}}",
+      slug: "{{APP_SLUG}}",
+      type: "enterprise",
+      createdAt: new Date(),
+    });
   }
 
-  return createdUser;
+  const [existingMember] = await orm
+    .select()
+    .from(schema.members)
+    .where(eq(schema.members.userId, userId))
+    .limit(1);
+
+  if (!existingMember) {
+    await orm.insert(schema.members).values({
+      id: uuidv4(),
+      organizationId: ORGANIZATION_ID,
+      userId,
+      role: "owner",
+      createdAt: new Date(),
+    });
+  }
+
+  const [existingTeam] = await orm
+    .select()
+    .from(schema.teams)
+    .where(eq(schema.teams.id, TEAM_ID))
+    .limit(1);
+
+  if (!existingTeam) {
+    await orm.insert(schema.teams).values({
+      id: TEAM_ID,
+      name: "Editorial",
+      organizationId: ORGANIZATION_ID,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+  }
+
+  const [existingTeamMember] = await orm
+    .select()
+    .from(schema.teamMembers)
+    .where(eq(schema.teamMembers.userId, userId))
+    .limit(1);
+
+  if (!existingTeamMember) {
+    await orm.insert(schema.teamMembers).values({
+      id: uuidv4(),
+      teamId: TEAM_ID,
+      userId,
+      role: "owner",
+      createdAt: new Date(),
+    });
+  }
+
+  return { organizationId: ORGANIZATION_ID, teamId: TEAM_ID };
 }
 
 async function seedPosts(userId: string, organizationId: string | null, teamId: string | null) {
@@ -64,7 +144,7 @@ async function seedPosts(userId: string, organizationId: string | null, teamId:
       organizationId,
       teamId,
       title: "Three habits that keep CRUD apps from drifting into chaos",
-      slug: "three-habits-that-keep-crud-apps-focused",
+      slug: "three-habits-that-keep-crud{{PACKAGE_SCOPE}}s-focused",
       excerpt: "A draft about explicit composition, typed contracts, and URL state.",
       content:
         "Keep your composition explicit, keep your schemas honest, and keep the URL involved in user intent. Those three choices do most of the architectural work in a small product.",
@@ -90,22 +170,11 @@ async function seedPosts(userId: string, organizationId: string | null, teamId:
 async function seed() {
   await syncDatabase();
   const user = await ensureDemoUser();
+  const { organizationId, teamId } = await ensureOrganization(user.id);
 
-  const [member] = await orm
-    .select()
-    .from(schema.members)
-    .where(eq(schema.members.userId, user.id))
-    .limit(1);
-
-  const [teamMember] = await orm
-    .select()
-    .from(schema.teamMembers)
-    .where(eq(schema.teamMembers.userId, user.id))
-    .limit(1);
-
-  await seedPosts(user.id, member?.organizationId ?? null, teamMember?.teamId ?? null);
+  await seedPosts(user.id, organizationId, teamId);
 
   console.info(`Seed completed. Demo login: ${DEMO_EMAIL} / ${DEMO_PASSWORD}`);
 }
 
-seed();
+void seed();

package/templates/minimal-app/apps/server/src/app.ts.tpl

@@ -1,35 +1,25 @@
-import { createBackendApp, type InferBackendAppRouter } from "@m5kdev/backend/app";
+import { createBackendApp } from "@m5kdev/backend/app";
 import { createBetterAuth } from "@m5kdev/backend/modules/auth/auth.lib";
-import type { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
+import { AuthModule } from "@m5kdev/backend/modules/auth/auth.module";
+import { EmailModule } from "@m5kdev/backend/modules/email/email.module";
+import { NotificationModule } from "@m5kdev/backend/modules/notification/notification.module";
+import { WorkflowModule } from "@m5kdev/backend/modules/workflow/workflow.module";
+import { templates } from "{{PACKAGE_SCOPE}}/email";
+import { APP_NAME } from "{{PACKAGE_SCOPE}}/shared/modules/app/app.constants";
 import cors from "cors";
 import express from "express";
-import {
-  authBackendModule,
-  emailBackendModule,
-  notificationBackendModule,
-  postsBackendModule,
-  workflowBackendModule,
-} from "./modules";
+import { schema } from "./generated/schema";
+import { PostsModule } from "./modules/posts/posts.module";
 
 const app = express();
 const appUrl = process.env.VITE_APP_URL ?? "http://localhost:5173";
 const serverUrl = process.env.VITE_SERVER_URL ?? "http://localhost:8080";
-
-app.use(express.json());
-app.use(
-  cors({
-    origin: [appUrl],
-    credentials: true,
-    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-    allowedHeaders: ["Content-Type", "Authorization"],
-  })
-);
-
 const databaseUrl = process.env.DATABASE_URL ?? "file:./local.db";
 const syncUrl = process.env.TURSO_DATABASE_URL;
 const authToken = process.env.TURSO_AUTH_TOKEN;
 const redisUrl = process.env.REDIS_URL ?? "redis://127.0.0.1:6379";
 const resendApiKey = process.env.RESEND_API_KEY;
+const enableWaitlist = process.env.VITE_ENABLE_WAITLIST === "true";
 
 const connection =
   syncUrl && authToken
@@ -44,52 +34,82 @@ const connection =
         url: databaseUrl,
       };
 
-export const backendApp = createBackendApp({
-  db: connection,
-  express: app,
-  app: {
-    name: "{{APP_NAME}}",
-    urls: {
-      web: appUrl,
-      api: serverUrl,
+app.use(express.json());
+app.use(
+  cors({
+    origin: [appUrl],
+    credentials: true,
+    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowedHeaders: [
+      "Content-Type",
+      "Authorization",
+      "Waitlist-Invitation-Code",
+      "Organization-Invitation-Code",
+      "Admin-Create-Verified-User",
+    ],
+  })
+);
+
+export const builtBackendApp = createBackendApp(
+  {
+    db: connection,
+    express: app,
+    schema: schema as never,
+    app: {
+      name: APP_NAME,
+      urls: {
+        web: appUrl,
+        api: serverUrl,
+      },
     },
-  },
-  redis: {
-    url: redisUrl,
-    options: { maxRetriesPerRequest: null },
-  },
-  resend: resendApiKey ? { apiKey: resendApiKey } : undefined,
-  email: {
-    mode: resendApiKey ? "send" : "store",
-    from: "no-reply@local.m5kdev.test",
-    systemNotificationEmail: "ops@local.m5kdev.test",
-    outputDirectory: ".emails",
-  },
-  auth: {
-    factory({ db, services, appConfig }) {
-      return createBetterAuth({
-        orm: db.orm as never,
-        schema: db.schema as never,
-        services: {
-          email: services.email.email,
-        },
-        app: appConfig,
-        config: {
-          waitlist: false,
-        },
-      });
+    redis: {
+      url: redisUrl,
+      options: { maxRetriesPerRequest: null },
+    },
+    resend: resendApiKey ? { apiKey: resendApiKey } : undefined,
+    email: {
+      mode: resendApiKey ? "send" : "store",
+      from: "no-reply@local.m5kdev.test",
+      systemNotificationEmail: "ops@local.m5kdev.test",
+      outputDirectory: ".emails",
+    },
+    auth: {
+      factory({ db, services, appConfig }) {
+        return createBetterAuth({
+          orm: db.orm as never,
+          schema: db.schema as never,
+          services: {
+            email: services.email.email,
+          },
+          app: appConfig,
+          config: {
+            waitlist: enableWaitlist,
+            provisionedAccountEmailDomain: "provisioned.{{APP_SLUG}}.local",
+          },
+          options: {
+            secret: process.env.BETTER_AUTH_SECRET ?? "QJvCmK9UBuHAWbNr2vV3ROVt8XrBYV5d",
+          },
+        });
+      },
     },
   },
-})
-  .use(emailBackendModule)
-  .use(authBackendModule)
-  .use(workflowBackendModule)
-  .use(notificationBackendModule)
-  .use(postsBackendModule);
+  [
+    new EmailModule(templates as never),
+    new AuthModule(),
+    new WorkflowModule({
+      queues: {
+        fast: { concurrency: 5 },
+      },
+      defaultQueue: "fast",
+      defaults: {
+        timeout: 60_000,
+        jobOptions: { removeOnComplete: { age: 3600 } },
+      },
+    }),
+    new NotificationModule(),
+    new PostsModule(),
+  ] as const
+);
 
-export const builtBackendApp = backendApp.build();
 export const appRouter = builtBackendApp.trpc.router;
-
-export type AppRouter = InferBackendAppRouter<typeof backendApp>;
-export type RouterInputs = inferRouterInputs<AppRouter>;
-export type RouterOutputs = inferRouterOutputs<AppRouter>;
+export type AppRouter = typeof appRouter;

package/templates/minimal-app/apps/server/src/generated/schema.ts.tpl

@@ -0,0 +1,13 @@
+import * as authTables from "@m5kdev/backend/modules/auth/auth.db";
+import * as notificationTables from "@m5kdev/backend/modules/notification/notification.db";
+import * as workflowTables from "@m5kdev/backend/modules/workflow/workflow.db";
+import * as postsTables from "../modules/posts/posts.db";
+
+export const schema = {
+  ...authTables,
+  ...workflowTables,
+  ...notificationTables,
+  ...postsTables,
+};
+
+export type AppDbSchema = typeof schema;

package/templates/minimal-app/apps/server/src/index.ts.tpl

@@ -1,5 +1,6 @@
 import type { Server } from "node:http";
 import { builtBackendApp } from "./app";
+
 const port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 8080;
 
 let httpServer: Server | undefined;
@@ -38,7 +39,9 @@ async function start(): Promise<void> {
   await builtBackendApp.start();
   await new Promise<void>((resolve, reject) => {
     httpServer = builtBackendApp.express.app.listen(port, () => {
-      console.info(`Server running at ${process.env.VITE_SERVER_URL ?? `http://localhost:${port}`}`);
+      console.info(
+        `Server running at ${process.env.VITE_SERVER_URL ?? `http://localhost:${port}`}`
+      );
       resolve();
     });
     httpServer.on("error", reject);

package/templates/minimal-app/apps/server/src/lib/auth.ts.tpl

@@ -1,6 +1,12 @@
 import { builtBackendApp } from "../app";
 
-export const auth = builtBackendApp.auth!.instance;
+const authInstance = builtBackendApp.auth?.instance;
+
+if (!authInstance) {
+  throw new Error("Auth is not configured on the backend app.");
+}
+
+export const auth = authInstance;
 
 export type Session = typeof auth.$Infer.Session;
 export type User = Session["user"];

package/templates/minimal-app/apps/server/src/modules/posts/posts.db.ts.tpl

@@ -1,5 +1,5 @@
-import { type AnySQLiteColumn, integer, sqliteTable as table, text } from "drizzle-orm/sqlite-core";
 import { organizations, teams, users } from "@m5kdev/backend/modules/auth/auth.db";
+import { integer, sqliteTable as table, text } from "drizzle-orm/sqlite-core";
 import { v4 as uuidv4 } from "uuid";
 
 export const posts = table("posts", {

package/templates/minimal-app/apps/server/src/modules/posts/posts.grants.ts.tpl

@@ -1,40 +1,40 @@
-import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
-
-export const postsGrants: ResourceGrant[] = [
-  {
-    action: "write",
-    level: "team",
-    role: "owner",
-    access: "own",
-  },
-  {
-    action: "publish",
-    level: "team",
-    role: "owner",
-    access: "own",
-  },
-  {
-    action: "delete",
-    level: "team",
-    role: "owner",
-    access: "own",
-  },
-  {
-    action: "write",
-    level: "organization",
-    role: "owner",
-    access: "own",
-  },
-  {
-    action: "publish",
-    level: "organization",
-    role: "owner",
-    access: "own",
-  },
-  {
-    action: "delete",
-    level: "organization",
-    role: "owner",
-    access: "own",
-  },
-];
+import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
+
+export const postsGrants: ResourceGrant[] = [
+  {
+    action: "write",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "publish",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "delete",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "write",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "publish",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "delete",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+];