diff --git a/AGENTS.md b/AGENTS.md index 7ddc242..47efbc4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,3 +106,28 @@ TASKS.md 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. diff --git a/TASKS.md b/TASKS.md index b3e6dd9..61f5251 100644 --- a/TASKS.md +++ b/TASKS.md @@ -137,3 +137,4 @@ open until it is run on disposable machines with the required account setups. - [x] Restore SSH firewall state using enum names, preserve retry state on cleanup failure, and show the elevated error without a wrapper stack trace. - [x] Install MPC-HC through clsid2.mpc-hc and link its config to the package result. - [x] Standardize entrypoint error summaries, status colors, plain redirected output, and automation exit codes across setup, updates, capture, CLI, and SSH. +- [x] Record the cross-script output and error-handling convention in AGENTS.md and the advanced guide. diff --git a/docs/advanced_commands.md b/docs/advanced_commands.md index 24048c2..56f663b 100644 --- a/docs/advanced_commands.md +++ b/docs/advanced_commands.md @@ -253,7 +253,9 @@ messages. Deployment logs are under `%LOCALAPPDATA%\ConfigCentral\logs`. Running `install.ps1` as a file preserves the bootstrap process exit code. With `irm | iex`, the terminal stays open and `$LASTEXITCODE` contains that code. -Errors raised before deployment may still include PowerShell diagnostics. +Runtime failures in setup, bootstrap, updates, capture, and SSH helpers use the +same concise error presentation. Native installer diagnostics remain visible; +PowerShell parameter-binding or syntax errors can still use PowerShell formatting. ## Config conflicts and recovery @@ -319,5 +321,9 @@ and repository hygiene checks; it does not pretend to execute Windows behavior. - Package removal and deletion of formerly managed configs are deliberately manual operations. -Terminal results color status labels only. Redirected output and JSON remain plain. -Set `$env:NO_COLOR = "1"` to disable status colors in a terminal. +Item results color status labels; script summaries use the same palette: red +errors, yellow warnings, green completion, gray unchanged items, and cyan planned +actions. Redirected output and JSON remain plain. Set `$env:NO_COLOR = "1"` to +disable colors in a terminal. Errors go to stderr; JSON errors stay structured. +Runtime failures preserve nonzero status codes, and web commands leave the +terminal open with the outcome in `$LASTEXITCODE`.