Document consistent script output and failure handling
This commit is contained in:
parent
a801f8ca0b
commit
18ab1c0dff
25
AGENTS.md
25
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.
|
||||
|
|
|
|||
1
TASKS.md
1
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.
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue