@atlashub/smartstack-cli 2.8.0 → 3.0.0

package/templates/hooks/hooks.json

@@ -18,6 +18,15 @@
             "command": "${CLAUDE_HOOKS_DIR}/ralph-mcp-logger.sh"
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_HOOKS_DIR}/appsettings-guard.sh"
+          }
+        ]
       }
     ],
     "Stop": [

package/templates/project/test-frontend/msw/handlers.ts

@@ -0,0 +1,58 @@
+import { http, HttpResponse } from 'msw';
+
+/**
+ * Default MSW handlers for SmartStack API endpoints.
+ * These handlers mock common API calls used across the application.
+ *
+ * Override these in individual tests using server.use().
+ *
+ * @example
+ * // In a test file:
+ * server.use(
+ *   http.get('/api/products', () =>
+ *     HttpResponse.json({
+ *       items: [{ id: '1', code: 'P-01', name: 'Test Product' }],
+ *       totalCount: 1,
+ *       pageNumber: 1,
+ *       pageSize: 10,
+ *     })
+ *   )
+ * );
+ */
+export const handlers = [
+  // Auth endpoints
+  http.get('/api/auth/me', () =>
+    HttpResponse.json({
+      id: 'test-user-id',
+      email: 'test-admin@smartstack.io',
+      name: 'Test Admin',
+      role: 'Administrator',
+      permissions: ['*'],
+    })
+  ),
+
+  http.post('/api/auth/login', () =>
+    HttpResponse.json({
+      token: 'test-jwt-token',
+      user: {
+        id: 'test-user-id',
+        email: 'test-admin@smartstack.io',
+        name: 'Test Admin',
+      },
+    })
+  ),
+
+  // Navigation endpoints
+  http.get('/api/navigation', () =>
+    HttpResponse.json([])
+  ),
+
+  // User preferences
+  http.get('/api/users/preferences', () =>
+    HttpResponse.json({})
+  ),
+
+  http.put('/api/users/preferences', () =>
+    HttpResponse.json({ success: true })
+  ),
+];

package/templates/project/test-frontend/msw/server.ts

@@ -0,0 +1,25 @@
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+/**
+ * MSW (Mock Service Worker) server for intercepting API calls in tests.
+ * Configured with default handlers that mock common SmartStack API endpoints.
+ *
+ * Usage:
+ * - Default handlers are loaded from ./handlers.ts
+ * - Override handlers per-test using server.use()
+ *
+ * @example
+ * import { server } from '@/test/msw/server';
+ * import { http, HttpResponse } from 'msw';
+ *
+ * test('custom handler', () => {
+ *   server.use(
+ *     http.get('/api/products', () =>
+ *       HttpResponse.json({ items: [], totalCount: 0 })
+ *     )
+ *   );
+ *   // ... test code
+ * });
+ */
+export const server = setupServer(...handlers);

package/templates/project/test-frontend/setup.ts

@@ -0,0 +1,16 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach, beforeAll, afterAll } from 'vitest';
+import { server } from './msw/server';
+
+// Start MSW server before all tests
+beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }));
+
+// Reset handlers after each test (to not leak state between tests)
+afterEach(() => {
+  cleanup();
+  server.resetHandlers();
+});
+
+// Close MSW server after all tests
+afterAll(() => server.close());

package/templates/project/test-frontend/test-utils.tsx

@@ -0,0 +1,59 @@
+import React, { type ReactElement } from 'react';
+import { render, type RenderOptions } from '@testing-library/react';
+import { BrowserRouter } from 'react-router-dom';
+import { I18nextProvider } from 'react-i18next';
+import i18n from '../i18n'; // Adjust path to your i18n config
+
+/**
+ * AuthContext mock for tests.
+ * Provides a default authenticated user with admin permissions.
+ */
+const mockAuthContext = {
+  user: {
+    id: 'test-user-id',
+    email: 'test-admin@smartstack.io',
+    name: 'Test Admin',
+    role: 'Administrator',
+  },
+  isAuthenticated: true,
+  isLoading: false,
+  login: async () => {},
+  logout: async () => {},
+  hasPermission: () => true,
+  refreshPermissions: async () => {},
+};
+
+/**
+ * Wraps components with all necessary providers for testing.
+ * Includes: Router, i18n, Auth context.
+ */
+function AllProviders({ children }: { children: React.ReactNode }) {
+  return (
+    <BrowserRouter>
+      <I18nextProvider i18n={i18n}>
+        {children}
+      </I18nextProvider>
+    </BrowserRouter>
+  );
+}
+
+/**
+ * Custom render function that wraps components with test providers.
+ * Use this instead of @testing-library/react's render.
+ *
+ * @example
+ * import { renderWithProviders, screen } from '@/test/test-utils';
+ * renderWithProviders(<MyComponent />);
+ * expect(screen.getByText('Hello')).toBeInTheDocument();
+ */
+function renderWithProviders(
+  ui: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) {
+  return render(ui, { wrapper: AllProviders, ...options });
+}
+
+// Re-export everything from testing-library
+export * from '@testing-library/react';
+export { renderWithProviders };
+export { mockAuthContext };

package/templates/project/test-frontend/vitest.config.ts

@@ -0,0 +1,31 @@
+/// <reference types="vitest/config" />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    css: false,
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: [
+        'src/test/**',
+        'src/**/*.d.ts',
+        'src/main.tsx',
+        'src/vite-env.d.ts',
+      ],
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});

package/templates/skills/_resources/config-safety.md

@@ -0,0 +1,61 @@
+# Configuration File Safety Rules
+
+## appsettings*.json Protection
+
+### MANDATORY Rules
+
+1. **NEVER use Write tool on `appsettings*.json`** — ALWAYS use Edit for targeted changes
+2. **NEVER remove existing top-level sections** — only add or modify values within existing structure
+3. **NEVER delete configuration keys** — replace secret VALUES with `<CONFIGURE_HERE>` placeholder
+4. **When adding a new section**, use Edit to insert at the correct location (before the closing `}`)
+
+### WHY
+
+Claude's Write tool replaces the entire file. If you read a 200-line appsettings.json but only reproduce 150 lines in the Write, 50 lines of configuration are permanently lost. This has caused production incidents where entire authentication, logging, or integration sections disappeared.
+
+### Correct Patterns
+
+| Action | Tool | Approach |
+|--------|------|----------|
+| Add new section | Edit | Find closing `}`, replace with new section + `}` |
+| Modify a value | Edit | Target the specific key-value pair |
+| Add a key to section | Edit | Find the section's closing `}`, add key before it |
+| Replace secrets | Edit | Replace the VALUE only, keep the key |
+
+### Example: Adding a New Section
+
+```
+// Use Edit tool with:
+// old_string:   "Serilog": { ... }\n}
+// new_string:   "Serilog": { ... },\n  "NewSection": { "Key": "<CONFIGURE_HERE>" }\n}
+```
+
+### Secret Value Handling
+
+```json
+// WRONG - removing the key entirely
+"Jwt": { }
+
+// WRONG - deleting the section
+// (section missing from file)
+
+// CORRECT - placeholder value preserving structure
+"Jwt": {
+  "SecretKey": "<CONFIGURE_HERE>",
+  "Issuer": "<CONFIGURE_HERE>",
+  "Audience": "<CONFIGURE_HERE>",
+  "ExpirationMinutes": 60
+}
+```
+
+### Exception: New File Creation
+
+Write is acceptable ONLY when creating a NEW `appsettings.*.json` file that does not yet exist on disk (e.g., `appsettings.Local.json` during `/gitflow start`). The PreToolUse hook automatically allows this case.
+
+### Protection Layers
+
+| Layer | Mechanism | When |
+|-------|-----------|------|
+| Hook `appsettings-guard.sh` | PreToolUse on Write | Blocks Write if top-level sections would be lost |
+| Commit agent step 2b | During `/gitflow commit` | Detects section removal vs HEAD before staging |
+| These instructions | During development | Prevents the issue from occurring |

package/templates/skills/_resources/formatting-guide.md

@@ -46,7 +46,7 @@ Always in simple code block:
 
 ```markdown
 ```
-/gitflow:1-init --exec
+/gitflow init --exec
 ```
 ```
 
@@ -77,7 +77,7 @@ npm test
 
 ```markdown
 <!-- INCORRECT -->
-Execute `/gitflow:1-init`
+Execute `/gitflow init`
 Run the command `npm run build`
 ```
 

package/templates/skills/_shared.md

@@ -99,6 +99,27 @@ if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin
     return BadRequest(new { message = "Cannot modify system accounts" });
 ```
 
+## FORBIDDEN: Temporary Files and Scripts (ALL SKILLS)
+
+> **ABSOLUTE PROHIBITION: NEVER create temporary files, scripts, or helper files.**
+
+This includes but is not limited to:
+- `.ps1`, `.sh`, `.bat`, `.cmd` scripts
+- `temp-*`, `tmp-*`, `helper-*` files
+- Any file created solely to discover types, scan DLLs, or read metadata
+
+**How to discover .NET types WITHOUT scripts:**
+| Need | Tool to Use |
+|------|-------------|
+| Find a class/entity | `Grep` for `class {Name}` in `*.cs` files |
+| Find services/interfaces | `Glob` for `**/I*Service.cs` in Application layer |
+| Find NuGet packages | `Read` the `.csproj` file directly |
+| Find existing entities | `Glob` for `**/*.cs` in Domain layer |
+| Validate conventions | MCP `validate_conventions` tool |
+| Cannot find after 2 tries | **ASK the user** |
+
+**If you catch yourself about to create a script file: STOP. Use the tools above instead.**
+
 ## Common Validation Checklist
 
 ```

package/templates/skills/application/SKILL.md

@@ -48,7 +48,10 @@ This skill uses progressive step loading. Each step calls MCP tools for generati
 | `mcp__smartstack__scaffold_api_client` | TypeScript API client |
 | `mcp__smartstack__scaffold_routes` | React Router configuration |
 | `mcp__smartstack__suggest_migration` | Migration name suggestion |
-| `mcp__smartstack__scaffold_tests` | Test suite generation |
+| `mcp__smartstack__scaffold_tests` | Test suite generation (backend) |
+| `mcp__smartstack__scaffold_frontend_tests` | Test suite generation (frontend React) |
+| `mcp__smartstack__validate_conventions` | Post-generation convention check |
+| `mcp__smartstack__review_code` | Code quality audit |
 
 ## WHEN THIS SKILL ACTIVATES
 
@@ -88,14 +91,17 @@ WEB (React) → API (.NET) → Application → Infrastructure → Database
 3. ROLES (RolePermission mappings)
 3b. CLIENT SEED PROVIDER (client projects only - IClientSeedDataProvider)
 4. API (Controller + DTOs via /controller:create)
+   4b. VALIDATE (/validate - convention check on generated backend)
 5. SERVICES (Interface + Implementation)
 6. FRONTEND (Page + Components + Hooks)
 7. I18N (fr, en, it, de)
 8. ROUTES (nested routes mandatory)
 9. PREFERENCES (Hook pattern)
 10. MIGRATION (/efcore:migration)
-11. TESTS (scaffold_tests - 6 categories)
-12. DOCUMENTATION (in-app user doc via /documentation - if userDocRequired)
+11. TESTS - Backend (scaffold_tests - 7 categories including real integration)
+12. TESTS - Frontend (scaffold_frontend_tests - Vitest + Testing Library + MSW)
+13. REVIEW (/review-code - security + architecture + quality audit)
+14. DOCUMENTATION (in-app user doc via /documentation - if userDocRequired)
 ```
 
 ### 3b. Client Seed Provider (client projects only)
@@ -151,6 +157,9 @@ export function use{Module}Preferences() {
 | `/workflow` | Automated emails | IWorkflowService.TriggerAsync |
 | `/ai-prompt` | AI assistance | IAiCompletionService |
 | `/feature-full` | Complete feature | Orchestration all skills |
+| `/validate` | After step-04 (backend) | MCP `validate_conventions` on generated code |
+| `/review-code` | After step-07 (tests) | Security (OWASP), architecture, SOLID, performance audit |
+| `/validate-feature` | After step-07 (tests) | Compile + test + API smoke test |
 | `/documentation` | In-app user doc | Documentation page via doc-data.ts + DocRenderer |
 
 ### Notification Integration Pattern
@@ -179,6 +188,26 @@ await _workflowService.TriggerAsync("{entity}.created", new Dictionary<string, o
 | EntityCard for cards | Manual cards with divs |
 | DataTable for tables | Sequential GUIDs |
 
+### FORBIDDEN ACTIONS (BLOCKING)
+
+> **NEVER create temporary files, scripts, or helper files of any kind.**
+
+| FORBIDDEN | USE INSTEAD |
+|-----------|-------------|
+| Creating `.ps1` scripts | `Grep` tool to search `.cs` files |
+| Creating `.sh` / `.bat` scripts | `Glob` tool to find files by pattern |
+| Creating `temp-*` files | `Read` tool to inspect file contents |
+| Scanning DLLs / assemblies | Search source `.cs` files directly |
+| Running `dotnet` reflection commands | MCP `validate_conventions` tool |
+| Any file not part of the final deliverable | Ask the user if information is missing |
+
+**Type Discovery Rules:**
+- To find base classes: `Grep` for `class BaseEntity` or `class {Name}` in `*.cs` files
+- To find existing services: `Glob` for `**/I*Service.cs` in the Application layer
+- To find NuGet packages: `Read` the `.csproj` files directly
+- To find existing entities: `Glob` for `**/*.cs` in the Domain layer
+- If a type cannot be found after 2 search attempts: **ASK the user**, do NOT create scripts
+
 ## ASSOCIATED FILES
 
 ### Step Files (ACTIVE - Use These)

package/templates/skills/application/steps/step-04-backend.md

@@ -13,6 +13,8 @@ next_step: steps/step-05-frontend.md
 - ALWAYS generate Entity + Service + Controller as a unit
 - NEVER skip controller generation - API is required
 - YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+- **NEVER use Write on appsettings*.json** - ALWAYS use Edit (see _resources/config-safety.md)
+- **Replace secret VALUES with `<CONFIGURE_HERE>`** - NEVER delete keys or sections
 
 ## YOUR TASK
 
@@ -531,6 +533,25 @@ Scaffold the SQL objects infrastructure:
 
 **If SqlObjectHelper already exists:** Skip this check.
 
+### Check 6: Convention Validation (RECOMMENDED)
+
+Run MCP convention validation on the generated backend code:
+
+```
+Tool: mcp__smartstack__validate_conventions
+Args:
+  target: "backend"
+  scope: "{entity_name}"
+```
+
+This verifies:
+- Naming conventions (PascalCase entities, correct prefixes)
+- Architecture layers respected (no cross-layer violations)
+- Required attributes present (NavRoute, RequirePermission)
+- DTO patterns followed
+
+IF violations found: Fix them before proceeding to step-05.
+
 ---
 
 ## SUCCESS METRICS

package/templates/skills/application/steps/step-05-frontend.md

@@ -40,22 +40,28 @@ From previous steps:
 
 ## EXECUTION SEQUENCE
 
-### 1. Generate React Component
+### 1. Generate Frontend Pages (conventions-compliant)
 
 ```
 Tool: mcp__smartstack__scaffold_extension
 Args:
-  type: "component"
+  type: "page"
   name: "{entity_name}"
   options:
+    navRoute: "{full_path}"
     outputPath: "web/src/pages/{context}/{application}/{module}"
     dryRun: false
 ```
 
-This generates:
-- `{EntityName}Page.tsx` - Main page component
-- `{EntityName}ListView.tsx` - Reusable list view
-- `use{EntityName}.ts` - Custom hook for data
+This generates (all natively compliant with /ui-components conventions):
+- `{EntityName}Page.tsx` — List page wrapper with i18n
+- `{EntityName}ListView.tsx` — EntityCard grid + DataTable + ViewToggle + responsive + loading/error/empty states
+- `{EntityName}DetailPage.tsx` — Detail page with back button + pill tabs + info cards
+- `use{EntityName}Preferences.ts` — Preferences hook (viewMode, sorting, filters, columns)
+- i18n files for 4 languages (fr, en, it, de)
+
+> **Note:** The `type: "page"` scaffold already includes CSS variables, EntityCard, responsive grid,
+> semantic HTML, memo/useCallback, and all ui-components conventions. No manual corrections needed.
 
 ### 2. Generate API Client
 
@@ -134,38 +140,16 @@ If the context doesn't have a layout route yet, create one wrapping all child ro
 
 **Remember:** Also add the routes inside the tenant-prefixed block (`/t/:slug/...`) if it exists.
 
-### 4. Generate i18n Files
-
-Create translation files for each language:
+### 4. Verify i18n Files
 
-```markdown
-### French (fr/{entityCode}.json)
-```json
-{
-  "title": "{labels.fr}",
-  "subtitle": "Gestion de {labels.fr}",
-  "columns": {
-    "code": "Code",
-    "name": "Nom",
-    "createdAt": "Créé le",
-    "actions": "Actions"
-  },
-  "form": {
-    "code": "Code",
-    "name": "Nom",
-    "submit": "Enregistrer",
-    "cancel": "Annuler"
-  },
-  "messages": {
-    "created": "{labels.fr} créé avec succès",
-    "updated": "{labels.fr} mis à jour avec succès",
-    "deleted": "{labels.fr} supprimé avec succès",
-    "error": "Une erreur est survenue"
-  }
-}
-```
+> **Note:** i18n files are now auto-generated by `type: "page"` scaffold (step 1).
+> Verify the 4 language files were created and customize the `title`/`subtitle` with the proper labels.
 
-Repeat for en, it, de with appropriate translations.
+If the generated translations need customization (e.g., replacing generic title with `{labels.fr}`):
+- `i18n/locales/fr/{entityCode}.json` → set `"title": "{labels.fr}"`
+- `i18n/locales/en/{entityCode}.json` → set `"title": "{labels.en}"`
+- `i18n/locales/it/{entityCode}.json` → set `"title": "{labels.it}"`
+- `i18n/locales/de/{entityCode}.json` → set `"title": "{labels.de}"`
 
 ### 5. Present Output to User