From 0ba08e53ec88db6134fe51fcfc0de9d0c47dd5a5 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 16 Oct 2026 14:33:29 +0200 Subject: [PATCH] Document desktop application configuration --- README.md | 14 +++-- TASKS.md | 8 +-- docs/desktop-app-configs.md | 106 +++++++++++++++++++++++++++++++++ docs/manifest-contract.md | 14 +++-- tools/Export-MpcHcSettings.ps1 | 41 +++++++++++++ 5 files changed, 171 insertions(+), 12 deletions(-) create mode 100644 docs/desktop-app-configs.md create mode 100644 tools/Export-MpcHcSettings.ps1 diff --git a/README.md b/README.md index b55e526..969181f 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,11 @@ Put source files below `configs/`. Config targets accept `%APPDATA%`, The complete schema, precedence rules, package policies, and exit codes are in [the manifest contract](docs/manifest-contract.md). +MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have +application-specific safety rules. See the +[desktop application configuration guide](docs/desktop-app-configs.md) before +populating those declarations. + ## Daily commands ```powershell @@ -120,10 +125,11 @@ an existing file it has never managed, or a locally deleted managed file is a conflict. Normal apply leaves the destination alone. `-ForceConfigs` makes a timestamped backup and then deploys the repository version. -`cc restore -Config NAME` restores the newest backup and first backs up the file -being replaced. Removing a config from a manifest stops managing it; it does not -delete the destination. Removing a package stops managing it; it does not -uninstall software. +`cc restore -Config NAME` restores the newest whole-file or INI backup and first +backs up the file being replaced. Registry and hosts backups require deliberate +manual restoration from an administrator shell. Removing a config from a +manifest stops managing it; it does not delete the destination. Removing a +package stops managing it; it does not uninstall software. User state is stored under `%LOCALAPPDATA%\ConfigCentral`: diff --git a/TASKS.md b/TASKS.md index 8bf5322..4978f52 100644 --- a/TASKS.md +++ b/TASKS.md @@ -104,8 +104,8 @@ open until it is run on disposable machines with the required account setups. - [x] Add WinGet packages for MPC-HC, Ontime, XnView MP, and Nextcloud Desktop. - [x] Add a safe registry-value adapter for MPC-HC settings. -- [ ] Manage Ontime user settings without treating projects, uploads, or logs as config. -- [ ] Manage XnView MP preferences without committing its catalog or thumbnails. -- [ ] Add safe Nextcloud preconfiguration without committing account credentials. +- [x] Manage Ontime user settings without treating projects, uploads, or logs as config. +- [x] Manage XnView MP preferences without committing its catalog or thumbnails. +- [x] Add safe Nextcloud preconfiguration without committing account credentials. - [x] Manage a marked block in the Windows hosts file through the elevated worker. -- [ ] Document how to capture and customize the application-specific values. +- [x] Document how to capture and customize the application-specific values. diff --git a/docs/desktop-app-configs.md b/docs/desktop-app-configs.md new file mode 100644 index 0000000..c8f8255 --- /dev/null +++ b/docs/desktop-app-configs.md @@ -0,0 +1,106 @@ +# Desktop application configuration + +The `desktop-apps` profile installs MPC-HC, Ontime, XnView MP, and Nextcloud +Desktop and declares their safe configuration surfaces. Close an application +before applying its config so it does not immediately overwrite the result. + +The checked-in declarations start as safe no-ops or comment-only files. Populate +only the values you want shared across every selected machine. + +## MPC-HC + +MPC-HC normally stores preferences below +`HKCU\Software\MPC-HC\MPC-HC`. Config Central applies only values listed in +`configs/mpc-hc/settings.json`; it does not delete other values or registry keys. + +On the machine whose settings should be the baseline, close MPC-HC and run: + +```powershell +pwsh -File .\tools\Export-MpcHcSettings.ps1 +``` + +The exporter omits history, favorites, recent files, URLs, and common path-like +values by default. Review the generated JSON anyway before committing it. Remove +any value that is machine-specific. `-IncludePrivateValues` exists for deliberate +local export work, but its output should almost never be committed. + +## Ontime + +The profile manages Ontime's supported CSS override at +`%APPDATA%\Ontime\user\styles\override.css`. Edit +`configs/ontime/override.css` to define the shared presentation. + +Ontime stores projects, uploads, logs, crash data, its database, and volatile +`app-state.json` beneath `%APPDATA%\Ontime`. Config Central leaves those files +alone. In particular, `app-state.json` contains the active project, rundown, +server port, and session health, so copying it between machines would be wrong. + +## XnView MP + +The profile overlays keys from `configs/xnviewmp/xnview.ini` onto +`%APPDATA%\XnViewMP\xnview.ini`. Unlisted sections and keys remain untouched, +including the catalog and thumbnail databases. + +Use **Settings > Integration > Paths > Open Config Files Location** in XnView MP +to locate the active INI file. Copy only portable sections and keys into the +repository overlay. Some XnView installations use an additional `settings` +subdirectory or portable mode; override the `xnviewmp-settings` target in that +machine's manifest when its displayed path differs. + +Avoid sharing catalog paths, recent folders, database locations, or other values +that name a local drive. + +## Nextcloud Desktop + +Nextcloud's Windows configuration file is +`%APPDATA%\Nextcloud\nextcloud.cfg`. The profile uses an INI overlay from +`configs/nextcloud/managed.ini`, so account sections and other unlisted keys stay +untouched. + +Never commit the full `nextcloud.cfg`: it contains account and authentication +material. Add only documented, non-secret preferences to `managed.ini`. Account +setup should remain interactive. To prefill a first-run wizard without storing a +password, Nextcloud supports commands such as: + +```powershell +& 'C:\Program Files\Nextcloud\nextcloud.exe' ` + --overrideserverurl 'https://cloud.example.com' ` + --overridelocaldir 'D:/Nextcloud' +``` + +The local folder is commonly machine-specific, so this command is not run by the +shared profile. + +## Windows hosts file + +Add entries to `configs/windows/hosts.entries`: + +```text +192.0.2.10 service.example.test +2001:db8::10 service-v6.example.test alias.example.test +``` + +Config Central validates every active line, requests elevation, backs up the +hosts file, and owns only this marked section: + +```text +# BEGIN CONFIG CENTRAL: windows-hosts +... +# END CONFIG CENTRAL: windows-hosts +``` + +Lines outside that block are preserved. A comment-only declaration is a no-op. + +## Applying changes + +Run `cc plan` first. Existing unmanaged values are reported as conflicts rather +than overwritten. Once the repository version is correct, use: + +```powershell +cc apply -ForceConfigs +``` + +Forced file and hosts updates are backed up under +`%LOCALAPPDATA%\ConfigCentral\backups`. Registry backups contain only the values +managed by the declaration. Inspect and commit each source file separately so no +history, credentials, tokens, or machine-specific paths enter Git. diff --git a/docs/manifest-contract.md b/docs/manifest-contract.md index 0e060c3..f354649 100644 --- a/docs/manifest-contract.md +++ b/docs/manifest-contract.md @@ -25,13 +25,19 @@ An unavailable requested version, unsupported installer scope, ambiguous inventory, or unknown installed version becomes a failed package operation with the WinGet diagnostics preserved. Configs requiring that package are skipped. -Config mode is currently `copy`. Sources are repository-relative files and must -remain below `configs/` after canonicalization. Targets may be absolute Windows -paths and may use `%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, or -`%PROGRAMDATA%`. Expansion uses the original desktop user's captured paths. +Config modes are `copy`, `ini-overlay`, `registry`, and `hosts-block`. Sources +are repository-relative files and must remain below `configs/` after +canonicalization. File targets may be absolute Windows paths and may use +`%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, `%PROGRAMDATA%`, or +`%SYSTEMROOT%`. Expansion uses the original desktop user's captured paths. Unknown variables, relative targets, colliding destinations, and sources escaping the repository are errors. Target comparisons are case-insensitive. +An INI overlay owns only the sections and keys declared in its source. Registry +mode accepts typed JSON values and is constrained to the MPC-HC HKCU subtree. +Hosts mode validates entries and owns one named marker block in the Windows hosts +file; changes use the elevated worker. Empty adapter declarations are no-ops. + The commands are: ```text diff --git a/tools/Export-MpcHcSettings.ps1 b/tools/Export-MpcHcSettings.ps1 new file mode 100644 index 0000000..df833f9 --- /dev/null +++ b/tools/Export-MpcHcSettings.ps1 @@ -0,0 +1,41 @@ +[CmdletBinding()] +param( + [string]$OutputPath = (Join-Path $PSScriptRoot '..\configs\mpc-hc\settings.json'), + [switch]$IncludePrivateValues +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +$rootPath = 'HKCU:\Software\MPC-HC\MPC-HC' +if (-not (Test-Path -LiteralPath $rootPath)) { throw "MPC-HC registry settings were not found at '$rootPath'. Start MPC-HC and save its settings first." } + +$root = Get-Item -LiteralPath $rootPath +$excludedSubkeys = '(?i)(^|\\)(MediaHistory|Recent File List|Favorites)(\\|$)' +$excludedValues = '(?i)(path|directory|folder|filename|lastopen|lastused|recent|url)' +$values = [Collections.Generic.List[object]]::new() + +foreach ($key in @($root) + @(Get-ChildItem -LiteralPath $rootPath -Recurse)) { + $relativePath = $key.Name.Substring($root.Name.Length).TrimStart('\') + if (-not $IncludePrivateValues -and $relativePath -match $excludedSubkeys) { continue } + foreach ($name in $key.GetValueNames()) { + if ([string]::IsNullOrWhiteSpace($name)) { continue } + if (-not $IncludePrivateValues -and $name -match $excludedValues) { continue } + $kind = [string]$key.GetValueKind($name) + if ($kind -notin @('String', 'ExpandString', 'DWord', 'QWord', 'MultiString', 'Binary')) { continue } + $raw = $key.GetValue($name, $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames) + $value = switch ($kind) { + 'Binary' { @([byte[]]$raw) } + 'MultiString' { @([string[]]$raw) } + default { $raw } + } + $values.Add([ordered]@{ path = $relativePath; name = $name; type = $kind; value = $value }) + } +} + +$document = [ordered]@{ schemaVersion = 1; values = @($values | Sort-Object path, name) } +$fullOutputPath = [IO.Path]::GetFullPath($OutputPath) +[void](New-Item -ItemType Directory -Path (Split-Path -Parent $fullOutputPath) -Force) +$document | ConvertTo-Json -Depth 16 | Set-Content -LiteralPath $fullOutputPath -Encoding utf8NoBOM +Write-Host "Exported $($values.Count) MPC-HC values to '$fullOutputPath'." +Write-Warning 'Review the file for machine-specific paths or private history before committing it.'