@ftisindia/create-app 0.1.0

package/template/README.md

@@ -0,0 +1,146 @@
+# __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.
+
+## Quickstart
+
+Install dependencies if the scaffolder did not already do it:
+
+```bash
+npm install
+```
+
+Run the guided local setup:
+
+```bash
+npm run setup:local
+```
+
+Make sure PostgreSQL is running before setup starts. If your local PostgreSQL user,
+password, host, or port differs from the default, update `.env` when the setup prompt
+opens it for review.
+
+The setup command checks and creates `.env` values, creates the `app` and `app_test` PostgreSQL databases if they are missing, generates Prisma, deploys migrations, seeds permissions, and prints demo login credentials. It is non-destructive: it does not drop, reset, truncate, or overwrite existing data.
+
+Start the API:
+
+```bash
+npm run start:dev
+```
+
+Open:
+
+```txt
+http://localhost:3000/health
+http://localhost:3000/docs
+```
+
+Use the printed demo email/password at `POST /auth/login`, then paste the returned access token into Swagger's bearer authorization.
+
+For a fresher-friendly API walkthrough, response-shape notes, and Swagger usage
+rules, read `docs/API_REFERENCE.md`.
+
+## PostgreSQL
+
+The default `.env` expects a local PostgreSQL server reachable at:
+
+```txt
+postgresql://postgres:postgres@localhost:5432/app
+```
+
+Any reachable PostgreSQL works. Update `DATABASE_URL` and `TEST_DATABASE_URL` in `.env` if your local user, password, host, port, or database names differ. `npm run db:create` creates missing databases only; it never deletes existing databases.
+
+## Daily Commands
+
+```bash
+npm run setup:local   # guided, idempotent local bootstrap
+npm run start:dev     # start in watch mode
+npm run lint          # ESLint
+npm run format        # Prettier write
+npm run build         # Nest build
+npm test              # unit tests
+npm run test:e2e      # e2e tests against TEST_DATABASE_URL
+```
+
+`npm run db:reset` is the only destructive database command and is intentionally separate.
+
+## Core Endpoints
+
+```txt
+GET  /health
+GET  /docs
+POST /auth/signup
+POST /auth/login
+POST /auth/refresh
+POST /auth/oauth/exchange
+POST /auth/logout
+GET  /auth/google
+GET  /auth/google/callback
+GET  /auth/me
+POST /organisations
+GET  /organisations/:orgId/memberships/me
+GET  /organisations/:orgId/memberships
+PATCH /organisations/:orgId/memberships/:membershipId/status
+PATCH /organisations/:orgId/memberships/:membershipId/role
+PATCH /organisations/:orgId/memberships/:membershipId/owner
+PATCH /organisations/:orgId/memberships/:membershipId/billing-contact
+POST /organisations/:orgId/memberships/transfer-owner
+POST /organisations/:orgId/invitations
+GET  /organisations/:orgId/invitations
+POST /organisations/:orgId/invitations/:invitationId/revoke
+POST /organisations/:orgId/invitations/:invitationId/resend
+POST /invitations/accept
+POST /invitations/decline
+GET  /organisations/:orgId/access-control/permissions
+GET  /organisations/:orgId/access-control/route-permissions
+GET  /organisations/:orgId/access-control/roles
+POST /organisations/:orgId/access-control/roles
+PATCH /organisations/:orgId/access-control/roles/:roleId
+DELETE /organisations/:orgId/access-control/roles/:roleId
+GET  /organisations/:orgId/access-control/roles/:roleId/permissions
+PUT  /organisations/:orgId/access-control/roles/:roleId/permissions
+GET  /organisations/:orgId/audit
+GET  /organisations/:orgId/settings
+GET  /organisations/:orgId/settings/:key
+PATCH /organisations/:orgId/settings
+GET  /organisations/:orgId/sample/status
+POST /organisations/:orgId/sample/echo
+```
+
+## Architecture Rules
+
+- JWTs contain identity only. Organisation membership, roles, and permissions are read per request.
+- Organisation-scoped routes use path scope: `/organisations/:orgId/...`.
+- Protected organisation routes use `JwtAuthGuard`, `OrgScopeGuard`, `PermissionGuard`, and `@RequirePermissions(...)`.
+- Every permission-gated route must be represented in `route-permission-registry.ts`; startup and tests fail on drift.
+- Mutating business flows should write audit rows.
+- Setup and CI commands are non-destructive. Use `npm run db:reset` only when you explicitly want to reset a local database.
+
+## Adding Features
+
+Use the sample module as the copy-paste reference:
+
+```txt
+src/modules/sample
+docs/SAMPLE_MODULE.md
+docs/MODULE_COMPLETION_CHECKLIST.md
+```
+
+You can also scaffold a starter module:
+
+```bash
+npm run gen:module -- billing-reports
+```
+
+The generator creates a guarded org-scoped controller, DTO, service with request-context and audit patterns, permission keys, route registry entries, and a starter spec. It prints the `AppModule` import you still need to add.
+
+## REST Client
+
+`docs/api.http` contains a REST Client flow for health, login, organisation setup, invitations, RBAC, settings, audit, and the sample endpoint.
+
+## API Documentation
+
+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.

package/template/_editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+*.log
+.env
+.env.*
+!.env.example

package/template/_nvmrc

@@ -0,0 +1 @@
+20

package/template/_package.json

@@ -0,0 +1,107 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "nest build",
+    "db:create": "node scripts/db-create.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "gen:module": "node scripts/gen-module.mjs",
+    "lint": "eslint .",
+    "prepare": "husky || true",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/main.js",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev --name init",
+    "prisma:deploy": "prisma migrate deploy",
+    "prisma:seed": "prisma db seed",
+    "seed:test-user-org": "tsx scripts/seed-test-user-org.ts",
+    "setup": "node scripts/setup-local.mjs",
+    "setup:local": "node scripts/setup-local.mjs",
+    "setup:ci": "node scripts/setup-local.mjs --yes",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "test:e2e": "node scripts/test-db.mjs && jest --config test/jest-e2e.json --runInBand",
+    "test:watch": "jest --watch",
+    "db:reset": "prisma migrate reset"
+  },
+  "dependencies": {
+    "@casl/ability": "6.8.1",
+    "@nestjs/common": "11.1.24",
+    "@nestjs/config": "4.0.4",
+    "@nestjs/core": "11.1.24",
+    "@nestjs/jwt": "11.0.2",
+    "@nestjs/passport": "11.0.5",
+    "@nestjs/platform-express": "11.1.24",
+    "@nestjs/swagger": "11.4.4",
+    "@nestjs/throttler": "6.5.0",
+    "@prisma/client": "5.22.0",
+    "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",
+    "pg": "8.21.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@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",
+    "@types/passport-google-oauth20": "2.0.17",
+    "@types/passport-jwt": "4.0.1",
+    "@types/pg": "8.20.0",
+    "@types/supertest": "7.2.0",
+    "eslint": "10.4.1",
+    "eslint-config-prettier": "10.1.8",
+    "globals": "17.6.0",
+    "husky": "9.1.7",
+    "jest": "30.4.2",
+    "lint-staged": "17.0.6",
+    "prettier": "3.8.3",
+    "prisma": "5.22.0",
+    "supertest": "7.2.2",
+    "ts-jest": "29.4.11",
+    "ts-node": "10.9.2",
+    "tsconfig-paths": "4.2.0",
+    "tsx": "4.22.3",
+    "typescript-eslint": "8.60.0",
+    "typescript": "5.9.3"
+  },
+  "lint-staged": {
+    "*.{js,mjs,ts,json,md,yml,yaml}": "prettier --write",
+    "*.{js,mjs,ts}": "eslint --fix"
+  },
+  "prisma": {
+    "seed": "tsx prisma/seed.ts"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": ".",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "src/**/*.(t|j)s"
+    ],
+    "coverageDirectory": "coverage",
+    "testEnvironment": "node"
+  }
+}

package/template/_prettierignore

@@ -0,0 +1,5 @@
+coverage
+dist
+node_modules
+package-lock.json
+*.prisma

package/template/_prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "endOfLine": "auto"
+}

package/template/docs/API_REFERENCE.md

@@ -0,0 +1,123 @@
+# API Reference
+
+The generated app exposes interactive Swagger documentation at:
+
+```txt
+http://localhost:3000/docs
+```
+
+Start the API first:
+
+```bash
+npm run start:dev
+```
+
+## Authentication In Swagger
+
+1. Run `npm run setup:local` and copy the printed demo email and password.
+2. Open `/docs`.
+3. Run `POST /auth/login` with the demo credentials.
+4. Copy `accessToken` from the response.
+5. Click `Authorize` in Swagger.
+6. Paste the token as the bearer token value.
+
+After authorization, Swagger can call protected routes directly.
+
+## Common Response Shape
+
+Successful responses are documented per endpoint with typed response DTOs. Most
+date values are ISO strings.
+
+Errors use one common envelope:
+
+```json
+{
+  "error": {
+    "code": "BAD_REQUEST",
+    "message": "Validation failed.",
+    "details": {}
+  }
+}
+```
+
+Typical status codes:
+
+```txt
+400 invalid body, route parameter, or query string
+401 missing or invalid bearer token
+403 authenticated user lacks org access or permission
+404 resource not found
+409 request conflicts with current state
+410 invitation token expired or no longer usable
+429 auth endpoint rate limit exceeded
+503 health check dependency failure
+```
+
+## Organisation-Scoped Routes
+
+Most business routes are scoped under:
+
+```txt
+/organisations/:orgId/...
+```
+
+For those routes:
+
+- `JwtAuthGuard` verifies the user identity.
+- `OrgScopeGuard` loads the active membership for `orgId`.
+- `PermissionGuard` checks the route permissions.
+- `route-permission-registry.ts` is validated at startup and in tests, so
+  permission-gated routes must stay registered.
+
+Use `POST /organisations` first if you need a fresh `orgId`.
+
+## Endpoint Groups
+
+| Group          | Purpose                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| Health         | Confirm API and database availability.                                  |
+| Auth           | Signup, login, refresh, logout, Google OAuth handoff, current user.     |
+| Organisations  | Create an organisation and seed owner role/settings.                    |
+| Memberships    | Read memberships and manage status, role, owner, billing contact.       |
+| Invitations    | Invite, resend, revoke, accept, and decline organisation invitations.   |
+| Access control | List permissions, route-permission mapping, and manage roles.           |
+| Settings       | Read and update typed organisation settings.                            |
+| Audit          | Search organisation audit events.                                       |
+| Sample         | Copy-paste reference for request context, RBAC, DTOs, and audit writes. |
+
+## REST Client File
+
+`docs/api.http` contains a runnable flow for VS Code REST Client or compatible
+HTTP clients. It mirrors the Swagger groups and is useful when a developer wants
+repeatable API calls outside the browser.
+
+Update the variables at the top after setup:
+
+```http
+@baseUrl = http://localhost:3000
+@email = owner@example.com
+@password = replace-with-printed-setup-password
+@orgId = replace-with-org-id
+@roleId = replace-with-role-id
+```
+
+## Keeping Swagger Complete
+
+When adding a new endpoint, add these pieces in the same change:
+
+- `@ApiTags` on the controller, or reuse the existing controller tag.
+- `@ApiOperation` on every handler.
+- `@ApiBearerAuth` for protected routes.
+- `@ApiParam` and query DTO properties for route/query inputs.
+- `@ApiProperty` or `@ApiPropertyOptional` on request DTO fields.
+- A response DTO and `@ApiOkResponse` or `@ApiCreatedResponse`.
+- `ApiErrorResponses` or `ApiProtectedErrorResponses`.
+- A matching entry in `docs/api.http` for important flows.
+
+Run these checks before handing the module to another developer:
+
+```bash
+npm run lint
+npm run build
+npm test
+```

package/template/docs/GETTING_STARTED.md

@@ -0,0 +1,65 @@
+# Getting Started
+
+## One-Command Local Setup
+
+```bash
+npm run setup:local
+```
+
+The setup script:
+
+- creates `.env` from `.env.example` if needed
+- fills missing `DATABASE_URL`, `TEST_DATABASE_URL`, `JWT_SECRET`, and `TEST_USER_PASSWORD`
+- creates the dev and test PostgreSQL databases if they do not exist
+- generates Prisma Client
+- deploys migrations
+- seeds the permission catalogue
+- seeds a demo owner, organisation, roles, settings, and membership
+- prints the demo login credentials
+
+It is non-destructive. It does not drop, reset, truncate, or overwrite existing application data.
+
+## PostgreSQL
+
+The default expects a local PostgreSQL server with user `postgres`, password `postgres`, and host `localhost:5432`.
+
+```txt
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
+TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app_test
+```
+
+If your database differs, edit `.env` and rerun `npm run setup:local`.
+
+## Start The API
+
+```bash
+npm run start:dev
+```
+
+Open:
+
+```txt
+http://localhost:3000/health
+http://localhost:3000/docs
+```
+
+Login through Swagger with the printed demo credentials and authorize with the returned bearer token.
+
+Read `docs/API_REFERENCE.md` for the full Swagger workflow, response shapes,
+error envelope, endpoint groups, and the checklist for keeping future endpoints
+documented.
+
+## Useful Commands
+
+```bash
+npm run setup:local
+npm run db:create
+npm run lint
+npm run format
+npm run build
+npm test
+npm run test:e2e
+npm run start:dev
+```
+
+`npm run db:reset` is intentionally separate and destructive.

package/template/docs/MODULE_COMPLETION_CHECKLIST.md

@@ -0,0 +1,40 @@
+# Module Completion Checklist
+
+Use this checklist before considering a new organisation-scoped module complete.
+
+## Structure
+
+- [ ] Module follows `application`, `dto`, `presentation`, `types`, and `infrastructure` folders where relevant.
+- [ ] Controller route is path-scoped with `/organisations/:orgId/...` for organisation data.
+- [ ] Controller uses `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`.
+- [ ] Every protected handler has `@RequirePermissions(...)`.
+- [ ] Route-permission registry includes every protected route.
+
+## Security
+
+- [ ] Service calls `requestContext.assertOrgScope(orgId)` before reading or writing organisation data.
+- [ ] Queries filter by `orgId` explicitly.
+- [ ] Raw SQL, if any, filters by `orgId` explicitly.
+- [ ] Cross-organisation IDs are rejected or return not found.
+- [ ] Owner-only behavior is enforced in the service layer, not only through route metadata.
+
+## Data and Transactions
+
+- [ ] Writes that touch multiple rows use a transaction.
+- [ ] Uniqueness and integrity rules are backed by database constraints where practical.
+- [ ] Prisma known errors that users can trigger are mapped to clear HTTP errors.
+- [ ] Cache invalidation, if needed, runs after the transaction commits.
+
+## Audit and Settings
+
+- [ ] Security-sensitive, billing, identity, access-control, and organisation-configuration writes create audit rows.
+- [ ] Audit metadata includes previous and next values when useful.
+- [ ] New setting keys are added to typed setting definitions and validated.
+
+## Verification
+
+- [ ] Build passes.
+- [ ] Prisma generate passes.
+- [ ] Happy-path API flow is verified.
+- [ ] Missing-permission and cross-org access are verified.
+- [ ] Seed/setup scripts remain idempotent.

package/template/docs/OAUTH.md

@@ -0,0 +1,46 @@
+# OAuth
+
+## Google OAuth
+
+Google OAuth is optional and disabled by default.
+
+When enabled, the flow is:
+
+```txt
+GET /auth/google
+GET /auth/google/callback
+POST /auth/oauth/exchange
+```
+
+The callback redirects to `AUTH_GOOGLE_SUCCESS_REDIRECT_URL` with a short-lived one-time `code`. The client exchanges that code with `POST /auth/oauth/exchange` to receive JWT access and refresh tokens.
+
+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.
+
+The rest of the app remains stateless JWT. There is no `passport.session()` and no persistent login session.
+
+## Auth Endpoint Hardening
+
+Login uses the same generic failure response and a dummy-hash path for missing users so
+the password-check timing stays consistent. Signup returns a generic conflict response
+for duplicate emails, but it is still weakly enumerable by design because successful
+signup immediately returns tokens. Full non-enumerable signup requires a deferred
+email-verification flow; rate-limit auth endpoints before exposing the app publicly.
+
+Set these values when `AUTH_GOOGLE_ENABLED=true`:
+
+```txt
+AUTH_GOOGLE_CLIENT_ID=
+AUTH_GOOGLE_CLIENT_SECRET=
+AUTH_GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
+AUTH_GOOGLE_SUCCESS_REDIRECT_URL=http://localhost:3000/auth/google/success
+AUTH_GOOGLE_ERROR_REDIRECT_URL=http://localhost:3000/auth/google/error
+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.

package/template/docs/SAMPLE_MODULE.md

@@ -0,0 +1,23 @@
+# Sample Module
+
+The generated app includes a small `SampleModule` under `src/modules/sample`.
+
+It exists to demonstrate the expected shape of an organisation-scoped module:
+
+- path-scoped routes under `/organisations/:orgId/sample`
+- `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`
+- explicit permission metadata
+- service-level `requestContext.assertOrgScope(orgId)`
+- request-context reads in service responses
+- DTO validation
+- audit writes for mutating commands
+- route-permission registry entries
+
+## Routes
+
+```txt
+GET  /organisations/:orgId/sample/status  organisations.read
+POST /organisations/:orgId/sample/echo    organisations.update
+```
+
+The module is intentionally simple and has no database table. Replace or delete it when your first real business module is ready.