@lewishowles/cli-style 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 - 2026-07-02
+
+### Added
+
+- Added Bash adapter convenience functions for common renderers: `cli_style_status`, `cli_style_row`, `cli_style_divider`, and `cli_style_hint`.
+- Added Bash adapter escaping for dynamic string values, so scripts can pass quotes, backslashes, paths, and messages without hand-building JSON.
+- Added README examples for JS CLI entrypoint wiring with `createCliStyle({ argv, env, stdout })` and helper-first Bash adapter usage.
+
+### Changed
+
+- Lightened the muted colour token so secondary text stays readable on dark surfaces.
+
 ## 0.4.1 - 2026-07-01
 
 ### Fixed

package/README.md

@@ -27,8 +27,9 @@ export PATH="/path/to/cli-style/bin:$PATH"
 import { createCliStyle, status } from "@lewishowles/cli-style";
 
 const ui = createCliStyle({
-	profile: "human",
-	width: 80,
+	argv: process.argv.slice(2),
+	env: process.env,
+	stdout: process.stdout,
 });
 
 const output = status("success", "184 tests", {
@@ -41,6 +42,8 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
+Create the `ui` instance at the CLI entrypoint, then pass it to command handlers. That keeps flag, environment, stream, colour, Unicode, and width detection in one place.
+
 ## Reporter
 
 Use a reporter when a script needs grouped output rather than one row per file.
@@ -131,19 +134,33 @@ The package contains `bin/cli-style` and `adapters/`. Install it into a repo-loc
 ```bash
 source "$(cli-style adapter-path bash)"
 
-cli_style_render status --profile diagnostic <<'JSON'
-{
-  "type": "success",
-  "label": "Build passed",
-  "detail": "184 tests"
-}
-JSON
+label='Build "passed"'
+detail="/path/to/project"
+
+cli_style_status success "$label" "$detail" --profile diagnostic
+cli_style_row "Workspace" "$detail" --plain
+cli_style_hint "Run \"check\" before release" --plain
+cli_style_divider "Project setup" --plain
+```
+
+Use the convenience functions for dynamic Bash values. They build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
+
+`cli_style_status` accepts `type`, `label`, `detail`, then render flags. Pass an empty detail when you only need a label:
+
+```bash
+cli_style_status success "Done" "" --plain
 ```
 
 Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
 
 ```bash
-CLI_STYLE_BIN="/path/to/cli-style" cli_style_render status --plain <<'JSON'
+CLI_STYLE_BIN="/path/to/cli-style" cli_style_status success "Build passed" "" --plain
+```
+
+Keep `cli_style_render` for literal or prebuilt JSON:
+
+```bash
+cli_style_render status --plain <<'JSON'
 {
   "type": "success",
   "label": "Build passed"

package/adapters/bash/cli-style.sh

@@ -23,6 +23,40 @@ cli_style_has_binary() {
 	command -v "$binary" >/dev/null 2>&1
 }
 
+# Escape a Bash string for JSON string values.
+#
+# @param  {string}  value
+#     String value to encode.
+cli_style_json_string() {
+	local value="${1:-}"
+
+	value="${value//\\/\\\\}"
+	value="${value//\"/\\\"}"
+	value="${value//$'\b'/\\b}"
+	value="${value//$'\f'/\\f}"
+	value="${value//$'\n'/\\n}"
+	value="${value//$'\r'/\\r}"
+	value="${value//$'\t'/\\t}"
+
+	printf '"%s"' "$value"
+}
+
+# Render a JSON object through the shared cli-style command.
+#
+# @param  {string}  renderer
+#     Stable renderer name accepted by `cli-style render`.
+# @param  {string}  json
+#     Prebuilt JSON object.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_render_json() {
+	local renderer="${1:-}"
+	local json="${2:-}"
+
+	shift 2
+	printf '%s\n' "$json" | cli_style_render "$renderer" "$@"
+}
+
 # Render stdin JSON through the shared cli-style command.
 #
 # @param  {string}  renderer
@@ -48,3 +82,96 @@ cli_style_render() {
 
 	"$binary" render "$renderer" "$@"
 }
+
+# Render a result status line from Bash string values.
+#
+# @param  {string}  type
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  label
+#     Status label.
+# @param  {string}  detail
+#     Optional detail text.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_status() {
+	local type="${1:-}"
+	local label="${2:-}"
+	local detail="${3:-}"
+	local json
+
+	if (($# >= 3)); then
+		shift 3
+	else
+		set --
+	fi
+
+	json="{\"type\":$(cli_style_json_string "$type"),\"label\":$(cli_style_json_string "$label"),\"detail\":$(cli_style_json_string "$detail")}"
+
+	cli_style_render_json status "$json" "$@"
+}
+
+# Render a labelled value row from Bash string values.
+#
+# @param  {string}  label
+#     Row label.
+# @param  {string}  value
+#     Row value.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_row() {
+	local label="${1:-}"
+	local value="${2:-}"
+	local json
+
+	if (($# >= 2)); then
+		shift 2
+	else
+		set --
+	fi
+
+	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value")}"
+
+	cli_style_render_json row "$json" "$@"
+}
+
+# Render a divider from a Bash string value.
+#
+# @param  {string}  label
+#     Optional divider label.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_divider() {
+	local label="${1:-}"
+	local json
+
+	if (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"label\":$(cli_style_json_string "$label")}"
+
+	cli_style_render_json divider "$json" "$@"
+}
+
+# Render a hint from a Bash string value.
+#
+# @param  {string}  message
+#     Hint message.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_hint() {
+	local message="${1:-}"
+	local json
+
+	if (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"message\":$(cli_style_json_string "$message")}"
+
+	cli_style_render_json hint "$json" "$@"
+}

package/package.json

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

package/src/theme/colours.js

@@ -5,7 +5,7 @@ export const colourTokens = {
 	border: "#2a3a42",
 	danger: "#ff7272",
 	info: "#8bbdff",
-	muted: "#6f7f87",
+	muted: "#7a8a92",
 	success: "#8fdf72",
 	surface: "#0f181b",
 	surfaceRaised: "#132024",