@atlashub/smartstack-cli 3.36.0 → 3.38.0

package/templates/skills/documentation/steps/step-02-generate.md

@@ -0,0 +1,231 @@
+---
+name: Generate - Documentation Content
+description: Generate documentation TSX, i18n files, and data files based on type
+next_step: step-03-validate.md
+---
+
+## STEP 02: Generate — Documentation Content
+
+### Purpose
+
+Generate the complete documentation structure based on type (user/developer/database/testing/update) using data collected in step-01.
+
+### Generation By Type
+
+#### For `user` Type: Standalone Mock UI Page
+
+**IMPORTANT:** Generate a **standalone TSX page** with **annotated Mock UI** components that faithfully reproduce the real application interface. Each Mock UI section MUST be followed by `Annotation` components explaining each visual element. **DO NOT use DocRenderer or doc-data.ts for user type.**
+
+**Output:** Standalone React TSX component (~400-600 lines)
+
+**Structure — 9 Sections:**
+
+1. **Section 1: Business Value** — Problem + solution
+2. **Section 2: Access** — Navigation breadcrumb + URL
+3. **Section 3: Interface Overview** — Annotated Mock UI (faithful to real page)
+4. **Section 4: Create Form** — Annotated Mock UI (faithful to real form)
+5. **Section 5: Detail View** — Annotated Mock UI (faithful to real detail)
+6. **Section 6: Use Cases** — 2-3 personas
+7. **Section 7: Features** — 5 features with examples
+8. **Section 8: FAQ** — 5 non-technical questions
+9. **Section 9: Technical Reference** — Collapsible: business rules + API endpoints
+
+> **REMOVED:** "Benefits" and "Before/After" sections are NOT included. This is user documentation, not a sales pitch.
+
+**Files to Generate:**
+
+- `docs/business/{application}/{module}/index.tsx` (main page)
+- `docs/business/{application}/{module}/i18n/fr.json` (French)
+- `docs/business/{application}/{module}/i18n/en.json` (English)
+- `docs/business/{application}/{module}/i18n/de.json` (German)
+- `docs/business/{application}/{module}/i18n/it.json` (Italian)
+
+**i18n Format:** FLAT JSON (no root key) for standalone pages
+
+```json
+{
+  "title": "Module Title",
+  "subtitle": "...",
+  "sections": { ... }
+}
+```
+
+#### For `developer|database|testing` Types: Data-Driven with DocRenderer
+
+**Files to Generate:**
+
+- `docs/developer/{category}/{tool}Page.tsx` (wrapper)
+- `docs/developer/{category}/doc-data.ts` (data, ~50 lines)
+- `docs/developer/{category}/i18n/fr.json` (French)
+- `docs/developer/{category}/i18n/en.json` (English)
+- `docs/developer/{category}/i18n/de.json` (German)
+- `docs/developer/{category}/i18n/it.json` (Italian)
+
+**Workflow:**
+
+```
+1. Read source data (feature.json, code patterns)
+2. Generate doc-data.ts (data file, ~50 lines)
+3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
+4. Generate i18n files in ALL 4 languages (FR, EN, DE, IT) — with root key for DocRenderer
+5. Update docs-manifest.json
+6. Update App.tsx routing and parent indexes
+```
+
+**index.tsx Format for DocRenderer:**
+
+```tsx
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
+
+export default function {Tool}DocPage() {
+  return (
+    <DocRenderer
+      data={docData}
+      backPath="/docs/developer"
+      backLabel="nav.backToDeveloper"
+      i18nNamespace="docsDeveloper{Tool}"
+    />
+  );
+}
+```
+
+**i18n Format:** Nested JSON with root key matching namespace
+
+```json
+{
+  "docsDeveloper{Tool}": {
+    "title": "Tool Title",
+    "subtitle": "...",
+    "sections": { ... }
+  }
+}
+```
+
+#### For `update` Type
+
+Re-generate files using the same workflow as original type, but:
+
+```
+1. Read real page TSX → update Mock UI if interface changed
+2. Read controller → update API endpoints and business rules
+3. Update i18n files in ALL 4 languages (FR, EN, DE, IT)
+4. Update docs-manifest.json timestamps (refreshed_at)
+5. Do NOT regenerate route registration (already exists)
+```
+
+### Extraction Scripts Reference
+
+#### extract-api-endpoints.ts
+
+**Purpose:** Extract all API endpoints from SmartStack controllers
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**What it extracts:**
+- Controller file path (e.g., `UsersController.cs`)
+- HTTP method (`[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`)
+- Route suffix (e.g., `{id:guid}`, `activate`)
+- Base path from `[NavRoute("administration.users")]`
+- Permission from `[RequirePermission(Permissions.Admin.Users.View)]`
+- Handler method name
+
+**Output:** JSON array
+```json
+[
+  {
+    "method": "GET",
+    "path": "/api/administration/users",
+    "handler": "GetUsers",
+    "permission": "administration.users.read"
+  }
+]
+```
+
+#### extract-business-rules.ts
+
+**Purpose:** Extract business rules from Domain entities and unit tests
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Phase 1: Domain Entity Extraction**
+- Scans Domain entity (e.g., `User.cs`)
+- Looks for guard clauses: `if (...) throw new DomainException("...")`
+- Looks for validation in Create/Update methods
+- Extracts exception messages and context
+
+**Phase 2: Unit Tests Extraction**
+- Scans unit test file (e.g., `UserTests.cs`)
+- Looks for test methods with `[Fact]` attribute
+- Extracts test names and scenarios (edge cases)
+- Maps to business rule statements
+
+**Output:** JSON array
+```json
+[
+  {
+    "id": "BR-001",
+    "name": "Email requis",
+    "category": "Validation",
+    "statement": "Un utilisateur doit avoir une adresse email valide et non vide"
+  }
+]
+```
+
+#### generate-doc-with-mock-ui.ts
+
+**Purpose:** Main generator - creates complete documentation TSX with Mock UI
+
+**Input:**
+- `--module {module}` - Module name (e.g., users)
+- `--application {application}` - Application (e.g., administration)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Workflow:**
+1. Find Domain entity file (users → User.cs via singularize)
+2. Extract entity properties (name, type, nullable, required)
+3. Call `extract-api-endpoints.ts`
+4. Call `extract-business-rules.ts`
+5. Generate mock data (5 sample records with realistic values)
+6. Generate KPI stats (Total, Active/Inactive, Status breakdown)
+7. Generate table UI (smart column selection - 6 most relevant)
+8. Generate form UI (intelligent field types based on property)
+9. Output complete TSX file to stdout
+
+**Smart Features:**
+- **Singularize**: users → User.cs, tenants → Tenant.cs
+- **Property filtering**: Excludes hash, token, *Id, normalized, internal
+- **Priority selection**: name/title > email > status > date
+- **Field type detection**: email → email input, bool → checkbox
+- **Mock value generation**: Realistic emails, names, dates, GUIDs
+
+**Output:** Complete React TSX component (400-500 lines)
+
+### Absolute Rules
+
+1. **NEVER** hardcoded text → `useTranslation('namespace')`
+2. **NEVER** ASCII art → React/HTML components for ERD
+3. **ALWAYS** read the REAL page TSX before generating Mock UI
+4. **ALWAYS** read the controller to extract real API endpoints
+5. **ALWAYS** annotate every Mock UI section with `Annotation` components
+6. **ALWAYS** generate i18n in ALL 4 languages (FR, EN, DE, IT)
+7. **ALWAYS** use FLAT JSON (no root key) for standalone `user` type pages
+8. **ALWAYS** use nested JSON with root key for DocRenderer pages
+
+### Success Metrics
+
+- [x] TSX file generated with correct structure
+- [x] Mock UI faithfully reproduces real interface
+- [x] Every Mock UI section annotated with `Annotation` components
+- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT)
+- [x] JSON format correct (FLAT for user, nested for others)
+- [x] All hardcoded text uses `useTranslation()`
+- [x] No "Benefices" or "Avant/Apres" sections present
+
+### Next Step
+
+→ **step-03-validate.md** — Validate completeness and integrate into project.

package/templates/skills/documentation/steps/step-03-validate.md

@@ -0,0 +1,238 @@
+---
+name: Validate - Completeness and Integration
+description: Validate documentation completeness, accuracy, and integrate into SmartStack app
+next_step: null
+---
+
+## STEP 03: Validate — Completeness and Integration
+
+### Purpose
+
+Validate that generated documentation is complete and accurate, then integrate into the SmartStack app with proper routing and i18n configuration.
+
+### Validation Checklist
+
+#### All Types
+
+- [ ] Documentation page renders correctly in React app
+- [ ] i18n files created in ALL 4 languages (FR, EN, DE, IT)
+- [ ] Files saved to correct directory paths
+- [ ] docs-manifest.json updated with new entry
+- [ ] NO "Benefices" or "Avant/Apres" sections present
+
+#### For `user` Type Only
+
+- [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
+- [ ] Every Mock UI section has `Annotation` components explaining each visual element
+- [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
+- [ ] Route registered in App.tsx
+- [ ] Module appears in UserIndexPage.tsx (if applicable)
+- [ ] DocPanelContext.tsx mapping updated for all module routes
+- [ ] i18n/config.ts updated with new namespace
+- [ ] BookOpen edge button opens correct doc for the module's routes
+
+#### For `developer|database|testing` Types
+
+- [ ] i18n JSON uses root key matching namespace
+- [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
+- [ ] doc-data.ts contains structured data (~50 lines)
+- [ ] Route registered in App.tsx and parent indexes
+
+#### For `update` Type
+
+- [ ] Mock UI updates reflect current interface
+- [ ] API endpoints verified against current controller
+- [ ] Business rules updated with any new validation rules
+- [ ] docs-manifest.json timestamps refreshed
+- [ ] All 4 language files updated
+
+### Integration Steps
+
+#### UserIndexPage Integration (TYPE: user only)
+
+**MANDATORY** for `user` modules: Add the module to the navigation hierarchy.
+
+| File | Modification |
+|------|--------------|
+| `UserIndexPage.tsx` | Add icon + entry in `modules[]` of parent application |
+| `fr/docs.json` | Add `user.modules.{module}.name` and `.description` |
+| `en/docs.json` | Add `user.modules.{module}.name` and `.description` |
+
+**Parent applications:**
+- `Administration`: admin modules (users, roles, ai, entra...)
+- `Support`: support modules (tickets, sla, templates...)
+- `MySpace`: personal modules (profile, preferences...)
+
+**Verification:** The module should appear on `/docs/user` under its application.
+
+#### DocPanelContext Integration (TYPE: user only)
+
+**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.
+
+**File to update:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+
+**What to add:** For each module, add entries in the `docMapping` object for ALL the module's routes:
+
+```typescript
+const docMapping: Record<string, string> = {
+  // Administration > {Module}
+  '{module}': '/docs/business/administration/{module}',
+  '{module}/list': '/docs/business/administration/{module}',
+  '{module}/create': '/docs/business/administration/{module}',
+  '{module}/dashboard': '/docs/business/administration/{module}',
+  // ... add ALL sub-routes that exist for the module
+};
+```
+
+**Also update `appDocMapping`** if the module is the "default" for its application:
+
+```typescript
+const appDocMapping: Record<string, string> = {
+  'administration': '/docs/business/administration/users',  // default for admin
+};
+```
+
+**Key resolution logic:** The `getDocUrlForPath()` function extracts segments from the pathname:
+- `/administration/users/list` → tries `users/list`, then `users`
+- `/support/tickets/123` → tries `tickets/123`, then `tickets`
+
+#### App.tsx Routing
+
+**For `user` type:** Add dynamic import and route:
+
+```tsx
+const {Module}DocPage = lazy(() =>
+  import('@/pages/docs/business/{application}/{module}')
+);
+
+// In routes array:
+{
+  path: '/docs/business/{application}/{module}',
+  element: <Suspense><{Module}DocPage /></Suspense>
+}
+```
+
+**For `developer|database|testing` types:** Add to appropriate category:
+
+```tsx
+const {Tool}DocPage = lazy(() =>
+  import('@/pages/docs/developer/{category}/{tool}')
+);
+
+// In routes array:
+{
+  path: '/docs/developer/{category}/{tool}',
+  element: <Suspense><{Tool}DocPage /></Suspense>
+}
+```
+
+#### i18n Config Update
+
+**File:** `web/smartstack-web/src/i18n/config.ts`
+
+Add the new namespace to `loadLanguageResources`:
+
+```typescript
+// 1. Add to destructured imports
+const {
+  docsAdministrationUsers,
+  docsAdministrationPermissions,
+  docsAdministrationNewModule, // NEW
+  // ...
+} = resources;
+
+// 2. Add dynamic import with fallback
+const docsAdministrationNewModule = await import(
+  '@i18n/docs-administration-new-module.json'
+).catch(() => ({ default: {} }));
+
+// 3. Add to return object
+return {
+  // ...
+  docsAdministrationNewModule,
+};
+
+// 4. Add to ns array in i18n.init()
+ns: [
+  'common',
+  'nav',
+  'docsAdministrationUsers',
+  'docsAdministrationPermissions',
+  'docsAdministrationNewModule', // NEW
+  // ...
+]
+```
+
+#### docs-manifest.json Update
+
+Add or update entry with metadata:
+
+```json
+{
+  "id": "{module}",
+  "type": "user",
+  "title": "Module Title",
+  "application": "administration",
+  "path": "/docs/business/administration/{module}",
+  "created_at": "2026-02-17T10:30:00Z",
+  "refreshed_at": "2026-02-17T10:30:00Z",
+  "i18n_namespace": "docsAdministration{Module}",
+  "routes": [
+    "{module}",
+    "{module}/list",
+    "{module}/create"
+  ]
+}
+```
+
+### Data Sources Reference
+
+| Data | Source |
+|------|--------|
+| DB schemas | `src/SmartStack.Infrastructure/Persistence/Configurations/` |
+| Tables | `ApplicationDbContextModelSnapshot.cs` |
+| Existing documentation | `web/smartstack-web/src/pages/docs/` |
+| Testing tools | WebSearch (current versions) |
+| Real UI pages | `web/smartstack-web/src/pages/{Application}/` |
+| Controllers | `src/SmartStack.Api/Controllers/` |
+| Domain entities | `src/SmartStack.Domain/Entities/` |
+| Permissions | `src/SmartStack.Domain/Authorization/Permissions.cs` |
+
+### Associated Files Reference
+
+- **React Templates:** `templates.md`
+- **Data Schema:** `data-schema.md`
+- **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
+- **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
+- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
+- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
+- **Manifest Schema:** `_resources/docs-manifest-schema.md`
+- **Complete Command:** `.claude/commands/documentation-module.md`
+
+### Success Metrics
+
+- [x] Documentation page renders correctly in React app
+- [x] Mock UI faithfully reproduces the real page interface (user type)
+- [x] Every Mock UI section has `Annotation` components (user type)
+- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
+- [x] Route registered in App.tsx
+- [x] docs-manifest.json updated
+- [x] i18n/config.ts updated with new namespace
+- [x] Module appears in UserIndexPage (if type = user)
+- [x] DocPanelContext.tsx mapping updated (if type = user)
+- [x] BookOpen edge button opens correct doc for the module's routes
+- [x] NO "Benefices" or "Avant/Apres" sections present
+- [x] All tests pass and app builds successfully
+
+### Completion
+
+**Documentation workflow complete.** The generated documentation is now:
+- Fully integrated into SmartStack app
+- Accessible via routing system
+- Accessible via DocPanel contextual button
+- Internationalized in FR, EN, DE, IT
+- Listed in docs-manifest.json for discovery
+
+**Next:** Monitor for feedback on documentation accuracy and completeness. Use step-03 validation checklist for future updates.