config-central/docs/manifest-contract.md

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

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

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.