diff --git a/TASKS.md b/TASKS.md index 2230380..20a04e4 100644 --- a/TASKS.md +++ b/TASKS.md @@ -153,7 +153,7 @@ open until it is run on disposable machines with the required account setups. ## Portable software - [x] Document portable package identity, pinning, storage and recovery semantics. -- [ ] Validate and resolve portable package declarations alongside WinGet. +- [x] Validate and resolve portable package declarations alongside WinGet (17 Linux Pester tests pass). - [ ] Implement portable ZIP planning, verified staging, launchers and recovery with focused tests. - [ ] Add the verified PDF Presenter release to the desktop profile and document updates. - [ ] Validate portable installation, Start menu launch and running-app handling on disposable Windows x64. diff --git a/schemas/profile.schema.json b/schemas/profile.schema.json index 8355fc8..52a3b70 100644 --- a/schemas/profile.schema.json +++ b/schemas/profile.schema.json @@ -4,19 +4,33 @@ "title": "Config Central profile", "type": "object", "additionalProperties": false, - "required": ["schemaVersion", "name"], + "required": [ + "schemaVersion", + "name" + ], "properties": { - "schemaVersion": { "const": 1 }, - "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, - "description": { "type": "string" }, + "schemaVersion": { + "const": 1 + }, + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]*$" + }, + "description": { + "type": "string" + }, "packages": { "type": "array", - "items": { "$ref": "#/$defs/package" }, + "items": { + "$ref": "#/$defs/package" + }, "default": [] }, "configs": { "type": "array", - "items": { "$ref": "#/$defs/config" }, + "items": { + "$ref": "#/$defs/config" + }, "default": [] } }, @@ -24,33 +38,202 @@ "package": { "type": "object", "additionalProperties": false, - "required": ["id"], + "required": [ + "id" + ], "properties": { - "id": { "type": "string", "minLength": 1 }, - "source": { "type": "string", "minLength": 1, "default": "winget" }, - "scope": { "enum": ["user", "machine"] }, - "version": { "type": "string", "minLength": 1 }, - "update": { "enum": ["latest", "pinned", "install-only"], "default": "latest" }, - "enabled": { "type": "boolean", "default": true } - } + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "default": "winget" + }, + "scope": { + "enum": [ + "user", + "machine" + ] + }, + "version": { + "type": "string", + "minLength": 1 + }, + "update": { + "enum": [ + "latest", + "pinned", + "install-only" + ], + "default": "latest" + }, + "enabled": { + "type": "boolean", + "default": true + }, + "provider": { + "enum": [ + "winget", + "portable" + ], + "default": "winget" + }, + "url": { + "type": "string", + "pattern": "^https://[^\\s]+\\.zip(\\?[^\\s]*)?$" + }, + "sha256": { + "type": "string", + "pattern": "^[a-fA-F0-9]{64}$" + }, + "executable": { + "type": "string", + "pattern": "^[A-Za-z0-9_-][A-Za-z0-9._/-]*\\.exe$" + } + }, + "allOf": [ + { + "if": { + "properties": { + "provider": { + "const": "portable" + } + }, + "required": [ + "provider" + ] + }, + "then": { + "properties": { + "id": { + "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" + }, + "source": { + "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" + }, + "scope": { + "const": "user" + } + }, + "allOf": [ + { + "if": { + "properties": { + "enabled": { + "const": false + } + }, + "required": [ + "enabled" + ] + }, + "else": { + "required": [ + "version", + "url", + "sha256", + "executable", + "update" + ], + "properties": { + "version": { + "pattern": "^\\d+\\.\\d+(\\.\\d+){0,2}$" + }, + "update": { + "enum": [ + "pinned", + "install-only" + ] + } + } + } + } + ] + }, + "else": { + "not": { + "anyOf": [ + { + "required": [ + "url" + ] + }, + { + "required": [ + "sha256" + ] + }, + { + "required": [ + "executable" + ] + } + ] + } + } + } + ] }, "config": { "type": "object", "additionalProperties": false, - "required": ["name"], + "required": [ + "name" + ], "properties": { - "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, - "source": { "type": "string", "minLength": 1 }, - "target": { "type": "string", "minLength": 1 }, - "mode": { "enum": ["copy", "ini-overlay", "registry", "hosts-block", "windows-sounds", "windows-power"], "default": "copy" }, - "requiresPackage": { "type": "string", "minLength": 1 }, - "enabled": { "type": "boolean", "default": true } + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]*$" + }, + "source": { + "type": "string", + "minLength": 1 + }, + "target": { + "type": "string", + "minLength": 1 + }, + "mode": { + "enum": [ + "copy", + "ini-overlay", + "registry", + "hosts-block", + "windows-sounds", + "windows-power" + ], + "default": "copy" + }, + "requiresPackage": { + "type": "string", + "minLength": 1 + }, + "enabled": { + "type": "boolean", + "default": true + } }, "allOf": [ { - "if": { "properties": { "enabled": { "const": false } }, "required": ["enabled"] }, + "if": { + "properties": { + "enabled": { + "const": false + } + }, + "required": [ + "enabled" + ] + }, "then": {}, - "else": { "required": ["source", "target"] } + "else": { + "required": [ + "source", + "target" + ] + } } ] } diff --git a/src/Manifest.psm1 b/src/Manifest.psm1 index 8d963ca..cd06836 100644 --- a/src/Manifest.psm1 +++ b/src/Manifest.psm1 @@ -45,6 +45,23 @@ function Get-OptionalProperty { return $property.Value } +function Assert-PortableDeclaration { + param($Item, [string]$Source) + if ($Source -cnotmatch '^[a-z0-9][a-z0-9-]{0,63}$' -or $Item.id -cnotmatch '^[a-z0-9][a-z0-9-]{0,63}$') { throw 'Portable source and id must be lowercase slugs.' } + if ((Get-OptionalProperty $Item 'scope' 'user') -ne 'user') { throw 'Portable packages require user scope.' } + if (-not (Get-OptionalProperty $Item 'enabled' $true)) { return } + foreach ($field in @('version', 'url', 'sha256', 'executable', 'update')) { + if ([string]::IsNullOrWhiteSpace([string](Get-OptionalProperty $Item $field))) { throw "Portable package requires $field." } + } + $parsed = $null + if ($Item.version -notmatch '^\d+\.\d+(\.\d+){0,2}$' -or -not [version]::TryParse($Item.version, [ref]$parsed)) { throw 'Portable version must be a numeric dotted version.' } + $uri = $null + if (-not [uri]::TryCreate($Item.url, [UriKind]::Absolute, [ref]$uri) -or $uri.Scheme -ne 'https' -or $uri.UserInfo -or $uri.Fragment -or $uri.AbsolutePath -notlike '*.zip') { throw 'Portable URL must be an HTTPS ZIP URL without credentials or fragment.' } + 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.' } +} + function Assert-ItemList { param($Items, [ValidateSet('package', 'config')][string]$Kind, [string]$Location) if ($null -eq $Items) { return } @@ -54,10 +71,17 @@ function Assert-ItemList { $index = 0 foreach ($item in $Items) { if ($Kind -eq 'package') { - Assert-AllowedProperties $item @('id', 'source', 'scope', 'version', 'update', 'enabled') "$Location[$index]" + Assert-AllowedProperties $item @('id', 'source', 'scope', 'version', 'update', 'enabled', 'provider', 'url', 'sha256', 'executable') "$Location[$index]" if ([string]::IsNullOrWhiteSpace([string](Get-OptionalProperty $item 'id'))) { throw "$Location[$index].id is required." } $source = [string](Get-OptionalProperty $item 'source' 'winget') $key = "$source/$($item.id)" + $provider = Get-OptionalProperty $item 'provider' 'winget' + if ($provider -notin @('winget', 'portable')) { throw 'Unknown package provider.' } + if ($provider -eq 'portable') { + $key = "portable/$key" + Assert-PortableDeclaration $item $source + } + elseif (@('url', 'sha256', 'executable') | 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') @@ -118,6 +142,7 @@ function Add-ManifestItems { if ($Kind -eq 'package') { $source = [string](Get-OptionalProperty $item 'source' 'winget') $key = "$source/$($item.id)".ToLowerInvariant() + if ((Get-OptionalProperty $item 'provider' 'winget') -eq 'portable') { $key = "portable/$key" } } else { $key = ([string]$item.name).ToLowerInvariant() } $enabled = [bool](Get-OptionalProperty $item 'enabled' $true) @@ -125,7 +150,7 @@ function Add-ManifestItems { if ($Kind -eq 'package') { $normalized = [ordered]@{ id = [string]$item.id; source = $source; update = [string](Get-OptionalProperty $item 'update' 'latest') } - foreach ($field in @('scope', 'version')) { + foreach ($field in @('scope', 'version', 'provider', 'url', 'sha256', 'executable')) { $value = Get-OptionalProperty $item $field if ($null -ne $value) { $normalized[$field] = [string]$value } } diff --git a/tests/PortableManifest.Tests.ps1 b/tests/PortableManifest.Tests.ps1 new file mode 100644 index 0000000..fdc77e7 --- /dev/null +++ b/tests/PortableManifest.Tests.ps1 @@ -0,0 +1,46 @@ +Import-Module "$PSScriptRoot/../src/Manifest.psm1" -Force +Describe 'Portable declarations' { + InModuleScope Manifest { + BeforeEach { + $item = [pscustomobject]@{ id = 'presenter'; provider = 'portable'; source = 'gitea'; version = '1.2.3'; update = 'pinned'; url = 'https://example.org/app.zip'; sha256 = ('a' * 64); executable = 'bundle/app.exe' } + } + It 'normalizes portable fields and keeps provider identities separate' { + Assert-ItemList @($item) package test + $items = [ordered]@{} + Add-ManifestItems $items @($item, [pscustomobject]@{ id = 'presenter'; source = 'gitea' }) package + $items.Count | Should -Be 2 + $items['portable/gitea/presenter'].executable | Should -Be 'bundle/app.exe' + Add-ManifestItems $items @([pscustomobject]@{ id = 'presenter'; source = 'gitea'; provider = 'portable'; enabled = $false }) package + $items.Count | Should -Be 1 + $items.Contains('gitea/presenter') | Should -BeTrue + } + It 'replaces the entire portable item with a later override' { + $items = [ordered]@{} + Add-ManifestItems $items @($item) package + $item.version = '2.0' + Add-ManifestItems $items @($item) package + $items.Count | Should -Be 1 + $items['portable/gitea/presenter'].version | Should -Be '2.0' + } + It 'rejects unsafe or unsupported declarations' -ForEach @( + @{ Field = 'executable'; Value = '../app.exe' } + @{ Field = 'executable'; Value = 'C:/app.exe' } + @{ Field = 'executable'; Value = 'con/app.exe' } + @{ Field = 'url'; Value = 'http://example.org/app.zip' } + @{ Field = 'url'; Value = 'https://user:secret@example.org/app.zip' } + @{ Field = 'sha256'; Value = 'bad' } + @{ Field = 'scope'; Value = 'machine' } + @{ Field = 'update'; Value = 'latest' } + @{ Field = 'version'; Value = '../1.0' } + @{ Field = 'provider'; Value = 'script' } + ) { + $item | Add-Member -NotePropertyName $Field -NotePropertyValue $Value -Force + { Assert-ItemList @($item) package test } | Should -Throw + } + It 'rejects duplicate portable entries and WinGet download fields' { + { Assert-ItemList @($item, $item) package test } | Should -Throw '*Duplicate*' + $item.provider = 'winget' + { Assert-ItemList @($item) package test } | Should -Throw '*Portable fields*' + } + } +}