@lewishowles/cli-style 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.0 - 2026-06-29
+
+### Added
+
+- Added `createReporter()` for grouped setup and diagnostics output.
+- Added `severityOrder` and `getHighestSeverityResult()` for group result summaries.
+- Added shared `normaliseWidth()` helpers for width-aware renderers.
+- Added reporter output to the style gallery.
+
+### Changed
+
+- Darkened the muted colour token so unchanged rows are easier to distinguish from normal foreground text.
+
 ## 0.2.2 - 2026-06-29
 
 ### Added

package/README.md

@@ -41,6 +41,43 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
+## Reporter
+
+Use a reporter when a script needs grouped output rather than one row per file.
+
+```js
+import { createReporter } from "@lewishowles/cli-style";
+
+const reporter = createReporter({
+	colour: false,
+});
+
+reporter.section("Setting up Claude + Codex", "(project)");
+reporter.group("Agent scripts", [
+	{
+		label: "project-diagnostics.py",
+		result: "unchanged",
+	},
+	{
+		label: "repo-context.py",
+		result: "unchanged",
+	},
+], {
+	summary: "2 already linked",
+});
+reporter.status("success", "Done.");
+
+console.log(reporter.render());
+```
+
+Groups can include verbose detail rows when a caller opts in:
+
+```js
+const reporter = createReporter({
+	verbose: process.env.AGENTS_VERBOSE === "1",
+});
+```
+
 ## CLI
 
 Use `cli-style render <renderer>` when a script needs rendered text from JSON input.

package/package.json

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

package/src/create-cli-style.js

@@ -1,6 +1,7 @@
 import { resolveProfile } from "./capability/resolve-profile.js";
 import { resolveTerminalCapabilities } from "./capability/terminal.js";
 import { profiles } from "./profiles/profiles.js";
+import { createReporter } from "./reporters/create-reporter.js";
 
 /**
  * Create a CLI style renderer with stable, testable defaults.
@@ -27,6 +28,10 @@ export function createCliStyle(options = {}) {
 		print: (value) => {
 			console.log(value);
 		},
+		reporter: (reporterOptions = {}) => createReporter({
+			...resolvedOptions,
+			...reporterOptions,
+		}),
 		write: (value) => {
 			process.stdout.write(value);
 		},

package/src/formatters/width.js

@@ -0,0 +1,92 @@
+// Default terminal width used when no usable width is provided.
+export const defaultWidth = 80;
+
+// Narrowest width that still leaves room for meaningful terminal output.
+export const minimumWidth = 20;
+
+/**
+ * Resolve a usable terminal width.
+ *
+ * @param  {*}  width
+ *     Caller-provided width.
+ * @param  {object}  options
+ *     Width bounds.
+ * @param  {number}  options.defaultWidth
+ *     Width to use when the input is unusable.
+ * @param  {number}  options.maxWidth
+ *     Optional maximum width.
+ * @param  {number}  options.minWidth
+ *     Minimum accepted width.
+ * @returns  {number}
+ *     Integer width within the requested bounds.
+ */
+export function normaliseWidth(width, options = {}) {
+	const fallback = normaliseBound(options.defaultWidth, defaultWidth);
+	const lowerBound = normaliseBound(options.minWidth, minimumWidth);
+	const upperBound = normaliseOptionalBound(options.maxWidth);
+	const numericWidth = Number(width);
+
+	if (width === null || width === undefined || !Number.isFinite(numericWidth)) {
+		return clampWidth(fallback, lowerBound, upperBound);
+	}
+
+	return clampWidth(Math.floor(numericWidth), lowerBound, upperBound);
+}
+
+/**
+ * Resolve a positive numeric bound.
+ *
+ * @param  {*}  value
+ *     Caller-provided bound.
+ * @param  {number}  fallback
+ *     Bound to use when value is unusable.
+ * @returns  {number}
+ *     Positive integer bound.
+ */
+function normaliseBound(value, fallback) {
+	const numericValue = Number(value);
+
+	if (!Number.isFinite(numericValue) || numericValue < 1) {
+		return fallback;
+	}
+
+	return Math.floor(numericValue);
+}
+
+/**
+ * Resolve an optional maximum width.
+ *
+ * @param  {*}  value
+ *     Caller-provided maximum width.
+ * @returns  {number|null}
+ *     Positive integer maximum or null.
+ */
+function normaliseOptionalBound(value) {
+	const numericValue = Number(value);
+
+	if (!Number.isFinite(numericValue) || numericValue < 1) {
+		return null;
+	}
+
+	return Math.floor(numericValue);
+}
+
+/**
+ * Clamp a width between configured bounds.
+ *
+ * @param  {number}  width
+ *     Width to clamp.
+ * @param  {number}  minWidth
+ *     Lower bound.
+ * @param  {number|null}  maxWidth
+ *     Optional upper bound.
+ * @returns  {number}
+ *     Clamped width.
+ */
+function clampWidth(width, minWidth, maxWidth) {
+	const lowerClampedWidth = Math.max(width, minWidth);
+
+	return maxWidth === null
+		? lowerClampedWidth
+		: Math.min(lowerClampedWidth, Math.max(maxWidth, minWidth));
+}

package/src/gallery/render-gallery.js

@@ -17,6 +17,7 @@ import { row } from "../primitives/row.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
 import { table } from "../primitives/table.js";
+import { createReporter } from "../reporters/create-reporter.js";
 import { resultTypes } from "../theme/results.js";
 
 // Chip tone examples should expose every configured pill colour.
@@ -128,6 +129,7 @@ export const gallerySections = [
 // Pattern fixtures available for focused output and interactive search.
 export const galleryFixtures = [
 	"diagnostic-report",
+	"reporter",
 	"command-result",
 	"task-summary",
 	"agent-transcript",
@@ -435,6 +437,64 @@ function renderPatterns(options, fixture) {
 		],
 		title: "Project diagnostics",
 	}, options);
+	const reporter = createReporter(options);
+
+	reporter.section("Setting up Claude + Codex", "(project)");
+	reporter.group("Project files", [
+		{
+			detail: "already exists",
+			label: "AGENTS.md",
+			result: resultTypes.UNCHANGED,
+		},
+		{
+			detail: "already exists",
+			label: "WORKSPACE.md",
+			result: resultTypes.UNCHANGED,
+		},
+	], {
+		summary: "2 already present",
+	});
+	reporter.group("Agent scripts", [
+		{
+			detail: "already linked",
+			label: "project-diagnostics.py",
+			result: resultTypes.UNCHANGED,
+		},
+		{
+			detail: "already linked",
+			label: "generated-file-guard.py",
+			result: resultTypes.UNCHANGED,
+		},
+		{
+			detail: "already linked",
+			label: "repo-context.py",
+			result: resultTypes.UNCHANGED,
+		},
+		{
+			detail: "already linked",
+			label: "change-impact.py",
+			result: resultTypes.UNCHANGED,
+		},
+	], {
+		summary: "4 already linked",
+	});
+	reporter.group("Claude files", [
+		{
+			detail: "already exists",
+			label: ".claude/",
+			result: resultTypes.UNCHANGED,
+		},
+		{
+			detail: "already up to date",
+			label: ".claude/.claudeignore",
+			result: resultTypes.UNCHANGED,
+		},
+	], {
+		summary: "2 already current",
+	});
+	reporter.status(resultTypes.SUCCESS, "Done.");
+
+	const reporterOutput = reporter.render();
 	const nextStep = nextStepBlock({
 		alternatives: [
 			"Review the focused gallery fixture",
@@ -493,6 +553,7 @@ function renderPatterns(options, fixture) {
 		"confirmation-result": ["Confirmation result", confirmation],
 		"diagnostic-report": ["Diagnostic report", report],
 		"next-step-block": ["Next-step block", nextStep],
+		"reporter": ["Reporter", reporterOutput],
 		"task-summary": ["Task summary", summary],
 	};
 
@@ -509,6 +570,9 @@ function renderPatterns(options, fixture) {
 		"Diagnostic report",
 		frameExample(report, options),
 		"",
+		"Reporter",
+		frameExample(reporterOutput, options),
+		"",
 		"Command result",
 		frameExample(command, options),
 		"",

package/src/index.js

@@ -23,6 +23,7 @@ export {
 } from "./gallery/render-gallery.js";
 
 export { background, foreground, stripAnsi, style } from "./formatters/ansi.js";
+export { defaultWidth, minimumWidth, normaliseWidth } from "./formatters/width.js";
 export { agentTranscript } from "./patterns/agent-transcript.js";
 export { auditFinding } from "./patterns/audit-finding.js";
 export { commandResult } from "./patterns/command-result.js";
@@ -41,6 +42,12 @@ export { row } from "./primitives/row.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";
 export { table } from "./primitives/table.js";
+export {
+	createReporter,
+	renderGroup,
+	renderReporterStatus,
+	renderSection,
+} from "./reporters/create-reporter.js";
 export {
 	chartColours,
 	chipColours,
@@ -54,4 +61,11 @@ export {
 	terminalColours,
 	toneColours,
 } from "./theme/colours.js";
-export { getResultSymbol, getResultToken, resultTokens, resultTypes } from "./theme/results.js";
+export {
+	getHighestSeverityResult,
+	getResultSymbol,
+	getResultToken,
+	resultTokens,
+	resultTypes,
+	severityOrder,
+} from "./theme/results.js";

package/src/reporters/create-reporter.js

@@ -0,0 +1,214 @@
+import { isNonEmptyString } from "../patterns/helpers.js";
+import { status as renderStatus } from "../primitives/status.js";
+import {
+	getHighestSeverityResult,
+	getResultToken,
+	resultTypes,
+	severityOrder,
+} from "../theme/results.js";
+
+// Reporter output default options.
+const reporterDefaults = {
+	colour: false,
+	unicode: true,
+	verbose: false,
+};
+
+/**
+ * Create a pure string reporter for grouped CLI output.
+ *
+ * @param  {object}  options
+ *     Rendering and reporter options.
+ * @param  {boolean}  options.verbose
+ *     Whether groups should include detail rows by default.
+ * @returns  {object}
+ *     Reporter helpers.
+ */
+export function createReporter(options = {}) {
+	const reporterOptions = {
+		...reporterDefaults,
+		...options,
+	};
+	const lines = [];
+
+	return {
+		group: (label, items = [], groupOptions = {}) => append(lines, renderGroup(label, items, {
+			...reporterOptions,
+			...groupOptions,
+		})),
+		lines,
+		render: () => lines.join("\n"),
+		section: (label, detail = "", sectionOptions = {}) => append(lines, renderSection(label, detail, {
+			...reporterOptions,
+			...sectionOptions,
+		})),
+		status: (resultType, label, detail = "", statusOptions = {}) => append(lines, renderReporterStatus(resultType, label, detail, {
+			...reporterOptions,
+			...statusOptions,
+		})),
+	};
+}
+
+/**
+ * Render a reporter group without mutating a reporter instance.
+ *
+ * @param  {string}  label
+ *     Group label.
+ * @param  {object[]}  items
+ *     Child result rows.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered group.
+ */
+export function renderGroup(label, items = [], options = {}) {
+	const normalisedItems = normaliseItems(items);
+	const resultType = options.result ?? getHighestSeverityResult(normalisedItems.map((item) => item.result));
+	const summary = options.summary ?? summariseItems(normalisedItems);
+	const groupLine = renderReporterStatus(resultType, label, summary, options);
+
+	if (options.verbose !== true || normalisedItems.length === 0) {
+		return groupLine;
+	}
+
+	const detailLines = normalisedItems.map((item) => {
+		const line = renderReporterStatus(item.result, item.label, item.detail, options);
+
+		return `  ${line}`;
+	});
+
+	return [groupLine, ...detailLines].join("\n");
+}
+
+/**
+ * Render a reporter section heading.
+ *
+ * @param  {string}  label
+ *     Section label.
+ * @param  {string}  detail
+ *     Optional detail.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered section row.
+ */
+export function renderSection(label, detail = "", options = {}) {
+	return renderReporterStatus(resultTypes.INFO, label, detail, options);
+}
+
+/**
+ * Render one reporter status row.
+ *
+ * @param  {string}  resultType
+ *     Result type.
+ * @param  {string}  label
+ *     Row label.
+ * @param  {string}  detail
+ *     Optional detail.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered status row.
+ */
+export function renderReporterStatus(resultType, label, detail = "", options = {}) {
+	return renderStatus(resultType, detail, {
+		...options,
+		label,
+	});
+}
+
+/**
+ * Append a rendered line to the reporter state.
+ *
+ * @param  {string[]}  lines
+ *     Reporter lines.
+ * @param  {string}  value
+ *     Rendered value.
+ * @returns  {string}
+ *     Appended value.
+ */
+function append(lines, value) {
+	lines.push(value);
+
+	return value;
+}
+
+/**
+ * Keep only rows that can render useful output.
+ *
+ * @param  {object[]}  items
+ *     Caller-provided items.
+ * @returns  {object[]}
+ *     Normalised items.
+ */
+function normaliseItems(items) {
+	if (!Array.isArray(items)) {
+		return [];
+	}
+
+	return items
+		.filter((item) => item !== null && typeof item === "object")
+		.map((item) => ({
+			detail: isNonEmptyString(item.detail) ? item.detail : "",
+			label: isNonEmptyString(item.label) ? item.label : getResultToken(item.result).label,
+			result: getResultToken(item.result) === getResultToken(resultTypes.UNKNOWN)
+				? resultTypes.UNKNOWN
+				: item.result,
+		}));
+}
+
+/**
+ * Summarise grouped items by result label.
+ *
+ * @param  {object[]}  items
+ *     Normalised group items.
+ * @returns  {string}
+ *     Human-readable count summary.
+ */
+function summariseItems(items) {
+	if (items.length === 0) {
+		return "";
+	}
+
+	const counts = new Map();
+
+	for (const item of items) {
+		counts.set(item.result, (counts.get(item.result) ?? 0) + 1);
+	}
+
+	return [...counts.entries()]
+		.sort(([left], [right]) => resultPriority(left) - resultPriority(right))
+		.map(([resultType, count]) => formatCount(resultType, count))
+		.join(", ");
+}
+
+/**
+ * Format a result count.
+ *
+ * @param  {string}  resultType
+ *     Result type.
+ * @param  {number}  count
+ *     Result count.
+ * @returns  {string}
+ *     Count label.
+ */
+function formatCount(resultType, count) {
+	const token = getResultToken(resultType);
+	const label = token.label.toLowerCase();
+
+	return `${count} ${label}`;
+}
+
+/**
+ * Resolve a result's severity index.
+ *
+ * @param  {string}  resultType
+ *     Result type.
+ * @returns  {number}
+ *     Priority index.
+ */
+function resultPriority(resultType) {
+	const highestResult = getHighestSeverityResult([resultType]);
+
+	return severityOrder.indexOf(highestResult);
+}

package/src/theme/colours.js

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

package/src/theme/results.js

@@ -10,6 +10,18 @@ export const resultTypes = {
 	WARNING: "warning",
 };
 
+// Highest-priority result first for grouped summaries.
+export const severityOrder = [
+	resultTypes.FAILED,
+	resultTypes.WARNING,
+	resultTypes.PARTIAL,
+	resultTypes.UNKNOWN,
+	resultTypes.SUCCESS,
+	resultTypes.SKIPPED,
+	resultTypes.INFO,
+	resultTypes.UNCHANGED,
+];
+
 // Display tokens for result states before colour rendering exists.
 export const resultTokens = {
 	[resultTypes.FAILED]: {
@@ -98,6 +110,28 @@ export function getResultToken(resultType) {
 	return resultTokens[resultType] ?? resultTokens[resultTypes.UNKNOWN];
 }
 
+/**
+ * Resolve the highest-priority result from a list.
+ *
+ * @param  {string[]}  resultList
+ *     Result types to compare.
+ * @returns  {string}
+ *     Highest-priority result, or unknown when no known result is present.
+ */
+export function getHighestSeverityResult(resultList) {
+	if (!Array.isArray(resultList) || resultList.length === 0) {
+		return resultTypes.UNKNOWN;
+	}
+
+	for (const resultType of severityOrder) {
+		if (resultList.includes(resultType)) {
+			return resultType;
+		}
+	}
+
+	return resultTypes.UNKNOWN;
+}
+
 /**
  * Resolve the display symbol for a result type.
  *