docs: map existing codebase

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 09:28:40 +02:00
parent 10bfe6debc
commit 63cf69f114
7 changed files with 1490 additions and 0 deletions
--- a/.planning/codebase/ARCHITECTURE.md
+++ b/.planning/codebase/ARCHITECTURE.md
@@ -0,0 +1,302 @@
+# Architecture
+
+**Analysis Date:** 2026-04-02
+
+## Pattern Overview
+
+**Overall:** Monolithic PowerShell Application with WinForms UI and Async Runspace Pattern
+
+**Key Characteristics:**
+- Single-file PowerShell script (6408 lines) serving as entry point
+- Native WinForms GUI (no external UI framework dependencies)
+- Asynchronous operations via dedicated PowerShell runspaces to prevent UI blocking
+- Hashtable-based state management for inter-runspace communication
+- PnP.PowerShell module for all SharePoint Online interactions
+- Profile and template persistence via JSON files
+- Region-based code organization for logical grouping
+
+## Layers
+
+**Presentation Layer (GUI):**
+- Purpose: User interface and interaction handling
+- Location: `Sharepoint_ToolBox.ps1` lines 2990-3844 (GUI setup) + event handlers
+- Contains: WinForms controls, dialogs, input validation, visual updates
+- Depends on: Shared helpers, Settings layer
+- Used by: Event handlers, runspace callbacks via synchronized hashtable
+
+**Application Layer (Business Logic):**
+- Purpose: Core operations for each feature (permissions, storage, templates, search, duplicates)
+- Location: `Sharepoint_ToolBox.ps1` multiple regions:
+  - Permissions: lines 1784-2001
+  - Storage: lines 2002-2110
+  - File Search: lines 2112-2233
+  - Duplicates: lines 2235-2408
+  - Templates: lines 475-1360
+  - Transfer/Bulk: lines 2410-3000
+- Contains: PnP API calls, data aggregation, report generation
+- Depends on: PnP.PowerShell module, Presentation feedback
+- Used by: Event handlers via runspaces, HTML/CSV export functions
+
+**Data Access Layer:**
+- Purpose: File I/O, persistence, caching
+- Location: `Sharepoint_ToolBox.ps1` dedicated regions:
+  - Profile Management: lines 48-127
+  - Settings: lines 129-154
+  - Template Management: lines 475-533
+- Contains: JSON serialization/deserialization, profile CRUD, settings management
+- Depends on: File system access
+- Used by: Application layer, GUI initialization
+
+**Export & Reporting Layer:**
+- Purpose: Transform data to CSV and interactive HTML
+- Location: `Sharepoint_ToolBox.ps1`:
+  - Permissions HTML: lines 1361-1617
+  - Storage HTML: lines 1619-1784
+  - Search HTML: lines 2112-2233
+  - Duplicates HTML: lines 2235-2408
+  - Transfer HTML: lines 2412-2547
+- Contains: HTML template generation, JavaScript for interactivity, CSV formatting
+- Depends on: Application layer data, System.Drawing for styling
+- Used by: Feature implementations for export operations
+
+**Integration Layer:**
+- Purpose: External service communication (SharePoint, PnP.PowerShell)
+- Location: `Sharepoint_ToolBox.ps1` PnP function regions
+- Contains: Connect-PnPOnline, Get-PnP* cmdlets, authentication handling
+- Depends on: PnP.PowerShell module, credentials from user input
+- Used by: Application layer operations
+
+**Utilities & Helpers:**
+- Purpose: Cross-cutting formatting, UI helpers, internationalization
+- Location: `Sharepoint_ToolBox.ps1`:
+  - Shared Helpers: lines 4-46
+  - Internationalization: lines 2732-2989
+  - UI Control Factories: lines 3119-3146
+- Contains: Write-Log, Format-Bytes, EscHtml, T() translator, control builders
+- Depends on: System.Windows.Forms, language JSON file
+- Used by: All other layers
+
+## Data Flow
+
+**Permissions Report Generation:**
+
+1. User selects site(s) and report options in GUI (Permissions tab)
+2. Click "Générer le rapport" triggers event handler at line 4068+
+3. Validation via `Validate-Inputs` (line 30)
+4. GUI triggers runspace via `Start-Job` with user parameters
+5. Runspace calls `Generate-PnPSitePermissionRpt` (line 1852)
+6. `Generate-PnPSitePermissionRpt` connects to SharePoint via `Connect-PnPOnline` (line 1864)
+7. Recursive permission scanning:
+   - `Get-PnPWebPermission` (line 1944) for site/webs
+   - `Get-PnPListPermission` (line 1912) for lists and libraries
+   - `Get-PnPFolderPermission` (line 1882) for folders (if enabled)
+   - `Get-PnPPermissions` (line 1786) extracts individual role assignments
+8. Results accumulated in `$script:AllPermissions` array
+9. Export based on format choice:
+   - CSV: `Merge-PermissionRows` (line 1363) then `Export-Csv`
+   - HTML: `Export-PermissionsToHTML` (line 1389) generates interactive report
+10. Output file path returned to UI via synchronized hashtable
+11. User can open report via `btnPermOpen` click handler
+
+**Storage Metrics Scan:**
+
+1. User selects storage options and sites
+2. Click "Générer les métriques" triggers runspace job
+3. Job calls `Get-SiteStorageMetrics` (line 2004)
+4. Per-site or per-library scanning:
+   - Connect to web via `Connect-PnPOnline`
+   - `Get-PnPList` retrieves document libraries (if per-library mode)
+   - `Get-PnPFolderStorageMetric` for library/root metrics
+   - `Collect-FolderStorage` (recursive nested function) walks folder tree to configured depth
+5. Results accumulate in `$script:storageResults` with hierarchy intact
+6. HTML or CSV export writes report file
+7. File path communicated back to UI
+
+**Site Picker (Browse Sites):**
+
+1. User clicks "Voir les sites" button
+2. `Show-SitePicker` dialog opens (line 212)
+3. User clicks "Charger les sites" button
+4. Dialog initializes `$script:_pkl` state hashtable (line 315)
+5. Runspace spawned in `btnLoad.Add_Click` (line 395)
+6. Runspace connects to admin site and retrieves all sites via `Get-PnPTenantSite`
+7. Results queued back to UI via synchronized `$script:_pkl.Sync` hashtable
+8. Timer polls `$script:_pkl.Sync` and updates ListView asynchronously
+9. User filters by text, sorts columns, checks/unchecks sites
+10. Returns selected site URLs in `$script:SelectedSites` array
+
+**File Search:**
+
+1. User enters search criteria (extensions, regex, date ranges, etc.)
+2. Click "Lancer la recherche" triggers runspace
+3. Runspace uses PnP Search API (KQL) with filters:
+   - File extension filters via `fileExtension:ext1` OR syntax
+   - Date range filters via `Created >= date`
+   - Regex applied client-side after retrieval
+4. Results paginated and accumulated
+5. Exported to CSV or HTML with interactive filtering/sorting
+
+**Duplicate Detection:**
+
+1. User chooses file or folder mode and comparison criteria
+2. Click "Lancer le scan" triggers runspace
+3. File duplicates: Search API with filename-based grouping
+4. Folder duplicates: Enumerate all folders, compare attributes (size, dates, subfolder/file counts)
+5. Results grouped by match criteria
+6. HTML export shows grouped duplicates with visual indicators (green/orange for matching/differing fields)
+
+**Template Capture & Apply:**
+
+1. Capture mode: `Show-TemplateManager` dialog (line 542)
+   - User selects "Capture from site"
+   - Runspace scans site structure via `Get-PnPList`, `Get-PnPFolderItem`, `Get-PnPWebPermission`
+   - Captures libraries, folders, permission groups, site logo, title
+   - Persisted to `Sharepoint_Templates.json`
+2. Apply mode: User selects template and target site
+   - Runspace creates lists/libraries via `New-PnPList`
+   - Replicates folder structure via `New-PnPFolder`
+   - Applies permission groups if selected
+   - Logs creation results
+
+**State Management:**
+
+- `$script:` variables hold state across runspace calls (profiles, sites, results, settings)
+- Synchronized hashtables (`$script:_pkl`, `$script:_sync`) enable runspace-to-UI communication
+- Timer at line 3850-3870 polls synchronized hashtable and updates GUI with progress/results
+- Event handlers trigger jobs but don't block waiting for completion (asynchronous pattern)
+
+## Key Abstractions
+
+**Runspace Encapsulation:**
+
+- Purpose: Execute long-running SharePoint operations without freezing GUI
+- Pattern: `$job = Start-Job -ScriptBlock { ... } -RunspacePool $rsPool`
+- Example: `Start-NextStorageScan` (line 4536) manages storage scan runspace jobs
+- Trade-off: Requires careful state management via shared hashtables; no direct closures
+
+**Hashtable-Based State:**
+
+- Purpose: Share mutable state between main runspace and job runspaces
+- Pattern: `$sync = @{ Data = @(); Status = "Running" }` passed to job
+- Example: `$script:_pkl` (line 315) manages site picker state across checkbox events
+- Benefit: Avoids closure complexity; timer can poll changes safely
+
+**Dialog Modal Isolation:**
+
+- Purpose: Site picker and template manager as isolated UI contexts
+- Pattern: `Show-SitePicker` and `Show-TemplateManager` create self-contained `Form` objects
+- State stored in `$script:_pkl` and `$script:_tpl` respectively
+- Returns result arrays (selected sites, template data) to main form
+
+**Language Translation System:**
+
+- Purpose: Internationalization without external dependencies
+- Pattern: `T("key")` function (line 2908) looks up keys in `$script:LangDict` hashtable
+- Source: `lang/fr.json` contains French translations; English is hardcoded
+- Used throughout: All UI labels, buttons, messages use `T()` for localization
+
+**HTML Export Templates:**
+
+- Purpose: Dynamically generate interactive HTML reports with embedded JavaScript
+- Pattern: String templates with `@"` heredoc syntax containing HTML/CSS/JS
+- Examples:
+  - `Export-PermissionsToHTML` (line 1389): Responsive table, collapsible groups, copy-to-clipboard
+  - `Export-StorageToHTML` (line 1621): Tree visualization, sorting, filtering
+  - `Export-DuplicatesToHTML` (line 2235): Grouped duplicates with visual indicators
+- Benefit: No external libraries; reports are self-contained single-file HTML
+
+## Entry Points
+
+**Main GUI Form:**
+- Location: `Sharepoint_ToolBox.ps1` line 2992
+- Triggers: Script execution via `.ps1` file or PowerShell IDE
+- Responsibilities:
+  - Initialize WinForms components (form, controls, menus)
+  - Load and populate profiles/settings from JSON
+  - Register event handlers for all buttons and controls
+  - Run main event loop `[void]$form.ShowDialog()`
+
+**Feature Event Handlers:**
+- Location: Various in lines 4068+ (Event Handlers region)
+- Examples:
+  - `btnPermRun.Add_Click` → Permissions report generation
+  - `btnStorRun.Add_Click` → Storage metrics scan
+  - `btnSearchRun.Add_Click` → File search
+  - `btnDupRun.Add_Click` → Duplicate detection
+- Pattern: Validate inputs, start runspace job, launch progress animation, register cleanup callback
+
+**Background Runspaces:**
+- Entry: `Start-Job -ScriptBlock { Generate-PnPSitePermissionRpt ... }`
+- Execution: PnP cmdlets execute within runspace's isolated context
+- Completion: Job completion callback writes results to synchronized hashtable; timer detects and updates UI
+
+**Language Switch:**
+- Location: Menu → Language submenu (line 3011+)
+- Handler: `Switch-AppLanguage` (line 4167)
+- Updates: All UI labels via `Update-UILanguage` (line 2951)
+
+## Error Handling
+
+**Strategy:** Try/Catch with graceful degradation; errors logged to UI RichTextBox
+
+**Patterns:**
+
+1. **Runspace Error Handling:**
+   ```powershell
+   try { $result = Get-PnPList }
+   catch { Write-Log "Error: $($_.Exception.Message)" "Red" }
+   ```
+
+2. **Connection Validation:**
+   - `Validate-Inputs` (line 30) checks required fields before operation
+   - `Connect-PnPOnline` fails if credentials invalid; caught and logged
+
+3. **File I/O Protection:**
+   ```powershell
+   if (Test-Path $path) {
+       try { $data = Get-Content $path -Raw | ConvertFrom-Json }
+       catch {} # Silently ignore JSON parse errors
+   }
+   ```
+
+4. **UI Update Safety:**
+   - `Write-Log` checks `if ($script:LogBox -and !$script:LogBox.IsDisposed)` before updating
+   - Prevents access to disposed UI objects after form close
+
+5. **Missing Configuration Handling:**
+   - Settings default to English + current directory if file missing
+   - Profiles default to empty array if file missing
+   - Templates default to empty if file corrupted
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Framework: `Write-Log` function (line 6)
+- Pattern: Writes colored messages to RichTextBox + host console
+- Usage: All operations log status (connecting, scanning, exporting)
+- Timestamps: `Get-Date -Format 'HH:mm:ss'` prefixes each message
+
+**Validation:**
+- Entry point: `Validate-Inputs` (line 30) checks ClientID and Site URL
+- Pattern: Early return if missing; user sees MessageBox with missing field hint
+- Localization: Error messages use `T()` function for i18n
+
+**Authentication:**
+- Method: Interactive browser login via `Connect-PnPOnline -Interactive`
+- Pattern: PnP module opens browser for Azure AD consent; token cached within session
+- Credential scope: Per site connection; multiple connections supported (for multi-site operations)
+- Token management: Automatic via PnP.PowerShell; no manual handling
+
+**Asynchronous Progress:**
+- Animation: `Start-ProgressAnim` (line 3845) flashes "Running..." in status label
+- Polling: Timer at line 3850-3870 checks `$job.State` and synchronized hashtable every 300ms
+- Cleanup: `Stop-ProgressAnim` (line 3850) stops animation when job completes
+
+**UI Responsiveness:**
+- Pattern: `[System.Windows.Forms.Application]::DoEvents()` called during long operations
+- Benefit: Allows UI events (button clicks, close) to process while waiting
+- Cost: Runspace jobs recommended for truly long operations (>5 second operations)
+
+---
+
+*Architecture analysis: 2026-04-02*
--- a/.planning/codebase/CONCERNS.md
+++ b/.planning/codebase/CONCERNS.md
@@ -0,0 +1,221 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-04-02
+
+## Tech Debt
+
+**Silent Error Handling (Widespread):**
+- Issue: 38 empty `catch` blocks that suppress errors without logging
+- Files: `Sharepoint_ToolBox.ps1` (lines 1018, 1020, 1067, 1068, 1144, 2028, 2030, etc.)
+- Impact: Failures go unnoticed, making debugging difficult. Users don't know why operations fail. Error conditions are hidden from logs.
+- Fix approach: Add logging to all `catch` blocks. Use `BgLog` for background tasks, `Write-Log` for UI threads. Example: `catch { BgLog "Folder enumeration failed: $_" "DarkGray" }` instead of `catch {}`
+
+**Resource Cleanup Issues:**
+- Issue: Runspace and PowerShell objects created in background jobs may not be properly disposed if exceptions occur
+- Files: `Sharepoint_ToolBox.ps1` lines 1040-1052, 4564-4577, 5556-5577
+- Impact: Memory leaks possible if UI interactions are interrupted. Zombie runspaces could accumulate over multiple operations.
+- Fix approach: Wrap all runspace/PS object creation in try-finally blocks. Ensure `$rs.Dispose()` and `$ps.Dispose()` are called in finally block, not just in success path
+
+**Overly Broad Error Suppression:**
+- Issue: 27 instances of `-ErrorAction SilentlyContinue` spread throughout code
+- Files: `Sharepoint_ToolBox.ps1` (e.g., lines 1142, 1188, 2070, 4436, etc.)
+- Impact: Real failures indistinguishable from expected failures (e.g., list doesn't exist vs. connection failed). Masks bugs.
+- Fix approach: Use selective error suppression. Only suppress when you've explicitly checked for the condition (e.g., "if list doesn't exist, create it"). Otherwise use `-ErrorAction Stop` with explicit try-catch.
+
+**Inconsistent JSON Error Handling:**
+- Issue: JSON parsing in `Load-Profiles`, `Load-Settings`, `Load-Templates` uses empty catch blocks
+- Files: `Sharepoint_ToolBox.ps1` lines 61, 140, 568-570
+- Impact: Corrupted JSON files silently fail and return empty defaults, losing user data silently
+- Fix approach: Log actual error message. Implement validation schema. Create backup of corrupted files.
+
+## Known Bugs
+
+**Blank Client ID Warning Not Actionable:**
+- Symptoms: "WARNING: No Client ID returned" appears but doesn't prevent further operations or clear user input
+- Files: `Sharepoint_ToolBox.ps1` line 4237
+- Trigger: Azure AD app registration completes but returns null ClientId (can happen with certain tenant configurations)
+- Workaround: Manually register app via Azure Portal and paste Client ID
+- Fix approach: Check for null ClientId before continuing, clear the warning state properly
+
+**Group Member Addition Silent Failures:**
+- Symptoms: Members appear not to be added to sites, but no error shown in UI
+- Files: `Sharepoint_ToolBox.ps1` lines 1222-1225, 5914, 5922 (try-catch with SilentlyContinue)
+- Trigger: User exists but cannot be added to group (permissions, licensing, or source-specific SP group issues)
+- Workaround: Manual group membership assignment
+- Fix approach: Replace SilentlyContinue with explicit logging of why Add-PnPGroupMember failed
+
+**Folder Metadata Loss in Template Application:**
+- Symptoms: Folder permissions captured correctly but not reapplied when permissions=true but structure already exists
+- Files: `Sharepoint_ToolBox.ps1` lines 1229-1292 (folder-level permission application depends on library structure map being built first)
+- Trigger: Target library created by Apply-FolderTree but permissions application logic expects library to already exist in template structure
+- Workaround: Delete and recreate target library, or manually apply permissions via SharePoint UI
+- Fix approach: Build library map before applying folder tree, or add validation that all referenced libraries exist
+
+**CSV Import for Bulk Operations Not Validated:**
+- Symptoms: Invalid CSV format silently fails, users see no clear error, form appears unresponsive
+- Files: `Sharepoint_ToolBox.ps1` lines 5765-5800 (CSV parsing with inadequate error context)
+- Trigger: CSV with missing headers, wrong delimiter, or invalid format
+- Workaround: Edit CSV manually to match expected format, restart tool
+- Fix approach: Add CSV schema validation before processing, show specific validation errors
+
+## Security Considerations
+
+**Client ID and Tenant URL Hardcoded in Temp Files:**
+- Risk: Temp registration script contains unencrypted Client ID and Tenant ID in plaintext
+- Files: `Sharepoint_ToolBox.ps1` lines 4210-4245 (temp file creation)
+- Current mitigation: Temp file cleanup attempted but not guaranteed if process crashes
+- Recommendations: Use SecureString to pass credentials, delete temp file with -Force in finally block, or use named pipes instead of files
+
+**No Validation of Tenant URL Format:**
+- Risk: Arbitrary URLs accepted, could be typos leading to authentication against wrong tenant
+- Files: `Sharepoint_ToolBox.ps1` lines 4306-4317, 30-43 (Validate-Inputs)
+- Current mitigation: URL used as-is, relies on PnP authentication failure to catch issues
+- Recommendations: Add regex validation for SharePoint tenant URLs, warn on suspicious patterns
+
+**Profile File Contains Credentials in Plaintext:**
+- Risk: `Sharepoint_Export_profiles.json` contains Client ID and Tenant URL in plaintext on disk
+- Files: `Sharepoint_ToolBox.ps1` lines 50-72 (profile persistence)
+- Current mitigation: File located in user home directory (Windows ACL protection), but still plaintext
+- Recommendations: Consider encrypting profile file with DPAPI, or move to Windows Credential Manager
+
+**PnP PowerShell Module Trust Not Validated:**
+- Risk: Module imported without version pinning, could load compromised version
+- Files: `Sharepoint_ToolBox.ps1` lines 151, 1151, 4218, 4521, 5833 (Import-Module PnP.PowerShell)
+- Current mitigation: None
+- Recommendations: Pin module version in manifest, use `-MinimumVersion` parameter, check module signature
+
+## Performance Bottlenecks
+
+**Synchronous UI Freezes During Large Operations:**
+- Problem: File search with 50,000 result limit processes all results at once, building HTML string in memory
+- Files: `Sharepoint_ToolBox.ps1` lines 2112-2133 (Export-SearchResultsToHTML builds entire table in string)
+- Cause: All results concatenated into single `$rows` string before sending to UI
+- Improvement path: Implement pagination in HTML reports, stream results rather than buffering all in memory. For large datasets, chunk exports into multiple files.
+
+**Folder Storage Recursion Not Depth-Limited by Default:**
+- Problem: `Collect-FolderStorage` recurses unlimited depth unless explicitly capped, can take hours on deep folder structures
+- Files: `Sharepoint_ToolBox.ps1` lines 2009-2032, 4432-4455
+- Cause: CurrentDepth compared against FolderDepth limit, but FolderDepth defaults to 999 if not set
+- Improvement path: Default to depth 3-4, show estimated scan time based on depth, implement cancellation token
+
+**No Parallel Processing for Multiple Sites:**
+- Problem: Sites processed sequentially in Permissions/Storage reports, one site blocks all others
+- Files: `Sharepoint_ToolBox.ps1` lines 4379-4401 (foreach loop in permissions scan)
+- Cause: Single-threaded approach with `Connect-PnPOnline` context switches
+- Improvement path: Queue-based processing for multiple sites (partially done for storage scans), implement async context management
+
+**HTML Report Generation for Large Duplicates List:**
+- Problem: Export-DuplicatesToHTML builds entire HTML in memory, slow for 10,000+ duplicates
+- Files: `Sharepoint_ToolBox.ps1` lines 2235-2400 (HTML string concatenation in loop)
+- Cause: All groups converted to HTML before writing to file
+- Improvement path: Stream HTML generation, write to file incrementally, implement lazy-loading tables in browser
+
+## Fragile Areas
+
+**Language System (T() function):**
+- Files: `Sharepoint_ToolBox.ps1` (translation lookups throughout, ~15 hardcoded English fallbacks like "Veuillez renseigner")
+- Why fragile: Language loading can fail silently, UI control updates hardcoded at multiple locations, no fallback chain for missing translations
+- Safe modification: Add validation that all UI strings have corresponding translation keys before form creation. Create helper function that returns English default if key missing.
+- Test coverage: No tests for translation system. Gaps: Missing translations for error messages, hardcoded "Veuillez renseigner" strings that bypass T() function
+
+**Profile Management:**
+- Files: `Sharepoint_ToolBox.ps1` lines 50-127
+- Why fragile: Profile list is in-memory array that syncs with JSON file. If Save-Profiles fails, changes are lost. No transaction semantics.
+- Safe modification: Implement write-lock pattern. Create backup before write. Validate JSON before replacing file.
+- Test coverage: No validation that profile save actually persists. Race condition if opened in multiple instances.
+
+**Runspace State Machine:**
+- Files: `Sharepoint_ToolBox.ps1` lines 1034-1095, 4580-4650 (runspace creation, async timer polling)
+- Why fragile: UI state (`btnGenPerms.Enabled = false`) set before runspace begins, but no explicit state reset if runspace crashes or hangs
+- Safe modification: Implement state enum (Idle, Running, Done, Error). Always reset state in finally block. Set timeout on runspace execution.
+- Test coverage: No timeout tests. Gaps: What happens if runspace hangs indefinitely? Button remains disabled forever.
+
+**Site Picker List View:**
+- Files: `Sharepoint_ToolBox.ps1` lines 157-250 (_Pkl-* functions)
+- Why fragile: AllSites list updates while UI may be reading it (SuppressCheck flag used but incomplete synchronization)
+- Safe modification: Use proper locking or rebuild entire list atomically. Current approach relies on flag which may miss updates.
+- Test coverage: No concurrent access tests. Gaps: What if site is checked while sort is happening?
+
+## Scaling Limits
+
+**Permissions Report HTML with Large Item Counts:**
+- Current capacity: Tested up to ~5,000 items, performance degrades significantly
+- Limit: HTML table becomes unusable in browser above 10,000 rows (sorting, filtering slow)
+- Scaling path: Implement client-side virtual scrolling in HTML template, paginate into multiple reports, add server-side filtering before export
+
+**File Search Result Limit:**
+- Current capacity: 50,000 result maximum hardcoded
+- Limit: Beyond 50,000 files, results truncated without warning
+- Scaling path: Implement pagination in SharePoint Search API, show "more results available" warning, allow user to refine search
+
+**Runspace Queue Processing:**
+- Current capacity: Single queue per scan, sequential processing
+- Limit: If background job produces messages faster than timer dequeues, queue could grow unbounded
+- Scaling path: Implement back-pressure (slow producer if queue > 1000 items), implement priority queue
+
+**Profile JSON File Size:**
+- Current capacity: Profiles loaded entirely into memory, no limit on file size
+- Limit: If user creates 1,000+ profiles, JSON file becomes slow to load/save
+- Scaling path: Implement profile paging, index file by profile name, lazy-load profile details
+
+## Dependencies at Risk
+
+**PnP.PowerShell Module Version Mismatch:**
+- Risk: Module API changes between major versions, cmdlet parameter changes
+- Impact: Features relying on specific cmdlet parameters break silently
+- Migration plan: Pin to stable version range in script header. Create version compatibility matrix. Test against 2-3 stable versions.
+
+**System.Windows.Forms Dependency:**
+- Risk: WinForms support in PowerShell 7 is deprecated, future versions may not ship it
+- Impact: GUI completely broken on future PowerShell versions
+- Migration plan: Consider migrating to WPF or cross-platform GUI framework (Avalonia). Current WinForms code is tied to Assembly loading.
+
+## Missing Critical Features
+
+**No Operation Cancellation:**
+- Problem: Running operations (permissions scan, storage metrics, file search) cannot be stopped mid-execution
+- Blocks: User stuck waiting for slow operations to complete, no way to abort except kill process
+
+**No Audit Log:**
+- Problem: No record of who ran what operation, what results were exported, when last backup occurred
+- Blocks: Compliance, troubleshooting
+
+**No Dry-Run for Most Operations:**
+- Problem: Only version cleanup has dry-run. Permission changes, site creation applied immediately without preview
+- Blocks: Prevents risk assessment before making changes
+
+## Test Coverage Gaps
+
+**PnP Connection Failures:**
+- What's not tested: Connection timeouts, intermittent network issues, authentication failures mid-operation
+- Files: `Sharepoint_ToolBox.ps1` lines 36, 157, 170, 2036, 4458, etc. (Connect-PnPOnline calls)
+- Risk: Tool may hang indefinitely if connection drops. No retry logic.
+- Priority: High
+
+**Malformed JSON Resilience:**
+- What's not tested: Templates.json, Profiles.json, Settings.json with invalid JSON, missing fields, type mismatches
+- Files: `Sharepoint_ToolBox.ps1` lines 61, 140, 568 (ConvertFrom-Json)
+- Risk: Tool fails to start or loses user data
+- Priority: High
+
+**Large-Scale Operations:**
+- What's not tested: Permissions scan on site with 50,000+ items, storage metrics on 10,000+ folders, file search returning 40,000+ results
+- Files: Bulk scanning functions throughout
+- Risk: Memory exhaustion, timeout, UI freeze
+- Priority: Medium
+
+**Runspace Cleanup on Error:**
+- What's not tested: Runspace exception handling, cleanup if UI window closes during background operation
+- Files: `Sharepoint_ToolBox.ps1` lines 1040-1052, 4564-4577, 5556-5577
+- Risk: Zombie processes, resource leaks
+- Priority: Medium
+
+**CSV Format Validation:**
+- What's not tested: Invalid column headers, wrong delimiter, missing required columns in bulk operations
+- Files: `Sharepoint_ToolBox.ps1` lines 5765-5800
+- Risk: Silent failures, partial data import
+- Priority: Medium
+
+---
+
+*Concerns audit: 2026-04-02*
--- a/.planning/codebase/CONVENTIONS.md
+++ b/.planning/codebase/CONVENTIONS.md
@@ -0,0 +1,210 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-04-02
+
+## Naming Patterns
+
+**Functions:**
+- PascalCase for public functions: `Write-Log`, `Get-ProfilesFilePath`, `Load-Profiles`, `Save-Profiles`, `Show-InputDialog`
+- Verb-Noun format using standard PowerShell verbs: Get-, Load-, Save-, Show-, Export-, Apply-, Validate-, Merge-, Refresh-, Switch-
+- Private/internal functions prefixed with underscore: `_Pkl-FormatMB`, `_Pkl-Sort`, `_Pkl-Repopulate`, `_Tpl-Repopulate`, `_Tpl-Log`
+- Descriptive names reflecting operation scope: `Get-SiteStorageMetrics`, `Collect-FolderStorage`, `Collect-WebStorage`, `Export-PermissionsToHTML`
+
+**Variables:**
+- camelCase for local variables: `$message`, `$color`, `$data`, `$index`, `$siteSrl`
+- PascalCase for control variables and form elements: `$form`, `$LogBox`, `$ClientId`, `$SiteURL`
+- Prefixed script-scope variables with `$script:` for shared state: `$script:LogBox`, `$script:Profiles`, `$script:SelectedSites`, `$script:_pkl`, `$script:_tpl`
+- Abbreviated but meaningful names in tight loops: `$s` (site), `$e` (event), `$i` (index), `$m` (message), `$c` (color)
+- Hashtable keys use camelCase: `@{ name = "...", clientId = "...", tenantUrl = "..." }`
+
+**Parameters:**
+- Type hints included in function signatures: `[string]$Message`, `[array]$Data`, `[switch]$IncludeSubsites`, `[int]$CurrentDepth`
+- Optional parameters use `= $null` or `= $false` defaults: `[string]$Color = "LightGreen"`, `[System.Windows.Forms.Form]$Owner = $null`
+- Single-letter abbreviated parameters in nested functions: `param($s, $e)` for event handlers
+
+**File/Directory Names:**
+- Single main script file: `Sharepoint_ToolBox.ps1`
+- Settings/profile files: `Sharepoint_Settings.json`, `Sharepoint_Export_profiles.json`, `Sharepoint_Templates.json`
+- Generated report files use pattern: `{ReportType}_{site/date}_{timestamp}.{csv|html}`
+
+## Code Style
+
+**Formatting:**
+- No explicit formatter configured
+- Indentation: 4 spaces (PowerShell default)
+- Line length: practical limit around 120 characters (some HTML generation lines exceed this)
+- Braces on same line for blocks: `function Name { ... }`, `if ($condition) { ... }`
+- Region markers used for file organization: `#region ===== Section Name =====` and `#endregion`
+
+**Regions Organization (in `Sharepoint_ToolBox.ps1`):**
+- Shared Helpers (utility functions)
+- Profile Management (profile CRUD, loading/saving)
+- Settings (configuration handling)
+- Site Picker (dialog and list management)
+- Template Management (capture, apply, storage)
+- HTML Export: Permissions and Storage (report generation)
+- PnP: Permissions and Storage Metrics (SharePoint API operations)
+- File Search (advanced file search functionality)
+- Transfer (file/folder transfer operations)
+- Bulk Site Creation (site creation from templates)
+- Internationalization (multi-language support)
+- GUI (main form and controls definition)
+- Event Handlers (button clicks, selections, menu actions)
+- Structure (folder tree CSV parsing)
+
+**Comments:**
+- Inline comments explain non-obvious logic: `# Groups rows that share the same Users + Permissions`
+- Block comments precede major sections: `# -- Top bar --`, `# -- Site list (ListView with columns) --`
+- Section separators use dashes: `# ── Profile Management ─────────────────────────────────`
+- Descriptive comments in complex functions explain algorithm: `# Recursively collects subfolders up to $MaxDepth levels deep`
+- No JSDoc/TSDoc style - pure text comments
+
+## Import Organization
+
+**Module Imports:**
+- `Add-Type -AssemblyName` for .NET assemblies at script start:
+  - `System.Windows.Forms` for UI controls
+  - `System.Drawing` for colors and fonts
+- `Import-Module PnP.PowerShell` dynamically when needed in background runspace blocks
+- No explicit order beyond UI assemblies first
+
+## Error Handling
+
+**Patterns:**
+- Broad `try-catch` blocks with minimal logging: `try { ... } catch {}`
+- Silent error suppression common: empty catch blocks swallow exceptions
+- Explicit error capture in key operations: `catch { $Sync.Error = $_.Exception.Message }`
+- Error logging via `Write-Log` with color coding:
+  - Red for critical failures: `Write-Log "Erreur: $message" "Red"`
+  - Yellow for informational messages: `Write-Log "Processing..." "Yellow"`
+  - DarkGray for skipped items: `Write-Log "Skipped: $reason" "DarkGray"`
+- Exception messages extracted and logged: `$_.Exception.Message`
+- Validation checks return boolean: `if ([string]::IsNullOrWhiteSpace(...)) { return $false }`
+
+## Logging
+
+**Framework:** Native `Write-Log` function + UI RichTextBox display
+
+**Patterns:**
+```powershell
+function Write-Log {
+    param([string]$Message, [string]$Color = "LightGreen")
+    if ($script:LogBox -and !$script:LogBox.IsDisposed) {
+        # Append to UI with timestamp and color
+        $script:LogBox.AppendText("$(Get-Date -Format 'HH:mm:ss') - $Message`n")
+    }
+    Write-Host $Message  # Also output to console
+}
+```
+
+**Logging locations:**
+- Long-running operations log to RichTextBox in real-time via background runspace queue
+- Background functions use custom `BgLog` helper that queues messages: `function BgLog([string]$m, [string]$c="LightGreen")`
+- Colors indicate message type: LightGreen (success), Yellow (info), Cyan (detail), DarkGray (skip), Red (error)
+- Timestamps added automatically: `HH:mm:ss` format
+
+## Validation
+
+**Input Validation:**
+- Null/whitespace checks: `[string]::IsNullOrWhiteSpace($variable)`
+- Array/collection size checks: `$array.Count -gt 0`, `$items -and $items.Count -gt 0`
+- Index bounds validation: `if ($idx -lt 0 -or $idx -ge $array.Count) { return }`
+- UI MessageBox dialogs for user-facing errors: `[System.Windows.Forms.MessageBox]::Show(...)`
+- Function-level validation via `Validate-Inputs` pattern
+
+## String Handling
+
+**HTML Escaping:**
+- Custom `EscHtml` function escapes special characters for HTML generation:
+  ```powershell
+  function EscHtml([string]$s) {
+      return $s -replace '&','&amp;' -replace '<','&lt;' -replace '>','&gt;' -replace '"','&quot;'
+  }
+  ```
+- Applied to all user-supplied data rendered in HTML reports
+
+**String Interpolation:**
+- Double-quoted strings with `$variable` expansion: `"URL: $url"`
+- Format operator for complex strings: `"Template '{0}' saved" -f $name`
+- Localization helper function `T` for i18n strings: `T "profile"`, `T "btn.save"`
+
+## Function Design
+
+**Size:** Functions range from 5-50 lines for utilities, 100+ lines for complex operations
+
+**Parameters:**
+- Explicit type declarations required
+- Optional parameters use default values
+- Switch parameters for boolean flags: `[switch]$IncludeSubsites`
+- Complex objects passed as reference (arrays, hashtables)
+
+**Return Values:**
+- Functions return results or arrays: `return @()`, `return $data`
+- Boolean results for validation: `return $true` / `return $false`
+- PSCustomObject for structured data: `[PSCustomObject]@{ Name = ...; Value = ... }`
+- Void operations often silent or logged
+
+## Object/Struct Patterns
+
+**PSCustomObject for Data:**
+```powershell
+[PSCustomObject]@{
+    name              = "value"
+    clientId          = "value"
+    capturedAt        = (Get-Date -Format 'dd/MM/yyyy HH:mm')
+    options           = @{ structure = $true; permissions = $true }
+}
+```
+
+**Hashtable for Mutable State:**
+```powershell
+$script:_pkl = @{
+    AllSites      = @()
+    CheckedUrls   = [System.Collections.Generic.HashSet[string]]::new()
+    SortCol       = 0
+    SortAsc       = $true
+}
+```
+
+**Synchronized Hashtable for Thread-Safe State:**
+```powershell
+$sync = [hashtable]::Synchronized(@{
+    Done  = $false
+    Error = $null
+    Queue = [System.Collections.Generic.Queue[object]]::new()
+})
+```
+
+## Class/Type Usage
+
+- Minimal custom classes; primarily uses `[PSCustomObject]`
+- Extensive use of .NET types:
+  - `[System.Windows.Forms.*]` for UI controls
+  - `[System.Drawing.Color]` for colors
+  - `[System.Drawing.Font]` for typography
+  - `[System.Drawing.Point]`, `[System.Drawing.Size]` for positioning
+  - `[System.Collections.Generic.HashSet[string]]` for efficient lookups
+  - `[System.Collections.Generic.Queue[object]]` for message queues
+  - `[System.Management.Automation.Runspaces.*]` for background execution
+
+## Date/Time Formatting
+
+**Consistent format:** `dd/MM/yyyy HH:mm` (European format)
+- Used for timestamps in reports and logs
+- Timestamps in logs: `HH:mm:ss`
+- Storage/file metrics: `dd/MM/yyyy HH:mm`
+
+## Performance Patterns
+
+**Batch Operations:**
+- Form updates wrapped in `BeginUpdate()` / `EndUpdate()` to prevent flickering
+- ListView population optimized: clear, populate, sort in batch
+
+**Threading:**
+- Long-running PnP operations execute in separate runspace
+- Main UI thread communicates via synchronized hashtable + timer polling
+- Async UI updates via `Timer` with `DoEvents()` for responsiveness
+
+---
+
+*Convention analysis: 2026-04-02*
--- a/.planning/codebase/INTEGRATIONS.md
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,149 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-02
+
+## APIs & External Services
+
+**SharePoint Online:**
+- Service: Microsoft SharePoint Online (via Microsoft 365)
+- What it's used for: Site management, permission auditing, file search, storage metrics, templating, bulk operations
+  - SDK/Client: PnP.PowerShell module
+  - Auth: Azure AD interactive login (ClientId required)
+  - Connection method: `Connect-PnPOnline -Url <SiteUrl> -Interactive -ClientId <ClientId>`
+  - Search: SharePoint Search API using KQL (keyword query language) via `Submit-PnPSearchQuery`
+
+**Azure AD:**
+- Service: Microsoft Entra ID (formerly Azure Active Directory)
+- What it's used for: User authentication and app registration
+  - SDK/Client: PnP.PowerShell (handles auth flow)
+  - Auth: Interactive browser-based login
+  - App Registration: Required with delegated permissions configured
+  - No service principal or client secret used (interactive auth only)
+
+## Data Storage
+
+**Databases:**
+- None detected - Application uses file-based storage only
+
+**File Storage:**
+- Service: Local filesystem only
+- Connection: Configured data folder for JSON files
+- Client: PowerShell native file I/O
+- Configuration: `Sharepoint_Settings.json` stores dataFolder path
+
+**Caching:**
+- Service: None detected
+- In-memory collections used during session (synchronized hashtables for runspace communication)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Azure AD (Microsoft Entra ID)
+  - Implementation: Interactive browser-based OAuth 2.0 flow
+  - No client secrets or certificates
+  - User must have access to target SharePoint tenant
+  - App registration required with delegated permissions
+
+**Registration Process:**
+- User creates Azure AD App Registration
+- Client ID stored in profile for reuse
+- Helper script available: `Register-PnPEntraIDAppForInteractiveLogin` (via PnP.PowerShell)
+- Result file: Temporary JSON stored in system temp folder, user copies Client ID manually
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- None detected - Errors written to UI log box via `Write-Log` function
+- Location: UI RichTextBox control in application
+
+**Logs:**
+- Approach: In-app console logging
+  - Function: `Write-Log $Message [Color]` writes timestamped messages to UI log box
+  - Colors: LightGreen (default), Red (errors), Yellow (KQL queries), DarkOrange (dry-run operations)
+  - File location: `C:\Users\SebastienQUEROL\Documents\projets\Sharepoint\Sharepoint_ToolBox.ps1` (lines 6-17)
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Not applicable - Desktop application (local execution)
+
+**CI Pipeline:**
+- None detected
+
+**Execution Model:**
+- Direct script execution: `.\Sharepoint_Toolbox.ps1`
+- No installation/setup required beyond PowerShell and PnP.PowerShell module
+
+## Environment Configuration
+
+**Required env vars:**
+- None required - All configuration stored in JSON files
+- User inputs via GUI: Client ID, Tenant URL, Site URL
+
+**Secrets location:**
+- Not applicable - Interactive auth uses no stored secrets
+- User manages Client ID (non-sensitive app identifier)
+- Session credentials handled by Azure AD auth flow (in-memory only)
+
+**Configuration files:**
+- `Sharepoint_Settings.json` - Data folder, language preference
+- `Sharepoint_Export_profiles.json` - Saved connection profiles (Tenant URL, Client ID)
+- `Sharepoint_Templates.json` - Captured site templates
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None detected
+
+**Outgoing:**
+- None detected
+
+## Search & Query Integration
+
+**SharePoint Search API:**
+- Usage: File search across libraries using KQL
+- Location: `Sharepoint_ToolBox.ps1` lines 4744-4773 (search query building)
+- Function: `Submit-PnPSearchQuery -Query $kql`
+- Pagination: Automatic via PnP.PowerShell
+- Client-side filtering: Regex filters applied after results fetched
+- Query example: Supports file extension, name/path patterns, creation/modification date ranges, author filters, max result limits
+
+## Export & Report Formats
+
+**Output Formats:**
+- CSV: PowerShell `Export-Csv` cmdlet (UTF-8 encoding, no type info)
+- HTML: Custom HTML generation with:
+  - Interactive tables (sorting, filtering by column)
+  - Collapsible sections (durable state via CSS/JS)
+  - Charts and metrics visualization
+  - Inline styling (no external CSS file)
+
+**Export Functions:**
+- `Export-PermissionsToHTML` (line 1389)
+- `Export-StorageToHTML` (line 1621)
+- `Export-SearchResultsToHTML` (line 2112)
+- `Export-DuplicatesToHTML` (line 2235)
+- `Export-TransferVerifyToHTML` (line 2412)
+
+## Bulk Import Formats
+
+**CSV Input:**
+- Bulk member add: Expects columns for site, group, user email
+- Bulk site creation: Site name, alias, owner email, description
+- Bulk file transfer: Source site/path, destination site/path
+- Folder structure: Library name, folder path, permissions
+
+**Parsing:**
+- PowerShell `Import-Csv` - Standard CSV parsing
+- Headers used as property names
+
+## API Rate Limiting
+
+**SharePoint Online:**
+- No explicit rate limiting handling detected
+- Assumes PnP.PowerShell handles throttling internally
+- Pagination used for large result sets (PageSize 2000 for list items)
+
+---
+
+*Integration audit: 2026-04-02*
--- a/.planning/codebase/STACK.md
+++ b/.planning/codebase/STACK.md
@@ -0,0 +1,103 @@
+# Technology Stack
+
+**Analysis Date:** 2026-04-02
+
+## Languages
+
+**Primary:**
+- PowerShell 5.1+ - All application logic, UI, and SharePoint integration
+
+## Runtime
+
+**Environment:**
+- Windows PowerShell 5.1+ or PowerShell Core 7.0+
+- .NET Framework (built-in with PowerShell)
+
+**Execution Model:**
+- Desktop application (WinForms GUI)
+- Synchronous runspace threading for async operations without blocking UI
+
+## Frameworks
+
+**UI:**
+- System.Windows.Forms (native .NET, bundled with PowerShell)
+- System.Drawing (native .NET for graphics and colors)
+
+**SharePoint/Cloud Integration:**
+- PnP.PowerShell (latest version) - All SharePoint Online API interactions
+- Azure AD App Registration for authentication (required)
+
+**Testing:**
+- No dedicated test framework detected (manual testing assumed)
+
+**Build/Dev:**
+- No build system (single .ps1 script file executed directly)
+
+## Key Dependencies
+
+**Critical:**
+- PnP.PowerShell - Required for all SharePoint Online operations
+  - Location: Installed via `Install-Module PnP.PowerShell`
+  - Used for: Site enumeration, permissions scanning, storage metrics, file search, templating, bulk operations
+  - Connection: Interactive authentication via Azure AD App (ClientId required)
+
+**Infrastructure:**
+- System.Windows.Forms - Desktop UI framework
+- System.Drawing - UI graphics and rendering
+- Microsoft.SharePoint.Client - Underlying SharePoint CSOM (via PnP.PowerShell)
+
+## Configuration
+
+**Environment:**
+- `Sharepoint_Settings.json` - User preferences (data folder location, language)
+- `Sharepoint_Export_profiles.json` - Saved connection profiles (Tenant URL, Client ID)
+- `Sharepoint_Templates.json` - Site structure templates (captured and reapplied)
+
+**Build:**
+- Single executable: `Sharepoint_ToolBox.ps1`
+- Launched directly: `.\Sharepoint_Toolbox.ps1`
+
+**Localization:**
+- File: `lang/fr.json` - French translations
+- Default: English (en)
+- Loaded dynamically at runtime
+
+## Platform Requirements
+
+**Development:**
+- Windows Operating System (WinForms is Windows-only)
+- PowerShell 5.1+
+- Internet connection for Azure AD authentication
+- Access to SharePoint Online tenant
+
+**Production:**
+- Windows 10/11 (or Windows Server 2016+)
+- PowerShell 5.1 minimum
+- Azure AD tenant with properly configured app registration
+- Network access to target SharePoint Online sites
+
+## Data Persistence
+
+**Local Storage:**
+- JSON files in configurable data folder (default: `Sharepoint_Export_profiles.json`, `Sharepoint_Templates.json`, `Sharepoint_Settings.json`)
+- CSV exports of reports and bulk operation results
+- HTML reports with interactive UI
+
+**No external databases** - All storage is file-based and local
+
+## Authentication
+
+**Method:**
+- Azure AD Interactive Login (user-initiated browser-based auth)
+- Client ID (App Registration ID) required
+- No client secrets or certificates (interactive auth flow only)
+- PnP.PowerShell handles Azure AD token acquisition
+
+## Known Versions
+
+- PowerShell: 5.1 (minimum requirement stated in README)
+- PnP.PowerShell: Not pinned (latest version recommended)
+
+---
+
+*Stack analysis: 2026-04-02*
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,249 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-02
+
+## Directory Layout
+
+```
+Sharepoint-Toolbox/
+├── .planning/                          # GSD planning documentation
+├── .git/                               # Git repository
+├── .gitea/                             # Gitea configuration
+├── .claude/                            # Claude IDE configuration
+├── examples/                           # CSV example files for bulk operations
+│   ├── bulk_add_members.csv            # Template: add users to groups
+│   ├── bulk_create_sites.csv           # Template: create multiple sites
+│   ├── bulk_transfer.csv               # Template: transfer site ownership
+│   └── folder_structure.csv            # Template: create folder hierarchies
+├── lang/                               # Language/localization files
+│   └── fr.json                         # French language translations
+├── Sharepoint_ToolBox.ps1              # Main application (6408 lines)
+├── Sharepoint_Settings.json            # User settings (data folder, language preference)
+├── Sharepoint_Export_profiles.json     # Saved connection profiles (generated at runtime)
+├── Sharepoint_Templates.json           # Saved site templates (generated at runtime)
+├── README.md                           # Documentation and feature overview
+├── TODO.md                             # Future feature roadmap
+└── SPToolbox-logo.png                  # Application logo
+```
+
+## Directory Purposes
+
+**`examples/`:**
+- Purpose: Reference CSV templates for bulk operations
+- Contains: CSV example files demonstrating column structure for bulk tasks
+- Key files:
+  - `bulk_add_members.csv`: User email and group name mappings
+  - `bulk_create_sites.csv`: Site title, URL, type, language
+  - `bulk_transfer.csv`: Source site, target owner email
+  - `folder_structure.csv`: Folder paths to create under libraries
+- Non-versioned: May contain user data after operations
+- Access: Referenced by bulk operation dialogs; templates shown in UI
+
+**`lang/`:**
+- Purpose: Store language packs for UI localization
+- Contains: JSON files with key-value pairs for UI text
+- Key files:
+  - `fr.json`: Complete French translations for all UI elements, buttons, messages
+- Naming: `<language-code>.json` (e.g., `en.json`, `fr.json`)
+- Loading: `Load-Language` function (line 2933) reads and caches translation dict
+- Integration: `T("key")` function (line 2908) looks up translations at runtime
+
+**`.planning/`:**
+- Purpose: GSD (GitHub Sync & Deploy) planning and analysis documents
+- Contains: Generated documentation for architecture, structure, conventions, concerns
+- Generated: By GSD mapping tools; not manually edited
+- Committed: Yes, tracked in version control
+
+## Key File Locations
+
+**Entry Points:**
+
+- `Sharepoint_ToolBox.ps1` (lines 1-6408): Single monolithic PowerShell script
+  - Execution: `.ps1` file run directly or sourced from PowerShell ISE/terminal
+  - Initialization: Lines 6386-6408 load settings, language, profiles, then show main form
+  - Exit: Triggered by form close or exception; automatic cleanup of runspaces
+
+- Main GUI Form instantiation: `Sharepoint_ToolBox.ps1` line 2992
+  - Creates WinForms.Form object
+  - Registers all event handlers
+  - Shows dialog via `[void]$form.ShowDialog()` at line 6405
+
+**Configuration:**
+
+- `Sharepoint_Settings.json`: User preferences
+  - Structure: `{ "dataFolder": "...", "lang": "en" }`
+  - Loaded by: `Load-Settings` (line 136)
+  - Saved by: `Save-Settings` (line 147)
+  - Auto-created: If missing, defaults to English + script root directory
+
+- `Sharepoint_Export_profiles.json`: Connection profiles (auto-created)
+  - Structure: `{ "profiles": [ { "name": "Prod", "clientId": "...", "tenantUrl": "..." }, ... ] }`
+  - Loaded by: `Load-Profiles` (line 57)
+  - Saved by: `Save-Profiles` (line 68)
+  - Location: Determined by `Get-ProfilesFilePath` (line 50) - same as settings
+
+- `Sharepoint_Templates.json`: Captured site templates (auto-created)
+  - Structure: `{ "templates": [ { "name": "...", "libraries": [...], "groups": [...], ... }, ... ] }`
+  - Loaded by: `Load-Templates` (line 484)
+  - Saved by: `Save-Templates` (line 495)
+  - Location: Same folder as profiles/settings
+
+**Core Logic:**
+
+- Permissions Report: `Sharepoint_ToolBox.ps1` lines 1784-2001
+  - `Generate-PnPSitePermissionRpt` (line 1852): Main permission scanning function
+  - `Get-PnPWebPermission` (line 1944): Recursive site/subsite scanning
+  - `Get-PnPListPermission` (line 1912): Library and list enumeration
+  - `Get-PnPFolderPermission` (line 1882): Folder-level permission scanning
+  - `Get-PnPPermissions` (line 1786): Individual role assignment extraction
+
+- Storage Metrics: `Sharepoint_ToolBox.ps1` lines 2002-2110
+  - `Get-SiteStorageMetrics` (line 2004): Main storage scan function
+  - Nested `Collect-FolderStorage` (line 2010): Recursive folder traversal
+  - Nested `Collect-WebStorage` (line 2034): Per-web storage collection
+
+- File Search: `Sharepoint_ToolBox.ps1` lines 2112-2233
+  - Search API integration via PnP.PowerShell
+  - KQL (Keyword Query Language) filter construction
+  - Client-side regex filtering after API retrieval
+
+- Template Management: `Sharepoint_ToolBox.ps1` lines 475-1360
+  - `Show-TemplateManager` (line 542): Template dialog
+  - Capture state machine in dialog event handlers
+  - Template persistence via JSON serialization
+
+- Duplicate Detection: `Sharepoint_ToolBox.ps1` lines 2235-2408
+  - File mode: Search API with grouping by filename
+  - Folder mode: Direct library enumeration + comparison
+  - HTML export with grouped UI
+
+**Testing:**
+
+- No automated test framework present
+- Manual testing via GUI interaction
+- Examples folder (`examples/`) provides test data templates
+
+**Localization:**
+
+- `lang/fr.json`: French translations
+  - Format: JSON object with `"_name"` and `"_code"` metadata + translation keys
+  - Loading: `Load-Language` (line 2933) parses JSON into `$script:LangDict`
+  - Usage: `T("key")` replaces hardcoded English strings with translations
+  - UI Update: `Update-UILanguage` (line 2951) updates all registered controls
+
+## Naming Conventions
+
+**Files:**
+
+- Main application: `Sharepoint_ToolBox.ps1` (PascalCase with underscore separator)
+- Settings/data: `Sharepoint_<Type>.json` (e.g., `Sharepoint_Settings.json`)
+- Generated exports: `<Report>_<site>_<timestamp>.<format>` or `<Report>_<mode>_<timestamp>.<format>`
+  - Permissions: `Permissions_<site>_<yyyyMMdd_HHmmss>.csv/html`
+  - Storage: `Storage_<site>_<yyyyMMdd_HHmmss>.csv/html`
+  - Search: `FileSearch_<yyyyMMdd_HHmmss>.csv/html`
+  - Duplicates: `Duplicates_<mode>_<yyyyMMdd_HHmmss>.csv/html`
+- Language files: `<language-code>.json` (lowercase, e.g., `fr.json`)
+- Example files: `<operation>_<type>.csv` (lowercase with underscore, e.g., `bulk_add_members.csv`)
+
+**PowerShell Functions:**
+
+- Public functions: `Verb-Noun` naming (e.g., `Generate-PnPSitePermissionRpt`, `Get-SiteStorageMetrics`)
+- Private/internal functions: Prefixed with `_` or grouped in regions (e.g., `_Pkl-Sort`, `_Pkl-Repopulate`)
+- Event handlers: Declared inline in `.Add_Click` or `.Add_TextChanged` blocks; not named separately
+- Nested functions (inside others): CamelCase with parent context (e.g., `Collect-FolderStorage` inside `Get-SiteStorageMetrics`)
+
+**Variables:**
+
+- Script-scope state: `$script:<name>` (e.g., `$script:AllPermissions`, `$script:DataFolder`)
+- Local function scope: camelCase (e.g., `$result`, `$dlg`, `$lists`)
+- Control references: descriptive with type suffix (e.g., `$txtClientId`, `$btnPermRun`, `$cboProfile`)
+- Control variables stored in script scope: Prefixed `$script:` for access across event handlers
+- Temporary arrays: `$<plural>` (e.g., `$sites`, `$folders`, `$results`)
+
+**Types:**
+
+- Region markers: `#region ===== <Name> =====` (e.g., `#region ===== GUI =====`)
+- Comments: Double hash for section comments (e.g., `# ── Label helper ──`)
+
+**Exports:**
+
+- HTML: Class names like `permission-table`, `storage-tree`, `duplicate-group`
+- CSV: Column headers match object property names (e.g., `Title`, `URL`, `Permissions`)
+
+## Where to Add New Code
+
+**New Feature:**
+
+1. Create a new region section in `Sharepoint_ToolBox.ps1`:
+   ```powershell
+   #region ===== [Feature Name] =====
+   function [Verb]-[Feature](...) { ... }
+   #endregion
+   ```
+
+2. Primary code locations:
+   - Core logic: After line 2408 (after duplicates region, before Transfer region)
+   - PnP interaction: Own `#region` mirroring storage/permissions pattern
+   - HTML export helper: Create function like `Export-[Feature]ToHTML` in dedicated region
+
+3. Add UI tab or button:
+   - Create new TabPage in `$tabs` (around line 3113+)
+   - Register event handler for execution button in Event Handlers region (line 4068+)
+   - Add label in French translation file (`lang/fr.json`)
+
+4. Add menu item if needed:
+   - Modify MenuStrip construction around line 3001-3027
+   - Register handler in Event Handlers region
+
+5. Persist settings:
+   - Add properties to `Sharepoint_Settings.json` structure
+   - Update `Load-Settings` (line 136) to include new fields
+   - Update `Save-Settings` (line 147) to serialize new fields
+
+**New Component/Module:**
+
+- Keep as internal functions (no separate files)
+- If complexity exceeds 500 lines, consider refactoring into regions
+- Pattern: All code stays in single `Sharepoint_ToolBox.ps1` file
+- Dependencies: Use script-scope variables for shared state
+
+**Utilities:**
+
+- Shared helpers: `Shared Helpers` region (line 4-46)
+  - Add new helper function here if used by multiple features
+  - Examples: `Write-Log`, `Format-Bytes`, `EscHtml`, `Validate-Inputs`
+
+- UI control factories: Lines 3119-3146
+  - Add new `New-<Control>` helper for frequently used UI patterns
+  - Examples: `New-Group`, `New-Check`, `New-Radio`, `New-ActionBtn`
+
+- Internationalization: `Internationalization` region (line 2732-2989)
+  - Add new translation keys to `lang/fr.json`
+  - Update `T()` function if new resolution logic needed
+
+## Special Directories
+
+**`examples/`:**
+- Purpose: CSV templates for user reference
+- Generated: No; committed as examples
+- Committed: Yes, tracked in version control
+- Accessed by: Bulk operation dialogs (not directly imported by code; users download manually)
+- Content: Non-executable; user-facing documentation
+
+**`.planning/`:**
+- Purpose: GSD-generated codebase analysis and planning documents
+- Generated: Yes; created by GSD mapping tools during `/gsd:map-codebase`
+- Committed: Yes; documents are version-controlled
+- Accessed by: `/gsd:plan-phase` and `/gsd:execute-phase` commands for context
+- Content: Markdown documents describing architecture, structure, conventions, concerns, stack, integrations
+
+**Generated Files (Runtime):**
+
+Files created at runtime, not part of initial repository:
+- `Sharepoint_Export_profiles.json`: User-created connection profiles
+- `Sharepoint_Templates.json`: User-captured site templates
+- Export reports: `*_<timestamp>.(csv|html)` files in output folder (default: script root or user-selected)
+
+---
+
+*Structure analysis: 2026-04-02*
--- a/.planning/codebase/TESTING.md
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,256 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-04-02
+
+## Test Framework
+
+**Status:** No automated testing framework detected
+
+**Infrastructure:** Not applicable
+- No test runner (Jest, Vitest, Pester)
+- No test configuration files
+- No test suite in codebase
+- No CI/CD pipeline test stage configured
+
+## Testing Approach
+
+**Current Testing Model:** Manual testing via GUI
+
+**Test Methods:**
+- **GUI Testing:** All functionality tested through WinForms UI
+  - Manual interaction with controls and dialogs
+  - Visual verification of results in generated reports
+  - Log output observation in RichTextBox
+- **Report Validation:** HTML and CSV exports manually reviewed for correctness
+- **API Integration:** Manual testing of PnP.PowerShell operations against live SharePoint tenant
+- **Regression Testing:** Ad-hoc manual verification of features after changes
+
+## Code Organization for Testing
+
+**Testability Patterns:** Limited
+
+The monolithic single-file architecture (`Sharepoint_ToolBox.ps1` at 6408 lines) makes isolated unit testing challenging. Key observations:
+
+**Tight Coupling to UI:**
+- Core business logic embedded in event handlers
+- Heavy reliance on global `$script:` scope for state
+- Example: `Load-Profiles` reads from `Get-ProfilesFilePath`, which is file-system dependent
+- Site picker functionality (`Show-SitePicker`) spawns background runspace but depends on form being instantiated
+
+**Hard Dependencies:**
+- PnP.PowerShell module imported dynamically in background runspace blocks
+- File system access (profiles, templates, settings) not abstracted
+- SharePoint connection state implicit in PnP connection context
+
+**Areas with Better Isolation:**
+- Pure utility functions like `Format-Bytes`, `EscHtml` could be unit tested
+- Data transformation functions like `Merge-PermissionRows` accept input arrays and return structured output
+- HTML generation in `Export-PermissionsToHTML` and `Export-StorageToHTML` could be tested against expected markup
+
+## Background Runspace Pattern
+
+**Async Execution Model:**
+Most long-running operations execute in separate PowerShell runspace to prevent UI blocking:
+
+```powershell
+# 1. Create synchronized hashtable for communication
+$sync = [hashtable]::Synchronized(@{
+    Done   = $false
+    Error  = $null
+    Result = $null
+    Queue  = [System.Collections.Generic.Queue[object]]::new()
+})
+
+# 2. Define background script block (has access to passed parameters only)
+$bgScript = {
+    param($Url, $ClientId, $Sync)
+    try {
+        Import-Module PnP.PowerShell -ErrorAction Stop
+        Connect-PnPOnline -Url $Url -Interactive -ClientId $ClientId
+        # Perform work
+        $Sync.Result = $data
+    } catch {
+        $Sync.Error = $_.Exception.Message
+    } finally {
+        $Sync.Done = $true
+    }
+}
+
+# 3. Launch in runspace
+$rs = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspace()
+$rs.ApartmentState = "STA"; $rs.ThreadOptions = "ReuseThread"; $rs.Open()
+$ps = [System.Management.Automation.PowerShell]::Create()
+$ps.Runspace = $rs
+[void]$ps.AddScript($bgScript)
+[void]$ps.AddArgument($url)
+$hnd = $ps.BeginInvoke()
+
+# 4. Poll completion with timer
+$tmr = New-Object System.Windows.Forms.Timer
+$tmr.Interval = 300
+$tmr.Add_Tick({
+    if ($sync.Done) {
+        [void]$ps.EndInvoke($hnd)
+        $rs.Close(); $rs.Dispose()
+        # Update UI with $sync.Result
+    }
+})
+$tmr.Start()
+```
+
+**Used for:**
+- Site picker loading: `Show-SitePicker` (lines 212-471)
+- Template capture: Background job in template manager (lines 900+)
+- Site creation: Background job in bulk creation (lines 1134+)
+- Permission/storage export: Operations triggered from event handlers
+- File search: Background search execution
+
+## Message Queue Pattern
+
+**For logging from background runspaces:**
+
+```powershell
+# Background function enqueues messages
+function BgLog([string]$m, [string]$c="LightGreen") {
+    $Sync.Queue.Enqueue([PSCustomObject]@{ Text=$m; Color=$c })
+}
+
+# Main thread timer dequeues and displays
+$tmr.Add_Tick({
+    while ($sync.Queue.Count -gt 0) {
+        $msg = $sync.Queue.Dequeue()
+        _Tpl-Log -Box $textBox -Msg $msg.Text -Color $msg.Color
+    }
+})
+```
+
+**Rationale:** Avoids cross-thread UI access violations by queueing messages from worker thread.
+
+## Common Testing Patterns in Code
+
+**Null/Existence Checks:**
+```powershell
+# Before using objects
+if ($script:LogBox -and !$script:LogBox.IsDisposed) { ... }
+if ($data -and $data.Count -gt 0) { ... }
+if ([string]::IsNullOrWhiteSpace($value)) { return $false }
+```
+
+**Error Logging in Loops:**
+```powershell
+# Catch errors in data processing, log, continue
+foreach ($item in $items) {
+    try {
+        # Process item
+    } catch { 
+        BgLog "  Skipped: $($_.Exception.Message)" "DarkGray" 
+    }
+}
+```
+
+**Validation Before Operations:**
+```powershell
+function Validate-Inputs {
+    if ([string]::IsNullOrWhiteSpace($script:txtClientId.Text)) {
+        [System.Windows.Forms.MessageBox]::Show(...)
+        return $false
+    }
+    return $true
+}
+
+# Called before starting long operations
+if (-not (Validate-Inputs)) { return }
+```
+
+## Data Flow Testing Approach
+
+**For Feature Development:**
+
+1. **Manual Test Cases** (observed pattern, not formalized):
+   - Permissions Export:
+     - Select site with multiple libraries
+     - Choose CSV format
+     - Verify CSV contains all libraries and permissions
+     - Test HTML format in browser for interactivity
+   
+   - Storage Metrics:
+     - Run with `PerLibrary` flag
+     - Verify folder hierarchy is captured
+     - Test recursive subsite inclusion
+     - Validate byte calculations
+   
+   - Template Capture/Apply:
+     - Capture from source site
+     - Verify JSON structure
+     - Create new site from template
+     - Verify structure, permissions, settings applied
+   
+   - File Search:
+     - Test regex patterns
+     - Verify date filtering
+     - Test large result sets (pagination)
+     - Check CSV/HTML output
+
+2. **Visual Verification:**
+   - Log output reviewed in RichTextBox for progress
+   - Generated HTML reports tested in multiple browsers
+   - CSV files opened in Excel for format verification
+
+## Fragility Points & Testing Considerations
+
+**PnP Connection Management:**
+- No connection pooling; each operation may create new connection
+- Interactive auth prompt appears per runspace
+- **Risk:** Auth failures not consistently handled
+- **Testing Need:** Mock PnP module or use test tenant
+
+**HTML Generation:**
+- String concatenation for large HTML documents (lines 1475+)
+- Inline CSS for styling
+- JavaScript for interactivity
+- **Risk:** Complex HTML fragments prone to markup errors
+- **Testing Need:** Validate HTML structure and JavaScript functionality
+
+**JSON Persistence:**
+- Profiles, templates, settings stored in JSON
+- ConvertTo-Json/-From-Json without depth specification can truncate
+- **Risk:** Nested objects may not round-trip correctly
+- **Testing Need:** Validate all object types persist/restore
+
+**Background Runspace Cleanup:**
+- Runspace and PowerShell objects must be disposed
+- Timer must be stopped and disposed
+- **Risk:** Resource leaks if exception occurs before cleanup
+- **Testing Need:** Verify cleanup in error paths
+
+## Suggested Testing Improvements
+
+**Unit Testing:**
+1. Extract pure functions (no UI/file system dependencies)
+   - `Format-Bytes`, `EscHtml`, `Merge-PermissionRows`
+   - HTML generation functions
+   
+2. Use Pester framework for PowerShell unit tests:
+   ```powershell
+   Describe "Format-Bytes" {
+       It "Formats bytes to GB" {
+           Format-Bytes (1GB * 2) | Should -Be "2 GB"
+       }
+   }
+   ```
+
+3. Mock file system and PnP operations for integration tests
+
+**Integration Testing:**
+1. Use test SharePoint tenant for functional testing
+2. Automate report generation and validation
+3. Script common user workflows
+
+**Regression Testing:**
+1. Maintain test suite of sites with known structures
+2. Generate reports, compare outputs
+3. Run before major releases
+
+---
+
+*Testing analysis: 2026-04-02*