Document consistent script output and failure handling

This commit is contained in:
Dandaedre 2026-10-19 15:31:44 +02:00
parent a801f8ca0b
commit 18ab1c0dff
3 changed files with 35 additions and 3 deletions

View File

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

View File

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

View File

@ -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`.