69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|