@atlashub/smartstack-cli 1.13.2 → 1.14.0

package/templates/commands/refactor.md

@@ -0,0 +1,164 @@
+---
+description: Refactor code by finding files, grouping them, and launching parallel Snipper agents
+argument-hint: <search-pattern-or-description>
+---
+
+<objective>
+Refactor code matching #$ARGUMENTS across the codebase using parallel Snipper agents for maximum speed.
+
+This command finds all relevant files, creates ONE instruction file, then launches Snipper agents in parallel with batches of max 3 files each.
+</objective>
+
+<process>
+
+## Phase 1: Discovery
+
+1. **Parse the refactor request**: Understand what #$ARGUMENTS means
+   - Could be: method name, component name, pattern, code smell, etc.
+   - Identify the search strategy (Grep for code patterns, Glob for file patterns)
+
+2. **Find all affected files**:
+   - Use Grep to search for the pattern in the codebase
+   - Use Glob if searching by file name patterns
+   - Exclude node_modules, .git, dist, build directories
+   - List all files that need refactoring
+
+3. **Analyze scope**:
+   - Count total files found
+   - If more than 15 files, ask user to confirm or narrow scope
+   - Show preview of files to refactor
+
+## Phase 2: Create Instructions
+
+4. **Create task folder**:
+   - Generate unique ID: `refactor-{timestamp}`
+   - Create folder: `.claude/tasks/refactor-{timestamp}/`
+
+5. **Create ONE instruction file**:
+   Create `.claude/tasks/refactor-{id}/instructions.md` with precise, adaptive instructions:
+
+   ```markdown
+   # Refactor Instructions
+
+   ## Objective
+   {Clear description of what to refactor based on #$ARGUMENTS}
+
+   ## What to Change
+   {Specific patterns/code to find and modify}
+
+   ## How to Change
+   {Step-by-step transformation rules}
+
+   ## Rules
+   - Follow existing codebase patterns
+   - No unnecessary comments
+   - Preserve functionality
+   - Only modify what's necessary for this refactor
+   ```
+
+   **IMPORTANT**: Make instructions adaptive - they should work for ANY file in the list.
+
+## Phase 3: Group and Execute
+
+6. **Group files into batches**:
+   - Maximum 3 files per batch
+   - Group by related functionality when possible
+
+7. **Launch Snipper agents in parallel**:
+   For EACH batch, use Task tool with subagent_type='Snipper':
+
+   ```
+   Using the instructions in .claude/tasks/refactor-{id}/instructions.md, refactor these files:
+   - {file_1}
+   - {file_2}
+   - {file_3}
+   ```
+
+   **CRITICAL**: Launch ALL batches in a SINGLE message with multiple Task calls.
+
+8. **Wait for completion**:
+   - All Snipper agents run in parallel
+   - Collect results from each
+
+## Phase 4: Verification
+
+9. **Validate changes**:
+   - Run `pnpm lint` or `npm run lint` to check for errors
+   - Run `pnpm tsc` or `npx tsc` if TypeScript project
+   - Report any failures
+
+10. **Summary report**:
+    - List all files modified
+    - Show any errors encountered
+    - Provide next steps if needed
+
+</process>
+
+<instructions_template>
+Create ONE file at `.claude/tasks/refactor-{id}/instructions.md`:
+
+```markdown
+# Refactor: {title}
+
+## Objective
+{What needs to be refactored - derived from #$ARGUMENTS}
+
+## Pattern to Find
+{Exact code pattern, method name, or structure to locate}
+
+## Transformation
+{How to transform the found pattern - be specific and adaptive}
+
+## Examples
+Before:
+```
+{example of current code}
+```
+
+After:
+```
+{example of refactored code}
+```
+
+## Constraints
+- Only modify code matching the pattern
+- Preserve all existing functionality
+- Follow codebase conventions
+- No comments unless necessary
+```
+</instructions_template>
+
+<snipper_prompt_template>
+For each batch, call Snipper with:
+
+```
+Using the instructions in .claude/tasks/refactor-{id}/instructions.md, refactor these files:
+- {file_path_1}
+- {file_path_2}
+- {file_path_3}
+
+Read the instructions file first, then apply the refactor to each file.
+```
+</snipper_prompt_template>
+
+<success_criteria>
+- All target files identified
+- ONE instruction file created in `.claude/tasks/refactor-{id}/instructions.md`
+- Snipper agents launched in parallel (max 3 files per agent)
+- All batches completed successfully
+- Lint/type checks pass
+- Summary provided to user
+</success_criteria>
+
+<example>
+User: `/refactor rename getUserData to fetchUserProfile`
+
+1. Grep finds 12 files containing "getUserData"
+2. Creates `.claude/tasks/refactor-1702489200/`
+3. Creates ONE file: `instructions.md` with rename rules
+4. Groups into 4 batches of 3 files
+5. Launches 4 Snipper agents in parallel, each with:
+   "Using instructions in .../instructions.md, refactor: file1, file2, file3"
+6. Waits for completion, runs lint
+7. Reports: "Refactored 12 files, renamed getUserData to fetchUserProfile"
+</example>

package/templates/project/DependencyInjection.Application.cs.template

@@ -0,0 +1,25 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace {{ProjectName}}.Application;
+
+/// <summary>
+/// Dependency injection configuration for client Application layer.
+/// </summary>
+public static class DependencyInjection
+{
+    /// <summary>
+    /// Adds client-specific application services to the DI container.
+    ///
+    /// IMPORTANT: This must be called AFTER AddSmartStackApplication()
+    /// to ensure all Core services are available.
+    /// </summary>
+    public static IServiceCollection Add{{ProjectName}}Application(
+        this IServiceCollection services)
+    {
+        // TODO: Register your application services here
+        // Example:
+        // services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(DependencyInjection).Assembly));
+
+        return services;
+    }
+}

package/templates/project/DependencyInjection.Infrastructure.cs.template

@@ -0,0 +1,61 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Diagnostics;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using {{ProjectName}}.Application.Common.Interfaces;
+using {{ProjectName}}.Infrastructure.Persistence;
+using SmartStack.Infrastructure.Persistence.Configurations;
+
+namespace {{ProjectName}}.Infrastructure;
+
+/// <summary>
+/// Dependency injection configuration for client Infrastructure layer.
+/// </summary>
+public static class DependencyInjection
+{
+    /// <summary>
+    /// Adds client-specific infrastructure services to the DI container.
+    ///
+    /// IMPORTANT: This must be called AFTER AddSmartStackInfrastructure()
+    /// to ensure CoreDbContext is registered first.
+    /// </summary>
+    public static IServiceCollection Add{{ProjectName}}Infrastructure(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        // ExtensionsDbContext with migrations in 'extensions' schema
+        services.AddDbContext<ExtensionsDbContext>(options =>
+        {
+            options.UseSqlServer(
+                configuration.GetConnectionString("DefaultConnection"),
+                sqlOptions =>
+                {
+                    sqlOptions.MigrationsAssembly(typeof(ExtensionsDbContext).Assembly.FullName);
+
+                    // Store migrations history in extensions schema (separate from Core)
+                    sqlOptions.MigrationsHistoryTable("__EFMigrationsHistory", SchemaConstants.Extensions);
+
+                    // Enable retry policy for transient failures
+                    sqlOptions.EnableRetryOnFailure(
+                        maxRetryCount: 5,
+                        maxRetryDelay: TimeSpan.FromSeconds(10),
+                        errorNumbersToAdd: null);
+
+                    // Set command timeout
+                    sqlOptions.CommandTimeout(60);
+                });
+
+            // Suppress false positive warning for static seed data
+            options.ConfigureWarnings(w => w.Ignore(RelationalEventId.PendingModelChangesWarning));
+        });
+
+        // Register the interface
+        services.AddScoped<IExtensionsDbContext>(provider =>
+            provider.GetRequiredService<ExtensionsDbContext>());
+
+        // TODO: Register your services here
+        // services.AddScoped<IOrderService, OrderService>();
+
+        return services;
+    }
+}

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);
+    }
+}