122 lines
6.9 KiB
Markdown
122 lines
6.9 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 update-software [-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` uses the current checkout, skips every config, applies normal
|
|
WinGet policies, and resolves opted-in portable packages from their release API
|
|
before planning and installing them. A release lookup failure is an item failure
|
|
and does not prevent independent package operations.
|
|
|
|
`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, automatic release discovery, 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` and a shortcut in the user's Start menu under
|
|
`Config Central` use an atomically replaced `current.json` receipt. Receipts track
|
|
version, archive checksum and installed file hashes. Plan/status inspect these
|
|
files without downloading or writing. Missing files 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.
|
|
|
|
Apply downloads and verifies the pinned archive, rejects unsafe ZIP paths and
|
|
links, stages a new directory, and only then switches the receipt. Old versions
|
|
are retained. Close the application before an update; running instances block
|
|
replacement. Failures retain the previous receipt, and reruns recover incomplete
|
|
installs. 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, 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. Pinning a preview release is explicit consent to
|
|
that release, not permission to follow future prereleases automatically.
|
|
|
|
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.
|