Private/Apply.ps1

# Applying a plan: backup and rollback files first, then per batch: drift check -> PATCH -> verify. Every outcome is logged.

function Get-STMDataRoot {
    $root = $script:STM.Settings.DataRoot
    if (-not $root) {
        $base = if ($env:LOCALAPPDATA) { $env:LOCALAPPDATA } else { Join-Path $HOME '.local/share' }
        $root = Join-Path $base 'IntuneScopeTagManager'
    }
    if (-not (Test-Path -LiteralPath $root)) { New-Item -ItemType Directory -Path $root -Force | Out-Null }
    return $root
}

function Write-STMAudit {
    param([Parameter(Mandatory)][string]$Event, [hashtable]$Data)
    $entry = [ordered]@{ timeUtc = [DateTime]::UtcNow.ToString('o'); event = $Event; tenant = $script:STM.TenantId; account = $script:STM.Account; computer = [Environment]::MachineName }
    if ($Data) { foreach ($k in $Data.Keys) { $entry[$k] = $Data[$k] } }
    $line = $entry | ConvertTo-Json -Compress -Depth 6
    Add-Content -LiteralPath (Join-Path (Get-STMDataRoot) 'audit.log') -Value $line -Encoding utf8
}

function ConvertTo-STMLegacyCsvRows {
    # Same columns as the existing Update-IntuneScopeTags-Bulk.ps1 so a rollback file also works with the old script.
    param([object[]]$Items, [ValidateSet('Before', 'After')][string]$Side, [string]$Note)
    foreach ($i in $Items) {
        [pscustomobject][ordered]@{
            ObjectType = $i.Type; ObjectId = $i.Id; DisplayName = $i.Name
            ScopeTags = (@($i.$Side) -join ';'); Mode = 'Replace'; Notes = $Note
        }
    }
}

function Export-STMPlan {
    <# Writes a plan as JSON (machine) and CSV (change board review). #>
    param([Parameter(Mandatory)]$Plan, [Parameter(Mandatory)][string]$Directory)
    if (-not (Test-Path -LiteralPath $Directory)) { New-Item -ItemType Directory -Path $Directory -Force | Out-Null }
    $json = Join-Path $Directory "ScopeTagPlan_$($Plan.PlanId).json"
    $csv = Join-Path $Directory "ScopeTagPlan_$($Plan.PlanId).csv"
    $Plan | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $json -Encoding utf8
    $Plan.Items | ForEach-Object {
        [pscustomobject][ordered]@{
            State = $_.State; ObjectType = $_.Type; TypeLabel = $_.TypeLabel; ObjectId = $_.Id; DisplayName = $_.Name; Platform = $_.Platform
            CurrentScopeTags = ($_.BeforeNames -join ';'); NewScopeTags = ($_.AfterNames -join ';')
            Added = (($_.Added | ForEach-Object { Get-STMTagName $_ }) -join ';'); Removed = (($_.Removed | ForEach-Object { Get-STMTagName $_ }) -join ';')
            CurrentScopeTagIds = ($_.Before -join ';'); NewScopeTagIds = ($_.After -join ';')
            LosesVisibility = ($_.VisibilityLost -join '; '); GainsVisibility = ($_.VisibilityGained -join '; ')
            Issues = ($_.Issues -join '; '); Warnings = ($_.Warnings -join '; '); Notes = $_.Note
        }
    } | Export-Csv -LiteralPath $csv -NoTypeInformation -Encoding utf8
    return [pscustomobject]@{ Json = $json; Csv = $csv; Hash = $Plan.Hash }
}

function Import-STMPlanFile {
    <# Loads a plan JSON (for example one approved by change control) and checks its fingerprint. #>
    param([Parameter(Mandatory)][string]$Path)
    $plan = Get-Content -LiteralPath $Path -Raw | ConvertFrom-STMJson
    $expected = $plan.Hash
    $actual = Get-STMPlanHash -Plan $plan
    if ($expected -ne $actual) { throw "Plan file was edited after it was created (fingerprint $actual, expected $expected). Rebuild the plan." }
    if ($script:STM.TenantId -and $plan.Tenant -and $plan.Tenant -ne $script:STM.TenantId) { throw "Plan was built for tenant $($plan.Tenant) but you are signed in to $($script:STM.TenantId)." }
    $script:STM.Plans[$plan.PlanId] = $plan
    return $plan
}

function Start-STMRun {
    param([Parameter(Mandatory)]$Plan, [string]$Confirmation)
    if ($script:STM.Mode -ne 'ReadWrite') { throw 'Signed in read-only. Reconnect in write mode to apply changes.' }
    if (-not $Plan.CanApply) { throw "This plan cannot be applied: $(@($Plan.PlanIssues) -join ' ') Ready items: $($Plan.Summary.Ready)." }
    if ((Get-STMPlanHash -Plan $Plan) -ne $Plan.Hash) { throw 'Plan fingerprint changed; rebuild the plan.' }
    $ready = @($Plan.Items | Where-Object State -eq 'Ready')
    # Re-check the rules with this session's settings rather than trusting the plan's own verdict.
    $recheck = [System.Collections.Generic.List[string]]::new()
    $cap = [int]$script:STM.Settings.MaxChangesPerRun
    if ($cap -gt 0 -and $ready.Count -gt $cap -and -not ($Plan.OverrideCap -and $Plan.OverrideReason)) { $recheck.Add("$($ready.Count) changes exceed the per-run cap of $cap and the plan has no override with a reason.") }
    $protected = Get-STMProtectedTagIds
    $pm = Get-STMProtectedTagProblem -Protected $protected
    if ($pm -and $script:STM.Settings.ProtectedTagMissingBehavior -eq 'Block') { $recheck.Add($pm) }
    foreach ($it in $ready) {
        $b = @($it.Before | Where-Object { "$_" -ne '' }); $a = @($it.After | Where-Object { "$_" -ne '' })
        if (@($b + $a | Where-Object { $protected.Ids -contains $_ }).Count) { $recheck.Add("$($it.Key) involves a protected scope tag.") }
        if (-not $a.Count -and -not $Plan.AllowNoExplicitTags) { $recheck.Add("$($it.Key) would be left with no scope tags and the plan does not allow that.") }
        if ($a.Count -gt 100) { $recheck.Add("$($it.Key) would have more than 100 scope tags.") }
        if ($script:STM.AppOnly) {
            $wd = Get-STMTypeDef -Key $it.Type
            $ws = if ($wd -and $wd.PSObject.Properties['writeScope']) { [string]$wd.writeScope } else { '' }
            if ($ws -and -not (Test-STMAppHasWrite -Permission $ws)) { $recheck.Add("$($it.Key): the app registration lacks the $ws application permission.") }
        }
        if (@($it.Issues | Where-Object { $_ }).Count) { $recheck.Add("$($it.Key) has unresolved issues.") }
    }
    if ($recheck.Count) { throw "This plan cannot be applied: $(@($recheck | Select-Object -First 5) -join ' ')" }
    $expected = "APPLY $($ready.Count)"
    if ($Confirmation -cne $expected) { throw "Type '$expected' to confirm." }
    if ($script:STM.ActiveRun -and -not $script:STM.Runs[$script:STM.ActiveRun].Done) { throw 'Another run is in progress in this session.' }

    $runId = "{0}-{1}" -f [DateTime]::UtcNow.ToString('yyyyMMdd-HHmmss'), ([guid]::NewGuid().ToString('N').Substring(0, 6))
    $dir = Join-Path (Join-Path (Get-STMDataRoot) 'Runs') $runId
    New-Item -ItemType Directory -Path $dir -Force | Out-Null
    # Backup and rollback files exist before the first write.
    $Plan | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath (Join-Path $dir 'plan.json') -Encoding utf8
    $ready | Select-Object Key, Type, Id, Name, Before, BeforeNames | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $dir 'backup.json') -Encoding utf8
    ConvertTo-STMLegacyCsvRows -Items $ready -Side Before -Note "Rollback of run $runId" | Export-Csv -LiteralPath (Join-Path $dir 'rollback.csv') -NoTypeInformation -Encoding utf8

    $run = [ordered]@{
        RunId = $runId; PlanId = $Plan.PlanId; PlanHash = $Plan.Hash; Folder = $dir; StartedUtc = [DateTime]::UtcNow.ToString('o')
        Items = $ready; Cursor = 0; Results = [System.Collections.Generic.List[object]]::new(); Done = $false; Cancelled = $false
        Counts = [ordered]@{ Applied = 0; AppliedUnverified = 0; SkippedDrift = 0; SkippedProtected = 0; Failed = 0; NoChange = 0 }
    }
    $script:STM.Runs[$runId] = $run
    $script:STM.ActiveRun = $runId
    Write-STMAudit -Event 'RunStarted' -Data @{ runId = $runId; planId = $Plan.PlanId; planHash = $Plan.Hash; items = $ready.Count; folder = $dir }
    Add-Content -LiteralPath (Join-Path $dir 'run.log') -Value "$([DateTime]::UtcNow.ToString('o')) Run $runId started by $($script:STM.Account) for plan $($Plan.PlanId) ($($ready.Count) objects)" -Encoding utf8
    return Get-STMRunView -RunId $runId
}

function Get-STMWriteBody {
    param($Item, $Def, [string[]]$Tags)
    $prop = if ($Def.PSObject.Properties['tagProperty']) { $Def.tagProperty } else { 'roleScopeTagIds' }
    $body = [ordered]@{}
    if ($Def.writeStrategy -eq 'PatchWithODataType' -and $Item.ODataType) { $body['@odata.type'] = $Item.ODataType }
    $body[$prop] = [string[]]@($Tags | Where-Object { "$_" -ne '' })
    return $body
}

function Step-STMRun {
    <# Processes the next batch (up to 20 objects): re-read, compare with the plan's "before", write, re-read to verify. #>
    param([Parameter(Mandatory)][string]$RunId, [int]$BatchSize = 20)
    $run = $script:STM.Runs[$RunId]
    if (-not $run) { throw "Unknown run $RunId" }
    if ($run.Done) { return Get-STMRunView -RunId $RunId }
    $chunk = @($run.Items | Select-Object -Skip $run.Cursor -First $BatchSize)
    if (-not $chunk.Count) { return (Complete-STMRun -RunId $RunId) }
    $protected = (Get-STMProtectedTagIds).Ids

    # 1. Drift check: the live object must still match what the plan saw.
    $live = Get-STMLiveObject -Refs @($chunk | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } })
    $toWrite = [System.Collections.Generic.List[object]]::new()
    foreach ($i in $chunk) {
        $l = $live[$i.Key]
        $res = [ordered]@{ TimeUtc = [DateTime]::UtcNow.ToString('o'); Key = $i.Key; Type = $i.Type; Id = $i.Id; Name = $i.Name; Before = ($i.Before -join ';'); Planned = ($i.After -join ';'); Live = ''; Result = ''; Detail = '' }
        if (-not $l.Row) { $res.Result = 'Failed'; $res.Detail = "Could not re-read object: $($l.Error)" }
        else {
            $now = @($l.Row.TagIds)
            $res.Live = $now -join ';'
            if (@($now | Where-Object { $protected -contains $_ }).Count) { $res.Result = 'SkippedProtected'; $res.Detail = 'Object now carries a protected tag' }
            elseif ((@($now) -join ',') -ne (@($i.Before) -join ',')) {
                if ((@($now) -join ',') -eq (@($i.After) -join ',')) { $res.Result = 'NoChange'; $res.Detail = 'Already has the planned tags' }
                else { $res.Result = 'SkippedDrift'; $res.Detail = "Changed since the plan was built (now: $((@($now | ForEach-Object { Get-STMTagName $_ })) -join ', ')). Rebuild the plan for this object." }
            }
            else { $i | Add-Member -NotePropertyName LiveODataType -NotePropertyValue $l.Row.ODataType -Force; $toWrite.Add($i) }
        }
        if ($res.Result) { $run.Results.Add([pscustomobject]$res) }
        else { $i | Add-Member -NotePropertyName PendingResult -NotePropertyValue $res -Force }
    }

    # 2. Write.
    if ($toWrite.Count) {
        $reqs = @(foreach ($i in $toWrite) {
            $def = Get-STMTypeDef -Key $i.Type
            $item = [pscustomobject]@{ ODataType = if ($i.LiveODataType) { $i.LiveODataType } else { $i.ODataType } }
            @{ id = $i.Key; method = 'PATCH'; url = "/$($def.path)/$($i.Id)"; body = (Get-STMWriteBody -Item $item -Def $def -Tags $i.After) }
        })
        $w = Invoke-STMBatch -Requests $reqs
        $written = [System.Collections.Generic.List[object]]::new()
        foreach ($i in $toWrite) {
            $r = $w[$i.Key]
            if ($r -and $r.status -ge 200 -and $r.status -lt 300) { $written.Add($i) }
            else {
                $i.PendingResult.Result = 'Failed'
                $err = if ($r) { $r.error } else { 'No response' }
                if ($err -match 'MultiAdminApprovalRequired') { $err += '. This tenant requires Multi Admin Approval for this change; request approval in the Intune admin center.' }
                $i.PendingResult.Detail = $err
                $run.Results.Add([pscustomobject]$i.PendingResult)
            }
        }
        # 3. Verify.
        if ($written.Count) {
            $check = Get-STMLiveObject -Refs @($written | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } })
            foreach ($i in $written) {
                $c = $check[$i.Key]
                $got = if ($c.Row) { @($c.Row.TagIds) } else { @() }
                $i.PendingResult.Live = $got -join ';'
                if ($c.Row -and ((@($got) -join ',') -eq (@($i.After) -join ','))) { $i.PendingResult.Result = 'Applied'; $i.PendingResult.Detail = 'Written and verified' }
                else { $i.PendingResult.Result = 'AppliedUnverified'; $i.PendingResult.Detail = 'Write accepted; read-back did not match yet (Intune can lag). Final verification runs at the end.' }
                $run.Results.Add([pscustomobject]$i.PendingResult)
                if ($c.Row -and $script:STM.Inventory.ContainsKey($i.Key)) { $script:STM.Inventory[$i.Key] = $c.Row }
            }
        }
    }
    $run.Cursor += $chunk.Count
    Save-STMRunResults -RunId $RunId
    if ($run.Cursor -ge $run.Items.Count) { return (Complete-STMRun -RunId $RunId) }
    return Get-STMRunView -RunId $RunId
}

function Complete-STMRun {
    param([Parameter(Mandatory)][string]$RunId, [int]$VerifyAttempts = 3, [int]$VerifyDelaySeconds = 3)
    $run = $script:STM.Runs[$RunId]
    $pending = @($run.Results | Where-Object Result -eq 'AppliedUnverified')
    for ($a = 1; $a -le $VerifyAttempts -and $pending.Count; $a++) {
        Start-Sleep -Seconds $VerifyDelaySeconds
        $check = Get-STMLiveObject -Refs @($pending | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } })
        foreach ($p in $pending) {
            $c = $check[$p.Key]
            if ($c.Row -and ((@($c.Row.TagIds) -join ';') -eq $p.Planned)) { $p.Result = 'Applied'; $p.Detail = "Written and verified (attempt $a)"; $p.Live = $p.Planned }
        }
        $pending = @($run.Results | Where-Object Result -eq 'AppliedUnverified')
    }
    $run.Done = $true
    $run.FinishedUtc = [DateTime]::UtcNow.ToString('o')
    Save-STMRunResults -RunId $RunId
    $v = Get-STMRunView -RunId $RunId
    Write-STMAudit -Event 'RunFinished' -Data @{ runId = $RunId; counts = $v.Counts; cancelled = $run.Cancelled }
    Add-Content -LiteralPath (Join-Path $run.Folder 'run.log') -Value "$([DateTime]::UtcNow.ToString('o')) Run finished: $(($v.Counts.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" }) -join ' ')" -Encoding utf8
    return $v
}

function Stop-STMRun {
    param([Parameter(Mandatory)][string]$RunId)
    $run = $script:STM.Runs[$RunId]
    if (-not $run.Done) {
        $run.Cancelled = $true
        foreach ($i in @($run.Items | Select-Object -Skip $run.Cursor)) {
            $run.Results.Add([pscustomobject][ordered]@{ TimeUtc = [DateTime]::UtcNow.ToString('o'); Key = $i.Key; Type = $i.Type; Id = $i.Id; Name = $i.Name; Before = ($i.Before -join ';'); Planned = ($i.After -join ';'); Live = ''; Result = 'NotRun'; Detail = 'Run stopped before this object' })
        }
        $run.Cursor = $run.Items.Count
        return (Complete-STMRun -RunId $RunId -VerifyAttempts 1 -VerifyDelaySeconds 1)
    }
    return Get-STMRunView -RunId $RunId
}

function Save-STMRunResults {
    param([Parameter(Mandatory)][string]$RunId)
    $run = $script:STM.Runs[$RunId]
    $run.Results | Export-Csv -LiteralPath (Join-Path $run.Folder 'results.csv') -NoTypeInformation -Encoding utf8
    $run.Results | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $run.Folder 'results.json') -Encoding utf8
}

function Get-STMRunView {
    param([Parameter(Mandatory)][string]$RunId)
    $run = $script:STM.Runs[$RunId]
    $counts = [ordered]@{}
    foreach ($k in 'Applied', 'AppliedUnverified', 'NoChange', 'SkippedDrift', 'SkippedProtected', 'Failed', 'NotRun') { $counts[$k] = @($run.Results | Where-Object Result -eq $k).Count }
    [pscustomobject][ordered]@{
        RunId = $run.RunId; PlanId = $run.PlanId; Folder = $run.Folder; StartedUtc = $run.StartedUtc; FinishedUtc = $run.FinishedUtc
        Total = $run.Items.Count; Processed = [math]::Min($run.Cursor, $run.Items.Count); Done = $run.Done; Cancelled = $run.Cancelled
        Counts = $counts; Results = @($run.Results)
    }
}

function Get-STMRunHistory {
    $dir = Join-Path (Get-STMDataRoot) 'Runs'
    if (-not (Test-Path -LiteralPath $dir)) { return @() }
    Get-ChildItem -LiteralPath $dir -Directory | Sort-Object Name -Descending | ForEach-Object {
        $res = @(); $plan = $null
        $rf = Join-Path $_.FullName 'results.json'; $pf = Join-Path $_.FullName 'plan.json'
        if (Test-Path $rf) { $res = @(Get-Content -LiteralPath $rf -Raw | ConvertFrom-Json) }
        if (Test-Path $pf) { $plan = Get-Content -LiteralPath $pf -Raw | ConvertFrom-STMJson }
        [pscustomobject][ordered]@{
            RunId = $_.Name; Folder = $_.FullName; PlanTitle = if ($plan) { $plan.Title } else { '' }; Tenant = if ($plan) { $plan.Tenant } else { '' }
            Applied = @($res | Where-Object { $_.Result -in 'Applied', 'AppliedUnverified' }).Count
            Failed = @($res | Where-Object Result -eq 'Failed').Count
            Skipped = @($res | Where-Object { $_.Result -like 'Skipped*' }).Count
            HasRollback = Test-Path (Join-Path $_.FullName 'rollback.csv')
        }
    }
}

function New-STMRollbackOperations {
    <# Rollback = put every object this run changed back to its "before" tags (Replace). Objects the run did not change are left out. #>
    param([Parameter(Mandatory)][string]$RunId)
    $dir = Join-Path (Join-Path (Get-STMDataRoot) 'Runs') $RunId
    $results = @(Get-Content -LiteralPath (Join-Path $dir 'results.json') -Raw | ConvertFrom-Json)
    $changed = @($results | Where-Object { $_.Result -in 'Applied', 'AppliedUnverified' })
    foreach ($c in $changed) {
        [pscustomobject]@{ Type = $c.Type; Id = $c.Id; Mode = 'Replace'; Tags = @("$($c.Before)" -split ';' | Where-Object { $_ }); Note = "Rollback of run $RunId"; Source = "rollback:$RunId" }
    }
}