Define configuration manifest contract
This commit is contained in:
parent
6498342e41
commit
6c19178550
14
TASKS.md
14
TASKS.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
[core]
|
||||
autocrlf = true
|
||||
[init]
|
||||
defaultBranch = main
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
theme = "base16_default_dark"
|
||||
|
||||
[editor]
|
||||
line-number = "relative"
|
||||
mouse = true
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"$schema": "../schemas/machine.schema.json",
|
||||
"schemaVersion": 1,
|
||||
"name": "example-desktop",
|
||||
"profiles": ["base", "development"],
|
||||
"packages": [],
|
||||
"configs": []
|
||||
}
|
||||
|
|
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -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": []
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -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"] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue