# 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 `install.ps1` and `bootstrap.ps1` compatible with built-in Windows PowerShell 5.1 so a fresh machine can start. Keep `install.ps1` as a thin web entrypoint that stages and invokes the bootstrap rather than duplicating setup logic. - 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 install.ps1 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. ## User-facing output and failures - Apply the same output conventions to every public script and CLI command. Show a concise outcome, the actual cause, and an actionable next step. Expected failures must not appear as a PowerShell stack trace or a generic exit-code-only wrapper error. Preserve underlying diagnostics from child processes. - Use red for failures, yellow for conflicts/warnings/skips/reboot requests, green for completed work, gray for unchanged items, and cyan for planned work or informational statuses. Keep names and explanations readable without color. - Honor NO_COLOR and keep redirected output plain. Keep JSON and internal worker responses machine-readable, without banners, color escapes, or capture chatter. - Catch exceptions at user-facing entrypoints. Internal helpers should still propagate failures to their caller; never silently turn a failed operation into success. Do not use a terminating Write-Error inside a top-level catch. - Preserve meaningful process exit codes when invoked as a file. Web execution through irm | iex must keep the terminal open and expose the outcome through LASTEXITCODE. Describe partial completion honestly and retain retry state. - Use Write-ConfigCentralMessage for standalone entrypoint messages. Its small identical implementation is embedded to keep web scripts dependency-free; tests/Output.Tests.ps1 verifies that the copies stay synchronized. Use the CLI result renderer for per-item output. Internal workers retain structured output. - Test failure presentation, exit codes, JSON purity, and plain-output behavior when changing error handling. Explicitly distinguish mocked/Linux validation from Windows execution.