@ftisindia/create-app 0.1.0

package/template/scripts/seed-test-user-org.ts

@@ -0,0 +1,264 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import bcrypt from 'bcryptjs';
+import { randomBytes } from 'crypto';
+import { AuthProvider, MembershipStatus, Prisma, PrismaClient } from '@prisma/client';
+import {
+  defaultOrganisationRoles,
+  defaultOrganisationSettings,
+} from '../src/modules/organisations/types/default-organisation-data';
+
+loadEnvFile();
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required. Set it in .env before running this script.');
+}
+
+const prisma = new PrismaClient({
+  datasources: {
+    db: {
+      url: databaseUrl,
+    },
+  },
+});
+
+const email = normalizeEmail(process.env.TEST_USER_EMAIL ?? 'owner@example.com');
+const configuredPassword = process.env.TEST_USER_PASSWORD?.trim();
+const password = configuredPassword || randomBytes(18).toString('base64url');
+const displayName = process.env.TEST_USER_DISPLAY_NAME ?? 'Starter Owner';
+const orgName = process.env.TEST_ORG_NAME ?? 'Demo Organisation';
+const orgSlug = normalizeSlug(process.env.TEST_ORG_SLUG ?? 'demo');
+
+async function main() {
+  assertSafeEnvironment();
+  assertPassword(password);
+
+  const passwordHash = await bcrypt.hash(password, 12);
+
+  const result = await prisma.$transaction(async (tx) => {
+    const user = await tx.user.upsert({
+      where: { email },
+      update: {
+        displayName,
+        passwordHash,
+        isActive: true,
+      },
+      create: {
+        email,
+        displayName,
+        passwordHash,
+        isActive: true,
+      },
+    });
+
+    await tx.authIdentity.upsert({
+      where: {
+        provider_providerUserId: {
+          provider: AuthProvider.EMAIL_PASSWORD,
+          providerUserId: email,
+        },
+      },
+      update: {
+        userId: user.id,
+        email,
+      },
+      create: {
+        userId: user.id,
+        provider: AuthProvider.EMAIL_PASSWORD,
+        providerUserId: email,
+        email,
+      },
+    });
+
+    const organisation = await tx.organisation.upsert({
+      where: { slug: orgSlug },
+      update: {
+        name: orgName,
+      },
+      create: {
+        name: orgName,
+        slug: orgSlug,
+      },
+    });
+
+    const roles = await Promise.all(
+      defaultOrganisationRoles.map((roleName) =>
+        tx.role.upsert({
+          where: {
+            orgId_name: {
+              orgId: organisation.id,
+              name: roleName,
+            },
+          },
+          update: {
+            isSystemSeeded: true,
+          },
+          create: {
+            orgId: organisation.id,
+            name: roleName,
+            isSystemSeeded: true,
+          },
+        }),
+      ),
+    );
+
+    const ownerRole = roles.find((role) => role.name === 'Owner');
+    if (!ownerRole) {
+      throw new Error('Owner role was not seeded.');
+    }
+
+    await Promise.all(
+      defaultOrganisationSettings.map((setting) =>
+        tx.organisationSetting.upsert({
+          where: {
+            orgId_key: {
+              orgId: organisation.id,
+              key: setting.key,
+            },
+          },
+          update: {},
+          create: {
+            orgId: organisation.id,
+            key: setting.key,
+            value: setting.value,
+          },
+        }),
+      ),
+    );
+
+    const membership = await tx.membership.upsert({
+      where: {
+        userId_orgId: {
+          userId: user.id,
+          orgId: organisation.id,
+        },
+      },
+      update: {
+        roleId: ownerRole.id,
+        status: MembershipStatus.ACTIVE,
+        isOwner: true,
+        isBillingContact: true,
+      },
+      create: {
+        userId: user.id,
+        orgId: organisation.id,
+        roleId: ownerRole.id,
+        status: MembershipStatus.ACTIVE,
+        isOwner: true,
+        isBillingContact: true,
+      },
+    });
+
+    await tx.auditLog.create({
+      data: {
+        orgId: organisation.id,
+        actorUserId: user.id,
+        action: 'bootstrap.test_user_org',
+        targetType: 'Organisation',
+        targetId: organisation.id,
+        metadata: {
+          email,
+          orgSlug,
+          membershipId: membership.id,
+        } satisfies Prisma.InputJsonObject,
+      },
+    });
+
+    return { membership, organisation, user };
+  });
+
+  console.log('Test user and organisation are ready.');
+  console.log(`Email: ${email}`);
+  if (configuredPassword) {
+    console.log('Password: value from TEST_USER_PASSWORD');
+  } else {
+    console.log(`Generated password: ${password}`);
+  }
+  console.log(`Organisation: ${result.organisation.name} (${result.organisation.slug})`);
+  console.log(`Organisation ID: ${result.organisation.id}`);
+  console.log(`Membership ID: ${result.membership.id}`);
+}
+
+function assertSafeEnvironment() {
+  const nodeEnv = process.env.NODE_ENV ?? 'development';
+  const isSafeDefaultEnvironment = nodeEnv === 'development' || nodeEnv === 'test';
+  if (!isSafeDefaultEnvironment && process.env.ALLOW_TEST_BOOTSTRAP !== 'true') {
+    throw new Error(
+      'Refusing to seed test user/org outside development/test. Set ALLOW_TEST_BOOTSTRAP=true to override.',
+    );
+  }
+}
+
+function assertPassword(value: string) {
+  if (value.length < 8 || value.length > 128) {
+    throw new Error('TEST_USER_PASSWORD must be between 8 and 128 characters.');
+  }
+}
+
+function loadEnvFile() {
+  const envPath = resolve(process.cwd(), '.env');
+  if (!existsSync(envPath)) {
+    return;
+  }
+
+  const lines = readFileSync(envPath, '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: string) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+function normalizeEmail(value: string) {
+  return value.trim().toLowerCase();
+}
+
+function normalizeSlug(value: string) {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!slug) {
+    throw new Error('TEST_ORG_SLUG must contain at least one letter or number.');
+  }
+
+  return slug;
+}
+
+main()
+  .then(async () => {
+    await prisma.$disconnect();
+  })
+  .catch(async (error) => {
+    console.error(error);
+    await prisma.$disconnect();
+    process.exit(1);
+  });

package/template/scripts/setup-local.mjs

@@ -0,0 +1,224 @@
+import { spawn } from 'child_process';
+import { randomBytes } from 'crypto';
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { createInterface } from 'readline/promises';
+
+const DEFAULT_DATABASE_URL = 'postgresql://postgres:postgres@localhost:5432/app';
+const ENV_FILE = '.env';
+const ENV_EXAMPLE_FILE = '.env.example';
+
+const yes = process.argv.includes('--yes') || process.argv.includes('-y') || !process.stdin.isTTY;
+const envUpdates = ensureLocalEnv();
+
+printHeader(envUpdates);
+
+if (!yes) {
+  const confirmed = await confirm('Create local databases, run migrations, and seed demo data?');
+  if (!confirmed) {
+    console.log('Setup cancelled. No database changes were made.');
+    process.exit(0);
+  }
+}
+
+const steps = [
+  { label: 'Create local databases if missing', command: 'npm run db:create' },
+  { label: 'Generate Prisma client', command: 'npm run prisma:generate' },
+  {
+    label: 'Apply Prisma migrations',
+    command: 'npm run prisma:deploy',
+    retryOnP1001: true,
+  },
+  { label: 'Seed permission catalogue', command: 'npm run prisma:seed' },
+  {
+    label: 'Seed demo owner and organisation',
+    command: 'npm run seed:test-user-org',
+  },
+];
+
+for (const step of steps) {
+  await runStep(step);
+}
+
+printDone();
+
+async function runStep(step) {
+  const maxAttempts = step.retryOnP1001 ? 2 : 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    console.log(`\n[ ] ${step.label}`);
+    const result = await run(step.command);
+
+    if (result.code === 0) {
+      console.log(`[x] ${step.label}`);
+      return;
+    }
+
+    const canRetry = step.retryOnP1001 && attempt < maxAttempts && result.output.includes('P1001');
+    if (!canRetry) {
+      console.error(`[!] ${step.label} failed.`);
+      process.exit(result.code ?? 1);
+    }
+
+    console.warn('Prisma reported P1001. Retrying once...');
+  }
+}
+
+function ensureLocalEnv() {
+  if (!existsSync(ENV_FILE)) {
+    if (!existsSync(ENV_EXAMPLE_FILE)) {
+      throw new Error('.env.example was not found.');
+    }
+
+    copyFileSync(ENV_EXAMPLE_FILE, ENV_FILE);
+  }
+
+  const current = loadEnvFile();
+  const updates = new Map();
+  const databaseUrl = current.DATABASE_URL || DEFAULT_DATABASE_URL;
+
+  if (!current.DATABASE_URL) {
+    updates.set('DATABASE_URL', databaseUrl);
+  }
+
+  if (!current.TEST_DATABASE_URL) {
+    updates.set('TEST_DATABASE_URL', deriveTestDatabaseUrl(databaseUrl));
+  }
+
+  if (!current.JWT_SECRET) {
+    updates.set('JWT_SECRET', randomBytes(32).toString('base64url'));
+  }
+
+  if (!current.TEST_USER_PASSWORD) {
+    updates.set('TEST_USER_PASSWORD', randomBytes(18).toString('base64url'));
+  }
+
+  if (updates.size > 0) {
+    writeEnvUpdates(updates);
+  }
+
+  return updates;
+}
+
+function loadEnvFile() {
+  if (!existsSync(ENV_FILE)) {
+    return {};
+  }
+
+  const env = {};
+  for (const line of readFileSync(ENV_FILE, 'utf8').split(/\r?\n/)) {
+    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 value = trimmed.slice(equalsIndex + 1).trim();
+    env[key] = stripQuotes(value);
+  }
+
+  return env;
+}
+
+function writeEnvUpdates(updates) {
+  const lines = existsSync(ENV_FILE) ? readFileSync(ENV_FILE, 'utf8').split(/\r?\n/) : [];
+  const seen = new Set();
+  const updated = lines.map((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=/);
+    if (!match || !updates.has(match[1])) {
+      return line;
+    }
+
+    seen.add(match[1]);
+    return `${match[1]}=${updates.get(match[1])}`;
+  });
+
+  for (const [key, value] of updates) {
+    if (!seen.has(key)) {
+      updated.push(`${key}=${value}`);
+    }
+  }
+
+  writeFileSync(ENV_FILE, `${updated.join('\n').replace(/\n+$/u, '')}\n`);
+}
+
+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 printHeader(updates) {
+  console.log('\nFoundation starter local setup');
+  console.log(
+    'This command is non-destructive: it creates missing databases, deploys migrations, and upserts seed data.',
+  );
+  console.log('\nChecklist:');
+  console.log(`[x] ${ENV_FILE} exists`);
+  for (const key of ['DATABASE_URL', 'TEST_DATABASE_URL', 'JWT_SECRET', 'TEST_USER_PASSWORD']) {
+    const status = updates.has(key) ? 'created' : 'already set';
+    console.log(`[x] ${key} ${status}`);
+  }
+}
+
+function printDone() {
+  const latestEnv = loadEnvFile();
+  console.log('\nLocal setup complete.');
+  console.log('\nDemo login');
+  console.log(`Email: ${latestEnv.TEST_USER_EMAIL || 'owner@example.com'}`);
+  console.log(`Password: ${latestEnv.TEST_USER_PASSWORD}`);
+  console.log(`Organisation slug: ${latestEnv.TEST_ORG_SLUG || 'demo'}`);
+  console.log('\nNext command: npm run start:dev');
+  console.log(
+    'Then open http://localhost:3000/docs and authorize with the login response access token.',
+  );
+}
+
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} [Y/n] `);
+    return answer.trim().toLowerCase() !== 'n';
+  } finally {
+    rl.close();
+  }
+}
+
+function run(command) {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      env: process.env,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let output = '';
+    child.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      output += text;
+      process.stdout.write(text);
+    });
+    child.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      output += text;
+      process.stderr.write(text);
+    });
+    child.once('exit', (code) => resolve({ code, output }));
+  });
+}
+
+function stripQuotes(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}

package/template/scripts/test-db.mjs

@@ -0,0 +1,69 @@
+import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+
+loadEnvFile();
+
+const testDatabaseUrl = process.env.TEST_DATABASE_URL;
+if (!testDatabaseUrl) {
+  throw new Error('TEST_DATABASE_URL is required for npm run test:e2e.');
+}
+
+await run('npm run db:create');
+await run('npx prisma migrate deploy', { DATABASE_URL: testDatabaseUrl });
+await run('npx prisma db seed', { DATABASE_URL: testDatabaseUrl });
+
+function run(command, env = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      env: { ...process.env, ...env },
+      shell: true,
+      stdio: 'inherit',
+    });
+
+    child.once('exit', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`${command} exited with code ${code}`));
+    });
+  });
+}
+
+function loadEnvFile() {
+  if (!existsSync('.env')) {
+    return;
+  }
+
+  for (const line of readFileSync('.env', 'utf8').split(/\r?\n/)) {
+    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/src/app.module.ts

@@ -0,0 +1,58 @@
+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: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      cache: true,
+      expandVariables: true,
+      load: [appConfig, authConfig, databaseConfig, rbacConfig],
+      validate,
+    }),
+    ThrottlerModule.forRoot([
+      {
+        ttl: 60_000,
+        limit: 100,
+      },
+    ]),
+    PrismaModule,
+    HealthModule,
+    AuthModule,
+    RequestContextModule,
+    AccessControlModule,
+    AuditModule,
+    OrganisationsModule,
+    MembershipsModule,
+    InvitationsModule,
+    SettingsModule,
+    SampleModule,
+  ],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+  ],
+})
+export class AppModule {}

package/template/src/common/decorators/.gitkeep

@@ -0,0 +1 @@
+# keep

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

@@ -0,0 +1,17 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+class ErrorBodyDto {
+  @ApiProperty({ example: "BAD_REQUEST" })
+  code!: string;
+
+  @ApiProperty({ example: "Validation failed." })
+  message!: string;
+
+  @ApiPropertyOptional({ type: Object })
+  details?: Record<string, unknown>;
+}
+
+export class ErrorResponseDto {
+  @ApiProperty({ type: ErrorBodyDto })
+  error!: ErrorBodyDto;
+}

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

@@ -0,0 +1,51 @@
+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",
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+  })
+  userId!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  roleId!: string;
+
+  @ApiProperty({ enum: MembershipStatus, example: MembershipStatus.ACTIVE })
+  status!: MembershipStatus;
+
+  @ApiProperty({ example: true })
+  isOwner!: boolean;
+
+  @ApiProperty({ example: true })
+  isBillingContact!: boolean;
+
+  @ApiPropertyOptional({ type: ActiveUserSummaryDto })
+  user?: ActiveUserSummaryDto;
+
+  @ApiPropertyOptional({ type: RoleSummaryDto })
+  role?: RoleSummaryDto;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  updatedAt!: string;
+}

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

@@ -0,0 +1,11 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class DeletedResponseDto {
+  @ApiProperty({ example: true })
+  deleted!: boolean;
+}
+
+export class RevokedResponseDto {
+  @ApiProperty({ example: true })
+  revoked!: boolean;
+}