Document desktop application configuration

This commit is contained in:
Dandaedre 2026-10-16 14:33:29 +02:00
parent 32549e0fe8
commit 0ba08e53ec
5 changed files with 171 additions and 12 deletions

View File

@ -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`:

View File

@ -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.

106
docs/desktop-app-configs.md Normal file
View File

@ -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.

View File

@ -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

View File

@ -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.'