@atlashub/smartstack-cli 4.32.0 → 4.34.0

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 |

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

@@ -0,0 +1,339 @@
+# {{ProjectName}} Web - React Frontend Memory
+
+## Purpose
+
+React SPA frontend. Communicates with {{ProjectName}}.Api via REST + SignalR.
+
+## Tech Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| React | ^18 / ^19 | UI library |
+| TypeScript | ~5.9.3 | Type safety (strict mode) |
+| Vite | ^7.2 | Build tool + dev server |
+| React Router | ^6 / ^7 | Routing (lazy-loaded) |
+| Context API | - | Client + server state |
+| Axios | ^1.13 | HTTP client |
+| Tailwind CSS | ^4.1 | Styling |
+| i18next | ^25.7 | Internationalization |
+| SignalR | ^10.0 | Real-time updates |
+| Lucide React | ^0.562 | Icons |
+
+---
+
+## CRITICAL: Internationalization (i18n) - 4 Languages Required
+
+### Rules
+
+- **CRITICAL**: Every page MUST use translations via `useTranslation()` hook
+- **CRITICAL**: All user-visible text MUST be in translation files (fr, en, it, de)
+- **NEVER** hardcode text strings in components
+- **ALWAYS** add translations to ALL 4 locales: `fr/`, `en/`, `it/`, `de/`
+
+### Supported Languages
+
+| Language | Code | Folder |
+|----------|------|--------|
+| French | `fr` | `locales/fr/` |
+| English | `en` | `locales/en/` |
+| Italian | `it` | `locales/it/` |
+| German | `de` | `locales/de/` |
+
+### Structure
+
+```
+src/i18n/
+├── config.ts                    → i18next configuration
+└── locales/
+    ├── en/
+    │   ├── common.json          → Common UI (buttons, labels, errors)
+    │   ├── navigation.json      → Menu and navigation
+    │   └── {feature}.json       → Feature-specific translations
+    ├── fr/
+    │   └── ...                  → Same structure as en/
+    ├── it/
+    │   └── ...                  → Same structure as en/
+    └── de/
+        └── ...                  → Same structure as en/
+```
+
+### Usage in Pages
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export function ExamplePage() {
+  const { t } = useTranslation('feature');  // Specify namespace
+
+  return (
+    <div>
+      <h1>{t('pageTitle')}</h1>
+      <p>{t('description')}</p>
+      <button>{t('common:save')}</button>  {/* Cross-namespace */}
+    </div>
+  );
+}
+```
+
+### Adding New Translations
+
+**ALWAYS add to ALL 4 languages** (en, fr, it, de) with the same structure.
+
+### Translation Keys Convention
+
+- Use **dot notation** for nested keys: `orders.pageTitle`
+- Use **camelCase** for key names
+- Group by feature/section: `orders.table.headerName`
+- Common actions in `common` namespace: `common:save`, `common:cancel`
+
+---
+
+## Structure
+
+```
+{{ProjectNameLower}}-web/
+├── src/
+│   ├── main.tsx                 → Entry point
+│   ├── App.tsx                  → Root component + providers + DynamicRouter
+│   ├── i18n/                    → Internationalization
+│   │   ├── config.ts            → i18next setup
+│   │   └── locales/             → Translation files (fr/en/it/de)
+│   ├── services/                → API client layer
+│   │   └── api/
+│   │       ├── apiClient.ts     → Axios instance + interceptors
+│   │       └── {feature}Api.ts  → Feature-specific API modules
+│   ├── components/              → Shared & domain components
+│   │   ├── ui/                  → Base UI components (DataTable, Modal, etc.)
+│   │   ├── layout/              → Layout components
+│   │   ├── routing/             → Route guards + dynamic routing
+│   │   └── {feature}/           → Feature-specific components
+│   ├── pages/                   → Page components
+│   │   └── {application}/{module}/ → Organized by navigation hierarchy
+│   ├── contexts/                → React Context providers
+│   ├── hooks/                   → Custom hooks
+│   ├── layouts/                 → Layout wrappers
+│   ├── utils/                   → Utility functions
+│   ├── types/                   → Global types
+│   ├── routes/                  → Route definitions
+│   └── extensions/              → Extension system (PageRegistry)
+├── tests/                       → Vitest tests (NOT in src/)
+│   ├── utils/                   → Pure utility tests
+│   ├── components/              → Component tests
+│   ├── hooks/                   → Hook tests
+│   └── services/                → Service tests
+├── vite.config.ts
+├── vitest.config.ts
+├── tsconfig.json
+└── eslint.config.js
+```
+
+## Patterns
+
+### Page Template with i18n
+
+```tsx
+// src/pages/{module}/{PageName}Page.tsx
+import { useTranslation } from 'react-i18next';
+
+export function ExamplePage() {
+  const { t } = useTranslation('feature');
+
+  return (
+    <div className="container mx-auto p-4">
+      <h1 className="text-2xl font-bold">{t('example.pageTitle')}</h1>
+      <p className="text-muted-foreground">{t('example.description')}</p>
+
+      <div className="mt-4 flex gap-2">
+        <button className="btn-primary">{t('common:save')}</button>
+        <button className="btn-secondary">{t('common:cancel')}</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### API Client
+
+```typescript
+// src/services/api/apiClient.ts — uses Axios instance
+import { api } from '@/services/api/apiClient';
+
+// Request interceptors automatically add:
+// - Authorization: Bearer {token}
+// - X-Tenant-Slug: {currentTenantSlug}
+// - Accept-Language: {i18nextLng}
+// - X-Correlation-ID: {UUID}
+
+// Usage in service files:
+const orders = await api.get<Order[]>('/orders');
+const order = await api.post<Order>('/orders', { name, amount });
+```
+
+### API Service File Pattern
+
+```typescript
+// src/services/api/{feature}Api.ts
+import { api } from './apiClient';
+
+export interface OrderDto {
+  id: string;
+  name: string;
+  amount: number;
+  isActive: boolean;
+}
+
+export const orderApi = {
+  getAll: (search?: string) =>
+    api.get<OrderDto[]>('/orders', { params: { search } }),
+
+  getById: (id: string) =>
+    api.get<OrderDto>(`/orders/${id}`),
+
+  create: (data: Partial<OrderDto>) =>
+    api.post<OrderDto>('/orders', data),
+
+  update: (id: string, data: Partial<OrderDto>) =>
+    api.put<OrderDto>(`/orders/${id}`, data),
+
+  delete: (id: string) =>
+    api.delete(`/orders/${id}`),
+};
+```
+
+### Custom Hook Pattern
+
+```typescript
+// src/hooks/useOrderDetail.ts
+import { useState, useCallback } from 'react';
+import { orderApi, OrderDto } from '@/services/api/orderApi';
+
+export function useOrderDetail(id: string) {
+  const [data, setData] = useState<OrderDto | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await orderApi.getById(id);
+      setData(result);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  }, [id]);
+
+  return { data, loading, error, load };
+}
+```
+
+### Context Provider Pattern
+
+```typescript
+// src/contexts/ExampleContext.tsx
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+interface ExampleContextType {
+  value: string;
+  setValue: (v: string) => void;
+}
+
+const ExampleContext = createContext<ExampleContextType | null>(null);
+
+export function ExampleProvider({ children }: { children: ReactNode }) {
+  const [value, setValue] = useState('');
+  return (
+    <ExampleContext.Provider value={{ value, setValue }}>
+      {children}
+    </ExampleContext.Provider>
+  );
+}
+
+export function useExample() {
+  const ctx = useContext(ExampleContext);
+  if (!ctx) throw new Error('useExample must be used within ExampleProvider');
+  return ctx;
+}
+```
+
+## UI Styling Patterns
+
+### Semantic Color Usage
+
+| Color | CSS Variables | Usage |
+|-------|---------------|-------|
+| `blue` | `--info-*` | Totals, informational, in progress |
+| `green` | `--success-*` | Completed, resolved, active |
+| `yellow` | `--warning-*` | Pending, on hold, warnings |
+| `red` | `--error-*` | Errors, critical, failed |
+| `neutral` | `--bg-secondary`, `--text-primary` | Inactive, closed, disabled |
+
+---
+
+## Commands
+
+```bash
+# Development
+npm run dev              # Start dev server (port 6173)
+
+# Build
+npm run build            # Production build
+
+# Tests (MANDATORY before commit)
+npm test                 # Run all tests
+npm run test:watch       # Watch mode
+npm run test:coverage    # Coverage report
+
+# Lint
+npm run lint             # ESLint check
+npm run typecheck        # TypeScript type check
+```
+
+## Routing
+
+### Lazy Loading
+
+All non-critical pages use `React.lazy()` for code splitting:
+
+```tsx
+const OrdersPage = lazy(() =>
+  import('@/pages/{module}/OrdersPage').then(m => ({ default: m.OrdersPage }))
+);
+```
+
+### Route Guards (Layered)
+
+```
+Auth check → Tenant transition → Permission check → Render
+```
+
+---
+
+## Rules
+
+1. **CRITICAL: i18n Required** - ALL pages must use `useTranslation()` with all 4 language files (fr/en/it/de)
+2. **Pages in `pages/`**, components in `components/`** - organized by application/module
+3. **Custom hooks for logic** - extract API calls and state management from components into `hooks/`
+4. **Context API for global state** - use `contexts/` for auth, tenant, navigation, theme, etc.
+5. **Axios API client** - all HTTP calls via `services/api/apiClient.ts`, never raw `fetch()`
+6. **TypeScript strict mode** - no `any` types
+7. **Tailwind for styling** - no CSS files, no inline styles (`style={{}}`)
+8. **Functional components only** - no class components
+9. **Composition over inheritance** - use props and children
+10. **Tests in `tests/`** - NOT in `src/`, use Vitest + Testing Library
+
+## CRITICAL: Tabs Must Persist in URL
+
+When creating a page with tabs, **ALWAYS** persist the active tab in the URL query params (`?tab=xxx`).
+Use the `useTabNavigation` hook.
+
+## When Adding New Feature
+
+1. Create page in `pages/{application}/{module}/`
+2. Create components in `components/{feature}/`
+3. Create API service in `services/api/{feature}Api.ts`
+4. Create custom hooks in `hooks/use{Feature}.ts`
+5. Register page via `PageRegistry.register()`
+6. **CRITICAL**: Add translations to ALL 4 locales: `i18n/locales/{fr,en,it,de}/`