Netscoot

2.1.1

Netscoot.Shared/Common/Plan.ps1

# Shared move-plan engine used by the move cmdlets so the transaction is uniform.
#
# A move is a transaction: detach references (while old paths resolve) -> move -> reattach.
# Each reconciliation item bundles its Detach + Reattach. Confirmation/preview is the caller's
# job via $PSCmdlet.ShouldProcess (canonical -WhatIf/-Confirm); this engine just runs the
# transaction once the operation is approved.

function New-MoveResult {
    # Build a move cmdlet's result object with a uniform base shape (Engine, Source,
    # Destination, Performed, SkippedCount) plus engine-specific extras, and stamp the
    # given PSTypeName for formatting/filtering. Every move cmdlet emits one of these.
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$TypeName,
        [Parameter(Mandatory)][ValidateSet('dotnet', 'native', 'unity', 'powershell')][string]$Engine,
        [Parameter(Mandatory)][string]$Source,
        [Parameter(Mandatory)][string]$Destination,
        [bool]$Performed,
        [int]$SkippedCount = 0,
        [hashtable]$Extra = @{}
    )
    $ordered = [ordered]@{
        Engine       = $Engine
        Source       = $Source
        Destination  = $Destination
        Performed    = $Performed
        SkippedCount = $SkippedCount
    }
    foreach ($k in $Extra.Keys) { $ordered[$k] = $Extra[$k] }
    $obj = [pscustomobject]$ordered
    $obj.PSObject.TypeNames.Insert(0, $TypeName)
    return $obj
}

function Resolve-MoveContext {
    # Shared front-half of every move: resolve git usage (red guidance + ShouldContinue/abort
    # when missing) and whether to confirm per-line. Returns { UseGit; PerLine } or $null on
    # abort (after writing the GitMissingAborted error via the calling cmdlet).
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][System.Management.Automation.PSCmdlet]$Cmdlet,
        [switch]$Force,
        [Parameter(Mandatory)]$TargetForError
    )
    $gitMode = Resolve-GitUsage -Cmdlet $Cmdlet -Force:$Force
    if ($gitMode -eq 'Abort') {
        $Cmdlet.WriteError([System.Management.Automation.ErrorRecord]::new(
                [System.OperationCanceledException]::new('Aborted: git not found and the plain-move fallback was declined.'),
                'GitMissingAborted', [System.Management.Automation.ErrorCategory]::OperationStopped, $TargetForError))
        return $null
    }
    [pscustomobject]@{ UseGit = ($gitMode -eq 'Git') }
}

function New-MoveItem {
    # Build one reconciliation item. Pass module-bound scriptblocks (not .GetNewClosure() -
    # closures rebind to the caller's scope and lose module-private functions like Invoke-Dotnet)
    # and hand loop values in via *Args. Mark Optional for heuristic/non-load-bearing items.
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$Description,
        [scriptblock]$Detach,
        [object[]]$DetachArgs = @(),
        [scriptblock]$Reattach,
        [object[]]$ReattachArgs = @(),
        [switch]$Optional
    )
    [pscustomobject]@{
        Description  = $Description
        Detach       = $Detach;   DetachArgs   = $DetachArgs
        Reattach     = $Reattach; ReattachArgs = $ReattachArgs
        Optional     = [bool]$Optional
    }
}

function Invoke-MovePlan {
    # Run the move transaction: detach all reconciliation items (old paths still resolve),
    # perform the move, reattach all items. Confirmation/-WhatIf is the caller's ShouldProcess
    # gate - this only runs once approved.
    #
    # Rollback: any step that fails throws (Invoke-Dotnet throws on non-zero exit; Move-PathTracked
    # throws on a failed move). To avoid leaving a half-reconciled repository, the caller passes the files
    # the reconciliation edits (-BackupPath) and a move-reversing scriptblock (-Rollback). On any
    # failure this restores those files from a snapshot and reverses the move, returning the repository to
    # its pre-move state. This is the safety net for the -Force (no-git) path, which otherwise has
    # no git history to recover from; with git it complements (does not replace) `git restore`.
    [CmdletBinding()]
    [OutputType([pscustomobject])]
    param(
        [Parameter(Mandatory)][string]$Caption,
        [AllowEmptyCollection()][object[]]$Items = @(),
        [Parameter(Mandatory)][scriptblock]$Move,
        [object[]]$MoveArgs = @(),
        [string[]]$BackupPath = @(),
        [scriptblock]$Rollback,
        [object[]]$RollbackArgs = @(),
        # Write-ahead journaling. When -Command is supplied and journaling is enabled, a 'pending'
        # record is written BEFORE the transaction and a 'committed'/'rolledback' record after, so an
        # interrupted move is detectable. $UndoParams is the splat that reverses the move (same mover,
        # source/destination swapped). Omit these (or pass -NoJournal) to skip journaling.
        [string]$RepositoryRoot,
        [string]$Command,
        [string]$Engine,
        [string]$Source,
        [string]$Destination,
        [hashtable]$UndoParams,
        [switch]$NoJournal
    )
    Write-Verbose "Reconciling $(@($Items).Count) reference(s) around: $Caption"

    # The edited files we will snapshot, deduped and limited to ones that exist now, in a stable
    # order so the persisted index (f0, f1, ...) matches on recovery.
    $kept = @(@($BackupPath) | Select-Object -Unique | Where-Object { $_ -and (Test-Path -LiteralPath $_ -PathType Leaf) })
    $snapDir = $null
    if ($kept.Count) {
        $snapDir = Join-Path ([System.IO.Path]::GetTempPath()) ("netscoot_snap_" + [guid]::NewGuid().ToString('N').Substring(0, 8))
        New-Item -ItemType Directory -Path $snapDir | Out-Null
    }

    # Write-ahead: record intent before anything reversible happens, so a crash leaves a detectable
    # 'pending' entry (carrying source/destination, the snapshot dir, and the file->index mapping for
    # content recovery).
    $journaling = $Command -and (-not $NoJournal) -and (Test-MoveJournalEnabled -RepositoryRoot $RepositoryRoot)
    $hint = if ($Command -and $UndoParams) { Format-UndoHint -Command $Command -UndoParams $UndoParams } else { $null }
    $entry = $null
    if ($journaling) {
        $entry = Start-MoveJournalEntry -RepositoryRoot $RepositoryRoot -Command $Command -Engine $Engine `
            -Source $Source -Destination $Destination -Undo @{ Command = $Command; Params = $UndoParams } `
            -Snapshot $(if ($snapDir) { $snapDir } else { '' }) -Backup $kept
    }

    # Snapshot the edited files as f0, f1, ... (index = position in $kept), keyed by original path.
    $snap = [ordered]@{}
    if ($snapDir) {
        for ($i = 0; $i -lt $kept.Count; $i++) {
            $copy = Join-Path $snapDir ("f{0}" -f $i)
            Copy-Item -LiteralPath $kept[$i] -Destination $copy -Force
            $snap[$kept[$i]] = $copy
        }
    }

    $moved = $false
    try {
        # NOTE: @var is the splat operator (needs a bare variable); @(expr) is array-subexpression
        # and would pass the whole array as one argument. So copy to a local, then splat.
        foreach ($it in $Items) {
            if ($it.Detach) { $da = @($it.DetachArgs); & $it.Detach @da }
        }
        $ma = @($MoveArgs); & $Move @ma
        $moved = $true
        foreach ($it in $Items) {
            if ($it.Reattach) { $ra = @($it.ReattachArgs); & $it.Reattach @ra }
        }
    } catch {
        $cause = $_
        $rollbackOk = $true
        # Reverse the move first (so files return to where the snapshot expects them)...
        if ($moved -and $Rollback) {
            try { $rba = @($RollbackArgs); & $Rollback @rba }
            catch { $rollbackOk = $false; Write-Warning "Rollback move-back failed: $($_.Exception.Message)" }
        }
        # ...then restore every edited file's original content.
        foreach ($orig in $snap.Keys) {
            try { Copy-Item -LiteralPath $snap[$orig] -Destination $orig -Force }
            catch { $rollbackOk = $false; Write-Warning "Rollback restore failed for ${orig}: $($_.Exception.Message)" }
        }
        if ($rollbackOk) {
            # Cleanly reversed: mark the entry rolled back and drop the (now-moot) snapshot.
            if ($snapDir) { Remove-Item -LiteralPath $snapDir -Recurse -Force -ErrorAction SilentlyContinue }
            if ($journaling) { Complete-MoveJournalEntry -RepositoryRoot $RepositoryRoot -Entry $entry -Status 'rolledback' }
            throw "Move failed and was rolled back to the original state. Cause: $($cause.Exception.Message)"
        }
        # Partial state: leave the 'pending' entry and its snapshot in place so the move is detectable
        # (Get-InterruptedMove) and recoverable (Repair-NetscootJournal).
        throw "Move failed AND rollback was incomplete - the repository may be in a partial state. Check git status, or run Repair-NetscootJournal to recover. Cause: $($cause.Exception.Message)"
    }
    if ($snapDir) { Remove-Item -LiteralPath $snapDir -Recurse -Force -ErrorAction SilentlyContinue }
    if ($journaling) {
        Complete-MoveJournalEntry -RepositoryRoot $RepositoryRoot -Entry $entry -Status 'committed'
        Write-Host "Undo with: Undo-Netscoot (replays: $hint)" -ForegroundColor DarkGray
    } elseif ($hint) {
        Write-Host "Undo (journaling off): $hint" -ForegroundColor DarkGray
    }

    [pscustomobject]@{ Applied = @($Items).Count; Skipped = 0 }
}