Define pinned portable package contract

This commit is contained in:
Dandaedre 2026-11-20 08:11:03 +01:00
parent c0bd86cdb3
commit d86b776425
2 changed files with 45 additions and 0 deletions

View File

@ -149,3 +149,11 @@ open until it is run on disposable machines with the required account setups.
- [x] Add capture/apply adapters for Windows sound-event assignments and the active plan's battery display timeout, with constrained declarations, backups, drift detection, and rollback; validate with Linux mocks.
- [x] Enable the Windows sound/power defaults in desktop profiles and document the capture/update workflow.
- [x] Clarify when to use install versus the faster config-only update in the README.
## Portable software
- [x] Document portable package identity, pinning, storage and recovery semantics.
- [ ] Validate and resolve portable package declarations alongside WinGet.
- [ ] 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.

View File

@ -66,3 +66,40 @@ document suitable for automation. Exit codes are stable: `0` success/no drift,
`2` invalid command or manifest, `3` prerequisite failure, `4` conflicts or
pending drift from `status`, `5` an operation failed, `6` reboot required, and
`10` another apply is running.
## Portable ZIP packages
Packages may set `provider: "portable"` (the default remains `winget`). Portable
identity is `portable/source/id`; existing WinGet identity stays `source/id`.
Later profiles and machine overrides replace the entire item with that identity;
`enabled: false` needs only provider, source and ID. Portable source and ID are
lowercase slugs, independent of WinGet sources.
Enabled portable entries require `version` (numeric dotted version), `url`
(HTTPS ZIP), `sha256` (64 hex digits), `executable` (relative forward-slash path
inside the ZIP ending in .exe), and `update: "pinned"` or `"install-only"`.
Only user scope and Windows x64 are supported initially. No installer commands,
script hooks, automatic release discovery, or elevation are supported.
Installations live under `<DataRoot>/apps/<source>/<id>`, 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
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.
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
replacement. Failures retain the previous receipt, and reruns recover incomplete
installs. A newer installed version is left alone with a warning. Changing the
archive hash without changing its version is rejected. Removing the manifest
entry does not remove files or shortcuts. Config-only runs skip these packages.
To update, review a release, verify its archive against the publisher's checksum,
and commit its version, exact URL, SHA-256 and executable path together. The next
full sync applies that version. Pinning a preview release is explicit consent to
that release, not permission to follow future prereleases automatically.