config-central/docs/manifest-contract.md

152 lines
8.8 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` 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.
`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.
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.