diff --git a/README.md b/README.md index 1edfa0e..2b401df 100644 --- a/README.md +++ b/README.md @@ -33,18 +33,25 @@ user, and run: cc update-software ``` -This command updates software selected by the current machine manifest without -deploying any configs. It runs operations sequentially in this order: +This command updates Config Central and the software selected by the machine +manifest without deploying any configs. It runs operations in this order: -1. Resolve and apply opted-in portable packages. Config Central selects the +1. Fetch the configured repository branch and run the rest of the command from + an immutable snapshot of that exact commit. This gives the update the latest + Config Central code and software policy without replacing a running script. +2. Resolve and apply opted-in portable packages. Config Central selects the newest release allowed by the package's channel, downloads its exact Windows asset, verifies it against the release's published SHA-256 checksum, stages it in a new version directory, and switches to it only after setup succeeds. -2. Install or upgrade every declared WinGet package by exact ID and source, +3. Install or upgrade every declared WinGet package by exact ID and source, according to its `latest`, `pinned`, or `install-only` policy. Applications not declared in Config Central are left alone; the command does not run an unrestricted `winget upgrade --all`. +After the snapshot finishes, Config Central fast-forwards its installed checkout +to that same revision so later `cc` commands use the updated CLI. A checkout that +has diverged is preserved and reported as a failed self-update. + Machine-scope WinGet operations may request administrator approval. Config Central preserves installer diagnostics, continues independent packages after an item failure, reports reboot requirements, and never restarts Windows. Close @@ -56,8 +63,8 @@ its preview channel, verifies `SHA256SUMS`, and creates a Start menu shortcut at Start → Config Central → idle-org that launches `pdf-presenter.exe` directly with its embedded icon. -`update-software` uses the current repository checkout and does not fetch new -Config Central policy. Run `cc sync` first when the repository itself has changed. +Like `cc sync`, `update-software` refuses to fetch while the checkout contains +uncommitted or untracked files. It does not reset or overwrite those edits. For the release declaration and manual pin-review workflow, see [portable package updates](docs/advanced_commands.md#portable-package-updates). diff --git a/TASKS.md b/TASKS.md index beeadef..2d53fbf 100644 --- a/TASKS.md +++ b/TASKS.md @@ -160,3 +160,4 @@ open until it is run on disposable machines with the required account setups. - [x] Add `update-software` with checksum-verified Gitea release discovery and package-only execution; validate against the live PDF Presenter feed and run the Linux suite (155 passed, 5 Windows-only skips). - [x] Launch portable GUI packages directly from Start menu shortcuts with their embedded icons; repair legacy PowerShell-target shortcuts on the next apply (159 Linux Pester tests pass; Windows acceptance remains open above). - [x] Run portable release updates before declared WinGet updates in `update-software` and document the complete workflow in the README. +- [x] Refresh Config Central from an immutable remote snapshot before `update-software` applies portable and declared WinGet updates (163 Linux Pester tests pass; 5 Windows-only skips). diff --git a/docs/advanced_commands.md b/docs/advanced_commands.md index a860142..e8ace5f 100644 --- a/docs/advanced_commands.md +++ b/docs/advanced_commands.md @@ -125,9 +125,9 @@ A failed download makes no deployment changes. Partial deployment failures are reported; rerun after correcting the reported problem. The downloaded code runs with your account's permissions, so use a repository you trust. -The installed `cc` continues to use its existing local checkout. To refresh that -checkout and its CLI for advanced work, rerun setup (use `-SkipApply` if -you only want to refresh tooling). The web updater itself needs no such refresh. +The web updater leaves the installed `cc` checkout unchanged. Run +`cc update-software` to refresh the CLI and installed software, or rerun setup +with `-SkipApply` when you only want to repair the checkout and launcher. ## Define profiles and machines @@ -180,7 +180,7 @@ populating those declarations. cc plan # show intended work; change nothing cc apply # apply the current checkout cc sync # fetch and apply an immutable remote snapshot -cc update-software # update declared software; skip all configs +cc update-software # refresh cc, then update declared software cc status # show drift and the last run cc sync -ConfigsOnly # fetch and deploy configs; do not call WinGet cc apply -ForceConfigs # back up local edits, then replace them @@ -348,15 +348,19 @@ To update installed software, close PDF Presenter and run: cc update-software ``` -The command checks the Gitea releases API for opted-in portable packages first, -then asks WinGet to apply each declared package's policy by exact ID. PDF -Presenter follows the newest eligible preview or stable release. Unmanaged -WinGet applications are left alone. Configs are not planned or changed. +The command fetches the configured repository branch and continues from an +immutable snapshot of that commit, so the current run uses the latest Config +Central code and policy. It then checks the Gitea releases API for opted-in +portable packages and asks WinGet to apply each declared package's policy by +exact ID. PDF Presenter follows the newest eligible preview or stable release. +Unmanaged WinGet applications are left alone. Configs are not planned or changed. Each release lookup resolves one exact ZIP, reads its exact entry from `SHA256SUMS`, and verifies the downloaded archive before activation. A lookup or checksum failure is reported for that package while independent packages -continue. The command uses the current checkout; use `cc sync` first when you -also need newer repository policy. +continue. As with `sync`, local checkout changes must be committed or removed +before the fetch; Config Central never discards them automatically. After the +software run, the installed checkout is advanced to the resolved commit with a +fast-forward-only merge so subsequent `cc` commands use the refreshed version. To review and advance the deterministic repository pin: diff --git a/docs/manifest-contract.md b/docs/manifest-contract.md index acb8b91..cadd1e6 100644 --- a/docs/manifest-contract.md +++ b/docs/manifest-contract.md @@ -57,11 +57,14 @@ cc menu [-Machine NAME] current checkout. `sync` fetches its configured remote and runs from a staged snapshot of the resolved commit. Config conflicts require `-ForceConfigs`, which always makes a backup first. Removing a manifest entry merely stops management. -`update-software` uses the current checkout and skips every config. It resolves -and applies portable packages first, then installs or upgrades each declared -WinGet package according to its normal policy and exact ID. It never performs an -unbounded `winget upgrade --all`. A release lookup failure is an item failure and -does not prevent independent package operations. +`update-software` fetches the configured branch and executes itself from an +immutable snapshot of the resolved commit, then skips every config. It resolves +and applies portable packages first, followed by each declared WinGet package +according to its normal policy and exact ID. It never performs an unbounded +`winget upgrade --all`. A release lookup failure is an item failure and does not +prevent independent package operations. When the snapshot run finishes, the +installed checkout advances to the same revision only when Git can fast-forward +it without discarding local work. `schedule` registers a limited, interactive-user task at logon. Scheduled runs always use `sync -ConfigsOnly`; package installation and upgrades remain manual diff --git a/src/Core.psm1 b/src/Core.psm1 index 43d3c09..582e95e 100644 --- a/src/Core.psm1 +++ b/src/Core.psm1 @@ -138,15 +138,15 @@ function Invoke-ApplyPlan { finally { Exit-ApplyLock -Lock $lock -Paths $Paths } } -function Invoke-SnapshotApply { - param([string]$Snapshot, [string]$Machine, $Paths, [string]$Revision, [switch]$ConfigsOnly, [switch]$ForceConfigs) - $arguments = @('-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', (Join-Path $Snapshot 'cc.ps1'), 'apply', '-Machine', $Machine, '-DataRoot', $Paths.Root, '-RepositoryRoot', $Snapshot, '-Revision', $Revision, '-FromSnapshot', '-Json') +function Invoke-SnapshotCommand { + param([string]$Snapshot, [string]$Machine, $Paths, [string]$Revision, [ValidateSet('apply', 'update-software')][string]$Command, [switch]$ConfigsOnly, [switch]$ForceConfigs) + $arguments = @('-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', (Join-Path $Snapshot 'cc.ps1'), $Command, '-Machine', $Machine, '-DataRoot', $Paths.Root, '-RepositoryRoot', $Snapshot, '-Revision', $Revision, '-FromSnapshot', '-Json') if ($ConfigsOnly) { $arguments += '-ConfigsOnly' } if ($ForceConfigs) { $arguments += '-ForceConfigs' } $text = & pwsh.exe @arguments $exitCode = $LASTEXITCODE try { $child = ($text -join [Environment]::NewLine) | ConvertFrom-Json -Depth 32 } - catch { throw "Snapshot apply returned invalid output (exit $exitCode): $($text -join [Environment]::NewLine)" } + catch { throw "Snapshot command returned invalid output (exit $exitCode): $($text -join [Environment]::NewLine)" } return $child } @@ -191,12 +191,25 @@ function Invoke-ConfigCentral { $settings = Read-JsonState -Path $Paths.Settings -Default ([ordered]@{}) $remoteRevision = Resolve-RemoteRevision -RepositoryRoot $RepositoryRoot -Settings $settings $snapshot = New-RepositorySnapshot -RepositoryRoot $RepositoryRoot -Revision $remoteRevision -Paths $Paths - return Invoke-SnapshotApply -Snapshot $snapshot -Machine $Machine -Paths $Paths -Revision $remoteRevision -ConfigsOnly:$ConfigsOnly -ForceConfigs:$ForceConfigs + return Invoke-SnapshotCommand -Snapshot $snapshot -Machine $Machine -Paths $Paths -Revision $remoteRevision -Command apply -ConfigsOnly:$ConfigsOnly -ForceConfigs:$ForceConfigs } if ($Command -eq 'update-software') { if ($ConfigsOnly -or $ForceConfigs) { throw 'update-software does not accept config options.' } - if ($FromSnapshot) { throw 'update-software cannot run as a snapshot child.' } + if (-not $FromSnapshot) { + $settings = Read-JsonState -Path $Paths.Settings -Default ([ordered]@{}) + $remoteRevision = Resolve-RemoteRevision -RepositoryRoot $RepositoryRoot -Settings $settings + $snapshot = New-RepositorySnapshot -RepositoryRoot $RepositoryRoot -Revision $remoteRevision -Paths $Paths + $result = Invoke-SnapshotCommand -Snapshot $snapshot -Machine $Machine -Paths $Paths -Revision $remoteRevision -Command update-software + try { $selfUpdate = Update-RepositoryCheckout -RepositoryRoot $RepositoryRoot -Revision $remoteRevision } + catch { + $selfUpdate = [pscustomobject]@{ name = 'Config Central'; status = 'Failed'; message = $_.Exception.Message } + $result.succeeded = $false + $result.exitCode = 5 + } + $result.operations = @($selfUpdate) + @($result.operations) + return $result + } if ([string]::IsNullOrWhiteSpace($Revision)) { $Revision = Get-RepositoryRevision -RepositoryRoot $RepositoryRoot } $softwarePlan = Get-SoftwareUpdatePlan -Machine $Machine -RepositoryRoot $RepositoryRoot -Paths $Paths return Invoke-ApplyPlan -Plan $softwarePlan -Machine $Machine -RepositoryRoot $RepositoryRoot -Paths $Paths -Revision $Revision -Command 'update-software' diff --git a/src/Repository.psm1 b/src/Repository.psm1 index 90b3184..afaddf9 100644 --- a/src/Repository.psm1 +++ b/src/Repository.psm1 @@ -60,6 +60,21 @@ function New-RepositorySnapshot { } } +function Update-RepositoryCheckout { + param([Parameter(Mandatory)][string]$RepositoryRoot, [Parameter(Mandatory)][string]$Revision) + if ($Revision -notmatch '^[0-9a-f]{40,64}$') { throw "Invalid checkout revision '$Revision'." } + if (Test-RepositoryDirty -RepositoryRoot $RepositoryRoot) { throw 'Repository changed during the update; commit or remove local changes before retrying.' } + $current = Get-RepositoryRevision -RepositoryRoot $RepositoryRoot + if ($current -eq $Revision) { + return [pscustomobject]@{ name = 'Config Central'; status = 'Unchanged'; message = "Already at revision $Revision" } + } + try { [void](Invoke-Git -RepositoryRoot $RepositoryRoot -Arguments @('merge', '--ff-only', $Revision)) } + catch { throw "Config Central ran from revision $Revision, but its checkout could not be fast-forwarded. Resolve local branch divergence and retry. $($_.Exception.Message)" } + $updated = Get-RepositoryRevision -RepositoryRoot $RepositoryRoot + if ($updated -ne $Revision) { throw "Config Central checkout stopped at unexpected revision '$updated'." } + [pscustomobject]@{ name = 'Config Central'; status = 'Succeeded'; message = "Updated checkout from $current to $Revision" } +} + function Save-ConfigCentralSettings { param([Parameter(Mandatory)]$Paths, [Parameter(Mandatory)][string]$RepositoryUrl, [Parameter(Mandatory)][string]$Branch, [Parameter(Mandatory)][string]$Machine) $settings = [ordered]@{ @@ -78,4 +93,4 @@ function Save-ConfigCentralSettings { return $settings } -Export-ModuleMember -Function Invoke-Git, Get-RepositoryRevision, Test-RepositoryDirty, Resolve-RemoteRevision, New-RepositorySnapshot, Save-ConfigCentralSettings +Export-ModuleMember -Function Invoke-Git, Get-RepositoryRevision, Test-RepositoryDirty, Resolve-RemoteRevision, New-RepositorySnapshot, Update-RepositoryCheckout, Save-ConfigCentralSettings diff --git a/tests/Cli.Tests.ps1 b/tests/Cli.Tests.ps1 index 1baf64e..eaeaac0 100644 --- a/tests/Cli.Tests.ps1 +++ b/tests/Cli.Tests.ps1 @@ -20,7 +20,7 @@ Describe 'Software update CLI' { It 'recognizes update-software as a command' { $output = & (Join-Path $PSHOME $(if ($IsWindows) { 'pwsh.exe' } else { 'pwsh' })) -NoProfile -File "$PSScriptRoot/../cc.ps1" update-software -Machine missing-test-machine -DataRoot "$TestDrive/software-data" 2>&1 $LASTEXITCODE | Should -Be 2 - ($output | Out-String) | Should -Match 'Missing machine manifest' + ($output | Out-String) | Should -Match 'No repository branch is configured' ($output | Out-String) | Should -Not -Match 'ValidateSet|Cannot validate argument' } } diff --git a/tests/Core.Tests.ps1 b/tests/Core.Tests.ps1 index 0bce93c..a4907d2 100644 --- a/tests/Core.Tests.ps1 +++ b/tests/Core.Tests.ps1 @@ -159,15 +159,51 @@ Describe 'Software update command' { } } - It 'runs package-only work under the update-software command name' { + It 'refreshes Config Central and runs update-software from the remote snapshot' { InModuleScope Core -Parameters @{ Working = $TestDrive } { - Mock Get-RepositoryRevision { 'abc' } + Mock Read-JsonState { @{ branch = 'main' } } + Mock Resolve-RemoteRevision { 'remote-revision' } + Mock New-RepositorySnapshot { "$Working/snapshot" } + Mock Invoke-SnapshotCommand { [pscustomobject]@{ command = $Command; revision = $Revision; operations = @(); succeeded = $true; exitCode = 0 } } + Mock Update-RepositoryCheckout { [pscustomobject]@{ name = 'Config Central'; status = 'Succeeded'; message = 'Updated' } } + $paths = Get-ConfigCentralPaths -DataRoot "$Working/software-refresh" + $result = Invoke-ConfigCentral -Command update-software -Machine test -Paths $paths -RepositoryRoot $Working + $result.command | Should -Be 'update-software' + $result.revision | Should -Be 'remote-revision' + $result.operations[0].name | Should -Be 'Config Central' + Should -Invoke Resolve-RemoteRevision -Times 1 -Exactly + Should -Invoke New-RepositorySnapshot -Times 1 -Exactly -ParameterFilter { $Revision -eq 'remote-revision' } + Should -Invoke Invoke-SnapshotCommand -Times 1 -Exactly -ParameterFilter { $Command -eq 'update-software' -and $Revision -eq 'remote-revision' } + Should -Invoke Update-RepositoryCheckout -Times 1 -Exactly -ParameterFilter { $Revision -eq 'remote-revision' } + } + } + + It 'reports a self-update failure without hiding completed software results' { + InModuleScope Core -Parameters @{ Working = $TestDrive } { + Mock Read-JsonState { @{ branch = 'main' } } + Mock Resolve-RemoteRevision { 'remote-revision' } + Mock New-RepositorySnapshot { "$Working/snapshot" } + Mock Invoke-SnapshotCommand { [pscustomobject]@{ command = $Command; revision = $Revision; operations = @([pscustomobject]@{ name = 'App'; status = 'Succeeded' }); succeeded = $true; exitCode = 0 } } + Mock Update-RepositoryCheckout { throw 'Branch diverged' } + $paths = Get-ConfigCentralPaths -DataRoot "$Working/software-refresh-failure" + $result = Invoke-ConfigCentral -Command update-software -Machine test -Paths $paths -RepositoryRoot $Working + $result.succeeded | Should -BeFalse + $result.exitCode | Should -Be 5 + $result.operations.name | Should -Be @('Config Central', 'App') + $result.operations[0].message | Should -Match 'Branch diverged' + } + } + + It 'runs package-only work inside the refreshed snapshot' { + InModuleScope Core -Parameters @{ Working = $TestDrive } { + Mock Resolve-RemoteRevision { throw 'Snapshot child must not fetch' } Mock Get-SoftwareUpdatePlan { [pscustomobject]@{ packages = @(); configs = @(); state = @{ schemaVersion = 1; configs = @{} } } } Mock Invoke-ApplyPlan { [pscustomobject]@{ command = $Command; succeeded = $true; exitCode = 0 } } $paths = Get-ConfigCentralPaths -DataRoot "$Working/software-command" - $result = Invoke-ConfigCentral -Command update-software -Machine test -Paths $paths -RepositoryRoot $Working + $result = Invoke-ConfigCentral -Command update-software -Machine test -Paths $paths -RepositoryRoot $Working -FromSnapshot -Revision abc $result.command | Should -Be 'update-software' Should -Invoke Invoke-ApplyPlan -Times 1 -Exactly -ParameterFilter { $Command -eq 'update-software' } + Should -Invoke Resolve-RemoteRevision -Times 0 } } diff --git a/tests/Repository.Tests.ps1 b/tests/Repository.Tests.ps1 index b4dd6b5..2b42bd6 100644 --- a/tests/Repository.Tests.ps1 +++ b/tests/Repository.Tests.ps1 @@ -4,6 +4,28 @@ BeforeAll { } Describe 'Repository synchronization' { + It 'fast-forwards the checkout to the resolved revision' { + InModuleScope Repository { + $script:revisionChecks = 0 + Mock Test-RepositoryDirty { $false } + Mock Get-RepositoryRevision { $script:revisionChecks++; if ($script:revisionChecks -eq 1) { 'a' * 40 } else { 'b' * 40 } } + Mock Invoke-Git { [pscustomobject]@{ exitCode = 0; output = '' } } + $result = Update-RepositoryCheckout -RepositoryRoot 'C:\repo' -Revision ('b' * 40) + $result.status | Should -Be 'Succeeded' + Should -Invoke Invoke-Git -Times 1 -Exactly -ParameterFilter { $Arguments -join ' ' -eq ('merge --ff-only ' + ('b' * 40)) } + } + } + + It 'does not touch an already current checkout' { + InModuleScope Repository { + Mock Test-RepositoryDirty { $false } + Mock Get-RepositoryRevision { 'a' * 40 } + Mock Invoke-Git { throw 'Git merge must not run' } + (Update-RepositoryCheckout -RepositoryRoot 'C:\repo' -Revision ('a' * 40)).status | Should -Be 'Unchanged' + Should -Invoke Invoke-Git -Times 0 + } + } + It 'rejects unsafe branch names before fetching' { { Resolve-RemoteRevision -RepositoryRoot $TestDrive -Settings @{ branch = '../main' } } | Should -Throw '*Unsafe branch*' }