diff --git a/TASKS.md b/TASKS.md index 520dbcb..ae13ea9 100644 --- a/TASKS.md +++ b/TASKS.md @@ -128,3 +128,4 @@ open until it is run on disposable machines with the required account setups. - [x] Retry an upgrade with an install when WinGet reports no matching installed package, preserving scope and testing bounded retries. - [x] Make web config updates force replacement with backups by default, with an explicit opt-out. - [x] Apply the force-by-default policy during install/bootstrap too, with a preserve-local-configs opt-out. +- [x] Replace bootstrap exit-code exceptions with friendly partial-success, reboot, and busy summaries while preserving automation status. diff --git a/docs/advanced_commands.md b/docs/advanced_commands.md index 29e61e6..10657f1 100644 --- a/docs/advanced_commands.md +++ b/docs/advanced_commands.md @@ -244,6 +244,17 @@ From CachyOS, retrieve a completed capture for review with: scp -r USER@WINDOWS-PC:'Documents/ConfigCentral/captures/MACHINE-yyyyMMdd-HHmmss' ./ ``` +## Setup outcomes + +When deployment is incomplete, the web installer shows a short summary after the +per-item results. Successful changes remain applied. Correct the listed issue +and rerun setup. Reboot requests and an already-running update have separate +messages. Deployment logs are under `%LOCALAPPDATA%\ConfigCentral\logs`. + +Running `install.ps1` as a file preserves the bootstrap process exit code. +With `irm | iex`, the terminal stays open and `$LASTEXITCODE` contains that code. +Errors raised before deployment may still include PowerShell diagnostics. + ## Config conflicts and recovery Config Central stores the hash it last deployed. A different destination hash, diff --git a/install.ps1 b/install.ps1 index 7d875d0..f10de93 100644 --- a/install.ps1 +++ b/install.ps1 @@ -32,6 +32,34 @@ if (-not [string]::IsNullOrWhiteSpace($Machine) -and $Machine -notmatch '^[a-z0- } if ($env:CONFIG_CENTRAL_SKIP_APPLY -eq '1') { $SkipApply = $true } +function Write-SetupFailure { + param([int]$ExitCode) + Write-Host '' + switch ($ExitCode) { + 5 { + Write-Host 'Setup finished with some items needing attention.' -ForegroundColor Yellow + Write-Host 'Successful changes were kept. Review the Failed, Conflict, or Skipped items above.' + Write-Host 'Fix the reported issue, then rerun setup; completed items will be checked and skipped when current.' + } + 6 { + Write-Host 'Setup completed. Windows needs a restart to finish installation.' -ForegroundColor Yellow + Write-Host 'Restart when convenient; Config Central will not restart this computer automatically.' + } + 10 { + Write-Host 'Another Config Central update is already running.' -ForegroundColor Yellow + Write-Host 'Wait for it to finish, then rerun setup.' + } + default { + Write-Host "Setup could not complete (exit code $ExitCode)." -ForegroundColor Yellow + Write-Host 'Review the diagnostic above, correct the problem, and rerun setup.' + } + } + if ($ExitCode -ne 6) { + Write-Host 'Run cc doctor in a new terminal to check setup.' + Write-Host ('Deployment logs: ' + (Join-Path $env:LOCALAPPDATA 'ConfigCentral\logs')) + } +} + function Get-SavedMachine { $settingsPath = Join-Path $env:LOCALAPPDATA 'ConfigCentral\settings.json' if (-not (Test-Path -LiteralPath $settingsPath -PathType Leaf)) { return $null } @@ -130,7 +158,14 @@ try { & $windowsPowerShell @arguments $bootstrapExitCode = $LASTEXITCODE - if ($bootstrapExitCode -ne 0) { throw "Bootstrap failed with exit code $bootstrapExitCode." } + if ($bootstrapExitCode -ne 0) { + Write-SetupFailure -ExitCode $bootstrapExitCode + # File execution returns a process exit code. Web execution keeps the + # interactive terminal open and exposes the status through LASTEXITCODE. + if ($MyInvocation.MyCommand.PSObject.Properties['Path']) { exit $bootstrapExitCode } + $global:LASTEXITCODE = $bootstrapExitCode + return + } Write-Host '' Write-Host "Config Central is ready for '$Machine'." diff --git a/tests/Installer.Tests.ps1 b/tests/Installer.Tests.ps1 index e43ede0..da7e80b 100644 --- a/tests/Installer.Tests.ps1 +++ b/tests/Installer.Tests.ps1 @@ -9,6 +9,11 @@ BeforeAll { $node -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq 'Select-ConfigCentralMachine' }, $true) . ([scriptblock]::Create($functionAst.Extent.Text)) + $outcomeAst = $installerAst.Find({ + param($node) + $node -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq 'Write-SetupFailure' + }, $true) + . ([scriptblock]::Create($outcomeAst.Extent.Text)) } Describe 'One-stop installer machine selection' { @@ -80,3 +85,31 @@ Describe 'Setup config replacement policy' { } } } + +Describe 'Friendly setup outcomes' { + BeforeEach { + $script:previousLocalAppData = $env:LOCALAPPDATA + $env:LOCALAPPDATA = $TestDrive + Mock Write-Host {} + } + AfterEach { $env:LOCALAPPDATA = $script:previousLocalAppData } + + It 'explains partial completion without throwing' { + { Write-SetupFailure -ExitCode 5 } | Should -Not -Throw + Should -Invoke Write-Host -ParameterFilter { $Object -like '*Successful changes were kept*' } -Times 1 + Should -Invoke Write-Host -ParameterFilter { $Object -like '*Deployment logs:*' } -Times 1 + } + It 'presents reboot required as completion rather than a failure' { + Write-SetupFailure -ExitCode 6 + Should -Invoke Write-Host -ParameterFilter { $Object -like '*Setup completed*restart*' } -Times 1 + Should -Invoke Write-Host -ParameterFilter { $Object -like '*could not complete*' } -Times 0 + } + It 'gives a retry instruction for an active update' { + Write-SetupFailure -ExitCode 10 + Should -Invoke Write-Host -ParameterFilter { $Object -like '*Wait for it to finish*' } -Times 1 + } + It 'retains unknown error codes in the summary' { + Write-SetupFailure -ExitCode 123 + Should -Invoke Write-Host -ParameterFilter { $Object -like '*exit code 123*' } -Times 1 + } +}