@lewishowles/cli-style 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## 0.8.1 - 2026-07-15
+
+### Fixed
+
+- Fixed the Python and Swift adapters losing ANSI colour: they now set `FORCE_COLOR=1` for the child process when the caller's own stdout is a TTY, unless the caller has already set `FORCE_COLOR` or `NO_COLOR`.
+- Documented that captured Bash output (command substitution) cannot auto-detect its eventual destination and requires an explicit `FORCE_COLOR=1` to opt into colour.
+
+## 0.8.0 - 2026-07-05
+
+### Added
+
+- Added Swift adapter with convenience functions for scalar primitives and per-script patterns: `CliStyle.status`, `CliStyle.row`, `CliStyle.span`, `CliStyle.hint`, `CliStyle.divider`, `CliStyle.commandResult`, `CliStyle.auditFinding`, `CliStyle.taskSummary`, `CliStyle.confirmationResult`, and `CliStyle.nextStepBlock`.
+- Added `cli-style adapter-path swift` support for discovering the Swift adapter file path.
+
+### Changed
+
+- Extended the README renderer table with a Swift helper column covering all 20 renderers.
+
 ## 0.7.0 - 2026-07-05
 
 ### Added

package/README.md

@@ -2,12 +2,12 @@
 
 Shared terminal output styles for local tools, diagnostics, agent-facing reports, and package CLIs.
 
-Use it directly from JavaScript, or call the same renderers from Bash and Python through the `cli-style` binary.
+Use it directly from JavaScript, or call the same renderers from Bash, Python, and Swift through the `cli-style` binary.
 
 ## Requirements
 
 - Bun and Node.js 20 or newer for JavaScript projects and local binary builds
-- The standalone `cli-style` binary for Bash or Python projects that should not install Bun
+- The standalone `cli-style` binary for Bash, Python, or Swift projects that should not install Bun
 
 ## Install
 
@@ -17,7 +17,7 @@ JavaScript projects can install the package directly:
 bun add @lewishowles/cli-style
 ```
 
-Bash and Python projects call the `cli-style` binary through thin adapters. If the project already has Node or Bun tooling, add this package as a dev dependency and use the package binary. Otherwise, install or vendor the standalone binary and put it on `PATH`:
+Bash, Python, and Swift projects call the `cli-style` binary through thin adapters. If the project already has Node or Bun tooling, add this package as a dev dependency and use the package binary. Otherwise, install or vendor the standalone binary and put it on `PATH`:
 
 ```bash
 export PATH="/path/to/cli-style/bin:$PATH"
@@ -41,7 +41,7 @@ The package contains `bin/cli-style` and `adapters/`.
 
 ## Choose an integration
 
-All renderers return text. JavaScript imports functions directly. CLI, Bash, and Python integrations pass JSON-compatible data to a named renderer.
+All renderers return text. JavaScript imports functions directly. CLI, Bash, Python, and Swift integrations pass JSON-compatible data to a named renderer.
 
 ### JavaScript
 
@@ -107,6 +107,14 @@ cli_style_next_step_block "Update helpers scripts" "Wrappers are now available"
 
 The convenience functions build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
 
+Direct Bash calls use `cli-style`'s native stdout detection. When a helper's output is captured, the adapter cannot know where the captured text will be written, so set `FORCE_COLOR=1` explicitly when the destination is an interactive terminal:
+
+```bash
+command="$(FORCE_COLOR=1 cli_style_span "npm run docs:readme" info)"
+```
+
+Python and Swift automatically set `FORCE_COLOR=1` for the child render process when their caller's stdout is an interactive terminal. An existing `FORCE_COLOR` or `NO_COLOR` value is preserved. `FORCE_COLOR=0` does not enable colour, while `NO_COLOR`, `TERM=dumb`, and explicit no-colour flags remain authoritative.
+
 Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
 
 ```bash
@@ -169,33 +177,75 @@ output = render(
 print(output)
 ```
 
+### Swift
+
+Add the adapter file to your Swift project, then use the `CliStyle` enum for convenience functions or the generic `render` method:
+
+```bash
+cli-style adapter-path swift
+# Returns the path to CliStyle.swift for inclusion in your project
+```
+
+```swift
+let options = CliStyleOptions(binary: "./bin/cli-style.js", isPlain: true)
+
+print(try CliStyle.status(type: "success", label: "Build passed", detail: "184 tests", options: options))
+print(try CliStyle.row(label: "Workspace", value: "/path/to/project", options: options))
+print(try CliStyle.row(label: "Bundle", value: "over budget", result: "failed", options: options))
+let command = try CliStyle.span(value: "npm run docs:readme", tone: "info", options: options)
+print(try CliStyle.hint(message: "Run " + command + " before release", options: options))
+print(try CliStyle.divider(label: "Project setup", options: options))
+
+print(try CliStyle.commandResult(result: "success", summary: "Build passed", command: "bun run test:unit", exitCode: 0, duration: "1.2s", detail: "184 tests", options: options))
+print(try CliStyle.taskSummary(result: "partial", task: "Adopt cli-style", summary: "Wrappers added", completed: "Updated adapter", remaining: "Update scripts", options: options))
+print(try CliStyle.confirmationResult(state: "confirmed", action: "Publish release", item: "v0.6.0", detail: "Tag push starts npm publish", options: options))
+print(try CliStyle.nextStepBlock(nextStep: "Update helpers scripts", reason: "Wrappers are now available", command: "scripts/setup.sh --check", alternative: "", options: options))
+```
+
+Convenience functions build the renderer payload internally, so callers pass plain Swift strings without hand-building JSON.
+
+Pass `binary:` in `CliStyleOptions` when `cli-style` is not on `PATH`. The generic `CliStyle.render(_:data:options:)` method remains for aggregate patterns or multi-item fields:
+
+```swift
+let output = try CliStyle.render(
+    "diagnostic-report",
+    data: [
+        "title": "Release checks",
+        "checks": [["name": "README", "result": "success"]],
+    ],
+    options: CliStyleOptions(profile: "diagnostic")
+)
+
+print(output)
+```
+
 ## Available renderers
 
 Renderer names are stable for `cli-style render`, `cli_style_render`, and Python `render()`. JavaScript uses camel-case function names.
 
-| Renderer              | JavaScript                            | Bash helper                          | Python helper                      | Purpose                                                         |
-| --------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
-| `status`              | `status(resultType, detail, options)` | `cli_style_status type label detail` | `status(type, label, detail)`      | Result line with symbol, label, and detail.                     |
-| `row`                 | `row(label, value, options)`          | `cli_style_row label value [result]` | `row(label, value, result)`        | Aligned label/value row, optionally marked with a result state. |
-| `span`                | `span(value, tone, options)`          | `cli_style_span value [tone]`        | `span(value, tone)`                | Inline colour or weight for a word, command, file, or value.    |
-| `hint`                | `hint(message, options)`              | `cli_style_hint message`             | `hint(message)`                    | Informational hint line.                                        |
-| `divider`             | `divider(options)`                    | `cli_style_divider label`            | `divider(label)`                   | Section divider with an optional label.                         |
-| `command-result`      | `commandResult(options)`              | `cli_style_command_result ...`       | `command_result(...)`              | Command execution outcome with exit code and duration.          |
-| `audit-finding`       | `auditFinding(options)`               | `cli_style_audit_finding ...`        | `audit_finding(...)`               | Structured audit finding with evidence and recommendation.      |
-| `task-summary`        | `taskSummary(options)`                | `cli_style_task_summary ...`         | `task_summary(...)`                | Task progress with completed and remaining items.               |
-| `confirmation-result` | `confirmationResult(options)`         | `cli_style_confirmation_result ...`  | `confirmation_result(...)`         | Confirmation outcome with action and item.                      |
-| `next-step-block`     | `nextStepBlock(options)`              | `cli_style_next_step_block ...`      | `next_step_block(...)`             | Next-step guidance with command and alternative.                |
-| `chip`                | `chip(label, tone, options)`          | Use `cli_style_render`               | Use `render("chip", ...)`          | Compact labelled state.                                         |
-| `panel`               | `panel(options)`                      | Use `cli_style_render`               | Use `render("panel", ...)`         | Framed content block for grouped output.                        |
-| `table`               | `table(options)`                      | Use `cli_style_render`               | Use `render("table", ...)`         | Tabular records with narrow-width fallback.                     |
-| `progress-bar`        | `progressBar(options)`                | Use `cli_style_render`               | Use `render("progress-bar", ...)`  | Single progress value with numeric text.                        |
-| `bar-chart`           | `barChart(options)`                   | Use `cli_style_render`               | Use `render("bar-chart", ...)`     | Multi-row bar chart.                                            |
-| `step`                | `step(label, state, options)`         | Use `cli_style_render`               | Use `render("step", ...)`          | One workflow step.                                              |
-| `step-progress`       | `stepProgress(options)`               | Use `cli_style_render`               | Use `render("step-progress", ...)` | Numbered workflow steps.                                        |
-| `empty-state`         | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Use `render("empty-state", ...)`   | Empty result message.                                           |
-| `error-block`         | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Use `render("error-block", ...)`   | Structured error block.                                         |
-
-Use `render("<renderer>", data, ...)` for aggregate patterns (`diagnostic-report`, `agent-transcript`, `compact-data-table`) or any renderer with multi-item fields.
+| Renderer              | JavaScript                            | Bash helper                          | Python helper                      | Swift helper                           | Purpose                                                         |
+| --------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
+| `status`              | `status(resultType, detail, options)` | `cli_style_status type label detail` | `status(type, label, detail)`      | `CliStyle.status(type, label, detail)` | Result line with symbol, label, and detail.                     |
+| `row`                 | `row(label, value, options)`          | `cli_style_row label value [result]` | `row(label, value, result)`        | `CliStyle.row(label, value, result)`   | Aligned label/value row, optionally marked with a result state. |
+| `span`                | `span(value, tone, options)`          | `cli_style_span value [tone]`        | `span(value, tone)`                | `CliStyle.span(value, tone)`           | Inline colour or weight for a word, command, file, or value.    |
+| `hint`                | `hint(message, options)`              | `cli_style_hint message`             | `hint(message)`                    | `CliStyle.hint(message)`               | Informational hint line.                                        |
+| `divider`             | `divider(options)`                    | `cli_style_divider label`            | `divider(label)`                   | `CliStyle.divider(label)`              | Section divider with an optional label.                         |
+| `command-result`      | `commandResult(options)`              | `cli_style_command_result ...`       | `command_result(...)`              | `CliStyle.commandResult(...)`          | Command execution outcome with exit code and duration.          |
+| `audit-finding`       | `auditFinding(options)`               | `cli_style_audit_finding ...`        | `audit_finding(...)`               | `CliStyle.auditFinding(...)`           | Structured audit finding with evidence and recommendation.      |
+| `task-summary`        | `taskSummary(options)`                | `cli_style_task_summary ...`         | `task_summary(...)`                | `CliStyle.taskSummary(...)`            | Task progress with completed and remaining items.               |
+| `confirmation-result` | `confirmationResult(options)`         | `cli_style_confirmation_result ...`  | `confirmation_result(...)`         | `CliStyle.confirmationResult(...)`     | Confirmation outcome with action and item.                      |
+| `next-step-block`     | `nextStepBlock(options)`              | `cli_style_next_step_block ...`      | `next_step_block(...)`             | `CliStyle.nextStepBlock(...)`          | Next-step guidance with command and alternative.                |
+| `chip`                | `chip(label, tone, options)`          | Use `cli_style_render`               | Use `render("chip", ...)`          | Use `CliStyle.render`                  | Compact labelled state.                                         |
+| `panel`               | `panel(options)`                      | Use `cli_style_render`               | Use `render("panel", ...)`         | Use `CliStyle.render`                  | Framed content block for grouped output.                        |
+| `table`               | `table(options)`                      | Use `cli_style_render`               | Use `render("table", ...)`         | Use `CliStyle.render`                  | Tabular records with narrow-width fallback.                     |
+| `progress-bar`        | `progressBar(options)`                | Use `cli_style_render`               | Use `render("progress-bar", ...)`  | Use `CliStyle.render`                  | Single progress value with numeric text.                        |
+| `bar-chart`           | `barChart(options)`                   | Use `cli_style_render`               | Use `render("bar-chart", ...)`     | Use `CliStyle.render`                  | Multi-row bar chart.                                            |
+| `step`                | `step(label, state, options)`         | Use `cli_style_render`               | Use `render("step", ...)`          | Use `CliStyle.render`                  | One workflow step.                                              |
+| `step-progress`       | `stepProgress(options)`               | Use `cli_style_render`               | Use `render("step-progress", ...)` | Use `CliStyle.render`                  | Numbered workflow steps.                                        |
+| `empty-state`         | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Use `render("empty-state", ...)`   | Use `CliStyle.render`                  | Empty result message.                                           |
+| `error-block`         | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Use `render("error-block", ...)`   | Use `CliStyle.render`                  | Structured error block.                                         |
+
+Use `render("<renderer>", data, ...)` (Python) or `CliStyle.render(_:data:options:)` (Swift) for aggregate patterns (`diagnostic-report`, `agent-transcript`, `compact-data-table`) or any renderer with multi-item fields.
 
 ## Primitive data shapes
 
@@ -301,6 +351,8 @@ The Bash adapter also exposes scalar convenience wrappers for per-script usage:
 
 Pass an empty string for optional positional fields you want to skip. Use `cli_style_render` or `cli_style_render_json` for aggregate reports, tables, transcripts, and multi-item arrays.
 
+Swift equivalents are available as `CliStyle.commandResult(...)`, `CliStyle.auditFinding(...)`, `CliStyle.taskSummary(...)`, `CliStyle.confirmationResult(...)`, and `CliStyle.nextStepBlock(...)`. Use `CliStyle.render` for aggregate reports, tables, transcripts, and multi-item arrays.
+
 ### Pattern example
 
 JavaScript:
@@ -462,7 +514,7 @@ Most renderers accept the same output options:
 | `unicode` | Whether Unicode symbols should be used.                                   |
 | `width`   | Available output width for renderers that adapt layout.                   |
 
-Use `createCliStyle()` to resolve these options from `argv`, `env`, `stdout`, CI, TTY, `NO_COLOR`, and terminal capability.
+Use `createCliStyle()` to resolve these options from `argv`, `env`, `stdout`, CI, TTY, `NO_COLOR`, `FORCE_COLOR`, and terminal capability.
 
 ### CLI and Bash flags
 
@@ -488,6 +540,20 @@ Use `createCliStyle()` to resolve these options from `argv`, `env`, `stdout`, CI
 | `binary`     | Path or command name for the `cli-style` binary. |
 | `extra_args` | Extra CLI arguments to pass through.             |
 
+### Swift options
+
+Swift options are passed via the `CliStyleOptions` struct:
+
+| Property      | Purpose                                          |
+| ------------- | ------------------------------------------------ |
+| `binary`      | Path or command name for the `cli-style` binary. |
+| `profile`     | Render with a named profile.                     |
+| `width`       | Override detected output width.                  |
+| `isPlain`     | Disable colour and Unicode decoration.           |
+| `isNoColour`  | Disable ANSI colour.                             |
+| `isNoUnicode` | Use ASCII symbols.                               |
+| `extraArgs`   | Extra CLI arguments to pass through.             |
+
 ## Profiles
 
 | Profile      | Behaviour                                                                         |

package/adapters/python/cli_style.py

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 from typing import Any, Sequence
 
@@ -23,6 +24,20 @@ class CliStyleRenderError(CliStyleError):
 	"""Raised when cli-style rejects a render request."""
 
 
+# Resolve the child environment while preserving explicit caller controls.
+def resolve_subprocess_environment() -> dict[str, str]:
+	environment = os.environ.copy()
+
+	if (
+		sys.stdout.isatty()
+		and "FORCE_COLOR" not in environment
+		and "NO_COLOR" not in environment
+	):
+		environment["FORCE_COLOR"] = "1"
+
+	return environment
+
+
 # Render caller data through `cli-style render`.
 #
 # @param  {str}  renderer
@@ -72,6 +87,7 @@ def render(
 		command,
 		capture_output=True,
 		check=False,
+		env=resolve_subprocess_environment(),
 		input=json.dumps(data),
 		text=True,
 	)

package/adapters/swift/CliStyle.swift

@@ -0,0 +1,428 @@
+import Foundation
+#if canImport(Darwin)
+import Darwin
+#elseif canImport(Glibc)
+import Glibc
+#endif
+
+// Error types for cli-style adapter failures.
+enum CliStyleError: Error {
+	case notFound(String)
+	case renderFailed(String)
+	case invalidInput(String)
+}
+
+// Options for controlling cli-style render behaviour.
+struct CliStyleOptions {
+	// Binary path or command name.
+	var binary: String = "cli-style"
+
+	// Profile name such as human, agent, or json.
+	var profile: String? = nil
+
+	// Terminal width in characters.
+	var width: Int? = nil
+
+	// Force plain text output.
+	var isPlain: Bool = false
+
+	// Disable colour output.
+	var isNoColour: Bool = false
+
+	// Disable Unicode symbols.
+	var isNoUnicode: Bool = false
+
+	// Additional arguments passed through to the binary.
+	var extraArgs: [String] = []
+}
+
+// Render caller data through the shared cli-style binary.
+enum CliStyle {
+
+	/**
+	 Render a dictionary through `cli-style render`.
+
+	 - parameter renderer: Stable renderer name accepted by `cli-style render`.
+	 - parameter data: JSON-serialisable renderer input.
+	 - parameter options: Render options including binary path and output flags.
+	 - returns: Rendered string output from cli-style.
+	 - throws: `CliStyleError` if the binary is missing, input is invalid, or rendering fails.
+	 */
+	static func render(
+		_ renderer: String,
+		data: [String: Any],
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		if renderer.isEmpty {
+			throw CliStyleError.invalidInput("renderer must be a non-empty string")
+		}
+
+		let resolvedBinary = try resolveBinary(options.binary)
+
+		let jsonData: Data
+
+		do {
+			jsonData = try JSONSerialization.data(withJSONObject: data)
+		} catch {
+			throw CliStyleError.invalidInput("data is not JSON-serialisable")
+		}
+
+		var arguments = ["render", renderer]
+
+		if let profile = options.profile {
+			arguments += ["--profile", profile]
+		}
+
+		if let width = options.width {
+			arguments += ["--width", String(width)]
+		}
+
+		if options.isPlain {
+			arguments.append("--plain")
+		}
+
+		if options.isNoColour {
+			arguments.append("--no-colour")
+		}
+
+		if options.isNoUnicode {
+			arguments.append("--no-unicode")
+		}
+
+		arguments += options.extraArgs
+
+		let process = Process()
+		process.executableURL = URL(fileURLWithPath: resolvedBinary)
+		process.arguments = arguments
+		process.environment = resolveProcessEnvironment()
+
+		let stdinPipe = Pipe()
+		let stdoutPipe = Pipe()
+		let stderrPipe = Pipe()
+		process.standardInput = stdinPipe
+		process.standardOutput = stdoutPipe
+		process.standardError = stderrPipe
+
+		do {
+			try process.run()
+		} catch {
+			throw CliStyleError.renderFailed("failed to launch cli-style: \(error.localizedDescription)")
+		}
+
+		stdinPipe.fileHandleForWriting.write(jsonData)
+		stdinPipe.fileHandleForWriting.closeFile()
+
+		process.waitUntilExit()
+
+		let stdoutData = stdoutPipe.fileHandleForReading.readDataToEndOfFile()
+		let stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()
+
+		if process.terminationStatus != 0 {
+			let stderrText = String(data: stderrData, encoding: .utf8)?
+				.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+			let message = stderrText.isEmpty
+				? "cli-style render failed with exit code \(process.terminationStatus)"
+				: stderrText
+
+			throw CliStyleError.renderFailed(message)
+		}
+
+		let stdoutText = String(data: stdoutData, encoding: .utf8) ?? ""
+		return stdoutText.trimmingCharacters(in: .newlines)
+	}
+
+	/**
+	 * Resolve the child environment for a captured render.
+	 */
+	private static func resolveProcessEnvironment() -> [String: String] {
+		var environment = ProcessInfo.processInfo.environment
+
+		if isatty(STDOUT_FILENO) == 1 &&
+			environment["FORCE_COLOR"] == nil &&
+			environment["NO_COLOR"] == nil {
+			environment["FORCE_COLOR"] = "1"
+		}
+
+		return environment
+	}
+
+	/**
+	 Render a result status line.
+
+	 - parameter type: Result type such as success, failed, warning, or skipped.
+	 - parameter label: Status label.
+	 - parameter detail: Optional detail text.
+	 - parameter options: Render options.
+	 - returns: Rendered status line.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func status(
+		type: String,
+		label: String = "",
+		detail: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("status", data: [
+			"type": type,
+			"label": label,
+			"detail": detail,
+		], options: options)
+	}
+
+	/**
+	 Render a labelled value row.
+
+	 - parameter label: Row label.
+	 - parameter value: Row value.
+	 - parameter result: Optional result type for a symbol and tone.
+	 - parameter options: Render options.
+	 - returns: Rendered row line.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func row(
+		label: String,
+		value: String,
+		result: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("row", data: [
+			"label": label,
+			"value": value,
+			"result": result,
+		], options: options)
+	}
+
+	/**
+	 Render an inline span.
+
+	 - parameter value: Span text.
+	 - parameter tone: Optional colour tone, defaulting to info.
+	 - parameter options: Render options.
+	 - returns: Rendered span string.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func span(
+		value: String,
+		tone: String = "info",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("span", data: [
+			"value": value,
+			"tone": tone,
+		], options: options)
+	}
+
+	/**
+	 Render a divider.
+
+	 - parameter label: Optional divider label.
+	 - parameter options: Render options.
+	 - returns: Rendered divider line.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func divider(
+		label: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("divider", data: [
+			"label": label,
+		], options: options)
+	}
+
+	/**
+	 Render a hint.
+
+	 - parameter message: Hint message.
+	 - parameter options: Render options.
+	 - returns: Rendered hint line.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func hint(
+		message: String,
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("hint", data: [
+			"message": message,
+		], options: options)
+	}
+
+	/**
+	 Render a command result pattern.
+
+	 - parameter result: Result type such as success, failed, warning, or skipped.
+	 - parameter summary: Summary line.
+	 - parameter command: Optional command text.
+	 - parameter exitCode: Optional integer exit code.
+	 - parameter duration: Optional duration text.
+	 - parameter detail: Optional detail line.
+	 - parameter options: Render options.
+	 - returns: Rendered command result block.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func commandResult(
+		result: String,
+		summary: String,
+		command: String = "",
+		exitCode: Int? = nil,
+		duration: String = "",
+		detail: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		var data: [String: Any] = [
+			"result": result,
+			"summary": summary,
+			"command": command,
+			"duration": duration,
+			"details": detail.isEmpty ? [] : [detail],
+		]
+
+		// JSONSerialization needs NSNull for explicit null values.
+		if let exitCode = exitCode {
+			data["exitCode"] = exitCode
+		} else {
+			data["exitCode"] = NSNull()
+		}
+
+		return try render("command-result", data: data, options: options)
+	}
+
+	/**
+	 Render an audit finding pattern.
+
+	 - parameter result: Result type such as success, failed, warning, or skipped.
+	 - parameter finding: Finding summary.
+	 - parameter location: Optional source location.
+	 - parameter recommendation: Optional recommendation text.
+	 - parameter evidence: Optional evidence line.
+	 - parameter reference: Optional reference line.
+	 - parameter options: Render options.
+	 - returns: Rendered audit finding block.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func auditFinding(
+		result: String,
+		finding: String,
+		location: String = "",
+		recommendation: String = "",
+		evidence: String = "",
+		reference: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("audit-finding", data: [
+			"result": result,
+			"finding": finding,
+			"location": location,
+			"recommendation": recommendation,
+			"evidence": evidence.isEmpty ? [] : [evidence],
+			"references": reference.isEmpty ? [] : [reference],
+		], options: options)
+	}
+
+	/**
+	 Render a task summary pattern.
+
+	 - parameter result: Result type such as success, failed, warning, or skipped.
+	 - parameter task: Task label.
+	 - parameter summary: Optional summary detail.
+	 - parameter completed: Optional completed item.
+	 - parameter remaining: Optional remaining item.
+	 - parameter options: Render options.
+	 - returns: Rendered task summary block.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func taskSummary(
+		result: String,
+		task: String,
+		summary: String = "",
+		completed: String = "",
+		remaining: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("task-summary", data: [
+			"result": result,
+			"task": task,
+			"summary": summary,
+			"completed": completed.isEmpty ? [] : [completed],
+			"remaining": remaining.isEmpty ? [] : [remaining],
+		], options: options)
+	}
+
+	/**
+	 Render a confirmation result pattern.
+
+	 - parameter state: Confirmation state such as confirmed, cancelled, or skipped.
+	 - parameter action: Action label.
+	 - parameter item: Optional item label.
+	 - parameter detail: Optional detail text.
+	 - parameter options: Render options.
+	 - returns: Rendered confirmation result block.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func confirmationResult(
+		state: String,
+		action: String,
+		item: String = "",
+		detail: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("confirmation-result", data: [
+			"state": state,
+			"action": action,
+			"item": item,
+			"detail": detail,
+		], options: options)
+	}
+
+	/**
+	 Render a next-step block pattern.
+
+	 - parameter nextStep: Next step text.
+	 - parameter reason: Optional reason text.
+	 - parameter command: Optional command line.
+	 - parameter alternative: Optional alternative line.
+	 - parameter options: Render options.
+	 - returns: Rendered next-step block.
+	 - throws: `CliStyleError` on failure.
+	 */
+	static func nextStepBlock(
+		nextStep: String,
+		reason: String = "",
+		command: String = "",
+		alternative: String = "",
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		try render("next-step-block", data: [
+			"next": nextStep,
+			"reason": reason,
+			"commands": command.isEmpty ? [] : [command],
+			"alternatives": alternative.isEmpty ? [] : [alternative],
+		], options: options)
+	}
+
+	/**
+	 Resolve a command name or executable path for subprocess use.
+
+	 - parameter binary: Binary path or command name.
+	 - returns: Resolved executable path.
+	 - throws: `CliStyleError.notFound` if the binary cannot be found.
+	 */
+	static func resolveBinary(_ binary: String) throws -> String {
+		if binary.contains("/") {
+			if FileManager.default.isExecutableFile(atPath: binary) {
+				return binary
+			}
+			throw CliStyleError.notFound("cli-style binary not found: \(binary)")
+		}
+
+		let path = ProcessInfo.processInfo.environment["PATH"] ?? ""
+
+		for directory in path.split(separator: ":") {
+			let candidate = "\(directory)/\(binary)"
+			if FileManager.default.isExecutableFile(atPath: candidate) {
+				return candidate
+			}
+		}
+
+		throw CliStyleError.notFound("cli-style binary not found: \(binary)")
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.7.0",
+	"version": "0.8.1",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

package/src/capability/terminal.js

@@ -23,12 +23,14 @@ export function resolveTerminalCapabilities(options = {}) {
 	const isTty = stdout.isTTY === true;
 	const isCi = env.CI === "true" || env.CI === "1";
 	const isDumb = env.TERM === "dumb";
+	const forceColour = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
 	const width = resolveWidth(stdout.columns);
 	const usesPlain = argv.includes("--plain");
 
 	const colour = resolveColour({
 		argv,
 		env,
+		forceColour,
 		isDumb,
 		isTty,
 		usesPlain,
@@ -69,7 +71,7 @@ function resolveColour(options) {
 		return false;
 	}
 
-	return options.isTty;
+	return options.forceColour || options.isTty;
 }
 
 /**

package/src/cli/adapter-path-command.js

@@ -12,6 +12,10 @@ const adapterPaths = {
 		releasePath: "adapters/python",
 		sourceUrl: new URL("../../adapters/python", import.meta.url),
 	},
+	swift: {
+		releasePath: "adapters/swift/CliStyle.swift",
+		sourceUrl: new URL("../../adapters/swift/CliStyle.swift", import.meta.url),
+	},
 };
 
 // Adapter names accepted by the adapter-path command.