create-m5kdev 0.33.0 → 0.35.0

package/templates/minimal-app/apps/expo/src/lib/trpc.ts.tpl

@@ -1,20 +1,20 @@
-import type { BackendTRPCRouter } from "@m5kdev/backend/types";
-import { transformer } from "@m5kdev/commons/utils/trpc";
-import { createTRPCClient, httpBatchLink } from "@trpc/client";
-import { serverUrl } from "../config";
-
-export const trpcClient = createTRPCClient<BackendTRPCRouter>({
-  links: [
-    httpBatchLink({
-      url: `${serverUrl}/trpc`,
-      fetch(url, options) {
-        return fetch(url, {
-          ...options,
-          body: options?.body ? (options.body as BodyInit | null | undefined) : undefined,
-          credentials: "include",
-        });
-      },
-      transformer,
-    }),
-  ],
-});
+import type { BackendTRPCRouter } from "@m5kdev/backend/types";
+import { transformer } from "@m5kdev/commons/utils/trpc";
+import { createTRPCClient, httpBatchLink } from "@trpc/client";
+import { serverUrl } from "../config";
+
+export const trpcClient = createTRPCClient<BackendTRPCRouter>({
+  links: [
+    httpBatchLink({
+      url: `${serverUrl}/trpc`,
+      fetch(url, options) {
+        return fetch(url, {
+          ...options,
+          body: options?.body ? (options.body as BodyInit | null | undefined) : undefined,
+          credentials: "include",
+        });
+      },
+      transformer,
+    }),
+  ],
+});

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

@@ -1,11 +1,11 @@
-{
-  "extends": "expo/tsconfig.base",
-  "compilerOptions": {
-    "strict": true,
-    "paths": {
-      "@/*": ["./src/*"],
-      "@/assets/*": ["./assets/*"]
-    }
-  },
-  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts", "uniwind-env.d.ts"]
-}
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/assets/*": ["./assets/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts", "uniwind-env.d.ts"]
+}

package/templates/minimal-app/apps/expo/uniwind-env.d.ts.tpl

@@ -1 +1 @@
-/// <reference types="uniwind/types" />
+/// <reference types="uniwind/types" />

package/templates/minimal-app/apps/landing/.env.production.example.tpl

@@ -0,0 +1,7 @@
+# Copy to .env.production and fill in values. This file is not copied into the
+# image (.dockerignore excludes .env*). landing:deploy forwards every key as a
+# Fly build secret; landing:secrets imports the same file as runtime secrets.
+
+VITE_APP_NAME={{APP_NAME}}
+VITE_APP_URL=
+VITE_SERVER_URL=

package/templates/minimal-app/apps/landing/Dockerfile.tpl

@@ -0,0 +1,39 @@
+# syntax = docker/dockerfile:1
+
+FROM node:24-slim AS base
+
+LABEL fly_launch_runtime="NodeJS"
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+FROM base AS build
+
+RUN apt-get update -qq && \
+    apt-get install -y python-is-python3 pkg-config build-essential ca-certificates && \
+    update-ca-certificates
+
+RUN npm install -g pnpm@10.13.1
+
+COPY --link . .
+
+RUN pnpm install --frozen-lockfile --prod=false
+
+# Frontend bake needs VITE_* from the operator env file. The wrapper passes
+# ALL_SECRETS (every key) plus per-key --build-secret flags.
+RUN --mount=type=secret,id=ALL_SECRETS,required=false \
+    if [ -f /run/secrets/ALL_SECRETS ]; then . /run/secrets/ALL_SECRETS; fi && \
+    pnpm --filter={{PACKAGE_SCOPE}}/landing build
+
+RUN pnpm --filter={{PACKAGE_SCOPE}}/landing deploy --prod --legacy /deploy
+RUN cp -r /app/apps/landing/dist /deploy/dist
+
+FROM base
+
+COPY --from=build /deploy /app
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+
+WORKDIR /app
+
+CMD ["npm", "run", "start"]

package/templates/minimal-app/apps/landing/fly.toml.tpl

@@ -0,0 +1,20 @@
+app = "{{APP_SLUG}}-landing"
+primary_region = "iad"
+
+[build]
+
+[env]
+  PORT = "8080"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+  processes = ["app"]
+
+[[vm]]
+  memory = "1gb"
+  cpu_kind = "shared"
+  cpus = 1

package/templates/minimal-app/apps/landing/index.html.tpl

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <meta
+      name="description"
+      content="{{APP_NAME}} — an AI SaaS workspace."
+    />
+    <link
+      rel="preconnect"
+      href="https://fonts.googleapis.com"
+    />
+    <link
+      rel="preconnect"
+      href="https://fonts.gstatic.com"
+      crossorigin
+    />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,700&family=Figtree:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script
+      type="module"
+      src="/src/main.tsx"
+    ></script>
+  </body>
+</html>

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

@@ -0,0 +1,34 @@
+{
+  "name": "{{PACKAGE_SCOPE}}/landing",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "start": "vite preview --host 0.0.0.0 --port 8080",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@heroui/react": "catalog:m5kdev",
+    "@heroui/styles": "catalog:m5kdev",
+    "react": "catalog:m5kdev",
+    "react-dom": "catalog:m5kdev",
+    "react-router": "catalog:m5kdev",
+    "tailwindcss": "catalog:m5kdev",
+    "tw-animate-css": "catalog:m5kdev",
+    "vite": "catalog:m5kdev"
+  },
+  "devDependencies": {
+    "@m5kdev/config": "catalog:m5kdev",
+    "@tailwindcss/vite": "catalog:m5kdev",
+    "@types/react": "catalog:m5kdev",
+    "@types/react-dom": "catalog:m5kdev",
+    "@vitejs/plugin-react": "catalog:m5kdev",
+    "babel-plugin-react-compiler": "catalog:m5kdev",
+    "typescript": "catalog:m5kdev",
+    "vite-tsconfig-paths": "catalog:m5kdev"
+  }
+}

package/templates/minimal-app/apps/landing/src/App.tsx.tpl

@@ -0,0 +1,12 @@
+import { BrowserRouter, Route, Routes } from "react-router";
+import { LandingPage } from "./LandingPage";
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="*" element={<LandingPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}

package/templates/minimal-app/apps/landing/src/LandingPage.tsx.tpl

@@ -0,0 +1,37 @@
+import { Button, Card } from "@heroui/react";
+
+export function LandingPage() {
+  const appName = import.meta.env.VITE_APP_NAME ?? "{{APP_NAME}}";
+  const appUrl = import.meta.env.VITE_APP_URL ?? "http://localhost:5173";
+
+  return (
+    <main className="relative flex min-h-dvh flex-col items-center justify-center overflow-hidden px-6 py-16">
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute inset-0 bg-[radial-gradient(circle_at_top,oklch(0.92_0.04_85),transparent_55%)]"
+      />
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute inset-0 opacity-[0.12] [background-image:repeating-linear-gradient(0deg,transparent,transparent_23px,var(--color-rule)_24px)]"
+      />
+      <Card className="relative max-w-xl border border-[var(--color-rule)] bg-[color-mix(in_oklch,var(--color-paper)_92%,white)] shadow-none">
+        <Card.Header className="grid gap-4 p-8 pb-4 sm:p-10 sm:pb-4">
+          <p className="text-xs font-medium tracking-[0.28em] text-[color-mix(in_oklch,var(--color-ink)_55%,transparent)] uppercase">
+            Public site
+          </p>
+          <Card.Title className="font-[family-name:var(--font-display)] text-5xl leading-[0.95] font-medium tracking-tight sm:text-6xl">
+            {appName}
+          </Card.Title>
+          <Card.Description className="max-w-md text-base leading-relaxed text-[color-mix(in_oklch,var(--color-ink)_72%,transparent)]">
+            An AI SaaS workspace. Sign in on the app when you are ready to write, ship, and operate.
+          </Card.Description>
+        </Card.Header>
+        <Card.Footer className="p-8 pt-2 sm:p-10 sm:pt-2">
+          <Button variant="primary" onPress={() => window.location.assign(appUrl)}>
+            Open app
+          </Button>
+        </Card.Footer>
+      </Card>
+    </main>
+  );
+}

package/templates/minimal-app/apps/landing/src/index.css.tpl

@@ -0,0 +1,24 @@
+/* biome-ignore-all lint/suspicious/noUnknownAtRules: Tailwind v4 */
+
+@import "tailwindcss";
+@import "@heroui/styles";
+@import "tw-animate-css";
+
+@theme {
+  --font-display: "Fraunces", "Times New Roman", serif;
+  --font-sans: "Figtree", ui-sans-serif, system-ui, sans-serif;
+  --color-ink: oklch(0.22 0.03 250);
+  --color-paper: oklch(0.97 0.01 85);
+  --color-rule: oklch(0.84 0.02 85);
+  --accent: oklch(0.6204 0.195 253.83);
+}
+
+html {
+  font-family: var(--font-sans);
+  background: var(--color-paper);
+  color: var(--color-ink);
+}
+
+body {
+  margin: 0;
+}

package/templates/minimal-app/apps/landing/src/main.tsx.tpl

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./index.css";
+
+const rootElement = document.getElementById("root");
+
+if (!rootElement) {
+  throw new Error("Root element #root not found.");
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/templates/minimal-app/apps/landing/src/vite-env.d.ts.tpl

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME?: string;
+  readonly VITE_APP_URL?: string;
+  readonly VITE_SERVER_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

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

@@ -0,0 +1,12 @@
+{
+  "extends": "@m5kdev/config/tsconfig.vite.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "ignoreDeprecations": "6.0",
+    "rootDir": ".",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo"
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}

package/templates/minimal-app/apps/landing/vite.config.ts.tpl

@@ -0,0 +1,25 @@
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [
+    tailwindcss(),
+    react({
+      babel: {
+        plugins: ["babel-plugin-react-compiler"],
+      },
+    }),
+    tsconfigPaths(),
+  ],
+  resolve: {
+    dedupe: ["react", "react-dom", "react-router"],
+  },
+  envDir: "../shared",
+  preview: {
+    host: "0.0.0.0",
+    port: 8080,
+  },
+});

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

@@ -1,46 +1,55 @@
-# 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
-└── <module>.module.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.
-- Register modules in `apps/server/src/app.ts`; use `db.ts` only for scripts that need direct DB.
-
-## Avoid Trivial Service Delegation
-
-- Do not add service methods that merely call another service.
-- Call the owning service directly unless the method adds a business rule, authorization, validation, orchestration, a transaction boundary, or meaningful domain translation.
-- Renaming a dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a wrapper.
-- If removing the method and calling the dependency directly would lose no behavior or boundary, do not add it.
-
-## Workflow, Redis, and push notifications
-
-- `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()`, which listens and handles SIGINT/SIGTERM. Extra shutdown work (telemetry) is `onShutdown` on `createBackendApp`.
-- 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`.
+# 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
+└── <module>.module.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.
+- Register Core Modules and app modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`. Do not use `backendApp.use`. Optional Backend Modules (`@m5kdev/module-*`) are not scaffolded; add them only when the product needs Clay, Docx, Pdf, Social, or Video.
+// m5k:ai:start
+- `AIModule` is registered in `app.ts` with an app-owned Mastra Agent (`assistant`). Conversation HTTP lives on `/ai`. Set `OPENROUTER_API_KEY` for live replies. Do not add a Starter service wrapper around `AIService` chat.
+// m5k:ai:end
+- Database commands live in server `db.ts` (`pnpm drizzle:reset`, `drizzle:sync`, `drizzle:seed`) and call Kernel `runDb` — they must not import `app.ts`.
+
+## Avoid Trivial Service Delegation
+
+- Do not add service methods that merely call another service.
+- Call the owning service directly unless the method adds a business rule, authorization, validation, orchestration, a transaction boundary, or meaningful domain translation.
+- Renaming a dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a wrapper.
+- If removing the method and calling the dependency directly would lose no behavior or boundary, do not add it.
+
+## Runtime notes
+
+// m5k:workflows:start
+- `WorkflowModule` is registered in `app.ts`. Start **Redis** locally (`REDIS_URL`) before `pnpm dev` on the server, or background jobs will not run.
+- Server event: emit through Auth from a job `.handle` when the UI must refresh a change the trigger mutation did not return. See `.cursor/rules/server-event-emit.mdc`.
+// m5k:workflows:end
+- `index.ts` calls `builtBackendApp.start()`, which listens and handles SIGINT/SIGTERM. Extra shutdown work (telemetry) is `onShutdown` on `createBackendApp`.
+- After changing Drizzle tables, run `pnpm --filter ./apps/server drizzle:generate` then `drizzle:migrate` — do not hand-edit SQL migrations in this repo.
+
+// m5k:notifications:start
+- `NotificationModule` is registered in `app.ts` when this feature is selected. Push-related server env vars are documented in `apps/shared/.env.example`.
+// m5k:notifications:end

package/templates/minimal-app/apps/server/{drizzle/seed.e2e.ts.tpl → db.e2e.ts.tpl}

@@ -1,18 +1,39 @@
 /**
  * E2E fixture seed — used only by the e2e package's prepare scripts, never by
  * generated apps (the CLI excludes this file). The user-facing demo seed lives
- * in ./seed.ts.
+ * in ./db.ts.
  */
+import { type RunDbSeedContext, runDb } from "@m5kdev/backend/db";
 import { hashPassword } from "better-auth/crypto";
 import { eq } from "drizzle-orm";
 import { v4 as uuidv4 } from "uuid";
-import { orm, schema } from "./db";
-import { ensureDevServerStopped } from "./guard";
+import * as schema from "./src/schema";
 
 const profile = process.env.AUTH_E2E_PROFILE ?? "standard";
 const ADMIN_EMAIL = `admin.${profile}@auth-e2e.local`;
 const ADMIN_PASSWORD = "password1234";
 
+type SeedOrm = RunDbSeedContext<typeof schema>["orm"];
+
+void runDb({
+  schema,
+  seed: async ({ orm }) => {
+    const admin = await ensureUser({
+      orm,
+      id: `auth-e2e-admin-${profile}`,
+      name: "Auth E2E Admin",
+      email: ADMIN_EMAIL,
+      password: ADMIN_PASSWORD,
+      role: "admin",
+    });
+    const { organizationId } = await ensureOrganization({ orm, userId: admin.id });
+    await seedPosts({ orm, userId: admin.id, organizationId });
+    await seedExpiredWaitlistCode(orm);
+    await seedProvisionedClaimUser(orm);
+    console.info(`Seeded ${profile}. Admin login: ${ADMIN_EMAIL} / ${ADMIN_PASSWORD}`);
+  },
+});
+
 function slugify(value: string): string {
   return value
     .trim()
@@ -21,27 +42,24 @@ function slugify(value: string): string {
     .replace(/^-+|-+$/g, "");
 }
 
-async function ensureUser({
-  id,
-  name,
-  email,
-  password,
-  role = "user",
-  emailVerified = true,
-}: {
+async function ensureUser(input: {
+  orm: SeedOrm;
   id: string;
   name: string;
   email: string;
   password?: string;
   role?: string;
   emailVerified?: boolean;
-}) {
+}): Promise<typeof schema.users.$inferSelect> {
+  const { orm, id, name, email, password, role = "user", emailVerified = true } = input;
   const [existingUser] = await orm
     .select()
     .from(schema.users)
     .where(eq(schema.users.email, email))
     .limit(1);
-  if (existingUser) return existingUser;
+  if (existingUser) {
+    return existingUser;
+  }
 
   const [user] = await orm
     .insert(schema.users)
@@ -56,7 +74,9 @@ async function ensureUser({
     })
     .returning();
 
-  if (!user) throw new Error(`Failed to seed user ${email}`);
+  if (!user) {
+    throw new Error(`Failed to seed user ${email}`);
+  }
 
   if (password) {
     await orm.insert(schema.accounts).values({
@@ -73,7 +93,11 @@ async function ensureUser({
   return user;
 }
 
-async function ensureOrganization(userId: string) {
+async function ensureOrganization(input: {
+  orm: SeedOrm;
+  userId: string;
+}): Promise<{ organizationId: string; teamId: string }> {
+  const { orm, userId } = input;
   const organizationId = `auth-e2e-enterprise-${profile}`;
   const teamId = `auth-e2e-team-${profile}`;
 
@@ -144,9 +168,16 @@ async function ensureOrganization(userId: string) {
   return { organizationId, teamId };
 }
 
-async function seedPosts(userId: string, organizationId: string) {
+async function seedPosts(input: {
+  orm: SeedOrm;
+  userId: string;
+  organizationId: string;
+}): Promise<void> {
+  const { orm, userId, organizationId } = input;
   const existingPosts = await orm.select().from(schema.posts).limit(1);
-  if (existingPosts.length > 0) return;
+  if (existingPosts.length > 0) {
+    return;
+  }
 
   const posts = [
     {
@@ -175,13 +206,15 @@ async function seedPosts(userId: string, organizationId: string) {
   );
 }
 
-async function seedExpiredWaitlistCode() {
+async function seedExpiredWaitlistCode(orm: SeedOrm): Promise<void> {
   const [existing] = await orm
     .select()
     .from(schema.waitlist)
     .where(eq(schema.waitlist.code, "expired-waitlist-code"))
     .limit(1);
-  if (existing) return;
+  if (existing) {
+    return;
+  }
 
   await orm.insert(schema.waitlist).values({
     id: uuidv4(),
@@ -196,8 +229,9 @@ async function seedExpiredWaitlistCode() {
   });
 }
 
-async function seedProvisionedClaimUser() {
+async function seedProvisionedClaimUser(orm: SeedOrm): Promise<typeof schema.users.$inferSelect> {
   const user = await ensureUser({
+    orm,
     id: `auth-e2e-claim-user-${profile}`,
     name: "Provisioned Claim User",
     email: `claim.${profile}@provisioned.auth-e2e.local`,
@@ -210,7 +244,9 @@ async function seedProvisionedClaimUser() {
     .from(schema.waitlist)
     .where(eq(schema.waitlist.claimUserId, user.id))
     .limit(1);
-  if (existingClaim) return user;
+  if (existingClaim) {
+    return user;
+  }
 
   await orm.insert(schema.waitlist).values({
     id: `auth-e2e-claim-${profile}`,
@@ -225,22 +261,3 @@ async function seedProvisionedClaimUser() {
 
   return user;
 }
-
-async function seed() {
-  await ensureDevServerStopped();
-  const admin = await ensureUser({
-    id: `auth-e2e-admin-${profile}`,
-    name: "Auth E2E Admin",
-    email: ADMIN_EMAIL,
-    password: ADMIN_PASSWORD,
-    role: "admin",
-  });
-  const { organizationId } = await ensureOrganization(admin.id);
-  await seedPosts(admin.id, organizationId);
-  await seedExpiredWaitlistCode();
-  await seedProvisionedClaimUser();
-
-  console.info(`Seeded ${profile}. Admin login: ${ADMIN_EMAIL} / ${ADMIN_PASSWORD}`);
-}
-
-void seed();