create-forgeon 0.0.1

package/README.md

@@ -0,0 +1,11 @@
+# create-forgeon
+
+CLI package for generating Forgeon fullstack monorepo projects.
+
+## Usage
+
+```bash
+npx create-forgeon@latest my-app --frontend react --db prisma --i18n true --docker true
+```
+
+If flags are omitted, the CLI asks interactive questions.

package/bin/create-forgeon.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stdin as input, stdout as output } from 'node:process';
+
+const SUPPORTED_FRONTENDS = ['react', 'angular'];
+const SUPPORTED_DBS = ['prisma'];
+
+function printHelp() {
+  console.log(`create-forgeon
+
+Usage:
+  npx create-forgeon@latest <project-name> [options]
+
+Options:
+  --frontend <react|angular>   Frontend preset (default: react)
+  --db <prisma>                DB preset (default: prisma)
+  --i18n <true|false>          Enable i18n (default: true)
+  --docker <true|false>        Include docker/infra files (default: true)
+  --install                    Run pnpm install after generation
+  -y, --yes                    Skip prompts and use defaults
+  -h, --help                   Show this help
+`);
+}
+
+function parseBoolean(value, fallback) {
+  if (value === undefined) return fallback;
+  if (typeof value === 'boolean') return value;
+
+  const normalized = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'y'].includes(normalized)) return true;
+  if (['false', '0', 'no', 'n'].includes(normalized)) return false;
+
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+
+function toKebabCase(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'forgeon-app';
+}
+
+function copyRecursive(source, destination) {
+  const stat = fs.statSync(source);
+
+  if (stat.isDirectory()) {
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source)) {
+      copyRecursive(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+
+  fs.copyFileSync(source, destination);
+}
+
+function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const options = {
+    name: undefined,
+    frontend: undefined,
+    db: undefined,
+    i18n: undefined,
+    docker: undefined,
+    install: false,
+    yes: false,
+    help: false,
+  };
+
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--') {
+      continue;
+    }
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '-y' || arg === '--yes') {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === '--install') {
+      options.install = true;
+      continue;
+    }
+
+    if (arg.startsWith('--no-')) {
+      const key = arg.slice(5);
+      if (key === 'install') options.install = false;
+      if (key === 'docker') options.docker = false;
+      if (key === 'i18n') options.i18n = false;
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      const [keyRaw, inlineValue] = arg.split('=');
+      const key = keyRaw.slice(2);
+
+      let value = inlineValue;
+      if (value === undefined && args[i + 1] && !args[i + 1].startsWith('-')) {
+        value = args[i + 1];
+        i += 1;
+      }
+
+      if (key in options) {
+        options[key] = value;
+      }
+
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (!options.name && positional.length > 0) {
+    options.name = positional[0];
+  }
+
+  const rl = readline.createInterface({ input, output });
+
+  if (!options.name) {
+    options.name = await rl.question('Project name: ');
+  }
+
+  if (!options.yes && !options.frontend) {
+    options.frontend =
+      (await rl.question('Frontend (react/angular) [react]: ')) || 'react';
+  }
+
+  if (!options.yes && !options.db) {
+    options.db = (await rl.question('DB preset [prisma]: ')) || 'prisma';
+  }
+
+  if (!options.yes && options.i18n === undefined) {
+    options.i18n = (await rl.question('Enable i18n (true/false) [true]: ')) || 'true';
+  }
+
+  if (!options.yes && options.docker === undefined) {
+    options.docker =
+      (await rl.question('Include Docker/infra (true/false) [true]: ')) || 'true';
+  }
+
+  await rl.close();
+
+  if (!options.name || options.name.trim().length === 0) {
+    console.error('Project name is required.');
+    process.exit(1);
+  }
+
+  const frontendRaw = (options.frontend ?? 'react').toString().toLowerCase();
+  const dbRaw = (options.db ?? 'prisma').toString().toLowerCase();
+  const i18nEnabled = parseBoolean(options.i18n, true);
+  const dockerEnabled = parseBoolean(options.docker, true);
+
+  const frontend = SUPPORTED_FRONTENDS.includes(frontendRaw) ? frontendRaw : 'react';
+  if (frontendRaw !== frontend) {
+    console.warn(`Unsupported frontend "${frontendRaw}". Falling back to "react".`);
+  }
+  if (frontend === 'angular') {
+    console.warn('Angular preset is planned, but not implemented yet. Falling back to React.');
+  }
+
+  const db = SUPPORTED_DBS.includes(dbRaw) ? dbRaw : 'prisma';
+  if (dbRaw !== db) {
+    console.warn(`Unsupported db preset "${dbRaw}". Falling back to "prisma".`);
+  }
+
+  const projectName = options.name.trim();
+  const targetRoot = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetRoot)) {
+    console.error(`Target directory already exists: ${targetRoot}`);
+    process.exit(1);
+  }
+
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const templateRoot = path.resolve(scriptDir, '..', 'templates', 'base');
+
+  copyRecursive(templateRoot, targetRoot);
+
+  const rootPackageJsonPath = path.join(targetRoot, 'package.json');
+  const rootPackageJson = JSON.parse(fs.readFileSync(rootPackageJsonPath, 'utf8'));
+  rootPackageJson.name = toKebabCase(projectName);
+
+  if (rootPackageJson.scripts) {
+    delete rootPackageJson.scripts['create:forgeon'];
+
+    if (!dockerEnabled) {
+      delete rootPackageJson.scripts['docker:up'];
+      delete rootPackageJson.scripts['docker:down'];
+    }
+  }
+
+  writeJson(rootPackageJsonPath, rootPackageJson);
+
+  if (!dockerEnabled) {
+    fs.rmSync(path.join(targetRoot, 'infra'), { recursive: true, force: true });
+  } else {
+    const envExamplePath = path.join(targetRoot, 'infra', 'docker', '.env.example');
+    if (fs.existsSync(envExamplePath)) {
+      const current = fs.readFileSync(envExamplePath, 'utf8');
+      const next = current
+        .replace(/I18N_ENABLED=.*/g, `I18N_ENABLED=${i18nEnabled}`)
+        .replace(/I18N_DEFAULT_LANG=.*/g, 'I18N_DEFAULT_LANG=en')
+        .replace(/I18N_FALLBACK_LANG=.*/g, 'I18N_FALLBACK_LANG=en');
+      fs.writeFileSync(envExamplePath, next, 'utf8');
+    }
+  }
+
+  const apiEnvExamplePath = path.join(targetRoot, 'apps', 'api', '.env.example');
+  const apiEnv = [
+    'PORT=3000',
+    'DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app?schema=public',
+    `I18N_ENABLED=${i18nEnabled}`,
+    'I18N_DEFAULT_LANG=en',
+    'I18N_FALLBACK_LANG=en',
+  ].join('\n');
+  fs.writeFileSync(apiEnvExamplePath, `${apiEnv}\n`, 'utf8');
+
+  if (parseBoolean(options.install, false)) {
+    const pnpmCmd = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+    const result = spawnSync(pnpmCmd, ['install'], {
+      cwd: targetRoot,
+      stdio: 'inherit',
+      shell: false,
+    });
+
+    if (result.status !== 0) {
+      process.exit(result.status ?? 1);
+    }
+  }
+
+  console.log('Forgeon scaffold generated.');
+  console.log(`- path: ${targetRoot}`);
+  console.log(`- frontend: ${frontend}`);
+  console.log(`- db: ${db}`);
+  console.log(`- i18n: ${i18nEnabled}`);
+  console.log(`- docker: ${dockerEnabled}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "create-forgeon",
+  "version": "0.0.1",
+  "description": "Forgeon project generator CLI",
+  "license": "MIT",
+  "author": "Forgeon",
+  "type": "module",
+  "bin": {
+    "create-forgeon": "bin/create-forgeon.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ]
+}

package/templates/base/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*.{ts,tsx,js,mjs,cjs,json,md,yml,yaml,css,html,prisma,sql,conf}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

package/templates/base/README.md

@@ -0,0 +1,56 @@
+# Forgeon Fullstack Scaffold
+
+Canonical monorepo scaffold for NestJS + frontend with shared packages, built-in docs, optional i18n (enabled by default), and default DB stack Prisma + Postgres.
+
+## Quick Start (Dev)
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+2. Start local Postgres (Docker):
+   ```bash
+   docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up db -d
+   ```
+3. Run API + web in dev mode:
+   ```bash
+   pnpm dev
+   ```
+4. Open:
+   - Web: `http://localhost:5173`
+   - API health: `http://localhost:3000/api/health`
+
+## Quick Start (Docker)
+
+```bash
+docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
+```
+
+Open `http://localhost:8080`.
+
+## i18n Toggle
+
+Set in env:
+- `I18N_ENABLED=true|false`
+- `I18N_DEFAULT_LANG=en`
+- `I18N_FALLBACK_LANG=en`
+
+When `I18N_ENABLED=false`, API runs without loading i18n module.
+
+## Prisma In Docker Start
+
+API container starts with:
+1. `prisma migrate deploy`
+2. `node apps/api/dist/main.js`
+
+This keeps container startup production-like while still simple.
+
+## Generator Command
+
+Use:
+```bash
+pnpm create:forgeon -- --name my-app --frontend react --db prisma --i18n true
+```
+
+If flags are omitted, script asks questions interactively.
+

package/templates/base/apps/api/Dockerfile

@@ -0,0 +1,23 @@
+FROM node:20-alpine
+
+WORKDIR /app
+RUN corepack enable
+
+COPY package.json pnpm-workspace.yaml tsconfig.base.json ./
+COPY apps/api/package.json apps/api/package.json
+COPY packages/core/package.json packages/core/package.json
+COPY packages/i18n/package.json packages/i18n/package.json
+
+RUN pnpm install --frozen-lockfile=false
+
+COPY apps/api apps/api
+COPY packages/core packages/core
+COPY packages/i18n packages/i18n
+COPY resources resources
+
+RUN pnpm --filter @forgeon/i18n build
+RUN pnpm --filter @forgeon/api prisma:generate
+RUN pnpm --filter @forgeon/api build
+
+EXPOSE 3000
+CMD ["sh", "-c", "pnpm --filter @forgeon/api prisma:migrate:deploy && node apps/api/dist/main.js"]

package/templates/base/apps/api/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@forgeon/api",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "predev": "pnpm --filter @forgeon/i18n build",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "ts-node --transpile-only src/main.ts",
+    "start": "node dist/main.js",
+    "prisma:generate": "prisma generate --schema prisma/schema.prisma",
+    "prisma:migrate:dev": "prisma migrate dev --schema prisma/schema.prisma",
+    "prisma:migrate:deploy": "prisma migrate deploy --schema prisma/schema.prisma",
+    "prisma:studio": "prisma studio --schema prisma/schema.prisma",
+    "prisma:seed": "ts-node --transpile-only prisma/seed.ts"
+  },
+  "dependencies": {
+    "@forgeon/i18n": "workspace:*",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "@prisma/client": "^6.18.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "nestjs-i18n": "^10.5.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.7",
+    "prisma": "^6.18.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3"
+  },
+  "prisma": {
+    "seed": "ts-node --transpile-only prisma/seed.ts"
+  }
+}
+

package/templates/base/apps/api/prisma/migrations/0001_init/migration.sql

@@ -0,0 +1,12 @@
+-- CreateTable
+CREATE TABLE "User" (
+    "id" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

package/templates/base/apps/api/prisma/migrations/migration_lock.toml

@@ -0,0 +1 @@
+provider = "postgresql"

package/templates/base/apps/api/prisma/schema.prisma

@@ -0,0 +1,15 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}

package/templates/base/apps/api/prisma/seed.ts

@@ -0,0 +1,20 @@
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  await prisma.user.upsert({
+    where: { email: 'seed@example.com' },
+    update: {},
+    create: { email: 'seed@example.com' },
+  });
+}
+
+main()
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });

package/templates/base/apps/api/src/app.module.ts

@@ -0,0 +1,34 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ForgeonI18nModule } from '@forgeon/i18n';
+import { join } from 'path';
+import appConfig from './config/app.config';
+import { HealthController } from './health/health.controller';
+import { PrismaModule } from './prisma/prisma.module';
+import { AppExceptionFilter } from './common/filters/app-exception.filter';
+
+const i18nEnabled = (process.env.I18N_ENABLED ?? 'true').toLowerCase() !== 'false';
+const i18nDefaultLang = process.env.I18N_DEFAULT_LANG ?? 'en';
+const i18nFallbackLang = process.env.I18N_FALLBACK_LANG ?? 'en';
+const i18nPath = join(__dirname, '..', '..', '..', 'resources', 'i18n');
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      load: [appConfig],
+      envFilePath: '.env',
+    }),
+    ForgeonI18nModule.register({
+      enabled: i18nEnabled,
+      defaultLang: i18nDefaultLang,
+      fallbackLang: i18nFallbackLang,
+      path: i18nPath,
+    }),
+    PrismaModule,
+  ],
+  controllers: [HealthController],
+  providers: [AppExceptionFilter],
+})
+export class AppModule {}
+

package/templates/base/apps/api/src/common/dto/echo-query.dto.ts

@@ -0,0 +1,6 @@
+import { IsNotEmpty } from 'class-validator';
+
+export class EchoQueryDto {
+  @IsNotEmpty({ message: 'validation.required' })
+  value!: string;
+}

package/templates/base/apps/api/src/common/filters/app-exception.filter.ts

@@ -0,0 +1,130 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Injectable,
+  Optional,
+} from '@nestjs/common';
+import { I18nService } from 'nestjs-i18n';
+import { Request, Response } from 'express';
+
+@Injectable()
+@Catch()
+export class AppExceptionFilter implements ExceptionFilter {
+  constructor(@Optional() private readonly i18n?: I18nService) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const context = host.switchToHttp();
+    const response = context.getResponse<Response>();
+    const request = context.getRequest<Request>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const payload =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : { message: 'Internal server error' };
+
+    const code = this.resolveCode(status);
+    const message = this.resolveMessage(payload, status, request);
+    const details = this.resolveDetails(payload);
+
+    response.status(status).json({
+      error: {
+        code,
+        message,
+        ...(details !== undefined ? { details } : {}),
+      },
+    });
+  }
+
+  private resolveCode(status: number): string {
+    switch (status) {
+      case HttpStatus.BAD_REQUEST:
+        return 'validation_error';
+      case HttpStatus.UNAUTHORIZED:
+        return 'unauthorized';
+      case HttpStatus.FORBIDDEN:
+        return 'forbidden';
+      case HttpStatus.NOT_FOUND:
+        return 'not_found';
+      case HttpStatus.CONFLICT:
+        return 'conflict';
+      default:
+        return 'internal_error';
+    }
+  }
+
+  private resolveMessage(
+    payload: unknown,
+    status: number,
+    request: Request,
+  ): string {
+    const lang = this.resolveLang(request);
+
+    if (status === HttpStatus.NOT_FOUND) {
+      return this.translate('errors.notFound', lang);
+    }
+
+    if (typeof payload === 'string') {
+      return this.translate(payload, lang);
+    }
+
+    if (typeof payload === 'object' && payload !== null) {
+      const obj = payload as { message?: string | string[] };
+      if (Array.isArray(obj.message) && obj.message.length > 0) {
+        return this.translate(obj.message[0], lang);
+      }
+      if (typeof obj.message === 'string') {
+        return this.translate(obj.message, lang);
+      }
+    }
+
+    return 'Internal server error';
+  }
+
+  private resolveDetails(payload: unknown): unknown {
+    if (typeof payload !== 'object' || payload === null) {
+      return undefined;
+    }
+
+    const obj = payload as { message?: string | string[]; error?: string };
+    if (Array.isArray(obj.message) && obj.message.length > 1) {
+      return obj.message;
+    }
+
+    return undefined;
+  }
+
+  private resolveLang(request: Request): string | undefined {
+    const queryLang = request.query?.lang;
+    if (typeof queryLang === 'string' && queryLang.length > 0) {
+      return queryLang;
+    }
+
+    const header = request.headers['accept-language'];
+    if (typeof header === 'string' && header.length > 0) {
+      return header.split(',')[0].trim();
+    }
+
+    return undefined;
+  }
+
+  private translate(keyOrMessage: string, lang?: string): string {
+    if (!this.i18n) {
+      return keyOrMessage;
+    }
+
+    const translated = this.i18n.t(keyOrMessage, {
+      lang,
+      defaultValue: keyOrMessage,
+    });
+
+    return typeof translated === 'string' ? translated : keyOrMessage;
+  }
+}

package/templates/base/apps/api/src/config/app.config.ts

@@ -0,0 +1,13 @@
+import { registerAs } from '@nestjs/config';
+
+const toBoolean = (value: string | undefined, defaultValue: boolean): boolean => {
+  if (value === undefined) return defaultValue;
+  return value.toLowerCase() === 'true';
+};
+
+export default registerAs('app', () => ({
+  port: Number(process.env.PORT ?? 3000),
+  i18nEnabled: toBoolean(process.env.I18N_ENABLED, true),
+  i18nDefaultLang: process.env.I18N_DEFAULT_LANG ?? 'en',
+  i18nFallbackLang: process.env.I18N_FALLBACK_LANG ?? 'en',
+}));