@thinhnguyencth1204/nextcli 0.3.0 → 0.4.1

package/templates/next-base/src/components/branding/logo.tsx

@@ -0,0 +1,27 @@
+import Image from "next/image";
+import { branding } from "@/config/branding";
+import { cn } from "@/utils/cn";
+
+type LogoProps = {
+  className?: string;
+  size?: number;
+  showLabel?: boolean;
+};
+
+export function Logo({ className, size = 28, showLabel = false }: LogoProps) {
+  return (
+    <span className={cn("inline-flex items-center gap-2", className)}>
+      <Image
+        src={branding.logoPath}
+        alt={branding.projectName}
+        width={size}
+        height={size}
+        className="shrink-0"
+        priority
+      />
+      {showLabel ? (
+        <span className="font-semibold">{branding.projectName}</span>
+      ) : null}
+    </span>
+  );
+}

package/templates/next-base/src/components/layout/private/app-sidebar.tsx

@@ -2,19 +2,18 @@
 
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import Link from "next/link";
-import { useTranslations } from "next-intl";
 import {
   useSidebar,
   Sidebar,
   SidebarHeader,
   SidebarTrigger,
 } from "@/components/ui/sidebar";
+import { Logo } from "@/components/branding/logo";
 import { NavSidebar } from "@/components/layout/private/nav-sidebar";
 import { cn } from "@/utils/cn";
 
 export function AppSidebar() {
   const { state, isMobile } = useSidebar();
-  const t = useTranslations("common");
   const isCollapsed = state === "collapsed";
 
   return (
@@ -35,8 +34,8 @@ export function AppSidebar() {
         </div>
       )}
       <SidebarHeader className="p-3">
-        <Link href="/" className="font-semibold">
-          {t("appName")}
+        <Link href="/dashboard">
+          <Logo showLabel />
         </Link>
       </SidebarHeader>
       <NavSidebar />

package/templates/next-base/src/components/layout/private/dashboard-layout.tsx

@@ -6,6 +6,7 @@ import { useTranslations } from "next-intl";
 import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { Button } from "@/components/ui/button";
+import { Logo } from "@/components/branding/logo";
 import { AppSidebar } from "@/components/layout/private/app-sidebar";
 import { NavUser } from "@/components/layout/private/nav-user";
 import { useIsMobile } from "@/hooks/use-mobile";
@@ -21,7 +22,7 @@ export function DashboardLayout({ children }: { children: React.ReactNode }) {
         <header className="flex h-14 items-center justify-between border-b bg-card px-4">
           <div className="flex items-center gap-2">
             {isMobile && <SidebarTrigger />}
-            <p className="font-semibold">__PROJECT_NAME__</p>
+            <Logo showLabel />
           </div>
 
           <div className="flex items-center gap-2">

package/templates/next-base/src/config/branding.ts

@@ -0,0 +1,14 @@
+/**
+ * Central branding config — edit these values after scaffolding.
+ * See SETUP.md § Branding for env vs display settings.
+ */
+export const branding = {
+  /** Display name shown in UI (header, metadata, sidebar). */
+  projectName: "__PROJECT_NAME__",
+  /** URL-safe slug (package name, DB name). Set at create time. */
+  projectSlug: "__PROJECT_NAME__",
+  /** Short app description for metadata. */
+  description: "Outsource-ready Next.js scaffolded by NexTCLI",
+  /** Public path to logo asset under /public. */
+  logoPath: "/logo.svg",
+} as const;

package/templates/next-base/src/features/auth/components/account-panel.tsx

@@ -2,32 +2,34 @@
 
 import { useEffect, useState } from "react";
 import { useTranslations } from "next-intl";
-import { publicApi } from "@/lib/axios-instance";
+import { protectedApi } from "@/lib/axios-instance";
 import type { ApiSuccess } from "@/types";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 
-type SessionPayload = {
+type MePayload = {
   user?: {
     id: string;
-    email: string;
+    username: string;
+    email?: string | null;
     name?: string | null;
+    role?: { name: string; level: number } | null;
   };
 };
 
 export function AccountPanel() {
   const t = useTranslations("auth.account");
-  const [session, setSession] = useState<SessionPayload | null>(null);
+  const [session, setSession] = useState<MePayload | null>(null);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
     let mounted = true;
     const run = async () => {
       try {
-        const response = await publicApi.get("/api/v1/auth/me", {
+        const response = await protectedApi.get("/api/v1/auth/me", {
           withCredentials: true,
         });
         if (mounted) {
-          setSession((response.data as ApiSuccess<SessionPayload>).data);
+          setSession((response.data as ApiSuccess<MePayload>).data);
         }
       } catch {
         if (mounted) {
@@ -64,7 +66,10 @@ export function AccountPanel() {
           {t("userId")}: {session.user.id}
         </p>
         <p>
-          {t("email")}: {session.user.email}
+          {t("username")}: {session.user.username}
+        </p>
+        <p>
+          {t("email")}: {session.user.email ?? t("na")}
         </p>
         <p>
           {t("name")}: {session.user.name ?? t("na")}

package/templates/next-base/src/features/auth/components/change-password-form.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useState } from "react";
+import type { FormEvent } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { toast } from "sonner";
+import { protectedApi } from "@/lib/axios-instance";
+import { changePasswordSchema } from "@/features/auth/validations";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export function ChangePasswordForm() {
+  const router = useRouter();
+  const t = useTranslations("auth.changePasswordForm");
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+
+    const parsed = changePasswordSchema.safeParse({
+      currentPassword,
+      newPassword,
+    });
+
+    if (!parsed.success) {
+      toast.error(t("invalidInput"));
+      return;
+    }
+
+    try {
+      setIsSubmitting(true);
+      await protectedApi.post("/api/v1/auth/change-password", parsed.data, {
+        withCredentials: true,
+      });
+      toast.success(t("success"));
+      router.push("/dashboard");
+      router.refresh();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : t("failed");
+      toast.error(message);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <Card>
+      <CardContent className="pt-6">
+        <form onSubmit={onSubmit} className="grid gap-4">
+          <div className="grid gap-2">
+            <Label htmlFor="currentPassword">{t("currentPassword")}</Label>
+            <Input
+              id="currentPassword"
+              type="password"
+              value={currentPassword}
+              onChange={(event) => setCurrentPassword(event.target.value)}
+              required
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="newPassword">{t("newPassword")}</Label>
+            <Input
+              id="newPassword"
+              type="password"
+              value={newPassword}
+              onChange={(event) => setNewPassword(event.target.value)}
+              required
+            />
+          </div>
+          <Button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? t("submitting") : t("submit")}
+          </Button>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}

package/templates/next-base/src/features/auth/components/sign-in-form.tsx

@@ -14,17 +14,22 @@ import { Card, CardContent } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 
+type LoginResponse = {
+  accessToken: string;
+  requirePasswordChange: boolean;
+};
+
 export function SignInForm() {
   const router = useRouter();
   const t = useTranslations("auth.signInForm");
-  const [email, setEmail] = useState("");
+  const [username, setUsername] = useState("");
   const [password, setPassword] = useState("");
   const [isSubmitting, setIsSubmitting] = useState(false);
 
   const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
     event.preventDefault();
 
-    const parsed = signInSchema.safeParse({ email, password });
+    const parsed = signInSchema.safeParse({ username, password });
     if (!parsed.success) {
       toast.error(t("invalidInput"));
       return;
@@ -35,16 +40,15 @@ export function SignInForm() {
       const response = await publicApi.post("/api/v1/auth/login", parsed.data, {
         withCredentials: true,
       });
-      const accessToken = (response.data as ApiSuccess<{ accessToken: string }>)
-        .data?.accessToken;
-      if (!accessToken) {
+      const payload = (response.data as ApiSuccess<LoginResponse>).data;
+      if (!payload?.accessToken) {
         toast.error(t("missingAccessToken"));
         return;
       }
 
-      setAccessToken(accessToken);
+      setAccessToken(payload.accessToken);
       toast.success(t("success"));
-      router.push("/account");
+      router.push(payload.requirePasswordChange ? "/change-password" : "/dashboard");
       router.refresh();
     } catch (error) {
       const message = error instanceof Error ? error.message : t("failed");
@@ -59,13 +63,13 @@ export function SignInForm() {
       <CardContent className="pt-6">
         <form onSubmit={onSubmit} className="grid gap-4">
           <div className="grid gap-2">
-            <Label htmlFor="email">{t("email")}</Label>
+            <Label htmlFor="username">{t("username")}</Label>
             <Input
-              id="email"
-              type="email"
-              value={email}
-              onChange={(event) => setEmail(event.target.value)}
-              placeholder={t("emailPlaceholder")}
+              id="username"
+              value={username}
+              onChange={(event) => setUsername(event.target.value)}
+              placeholder={t("usernamePlaceholder")}
+              autoComplete="username"
               required
             />
           </div>
@@ -77,6 +81,7 @@ export function SignInForm() {
               value={password}
               onChange={(event) => setPassword(event.target.value)}
               placeholder={t("passwordPlaceholder")}
+              autoComplete="current-password"
               required
             />
           </div>

package/templates/next-base/src/features/auth/validations.ts

@@ -1,8 +1,14 @@
 import { z } from "zod";
 
 export const signInSchema = z.object({
-  email: z.string().email(),
+  username: z.string().min(3).max(30),
   password: z.string().min(8),
 });
 
+export const changePasswordSchema = z.object({
+  currentPassword: z.string().min(8),
+  newPassword: z.string().min(8),
+});
+
 export type SignInInput = z.infer<typeof signInSchema>;
+export type ChangePasswordInput = z.infer<typeof changePasswordSchema>;

package/templates/next-base/src/features/users/services.ts

@@ -0,0 +1,132 @@
+import type { Role, User } from "@prisma/client";
+import { INTERNAL_EMAIL_DOMAIN, SUPER_ADMIN_USERNAME } from "@/lib/constants";
+import { auth } from "@/lib/auth";
+import prisma from "@/lib/prisma";
+import type { CreateUserInput, UpdateUserInput } from "@/features/users/validations";
+
+export type UserWithRole = User & { role: Role | null };
+
+function toPublicUser(user: UserWithRole) {
+  return {
+    id: user.id,
+    username: user.username,
+    displayUsername: user.displayUsername,
+    name: user.name,
+    email: user.email,
+    requirePasswordChange: user.requirePasswordChange,
+    role: user.role
+      ? { id: user.role.id, name: user.role.name, level: user.role.level }
+      : null,
+    createdAt: user.createdAt,
+    updatedAt: user.updatedAt,
+  };
+}
+
+export async function listUsersForActor(actorLevel: number) {
+  const users = await prisma.user.findMany({
+    where: {
+      username: { not: SUPER_ADMIN_USERNAME },
+      role: {
+        level: { lt: actorLevel },
+      },
+    },
+    include: { role: true },
+    orderBy: { createdAt: "desc" },
+  });
+
+  return users.map(toPublicUser);
+}
+
+export async function getUserByIdForActor(
+  id: string,
+  actorLevel: number,
+): Promise<ReturnType<typeof toPublicUser> | null> {
+  const user = await prisma.user.findFirst({
+    where: {
+      id,
+      username: { not: SUPER_ADMIN_USERNAME },
+      role: {
+        level: { lt: actorLevel },
+      },
+    },
+    include: { role: true },
+  });
+
+  return user ? toPublicUser(user) : null;
+}
+
+export async function createUserRecord(
+  input: CreateUserInput,
+  options?: { requirePasswordChange?: boolean },
+) {
+  const placeholderEmail =
+    input.email ?? `${input.username}@${INTERNAL_EMAIL_DOMAIN}`;
+
+  await auth.api.signUpEmail({
+    body: {
+      email: placeholderEmail,
+      password: input.password,
+      name: input.name ?? input.username,
+      username: input.username,
+      displayUsername: input.username,
+    },
+  });
+
+  const created = await prisma.user.findUnique({
+    where: { username: input.username },
+    include: { role: true },
+  });
+
+  if (!created) {
+    throw new Error("USER_CREATE_FAILED");
+  }
+
+  const updated = await prisma.user.update({
+    where: { id: created.id },
+    data: {
+      roleId: input.roleId,
+      email: input.email ?? placeholderEmail,
+      requirePasswordChange: options?.requirePasswordChange ?? input.requirePasswordChange ?? false,
+    },
+    include: { role: true },
+  });
+
+  return toPublicUser(updated);
+}
+
+export async function updateUserRecord(id: string, input: UpdateUserInput) {
+  const existing = await prisma.user.findUnique({
+    where: { id },
+    include: { role: true },
+  });
+
+  if (!existing) {
+    return null;
+  }
+
+  if (input.password) {
+    const { hashPassword } = await import("better-auth/crypto");
+    const hashed = await hashPassword(input.password);
+    await prisma.account.updateMany({
+      where: { userId: id, providerId: "credential" },
+      data: { password: hashed },
+    });
+  }
+
+  const updated = await prisma.user.update({
+    where: { id },
+    data: {
+      name: input.name,
+      email: input.email,
+      roleId: input.roleId,
+      requirePasswordChange: input.requirePasswordChange,
+    },
+    include: { role: true },
+  });
+
+  return toPublicUser(updated);
+}
+
+export async function deleteUserRecord(id: string) {
+  await prisma.user.delete({ where: { id } });
+}

package/templates/next-base/src/features/users/validations.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  username: z.string().min(3).max(30),
+  password: z.string().min(8),
+  name: z.string().min(1).max(120).optional(),
+  email: z.string().email().optional(),
+  roleId: z.string().min(1),
+  requirePasswordChange: z.boolean().optional(),
+});
+
+export const updateUserSchema = z.object({
+  name: z.string().min(1).max(120).optional(),
+  email: z.string().email().nullable().optional(),
+  roleId: z.string().min(1).optional(),
+  password: z.string().min(8).optional(),
+  requirePasswordChange: z.boolean().optional(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;

package/templates/next-base/src/instrumentation.ts

@@ -0,0 +1,14 @@
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") {
+    return;
+  }
+
+  try {
+    const { runBootstrap } = await import("@/lib/bootstrap");
+    await runBootstrap();
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Unknown instrumentation error";
+    console.warn(`[instrumentation] Bootstrap failed: ${message}`);
+  }
+}

package/templates/next-base/src/lib/auth-client.ts

@@ -1,7 +1,7 @@
 import { createAuthClient } from "better-auth/react";
-import { jwtClient } from "better-auth/client/plugins";
+import { jwtClient, usernameClient } from "better-auth/client/plugins";
 
 export const authClient = createAuthClient({
   baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
-  plugins: [jwtClient()],
+  plugins: [jwtClient(), usernameClient()],
 });

package/templates/next-base/src/lib/auth.ts

@@ -1,6 +1,6 @@
 import { betterAuth } from "better-auth/minimal";
 import { prismaAdapter } from "better-auth/adapters/prisma";
-import { jwt } from "better-auth/plugins";
+import { jwt, username } from "better-auth/plugins";
 import prisma from "@/lib/prisma";
 
 const socialProviders = {
@@ -12,7 +12,7 @@ export const auth = betterAuth({
   database: prismaAdapter(prisma, {
     provider: "postgresql",
   }),
-  plugins: [jwt()],
+  plugins: [jwt(), username()],
   emailAndPassword: {
     enabled: true,
   },

package/templates/next-base/src/lib/bootstrap.ts

@@ -0,0 +1,96 @@
+import type { PrismaClient } from "@prisma/client";
+import {
+  ADMIN_ROLE_LEVEL,
+  ADMIN_ROLE_NAME,
+  INTERNAL_EMAIL_DOMAIN,
+  SUPER_ADMIN_USERNAME,
+} from "@/lib/constants";
+import { auth } from "@/lib/auth";
+import prisma from "@/lib/prisma";
+
+const DEFAULT_ADMIN_PASSWORD = "admin";
+
+function hasRoleModel(client: PrismaClient): boolean {
+  const delegate = (
+    client as PrismaClient & { role?: { findUnique?: unknown } }
+  ).role;
+  return typeof delegate?.findUnique === "function";
+}
+
+function logBootstrapSkip(message: string): void {
+  console.warn(`[bootstrap] ${message}`);
+}
+
+export async function runBootstrap(): Promise<void> {
+  if (!hasRoleModel(prisma)) {
+    logBootstrapSkip(
+      "Prisma client is missing the Role model. Run: bun run db:generate && bun run db:migrate",
+    );
+    return;
+  }
+
+  try {
+    let adminRole = await prisma.role.findUnique({
+      where: { name: ADMIN_ROLE_NAME },
+    });
+
+    if (!adminRole) {
+      adminRole = await prisma.role.create({
+        data: {
+          name: ADMIN_ROLE_NAME,
+          level: ADMIN_ROLE_LEVEL,
+        },
+      });
+    }
+
+    const existingAdmin = await prisma.user.findUnique({
+      where: { username: SUPER_ADMIN_USERNAME },
+    });
+
+    if (existingAdmin) {
+      if (!existingAdmin.roleId) {
+        await prisma.user.update({
+          where: { id: existingAdmin.id },
+          data: { roleId: adminRole.id },
+        });
+      }
+      return;
+    }
+
+    try {
+      await auth.api.signUpEmail({
+        body: {
+          email: `${SUPER_ADMIN_USERNAME}@${INTERNAL_EMAIL_DOMAIN}`,
+          password: DEFAULT_ADMIN_PASSWORD,
+          name: "Administrator",
+          username: SUPER_ADMIN_USERNAME,
+          displayUsername: SUPER_ADMIN_USERNAME,
+        },
+      });
+    } catch {
+      // User may already exist from a partial bootstrap run.
+    }
+
+    const adminUser = await prisma.user.findUnique({
+      where: { username: SUPER_ADMIN_USERNAME },
+    });
+
+    if (!adminUser) {
+      return;
+    }
+
+    await prisma.user.update({
+      where: { id: adminUser.id },
+      data: {
+        roleId: adminRole.id,
+        requirePasswordChange: true,
+      },
+    });
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Unknown bootstrap error";
+    logBootstrapSkip(
+      `Skipped admin seed (${message}). Ensure Postgres is running and run: bun run db:migrate`,
+    );
+  }
+}

package/templates/next-base/src/lib/constants.ts

@@ -0,0 +1,7 @@
+/** Built-in super-admin account username — protected from RBAC mutations. */
+export const SUPER_ADMIN_USERNAME = "admin";
+
+export const ADMIN_ROLE_NAME = "admin";
+export const ADMIN_ROLE_LEVEL = 100;
+
+export const INTERNAL_EMAIL_DOMAIN = "internal.local";

package/templates/next-base/src/lib/rbac.ts

@@ -0,0 +1,62 @@
+import { headers } from "next/headers";
+import type { Role, User } from "@prisma/client";
+import { auth } from "@/lib/auth";
+import prisma from "@/lib/prisma";
+import { SUPER_ADMIN_USERNAME } from "@/lib/constants";
+
+export type SessionUser = User & { role: Role | null };
+
+export async function getSessionUser(
+  requestHeaders?: Headers,
+): Promise<SessionUser | null> {
+  const session = await auth.api.getSession({
+    headers: requestHeaders ?? (await headers()),
+  });
+
+  if (!session?.user?.id) {
+    return null;
+  }
+
+  return prisma.user.findUnique({
+    where: { id: session.user.id },
+    include: { role: true },
+  });
+}
+
+export function isSuperAdmin(user: Pick<User, "username">): boolean {
+  return user.username === SUPER_ADMIN_USERNAME;
+}
+
+export function canActOnUser(
+  actor: SessionUser,
+  target: SessionUser,
+): boolean {
+  if (isSuperAdmin(target)) {
+    return false;
+  }
+
+  if (!actor.role || !target.role) {
+    return false;
+  }
+
+  return actor.role.level > target.role.level;
+}
+
+export function canAssignRole(
+  actor: SessionUser,
+  targetRole: Pick<Role, "level">,
+): boolean {
+  if (!actor.role) {
+    return false;
+  }
+
+  return actor.role.level > targetRole.level;
+}
+
+export function requireAuthenticated(
+  user: SessionUser | null,
+): asserts user is SessionUser {
+  if (!user) {
+    throw new Error("UNAUTHORIZED");
+  }
+}