@lewishowles/cli-style 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lewis Howles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# CLI style
+
+Shared terminal output styles for tools, diagnostics, and package CLIs.
+
+## Requirements
+
+- Bun
+- Node.js 20 or newer
+
+## Install
+
+JavaScript projects can install the package directly:
+
+```bash
+bun add @lewishowles/cli-style
+```
+
+Bash and Python projects still need the package available somewhere, because their adapters call the `cli-style` binary. If the project already has Node or Bun tooling, add it as a dev dependency. Otherwise, link or vendor this package in a stable tools directory and point the adapters at that copy:
+
+```bash
+export CLI_STYLE_BIN="/path/to/cli-style/bin/cli-style.js"
+export PYTHONPATH="/path/to/cli-style/adapters/python:$PYTHONPATH"
+```
+
+## JavaScript
+
+```js
+import { createCliStyle, status } from "@lewishowles/cli-style";
+
+const ui = createCliStyle({
+	profile: "human",
+	width: 80,
+});
+
+const output = status("success", "184 tests", {
+	...ui.options,
+	label: "Build passed",
+});
+
+ui.print(output);
+```
+
+Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
+
+## CLI
+
+Use `cli-style render <renderer>` when a script needs rendered text from JSON input.
+
+```bash
+cli-style render status --profile diagnostic <<'JSON'
+{
+  "type": "success",
+  "label": "Build passed",
+  "detail": "184 tests"
+}
+JSON
+```
+
+```bash
+cli-style render task-summary --plain <<'JSON'
+{
+  "title": "Task summary",
+  "completed": ["Added render command"],
+  "remaining": ["Add adapters"]
+}
+JSON
+```
+
+`render` supports `--profile`, `--plain`, `--no-colour`, `--no-color`, `--no-unicode`, and `--width`. It rejects `--json`; JSON profile behaviour is for library calls and machine-readable commands.
+
+## Bash
+
+```bash
+source /path/to/node_modules/@lewishowles/cli-style/adapters/bash/cli-style.sh
+
+cli_style_render status --profile diagnostic <<'JSON'
+{
+  "type": "success",
+  "label": "Build passed",
+  "detail": "184 tests"
+}
+JSON
+```
+
+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'
+{
+  "type": "success",
+  "label": "Build passed"
+}
+JSON
+```
+
+## Python
+
+Add `/path/to/node_modules/@lewishowles/cli-style/adapters/python` to `PYTHONPATH`, then import the helper:
+
+```python
+from cli_style import render
+
+output = render(
+	"status",
+	{
+		"type": "success",
+		"label": "Build passed",
+		"detail": "184 tests",
+	},
+	profile="diagnostic",
+)
+
+print(output)
+```
+
+Pass `binary=` when `cli-style` is not on `PATH`:
+
+```python
+output = render(
+	"status",
+	{
+		"type": "success",
+		"label": "Build passed",
+	},
+	binary="/path/to/cli-style",
+	plain=True,
+)
+```
+
+## Profiles
+
+| Profile      | Behaviour                                                                         |
+| ------------ | --------------------------------------------------------------------------------- |
+| `human`      | Colour and Unicode when supported; compact but visually pleasant.                 |
+| `agent`      | Markdown-like, structured, easy to quote or parse.                                |
+| `diagnostic` | Optimised for check summaries, findings, skipped checks, and next actions.        |
+| `ci`         | Stable, grep-friendly, no decorative panels; colour off unless explicitly forced. |
+| `plain`      | No ANSI, no Unicode dependency, simple text layout.                               |
+| `json`       | Machine-readable only; library calls return structured data unchanged.            |
+
+## Gallery
+
+```bash
+cli-style gallery
+cli-style gallery no-colour
+cli-style gallery --section patterns
+cli-style gallery --fixture audit-finding
+cli-style gallery --profile agent
+cli-style gallery --width 64
+cli-style gallery --variants
+```
+
+Use the gallery to review current renderer output. Use `--interactive` to select a section or fixture with `fzf` when it is installed.

package/adapters/bash/cli-style.sh

@@ -0,0 +1,50 @@
+# Sourceable Bash helpers for rendering through the cli-style binary.
+
+# Return the configured cli-style binary.
+#
+# @returns  {string}
+#     Binary path or command name.
+cli_style_binary() {
+	printf '%s\n' "${CLI_STYLE_BIN:-cli-style}"
+}
+
+# Returns 0 when a binary can be executed.
+#
+# @param  {string}  binary
+#     Binary path or command name.
+cli_style_has_binary() {
+	local binary="$1"
+
+	if [[ "$binary" == */* ]]; then
+		[[ -x "$binary" ]]
+		return
+	fi
+
+	command -v "$binary" >/dev/null 2>&1
+}
+
+# Render stdin JSON through the shared cli-style command.
+#
+# @param  {string}  renderer
+#     Stable renderer name accepted by `cli-style render`.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_render() {
+	local renderer="${1:-}"
+	local binary
+
+	if [[ "$renderer" == "" ]]; then
+		printf 'Missing renderer\n' >&2
+		return 2
+	fi
+
+	shift
+	binary="$(cli_style_binary)"
+
+	if ! cli_style_has_binary "$binary"; then
+		printf 'cli-style binary not found: %s\n' "$binary" >&2
+		return 127
+	fi
+
+	"$binary" render "$renderer" "$@"
+}

package/adapters/python/cli_style.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# Render caller data through the shared cli-style binary.
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Sequence
+
+
+class CliStyleError(RuntimeError):
+	"""Base error for cli-style adapter failures."""
+
+
+class CliStyleNotFoundError(CliStyleError):
+	"""Raised when the cli-style binary cannot be found."""
+
+
+class CliStyleRenderError(CliStyleError):
+	"""Raised when cli-style rejects a render request."""
+
+
+# Render caller data through `cli-style render`.
+#
+# @param  {str}  renderer
+#     Stable renderer name accepted by `cli-style render`.
+# @param  {dict}  data
+#     JSON-serialisable renderer input.
+def render(
+	renderer: str,
+	data: dict[str, Any],
+	*,
+	binary: str = "cli-style",
+	profile: str | None = None,
+	width: int | None = None,
+	plain: bool = False,
+	no_colour: bool = False,
+	no_unicode: bool = False,
+	extra_args: Sequence[str] | None = None,
+) -> str:
+	if not isinstance(renderer, str) or renderer == "":
+		raise ValueError("renderer must be a non-empty string")
+
+	if not isinstance(data, dict):
+		raise TypeError("data must be a dict")
+
+	resolved_binary = resolve_binary(binary)
+	command = [resolved_binary, "render", renderer]
+
+	if profile is not None:
+		command.extend(["--profile", profile])
+
+	if width is not None:
+		command.extend(["--width", str(width)])
+
+	if plain:
+		command.append("--plain")
+
+	if no_colour:
+		command.append("--no-colour")
+
+	if no_unicode:
+		command.append("--no-unicode")
+
+	if extra_args is not None:
+		command.extend(extra_args)
+
+	result = subprocess.run(
+		command,
+		capture_output=True,
+		check=False,
+		input=json.dumps(data),
+		text=True,
+	)
+
+	if result.returncode != 0:
+		message = result.stderr.strip() or f"cli-style render failed with exit code {result.returncode}"
+		raise CliStyleRenderError(message)
+
+	return result.stdout.rstrip("\n")
+
+
+# Resolve a command name or executable path for subprocess use.
+#
+# @param  {str}  binary
+#     Binary path or command name.
+def resolve_binary(binary: str) -> str:
+	if "/" in binary:
+		path = Path(binary)
+
+		if path.is_file() and os.access(path, os.X_OK):
+			return str(path)
+
+		raise CliStyleNotFoundError(f"cli-style binary not found: {binary}")
+
+	resolved = shutil.which(binary)
+
+	if resolved is None:
+		raise CliStyleNotFoundError(f"cli-style binary not found: {binary}")
+
+	return resolved

package/bin/cli-style.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+
+import { Buffer } from "node:buffer";
+
+import { createCliStyle, renderGallery, renderHelp } from "../src/index.js";
+import {
+	parseGalleryRequest,
+	selectInteractiveGalleryRequest,
+} from "../src/cli/gallery-command.js";
+import {
+	parseRenderRequest,
+	renderJsonInput,
+} from "../src/cli/render-command.js";
+
+// Command-line arguments passed to the package binary.
+const args = process.argv.slice(2);
+
+// First positional command requested by the caller.
+const command = args[0];
+
+// Renderer configured from the current terminal.
+const ui = createCliStyle({
+	argv: args,
+	env: process.env,
+	stdout: process.stdout,
+});
+
+/**
+ * Print text with a trailing newline.
+ *
+ * @param  {string}  value
+ *     Text to print.
+ * @returns  {void}
+ */
+function print(value) {
+	console.log(value);
+}
+
+if (command === undefined || command === "--help" || command === "-h") {
+	print(renderHelp());
+} else if (command === "gallery") {
+	try {
+		const request = parseGalleryRequest(args.slice(1));
+		const selectedRequest = selectInteractiveGalleryRequest(request);
+
+		print(renderGallery(ui.options, selectedRequest));
+	} catch (error) {
+		console.error(error.message);
+		process.exitCode = 1;
+	}
+} else if (command === "render") {
+	try {
+		const request = parseRenderRequest(args.slice(1));
+		const input = await readStdin();
+
+		print(renderJsonInput(input, request, ui.options));
+	} catch (error) {
+		console.error(error.message);
+		process.exitCode = 1;
+	}
+} else {
+	console.error(`Unknown command: ${command}`);
+	console.error("");
+	console.error(renderHelp());
+	process.exitCode = 1;
+}
+
+/**
+ * Read all stdin data for custom render input.
+ *
+ * @returns  {Promise<string>}
+ *     Stdin text.
+ */
+async function readStdin() {
+	const chunks = [];
+
+	for await (const chunk of process.stdin) {
+		chunks.push(Buffer.from(chunk));
+	}
+
+	return Buffer.concat(chunks).toString("utf8");
+}

package/examples/diagnostic.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+
+import { diagnosticReport } from "../src/index.js";
+
+// Example data shaped like a local diagnostic command summary.
+const report = {
+	checks: [
+		{
+			detail: "30 tests",
+			name: "Unit tests",
+			result: "success",
+		},
+	],
+	findings: [],
+	nextActions: ["Build Bash and Python adapters"],
+	skippedChecks: [
+		{
+			name: "Full suite",
+			reason: "Not needed for adapter smoke test",
+		},
+	],
+	title: "Diagnostics",
+};
+
+console.log(diagnosticReport(report, {
+	colour: false,
+	profile: "diagnostic",
+	unicode: true,
+	width: 80,
+}));

package/examples/diagnostic.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# Render a diagnostic report through the Python adapter.
+
+from pathlib import Path
+import sys
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+sys.path.insert(0, str(SCRIPT_DIR.parent / "adapters" / "python"))
+
+from cli_style import render  # noqa: E402
+
+
+report = {
+	"title": "Diagnostics",
+	"checks": [
+		{
+			"result": "success",
+			"name": "Unit tests",
+			"detail": "30 tests",
+		},
+	],
+	"findings": [],
+	"skippedChecks": [
+		{
+			"name": "Full suite",
+			"reason": "Not needed for adapter smoke test",
+		},
+	],
+	"nextActions": ["Build Bash and Python adapters"],
+}
+
+print(render(
+	"diagnostic-report",
+	report,
+	binary=str(SCRIPT_DIR.parent / "bin" / "cli-style.js"),
+	profile="diagnostic",
+))

package/examples/diagnostic.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Render a diagnostic report through the Bash adapter.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+source "$SCRIPT_DIR/../adapters/bash/cli-style.sh"
+
+CLI_STYLE_BIN="${CLI_STYLE_BIN:-"$SCRIPT_DIR/../bin/cli-style.js"}" cli_style_render diagnostic-report --profile diagnostic <<'JSON'
+{
+	"title": "Diagnostics",
+	"checks": [
+		{
+			"result": "success",
+			"name": "Unit tests",
+			"detail": "30 tests"
+		}
+	],
+	"findings": [],
+	"skippedChecks": [
+		{
+			"name": "Full suite",
+			"reason": "Not needed for adapter smoke test"
+		}
+	],
+	"nextActions": ["Build Bash and Python adapters"]
+}
+JSON

package/examples/gallery.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+
+import { renderGallery } from "../src/index.js";
+
+// Stable options for reviewing gallery output outside the current terminal.
+const reviewOptions = {
+	colour: false,
+	profile: "plain",
+	unicode: false,
+	width: 64,
+};
+
+// Variants request exercises every gallery capability variant with fixed sample data.
+const reviewRequest = {
+	variants: true,
+};
+
+console.log(renderGallery(reviewOptions, reviewRequest));

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@lewishowles/cli-style",
+	"version": "0.1.0",
+	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/lewishowles/cli-style.git"
+	},
+	"bin": {
+		"cli-style": "./bin/cli-style.js"
+	},
+	"files": [
+		"adapters",
+		"bin",
+		"examples",
+		"src",
+		"README.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": "./src/index.js"
+	},
+	"publishConfig": {
+		"registry": "https://npm.pkg.github.com/"
+	},
+	"scripts": {
+		"check": "vp check --fix",
+		"cli-style:gallery": "bun ./bin/cli-style.js gallery",
+		"test:unit": "bun test"
+	},
+	"devDependencies": {
+		"@stylistic/eslint-plugin": "^5.10.0",
+		"vite": "npm:@voidzero-dev/vite-plus-core@0.2.1",
+		"vite-plus": "0.2.1"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"packageManager": "bun@1.3.14"
+}

package/src/capability/resolve-profile.js

@@ -0,0 +1,69 @@
+import { isProfile, profiles } from "../profiles/profiles.js";
+
+/**
+ * Resolve the active output profile from explicit options, flags, and environment.
+ *
+ * @param  {object}  options
+ *     Profile resolution inputs.
+ * @param  {string}  options.profile
+ *     Explicit profile name.
+ * @param  {string[]}  options.argv
+ *     CLI arguments to inspect.
+ * @param  {object}  options.env
+ *     Environment values to inspect.
+ * @returns  {string}
+ *     Resolved profile name.
+ */
+export function resolveProfile(options = {}) {
+	const argv = options.argv ?? [];
+	const env = options.env ?? {};
+
+	if (argv.includes("--json")) {
+		return profiles.JSON;
+	}
+
+	if (argv.includes("--plain")) {
+		return profiles.PLAIN;
+	}
+
+	const flagProfile = readProfileFlag(argv);
+
+	if (flagProfile !== null) {
+		return isProfile(flagProfile) ? flagProfile : profiles.HUMAN;
+	}
+
+	if (isProfile(options.profile)) {
+		return options.profile;
+	}
+
+	if (env.CI === "true" || env.CI === "1") {
+		return profiles.CI;
+	}
+
+	return profiles.HUMAN;
+}
+
+/**
+ * Read `--profile value` or `--profile=value` from CLI args.
+ *
+ * @param  {string[]}  argv
+ *     CLI arguments to inspect.
+ * @returns  {string|null}
+ *     Profile flag value when present.
+ */
+function readProfileFlag(argv) {
+	const profilePrefix = "--profile=";
+	const inlineProfile = argv.find((arg) => arg.startsWith(profilePrefix));
+
+	if (inlineProfile !== undefined) {
+		return inlineProfile.slice(profilePrefix.length);
+	}
+
+	const profileFlagIndex = argv.indexOf("--profile");
+
+	if (profileFlagIndex === -1) {
+		return null;
+	}
+
+	return argv[profileFlagIndex + 1] ?? "";
+}