feat(backend): deterministic seed API and safer user updates for dev data

- Add SeedDevOptions (faker seed, user count clamp, fixed createdAt upper bound)
  and stable nbw-seed-* emails; document limits in seed.types.
- Extend GET /seed/seed-dev with optional query params; await seeding; guard when
  NODE_ENV is not development.
- Fix socialLinks seeding via a plain object; expand seed controller/service tests.
- UserService.update now applies $set from toObject() and strips nested _id to
  avoid Mongoose circular-reference errors on findByIdAndUpdate.

Author: tomast1337

CONTRIBUTING.md

@@ -21,22 +21,37 @@ You'll need the following installed on your machine:
 - [Docker](https://www.docker.com/)
 - [Docker Compose](https://docs.docker.com/compose/)
 
-We provide a `docker-compose-dev.yml` file that sets up:
+We provide [`docker-compose.yml`](docker-compose.yml) at the repository root. It defines:
 
-- A MongoDB instance
-- A local mail server (`maildev`)
-- An S3-compatible storage (`minio`)
-- A MinIO client
+- **MongoDB**
+- **MailDev** (SMTP + web UI for local email)
+- **MinIO** (S3-compatible storage)
+- A **MinIO client** job (profile `minio-init`) that creates buckets and CORS—**not** started by a plain `docker compose up`
 
-To start the services, run the following in the root directory:
+Start dependencies from the repo root in one of these ways:
+
+**Recommended** (waits for MongoDB and MinIO to be healthy, then runs bucket setup):
+
+```bash
+bun run docker:up
+```
+
+**Manual** (then create buckets once; uploads will fail with `NoSuchBucket` until you do):
+
+```bash
+docker compose up -d
+bun run docker:minio-init
+```
+
+To tear down volumes and start clean (still runs MinIO init after `up --wait`):
 
 ```bash
-docker-compose -f docker-compose.yml up -d
+bun run docker:reset:fresh
 ```
 
-> Remove the `-d` flag if you'd like to see container logs in your terminal.
+> Drop `-d` on `docker compose up -d` if you prefer logs attached to your terminal.
 
-You can find authentication details in the [`docker-compose.yml`](docker-compose.yml) file.
+Ports and default credentials (Mongo, MinIO, MailDev) are in [`docker-compose.yml`](docker-compose.yml). Match the MinIO bucket names and keys in your backend `.env` (see the example block under **Environment Variables** below).
 
 ---
 

apps/backend/.env.development.example

@@ -23,6 +23,15 @@ APP_DOMAIN=
 
 RECAPTCHA_KEY=
 
+# MinIO from repo docker-compose: after `docker compose up -d` (or `bun run docker:up`),
+# create buckets once with `bun run docker:minio-init` from the monorepo root (see root package.json).
+# Example local values (match docker-compose mc bucket names):
+# S3_ENDPOINT=http://localhost:9000
+# S3_BUCKET_SONGS=noteblockworld-songs
+# S3_BUCKET_THUMBS=noteblockworld-thumbs
+# S3_KEY=minioadmin
+# S3_SECRET=minioadmin
+# S3_REGION=us-east-1
 S3_ENDPOINT=
 S3_BUCKET_SONGS=
 S3_BUCKET_THUMBS=

apps/backend/src/seed/seed.controller.spec.ts

@@ -1,26 +1,140 @@
+import { BadRequestException } from '@nestjs/common';
 import { Test, TestingModule } from '@nestjs/testing';
 
 import { SeedController } from './seed.controller';
 import { SeedService } from './seed.service';
+import {
+  DEFAULT_SEED_DATA_TIME_CAP,
+  DEFAULT_SEED_FAKER,
+  SEED_USER_COUNT_MAX,
+} from './seed.types';
 
 describe('SeedController', () => {
   let controller: SeedController;
+  let seedService: { seedDev: jest.Mock };
+
+  async function createController(nodeEnv: string) {
+    seedService = { seedDev: jest.fn().mockResolvedValue(undefined) };
 
-  beforeEach(async () => {
     const module: TestingModule = await Test.createTestingModule({
       controllers: [SeedController],
       providers: [
-        {
-          provide: SeedService,
-          useValue: {},
-        },
+        { provide: SeedService, useValue: seedService },
+        { provide: 'NODE_ENV', useValue: nodeEnv },
       ],
     }).compile();
 
-    controller = module.get<SeedController>(SeedController);
+    return module.get<SeedController>(SeedController);
+  }
+
+  beforeEach(async () => {
+    controller = await createController('development');
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
   });
 
   it('should be defined', () => {
     expect(controller).toBeDefined();
   });
+
+  describe('seed', () => {
+    it('calls seedDev with defaults when query params are omitted', async () => {
+      const result = await controller.seed(undefined, undefined, undefined);
+
+      expect(seedService.seedDev).toHaveBeenCalledTimes(1);
+      expect(seedService.seedDev).toHaveBeenLastCalledWith({
+        fakerSeed: DEFAULT_SEED_FAKER,
+        userCount: 100,
+      });
+      expect(result).toMatchObject({
+        message: 'Seeding complete',
+        fakerSeed: DEFAULT_SEED_FAKER,
+        userCount: 100,
+        createdAtUpper: DEFAULT_SEED_DATA_TIME_CAP.toISOString(),
+      });
+    });
+
+    it('parses fakerSeed and userCount from query strings', async () => {
+      await controller.seed('7', '12', undefined);
+
+      expect(seedService.seedDev).toHaveBeenLastCalledWith({
+        fakerSeed: 7,
+        userCount: 12,
+      });
+    });
+
+    it('passes createdAtUpper when a valid ISO string is provided', async () => {
+      const iso = '2024-03-01T15:30:00.000Z';
+      await controller.seed(undefined, undefined, iso);
+
+      expect(seedService.seedDev).toHaveBeenLastCalledWith({
+        fakerSeed: DEFAULT_SEED_FAKER,
+        userCount: 100,
+        createdAtUpper: new Date(iso),
+      });
+    });
+
+    it('clamps userCount to the configured maximum', async () => {
+      await controller.seed(
+        undefined,
+        String(SEED_USER_COUNT_MAX + 999),
+        undefined,
+      );
+
+      expect(seedService.seedDev).toHaveBeenLastCalledWith({
+        fakerSeed: DEFAULT_SEED_FAKER,
+        userCount: SEED_USER_COUNT_MAX,
+      });
+    });
+
+    it('clamps userCount to at least 1', async () => {
+      await controller.seed(undefined, '0', undefined);
+
+      expect(seedService.seedDev).toHaveBeenLastCalledWith({
+        fakerSeed: DEFAULT_SEED_FAKER,
+        userCount: 1,
+      });
+    });
+
+    it('throws BadRequest when fakerSeed is not an integer', async () => {
+      await expect(
+        controller.seed('not-int', undefined, undefined),
+      ).rejects.toThrow(BadRequestException);
+      await expect(
+        controller.seed('not-int', undefined, undefined),
+      ).rejects.toThrow('fakerSeed must be an integer');
+      expect(seedService.seedDev).not.toHaveBeenCalled();
+    });
+
+    it('throws BadRequest when userCount is not an integer', async () => {
+      await expect(controller.seed(undefined, 'x', undefined)).rejects.toThrow(
+        BadRequestException,
+      );
+      expect(seedService.seedDev).not.toHaveBeenCalled();
+    });
+
+    it('throws BadRequest when createdAtUpper is not a valid date', async () => {
+      await expect(
+        controller.seed(undefined, undefined, 'not-a-date'),
+      ).rejects.toThrow(BadRequestException);
+      await expect(
+        controller.seed(undefined, undefined, 'not-a-date'),
+      ).rejects.toThrow('createdAtUpper must be a valid ISO 8601 date string');
+      expect(seedService.seedDev).not.toHaveBeenCalled();
+    });
+
+    it('throws BadRequest when NODE_ENV is not development', async () => {
+      const prodController = await createController('production');
+
+      await expect(
+        prodController.seed(undefined, undefined, undefined),
+      ).rejects.toThrow(BadRequestException);
+      await expect(
+        prodController.seed(undefined, undefined, undefined),
+      ).rejects.toThrow('Seeding is only allowed in development mode');
+      expect(seedService.seedDev).not.toHaveBeenCalled();
+    });
+  });
 });

apps/backend/src/seed/seed.controller.ts

@@ -1,21 +1,130 @@
-import { Controller, Get } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+  BadRequestException,
+  Controller,
+  Get,
+  Inject,
+  Query,
+} from '@nestjs/common';
+import { ApiOperation, ApiQuery, ApiTags } from '@nestjs/swagger';
 
 import { SeedService } from './seed.service';
+import {
+  DEFAULT_SEED_DATA_TIME_CAP,
+  DEFAULT_SEED_FAKER,
+  SEED_USER_COUNT_MAX,
+  SEED_USER_COUNT_MIN,
+  type SeedDevOptions,
+} from './seed.types';
 
 @Controller('seed')
 @ApiTags('seed')
 export class SeedController {
-  constructor(private readonly seedService: SeedService) {}
+  constructor(
+    private readonly seedService: SeedService,
+    @Inject('NODE_ENV')
+    private readonly NODE_ENV: string,
+  ) {}
 
   @Get('seed-dev')
   @ApiOperation({
-    summary: 'Seed the database with development data',
+    summary:
+      'Seed the database with development data (deterministic by default)',
+    description:
+      'Uses a fixed Faker seed and stable user emails unless overridden. ' +
+      'Use a fresh database or expect "email already registered" on repeat. ' +
+      'Song `publicId` values still use random nanoids from the upload pipeline.',
   })
-  async seed() {
-    this.seedService.seedDev();
+  @ApiQuery({
+    name: 'fakerSeed',
+    required: false,
+    type: Number,
+    example: DEFAULT_SEED_FAKER,
+  })
+  @ApiQuery({
+    name: 'userCount',
+    required: false,
+    type: Number,
+    example: 20,
+    description: `Clamped to ${SEED_USER_COUNT_MIN}–${SEED_USER_COUNT_MAX}.`,
+  })
+  @ApiQuery({
+    name: 'createdAtUpper',
+    required: false,
+    type: String,
+    example: DEFAULT_SEED_DATA_TIME_CAP.toISOString(),
+    description: 'ISO 8601 upper bound for random user/song createdAt.',
+  })
+  async seed(
+    @Query('fakerSeed') fakerSeedRaw?: string,
+    @Query('userCount') userCountRaw?: string,
+    @Query('createdAtUpper') createdAtUpperIso?: string,
+  ) {
+    if (this.NODE_ENV !== 'development') {
+      throw new BadRequestException(
+        'Seeding is only allowed in development mode',
+      );
+    }
+    const fakerSeed = parseOptionalIntQuery(
+      fakerSeedRaw,
+      DEFAULT_SEED_FAKER,
+      'fakerSeed',
+    );
+    const userCount = parseOptionalIntQuery(
+      userCountRaw,
+      100,
+      'userCount',
+      SEED_USER_COUNT_MIN,
+      SEED_USER_COUNT_MAX,
+    );
+
+    const options: SeedDevOptions = { fakerSeed, userCount };
+
+    if (createdAtUpperIso !== undefined && createdAtUpperIso !== '') {
+      const d = new Date(createdAtUpperIso);
+      if (Number.isNaN(d.getTime())) {
+        throw new BadRequestException(
+          'createdAtUpper must be a valid ISO 8601 date string',
+        );
+      }
+      options.createdAtUpper = d;
+    }
+
+    await this.seedService.seedDev(options);
+
     return {
-      message: 'Seeding in progress',
+      message: 'Seeding complete',
+      fakerSeed: options.fakerSeed,
+      userCount: options.userCount,
+      createdAtUpper: (
+        options.createdAtUpper ?? DEFAULT_SEED_DATA_TIME_CAP
+      ).toISOString(),
     };
   }
 }
+
+function parseOptionalIntQuery(
+  raw: string | undefined,
+  fallback: number,
+  name: string,
+  min?: number,
+  max?: number,
+): number {
+  if (raw === undefined || raw === '') {
+    return fallback;
+  }
+
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) {
+    throw new BadRequestException(`${name} must be an integer`);
+  }
+
+  let v = Math.trunc(n);
+  if (min !== undefined) {
+    v = Math.max(min, v);
+  }
+  if (max !== undefined) {
+    v = Math.min(max, v);
+  }
+
+  return v;
+}