doo-boilerplate 0.1.0

package/dist/index.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as p4 from "@clack/prompts";
+import pc3 from "picocolors";
+import path5 from "path";
+import fse4 from "fs-extra";
+import { Command } from "commander";
+
+// src/prompts.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// src/utils/validate.ts
+import validatePkgName from "validate-npm-package-name";
+function validateProjectName(name) {
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    return "Project name cannot contain path separators";
+  }
+  const result = validatePkgName(name);
+  if (!result.validForNewPackages) {
+    return result.errors?.[0] ?? result.warnings?.[0] ?? "Invalid package name";
+  }
+  return void 0;
+}
+
+// src/prompts.ts
+async function collectOptions(defaults, isTTY2 = true) {
+  if (!isTTY2) {
+    const valid = ["editor", "charts", "dnd", "sentry"];
+    const validPMs2 = ["npm", "yarn", "pnpm", "bun", "deno"];
+    const projectName2 = defaults.projectName ?? "my-portal";
+    const framework2 = defaults.framework === "nextjs" || defaults.framework === "vite" ? defaults.framework : "vite";
+    const packageManager2 = validPMs2.includes(defaults.pm) ? defaults.pm : "pnpm";
+    const features2 = (defaults.features ?? []).filter((f) => valid.includes(f));
+    const auth2 = defaults.auth === "jwt" || defaults.auth === "oauth" || defaults.auth === "none" ? defaults.auth : "jwt";
+    return { projectName: projectName2, framework: framework2, packageManager: packageManager2, features: features2, auth: auth2, install: true };
+  }
+  let projectName;
+  if (defaults.projectName) {
+    const validation = validateProjectName(defaults.projectName);
+    if (validation !== void 0) {
+      p.cancel(`Invalid project name: ${validation}`);
+      process.exit(1);
+    }
+    projectName = defaults.projectName;
+  } else {
+    const answer = await p.text({
+      message: "Project name",
+      placeholder: "my-portal",
+      defaultValue: "my-portal",
+      validate: validateProjectName
+    });
+    if (p.isCancel(answer)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    projectName = answer;
+  }
+  let framework;
+  if (defaults.framework === "nextjs" || defaults.framework === "vite") {
+    framework = defaults.framework;
+  } else {
+    const answer = await p.select({
+      message: "Framework",
+      options: [
+        { value: "nextjs", label: "Next.js 16", hint: "SSR \xB7 App Router \xB7 i18n-ready" },
+        { value: "vite", label: "Vite 7", hint: "SPA \xB7 faster builds \xB7 TanStack Router" }
+      ]
+    });
+    if (p.isCancel(answer)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    framework = answer;
+  }
+  const validPMs = ["npm", "yarn", "pnpm", "bun", "deno"];
+  let packageManager;
+  if (validPMs.includes(defaults.pm)) {
+    packageManager = defaults.pm;
+  } else {
+    const answer = await p.select({
+      message: "Package manager",
+      options: [
+        { value: "npm", label: "npm", hint: "Node package manager" },
+        { value: "yarn", label: "yarn", hint: "Fast, reliable" },
+        { value: "pnpm", label: "pnpm", hint: "Efficient disk usage" },
+        { value: "bun", label: "bun", hint: "All-in-one runtime" },
+        { value: "deno", label: "deno", hint: "Secure by default" }
+      ]
+    });
+    if (p.isCancel(answer)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    packageManager = answer;
+  }
+  let features;
+  if (defaults.features && defaults.features.length > 0) {
+    const valid = ["editor", "charts", "dnd", "sentry"];
+    features = defaults.features.filter((f) => valid.includes(f));
+  } else {
+    const answer = await p.multiselect({
+      message: "Features " + pc.dim("(space to toggle, enter to confirm)"),
+      options: [
+        { value: "editor", label: "Rich text editor", hint: "Tiptap" },
+        { value: "charts", label: "Charts", hint: "ECharts" },
+        { value: "dnd", label: "Drag & drop", hint: "@dnd-kit" },
+        { value: "sentry", label: "Error tracking", hint: "Sentry" }
+      ],
+      required: false
+    });
+    if (p.isCancel(answer)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    features = answer;
+  }
+  let auth;
+  if (defaults.auth === "jwt" || defaults.auth === "oauth" || defaults.auth === "none") {
+    auth = defaults.auth;
+  } else {
+    const answer = await p.select({
+      message: "Auth pattern",
+      options: [
+        { value: "jwt", label: "JWT tokens", hint: "access + refresh token flow" },
+        { value: "oauth", label: "OAuth", hint: "placeholder, configure later" },
+        { value: "none", label: "None", hint: "skip auth setup" }
+      ]
+    });
+    if (p.isCancel(answer)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    auth = answer;
+  }
+  const installAnswer = await p.confirm({
+    message: "Install dependencies now?",
+    initialValue: true
+  });
+  if (p.isCancel(installAnswer)) {
+    p.cancel("Operation cancelled.");
+    process.exit(0);
+  }
+  const install2 = installAnswer;
+  return { projectName, framework, packageManager, features, auth, install: install2 };
+}
+
+// src/scaffold.ts
+import fse3 from "fs-extra";
+import path3 from "path";
+import { fileURLToPath } from "url";
+
+// src/utils/package-json.ts
+import fse from "fs-extra";
+import path from "path";
+async function mergeDepsIntoPackageJson(destDir, deps) {
+  const pkgPath = path.join(destDir, "package.json");
+  const pkg = await fse.readJson(pkgPath);
+  if (deps.dependencies) {
+    pkg.dependencies = { ...pkg.dependencies, ...deps.dependencies };
+  }
+  if (deps.devDependencies) {
+    pkg.devDependencies = { ...pkg.devDependencies, ...deps.devDependencies };
+  }
+  await fse.writeJson(pkgPath, pkg, { spaces: 2 });
+}
+
+// src/utils/template.ts
+import fse2 from "fs-extra";
+import path2 from "path";
+var TEXT_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".json",
+  ".md",
+  ".yml",
+  ".yaml",
+  ".env",
+  ".css",
+  ".html",
+  ".txt"
+];
+async function getAllTextFiles(dir) {
+  const entries = await fse2.readdir(dir, { withFileTypes: true, recursive: true });
+  return entries.filter((e) => {
+    if (!e.isFile()) return false;
+    if (!TEXT_EXTENSIONS.some((ext) => e.name.endsWith(ext))) return false;
+    const parent = e.parentPath ?? e.path ?? dir;
+    const fullPath = path2.join(parent, e.name);
+    return !fullPath.includes("node_modules") && !fullPath.includes(`${path2.sep}optional${path2.sep}`);
+  }).map((e) => {
+    const parent = e.parentPath ?? e.path ?? dir;
+    return path2.join(parent, e.name);
+  });
+}
+async function replaceInFiles(dir, replacements) {
+  const files = await getAllTextFiles(dir);
+  await Promise.all(
+    files.map(async (file) => {
+      let content = await fse2.readFile(file, "utf-8");
+      let changed = false;
+      for (const [from, to] of Object.entries(replacements)) {
+        if (content.includes(from)) {
+          content = content.replaceAll(from, to);
+          changed = true;
+        }
+      }
+      if (changed) {
+        await fse2.writeFile(file, content, "utf-8");
+      }
+    })
+  );
+}
+
+// src/scaffold.ts
+var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
+var FILE_RENAMES = [
+  ["_gitignore", ".gitignore"],
+  ["_env.example", ".env.example"],
+  ["_prettierrc", ".prettierrc"],
+  ["_prettierignore", ".prettierignore"]
+];
+async function scaffold(options, destDir) {
+  const templateName = options.framework === "nextjs" ? "template-nextjs" : "template-vite";
+  const templateSymlink = path3.join(__dirname2, "..", "templates", templateName);
+  const templateDir = await fse3.realpath(templateSymlink);
+  await fse3.copy(templateDir, destDir, {
+    overwrite: true,
+    filter: (src) => !src.includes(`${path3.sep}optional${path3.sep}`) && src !== path3.join(templateDir, "optional")
+  });
+  for (const [from, to] of FILE_RENAMES) {
+    const fromPath = path3.join(destDir, from);
+    const toPath = path3.join(destDir, to);
+    if (await fse3.pathExists(fromPath)) {
+      await fse3.move(fromPath, toPath);
+    }
+  }
+  for (const feature of options.features) {
+    await applyFeature(feature, templateDir, destDir);
+  }
+  await replaceInFiles(destDir, {
+    "{{PROJECT_NAME}}": options.projectName,
+    "{{YEAR}}": (/* @__PURE__ */ new Date()).getFullYear().toString()
+  });
+}
+async function applyFeature(feature, templateDir, destDir) {
+  const featureDir = path3.join(templateDir, "optional", feature);
+  if (!await fse3.pathExists(featureDir)) return;
+  const filesDir = path3.join(featureDir, "files");
+  if (await fse3.pathExists(filesDir)) {
+    await fse3.copy(filesDir, path3.join(destDir, "src"), { overwrite: true });
+  }
+  const depsFile = path3.join(featureDir, "deps.json");
+  if (await fse3.pathExists(depsFile)) {
+    const deps = await fse3.readJson(depsFile);
+    await mergeDepsIntoPackageJson(destDir, deps);
+  }
+}
+
+// src/install.ts
+import { execa } from "execa";
+import * as p2 from "@clack/prompts";
+function getInstallArgs(pm) {
+  if (pm === "deno") return { cmd: "deno", args: ["install", "--node-modules-dir"] };
+  return { cmd: pm, args: ["install"] };
+}
+async function install(destDir, packageManager) {
+  const spinner3 = p2.spinner();
+  spinner3.start("Installing dependencies...");
+  try {
+    const { cmd, args } = getInstallArgs(packageManager);
+    await execa(cmd, args, { cwd: destDir });
+    spinner3.stop("Dependencies installed");
+  } catch (err) {
+    spinner3.stop("Installation failed");
+    throw err;
+  }
+}
+
+// src/git.ts
+import { execa as execa2 } from "execa";
+async function initGit(destDir) {
+  await execa2("git", ["init"], { cwd: destDir });
+  await execa2("git", ["add", "-A"], { cwd: destDir });
+  await execa2("git", ["commit", "-m", "chore: initial scaffold from create-pila-app"], {
+    cwd: destDir
+  });
+}
+
+// src/post-setup.ts
+import * as p3 from "@clack/prompts";
+import pc2 from "picocolors";
+import path4 from "path";
+function printSuccess(options, destDir, isTTY2 = true) {
+  const relPath = path4.relative(process.cwd(), destDir);
+  const cdTarget = relPath || options.projectName;
+  const runCmd = `${options.packageManager} ${options.packageManager === "npm" ? "run dev" : "dev"}`;
+  const installLine = options.install ? "" : `  ${pc2.cyan(`${options.packageManager} install`)}
+`;
+  const msg = `${pc2.green("\u2713")} Project created! Get started:
+
+  ${pc2.cyan(`cd ${cdTarget}`)}
+` + installLine + `  ${pc2.cyan(runCmd)}
+
+  ${pc2.dim("Copy .env.example \u2192 .env and fill in your API URLs.")}`;
+  if (isTTY2) {
+    p3.outro(msg);
+  } else {
+    console.log("\n" + msg + "\n");
+  }
+}
+
+// src/cli.ts
+var isTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+function log(msg) {
+  console.log(msg);
+}
+async function run() {
+  const program = new Command().name("create-pila-app").description("Scaffold a Pila portal frontend project").version("0.1.0").argument("[project-name]", "Name of the project").option("--framework <framework>", "nextjs or vite").option("--pm <pm>", "Package manager: npm, yarn, pnpm, bun, or deno").option("--features <features>", "Comma-separated: editor,charts,dnd,sentry").option("--auth <auth>", "jwt, oauth, or none").option("--no-install", "Skip dependency installation").option("--no-git", "Skip git initialization").parse(process.argv);
+  log("");
+  if (isTTY) {
+    p4.intro(pc3.bgCyan(pc3.black(" create-pila-app ")));
+  } else {
+    log(pc3.bgCyan(pc3.black(" create-pila-app ")));
+  }
+  const args = program.args;
+  const opts = program.opts();
+  const options = await collectOptions({
+    projectName: args[0],
+    framework: opts.framework,
+    pm: opts.pm,
+    features: opts.features?.split(","),
+    auth: opts.auth
+  }, isTTY);
+  if (!opts.install) {
+    options.install = false;
+  }
+  const destDir = path5.resolve(process.cwd(), options.projectName);
+  if (await fse4.pathExists(destDir)) {
+    const files = await fse4.readdir(destDir);
+    if (files.length > 0) {
+      const msg = `Directory "${options.projectName}" already exists and is not empty.`;
+      if (isTTY) p4.cancel(msg);
+      else log(pc3.red("\u2716 " + msg));
+      process.exit(1);
+    }
+  }
+  await fse4.ensureDir(destDir);
+  log(pc3.cyan("\u2192 Scaffolding project..."));
+  if (isTTY) {
+    const scaffoldSpinner = p4.spinner();
+    scaffoldSpinner.start("Scaffolding project...");
+    try {
+      await scaffold(options, destDir);
+      scaffoldSpinner.stop("Project scaffolded");
+    } catch (err) {
+      scaffoldSpinner.stop("Scaffolding failed");
+      throw err;
+    }
+  } else {
+    await scaffold(options, destDir);
+    log(pc3.green("\u2713 Project scaffolded"));
+  }
+  if (options.install) {
+    await install(destDir, options.packageManager);
+  }
+  if (opts.git !== false) {
+    try {
+      await initGit(destDir);
+    } catch {
+    }
+  }
+  printSuccess(options, destDir, isTTY);
+}
+
+// src/index.ts
+(async () => {
+  await run();
+})();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "doo-boilerplate",
+  "version": "0.1.0",
+  "description": "CLI to scaffold Pila portal frontend projects",
+  "type": "module",
+  "bin": { "create-pila-app": "./dist/index.js" },
+  "main": "./dist/index.js",
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "copy-templates": "node scripts/copy-templates.mjs",
+    "prepublishOnly": "node scripts/copy-templates.mjs && tsup"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "commander": "^13.0.0",
+    "execa": "^9.5.2",
+    "fs-extra": "^11.2.0",
+    "picocolors": "^1.1.1",
+    "validate-npm-package-name": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/template-nextjs/Dockerfile

@@ -0,0 +1,29 @@
+# Stage 1: Dependencies
+FROM node:22-alpine AS deps
+RUN corepack enable && corepack prepare pnpm@latest --activate
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# Stage 2: Builder
+FROM node:22-alpine AS builder
+RUN corepack enable && corepack prepare pnpm@latest --activate
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ARG NEXT_PUBLIC_API_URL
+ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
+RUN pnpm build
+
+# Stage 3: Runner
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000 HOSTNAME="0.0.0.0"
+CMD ["node", "server.js"]

package/templates/template-nextjs/README.md

@@ -0,0 +1,215 @@
+# {{PROJECT_NAME}}
+
+> Next.js 16 server-side rendered portal frontend
+
+Production-ready Next.js 16 application with App Router, i18n, dark mode, authentication, and DevOps integration.
+
+## Quick Start
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Available Scripts
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm dev` | Start dev server with Turbopack |
+| `pnpm build` | Build for production |
+| `pnpm start` | Run production server |
+| `pnpm lint` | Run ESLint |
+| `pnpm lint:fix` | Fix linting issues |
+| `pnpm type-check` | TypeScript type checking |
+| `pnpm format` | Format code with Prettier |
+| `pnpm format:check` | Check formatting without changes |
+| `pnpm knip` | Find unused files/exports |
+| `pnpm gen:api` | Generate types from Swagger spec |
+| `pnpm gen:api:watch` | Watch mode for API generation |
+| `pnpm docker:build` | Build & scan Docker image |
+| `pnpm docker:scan` | Security scan image with Trivy |
+
+## Tech Stack
+
+- **Framework:** Next.js 16 with App Router
+- **Styling:** Tailwind CSS 4 + Shadcn/ui
+- **i18n:** next-intl (EN/VI built-in)
+- **State:** Zustand 5 (global) + TanStack Query 5 (server)
+- **Forms:** React Hook Form + Zod
+- **HTTP:** Axios with JWT interceptors
+- **Auth:** JWT store with refresh token persistence
+- **DevOps:** Docker (multi-stage) + Trivy security scan
+
+## Environment Variables
+
+Copy `.env.example` to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+Key variables:
+
+```env
+# API Configuration
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_API_AUTH_URL=http://localhost:8001
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_NAME={{PROJECT_NAME}}
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── (auth)/              # Auth layout group (login, register)
+│   ├── (dashboard)/         # Protected layout group
+│   ├── layout.tsx           # Root layout
+│   └── page.tsx             # Homepage
+├── components/
+│   ├── ui/                  # Shadcn/ui components
+│   └── **/                  # Feature-specific components
+├── features/
+│   ├── auth/
+│   │   ├── hooks/
+│   │   ├── stores/          # Zustand auth store
+│   │   ├── services/
+│   │   │   └── gen/         # Generated API types (gen:api)
+│   │   └── types/
+│   └── **/
+├── hooks/                   # Custom React hooks
+├── i18n/
+│   ├── request.ts           # Server-side i18n setup
+│   ├── routing.ts           # Route configuration
+│   └── translations/        # Message files
+├── lib/
+│   ├── cn.ts                # Tailwind merge utility
+│   ├── http.ts              # Axios instance
+│   └── **/
+├── middleware.ts            # next-intl middleware
+├── providers/
+│   ├── ClientProvider.tsx    # Client-side providers
+│   └── ThemeProvider.tsx     # next-themes setup
+├── stores/                  # Zustand stores
+├── styles/
+│   ├── globals.css
+│   └── variables.css        # CSS variables
+└── types/
+    └── index.ts
+```
+
+## API Code Generation
+
+Generate TypeScript types from backend Swagger spec:
+
+```bash
+# Place spec at docs/swagger/api.json
+curl https://api.example.com/swagger.json > docs/swagger/api.json
+
+# Generate types
+pnpm gen:api
+
+# Watch mode during API development
+pnpm gen:api:watch
+```
+
+Generated types appear in `src/features/auth/services/gen/`.
+
+## Docker Deployment
+
+### Build & Scan
+
+```bash
+pnpm docker:build
+```
+
+Builds optimized multi-stage image and scans for vulnerabilities with Trivy.
+
+### Local Development
+
+```bash
+docker-compose up
+# App runs on http://localhost:3000
+```
+
+Environment variables read from `.env` file.
+
+### Production Build
+
+```bash
+docker build -t my-app:latest \
+  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com .
+
+docker run -p 3000:3000 \
+  -e NEXT_PUBLIC_API_URL=https://api.example.com \
+  my-app:latest
+```
+
+## Next.js App Router Basics
+
+### Routing
+
+Routes defined by file structure in `src/app/`:
+
+```
+app/
+├── page.tsx           → /
+├── about/
+│   └── page.tsx       → /about
+└── (auth)/
+    ├── login/
+    │   └── page.tsx   → /login
+    └── register/
+        └── page.tsx   → /register
+```
+
+Parentheses `(auth)` create layout groups without affecting URL.
+
+### Server & Client Components
+
+By default, all components are **Server Components** (run on server):
+
+```typescript
+// src/app/page.tsx (Server Component)
+export default function Home() {
+  return <h1>SSR rendered on server</h1>
+}
+```
+
+For client-side logic, add `'use client'`:
+
+```typescript
+// src/components/Counter.tsx (Client Component)
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+### Layouts
+
+Create shared layouts for route groups:
+
+```typescript
+// src/app/(dashboard)/layout.tsx
+export default function DashboardLayout({ children }) {
+  return (
+    <div>
+      <nav>Sidebar</nav>
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+---
+
+**Learn more:** [Next.js Docs](https://nextjs.org/docs)

package/templates/template-nextjs/_env.example

@@ -0,0 +1,7 @@
+# API Configuration
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_API_AUTH_URL=http://localhost:8001
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_NAME={{PROJECT_NAME}}

package/templates/template-nextjs/_gitignore

@@ -0,0 +1,8 @@
+.env
+.env.local
+.env.production
+node_modules
+.next
+dist
+*.log
+.turbo

package/templates/template-nextjs/_prettierignore

@@ -0,0 +1,4 @@
+node_modules
+.next
+dist
+src/features/*/services/gen

package/templates/template-nextjs/_prettierrc

@@ -0,0 +1,12 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "endOfLine": "lf",
+  "plugins": ["@trivago/prettier-plugin-sort-imports", "prettier-plugin-tailwindcss"],
+  "importOrder": ["^(react|next)(.*)", "^@/", "^\\."],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true
+}