diff --git a/README.md b/README.md new file mode 100644 index 0000000..b55e526 --- /dev/null +++ b/README.md @@ -0,0 +1,177 @@ +# Config Central + +Config Central is a small PowerShell CLI for keeping several Windows desktops on +the same declared software and configuration baseline. Each machine pulls this +Git repository, resolves its profiles, installs or updates declared packages with +WinGet, and copies managed config files with drift detection and backups. + +There is no central server or resident agent. The normal workflow is: + +```text +Git fetch -> immutable commit snapshot -> plan -> WinGet -> config copies -> state +``` + +## Requirements + +- Windows 10 version 1809 or newer, Windows 11, or Windows Server 2025 +- Windows PowerShell 5.1 for initial bootstrap +- PowerShell 7, Git, and WinGet after bootstrap +- An interactive desktop account; administrator credentials when a machine-scope + installer needs them + +The bootstrap checks and installs its prerequisites. WinGet must be supported by +the Windows edition and able to reach its configured sources. + +## Onboard a machine + +Download `bootstrap.ps1` from a trusted revision of this repository, inspect it, +then run it from Windows PowerShell: + +```powershell +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 ` + -Repository 'https://your-server/you/config-central.git' ` + -Branch main ` + -Machine example-desktop +``` + +Bootstrap repairs WinGet if necessary, installs Git and PowerShell 7, clones the +configured branch under `%LOCALAPPDATA%\ConfigCentral\repository`, saves the +machine selection, adds `cc` to the user PATH, and performs the first apply. It +is safe to rerun after a failed prerequisite installation. Use `-SkipApply` when +you only want to establish the checkout and launcher. + +Open a new terminal after bootstrap so the updated user PATH is visible, then +check the installation: + +```powershell +cc doctor +cc plan +cc apply +``` + +## Define profiles and machines + +Profiles live in `profiles/`. Machines live in `machines/` and list profiles in +precedence order. Later profiles replace earlier entries; machine entries replace +all profile entries. A package is identified by `source/id`, and a config by +`name`. Set `enabled` to `false` in a later layer to remove an inherited item. + +```json +{ + "schemaVersion": 1, + "name": "workstation", + "profiles": ["base", "development"], + "packages": [ + { + "id": "Microsoft.VisualStudioCode", + "source": "winget", + "scope": "machine", + "update": "latest" + } + ], + "configs": [] +} +``` + +Put source files below `configs/`. Config targets accept `%APPDATA%`, +`%LOCALAPPDATA%`, `%USERPROFILE%`, and `%PROGRAMDATA%`: + +```json +{ + "name": "helix-config", + "source": "configs/helix/config.toml", + "target": "%APPDATA%/helix/config.toml", + "mode": "copy", + "requiresPackage": "Helix.Helix" +} +``` + +The complete schema, precedence rules, package policies, and exit codes are in +[the manifest contract](docs/manifest-contract.md). + +## Daily commands + +```powershell +cc plan # show intended work; change nothing +cc apply # apply the current checkout +cc sync # fetch and apply an immutable remote snapshot +cc status # show drift and the last run +cc sync -ConfigsOnly # fetch and deploy configs; do not call WinGet +cc apply -ForceConfigs # back up local edits, then replace them +cc restore -Config helix-config # restore the newest backup +cc doctor # inspect prerequisites and sources +cc menu # optional numbered menu +``` + +`sync` refuses to run while the checkout has uncommitted or untracked files. It +does not reset the checkout. Commit your edits first, or remove files you did not +intend to keep. + +Package installs run sequentially. Machine-scope packages are sent together to a +constrained elevated worker, so one UAC approval covers the batch. User config +paths come from the original desktop session even when different administrator +credentials approve the package work. A required reboot is reported with exit +code `6`; Config Central never reboots the machine itself. + +## Config conflicts and recovery + +Config Central stores the hash it last deployed. A different destination hash, +an existing file it has never managed, or a locally deleted managed file is a +conflict. Normal apply leaves the destination alone. `-ForceConfigs` makes a +timestamped backup and then deploys the repository version. + +`cc restore -Config NAME` restores the newest backup and first backs up the file +being replaced. Removing a config from a manifest stops managing it; it does not +delete the destination. Removing a package stops managing it; it does not +uninstall software. + +User state is stored under `%LOCALAPPDATA%\ConfigCentral`: + +```text +settings.json repository, branch, machine, and original user paths +state.json deployed hashes, last run, and applied revision +logs/ per-run package and config results +backups/ timestamped config backups grouped by config name +snapshots/ immutable Git commit snapshots used by sync +``` + +## Optional logon sync + +```powershell +cc schedule +cc unschedule +``` + +The scheduled task runs in the interactive user's limited context and always +uses `sync -ConfigsOnly`. Package installation remains manual because a logon +task must not stall on UAC or an installer prompt. + +## Validation + +On a Windows development machine with Pester 5: + +```powershell +Invoke-Pester -Path .\tests +``` + +Real bootstrap, WinGet, UAC, and separate-admin-account tests require a disposable +Windows machine. Opt in to the integration suite there with +`CONFIG_CENTRAL_INTEGRATION=1`. The Jenkins pipeline follows the project's +FreeBSD worker style and runs dependency-free PowerShell structure, JSON contract, +and repository hygiene checks; it does not pretend to execute Windows behavior. + +## Current limitations + +- Config deployment supports whole-file copies only. It does not merge arbitrary + application formats. +- `latest` packages are offered to WinGet during apply. WinGet decides whether an + upgrade exists, so a plan may say `Upgrade` when the installed version is + already current. +- WinGet inventory contains only packages WinGet recognizes. Unknown versions and + installer-specific scope failures are reported with WinGet diagnostics. +- Package operations are not transactional and are not rolled back after a later + failure. Successful independent work is recorded so the next run can resume. +- Config Central does not disable Defender, UAC, malware scanning, or installer + integrity checks. +- Package removal and deletion of formerly managed configs are deliberately + manual operations. diff --git a/TASKS.md b/TASKS.md index fed6aa9..0668324 100644 --- a/TASKS.md +++ b/TASKS.md @@ -1,7 +1,7 @@ # Implementation tasks -The architecture is agreed as a starting point; implementation has not begun. -Complete the core CLI and manual workflow before optional automation or a TUI. +The core CLI and manual workflow are implemented. Windows-only validation remains +open until it is run on disposable machines with the required account setups. ## 1. Define manifests and command contracts @@ -87,9 +87,9 @@ Complete the core CLI and manual workflow before optional automation or a TUI. - [ ] Test elevation using both the same account and separate admin credentials. - [x] Test paths containing spaces/non-ASCII characters and interrupted runs. - [x] Test config-only updates and recovery after an installer requests a reboot. -- [ ] Write README instructions for onboarding a machine, editing profiles, +- [x] Write README instructions for onboarding a machine, editing profiles, syncing, resolving conflicts, restoring configs, and finding logs. -- [ ] Document supported Windows versions, limitations, and which verification +- [x] Document supported Windows versions, limitations, and which verification requires Windows. ## Later, only when useful