ExternalDiskKit.ps1

#Requires -Version 5.1
#Requires -RunAsAdministrator
# README
# ExternalDiskKit — inventory, diagnose, repair, and (optionally) partition/format
# removable disks only. Default is report-only. Not TestDisk, not data recovery,
# not an in-place MBR<->GPT converter. Backup first. Admin required.
#   Get-Help .\ExternalDiskKit.ps1 -Full
#   .\ExternalDiskKit.ps1
#   .\ExternalDiskKit.ps1 -DiskNumber 2 -Diagnose
#   .\ExternalDiskKit.ps1 -DiskNumber 2 -Initialize -Format NTFS -Label BACKUP -WhatIf
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
param(
    [int]$DiskNumber,
    [string]$Serial,
    [string[]]$AllowBusType = @('USB', 'SD', 'MMC', '1394', 'FileBackedVirtual'),
    [switch]$AllowInternalDisks,
    [switch]$Force,
    [string]$LogPath,
    [string]$CsvPath,
    [string]$HtmlPath,
    [switch]$NonInteractive,
    [switch]$IReallyMeanIt,
    [switch]$List,
    [switch]$Diagnose,
    [switch]$Repair,
    [switch]$ClearReadOnly,
    [string]$Letter,
    [switch]$Initialize,
    [ValidateSet('GPT', 'MBR')]
    [string]$PartitionStyle = 'GPT',
    [switch]$CreatePartition,
    [ValidateSet('NTFS', 'exFAT')]
    [string]$Format,
    [string]$Label,
    [int]$AllocationUnitSize,
    [switch]$Clean,
    [switch]$Eject,
    [switch]$Menu,
    [switch]$SelfTest,
    [switch]$UnlockBitLocker,
    [switch]$Gui
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

#region helpers

$script:Bound = @{}
foreach ($boundKey in @($PSBoundParameters.Keys)) {
    $script:Bound[$boundKey] = $PSBoundParameters[$boundKey]
}
$script:EdkCmdlet = $PSCmdlet
$script:ExitCode = 0
$script:TranscriptStarted = $false
$script:InvCulture = [System.Globalization.CultureInfo]::InvariantCulture
$script:InSelfTest = $false
$script:EdkConfirmCallback = $null
$script:EdkSerialCallback = $null
$script:EdkLogCallback = $null
$script:EdkLastVerdict = ''
$script:EdkSkipInitializeDisk = $false
if ($null -eq (Get-Variable -Name EdkSkipMain -Scope Script -ErrorAction SilentlyContinue)) {
    $script:EdkSkipMain = $false
}
# -WhatIf on this script must not leak into Import-Module / Start-Transcript / Get-Disk.
$script:EdkWhatIf = [bool]$WhatIfPreference
$WhatIfPreference = 'SilentlyContinue'

function Test-EdkBound {
    param([string]$Name)
    return $script:Bound.ContainsKey($Name)
}

function Get-EdkProp {
    param(
        $Object,
        [string]$Name,
        $Default = $null
    )
    if ($null -eq $Object) { return $Default }
    $prop = $Object.PSObject.Properties[$Name]
    if ($null -eq $prop) { return $Default }
    $val = $prop.Value
    if ($null -eq $val) { return $Default }
    return $val
}

function Get-EdkBusTypeName {
    param($BusType)
    $s = [string]$BusType
    if ([string]::IsNullOrWhiteSpace($s)) { return 'Unknown' }
    return ($s.Trim() -replace '\s', '')
}

function Get-EdkSizeGbText {
    param([int64]$Bytes)
    if ($Bytes -lt 0) { $Bytes = 0 }
    $gb = [math]::Round(($Bytes / 1GB), 1)
    return $gb.ToString('0.0', $script:InvCulture)
}

function Get-EdkSerialText {
    param($Value)
    if ($null -eq $Value) { return '' }
    return ([string]$Value).Trim()
}

function Get-EdkSerialTail {
    param([string]$SerialNumber)
    if ([string]::IsNullOrWhiteSpace($SerialNumber)) { return 'NOSERIAL' }
    $s = $SerialNumber.Trim()
    if ($s.Length -le 4) { return $s }
    return $s.Substring($s.Length - 4)
}

function Get-EdkChallengePhrase {
    param($Identity)
    return 'DELETE'
}

function Get-EdkDriveLetterText {
    param($Partition)
    $c = Get-EdkProp $Partition 'DriveLetter' $null
    if ($null -eq $c) { return '' }
    $s = ([string]$c).Trim()
    if ([string]::IsNullOrWhiteSpace($s)) { return '' }
    $ch = $s[0]
    if ([int][char]$ch -eq 0) { return '' }
    if ($ch -eq ':') { return '' }
    return ([string]$ch).ToUpperInvariant()
}

function ConvertTo-EdkLetter {
    param([string]$Value)
    if ([string]::IsNullOrWhiteSpace($Value)) { return '' }
    $s = $Value.Trim().TrimEnd(':').Trim()
    if ($s.Length -ne 1) {
        Stop-Edk -Code 3 -Message 'Letter must be a single drive letter (for example E or E:).'
    }
    $ch = $s.ToUpperInvariant()
    if ($ch -notmatch '^[A-Z]$') {
        Stop-Edk -Code 3 -Message 'Letter must be A-Z.'
    }
    return $ch
}

function Write-EdkLog {
    param(
        [string]$Message,
        [ValidateSet('Info', 'Warn', 'Error', 'Success', 'Target', 'Plan')]
        [string]$Level = 'Info'
    )
    $color = 'Gray'
    switch ($Level) {
        'Info'    { $color = 'Gray' }
        'Warn'    { $color = 'Yellow' }
        'Error'   { $color = 'Red' }
        'Success' { $color = 'Green' }
        'Target'  { $color = 'Cyan' }
        'Plan'    { $color = 'Yellow' }
    }
    Write-Host $Message -ForegroundColor $color
    Write-Verbose $Message
    if ($null -ne $script:EdkLogCallback) {
        try { & $script:EdkLogCallback $Message $Level } catch { }
    }
}

function Write-EdkTargetBanner {
    param($Identity)
    $serial = $Identity.SerialNumber
    if ([string]::IsNullOrWhiteSpace($serial)) { $serial = '(no serial)' }
    $name = $Identity.FriendlyName
    if ([string]::IsNullOrWhiteSpace($name)) { $name = '(unknown model)' }
    $line = 'Target: Disk {0} | {1} | {2} GB | {3} | {4}' -f @(
        $Identity.Number
        $serial
        $Identity.SizeGbText
        $Identity.BusType
        $name
    )
    Write-EdkLog -Message $line -Level Target
}

function Stop-Edk {
    param(
        [int]$Code,
        [string]$Message,
        [ValidateSet('Error', 'Warn', 'Info', 'Success')]
        [string]$Level = 'Error'
    )
    $script:ExitCode = $Code
    if (-not [string]::IsNullOrWhiteSpace($Message)) {
        Write-EdkLog -Message $Message -Level $Level
    }
    throw ('EDK_EXIT:{0}' -f $Code)
}

function Exit-Edk {
    param([int]$Code)
    $script:ExitCode = $Code
    if ($script:TranscriptStarted) {
        try { Stop-Transcript -WhatIf:$false -Confirm:$false | Out-Null } catch { }
        $script:TranscriptStarted = $false
    }
    exit $Code
}

function Get-EdkSerialFromWmi {
    param([int]$Number)
    try {
        $w = Get-CimInstance -ClassName Win32_DiskDrive -Filter ("Index=$Number") -ErrorAction Stop
        if ($null -eq $w) { return '' }
        return (Get-EdkSerialText (Get-EdkProp $w 'SerialNumber' ''))
    } catch {
        return ''
    }
}

function ConvertTo-EdkDiskIdentity {
    param($Disk)
    $serial = Get-EdkSerialText (Get-EdkProp $Disk 'SerialNumber' '')
    $number = [int](Get-EdkProp $Disk 'Number' -1)
    if ([string]::IsNullOrWhiteSpace($serial) -and $number -ge 0) {
        $serial = Get-EdkSerialFromWmi -Number $number
    }
    $sizeBytes = [int64](Get-EdkProp $Disk 'Size' 0)
    $allocated = [int64](Get-EdkProp $Disk 'AllocatedSize' 0)
    $unalloc = $sizeBytes - $allocated
    if ($unalloc -lt 0) { $unalloc = 0 }
    $bus = Get-EdkBusTypeName (Get-EdkProp $Disk 'BusType' 'Unknown')

    [pscustomobject]@{
        Number             = $number
        SerialNumber       = $serial
        SizeBytes          = $sizeBytes
        SizeGbText         = (Get-EdkSizeGbText -Bytes $sizeBytes)
        FriendlyName       = [string](Get-EdkProp $Disk 'FriendlyName' '')
        BusType            = $bus
        BusTypeRaw         = [string](Get-EdkProp $Disk 'BusType' '')
        PartitionStyle     = [string](Get-EdkProp $Disk 'PartitionStyle' '')
        OperationalStatus  = [string](Get-EdkProp $Disk 'OperationalStatus' '')
        HealthStatus       = [string](Get-EdkProp $Disk 'HealthStatus' '')
        IsOffline          = [bool](Get-EdkProp $Disk 'IsOffline' $false)
        IsReadOnly         = [bool](Get-EdkProp $Disk 'IsReadOnly' $false)
        IsSystem           = [bool](Get-EdkProp $Disk 'IsSystem' $false)
        IsBoot             = [bool](Get-EdkProp $Disk 'IsBoot' $false)
        AllocatedSize      = $allocated
        UnallocatedSize    = $unalloc
        UniqueId           = [string](Get-EdkProp $Disk 'UniqueId' '')
        Raw                = $Disk
    }
}

function Get-EdkLiveDisks {
    try {
        return @(Get-Disk -ErrorAction Stop)
    } catch {
        Stop-Edk -Code 5 -Message ('Get-Disk failed: {0}' -f $_.Exception.Message)
    }
    return @()
}

function Get-EdkIdentityList {
    $out = New-Object System.Collections.ArrayList
    foreach ($d in (Get-EdkLiveDisks)) {
        [void]$out.Add((ConvertTo-EdkDiskIdentity -Disk $d))
    }
    return @($out.ToArray())
}

function Test-EdkShouldProcess {
    param(
        [string]$Target,
        [string]$CmdletLine
    )
    Write-EdkLog -Message ('  PLAN  {0}' -f $CmdletLine) -Level Plan
    if ($script:EdkWhatIf) {
        try {
            if ($null -ne $script:EdkCmdlet) {
                $null = $script:EdkCmdlet.ShouldProcess($Target, $CmdletLine)
            }
        } catch { }
        return $false
    }
    if ($null -eq $script:EdkCmdlet) {
        return $true
    }
    try {
        return [bool]$script:EdkCmdlet.ShouldProcess($Target, $CmdletLine)
    } catch {
        return $true
    }
}

function Invoke-EdkPlan {
    param(
        [string]$Target,
        [string[]]$CmdletLines
    )
    $execute = $true
    foreach ($line in @($CmdletLines)) {
        if ([string]::IsNullOrWhiteSpace($line)) { continue }
        $ok = Test-EdkShouldProcess -Target $Target -CmdletLine $line
        if (-not $ok) {
            $execute = $false
        }
    }
    if ($script:EdkWhatIf) {
        Write-EdkLog -Message 'WhatIf: no changes made.' -Level Warn
        return $false
    }
    if (-not $execute) {
        Stop-Edk -Code 4 -Message 'Aborted (Confirm declined).' -Level Warn
    }
    return $true
}

function Start-EdkTranscript {
    if ([string]::IsNullOrWhiteSpace($LogPath)) {
        $name = 'ExternalDiskKit-{0:yyyyMMdd-HHmmss}.log' -f (Get-Date)
        $script:LogFile = Join-Path $env:TEMP $name
    } else {
        $script:LogFile = $LogPath
    }
    try {
        $parent = Split-Path -Parent $script:LogFile
        if (-not [string]::IsNullOrWhiteSpace($parent) -and -not (Test-Path -LiteralPath $parent)) {
            New-Item -ItemType Directory -Path $parent -Force -WhatIf:$false -Confirm:$false | Out-Null
        }
        Start-Transcript -Path $script:LogFile -Force -WhatIf:$false -Confirm:$false | Out-Null
        $script:TranscriptStarted = $true
        Write-EdkLog -Message ('Log: {0}' -f $script:LogFile) -Level Info
    } catch {
        Write-EdkLog -Message ('Could not start transcript: {0}' -f $_.Exception.Message) -Level Warn
    }
}

#endregion helpers

#region safety

function Test-EdkIsRemovable {
    param(
        $Identity,
        [string[]]$Allow = $null
    )
    if ($null -eq $Allow -or $Allow.Count -eq 0) {
        $Allow = $AllowBusType
    }
    $bus = Get-EdkBusTypeName (Get-EdkProp $Identity 'BusType' 'Unknown')
    if ([string]::IsNullOrWhiteSpace($bus)) { $bus = 'Unknown' }
    $allowed = @()
    foreach ($a in @($Allow)) {
        $n = Get-EdkBusTypeName $a
        if (-not [string]::IsNullOrWhiteSpace($n)) { $allowed += $n.ToUpperInvariant() }
    }
    return ($allowed -contains $bus.ToUpperInvariant())
}

function Test-EdkIsProtectedSystemDisk {
    param($Identity)

    if ([bool](Get-EdkProp $Identity 'IsSystem' $false)) { return $true }
    if ([bool](Get-EdkProp $Identity 'IsBoot' $false)) { return $true }
    if ([bool](Get-EdkProp $Identity 'IsOS' $false)) { return $true }

    $number = [int](Get-EdkProp $Identity 'Number' -1)
    if ($number -lt 0) { return $false }

    $sysLetter = ''
    if (-not [string]::IsNullOrWhiteSpace($env:SystemDrive)) {
        $sysLetter = $env:SystemDrive.Trim().TrimEnd('\').TrimEnd(':').ToUpperInvariant()
    }

    try {
        $parts = @(Get-EdkPartitions -DiskNumber $number)
        foreach ($p in $parts) {
            if ([bool](Get-EdkProp $p 'IsSystem' $false)) { return $true }
            if ([bool](Get-EdkProp $p 'IsBoot' $false)) { return $true }
            $dl = Get-EdkDriveLetterText $p
            if ($sysLetter -and $dl -eq $sysLetter) { return $true }
        }
    } catch { }

    try {
        $vols = @(Get-CimInstance -ClassName Win32_Volume -ErrorAction Stop)
        foreach ($v in $vols) {
            $flag = $false
            if ([bool](Get-EdkProp $v 'SystemVolume' $false)) { $flag = $true }
            if ([bool](Get-EdkProp $v 'BootVolume' $false)) { $flag = $true }
            if ([bool](Get-EdkProp $v 'PageFilePresent' $false)) { $flag = $true }
            if (-not $flag) { continue }
            $dl = Get-EdkSerialText (Get-EdkProp $v 'DriveLetter' '')
            $dl = $dl.TrimEnd(':')
            if ([string]::IsNullOrWhiteSpace($dl)) { continue }
            try {
                $part = Get-Partition -DriveLetter $dl[0] -ErrorAction Stop
                if ($null -ne $part -and [int]$part.DiskNumber -eq $number) { return $true }
            } catch { }
        }
    } catch { }

    try {
        $pages = @(Get-CimInstance -ClassName Win32_PageFileUsage -ErrorAction Stop)
        foreach ($pf in $pages) {
            $name = [string](Get-EdkProp $pf 'Name' '')
            if ([string]::IsNullOrWhiteSpace($name)) { continue }
            $dl = $name.Substring(0, 1).ToUpperInvariant()
            try {
                $part = Get-Partition -DriveLetter $dl -ErrorAction Stop
                if ($null -ne $part -and [int]$part.DiskNumber -eq $number) { return $true }
            } catch { }
        }
    } catch { }

    return $false
}

function Assert-EdkBusAllowed {
    param($Identity)
    if (Test-EdkIsRemovable -Identity $Identity) { return }

    $bus = $Identity.BusType
    $msg = 'Refused: bus type {0} is not in the removable allow-list ({1}).' -f $bus, ($AllowBusType -join ', ')
    if (-not $AllowInternalDisks -or -not $Force) {
        Stop-Edk -Code 3 -Message ($msg + ' Internal disks need -AllowInternalDisks -Force and the full serial.')
    }

    $want = $Identity.SerialNumber
    if ([string]::IsNullOrWhiteSpace($want)) {
        Stop-Edk -Code 3 -Message 'Refused: internal disk has no serial, cannot confirm identity.'
    }

    if ($NonInteractive) {
        if (-not $IReallyMeanIt) {
            Stop-Edk -Code 3 -Message 'NonInteractive internal disk: also pass -IReallyMeanIt and -Serial.'
        }
        if (-not (Test-EdkBound 'Serial')) {
            Stop-Edk -Code 3 -Message 'NonInteractive internal disk: -Serial is required and must match.'
        }
        if ($Serial.Trim().ToUpperInvariant() -ne $want.ToUpperInvariant()) {
            Stop-Edk -Code 3 -Message 'Refused: -Serial does not match the internal disk serial.'
        }
        Write-EdkLog -Message 'AllowInternalDisks: serial matched (non-interactive).' -Level Warn
        return
    }

    Write-EdkLog -Message $msg -Level Warn
    Write-EdkLog -Message ('Type the FULL serial to allow this internal disk ({0}):' -f $want.Length) -Level Warn
    if ($null -ne $script:EdkSerialCallback) {
        $typed = [string](& $script:EdkSerialCallback $want $Identity)
    } else {
        $typed = Read-Host 'Full serial'
    }
    if ([string]::IsNullOrWhiteSpace($typed) -or $typed.Trim().ToUpperInvariant() -ne $want.ToUpperInvariant()) {
        Stop-Edk -Code 3 -Message 'Refused: full serial did not match.'
    }
}

function Assert-EdkNotSystemDisk {
    param($Identity)
    if (Test-EdkIsProtectedSystemDisk -Identity $Identity) {
        Stop-Edk -Code 3 -Message 'looks like system disk — refused'
    }
}

function Get-EdkBitLockerInfo {
    param([int]$DiskNumber)
    $rows = New-Object System.Collections.ArrayList
    $modOk = $false
    try {
        $null = Get-Command Get-BitLockerVolume -ErrorAction Stop
        $modOk = $true
    } catch {
        $modOk = $false
    }
    if (-not $modOk) {
        return @{ Available = $false; Locked = $false; Protected = $false; Rows = @() }
    }

    $locked = $false
    $protected = $false
    $parts = @(Get-EdkPartitions -DiskNumber $DiskNumber)
    foreach ($p in $parts) {
        $dl = Get-EdkDriveLetterText $p
        if ([string]::IsNullOrWhiteSpace($dl)) { continue }
        $mp = '{0}:' -f $dl
        try {
            $bl = Get-BitLockerVolume -MountPoint $mp -ErrorAction Stop
            $lockStatus = [string](Get-EdkProp $bl 'LockStatus' '')
            $prot = [string](Get-EdkProp $bl 'ProtectionStatus' '')
            $volStatus = [string](Get-EdkProp $bl 'VolumeStatus' '')
            # Unlocked contains the substring "Locked" — match the whole token only.
            if ($lockStatus -eq 'Locked') { $locked = $true }
            if ($prot -eq 'On') { $protected = $true }
            [void]$rows.Add([pscustomobject]@{
                Mount             = $mp
                ProtectionStatus  = $prot
                VolumeStatus      = $volStatus
                LockStatus        = $lockStatus
            })
        } catch { }
    }
    return @{
        Available = $true
        Locked    = $locked
        Protected = $protected
        Rows      = @($rows.ToArray())
    }
}

function Assert-EdkBitLockerForDestroy {
    param($Identity)
    $info = Get-EdkBitLockerInfo -DiskNumber $Identity.Number
    if (-not $info.Available) {
        Write-EdkLog -Message 'BitLocker: module not available (treated as unlocked / n/a).' -Level Warn
        return
    }
    if (-not $info.Protected -and -not $info.Locked) { return }

    if ($info.Locked) {
        if (-not $UnlockBitLocker) {
            Stop-Edk -Code 3 -Message 'locked — BitLocker is locked. Unlock the volume in Windows, then re-run with -UnlockBitLocker.'
        }
        $again = Get-EdkBitLockerInfo -DiskNumber $Identity.Number
        if ($again.Locked) {
            Stop-Edk -Code 3 -Message 'locked — still locked after -UnlockBitLocker. This script does not take passwords; unlock first.'
        }
    } elseif (-not $UnlockBitLocker) {
        Stop-Edk -Code 3 -Message 'BitLocker protection is On. Unlock/suspend in Windows if needed, then pass -UnlockBitLocker to acknowledge format/clean.'
    }
}

function Show-EdkPreviewTable {
    param($Identity)
    Write-EdkLog -Message 'Current layout:' -Level Info
    $rows = @(Get-EdkPartitionRows -Identity $Identity)
    if ($rows.Count -eq 0) {
        Write-Host '  (no partitions / RAW or unreadable)' -ForegroundColor DarkGray
        return
    }
    $rows | Format-Table -AutoSize | Out-String -Width 200 | Write-Host
}

function Complete-EdkVolume {
    param(
        [string]$DriveLetter,
        [string]$FileSystem = ''
    )
    if ([string]::IsNullOrWhiteSpace($DriveLetter)) { return }
    $dl = $DriveLetter.Trim().TrimEnd(':').ToUpperInvariant()
    if ($dl -notmatch '^[A-Z]$') { return }
    Write-EdkLog -Message ('Finishing {0}: so it is ready to use...' -f $dl) -Level Info
    Start-Sleep -Seconds 1
    $fs = $FileSystem
    if ([string]::IsNullOrWhiteSpace($fs)) {
        $vol = Get-EdkVolumeForLetter -DriveLetter $dl
        $fs = [string](Get-EdkProp $vol 'FileSystemType' (Get-EdkProp $vol 'FileSystem' ''))
    }
    $ok = $false
    if ($fs -match '^(NTFS|ReFS)$' -or [string]::IsNullOrWhiteSpace($fs)) {
        try {
            Write-EdkLog -Message ('  Repair-Volume -DriveLetter {0} -OfflineScanAndFix' -f $dl)
            $r = Repair-Volume -DriveLetter $dl[0] -OfflineScanAndFix -ErrorAction Stop
            Write-EdkLog -Message ('    result: {0}' -f $r) -Level Success
            $ok = $true
        } catch {
            Write-EdkLog -Message ('  Offline Repair-Volume failed: {0}' -f $_.Exception.Message) -Level Warn
        }
    }
    if (-not $ok) {
        Write-EdkLog -Message ('  chkdsk {0}: /F /X' -f $dl)
        $chk = & chkdsk ('{0}:' -f $dl) /F /X 2>&1 | Out-String
        if (-not [string]::IsNullOrWhiteSpace($chk)) {
            foreach ($line in @($chk -split "`r?`n")) {
                if (-not [string]::IsNullOrWhiteSpace($line)) {
                    Write-EdkLog -Message ('    {0}' -f $line.Trim())
                }
            }
        }
    }
    Start-Sleep -Seconds 1
    $dirty = Get-EdkDirtyText -DriveLetter $dl
    if ($dirty -eq 'Dirty') {
        Write-EdkLog -Message ('  {0}: is still dirty after repair.' -f $dl) -Level Warn
        return $false
    }
    Write-EdkLog -Message ('  {0}: is clean and ready to use.' -f $dl) -Level Success
    return $true
}

function Assert-EdkConfirmation {
    param(
        $Identity,
        [string]$Action,
        [string[]]$PlanLines = @()
    )
    Write-EdkTargetBanner -Identity $Identity
    Show-EdkPreviewTable -Identity $Identity
    $phrase = Get-EdkChallengePhrase -Identity $Identity
    Write-EdkLog -Message ('Destructive action: {0}' -f $Action) -Level Error
    if (@($PlanLines).Count -gt 0) {
        foreach ($pl in @($PlanLines)) {
            Write-EdkLog -Message ('  PLAN  {0}' -f $pl) -Level Plan
        }
    }
    if ($null -eq $script:EdkConfirmCallback) {
        Write-EdkLog -Message 'Type DELETE to proceed.' -Level Warn
    }

    if ($script:EdkWhatIf) {
        Write-EdkLog -Message 'WhatIf: skipping typed confirmation.' -Level Warn
        return
    }

    if ($NonInteractive) {
        if (-not $IReallyMeanIt) {
            Stop-Edk -Code 3 -Message 'NonInteractive: destructive actions need -IReallyMeanIt and -Serial.'
        }
        if (-not (Test-EdkBound 'Serial')) {
            Stop-Edk -Code 3 -Message 'NonInteractive: -Serial is required for destructive actions.'
        }
        $got = $Serial.Trim().ToUpperInvariant()
        $want = $Identity.SerialNumber.ToUpperInvariant()
        if ([string]::IsNullOrWhiteSpace($want) -or $got -ne $want) {
            Stop-Edk -Code 3 -Message 'NonInteractive: -Serial does not match the target disk serial.'
        }
        Write-EdkLog -Message 'NonInteractive: -IReallyMeanIt and serial matched.' -Level Warn
        return
    }

    if ($null -ne $script:EdkConfirmCallback) {
        $ok = $false
        try { $ok = [bool](& $script:EdkConfirmCallback $phrase $Identity $Action $PlanLines) } catch { $ok = $false }
        if (-not $ok) {
            Stop-Edk -Code 4 -Message 'Aborted (confirmation dialog).' -Level Warn
        }
        return
    }

    $entered = Read-Host 'Confirmation'
    if ([string]::IsNullOrWhiteSpace($entered)) {
        Stop-Edk -Code 4 -Message 'Aborted (empty confirmation).' -Level Warn
    }
    if ($entered.Trim().ToUpperInvariant() -ne $phrase.ToUpperInvariant()) {
        Stop-Edk -Code 4 -Message 'Confirmation did not match. Aborted.' -Level Warn
    }
}

function Get-EdkTargetDisk {
    param(
        [switch]$RequireTarget,
        [switch]$IncludeNonRemovable
    )

    $all = @(Get-EdkIdentityList)
    $candidates = @($all)

    if (Test-EdkBound 'DiskNumber') {
        $candidates = @($candidates | Where-Object { $_.Number -eq $DiskNumber })
        if ($candidates.Count -eq 0) {
            Stop-Edk -Code 2 -Message ('No disk with Number {0}.' -f $DiskNumber)
        }
    }

    if (Test-EdkBound 'Serial') {
        $want = $Serial.Trim().ToUpperInvariant()
        if ([string]::IsNullOrWhiteSpace($want)) {
            Stop-Edk -Code 2 -Message 'Serial was empty after trim.'
        }
        $candidates = @($candidates | Where-Object {
            -not [string]::IsNullOrWhiteSpace($_.SerialNumber) -and
            $_.SerialNumber.ToUpperInvariant() -eq $want
        })
        if ($candidates.Count -eq 0) {
            Stop-Edk -Code 2 -Message ('No disk with serial {0}.' -f $Serial.Trim())
        }
        if ($candidates.Count -gt 1 -and -not (Test-EdkBound 'DiskNumber')) {
            Stop-Edk -Code 3 -Message 'Multiple disks share that serial. Also pass -DiskNumber.'
        }
    }

    if (-not $IncludeNonRemovable) {
        $filtered = @($candidates | Where-Object { Test-EdkIsRemovable -Identity $_ })
        if ($RequireTarget -and (Test-EdkBound 'DiskNumber' -or Test-EdkBound 'Serial') -and $filtered.Count -eq 0 -and $candidates.Count -gt 0) {
            $one = $candidates[0]
            Write-EdkTargetBanner -Identity $one
            Assert-EdkNotSystemDisk -Identity $one
            Assert-EdkBusAllowed -Identity $one
            return $one
        }
        $candidates = $filtered
    }

    if (-not $RequireTarget) {
        return @($candidates)
    }

    if ($candidates.Count -eq 0) {
        Stop-Edk -Code 2 -Message 'No matching removable disk.'
    }
    if ($candidates.Count -gt 1) {
        Stop-Edk -Code 2 -Message 'Multiple removable disks match. Pass -DiskNumber and/or -Serial.'
    }
    $one = $candidates[0]
    Write-EdkTargetBanner -Identity $one
    Assert-EdkNotSystemDisk -Identity $one
    Assert-EdkBusAllowed -Identity $one
    return $one
}

function Assert-EdkIdentityStillMatches {
    param($Identity)
    $freshList = @(Get-EdkIdentityList | Where-Object { $_.Number -eq $Identity.Number })
    if ($freshList.Count -ne 1) {
        Stop-Edk -Code 3 -Message 'Refused: disk number disappeared or duplicated before write.'
    }
    $fresh = $freshList[0]
    $serialA = $Identity.SerialNumber.ToUpperInvariant()
    $serialB = $fresh.SerialNumber.ToUpperInvariant()
    if ($serialA -ne $serialB) {
        Stop-Edk -Code 3 -Message 'Refused: serial changed before write. Not acting on disk number alone.'
    }
    if ($Identity.SizeBytes -ne $fresh.SizeBytes) {
        Stop-Edk -Code 3 -Message 'Refused: size changed before write. Not acting on disk number alone.'
    }
    return $fresh
}

#endregion safety

#region inventory

function Get-EdkVolumeForLetter {
    param([string]$DriveLetter)
    if ([string]::IsNullOrWhiteSpace($DriveLetter)) { return $null }
    try {
        $v = Get-Volume -DriveLetter $DriveLetter[0] -ErrorAction Stop
        return $v
    } catch {
        return $null
    }
}

function Get-EdkPartitions {
    param([int]$DiskNumber)
    $old = $ErrorActionPreference
    $ErrorActionPreference = 'SilentlyContinue'
    try {
        $parts = @(Get-Partition -DiskNumber $DiskNumber -ErrorAction SilentlyContinue)
        if ($null -eq $parts) { return @() }
        return @($parts)
    } catch {
        return @()
    } finally {
        $ErrorActionPreference = $old
    }
}

function Test-EdkHasNoPartitions {
    param([int]$DiskNumber)
    $parts = @(Get-EdkPartitions -DiskNumber $DiskNumber)
    return ($parts.Count -eq 0)
}

function Get-EdkDiskStyle {
    param([int]$DiskNumber)
    $d = Get-Disk -Number $DiskNumber -ErrorAction Stop
    return [string](Get-EdkProp $d 'PartitionStyle' '')
}

function Invoke-EdkDiskpart {
    param(
        [int]$Number,
        [string[]]$Commands
    )
    $lines = New-Object System.Collections.ArrayList
    [void]$lines.Add(('select disk {0}' -f $Number))
    foreach ($c in @($Commands)) { [void]$lines.Add($c) }
    $script = ($lines.ToArray() -join "`r`n") + "`r`n"
    Write-EdkLog -Message ('  PLAN  diskpart: {0}' -f (($lines.ToArray()) -join '; ')) -Level Plan
    if ($script:EdkWhatIf) { return }
    $out = $script | diskpart 2>&1 | Out-String
    if (-not [string]::IsNullOrWhiteSpace($out)) {
        Write-EdkLog -Message $out.Trim()
    }
    Start-Sleep -Seconds 1
}

function Initialize-EdkPartitionTable {
    param(
        [int]$Number,
        [string]$WantStyle
    )
    $style = Get-EdkDiskStyle -DiskNumber $Number
    $empty = Test-EdkHasNoPartitions -DiskNumber $Number
    if ($style -eq 'RAW') {
        Initialize-Disk -Number $Number -PartitionStyle $WantStyle -Confirm:$false -ErrorAction Stop
        Write-EdkLog -Message ('Initialized disk {0} as {1}.' -f $Number, $WantStyle) -Level Success
        return
    }
    if ($empty -and $style -eq $WantStyle) {
        Write-EdkLog -Message ('Disk {0} is already empty {1}. Skipping Initialize-Disk.' -f $Number, $style) -Level Warn
        return
    }
    if (-not $empty) {
        Stop-Edk -Code 3 -Message ('Disk {0} still has partitions ({1}). Clean first.' -f $Number, $style)
    }
    # Empty but wrong style, or leftover "already initialized" after clean.
    $conv = 'convert mbr'
    if ($WantStyle -eq 'GPT') { $conv = 'convert gpt' }
    Write-EdkLog -Message ('Empty {0} disk cannot Initialize-Disk. Converting table to {1}.' -f $style, $WantStyle) -Level Warn
    Invoke-EdkDiskpart -Number $Number -Commands @($conv)
    $style2 = Get-EdkDiskStyle -DiskNumber $Number
    if ($style2 -eq 'RAW') {
        Initialize-Disk -Number $Number -PartitionStyle $WantStyle -Confirm:$false -ErrorAction Stop
        Write-EdkLog -Message ('Initialized disk {0} as {1}.' -f $Number, $WantStyle) -Level Success
        return
    }
    if ($style2 -ne $WantStyle) {
        Stop-Edk -Code 5 -Message ('Could not set partition style to {0} (now {1}).' -f $WantStyle, $style2)
    }
    Write-EdkLog -Message ('Disk {0} is empty {1}.' -f $Number, $style2) -Level Success
}

function Get-EdkDirtyText {
    param([string]$DriveLetter)
    if ([string]::IsNullOrWhiteSpace($DriveLetter)) { return '' }
    try {
        $out = & fsutil dirty query ('{0}:' -f $DriveLetter) 2>&1 | Out-String
        if ($out -match 'NOT Dirty') { return 'Clean' }
        if ($out -match 'is Dirty') { return 'Dirty' }
        return $out.Trim()
    } catch {
        return ''
    }
}

function Get-EdkAllocUnit {
    param([string]$DriveLetter)
    if ([string]::IsNullOrWhiteSpace($DriveLetter)) { return $null }
    try {
        $filter = "DriveLetter='{0}:'" -f $DriveLetter
        $v = Get-CimInstance -ClassName Win32_Volume -Filter $filter -ErrorAction Stop
        $b = Get-EdkProp $v 'BlockSize' $null
        if ($null -eq $b) { return $null }
        return [int64]$b
    } catch {
        return $null
    }
}

function Get-EdkPartitionRows {
    param($Identity)
    $rows = New-Object System.Collections.ArrayList
    $parts = @(Get-EdkPartitions -DiskNumber $Identity.Number)
    $bl = Get-EdkBitLockerInfo -DiskNumber $Identity.Number
    $blMap = @{}
    foreach ($b in @($bl.Rows)) {
        $blMap[$b.Mount] = $b
    }
    foreach ($p in $parts) {
        $dl = Get-EdkDriveLetterText $p
        $vol = $null
        if ($dl) { $vol = Get-EdkVolumeForLetter -DriveLetter $dl }
        $fs = ''
        $label = ''
        $health = ''
        if ($null -ne $vol) {
            $fs = [string](Get-EdkProp $vol 'FileSystemType' (Get-EdkProp $vol 'FileSystem' ''))
            $label = [string](Get-EdkProp $vol 'FileSystemLabel' '')
            $health = [string](Get-EdkProp $vol 'HealthStatus' '')
        }
        $dirty = Get-EdkDirtyText -DriveLetter $dl
        $alloc = Get-EdkAllocUnit -DriveLetter $dl
        $blText = 'n/a'
        if ($dl) {
            $key = '{0}:' -f $dl
            if ($blMap.ContainsKey($key)) {
                $brow = $blMap[$key]
                $blText = '{0}/{1}' -f $brow.LockStatus, $brow.ProtectionStatus
            } elseif (-not $bl.Available) {
                $blText = 'n/a'
            } else {
                $blText = 'Off'
            }
        }
        [void]$rows.Add([pscustomobject]@{
            Disk          = $Identity.Number
            Partition     = [int](Get-EdkProp $p 'PartitionNumber' 0)
            Type          = [string](Get-EdkProp $p 'Type' '')
            Offset        = [int64](Get-EdkProp $p 'Offset' 0)
            SizeBytes     = [int64](Get-EdkProp $p 'Size' 0)
            Size          = ('{0} GB' -f (Get-EdkSizeGbText -Bytes ([int64](Get-EdkProp $p 'Size' 0))))
            Letter        = $dl
            FileSystem    = $fs
            Label         = $label
            Health        = $health
            Dirty         = $dirty
            AllocUnit     = $alloc
            BitLocker     = $blText
            IsSystem      = [bool](Get-EdkProp $p 'IsSystem' $false)
            IsBoot        = [bool](Get-EdkProp $p 'IsBoot' $false)
            IsReadOnly    = [bool](Get-EdkProp $p 'IsReadOnly' $false)
            IsActive      = [bool](Get-EdkProp $p 'IsActive' $false)
        })
    }
    return @($rows.ToArray())
}

function Get-EdkInventoryRows {
    param($Identities)
    $rows = New-Object System.Collections.ArrayList
    foreach ($id in @($Identities)) {
        $sys = Test-EdkIsProtectedSystemDisk -Identity $id
        [void]$rows.Add([pscustomobject]@{
            Number            = $id.Number
            FriendlyName      = $id.FriendlyName
            SerialNumber      = $id.SerialNumber
            BusType           = $id.BusType
            PartitionStyle    = $id.PartitionStyle
            OperationalStatus = $id.OperationalStatus
            HealthStatus      = $id.HealthStatus
            SizeGB            = $id.SizeGbText
            SizeBytes         = $id.SizeBytes
            UnallocatedGB     = (Get-EdkSizeGbText -Bytes $id.UnallocatedSize)
            Offline           = $id.IsOffline
            ReadOnly          = $id.IsReadOnly
            IsSystem          = $id.IsSystem
            IsBoot            = $id.IsBoot
            ProtectedSystem   = $sys
        })
    }
    return @($rows.ToArray())
}

function Export-EdkReport {
    param(
        $DiskRows,
        $PartitionRows
    )
    if (-not [string]::IsNullOrWhiteSpace($CsvPath)) {
        try {
            $DiskRows | Export-Csv -Path $CsvPath -NoTypeInformation -Encoding UTF8
            Write-EdkLog -Message ('CSV: {0}' -f $CsvPath) -Level Success
        } catch {
            Stop-Edk -Code 5 -Message ('CSV export failed: {0}' -f $_.Exception.Message)
        }
    }
    if (-not [string]::IsNullOrWhiteSpace($HtmlPath)) {
        try {
            $title = 'ExternalDiskKit inventory {0}' -f (Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
            $html = $DiskRows | ConvertTo-Html -Title $title -PreContent ('<h1>{0}</h1>' -f $title)
            Set-Content -Path $HtmlPath -Value $html -Encoding UTF8
            Write-EdkLog -Message ('HTML: {0}' -f $HtmlPath) -Level Success
        } catch {
            Stop-Edk -Code 5 -Message ('HTML export failed: {0}' -f $_.Exception.Message)
        }
    }
}

function Invoke-EdkInventory {
    param(
        [object[]]$Identities,
        [switch]$Single
    )
    $ids = @($Identities)
    if ($ids.Count -eq 0) {
        Write-EdkLog -Message 'No matching removable disks.' -Level Warn
        Write-Host ''
        Write-Host '  (empty table — USB/SD/MMC/1394/VHD only by default; exit 0)' -ForegroundColor DarkGray
        Write-Host ''
        Export-EdkReport -DiskRows @() -PartitionRows @()
        return 0
    }

    foreach ($id in $ids) {
        Write-EdkTargetBanner -Identity $id
    }

    $diskRows = @(Get-EdkInventoryRows -Identities $ids)
    Write-Host ''
    Write-Host 'Disks' -ForegroundColor Cyan
    $diskRows | Select-Object Number, FriendlyName, SerialNumber, BusType, PartitionStyle, OperationalStatus, HealthStatus, SizeGB, UnallocatedGB, Offline, ReadOnly, IsSystem, IsBoot, ProtectedSystem |
        Format-Table -AutoSize | Out-String -Width 240 | Write-Host

    $partRows = New-Object System.Collections.ArrayList
    foreach ($id in $ids) {
        foreach ($r in @(Get-EdkPartitionRows -Identity $id)) {
            [void]$partRows.Add($r)
        }
    }
    Write-Host 'Partitions' -ForegroundColor Cyan
    if ($partRows.Count -eq 0) {
        Write-Host '  (none)' -ForegroundColor DarkGray
    } else {
        @($partRows.ToArray()) | Select-Object Disk, Partition, Type, Letter, FileSystem, Label, Size, Dirty, AllocUnit, BitLocker, IsSystem, IsBoot |
            Format-Table -AutoSize | Out-String -Width 240 | Write-Host
    }

    Export-EdkReport -DiskRows $diskRows -PartitionRows @($partRows.ToArray())
    return 0
}

#endregion inventory

#region diagnose

function Get-EdkStoragePolicyWriteProtect {
    $path = 'HKLM:\SYSTEM\CurrentControlSet\Control\StorageDevicePolicies'
    try {
        if (-not (Test-Path -LiteralPath $path)) {
            return [pscustomobject]@{ Present = $false; WriteProtect = $null }
        }
        $item = Get-ItemProperty -LiteralPath $path -ErrorAction Stop
        $wp = $null
        if ($item.PSObject.Properties.Name -contains 'WriteProtect') {
            $wp = $item.WriteProtect
        }
        return [pscustomobject]@{ Present = $true; WriteProtect = $wp }
    } catch {
        return [pscustomobject]@{ Present = $false; WriteProtect = $null }
    }
}

function Get-EdkRecentDiskEvents {
    param([int]$DiskNumber)
    $start = (Get-Date).AddDays(-7)
    $providers = @('disk', 'Disk', 'Ntfs', 'NTFS', 'Microsoft-Windows-Ntfs', 'diskpart', 'partmgr', 'Partmgr')
    $found = New-Object System.Collections.ArrayList
    foreach ($prov in $providers) {
        try {
            $ev = @(Get-WinEvent -FilterHashtable @{
                LogName      = 'System'
                ProviderName = $prov
                StartTime    = $start
            } -ErrorAction Stop)
        } catch {
            $ev = @()
        }
        foreach ($e in $ev) {
            $msg = [string](Get-EdkProp $e 'Message' '')
            $keep = $true
            if ($msg -match 'Volume Windows|HarddiskVolumeShadowCopy|is healthy. No action is needed') {
                $keep = $false
            }
            if ($msg -match 'disk\s+\d+' -or $msg -match 'PHYSICALDRIVE\d+') {
                $keep = $false
                if ($msg -match ("disk\s+$DiskNumber\b")) { $keep = $true }
                if ($msg -match ("PHYSICALDRIVE$DiskNumber\b")) { $keep = $true }
            }
            if (-not $keep) { continue }
            [void]$found.Add([pscustomobject]@{
                Time     = $e.TimeCreated
                Provider = $e.ProviderName
                Id       = $e.Id
                Level    = $e.LevelDisplayName
                Message  = ($msg -replace '\s+', ' ').Trim()
            })
        }
    }
    $uniq = @($found | Sort-Object Time -Descending)
    if ($uniq.Count -gt 15) { $uniq = $uniq[0..14] }
    return @($uniq)
}

function Invoke-EdkDiagnose {
    param($Identity)

    Write-EdkTargetBanner -Identity $Identity
    $verdict = 'ready to use'
    $notes = New-Object System.Collections.ArrayList

    if (Test-EdkIsProtectedSystemDisk -Identity $Identity) {
        Write-EdkLog -Message 'looks like system disk — refused' -Level Error
        Stop-Edk -Code 3 -Message 'looks like system disk — refused'
    }
    if (-not (Test-EdkIsRemovable -Identity $Identity)) {
        [void]$notes.Add('Bus type is not in the removable allow-list.')
        $verdict = 'locked'
        Assert-EdkBusAllowed -Identity $Identity
    }

    Write-EdkLog -Message 'Flags' -Level Target
    Write-EdkLog -Message ('  Offline={0}  ReadOnly={1}  System={2}  Boot={3}  Status={4}  Health={5}  Style={6}' -f @(
        $Identity.IsOffline, $Identity.IsReadOnly, $Identity.IsSystem, $Identity.IsBoot,
        $Identity.OperationalStatus, $Identity.HealthStatus, $Identity.PartitionStyle
    ))

    if ($Identity.IsOffline) {
        [void]$notes.Add('Disk is offline.')
    }
    if ($Identity.IsReadOnly) {
        [void]$notes.Add('Disk IsReadOnly is set (write-protect or policy).')
        $verdict = 'locked'
    }

    $style = $Identity.PartitionStyle
    if ($style -eq 'RAW' -or [string]::IsNullOrWhiteSpace($style) -or (Test-EdkHasNoPartitions -DiskNumber $Identity.Number)) {
        [void]$notes.Add('No partitions (empty or RAW table). Click Format to make it usable.')
        $verdict = 'no partition table'
    }

    $policy = Get-EdkStoragePolicyWriteProtect
    Write-EdkLog -Message 'Write-protect clues' -Level Target
    if ($policy.Present) {
        Write-EdkLog -Message ('  StorageDevicePolicies.WriteProtect = {0}' -f $policy.WriteProtect)
        if ($policy.WriteProtect -eq 1) {
            [void]$notes.Add('Machine policy StorageDevicePolicies.WriteProtect=1.')
            $verdict = 'locked'
        }
    } else {
        Write-EdkLog -Message '  StorageDevicePolicies key not present (normal).'
    }

    $bl = Get-EdkBitLockerInfo -DiskNumber $Identity.Number
    Write-EdkLog -Message 'BitLocker' -Level Target
    if (-not $bl.Available) {
        Write-EdkLog -Message '  n/a (Get-BitLockerVolume not available)'
    } elseif (@($bl.Rows).Count -eq 0) {
        Write-EdkLog -Message '  no lettered volumes / not enabled'
    } else {
        foreach ($r in @($bl.Rows)) {
            Write-EdkLog -Message ('  {0}  Lock={1}  Protection={2}  Volume={3}' -f $r.Mount, $r.LockStatus, $r.ProtectionStatus, $r.VolumeStatus)
        }
        if ($bl.Locked) {
            $verdict = 'locked'
            [void]$notes.Add('BitLocker volume is locked.')
        }
    }

    Write-EdkLog -Message 'Volumes / dirty bit / scan' -Level Target
    $parts = @(Get-EdkPartitionRows -Identity $Identity)
    if ($parts.Count -eq 0) {
        Write-EdkLog -Message '  no partitions'
    }
    $needsFix = $false
    foreach ($p in $parts) {
        Write-EdkLog -Message ('  Part {0}  {1}:  {2}  {3}  dirty={4}' -f $p.Partition, $p.Letter, $p.FileSystem, $p.Label, $p.Dirty)
        if ($p.Dirty -eq 'Dirty') {
            $needsFix = $true
            [void]$notes.Add(('Volume {0}: dirty bit is set — running an automatic repair.' -f $p.Letter))
        }
        if ([string]::IsNullOrWhiteSpace($p.Letter)) { continue }
        $fs = [string]$p.FileSystem
        if ($fs -and $fs -notmatch '^(NTFS|ReFS)$') {
            Write-EdkLog -Message ('  Live Repair-Volume scan skipped on {0}: ({1}).' -f $p.Letter, $fs)
            continue
        }
        try {
            Write-EdkLog -Message ('  Repair-Volume -DriveLetter {0} -Scan' -f $p.Letter)
            $scan = Repair-Volume -DriveLetter $p.Letter[0] -Scan -ErrorAction Stop
            Write-EdkLog -Message ('    scan result: {0}' -f $scan)
            $scanText = [string]$scan
            if ($scanText -match 'ErrorsFound|Corrupt') {
                $needsFix = $true
                [void]$notes.Add(('Scan found issues on {0}: ({1})' -f $p.Letter, $scanText))
            }
        } catch {
            $err = [string]$_.Exception.Message
            if ($err -match 'snapshot|offline scan and fix|not supported') {
                Write-EdkLog -Message ('  Live scan is not reliable on USB ({0}). Will use an offline repair if needed.' -f $p.Letter) -Level Warn
                if ($p.Dirty -eq 'Dirty') { $needsFix = $true }
            } else {
                Write-EdkLog -Message ('  Scan failed on {0}: {1}' -f $p.Letter, $err) -Level Warn
                $needsFix = $true
                [void]$notes.Add(('Scan failed on {0}:.' -f $p.Letter))
            }
        }
    }

    if ($needsFix) {
        foreach ($p in $parts) {
            if ([string]::IsNullOrWhiteSpace($p.Letter)) { continue }
            [void](Complete-EdkVolume -DriveLetter $p.Letter -FileSystem $p.FileSystem)
        }
        $parts = @(Get-EdkPartitionRows -Identity $Identity)
        $stillDirty = $false
        foreach ($p in $parts) {
            if ($p.Dirty -eq 'Dirty') { $stillDirty = $true }
        }
        if ($stillDirty) {
            $verdict = 'needs repair'
            [void]$notes.Add('Automatic repair ran, but the volume is still dirty.')
        } else {
            [void]$notes.Add('Automatic repair finished. Dirty bit is clear.')
        }
    }

    Write-EdkLog -Message 'Recent System log (disk/ntfs/partmgr, 7 days)' -Level Target
    $events = @(Get-EdkRecentDiskEvents -DiskNumber $Identity.Number)
    if ($events.Count -eq 0) {
        Write-EdkLog -Message '  none matched'
    } else {
        foreach ($e in $events) {
            $cut = $e.Message
            if ($cut.Length -gt 140) { $cut = $cut.Substring(0, 137) + '...' }
            Write-EdkLog -Message ('  {0:yyyy-MM-dd HH:mm}  [{1}] {2}  {3}' -f $e.Time, $e.Level, $e.Provider, $cut)
        }
        $bad = @($events | Where-Object { $_.Level -match 'Error|Warning|Critical' })
        if ($bad.Count -gt 0) {
            [void]$notes.Add(('Saw {0} recent disk/NTFS error or warning event(s).' -f $bad.Count))
        }
    }

    if ($verdict -eq 'ready to use' -and $parts.Count -eq 0) {
        $verdict = 'no partition table'
    }
    $vLevel = 'Error'
    if ($verdict -eq 'ready to use') { $vLevel = 'Success' }
    elseif ($verdict -eq 'no partition table') { $vLevel = 'Warn' }
    elseif ($verdict -eq 'needs repair') { $vLevel = 'Warn' }
    Write-EdkLog -Message ('Verdict: {0}' -f $verdict) -Level $vLevel
    foreach ($n in @($notes.ToArray())) {
        Write-EdkLog -Message ('  - {0}' -f $n) -Level Warn
    }
    if ($verdict -eq 'ready to use') {
        Write-EdkLog -Message '  This USB is good to go. You can copy files to it, or Eject when you are done.' -Level Success
    }
    $script:EdkLastVerdict = $verdict
    return 0
}

#endregion diagnose

#region repair

function Get-EdkDataPartitions {
    param([int]$DiskNumber)
    $parts = @(Get-EdkPartitions -DiskNumber $DiskNumber)
    $out = New-Object System.Collections.ArrayList
    foreach ($p in $parts) {
        $type = [string](Get-EdkProp $p 'Type' '')
        $size = [int64](Get-EdkProp $p 'Size' 0)
        if ($size -lt 8MB) { continue }
        if ($type -match 'Reserved|MSR|ESP|Recovery') { continue }
        if ([bool](Get-EdkProp $p 'IsSystem' $false) -and $type -match 'System') { continue }
        [void]$out.Add($p)
    }
    return @($out.ToArray())
}

function Invoke-EdkRepair {
    param($Identity)

    $fresh = Assert-EdkIdentityStillMatches -Identity $Identity
    $target = 'Disk {0} | {1}' -f $fresh.Number, $fresh.SerialNumber
    $plan = New-Object System.Collections.ArrayList

    if ($fresh.IsOffline) {
        [void]$plan.Add(('Set-Disk -Number {0} -IsOffline $false' -f $fresh.Number))
    }
    if ($ClearReadOnly -or ($Repair -and $fresh.IsReadOnly -and $ClearReadOnly)) {
        [void]$plan.Add(('Set-Disk -Number {0} -IsReadOnly $false' -f $fresh.Number))
    } elseif ($ClearReadOnly) {
        [void]$plan.Add(('Set-Disk -Number {0} -IsReadOnly $false' -f $fresh.Number))
    }

    $letterNorm = ''
    if (Test-EdkBound 'Letter') {
        $letterNorm = ConvertTo-EdkLetter -Value $Letter
        $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
        if ($data.Count -eq 0) {
            Stop-Edk -Code 5 -Message 'No data partition found to assign a letter. Initialize/create a partition first.'
        }
        $pick = $data[0]
        foreach ($d in $data) {
            if ([string]::IsNullOrWhiteSpace((Get-EdkDriveLetterText $d))) { $pick = $d; break }
        }
        [void]$plan.Add(('Set-Partition -DiskNumber {0} -PartitionNumber {1} -NewDriveLetter {2}' -f $fresh.Number, $pick.PartitionNumber, $letterNorm))
    }

    if ($Repair) {
        $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
        foreach ($d in $data) {
            $dl = Get-EdkDriveLetterText $d
            if ($letterNorm) { $dl = $letterNorm }
            if ([string]::IsNullOrWhiteSpace($dl)) {
                Write-EdkLog -Message ('Partition {0} has no letter; skip Repair-Volume.' -f $d.PartitionNumber) -Level Warn
                continue
            }
            [void]$plan.Add(('Repair-Volume -DriveLetter {0} -OfflineScanAndFix' -f $dl))
        }
        if ($plan.Count -eq 0 -and -not $fresh.IsOffline -and -not $ClearReadOnly) {
            Write-EdkLog -Message 'Nothing to repair (online, not read-only, no lettered volume).' -Level Warn
            return 0
        }
    }

    if ($plan.Count -eq 0) {
        Write-EdkLog -Message 'Nothing to do.' -Level Warn
        return 0
    }

    Show-EdkPreviewTable -Identity $fresh
    if (-not (Invoke-EdkPlan -Target $target -CmdletLines @($plan.ToArray()))) {
        return 0
    }

    try {
        if ($fresh.IsOffline) {
            Set-Disk -Number $fresh.Number -IsOffline $false -Confirm:$false
            Write-EdkLog -Message ('Disk {0} is online.' -f $fresh.Number) -Level Success
        }
        if ($ClearReadOnly) {
            Set-Disk -Number $fresh.Number -IsReadOnly $false -Confirm:$false
            Write-EdkLog -Message ('Disk {0} IsReadOnly cleared.' -f $fresh.Number) -Level Success
        }
        if ($letterNorm) {
            $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
            $pick = $data[0]
            foreach ($d in $data) {
                if ([string]::IsNullOrWhiteSpace((Get-EdkDriveLetterText $d))) { $pick = $d; break }
            }
            $existing = Get-EdkDriveLetterText $pick
            if ($existing -eq $letterNorm) {
                Write-EdkLog -Message ('Partition {0} already has letter {1}.' -f $pick.PartitionNumber, $letterNorm) -Level Info
            } else {
                Set-Partition -DiskNumber $fresh.Number -PartitionNumber $pick.PartitionNumber -NewDriveLetter $letterNorm -Confirm:$false
                Write-EdkLog -Message ('Assigned letter {0}:' -f $letterNorm) -Level Success
            }
        }
        if ($Repair) {
            $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
            foreach ($d in $data) {
                $dl = Get-EdkDriveLetterText $d
                if ($letterNorm) { $dl = $letterNorm }
                if ([string]::IsNullOrWhiteSpace($dl)) { continue }
                Write-EdkLog -Message ('Repair-Volume -DriveLetter {0} -OfflineScanAndFix ...' -f $dl) -Level Info
                $r = Repair-Volume -DriveLetter $dl[0] -OfflineScanAndFix -ErrorAction Stop
                Write-EdkLog -Message ('  result: {0}' -f $r) -Level Success
            }
        }
    } catch {
        Stop-Edk -Code 5 -Message ('Cmdlet failed: {0}' -f $_.Exception.Message)
    }

    $after = @(Get-EdkIdentityList | Where-Object { $_.Number -eq $fresh.Number })
    if ($after.Count -eq 1) { [void](Invoke-EdkInventory -Identities $after -Single) }
    return 0
}

#endregion repair

#region layout

function Test-EdkLayoutRequested {
    if ($Initialize) { return $true }
    if ($CreatePartition) { return $true }
    if (Test-EdkBound 'Format') { return $true }
    return $false
}

function Invoke-EdkLayout {
    param($Identity)

    if ((Test-EdkBound 'Label' -or $AllocationUnitSize) -and -not (Test-EdkBound 'Format')) {
        Stop-Edk -Code 3 -Message '-Label / -AllocationUnitSize require -Format NTFS|exFAT.'
    }

    $fresh = Assert-EdkIdentityStillMatches -Identity $Identity
    Assert-EdkBitLockerForDestroy -Identity $fresh

    $style = $fresh.PartitionStyle
    $emptyTable = Test-EdkHasNoPartitions -DiskNumber $fresh.Number
    if ($Initialize -and $style -ne 'RAW' -and -not $emptyTable) {
        Stop-Edk -Code 3 -Message ('Disk is {0}, not RAW. -Clean first if you intend to wipe the table, then -Initialize.' -f $style)
    }
    if (-not $Initialize -and $CreatePartition -and $style -eq 'RAW') {
        Stop-Edk -Code 3 -Message 'RAW disk: pass -Initialize (and optionally -CreatePartition -Format).'
    }
    if ((Test-EdkBound 'Format') -and -not $CreatePartition) {
        $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
        $hasLetter = $false
        foreach ($d in $data) {
            if (Get-EdkDriveLetterText $d) { $hasLetter = $true; break }
        }
        if (-not $hasLetter) {
            Stop-Edk -Code 3 -Message '-Format needs an existing lettered volume or -CreatePartition.'
        }
    }

    $letterNorm = ''
    if (Test-EdkBound 'Letter') {
        $letterNorm = ConvertTo-EdkLetter -Value $Letter
    }

    $fsText = $Format
    if (-not (Test-EdkBound 'Format')) { $fsText = '(no format)' }
    $labelText = $Label
    if ([string]::IsNullOrWhiteSpace($labelText)) { $labelText = '(no label)' }
    $action = 'ERASE this USB and create a new {0} partition formatted as {1}, label {2}. All files on this stick will be gone.' -f $PartitionStyle, $fsText, $labelText

    $target = 'Disk {0} | {1} | {2} GB' -f $fresh.Number, $fresh.SerialNumber, $fresh.SizeGbText
    $plan = New-Object System.Collections.ArrayList
    if ($fresh.IsOffline) {
        [void]$plan.Add(('Set-Disk -Number {0} -IsOffline $false' -f $fresh.Number))
    }
    if ($Initialize) {
        if ($style -eq 'RAW') {
            [void]$plan.Add(('Initialize-Disk -Number {0} -PartitionStyle {1}' -f $fresh.Number, $PartitionStyle))
        } elseif ($emptyTable -and $style -eq $PartitionStyle) {
            [void]$plan.Add(('(skip Initialize-Disk — empty {0} table already present)' -f $style))
        } elseif ($emptyTable) {
            [void]$plan.Add(('diskpart: select disk {0}; convert {1}' -f $fresh.Number, $PartitionStyle.ToLowerInvariant()))
        }
    }
    if ($CreatePartition) {
        if ($letterNorm) {
            [void]$plan.Add(('New-Partition -DiskNumber {0} -UseMaximumSize -DriveLetter {1}' -f $fresh.Number, $letterNorm))
        } else {
            [void]$plan.Add(('New-Partition -DiskNumber {0} -UseMaximumSize -AssignDriveLetter' -f $fresh.Number))
        }
    }
    if (Test-EdkBound 'Format') {
        $fmtTarget = '<assigned-letter>'
        if ($letterNorm) { $fmtTarget = $letterNorm }
        $fmt = 'Format-Volume -DriveLetter {0} -FileSystem {1} -Confirm:$false' -f $fmtTarget, $Format
        if (-not [string]::IsNullOrWhiteSpace($Label)) {
            $fmt = $fmt + (" -NewFileSystemLabel '{0}'" -f $Label)
        }
        if ($AllocationUnitSize -gt 0) {
            $fmt = $fmt + (' -AllocationUnitSize {0}' -f $AllocationUnitSize)
        }
        [void]$plan.Add($fmt)
        [void]$plan.Add(('Repair-Volume / chkdsk on {0}: so the stick is ready to use' -f $fmtTarget))
    }

    Assert-EdkConfirmation -Identity $fresh -Action $action -PlanLines @($plan.ToArray())

    if (-not (Invoke-EdkPlan -Target $target -CmdletLines @($plan.ToArray()))) {
        return 0
    }

    $fresh = Assert-EdkIdentityStillMatches -Identity $fresh
    $newPart = $null
    try {
        if ($fresh.IsOffline) {
            Set-Disk -Number $fresh.Number -IsOffline $false -Confirm:$false
            Write-EdkLog -Message ('Disk {0} is online.' -f $fresh.Number) -Level Success
        }
        if ($Initialize) {
            Initialize-EdkPartitionTable -Number $fresh.Number -WantStyle $PartitionStyle
        }
        if ($CreatePartition) {
            $np = @{
                DiskNumber     = $fresh.Number
                UseMaximumSize = $true
                ErrorAction    = 'Stop'
            }
            if ($letterNorm) {
                $np['DriveLetter'] = [char]$letterNorm[0]
            } else {
                $np['AssignDriveLetter'] = $true
            }
            $newPart = New-Partition @np
            $assigned = Get-EdkDriveLetterText $newPart
            Write-EdkLog -Message ('Created partition {0} letter={1}' -f $newPart.PartitionNumber, $assigned) -Level Success
        }
        if (Test-EdkBound 'Format') {
            $dl = $letterNorm
            if ($newPart) {
                $dl = Get-EdkDriveLetterText $newPart
            }
            if ([string]::IsNullOrWhiteSpace($dl)) {
                $data = @(Get-EdkDataPartitions -DiskNumber $fresh.Number)
                foreach ($d in $data) {
                    $cand = Get-EdkDriveLetterText $d
                    if ($cand) { $dl = $cand; break }
                }
            }
            if ([string]::IsNullOrWhiteSpace($dl)) {
                Stop-Edk -Code 5 -Message 'Format-Volume: no drive letter available.'
            }
            $fp = @{
                DriveLetter = $dl[0]
                FileSystem  = $Format
                Confirm     = $false
                Force       = $true
                ErrorAction = 'Stop'
            }
            if (-not [string]::IsNullOrWhiteSpace($Label)) {
                $fp['NewFileSystemLabel'] = $Label
            }
            if ($AllocationUnitSize -gt 0) {
                $fp['AllocationUnitSize'] = $AllocationUnitSize
            }
            $null = Format-Volume @fp
            Write-EdkLog -Message ('Formatted {0}: as {1}.' -f $dl, $Format) -Level Success
            [void](Complete-EdkVolume -DriveLetter $dl -FileSystem $Format)
        }
    } catch {
        Stop-Edk -Code 5 -Message ('Cmdlet failed: {0}' -f $_.Exception.Message)
    }

    $after = @(Get-EdkIdentityList | Where-Object { $_.Number -eq $fresh.Number })
    if ($after.Count -eq 1) { [void](Invoke-EdkInventory -Identities $after -Single) }
    return 0
}

#endregion layout

#region clean

function Invoke-EdkClean {
    param($Identity)

    $fresh = Assert-EdkIdentityStillMatches -Identity $Identity
    if (-not (Test-EdkIsRemovable -Identity $fresh)) {
        Assert-EdkBusAllowed -Identity $fresh
    }
    Assert-EdkBitLockerForDestroy -Identity $fresh
    $target = 'Disk {0} | {1} | {2} GB' -f $fresh.Number, $fresh.SerialNumber, $fresh.SizeGbText
    $plan = New-Object System.Collections.ArrayList
    if ($fresh.IsOffline) {
        [void]$plan.Add(('Set-Disk -Number {0} -IsOffline $false' -f $fresh.Number))
    }
    [void]$plan.Add(('Clear-Disk -Number {0} -RemoveData -RemoveOEM -Confirm:$false' -f $fresh.Number))
    $wipeAction = 'ERASE every partition and all files on this USB. The stick will be blank. This cannot be undone.'
    Assert-EdkConfirmation -Identity $fresh -Action $wipeAction -PlanLines @($plan.ToArray())
    if (-not (Invoke-EdkPlan -Target $target -CmdletLines @($plan.ToArray()))) {
        return 0
    }

    $fresh = Assert-EdkIdentityStillMatches -Identity $fresh
    try {
        if ($fresh.IsOffline) {
            Set-Disk -Number $fresh.Number -IsOffline $false -Confirm:$false
        }
        Clear-Disk -Number $fresh.Number -RemoveData -RemoveOEM -Confirm:$false -ErrorAction Stop
        Write-EdkLog -Message ('Cleared partition table on disk {0}.' -f $fresh.Number) -Level Success
    } catch {
        Stop-Edk -Code 5 -Message ('Cmdlet failed: {0}' -f $_.Exception.Message)
    }

    $after = @(Get-EdkIdentityList | Where-Object { $_.Number -eq $fresh.Number })
    if ($after.Count -eq 1) { [void](Invoke-EdkInventory -Identities $after -Single) }
    return 0
}

#endregion clean

#region eject

function Invoke-EdkEject {
    param($Identity)

    $fresh = Assert-EdkIdentityStillMatches -Identity $Identity
    $letters = New-Object System.Collections.ArrayList
    foreach ($p in @(Get-EdkPartitionRows -Identity $fresh)) {
        if (-not [string]::IsNullOrWhiteSpace($p.Letter)) {
            [void]$letters.Add($p.Letter)
        }
    }

    $target = 'Disk {0} | {1}' -f $fresh.Number, $fresh.SerialNumber
    $plan = New-Object System.Collections.ArrayList
    foreach ($dl in @($letters.ToArray())) {
        [void]$plan.Add(('Shell.Application Namespace(17).ParseName("{0}:\").InvokeVerb("Eject")' -f $dl))
    }
    [void]$plan.Add(('Set-Disk -Number {0} -IsOffline $true' -f $fresh.Number))

    Show-EdkPreviewTable -Identity $fresh
    if (-not (Invoke-EdkPlan -Target $target -CmdletLines @($plan.ToArray()))) {
        return 0
    }

    $ejectWarned = $false
    foreach ($dl in @($letters.ToArray())) {
        try {
            $shell = New-Object -ComObject Shell.Application
            $ns = $shell.Namespace(17)
            if ($null -ne $ns) {
                $item = $ns.ParseName(('{0}:\' -f $dl))
                if ($null -ne $item) {
                    $item.InvokeVerb('Eject')
                    Write-EdkLog -Message ('Requested eject of {0}:' -f $dl) -Level Success
                }
            }
        } catch {
            Write-EdkLog -Message ('Eject verb failed for {0}: {1}' -f $dl, $_.Exception.Message) -Level Warn
            $ejectWarned = $true
        }
    }
    try {
        Set-Disk -Number $fresh.Number -IsOffline $true -Confirm:$false -ErrorAction Stop
        Write-EdkLog -Message ('Disk {0} is offline.' -f $fresh.Number) -Level Success
    } catch {
        if ($ejectWarned) {
            Write-EdkLog -Message ('Offline failed after eject request: {0}' -f $_.Exception.Message) -Level Warn
            Write-EdkLog -Message 'Windows may still consider the device in use. Safe to unplug if the OS balloon says so.' -Level Warn
            return 0
        }
        Stop-Edk -Code 5 -Message ('Cmdlet failed: {0}' -f $_.Exception.Message)
    }
    if ($ejectWarned) {
        Write-EdkLog -Message 'Disk is offline; eject verb had a warning.' -Level Warn
    }
    return 0
}

#endregion eject

#region menu

function Invoke-EdkMenu {
    if ($NonInteractive) {
        Stop-Edk -Code 3 -Message '-Menu cannot run with -NonInteractive.'
    }

    $preselect = $null
    if (Test-EdkBound 'DiskNumber') { $preselect = $DiskNumber }

    while ($true) {
        Write-Host ''
        Write-Host '  ExternalDiskKit  (removable disks)' -ForegroundColor Cyan
        $ids = @(Get-EdkTargetDisk)
        if ($ids.Count -eq 0) {
            Write-Host '  No removable disks right now.' -ForegroundColor Yellow
        }
        $i = 1
        $map = @{}
        foreach ($id in $ids) {
            $serial = $id.SerialNumber
            if ([string]::IsNullOrWhiteSpace($serial)) { $serial = '(no serial)' }
            $mark = ''
            if ($null -ne $preselect -and $id.Number -eq $preselect) { $mark = '  <' }
            Write-Host ('  {0}. Disk {1} | {2} | {3} GB | {4} | {5}{6}' -f $i, $id.Number, $serial, $id.SizeGbText, $id.BusType, $id.FriendlyName, $mark)
            $map[$i] = $id
            $i++
        }
        Write-Host ''
        Write-Host '  L list/inventory   D diagnose   R repair   F format wizard' -ForegroundColor Gray
        Write-Host '  C clean (wipe table)   E eject   Q quit' -ForegroundColor Gray
        Write-Host ''
        $choice = (Read-Host '  Disk number from list, or action').Trim()
        if ($choice -match '^(q|quit|exit)$') { return 0 }
        if ([string]::IsNullOrWhiteSpace($choice)) { continue }

        $selected = $null
        if ($choice -match '^\d+$') {
            $n = [int]$choice
            if ($map.ContainsKey($n)) {
                $selected = $map[$n]
                $act = (Read-Host '  Action for this disk [L D R F C E]').Trim().ToUpperInvariant()
            } else {
                Write-EdkLog -Message 'Unknown list index.' -Level Warn
                continue
            }
        } else {
            $act = $choice.ToUpperInvariant()
            if ($ids.Count -eq 1) {
                $selected = $ids[0]
            } elseif ($null -ne $preselect) {
                foreach ($id in $ids) {
                    if ($id.Number -eq $preselect) { $selected = $id; break }
                }
            }
            if ($null -eq $selected -and $act -ne 'L') {
                Write-EdkLog -Message 'Pick a disk index first (or plug in a single removable disk).' -Level Warn
                continue
            }
        }

        try {
            switch ($act) {
                'L' {
                    if ($null -eq $selected) { [void](Invoke-EdkInventory -Identities $ids) }
                    else { [void](Invoke-EdkInventory -Identities @($selected) -Single) }
                }
                'D' { [void](Invoke-EdkDiagnose -Identity $selected) }
                'R' {
                    $script:Bound['Repair'] = $true
                    $Repair = $true
                    [void](Invoke-EdkRepair -Identity $selected)
                }
                'F' {
                    Write-Host '  Partition style GPT or MBR [GPT]:' -NoNewline
                    $st = (Read-Host).Trim().ToUpperInvariant()
                    if ([string]::IsNullOrWhiteSpace($st)) { $st = 'GPT' }
                    if ($st -ne 'GPT' -and $st -ne 'MBR') {
                        Write-EdkLog -Message 'Style must be GPT or MBR.' -Level Error
                        break
                    }
                    Write-Host '  File system NTFS or exFAT (required, recommended exFAT if >= 32 GB):' -NoNewline
                    $fs = (Read-Host).Trim()
                    if ($fs -ne 'NTFS' -and $fs -ne 'exFAT') {
                        Write-EdkLog -Message 'Filesystem must be NTFS or exFAT.' -Level Error
                        break
                    }
                    Write-Host '  Label (optional):' -NoNewline
                    $lb = Read-Host
                    $PartitionStyle = $st
                    $Format = $fs
                    $Label = $lb
                    $Initialize = $true
                    $CreatePartition = $true
                    $script:Bound['Format'] = $true
                    if ($selected.PartitionStyle -ne 'RAW') {
                        Write-EdkLog -Message 'Disk is not RAW. The wizard will Clean then Initialize+Format. Abort if that is not what you want.' -Level Warn
                        [void](Invoke-EdkClean -Identity $selected)
                        $selected = Assert-EdkIdentityStillMatches -Identity $selected
                    }
                    [void](Invoke-EdkLayout -Identity $selected)
                }
                'C' { [void](Invoke-EdkClean -Identity $selected) }
                'E' { [void](Invoke-EdkEject -Identity $selected) }
                default { Write-EdkLog -Message 'Unknown action.' -Level Warn }
            }
        } catch {
            if ($_.Exception.Message -match '^EDK_EXIT:') {
                Write-EdkLog -Message 'Action stopped by a safety gate. Menu continues.' -Level Warn
            } else {
                Write-EdkLog -Message ('Menu action failed: {0}' -f $_.Exception.Message) -Level Error
            }
        }
    }
}

#endregion menu

#region selftest

function Get-EdkDiskFingerprint {
    $disks = @()
    try { $disks = @(Get-Disk -ErrorAction Stop) } catch { $disks = @() }
    $parts = @()
    try { $parts = @(Get-Partition -ErrorAction Stop) } catch { $parts = @() }
    $dBits = New-Object System.Collections.ArrayList
    foreach ($d in $disks) {
        [void]$dBits.Add(('{0}|{1}|{2}|{3}' -f $d.Number, $d.PartitionStyle, $d.Size, (Get-EdkSerialText $d.SerialNumber)))
    }
    $pBits = New-Object System.Collections.ArrayList
    foreach ($p in $parts) {
        [void]$pBits.Add(('{0}:{1}:{2}' -f $p.DiskNumber, $p.PartitionNumber, $p.Size))
    }
    return ((@($dBits.ToArray()) -join ';') + '#' + (@($pBits.ToArray()) -join ';'))
}

function Invoke-EdkSelfTest {
    $script:InSelfTest = $true
    $failed = 0
    function Show-EdkTest {
        param([string]$Name, [bool]$Pass, [string]$Detail)
        if ($Pass) {
            Write-EdkLog -Message ('  PASS  {0}  {1}' -f $Name, $Detail) -Level Success
        } else {
            Write-EdkLog -Message ('  FAIL  {0}  {1}' -f $Name, $Detail) -Level Error
            $script:TestFailed = $true
        }
    }
    $script:TestFailed = $false

    Write-Host ''
    Write-Host 'ExternalDiskKit -SelfTest' -ForegroundColor Cyan

    # 1. Real OS disk is protected
    $sysPass = $false
    $sysDetail = 'no IsSystem/IsBoot disk found'
    try {
        $sysDisks = @()
        foreach ($id in @(Get-EdkIdentityList)) {
            if (Test-EdkIsProtectedSystemDisk -Identity $id) { $sysDisks += $id }
        }
        if ($sysDisks.Count -gt 0) {
            $sysPass = $true
            $sysDetail = ('disk {0} ({1})' -f $sysDisks[0].Number, $sysDisks[0].FriendlyName)
        }
    } catch {
        $sysDetail = $_.Exception.Message
    }
    Show-EdkTest -Name 'Refuse OS disk' -Pass $sysPass -Detail $sysDetail

    # 2. NVMe (live or synthetic) is not removable
    $nvmePass = $false
    $nvmeDetail = ''
    $liveNvme = @()
    foreach ($id in @(Get-EdkIdentityList)) {
        if ($id.BusType -eq 'NVMe') { $liveNvme += $id }
    }
    if ($liveNvme.Count -gt 0) {
        $nvmePass = -not (Test-EdkIsRemovable -Identity $liveNvme[0])
        $nvmeDetail = ('live NVMe disk {0} removable={1}' -f $liveNvme[0].Number, (Test-EdkIsRemovable -Identity $liveNvme[0]))
    } else {
        $fake = [pscustomobject]@{
            Number = 99; BusType = 'NVMe'; IsSystem = $false; IsBoot = $false
            SerialNumber = 'FAKESERIAL'; SizeBytes = 1TB; FriendlyName = 'Fake NVMe'
        }
        $nvmePass = -not (Test-EdkIsRemovable -Identity $fake)
        $nvmeDetail = 'synthetic NVMe object'
    }
    Show-EdkTest -Name 'Refuse NVMe without override' -Pass $nvmePass -Detail $nvmeDetail

    # 3. Inventory with current USB set (including zero)
    $invPass = $false
    $invDetail = ''
    try {
        $rem = @(Get-EdkTargetDisk)
        $invPass = $true
        $invDetail = ('{0} removable disk(s) — empty is exit 0' -f $rem.Count)
        [void](Invoke-EdkInventory -Identities $rem)
    } catch {
        $invDetail = $_.Exception.Message
    }
    Show-EdkTest -Name 'Inventory (zero USB ok)' -Pass $invPass -Detail $invDetail

    # 4. WhatIf initialize does not change anything
    $whatPass = $false
    $whatDetail = 'no removable disk to WhatIf against (skipped as pass)'
    $removable = @()
    try { $removable = @(Get-EdkTargetDisk) } catch { $removable = @() }
    if ($removable.Count -eq 0) {
        $whatPass = $true
    } else {
        $before = Get-EdkDiskFingerprint
        $oldWhatIf = $script:EdkWhatIf
        $script:EdkWhatIf = $true
        try {
            $id = $removable[0]
            $plan = @(
                ('Initialize-Disk -Number {0} -PartitionStyle GPT' -f $id.Number)
                ('New-Partition -DiskNumber {0} -UseMaximumSize -AssignDriveLetter' -f $id.Number)
                'Format-Volume -DriveLetter <assigned-letter> -FileSystem NTFS -Confirm:$false'
            )
            [void](Invoke-EdkPlan -Target ('Disk {0}' -f $id.Number) -CmdletLines $plan)
        } finally {
            $script:EdkWhatIf = $oldWhatIf
        }
        $after = Get-EdkDiskFingerprint
        $whatPass = ($before -eq $after)
        if ($whatPass) { $whatDetail = ('disk {0} fingerprint unchanged' -f $removable[0].Number) }
        else { $whatDetail = 'fingerprint changed during -WhatIf (unexpected)' }
    }
    Show-EdkTest -Name 'WhatIf initialize does not change anything' -Pass $whatPass -Detail $whatDetail

    # 5. Confirmation formatter
    $emptyId = [pscustomobject]@{ SerialNumber = ''; SizeGbText = '931.5' }
    $phrase1 = Get-EdkChallengePhrase -Identity $emptyId
    $fmtPass = ($phrase1 -eq 'DELETE')
    $longId = [pscustomobject]@{ SerialNumber = 'ABCDEF1234'; SizeGbText = (Get-EdkSizeGbText -Bytes 1000000000000) }
    $phrase2 = Get-EdkChallengePhrase -Identity $longId
    $fmtPass = $fmtPass -and ($phrase2 -eq 'DELETE')
    $sizeCheck = (Get-EdkSizeGbText -Bytes 0) -eq '0.0'
    $fmtPass = $fmtPass -and $sizeCheck
    Show-EdkTest -Name 'Confirmation formatter (NOSERIAL + 1 decimal GB)' -Pass $fmtPass -Detail $phrase1

    if ($script:TestFailed) { $failed = 1 }
    if ($failed -ne 0) {
        Stop-Edk -Code 5 -Message 'SelfTest failed.'
    }
    Write-EdkLog -Message 'SelfTest passed.' -Level Success
    return 0
}

#endregion selftest

#region main

function Get-EdkActionList {
    $actions = New-Object System.Collections.ArrayList
    if ($Diagnose) { [void]$actions.Add('Diagnose') }
    if ($Repair -or $ClearReadOnly) { [void]$actions.Add('Repair') }
    if ($Clean) { [void]$actions.Add('Clean') }
    if ($Eject) { [void]$actions.Add('Eject') }
    if ($Menu) { [void]$actions.Add('Menu') }
    if ($SelfTest) { [void]$actions.Add('SelfTest') }
    if (Test-EdkLayoutRequested) { [void]$actions.Add('Layout') }
    # Letter-only counts as repair-ish unless another action already covers it
    if ((Test-EdkBound 'Letter') -and -not $Repair -and -not $ClearReadOnly -and -not (Test-EdkLayoutRequested) -and -not $Clean -and -not $Eject) {
        if ($actions -notcontains 'Repair') { [void]$actions.Add('Repair') }
    }
    if ($List -and $actions.Count -gt 0) {
        Stop-Edk -Code 3 -Message '-List cannot be combined with another action switch.'
    }
    if ($Gui -and $actions.Count -gt 0) {
        Stop-Edk -Code 3 -Message '-Gui cannot be combined with another action switch.'
    }
    return @($actions.ToArray())
}

function Start-EdkGuiHost {
    $guiPath = Join-Path $PSScriptRoot 'ExternalDiskKit.Gui.ps1'
    if (-not (Test-Path -LiteralPath $guiPath)) {
        Stop-Edk -Code 5 -Message ('GUI file not found: {0}' -f $guiPath)
    }
    $state = [System.Threading.Thread]::CurrentThread.GetApartmentState()
    if ($state -ne 'STA') {
        $ps = Join-Path $PSHOME 'powershell.exe'
        $arg = '-NoProfile -ExecutionPolicy Bypass -STA -WindowStyle Hidden -File "{0}" -Gui' -f $PSCommandPath
        $p = Start-Process -FilePath $ps -ArgumentList $arg -Wait -PassThru
        $code = 0
        if ($null -ne $p -and $null -ne $p.ExitCode) { $code = [int]$p.ExitCode }
        Exit-Edk -Code $code
    }
    . $guiPath
    Show-EdkWindow
}

try {
    try {
        [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
        $OutputEncoding = [System.Text.Encoding]::UTF8
    } catch { }

    try {
        $WhatIfPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue
        Import-Module Storage -ErrorAction Stop | Out-Null
    } catch {
        Write-Host ('Storage module is required (in-box on Windows 8+/Server 2012+): {0}' -f $_.Exception.Message) -ForegroundColor Red
        exit 5
    }

    if ($script:EdkSkipMain) {
        return
    }

    if ($Gui) {
        $ConfirmPreference = 'None'
        Start-EdkTranscript
        Start-EdkGuiHost
        Exit-Edk -Code 0
    }

    if (Test-EdkBound 'Letter') {
        $null = ConvertTo-EdkLetter -Value $Letter
    }

    Start-EdkTranscript

    $actions = @(Get-EdkActionList)
    if ($actions.Count -gt 1) {
        Stop-Edk -Code 3 -Message ('One action at a time. Got: {0}' -f ($actions -join ', '))
    }

    $code = 0
    if ($SelfTest) {
        $code = Invoke-EdkSelfTest
    } elseif ($Menu) {
        $code = Invoke-EdkMenu
    } elseif ($Diagnose) {
        $id = Get-EdkTargetDisk -RequireTarget
        $code = Invoke-EdkDiagnose -Identity $id
    } elseif ($Clean) {
        $id = Get-EdkTargetDisk -RequireTarget
        $code = Invoke-EdkClean -Identity $id
    } elseif ($Eject) {
        $id = Get-EdkTargetDisk -RequireTarget
        $code = Invoke-EdkEject -Identity $id
    } elseif (Test-EdkLayoutRequested) {
        $id = Get-EdkTargetDisk -RequireTarget
        $code = Invoke-EdkLayout -Identity $id
    } elseif ($Repair -or $ClearReadOnly -or (Test-EdkBound 'Letter')) {
        $id = Get-EdkTargetDisk -RequireTarget
        $code = Invoke-EdkRepair -Identity $id
    } else {
        # Default / -List: inventory. Specified disk that is internal still goes through
        # Get-EdkTargetDisk without -RequireTarget so we only list removable, unless the
        # operator named a disk — then resolve it (and warn/refuse system on writes only).
        if (Test-EdkBound 'DiskNumber' -or Test-EdkBound 'Serial') {
            $ids = @(Get-EdkTargetDisk -IncludeNonRemovable)
            if ($ids.Count -eq 0) {
                Stop-Edk -Code 2 -Message 'No matching disk.'
            }
            foreach ($named in $ids) {
                if (Test-EdkIsProtectedSystemDisk -Identity $named) {
                    Write-EdkLog -Message 'looks like system disk — writes refused' -Level Error
                } elseif (-not (Test-EdkIsRemovable -Identity $named)) {
                    Write-EdkLog -Message 'Not in the removable allow-list. Writes need -AllowInternalDisks -Force and the full serial.' -Level Warn
                }
            }
            $code = Invoke-EdkInventory -Identities $ids -Single
        } else {
            $ids = @(Get-EdkTargetDisk)
            $code = Invoke-EdkInventory -Identities $ids
        }
    }

    Exit-Edk -Code $code
} catch {
    $msg = [string]$_.Exception.Message
    if ($msg -match '^EDK_EXIT:(\d+)') {
        $code = [int]$Matches[1]
        if ($script:ExitCode -ne 0) { $code = $script:ExitCode }
        Exit-Edk -Code $code
    }
    if ($msg -match '^EDK_EXIT:(\d+):(.+)$') {
        Write-EdkLog -Message $Matches[2] -Level Error
        Exit-Edk -Code ([int]$Matches[1])
    }
    Write-EdkLog -Message ('Cmdlet failed: {0}' -f $msg) -Level Error
    Exit-Edk -Code 5
}

#endregion main

<#
.SYNOPSIS
    Inventory, diagnose, repair, and optionally partition/format external/removable disks only.

.DESCRIPTION
    README: ExternalDiskKit inventories, diagnoses, repairs, and (optionally) partitions/formats
    removable disks only. Default is report-only. Not TestDisk, not data recovery, not an
    in-place MBR<->GPT converter. Backup first. Admin required.

    Safer wrapper around in-box Storage cmdlets (Get-Disk, Initialize-Disk, New-Partition,
    Format-Volume, Clear-Disk, Repair-Volume). Default mode is a report of removable disks
    (USB, SD, MMC, 1394, FileBackedVirtual). Destructive actions require explicit switches,
    -WhatIf/-Confirm, and a typed DELETE challenge.

    This is not TestDisk, not a boot-record rebuild tool, and it will not convert MBR<->GPT
    in place with data. It will not target the Windows system disk. Internal bus types
    (SATA, NVMe, RAID, SCSI, SAS, Fibre Channel, unknown) are refused unless
    -AllowInternalDisks AND -Force AND the operator types the full serial.

    Filesystem when formatting must be explicit: NTFS or exFAT. Recommended: exFAT for
    removable disks 32 GB or larger (binary GB as shown), NTFS otherwise.

    Empty inventory (no matching removable disks, no -DiskNumber/-Serial) exits 0.
    A specified disk/serial that does not match exits 2.

.PARAMETER DiskNumber
    Disk number from Get-Disk. Never used alone for writes: serial, size, and name are
    re-checked. Unspecified [int] is ignored unless you actually pass -DiskNumber.

.PARAMETER Serial
    Disk serial number to match (case-insensitive, trimmed). Required for destructive
    work in -NonInteractive (together with -IReallyMeanIt).

.PARAMETER AllowBusType
    Extra/override allow-list of bus types. Default: USB, SD, MMC, 1394, FileBackedVirtual.
    Spaces in names are ignored ("File Backed Virtual" matches FileBackedVirtual).

.PARAMETER AllowInternalDisks
    Dangerous. Must be combined with -Force and typing the full serial (or -IReallyMeanIt
    plus -Serial when -NonInteractive). Still never allows the Windows system disk.

.PARAMETER Force
    Required together with -AllowInternalDisks to even consider an internal bus.

.PARAMETER LogPath
    Transcript path. Default: $env:TEMP\ExternalDiskKit-yyyyMMdd-HHmmss.log

.PARAMETER CsvPath
    Optional CSV export of the inventory rows.

.PARAMETER HtmlPath
    Optional HTML export of the inventory rows.

.PARAMETER NonInteractive
    Never prompt. Inventory/diagnose/selftest are allowed. Destructive actions are
    refused unless -IReallyMeanIt and -Serial are passed and match.

.PARAMETER IReallyMeanIt
    Non-interactive override for destructive actions. Does nothing without -NonInteractive
    and -Serial.

.PARAMETER List
    Force inventory mode (the default when no action switch is set).

.PARAMETER Diagnose
    Non-destructive diagnosis: dirty bit, Repair-Volume -Scan, recent disk/NTFS events,
    write-protect clues, plain-English verdict.

.PARAMETER Repair
    Soft repair: online the disk, optionally clear read-only, optionally assign a letter,
    Repair-Volume -OfflineScanAndFix.

.PARAMETER ClearReadOnly
    With -Repair (or alone): Set-Disk -IsReadOnly $false.

.PARAMETER Letter
    Drive letter to assign (E or E:). Alone, this assigns/changes a letter on the target
    data partition. With -Initialize/-CreatePartition, used instead of auto-assign.

.PARAMETER Initialize
    Initialize-Disk as GPT (default) or MBR. Disk must be RAW; otherwise use -Clean first.

.PARAMETER PartitionStyle
    GPT (default) or MBR. Used with -Initialize.

.PARAMETER CreatePartition
    New-Partition -UseMaximumSize on remaining space.

.PARAMETER Format
    NTFS or exFAT. Must be explicit — no implicit default. Recommended: exFAT for
    removable disks 32 GB or larger.

.PARAMETER Label
    Volume label for Format-Volume. Requires -Format.

.PARAMETER AllocationUnitSize
    Optional bytes for Format-Volume -AllocationUnitSize. Requires -Format.

.PARAMETER Clean
    Clear-Disk -RemoveData -RemoveOEM. Very destructive. Removable only by default.

.PARAMETER Eject
    Offline the disk and request Shell eject when a letter exists.

.PARAMETER Menu
    Interactive numbered list of removable disks and actions. Same safety gates.

.PARAMETER SelfTest
    Live + synthetic safety tests. Does not format or clean.

.PARAMETER UnlockBitLocker
    Acknowledge BitLocker. Format/clean still refuse if the volume is locked; this
    script never takes a password. Unlock in Windows first, then re-run with this switch.

.PARAMETER Gui
    Open the mouse-first WPF window (same as ExternalDiskKit.Gui.ps1 / run.cmd).

.EXAMPLE
    .\ExternalDiskKit.ps1
    Inventory removable disks (empty table and exit 0 if none).

.EXAMPLE
    .\ExternalDiskKit.ps1 -DiskNumber 2 -Diagnose
    Diagnose disk 2 (must still pass the removable/system gates).

.EXAMPLE
    .\ExternalDiskKit.ps1 -Serial 'XYZ' -Letter E
    Assign letter E to the data partition on the disk whose serial matches XYZ.

.EXAMPLE
    .\ExternalDiskKit.ps1 -DiskNumber 2 -Repair
    Online disk 2 and run Repair-Volume -OfflineScanAndFix on its data volume(s).

.EXAMPLE
    .\ExternalDiskKit.ps1 -DiskNumber 2 -Initialize -CreatePartition -Format NTFS -Label BACKUP -WhatIf
    Print the exact Initialize-Disk / New-Partition / Format-Volume lines. No changes.

.EXAMPLE
    .\ExternalDiskKit.ps1 -DiskNumber 2 -Clean
    Wipe the partition table after typing DELETE (CLI) or clicking Confirm (GUI).

.EXAMPLE
    .\ExternalDiskKit.ps1 -List -CsvPath $env:TEMP\edk.csv -HtmlPath $env:TEMP\edk.html
    Inventory plus exports.

.NOTES
    Limitations: not TestDisk; not data recovery; not boot-record rebuild; not in-place
    MBR<->GPT with data; not dynamic disks/RAID/LVM. Backup first. Admin required.
    Compatible with Windows PowerShell 5.1 and PowerShell 7 on Windows.

    Exit codes: 0 ok, 2 no matching disk, 3 refused safety, 4 user aborted, 5 cmdlet failed.

    Confirmation phrase (CLI wipe/format/clean): type DELETE.
    The GUI uses Confirm / Cancel and does not ask you to type anything.

    -SelfTest checks: refuse OS disk, refuse NVMe without override, -WhatIf initialize
    does not change anything, inventory with zero USB disks is ok (exit 0).
#>