@pattern-stack/codegen 0.6.8 → 0.7.0

package/templates/entity/new/backend/domain/entity.ejs.t

@@ -16,23 +16,6 @@ force: true
 <% if (hasEntityRefFields) { -%>
 import type { EntityType } from '<%= locations.dbSchemaServer.import %>';
 <% } -%>
-<%
-// Collect unique non-self-referential imports
-const importedEntities = new Set();
-[...belongsToRelations, ...hasManyRelations, ...hasOneRelations].forEach((rel) => {
-  if (rel.target !== name) {
-    importedEntities.add(rel.target);
-  }
-});
--%>
-<% if (importedEntities.size > 0) { -%>
-
-<% importedEntities.forEach((target) => {
-  const targetClass = target.charAt(0).toUpperCase() + target.slice(1).replace(/_([a-z])/g, (_, c) => c.toUpperCase());
--%>
-import type { <%= targetClass %> } from '../<%= target %>/<%= target %>.entity';
-<% }) -%>
-<% } -%>
 
 export class <%= className %> {
 	constructor(
@@ -51,28 +34,12 @@ export class <%= className %> {
 		public readonly validFrom: Date | null,
 		public readonly validTo: Date | null,
 		public readonly isActive: boolean,
-<% } -%>
-<% if (hasRelationships) { -%>
-		// Loaded relations (optional, populated when eager-loaded)
-<% belongsToRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>,
-<% }) -%>
-<% hasManyRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>[],
-<% }) -%>
-<% hasOneRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>,
-<% }) -%>
 <% } -%>
 	) {}
 
 	static fromRecord(
 		// biome-ignore lint/suspicious/noExplicitAny: Drizzle records have dynamic shape
 		record: Record<string, any>,
-<% if (hasRelationships) { -%>
-		// biome-ignore lint/suspicious/noExplicitAny: Returns different entity types
-		mapRelation?: (name: string, data: unknown) => any,
-<% } -%>
 	): <%= className %> {
 		return new <%= className %>(
 			record.id,
@@ -90,17 +57,6 @@ export class <%= className %> {
 			record.validFrom,
 			record.validTo,
 			record.isActive,
-<% } -%>
-<% if (hasRelationships) { -%>
-<% belongsToRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
-<% hasManyRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
-<% hasOneRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
 <% } -%>
 		);
 	}

package/templates/entity/new/backend/domain/grouped-index.ejs.t

@@ -14,23 +14,6 @@ force: true
 <% if (hasEntityRefFields) { -%>
 import type { EntityType } from '<%= locations.dbSchemaServer.import %>';
 <% } -%>
-<%
-// Collect unique non-self-referential imports
-const importedEntities = new Set();
-[...belongsToRelations, ...hasManyRelations, ...hasOneRelations].forEach((rel) => {
-  if (rel.target !== name) {
-    importedEntities.add(rel.target);
-  }
-});
--%>
-<% if (importedEntities.size > 0) { -%>
-
-<% importedEntities.forEach((target) => {
-  const targetClass = target.charAt(0).toUpperCase() + target.slice(1).replace(/_([a-z])/g, (_, c) => c.toUpperCase());
--%>
-import type { <%= targetClass %> } from '../<%= target %>';
-<% }) -%>
-<% } -%>
 
 // ============================================================================
 // Entity
@@ -53,28 +36,12 @@ export class <%= className %> {
 		public readonly validFrom: Date | null,
 		public readonly validTo: Date | null,
 		public readonly isActive: boolean,
-<% } -%>
-<% if (hasRelationships) { -%>
-		// Loaded relations (optional, populated when eager-loaded)
-<% belongsToRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>,
-<% }) -%>
-<% hasManyRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>[],
-<% }) -%>
-<% hasOneRelations.forEach((rel) => { -%>
-		public readonly <%= rel.name %>?: <%= rel.targetClass %>,
-<% }) -%>
 <% } -%>
 	) {}
 
 	static fromRecord(
 		// biome-ignore lint/suspicious/noExplicitAny: Drizzle records have dynamic shape
 		record: Record<string, any>,
-<% if (hasRelationships) { -%>
-		// biome-ignore lint/suspicious/noExplicitAny: Returns different entity types
-		mapRelation?: (name: string, data: unknown) => any,
-<% } -%>
 	): <%= className %> {
 		return new <%= className %>(
 			record.id,
@@ -92,17 +59,6 @@ export class <%= className %> {
 			record.validFrom,
 			record.validTo,
 			record.isActive,
-<% } -%>
-<% if (hasRelationships) { -%>
-<% belongsToRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
-<% hasManyRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
-<% hasOneRelations.forEach((rel) => { -%>
-			record.<%= rel.name %> ? mapRelation?.('<%= rel.name %>', record.<%= rel.name %>) : undefined,
-<% }) -%>
 <% } -%>
 		);
 	}
@@ -111,18 +67,6 @@ export class <%= className %> {
 // ============================================================================
 // Repository Interface
 // ============================================================================
-<% if (hasRelationships) { -%>
-
-/**
- * Type-safe eager loading options.
- * Pass to repository methods to include related entities.
- */
-export type <%= className %>With = {
-<% relationships.forEach((rel) => { -%>
-	<%= rel.name %>?: boolean;
-<% }) -%>
-};
-<% } -%>
 
 /**
  * Domain-level input types for repository operations.
@@ -143,8 +87,8 @@ export type Update<%= className %>Input = Partial<Create<%= className %>Input>;
 
 export interface I<%= className %>Repository {
 	create(input: Create<%= className %>Input): Promise<<%= className %>>;
-	findById(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %> | null>;
-	findAll(<%= hasRelationships ? `include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findById(id: string): Promise<<%= className %> | null>;
+	findAll(): Promise<<%= className %>[]>;
 	update(id: string, input: Update<%= className %>Input): Promise<<%= className %> | null>;
 	delete(id: string): Promise<<%= className %> | null>;
 <% if (hasSoftDelete) { -%>
@@ -154,10 +98,10 @@ export interface I<%= className %>Repository {
 	findOnlyDeleted(): Promise<<%= className %>[]>;
 <% } -%>
 <% belongsToRelations.forEach((rel) => { -%>
-	findBy<%= rel.foreignKeyPascal %>(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findBy<%= rel.foreignKeyPascal %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= className %>[]>;
 <% }) -%>
 <% entityRefFields.forEach((ref) => { -%>
-	findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string): Promise<<%= className %>[]>;
 <% }) -%>
 }
 <% } -%>

package/templates/entity/new/backend/domain/index.ejs.t

@@ -11,5 +11,5 @@ force: true
  * when using separate file layout (file_grouping: "separate")
  */
 
-export * from './<%= name %>.entity';
-export * from './<%= name %>.repository.interface';
+export * from './<%= fileNames.entity.replace('.ts', '') %>';
+export * from './<%= fileNames.repositoryInterface.replace('.ts', '') %>';

package/templates/entity/new/backend/domain/repository-interface.ejs.t

@@ -9,25 +9,13 @@ force: true
  * Generated by entity codegen - do not edit directly
  */
 
-import type { <%= className %> } from './<%= name %>.entity';
+import type { <%= className %> } from './<%= (typeof fileNames !== 'undefined' ? fileNames.entity : name + '.entity.ts').replace('.ts', '') %>';
 <% if (hasEntityRefFields) { -%>
 import type { EntityType } from '<%= locations.dbSchemaServer.import %>';
 <% } -%>
 <% if (hasEmits && (createEventType || updateEventType || deleteEventType)) { -%>
 import type { DrizzleTransaction } from '<%= eventsTokenImport %>';
 <% } -%>
-<% if (hasRelationships) { -%>
-
-/**
- * Type-safe eager loading options.
- * Pass to repository methods to include related entities.
- */
-export type <%= className %>With = {
-<% relationships.forEach((rel) => { -%>
-	<%= rel.name %>?: boolean;
-<% }) -%>
-};
-<% } -%>
 
 /**
  * Domain-level input types for repository operations.
@@ -48,8 +36,8 @@ export type Update<%= className %>Input = Partial<Create<%= className %>Input>;
 
 export interface I<%= className %>Repository {
 	create(input: Create<%= className %>Input<%= (hasEmits && createEventType) ? ', tx?: DrizzleTransaction' : '' %>): Promise<<%= className %>>;
-	findById(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %> | null>;
-	findAll(<%= hasRelationships ? `include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findById(id: string): Promise<<%= className %> | null>;
+	findAll(): Promise<<%= className %>[]>;
 	update(id: string, input: Update<%= className %>Input<%= (hasEmits && updateEventType) ? ', tx?: DrizzleTransaction' : '' %>): Promise<<%= className %> | null>;
 	delete(id: string<%= (hasEmits && deleteEventType) ? ', tx?: DrizzleTransaction' : '' %>): Promise<<%= className %> | null>;
 <% if (hasSoftDelete) { -%>
@@ -58,16 +46,27 @@ export interface I<%= className %>Repository {
 	findWithDeleted(): Promise<<%= className %>[]>;
 	findOnlyDeleted(): Promise<<%= className %>[]>;
 <% } -%>
+<%_
+// CGP-358: FK methods with opts take priority. Always emit FK signatures with opts.
+// Skip declarative query signature when FK covers the same method name.
+const _riFkMethodNames = new Set(belongsToRelations.map(rel => `findBy${rel.foreignKeyPascal}`));
+_%>
 <% belongsToRelations.forEach((rel) => { -%>
-	findBy<%= rel.foreignKeyPascal %>(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findBy<%= rel.foreignKeyPascal %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= className %>[]>;
 <% }) -%>
 <% entityRefFields.forEach((ref) => { -%>
-	findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]>;
+	findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string): Promise<<%= className %>[]>;
 <% }) -%>
 <% if (hasDeclarativeQueries) { -%>
 	// Declarative queries (from queries: block in entity YAML)
 <% processedQueries.forEach((q) => { -%>
+<%_
+// Skip declarative signature when FK method covers it (opts is a superset of plain single-param).
+const _skipRiDq = _riFkMethodNames.has(q.methodName) && !q.isUnique && !q.hasVia && !q.hasSelect;
+_%>
+<% if (!_skipRiDq) { -%>
 	<%= q.methodName %>(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>>;
+<% } -%>
 <% }) -%>
 <% } -%>
 }

package/templates/entity/new/backend/modules/core/module.ejs.t

@@ -32,6 +32,9 @@ import { <%= className %>Repository } from '<%= imports.moduleToRepository %>';
 <% if (hasDeclarativeQueries) { -%>
 import { declarativeQueryClasses } from '<%= imports.moduleToDeclarativeQueries %>';
 <% } -%>
+<% if (hasRelationships && !isGrouped) { -%>
+import { relationshipQueryClasses } from '<%= imports.moduleToRelationshipQueries %>';
+<% } -%>
 <% if (exposeRest || exposeElectric) { -%>
 import { <%= classNamePlural %>Controller } from '<%= imports.moduleToController %>';
 <% } -%>
@@ -58,6 +61,10 @@ import { create<%= className %>Schema, update<%= className %>Schema, <%= camelNa
 <% if (hasDeclarativeQueries) { -%>
 		// Declarative queries
 		...declarativeQueryClasses,
+<% } -%>
+<% if (hasRelationships && !isGrouped) { -%>
+		// Relationship composition queries
+		...relationshipQueryClasses,
 <% } -%>
 	],
 	exports: [
@@ -71,6 +78,9 @@ import { create<%= className %>Schema, update<%= className %>Schema, <%= camelNa
 		<%= deleteCommandClass %>,
 <% if (hasDeclarativeQueries) { -%>
 		...declarativeQueryClasses,
+<% } -%>
+<% if (hasRelationships && !isGrouped) { -%>
+		...relationshipQueryClasses,
 <% } -%>
 	],
 })

package/templates/entity/new/backend/presentation/controller.ejs.t

@@ -19,9 +19,6 @@ import {
 	ParseUUIDPipe,
 	Post,
 	Put,
-<% if (hasRelationships) { -%>
-	Query,
-<% } -%>
 	UsePipes,
 } from '@nestjs/common';
 import {
@@ -44,9 +41,6 @@ import { <%= deleteCommandClass %> } from '<%= imports.controllerToDeleteCommand
 import { <%= updateCommandClass %> } from '<%= imports.controllerToUpdateCommand %>';
 import { ZodValidationPipe } from '../../core/pipes/zod-validation.pipe';
 import { <%= className %> } from '<%= imports.controllerToDomain %>';
-<% if (hasRelationships) { -%>
-import type { <%= className %>With } from '<%= imports.controllerToDomain %>';
-<% } -%>
 
 // OPENAPI-3: controller decorators reference schemas by `$ref` rather
 // than `type:` class references because generated DTOs are Zod-derived
@@ -72,12 +66,8 @@ export class <%= classNamePlural %>Controller {
 	})
 	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
 	@Get()
-	async findAll(<%- hasRelationships ? `@Query('include') include?: string` : '' %>): Promise<<%= className %>[]> {
-<% if (hasRelationships) { -%>
-		return this.list<%= classNamePlural %>Query.execute(this.parseInclude(include));
-<% } else { -%>
+	async findAll(): Promise<<%= className %>[]> {
 		return this.list<%= classNamePlural %>Query.execute();
-<% } -%>
 	}
 
 	@ApiOperation({ summary: 'Find <%= name %> by id', operationId: 'find<%= className %>ById' })
@@ -88,15 +78,8 @@ export class <%= classNamePlural %>Controller {
 	@Get(':id')
 	async findById(
 		@Param('id', ParseUUIDPipe) id: string,
-<% if (hasRelationships) { -%>
-		@Query('include') include?: string,
-<% } -%>
 	): Promise<<%= className %>> {
-<% if (hasRelationships) { -%>
-		return this.get<%= className %>ByIdQuery.execute(id, this.parseInclude(include));
-<% } else { -%>
 		return this.get<%= className %>ByIdQuery.execute(id);
-<% } -%>
 	}
 
 	@ApiOperation({ summary: 'Create <%= name %>', operationId: 'create<%= className %>' })
@@ -144,23 +127,8 @@ export class <%= classNamePlural %>Controller {
 	): Promise<<%= className %>> {
 		return this.delete<%= className %>Command.execute(id, { actor: { tenantId, userId } });
 	}
-<% if (hasRelationships) { -%>
-
-	/**
-	 * Parse comma-separated include query param into typed options.
-	 * Example: ?include=account,owner → { account: true, owner: true }
-	 */
-	private parseInclude(include?: string): <%= className %>With | undefined {
-		if (!include) return undefined;
-		const parts = include.split(',').map((s) => s.trim());
-		return {
-<% relationships.forEach((rel) => { -%>
-			<%= rel.name %>: parts.includes('<%= rel.name %>'),
-<% }) -%>
-		};
-	}
-<% } -%>
 }
+
 <% } -%>
 <% if (exposeElectric) { -%>
 /**

package/templates/entity/new/clean-lite-ps/entity.ejs.t

@@ -7,6 +7,9 @@ import {
 <%_ clpDrizzleImports.filter(i => i !== 'relations').forEach(i => { _%>
   <%= i %>,
 <%_ }) _%>
+<%_ if (typeof clpHasSelfFk !== 'undefined' && clpHasSelfFk) { _%>
+  type AnyPgColumn,
+<%_ } _%>
 } from 'drizzle-orm/pg-core';
 <%_ if (clpHasRelationsBlock) { _%>
 import { relations, type InferSelectModel } from 'drizzle-orm';
@@ -18,6 +21,12 @@ import { type InferSelectModel } from 'drizzle-orm';
 import { <%= rel.relatedTable %> } from '<%= rel.importPath %>';
 <%_ } _%>
 <%_ }) _%>
+<%_ /* CGP-358b: import has_many target tables for many() relation const */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ clpExistingHasMany.filter(rel => !rel.isSelfRef).forEach(rel => { _%>
+import { <%= rel.targetPlural %> } from '../<%= rel.targetPlural %>/<%= rel.target %>.entity';
+<%_ }) _%>
+<%_ } _%>
 <%_ if (typeof clpEnumFields !== 'undefined' && clpEnumFields.length > 0) { _%>
 
 <%_ clpEnumFields.forEach(ef => { _%>
@@ -36,7 +45,7 @@ export const <%= entityNamePlural %> = pgTable(
     // cascade rules never fire for a soft-deleted parent. This FK constraint only applies on
     // hard-delete (e.g. admin purge). See ADR-021: docs/adrs/ADR-021-on-delete-semantics.md
 <%_ } _%>
-    <%= rel.camelField %>: uuid('<%= rel.field %>')<%= rel.nullable ? '' : '.notNull()' %>.references(() => <%= rel.relatedTable %>.id, { onDelete: '<%= rel.onDelete %>' }),
+    <%= rel.camelField %>: uuid('<%= rel.field %>')<%= rel.nullable ? '' : '.notNull()' %>.references(<%= rel.isSelfFk ? '(): AnyPgColumn ' : '() ' %>=> <%= rel.relatedTable %>.id, { onDelete: '<%= rel.onDelete %>' }),
 <%_ }) _%>
 <%_ clpProcessedFields.forEach(field => { _%>
     <%= field.camelName %>: <%- field.drizzleChain %>,
@@ -57,14 +66,18 @@ export const <%= entityNamePlural %> = pgTable(
   },
 );
 <%_ if (clpHasRelationsBlock) { _%>
+<%_ const needsMany = typeof clpExistingHasMany !== 'undefined' && clpExistingHasMany.length > 0; _%>
 
-export const <%= entityNamePlural %>Relations = relations(<%= entityNamePlural %>, ({ one }) => ({
+export const <%= entityNamePlural %>Relations = relations(<%= entityNamePlural %>, ({ one<%= needsMany ? ', many' : '' %> }) => ({
 <%_ clpBelongsTo.forEach(rel => { _%>
   <%= rel.relationKey %>: one(<%= rel.relatedTable %>, {
     fields: [<%= entityNamePlural %>.<%= rel.camelField %>],
     references: [<%= rel.relatedTable %>.id],
   }),
 <%_ }) _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { clpExistingHasMany.forEach(rel => { _%>
+  <%= rel.name %>: many(<%= rel.targetPlural %>),
+<%_ }) } _%>
 }));
 <%_ } _%>
 

package/templates/entity/new/clean-lite-ps/module.ejs.t

@@ -13,9 +13,21 @@ force: true
 import { Inject, Module, type OnModuleInit } from '@nestjs/common';
 import { OPENAPI_REGISTRY, type OpenApiRegistry } from '@shared/openapi';
 import { DatabaseModule } from '@shared/database/database.module';
-<%_ clpBelongsTo.forEach(rel => { _%>
-// import { <%= rel.relatedEntityPascal %>sModule } from '../<%= rel.relatedPlural %>/<%= rel.relatedPlural %>.module';
+<%_ /* CGP-358b: Import cross-entity repos needed for has_many composition */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const hasManyNeedingImport = clpExistingHasMany.filter(r => !r.isSelfRef); _%>
+<%_ const uniqueHasManyForModule = [...new Map(hasManyNeedingImport.map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyForModule.forEach(rel => { _%>
+import { <%= rel.targetClass %>Repository } from '../<%= rel.targetPlural %>/<%= rel.target %>.repository';
+<%_ }) _%>
+<%_ } _%>
+<%_ /* CGP-358b: Import cross-entity repos needed for belongs_to composition */ _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToForModule = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToForModule.forEach(rel => { _%>
+import { <%= rel.relatedEntityPascal %>Repository } from '../<%= rel.relatedPlural %>/<%= rel.relatedEntity %>.repository';
 <%_ }) _%>
+<%_ } _%>
 <% if (eavEnabled) { -%>
 import { FieldValuesModule } from '../field_values/field_values.module';
 <% } -%>
@@ -68,6 +80,19 @@ import { <%= classNames.searchController %> } from './<%= entityName %>-search.c
   providers: [
     <%= classNames.repository %>,
     <%= classNames.service %>,
+<%_ /* CGP-358b: Register cross-entity repos as providers (needed for service DI) */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const uniqueHasManyProviders = [...new Map(clpExistingHasMany.filter(r => !r.isSelfRef).map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyProviders.forEach(rel => { _%>
+    <%= rel.targetClass %>Repository,
+<%_ }) _%>
+<%_ } _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToProviders = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToProviders.forEach(rel => { _%>
+    <%= rel.relatedEntityPascal %>Repository,
+<%_ }) _%>
+<%_ } _%>
     <%= classNames.findByIdUseCase %>,
     <%= classNames.listUseCase %>,
 <% if (eavEnabled) { -%>

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -5,6 +5,8 @@
  * all variables required by the clean-lite-ps template set.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import pluralizePkg from 'pluralize';
 // The patterns barrel has the side effect of pre-registering the five
 // library-shipped patterns (Base / Synced / Activity / Knowledge /
@@ -306,6 +308,57 @@ function mapOnDelete(onDelete) {
   return map[onDelete] ?? 'restrict';
 }
 
+/**
+ * Process has_many relationships into HasManyRelation[].
+ *
+ * Mirrors processBelongsTo. The `foreign_key` declared on a has_many
+ * relationship is the inverse FK living on the *target* entity's table —
+ * e.g. `account.relationships.contacts: { foreign_key: account_id }` means
+ * contacts.account_id. The method name on AccountRepository would be
+ * `findByAccountId`.
+ */
+function processHasMany(relationships, parentEntityNamePlural, fs, path, srcRoot) {
+  if (!relationships) return [];
+
+  const result = [];
+
+  for (const [relName, rel] of Object.entries(relationships)) {
+    if (rel.type !== 'has_many') continue;
+
+    const target = rel.target;
+    const inverseForeignKey = rel.foreign_key;
+    const targetPlural = pluralize(target);
+    const isSelfRef = targetPlural === parentEntityNamePlural;
+
+    // Check whether the target entity has already been generated.
+    // Only include targets that exist so the import block doesn't
+    // reference files that aren't on disk yet (two-pass generation).
+    let targetExists = false;
+    if (fs && path && srcRoot) {
+      const nestedPath = path.resolve(srcRoot, 'modules', targetPlural, `${target}.entity.ts`);
+      const flatPath = path.resolve(srcRoot, 'modules', `${target}.entity.ts`);
+      targetExists = fs.existsSync(nestedPath) || fs.existsSync(flatPath) || isSelfRef;
+    } else {
+      targetExists = isSelfRef;
+    }
+
+    result.push({
+      name: relName,
+      target,
+      targetClass: pascalCase(target),
+      targetPlural,
+      inverseForeignKey,
+      inverseForeignKeyCamel: camelCase(inverseForeignKey),
+      inverseForeignKeyPascal: pascalCase(inverseForeignKey),
+      isSelfRef,
+      targetExists,
+      importPath: `../${targetPlural}/${target}.repository`,
+    });
+  }
+
+  return result;
+}
+
 /**
  * Process belongs_to relationships into BelongsToRelation[]
  */
@@ -364,7 +417,7 @@ function processBelongsTo(relationships, parentEntityNamePlural) {
 /**
  * Collect drizzle imports needed for entity fields
  */
-function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking) {
+function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany = []) {
   const imports = new Set(['pgTable', 'uuid']);
 
   for (const field of processedFields) {
@@ -394,7 +447,7 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
     imports.add('jsonb');
   }
 
-  if (belongsTo.length > 0) {
+  if (belongsTo.length > 0 || hasMany.length > 0) {
     imports.add('relations');
   }
 
@@ -769,6 +822,9 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   // Process belongs_to relationships
   const belongsTo = processBelongsTo(relationships, entityNamePlural);
 
+  // Process has_many relationships (CGP-358b)
+  const hasMany = processHasMany(relationships, entityNamePlural, fs, path, srcRoot);
+
   // Issue #41 — warn when a soft-delete entity declares non-restrict on_delete on any
   // belongs_to relation. The FK constraint applies to hard-delete only;
   // developers expecting soft-delete cascade must use activeParentFilter() instead.
@@ -815,9 +871,9 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     }));
 
   // Drizzle imports needed
-  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking);
-  // Whether relations() import is needed
-  const hasRelationsBlock = belongsTo.length > 0;
+  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany);
+  // Whether relations() import is needed (CGP-358b: also trigger on has_many)
+  const hasRelationsBlock = belongsTo.length > 0 || hasMany.length > 0;
 
   // Output paths
   const outputPaths = {
@@ -1011,6 +1067,12 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     // Drizzle
     clpDrizzleImports: drizzleEntityImports,
     clpHasRelationsBlock: hasRelationsBlock,
+    // A self-referential belongs_to FK requires the `references()` callback
+    // to carry a `: AnyPgColumn` return-type annotation; otherwise TypeScript's
+    // strict mode flags the table const with TS7022/TS7024 (circular initializer).
+    // Surfaced by the cgp-62 relationship-scenario smoke when generating a CRM
+    // account with a `parent_account_id` self-FK.
+    clpHasSelfFk: belongsTo.some((rel) => rel.isSelfFk),
     clpEnumFields,
 
     // Declarative queries
@@ -1020,5 +1082,10 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     hasMultiFieldQuery,
     hasOrderedQuery,
     hasViaQuery,
+
+    // CGP-358b: has_many relationships for service-layer composition
+    clpHasMany: hasMany,
+    clpHasManyRelations: hasMany.length > 0,
+    clpExistingHasMany: hasMany.filter((r) => r.targetExists),
   };
 }

package/templates/entity/new/clean-lite-ps/repository.ejs.t

@@ -4,7 +4,17 @@ skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
 import { Injectable, Inject } from '@nestjs/common';
-<% if (hasDeclarativeQueries) { -%>
+<%_
+// CGP-358: FK methods with opts take priority over same-named declarative query impl.
+// Always emit FK methods; skip declarative body when FK covers same name.
+const _fkMethods = (typeof clpBelongsTo !== 'undefined') ? clpBelongsTo : [];
+const _fkMethodNamesCLP = new Set(_fkMethods.map(rel => {
+  const _p = rel.camelField.charAt(0).toUpperCase() + rel.camelField.slice(1);
+  return `findBy${_p}`;
+}));
+const _needsEq = hasDeclarativeQueries || _fkMethods.length > 0;
+_%>
+<% if (_needsEq) { -%>
 import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc, asc' : '' %> } from 'drizzle-orm';
 <% } -%>
 <% if (eavValueTable) { -%>
@@ -48,6 +58,12 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
   // Declarative queries (from queries: block in entity YAML)
   // ═══════════════════════════════════════════════════════════════════════
 <%_ processedQueries.forEach((q) => { _%>
+<%_
+// CGP-358: Skip declarative impl when a FK method covers this method name.
+// FK methods accept opts, making them a superset of a plain non-unique single-param query.
+const _skipClpDq = _fkMethodNamesCLP.has(q.methodName) && !q.isUnique && !q.hasVia && !q.hasSelect;
+_%>
+<%_ if (!_skipClpDq) { _%>
 
   async <%= q.methodName %>(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>> {
 <% if (q.isUnique) { -%>
@@ -61,11 +77,27 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
     return rows as <%= classNames.entity %>[];
 <% } -%>
   }
+<%_ } _%>
 <%_ }) _%>
 <% } else { -%>
 
   // TODO: Add entity-specific query methods here.
 <% } -%>
+<%_ if (_fkMethods.length > 0) { _%>
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // FK traversal methods (from belongs_to relationships — CGP-358b)
+  // Called by service-layer composition methods on the inverse (has_many) side.
+  // ═══════════════════════════════════════════════════════════════════════
+<%_ _fkMethods.forEach(rel => { _%>
+
+  async findBy<%= rel.camelField.charAt(0).toUpperCase() + rel.camelField.slice(1) %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= classNames.entity %>[]> {
+    let q = this.baseQuery().where(eq(this.table['<%= rel.camelField %>'], id));
+    if (opts?.limit) q = (q as any).limit(opts.limit);
+    return (await q) as <%= classNames.entity %>[];
+  }
+<%_ }) _%>
+<%_ } _%>
 <% if (eavValueTable) { -%>
 
   // ═══════════════════════════════════════════════════════════════════════