diff --git a/.planning/10-CONTEXT.md b/.planning/10-CONTEXT.md new file mode 100644 index 0000000..14cdf55 --- /dev/null +++ b/.planning/10-CONTEXT.md @@ -0,0 +1,79 @@ +--- +phase: 10 +title: Branding Data Foundation +status: ready-for-planning +created: 2026-04-08 +--- + +# Phase 10 Context: Branding Data Foundation + +## Decided Areas (from prior research + STATE.md) + +These are locked — do not re-litigate during planning or execution. + +| Decision | Value | +|---|---| +| Logo storage format | Base64 strings in JSON (not file paths) | +| MSP logo location | `BrandingSettings.cs` model → `branding.json` | +| Client logo location | On `TenantProfile` model (per-tenant) | +| File path after import | Discarded — only base64 persists | +| SVG support | Rejected (XSS risk) — PNG/JPG only | +| User directory service | New `GraphUserDirectoryService`, separate from `GraphUserSearchService` | +| Directory auto-load | No — explicit "Load Directory" button required | +| New NuGet packages | None — existing stack covers everything | +| Export service signature | Optional `ReportBranding? branding = null` parameter on existing export methods | + +## Discussed Areas + +### 1. Logo Metadata Model + +**Decision:** Store base64 + MIME type as separate fields in a shared `LogoData` record. + +- Shared model: `LogoData { string Base64, string MimeType }` — used by both MSP logo (in `BrandingSettings`) and client logo (on `TenantProfile`) +- `MimeType` is `"image/png"` or `"image/jpeg"`, determined at import time from magic bytes +- No other metadata stored — no original filename, dimensions, or import date +- Export services concatenate `data:{MimeType};base64,{Base64}` for HTML `` tags +- WPF preview converts `Base64` bytes to `BitmapImage` directly + +### 2. Logo Validation & Compression + +**Decision:** Validate format via magic bytes, auto-compress oversized files silently. + +- **Format detection:** Read file header magic bytes only — ignore file extension entirely + - PNG signature: `89 50 4E 47` (first 4 bytes) + - JPEG signature: `FF D8 FF` (first 3 bytes) + - Anything else → reject with specific error message (e.g., "File format is BMP, only PNG and JPG are accepted") +- **Size handling:** If file exceeds 512 KB, auto-compress silently (no user notification) + - Strategy: resize dimensions (e.g., max 300px width/height) + reduce quality + - Keep original format — PNG stays PNG, JPEG stays JPEG (no format conversion) + - Compress until under 512 KB +- **Dimension limits:** None — the 512 KB cap and compression handle naturally +- **Validation errors:** Specific messages for format rejection (format-related only, since size is auto-handled) + +### 3. Profile Deletion & Duplication Behavior + +**Decision:** Warn about logo loss on deletion; do NOT copy logo on duplication. + +- **Deletion:** When deleting a tenant profile that has a client logo, the confirmation message explicitly mentions it: "This will also remove its client logo." The logo is embedded in the profile JSON, so deletion is automatic — no orphaned files. +- **Duplication:** Duplicating a tenant profile copies connection fields (Name, TenantUrl, ClientId) but starts with a blank client logo. The user must re-import or auto-pull for the new profile. Rationale: duplicated profiles are typically for different tenants, so the logo shouldn't carry over. + +## Deferred Ideas (out of scope for Phase 10) + +- Logo preview in Settings UI (Phase 12) +- Auto-pull client logo from Entra branding API (Phase 11/12) +- Report header layout with logos side-by-side (Phase 11) +- "Load Directory" button placement decision (Phase 14) +- Session-scoped directory cache (UDIR-F01, deferred) + +## code_context + +| Asset | Path | Reuse | +|---|---|---| +| TenantProfile model | `SharepointToolbox/Core/Models/TenantProfile.cs` | Extend with `LogoData? ClientLogo` property | +| AppSettings model | `SharepointToolbox/Core/Models/AppSettings.cs` | Reference for BrandingSettings pattern | +| SettingsRepository | `SharepointToolbox/Infrastructure/Persistence/SettingsRepository.cs` | Clone pattern for BrandingRepository (write-then-replace + SemaphoreSlim) | +| ProfileRepository | `SharepointToolbox/Infrastructure/Persistence/ProfileRepository.cs` | Already handles TenantProfile persistence — will serialize new logo field | +| GraphUserSearchService | `SharepointToolbox/Services/GraphUserSearchService.cs` | Reference for Graph SDK usage, auth, and query patterns | +| GraphClientFactory | `SharepointToolbox/Infrastructure/Auth/GraphClientFactory.cs` | Provides `GraphServiceClient` for new directory service | +| DI registration | `SharepointToolbox/App.xaml.cs` (lines 73-163) | Register new BrandingRepository, BrandingService, GraphUserDirectoryService | +| Profile deletion UI | `SharepointToolbox/ViewModels/ProfileManagementViewModel.cs` | Update deletion confirmation message to mention logo | diff --git a/.planning/phases/10-branding-data-foundation/10-CONTEXT.md b/.planning/phases/10-branding-data-foundation/10-CONTEXT.md new file mode 100644 index 0000000..14cdf55 --- /dev/null +++ b/.planning/phases/10-branding-data-foundation/10-CONTEXT.md @@ -0,0 +1,79 @@ +--- +phase: 10 +title: Branding Data Foundation +status: ready-for-planning +created: 2026-04-08 +--- + +# Phase 10 Context: Branding Data Foundation + +## Decided Areas (from prior research + STATE.md) + +These are locked — do not re-litigate during planning or execution. + +| Decision | Value | +|---|---| +| Logo storage format | Base64 strings in JSON (not file paths) | +| MSP logo location | `BrandingSettings.cs` model → `branding.json` | +| Client logo location | On `TenantProfile` model (per-tenant) | +| File path after import | Discarded — only base64 persists | +| SVG support | Rejected (XSS risk) — PNG/JPG only | +| User directory service | New `GraphUserDirectoryService`, separate from `GraphUserSearchService` | +| Directory auto-load | No — explicit "Load Directory" button required | +| New NuGet packages | None — existing stack covers everything | +| Export service signature | Optional `ReportBranding? branding = null` parameter on existing export methods | + +## Discussed Areas + +### 1. Logo Metadata Model + +**Decision:** Store base64 + MIME type as separate fields in a shared `LogoData` record. + +- Shared model: `LogoData { string Base64, string MimeType }` — used by both MSP logo (in `BrandingSettings`) and client logo (on `TenantProfile`) +- `MimeType` is `"image/png"` or `"image/jpeg"`, determined at import time from magic bytes +- No other metadata stored — no original filename, dimensions, or import date +- Export services concatenate `data:{MimeType};base64,{Base64}` for HTML `` tags +- WPF preview converts `Base64` bytes to `BitmapImage` directly + +### 2. Logo Validation & Compression + +**Decision:** Validate format via magic bytes, auto-compress oversized files silently. + +- **Format detection:** Read file header magic bytes only — ignore file extension entirely + - PNG signature: `89 50 4E 47` (first 4 bytes) + - JPEG signature: `FF D8 FF` (first 3 bytes) + - Anything else → reject with specific error message (e.g., "File format is BMP, only PNG and JPG are accepted") +- **Size handling:** If file exceeds 512 KB, auto-compress silently (no user notification) + - Strategy: resize dimensions (e.g., max 300px width/height) + reduce quality + - Keep original format — PNG stays PNG, JPEG stays JPEG (no format conversion) + - Compress until under 512 KB +- **Dimension limits:** None — the 512 KB cap and compression handle naturally +- **Validation errors:** Specific messages for format rejection (format-related only, since size is auto-handled) + +### 3. Profile Deletion & Duplication Behavior + +**Decision:** Warn about logo loss on deletion; do NOT copy logo on duplication. + +- **Deletion:** When deleting a tenant profile that has a client logo, the confirmation message explicitly mentions it: "This will also remove its client logo." The logo is embedded in the profile JSON, so deletion is automatic — no orphaned files. +- **Duplication:** Duplicating a tenant profile copies connection fields (Name, TenantUrl, ClientId) but starts with a blank client logo. The user must re-import or auto-pull for the new profile. Rationale: duplicated profiles are typically for different tenants, so the logo shouldn't carry over. + +## Deferred Ideas (out of scope for Phase 10) + +- Logo preview in Settings UI (Phase 12) +- Auto-pull client logo from Entra branding API (Phase 11/12) +- Report header layout with logos side-by-side (Phase 11) +- "Load Directory" button placement decision (Phase 14) +- Session-scoped directory cache (UDIR-F01, deferred) + +## code_context + +| Asset | Path | Reuse | +|---|---|---| +| TenantProfile model | `SharepointToolbox/Core/Models/TenantProfile.cs` | Extend with `LogoData? ClientLogo` property | +| AppSettings model | `SharepointToolbox/Core/Models/AppSettings.cs` | Reference for BrandingSettings pattern | +| SettingsRepository | `SharepointToolbox/Infrastructure/Persistence/SettingsRepository.cs` | Clone pattern for BrandingRepository (write-then-replace + SemaphoreSlim) | +| ProfileRepository | `SharepointToolbox/Infrastructure/Persistence/ProfileRepository.cs` | Already handles TenantProfile persistence — will serialize new logo field | +| GraphUserSearchService | `SharepointToolbox/Services/GraphUserSearchService.cs` | Reference for Graph SDK usage, auth, and query patterns | +| GraphClientFactory | `SharepointToolbox/Infrastructure/Auth/GraphClientFactory.cs` | Provides `GraphServiceClient` for new directory service | +| DI registration | `SharepointToolbox/App.xaml.cs` (lines 73-163) | Register new BrandingRepository, BrandingService, GraphUserDirectoryService | +| Profile deletion UI | `SharepointToolbox/ViewModels/ProfileManagementViewModel.cs` | Update deletion confirmation message to mention logo | diff --git a/.planning/phases/10-branding-data-foundation/10-VALIDATION.md b/.planning/phases/10-branding-data-foundation/10-VALIDATION.md new file mode 100644 index 0000000..e228370 --- /dev/null +++ b/.planning/phases/10-branding-data-foundation/10-VALIDATION.md @@ -0,0 +1,79 @@ +--- +phase: 10 +slug: branding-data-foundation +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-04-08 +--- + +# Phase 10 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | xUnit 2.9.3 + Moq 4.20.72 | +| **Config file** | `SharepointToolbox.Tests/SharepointToolbox.Tests.csproj` | +| **Quick run command** | `dotnet test --filter "Category=Unit" --no-build` | +| **Full suite command** | `dotnet test` | +| **Estimated runtime** | ~15 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `dotnet test --filter "Category=Unit" --no-build` +- **After every plan wave:** Run `dotnet test` +- **Before `/gsd:verify-work`:** Full suite must be green +- **Max feedback latency:** 15 seconds + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|-----------|-------------------|-------------|--------| +| 10-01-01 | 01 | 1 | BRAND-01 | unit | `dotnet test --filter "FullyQualifiedName~BrandingRepositoryTests" --no-build` | ❌ W0 | ⬜ pending | +| 10-01-02 | 01 | 1 | BRAND-06 | unit | `dotnet test --filter "FullyQualifiedName~BrandingServiceTests" --no-build` | ❌ W0 | ⬜ pending | +| 10-01-03 | 01 | 1 | BRAND-03 | unit | `dotnet test --filter "FullyQualifiedName~ProfileServiceTests" --no-build` | ✅ extend | ⬜ pending | +| 10-02-01 | 02 | 1 | UDIR-02 | unit | `dotnet test --filter "FullyQualifiedName~GraphUserDirectoryServiceTests" --no-build` | ❌ W0 | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `SharepointToolbox.Tests/Services/BrandingRepositoryTests.cs` — stubs for BRAND-01 persistence round-trip +- [ ] `SharepointToolbox.Tests/Services/BrandingServiceTests.cs` — stubs for BRAND-06 magic bytes, compression, rejection +- [ ] `SharepointToolbox.Tests/Services/GraphUserDirectoryServiceTests.cs` — stubs for UDIR-02 pagination +- [ ] Extend `SharepointToolbox.Tests/Services/ProfileServiceTests.cs` — add BRAND-03 `ClientLogo` round-trip test + +*Existing infrastructure covers test framework setup.* + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| MSP logo survives app restart | BRAND-01 | Requires full app lifecycle (start, import, close, reopen) | 1. Run app, import MSP logo 2. Close app 3. Reopen app 4. Verify logo still present in branding.json | +| Client logo isolated between tenants | BRAND-03 | Requires multi-profile JSON inspection | 1. Import logo for Tenant A 2. Verify Tenant B profile has no logo field 3. Delete Tenant A logo 4. Verify Tenant B unaffected | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` verify or Wave 0 dependencies +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 15s +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending