config-central/docs/manifest-contract.md

9.5 KiB

Manifest and CLI contract

Config Central reads version 1 JSON manifests. Profile names map to profiles/<name>.json; machine names map to machines/<name>.json. Unknown fields, unknown profiles, duplicate keys in one manifest, unsupported schema versions, and invalid paths are errors reported before any changes are made.

Profiles are applied in the order listed by a machine. Later profiles override earlier profiles, and the machine manifest overrides every profile. Packages are keyed by the case-insensitive pair source/id; configs are keyed by their case-insensitive name. An override replaces the complete earlier item rather than merging individual fields. An item containing enabled: false removes the inherited item. Duplicate keys within one manifest are rejected.

Package source defaults to winget; update defaults to latest. The update policies are:

  • latest: install when absent and upgrade when WinGet reports an available version. If version is present, it acts like pinned.
  • pinned: require version, install or move to that exact version when WinGet offers it, and leave an already newer version alone with a warning.
  • install-only: install when absent and never upgrade an installed package.

Package state defaults to present. A WinGet package with state: "absent" is uninstalled by exact ID when present and otherwise reported unchanged. This is an explicit removal policy; deleting a package entry still only stops management. Portable rename removal continues to use replaces.

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

cc doctor [-Machine NAME]
cc plan [-Machine NAME] [-ConfigsOnly] [-Json]
cc apply [-Machine NAME] [-ConfigsOnly] [-ForceConfigs] [-Json]
cc sync [-Machine NAME] [-ConfigsOnly] [-ForceConfigs] [-Json]
cc update-software [-Machine NAME] [-Json]
cc software-update [-Machine NAME] [-Json]
cc status [-Machine NAME] [-Json]
cc restore -Config NAME [-Machine NAME] [-Json]
cc schedule [-Machine NAME]
cc unschedule [-Machine NAME]
cc menu [-Machine NAME]

plan and status never mutate packages or deployed configs. apply uses the current checkout. sync fetches its configured remote and runs from a staged snapshot of the resolved commit. Config conflicts require -ForceConfigs, which always makes a backup first. Removing a manifest entry merely stops management. update-software fetches the configured branch and executes itself from an immutable snapshot of the resolved commit, then skips every config. It resolves and applies portable packages first, followed by each declared WinGet package according to its normal policy and exact ID. It never performs an unbounded winget upgrade --all. A release lookup failure is an item failure and does not prevent independent package operations. When the snapshot run finishes, the installed checkout advances to the same revision only when Git can fast-forward it without discarding local work. software-update is a CLI alias normalized to the same command and result name. Interactive software updates show elapsed activity feedback; redirected human output uses one plain status line and JSON output contains no progress text.

schedule registers a limited, interactive-user task at logon. Scheduled runs always use sync -ConfigsOnly; package installation and upgrades remain manual so an unattended task never waits for UAC. unschedule removes that task.

Human output lists the action, item, and explanation. -Json emits one JSON 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, 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 remains available for terminal use. The shortcut under the user's Config Central Start menu folder targets the active GUI executable directly, uses its embedded icon, and is replaced on version changes. An atomically replaced current.json receipt tracks version, archive checksum and installed file hashes. Plan/status inspect these files without downloading or writing. Missing or legacy PowerShell-style shortcuts 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.

Portable packages may declare a displayName and a unique fileAssociations array of lowercase extensions such as [".pdf"]. Associations are registered for the desktop user with application-specific ProgIDs and Default Apps capabilities. Planning detects missing or stale registration, and installation points each open command and icon at the active verified executable. Config Central does not overwrite Windows' protected default-app user choice; the user selects the registered handler once in Windows Settings or Explorer.

An optional repository-relative fileAssociationIcon below assets/ supplies a stable .ico for associated documents. Config Central copies and verifies it in the package root instead of pointing Explorer at a versioned executable icon.

A renamed portable package may declare replaces with the old lowercase source and id, plus any old fileAssociations that must be unregistered. When the predecessor registered itself separately, legacyRegistration names its Registered Applications value and ProgIDs so Config Central can also remove those obsolete Default Apps and Open With entries. This is an explicit removal request. Config Central activates and verifies the new package first, then removes the old managed root, Start menu shortcut, Default Apps registration and listed ProgIDs. Missing or locally modified files in the old active installation stop removal with a warning. Cleanup is retried on the next package run without downloading the new version again. Windows owns the protected default-app choice, so a renamed handler must be selected once under its new name.

Apply downloads and verifies the pinned archive, rejects unsafe ZIP paths and links, stages a new directory, and only then switches the receipt. After activation, older managed version directories are removed. Download, verification, or setup failures retain the previous receipt and working version. Cleanup failures warn and retry without downloading on the next run. Close the application before an update; running instances block replacement. 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 the deterministic pin, 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. A release channel only affects the explicit update-software command.

Portable packages can opt into release discovery for update-software with releaseApi, releaseChannel, assetTemplate, executableTemplate, and an optional checksumAsset (default SHA256SUMS). The API must be an HTTPS Gitea releases endpoint. Templates contain one {version} placeholder and no path separators in the asset template. Channels are stable or prerelease; prerelease follows preview and stable releases, while stable ignores previews. Draft releases, malformed version tags, ambiguous assets, missing or ambiguous checksum entries, cross-host download URLs, and versions older than the manifest pin are rejected. Resolution produces exact URL, checksum, and executable values in memory and never edits the repository manifest.