@lewishowles/cli-style 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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
+
+- Updated grouped reporter summaries so skipped rows outrank success rows while warnings and failures still take precedence.
+- Added the project-local vite-plus pre-commit hook setup so commits run the existing staged checks.
+
 ## 0.4.0 - 2026-06-30
 
 ### Added

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.
@@ -53,18 +56,22 @@ const reporter = createReporter({
 });
 
 reporter.divider("Project setup", "Claude + Codex");
-reporter.group("Agent scripts", [
-	{
-		label: "project-diagnostics.py",
-		result: "unchanged",
-	},
+reporter.group(
+	"Agent scripts",
+	[
+		{
+			label: "project-diagnostics.py",
+			result: "unchanged",
+		},
+		{
+			label: "repo-context.py",
+			result: "unchanged",
+		},
+	],
 	{
-		label: "repo-context.py",
-		result: "unchanged",
+		summary: "2 already linked",
 	},
-], {
-	summary: "2 already linked",
-});
+);
 reporter.status("success", "Done.");
 
 console.log(reporter.render());
@@ -127,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/examples/diagnostic.mjs

@@ -22,9 +22,11 @@ const report = {
 	title: "Diagnostics",
 };
 
-console.log(diagnosticReport(report, {
-	colour: false,
-	profile: "diagnostic",
-	unicode: true,
-	width: 80,
-}));
+console.log(
+	diagnosticReport(report, {
+		colour: false,
+		profile: "diagnostic",
+		unicode: true,
+		width: 80,
+	}),
+);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {
@@ -32,6 +32,7 @@
 		"check": "vp check --fix",
 		"cli-style:gallery": "bun ./bin/cli-style.js gallery",
 		"package:binary": "scripts/package-binary.sh",
+		"prepare": "vp config",
 		"smoke:binary": "./dist/bin/cli-style render status --plain < tests/fixtures/render/status-success.json",
 		"test:unit": "bun test"
 	},

package/src/cli/gallery-command.js

@@ -1,19 +1,10 @@
 import { spawnSync } from "node:child_process";
 
-import {
-	galleryFixtures,
-	gallerySections,
-	galleryVariants,
-} from "../gallery/render-gallery.js";
+import { galleryFixtures, gallerySections, galleryVariants } from "../gallery/render-gallery.js";
 import { isProfile, profiles } from "../profiles/profiles.js";
 
 // Global rendering flags accepted after `gallery` for focused review commands.
-const globalRenderingFlags = new Set([
-	"--no-color",
-	"--no-colour",
-	"--no-unicode",
-	"--plain",
-]);
+const globalRenderingFlags = new Set(["--no-color", "--no-colour", "--no-unicode", "--plain"]);
 
 /**
  * Parse gallery command arguments.
@@ -25,6 +16,7 @@ const globalRenderingFlags = new Set([
  */
 export function parseGalleryRequest(args = []) {
 	let hasVariant = false;
+
 	const request = {
 		fixture: undefined,
 		interactive: false,
@@ -96,15 +88,13 @@ export function selectInteractiveGalleryRequest(request) {
 		...gallerySections.map((section) => `section:${section}`),
 		...galleryFixtures.map((fixture) => `fixture:${fixture}`),
 	];
-	const selection = spawnSync("fzf", [
-		"--height=60%",
-		"--layout=reverse",
-		"--prompt=Gallery > ",
-	], {
+
+	const selection = spawnSync("fzf", ["--height=60%", "--layout=reverse", "--prompt=Gallery > "], {
 		encoding: "utf8",
 		input: choices.join("\n"),
 		stdio: ["pipe", "pipe", "inherit"],
 	});
+
 	const value = selection.status === 0 ? selection.stdout.trim() : "";
 
 	if (value === "") {

package/src/cli/render-command.js

@@ -22,73 +22,81 @@ import { isProfile, profiles } from "../profiles/profiles.js";
 const renderers = {
 	"agent-transcript": (input, options) => agentTranscript(input, options),
 	"audit-finding": (input, options) => auditFinding(input, options),
-	"bar-chart": (input, options) => barChart({
-		...input,
-		...options,
-	}),
-	chip: (input, options) => chip(input.label, input.tone, {
-		...input,
-		...options,
-	}),
+	"bar-chart": (input, options) =>
+		barChart({
+			...input,
+			...options,
+		}),
+	chip: (input, options) =>
+		chip(input.label, input.tone, {
+			...input,
+			...options,
+		}),
 	"command-result": (input, options) => commandResult(input, options),
 	"compact-data-table": (input, options) => compactDataTable(input, options),
 	"confirmation-result": (input, options) => confirmationResult(input, options),
 	"diagnostic-report": (input, options) => diagnosticReport(input, options),
-	divider: (input, options) => divider({
-		...input,
-		...options,
-	}),
-	"empty-state": (input, options) => emptyState(input.title, input.detail, {
-		...input,
-		...options,
-	}),
-	"error-block": (input, options) => errorBlock(input.title, input.lines, {
-		...input,
-		...options,
-	}),
-	hint: (input, options) => hint(input.message, {
-		...input,
-		...options,
-	}),
+	divider: (input, options) =>
+		divider({
+			...input,
+			...options,
+		}),
+	"empty-state": (input, options) =>
+		emptyState(input.title, input.detail, {
+			...input,
+			...options,
+		}),
+	"error-block": (input, options) =>
+		errorBlock(input.title, input.lines, {
+			...input,
+			...options,
+		}),
+	hint: (input, options) =>
+		hint(input.message, {
+			...input,
+			...options,
+		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
-	panel: (input, options) => panel({
-		...input,
-		...options,
-	}),
-	"progress-bar": (input, options) => progressBar({
-		...input,
-		...options,
-	}),
-	row: (input, options) => row(input.label, input.value, {
-		...input,
-		...options,
-	}),
-	status: (input, options) => status(input.type, input.detail, {
-		...input,
-		...options,
-	}),
-	step: (input, options) => step(input.label, input.state, {
-		...input,
-		...options,
-	}),
-	"step-progress": (input, options) => stepProgress({
-		...input,
-		...options,
-	}),
-	table: (input, options) => table({
-		...input,
-		...options,
-	}),
+	panel: (input, options) =>
+		panel({
+			...input,
+			...options,
+		}),
+	"progress-bar": (input, options) =>
+		progressBar({
+			...input,
+			...options,
+		}),
+	row: (input, options) =>
+		row(input.label, input.value, {
+			...input,
+			...options,
+		}),
+	status: (input, options) =>
+		status(input.type, input.detail, {
+			...input,
+			...options,
+		}),
+	step: (input, options) =>
+		step(input.label, input.state, {
+			...input,
+			...options,
+		}),
+	"step-progress": (input, options) =>
+		stepProgress({
+			...input,
+			...options,
+		}),
+	table: (input, options) =>
+		table({
+			...input,
+			...options,
+		}),
 	"task-summary": (input, options) => taskSummary(input, options),
 };
 
 // Global rendering flags accepted after `render <renderer>`.
-const globalRenderingFlags = new Set([
-	"--no-color",
-	"--no-colour",
-	"--no-unicode",
-	"--plain",
-]);
+const globalRenderingFlags = new Set(["--no-color", "--no-colour", "--no-unicode", "--plain"]);
 
 // Renderer names exposed for help text and tests.
 export const rendererNames = Object.keys(renderers);

package/src/create-cli-style.js

@@ -28,10 +28,11 @@ export function createCliStyle(options = {}) {
 		print: (value) => {
 			console.log(value);
 		},
-		reporter: (reporterOptions = {}) => createReporter({
-			...resolvedOptions,
-			...reporterOptions,
-		}),
+		reporter: (reporterOptions = {}) =>
+			createReporter({
+				...resolvedOptions,
+				...reporterOptions,
+			}),
 		write: (value) => {
 			process.stdout.write(value);
 		},