@lewishowles/cli-style 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 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
+
+- Added Python adapter convenience functions for scalar pattern usage: `command_result`, `audit_finding`, `task_summary`, `confirmation_result`, and `next_step_block`.
+- Added Python adapter convenience functions for common primitives: `status`, `row`, `span`, `hint`, and `divider`.
+- Added Bash adapter convenience functions for scalar pattern usage: `cli_style_command_result`, `cli_style_audit_finding`, `cli_style_task_summary`, `cli_style_confirmation_result`, and `cli_style_next_step_block`.
+- Added Bash adapter helpers for JSON string arrays and integer/null fields, so pattern wrappers can safely pass single-item list fields and exit codes.
+
+### Changed
+
+- Extended the README renderer table with a Python helper column covering all 20 renderers, including convenience functions and `render()` fallbacks for aggregate patterns.
+
 ## 0.6.0 - 2026-07-03
 
 ### 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
 
@@ -84,7 +84,7 @@ Use renderer names from the tables below, for example `status`, `row`, `diagnost
 
 ### Bash
 
-Source the Bash adapter, then use convenience helpers for common primitive renderers:
+Source the Bash adapter, then use convenience helpers for common primitive and per-script pattern renderers:
 
 ```bash
 source "$(cli-style adapter-path bash)"
@@ -98,6 +98,11 @@ cli_style_row "Bundle" "is 22.3 KB, above the 12.0 KB budget" failed --plain
 command="$(cli_style_span "npm run docs:readme" info --plain)"
 cli_style_hint "Run $command before release" --plain
 cli_style_divider "Project setup" --plain
+
+cli_style_command_result success "Build passed" "bun run test:unit" 0 "1.2s" "184 tests" --plain
+cli_style_task_summary partial "Adopt cli-style" "Bash wrappers added" "Updated adapter" "Update scripts" --plain
+cli_style_confirmation_result confirmed "Publish release" "v0.6.0" "Tag push starts npm publish" --plain
+cli_style_next_step_block "Update helpers scripts" "Wrappers are now available" "scripts/setup.sh --check" "" --plain
 ```
 
 The convenience functions build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
@@ -108,7 +113,7 @@ Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
 CLI_STYLE_BIN="/path/to/cli-style" cli_style_status success "Build passed" "" --plain
 ```
 
-Use `cli_style_render` for literal or prebuilt JSON, especially for structured patterns:
+Use `cli_style_render` for literal or prebuilt JSON, especially for aggregate patterns or multi-item pattern fields:
 
 ```bash
 cli_style_render diagnostic-report --profile diagnostic <<'JSON'
@@ -126,21 +131,37 @@ JSON
 
 ### Python
 
-Add the adapter directory to `PYTHONPATH`, then import the generic `render()` helper:
+Add the adapter directory to `PYTHONPATH`, then import the generic `render()` helper or convenience functions:
 
 ```bash
 export PYTHONPATH="$(cli-style adapter-path python):$PYTHONPATH"
 ```
 
+```python
+from cli_style import status, row, span, hint, divider
+
+kwargs = {"binary": "./bin/cli-style.js", "plain": True}
+
+print(status("success", "Build passed", "184 tests", **kwargs))
+print(row("Workspace", "/path/to/project", **kwargs))
+print(row("Bundle", "over budget", "failed", **kwargs))
+command = span("npm run docs:readme", "info", **kwargs)
+print(hint(f"Run {command} before release", **kwargs))
+print(divider("Project setup", **kwargs))
+```
+
+Convenience functions build the renderer payload internally, so callers pass plain Python strings without hand-building JSON.
+
+Pass `binary=` when `cli-style` is not on `PATH`. The generic `render()` helper remains for aggregate patterns or multi-item fields:
+
 ```python
 from cli_style import render
 
 output = render(
-	"status",
+	"diagnostic-report",
 	{
-		"type": "success",
-		"label": "Build passed",
-		"detail": "184 tests",
+		"title": "Release checks",
+		"checks": [{"name": "README", "result": "success"}],
 	},
 	profile="diagnostic",
 )
@@ -148,42 +169,75 @@ output = render(
 print(output)
 ```
 
-Pass `binary=` when `cli-style` is not on `PATH`:
+### Swift
 
-```python
-output = render(
-	"status",
-	{
-		"type": "success",
-		"label": "Build passed",
-	},
-	binary="/path/to/cli-style",
-	plain=True,
+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                          | Purpose                                                         |
-| --------------- | ------------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
-| `status`        | `status(resultType, detail, options)` | `cli_style_status type label detail` | Result line with symbol, label, and detail.                     |
-| `row`           | `row(label, value, options)`          | `cli_style_row label value [result]` | Aligned label/value row, optionally marked with a result state. |
-| `span`          | `span(value, tone, options)`          | `cli_style_span value [tone]`        | Inline colour or weight for a word, command, file, or value.    |
-| `hint`          | `hint(message, options)`              | `cli_style_hint message`             | Informational hint line.                                        |
-| `divider`       | `divider(options)`                    | `cli_style_divider label`            | Section divider with an optional label.                         |
-| `chip`          | `chip(label, tone, options)`          | Use `cli_style_render`               | Compact labelled state.                                         |
-| `panel`         | `panel(options)`                      | Use `cli_style_render`               | Framed content block for grouped output.                        |
-| `table`         | `table(options)`                      | Use `cli_style_render`               | Tabular records with narrow-width fallback.                     |
-| `progress-bar`  | `progressBar(options)`                | Use `cli_style_render`               | Single progress value with numeric text.                        |
-| `bar-chart`     | `barChart(options)`                   | Use `cli_style_render`               | Multi-row bar chart.                                            |
-| `step`          | `step(label, state, options)`         | Use `cli_style_render`               | One workflow step.                                              |
-| `step-progress` | `stepProgress(options)`               | Use `cli_style_render`               | Numbered workflow steps.                                        |
-| `empty-state`   | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Empty result message.                                           |
-| `error-block`   | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Structured error block.                                         |
-
-Python uses `render("<renderer>", data, ...)` for every renderer.
+| 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
 
@@ -277,6 +331,20 @@ Patterns are built-in composite renderers for common report shapes. They use the
 
 For visual examples, run `cli-style gallery --section patterns`.
 
+The Bash adapter also exposes scalar convenience wrappers for per-script usage:
+
+| Bash helper                     | Renderer              | Arguments before render flags                                              |
+| ------------------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `cli_style_command_result`      | `command-result`      | `result`, `summary`, `command`, `exit_code`, `duration`, `detail`          |
+| `cli_style_audit_finding`       | `audit-finding`       | `result`, `finding`, `location`, `recommendation`, `evidence`, `reference` |
+| `cli_style_task_summary`        | `task-summary`        | `result`, `task`, `summary`, `completed`, `remaining`                      |
+| `cli_style_confirmation_result` | `confirmation-result` | `state`, `action`, `item`, `detail`                                        |
+| `cli_style_next_step_block`     | `next-step-block`     | `next`, `reason`, `command`, `alternative`                                 |
+
+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:
@@ -464,6 +532,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/bash/cli-style.sh

@@ -41,6 +41,41 @@ cli_style_json_string() {
 	printf '"%s"' "$value"
 }
 
+# Escape Bash strings for a JSON string array.
+#
+# @param  {string}  ...
+#     String values to encode. Empty values are skipped.
+cli_style_json_string_array() {
+	local item
+	local separator=""
+
+	printf '['
+
+	for item in "$@"; do
+		if [[ "$item" != "" ]]; then
+			printf '%s' "$separator"
+			cli_style_json_string "$item"
+			separator=","
+		fi
+	done
+
+	printf ']'
+}
+
+# Render a Bash value as a JSON integer or null.
+#
+# @param  {string}  value
+#     Integer value to encode.
+cli_style_json_integer_or_null() {
+	local value="${1:-}"
+
+	if [[ "$value" =~ ^-?[0-9]+$ ]]; then
+		printf '%s' "$value"
+	else
+		printf 'null'
+	fi
+}
+
 # Render a JSON object through the shared cli-style command.
 #
 # @param  {string}  renderer
@@ -208,3 +243,168 @@ cli_style_hint() {
 
 	cli_style_render_json hint "$json" "$@"
 }
+
+# Render a command result pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  summary
+#     Summary line.
+# @param  {string}  command
+#     Optional command text.
+# @param  {string}  exit_code
+#     Optional integer exit code.
+# @param  {string}  duration
+#     Optional duration text.
+# @param  {string}  detail
+#     Optional detail line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_command_result() {
+	local result="${1:-}"
+	local summary="${2:-}"
+	local command="${3:-}"
+	local exit_code="${4:-}"
+	local duration="${5:-}"
+	local detail="${6:-}"
+	local json
+
+	if (($# >= 6)); then
+		shift 6
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"summary\":$(cli_style_json_string "$summary"),\"command\":$(cli_style_json_string "$command"),\"exitCode\":$(cli_style_json_integer_or_null "$exit_code"),\"duration\":$(cli_style_json_string "$duration"),\"details\":$(cli_style_json_string_array "$detail")}"
+
+	cli_style_render_json command-result "$json" "$@"
+}
+
+# Render an audit finding pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  finding
+#     Finding summary.
+# @param  {string}  location
+#     Optional source location.
+# @param  {string}  recommendation
+#     Optional recommendation text.
+# @param  {string}  evidence
+#     Optional evidence line.
+# @param  {string}  reference
+#     Optional reference line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_audit_finding() {
+	local result="${1:-}"
+	local finding="${2:-}"
+	local location="${3:-}"
+	local recommendation="${4:-}"
+	local evidence="${5:-}"
+	local reference="${6:-}"
+	local json
+
+	if (($# >= 6)); then
+		shift 6
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"finding\":$(cli_style_json_string "$finding"),\"location\":$(cli_style_json_string "$location"),\"recommendation\":$(cli_style_json_string "$recommendation"),\"evidence\":$(cli_style_json_string_array "$evidence"),\"references\":$(cli_style_json_string_array "$reference")}"
+
+	cli_style_render_json audit-finding "$json" "$@"
+}
+
+# Render a task summary pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  task
+#     Task label.
+# @param  {string}  summary
+#     Optional summary detail.
+# @param  {string}  completed
+#     Optional completed item.
+# @param  {string}  remaining
+#     Optional remaining item.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_task_summary() {
+	local result="${1:-}"
+	local task="${2:-}"
+	local summary="${3:-}"
+	local completed="${4:-}"
+	local remaining="${5:-}"
+	local json
+
+	if (($# >= 5)); then
+		shift 5
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"task\":$(cli_style_json_string "$task"),\"summary\":$(cli_style_json_string "$summary"),\"completed\":$(cli_style_json_string_array "$completed"),\"remaining\":$(cli_style_json_string_array "$remaining")}"
+
+	cli_style_render_json task-summary "$json" "$@"
+}
+
+# Render a confirmation result pattern from Bash string values.
+#
+# @param  {string}  state
+#     Confirmation state such as confirmed, cancelled, or skipped.
+# @param  {string}  action
+#     Action label.
+# @param  {string}  item
+#     Optional item label.
+# @param  {string}  detail
+#     Optional detail text.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_confirmation_result() {
+	local state="${1:-}"
+	local action="${2:-}"
+	local item="${3:-}"
+	local detail="${4:-}"
+	local json
+
+	if (($# >= 4)); then
+		shift 4
+	else
+		set --
+	fi
+
+	json="{\"state\":$(cli_style_json_string "$state"),\"action\":$(cli_style_json_string "$action"),\"item\":$(cli_style_json_string "$item"),\"detail\":$(cli_style_json_string "$detail")}"
+
+	cli_style_render_json confirmation-result "$json" "$@"
+}
+
+# Render a next-step block pattern from Bash string values.
+#
+# @param  {string}  next
+#     Next step text.
+# @param  {string}  reason
+#     Optional reason text.
+# @param  {string}  command
+#     Optional command line.
+# @param  {string}  alternative
+#     Optional alternative line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_next_step_block() {
+	local next="${1:-}"
+	local reason="${2:-}"
+	local command="${3:-}"
+	local alternative="${4:-}"
+	local json
+
+	if (($# >= 4)); then
+		shift 4
+	else
+		set --
+	fi
+
+	json="{\"next\":$(cli_style_json_string "$next"),\"reason\":$(cli_style_json_string "$reason"),\"commands\":$(cli_style_json_string_array "$command"),\"alternatives\":$(cli_style_json_string_array "$alternative")}"
+
+	cli_style_render_json next-step-block "$json" "$@"
+}

package/adapters/python/cli_style.py

@@ -83,6 +83,221 @@ def render(
 	return result.stdout.rstrip("\n")
 
 
+# Render a result status line from Python values.
+#
+# @param  {str}  type
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  label
+#     Status label.
+# @param  {str}  detail
+#     Optional detail text.
+def status(
+	type: str,
+	label: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("status", {"type": type, "label": label, "detail": detail}, **kwargs)
+
+
+# Render a labelled value row from Python values.
+#
+# @param  {str}  label
+#     Row label.
+# @param  {str}  value
+#     Row value.
+# @param  {str}  result
+#     Optional result type for a symbol and tone.
+def row(
+	label: str,
+	value: str,
+	result: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("row", {"label": label, "value": value, "result": result}, **kwargs)
+
+
+# Render an inline span from Python values.
+#
+# @param  {str}  value
+#     Span text.
+# @param  {str}  tone
+#     Optional colour tone, defaulting to info.
+def span(
+	value: str,
+	tone: str = "info",
+	**kwargs: Any,
+) -> str:
+	return render("span", {"value": value, "tone": tone}, **kwargs)
+
+
+# Render a divider from a Python value.
+#
+# @param  {str}  label
+#     Optional divider label.
+def divider(
+	label: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("divider", {"label": label}, **kwargs)
+
+
+# Render a hint from a Python value.
+#
+# @param  {str}  message
+#     Hint message.
+def hint(
+	message: str,
+	**kwargs: Any,
+) -> str:
+	return render("hint", {"message": message}, **kwargs)
+
+
+# Render a command result pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  summary
+#     Summary line.
+# @param  {str}  command
+#     Optional command text.
+# @param  {int|None}  exit_code
+#     Optional integer exit code.
+# @param  {str}  duration
+#     Optional duration text.
+# @param  {str}  detail
+#     Optional detail line.
+def command_result(
+	result: str,
+	summary: str,
+	command: str = "",
+	exit_code: int | None = None,
+	duration: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("command-result", {
+		"result": result,
+		"summary": summary,
+		"command": command,
+		"exitCode": exit_code,
+		"duration": duration,
+		"details": [detail] if detail else [],
+	}, **kwargs)
+
+
+# Render an audit finding pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  finding
+#     Finding summary.
+# @param  {str}  location
+#     Optional source location.
+# @param  {str}  recommendation
+#     Optional recommendation text.
+# @param  {str}  evidence
+#     Optional evidence line.
+# @param  {str}  reference
+#     Optional reference line.
+def audit_finding(
+	result: str,
+	finding: str,
+	location: str = "",
+	recommendation: str = "",
+	evidence: str = "",
+	reference: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("audit-finding", {
+		"result": result,
+		"finding": finding,
+		"location": location,
+		"recommendation": recommendation,
+		"evidence": [evidence] if evidence else [],
+		"references": [reference] if reference else [],
+	}, **kwargs)
+
+
+# Render a task summary pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  task
+#     Task label.
+# @param  {str}  summary
+#     Optional summary detail.
+# @param  {str}  completed
+#     Optional completed item.
+# @param  {str}  remaining
+#     Optional remaining item.
+def task_summary(
+	result: str,
+	task: str,
+	summary: str = "",
+	completed: str = "",
+	remaining: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("task-summary", {
+		"result": result,
+		"task": task,
+		"summary": summary,
+		"completed": [completed] if completed else [],
+		"remaining": [remaining] if remaining else [],
+	}, **kwargs)
+
+
+# Render a confirmation result pattern from Python values.
+#
+# @param  {str}  state
+#     Confirmation state such as confirmed, cancelled, or skipped.
+# @param  {str}  action
+#     Action label.
+# @param  {str}  item
+#     Optional item label.
+# @param  {str}  detail
+#     Optional detail text.
+def confirmation_result(
+	state: str,
+	action: str,
+	item: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("confirmation-result", {
+		"state": state,
+		"action": action,
+		"item": item,
+		"detail": detail,
+	}, **kwargs)
+
+
+# Render a next-step block pattern from Python values.
+#
+# @param  {str}  next_step
+#     Next step text.
+# @param  {str}  reason
+#     Optional reason text.
+# @param  {str}  command
+#     Optional command line.
+# @param  {str}  alternative
+#     Optional alternative line.
+def next_step_block(
+	next_step: str,
+	reason: str = "",
+	command: str = "",
+	alternative: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("next-step-block", {
+		"next": next_step,
+		"reason": reason,
+		"commands": [command] if command else [],
+		"alternatives": [alternative] if alternative else [],
+	}, **kwargs)
+
+
 # Resolve a command name or executable path for subprocess use.
 #
 # @param  {str}  binary

package/adapters/swift/CliStyle.swift

@@ -0,0 +1,407 @@
+import Foundation
+
+// 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
+
+		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)
+	}
+
+	/**
+	 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.6.0",
+	"version": "0.8.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

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.