From d86b77642507a4dc66687bdacbe2833a72f8a3e8 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 20 Nov 2026 08:11:03 +0100 Subject: [PATCH] Define pinned portable package contract --- TASKS.md | 8 ++++++++ docs/manifest-contract.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/TASKS.md b/TASKS.md index eb02689..2230380 100644 --- a/TASKS.md +++ b/TASKS.md @@ -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. diff --git a/docs/manifest-contract.md b/docs/manifest-contract.md index f354649..73f1ddc 100644 --- a/docs/manifest-contract.md +++ b/docs/manifest-contract.md @@ -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 `/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 +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.