From 6c1917855031f61ab52634da87cc7585e1349385 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 16 Oct 2026 13:44:31 +0200 Subject: [PATCH] Define configuration manifest contract --- TASKS.md | 14 ++++----- configs/git/.gitconfig | 4 +++ configs/helix/config.toml | 5 +++ docs/manifest-contract.md | 56 +++++++++++++++++++++++++++++++++ machines/example-desktop.json | 8 +++++ profiles/base.json | 19 ++++++++++++ profiles/development.json | 18 +++++++++++ schemas/machine.schema.json | 28 +++++++++++++++++ schemas/profile.schema.json | 58 +++++++++++++++++++++++++++++++++++ 9 files changed, 203 insertions(+), 7 deletions(-) create mode 100644 configs/git/.gitconfig create mode 100644 configs/helix/config.toml create mode 100644 docs/manifest-contract.md create mode 100644 machines/example-desktop.json create mode 100644 profiles/base.json create mode 100644 profiles/development.json create mode 100644 schemas/machine.schema.json create mode 100644 schemas/profile.schema.json diff --git a/TASKS.md b/TASKS.md index 19fa25e..3daff64 100644 --- a/TASKS.md +++ b/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 diff --git a/configs/git/.gitconfig b/configs/git/.gitconfig new file mode 100644 index 0000000..870baa9 --- /dev/null +++ b/configs/git/.gitconfig @@ -0,0 +1,4 @@ +[core] + autocrlf = true +[init] + defaultBranch = main diff --git a/configs/helix/config.toml b/configs/helix/config.toml new file mode 100644 index 0000000..384665f --- /dev/null +++ b/configs/helix/config.toml @@ -0,0 +1,5 @@ +theme = "base16_default_dark" + +[editor] +line-number = "relative" +mouse = true diff --git a/docs/manifest-contract.md b/docs/manifest-contract.md new file mode 100644 index 0000000..f82f08d --- /dev/null +++ b/docs/manifest-contract.md @@ -0,0 +1,56 @@ +# Manifest and CLI contract + +Config Central reads version 1 JSON manifests. Profile names map to +`profiles/.json`; machine names map to `machines/.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. diff --git a/machines/example-desktop.json b/machines/example-desktop.json new file mode 100644 index 0000000..95b81b8 --- /dev/null +++ b/machines/example-desktop.json @@ -0,0 +1,8 @@ +{ + "$schema": "../schemas/machine.schema.json", + "schemaVersion": 1, + "name": "example-desktop", + "profiles": ["base", "development"], + "packages": [], + "configs": [] +} diff --git a/profiles/base.json b/profiles/base.json new file mode 100644 index 0000000..dd16945 --- /dev/null +++ b/profiles/base.json @@ -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" + } + ] +} diff --git a/profiles/development.json b/profiles/development.json new file mode 100644 index 0000000..859a4f0 --- /dev/null +++ b/profiles/development.json @@ -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" + } + ] +} diff --git a/schemas/machine.schema.json b/schemas/machine.schema.json new file mode 100644 index 0000000..3cac1d6 --- /dev/null +++ b/schemas/machine.schema.json @@ -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": [] + } + } +} diff --git a/schemas/profile.schema.json b/schemas/profile.schema.json new file mode 100644 index 0000000..77aba75 --- /dev/null +++ b/schemas/profile.schema.json @@ -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"] } + } + ] + } + } +}