@atlashub/smartstack-mcp 1.2.2 → 1.2.3

package/dist/index.js

@@ -148,6 +148,10 @@ var defaultConfig = {
       "loc_",
       "lic_"
     ],
+    codePrefixes: {
+      core: "core_",
+      extension: "ext_"
+    },
     migrationFormat: "{context}_v{version}_{sequence}_{Description}",
     namespaces: {
       domain: "SmartStack.Domain",
@@ -226,6 +230,10 @@ function mergeConfig(base, override) {
         ...base.conventions.schemas,
         ...override.conventions?.schemas
       },
+      codePrefixes: {
+        ...base.conventions.codePrefixes,
+        ...override.conventions?.codePrefixes
+      },
       namespaces: {
         ...base.conventions.namespaces,
         ...override.conventions?.namespaces
@@ -280,6 +288,10 @@ var ConventionsConfigSchema = z.object({
     "loc_",
     "lic_"
   ]),
+  codePrefixes: z.object({
+    core: z.string().default("core_"),
+    extension: z.string().default("ext_")
+  }),
   migrationFormat: z.string().default("{context}_v{version}_{sequence}_{Description}"),
   namespaces: z.object({
     domain: z.string(),
@@ -323,7 +335,7 @@ var ConfigSchema = z.object({
 });
 var ValidateConventionsInputSchema = z.object({
   path: z.string().optional().describe("Project path to validate (default: SmartStack.app path)"),
-  checks: z.array(z.enum(["tables", "migrations", "services", "namespaces", "all"])).default(["all"]).describe("Types of checks to perform")
+  checks: z.array(z.enum(["tables", "migrations", "services", "namespaces", "entities", "all"])).default(["all"]).describe("Types of checks to perform")
 });
 var CheckMigrationsInputSchema = z.object({
   projectPath: z.string().optional().describe("EF Core project path"),
@@ -337,7 +349,10 @@ var ScaffoldExtensionInputSchema = z.object({
     namespace: z.string().optional().describe("Custom namespace"),
     baseEntity: z.string().optional().describe("Base entity to extend (for entity type)"),
     methods: z.array(z.string()).optional().describe("Methods to generate (for service type)"),
-    outputPath: z.string().optional().describe("Custom output path")
+    outputPath: z.string().optional().describe("Custom output path"),
+    isSystemEntity: z.boolean().optional().describe("If true, creates a system entity without TenantId"),
+    tablePrefix: z.string().optional().describe('Domain prefix for table name (e.g., "auth_", "nav_", "cfg_")'),
+    schema: z.enum(["core", "extensions"]).optional().describe("Database schema (default: core)")
   }).optional()
 });
 var ApiDocsInputSchema = z.object({
@@ -1135,6 +1150,19 @@ var scaffoldExtensionTool = {
           outputPath: {
             type: "string",
             description: "Custom output path"
+          },
+          isSystemEntity: {
+            type: "boolean",
+            description: "If true, creates a system entity without TenantId (for entity type)"
+          },
+          tablePrefix: {
+            type: "string",
+            description: 'Domain prefix for table name (e.g., "auth_", "nav_", "cfg_")'
+          },
+          schema: {
+            type: "string",
+            enum: ["core", "extensions"],
+            description: "Database schema (default: core)"
           }
         }
       }
@@ -1258,40 +1286,166 @@ services.AddScoped<I{{name}}Service, {{name}}Service>();
 async function scaffoldEntity(name, options, structure, config, result) {
   const namespace = options?.namespace || config.conventions.namespaces.domain;
   const baseEntity = options?.baseEntity;
+  const isSystemEntity = options?.isSystemEntity || false;
+  const tablePrefix = options?.tablePrefix || "ref_";
+  const schema = options?.schema || config.conventions.schemas.platform;
   const entityTemplate = `using System;
+using SmartStack.Domain.Common;
+using SmartStack.Domain.Common.Interfaces;
 
 namespace {{namespace}};
 
 /// <summary>
 /// {{name}} entity{{#if baseEntity}} extending {{baseEntity}}{{/if}}
 /// </summary>
-public class {{name}}{{#if baseEntity}} : {{baseEntity}}{{/if}}
+{{#if isSystemEntity}}
+public class {{name}} : SystemEntity
+{{else}}
+public class {{name}} : BaseEntity
+{{/if}}
 {
-{{#unless baseEntity}}
-    public Guid Id { get; set; }
+{{#if baseEntity}}
+    /// <summary>
+    /// Foreign key to {{baseEntity}}
+    /// </summary>
+    public Guid {{baseEntity}}Id { get; private set; }
+
+    /// <summary>
+    /// Navigation property to {{baseEntity}}
+    /// </summary>
+    public virtual {{baseEntity}}? {{baseEntity}} { get; private set; }
 
-    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+{{/if}}
+    // === BUSINESS PROPERTIES ===
+    // TODO: Add {{name}} specific properties here
 
-    public DateTime? UpdatedAt { get; set; }
+    /// <summary>
+    /// Private constructor for EF Core
+    /// </summary>
+    private {{name}}() { }
 
-{{/unless}}
-    // TODO: Add {{name}} specific properties
+    /// <summary>
+    /// Factory method to create a new {{name}}
+    /// </summary>
+{{#if isSystemEntity}}
+    public static {{name}} Create(
+        string code,
+        string? createdBy = null)
+    {
+        return new {{name}}
+        {
+            Id = Guid.NewGuid(),
+            Code = code.ToLowerInvariant(),
+            CreatedAt = DateTime.UtcNow,
+            CreatedBy = createdBy
+        };
+    }
+{{else}}
+    public static {{name}} Create(
+        Guid tenantId,
+        string code,
+        string? createdBy = null)
+    {
+        return new {{name}}
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Code = code.ToLowerInvariant(),
+            CreatedAt = DateTime.UtcNow,
+            CreatedBy = createdBy
+        };
+    }
+{{/if}}
+
+    /// <summary>
+    /// Update the entity
+    /// </summary>
+    public void Update(string? updatedBy = null)
+    {
+        UpdatedAt = DateTime.UtcNow;
+        UpdatedBy = updatedBy;
+    }
+
+    /// <summary>
+    /// Soft delete the entity
+    /// </summary>
+    public void SoftDelete(string? deletedBy = null)
+    {
+        IsDeleted = true;
+        DeletedAt = DateTime.UtcNow;
+        DeletedBy = deletedBy;
+    }
+
+    /// <summary>
+    /// Restore a soft-deleted entity
+    /// </summary>
+    public void Restore(string? restoredBy = null)
+    {
+        IsDeleted = false;
+        DeletedAt = null;
+        DeletedBy = null;
+        UpdatedAt = DateTime.UtcNow;
+        UpdatedBy = restoredBy;
+    }
 }
 `;
   const configTemplate = `using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using {{domainNamespace}};
 
 namespace {{infrastructureNamespace}}.Persistence.Configurations;
 
-public class {{name}}Configuration : IEntityTypeConfiguration<{{domainNamespace}}.{{name}}>
+public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
 {
-    public void Configure(EntityTypeBuilder<{{domainNamespace}}.{{name}}> builder)
+    public void Configure(EntityTypeBuilder<{{name}}> builder)
     {
-        builder.ToTable("{{tablePrefix}}{{name}}s");
+        // Table name with schema and domain prefix
+        builder.ToTable("{{tablePrefix}}{{name}}s", "{{schema}}");
 
+        // Primary key
         builder.HasKey(e => e.Id);
 
-        // TODO: Add {{name}} specific configuration
+{{#unless isSystemEntity}}
+        // Multi-tenant
+        builder.Property(e => e.TenantId).IsRequired();
+        builder.HasIndex(e => e.TenantId);
+
+        // Code: lowercase, unique per tenant (filtered for soft delete)
+        builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
+        builder.HasIndex(e => new { e.TenantId, e.Code })
+            .IsUnique()
+            .HasFilter("[IsDeleted] = 0")
+            .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_Tenant_Code_Unique");
+{{else}}
+        // Code: lowercase, unique (filtered for soft delete)
+        builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
+        builder.HasIndex(e => e.Code)
+            .IsUnique()
+            .HasFilter("[IsDeleted] = 0")
+            .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_Code_Unique");
+{{/unless}}
+
+        // Concurrency token
+        builder.Property(e => e.RowVersion).IsRowVersion();
+
+        // Audit fields
+        builder.Property(e => e.CreatedBy).HasMaxLength(256);
+        builder.Property(e => e.UpdatedBy).HasMaxLength(256);
+        builder.Property(e => e.DeletedBy).HasMaxLength(256);
+
+{{#if baseEntity}}
+        // Relationship to {{baseEntity}} (1:1)
+        builder.HasOne(e => e.{{baseEntity}})
+               .WithOne()
+               .HasForeignKey<{{name}}>(e => e.{{baseEntity}}Id)
+               .OnDelete(DeleteBehavior.Cascade);
+
+        // Index on foreign key
+        builder.HasIndex(e => e.{{baseEntity}}Id)
+               .IsUnique();
+{{/if}}
+
+        // TODO: Add additional configuration
     }
 }
 `;
@@ -1299,9 +1453,11 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{domainNamespace}
     namespace,
     name,
     baseEntity,
+    isSystemEntity,
+    tablePrefix,
+    schema,
     infrastructureNamespace: config.conventions.namespaces.infrastructure,
-    domainNamespace: config.conventions.namespaces.domain,
-    schema: config.conventions.schemas.platform
+    domainNamespace: config.conventions.namespaces.domain
   };
   const entityContent = Handlebars.compile(entityTemplate)(context);
   const configContent = Handlebars.compile(configTemplate)(context);
@@ -1319,7 +1475,13 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{domainNamespace}
   result.instructions.push(`public DbSet<${name}> ${name}s => Set<${name}>();`);
   result.instructions.push("");
   result.instructions.push("Create migration:");
-  result.instructions.push(`dotnet ef migrations add Add${name}`);
+  result.instructions.push(`dotnet ef migrations add core_vX.X.X_XXX_Add${name} --context ApplicationDbContext`);
+  result.instructions.push("");
+  result.instructions.push("Required fields from BaseEntity:");
+  result.instructions.push(`- Id (Guid), ${isSystemEntity ? "" : "TenantId (Guid), "}Code (string, lowercase)`);
+  result.instructions.push("- CreatedAt, UpdatedAt, CreatedBy, UpdatedBy (audit)");
+  result.instructions.push("- IsDeleted, DeletedAt, DeletedBy (soft delete)");
+  result.instructions.push("- RowVersion (concurrency)");
 }
 async function scaffoldController(name, options, structure, config, result) {
   const namespace = options?.namespace || `${config.conventions.namespaces.api}.Controllers`;
@@ -1905,7 +2067,7 @@ var conventionsResourceTemplate = {
   mimeType: "text/markdown"
 };
 async function getConventionsResource(config) {
-  const { schemas, tablePrefixes, migrationFormat, namespaces, servicePattern } = config.conventions;
+  const { schemas, tablePrefixes, codePrefixes, migrationFormat, namespaces, servicePattern } = config.conventions;
   return `# AtlasHub SmartStack Conventions
 
 ## Overview
@@ -1944,6 +2106,37 @@ Tables are organized by domain using prefixes:
 | \`loc_\` | Localization | loc_Languages, loc_Translations |
 | \`lic_\` | Licensing | lic_Licenses |
 
+### Navigation Code Prefixes
+
+All navigation data (Context, Application, Module, Section, Resource) uses code prefixes to distinguish system data from client extensions:
+
+| Origin | Prefix | Usage | Example |
+|--------|--------|-------|---------|
+| SmartStack (system) | \`${codePrefixes.core}\` | Protected, delivered with SmartStack | \`${codePrefixes.core}administration\` |
+| Client (extension) | \`${codePrefixes.extension}\` | Custom, added by clients | \`${codePrefixes.extension}it\` |
+
+**Navigation Hierarchy (5 levels):**
+
+\`\`\`
+Context \u2192 Application \u2192 Module \u2192 Section \u2192 Resource
+\`\`\`
+
+**Examples for each level:**
+
+| Level | Core Example | Extension Example |
+|-------|--------------|-------------------|
+| Context | \`${codePrefixes.core}administration\` | \`${codePrefixes.extension}it\` |
+| Application | \`${codePrefixes.core}settings\` | \`${codePrefixes.extension}custom_app\` |
+| Module | \`${codePrefixes.core}users\` | \`${codePrefixes.extension}inventory\` |
+| Section | \`${codePrefixes.core}management\` | \`${codePrefixes.extension}reports\` |
+| Resource | \`${codePrefixes.core}user_list\` | \`${codePrefixes.extension}stock_view\` |
+
+**Rules:**
+1. \`${codePrefixes.core}*\` codes are **protected** - clients cannot create or modify them
+2. \`${codePrefixes.extension}*\` codes are **free** - clients can create custom navigation
+3. SmartStack updates will never overwrite \`${codePrefixes.extension}*\` data
+4. Codes must be unique within their level (e.g., no two Contexts with same code)
+
 ### Entity Configuration
 
 \`\`\`csharp
@@ -2187,6 +2380,197 @@ public interface IUserServiceHooks
 
 ---
 
+## 7. Entity Conventions
+
+### Required Interfaces
+
+All entities MUST implement the following interfaces:
+
+| Interface | Properties | Required |
+|-----------|------------|----------|
+| \`ITenantEntity\` | \`TenantId\` (Guid) | **YES** (except system entities) |
+| \`IHasCode\` | \`Code\` (string, lowercase, max 100) | **YES** |
+| \`ISoftDeletable\` | \`IsDeleted\`, \`DeletedAt\`, \`DeletedBy\` | **YES** |
+| \`IVersioned\` | \`RowVersion\` (byte[]) | **YES** |
+| \`IHistoryEntity<T>\` | \`SourceId\`, \`ChangeType\`, \`OldValues\`, \`NewValues\`, \`ChangedAt\`, \`ChangedBy\` | For history tables |
+
+### Required Fields (All Entities)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`Id\` | \`Guid\` | Primary key |
+| \`TenantId\` | \`Guid\` | **Tenant identifier** (required for multi-tenant isolation) |
+| \`Code\` | \`string\` | Unique identifier per tenant (lowercase, max 100) |
+| \`CreatedAt\` | \`DateTime\` | Creation timestamp |
+| \`UpdatedAt\` | \`DateTime?\` | Last update timestamp |
+| \`CreatedBy\` | \`string?\` | User who created the entity |
+| \`UpdatedBy\` | \`string?\` | User who last updated the entity |
+| \`IsDeleted\` | \`bool\` | Soft delete flag |
+| \`DeletedAt\` | \`DateTime?\` | Deletion timestamp |
+| \`DeletedBy\` | \`string?\` | User who deleted the entity |
+| \`RowVersion\` | \`byte[]\` | Concurrency token |
+
+### Multi-Tenant Strategy
+
+\`\`\`csharp
+// Interface for tenant-scoped entities
+public interface ITenantEntity
+{
+    Guid TenantId { get; set; }
+}
+
+// Global query filter (applied automatically)
+builder.HasQueryFilter(e => e.TenantId == _currentTenantService.TenantId);
+\`\`\`
+
+**System Entities (without TenantId):**
+- Licenses (\`lic_\`)
+- Global configuration (\`cfg_\` system level)
+- Shared reference tables
+
+Use \`ISystemEntity\` marker interface for these entities.
+
+### Code Field Rules
+
+1. **Always lowercase** - Normalized via setter and value converter
+2. **Prefix required**: \`${codePrefixes.core}\` (system) or \`${codePrefixes.extension}\` (extensions)
+3. **Unique composite index**: \`(TenantId, Code) WHERE IsDeleted = 0\`
+4. **Max length**: 100 characters
+
+\`\`\`csharp
+// Code property with automatic lowercase normalization
+private string _code = string.Empty;
+public string Code
+{
+    get => _code;
+    set => _code = value?.ToLowerInvariant() ?? string.Empty;
+}
+\`\`\`
+
+### Soft Delete with Restore
+
+\`\`\`csharp
+public interface ISoftDeletable
+{
+    bool IsDeleted { get; set; }
+    DateTime? DeletedAt { get; set; }
+    string? DeletedBy { get; set; }
+}
+
+// Domain methods
+public void SoftDelete(string? deletedBy = null)
+{
+    IsDeleted = true;
+    DeletedAt = DateTime.UtcNow;
+    DeletedBy = deletedBy;
+}
+
+public void Restore(string? restoredBy = null)
+{
+    IsDeleted = false;
+    DeletedAt = null;
+    DeletedBy = null;
+    UpdatedAt = DateTime.UtcNow;
+    UpdatedBy = restoredBy;
+}
+\`\`\`
+
+### History Tables (JSON Pattern)
+
+\`\`\`csharp
+public interface IHistoryEntity<TSourceId>
+{
+    Guid Id { get; set; }
+    TSourceId SourceId { get; set; }
+    ChangeType ChangeType { get; set; }  // Created, Updated, Deleted
+    DateTime ChangedAt { get; set; }
+    string? ChangedBy { get; set; }
+    string? OldValues { get; set; }  // JSON snapshot before change
+    string? NewValues { get; set; }  // JSON snapshot after change
+}
+
+public enum ChangeType { Created = 1, Updated = 2, Deleted = 3 }
+\`\`\`
+
+### Complete Entity Example
+
+\`\`\`csharp
+public class MyEntity : BaseEntity
+{
+    // === REQUIRED (from BaseEntity) ===
+    // public Guid Id { get; set; }
+    // public Guid TenantId { get; set; }
+    // public string Code { get; set; }  // lowercase, unique per tenant
+    // public DateTime CreatedAt { get; set; }
+    // public DateTime? UpdatedAt { get; set; }
+    // public string? CreatedBy { get; set; }
+    // public string? UpdatedBy { get; set; }
+    // public bool IsDeleted { get; set; }
+    // public DateTime? DeletedAt { get; set; }
+    // public string? DeletedBy { get; set; }
+    // public byte[] RowVersion { get; set; }
+
+    // === BUSINESS PROPERTIES ===
+    public string Name { get; private set; } = null!;
+
+    private MyEntity() { }
+
+    public static MyEntity Create(Guid tenantId, string code, string name, string? createdBy = null)
+    {
+        return new MyEntity
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow,
+            CreatedBy = createdBy
+        };
+    }
+}
+\`\`\`
+
+### EF Core Configuration
+
+\`\`\`csharp
+public class MyEntityConfiguration : IEntityTypeConfiguration<MyEntity>
+{
+    public void Configure(EntityTypeBuilder<MyEntity> builder)
+    {
+        builder.ToTable("domain_MyEntities", "${schemas.platform}");
+        builder.HasKey(e => e.Id);
+
+        // Multi-tenant
+        builder.Property(e => e.TenantId).IsRequired();
+        builder.HasIndex(e => e.TenantId);
+
+        // Code: lowercase, unique per tenant (filtered)
+        builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
+        builder.HasIndex(e => new { e.TenantId, e.Code })
+            .IsUnique()
+            .HasFilter("[IsDeleted] = 0");
+
+        // Concurrency
+        builder.Property(e => e.RowVersion).IsRowVersion();
+
+        // Audit fields
+        builder.Property(e => e.CreatedBy).HasMaxLength(256);
+        builder.Property(e => e.UpdatedBy).HasMaxLength(256);
+        builder.Property(e => e.DeletedBy).HasMaxLength(256);
+    }
+}
+\`\`\`
+
+### Entity Types Summary
+
+| Type | Fields | Use Case |
+|------|--------|----------|
+| **BaseEntity** | All required fields | Standard tenant-scoped entities |
+| **SystemEntity** | All except TenantId | Shared system entities |
+| **HistoryEntity** | Id, TenantId, SourceId, ChangeType, Values, ChangedAt/By | Audit trail tables |
+
+---
+
 ## Quick Reference
 
 | Category | Convention | Example |
@@ -2194,11 +2578,14 @@ public interface IUserServiceHooks
 | Platform schema | \`${schemas.platform}\` | \`.ToTable("auth_Users", "${schemas.platform}")\` |
 | Extensions schema | \`${schemas.extensions}\` | \`.ToTable("client_Custom", "${schemas.extensions}")\` |
 | Table prefixes | \`${tablePrefixes.slice(0, 5).join(", ")}\`, etc. | \`auth_Users\`, \`nav_Modules\` |
+| Core code prefix | \`${codePrefixes.core}\` | \`${codePrefixes.core}administration\` |
+| Extension code prefix | \`${codePrefixes.extension}\` | \`${codePrefixes.extension}custom_module\` |
 | Migration | \`{context}_v{version}_{seq}_{Desc}\` | \`core_v1.0.0_001_CreateAuthUsers\` |
 | Interface | \`I<Name>Service\` | \`IUserService\` |
 | Implementation | \`<Name>Service\` | \`UserService\` |
 | Domain namespace | \`${namespaces.domain}\` | - |
 | API namespace | \`${namespaces.api}\` | - |
+| Required entity fields | Id, TenantId, Code, Audit, SoftDelete, RowVersion | See Entity Conventions |
 `;
 }