Register PDF Presenter as a PDF handler
Config Central CI Config Central passed all CI integrity checks.
Beffroi/config-central/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-20 12:52:42 +01:00
parent 52570d57b7
commit a82c4fc8b0
11 changed files with 206 additions and 9 deletions

View File

@ -61,7 +61,17 @@ so a failed activation does not remove the working copy.
PDF Presenter is the first portable release package. The desktop profile follows
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.
with its embedded icon. It is also registered as a per-user PDF handler. After
the first `cc update-software` or full apply, open its Windows Default Apps page:
```powershell
Start-Process 'ms-settings:defaultapps?registeredAppUser=ConfigCentral.idle-org.pdf-presenter'
```
Select PDF Presenter for `.pdf`. On older Windows builds that open the general
Default Apps page, right-click a PDF, choose **Open with → Choose another app**,
select **PDF Presenter**, and enable **Always**. Windows requires this one-time
user confirmation and Config Central preserves that choice across updates.
Like `cc sync`, `update-software` refuses to fetch while the checkout contains
uncommitted or untracked files. It does not reset or overwrite those edits.

View File

@ -156,8 +156,9 @@ open until it is run on disposable machines with the required account setups.
- [x] Validate and resolve portable package declarations alongside WinGet (17 Linux Pester tests pass).
- [x] Implement portable ZIP planning, verified staging, launchers and recovery with Linux Pester tests; keep Windows acceptance below open.
- [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.
- [ ] Validate portable installation, Start menu launch, PDF handler registration/default selection, 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).
- [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).
- [x] Register PDF Presenter as a per-user `.pdf` handler and document the one-time supported Windows Default Apps selection (167 Linux Pester tests pass; Windows acceptance remains open above).

View File

@ -381,6 +381,19 @@ 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.
The package also declares `displayName` and `fileAssociations`, which register
PDF Presenter per user as a `.pdf` handler with Windows Default Apps. The open
command passes the selected PDF directly to the active executable. Windows
requires the user to confirm the protected default-app choice. After applying
the package, open its settings page and select PDF Presenter for `.pdf`:
```powershell
Start-Process 'ms-settings:defaultapps?registeredAppUser=ConfigCentral.idle-org.pdf-presenter'
```
Updates repair the registration to point at the new verified executable without
rewriting the user's default-app preference.
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
are conflicts: inspect and save those changes elsewhere, then remove the affected

View File

@ -102,6 +102,14 @@ 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.
Portable packages may declare a `displayName` and a unique `fileAssociations`
array of lowercase extensions such as `[".pdf"]`. Associations are registered
for the desktop user with application-specific ProgIDs and Default Apps
capabilities. Planning detects missing or stale registration, and installation
points each open command and icon at the active verified executable. Config
Central does not overwrite Windows' protected default-app user choice; the user
selects the registered handler once in Windows Settings or Explorer.
Apply downloads and verifies the pinned archive, rejects unsafe ZIP paths and
links, stages a new directory, and only then switches the receipt. Old versions
are retained. Close the application before an update; running instances block

View File

@ -18,7 +18,9 @@
"releaseChannel": "prerelease",
"assetTemplate": "pdf-presenter-portable-x86_64-pc-windows-gnu-v{version}.zip",
"executableTemplate": "pdf-presenter-portable-x86_64-pc-windows-gnu-v{version}/pdf-presenter.exe",
"checksumAsset": "SHA256SUMS"
"checksumAsset": "SHA256SUMS",
"displayName": "PDF Presenter",
"fileAssociations": [".pdf"]
},
{ "id": "clsid2.mpc-hc", "source": "winget", "scope": "machine", "update": "latest" },
{ "id": "XnSoft.XnViewMP", "source": "winget", "scope": "machine", "update": "latest" },

View File

@ -115,6 +115,21 @@
"type": "string",
"pattern": "^[A-Za-z0-9._+-]+$",
"default": "SHA256SUMS"
},
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[^\\x00-\\x1f]+$"
},
"fileAssociations": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^\\.[a-z0-9]{1,16}$"
}
}
},
"allOf": [
@ -173,6 +188,9 @@
}
},
"dependentRequired": {
"fileAssociations": [
"displayName"
],
"releaseApi": [
"releaseChannel",
"assetTemplate",
@ -217,6 +235,16 @@
"sha256"
]
},
{
"required": [
"displayName"
]
},
{
"required": [
"fileAssociations"
]
},
{
"required": [
"executable"

View File

@ -61,6 +61,17 @@ function Assert-PortableDeclaration {
if ($Item.sha256 -notmatch '^[a-fA-F0-9]{64}$') { throw 'Portable sha256 must contain 64 hex digits.' }
if ($Item.executable -notmatch '^[A-Za-z0-9_-][A-Za-z0-9._/-]*\.exe$' -or @($Item.executable -split '/' | Where-Object { $_ -in @('', '.', '..') -or $_ -match '\.$|^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)' }).Count) { throw 'Unsafe portable executable path.' }
if ($Item.update -notin @('pinned', 'install-only')) { throw 'Portable packages require pinned or install-only updates.' }
$associationProperty = $Item.PSObject.Properties['fileAssociations']
if ($null -ne $associationProperty -and $associationProperty.Value -isnot [Array]) { throw 'Portable fileAssociations must be an array.' }
$associations = @(if ($null -ne $associationProperty) { $associationProperty.Value })
if ($associations.Count) {
$displayName = [string](Get-OptionalProperty $Item 'displayName')
if ([string]::IsNullOrWhiteSpace($displayName) -or $displayName.Length -gt 64 -or $displayName -match '[\x00-\x1f]') { throw 'Portable file associations require a safe displayName of at most 64 characters.' }
$seenAssociations = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
foreach ($extension in $associations) {
if ($extension -cnotmatch '^\.[a-z0-9]{1,16}$' -or -not $seenAssociations.Add($extension)) { throw "Invalid or duplicate portable file association '$extension'." }
}
}
$releaseFields = @('releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate')
$hasReleaseField = [bool]($releaseFields | Where-Object { $null -ne $Item.PSObject.Properties[$_] })
@ -99,7 +110,7 @@ function Assert-ItemList {
if ($Kind -eq 'package') {
Assert-AllowedProperties $item @(
'id', 'source', 'scope', 'version', 'update', 'enabled', 'provider', 'url', 'sha256', 'executable',
'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset'
'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset', 'displayName', 'fileAssociations'
) "$Location[$index]"
if ([string]::IsNullOrWhiteSpace([string](Get-OptionalProperty $item 'id'))) { throw "$Location[$index].id is required." }
$source = [string](Get-OptionalProperty $item 'source' 'winget')
@ -110,7 +121,7 @@ function Assert-ItemList {
$key = "portable/$key"
Assert-PortableDeclaration $item $source
}
elseif (@('url', 'sha256', 'executable', 'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset') | Where-Object { $null -ne $item.PSObject.Properties[$_] }) { throw 'Portable fields cannot be used by WinGet packages.' }
elseif (@('url', 'sha256', 'executable', 'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset', 'displayName', 'fileAssociations') | Where-Object { $null -ne $item.PSObject.Properties[$_] }) { throw 'Portable fields cannot be used by WinGet packages.' }
$scope = Get-OptionalProperty $item 'scope'
if ($null -ne $scope -and $scope -notin @('user', 'machine')) { throw "Invalid package scope at $Location[$index]." }
$update = [string](Get-OptionalProperty $item 'update' 'latest')
@ -181,10 +192,13 @@ function Add-ManifestItems {
$normalized = [ordered]@{ id = [string]$item.id; source = $source; update = [string](Get-OptionalProperty $item 'update' 'latest') }
foreach ($field in @(
'scope', 'version', 'provider', 'url', 'sha256', 'executable',
'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset'
'releaseApi', 'releaseChannel', 'assetTemplate', 'executableTemplate', 'checksumAsset', 'displayName', 'fileAssociations'
)) {
$value = Get-OptionalProperty $item $field
if ($null -ne $value) { $normalized[$field] = [string]$value }
if ($null -ne $value) {
if ($field -eq 'fileAssociations') { $normalized[$field] = [object[]]@($value) }
else { $normalized[$field] = [string]$value }
}
}
}
else {

View File

@ -53,6 +53,73 @@ function Test-PortableLegacyLauncher {
(Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant() -in $script:LegacyPortableLauncherHashes
}
function Get-PortableAssociationSpec {
param($Package, [Parameter(Mandatory)][string]$Executable)
if (-not $Package.PSObject.Properties['fileAssociations']) { return @() }
$registeredName = "ConfigCentral.$($Package.source).$($Package.id)"
$capabilitiesPath = "Software\ConfigCentral\Applications\$($Package.source)\$($Package.id)\Capabilities"
foreach ($extension in @($Package.fileAssociations)) {
$suffix = $extension.TrimStart('.').ToLowerInvariant()
[pscustomobject]@{
extension = $extension.ToLowerInvariant()
registeredName = $registeredName
capabilitiesPath = $capabilitiesPath
progId = "$registeredName.$suffix"
displayName = [string]$Package.displayName
description = "$($Package.displayName) $($suffix.ToUpperInvariant()) document"
executable = [IO.Path]::GetFullPath($Executable)
}
}
}
function Get-PortableRegistryValue {
param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][AllowEmptyString()][string]$Name)
$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($Path, $false)
if ($null -eq $key) { return $null }
try { return $key.GetValue($Name, $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) }
finally { $key.Dispose() }
}
function Set-PortableRegistryValue {
param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][AllowEmptyString()][string]$Name, [Parameter(Mandatory)][AllowEmptyString()][string]$Value)
$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($Path, $true)
if ($null -eq $key) { throw "Cannot create per-user registration key 'HKCU:\$Path'." }
try { $key.SetValue($Name, $Value, [Microsoft.Win32.RegistryValueKind]::String) }
finally { $key.Dispose() }
}
function Test-PortableFileAssociations {
param($Package, [Parameter(Mandatory)][string]$Executable)
$specs = @(Get-PortableAssociationSpec -Package $Package -Executable $Executable)
if (-not $specs.Count) { return $true }
if (-not $IsWindows) { return $false }
foreach ($spec in $specs) {
$command = '"' + $spec.executable + '" "%1"'
if ((Get-PortableRegistryValue 'Software\RegisteredApplications' $spec.registeredName) -ne $spec.capabilitiesPath -or
(Get-PortableRegistryValue $spec.capabilitiesPath 'ApplicationName') -ne $spec.displayName -or
(Get-PortableRegistryValue "$($spec.capabilitiesPath)\FileAssociations" $spec.extension) -ne $spec.progId -or
(Get-PortableRegistryValue "Software\Classes\$($spec.progId)" '') -ne $spec.description -or
(Get-PortableRegistryValue "Software\Classes\$($spec.progId)\DefaultIcon" '') -ne "$($spec.executable),0" -or
(Get-PortableRegistryValue "Software\Classes\$($spec.progId)\shell\open\command" '') -ne $command -or
$null -eq (Get-PortableRegistryValue "Software\Classes\$($spec.extension)\OpenWithProgids" $spec.progId)) { return $false }
}
return $true
}
function Set-PortableFileAssociations {
param($Package, [Parameter(Mandatory)][string]$Executable)
foreach ($spec in @(Get-PortableAssociationSpec -Package $Package -Executable $Executable)) {
Set-PortableRegistryValue 'Software\RegisteredApplications' $spec.registeredName $spec.capabilitiesPath
Set-PortableRegistryValue $spec.capabilitiesPath 'ApplicationName' $spec.displayName
Set-PortableRegistryValue $spec.capabilitiesPath 'ApplicationDescription' "Open supported documents with $($spec.displayName)."
Set-PortableRegistryValue "$($spec.capabilitiesPath)\FileAssociations" $spec.extension $spec.progId
Set-PortableRegistryValue "Software\Classes\$($spec.progId)" '' $spec.description
Set-PortableRegistryValue "Software\Classes\$($spec.progId)\DefaultIcon" '' "$($spec.executable),0"
Set-PortableRegistryValue "Software\Classes\$($spec.progId)\shell\open\command" '' ('"' + $spec.executable + '" "%1"')
Set-PortableRegistryValue "Software\Classes\$($spec.extension)\OpenWithProgids" $spec.progId ''
}
}
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 }
@ -161,10 +228,11 @@ function Get-PortablePackagePlan {
else { $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 (-not (Test-PortableFileAssociations -Package $Package -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, launcher, or shortcut'
$reason = 'Repair missing portable installation files, launcher, shortcut, or file associations'
}
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)" }
@ -305,12 +373,14 @@ function Invoke-PortablePackageOperation {
[IO.File]::Move((Join-Path $staging 'launch.ps1'), $paths.Launcher, $true)
$installedExecutable = Join-Path $destination $package.executable
Set-PortableShortcut -Paths $paths -Executable $installedExecutable
Set-PortableFileAssociations -Package $package -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'
$receipt | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $temporary -Encoding utf8NoBOM
[IO.File]::Move($temporary, $paths.Receipt, $true)
[pscustomobject]@{ name = $plan.name; status = 'Succeeded'; rebootRequired = $false; exitCode = 0; message = "Installed portable version $($package.version); previous versions retained" }
$associationMessage = if ($package.PSObject.Properties['fileAssociations']) { "; registered for $(@($package.fileAssociations) -join ', ') (choose it once in Windows Default Apps)" } else { '' }
[pscustomobject]@{ name = $plan.name; status = 'Succeeded'; rebootRequired = $false; exitCode = 0; message = "Installed portable version $($package.version); previous versions retained$associationMessage" }
}
catch {
[pscustomobject]@{ name = $Operation.name; status = 'Failed'; rebootRequired = $false; exitCode = 1; message = $_.Exception.Message }

View File

@ -23,6 +23,9 @@ Describe 'Manifest resolution' {
$presenter.provider | Should -Be 'portable'
$presenter.scope | Should -Be 'user'
$presenter.update | Should -Be 'pinned'
$presenter.displayName | Should -Be 'PDF Presenter'
($presenter.fileAssociations -is [Array]) | Should -BeTrue
$presenter.fileAssociations | Should -Be @('.pdf')
$result.packages.id | Should -Not -Contain 'cpvalente.ontime'
}

View File

@ -14,6 +14,8 @@ Describe 'Portable package lifecycle' {
Mock Assert-PortablePlatform {}
Mock Assert-PortableStopped {}
Mock Test-PortableShortcut { Test-Path -LiteralPath $Path -PathType Leaf }
Mock Test-PortableFileAssociations { $true }
Mock Set-PortableFileAssociations {}
Mock Set-PortableShortcut {
[void][IO.Directory]::CreateDirectory((Split-Path -Parent $Paths.Shortcut))
[IO.File]::WriteAllText($Paths.Shortcut, 'mock shortcut')
@ -62,6 +64,16 @@ Describe 'Portable package lifecycle' {
$plan.action | Should -Be 'Install'
$plan.reason | Should -Match 'shortcut'
}
It 'registers declared file handlers and repairs missing registration' {
$package | Add-Member displayName 'Test Presenter'
$package | Add-Member fileAssociations @('.pdf')
Mock Test-PortableFileAssociations { $false }
(Invoke-PortablePackageOperation (Get-PortablePackagePlan $package $root)).status | Should -Be 'Succeeded'
Should -Invoke Set-PortableFileAssociations -Times 1 -Exactly -ParameterFilter {
$Package.id -eq 'presenter' -and $Executable -like '*bundle*app.exe'
}
(Get-PortablePackagePlan $package $root).reason | Should -Match 'file associations'
}
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))
@ -202,6 +214,32 @@ Describe 'Standalone portable shortcut' {
}
}
Describe 'Portable file association registration' {
InModuleScope PortablePackages {
It 'builds a stable per-user PDF handler around the active executable' {
$package = [pscustomobject]@{ id = 'pdf-presenter'; source = 'idle-org'; displayName = 'PDF Presenter'; fileAssociations = @('.pdf') }
$spec = Get-PortableAssociationSpec -Package $package -Executable "$TestDrive/app/pdf-presenter.exe"
$spec.registeredName | Should -Be 'ConfigCentral.idle-org.pdf-presenter'
$spec.progId | Should -Be 'ConfigCentral.idle-org.pdf-presenter.pdf'
$spec.capabilitiesPath | Should -Be 'Software\ConfigCentral\Applications\idle-org\pdf-presenter\Capabilities'
$spec.extension | Should -Be '.pdf'
}
It 'writes a quoted PDF open command and per-user Default Apps registration' {
$package = [pscustomobject]@{ id = 'pdf-presenter'; source = 'idle-org'; displayName = 'PDF Presenter'; fileAssociations = @('.pdf') }
$executable = [IO.Path]::GetFullPath("$TestDrive/path with spaces/pdf-presenter.exe")
Mock Set-PortableRegistryValue {}
Set-PortableFileAssociations -Package $package -Executable $executable
Should -Invoke Set-PortableRegistryValue -Times 8 -Exactly
Should -Invoke Set-PortableRegistryValue -Times 1 -Exactly -ParameterFilter {
$Path -eq 'Software\RegisteredApplications' -and $Name -eq 'ConfigCentral.idle-org.pdf-presenter'
}
Should -Invoke Set-PortableRegistryValue -Times 1 -Exactly -ParameterFilter {
$Path -like '*\shell\open\command' -and $Name -eq '' -and $Value -eq ('"' + $executable + '" "%1"')
}
}
}
}
Describe 'Portable launcher presentation' {
It 'reports missing receipts concisely with a failing process exit code' {
$launcher = Join-Path $TestDrive 'launch.ps1'

View File

@ -15,4 +15,14 @@ Describe 'Published manifest schemas' {
$profile.packages[0].scope = 'machine'
$profile | ConvertTo-Json -Depth 8 | Test-Json -SchemaFile $schema -ErrorAction SilentlyContinue | Should -BeFalse
}
It 'requires a display name and safe extensions for portable file handlers' {
$schema = "$PSScriptRoot/../schemas/profile.schema.json"
$package = [ordered]@{ id = 'app'; provider = 'portable'; source = 'example'; version = '1.0'; update = 'pinned'; url = 'https://example.org/app.zip'; executable = 'app.exe'; sha256 = 'a' * 64; fileAssociations = @('.pdf') }
$profile = [ordered]@{ schemaVersion = 1; name = 'test'; packages = @($package) }
$profile | ConvertTo-Json -Depth 8 | Test-Json -SchemaFile $schema -ErrorAction SilentlyContinue | Should -BeFalse
$package.displayName = 'Example App'
$profile | ConvertTo-Json -Depth 8 | Test-Json -SchemaFile $schema | Should -BeTrue
$package.fileAssociations = @('pdf')
$profile | ConvertTo-Json -Depth 8 | Test-Json -SchemaFile $schema -ErrorAction SilentlyContinue | Should -BeFalse
}
}