@lewishowles/cli-style 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.9.0 - 2026-07-16
+
+### Added
+
+- Added a `rowGroup` primitive (`rowGroup()` in JS, the `row-group` renderer for `cli-style render`, and the same generic `render()`/`cli_style_render`/`CliStyle.render` entry points in Python, Bash, and Swift) that aligns a group of related rows automatically, without the caller computing `labelWidth` by hand.
+
+### Fixed
+
+- Fixed the Python, Bash, and Swift adapters silently dropping `row()`, `span()`, and `divider()` options beyond their two or three main fields. `row()` now forwards `labelWidth`, `labelColour`, `valueColour`, and `separator`; `span()` forwards `weight`; `divider()` forwards `dividerWidth`, `dividerColour`, and `labelColour`.
+
+## 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

package/README.md

@@ -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
@@ -219,6 +227,7 @@ Renderer names are stable for `cli-style render`, `cli_style_render`, and Python
 | --------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
 | `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. |
+| `row-group`           | `rowGroup(options)`                   | Use `cli_style_render`               | Use `render("row-group", ...)`     | Use `CliStyle.render`                  | Auto-aligned group of labelled value rows.                      |
 | `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.                         |
@@ -274,6 +283,27 @@ Use these shapes with `cli-style render`, `cli_style_render`, or Python `render(
 - `labelWidth`: optional minimum label width
 - `labelColour`, `valueColour`, `separator`: optional presentation overrides
 
+### `row-group`
+
+```json
+{
+	"rows": [
+		{
+			"label": "Package",
+			"value": "@lewishowles/components"
+		},
+		{
+			"label": "Version",
+			"value": "minor: 2.7.4 -> 2.8.0"
+		}
+	]
+}
+```
+
+- `rows`: labelled values to align and render
+- `labelWidth`: optional minimum width for every label
+- Per-row fields match `row`, including `label`, `value`, `result`, `labelColour`, `valueColour`, and `separator`
+
 ### `span`
 
 ```json
@@ -506,7 +536,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
 

package/adapters/bash/cli-style.sh

@@ -159,6 +159,11 @@ cli_style_row() {
 	local label="${1:-}"
 	local value="${2:-}"
 	local result=""
+	local label_width=""
+	local label_colour_json="null"
+	local value_colour_json="null"
+	local separator_json="null"
+	local -a render_args=()
 	local json
 
 	if (($# >= 3)) && [[ "${3:-}" != --* ]]; then
@@ -170,9 +175,60 @@ cli_style_row() {
 		set --
 	fi
 
-	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value"),\"result\":$(cli_style_json_string "$result")}"
+	while (($# > 0)); do
+		case "$1" in
+			--label-width)
+				label_width="${2:-}"
+				shift 2
+				;;
+			--label-width=*)
+				label_width="${1#*=}"
+				shift
+				;;
+			--label-colour)
+				label_colour_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--label-colour=*)
+				label_colour_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			--value-colour)
+				value_colour_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--value-colour=*)
+				value_colour_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			--separator)
+				separator_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--separator=*)
+				separator_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			*)
+				render_args+=("$1")
+				shift
+				;;
+		esac
+	done
+
+	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value"),\"result\":$(cli_style_json_string "$result"),\"labelWidth\":$(cli_style_json_integer_or_null "$label_width"),\"separator\":$separator_json"
+
+	if [[ "$label_colour_json" != "null" ]]; then
+		json="${json},\"labelColour\":$label_colour_json"
+	fi
 
-	cli_style_render_json row "$json" "$@"
+	if [[ "$value_colour_json" != "null" ]]; then
+		json="${json},\"valueColour\":$value_colour_json"
+	fi
+
+	json="${json}}"
+
+	cli_style_render_json row "$json" "${render_args[@]}"
 }
 
 # Render an inline span from Bash string values.
@@ -186,6 +242,8 @@ cli_style_row() {
 cli_style_span() {
 	local value="${1:-}"
 	local tone="info"
+	local weight_json="null"
+	local -a render_args=()
 	local json
 
 	if (($# >= 2)) && [[ "${2:-}" != --* ]]; then
@@ -197,9 +255,26 @@ cli_style_span() {
 		set --
 	fi
 
-	json="{\"value\":$(cli_style_json_string "$value"),\"tone\":$(cli_style_json_string "$tone")}"
+	while (($# > 0)); do
+		case "$1" in
+			--weight)
+				weight_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--weight=*)
+				weight_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			*)
+				render_args+=("$1")
+				shift
+				;;
+		esac
+	done
+
+	json="{\"value\":$(cli_style_json_string "$value"),\"tone\":$(cli_style_json_string "$tone"),\"weight\":$weight_json}"
 
-	cli_style_render_json span "$json" "$@"
+	cli_style_render_json span "$json" "${render_args[@]}"
 }
 
 # Render a divider from a Bash string value.
@@ -210,6 +285,10 @@ cli_style_span() {
 #     Render flags passed through to `cli-style render`.
 cli_style_divider() {
 	local label="${1:-}"
+	local divider_width=""
+	local divider_colour_json="null"
+	local label_colour_json="null"
+	local -a render_args=()
 	local json
 
 	if (($# >= 1)); then
@@ -218,9 +297,52 @@ cli_style_divider() {
 		set --
 	fi
 
-	json="{\"label\":$(cli_style_json_string "$label")}"
+	while (($# > 0)); do
+		case "$1" in
+			--divider-width)
+				divider_width="${2:-}"
+				shift 2
+				;;
+			--divider-width=*)
+				divider_width="${1#*=}"
+				shift
+				;;
+			--divider-colour)
+				divider_colour_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--divider-colour=*)
+				divider_colour_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			--label-colour)
+				label_colour_json="$(cli_style_json_string "${2:-}")"
+				shift 2
+				;;
+			--label-colour=*)
+				label_colour_json="$(cli_style_json_string "${1#*=}")"
+				shift
+				;;
+			*)
+				render_args+=("$1")
+				shift
+				;;
+		esac
+	done
+
+	json="{\"label\":$(cli_style_json_string "$label"),\"dividerWidth\":$(cli_style_json_integer_or_null "$divider_width")"
+
+	if [[ "$divider_colour_json" != "null" ]]; then
+		json="${json},\"dividerColour\":$divider_colour_json"
+	fi
+
+	if [[ "$label_colour_json" != "null" ]]; then
+		json="${json},\"labelColour\":$label_colour_json"
+	fi
+
+	json="${json}}"
 
-	cli_style_render_json divider "$json" "$@"
+	cli_style_render_json divider "$json" "${render_args[@]}"
 }
 
 # Render a hint from a Bash string value.

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,
 	)
@@ -108,13 +124,39 @@ def status(
 #     Row value.
 # @param  {str}  result
 #     Optional result type for a symbol and tone.
+# @param  {int|None}  label_width
+#     Optional minimum label width.
+# @param  {str|None}  label_colour
+#     Optional label colour token.
+# @param  {str|None}  value_colour
+#     Optional value colour token.
+# @param  {str|None}  separator
+#     Optional text between the label and value.
 def row(
 	label: str,
 	value: str,
 	result: str = "",
+	label_width: int | None = None,
+	label_colour: str | None = None,
+	value_colour: str | None = None,
+	separator: str | None = None,
 	**kwargs: Any,
 ) -> str:
-	return render("row", {"label": label, "value": value, "result": result}, **kwargs)
+	data = {
+		"label": label,
+		"value": value,
+		"result": result,
+		"labelWidth": label_width,
+		"separator": separator,
+	}
+
+	if label_colour is not None:
+		data["labelColour"] = label_colour
+
+	if value_colour is not None:
+		data["valueColour"] = value_colour
+
+	return render("row", data, **kwargs)
 
 
 # Render an inline span from Python values.
@@ -123,23 +165,46 @@ def row(
 #     Span text.
 # @param  {str}  tone
 #     Optional colour tone, defaulting to info.
+# @param  {str|None}  weight
+#     Optional ANSI text weight.
 def span(
 	value: str,
 	tone: str = "info",
+	weight: str | None = None,
 	**kwargs: Any,
 ) -> str:
-	return render("span", {"value": value, "tone": tone}, **kwargs)
+	return render("span", {"value": value, "tone": tone, "weight": weight}, **kwargs)
 
 
 # Render a divider from a Python value.
 #
 # @param  {str}  label
 #     Optional divider label.
+# @param  {int|None}  divider_width
+#     Optional divider width.
+# @param  {str|None}  divider_colour
+#     Optional divider colour token.
+# @param  {str|None}  label_colour
+#     Optional label colour token.
 def divider(
 	label: str = "",
+	divider_width: int | None = None,
+	divider_colour: str | None = None,
+	label_colour: str | None = None,
 	**kwargs: Any,
 ) -> str:
-	return render("divider", {"label": label}, **kwargs)
+	data = {
+		"label": label,
+		"dividerWidth": divider_width,
+	}
+
+	if divider_colour is not None:
+		data["dividerColour"] = divider_colour
+
+	if label_colour is not None:
+		data["labelColour"] = label_colour
+
+	return render("divider", data, **kwargs)
 
 
 # Render a hint from a Python value.

package/adapters/swift/CliStyle.swift

@@ -1,4 +1,9 @@
 import Foundation
+#if canImport(Darwin)
+import Darwin
+#elseif canImport(Glibc)
+import Glibc
+#endif
 
 // Error types for cli-style adapter failures.
 enum CliStyleError: Error {
@@ -89,6 +94,7 @@ enum CliStyle {
 		let process = Process()
 		process.executableURL = URL(fileURLWithPath: resolvedBinary)
 		process.arguments = arguments
+		process.environment = resolveProcessEnvironment()
 
 		let stdinPipe = Pipe()
 		let stdoutPipe = Pipe()
@@ -125,6 +131,21 @@ enum CliStyle {
 		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.
 
@@ -154,6 +175,10 @@ enum CliStyle {
 	 - parameter label: Row label.
 	 - parameter value: Row value.
 	 - parameter result: Optional result type for a symbol and tone.
+	 - parameter labelWidth: Optional minimum label width.
+	 - parameter labelColour: Optional label colour token.
+	 - parameter valueColour: Optional value colour token.
+	 - parameter separator: Optional text between the label and value.
 	 - parameter options: Render options.
 	 - returns: Rendered row line.
 	 - throws: `CliStyleError` on failure.
@@ -162,13 +187,35 @@ enum CliStyle {
 		label: String,
 		value: String,
 		result: String = "",
+		labelWidth: Int? = nil,
+		labelColour: String? = nil,
+		valueColour: String? = nil,
+		separator: String? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
-		try render("row", data: [
+		var data: [String: Any] = [
 			"label": label,
 			"value": value,
 			"result": result,
-		], options: options)
+		]
+
+		if let labelWidth = labelWidth {
+			data["labelWidth"] = labelWidth
+		}
+
+		if let labelColour = labelColour {
+			data["labelColour"] = labelColour
+		}
+
+		if let valueColour = valueColour {
+			data["valueColour"] = valueColour
+		}
+
+		if let separator = separator {
+			data["separator"] = separator
+		}
+
+		return try render("row", data: data, options: options)
 	}
 
 	/**
@@ -176,6 +223,7 @@ enum CliStyle {
 
 	 - parameter value: Span text.
 	 - parameter tone: Optional colour tone, defaulting to info.
+	 - parameter weight: Optional ANSI text weight.
 	 - parameter options: Render options.
 	 - returns: Rendered span string.
 	 - throws: `CliStyleError` on failure.
@@ -183,29 +231,56 @@ enum CliStyle {
 	static func span(
 		value: String,
 		tone: String = "info",
+		weight: String? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
-		try render("span", data: [
+		var data: [String: Any] = [
 			"value": value,
 			"tone": tone,
-		], options: options)
+		]
+
+		if let weight = weight {
+			data["weight"] = weight
+		}
+
+		return try render("span", data: data, options: options)
 	}
 
 	/**
 	 Render a divider.
 
 	 - parameter label: Optional divider label.
+	 - parameter dividerWidth: Optional divider width.
+	 - parameter dividerColour: Optional divider colour token.
+	 - parameter labelColour: Optional label colour token.
 	 - parameter options: Render options.
 	 - returns: Rendered divider line.
 	 - throws: `CliStyleError` on failure.
 	 */
 	static func divider(
 		label: String = "",
+		dividerWidth: Int? = nil,
+		dividerColour: String? = nil,
+		labelColour: String? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
-		try render("divider", data: [
+		var data: [String: Any] = [
 			"label": label,
-		], options: options)
+		]
+
+		if let dividerWidth = dividerWidth {
+			data["dividerWidth"] = dividerWidth
+		}
+
+		if let dividerColour = dividerColour {
+			data["dividerColour"] = dividerColour
+		}
+
+		if let labelColour = labelColour {
+			data["labelColour"] = labelColour
+		}
+
+		return try render("divider", data: data, options: options)
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"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/render-command.js

@@ -13,6 +13,7 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { rowGroup } from "../primitives/row-group.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress } from "../primitives/step-progress.js";
@@ -73,6 +74,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	"row-group": (input, options) =>
+		rowGroup({
+			...input,
+			...options,
+		}),
 	span: (input, options) =>
 		span(input.value, input.tone, {
 			...input,

package/src/gallery/render-gallery.js

@@ -14,6 +14,7 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { rowGroup } from "../primitives/row-group.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
@@ -715,6 +716,30 @@ function renderPrimitives(options) {
 			labelWidth: 8,
 			result: resultTypes.FAILED,
 		}),
+		"",
+		"Row groups",
+		rowGroup({
+			...options,
+			rows: [
+				{
+					label: "Package",
+					value: "@lewishowles/components",
+				},
+				{
+					label: "Version",
+					value: "minor: 2.7.4 -> 2.8.0",
+				},
+				{
+					label: "Checks",
+					value: "type-check, unit, build",
+				},
+				{
+					label: "Bundle",
+					result: resultTypes.FAILED,
+					value: "is 22.3 KB, above the 12.0 KB budget",
+				},
+			],
+		}),
 	].join("\n");
 }
 

package/src/index.js

@@ -35,6 +35,7 @@ export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
 export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";
+export { rowGroup } from "./primitives/row-group.js";
 export { span } from "./primitives/span.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";

package/src/primitives/row-group.js

@@ -0,0 +1,84 @@
+import { getResultSymbol } from "../theme/results.js";
+import { row } from "./row.js";
+
+/**
+ * Render related labelled values against a shared label width.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number}  options.labelWidth
+ *     Optional minimum label width.
+ * @param  {object[]}  options.rows
+ *     Labelled values to render.
+ * @returns  {string}
+ *     Rendered row group.
+ */
+export function rowGroup(options = {}) {
+	const rows = normaliseRows(options.rows);
+
+	if (rows.length === 0) {
+		return "";
+	}
+
+	const labelWidth = Math.max(
+		...rows.map((entry) => displayedLabelLength(entry, options)),
+		options.labelWidth ?? 0,
+	);
+
+	return rows
+		.map((entry) =>
+			row(entry.label, entry.value ?? "", {
+				...options,
+				...entry,
+				labelWidth,
+			}),
+		)
+		.join("\n");
+}
+
+/**
+ * Return rows with usable labels.
+ *
+ * @param  {object[]}  rows
+ *     Requested row entries.
+ * @returns  {object[]}
+ *     Valid row entries.
+ */
+function normaliseRows(rows) {
+	if (!Array.isArray(rows)) {
+		return [];
+	}
+
+	return rows.filter(
+		(entry) =>
+			entry !== null &&
+			typeof entry === "object" &&
+			typeof entry.label === "string" &&
+			entry.label !== "",
+	);
+}
+
+/**
+ * Return the visible width of a row label.
+ *
+ * @param  {object}  entry
+ *     Row entry.
+ * @param  {object}  options
+ *     Group rendering options.
+ * @returns  {number}
+ *     Displayed label length.
+ */
+function displayedLabelLength(entry, options) {
+	if (typeof entry.result !== "string" || entry.result === "") {
+		return entry.label.length;
+	}
+
+	const entryOptions = {
+		...options,
+		...entry,
+	};
+
+	const symbol = getResultSymbol(entry.result, entryOptions);
+
+	return [symbol, entry.label].join(" ").length;
+}