From f07e5bb3ff848ad2828bde3009f1e6bd5554c59b Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Sat, 31 Jan 2026 23:04:42 +0000
Subject: [PATCH] feat(cli): add DX-focused semantic output patterns

- Check() fluent builder for check results
- Task() for task headers
- Section() for section headers
- Hint() for labelled hints
- Severity() for severity-styled output
- Result() for pass/fail results

Consuming packages now have zero display logic.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 pkg/cli/check.go  | 91 +++++++++++++++++++++++++++++++++++++++++++++++
 pkg/cli/output.go | 60 +++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 pkg/cli/check.go

diff --git a/pkg/cli/check.go b/pkg/cli/check.go
new file mode 100644
index 0000000..499cd89
--- /dev/null
+++ b/pkg/cli/check.go
@@ -0,0 +1,91 @@
+package cli
+
+import "fmt"
+
+// CheckBuilder provides fluent API for check results.
+type CheckBuilder struct {
+	name     string
+	status   string
+	style    *AnsiStyle
+	icon     string
+	duration string
+}
+
+// Check starts building a check result line.
+//
+//	cli.Check("audit").Pass()
+//	cli.Check("fmt").Fail().Duration("2.3s")
+//	cli.Check("test").Skip()
+func Check(name string) *CheckBuilder {
+	return &CheckBuilder{name: name}
+}
+
+// Pass marks the check as passed.
+func (c *CheckBuilder) Pass() *CheckBuilder {
+	c.status = "passed"
+	c.style = SuccessStyle
+	c.icon = Glyph(":check:")
+	return c
+}
+
+// Fail marks the check as failed.
+func (c *CheckBuilder) Fail() *CheckBuilder {
+	c.status = "failed"
+	c.style = ErrorStyle
+	c.icon = Glyph(":cross:")
+	return c
+}
+
+// Skip marks the check as skipped.
+func (c *CheckBuilder) Skip() *CheckBuilder {
+	c.status = "skipped"
+	c.style = DimStyle
+	c.icon = "-"
+	return c
+}
+
+// Warn marks the check as warning.
+func (c *CheckBuilder) Warn() *CheckBuilder {
+	c.status = "warning"
+	c.style = WarningStyle
+	c.icon = Glyph(":warn:")
+	return c
+}
+
+// Duration adds duration to the check result.
+func (c *CheckBuilder) Duration(d string) *CheckBuilder {
+	c.duration = d
+	return c
+}
+
+// Message adds a custom message instead of status.
+func (c *CheckBuilder) Message(msg string) *CheckBuilder {
+	c.status = msg
+	return c
+}
+
+// String returns the formatted check line.
+func (c *CheckBuilder) String() string {
+	icon := c.icon
+	if c.style != nil {
+		icon = c.style.Render(c.icon)
+	}
+
+	status := c.status
+	if c.style != nil && c.status != "" {
+		status = c.style.Render(c.status)
+	}
+
+	if c.duration != "" {
+		return fmt.Sprintf("  %s %-20s %-10s %s", icon, c.name, status, DimStyle.Render(c.duration))
+	}
+	if status != "" {
+		return fmt.Sprintf("  %s %s %s", icon, c.name, status)
+	}
+	return fmt.Sprintf("  %s %s", icon, c.name)
+}
+
+// Print outputs the check result.
+func (c *CheckBuilder) Print() {
+	fmt.Println(c.String())
+}
diff --git a/pkg/cli/output.go b/pkg/cli/output.go
index 24be804..30983d1 100644
--- a/pkg/cli/output.go
+++ b/pkg/cli/output.go
@@ -2,6 +2,7 @@ package cli
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/host-uk/core/pkg/i18n"
 )
@@ -98,4 +99,63 @@ func Label(word, value string) {
 // Scanln reads from stdin.
 func Scanln(a ...any) (int, error) {
 	return fmt.Scanln(a...)
+}
+
+// Task prints a task header: "[label] message"
+//
+//	cli.Task("php", "Running tests...")  // [php] Running tests...
+//	cli.Task("go", i18n.Progress("build"))  // [go] Building...
+func Task(label, message string) {
+	fmt.Printf("%s %s\n\n", DimStyle.Render("["+label+"]"), message)
+}
+
+// Section prints a section header: "── SECTION ──"
+//
+//	cli.Section("audit")  // ── AUDIT ──
+func Section(name string) {
+	header := "── " + strings.ToUpper(name) + " ──"
+	fmt.Println(AccentStyle.Render(header))
+}
+
+// Hint prints a labelled hint: "label: message"
+//
+//	cli.Hint("install", "composer require vimeo/psalm")
+//	cli.Hint("fix", "core php fmt --fix")
+func Hint(label, message string) {
+	fmt.Printf("  %s %s\n", DimStyle.Render(label+":"), message)
+}
+
+// Severity prints a severity-styled message.
+//
+//	cli.Severity("critical", "SQL injection")  // red, bold
+//	cli.Severity("high", "XSS vulnerability")  // orange
+//	cli.Severity("medium", "Missing CSRF")     // amber
+//	cli.Severity("low", "Debug enabled")       // gray
+func Severity(level, message string) {
+	var style *AnsiStyle
+	switch strings.ToLower(level) {
+	case "critical":
+		style = NewStyle().Bold().Foreground(ColourRed500)
+	case "high":
+		style = NewStyle().Bold().Foreground(ColourOrange500)
+	case "medium":
+		style = NewStyle().Foreground(ColourAmber500)
+	case "low":
+		style = NewStyle().Foreground(ColourGray500)
+	default:
+		style = DimStyle
+	}
+	fmt.Printf("  %s %s\n", style.Render("["+level+"]"), message)
+}
+
+// Result prints a result line: "✓ message" or "✗ message"
+//
+//	cli.Result(passed, "All tests passed")
+//	cli.Result(false, "3 tests failed")
+func Result(passed bool, message string) {
+	if passed {
+		Success(message)
+	} else {
+		Error(message)
+	}
 }
\ No newline at end of file