# Roadmap: SharePoint Toolbox v2

## Overview

A full C#/WPF rewrite of a 6,400-line PowerShell-based SharePoint Online administration tool. The
project delivers a self-contained Windows desktop application that lets MSP administrators audit
and manage permissions, storage, and site provisioning across multiple client tenants from a single
tool. Foundation infrastructure (multi-tenant auth, async patterns, error handling, DI) must be
solid before any feature work begins — all 10 identified pitfalls in the existing codebase map
entirely to Phase 1. Subsequent phases deliver complete, verifiable feature areas in dependency
order: permissions first (validates auth and pagination), then storage and search (reuse those
patterns), then bulk and provisioning operations (highest write-risk features last), then
hardening and packaging.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation** - WPF shell, multi-tenant auth, DI, async patterns, error handling, logging, localization, JSON persistence (completed 2026-04-02)
- [x] **Phase 2: Permissions** - Permissions scan (single and multi-site), CSV and HTML report export
- [x] **Phase 3: Storage and File Operations** - Storage metrics, file search, and duplicate detection (completed 2026-04-02)
- [ ] **Phase 4: Bulk Operations and Provisioning** - Bulk member/site/transfer operations, site templates, folder structure provisioning
- [ ] **Phase 5: Distribution and Hardening** - Self-contained EXE packaging, end-to-end validation, FR locale completeness

## Phase Details

### Phase 1: Foundation
**Goal**: The application shell runs, users can authenticate to multiple tenants and switch between them without re-logging in, all long-running operations are cancellable and report progress, all errors surface visibly, and the infrastructure patterns that prevent the existing app's 10 known pitfalls are in place before any feature work begins.
**Depends on**: Nothing (first phase)
**Requirements**: FOUND-01, FOUND-02, FOUND-03, FOUND-04, FOUND-05, FOUND-06, FOUND-07, FOUND-08, FOUND-09, FOUND-10, FOUND-12
**Success Criteria** (what must be TRUE):
  1. User can create, rename, delete, and switch between tenant profiles via the UI — each profile stores tenant URL, client ID, and display name in a JSON file
  2. User can authenticate to a tenant via interactive browser login and the session persists across tenant switches without re-entering credentials (MSAL token cache per tenant)
  3. User can see real-time progress on any long-running operation and cancel it mid-execution with a button — the operation stops cleanly with no silent continuation
  4. When any operation fails, the user sees an actionable error message in the UI — no operation fails silently or swallows an exception
  5. UI language switches between English and French dynamically without restarting the application
**Plans**: 8 plans

Plans:
- [ ] 01-01-PLAN.md — Solution scaffold: WPF project + xUnit test project with Generic Host entry point
- [ ] 01-02-PLAN.md — Core layer: models, messages, pagination helper, retry helper, LogPanelSink
- [ ] 01-03-PLAN.md — Persistence layer: ProfileRepository + SettingsRepository + services + unit tests
- [ ] 01-04-PLAN.md — Auth layer: MsalClientFactory + SessionManager + unit tests
- [ ] 01-05-PLAN.md — Localization + Serilog: TranslationSource, EN/FR resx, integration tests
- [ ] 01-06-PLAN.md — ViewModels + WPF shell: FeatureViewModelBase, MainWindow XAML, global exception handlers
- [ ] 01-07-PLAN.md — UI dialogs: ProfileManagementDialog + SettingsView wired into shell
- [ ] 01-08-PLAN.md — Checkpoint: full test suite + visual verification of running application

### Phase 2: Permissions
**Goal**: Users can scan SharePoint permissions on one or many sites and export the results as both a raw CSV and a sortable, filterable HTML report — with no silent failures on large libraries and full control over scan scope.
**Depends on**: Phase 1
**Requirements**: PERM-01, PERM-02, PERM-03, PERM-04, PERM-05, PERM-06, PERM-07
**Success Criteria** (what must be TRUE):
  1. User can select one site or multiple sites and run a permissions scan that returns owners, members, guests, external users, and broken inheritance items
  2. User can choose configurable scan depth and whether to include or exclude inherited permissions before running
  3. User can export the permissions results to a CSV file with all raw permission data
  4. User can export the permissions results to an interactive HTML report where rows are sortable, filterable, and groupable by user
  5. Scanning a library with more than 5,000 items completes successfully — the tool paginates automatically and does not silently truncate or fail
**Plans**: 7 plans

Plans:
- [x] 02-01-PLAN.md — Wave 0: test scaffolds (PermissionsService, ViewModel, classification, CSV, HTML export tests) + PermissionEntryHelper
- [x] 02-02-PLAN.md — Core models + PermissionsService scan engine (PermissionEntry, ScanOptions, IPermissionsService, PermissionsService)
- [x] 02-03-PLAN.md — SiteListService: tenant admin site listing for multi-site picker (ISiteListService, SiteListService, SiteInfo)
- [x] 02-04-PLAN.md — Export services: CsvExportService (with row merging) + HtmlExportService (self-contained HTML)
- [x] 02-05-PLAN.md — Localization: 15 Phase 2 EN/FR keys in Strings.resx, Strings.fr.resx, Strings.Designer.cs
- [x] 02-06-PLAN.md — PermissionsViewModel + SitePickerDialog (XAML + code-behind)
- [x] 02-07-PLAN.md — DI wiring + PermissionsView XAML + MainWindow tab replacement + visual checkpoint

### Phase 3: Storage and File Operations
**Goal**: Users can view and export storage metrics per site and library, search for files across sites using multiple criteria, and detect duplicate files and folders — all with consistent export options and no silent failures on large datasets.
**Depends on**: Phase 2
**Requirements**: STOR-01, STOR-02, STOR-03, STOR-04, STOR-05, SRCH-01, SRCH-02, SRCH-03, SRCH-04, DUPL-01, DUPL-02, DUPL-03
**Success Criteria** (what must be TRUE):
  1. User can view storage consumption per library and per site (with configurable folder depth), including total size, version size, item count, and last modified date
  2. User can export storage metrics to CSV and to an interactive HTML with a collapsible tree view
  3. User can search for files across sites using at least extension, name/regex, date range, creator, and editor as criteria — with a configurable result cap up to 50,000 items
  4. User can export file search results to CSV and to an interactive sortable/filterable HTML
  5. User can scan for duplicate files (by name, size, creation date, modification date) and duplicate folders (by name, subfolder count, file count) and export the results to an HTML with grouped display
**Plans**: 8 plans

Plans:
- [ ] 03-01-PLAN.md — Wave 0: test scaffolds + models (StorageNode, SearchResult, DuplicateGroup/Item, options) + interfaces (IStorageService, ISearchService, IDuplicatesService) + export stubs
- [ ] 03-02-PLAN.md — StorageService: CSOM StorageMetrics scan engine (recursive folder tree, library-level aggregation)
- [ ] 03-03-PLAN.md — Storage export services: StorageCsvExportService + StorageHtmlExportService (collapsible tree HTML)
- [ ] 03-04-PLAN.md — SearchService (KQL pagination, client-side Regex) + DuplicatesService (composite key grouping, CAML folder scan)
- [ ] 03-05-PLAN.md — Search and Duplicate export services: SearchCsvExportService + SearchHtmlExportService + DuplicatesHtmlExportService
- [ ] 03-06-PLAN.md — Localization: all Phase 3 EN/FR keys for Storage, File Search, and Duplicates tabs
- [ ] 03-07-PLAN.md — StorageViewModel + StorageView XAML + DI wiring (Storage tab replaces FeatureTabBase stub)
- [ ] 03-08-PLAN.md — SearchViewModel + SearchView + DuplicatesViewModel + DuplicatesView + DI wiring + visual checkpoint

### Phase 4: Bulk Operations and Provisioning
**Goal**: Users can execute bulk write operations (member additions, site creation, file transfer) with per-item error reporting and cancellation, capture site structures as reusable templates, apply templates to create new sites, and provision folder structures from CSV — all without silent partial failures.
**Depends on**: Phase 3
**Requirements**: BULK-01, BULK-02, BULK-03, BULK-04, BULK-05, TMPL-01, TMPL-02, TMPL-03, TMPL-04, FOLD-01, FOLD-02
**Success Criteria** (what must be TRUE):
  1. User can transfer files and folders between sites with real-time progress tracking and can cancel mid-operation — transferred items are confirmed and failures are reported per-item
  2. User can add members to groups in bulk from a CSV file — each row that fails is reported individually, not silently skipped
  3. User can create multiple sites in bulk from a CSV file with per-site error reporting and mid-operation cancellation
  4. User can capture an existing site's structure (libraries, folders, permission groups, logo, settings) as a named template stored in JSON, then apply that template to create a new Communication or Teams site
  5. User can manage saved templates (create, rename, delete) and create folder structures on a target site from a CSV template
**Plans**: 10 plans

Plans:
- [ ] 04-01-PLAN.md — Dependencies + core models + interfaces + BulkOperationRunner + test scaffolds
- [ ] 04-02-PLAN.md — CsvValidationService + TemplateRepository with unit tests
- [ ] 04-03-PLAN.md — FileTransferService (CSOM MoveCopyUtil, conflict policies)
- [ ] 04-04-PLAN.md — BulkMemberService (Graph SDK batch + CSOM fallback)
- [ ] 04-05-PLAN.md — BulkSiteService (PnP Framework site creation)
- [ ] 04-06-PLAN.md — TemplateService + FolderStructureService
- [ ] 04-07-PLAN.md — Localization + shared dialogs + example CSV resources
- [ ] 04-08-PLAN.md — TransferViewModel + TransferView
- [ ] 04-09-PLAN.md — BulkMembersViewModel + BulkSitesViewModel + FolderStructureViewModel + Views
- [ ] 04-10-PLAN.md — TemplatesViewModel + TemplatesView + DI registration + MainWindow wiring + visual checkpoint

### Phase 5: Distribution and Hardening
**Goal**: The application ships as a single self-contained EXE that runs on a machine with no .NET runtime installed, all previously identified reliability constraints are verified end-to-end (5,000-item pagination, JSON corruption recovery, throttling retry, cancellation), and the French locale is complete and tested.
**Depends on**: Phase 4
**Requirements**: FOUND-11
**Success Criteria** (what must be TRUE):
  1. Running the published EXE on a clean machine with no .NET runtime installed launches the application and all features function correctly
  2. The application recovers gracefully when a SharePoint API call is throttled (429/503) — the user sees a retry progress message and the operation eventually completes or surfaces a clear failure
  3. The French locale is complete for all UI strings — no English fallback text appears when the language is set to French
  4. A scan against a library with more than 5,000 items returns complete, correct results with no silent truncation verified against a known dataset
**Plans**: TBD

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 8/8 | Complete   | 2026-04-02 |
| 2. Permissions | 7/7 | Complete | 2026-04-02 |
| 3. Storage and File Operations | 8/8 | Complete   | 2026-04-02 |
| 4. Bulk Operations and Provisioning | 6/10 | In Progress|  |
| 5. Distribution and Hardening | 0/? | Not started | - |
