@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/application/references/provider-template.md

@@ -1,191 +0,0 @@
-# IClientSeedDataProvider Template
-
-> Referenced from `steps/step-03b-provider.md` — C# template for client project seed data providers.
-
----
-
-## Provider Class Template
-
-**Location:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
-
-Where `{AppPascalName}` is derived from the application code (e.g., `free-bike` → `FreeBike`).
-
-```csharp
-using Microsoft.EntityFrameworkCore;
-using SmartStack.Application.Common.Interfaces;
-using SmartStack.Domain.Navigation;
-using SmartStack.Domain.Platform.Administration.Roles;
-
-namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
-
-/// <summary>
-/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
-/// into the SmartStack Core schema at application startup.
-/// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
-/// (no Core migrations required).
-/// </summary>
-public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
-{
-    public int Order => 100;
-
-    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // --- Application (idempotent — reuse if already exists) ---
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
-        var existingApp = await context.NavigationApplications
-            .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
-
-        NavigationApplication app;
-        if (existingApp != null)
-        {
-            app = existingApp; // Reuse existing for module seeding below
-        }
-        else
-        {
-            // v3.46+ signature : Zone removed. New flags isOpen + isPersonal at the END (optional, default false).
-            app = NavigationApplication.Create(
-                appEntry.Code, appEntry.Label,
-                appEntry.Description, appEntry.Icon, appEntry.IconType,
-                appEntry.Route, appEntry.DisplayOrder,
-                isOpen: appEntry.IsOpen, isPersonal: appEntry.IsPersonal);
-            context.NavigationApplications.Add(app);
-            await ((DbContext)context).SaveChangesAsync(ct);
-
-            // Application translations (only when creating new application)
-            foreach (var t in NavigationApplicationSeedData.GetTranslationEntries())
-            {
-                context.NavigationTranslations.Add(
-                    NavigationTranslation.Create(t.EntityType, app.Id, t.LanguageCode, t.Label, t.Description));
-            }
-            await ((DbContext)context).SaveChangesAsync(ct);
-        }
-
-        // --- Modules (idempotent per-module) ---
-        // var mod1Exists = await context.NavigationModules.AnyAsync(
-        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
-        // if (!mod1Exists) { context.NavigationModules.Add(NavigationModule.Create(...)); }
-        // Repeat per module...
-        await ((DbContext)context).SaveChangesAsync(ct);
-
-        // Resolve module entities
-        // var mod1Entity = await context.NavigationModules.FirstAsync(
-        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
-
-        // --- Module translations (IDEMPOTENT — check before inserting) ---
-        // CRITICAL: nav_Translations has unique index IX_nav_Translations_EntityType_EntityId_LanguageCode
-        // Always guard with AnyAsync to prevent duplicate key errors on re-runs.
-        // CRITICAL: Use modEntity.Id (actual DB ID), NOT seed-time GUID from SeedData class.
-        // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == mod1Entity.Id
-        //          && t.EntityType == NavigationEntityType.Module, ct))
-        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries())
-        //   { context.NavigationTranslations.Add(
-        //       NavigationTranslation.Create(t.EntityType, mod1Entity.Id, t.LanguageCode, t.Label, t.Description)); } }
-        await ((DbContext)context).SaveChangesAsync(ct);
-
-        // --- Sections (idempotent per-section) ---
-        // Check each section before inserting: AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ...)
-
-        // --- Section translations (IDEMPOTENT — same guard pattern as module translations) ---
-        // CRITICAL: secEntry.Id is a seed-time GUID ≠ actual DB ID.
-        // Resolve actual section from DB: var actualSection = await context.NavigationSections
-        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
-        // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == actualSection.Id && t.EntityType == NavigationEntityType.Section, ct))
-
-        // --- Resources (idempotent — use ACTUAL section IDs from DB) ---
-        // CRITICAL: NavigationSection.Create() generates its own random ID.
-        // MUST query actual section from DB to get real ID for FK references:
-        // var actualSection = await context.NavigationSections
-        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
-        // Then use actualSection.Id for NavigationResource.Create() and AnyAsync
-    }
-
-    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Resolve application from DB by Code — NOT seed-time GUID
-        var app = await context.NavigationApplications
-            .FirstAsync(a => a.Code == "{app_code}", ct);
-
-        // Check idempotence — scoped by actual DB ApplicationId
-        var exists = await context.Roles
-            .AnyAsync(r => r.ApplicationId == app.Id, ct);
-        if (exists) return;
-
-        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
-        // Use data from ApplicationRolesSeedData.cs
-        foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
-        {
-            var role = Role.Create(
-                name: entry.Name,
-                shortName: entry.Code,
-                category: RoleCategory.Application,
-                description: entry.Description,
-                isSystem: entry.IsSystem,
-                applicationId: app.Id,
-                code: entry.Code);
-            context.Roles.Add(role);
-        }
-        await ((DbContext)context).SaveChangesAsync(ct);
-    }
-
-    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Check idempotence
-        var exists = await context.Permissions
-            .AnyAsync(p => p.Path == "{full_path}.*", ct);
-        if (exists) return;
-
-        // Retrieve modules by Code for FK resolution
-        // Use data from {Module}PermissionSeedData.cs
-        // Create via Permission.CreateForModule(...) and Permission.CreateWildcard(...)
-        // ...
-        await ((DbContext)context).SaveChangesAsync(ct);
-    }
-
-    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Check idempotence
-        var exists = await context.RolePermissions
-            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{full_path}."), ct);
-        if (exists) return;
-
-        // Retrieve existing roles and created permissions
-        // Use data from {Module}RolePermissionSeedData.cs
-        // Create via RolePermission.Create(roleId, permissionId, "system")
-        // ...
-        await ((DbContext)context).SaveChangesAsync(ct);
-    }
-
-    // Private helper methods fed by SeedData classes
-    // ...
-}
-```
-
----
-
-## DI Registration
-
-Modify `Infrastructure/DependencyInjection.cs` of the client project:
-
-```csharp
-// Add using:
-using SmartStack.Application.Common.Interfaces;
-
-// In the registration method:
-services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
-```
-
----
-
-## Critical Rules
-
-1. **Factory methods mandatory**: `NavigationApplication.Create(zone, ...)`, `NavigationModule.Create(...)`, `Role.Create(name, shortName, category, ...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
-2. **Idempotence**: Each Seed method checks existence before inserting. **Translations require explicit `AnyAsync` guard** — unique index `IX_nav_Translations_EntityType_EntityId_LanguageCode` causes crashes on duplicate inserts
-3. **Translation EntityId**: ALWAYS use actual DB ID (e.g. `app.Id`, `mod1Entity.Id`, `actualSection.Id`), NEVER seed-time GUID from SeedData classes
-4. **Translation guard pattern**: `if (!await context.NavigationTranslations.AnyAsync(t => t.EntityId == {actualDbId} && t.EntityType == ..., ct))` — MANDATORY before every translation batch insert
-5. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
-6. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
-7. **Random GUIDs**: ALWAYS use `Guid.NewGuid()` — resolve FKs by Code lookup, not fixed IDs
-8. **Resolve FK by Code**: Parent entities (applications, modules, roles) are found by `Code` from DB, not by seed-time GUID
-9. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence

package/templates/skills/application/references/roles-client-project-handling.md

@@ -1,55 +0,0 @@
-# Step 3: Client Project Handling (seeding_strategy = "provider")
-
-> Referenced from `steps/step-03-roles.md` — Specific handling for client projects.
-
----
-
-## ApplicationRolesSeedData.cs (ONCE per application)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
-
-**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
-
-**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
-
-See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
-
-**Key requirements:**
-- Random GUIDs via `Guid.NewGuid()` — roles are resolved by Code at runtime
-- 4 roles: Admin, Manager, Contributor, Viewer
-- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
-- `ApplicationId` references the navigation application GUID
-- `IsSystem = false` (application-scoped, not system roles)
-
-**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
-
----
-
-## {Module}RolePermissionSeedData.cs (PER module)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
-
-**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
-
-Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
-These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
-
----
-
-## Default Role Mapping Table
-
-Based on navigation application prefix:
-
-| Application prefix | PlatformAdmin | TenantAdmin | StandardUser |
-|---------|---------------|-------------|--------------|
-| `administration.*` | Full CRUD | Read only | None |
-| `*` (business apps) | Full CRUD | Full CRUD | Read only |
-| `myspace.*` | None | Full CRUD | Full CRUD |
-
----
-
-## Summary
-
-After creating both files:
-- Proceed to step-03b-provider.md (which will skip for core projects)
-- The provider will consume these SeedData files to seed roles and permissions at runtime

package/templates/skills/application/references/roles-fallback-procedure.md

@@ -1,144 +0,0 @@
-# Role-Permission Generation: Fallback Procedure (When MCP Unavailable)
-
-> Reference for step-03-roles.md — Generates role-permission HasData entries following SmartStack.app patterns.
-
----
-
-## F1. Read Existing RolePermissionConfiguration.cs
-
-```
-Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
-```
-
-Read the file to determine:
-- Existing role-permission mappings
-- The GetSeedData() method structure
-- Which roles already have which permissions
-- The GUID generation method used (deterministic or hardcoded)
-
----
-
-## F2. Read Role GUIDs
-
-**System-level roles** (well-known GUIDs):
-
-| Role | GUID |
-|------|------|
-| SuperAdmin | Resolved by Code at runtime (NEVER hardcoded) |
-| PlatformAdmin | Resolved by Code at runtime (NEVER hardcoded) |
-| TenantAdmin | Resolved by Code at runtime (NEVER hardcoded) |
-| StandardUser | Resolved by Code at runtime (NEVER hardcoded) |
-
-**IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
-
-**Application-scoped roles** (resolved by Code at runtime):
-
-```csharp
-// ALWAYS resolve roles by Code at runtime — NEVER use deterministic/hardcoded GUIDs
-// Role IDs are generated via Guid.NewGuid() at seed time
-// Lookups use:
-var role = await context.Roles.FirstOrDefaultAsync(r => r.Code == "admin", ct);
-// roleCode values: "admin", "manager", "contributor", "viewer"
-```
-
-Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
-
----
-
-## F3. Determine Application-Based Default Mappings
-
-Based on `{full_path}` application prefix:
-
-| Application Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
-|----------------|------------|---------------|-----------|-------------|-----------------|------------|
-| `administration.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
-| `*` (business apps) | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
-| `myspace.*` | wildcard | None | Full CRUD | CRU | CR | R |
-
----
-
-## F4. Generate RolePermission HasData Entries
-
-Using `{permission_guids}` from step-02:
-
-```csharp
-// In RolePermissionConfiguration.cs - GetSeedData() method
-var seedDate = SeedConstants.SeedDate;
-
-// ============================================================
-// {MODULE_NAME} PERMISSIONS
-// ============================================================
-
-// SuperAdmin: already has *.* wildcard - no individual entries needed
-
-// PlatformAdmin (for administration.* scope)
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
-
-// Application-scoped: Admin → wildcard
-rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
-
-// Application-scoped: Manager → CRU (read + create + update — no delete)
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
-
-// Application-scoped: Contributor → CR
-rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-
-// Application-scoped: Viewer → R
-rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-```
-
----
-
-## F5. Write Code to RolePermissionConfiguration.cs
-
-**CRITICAL:** Do NOT just display code. WRITE it to the actual file.
-
-1. Open `RolePermissionConfiguration.cs`
-2. Find the `GetSeedData()` method
-3. Add the new role-permission entries to the list
-4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
-5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
-
----
-
-## F6. Present Summary
-
-```markdown
-## Role-Permission Mappings Generated (Fallback)
-
-| Role | Permissions |
-|------|-------------|
-| SuperAdmin | Already has wildcard access |
-| PlatformAdmin | {full_path}.read, .create, .update, .delete |
-| App Admin | {full_path}.* (wildcard) |
-| App Manager | {full_path}.read, .create, .update |
-| App Contributor | {full_path}.read, .create |
-| App Viewer | {full_path}.read |
-
-Written to: RolePermissionConfiguration.cs
-```
-
----
-
-## F7. Offer User Adjustment
-
-If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
-
----
-
-## Validation Checklist
-
-Before marking as completed, verify:
-
-- [ ] All role GUIDs correctly identified (system and application-scoped)
-- [ ] Role-permission mappings follow application hierarchy
-- [ ] Code WRITTEN to files (not just displayed)
-- [ ] Permission GUID references correct
-- [ ] Comments added for module grouping
-- [ ] No gaps or missing permissions

package/templates/skills/application/references/smartstack-provider.md

@@ -1,118 +0,0 @@
-# SmartStackProvider — Wrapping the Client App
-
-> **Reference for `application` skill** — how to bootstrap a SmartStack client project (npm `@atlashub/smartstack`) using the SDK provider.
-
-## When This Reference Applies
-
-- The client project consumes `@atlashub/smartstack` as an npm package (v3.7+)
-- You are generating or auditing `App.tsx` / `main.tsx` / the application bootstrap
-- The user asks "how do I wrap my app", "where do I put providers", "how do I configure SmartStack"
-
-If the project is the SmartStack platform itself (`SmartStack.app`), the platform's internal `App.tsx` already inlines the providers and does NOT use `<SmartStackProvider>` — only client projects use it.
-
----
-
-## SmartStackConfig shape
-
-```ts
-interface SmartStackConfig {
-  apiUrl: string;                          // REQUIRED — backend root URL (e.g. "https://api.client.com")
-  defaultLanguage?: 'fr' | 'en' | 'it' | 'de';  // default 'fr'
-  debug?: boolean;                          // verbose logging
-  logo?: ReactNode;                         // override branding logo
-  appName?: string;                         // displayed in title/header fallback
-  licenseKey?: string;                      // license string (validated against /api/license)
-  extensions?: ExtensionConfig;             // see references/extensions-system.md
-}
-```
-
----
-
-## Wrapping order (Outer → Inner)
-
-```tsx
-import { BrowserRouter } from 'react-router-dom';
-import { SmartStackProvider, DynamicRouter } from '@atlashub/smartstack';
-import '@atlashub/smartstack/theme.css';
-
-const config: SmartStackConfig = {
-  apiUrl: import.meta.env.VITE_API_URL,
-  defaultLanguage: 'fr',
-  appName: 'My Client App',
-};
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <BrowserRouter>
-      <SmartStackProvider config={config}>
-        <DynamicRouter />
-      </SmartStackProvider>
-    </BrowserRouter>
-  </StrictMode>,
-);
-```
-
-`<SmartStackProvider>` internally nests, in this order :
-
-```
-SmartStackContext (config)
-└─ GlobalErrorBoundary
-   └─ ExtensionProvider
-      └─ ThemeProvider
-         └─ FeatureConfigProvider
-            └─ AuthProvider
-               └─ TenantProvider
-                  └─ LicenseProvider
-                     └─ FavoritesProvider
-                        └─ SidebarProvider
-                           └─ SessionProvider
-                              └─ ThemeSync
-                                 └─ NavigationProvider
-                                    └─ SignalRProvider
-                                       └─ {children}
-```
-
-**Do NOT re-wrap any of these providers manually.** They are exported only for advanced cases (e.g., Storybook).
-
----
-
-## Hooks consumable from any descendant
-
-| Hook | Context | Returns |
-|---|---|---|
-| `useSmartStack()` | SmartStackContext | `{ config }` |
-| `useAuth()` | AuthContext | `{ user, login, logout, refresh, hasPermission }` |
-| `useTenant()` | TenantContext | `{ currentTenant, userTenants, switchTenant, isGlobalView }` |
-| `useNavigation()` | NavigationContext | `{ menu, reload, currentApp, currentModule, isLoading }` |
-| `useTheme()` | ThemeContext | `{ mode, selectedTheme, selectedPreset, setTheme, setPreset, toggleMode }` |
-| `useLicense()` | LicenseContext | `{ license, isFeatureEnabled, hasModule }` |
-| `useSignalR()` | SignalRContext | `{ isConnected, on, off, emit }` |
-| `useFavorites()` | FavoritesContext | `{ favorites, toggleFavorite, isFavorite }` |
-| `useSidebar()` | SidebarContext | `{ isCollapsed, toggle, setCollapsed }` |
-| `useFeatureConfig()` | FeatureConfigContext | `{ features }` |
-| `useDocPanel()` | DocPanelContext | `{ isOpen, toggle, openDoc }` |
-
-See [contexts-cheatsheet.md](contexts-cheatsheet.md) for usage examples.
-
----
-
-## DO / DON'T
-
-| ✅ DO | ❌ DON'T |
-|---|---|
-| Place `<SmartStackProvider>` exactly once at root | Wrap the same provider twice |
-| Put `<BrowserRouter>` ABOVE `<SmartStackProvider>` | Put `<SmartStackProvider>` above the router |
-| Read config via `useSmartStack()` from any descendant | Pass config down via props |
-| Import `componentRegistry.generated` in `main.tsx` BEFORE the render | Forget the import (DynamicRouter will not resolve pages) |
-| Wait for `i18nReady` promise before render | Render before i18n loaded (causes FOUC) |
-| Provide `apiUrl` via `import.meta.env.VITE_API_URL` | Hardcode the backend URL |
-
----
-
-## Reference source files (read-only — DO NOT copy verbatim)
-
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\router\types.ts` (SmartStackConfig)
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\main.tsx` (i18nReady + componentRegistry import)
-
-For overrides via `extensions`, see [extensions-system.md](extensions-system.md).