create-forgeon 0.3.15 → 0.3.17

package/templates/base/docs/AI/ROADMAP.md

@@ -1,171 +0,0 @@
-# ROADMAP
-
-This is a living plan. Scope and priorities may change.
-
-## Current Foundation (Implemented)
-
-- [x] Canonical scaffold: NestJS API + React web + Docker (+ default-on `db-prisma` module)
-- [x] Proxy preset selection: `caddy | nginx | none`
-- [x] `@forgeon/core`:
-  - [x] `core-config` (typed env config + validation)
-  - [x] `core-errors` (global envelope + exception filter)
-  - [x] `core-validation` (global validation pipe)
-- [x] `@forgeon/db-prisma` as default-applied DB module
-- [x] i18n add-module baseline:
-  - [x] `@forgeon/i18n`, `@forgeon/i18n-contracts`, `@forgeon/i18n-web`
-  - [x] shared dictionaries in `resources/i18n/*`
-  - [x] tooling: `i18n:sync`, `i18n:check`, `i18n:types`, `i18n:add`
-- [x] module diagnostics probes pattern (`/api/health/*` + web test buttons)
-
-## Standards (Accepted)
-
-- [x] `*-contracts` and `*-web` packages are ESM-first
-- [x] API runtime modules use Node-oriented TS config
-- [x] no cross-package imports via `/src/*`; only package entrypoints
-
-## Updated Priority Backlog
-
-### P0 (Immediate Must-Have)
-
-- [ ] `logger`
-  - [ ] canonical logger module
-  - [ ] requestId / correlationId propagation
-  - [ ] structured log conventions
-
-- [ ] `openapi / swagger`
-  - [ ] env toggle: `SWAGGER_ENABLED`
-  - [ ] standard setup
-  - [ ] bearer integration hook for jwt-auth
-  - [ ] `/docs` route
-
-- [ ] `jwt-auth`
-  - [ ] module split: contracts/api/web
-  - [ ] access + refresh baseline
-  - [ ] guards/strategy integration
-
-- [ ] `rbac / permissions`
-  - [ ] decorators: `@Roles()`, `@Permissions()`
-  - [ ] guard + policy helper
-  - [ ] contracts: `Role`, `Permission`
-  - [ ] integration with jwt-auth claims
-
-- [ ] `redis/queue foundation`
-  - [ ] base Redis config/service
-  - [ ] queue baseline (BullMQ or equivalent)
-  - [ ] retry and dead-letter conventions
-
-- [ ] `rate-limit`
-  - [ ] Nest Throttler add-module
-  - [ ] policies: route / user / ip
-  - [ ] error code: `TOO_MANY_REQUESTS`
-  - [ ] reverse-proxy-aware mode (`trust proxy`)
-
-- [ ] `files` (upload + storage)
-  - [ ] upload endpoints + DTO + guards
-  - [ ] storage presets: local + S3-compatible (MinIO/R2)
-  - [ ] MIME/size validation
-  - [ ] optional image processing subpackage (`sharp`)
-  - [ ] error codes: `UPLOAD_INVALID_TYPE`, `UPLOAD_TOO_LARGE`, `UPLOAD_QUOTA`
-
-### P1 (Strongly Recommended)
-
-- [ ] `testing baseline`
-  - [ ] unit + e2e presets
-  - [ ] test helpers for add-modules
-  - [ ] smoke test template for generated project
-
-- [ ] `CI quality gates`
-  - [ ] `typecheck`, `lint`, `test`, docker build smoke
-  - [ ] release gate checklist
-
-- [ ] `cache` (Redis)
-  - [ ] CacheModule preset
-  - [ ] key naming conventions
-  - [ ] shared wrapper/service
-
-- [ ] `scheduler`
-  - [ ] `@nestjs/schedule` integration
-  - [ ] task template
-  - [ ] optional distributed lock (Redis)
-
-- [ ] `mail`
-  - [ ] at least one provider preset (SMTP/Resend/SendGrid)
-  - [ ] templates: verify email, reset password
-  - [ ] optional outbox with queue
-
-- [ ] workspace `eslint/prettier` config package
-
-### P2 (Later)
-
-- [ ] frontend `http-client` module
-- [ ] frontend UI kit package
-  - [ ] migrate reusable parts from `eso-dt` (when available)
-  - [ ] extend missing primitives
-- [ ] `realtime` (ws)
-  - [ ] gateway baseline
-  - [ ] jwt auth for ws
-  - [ ] rooms + basic events
-- [ ] `webhooks` module (subject to scope validation)
-  - [ ] signed inbound verify (HMAC)
-  - [ ] signed outbound sender
-  - [ ] replay protection (timestamp/nonce)
-
-## Execution Plan (3 Sprints)
-
-### Sprint 1: Platform Baseline and Security Start
-
-Scope:
-- `logger`
-- `openapi/swagger`
-- `jwt-auth`
-- `testing baseline`
-- `CI quality gates`
-
-Definition of Done:
-- add-modules install cleanly via `create-forgeon add <module>`
-- local dev (`pnpm dev`) and docker build both pass on fresh generated project
-- each module has probe endpoint and web probe UI hook when applicable
-- docs updated in both root and template docs
-
-### Sprint 2: Authorization and Traffic Control
-
-Scope:
-- `rbac/permissions`
-- `redis/queue foundation`
-- `rate-limit`
-- `files`
-- `cache`
-
-Definition of Done:
-- claims/roles/permissions flow validated end-to-end (api + web contracts)
-- rate-limit and files include standardized error codes and envelope mapping
-- Redis-backed modules run in docker profile with documented env keys
-- at least one e2e happy-path per module
-
-### Sprint 3: Async Integrations and Frontend Foundation
-
-Scope:
-- `scheduler`
-- `mail`
-- workspace `eslint/prettier` config package
-- frontend `http-client`
-
-Definition of Done:
-- queue/scheduler/mail basic scenarios work in local + docker
-- frontend http-client consumes api contracts with typed errors
-- lint/typecheck/test/build pass through CI gate preset
-- docs include migration notes and extension points
-
-## Explicit Dependencies and Order Constraints
-
-- `rbac` depends on `jwt-auth`
-- `rate-limit` should follow Redis/queue foundation for scalable mode
-- `mail` should reuse queue foundation where possible
-- `openapi` is most useful before/with `jwt-auth` and `http-client`
-- `realtime` and `webhooks` stay post-MVP unless a concrete use-case appears
-
-## i18n Policy For Add-Modules
-
-- [ ] each add-module that introduces user-facing text defines its own namespace templates
-- [ ] if i18n is already enabled, namespace files are added during module installation
-- [ ] if module is installed first and i18n later, namespaces are merged during i18n installation

package/templates/base/docs/AI/TASKS.md

@@ -1,60 +0,0 @@
-# TASKS
-
-## Feature Discovery Matrix
-
-```text
-Scan this monorepo and build a backend feature matrix by app/package.
-Use only evidence from code and dependencies.
-Output:
-1) taxonomy by category
-2) feature comparison table
-3) common core
-4) unique features
-5) architectural inconsistencies
-Include file references for every feature.
-```
-
-## Add Module Package
-
-```text
-Create a new reusable package under packages/ for <feature-name>.
-Requirements:
-- minimal API
-- NestJS-compatible module
-- docs in package README
-- wire into apps/api conditionally via env flag
-- keep backward compatibility
-```
-
-## Refactor Core
-
-```text
-Move shared backend logic from apps/api into packages/core.
-Do not change behavior.
-Update imports, package dependencies, and docs.
-Run build checks and show changed files.
-```
-
-## Generate Preset
-
-```text
-Create or update create-forgeon preset flow:
-- keep canonical stack fixed: NestJS + React + Prisma/Postgres + Docker
-- allow only runtime proxy choice: caddy/nginx/none
-- update generated docs fragments
-- update docs/AI/ARCHITECTURE.md and docs/AI/MODULE_SPEC.md when scope changes
-```
-
-## Add Fullstack Module
-
-```text
-Implement `create-forgeon add <module-id>` for a fullstack feature.
-Requirements:
-- split module into contracts/api/web packages
-- contracts is source of truth for routes, DTOs, errors
-- if feasible, add module probe hooks in API (`/api/health/*`) and web diagnostics UI
-- if i18n is enabled, add module namespace files and wire them for both API and web
-- add docs note under docs/AI/MODULES/<module-id>.md
-- keep backward compatibility
-```
-

package/templates/base/docs/AI/VALIDATION.md

@@ -1,31 +0,0 @@
-# VALIDATION
-
-## Backend DTO Validation Standard
-
-- Use `class-validator` decorators on DTO classes.
-- Global validation is centralized in `@forgeon/core` via `createValidationPipe()`.
-- Current defaults:
-  - `whitelist: true`
-  - `transform: true`
-  - `validationError.target: false`
-  - `validationError.value: false`
-- Keep DTO validation messages stable and explicit.
-- For required values, use a consistent key or message pattern.
-
-## Config Validation Standard
-
-- Use Zod for env/config validation.
-- Core env is validated by `@forgeon/core` (`core-config`).
-- Each add-module validates only its own env keys with its own Zod schema.
-- Avoid one global env schema for all modules; keep schemas modular.
-
-## Error Details for Validation
-
-- Error envelope stays consistent:
-  - `error.code`
-  - `error.message`
-  - `error.status`
-  - optional `error.details`
-- Validation details should be structured (not `any`).
-- `core-validation` formats validation details as:
-  - `{ field?: string, message: string }[]`

package/templates/base/docs/README.md

@@ -1,18 +0,0 @@
-# Documentation Index
-
-- `AI/PROJECT.md` - project overview and run modes
-- `AI/ARCHITECTURE.md` - monorepo design and extension model
-- `AI/ROADMAP.md` - implementation roadmap and feature priorities
-- `AI/MODULE_SPEC.md` - fullstack module contract (`contracts/api/web`)
-- `AI/MODULE_CHECKS.md` - required runtime probe hooks for modules
-- `AI/VALIDATION.md` - DTO/env validation standards
-- `AI/TASKS.md` - ready-to-use Codex prompts
-
-## i18n Language Workflow
-
-Add a new language from existing namespaces:
-- `pnpm i18n:add uk`
-
-Useful follow-up commands:
-- `pnpm i18n:sync`
-- `pnpm i18n:check`

package/templates/module-fragments/jwt-auth/20_scope.md

@@ -1,19 +0,0 @@
-## Scope
-
-Implemented scope:
-
-1. Split into reusable packages:
-   - `@forgeon/auth-contracts`
-   - `@forgeon/auth-api`
-2. API runtime:
-   - JWT login/refresh/logout/me endpoints
-   - `JwtStrategy` + `JwtAuthGuard`
-   - `authConfig` + `authEnvSchema` wiring through root `ConfigModule` validator chain
-3. DB behavior:
-   - module install stays stateless by default
-   - refresh token hash persistence is enabled later through the `db-adapter` capability via `pnpm forgeon:sync-integrations`
-   - current DB adapter implementation for this integration is `db-prisma`
-   - if no DB adapter is installed, the module stays stateless and prints an optional integration warning with follow-up commands
-4. Module checks:
-   - API probe endpoint: `GET /api/health/auth`
-   - default web probe button + result block

package/templates/module-fragments/jwt-auth/90_status_implemented.md

@@ -1,8 +0,0 @@
-## Current State
-
-Status: implemented.
-
-Notes:
-- The persistence boundary is `db-adapter`, not a hard dependency on one concrete DB module.
-- The current DB adapter implementation for auth persistence is `db-prisma`.
-- If no DB adapter is installed, jwt-auth stays in stateless refresh mode and surfaces an optional integration warning.

package/templates/module-fragments/jwt-auth/90_status_planned.md

@@ -1,3 +0,0 @@
-## Current State
-
-This module is registered but not implemented yet.

package/templates/module-presets/jwt-auth/apps/api/prisma/migrations/0002_auth_refresh_token_hash/migration.sql

@@ -1,3 +0,0 @@
--- AlterTable
-ALTER TABLE "User"
-ADD COLUMN "refreshTokenHash" TEXT;

package/templates/module-presets/jwt-auth/apps/api/src/auth/prisma-auth-refresh-token.store.ts

@@ -1,36 +0,0 @@
-import {
-  AuthRefreshTokenStore,
-} from '@forgeon/auth-api';
-import { PrismaService } from '@forgeon/db-prisma';
-import { Injectable } from '@nestjs/common';
-
-@Injectable()
-export class PrismaAuthRefreshTokenStore implements AuthRefreshTokenStore {
-  readonly kind = 'prisma';
-
-  constructor(private readonly prisma: PrismaService) {}
-
-  async saveRefreshTokenHash(subject: string, hash: string): Promise<void> {
-    await this.prisma.user.upsert({
-      where: { email: subject },
-      create: { email: subject, refreshTokenHash: hash },
-      update: { refreshTokenHash: hash },
-      select: { id: true },
-    });
-  }
-
-  async getRefreshTokenHash(subject: string): Promise<string | null> {
-    const user = await this.prisma.user.findUnique({
-      where: { email: subject },
-      select: { refreshTokenHash: true },
-    });
-    return user?.refreshTokenHash ?? null;
-  }
-
-  async removeRefreshTokenHash(subject: string): Promise<void> {
-    await this.prisma.user.updateMany({
-      where: { email: subject },
-      data: { refreshTokenHash: null },
-    });
-  }
-}

package/templates/module-presets/jwt-auth/packages/auth-api/src/auth-refresh-token.store.ts

@@ -1,23 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-export const AUTH_REFRESH_TOKEN_STORE = Symbol('AUTH_REFRESH_TOKEN_STORE');
-
-export interface AuthRefreshTokenStore {
-  readonly kind: string;
-  saveRefreshTokenHash(subject: string, hash: string): Promise<void>;
-  getRefreshTokenHash(subject: string): Promise<string | null>;
-  removeRefreshTokenHash(subject: string): Promise<void>;
-}
-
-@Injectable()
-export class NoopAuthRefreshTokenStore implements AuthRefreshTokenStore {
-  readonly kind = 'none';
-
-  async saveRefreshTokenHash(): Promise<void> {}
-
-  async getRefreshTokenHash(): Promise<string | null> {
-    return null;
-  }
-
-  async removeRefreshTokenHash(): Promise<void> {}
-}

package/templates/module-presets/jwt-auth/packages/auth-api/src/auth.controller.ts

@@ -1,71 +0,0 @@
-import type { AuthUser } from '@forgeon/auth-contracts';
-import {
-  Body,
-  Controller,
-  Get,
-  Post,
-  Req,
-  UseGuards,
-} from '@nestjs/common';
-import { AuthService } from './auth.service';
-import { LoginDto, RefreshDto } from './dto';
-import { JwtAuthGuard } from './jwt-auth.guard';
-import { AuthJwtPayload } from './auth.types';
-
-type RequestWithUser = { user?: AuthJwtPayload };
-
-@Controller('auth')
-export class AuthController {
-  constructor(private readonly authService: AuthService) {}
-
-  @Post('login')
-  login(@Body() body: LoginDto) {
-    return this.authService.login(body);
-  }
-
-  @Post('refresh')
-  refresh(@Body() body: RefreshDto) {
-    return this.authService.refresh(body);
-  }
-
-  @UseGuards(JwtAuthGuard)
-  @Post('logout')
-  async logout(@Req() request: RequestWithUser) {
-    const user = this.getRequestUser(request);
-    await this.authService.logout(user);
-    return {
-      status: 'ok',
-      tokenStore: this.authService.getTokenStoreKind(),
-    };
-  }
-
-  @UseGuards(JwtAuthGuard)
-  @Get('me')
-  me(@Req() request: RequestWithUser) {
-    const user = this.getRequestUser(request);
-    return {
-      user: this.toAuthUser(user),
-      tokenStore: this.authService.getTokenStoreKind(),
-    };
-  }
-
-  private getRequestUser(request: RequestWithUser): AuthJwtPayload {
-    const user = request.user;
-    if (!user || typeof user.sub !== 'string' || typeof user.email !== 'string') {
-      return {
-        sub: 'unknown',
-        email: 'unknown@invalid.local',
-        roles: ['user'],
-      };
-    }
-    return user;
-  }
-
-  private toAuthUser(payload: AuthJwtPayload): AuthUser {
-    return {
-      sub: payload.sub,
-      email: payload.email,
-      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
-    };
-  }
-}

package/templates/module-presets/jwt-auth/packages/auth-api/src/auth.service.ts

@@ -1,175 +0,0 @@
-import type {
-  AuthErrorCode,
-  AuthUser,
-  LoginResponse,
-  RefreshResponse,
-  TokenPair,
-} from '@forgeon/auth-contracts';
-import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
-import { JwtService } from '@nestjs/jwt';
-import type { JwtSignOptions } from '@nestjs/jwt';
-import { compare, hash } from 'bcryptjs';
-import {
-  AUTH_REFRESH_TOKEN_STORE,
-  AuthRefreshTokenStore,
-} from './auth-refresh-token.store';
-import { AuthConfigService } from './auth-config.service';
-import { LoginDto, RefreshDto } from './dto';
-import { AuthJwtPayload } from './auth.types';
-
-type JwtExpiresIn = NonNullable<JwtSignOptions['expiresIn']>;
-
-const AUTH_ERROR_CODES: Record<
-  'invalidCredentials' | 'tokenExpired' | 'refreshInvalid',
-  AuthErrorCode
-> = {
-  invalidCredentials: 'AUTH_INVALID_CREDENTIALS',
-  tokenExpired: 'AUTH_TOKEN_EXPIRED',
-  refreshInvalid: 'AUTH_REFRESH_INVALID',
-};
-
-@Injectable()
-export class AuthService {
-  constructor(
-    private readonly jwtService: JwtService,
-    private readonly configService: AuthConfigService,
-    @Inject(AUTH_REFRESH_TOKEN_STORE)
-    private readonly refreshTokenStore: AuthRefreshTokenStore,
-  ) {}
-
-  getTokenStoreKind(): string {
-    return this.refreshTokenStore.kind;
-  }
-
-  async login(input: LoginDto): Promise<LoginResponse> {
-    const email = input.email.trim().toLowerCase();
-    if (email !== this.configService.demoEmail || input.password !== this.configService.demoPassword) {
-      throw new UnauthorizedException({
-        message: 'Invalid credentials',
-        details: { code: AUTH_ERROR_CODES.invalidCredentials },
-      });
-    }
-
-    const user: AuthUser = {
-      sub: email,
-      email,
-      roles: ['user'],
-    };
-
-    const tokens = await this.issueTokens(user);
-    return {
-      ...tokens,
-      user,
-      tokenStore: this.refreshTokenStore.kind,
-    };
-  }
-
-  async refresh(input: RefreshDto): Promise<RefreshResponse> {
-    let payload: AuthJwtPayload;
-    try {
-      payload = await this.jwtService.verifyAsync<AuthJwtPayload>(input.refreshToken, {
-        secret: this.configService.refreshSecret,
-      });
-    } catch (error) {
-      const code =
-        error instanceof Error && error.name === 'TokenExpiredError'
-          ? AUTH_ERROR_CODES.tokenExpired
-          : AUTH_ERROR_CODES.refreshInvalid;
-
-      throw new UnauthorizedException({
-        message: 'Refresh token is invalid or expired',
-        details: { code },
-      });
-    }
-
-    if (this.refreshTokenStore.kind !== 'none') {
-      const storedHash = await this.refreshTokenStore.getRefreshTokenHash(payload.sub);
-      if (!storedHash) {
-        throw new UnauthorizedException({
-          message: 'Refresh token is invalid or expired',
-          details: { code: AUTH_ERROR_CODES.refreshInvalid },
-        });
-      }
-
-      const matched = await compare(input.refreshToken, storedHash);
-      if (!matched) {
-        throw new UnauthorizedException({
-          message: 'Refresh token is invalid or expired',
-          details: { code: AUTH_ERROR_CODES.refreshInvalid },
-        });
-      }
-    }
-
-    const user = this.toAuthUser(payload);
-    const tokens = await this.issueTokens(user);
-    return {
-      ...tokens,
-      user,
-      tokenStore: this.refreshTokenStore.kind,
-    };
-  }
-
-  async logout(user: AuthJwtPayload): Promise<void> {
-    if (this.refreshTokenStore.kind === 'none') {
-      return;
-    }
-    await this.refreshTokenStore.removeRefreshTokenHash(user.sub);
-  }
-
-  getProbeStatus() {
-    return {
-      status: 'ok',
-      feature: 'jwt-auth',
-      tokenStore: this.refreshTokenStore.kind,
-      demoEmail: this.configService.demoEmail,
-    };
-  }
-
-  private async issueTokens(user: AuthUser): Promise<TokenPair> {
-    const payload: AuthJwtPayload = {
-      sub: user.sub,
-      email: user.email,
-      roles: user.roles,
-    };
-
-    const [accessToken, refreshToken] = await Promise.all([
-      this.jwtService.signAsync(payload, {
-        secret: this.configService.accessSecret,
-        expiresIn: this.toJwtExpiresIn(this.configService.accessExpiresIn),
-      }),
-      this.jwtService.signAsync(payload, {
-        secret: this.configService.refreshSecret,
-        expiresIn: this.toJwtExpiresIn(this.configService.refreshExpiresIn),
-      }),
-    ]);
-
-    if (this.refreshTokenStore.kind !== 'none') {
-      const tokenHash = await hash(refreshToken, this.configService.bcryptRounds);
-      await this.refreshTokenStore.saveRefreshTokenHash(user.sub, tokenHash);
-    }
-
-    return {
-      accessToken,
-      refreshToken,
-      tokenType: 'Bearer',
-      accessTtl: this.configService.accessExpiresIn,
-      refreshTtl: this.configService.refreshExpiresIn,
-    };
-  }
-
-  private toAuthUser(payload: AuthJwtPayload): AuthUser {
-    return {
-      sub: payload.sub,
-      email: payload.email,
-      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
-    };
-  }
-
-  private toJwtExpiresIn(value: string): JwtExpiresIn {
-    const trimmed = value.trim();
-    if (/^\d+$/.test(trimmed)) {
-      return Number(trimmed);
-    }
-    return trimmed as JwtExpiresIn;
-  }
-}

package/templates/module-presets/jwt-auth/packages/auth-api/src/auth.types.ts

@@ -1,6 +0,0 @@
-import type { AuthUser } from '@forgeon/auth-contracts';
-
-export interface AuthJwtPayload extends AuthUser {
-  iat?: number;
-  exp?: number;
-}

package/templates/module-presets/jwt-auth/packages/auth-api/src/dto/index.ts

@@ -1,2 +0,0 @@
-export * from './login.dto';
-export * from './refresh.dto';

package/templates/module-presets/jwt-auth/packages/auth-api/src/forgeon-auth.module.ts

@@ -1,47 +0,0 @@
-import {
-  DynamicModule,
-  Module,
-  ModuleMetadata,
-  Provider,
-} from '@nestjs/common';
-import { JwtModule } from '@nestjs/jwt';
-import { PassportModule } from '@nestjs/passport';
-import {
-  AUTH_REFRESH_TOKEN_STORE,
-  NoopAuthRefreshTokenStore,
-} from './auth-refresh-token.store';
-import { AuthConfigModule } from './auth-config.module';
-import { AuthController } from './auth.controller';
-import { AuthService } from './auth.service';
-import { JwtAuthGuard } from './jwt-auth.guard';
-import { JwtStrategy } from './jwt.strategy';
-
-export interface ForgeonAuthModuleOptions {
-  imports?: ModuleMetadata['imports'];
-  refreshTokenStoreProvider?: Provider;
-}
-
-@Module({})
-export class ForgeonAuthModule {
-  static register(options: ForgeonAuthModuleOptions = {}): DynamicModule {
-    const refreshTokenStoreProvider =
-      options.refreshTokenStoreProvider ??
-      ({
-        provide: AUTH_REFRESH_TOKEN_STORE,
-        useClass: NoopAuthRefreshTokenStore,
-      } satisfies Provider);
-
-    return {
-      module: ForgeonAuthModule,
-      imports: [
-        AuthConfigModule,
-        PassportModule.register({ defaultStrategy: 'jwt' }),
-        JwtModule.register({}),
-        ...(options.imports ?? []),
-      ],
-      controllers: [AuthController],
-      providers: [AuthService, JwtStrategy, JwtAuthGuard, refreshTokenStoreProvider],
-      exports: [AuthConfigModule, AuthService, JwtAuthGuard, AUTH_REFRESH_TOKEN_STORE],
-    };
-  }
-}