@ftisindia/create-app 0.1.0

package/template/prisma/schema.prisma

@@ -0,0 +1,299 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+enum OrganisationStatus {
+  ACTIVE
+  SUSPENDED
+  DELETED
+}
+
+enum MembershipStatus {
+  ACTIVE
+  SUSPENDED
+  REVOKED
+}
+
+enum AuthProvider {
+  EMAIL_PASSWORD
+  GOOGLE
+  FACEBOOK
+  MOBILE_OTP
+  MAGIC_LINK
+}
+
+enum InvitationTargetType {
+  EMAIL
+  MOBILE
+}
+
+enum InvitationStatus {
+  PENDING
+  ACCEPTED
+  DECLINED
+  EXPIRED
+  REVOKED
+}
+
+// Relation delete policy:
+// Required foreign keys use Prisma's default Restrict behavior so referenced
+// records cannot be deleted while dependent rows still exist. RolePermission.role
+// is the intentional exception: deleting a role cascades its permission join rows,
+// while RolePermission.permission remains restricted because permissions are
+// immutable seed data.
+
+model User {
+  id           String  @id @default(uuid())
+  email        String? @unique
+  mobile       String? @unique
+  passwordHash String?
+  displayName  String?
+  isActive     Boolean @default(true)
+
+  memberships         Membership[]
+  identities          AuthIdentity[]
+  refreshTokens       RefreshToken[]
+  authExchangeCodes   AuthExchangeCode[]
+  passwordResetTokens PasswordResetToken[]
+  auditLogs           AuditLog[]
+  sentInvitations     Invitation[]         @relation("InvitedByUser")
+  acceptedInvitations Invitation[]         @relation("AcceptedByUser")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+model AuthIdentity {
+  id String @id @default(uuid())
+
+  userId         String
+  provider       AuthProvider
+  providerUserId String
+  email          String?
+  mobile         String?
+
+  user User @relation(fields: [userId], references: [id])
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([provider, providerUserId])
+  @@index([userId])
+  @@index([provider])
+}
+
+model RefreshToken {
+  id String @id @default(uuid())
+
+  userId            String
+  tokenHash         String    @unique
+  expiresAt         DateTime
+  revokedAt         DateTime?
+  replacedByTokenId String?
+
+  user User @relation(fields: [userId], references: [id])
+
+  createdAt DateTime @default(now())
+
+  @@index([userId])
+  @@index([expiresAt])
+  @@index([revokedAt])
+}
+
+model AuthExchangeCode {
+  id String @id @default(uuid())
+
+  userId    String
+  tokenHash String    @unique
+  expiresAt DateTime
+  usedAt    DateTime?
+
+  user User @relation(fields: [userId], references: [id])
+
+  createdAt DateTime @default(now())
+
+  @@index([userId])
+  @@index([expiresAt])
+  @@index([usedAt])
+}
+
+model PasswordResetToken {
+  id String @id @default(uuid())
+
+  userId    String
+  tokenHash String    @unique
+  expiresAt DateTime
+  usedAt    DateTime?
+
+  user User @relation(fields: [userId], references: [id])
+
+  createdAt DateTime @default(now())
+
+  @@index([userId])
+  @@index([expiresAt])
+  @@index([usedAt])
+}
+
+model Organisation {
+  id     String             @id @default(uuid())
+  name   String
+  slug   String             @unique
+  status OrganisationStatus @default(ACTIVE)
+
+  memberships Membership[]
+  roles       Role[]
+  settings    OrganisationSetting[]
+  invitations Invitation[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+model OrganisationSetting {
+  id String @id @default(uuid())
+
+  orgId String
+  key   String
+  value Json
+
+  organisation Organisation @relation(fields: [orgId], references: [id])
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, key])
+  @@index([orgId])
+}
+
+model Membership {
+  id String @id @default(uuid())
+
+  userId String
+  orgId  String
+  roleId String
+
+  status           MembershipStatus @default(ACTIVE)
+  isOwner          Boolean          @default(false)
+  isBillingContact Boolean          @default(false)
+
+  user         User         @relation(fields: [userId], references: [id])
+  organisation Organisation @relation(fields: [orgId], references: [id])
+  role         Role         @relation(fields: [roleId, orgId], references: [id, orgId])
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([userId, orgId])
+  @@index([orgId])
+  @@index([userId])
+  @@index([status])
+}
+
+model Role {
+  id String @id @default(uuid())
+
+  orgId          String
+  name           String
+  description    String?
+  isSystemSeeded Boolean @default(false)
+
+  organisation Organisation     @relation(fields: [orgId], references: [id])
+  memberships  Membership[]
+  permissions  RolePermission[]
+  invitations  Invitation[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, name])
+  // Required by Membership.role so the database enforces same-org role assignment.
+  @@unique([id, orgId])
+  @@index([orgId])
+}
+
+model Invitation {
+  id String @id @default(uuid())
+
+  orgId                 String
+  targetType            InvitationTargetType
+  targetValue           String
+  normalizedTargetValue String
+
+  roleId    String
+  tokenHash String           @unique
+  status    InvitationStatus @default(PENDING)
+  expiresAt DateTime
+
+  invitedByUserId  String
+  acceptedByUserId String?
+
+  organisation   Organisation @relation(fields: [orgId], references: [id])
+  role           Role         @relation(fields: [roleId, orgId], references: [id, orgId])
+  invitedByUser  User         @relation("InvitedByUser", fields: [invitedByUserId], references: [id])
+  acceptedByUser User?        @relation("AcceptedByUser", fields: [acceptedByUserId], references: [id])
+
+  createdAt  DateTime  @default(now())
+  acceptedAt DateTime?
+  revokedAt  DateTime?
+
+  @@index([orgId])
+  @@index([targetType, normalizedTargetValue])
+  @@index([status])
+}
+
+model Permission {
+  id String @id @default(uuid())
+
+  key         String  @unique
+  module      String
+  action      String
+  subject     String
+  description String?
+
+  roles RolePermission[]
+
+  createdAt DateTime @default(now())
+}
+
+model RolePermission {
+  roleId       String
+  permissionId String
+
+  // Role deletion clears join rows; Permission deletion stays restricted for immutable seed data.
+  role       Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  permission Permission @relation(fields: [permissionId], references: [id])
+
+  createdAt DateTime @default(now())
+
+  @@id([roleId, permissionId])
+}
+
+model AuditLog {
+  id String @id @default(uuid())
+
+  orgId       String?
+  actorUserId String?
+  action      String
+  targetType  String
+  targetId    String?
+  metadata    Json?
+
+  ipAddress String?
+  userAgent String?
+
+  createdAt DateTime @default(now())
+
+  actorUser User? @relation(fields: [actorUserId], references: [id])
+
+  @@index([orgId])
+  @@index([orgId, createdAt])
+  @@index([actorUserId])
+  @@index([action])
+  @@index([targetType, targetId])
+  @@index([createdAt])
+}

package/template/prisma/seed.ts

@@ -0,0 +1,44 @@
+import { PrismaClient } from '@prisma/client';
+import { permissionKeys } from '../src/modules/access-control/types/permission-key';
+
+const prisma = new PrismaClient();
+
+function describePermission(key: string) {
+  const [module, action] = key.split('.');
+  return `${action} ${module}`.replaceAll('_', ' ');
+}
+
+async function main() {
+  await prisma.$transaction(
+    permissionKeys.map((key) => {
+      const [module, action] = key.split('.');
+
+      return prisma.permission.upsert({
+        where: { key },
+        update: {
+          module,
+          action,
+          subject: module,
+          description: describePermission(key),
+        },
+        create: {
+          key,
+          module,
+          action,
+          subject: module,
+          description: describePermission(key),
+        },
+      });
+    }),
+  );
+}
+
+main()
+  .then(async () => {
+    await prisma.$disconnect();
+  })
+  .catch(async (error) => {
+    console.error(error);
+    await prisma.$disconnect();
+    process.exit(1);
+  });

package/template/scripts/db-create.mjs

@@ -0,0 +1,126 @@
+import { existsSync, readFileSync } from 'fs';
+
+loadEnvFile();
+
+const { Client } = await import('pg').catch(() => {
+  throw new Error(
+    'The pg package is required for db:create. Run npm install first, then rerun npm run setup:local.',
+  );
+});
+
+const databaseUrls = collectDatabaseUrls();
+for (const databaseUrl of databaseUrls) {
+  await ensureDatabase(databaseUrl);
+}
+
+console.log('Database check complete.');
+
+function collectDatabaseUrls() {
+  const urls = new Set();
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    throw new Error('DATABASE_URL is required. Set it in .env or run npm run setup:local.');
+  }
+
+  urls.add(databaseUrl);
+  urls.add(process.env.TEST_DATABASE_URL || deriveTestDatabaseUrl(databaseUrl));
+  return [...urls];
+}
+
+async function ensureDatabase(databaseUrl) {
+  const parsed = new URL(databaseUrl);
+  const databaseName = decodeURIComponent(parsed.pathname.replace(/^\//u, ''));
+  if (!databaseName) {
+    throw new Error(`Database URL must include a database name: ${redactUrl(databaseUrl)}`);
+  }
+
+  const maintenanceUrl = new URL(databaseUrl);
+  maintenanceUrl.pathname = '/postgres';
+
+  const client = new Client({ connectionString: maintenanceUrl.toString() });
+  try {
+    await client.connect();
+  } catch (error) {
+    throw new Error(
+      [
+        `Could not connect to PostgreSQL at ${maintenanceUrl.host}.`,
+        'Start PostgreSQL locally or update DATABASE_URL in .env.',
+        `Original error: ${error.message}`,
+      ].join('\n'),
+      { cause: error },
+    );
+  }
+
+  try {
+    const existing = await client.query('SELECT 1 FROM pg_database WHERE datname = $1', [
+      databaseName,
+    ]);
+    if (existing.rowCount > 0) {
+      console.log(`[x] Database ${databaseName} exists`);
+      return;
+    }
+
+    await client.query(`CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+    console.log(`[x] Created database ${databaseName}`);
+  } finally {
+    await client.end();
+  }
+}
+
+function deriveTestDatabaseUrl(databaseUrl) {
+  const url = new URL(databaseUrl);
+  const databaseName = decodeURIComponent(url.pathname.replace(/^\//u, '')) || 'app';
+  url.pathname = `/${databaseName.endsWith('_test') ? databaseName : `${databaseName}_test`}`;
+  return url.toString();
+}
+
+function quoteIdentifier(value) {
+  return `"${value.replaceAll('"', '""')}"`;
+}
+
+function redactUrl(value) {
+  const url = new URL(value);
+  if (url.password) {
+    url.password = '***';
+  }
+  return url.toString();
+}
+
+function loadEnvFile() {
+  if (!existsSync('.env')) {
+    return;
+  }
+
+  const lines = readFileSync('.env', 'utf8').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const equalsIndex = trimmed.indexOf('=');
+    if (equalsIndex === -1) {
+      continue;
+    }
+
+    const key = trimmed.slice(0, equalsIndex).trim();
+    const rawValue = trimmed.slice(equalsIndex + 1).trim();
+    if (!key || process.env[key] !== undefined) {
+      continue;
+    }
+
+    process.env[key] = stripQuotes(rawValue);
+  }
+}
+
+function stripQuotes(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}

package/template/scripts/gen-module.mjs

@@ -0,0 +1,217 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+
+const rawName = process.argv[2];
+if (!rawName) {
+  throw new Error('Usage: npm run gen:module -- <module-name>');
+}
+
+const names = toNames(rawName);
+const moduleRoot = join('src', 'modules', names.kebab);
+const files = new Map([
+  [
+    join(moduleRoot, `${names.kebab}.module.ts`),
+    `import { Module } from '@nestjs/common';
+import { ${names.pascal}Controller } from './presentation/${names.kebab}.controller';
+import { ${names.pascal}Service } from './application/services/${names.kebab}.service';
+
+@Module({
+  controllers: [${names.pascal}Controller],
+  providers: [${names.pascal}Service],
+})
+export class ${names.pascal}Module {}
+`,
+  ],
+  [
+    join(moduleRoot, 'dto', `${names.kebab}-echo.dto.ts`),
+    `import { ApiProperty } from '@nestjs/swagger';
+import { IsString, MaxLength, MinLength } from 'class-validator';
+
+export class ${names.pascal}EchoDto {
+  @ApiProperty({ example: 'Hello from ${names.kebab}.' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  message!: string;
+}
+`,
+  ],
+  [
+    join(moduleRoot, 'application', 'services', `${names.kebab}.service.ts`),
+    `import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ${names.pascal}EchoDto } from '../../dto/${names.kebab}-echo.dto';
+
+@Injectable()
+export class ${names.pascal}Service {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  getStatus(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+
+    return {
+      ok: true,
+      orgId,
+      contextOrgId: this.requestContext.getOrgId(),
+      requestId: this.requestContext.getRequestId(),
+    };
+  }
+
+  async echo(user: AuthenticatedUser, orgId: string, dto: ${names.pascal}EchoDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const message = dto.message.trim();
+
+    await this.prisma.auditLog.create({
+      data: {
+        orgId,
+        actorUserId: user.id,
+        action: '${names.kebab}.echo',
+        targetType: '${names.pascal}',
+        targetId: orgId,
+        metadata: {
+          messageLength: message.length,
+          requestId: this.requestContext.getRequestId(),
+        } satisfies Prisma.InputJsonObject,
+      },
+    });
+
+    return {
+      orgId,
+      contextOrgId: this.requestContext.getOrgId(),
+      message,
+      requestId: this.requestContext.getRequestId(),
+    };
+  }
+}
+`,
+  ],
+  [
+    join(moduleRoot, 'presentation', `${names.kebab}.controller.ts`),
+    `import { Body, Controller, Get, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { CurrentUser } from '../../auth/presentation/current-user.decorator';
+import { AuthenticatedUser } from '../../auth/types/authenticated-user';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ${names.pascal}EchoDto } from '../dto/${names.kebab}-echo.dto';
+import { ${names.pascal}Service } from '../application/services/${names.kebab}.service';
+
+@ApiTags('${names.title}')
+@ApiBearerAuth()
+@Controller('organisations/:orgId/${names.kebab}')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ${names.pascal}Controller {
+  constructor(private readonly ${names.camel}Service: ${names.pascal}Service) {}
+
+  @Get('status')
+  @RequirePermissions('${names.permissionSubject}.read')
+  status(@Param('orgId') orgId: string) {
+    return this.${names.camel}Service.getStatus(orgId);
+  }
+
+  @Post('echo')
+  @HttpCode(200)
+  @RequirePermissions('${names.permissionSubject}.update')
+  echo(@CurrentUser() user: AuthenticatedUser, @Param('orgId') orgId: string, @Body() dto: ${names.pascal}EchoDto) {
+    return this.${names.camel}Service.echo(user, orgId, dto);
+  }
+}
+`,
+  ],
+  [
+    join('test', `${names.kebab}.spec.ts`),
+    `import { ${names.pascal}Service } from '../src/modules/${names.kebab}/application/services/${names.kebab}.service';
+
+describe('${names.pascal}Service', () => {
+  it('can be imported', () => {
+    expect(${names.pascal}Service).toBeDefined();
+  });
+});
+`,
+  ],
+]);
+
+for (const [path, content] of files) {
+  if (existsSync(path)) {
+    throw new Error(`Refusing to overwrite existing file: ${path}`);
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+appendPermissionKeys(names);
+appendRouteRegistryEntries(names);
+
+console.log(`Generated ${names.pascal}Module.`);
+console.log(`Add this to src/app.module.ts imports: ${names.pascal}Module`);
+console.log(`Import path: ./modules/${names.kebab}/${names.kebab}.module`);
+
+function appendPermissionKeys(names) {
+  const path = join('src', 'modules', 'access-control', 'types', 'permission-key.ts');
+  const source = readFileSync(path, 'utf8');
+  const keys = [`${names.permissionSubject}.read`, `${names.permissionSubject}.update`];
+  const missing = keys.filter((key) => !source.includes(`'${key}'`));
+  if (missing.length === 0) {
+    return;
+  }
+
+  const updated = source.replace(
+    '] as const;',
+    `${missing.map((key) => `  '${key}',`).join('\n')}\n] as const;`,
+  );
+  writeFileSync(path, updated);
+}
+
+function appendRouteRegistryEntries(names) {
+  const path = join('src', 'modules', 'access-control', 'types', 'route-permission-registry.ts');
+  const source = readFileSync(path, 'utf8');
+  const statusPath = `/organisations/:orgId/${names.kebab}/status`;
+  if (source.includes(statusPath)) {
+    return;
+  }
+
+  const entries = `  {
+    method: 'GET',
+    path: '${statusPath}',
+    permissions: ['${names.permissionSubject}.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/${names.kebab}/echo',
+    permissions: ['${names.permissionSubject}.update'],
+  },
+`;
+  writeFileSync(path, source.replace('];', `${entries}];`));
+}
+
+function toNames(value) {
+  const kebab = value
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+
+  if (!kebab) {
+    throw new Error('Module name must contain at least one letter or number.');
+  }
+
+  const parts = kebab.split('-');
+  const pascal = parts.map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join('');
+  return {
+    camel: `${pascal[0].toLowerCase()}${pascal.slice(1)}`,
+    kebab,
+    pascal,
+    permissionSubject: kebab,
+    title: parts.map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join(' '),
+  };
+}