@ftisindia/create-app 0.1.2 → 0.1.4

package/README.md

@@ -92,3 +92,68 @@ add a module and the architecture rules.
 Released under the **PolyForm Noncommercial License 1.0.0** — free for any noncommercial
 use. **Commercial use requires a separate commercial license from
 [ftisindia.com](https://ftisindia.com).** See the bundled `LICENSE` file.
+
+## Generating a module with `gen:module`
+
+Every project this CLI generates ships a `gen:module` script. In any generated project,
+run it to scaffold a new feature module that already follows the project's auth, RBAC,
+request-context, and audit conventions.
+
+```bash
+npm run gen:module -- billing
+```
+
+> Note the `--` before the name — it tells npm to pass the argument through to the
+> generator. Names are normalized automatically, so `billing`, `Billing`,
+> `"invoice items"`, and `invoiceItems` all resolve to the same module.
+
+### What it generates
+
+For a name like `billing`, you get:
+
+- `src/modules/billing/billing.module.ts` — the NestJS module (wires controller + service)
+- `src/modules/billing/dto/billing-echo.dto.ts` — a sample DTO (class-validator + Swagger)
+- `src/modules/billing/application/services/billing.service.ts` — a service with
+  `getStatus()` and `echo()` that use Prisma, request context, and write an audit-log row
+- `src/modules/billing/presentation/billing.controller.ts` — an org-scoped controller
+  guarded by `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`, exposing:
+  - `GET /organisations/:orgId/billing/status` — requires `billing.read`
+  - `POST /organisations/:orgId/billing/echo` — requires `billing.update`
+- `test/billing.spec.ts` — a starter unit test
+
+It also keeps RBAC in sync automatically by appending to:
+
+- `src/modules/access-control/types/permission-key.ts` — adds `billing.read` and `billing.update`
+- `src/modules/access-control/types/route-permission-registry.ts` — adds the two route
+  entries (startup and tests fail if a guarded route is missing here)
+
+The generator never overwrites existing files — it stops if any target already exists.
+
+### Two steps to finish
+
+1. **Register the module** in `src/app.module.ts` (the generator prints this reminder):
+   ```ts
+   import { BillingModule } from './modules/billing/billing.module';
+   // add BillingModule to the @Module({ imports: [...] }) array
+   ```
+2. **Re-seed permissions** so the new keys exist in the database and can be granted to roles:
+   ```bash
+   npm run prisma:seed
+   ```
+   Then assign `billing.read` / `billing.update` to the appropriate role(s).
+
+Start the app and the new guarded endpoints are live (visible in Swagger at `/docs`).
+
+### When not to use it
+
+- **You need a non-org-scoped or public route.** The output is hard-wired to
+  `/organisations/:orgId/<name>` with the org guards. Build global/unauthenticated
+  endpoints by hand instead.
+- **You're extending an existing module.** It scaffolds a brand-new module and refuses
+  to overwrite — add files to the existing module manually.
+- **Your feature doesn't map to simple read/update permissions.** It generates exactly
+  `<name>.read` and `<name>.update`; for richer permission sets, edit the generated
+  `permission-key.ts` and registry entries afterward.
+- **You want a different shape than the `status` + `echo` reference endpoints.** Treat
+  the output as a starting point, or copy `src/modules/sample` (see
+  `docs/SAMPLE_MODULE.md`) for a fuller reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftisindia/create-app",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "One-command scaffolder for the Phase 1 NestJS foundation starter.",
   "type": "module",
   "bin": {

package/template/README.md

@@ -1,4 +1,4 @@
-# __PROJECT_NAME__
+# **PROJECT_NAME**
 
 NestJS modular-monolith starter with email/password auth, Google OAuth handoff, organisations, memberships, invitations, per-organisation RBAC with CASL, request context, audit logs, typed settings, Swagger, and a complete sample module.
 
@@ -144,3 +144,67 @@ Swagger is mounted at `/docs` and includes tags, request schemas, response DTOs,
 common error responses, bearer authorization, route parameters, and examples for
 all implemented API routes. See `docs/API_REFERENCE.md` before adding or changing
 controllers.
+
+## Generating a module with `gen:module`
+
+Scaffold a new feature module that already follows the project's auth, RBAC,
+request-context, and audit conventions.
+
+```bash
+npm run gen:module -- billing
+```
+
+> Note the `--` before the name — it tells npm to pass the argument through to the
+> generator. Names are normalized automatically, so `billing`, `Billing`,
+> `"invoice items"`, and `invoiceItems` all resolve to the same module.
+
+### What it generates
+
+For a name like `billing`, you get:
+
+- `src/modules/billing/billing.module.ts` — the NestJS module (wires controller + service)
+- `src/modules/billing/dto/billing-echo.dto.ts` — a sample DTO (class-validator + Swagger)
+- `src/modules/billing/application/services/billing.service.ts` — a service with
+  `getStatus()` and `echo()` that use Prisma, request context, and write an audit-log row
+- `src/modules/billing/presentation/billing.controller.ts` — an org-scoped controller
+  guarded by `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`, exposing:
+  - `GET /organisations/:orgId/billing/status` — requires `billing.read`
+  - `POST /organisations/:orgId/billing/echo` — requires `billing.update`
+- `test/billing.spec.ts` — a starter unit test
+
+It also keeps RBAC in sync automatically by appending to:
+
+- `src/modules/access-control/types/permission-key.ts` — adds `billing.read` and `billing.update`
+- `src/modules/access-control/types/route-permission-registry.ts` — adds the two route
+  entries (startup and tests fail if a guarded route is missing here)
+
+The generator never overwrites existing files — it stops if any target already exists.
+
+### Two steps to finish
+
+1. **Register the module** in `src/app.module.ts` (the generator prints this reminder):
+   ```ts
+   import { BillingModule } from './modules/billing/billing.module';
+   // add BillingModule to the @Module({ imports: [...] }) array
+   ```
+2. **Re-seed permissions** so the new keys exist in the database and can be granted to roles:
+   ```bash
+   npm run prisma:seed
+   ```
+   Then assign `billing.read` / `billing.update` to the appropriate role(s).
+
+Start the app and the new guarded endpoints are live (visible in Swagger at `/docs`).
+
+### When not to use it
+
+- **You need a non-org-scoped or public route.** The output is hard-wired to
+  `/organisations/:orgId/<name>` with the org guards. Build global/unauthenticated
+  endpoints by hand instead.
+- **You're extending an existing module.** It scaffolds a brand-new module and refuses
+  to overwrite — add files to the existing module manually.
+- **Your feature doesn't map to simple read/update permissions.** It generates exactly
+  `<name>.read` and `<name>.update`; for richer permission sets, edit the generated
+  `permission-key.ts` and registry entries afterward.
+- **You want a different shape than the `status` + `echo` reference endpoints.** Treat
+  the output as a starting point, or copy `src/modules/sample` (see
+  `docs/SAMPLE_MODULE.md`) for a fuller reference.

package/template/_package.json

@@ -42,7 +42,6 @@
     "bcryptjs": "3.0.3",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
-    "express-session": "1.19.0",
     "passport": "0.7.0",
     "passport-google-oauth20": "2.0.0",
     "passport-jwt": "4.0.1",
@@ -56,7 +55,6 @@
     "@nestjs/cli": "11.0.21",
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.24",
-    "@types/express-session": "1.19.0",
     "@types/jest": "30.0.0",
     "@types/node": "20.19.41",
     "@types/passport": "1.0.17",

package/template/docs/API_REFERENCE.md

@@ -28,6 +28,19 @@ After authorization, Swagger can call protected routes directly.
 Successful responses are documented per endpoint with typed response DTOs. Most
 date values are ISO strings.
 
+Growable list endpoints such as memberships, invitations, and roles are cursor
+paginated:
+
+```json
+{
+  "items": [],
+  "nextCursor": null
+}
+```
+
+Use `?limit=50` and pass `nextCursor` back as `?cursor=...` to fetch the next
+page.
+
 Errors use one common envelope:
 
 ```json

package/template/docs/OAUTH.md

@@ -18,9 +18,12 @@ Failures redirect to `AUTH_GOOGLE_ERROR_REDIRECT_URL?error=oauth_failed`.
 
 ## State And PKCE
 
-Google OAuth uses state and PKCE. A short-lived `oauth.sid` session cookie is scoped only to `/auth/google` and `/auth/google/callback` so Passport can store and verify the OAuth state and PKCE code verifier during the handshake.
+Google OAuth uses state and PKCE. The API encrypts and authenticates the PKCE
+code verifier inside a short-lived state value, so the callback can be handled
+without an Express session store.
 
-The rest of the app remains stateless JWT. There is no `passport.session()` and no persistent login session.
+The app remains stateless JWT. There is no `passport.session()`, no persistent
+login session, and no in-memory OAuth session store.
 
 ## Auth Endpoint Hardening
 
@@ -43,4 +46,5 @@ SESSION_SECRET=
 
 `SESSION_SECRET` must be at least 32 random characters.
 
-The default `express-session` memory store is intended for development and single-instance deployments. In multi-instance production deployments, use sticky sessions or replace the store with a shared store such as Redis.
+When `NODE_ENV=production`, all configured Google callback/success/error URLs
+must use HTTPS.

package/template/scripts/gen-module.mjs

@@ -78,6 +78,8 @@ export class ${names.pascal}Service {
           messageLength: message.length,
           requestId: this.requestContext.getRequestId(),
         } satisfies Prisma.InputJsonObject,
+        ipAddress: this.requestContext.getIpAddress(),
+        userAgent: this.requestContext.getUserAgent(),
       },
     });
 

package/template/src/app.module.ts

@@ -1,25 +1,19 @@
-import { Module } from "@nestjs/common";
-import { ConfigModule } from "@nestjs/config";
-import { APP_GUARD } from "@nestjs/core";
-import { ThrottlerGuard, ThrottlerModule } from "@nestjs/throttler";
-import {
-  appConfig,
-  authConfig,
-  databaseConfig,
-  rbacConfig,
-  validate,
-} from "./config";
-import { PrismaModule } from "./database/prisma/prisma.module";
-import { AccessControlModule } from "./modules/access-control/access-control.module";
-import { AuditModule } from "./modules/audit/audit.module";
-import { AuthModule } from "./modules/auth/auth.module";
-import { HealthModule } from "./modules/health/health.module";
-import { InvitationsModule } from "./modules/invitations/invitations.module";
-import { MembershipsModule } from "./modules/memberships/memberships.module";
-import { OrganisationsModule } from "./modules/organisations/organisations.module";
-import { RequestContextModule } from "./modules/request-context/request-context.module";
-import { SampleModule } from "./modules/sample/sample.module";
-import { SettingsModule } from "./modules/settings/settings.module";
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { APP_GUARD } from '@nestjs/core';
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import { appConfig, authConfig, databaseConfig, rbacConfig, validate } from './config';
+import { PrismaModule } from './database/prisma/prisma.module';
+import { AccessControlModule } from './modules/access-control/access-control.module';
+import { AuditModule } from './modules/audit/audit.module';
+import { AuthModule } from './modules/auth/auth.module';
+import { HealthModule } from './modules/health/health.module';
+import { InvitationsModule } from './modules/invitations/invitations.module';
+import { MembershipsModule } from './modules/memberships/memberships.module';
+import { OrganisationsModule } from './modules/organisations/organisations.module';
+import { RequestContextModule } from './modules/request-context/request-context.module';
+import { SampleModule } from './modules/sample/sample.module';
+import { SettingsModule } from './modules/settings/settings.module';
 
 @Module({
   imports: [

package/template/src/common/dto/error-response.dto.ts

@@ -1,10 +1,10 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 class ErrorBodyDto {
-  @ApiProperty({ example: "BAD_REQUEST" })
+  @ApiProperty({ example: 'BAD_REQUEST' })
   code!: string;
 
-  @ApiProperty({ example: "Validation failed." })
+  @ApiProperty({ example: 'Validation failed.' })
   message!: string;
 
   @ApiPropertyOptional({ type: Object })

package/template/src/common/dto/membership-response.dto.ts

@@ -1,30 +1,30 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
-import { MembershipStatus } from "@prisma/client";
-import { RoleSummaryDto } from "./role-summary.dto";
-import { ActiveUserSummaryDto } from "./user-summary.dto";
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { MembershipStatus } from '@prisma/client';
+import { RoleSummaryDto } from './role-summary.dto';
+import { ActiveUserSummaryDto } from './user-summary.dto';
 
 export class MembershipResponseDto {
   @ApiProperty({
-    example: "0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3",
-    format: "uuid",
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
   })
   id!: string;
 
   @ApiProperty({
-    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
-    format: "uuid",
+    example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
+    format: 'uuid',
   })
   userId!: string;
 
   @ApiProperty({
-    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
-    format: "uuid",
+    example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
+    format: 'uuid',
   })
   orgId!: string;
 
   @ApiProperty({
-    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
-    format: "uuid",
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
   })
   roleId!: string;
 
@@ -43,9 +43,21 @@ export class MembershipResponseDto {
   @ApiPropertyOptional({ type: RoleSummaryDto })
   role?: RoleSummaryDto;
 
-  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
   createdAt!: string;
 
-  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
   updatedAt!: string;
 }
+
+export class MembershipListResponseDto {
+  @ApiProperty({ type: [MembershipResponseDto] })
+  items!: MembershipResponseDto[];
+
+  @ApiPropertyOptional({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    nullable: true,
+  })
+  nextCursor!: string | null;
+}

package/template/src/common/dto/mutation-response.dto.ts

@@ -1,4 +1,4 @@
-import { ApiProperty } from "@nestjs/swagger";
+import { ApiProperty } from '@nestjs/swagger';
 
 export class DeletedResponseDto {
   @ApiProperty({ example: true })

package/template/src/common/dto/pagination-query.dto.ts

@@ -0,0 +1,37 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, IsUUID, Max, Min } from 'class-validator';
+
+export const DEFAULT_PAGE_LIMIT = 50;
+export const MAX_PAGE_LIMIT = 100;
+
+export class PaginationQueryDto {
+  @ApiPropertyOptional({ example: 50, minimum: 1, maximum: MAX_PAGE_LIMIT })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(MAX_PAGE_LIMIT)
+  limit?: number;
+
+  @ApiPropertyOptional({
+    example: 'df6537c4-f58b-452e-a67e-18ec528d0f0f',
+    format: 'uuid',
+  })
+  @IsOptional()
+  @IsUUID()
+  cursor?: string;
+}
+
+export function resolvePageLimit(limit: number | undefined) {
+  return Math.min(limit ?? DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT);
+}
+
+export function toPage<T extends { id: string }>(rows: T[], limit: number) {
+  const items = rows.slice(0, limit);
+
+  return {
+    items,
+    nextCursor: rows.length > limit ? (items[items.length - 1]?.id ?? null) : null,
+  };
+}

package/template/src/common/dto/role-summary.dto.ts

@@ -1,16 +1,16 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export class RoleSummaryDto {
   @ApiProperty({
-    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
-    format: "uuid",
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
   })
   id!: string;
 
-  @ApiProperty({ example: "Owner" })
+  @ApiProperty({ example: 'Owner' })
   name!: string;
 
-  @ApiPropertyOptional({ example: "Full organisation access.", nullable: true })
+  @ApiPropertyOptional({ example: 'Full organisation access.', nullable: true })
   description?: string | null;
 
   @ApiPropertyOptional({ example: true })

package/template/src/common/dto/user-summary.dto.ts

@@ -1,19 +1,19 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export class UserSummaryDto {
   @ApiProperty({
-    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
-    format: "uuid",
+    example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
+    format: 'uuid',
   })
   id!: string;
 
-  @ApiPropertyOptional({ example: "owner@example.com", nullable: true })
+  @ApiPropertyOptional({ example: 'owner@example.com', nullable: true })
   email?: string | null;
 
-  @ApiPropertyOptional({ example: "+14155552671", nullable: true })
+  @ApiPropertyOptional({ example: '+14155552671', nullable: true })
   mobile?: string | null;
 
-  @ApiPropertyOptional({ example: "Starter Owner", nullable: true })
+  @ApiPropertyOptional({ example: 'Starter Owner', nullable: true })
   displayName?: string | null;
 }
 

package/template/src/common/filters/http-exception.filter.ts

@@ -1,10 +1,4 @@
-import {
-  ArgumentsHost,
-  Catch,
-  ExceptionFilter,
-  HttpException,
-  HttpStatus,
-} from "@nestjs/common";
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from '@nestjs/common';
 
 type HttpResponse = {
   status: (statusCode: number) => {
@@ -17,9 +11,7 @@ export class HttpExceptionFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {
     const response = host.switchToHttp().getResponse<HttpResponse>();
     const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
+      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
 
     response.status(status).json({
       error: {
@@ -32,25 +24,25 @@ export class HttpExceptionFilter implements ExceptionFilter {
 }
 
 function errorCode(status: number) {
-  return HttpStatus[status] ?? "ERROR";
+  return HttpStatus[status] ?? 'ERROR';
 }
 
 function errorMessage(exception: unknown) {
   if (!(exception instanceof HttpException)) {
-    return "Internal server error.";
+    return 'Internal server error.';
   }
 
   const body = exception.getResponse();
-  if (typeof body === "string") {
+  if (typeof body === 'string') {
     return body;
   }
 
-  if (isObject(body) && typeof body.message === "string") {
+  if (isObject(body) && typeof body.message === 'string') {
     return body.message;
   }
 
   if (isObject(body) && Array.isArray(body.message)) {
-    return body.message.join("; ");
+    return body.message.join('; ');
   }
 
   return exception.message;
@@ -67,12 +59,10 @@ function errorDetails(exception: unknown) {
   }
 
   return Object.fromEntries(
-    Object.entries(body).filter(
-      ([key]) => !["statusCode", "error", "message"].includes(key),
-    ),
+    Object.entries(body).filter(([key]) => !['statusCode', 'error', 'message'].includes(key)),
   );
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+  return typeof value === 'object' && value !== null;
 }

package/template/src/common/swagger/api-error-responses.ts

@@ -1,4 +1,4 @@
-import { applyDecorators } from "@nestjs/common";
+import { applyDecorators } from '@nestjs/common';
 import {
   ApiBadRequestResponse,
   ApiConflictResponse,
@@ -9,8 +9,8 @@ import {
   ApiServiceUnavailableResponse,
   ApiTooManyRequestsResponse,
   ApiUnauthorizedResponse,
-} from "@nestjs/swagger";
-import { ErrorResponseDto } from "../dto/error-response.dto";
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../dto/error-response.dto';
 
 type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 429 | 500 | 503;
 
@@ -27,15 +27,15 @@ const errorResponseFactories = {
 } satisfies Record<ApiErrorStatus, typeof ApiBadRequestResponse>;
 
 const descriptions: Record<ApiErrorStatus, string> = {
-  400: "The request body, route parameter, or query string is invalid.",
-  401: "Authentication failed or the bearer token is missing.",
-  403: "The authenticated user does not have access to this organisation or permission.",
-  404: "The requested resource was not found.",
-  409: "The request conflicts with current resource state.",
-  410: "The resource is no longer available.",
-  429: "Too many requests.",
-  500: "Unexpected server error.",
-  503: "The service is temporarily unavailable.",
+  400: 'The request body, route parameter, or query string is invalid.',
+  401: 'Authentication failed or the bearer token is missing.',
+  403: 'The authenticated user does not have access to this organisation or permission.',
+  404: 'The requested resource was not found.',
+  409: 'The request conflicts with current resource state.',
+  410: 'The resource is no longer available.',
+  429: 'Too many requests.',
+  500: 'Unexpected server error.',
+  503: 'The service is temporarily unavailable.',
 };
 
 export function ApiErrorResponses(...statuses: ApiErrorStatus[]) {

package/template/src/config/app.config.ts

@@ -1,7 +1,7 @@
-import { registerAs } from "@nestjs/config";
-import { getEnv } from "./env.validation";
+import { registerAs } from '@nestjs/config';
+import { getEnv } from './env.validation';
 
-export default registerAs("app", () => ({
+export default registerAs('app', () => ({
   nodeEnv: getEnv().NODE_ENV,
   port: getEnv().PORT,
 }));

package/template/src/config/auth.config.ts

@@ -1,7 +1,7 @@
-import { registerAs } from "@nestjs/config";
-import { getEnv } from "./env.validation";
+import { registerAs } from '@nestjs/config';
+import { getEnv } from './env.validation';
 
-export default registerAs("auth", () => {
+export default registerAs('auth', () => {
   const env = getEnv();
 
   return {

package/template/src/config/database.config.ts

@@ -1,6 +1,6 @@
-import { registerAs } from "@nestjs/config";
-import { getEnv } from "./env.validation";
+import { registerAs } from '@nestjs/config';
+import { getEnv } from './env.validation';
 
-export default registerAs("database", () => ({
+export default registerAs('database', () => ({
   url: getEnv().DATABASE_URL,
 }));