diff --git a/TASKS.md b/TASKS.md index d7188f7..a0b1e4a 100644 --- a/TASKS.md +++ b/TASKS.md @@ -158,3 +158,4 @@ open until it is run on disposable machines with the required account setups. - [x] Add the verified PDF Presenter 0.1.33 release to the desktop profile and document updates; validate archive/executable hashes and run the Linux suite (136 passed, 5 Windows-only skips). - [ ] Validate portable installation, Start menu launch and running-app handling on disposable Windows x64. - [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). diff --git a/docs/advanced_commands.md b/docs/advanced_commands.md index 2bde318..25759ca 100644 --- a/docs/advanced_commands.md +++ b/docs/advanced_commands.md @@ -371,9 +371,10 @@ To review and advance the deterministic repository pin: Default files live under `%LOCALAPPDATA%\ConfigCentral\apps\idle-org\pdf-presenter`. `launch.ps1` is the -stable launcher; the Start menu shortcut is under `Config Central\idle-org`. -`current.json` records the active version and hashes. Older version directories -are retained, and removing the profile entry does not uninstall anything. +stable terminal launcher; the Start menu shortcut under `Config Central\idle-org` +targets `pdf-presenter.exe` directly and uses its embedded icon. `current.json` +records the active version and hashes. Older version directories are retained, +and removing the profile entry does not uninstall anything. On a failed download, checksum check or setup step, fix the reported cause and retry. Missing managed files are repaired. Locally changed binaries or launchers diff --git a/docs/manifest-contract.md b/docs/manifest-contract.md index f932abb..05ad342 100644 --- a/docs/manifest-contract.md +++ b/docs/manifest-contract.md @@ -88,10 +88,12 @@ script hooks, or elevation are supported. Installations live under `/apps//`, normally under `%LOCALAPPDATA%/ConfigCentral`. Each successful install has its own version -folder. A stable `launch.ps1` and a shortcut in the user's Start menu under -`Config Central` use an atomically replaced `current.json` receipt. Receipts track -version, archive checksum and installed file hashes. Plan/status inspect these -files without downloading or writing. Missing files are repaired; modified +folder. A stable `launch.ps1` remains available for terminal use. The shortcut +under the user's `Config Central` Start menu folder targets the active GUI +executable directly, uses its embedded icon, and is replaced on version changes. +An atomically replaced `current.json` receipt tracks version, archive checksum +and installed file hashes. Plan/status inspect these files without downloading +or writing. Missing or legacy PowerShell-style shortcuts are repaired; modified managed files are conflicts and must be inspected before retrying. Settings and extra files are not managed or copied between versions; portable applications must store persistent settings outside their installation directory. diff --git a/src/PortablePackages.psm1 b/src/PortablePackages.psm1 index 260e8e9..f8bb29d 100644 --- a/src/PortablePackages.psm1 +++ b/src/PortablePackages.psm1 @@ -1,5 +1,9 @@ Set-StrictMode -Version Latest +$script:LegacyPortableLauncherHashes = @( + '644e2a37e75a4297bceba8da2605f5edffd12ad8adfde1bb244b3baa7fdd1f91' +) + function Assert-PortableRelativePath { param([string]$Path) if (-not $Path -or $Path -match '[\\:<>"|?*\x00-\x1f]' -or $Path.StartsWith('/')) { throw "Unsafe portable path '$Path'." } @@ -44,6 +48,11 @@ function Get-PortableLauncherContent { Get-Content -LiteralPath (Join-Path $PSScriptRoot 'portable-launcher.ps1') -Raw } +function Test-PortableLegacyLauncher { + param([Parameter(Mandatory)][string]$Path) + (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant() -in $script:LegacyPortableLauncherHashes +} + function Invoke-PortableReleaseRequest { param([Parameter(Mandatory)][string]$Uri, [Parameter(Mandatory)][ValidateSet('Json', 'Text')][string]$Kind) try { $response = Invoke-WebRequest -Uri $Uri -MaximumRedirection 5 -ErrorAction Stop } @@ -144,14 +153,18 @@ function Get-PortablePackagePlan { } if (Test-Path -LiteralPath $paths.Launcher) { Assert-PortableNoLinks $paths.Launcher - if ([IO.File]::ReadAllText($paths.Launcher) -cne (Get-PortableLauncherContent)) { throw "Locally modified launcher '$($paths.Launcher)'; inspect it before retrying." } + if ([IO.File]::ReadAllText($paths.Launcher) -cne (Get-PortableLauncherContent)) { + if (Test-PortableLegacyLauncher -Path $paths.Launcher) { $missing = $true } + else { throw "Locally modified launcher '$($paths.Launcher)'; inspect it before retrying." } + } } else { $missing = $true } - if ($paths.Shortcut -and -not (Test-Path -LiteralPath $paths.Shortcut)) { $missing = $true } + $activeExecutable = Join-Path $paths.Root "$($receipt.directory)/$($receipt.executable)" + if ($paths.Shortcut -and -not (Test-PortableShortcut -Path $paths.Shortcut -Executable $activeExecutable)) { $missing = $true } if ($receipt.version -eq $Package.version -and $receipt.sha256 -ne $Package.sha256) { throw 'Archive checksum changed without a version change; publish a new version before retrying.' } if ($missing) { if ($receipt.version -ne $Package.version -and ($Package.update -eq 'install-only' -or [version]$receipt.version -gt [version]$Package.version)) { throw 'Installed files are missing; pin the installed version to repair it without changing update policy.' } - $reason = 'Repair missing portable installation files or launcher' + $reason = 'Repair missing portable installation files, launcher, or shortcut' } elseif ($Package.update -eq 'install-only') { $action = 'None'; $reason = "Installed ($($receipt.version)); install-only policy" } elseif ([version]$receipt.version -gt [version]$Package.version) { $action = 'Warning'; $reason = "Installed $($receipt.version) is newer than requested $($Package.version)" } @@ -198,18 +211,51 @@ function Assert-PortableStopped { } } +function New-PortableShortcutShell { + New-Object -ComObject WScript.Shell +} + +function Get-PortableShortcutDetails { + param([Parameter(Mandatory)][string]$Path) + $shell = New-PortableShortcutShell + $shortcut = $shell.CreateShortcut($Path) + [pscustomobject]@{ + TargetPath = [string]$shortcut.TargetPath + Arguments = [string]$shortcut.Arguments + WorkingDirectory = [string]$shortcut.WorkingDirectory + IconLocation = [string]$shortcut.IconLocation + } +} + +function Test-PortableShortcut { + param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$Executable) + if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $false } + try { + Assert-PortableNoLinks $Path + $details = Get-PortableShortcutDetails -Path $Path + $target = [IO.Path]::GetFullPath($details.TargetPath) + $expected = [IO.Path]::GetFullPath($Executable) + return [string]::Equals($target, $expected, [StringComparison]::OrdinalIgnoreCase) -and + [string]::IsNullOrWhiteSpace($details.Arguments) + } + catch { return $false } +} + function Set-PortableShortcut { - param($Paths) + param($Paths, [Parameter(Mandatory)][string]$Executable) if (-not $Paths.Shortcut) { throw 'The desktop user Start menu directory is unavailable.' } + if (-not (Test-Path -LiteralPath $Executable -PathType Leaf)) { throw "Portable shortcut target is missing: '$Executable'." } Assert-PortableNoLinks $Paths.Shortcut [void][IO.Directory]::CreateDirectory((Split-Path -Parent $Paths.Shortcut)) $temporary = "$($Paths.Shortcut).$([guid]::NewGuid().ToString('N')).lnk" try { - $shell = New-Object -ComObject WScript.Shell + $shell = New-PortableShortcutShell $shortcut = $shell.CreateShortcut($temporary) - $shortcut.TargetPath = Join-Path $PSHOME 'pwsh.exe' - $shortcut.Arguments = '-NoLogo -NoProfile -ExecutionPolicy Bypass -File "' + $Paths.Launcher + '"' - $shortcut.WorkingDirectory = $Paths.Root + $shortcut.TargetPath = $Executable + $shortcut.Arguments = '' + $shortcut.WorkingDirectory = Split-Path -Parent $Executable + $shortcut.IconLocation = "$Executable,0" + $shortcut.Description = 'Managed by Config Central' $shortcut.Save() [IO.File]::Move($temporary, $Paths.Shortcut, $true) } @@ -254,12 +300,11 @@ function Invoke-PortablePackageOperation { Assert-PortableNoLinks $destination [void][IO.Directory]::CreateDirectory((Split-Path -Parent $destination)) [IO.Directory]::Move($expanded, $destination) - # Launcher content is constant across versions. Leave existing launchers intact. - if (-not (Test-Path -LiteralPath $paths.Launcher)) { - [IO.File]::WriteAllText((Join-Path $staging 'launch.ps1'), (Get-PortableLauncherContent)) - [IO.File]::Move((Join-Path $staging 'launch.ps1'), $paths.Launcher) - } - Set-PortableShortcut $paths + # Planning rejects unknown launcher edits; current and known legacy copies can be replaced safely. + [IO.File]::WriteAllText((Join-Path $staging 'launch.ps1'), (Get-PortableLauncherContent)) + [IO.File]::Move((Join-Path $staging 'launch.ps1'), $paths.Launcher, $true) + $installedExecutable = Join-Path $destination $package.executable + Set-PortableShortcut -Paths $paths -Executable $installedExecutable Assert-PortableStopped $paths.Root $receipt = [ordered]@{ schemaVersion = 1; version = $package.version; sha256 = $package.sha256; directory = $directory; executable = $package.executable; files = $files } $temporary = Join-Path $staging 'current.json' diff --git a/tests/PortablePackages.Tests.ps1 b/tests/PortablePackages.Tests.ps1 index 271e0e7..a763f19 100644 --- a/tests/PortablePackages.Tests.ps1 +++ b/tests/PortablePackages.Tests.ps1 @@ -13,6 +13,7 @@ Describe 'Portable package lifecycle' { Mock Get-PortableProgramsPath { Join-Path $root 'test-programs' } Mock Assert-PortablePlatform {} Mock Assert-PortableStopped {} + Mock Test-PortableShortcut { Test-Path -LiteralPath $Path -PathType Leaf } Mock Set-PortableShortcut { [void][IO.Directory]::CreateDirectory((Split-Path -Parent $Paths.Shortcut)) [IO.File]::WriteAllText($Paths.Shortcut, 'mock shortcut') @@ -54,6 +55,23 @@ Describe 'Portable package lifecycle' { (Get-PortablePackagePlan $package $root).action | Should -Be 'Conflict' (Invoke-PortablePackageOperation (Get-PortablePackagePlan $package $root)).status | Should -Be 'Conflict' } + It 'repairs a legacy PowerShell shortcut on the next apply' { + [void](Invoke-PortablePackageOperation (Get-PortablePackagePlan $package $root)) + Mock Test-PortableShortcut { $false } + $plan = Get-PortablePackagePlan $package $root + $plan.action | Should -Be 'Install' + $plan.reason | Should -Match 'shortcut' + } + It 'migrates the previous managed launcher without treating it as a local edit' { + $paths = Get-PortablePaths $package $root + [void](Invoke-PortablePackageOperation (Get-PortablePackagePlan $package $root)) + [IO.File]::WriteAllText($paths.Launcher, 'previous managed launcher') + Mock Test-PortableLegacyLauncher { $true } + $plan = Get-PortablePackagePlan $package $root + $plan.action | Should -Be 'Install' + (Invoke-PortablePackageOperation $plan).status | Should -Be 'Succeeded' + [IO.File]::ReadAllText($paths.Launcher) | Should -BeExactly (Get-PortableLauncherContent) + } It 'keeps the active receipt on checksum or shortcut failure and recovers on retry' { $paths = Get-PortablePaths $package $root [void](Invoke-PortablePackageOperation (Get-PortablePackagePlan $package $root)) @@ -140,6 +158,50 @@ Describe 'Portable package lifecycle' { } } +Describe 'Standalone portable shortcut' { + InModuleScope PortablePackages { + It 'targets the GUI executable directly and uses its embedded icon' { + $root = Join-Path $TestDrive 'standalone shortcut' + [void][IO.Directory]::CreateDirectory("$root/app") + $executable = Join-Path $root 'app/presenter.exe' + [IO.File]::WriteAllText($executable, 'gui') + $paths = [pscustomobject]@{ Root = $root; Shortcut = Join-Path $root 'menu/presenter.lnk' } + $script:shortcutObject = [pscustomobject]@{ + TargetPath = ''; Arguments = 'old'; WorkingDirectory = ''; IconLocation = ''; Description = ''; TemporaryPath = '' + } + $script:shortcutObject | Add-Member -MemberType ScriptMethod -Name Save -Value { + [IO.File]::WriteAllText($this.TemporaryPath, 'shortcut') + } + $script:shell = [pscustomobject]@{} + $script:shell | Add-Member -MemberType ScriptMethod -Name CreateShortcut -Value { + param($path) + $script:shortcutObject.TemporaryPath = $path + return $script:shortcutObject + } + Mock New-PortableShortcutShell { $script:shell } + Set-PortableShortcut -Paths $paths -Executable $executable + $script:shortcutObject.TargetPath | Should -Be $executable + $script:shortcutObject.Arguments | Should -BeNullOrEmpty + $script:shortcutObject.WorkingDirectory | Should -Be (Split-Path -Parent $executable) + $script:shortcutObject.IconLocation | Should -Be "$executable,0" + $script:shortcutObject.Description | Should -Be 'Managed by Config Central' + Test-Path $paths.Shortcut | Should -BeTrue + } + + It 'recognizes only argument-free shortcuts to the active executable' { + $executable = Join-Path $TestDrive 'active/app.exe' + [void][IO.Directory]::CreateDirectory((Split-Path -Parent $executable)) + [IO.File]::WriteAllText($executable, 'gui') + $shortcut = Join-Path $TestDrive 'app.lnk' + [IO.File]::WriteAllText($shortcut, 'shortcut') + Mock Get-PortableShortcutDetails { [pscustomobject]@{ TargetPath = $executable; Arguments = ''; WorkingDirectory = ''; IconLocation = '' } } + Test-PortableShortcut -Path $shortcut -Executable $executable | Should -BeTrue + Mock Get-PortableShortcutDetails { [pscustomobject]@{ TargetPath = (Join-Path $PSHOME 'pwsh.exe'); Arguments = '-File launch.ps1'; WorkingDirectory = ''; IconLocation = '' } } + Test-PortableShortcut -Path $shortcut -Executable $executable | Should -BeFalse + } + } +} + Describe 'Portable launcher presentation' { It 'reports missing receipts concisely with a failing process exit code' { $launcher = Join-Path $TestDrive 'launch.ps1'