@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/backend/data-layer/cli/scaffold-entity/__tests__/generate.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import { validate } from '../validate.js'
+import type { ScaffoldEntityInput, EntityField, EntityRelation } from '../types.js'
+
+function field(name: string, over: Partial<EntityField> = {}): EntityField {
+  return { name, type: 'string', required: true, isKey: false, indexed: false, ...over }
+}
+
+function rel(over: Partial<EntityRelation> & Pick<EntityRelation, 'type' | 'targetEntity'>): EntityRelation {
+  return { nullable: false, cascadeDelete: false, ...over }
+}
+
+function fixture(overrides: Partial<ScaffoldEntityInput> = {}): ScaffoldEntityInput {
+  return {
+    name: 'Opportunity',
+    pluralName: 'Opportunities',
+    module: 'pipeline',
+    appCode: 'TestV2',
+    domainPrefix: 'pipeline',
+    namespace: 'TestV2',
+    tenantMode: 'strict',
+    schemaTarget: 'extensions',
+    fields: [field('Title')],
+    relations: [],
+    constraints: [],
+    projectPath: '/tmp/project',
+    ...overrides,
+  }
+}
+
+const entityOf = (i: ScaffoldEntityInput) => generate(i).find(f => f.path.endsWith('Opportunity.cs'))!.content
+const configOf = (i: ScaffoldEntityInput) => generate(i).find(f => f.path.endsWith('OpportunityConfiguration.cs'))!.content
+
+describe('scaffold-entity / generate — no relations (regression guard)', () => {
+  it('emits the 3 files and NO relationship config when relations is empty', () => {
+    const files = generate(fixture())
+    expect(files.map(f => f.path)).toEqual(expect.arrayContaining([
+      expect.stringContaining('Domain/Entities/Opportunity.cs'),
+      expect.stringContaining('Domain/Entities/OpportunityEvents.cs'),
+      expect.stringContaining('Infrastructure/Persistence/Configurations/OpportunityConfiguration.cs'),
+    ]))
+    const cfg = configOf(fixture())
+    expect(cfg).not.toContain('HasOne')
+    expect(cfg).not.toContain('HasForeignKey')
+    expect(entityOf(fixture())).not.toContain('ICollection<')
+  })
+})
+
+describe('scaffold-entity / generate — owning relation (many-to-one)', () => {
+  it('emits the FK column, the reference navigation, and a real FK constraint (default Restrict)', () => {
+    const i = fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Contact' })] })
+    const entity = entityOf(i)
+    const config = configOf(i)
+    expect(entity).toContain('public Guid ContactId { get; private set; }')
+    expect(entity).toContain('public Contact Contact { get; private set; } = null!;')
+    expect(config).toContain('builder.HasOne(e => e.Contact).WithMany().HasForeignKey(e => e.ContactId).OnDelete(DeleteBehavior.Restrict);')
+    // required FK becomes a Create() parameter
+    expect(entity).toMatch(/public static Opportunity Create\([^)]*Guid contactId[^)]*\)/)
+  })
+
+  it('maps cascade vocabulary to DeleteBehavior (cascade → Cascade)', () => {
+    const i = fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Account', onDelete: 'cascade' })] })
+    expect(configOf(i)).toContain('.OnDelete(DeleteBehavior.Cascade);')
+  })
+
+  it('honors the legacy cascadeDelete boolean when onDelete is absent', () => {
+    const i = fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Account', cascadeDelete: true })] })
+    expect(configOf(i)).toContain('.OnDelete(DeleteBehavior.Cascade);')
+  })
+
+  it('a nullable set-null relation yields a nullable FK + nullable nav + SetNull', () => {
+    const i = fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Owner', foreignKey: 'OwnerUserId', nullable: true, onDelete: 'set-null' })] })
+    const entity = entityOf(i)
+    expect(entity).toContain('public Guid? OwnerUserId { get; private set; }')
+    expect(entity).toContain('public Owner? Owner { get; private set; }')
+    expect(configOf(i)).toContain('builder.HasOne(e => e.Owner).WithMany().HasForeignKey(e => e.OwnerUserId).OnDelete(DeleteBehavior.SetNull);')
+    // optional FK is NOT injected into the Create() initializer
+    expect(entity).not.toContain('OwnerUserId = ownerUserId,')
+  })
+
+  it('reuses an existing hand-declared Guid field instead of emitting a duplicate', () => {
+    const i = fixture({
+      fields: [field('Title'), field('ContactId', { type: 'guid', required: false })],
+      relations: [rel({ type: 'many-to-one', targetEntity: 'Contact', foreignKey: 'ContactId', nullable: true })],
+    })
+    const entity = entityOf(i)
+    expect((entity.match(/public Guid\? ContactId \{ get; private set; \}/g) ?? []).length).toBe(1)
+    expect(configOf(i)).toContain('.HasForeignKey(e => e.ContactId)')
+  })
+})
+
+describe('scaffold-entity / generate — inverse relation (one-to-many)', () => {
+  it('emits a collection navigation + HasMany config, and NO FK column on this side', () => {
+    const i = fixture({ relations: [rel({ type: 'one-to-many', targetEntity: 'OrderLine', onDelete: 'cascade' })] })
+    const entity = entityOf(i)
+    expect(entity).toContain('public ICollection<OrderLine> OrderLines { get; private set; } = new List<OrderLine>();')
+    expect(configOf(i)).toContain('builder.HasMany(e => e.OrderLines).WithOne().OnDelete(DeleteBehavior.Cascade);')
+    expect(entity).not.toContain('OrderLineId')
+  })
+})
+
+describe('scaffold-entity / validate — relation guards', () => {
+  it('rejects set-null on a non-nullable relation', () => {
+    const res = validate(fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Owner', onDelete: 'set-null' })] }))
+    expect(res.valid).toBe(false)
+    expect(res.errors.join(' ')).toContain('set-null')
+  })
+
+  it('rejects two relations resolving to the same FK column', () => {
+    const res = validate(fixture({
+      relations: [
+        rel({ type: 'many-to-one', targetEntity: 'Contact', foreignKey: 'PartyId' }),
+        rel({ type: 'many-to-one', targetEntity: 'Company', foreignKey: 'PartyId' }),
+      ],
+    }))
+    expect(res.valid).toBe(false)
+    expect(res.errors.join(' ')).toContain('duplicate foreign key')
+  })
+
+  it('accepts a well-formed owning relation', () => {
+    const res = validate(fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Contact' })] }))
+    expect(res.valid).toBe(true)
+    expect(res.errors).toHaveLength(0)
+  })
+})
+
+describe('scaffold-entity / generate — DB naming convention (SmartStack.app aligned)', () => {
+  it('table = {domainPrefix}_{PascalPlural} in the target schema', () => {
+    expect(configOf(fixture())).toContain('builder.ToTable("pipeline_Opportunities", SchemaConstants.Extensions);')
+  })
+
+  it('pluralizes the entity name when pluralName is omitted', () => {
+    const i = fixture({ name: 'Company', pluralName: undefined })
+    const cfg = generate(i).find(f => f.path.endsWith('CompanyConfiguration.cs'))!.content
+    expect(cfg).toContain('builder.ToTable("pipeline_Companies", SchemaConstants.Extensions);')
+  })
+
+  it('never remaps columns — PascalCase default mapping, no HasColumnName', () => {
+    const cfg = configOf(fixture({ fields: [field('FirstName', { maxLength: 100 })] }))
+    expect(cfg).not.toContain('HasColumnName')
+    expect(cfg).toContain('builder.Property(e => e.FirstName).IsRequired().HasMaxLength(100);')
+  })
+
+  it('emits no HasDatabaseName index overrides (EF default index names)', () => {
+    expect(configOf(fixture({ fields: [field('Code', { indexed: true })] }))).not.toContain('HasDatabaseName')
+  })
+
+  it('a plain Guid FK gets no Property line and no column remap', () => {
+    const cfg = configOf(fixture({ relations: [rel({ type: 'many-to-one', targetEntity: 'Contact' })] }))
+    expect(cfg).not.toContain('HasColumnName')
+    expect(cfg).not.toContain('builder.Property(e => e.ContactId)')
+    expect(cfg).toContain('.HasForeignKey(e => e.ContactId)')
+  })
+})

package/templates/skills/development/backend/data-layer/cli/scaffold-entity/generate.ts

@@ -0,0 +1,232 @@
+/**
+ * cli:scaffold-entity — generate.ts
+ *
+ * Generates a Domain entity + its EF Core Configuration. Both consume SmartStack
+ * NuGet packages:
+ *   - SmartStack.Core.Domain.BaseEntity (provides Id, CreatedAt, UpdatedAt, DeletedAt,
+ *     AddDomainEvent, etc.)
+ *   - SmartStack.Core.Domain.ITenantEntity / IOptionalTenantEntity
+ *   - SmartStack.Infrastructure.Persistence.SchemaConstants (Core / Extensions)
+ *
+ * Conventions enforced:
+ *   - Private parameterless ctor + static Create() factory (no public setters)
+ *   - Update() validates required string fields
+ *   - SoftDelete()/Restore() methods (DeletedAt-based)
+ *   - Table = "{domainPrefix}_{PluralName}" in schemaTarget ('core' for SmartStack
+ *     built-ins, 'extensions' for client modules)
+ *   - Indexes on CreatedAt (common query filter) and any field flagged `indexed: true`
+ */
+import { pluralize } from '../../../../../lib/string-utils.js'
+import type { ScaffoldEntityInput, GeneratedFile, EntityField, EntityRelation } from './types.js'
+
+export function generate(spec: ScaffoldEntityInput): GeneratedFile[] {
+  const ns = spec.namespace ?? spec.appCode
+  const reserved = new Set(['Id', 'CreatedAt', 'UpdatedAt', 'DeletedAt', 'TenantId'])
+  // Computed fields (with `formula`) are NOT emitted as Domain properties — they
+  // live only in the read DTOs where scaffold-business injects the formula into
+  // the LINQ projection. EF Configuration also ignores them (no column mapping).
+  const userFields = spec.fields.filter(f => !reserved.has(f.name) && !f.formula)
+
+  // ─── Relations → FK columns + navigation properties ───
+  // Owning side (many-to-one / one-to-one) carries the FK column on THIS entity;
+  // the collection side (one-to-many / many-to-many) only gets an inverse nav.
+  const owningRels = spec.relations.filter(r => r.type === 'many-to-one' || r.type === 'one-to-one')
+  const collectionRels = spec.relations.filter(r => r.type === 'one-to-many' || r.type === 'many-to-many')
+  const present = new Set(userFields.map(f => f.name.toLowerCase()))
+  // Synthesize a Guid FK column per owning relation so the Create/Update/column
+  // logic treats it like any other field. Skip when the spec already declares the
+  // Guid field by hand (cross-module style) — reuse it, only add the config.
+  // FK columns are NOT flagged indexed: EF Core auto-creates the FK index.
+  const fkFields: EntityField[] = []
+  for (const rel of owningRels) {
+    const fk = fkName(rel)
+    if (present.has(fk.toLowerCase())) continue
+    fkFields.push({ name: fk, type: 'guid', required: !rel.nullable, isKey: false, indexed: false })
+    present.add(fk.toLowerCase())
+  }
+  const columns = [...userFields, ...fkFields]
+  const reqFields = columns.filter(f => f.required)
+  const updatableFields = columns.filter(f => !f.isKey)
+
+  // Navigation properties (reference for the owning side, collection for the inverse).
+  const navProps = [
+    ...owningRels.map(rel => `    public ${rel.targetEntity}${rel.nullable ? '?' : ''} ${refNavName(rel)} { get; private set; }${rel.nullable ? '' : ' = null!;'}`),
+    ...collectionRels.map(rel => `    public ICollection<${rel.targetEntity}> ${collNavName(rel)} { get; private set; } = new List<${rel.targetEntity}>();`),
+  ]
+  const navBlock = navProps.length ? '\n\n' + navProps.join('\n') : ''
+
+  // EF Core relationship configuration — the REAL FK constraint + declared cascade.
+  const relConfig = [
+    ...owningRels.map(rel => rel.type === 'one-to-one'
+      ? `        builder.HasOne(e => e.${refNavName(rel)}).WithOne().HasForeignKey<${spec.name}>(e => e.${fkName(rel)}).OnDelete(DeleteBehavior.${onDeleteBehavior(rel)});`
+      : `        builder.HasOne(e => e.${refNavName(rel)}).WithMany().HasForeignKey(e => e.${fkName(rel)}).OnDelete(DeleteBehavior.${onDeleteBehavior(rel)});`),
+    ...collectionRels.map(rel => rel.type === 'many-to-many'
+      ? `        builder.HasMany(e => e.${collNavName(rel)}).WithMany();`
+      : `        builder.HasMany(e => e.${collNavName(rel)}).WithOne().OnDelete(DeleteBehavior.${onDeleteBehavior(rel)});`),
+  ]
+  const relBlock = relConfig.length ? '\n\n' + relConfig.join('\n') : ''
+  const tenantIface = spec.tenantMode === 'strict' ? ', ITenantEntity' : spec.tenantMode === 'optional' ? ', IOptionalTenantEntity' : ''
+  const tenantProp = spec.tenantMode === 'strict'
+    ? '\n    public Guid TenantId { get; private set; }'
+    : spec.tenantMode === 'optional'
+    ? '\n    public Guid? TenantId { get; private set; }'
+    : ''
+  const schemaConstant = spec.schemaTarget === 'core' ? 'SchemaConstants.Core' : 'SchemaConstants.Extensions'
+
+  const entity = `using SmartStack.Core.Domain;
+
+namespace ${ns}.Domain.Entities;
+
+public class ${spec.name} : BaseEntity${tenantIface}
+{${tenantProp}
+${columns.map(f => `    public ${csType(f)} ${f.name} { get; private set; }${defaultInitializer(f)}`).join('\n')}${navBlock}
+
+    private ${spec.name}() { }
+
+    public static ${spec.name} Create(${createParams(reqFields, spec.tenantMode !== 'none')})
+    {
+${reqFields.filter(f => f.type === 'string').map(f => `        ArgumentException.ThrowIfNullOrWhiteSpace(${camel(f.name)});`).join('\n')}
+        var entity = new ${spec.name}
+        {
+${reqFields.map(f => `            ${f.name} = ${camel(f.name)},`).join('\n')}${spec.tenantMode !== 'none' ? '\n            TenantId = tenantId,' : ''}
+        };
+        entity.AddDomainEvent(new ${spec.name}CreatedEvent(entity.Id));
+        return entity;
+    }
+
+    public void Update(${updateParams(updatableFields)})
+    {
+${updatableFields.filter(f => f.type === 'string' && f.required).map(f => `        ArgumentException.ThrowIfNullOrWhiteSpace(${camel(f.name)});`).join('\n')}
+${updatableFields.map(f => `        ${f.name} = ${camel(f.name)};`).join('\n')}
+        UpdatedAt = DateTime.UtcNow;
+        AddDomainEvent(new ${spec.name}UpdatedEvent(Id));
+    }
+
+    public void SoftDelete()
+    {
+        if (DeletedAt.HasValue) return;
+        DeletedAt = DateTime.UtcNow;
+        AddDomainEvent(new ${spec.name}DeletedEvent(Id));
+    }
+
+    public void Restore()
+    {
+        if (!DeletedAt.HasValue) return;
+        DeletedAt = null;
+        AddDomainEvent(new ${spec.name}RestoredEvent(Id));
+    }
+}
+`
+
+  const events = `using SmartStack.Core.Domain;
+
+namespace ${ns}.Domain.Entities;
+
+public record ${spec.name}CreatedEvent(Guid ${spec.name}Id) : IDomainEvent;
+public record ${spec.name}UpdatedEvent(Guid ${spec.name}Id) : IDomainEvent;
+public record ${spec.name}DeletedEvent(Guid ${spec.name}Id) : IDomainEvent;
+public record ${spec.name}RestoredEvent(Guid ${spec.name}Id) : IDomainEvent;
+`
+
+  const tableName = `${spec.domainPrefix}_${spec.pluralName ?? pluralize(spec.name)}`
+  const indexedFields = columns.filter(f => f.indexed)
+  // Column constraints only — NO HasColumnName. EF Core maps property → column in
+  // PascalCase by default, matching SmartStack.app (which never remaps columns:
+  // `FirstName`, `CreatedAt`, `ClientId`). A Property() line is emitted only when
+  // it carries a constraint (required string / maxLength); otherwise the column
+  // falls through to the default mapping.
+  const propLines = columns
+    .map(f => {
+      const required = f.required && f.type === 'string' ? '.IsRequired()' : ''
+      const maxLen = f.maxLength ? `.HasMaxLength(${f.maxLength})` : ''
+      return required || maxLen ? `        builder.Property(e => e.${f.name})${required}${maxLen};` : ''
+    })
+    .filter(Boolean)
+  const bodyLines: string[] = [
+    `        builder.ToTable("${tableName}", ${schemaConstant});`,
+    `        builder.HasKey(e => e.Id);`,
+    `        builder.HasQueryFilter(e => e.DeletedAt == null);`,
+    ``,
+    `        builder.HasIndex(e => e.CreatedAt);`,
+  ]
+  if (spec.tenantMode !== 'none') bodyLines.push(`        builder.HasIndex(e => e.TenantId);`)
+  if (propLines.length) bodyLines.push(``, ...propLines)
+  if (indexedFields.length) bodyLines.push(``, ...indexedFields.map(f => `        builder.HasIndex(e => e.${f.name});`))
+  const config = `using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using SmartStack.Infrastructure.Persistence;
+using ${ns}.Domain.Entities;
+
+namespace ${ns}.Infrastructure.Persistence.Configurations;
+
+public class ${spec.name}Configuration : IEntityTypeConfiguration<${spec.name}>
+{
+    public void Configure(EntityTypeBuilder<${spec.name}> builder)
+    {
+${bodyLines.join('\n')}${relBlock}
+    }
+}
+`
+
+  return [
+    { path: `src/${ns}.Domain/Entities/${spec.name}.cs`, content: entity },
+    { path: `src/${ns}.Domain/Entities/${spec.name}Events.cs`, content: events },
+    { path: `src/${ns}.Infrastructure/Persistence/Configurations/${spec.name}Configuration.cs`, content: config },
+  ]
+}
+
+// ─── Helpers ───
+
+function camel(s: string): string {
+  return s.charAt(0).toLowerCase() + s.slice(1)
+}
+
+function csType(f: EntityField): string {
+  const map: Record<string, string> = {
+    string: 'string', int: 'int', integer: 'int', number: 'decimal', decimal: 'decimal',
+    bool: 'bool', boolean: 'bool', datetime: 'DateTime', date: 'DateOnly', guid: 'Guid',
+  }
+  const base = map[f.type.toLowerCase()] ?? f.type
+  return !f.required && base !== 'string' ? `${base}?` : base
+}
+
+function defaultInitializer(f: EntityField): string {
+  if (f.required && f.type.toLowerCase() === 'string') return ' = null!;'
+  return ''
+}
+
+function createParams(reqFields: EntityField[], includeTenant: boolean): string {
+  const parts = reqFields.map(f => `${csType(f)} ${camel(f.name)}`)
+  if (includeTenant) parts.push('Guid tenantId')
+  return parts.join(', ')
+}
+
+function updateParams(fields: EntityField[]): string {
+  return fields.map(f => `${csType(f)} ${camel(f.name)}`).join(', ')
+}
+
+// ─── Relation helpers ───
+
+/** FK column name on the owning side. Default `${targetEntity}Id`. */
+function fkName(rel: EntityRelation): string {
+  return rel.foreignKey ?? `${rel.targetEntity}Id`
+}
+
+/** Reference navigation property name (owning side). Default = targetEntity. */
+function refNavName(rel: EntityRelation): string {
+  return rel.navigationName ?? rel.targetEntity
+}
+
+/** Collection navigation property name (inverse side). Default = `${targetEntity}s`. */
+function collNavName(rel: EntityRelation): string {
+  return rel.navigationName ?? `${rel.targetEntity}s`
+}
+
+/** Maps the BA cascade vocabulary to an EF Core `DeleteBehavior` member. */
+function onDeleteBehavior(rel: EntityRelation): string {
+  const action = rel.onDelete ?? (rel.cascadeDelete ? 'cascade' : 'restrict')
+  const map: Record<string, string> = {
+    'restrict': 'Restrict', 'cascade': 'Cascade', 'set-null': 'SetNull', 'no-action': 'NoAction',
+  }
+  return map[action] ?? 'Restrict'
+}

package/templates/skills/development/backend/data-layer/cli/scaffold-entity/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, join } from 'node:path'
+import { validate } from './validate.js'
+import { generate } from './generate.js'
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js'
+
+const COMMAND = 'scaffold-entity'
+
+function main(): void {
+  const { values } = parseArgs({ options: { spec: { type: 'string' }, outdir: { type: 'string' }, dry_run: { type: 'boolean', default: false } }, strict: true })
+  if (!values.spec) { printEnvelope(failGenerate(COMMAND, ['--spec is required'])); process.exit(1) }
+  let raw: unknown
+  try { raw = JSON.parse(values.spec) } catch { printEnvelope(failGenerate(COMMAND, ['Invalid JSON'])); process.exit(1) }
+  const v = validate(raw)
+  if (!v.valid) { printEnvelope(failGenerate(COMMAND, v.errors)); process.exit(1) }
+  const spec = raw as any
+  const files = generate(spec)
+  if (values.dry_run) {
+    printEnvelope(generateEnvelope(COMMAND, { data: { dryRun: true, files: files.map(f => f.path) }, warnings: v.warnings }))
+    process.exit(0)
+  }
+  const outdir = values.outdir ?? spec.projectPath
+  const written: string[] = []
+  for (const file of files) { const p = resolve(join(outdir, file.path)); mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, file.content, 'utf-8'); written.push(p) }
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { entity: spec.name, fileCount: written.length },
+    filesCreated: written,
+    warnings: v.warnings,
+    nextSteps: ['Run dotnet build'],
+  }))
+}
+main()

package/templates/skills/development/backend/data-layer/cli/scaffold-entity/types.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+
+export const EntityFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1),
+  required: z.boolean().default(true),
+  maxLength: z.number().optional(),
+  description: z.string().optional(),
+  isKey: z.boolean().default(false),
+  indexed: z.boolean().default(false),
+  /**
+   * Optional C# expression marking this field as a computed (derived) attribute.
+   * The Domain entity SKIPS the property entirely — the value lives only in the
+   * read DTOs (ListDto / DetailDto) where scaffold-business injects the formula
+   * into the LINQ projection. The EF Configuration also ignores the field.
+   * See `scaffold-business/types.ts` and `audit-data-model` rule DM-016.
+   */
+  formula: z.string().optional(),
+})
+
+export const EntityRelationSchema = z.object({
+  type: z.enum(['one-to-many', 'many-to-one', 'many-to-many', 'one-to-one']),
+  targetEntity: z.string().min(1),
+  /** FK column on the OWNING side (many-to-one / one-to-one). Default `${targetEntity}Id`. */
+  foreignKey: z.string().optional(),
+  /** Navigation property name. Default = targetEntity (reference) / `${targetEntity}s` (collection). */
+  navigationName: z.string().optional(),
+  nullable: z.boolean().default(false),
+  /**
+   * Referential action mirroring the BA data-model cascade vocabulary
+   * (`create-data-model/levels/relationships.md`). Maps to EF Core
+   * `DeleteBehavior`: restrict→Restrict, cascade→Cascade, set-null→SetNull,
+   * no-action→NoAction. When omitted, falls back to the legacy `cascadeDelete`
+   * boolean (true→cascade, false→restrict). Default effective behavior: restrict.
+   */
+  onDelete: z.enum(['restrict', 'cascade', 'set-null', 'no-action']).optional(),
+  /** @deprecated Legacy boolean — prefer `onDelete`. Honored only when `onDelete` is absent. */
+  cascadeDelete: z.boolean().default(false),
+})
+
+export const ScaffoldEntityInputSchema = z.object({
+  name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/),
+  pluralName: z.string().optional(),
+  module: z.string().min(1),
+  appCode: z.string().min(1),
+  domainPrefix: z.string().min(1).regex(/^[a-z][a-z0-9]*$/, 'domainPrefix must be lowercase alphanumeric'),
+  namespace: z.string().optional(),
+  tenantMode: z.enum(['strict', 'optional', 'none']).default('strict'),
+  schemaTarget: z.enum(['core', 'extensions']).default('extensions'),
+  fields: z.array(EntityFieldSchema).min(1),
+  relations: z.array(EntityRelationSchema).default([]),
+  constraints: z.array(z.string()).default([]),
+  projectPath: z.string().min(1),
+})
+
+export type EntityField = z.infer<typeof EntityFieldSchema>
+export type EntityRelation = z.infer<typeof EntityRelationSchema>
+export type ScaffoldEntityInput = z.infer<typeof ScaffoldEntityInputSchema>
+export interface GeneratedFile { path: string; content: string }
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }

package/templates/skills/development/backend/data-layer/cli/scaffold-entity/validate.ts

@@ -0,0 +1,42 @@
+import { ScaffoldEntityInputSchema, type EntityRelation, type ValidationResult } from './types.js'
+
+/** FK column name an owning relation (many-to-one / one-to-one) maps to. */
+function fkNameOf(rel: EntityRelation): string {
+  return rel.foreignKey ?? `${rel.targetEntity}Id`
+}
+
+/** Effective referential action: explicit `onDelete` wins, else legacy boolean, else restrict. */
+function onDeleteOf(rel: EntityRelation): 'restrict' | 'cascade' | 'set-null' | 'no-action' {
+  return rel.onDelete ?? (rel.cascadeDelete ? 'cascade' : 'restrict')
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ScaffoldEntityInputSchema.safeParse(raw)
+  if (!result.success) return { valid: false, errors: result.error.issues.map(i => `[${i.path.join('.')}] ${i.message}`), warnings: [] }
+  const spec = result.data
+  const warnings: string[] = []
+  const errors: string[] = []
+  const reserved = ['Id', 'CreatedAt', 'UpdatedAt', 'DeletedAt', 'TenantId']
+  for (const f of spec.fields) { if (reserved.includes(f.name)) warnings.push(`"${f.name}" inherited from BaseEntity — skipped`) }
+
+  // ─── Relations: validate the OWNING side (the one that carries the FK column) ───
+  const owning = spec.relations.filter(r => r.type === 'many-to-one' || r.type === 'one-to-one')
+  const fieldNames = new Map(spec.fields.map(f => [f.name.toLowerCase(), f]))
+  const seenFk = new Set<string>()
+  for (const rel of owning) {
+    const fk = fkNameOf(rel)
+    const action = onDeleteOf(rel)
+    if (reserved.includes(fk)) errors.push(`relation → ${rel.targetEntity}: foreign key "${fk}" collides with a BaseEntity property`)
+    if (action === 'set-null' && !rel.nullable) errors.push(`relation → ${rel.targetEntity}: onDelete "set-null" requires nullable: true`)
+    if (seenFk.has(fk.toLowerCase())) errors.push(`duplicate foreign key "${fk}" across relations — give one an explicit distinct foreignKey`)
+    seenFk.add(fk.toLowerCase())
+    const collide = fieldNames.get(fk.toLowerCase())
+    if (collide && collide.type.toLowerCase() !== 'guid') {
+      errors.push(`relation → ${rel.targetEntity}: foreign key "${fk}" collides with a non-Guid field of the same name`)
+    } else if (collide) {
+      warnings.push(`relation → ${rel.targetEntity}: reuses the existing "${fk}" Guid field as the FK column (no duplicate emitted)`)
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings }
+}

package/templates/skills/development/backend/data-layer/cli/scaffold-migration/execute.ts

@@ -0,0 +1,13 @@
+import { execSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import type { ScaffoldMigrationInput } from './types.js'
+
+export function execute(input: ScaffoldMigrationInput): { success: boolean; output: string } {
+  const cmd = `dotnet ef migrations add ${input.name} --project src/${input.appCode}.Infrastructure --startup-project src/${input.appCode}.Api`
+  try {
+    const out = execSync(cmd, { cwd: resolve(input.projectPath), encoding: 'utf-8', timeout: 120_000 })
+    return { success: true, output: out.slice(0, 2000) }
+  } catch (err: any) {
+    return { success: false, output: ((err.stdout ?? '') + '\n' + (err.stderr ?? '')).slice(0, 2000) }
+  }
+}

package/templates/skills/development/backend/data-layer/cli/scaffold-migration/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { execute } from './execute.js'
+import { executeEnvelope, failExecute, printEnvelope } from '../../../../../lib/output.js'
+
+const COMMAND = 'scaffold-migration'
+
+function main(): void {
+  const { values } = parseArgs({ options: { spec: { type: 'string' } }, strict: true })
+  if (!values.spec) { printEnvelope(failExecute(COMMAND, ['--spec is required'])); process.exit(1) }
+  let raw: unknown
+  try { raw = JSON.parse(values.spec) } catch { printEnvelope(failExecute(COMMAND, ['Invalid JSON'])); process.exit(1) }
+  const v = validate(raw)
+  if (!v.valid) { printEnvelope(failExecute(COMMAND, v.errors)); process.exit(1) }
+  const r = execute(raw as any)
+  if (r.success) {
+    printEnvelope(executeEnvelope(COMMAND, { report: { output: r.output }, nextSteps: ['Run dotnet build'] }))
+  } else {
+    printEnvelope({ ...failExecute(COMMAND, ['Migration failed']), report: { output: r.output }, nextSteps: ['Fix errors and retry'] })
+  }
+  process.exit(r.success ? 0 : 1)
+}
+
+main()

package/templates/skills/development/backend/data-layer/cli/scaffold-migration/types.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+export const ScaffoldMigrationInputSchema = z.object({
+  name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/),
+  module: z.string().min(1),
+  appCode: z.string().min(1),
+  projectPath: z.string().min(1),
+})
+
+export type ScaffoldMigrationInput = z.infer<typeof ScaffoldMigrationInputSchema>
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }

package/templates/skills/development/backend/data-layer/cli/scaffold-migration/validate.ts

@@ -0,0 +1,9 @@
+import { ScaffoldMigrationInputSchema, type ValidationResult } from './types.js'
+import { existsSync } from 'node:fs'
+
+export function validate(raw: unknown): ValidationResult {
+  const r = ScaffoldMigrationInputSchema.safeParse(raw)
+  if (!r.success) return { valid: false, errors: r.error.issues.map(i => `[${i.path.join('.')}] ${i.message}`), warnings: [] }
+  if (!existsSync(r.data.projectPath)) return { valid: false, errors: [`Project not found: ${r.data.projectPath}`], warnings: [] }
+  return { valid: true, errors: [], warnings: [] }
+}