@atlashub/smartstack-cli 4.33.0 → 4.34.0

package/templates/project/claude-md/infrastructure.CLAUDE.md.template

@@ -0,0 +1,168 @@
+# {{ProjectName}}.Infrastructure - Memory
+
+## Purpose
+
+Technical implementations. HOW things work. EF Core, external APIs, file system, email, etc.
+
+## Dependencies
+
+- **{{ProjectName}}.Domain** (entities, repository interfaces)
+- **{{ProjectName}}.Application** (IExtensionsDbContext, service interfaces)
+- **Microsoft.EntityFrameworkCore.SqlServer**
+- **Microsoft.EntityFrameworkCore.Design**
+
+## Structure
+
+```
+{{ProjectName}}.Infrastructure/
+├── Persistence/
+│   ├── ExtensionsDbContext.cs          → EF Core DbContext (implements IExtensionsDbContext)
+│   ├── Configurations/                 → Entity configurations (Fluent API)
+│   │   ├── {Feature}/                  → Feature-specific configs
+│   │   └── SchemaConstants.cs          → Extensions="extensions"
+│   ├── Migrations/                     → EF Core migrations
+│   └── Seeding/                        → Database seeders
+├── Services/                           → Service implementations
+└── DependencyInjection.cs
+```
+
+## Patterns
+
+### DbContext Template
+
+```csharp
+namespace {{ProjectName}}.Infrastructure.Persistence;
+
+public class ExtensionsDbContext : DbContext, IExtensionsDbContext
+{
+    public ExtensionsDbContext(DbContextOptions<ExtensionsDbContext> options)
+        : base(options) { }
+
+    public DbSet<Order> Orders => Set<Order>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.HasDefaultSchema(SchemaConstants.Extensions);
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ExtensionsDbContext).Assembly);
+    }
+
+    public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
+    {
+        return await base.SaveChangesAsync(ct);
+    }
+}
+```
+
+### Entity Configuration Template
+
+```csharp
+namespace {{ProjectName}}.Infrastructure.Persistence.Configurations.{Feature};
+
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        builder.ToTable("ext_Orders", SchemaConstants.Extensions);
+
+        builder.HasKey(o => o.Id);
+
+        builder.Property(o => o.Name)
+            .IsRequired()
+            .HasMaxLength(200);
+
+        builder.Property(o => o.Amount)
+            .HasPrecision(18, 2);
+
+        builder.HasIndex(o => o.Name);
+    }
+}
+```
+
+### Repository Implementation Template
+
+```csharp
+namespace {{ProjectName}}.Infrastructure.Persistence.Repositories;
+
+public class OrderRepository : IOrderRepository
+{
+    private readonly ExtensionsDbContext _context;
+
+    public OrderRepository(ExtensionsDbContext context)
+    {
+        _context = context;
+    }
+
+    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
+        => await _context.Orders.FindAsync(new object[] { id }, ct);
+
+    public async Task<IReadOnlyList<Order>> GetAllAsync(CancellationToken ct = default)
+        => await _context.Orders.ToListAsync(ct);
+
+    public async Task AddAsync(Order entity, CancellationToken ct = default)
+        => await _context.Orders.AddAsync(entity, ct);
+
+    public void Update(Order entity)
+        => _context.Orders.Update(entity);
+
+    public void Remove(Order entity)
+        => _context.Orders.Remove(entity);
+}
+```
+
+## DependencyInjection
+
+```csharp
+public static class DependencyInjection
+{
+    public static IServiceCollection AddInfrastructure(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        services.AddDbContext<ExtensionsDbContext>(options =>
+            options.UseSqlServer(
+                configuration.GetConnectionString("DefaultConnection"),
+                b => b.MigrationsAssembly(typeof(ExtensionsDbContext).Assembly.FullName)));
+
+        services.AddScoped<IExtensionsDbContext>(provider =>
+            provider.GetRequiredService<ExtensionsDbContext>());
+
+        return services;
+    }
+}
+```
+
+## EF Core Commands
+
+```bash
+# Create migration (ExtensionsDbContext)
+dotnet ef migrations add <Name> --context ExtensionsDbContext -p src/{{ProjectName}}.Infrastructure -s src/{{ProjectName}}.Api -o Persistence/Migrations
+
+# Update database
+dotnet ef database update --context ExtensionsDbContext -p src/{{ProjectName}}.Infrastructure -s src/{{ProjectName}}.Api
+
+# Remove last migration
+dotnet ef migrations remove --context ExtensionsDbContext -p src/{{ProjectName}}.Infrastructure -s src/{{ProjectName}}.Api
+```
+
+## Rules
+
+1. **ALL** EF configurations in `Configurations/` folder, organized by feature
+2. **NO** data annotations on entities - use Fluent API only
+3. **Repositories** implement interfaces from Application
+4. **DbContext** implements `IExtensionsDbContext` from Application
+5. **Migrations** stay in this project under `Persistence/Migrations/`
+6. **SQL objects via SqlObjectHelper** - TVFs/views use `SqlObjectHelper.ApplyAll(migrationBuilder)` and embedded `.sql` files
+7. **NO sequential/deterministic GUIDs in seed data** - All GUIDs must be generated via `[guid]::NewGuid()`
+8. **Schema prefix pattern** - Table names use format `{prefix}_{EntityName}` with schema `extensions`. Use `SchemaConstants.Extensions` constant.
+
+## When Adding New Entity
+
+1. Create entity in `{{ProjectName}}.Domain` with factory method
+2. Create repository interface in `{{ProjectName}}.Application/Common/Interfaces/Persistence/`
+3. Add `DbSet<Entity>` to `ExtensionsDbContext`
+4. Create configuration in `Persistence/Configurations/{Feature}/{Entity}Configuration.cs`
+5. Create repository in `Persistence/Repositories/{Entity}Repository.cs` (if needed)
+6. Register repository in `DependencyInjection.cs`
+7. Create migration: `/efcore:migration Add{Entity}`
+8. Run `/efcore:db-deploy` to apply migration

package/templates/project/claude-md/root.CLAUDE.md.template

@@ -0,0 +1,339 @@
+# {{ProjectName}} - Claude Instructions
+
+> **{{ProjectName}}** is built on the SmartStack platform (NuGet backend + npm frontend).
+> It extends SmartStack via the **Extensions pattern**: own DbContext, own schema, own modules.
+>
+> 1. SmartStack provides the core platform (auth, navigation, multi-tenant, licensing)
+> 2. {{ProjectName}} adds business-specific modules via `ExtensionsDbContext`
+> 3. Pages are registered via `PageRegistry.register()` — DynamicRouter resolves routes automatically
+> 4. Navigation is managed in DB (admin UI or seed data)
+
+> **Priority**: Read sections in order. Earlier sections override later ones.
+
+---
+
+## 1. GOLDEN RULES (ALWAYS APPLY)
+
+| # | Rule | Enforcement |
+|---|------|-------------|
+| 1 | **Domain layer has ZERO dependencies** | NEVER import from Application/Infrastructure/Api in Domain |
+| 2 | **Route = Permission path** | `/module/section` → `module.section.*` |
+| 3 | **All GUIDs MUST be random** | Generate via `[guid]::NewGuid()` - NEVER invent patterns |
+| 4 | **SQL objects via SqlObjectHelper** | TVFs/views use `SqlObjectHelper` + embedded `.sql` files. No other raw SQL. |
+| 5 | **Tables use domain prefix** | `ext_Orders`, `ext_Products` in `extensions` schema |
+| 6 | **Auto BugFix Issue after /debug** | After completing a `/debug` skill, ALWAYS run `/bugfix-issue` |
+| 7 | **One migration per feature branch** | Use `/efcore:migration` to manage |
+| 8 | **All code MUST have unit tests** | Backend: xUnit + FluentAssertions. Frontend: Vitest. No PR without tests |
+
+---
+
+## 2. GIT RESTRICTIONS
+
+### NEVER Execute Directly (propose to user)
+```
+git commit | git push | git merge | git rebase | git cherry-pick | git reset | git revert
+```
+
+### EXCEPTION: GitFlow Skills
+When user invokes `/gitflow:*` commands → **FOLLOW the skill instructions** and execute git commands as defined by that skill.
+
+| Context | Action |
+|---------|--------|
+| Manual git commands | **PROPOSE** only |
+| `/gitflow:*` skills | **FOLLOW skill** and execute |
+
+**GitFlow Rule**: Skills define a workflow. Execute commands **as specified by the skill**, not as an automatic pipeline.
+
+### Allowed (read-only)
+`git status` | `git log` | `git diff` | `git branch` | `git fetch` | `git worktree list`
+
+---
+
+## 3. ARCHITECTURE
+
+```
+{{ProjectName}}.sln
+├── src/
+│   ├── {{ProjectName}}.Domain         → Business logic (NO dependencies)
+│   ├── {{ProjectName}}.Application    → CQRS, use cases (→ Domain)
+│   ├── {{ProjectName}}.Infrastructure → EF Core, repositories, external services (→ Domain, Application)
+│   └── {{ProjectName}}.Api            → REST entry point (→ Application, Infrastructure)
+│       └── Controllers/               → Organized by Application/Module
+├── tests/
+│   └── {{ProjectName}}.Tests.Unit     → xUnit + FluentAssertions + Moq
+└── web/{{ProjectNameLower}}-web       → React + TypeScript + Vite
+    ├── tests/                         → Vitest unit tests (NOT in src/)
+    └── src/
+        ├── pages/                     → Organized by Application/Module
+        └── components/
+```
+
+**Dependency flow**: `Domain ← Application ← Infrastructure ← Api`
+
+> **Note**: Application references `Microsoft.EntityFrameworkCore` for `DbSet<T>` (used by `IExtensionsDbContext`),
+> `IQueryable<T>` async extensions, and `QueryableExtensions`.
+> This is an intentional architectural tradeoff — the `IExtensionsDbContext` interface remains the abstraction boundary.
+
+### Tech Stack
+| Layer | Tech | Version |
+|-------|------|---------|
+| Runtime | .NET | 10.0 |
+| ORM | EF Core | 10.0.1 |
+| Database | SQL Server | Latest |
+| Frontend | React + Vite | 19.x |
+| Language | TypeScript | 5.x |
+
+---
+
+## 4. NAVIGATION HIERARCHY
+
+```
+Application → Module → Section → Resource
+     ↓           ↓
+  myapp       orders
+     │           │
+     └───────────┴──→ Route: /myapp/orders
+                      Permission: myapp.orders.{action}
+```
+
+> **Note**: Applications have an `ApplicationZone` property (enum: `Platform`, `Personal`, `Business`) used for UI layout grouping only. It does NOT appear in routes or permissions.
+
+### Permission Actions
+`access` | `read` | `create` | `update` | `delete` | `export` | `import` | `approve` | `reject` | `assign` | `execute`
+
+### Adding Navigation
+1. Add HasData in `Navigation*Configuration.cs` (include `ComponentKey` for DynamicRouter)
+2. Run `/efcore:migration AddXxx`
+3. Register page in `componentRegistry.generated.ts` via `PageRegistry.register()`
+4. Add i18n in `navigation.json` (fr/en/it/de — all 4 languages)
+5. Create page component
+
+---
+
+## 5. DATABASE CONVENTIONS
+
+### Table Naming
+Format: `extensions.{prefix}_{TableName}`
+
+> **Note**: {{ProjectName}} uses the `extensions` schema, NOT the `core` schema (which belongs to SmartStack platform).
+
+### EF Core Config Pattern
+```csharp
+builder.ToTable("ext_Orders", SchemaConstants.Extensions);  // ✅ CORRECT
+builder.ToTable("Orders", "ext");                             // ❌ WRONG
+```
+
+### Migration Naming
+Format: `extensions_v{version}_{sequence}_{Description}`
+
+| Example |
+|---------|
+| `extensions_v1.0.0_001_CreateOrders` |
+| `extensions_v1.0.0_002_AddOrderItems` |
+
+> **Note**: Use `/efcore:migration` which calls MCP `suggest_migration` for automatic naming.
+
+---
+
+## 6. CODE CONVENTIONS
+
+### Naming
+| Type | Pattern | Example |
+|------|---------|---------|
+| Entity | Singular PascalCase | `Order`, `Product` |
+| Command | `{Action}{Entity}Command` | `CreateOrderCommand` |
+| Query | `Get{Entity}Query` | `GetOrderByIdQuery` |
+| Handler | `{Command/Query}Handler` | `CreateOrderCommandHandler` |
+| DTO | `{Entity}Dto` | `OrderDto`, `OrderResponseDto` |
+
+### Backend Patterns
+- **CQRS**: Commands/Queries in Application layer
+- **Repository**: Interfaces in Application, impl in Infrastructure
+- **DI**: Register in each layer's `DependencyInjection.cs`
+- **Domain Events**: Raise in Domain, handle in Application
+
+### Frontend Patterns
+- **Feature-based structure**: Group by feature
+- **Custom hooks**: `use*.ts` for logic
+- **API layer**: Centralized in `services/api/`
+- **Placeholder pages**: Use `UnderDevelopment` component for WIP sections
+
+---
+
+## 7. COMMANDS
+
+```bash
+# Build & Run
+dotnet build
+cd src/{{ProjectName}}.Api && dotnet run
+cd web/{{ProjectNameLower}}-web && npm run dev
+
+# Tests (MANDATORY before commit)
+dotnet test tests/{{ProjectName}}.Tests.Unit
+cd web/{{ProjectNameLower}}-web && npm test
+
+# EF Core
+/efcore:migration <Name>                       # Create migration (auto -o)
+/efcore:db-deploy                              # Apply migrations
+/efcore:db-status                              # Check status
+
+# GitFlow
+/gitflow commit                                # Commit with validation
+/gitflow pr                                    # Create PR
+```
+
+---
+
+## 8. API MANAGEMENT
+
+Claude MAY start/stop API as needed.
+
+```bash
+# Start (background)
+cd src/{{ProjectName}}.Api && dotnet run &
+
+# Stop
+taskkill /F /IM {{ProjectName}}.Api.exe 2>nul || pkill -f {{ProjectName}}.Api
+```
+
+**Rules**: Stop API when done. Stop before rebuild if files locked. Restart after code changes.
+
+---
+
+## 9. SECURITY RULES
+
+### GUID Generation (MANDATORY)
+```powershell
+# ALWAYS generate via PowerShell
+[guid]::NewGuid().ToString()
+1..10 | ForEach-Object { [guid]::NewGuid().ToString() }  # Multiple
+```
+
+**FORBIDDEN patterns**:
+- Repeated: `a1a1a1a1-b1b1-...`
+- Sequential: `00000001-0001-...`
+- Predictable: `a1b2c3d4-1111-2222-...`
+
+### Why
+- Predictable GUIDs enable enumeration attacks
+- OWASP requires cryptographically random identifiers
+
+---
+
+## 10. ENTITY HOOKS
+
+| Interface | When | Use Case |
+|-----------|------|----------|
+| `IBeforeCreate<T>` | Pre-create | Validation |
+| `IAfterCreate<T>` | Post-commit | Notifications |
+| `IBeforeUpdate<T>` | Pre-update | Validation |
+| `IAfterUpdate<T>` | Post-commit | Notifications |
+| `IBeforeDelete<T>` | Pre-delete | Can cancel |
+| `IAfterDelete<T>` | Post-commit | Cleanup |
+
+```csharp
+// Register in DependencyInjection.cs
+services.AddScoped<IAfterCreate<Order>, OrderCreatedNotificationHook>();
+```
+
+---
+
+## 11. LOGGING
+
+### Backend (Serilog)
+| Level | Usage |
+|-------|-------|
+| Critical | Security breaches, unauthorized access |
+| Error | Unhandled exceptions |
+| Warning | Validation failures |
+| Information | HTTP requests, user actions |
+| Debug | SQL queries (dev only) |
+
+### Frontend
+```typescript
+import { logService } from '@/services/logging/logService';
+logService.logError(error, 'ComponentName');
+logService.logCritical(error, 'ComponentName');  // Immediate send
+```
+
+---
+
+## 12. TESTING (MANDATORY)
+
+### Rule
+**Every new feature, entity, service, or utility MUST have corresponding unit tests.** No pull request should be merged without tests.
+
+### Backend Tests (xUnit v3 + FluentAssertions 8.x + Moq)
+
+| Layer | What to Test | Location |
+|-------|-------------|----------|
+| Domain | Entity creation, validation, state transitions | `tests/{{ProjectName}}.Tests.Unit/Domain/` |
+| Application | Behaviors, mappings, DTOs | `tests/{{ProjectName}}.Tests.Unit/Application/` |
+| Infrastructure | Services (JWT, FileStorage, etc.) | `tests/{{ProjectName}}.Tests.Unit/Services/` |
+| API | Controller responses, authorization | `tests/{{ProjectName}}.Tests.Unit/Controllers/` |
+
+```bash
+dotnet test tests/{{ProjectName}}.Tests.Unit
+```
+
+**Conventions:**
+- Test file naming: `{ClassName}Tests.cs`
+- Use factory methods (private constructors) - NEVER `new Entity { ... }`
+- Use `Guid.NewGuid()` for all Guid parameters - NEVER hardcode or use strings
+
+**FluentAssertions 8.x Gotchas:**
+- DateTime: `BeOnOrAfter()` / `BeBefore()` / `BeCloseTo(expected, TimeSpan.FromSeconds(5))` - NOT `BeGreaterThan()`
+- Collections: `HaveCount(n)` - NOT `HaveLength(n)`
+- String length: `content.Length.Should().BeGreaterThan(n)` - NOT `HaveLengthGreaterThan()`
+- Nullable: use `.Value` explicitly
+- `WithMessage("*keyword*")` wildcard OK - but do NOT pass `StringComparison` parameter
+
+**Domain Entity Test Pattern:**
+```csharp
+[Fact]
+public void Create_WithValidData_SetsAllProperties()
+{
+    var before = DateTime.UtcNow;
+    var entity = Entity.Create("name", "value");
+    entity.Name.Should().Be("name");
+    entity.CreatedAt.Should().BeOnOrAfter(before);
+    entity.Id.Should().NotBeEmpty();
+}
+
+[Fact]
+public void Create_WithEmptyName_ThrowsDomainException()
+{
+    var act = () => Entity.Create("", "value");
+    act.Should().Throw<DomainException>().WithMessage("*name*");
+}
+```
+
+### Frontend Tests (Vitest + Testing Library)
+
+| Category | What to Test | Location |
+|----------|-------------|----------|
+| Utils | Pure functions | `web/{{ProjectNameLower}}-web/tests/utils/` |
+| Services | Business logic | `web/{{ProjectNameLower}}-web/tests/services/` |
+| Hooks | Custom hooks | `web/{{ProjectNameLower}}-web/tests/hooks/` |
+| Components | UI with interactions | `web/{{ProjectNameLower}}-web/tests/components/` |
+
+```bash
+cd web/{{ProjectNameLower}}-web && npm test
+cd web/{{ProjectNameLower}}-web && npm run test:watch
+```
+
+**Conventions:**
+- Test file naming: `{fileName}.test.ts` or `{fileName}.test.tsx`
+- Tests in `web/{{ProjectNameLower}}-web/tests/` (NOT in `src/`)
+- Import with `@/` alias
+- Use `vi.mock()` for external dependencies
+
+### When to Write Tests
+
+| Trigger | Action |
+|---------|--------|
+| New domain entity | Add `{Entity}Tests.cs` with factory, validation, state machine tests |
+| New utility function | Add `{util}.test.ts` covering edge cases |
+| New service | Add `{Service}Tests.cs` or `{service}.test.ts` with mocked dependencies |
+| Bug fix | Add regression test that reproduces the bug BEFORE fixing |
+| New API endpoint | Add controller test with auth and response validation |