AINATIVEM-44 move docker-compose into database generator, add builder pattern docs

Author: youssef-saber-3

CLAUDE.md

@@ -70,6 +70,32 @@ cli.ts (collects prompts)
 - **New generator**: add `src/generators/node/<feature>.ts` + `.test.ts`, call from `nodeGenerator`
 - **Modify generated scaffold**: edit template strings in the corresponding generator file
 
+## Builder Pattern
+
+The scaffold generator uses `NodeProjectBuilder` + `BuildStep` (`src/generators/node/projectBuilder.ts`) to compose features without scattering conditional logic across generators.
+
+**How it works:**
+- `BuildStep` interface: `execute(outputDir: string, options: GeneratorOptions): Promise<void>`
+- Each feature is a private class implementing `BuildStep` (e.g. `OAuthStep`, `DatabaseStep`)
+- `NodeProjectBuilder` queues steps and runs them in order via `.build()`
+- Named methods like `.addOAuth()`, `.addDatabase()` push steps unconditionally
+- `when(condition, fn)` adds steps conditionally at the call site in `index.ts` — never inside `execute()`
+
+**Adding a new feature:**
+1. Create a private `BuildStep` class in `projectBuilder.ts`
+2. Add a named method to `NodeProjectBuilder`: `addMyFeature(): this { return this.addStep(new MyFeatureStep()); }`
+3. Call it in `index.ts`, via `when()` if conditional:
+   ```ts
+   .when(options.webhooks, b => b.addWebhooks())
+   ```
+
+**Rule: never put conditional logic inside `execute()`** — use `when()` at the call site. Steps must be unconditional internally; the builder chain controls what runs.
+
+**File content helpers:**
+- Use `SourceFileBuilder` (`src/utils/sourceFileBuilder.ts`) for TypeScript files with conditional imports or blocks — handles deduplication and formatting automatically
+- Use `RouterMountBuilder` (`src/utils/templates.ts`) to accumulate `app.use()` calls conditionally
+- Use plain `dedent` for static content (YAML, JSON, `.env`, SQL)
+
 ## MVP Scope
 
 The initial implementation targets:

src/generators/node/database.test.ts

@@ -184,3 +184,30 @@ describe('generateDatabase — drizzle.config.ts', () => {
 		expect(content).toContain('sqlite');
 	});
 });
+
+describe('generateDatabase — docker-compose.yml', () => {
+	it('generates docker-compose.yml for postgres with healthcheck', async () => {
+		const { generateDatabase } = await import('./database.js');
+		await generateDatabase(tmpDir, pgOptions);
+		expect(await exists(join(tmpDir, 'docker-compose.yml'))).toBe(true);
+		const content = await read('docker-compose.yml');
+		expect(content).toContain('postgres:16');
+		expect(content).toContain('pg_isready');
+		expect(content).toContain('healthcheck');
+	});
+
+	it('generates docker-compose.yml for mysql with healthcheck', async () => {
+		const { generateDatabase } = await import('./database.js');
+		await generateDatabase(tmpDir, mysqlOptions);
+		const content = await read('docker-compose.yml');
+		expect(content).toContain('mysql:8');
+		expect(content).toContain('mysqladmin');
+		expect(content).toContain('healthcheck');
+	});
+
+	it('does not generate docker-compose.yml for sqlite', async () => {
+		const { generateDatabase } = await import('./database.js');
+		await generateDatabase(tmpDir, sqliteOptions);
+		expect(await exists(join(tmpDir, 'docker-compose.yml'))).toBe(false);
+	});
+});

src/generators/node/database.ts

@@ -9,6 +9,9 @@ export async function generateDatabase(outputDir: string, options: GeneratorOpti
 	await generateMigrate(outputDir, options);
 	await generateMigrationSql(outputDir, options);
 	await generateDrizzleConfig(outputDir, options);
+	if (options.database === 'postgres' || options.database === 'mysql') {
+		await generateDockerCompose(outputDir, options);
+	}
 }
 
 async function generateSchema(outputDir: string, options: GeneratorOptions): Promise<void> {
@@ -232,6 +235,55 @@ function migrationSqlContent(database: GeneratorOptions['database']): string {
 	`;
 }
 
+async function generateDockerCompose(outputDir: string, options: GeneratorOptions): Promise<void> {
+	const content =
+		options.database === 'postgres'
+			? dedent`
+				services:
+				  db:
+				    image: postgres:16
+				    environment:
+				      POSTGRES_USER: app
+				      POSTGRES_PASSWORD: app
+				      POSTGRES_DB: ${options.projectName}
+				    ports:
+				      - '5432:5432'
+				    volumes:
+				      - db_data:/var/lib/postgresql/data
+				    healthcheck:
+				      test: ['CMD', 'pg_isready', '-U', 'app']
+				      interval: 5s
+				      timeout: 5s
+				      retries: 5
+
+				volumes:
+				  db_data:
+			`
+			: dedent`
+				services:
+				  db:
+				    image: mysql:8
+				    environment:
+				      MYSQL_ROOT_PASSWORD: app
+				      MYSQL_DATABASE: ${options.projectName}
+				      MYSQL_USER: app
+				      MYSQL_PASSWORD: app
+				    ports:
+				      - '3306:3306'
+				    volumes:
+				      - db_data:/var/lib/mysql
+				    healthcheck:
+				      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-u', 'app', '--password=app']
+				      interval: 5s
+				      timeout: 5s
+				      retries: 5
+
+				volumes:
+				  db_data:
+			`;
+	await writeFile(join(outputDir, 'docker-compose.yml'), content);
+}
+
 async function generateDrizzleConfig(outputDir: string, options: GeneratorOptions): Promise<void> {
 	const dialectMap: Record<GeneratorOptions['database'], string> = {
 		postgres: 'postgresql',

src/generators/node/index.ts

@@ -8,8 +8,6 @@ export const nodeGenerator: Generator = {
 			.addDatabase()
 			.addApp()
 			.when(options.webhooks, (b) => b.addWebhooks())
-			.when(options.database === 'postgres', (b) => b.addPostgres())
-			.when(options.database === 'mysql', (b) => b.addMySQL())
 			.when(options.appExtensions.length > 0, (b) => b.addAppExtensions())
 			.addPipedriveClient()
 			.addServerEntry()

src/generators/node/projectBuilder.test.ts

@@ -67,24 +67,3 @@ describe('NodeProjectBuilder', () => {
 	});
 });
 
-describe('PostgresDockerStep', () => {
-	it('generates docker-compose.yml with healthcheck', async () => {
-		await new NodeProjectBuilder(tmpDir, options).addPostgres().build();
-		expect(await exists(join(tmpDir, 'docker-compose.yml'))).toBe(true);
-		const content = await read('docker-compose.yml');
-		expect(content).toContain('postgres:16');
-		expect(content).toContain('healthcheck');
-		expect(content).toContain('pg_isready');
-	});
-});
-
-describe('MySQLDockerStep', () => {
-	it('generates docker-compose.yml with healthcheck', async () => {
-		const mysqlOptions: GeneratorOptions = { ...options, database: 'mysql' };
-		await new NodeProjectBuilder(tmpDir, mysqlOptions).addMySQL().build();
-		const content = await read('docker-compose.yml');
-		expect(content).toContain('mysql:8');
-		expect(content).toContain('healthcheck');
-		expect(content).toContain('mysqladmin');
-	});
-});

src/generators/node/projectBuilder.ts

@@ -146,64 +146,6 @@ class EnvExampleStep implements BuildStep {
 	}
 }
 
-class PostgresDockerStep implements BuildStep {
-	async execute(outputDir: string, options: GeneratorOptions): Promise<void> {
-		await writeFile(
-			join(outputDir, 'docker-compose.yml'),
-			dedent`
-				services:
-				  db:
-				    image: postgres:16
-				    environment:
-				      POSTGRES_USER: app
-				      POSTGRES_PASSWORD: app
-				      POSTGRES_DB: ${options.projectName}
-				    ports:
-				      - '5432:5432'
-				    volumes:
-				      - db_data:/var/lib/postgresql/data
-				    healthcheck:
-				      test: ['CMD', 'pg_isready', '-U', 'app']
-				      interval: 5s
-				      timeout: 5s
-				      retries: 5
-
-				volumes:
-				  db_data:
-			`,
-		);
-	}
-}
-
-class MySQLDockerStep implements BuildStep {
-	async execute(outputDir: string, options: GeneratorOptions): Promise<void> {
-		await writeFile(
-			join(outputDir, 'docker-compose.yml'),
-			dedent`
-				services:
-				  db:
-				    image: mysql:8
-				    environment:
-				      MYSQL_ROOT_PASSWORD: app
-				      MYSQL_DATABASE: ${options.projectName}
-				      MYSQL_USER: app
-				      MYSQL_PASSWORD: app
-				    ports:
-				      - '3306:3306'
-				    volumes:
-				      - db_data:/var/lib/mysql
-				    healthcheck:
-				      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-u', 'app', '--password=app']
-				      interval: 5s
-				      timeout: 5s
-				      retries: 5
-
-				volumes:
-				  db_data:
-			`,
-		);
-	}
-}
 
 export class NodeProjectBuilder {
 	private steps: BuildStep[] = [];
@@ -230,12 +172,6 @@ export class NodeProjectBuilder {
 	addWebhooks(): this {
 		return this.addStep(new WebhooksStep());
 	}
-	addPostgres(): this {
-		return this.addStep(new PostgresDockerStep());
-	}
-	addMySQL(): this {
-		return this.addStep(new MySQLDockerStep());
-	}
 	addAppExtensions(): this {
 		return this.addStep(new AppExtensionsStep());
 	}