@lewishowles/cli-style 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.12.0 - 2026-08-20
+
+### Added
+
+- Added `labelledLine(label, message, options)`, a general icon/label/message renderer with a configurable tone. `hint()` now delegates to it instead of duplicating its own rendering, with unchanged output for existing callers.
+- `row()` now wraps long values within the available row width (64 columns by default), instead of overflowing the line. Override with `wrapWidth`, or disable with `wrap: false`.
+
 ## 0.11.0 - 2026-07-24
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {
@@ -32,14 +32,14 @@
 		"check": "vp check --fix",
 		"cli-style:gallery": "bun ./bin/cli-style.js gallery",
 		"package:binary": "scripts/package-binary.sh",
-		"prepare": "vp config",
+		"prepare": "vp config --no-agent",
 		"smoke:binary": "./dist/bin/cli-style render status --plain < tests/fixtures/render/status-success.json",
 		"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"
+		"vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+		"vite-plus": "0.2.8"
 	},
 	"engines": {
 		"node": ">=20"

package/src/catalogue/renderer-catalogue.js

@@ -25,11 +25,18 @@ export const rendererCatalogue = [
 	["empty-state", "primitive", "emptyState", ["detail", "title"], undefined],
 	["error-block", "primitive", "errorBlock", ["lines", "title"], undefined],
 	["hint", "primitive", "hint", ["message"], undefined],
+	[
+		"labelled-line",
+		"primitive",
+		"labelledLine",
+		["icon", "label", "message", "wrap", "wrapWidth"],
+		undefined,
+	],
 	["next-step-block", "pattern", "nextStepBlock", ["next", "reason"], "next-step-block"],
 	["panel", "primitive", "panel", ["lines", "title", "tone"], undefined],
 	["progress-bar", "primitive", "progressBar", ["max", "value"], undefined],
-	["row", "primitive", "row", ["label", "value"], undefined],
-	["row-group", "primitive", "rowGroup", ["rows"], undefined],
+	["row", "primitive", "row", ["label", "value", "wrap", "wrapWidth"], undefined],
+	["row-group", "primitive", "rowGroup", ["rows", "wrap", "wrapWidth"], undefined],
 	["sparkline", "primitive", "sparkline", ["values"], "sparkline"],
 	["span", "primitive", "span", ["tone", "value"], undefined],
 	["status", "primitive", "status", ["detail", "type"], undefined],

package/src/cli/render-command.js

@@ -11,6 +11,7 @@ import { barChart } from "../primitives/bar-chart.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
+import { labelledLine } from "../primitives/labelled-line.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
@@ -62,6 +63,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	"labelled-line": (input, options) =>
+		labelledLine(input.label, input.message, {
+			...input,
+			...options,
+		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
 	panel: (input, options) =>
 		panel({

package/src/formatters/wrap.js

@@ -0,0 +1,220 @@
+// Width used when a caller doesn't provide one.
+const defaultWrapWidth = 64;
+const escapeCharacter = String.fromCharCode(27);
+const bellCharacter = String.fromCharCode(7);
+
+// Matches ANSI CSI and OSC escape sequences so they can be measured as zero-width.
+const ansiEscapePattern = new RegExp(
+	`${escapeCharacter}(?:\\[[0-?]*[ -/]*[@-~]|\\][^${bellCharacter}]*(?:${bellCharacter}|${escapeCharacter}\\\\))`,
+	"gu",
+);
+
+/**
+ * Wrap text to a maximum visible width, treating ANSI escape sequences as zero-width.
+ *
+ * @param  {string}  text
+ *     Text to wrap.
+ * @param  {number}  width
+ *     Maximum visible width per line.
+ * @returns  {string[]}
+ *     Wrapped lines.
+ */
+export function wrapText(text, width = defaultWrapWidth) {
+	const wrapWidth = resolveWrapWidth(width);
+	const tokens = tokenise(String(text));
+	const lines = [];
+
+	let line = [];
+
+	for (const token of tokens) {
+		if (token.value === "\n") {
+			lines.push(renderTokens(line));
+			line = [];
+			continue;
+		}
+
+		line.push(token);
+
+		while (visibleWidth(line) > wrapWidth) {
+			const whitespaceIndex = findLastWhitespace(line);
+
+			if (whitespaceIndex > 0) {
+				const left = line.slice(0, whitespaceIndex);
+
+				lines.push(renderTokens(left));
+				line = trimLeadingWhitespace(line.slice(whitespaceIndex + 1));
+				continue;
+			}
+
+			const splitIndex = findHardSplitIndex(line, wrapWidth);
+
+			lines.push(renderTokens(line.slice(0, splitIndex)));
+			line = line.slice(splitIndex);
+		}
+	}
+
+	lines.push(renderTokens(line));
+
+	return lines;
+}
+
+/**
+ * Resolve a usable wrap width, falling back to the default for invalid input.
+ *
+ * @param  {number}  width
+ *     Requested wrap width.
+ * @returns  {number}
+ *     Whole-number wrap width of at least 1.
+ */
+function resolveWrapWidth(width) {
+	const numericWidth = Number(width);
+
+	if (!Number.isFinite(numericWidth) || numericWidth < 1) {
+		return defaultWrapWidth;
+	}
+
+	return Math.floor(numericWidth);
+}
+
+/**
+ * Split text into visible characters and ANSI escape sequences.
+ *
+ * @param  {string}  text
+ *     Text to tokenise.
+ * @returns  {object[]}
+ *     Tokens, each with a `value` and its `visibleWidth`.
+ */
+function tokenise(text) {
+	const tokens = [];
+
+	let textStart = 0;
+
+	for (const match of text.matchAll(ansiEscapePattern)) {
+		appendTextTokens(tokens, text.slice(textStart, match.index));
+		tokens.push({
+			value: match[0],
+			visibleWidth: 0,
+		});
+		textStart = match.index + match[0].length;
+	}
+
+	appendTextTokens(tokens, text.slice(textStart));
+
+	return tokens;
+}
+
+/**
+ * Append one token per character of plain text to a token list.
+ *
+ * @param  {object[]}  tokens
+ *     Token list to append to.
+ * @param  {string}  text
+ *     Plain text, with no ANSI escape sequences.
+ * @returns  {void}
+ */
+function appendTextTokens(tokens, text) {
+	for (const value of text) {
+		tokens.push({
+			value,
+			visibleWidth: value === "\n" ? 0 : 1,
+		});
+	}
+}
+
+/**
+ * Sum the visible width of a list of tokens.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to measure.
+ * @returns  {number}
+ *     Total visible width.
+ */
+function visibleWidth(tokens) {
+	return tokens.reduce((width, token) => width + token.visibleWidth, 0);
+}
+
+/**
+ * Find the index of the last whitespace token, to break a line at a word boundary.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to search.
+ * @returns  {number}
+ *     Index of the last whitespace token, or -1 when none is found.
+ */
+function findLastWhitespace(tokens) {
+	for (let index = tokens.length - 1; index >= 0; index -= 1) {
+		const token = tokens[index];
+
+		if (token.visibleWidth === 1 && /\s/u.test(token.value)) {
+			return index;
+		}
+	}
+
+	return -1;
+}
+
+/**
+ * Find the index to split at when a line has no whitespace to break on.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to search.
+ * @param  {number}  width
+ *     Maximum visible width for the first segment.
+ * @returns  {number}
+ *     Index at which to split the tokens.
+ */
+function findHardSplitIndex(tokens, width) {
+	let currentWidth = 0;
+
+	for (let index = 0; index < tokens.length; index += 1) {
+		currentWidth += tokens[index].visibleWidth;
+
+		if (currentWidth >= width) {
+			return index + 1;
+		}
+	}
+
+	return tokens.length;
+}
+
+/**
+ * Remove leading whitespace tokens from a wrapped continuation line.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to trim.
+ * @returns  {object[]}
+ *     Tokens with leading whitespace removed.
+ */
+function trimLeadingWhitespace(tokens) {
+	const trimmedTokens = [];
+
+	let hasVisibleText = false;
+
+	for (const token of tokens) {
+		if (token.visibleWidth === 0) {
+			trimmedTokens.push(token);
+			continue;
+		}
+
+		if (!hasVisibleText && /\s/u.test(token.value)) {
+			continue;
+		}
+
+		hasVisibleText = true;
+		trimmedTokens.push(token);
+	}
+
+	return trimmedTokens;
+}
+
+/**
+ * Join a list of tokens back into a string.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to render.
+ * @returns  {string}
+ *     Rendered text.
+ */
+function renderTokens(tokens) {
+	return tokens.map((token) => token.value).join("");
+}

package/src/gallery/render-gallery.js

@@ -13,6 +13,7 @@ import { barChart } from "../primitives/bar-chart.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
+import { labelledLine } from "../primitives/labelled-line.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
@@ -771,6 +772,11 @@ function renderPrimitives(options) {
 		"",
 		"Feedback",
 		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
+		labelledLine("Notice", "Reusable labelled output", {
+			...options,
+			icon: "!",
+			tone: "warning",
+		}),
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
@@ -808,6 +814,23 @@ function renderPrimitives(options) {
 			labelWidth: 8,
 			result: resultTypes.FAILED,
 		}),
+		row(
+			"Description",
+			"This value wraps at the default width so long diagnostic details remain readable in a terminal.",
+			{
+				...options,
+				labelWidth: 11,
+			},
+		),
+		row(
+			"Raw output",
+			"This long value keeps its original line because wrapping is disabled for raw output.",
+			{
+				...options,
+				labelWidth: 11,
+				wrap: false,
+			},
+		),
 		"",
 		"Row groups",
 		rowGroup({
@@ -830,6 +853,10 @@ function renderPrimitives(options) {
 					result: resultTypes.FAILED,
 					value: "is 22.3 KB, above the 12.0 KB budget",
 				},
+				{
+					label: "Description",
+					value: "This group value inherits the default wrapping used by each row in the group.",
+				},
 			],
 		}),
 	].join("\n");

package/src/index.js

@@ -43,6 +43,7 @@ export { barChart } from "./primitives/bar-chart.js";
 export { chip } from "./primitives/chip.js";
 export { divider } from "./primitives/divider.js";
 export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
+export { labelledLine } from "./primitives/labelled-line.js";
 export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";

package/src/primitives/feedback.js

@@ -1,5 +1,6 @@
 import { foreground, style } from "../formatters/ansi.js";
 import { getResultSymbol, resultTypes } from "../theme/results.js";
+import { labelledLine } from "./labelled-line.js";
 import { panel } from "./panel.js";
 
 /**
@@ -15,15 +16,11 @@ import { panel } from "./panel.js";
  *     Rendered hint.
  */
 export function hint(message = "", options = {}) {
-	const prefix = "i Hint:";
-
-	if (options.colour !== true) {
-		return `${prefix} ${message}`;
-	}
-
-	const renderedPrefix = style(foreground(prefix, "info", options), "bold", options);
-
-	return `${renderedPrefix} ${message}`;
+	return labelledLine("Hint", message, {
+		icon: "i",
+		tone: "info",
+		...options,
+	});
 }
 
 /**

package/src/primitives/labelled-line.js

@@ -0,0 +1,134 @@
+import { foreground, style } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
+
+// Falls back to the informational tone when no colour token is given.
+const defaultColour = "info";
+
+// Sits between the colon-terminated prefix and the message.
+const messageSeparator = " ";
+
+/**
+ * Render an icon, label, and message as one wrapped line.
+ *
+ * @param  {string}  label
+ *     Label shown before the message; omit for an unlabelled line.
+ * @param  {string}  message
+ *     Message text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.icon
+ *     Optional icon shown before the label.
+ * @param  {string}  options.tone
+ *     Colour token for the icon and label when colour is enabled; defaults to "info".
+ * @param  {number}  options.width
+ *     Total line width; the message width is this minus the label and separator.
+ * @param  {boolean}  options.wrap
+ *     Set to false to keep the message on one line instead of wrapping it.
+ * @param  {number}  options.wrapWidth
+ *     Column width at which the message wraps onto a new line.
+ * @returns  {string}
+ *     Rendered labelled line.
+ */
+export function labelledLine(label = "", message = "", options = {}) {
+	const prefixText = createPrefix(label, options);
+	const prefix = renderPrefix(prefixText, options);
+	const messageText = String(message);
+
+	if (prefix === "") {
+		return messageText;
+	}
+
+	if (options.wrap === false) {
+		return `${prefix}${messageSeparator}${messageText}`;
+	}
+
+	const wrapWidth = resolveWrapWidth(prefixText, options);
+	const messageLines = wrapText(messageText, wrapWidth);
+	const continuationIndent = " ".repeat(prefixText.length + messageSeparator.length);
+	const wrappedMessage = messageLines.join(`\n${continuationIndent}`);
+
+	return `${prefix}${messageSeparator}${wrappedMessage}`;
+}
+
+/**
+ * Colour the icon/label prefix, sized from its plain-text length so the
+ * continuation indent lines up whether or not colour is applied.
+ *
+ * @param  {string}  prefix
+ *     Plain-text icon and label prefix.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Prefix, coloured when requested.
+ */
+function renderPrefix(prefix, options) {
+	if (prefix === "") {
+		return prefix;
+	}
+
+	if (options.colour !== true) {
+		return prefix;
+	}
+
+	const colouredPrefix = foreground(prefix, resolveColour(options), options);
+
+	return style(colouredPrefix, "bold", options);
+}
+
+/**
+ * Build the plain-text icon and label prefix.
+ *
+ * @param  {string}  label
+ *     Label text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Icon and label joined with a colon and space, or an empty string when both are empty.
+ */
+function createPrefix(label, options) {
+	const labelText = String(label);
+	const icon = typeof options.icon === "string" ? options.icon : "";
+	const labelPart = labelText === "" ? "" : `${labelText}:`;
+
+	return [icon, labelPart].filter((part) => part !== "").join(" ");
+}
+
+/**
+ * Pick the prefix's colour token.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Colour token, defaulting to "info" when no tone is given.
+ */
+function resolveColour(options) {
+	if (typeof options.tone === "string" && options.tone !== "") {
+		return options.tone;
+	}
+
+	return defaultColour;
+}
+
+/**
+ * Work out how wide the message can be before it wraps.
+ *
+ * @param  {string}  prefix
+ *     Plain-text icon and label prefix, used to size the continuation indent.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {number|undefined}
+ *     Explicit or derived wrap width, or undefined to use wrapText's own default.
+ */
+function resolveWrapWidth(prefix, options) {
+	if (options.wrapWidth !== undefined) {
+		return options.wrapWidth;
+	}
+
+	if (Number.isFinite(options.width)) {
+		return Math.max(1, options.width - prefix.length - messageSeparator.length);
+	}
+
+	return undefined;
+}

package/src/primitives/row.js

@@ -1,4 +1,5 @@
 import { foreground } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
 import { getResultSymbol, getResultToken } from "../theme/results.js";
 
 // Row labels use the same subdued tone as table headers by default.
@@ -7,6 +8,9 @@ const defaultLabelColour = "muted";
 // Rows use a compact gap that still reads cleanly in plain terminals.
 const defaultSeparator = "  ";
 
+// Keeps a wrapped value within a typical narrow terminal column.
+const defaultWrapWidth = 64;
+
 /**
  * Render a labelled value row.
  *
@@ -28,6 +32,12 @@ const defaultSeparator = "  ";
  *     Text between label and value.
  * @param  {string}  options.valueColour
  *     Optional colour token for the value.
+ * @param  {number}  options.width
+ *     Total row width used to calculate the available value width.
+ * @param  {boolean}  options.wrap
+ *     Set to false to keep the value on one line instead of wrapping it.
+ * @param  {number}  options.wrapWidth
+ *     Column width at which a value wraps onto a new line.
  * @returns  {string}
  *     Rendered row.
  */
@@ -45,7 +55,22 @@ export function row(label, value = "", options = {}) {
 	const renderedValue = renderValue(value, options);
 	const separator = options.separator ?? defaultSeparator;
 
-	return `${renderedLabel}${separator}${renderedValue}`;
+	if (options.wrap === false) {
+		return `${renderedLabel}${separator}${renderedValue}`;
+	}
+
+	const wrapWidth =
+		options.wrapWidth ??
+		(Number.isFinite(options.width)
+			? Math.max(1, options.width - labelWidth - separator.length)
+			: defaultWrapWidth);
+
+	const valueLines = wrapText(value, wrapWidth);
+	const continuationIndent = " ".repeat(labelWidth + separator.length);
+	const renderedValueLines = valueLines.map((line) => renderValue(line, options));
+	const wrappedValue = renderedValueLines.join(`\n${continuationIndent}`);
+
+	return `${renderedLabel}${separator}${wrappedValue}`;
 }
 
 /**