134 lines
7.1 KiB
Markdown
134 lines
7.1 KiB
Markdown
# 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.
|