7.1 KiB
7.1 KiB
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.ps1andbootstrap.ps1compatible with built-in Windows PowerShell 5.1 so a fresh machine can start. Keepinstall.ps1as 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
ccthrough a thin launcher forcc.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:
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: falsefor disabling inherited entries. Document precedence before implementing it. - Commands:
plan,sync,apply,status, anddoctor.syncfetches then applies;applyuses 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%\ConfigCentralwith 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.mdcheckbox 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.
planmust 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.mdas 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.