create-m5kdev 0.4.0

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

@@ -0,0 +1,25 @@
+import { Text } from "@react-email/components";
+import { BaseEmail } from "../components/BaseEmail";
+
+export default function PasswordResetEmail({
+  previewText = "Reset your password",
+  url,
+}: {
+  previewText?: string;
+  url: string;
+}) {
+  return (
+    <BaseEmail
+      previewText={previewText}
+      eyebrow="Access"
+      title="Reset your password"
+      ctaLabel="Choose a new password"
+      ctaUrl={url}
+      body={
+        <Text style={{ margin: "0" }}>
+          Use the secure link below to choose a new password for your {{APP_NAME}} account.
+        </Text>
+      }
+    />
+  );
+}

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

@@ -0,0 +1,26 @@
+import { Text } from "@react-email/components";
+import { BaseEmail } from "../components/BaseEmail";
+
+export default function VerificationEmail({
+  previewText = "Verify your email",
+  url,
+}: {
+  previewText?: string;
+  url: string;
+}) {
+  return (
+    <BaseEmail
+      previewText={previewText}
+      eyebrow="Welcome"
+      title="Verify your email"
+      ctaLabel="Verify account"
+      ctaUrl={url}
+      body={
+        <Text style={{ margin: "0" }}>
+          Confirm your email address to finish setting up {{APP_NAME}} and access your editorial
+          workspace.
+        </Text>
+      }
+    />
+  );
+}

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

@@ -0,0 +1,32 @@
+import type { FunctionComponent } from "react";
+import AccountDeletionEmail from "./emails/accountDeletionEmail";
+import OrganizationInviteEmail from "./emails/organizationInviteEmail";
+import PasswordResetEmail from "./emails/passwordResetEmail";
+import VerificationEmail from "./emails/verificationEmail";
+
+export const templates = {
+  accountDeletion: {
+    id: "account-deletion",
+    subject: "Delete your account",
+    previewText: "Confirm your account deletion",
+    react: AccountDeletionEmail as FunctionComponent<Record<string, unknown>>,
+  },
+  passwordReset: {
+    id: "password-reset",
+    subject: "Reset your password",
+    previewText: "Reset your password request",
+    react: PasswordResetEmail as FunctionComponent<Record<string, unknown>>,
+  },
+  verification: {
+    id: "verification",
+    subject: "Verify your email",
+    previewText: "Verify your email address",
+    react: VerificationEmail as FunctionComponent<Record<string, unknown>>,
+  },
+  organizationInvite: {
+    id: "organization-invite",
+    subject: "Join the organization",
+    previewText: "You have been invited to join an organization",
+    react: OrganizationInviteEmail as FunctionComponent<Record<string, unknown>>,
+  },
+};

package/templates/minimal-app/apps/email/tsconfig.json.tpl

@@ -0,0 +1,11 @@
+{
+  "extends": "@m5kdev/config/tsconfig.node.json",
+  "rootDir": ".",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "exclude": ["node_modules"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}

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

@@ -0,0 +1,30 @@
+# Server Module Structure Guide
+
+Use this for modules in `apps/server/src/modules/**`.
+
+## Preferred Module Layout
+
+Shared contracts:
+
+```
+apps/shared/src/modules/<module>/
+├── <module>.constants.ts
+└── <module>.schema.ts
+```
+
+Server module:
+
+```
+apps/server/src/modules/<module>/
+├── <module>.db.ts
+├── <module>.repository.ts
+├── <module>.service.ts
+└── <module>.trpc.ts
+```
+
+## Layer Boundaries
+
+- 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`.

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

@@ -0,0 +1,111 @@
+import { eq } from "drizzle-orm";
+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";
+
+async function ensureDemoUser() {
+  const [existingUser] = await orm
+    .select()
+    .from(schema.users)
+    .where(eq(schema.users.email, DEMO_EMAIL))
+    .limit(1);
+
+  if (existingUser) {
+    return existingUser;
+  }
+
+  await auth.api.createUser({
+    body: {
+      name: "Demo Editor",
+      email: DEMO_EMAIL,
+      password: DEMO_PASSWORD,
+      role: "admin",
+    },
+  } as never);
+
+  const [createdUser] = await orm
+    .select()
+    .from(schema.users)
+    .where(eq(schema.users.email, DEMO_EMAIL))
+    .limit(1);
+
+  if (!createdUser) {
+    throw new Error("Failed to create demo user.");
+  }
+
+  return createdUser;
+}
+
+async function seedPosts(userId: string, organizationId: string | null, teamId: string | null) {
+  const existingPosts = await orm.select().from(schema.posts).limit(1);
+  if (existingPosts.length > 0) {
+    return;
+  }
+
+  await orm.insert(schema.posts).values([
+    {
+      authorUserId: userId,
+      organizationId,
+      teamId,
+      title: "An editorial workflow you can ship in an afternoon",
+      slug: "editorial-workflow-in-an-afternoon",
+      excerpt: "A first draft on how this minimal starter is wired together.",
+      content:
+        "This starter keeps the moving parts visible. Shared contracts live in the shared app, business rules stay in services, and the web layer only does composition and UI work.",
+      status: "published",
+      publishedAt: new Date(),
+      createdAt: new Date(Date.now() - 1000 * 60 * 60 * 24 * 5),
+    },
+    {
+      authorUserId: userId,
+      organizationId,
+      teamId,
+      title: "Three habits that keep CRUD apps from drifting into chaos",
+      slug: "three-habits-that-keep-crud-apps-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.",
+      status: "draft",
+      createdAt: new Date(Date.now() - 1000 * 60 * 60 * 24 * 2),
+    },
+    {
+      authorUserId: userId,
+      organizationId,
+      teamId,
+      title: "What a minimal platform starter should still refuse to compromise on",
+      slug: "minimal-platform-starter-non-negotiables",
+      excerpt: "A published note on keeping the foundation opinionated without being heavy.",
+      content:
+        "Even a minimal starter should include auth, structured modules, and a coherent app shell. Cutting those corners only moves the complexity into the first week of work.",
+      status: "published",
+      publishedAt: new Date(Date.now() - 1000 * 60 * 60 * 16),
+      createdAt: new Date(Date.now() - 1000 * 60 * 60 * 18),
+    },
+  ]);
+}
+
+async function seed() {
+  await syncDatabase();
+  const user = await ensureDemoUser();
+
+  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);
+
+  console.info(`Seed completed. Demo login: ${DEMO_EMAIL} / ${DEMO_PASSWORD}`);
+}
+
+seed();

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

@@ -0,0 +1,18 @@
+import { spawnSync } from "node:child_process";
+
+export async function syncDatabase(): Promise<void> {
+  const command = process.platform === "win32" ? "drizzle-kit.cmd" : "drizzle-kit";
+  const result = spawnSync(command, ["push", "--config", "drizzle.config.ts", "--force"], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`drizzle-kit push failed with exit code ${result.status ?? "unknown"}`);
+  }
+}
+
+syncDatabase().then(() => {
+  console.info("Sync completed");
+});

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

@@ -0,0 +1,38 @@
+import * as dotenv from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+dotenv.config({ path: "../shared/.env" });
+
+const url = process.env.TURSO_DATABASE_URL || process.env.DATABASE_URL;
+const authToken = process.env.TURSO_AUTH_TOKEN;
+const schema = [
+  "./src/modules/**/*.db.ts",
+  "./node_modules/@m5kdev/backend/dist/src/modules/auth/*.db.js",
+];
+
+if (!url) {
+  throw new Error("DATABASE_URL or TURSO_DATABASE_URL must be set");
+}
+
+const isRemote = Boolean(process.env.TURSO_DATABASE_URL && authToken);
+
+export default defineConfig(
+  isRemote
+    ? {
+        dialect: "turso",
+        schema,
+        out: "./drizzle",
+        dbCredentials: {
+          url,
+          authToken,
+        },
+      }
+    : {
+        dialect: "sqlite",
+        schema,
+        out: "./drizzle",
+        dbCredentials: {
+          url,
+        },
+      }
+);

package/templates/minimal-app/apps/server/package.json.tpl

@@ -0,0 +1,50 @@
+{
+  "name": "{{PACKAGE_SCOPE}}/server",
+  "version": "0.0.0",
+  "private": true,
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch --env-file=../shared/.env src/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit",
+    "sync": "tsx --env-file=../shared/.env drizzle/sync.ts",
+    "seed": "tsx --env-file=../shared/.env drizzle/seed.ts"
+  },
+  "dependencies": {
+    "{{PACKAGE_SCOPE}}/email": "workspace:*",
+    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
+    "@libsql/client": "catalog:",
+    "@m5kdev/backend": "catalog:",
+    "@m5kdev/commons": "catalog:",
+    "@trpc/server": "catalog:",
+    "better-auth": "catalog:",
+    "cors": "catalog:",
+    "dotenv": "catalog:",
+    "drizzle-orm": "catalog:",
+    "express": "catalog:",
+    "neverthrow": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "uuid": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@m5kdev/config": "catalog:",
+    "@types/cors": "catalog:",
+    "@types/express": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "drizzle-kit": "catalog:",
+    "tslib": "catalog:",
+    "tsup": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:"
+  },
+  "exports": {
+    "./types": "./src/types.ts"
+  }
+}

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

@@ -0,0 +1,33 @@
+import * as auth from "@m5kdev/backend/modules/auth/auth.db";
+import { drizzle } from "drizzle-orm/libsql";
+import * as posts from "./modules/posts/posts.db";
+
+export const schema = {
+  ...auth,
+  ...posts,
+};
+
+const databaseUrl = process.env.DATABASE_URL ?? "file:./local.db";
+const syncUrl = process.env.TURSO_DATABASE_URL;
+const authToken = process.env.TURSO_AUTH_TOKEN;
+
+const connection =
+  syncUrl && authToken
+    ? {
+        url: databaseUrl,
+        syncUrl,
+        authToken,
+        syncInterval: 60,
+        readYourWrites: true,
+      }
+    : {
+        url: databaseUrl,
+      };
+
+export const orm = drizzle({
+  connection,
+  schema,
+});
+
+export type Orm = typeof orm;
+export type Schema = typeof schema;

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

@@ -0,0 +1,34 @@
+import { createAuthContext } from "@m5kdev/backend/utils/trpc";
+import * as trpcExpress from "@trpc/server/adapters/express";
+import { toNodeHandler } from "better-auth/node";
+import cors from "cors";
+import express from "express";
+import { auth } from "./lib/auth";
+import { appRouter } from "./trpc";
+
+const app = express();
+const port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 8080;
+
+app.use(express.json());
+app.use(
+  cors({
+    origin: [process.env.VITE_APP_URL ?? "http://localhost:5173"],
+    credentials: true,
+    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+  })
+);
+
+app.use(
+  "/trpc",
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext: createAuthContext(auth as never),
+  })
+);
+
+app.all("/api/auth/*", toNodeHandler(auth));
+
+app.listen(port, () => {
+  console.info(`Server running at ${process.env.VITE_SERVER_URL ?? `http://localhost:${port}`}`);
+});

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

@@ -0,0 +1,172 @@
+import {
+  createOrganizationAndTeam,
+  getActiveOrganizationAndTeam,
+} from "@m5kdev/backend/modules/auth/auth.utils";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { admin, lastLoginMethod, organization } from "better-auth/plugins";
+import { orm, schema } from "../db";
+import { emailService } from "../service";
+
+export const auth = betterAuth({
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.VITE_SERVER_URL ?? "http://localhost:8080",
+  session: {
+    expiresIn: 60 * 60 * 24 * 7,
+    updateAge: 60 * 60 * 24,
+    cookieCache: {
+      enabled: true,
+      maxAge: 60 * 5,
+    },
+    additionalFields: {
+      activeOrganizationRole: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+      },
+      activeTeamRole: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+      },
+    },
+  },
+  user: {
+    additionalFields: {
+      onboarding: {
+        type: "number",
+        required: false,
+        defaultValue: null,
+      },
+      preferences: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+      },
+      flags: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+      },
+      stripeCustomerId: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+        input: false,
+      },
+      paymentCustomerId: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+        input: false,
+      },
+      paymentPlanTier: {
+        type: "string",
+        required: false,
+        defaultValue: null,
+        input: false,
+      },
+      paymentPlanExpiresAt: {
+        type: "number",
+        required: false,
+        defaultValue: null,
+        input: false,
+      },
+    },
+  },
+  database: drizzleAdapter(orm, {
+    provider: "sqlite",
+    schema,
+    usePlural: true,
+  }),
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: false,
+    sendResetPassword: async ({ user, url }) => {
+      await emailService.sendResetPassword(user.email, url);
+    },
+  },
+  emailVerification: {
+    sendVerificationEmail: async ({ user, url }) => {
+      await emailService.sendVerification(user.email, url);
+    },
+  },
+  plugins: [
+    admin(),
+    lastLoginMethod(),
+    organization({
+      allowUserToCreateOrganization: false,
+      teams: {
+        enabled: true,
+        allowRemovingAllTeams: false,
+      },
+      sendInvitationEmail: async (data) => {
+        const invitationUrl = `${process.env.VITE_APP_URL ?? "http://localhost:5173"}/organization/accept-invitation?id=${data.id}`;
+        await emailService.sendOrganizationInvite(
+          data.email,
+          data.organization.name,
+          data.inviter.user.name || data.inviter.user.email,
+          data.role,
+          invitationUrl
+        );
+      },
+      schema: {
+        team: {
+          modelName: "team",
+        },
+        teamMember: {
+          modelName: "teamMember",
+          additionalFields: {
+            role: {
+              type: "string",
+              required: true,
+            },
+          },
+        },
+        member: {
+          modelName: "member",
+        },
+        invitation: {
+          modelName: "invitation",
+        },
+        organization: {
+          modelName: "organization",
+        },
+      },
+    }),
+  ],
+  trustedOrigins: [
+    process.env.VITE_APP_URL ?? "http://localhost:5173",
+    process.env.VITE_SERVER_URL ?? "http://localhost:8080",
+  ],
+  databaseHooks: {
+    user: {
+      create: {
+        after: async (user) => {
+          await createOrganizationAndTeam(orm, schema, user);
+        },
+      },
+    },
+    session: {
+      create: {
+        before: async (session) => {
+          const { organizationId, teamId, organizationRole, teamRole } =
+            await getActiveOrganizationAndTeam(orm, schema, session.userId);
+
+          return {
+            data: {
+              ...session,
+              activeOrganizationId: organizationId,
+              activeTeamId: teamId,
+              activeOrganizationRole: organizationRole,
+              activeTeamRole: teamRole,
+            },
+          };
+        },
+      },
+    },
+  },
+});
+
+export type Session = typeof auth.$Infer.Session;
+export type User = Session["user"];

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

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { templates } from "{{PACKAGE_SCOPE}}/email";
+import { EmailService } from "@m5kdev/backend/modules/email/email.service";
+import { logger } from "@m5kdev/backend/utils/logger";
+import { ok } from "neverthrow";
+
+interface LocalEmailServiceProps {
+  appName: string;
+  appUrl: string;
+}
+
+export class LocalEmailService extends EmailService {
+  constructor(props: LocalEmailServiceProps) {
+    super({
+      resendApiKey: "local",
+      brand: {
+        name: props.appName,
+        logo: `${props.appUrl}/mark.svg`,
+        tagline: `${props.appName} publishing workspace`,
+      },
+      noReplyFrom: "no-reply@local.m5kdev.test",
+      systemNotificationEmail: "ops@local.m5kdev.test",
+      templates: templates as never,
+    });
+  }
+
+  override async sendTemplate(
+    to: Parameters<EmailService["sendTemplate"]>[0],
+    templateKey: Parameters<EmailService["sendTemplate"]>[1],
+    templateProps: Parameters<EmailService["sendTemplate"]>[2],
+    options?: Parameters<EmailService["sendTemplate"]>[3]
+  ) {
+    const template = this.templates[String(templateKey)];
+    if (!template) {
+      return this.error("NOT_FOUND", `Email template not found: ${String(templateKey)}`);
+    }
+
+    const outputDirectory = path.resolve(process.cwd(), ".emails");
+    await fs.mkdir(outputDirectory, { recursive: true });
+
+    const payload = {
+      to,
+      templateId: template.id,
+      subject: options?.subject ?? template.subject ?? String(templateKey),
+      previewText: options?.previewText ?? template.previewText ?? String(templateKey),
+      props: templateProps,
+      createdAt: new Date().toISOString(),
+    };
+
+    const filename = `${Date.now()}-${template.id}.json`;
+    const outputPath = path.join(outputDirectory, filename);
+    await fs.writeFile(outputPath, JSON.stringify(payload, null, 2), "utf8");
+
+    logger.info(`Local email written to ${outputPath}`);
+    return ok();
+  }
+}

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

@@ -0,0 +1,23 @@
+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", {
+  id: text("id").primaryKey().$default(uuidv4),
+  authorUserId: text("author_user_id").references(() => users.id, { onDelete: "set null" }),
+  organizationId: text("organization_id").references(() => organizations.id, {
+    onDelete: "set null",
+  }),
+  teamId: text("team_id").references(() => teams.id, { onDelete: "set null" }),
+  title: text("title").notNull(),
+  slug: text("slug").notNull().unique(),
+  excerpt: text("excerpt"),
+  content: text("content").notNull(),
+  status: text("status").$type<"draft" | "published">().notNull().default("draft"),
+  publishedAt: integer("published_at", { mode: "timestamp" }),
+  createdAt: integer("created_at", { mode: "timestamp" })
+    .notNull()
+    .$default(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }),
+  deletedAt: integer("deleted_at", { mode: "timestamp" }),
+});