commit c51d7916a59fea2bb9b257aaa0fa9f18eccc3dbb Author: Dandaedre Date: Fri Oct 16 13:41:00 2026 +0200 Add project agent instructions diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..14fb02d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,105 @@ +# Project instructions + +## Purpose + +Config Central manages software installation and repository-backed configuration +across several Windows desktops. Each machine pulls from this repository and +applies its selected profiles. Keep the process simple, inspectable, and usable +from a terminal without a management server. + +## Architecture + +- Use PowerShell 7 for the CLI and implementation modules. Keep `bootstrap.ps1` + compatible with built-in Windows PowerShell 5.1 so a fresh machine can start. +- Use WinGet for software and Git for repository distribution. +- Use JSON manifests for profiles and machine definitions, with no YAML dependency. +- Expose `cc` through a thin launcher for `cc.ps1`. Implement CLI commands before + considering a TUI; any menu must reuse the same command implementation. +- Keep dependencies minimal. Do not introduce a compiled CLI, service, DSC layer, + or remote orchestration framework without a concrete need. + +Planned layout: + +```text +bootstrap.ps1 +cc.ps1 +src/ + Packages.psm1 + Configs.psm1 + Repository.psm1 + Elevation.psm1 + State.psm1 +profiles/ +machines/ +configs/ +tests/ +TASKS.md +``` + +## Desired behavior + +- Machine manifests select ordered profiles and provide explicit overrides. + Merge packages by package ID and source, and configs by stable config name. + Reject ambiguous definitions and unknown fields. Support `enabled: false` for + disabling inherited entries. Document precedence before implementing it. +- Commands: `plan`, `sync`, `apply`, `status`, and `doctor`. `sync` fetches then + applies; `apply` uses the current local revision. Support config-only sync. +- Resolve a repository revision before applying and execute from an immutable + snapshot. Never replace running scripts midway through a sync or discard local + repository edits automatically. +- Install missing packages and upgrade only declared packages according to their + update policy. Use explicit WinGet IDs and sources. Handle installer scope as a + package constraint rather than assuming every package supports both scopes. +- Run installations sequentially. Preserve diagnostics, interpret exit codes, + report reboot requirements, and never reboot automatically. +- Copy configuration files by default. Back up existing destinations before + replacement, track deployed hashes, and skip unchanged content. +- Report locally modified config files as conflicts. An explicit force option + may replace them only after backing them up. Do not implement generic merging + across arbitrary file formats. +- Removing a manifest entry stops managing it. Uninstalling applications or + deleting destination files requires an explicit operation. +- Record per-item results and the applied commit. Reruns inspect actual state and + recover from partial failure. Do not claim package operations are transactional. + +## Windows execution and storage + +- Run the controller as the desktop user. Elevate only the worker operations + that require administrator rights, preferably in a batch. +- Resolve user config paths using the original user's context, including when + elevation uses different credentials. Never accidentally target the admin + account's profile. +- Keep user checkout, state, backups, and logs under + `%LOCALAPPDATA%\ConfigCentral`. Protect machine-level state under + `%ProgramData%\ConfigCentral` with appropriate permissions. +- Validate manifest paths and elevated operations. Do not evaluate manifest + strings as PowerShell code or pass arbitrary commands to the elevated worker. +- Do not disable Defender, UAC, or installer integrity checks as setup steps. + Diagnose individual failures instead of adding broad security workarounds. +- Keep credentials and machine secrets out of manifests, logs, and Git. + +## Implementation and verification + +- Make every task step and each distinct modification a small, focused Git + commit. Do not combine unrelated work. A commit should contain one reviewable + behavior, fix, test, documentation change, or task-state update and should + leave the repository in a coherent state. +- Commit the corresponding `TASKS.md` checkbox update with the implementation + that completes it. If a task requires several independent changes, use several + small commits and mark the task complete only in the final commit. +- Use concise imperative commit messages that describe the completed change. + Review the staged diff before committing and never include unrelated user + changes. +- Keep package, config, repository, elevation, and state logic in separate modules. + Keep the CLI entry point small and make errors actionable. +- `plan` must not install packages or deploy configs. Provide stable exit codes + for automation and readable summaries for interactive use. +- Validate manifests and prerequisites before making changes. Prevent concurrent + applies and write state atomically. +- Test behavior with meaningful failure cases: profile precedence, path handling, + local edits, partial failure, reruns, and privilege boundaries. Mock installers + in unit tests; use a disposable Windows environment for installation checks. +- Run checks appropriate to the change. Clearly distinguish checks executed on + Windows from static checks or mocks executed elsewhere. +- Update `TASKS.md` as implementation progresses. Mark tasks complete only when + the behavior is implemented and relevant validation is done.