@lewishowles/cli-style 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 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
 

package/README.md

@@ -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,64 +131,71 @@ 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 render
+from cli_style import status, row, span, hint, divider
 
-output = render(
-	"status",
-	{
-		"type": "success",
-		"label": "Build passed",
-		"detail": "184 tests",
-	},
-	profile="diagnostic",
-)
+kwargs = {"binary": "./bin/cli-style.js", "plain": True}
 
-print(output)
+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))
 ```
 
-Pass `binary=` when `cli-style` is not on `PATH`:
+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",
+		"title": "Release checks",
+		"checks": [{"name": "README", "result": "success"}],
 	},
-	binary="/path/to/cli-style",
-	plain=True,
+	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                      | 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.
 
 ## Primitive data shapes
 
@@ -277,6 +289,18 @@ 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.
+
 ### Pattern example
 
 JavaScript:

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/package.json

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