@atlashub/smartstack-cli 1.13.2 → 1.14.1

package/templates/project/DesignTimeExtensionsDbContextFactory.cs.template

@@ -0,0 +1,70 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Design;
+using Microsoft.Extensions.Configuration;
+using SmartStack.Infrastructure.Persistence.Configurations;
+
+namespace {{ProjectName}}.Infrastructure.Persistence;
+
+/// <summary>
+/// Factory for creating ExtensionsDbContext at design time (for EF Core CLI tools).
+///
+/// This enables running migrations from the command line:
+/// <code>
+/// dotnet ef migrations add MyMigration --context ExtensionsDbContext
+/// dotnet ef database update --context ExtensionsDbContext
+/// dotnet ef migrations list --context ExtensionsDbContext
+/// dotnet ef migrations script --context ExtensionsDbContext -o deploy.sql
+/// </code>
+///
+/// IMPORTANT: Migrations are stored in the 'extensions' schema, separate from
+/// SmartStack Core migrations in the 'core' schema.
+/// </summary>
+public class DesignTimeExtensionsDbContextFactory : IDesignTimeDbContextFactory<ExtensionsDbContext>
+{
+    public ExtensionsDbContext CreateDbContext(string[] args)
+    {
+        // Try to find appsettings.json in various locations
+        var basePath = Directory.GetCurrentDirectory();
+
+        // Look for appsettings.json in common locations
+        var configPaths = new[]
+        {
+            basePath,
+            Path.Combine(basePath, "..", "{{ProjectName}}.Api"),
+            Path.Combine(basePath, "..", "..", "src", "{{ProjectName}}.Api"),
+        };
+
+        IConfigurationRoot? configuration = null;
+
+        foreach (var path in configPaths)
+        {
+            var configPath = Path.Combine(path, "appsettings.json");
+            if (File.Exists(configPath))
+            {
+                configuration = new ConfigurationBuilder()
+                    .SetBasePath(path)
+                    .AddJsonFile("appsettings.json", optional: false)
+                    .AddJsonFile("appsettings.Development.json", optional: true)
+                    .AddJsonFile("appsettings.Local.json", optional: true)
+                    .Build();
+                break;
+            }
+        }
+
+        // Fallback: use a default connection string for design-time operations
+        var connectionString = configuration?.GetConnectionString("DefaultConnection")
+            ?? "Server=(localdb)\\mssqllocaldb;Database={{ProjectName}}_DesignTime;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True";
+
+        var optionsBuilder = new DbContextOptionsBuilder<ExtensionsDbContext>();
+        optionsBuilder.UseSqlServer(connectionString, b =>
+        {
+            b.MigrationsAssembly(typeof(ExtensionsDbContext).Assembly.FullName);
+
+            // IMPORTANT: Store migrations history in 'extensions' schema
+            // This keeps client migrations separate from Core migrations
+            b.MigrationsHistoryTable("__EFMigrationsHistory", SchemaConstants.Extensions);
+        });
+
+        return new ExtensionsDbContext(optionsBuilder.Options);
+    }
+}

package/templates/project/ExampleEntity.cs.template

@@ -0,0 +1,116 @@
+using SmartStack.Domain.Common;
+
+namespace {{ProjectName}}.Domain.Entities;
+
+/// <summary>
+/// Example entity demonstrating FK reference to Core entities.
+///
+/// IMPORTANT: Notice that we store only the UserId (GUID), NOT a navigation property.
+/// This is because ExtensionsDbContext doesn't know about Core entities.
+/// Use ICoreDataService to fetch the User data when needed.
+/// </summary>
+public class Order : BaseAuditableEntity
+{
+    /// <summary>
+    /// Order number (auto-generated or custom format).
+    /// </summary>
+    public string OrderNumber { get; private set; } = null!;
+
+    /// <summary>
+    /// Foreign key to the User who created this order.
+    ///
+    /// IMPORTANT: This is a GUID reference only, NOT a navigation property!
+    /// Use ICoreDataService.GetUserByIdAsync() to fetch user details.
+    /// </summary>
+    public Guid CustomerId { get; private set; }
+
+    /// <summary>
+    /// Order status.
+    /// </summary>
+    public OrderStatus Status { get; private set; }
+
+    /// <summary>
+    /// Total amount.
+    /// </summary>
+    public decimal TotalAmount { get; private set; }
+
+    /// <summary>
+    /// Order date.
+    /// </summary>
+    public DateTime OrderDate { get; private set; }
+
+    /// <summary>
+    /// Optional notes.
+    /// </summary>
+    public string? Notes { get; private set; }
+
+    // Private constructor for EF Core
+    private Order() { }
+
+    /// <summary>
+    /// Creates a new order.
+    /// </summary>
+    /// <param name="orderNumber">Order number</param>
+    /// <param name="customerId">ID of the user placing the order (from Core)</param>
+    /// <param name="totalAmount">Total amount</param>
+    public static Order Create(string orderNumber, Guid customerId, decimal totalAmount)
+    {
+        return new Order
+        {
+            OrderNumber = orderNumber,
+            CustomerId = customerId,
+            Status = OrderStatus.Pending,
+            TotalAmount = totalAmount,
+            OrderDate = DateTime.UtcNow
+        };
+    }
+
+    public void Confirm()
+    {
+        if (Status != OrderStatus.Pending)
+            throw new InvalidOperationException("Only pending orders can be confirmed.");
+
+        Status = OrderStatus.Confirmed;
+    }
+
+    public void Ship()
+    {
+        if (Status != OrderStatus.Confirmed)
+            throw new InvalidOperationException("Only confirmed orders can be shipped.");
+
+        Status = OrderStatus.Shipped;
+    }
+
+    public void Complete()
+    {
+        if (Status != OrderStatus.Shipped)
+            throw new InvalidOperationException("Only shipped orders can be completed.");
+
+        Status = OrderStatus.Completed;
+    }
+
+    public void Cancel()
+    {
+        if (Status == OrderStatus.Completed)
+            throw new InvalidOperationException("Completed orders cannot be cancelled.");
+
+        Status = OrderStatus.Cancelled;
+    }
+
+    public void AddNotes(string notes)
+    {
+        Notes = notes;
+    }
+}
+
+/// <summary>
+/// Order status enum.
+/// </summary>
+public enum OrderStatus
+{
+    Pending = 0,
+    Confirmed = 1,
+    Shipped = 2,
+    Completed = 3,
+    Cancelled = 4
+}

package/templates/project/ExampleEntityConfiguration.cs.template

@@ -0,0 +1,64 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using {{ProjectName}}.Domain.Entities;
+using SmartStack.Infrastructure.Persistence.Configurations;
+
+namespace {{ProjectName}}.Infrastructure.Persistence.Configurations;
+
+/// <summary>
+/// EF Core configuration for the Order entity.
+///
+/// NOTE: The table is created in the 'extensions' schema as defined by
+/// ExtensionsDbContext.HasDefaultSchema(SchemaConstants.Extensions).
+/// </summary>
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        // Table name with domain prefix (following SmartStack conventions)
+        // Use a prefix that makes sense for your domain
+        builder.ToTable("biz_Orders", SchemaConstants.Extensions);
+
+        // Primary key
+        builder.HasKey(e => e.Id);
+
+        // Properties
+        builder.Property(e => e.OrderNumber)
+            .IsRequired()
+            .HasMaxLength(50);
+
+        builder.Property(e => e.Status)
+            .IsRequired();
+
+        builder.Property(e => e.TotalAmount)
+            .HasPrecision(18, 2);
+
+        builder.Property(e => e.OrderDate)
+            .IsRequired();
+
+        builder.Property(e => e.Notes)
+            .HasMaxLength(1000);
+
+        // CustomerId is a GUID FK to Core.auth_Users
+        // IMPORTANT: We do NOT create a navigation property or FK constraint
+        // because the User table is in a different DbContext (CoreDbContext)
+        builder.Property(e => e.CustomerId)
+            .IsRequired();
+
+        // NOTE: No .HasOne() or navigation property to User!
+        // Use ICoreDataService.GetUserByIdAsync() to fetch user data
+
+        // Indexes
+        builder.HasIndex(e => e.OrderNumber)
+            .IsUnique();
+
+        builder.HasIndex(e => e.CustomerId);
+
+        builder.HasIndex(e => e.Status);
+
+        builder.HasIndex(e => e.OrderDate);
+
+        // Query filter for soft delete (if using BaseAuditableEntity)
+        builder.HasQueryFilter(e => !e.IsDeleted);
+    }
+}

package/templates/project/ExampleService.cs.template

@@ -0,0 +1,146 @@
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Application.Common.Interfaces;
+using {{ProjectName}}.Application.Common.Interfaces;
+using {{ProjectName}}.Domain.Entities;
+
+namespace {{ProjectName}}.Infrastructure.Services;
+
+/// <summary>
+/// Example service demonstrating how to use ICoreDataService
+/// to fetch Core entity data (User, Role, etc.) from Extensions context.
+/// </summary>
+public class OrderService : IOrderService
+{
+    private readonly IExtensionsDbContext _context;
+    private readonly ICoreDataService _coreDataService;
+
+    public OrderService(
+        IExtensionsDbContext context,
+        ICoreDataService coreDataService)
+    {
+        _context = context;
+        _coreDataService = coreDataService;
+    }
+
+    /// <summary>
+    /// Gets an order by ID, including customer information from Core.
+    /// </summary>
+    public async Task<OrderWithCustomerDto?> GetOrderWithCustomerAsync(
+        Guid orderId,
+        CancellationToken cancellationToken = default)
+    {
+        // 1. Get the order from Extensions context
+        var order = await _context.Orders
+            .AsNoTracking()
+            .FirstOrDefaultAsync(o => o.Id == orderId, cancellationToken);
+
+        if (order == null)
+            return null;
+
+        // 2. Use ICoreDataService to fetch customer info from Core context
+        // This is the correct way to access Core entities from Extensions!
+        var customer = await _coreDataService.GetUserBasicInfoAsync(
+            order.CustomerId,
+            cancellationToken);
+
+        // 3. Combine the data
+        return new OrderWithCustomerDto
+        {
+            Id = order.Id,
+            OrderNumber = order.OrderNumber,
+            Status = order.Status.ToString(),
+            TotalAmount = order.TotalAmount,
+            OrderDate = order.OrderDate,
+            CustomerId = order.CustomerId,
+            CustomerEmail = customer?.Email ?? "Unknown",
+            CustomerName = customer?.DisplayName ?? "Unknown"
+        };
+    }
+
+    /// <summary>
+    /// Gets all orders for a customer.
+    /// </summary>
+    public async Task<IReadOnlyList<OrderDto>> GetOrdersByCustomerAsync(
+        Guid customerId,
+        CancellationToken cancellationToken = default)
+    {
+        // First verify the customer exists in Core
+        var customer = await _coreDataService.GetUserBasicInfoAsync(
+            customerId,
+            cancellationToken);
+
+        if (customer == null)
+            throw new InvalidOperationException($"Customer {customerId} not found.");
+
+        // Get orders from Extensions context
+        return await _context.Orders
+            .AsNoTracking()
+            .Where(o => o.CustomerId == customerId)
+            .OrderByDescending(o => o.OrderDate)
+            .Select(o => new OrderDto
+            {
+                Id = o.Id,
+                OrderNumber = o.OrderNumber,
+                Status = o.Status.ToString(),
+                TotalAmount = o.TotalAmount,
+                OrderDate = o.OrderDate
+            })
+            .ToListAsync(cancellationToken);
+    }
+
+    /// <summary>
+    /// Creates a new order.
+    /// </summary>
+    public async Task<Guid> CreateOrderAsync(
+        string orderNumber,
+        Guid customerId,
+        decimal totalAmount,
+        CancellationToken cancellationToken = default)
+    {
+        // Validate that the customer exists in Core before creating order
+        var customer = await _coreDataService.GetUserByIdAsync(
+            customerId,
+            cancellationToken);
+
+        if (customer == null)
+            throw new InvalidOperationException($"Customer {customerId} not found.");
+
+        if (!customer.IsActive)
+            throw new InvalidOperationException("Cannot create order for inactive customer.");
+
+        // Create the order in Extensions context
+        var order = Order.Create(orderNumber, customerId, totalAmount);
+
+        _context.Orders.Add(order);
+        await _context.SaveChangesAsync(cancellationToken);
+
+        return order.Id;
+    }
+}
+
+// === DTOs ===
+
+public record OrderDto
+{
+    public Guid Id { get; init; }
+    public string OrderNumber { get; init; } = null!;
+    public string Status { get; init; } = null!;
+    public decimal TotalAmount { get; init; }
+    public DateTime OrderDate { get; init; }
+}
+
+public record OrderWithCustomerDto : OrderDto
+{
+    public Guid CustomerId { get; init; }
+    public string CustomerEmail { get; init; } = null!;
+    public string CustomerName { get; init; } = null!;
+}
+
+// === Interface ===
+
+public interface IOrderService
+{
+    Task<OrderWithCustomerDto?> GetOrderWithCustomerAsync(Guid orderId, CancellationToken cancellationToken = default);
+    Task<IReadOnlyList<OrderDto>> GetOrdersByCustomerAsync(Guid customerId, CancellationToken cancellationToken = default);
+    Task<Guid> CreateOrderAsync(string orderNumber, Guid customerId, decimal totalAmount, CancellationToken cancellationToken = default);
+}

package/templates/project/ExtensionsDbContext.cs.template

@@ -0,0 +1,41 @@
+using Microsoft.EntityFrameworkCore;
+using {{ProjectName}}.Application.Common.Interfaces;
+using SmartStack.Infrastructure.Persistence.Configurations;
+
+namespace {{ProjectName}}.Infrastructure.Persistence;
+
+/// <summary>
+/// DbContext for client-specific entities (schema: extensions).
+///
+/// This context manages all entities specific to your project.
+/// SmartStack Core entities (User, Role, etc.) are managed separately
+/// by CoreDbContext from the SmartStack NuGet package.
+///
+/// IMPORTANT: To reference Core entities (User, Role, etc.):
+/// - Store only the GUID foreign key (e.g., CreatedByUserId)
+/// - Use ICoreDataService to fetch the related entity data
+/// - Do NOT create navigation properties to Core entities
+/// </summary>
+public class ExtensionsDbContext : DbContext, IExtensionsDbContext
+{
+    public ExtensionsDbContext(DbContextOptions<ExtensionsDbContext> options)
+        : base(options)
+    {
+    }
+
+    // === YOUR ENTITIES ===
+    // Add your DbSet properties here. Example:
+    // public DbSet<Order> Orders => Set<Order>();
+    // public DbSet<Product> Products => Set<Product>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+
+        // All client entities go into the 'extensions' schema
+        modelBuilder.HasDefaultSchema(SchemaConstants.Extensions);
+
+        // Load entity configurations from this assembly
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ExtensionsDbContext).Assembly);
+    }
+}

package/templates/project/IExtensionsDbContext.cs.template

@@ -0,0 +1,22 @@
+using Microsoft.EntityFrameworkCore;
+
+namespace {{ProjectName}}.Application.Common.Interfaces;
+
+/// <summary>
+/// Interface for Extensions DbContext (client-specific entities).
+///
+/// This interface provides access to all entities specific to your project.
+/// For Core entities (User, Role, Permission, etc.), use ICoreDataService.
+/// </summary>
+public interface IExtensionsDbContext
+{
+    // === YOUR ENTITIES ===
+    // Add DbSet properties for your entities here. Example:
+    // DbSet<Order> Orders { get; }
+    // DbSet<Product> Products { get; }
+
+    /// <summary>
+    /// Saves all changes made in this context to the database.
+    /// </summary>
+    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
+}

package/templates/project/Program.cs.template

@@ -0,0 +1,47 @@
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Api.Extensions;
+using {{ProjectName}}.Infrastructure;
+using {{ProjectName}}.Infrastructure.Persistence;
+using {{ProjectName}}.Application;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// ===================================================================
+// 1. Add SmartStack Core services (from NuGet package)
+// ===================================================================
+builder.Services.AddSmartStack(builder.Configuration, options =>
+{
+    options.EnableDevSeeding = builder.Environment.IsDevelopment();
+    options.EnableSwagger = builder.Environment.IsDevelopment();
+});
+
+// ===================================================================
+// 2. Add client-specific services (Dual-DbContext pattern)
+// ===================================================================
+builder.Services.Add{{ProjectName}}Infrastructure(builder.Configuration);
+builder.Services.Add{{ProjectName}}Application();
+
+var app = builder.Build();
+
+// ===================================================================
+// 3. Initialize SmartStack + apply migrations (in correct order!)
+// ===================================================================
+// This initializes SmartStack and applies Core migrations automatically
+await app.InitializeSmartStackAsync();
+
+// Apply Extensions migrations AFTER Core migrations
+// Your client-specific tables may have FK references to Core tables
+if (app.Environment.IsDevelopment())
+{
+    using var scope = app.Services.CreateScope();
+    var extDb = scope.ServiceProvider.GetRequiredService<ExtensionsDbContext>();
+    await extDb.Database.MigrateAsync();
+}
+
+// ===================================================================
+// 4. SmartStack middleware & endpoints
+// ===================================================================
+app.UseSmartStack();
+app.MapSmartStack();
+
+app.Run();

package/templates/project/README.md

@@ -0,0 +1,79 @@
+# SmartStack Client Project Templates
+
+These templates are used by the SmartStack CLI to generate new client projects.
+
+## Template Files
+
+| File | Description | Destination |
+|------|-------------|-------------|
+| `ExtensionsDbContext.cs.template` | DbContext for client entities | `{ProjectName}.Infrastructure/Persistence/` |
+| `IExtensionsDbContext.cs.template` | Interface for ExtensionsDbContext | `{ProjectName}.Application/Common/Interfaces/` |
+| `DependencyInjection.Infrastructure.cs.template` | DI configuration for Infrastructure | `{ProjectName}.Infrastructure/` |
+| `Program.cs.template` | API entry point with migration order | `{ProjectName}.Api/` |
+| `DesignTimeExtensionsDbContextFactory.cs.template` | Factory for EF Core CLI tools | `{ProjectName}.Infrastructure/Persistence/` |
+| `ExampleEntity.cs.template` | Example entity with FK to Core | `{ProjectName}.Domain/Entities/` (optional) |
+| `ExampleService.cs.template` | Example service using ICoreDataService | `{ProjectName}.Infrastructure/Services/` (optional) |
+| `ExampleEntityConfiguration.cs.template` | Example EF Core configuration | `{ProjectName}.Infrastructure/Persistence/Configurations/` (optional) |
+
+## Placeholders
+
+The following placeholders are replaced during project generation:
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `{{ProjectName}}` | PascalCase project name | `MyCompany` |
+
+## Architecture Overview
+
+### Dual DbContext Pattern
+
+SmartStack uses two separate DbContexts:
+
+1. **CoreDbContext** (from SmartStack NuGet package)
+   - Schema: `core`
+   - Manages: Users, Roles, Permissions, Navigation, etc.
+   - Migrations: `core.__EFMigrationsHistory`
+
+2. **ExtensionsDbContext** (client project)
+   - Schema: `extensions`
+   - Manages: Client-specific entities
+   - Migrations: `extensions.__EFMigrationsHistory`
+
+### FK References to Core Entities
+
+When your entities need to reference Core entities (User, Role, etc.):
+
+```csharp
+// IN YOUR ENTITY - Store GUID only
+public Guid CustomerId { get; private set; }  // FK to User
+
+// IN YOUR SERVICE - Use ICoreDataService
+var user = await _coreDataService.GetUserByIdAsync(entity.CustomerId);
+```
+
+**DO NOT** create navigation properties to Core entities, as ExtensionsDbContext doesn't know about them.
+
+### Migration Order
+
+Migrations must be applied in order:
+
+1. Core migrations first (SmartStack platform tables)
+2. Extensions migrations second (client tables that may reference Core)
+
+This is handled automatically in `Program.cs.template`.
+
+## Usage
+
+```bash
+# Create new project
+smartstack init MyProject
+
+# Add entity to Extensions
+smartstack scaffold entity Order --context extensions
+
+# Create migration
+dotnet ef migrations add ext_v1.0.0_001_AddOrders --context ExtensionsDbContext
+
+# Apply migrations
+dotnet ef database update
+```

package/templates/ralph/README.md

@@ -27,15 +27,17 @@ Edit `ralph.config.yaml` to customize:
 
 Ralph **requires** these MCP servers to function:
 
-1. **context7** - Library documentation
-   ```bash
-   claude mcp add context7
-   ```
+### 1. Download MCP packages
+```bash
+npm install -g @atlashub/smartstack-mcp
+npm install -g @upstash/context7-mcp
+```
 
-2. **smartstack** - Validation and scaffolding
-   ```bash
-   claude mcp add smartstack
-   ```
+### 2. Register in Claude Code
+```bash
+claude mcp add smartstack -- npx @atlashub/smartstack-mcp
+claude mcp add context7 -- npx @upstash/context7-mcp
+```
 
 ## Usage
 

package/templates/ralph/ralph.config.yaml

@@ -9,12 +9,12 @@ mcp:
   required:
     - name: context7
       description: "Library documentation and code examples"
-      install_command: "claude mcp add context7"
+      install_command: "npm install -g @upstash/context7-mcp && claude mcp add context7 -- npx @upstash/context7-mcp"
       health_check: true
 
     - name: smartstack
       description: "SmartStack validation and scaffolding"
-      install_command: "claude mcp add smartstack"
+      install_command: "npm install -g @atlashub/smartstack-mcp && claude mcp add smartstack -- npx @atlashub/smartstack-mcp"
       health_check: true
 
   # Behavior when MCP is unavailable