From 839488a5ee1e814be6db7be07f9c060c051cf760 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 3 Jul 2026 10:29:41 +0000 Subject: [PATCH] docs: update package specs for console and constants MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - console: document FormatSuccessMessageStderr, FormatInfoMessageStderr, FormatListItemStderr, FormatSectionHeaderStderr — the stderr-TTY-aware variants that check os.Stderr instead of os.Stdout before applying ANSI styling - constants: document FilePermSensitive, FilePermPublic, FilePermExecutable, DirPermSensitive, DirPermPublic file mode constants Packages analyzed this run: agentdrain, cli, console, constants Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- pkg/console/README.md | 17 +++++++++++++++++ pkg/constants/README.md | 12 ++++++++++++ 2 files changed, 29 insertions(+) diff --git a/pkg/console/README.md b/pkg/console/README.md index 60560dcdc21..1d87faa2184 100644 --- a/pkg/console/README.md +++ b/pkg/console/README.md @@ -48,6 +48,7 @@ The following components and functions are exported by the `console` package: | `RenderTitleBox` / `RenderErrorBox` / `RenderInfoSection` | funcs | Section rendering helpers | | `RenderComposedSections` | func | Composes and prints multiple sections | | `FormatSuccessMessage` / `FormatInfoMessage` / `FormatWarningMessage` / `FormatErrorMessage` | funcs | Styled status message formatting | +| `FormatSuccessMessageStderr` / `FormatInfoMessageStderr` / `FormatListItemStderr` / `FormatSectionHeaderStderr` | funcs | Stderr-TTY-aware variants of matching format functions | | `FormatCommandMessage` / `FormatProgressMessage` / `FormatVerboseMessage` | funcs | Additional message styles | | `FormatError` | func | Renders a structured `CompilerError` with context | | `FormatErrorChain` | func | Renders a wrapped-error chain | @@ -358,7 +359,9 @@ All `Format*` functions return a styled string ready to be printed to `os.Stderr | Function | Style | Typical use | |----------|-------|-------------| | `FormatSuccessMessage(message string) string` | Green, bold | Operation completed successfully | +| `FormatSuccessMessageStderr(message string) string` | Green, bold (stderr TTY) | Success message using stderr TTY detection | | `FormatInfoMessage(message string) string` | Cyan, bold | General informational output | +| `FormatInfoMessageStderr(message string) string` | Cyan, bold (stderr TTY) | Info message using stderr TTY detection | | `FormatWarningMessage(message string) string` | Orange, bold | Non-fatal warnings | | `FormatErrorMessage(message string) string` | Red, bold | Recoverable error messages | | `FormatCommandMessage(command string) string` | Purple | CLI commands and code snippets | @@ -366,11 +369,25 @@ All `Format*` functions return a styled string ready to be printed to `os.Stderr | `FormatPromptMessage(message string) string` | Cyan | Interactive prompt labels | | `FormatVerboseMessage(message string) string` | Muted/comment | Verbose/debug detail | | `FormatListItem(item string) string` | Foreground | Individual list entries | +| `FormatListItemStderr(item string) string` | Foreground (stderr TTY) | List entry using stderr TTY detection | | `FormatListHeader(header string) string` | Plain (WASM only) | Section headers inside lists | | `FormatSectionHeader(header string) string` | Bold, bordered | Section titles in output | +| `FormatSectionHeaderStderr(header string) string` | Bold, bordered (stderr TTY) | Section title using stderr TTY detection | | `FormatLocationMessage(message string) string` | Foreground (WASM only) | File and location paths | | `FormatCountMessage(message string) string` | Foreground (WASM only) | Counts and metrics | +### Stderr TTY Variants + +The `*Stderr` variants (`FormatSuccessMessageStderr`, `FormatInfoMessageStderr`, `FormatListItemStderr`, `FormatSectionHeaderStderr`) check whether **`os.Stderr`** is a terminal rather than `os.Stdout`. Use these when writing to `os.Stderr` directly, so that color stripping is applied correctly in non-interactive contexts (e.g., piped stderr). + +```go +// Use Stderr variants when writing directly to os.Stderr +fmt.Fprintln(os.Stderr, console.FormatInfoMessageStderr("Already configured")) +fmt.Fprintln(os.Stderr, console.FormatSuccessMessageStderr("Updated "+filePath)) +fmt.Fprintln(os.Stderr, console.FormatSectionHeaderStderr("Section Title")) +fmt.Fprintln(w, console.FormatListItemStderr("Detail item")) +``` + ### Usage Pattern ```go diff --git a/pkg/constants/README.md b/pkg/constants/README.md index f273b7dcaaa..0d4d53411d1 100644 --- a/pkg/constants/README.md +++ b/pkg/constants/README.md @@ -348,6 +348,18 @@ constants.ExpressionBreakThreshold // 100 — threshold at which long lines ge constants.CLIExtensionPrefix // "gh aw" — user-facing CLI prefix ``` +## File Permission Constants + +Standard `fs.FileMode` values for consistent file and directory creation: + +```go +constants.FilePermSensitive // 0o600 — owner-only read/write (config files, credentials) +constants.FilePermPublic // 0o644 — owner read/write + world read (normal files) +constants.FilePermExecutable // 0o755 — owner/group/world executable (scripts, binaries) +constants.DirPermSensitive // 0o750 — owner+group access (sensitive directories) +constants.DirPermPublic // 0o755 — standard non-sensitive directory access +``` + ## Runtime Configuration ```go