Define configuration manifest contract

This commit is contained in:
Dandaedre 2026-10-16 13:44:31 +02:00
parent 6498342e41
commit 6c19178550
9 changed files with 203 additions and 7 deletions

View File

@ -5,18 +5,18 @@ Complete the core CLI and manual workflow before optional automation or a TUI.
## 1. Define manifests and command contracts
- [ ] Define and document versioned JSON schemas for profiles and machines.
- [ ] Specify profile ordering, override precedence, disabled entries, duplicate
- [x] Define and document versioned JSON schemas for profiles and machines.
- [x] Specify profile ordering, override precedence, disabled entries, duplicate
handling, and validation errors.
- [ ] Define package fields: ID, source, optional scope/version, and update policy.
- [x] Define package fields: ID, source, optional scope/version, and update policy.
Specify behavior for unavailable versions and already-newer installations.
- [ ] Define config fields: name, repository source, destination, copy mode, and
- [x] Define config fields: name, repository source, destination, copy mode, and
optional package dependency.
- [ ] Define supported path variables, source containment checks, and destination
- [x] Define supported path variables, source containment checks, and destination
collision handling.
- [ ] Add example base/development profiles and a machine manifest using clearly
- [x] Add example base/development profiles and a machine manifest using clearly
documented sample choices.
- [ ] Specify command options, plan output, conflict handling, and exit codes.
- [x] Specify command options, plan output, conflict handling, and exit codes.
## 2. Build the CLI foundation

4
configs/git/.gitconfig Normal file
View File

@ -0,0 +1,4 @@
[core]
autocrlf = true
[init]
defaultBranch = main

View File

@ -0,0 +1,5 @@
theme = "base16_default_dark"
[editor]
line-number = "relative"
mouse = true

56
docs/manifest-contract.md Normal file
View File

@ -0,0 +1,56 @@
# 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 mode is currently `copy`. Sources are repository-relative files and must
remain below `configs/` after canonicalization. Targets may be absolute Windows
paths and may use `%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, or
`%PROGRAMDATA%`. 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.
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 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.
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.

View File

@ -0,0 +1,8 @@
{
"$schema": "../schemas/machine.schema.json",
"schemaVersion": 1,
"name": "example-desktop",
"profiles": ["base", "development"],
"packages": [],
"configs": []
}

19
profiles/base.json Normal file
View File

@ -0,0 +1,19 @@
{
"$schema": "../schemas/profile.schema.json",
"schemaVersion": 1,
"name": "base",
"description": "Common tools for every Windows machine.",
"packages": [
{ "id": "Git.Git", "source": "winget", "scope": "machine", "update": "latest" },
{ "id": "Microsoft.PowerShell", "source": "winget", "scope": "machine", "update": "latest" }
],
"configs": [
{
"name": "git-config",
"source": "configs/git/.gitconfig",
"target": "%USERPROFILE%/.gitconfig",
"mode": "copy",
"requiresPackage": "Git.Git"
}
]
}

18
profiles/development.json Normal file
View File

@ -0,0 +1,18 @@
{
"$schema": "../schemas/profile.schema.json",
"schemaVersion": 1,
"name": "development",
"description": "Developer workstation additions.",
"packages": [
{ "id": "Helix.Helix", "source": "winget", "scope": "machine", "update": "latest" }
],
"configs": [
{
"name": "helix-config",
"source": "configs/helix/config.toml",
"target": "%APPDATA%/helix/config.toml",
"mode": "copy",
"requiresPackage": "Helix.Helix"
}
]
}

View File

@ -0,0 +1,28 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://config-central.local/schemas/machine.schema.json",
"title": "Config Central machine",
"type": "object",
"additionalProperties": false,
"required": ["schemaVersion", "name", "profiles"],
"properties": {
"schemaVersion": { "const": 1 },
"name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
"profiles": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
},
"packages": {
"type": "array",
"items": { "$ref": "profile.schema.json#/$defs/package" },
"default": []
},
"configs": {
"type": "array",
"items": { "$ref": "profile.schema.json#/$defs/config" },
"default": []
}
}
}

View File

@ -0,0 +1,58 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://config-central.local/schemas/profile.schema.json",
"title": "Config Central profile",
"type": "object",
"additionalProperties": false,
"required": ["schemaVersion", "name"],
"properties": {
"schemaVersion": { "const": 1 },
"name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
"description": { "type": "string" },
"packages": {
"type": "array",
"items": { "$ref": "#/$defs/package" },
"default": []
},
"configs": {
"type": "array",
"items": { "$ref": "#/$defs/config" },
"default": []
}
},
"$defs": {
"package": {
"type": "object",
"additionalProperties": false,
"required": ["id"],
"properties": {
"id": { "type": "string", "minLength": 1 },
"source": { "type": "string", "minLength": 1, "default": "winget" },
"scope": { "enum": ["user", "machine"] },
"version": { "type": "string", "minLength": 1 },
"update": { "enum": ["latest", "pinned", "install-only"], "default": "latest" },
"enabled": { "type": "boolean", "default": true }
}
},
"config": {
"type": "object",
"additionalProperties": false,
"required": ["name"],
"properties": {
"name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
"source": { "type": "string", "minLength": 1 },
"target": { "type": "string", "minLength": 1 },
"mode": { "const": "copy", "default": "copy" },
"requiresPackage": { "type": "string", "minLength": 1 },
"enabled": { "type": "boolean", "default": true }
},
"allOf": [
{
"if": { "properties": { "enabled": { "const": false } }, "required": ["enabled"] },
"then": {},
"else": { "required": ["source", "target"] }
}
]
}
}
}