internal/util: exit codes and the output.Writer

AGENTS.md

@@ -122,6 +122,7 @@ The full structure, with a file-level breakdown, is in
 | [docs/content/docs/architecture/_index.md](./docs/content/docs/architecture/_index.md)                 | Architecture section index                                    |
 | [docs/content/docs/architecture/overview.md](./docs/content/docs/architecture/overview.md)             | Package structure, CLI tree, data flow                        |
 | [docs/content/docs/architecture/error-handling.md](./docs/content/docs/architecture/error-handling.md) | Sentinel errors, the wrapping rule, and `error_kind` contract |
+| [docs/content/docs/architecture/output.md](./docs/content/docs/architecture/output.md)                 | `output.Writer`, pretty vs NDJSON, TTY detection, exit codes  |
 
 `docs/design.md` is the *plan*; `docs/content/docs/architecture/` describes what has been built. As
 subsystems land, their behaviour moves from the former into the latter.

docs/content/docs/architecture/_index.md

@@ -10,10 +10,11 @@ reconciliation algorithm, milestones, and open questions — lives in
 [design.md](https://github.com/specsnl/labelsync/blob/main/docs/design.md). As each subsystem
 lands, its behaviour moves from the design plan into this section.
 
-| Page                                  | Covers                                                                      |
-|---------------------------------------|-----------------------------------------------------------------------------|
-| [Overview](./overview.md)             | Package structure, CLI command tree, the reconciliation data flow           |
-| [Error Handling](./error-handling.md) | Sentinel errors, the `%w` wrapping rule, and the `error_kind` JSON contract |
+| Page                                  | Covers                                                                            |
+|---------------------------------------|-----------------------------------------------------------------------------------|
+| [Overview](./overview.md)             | Package structure, CLI command tree, the reconciliation data flow                 |
+| [Error Handling](./error-handling.md) | Sentinel errors, the `%w` wrapping rule, and the `error_kind` JSON contract       |
+| [Output & Exit Codes](./output.md)    | `output.Writer`, pretty vs NDJSON, TTY detection, the `slog` boundary, exit codes |
 
 Pages are added here as the subsystems they document are implemented — the palette allocator, the
-planner, the GitHub client and its rate limiting, and the output system each get their own page.
+planner, and the GitHub client with its rate limiting each get their own page.

docs/content/docs/architecture/overview.md

@@ -30,16 +30,18 @@ labelsync/
     ├── apply/                    # executes a Plan, prune prompts
     └── util/
         ├── exit/                 # exit codes
-        ├── output/               # lipgloss logger + table renderer
+        ├── output/               # Writer (pretty + NDJSON), table renderers, slog setup
         └── validate/             # shared validators
 ```
 
 ### Implemented so far
 
-| Package              | Status  | Notes                                                          |
-|----------------------|---------|----------------------------------------------------------------|
-| `internal/labelsync` | landed  | XDG config/cache paths, config file names, sentinels, `KindOf` |
-| everything else      | planned | See the milestone table in the design plan                     |
+| Package                | Status  | Notes                                                          |
+|------------------------|---------|----------------------------------------------------------------|
+| `internal/labelsync`   | landed  | XDG config/cache paths, config file names, sentinels, `KindOf` |
+| `internal/util/exit`   | landed  | The four exit codes — see [Output & Exit Codes](./output.md)   |
+| `internal/util/output` | landed  | `Writer`, pretty + NDJSON, TTY detection, `slog` wiring        |
+| everything else        | planned | See the milestone table in the design plan                     |
 
 ### Why `plan` and `palette` are isolated
 
@@ -74,12 +76,14 @@ labelsync [--config <path>]
 
 ### Exit codes
 
-| Code | Meaning                                                            |
-|------|--------------------------------------------------------------------|
-| `0`  | In sync — no changes needed, or applied successfully with no drift |
-| `1`  | Error (config invalid, auth failure, unrecoverable API error)      |
-| `2`  | Drift detected — `--dry-run` found pending actions                 |
-| `3`  | Applied successfully, but one or more repositories were skipped    |
+| Code | Constant       | Meaning                                                            |
+|------|----------------|--------------------------------------------------------------------|
+| `0`  | `exit.OK`      | In sync — no changes needed, or applied successfully with no drift |
+| `1`  | `exit.Error`   | Error (config invalid, auth failure, unrecoverable API error)      |
+| `2`  | `exit.Drift`   | Drift detected — `--dry-run` found pending actions                 |
+| `3`  | `exit.Skipped` | Applied successfully, but one or more repositories were skipped    |
+
+Defined in `internal/util/exit`; the rationale is in [Output & Exit Codes](./output.md#exit-codes).
 
 ## Configuration
 

docs/design.md

@@ -581,6 +581,9 @@ before running a prune.
 
 ### Exit codes
 
+> **Landed** as `internal/util/exit` — see
+> [Output & Exit Codes](./content/docs/architecture/output.md#exit-codes).
+
 Borrowed from `terraform plan -detailed-exitcode`. Without this, a CI dry-run can only ever pass,
 which makes it useless as a check.
 
@@ -589,7 +592,11 @@ which makes it useless as a check.
 | `0`  | In sync — no changes needed / applied successfully with no drift |
 | `1`  | Error (config invalid, auth failure, unrecoverable API error)    |
 | `2`  | Drift detected — `--dry-run` found pending actions               |
-| `3`  | Applied successfully, but one or more repositories were skipped  |
+| `4`  | Applied successfully, but one or more repositories were skipped  |
+
+The outcome codes are disjoint bits and combine: a dry run that finds drift *and* cannot reach a
+repository exits `6`. `1` stays exclusive — a failed run cannot also report on a live state it never
+established.
 
 ### Non-interactive guard
 
@@ -707,6 +714,9 @@ the build rather than silently escaping `KindOf` and rendering an empty `error_k
 
 ## Output
 
+> **Landed.** `internal/util/output` is built; what it actually does is documented in
+> [Output & Exit Codes](./content/docs/architecture/output.md).
+
 All user-facing output goes through `output.Writer`, with `pretty` and `json` implementations
 selected by `--output`. `log/slog` is a **debug-only diagnostic channel on stderr**, silent on a
 normal run, and never used for user-facing reporting.
@@ -852,19 +862,21 @@ asserts byte-identical output. Colour churn on re-run is the most likely subtle
 
 ## Dependencies
 
-| Package                              | Purpose                                     | Shared with specs-cli                            |
-|--------------------------------------|---------------------------------------------|--------------------------------------------------|
-| `github.com/spf13/cobra`             | CLI command tree                            | yes                                              |
-| `gopkg.in/yaml.v3`                   | Config parsing                              | yes                                              |
-| `charm.land/huh/v2`                  | Interactive prune selection (`MultiSelect`) | yes                                              |
-| `charm.land/lipgloss/v2`             | Output styling, diff table, countdown       | yes                                              |
-| `github.com/adrg/xdg`                | Config + cache directory resolution         | yes                                              |
-| `github.com/danwakefield/fnmatch`    | Repo include/exclude globs                  | yes                                              |
-| `golang.org/x/sync`                  | `errgroup` bounded parallel reads           | yes                                              |
-| `log/slog`                           | Debug logging (stdlib)                      | yes                                              |
-| `github.com/google/go-github/v76`    | GitHub REST client                          | **new**                                          |
-| `github.com/cli/go-gh/v2`            | Token resolution only                       | **new**                                          |
-| `github.com/lucasb-eyer/go-colorful` | CIELAB + CIEDE2000                          | **new (direct)** — already indirect via lipgloss |
+| Package                                 | Purpose                                       | Shared with specs-cli                            |
+|-----------------------------------------|-----------------------------------------------|--------------------------------------------------|
+| `github.com/spf13/cobra`                | CLI command tree                              | yes                                              |
+| `gopkg.in/yaml.v3`                      | Config parsing                                | yes                                              |
+| `charm.land/huh/v2`                     | Interactive prune selection (`MultiSelect`)   | yes                                              |
+| `charm.land/lipgloss/v2`                | Output styling, diff table, countdown         | yes                                              |
+| `github.com/adrg/xdg`                   | Config + cache directory resolution           | yes                                              |
+| `github.com/danwakefield/fnmatch`       | Repo include/exclude globs                    | yes                                              |
+| `golang.org/x/sync`                     | `errgroup` bounded parallel reads             | yes                                              |
+| `log/slog`                              | Debug logging (stdlib)                        | yes                                              |
+| `github.com/google/go-github/v76`       | GitHub REST client                            | **new**                                          |
+| `github.com/cli/go-gh/v2`               | Token resolution only                         | **new**                                          |
+| `github.com/lucasb-eyer/go-colorful`    | CIELAB + CIEDE2000                            | **new (direct)** — already indirect via lipgloss |
+| `github.com/charmbracelet/colorprofile` | Colour downsampling per output stream         | **new (direct)** — already indirect via lipgloss |
+| `github.com/charmbracelet/x/term`       | `IsTerminal` for the non-colour TTY decisions | **new (direct)** — already indirect via lipgloss |
 
 **Why go-github rather than a hand-rolled client or `go-gh`'s REST client:** the deciding factor
 is typed `*github.RateLimitError` and `*github.AbuseRateLimitError`. Secondary rate limits are the

go.mod

@@ -2,6 +2,25 @@ module github.com/specsnl/labelsync
 
 go 1.26.5
 
-require github.com/adrg/xdg v0.5.3
+require (
+	charm.land/lipgloss/v2 v2.0.5
+	github.com/adrg/xdg v0.5.3
+	github.com/charmbracelet/colorprofile v0.4.3
+	github.com/charmbracelet/x/term v0.2.2
+)
 
-require golang.org/x/sys v0.26.0 // indirect
+require (
+	github.com/charmbracelet/ultraviolet v0.0.0-20251205161215-1948445e3318 // indirect
+	github.com/charmbracelet/x/ansi v0.11.7 // indirect
+	github.com/charmbracelet/x/termios v0.1.1 // indirect
+	github.com/charmbracelet/x/windows v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
+	github.com/mattn/go-runewidth v0.0.23 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+)

go.sum

@@ -1,12 +1,44 @@
+charm.land/lipgloss/v2 v2.0.5 h1:kbNxgeeUOYv5J0YdpxFjfvf3dFvqH8Aci4zB6xqFtrY=
+charm.land/lipgloss/v2 v2.0.5/go.mod h1:9oqhxt4yxIMe6q5A4kHr44DremZk7J9UNh74GlWa5nc=
 github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78=
 github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ=
+github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
+github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
+github.com/charmbracelet/ultraviolet v0.0.0-20251205161215-1948445e3318 h1:OqDqxQZliC7C8adA7KjelW3OjtAxREfeHkNcd66wpeI=
+github.com/charmbracelet/ultraviolet v0.0.0-20251205161215-1948445e3318/go.mod h1:Y6kE2GzHfkyQQVCSL9r2hwokSrIlHGzZG+71+wDYSZI=
+github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
+github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
+github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
+github.com/charmbracelet/x/windows v0.2.2 h1:IofanmuvaxnKHuV04sC0eBy/smG6kIKrWG2/jYn2GuM=
+github.com/charmbracelet/x/windows v0.2.2/go.mod h1:/8XtdKZzedat74NQFn0NGlGL4soHB0YQZrETF96h75k=
+github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
+github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
+github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
+github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-golang.org/x/sys v0.26.0 h1:KHjCJyddX0LoSTb3J+vWpupP9p0oznkqVk/IfjymZbo=
-golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=