config-central/AGENTS.md

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.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:

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.