@lewishowles/cli-style 0.12.1 → 0.14.0

package/src/cli/adapter-path-command.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// Adapter paths returned for shell and Python wrapper setup.
+// Adapter paths returned for consumer setup.
 const adapterPaths = {
 	bash: {
 		releasePath: "adapters/bash/cli-style.sh",
@@ -13,8 +13,8 @@ const adapterPaths = {
 		sourceUrl: new URL("../../adapters/python", import.meta.url),
 	},
 	swift: {
-		releasePath: "adapters/swift/CliStyle.swift",
-		sourceUrl: new URL("../../adapters/swift/CliStyle.swift", import.meta.url),
+		releasePath: "adapters/swift",
+		sourceUrl: new URL("../../adapters/swift", import.meta.url),
 	},
 };
 

package/src/cli/render-command.js

@@ -8,6 +8,7 @@ import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
 import { barChart } from "../primitives/bar-chart.js";
+import { bulletList } from "../primitives/bullet-list.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
@@ -33,6 +34,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	"bullet-list": (input, options) =>
+		bulletList(input.items, {
+			...input,
+			...options,
+		}),
 	chip: (input, options) =>
 		chip(input.label, input.tone, {
 			...input,

package/src/gallery/render-gallery.js

@@ -10,6 +10,7 @@ import { taskSummary } from "../patterns/task-summary.js";
 import { stripAnsi } from "../formatters/ansi.js";
 import { renderSpinnerFrame } from "../interactive/spinner.js";
 import { barChart } from "../primitives/bar-chart.js";
+import { bulletList } from "../primitives/bullet-list.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
@@ -764,12 +765,21 @@ function renderPrimitives(options) {
 		"Tables",
 		renderTableExample(options),
 		"",
+		"Truncated tables",
+		renderOverflowTableExample(options, "truncate"),
+		"",
+		"Wrapped tables",
+		renderOverflowTableExample(options, "wrap"),
+		"",
 		"Narrow tables",
 		renderTableExample({
 			...options,
 			width: 18,
 		}),
 		"",
+		"Bullet lists",
+		renderBulletListExamples(options),
+		"",
 		"Feedback",
 		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
 		labelledLine("Notice", "Reusable labelled output", {
@@ -866,6 +876,42 @@ function renderPrimitives(options) {
 	].join("\n");
 }
 
+/**
+ * Render representative flat, wrapped, nested, narrow, and plain bullet lists.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Bullet list examples.
+ */
+function renderBulletListExamples(options) {
+	return [
+		bulletList(["Install dependencies", "Run the unit tests", "Review the output"], options),
+		bulletList(["This item wraps so continuation lines stay aligned with the item text."], {
+			...options,
+			width: 40,
+		}),
+		bulletList(
+			[
+				{
+					items: ["Use the focused check", "Read the first failure"],
+					text: "Verification",
+				},
+				"Commit the completed chunk",
+			],
+			options,
+		),
+		bulletList(["Narrow output keeps the gutter readable."], {
+			...options,
+			width: 24,
+		}),
+		bulletList(["ASCII output remains easy to grep."], {
+			...options,
+			profile: "plain",
+		}),
+	].join("\n");
+}
+
 /**
  * Render wide or narrow table diagnostics.
  *
@@ -900,6 +946,40 @@ function renderTableExample(options) {
 	});
 }
 
+/**
+ * Render a table with a long-detail column capped by maxWidth.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  overflow
+ *     Overflow mode ('truncate' or 'wrap') for the capped column.
+ * @returns  {string}
+ *     Table example.
+ */
+function renderOverflowTableExample(options, overflow) {
+	return table({
+		...options,
+		columns: [
+			{
+				key: "source",
+				label: "Source",
+			},
+			{
+				key: "detail",
+				label: "Detail",
+				maxWidth: 28,
+				overflow,
+			},
+		],
+		rows: [
+			{
+				detail: "packages/cli-style/src/primitives/table.js",
+				source: "Table",
+			},
+		],
+	});
+}
+
 /**
  * Render a chart that exposes positive, warning, and negative colours.
  *

package/src/index.js

@@ -40,6 +40,7 @@ export { diffBlock } from "./patterns/diff-block.js";
 export { nextStepBlock } from "./patterns/next-step-block.js";
 export { taskSummary } from "./patterns/task-summary.js";
 export { barChart } from "./primitives/bar-chart.js";
+export { bulletList } from "./primitives/bullet-list.js";
 export { chip } from "./primitives/chip.js";
 export { divider } from "./primitives/divider.js";
 export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
@@ -62,6 +63,8 @@ export {
 	renderSection,
 } from "./reporters/create-reporter.js";
 
+export { bulletTokens, getBulletSymbol } from "./theme/bullets.js";
+
 export {
 	chartColours,
 	chipColours,

package/src/patterns/audit-finding.js

@@ -48,15 +48,15 @@ export function auditFinding(finding, options = {}) {
 
 	const title = isNonEmptyString(finding.title) ? finding.title : defaultTitle;
 	const summary = isNonEmptyString(finding.finding) ? finding.finding : "";
-	const evidence = normaliseStringList(finding.evidence).map((item) => `- ${item}`);
-	const references = normaliseStringList(finding.references).map((item) => `- ${item}`);
+	const evidence = normaliseStringList(finding.evidence);
+	const references = normaliseStringList(finding.references);
 
 	const sections = [
 		status(finding.result ?? resultTypes.UNKNOWN, summary, options),
 		renderLocation(finding.location, options),
-		renderSection("Evidence", evidence, options, false),
+		renderSection("Evidence", evidence, options, true),
 		renderTextSection("Recommendation", finding.recommendation, options),
-		renderSection("References", references, options, false),
+		renderSection("References", references, options, true),
 	].filter((section) => section !== "");
 
 	return [renderTitle(title, options), ...sections].join("\n\n");

package/src/patterns/command-result.js

@@ -48,13 +48,13 @@ export function commandResult(result, options = {}) {
 
 	const title = isNonEmptyString(result.title) ? result.title : defaultTitle;
 	const metadata = renderMetadata(result, options);
-	const details = normaliseStringList(result.details).map((detail) => `- ${detail}`);
+	const details = normaliseStringList(result.details);
 	const summary = isNonEmptyString(result.summary) ? result.summary : "";
 
 	const sections = [
 		status(result.result ?? resultTypes.UNKNOWN, summary, options),
 		metadata,
-		renderSection("Details", details, options, false),
+		renderSection("Details", details, options, true),
 	].filter((section) => section !== "");
 
 	return [renderTitle(title, options), ...sections].join("\n\n");

package/src/patterns/diagnostic-report.js

@@ -69,7 +69,8 @@ function renderChecks(checks, options) {
 		status(check.result, formatLabel(check.name, check.detail, options), options),
 	);
 
-	return renderSection("Checks", lines, options);
+	// Status lines already start with a symbol, so only agent Markdown adds bullets.
+	return renderSection("Checks", lines, options, options.profile === profiles.AGENT);
 }
 
 /**
@@ -89,7 +90,8 @@ function renderFindings(findings, options) {
 
 	const lines = validFindings.map((finding) => status(finding.result, finding.message, options));
 
-	return renderSection("Findings", lines, options);
+	// Only agent Markdown adds bullets beside the status symbol.
+	return renderSection("Findings", lines, options, options.profile === profiles.AGENT);
 }
 
 /**
@@ -111,7 +113,8 @@ function renderSkippedChecks(skippedChecks, options) {
 		status(resultTypes.SKIPPED, formatLabel(check.name, check.reason, options), options),
 	);
 
-	return renderSection("Skipped checks", lines, options);
+	// Only agent Markdown adds bullets beside the status symbol.
+	return renderSection("Skipped checks", lines, options, options.profile === profiles.AGENT);
 }
 
 /**

package/src/patterns/helpers.js

@@ -1,3 +1,4 @@
+import { bulletList } from "../primitives/bullet-list.js";
 import { profiles } from "../profiles/profiles.js";
 
 /**
@@ -72,7 +73,8 @@ export function normaliseStringList(values) {
  * @param  {object}  options
  *     Rendering options.
  * @param  {boolean}  listItems
- *     Whether agent output should use bullet items.
+ *     Whether to show each line as a bullet point, wrapped to the terminal
+ *     width. Pass false for single values, commands, or numbered lines.
  * @returns  {string}
  *     Rendered section.
  */
@@ -83,10 +85,15 @@ export function renderSection(title, lines, options, listItems = true) {
 
 	const heading = options.profile === profiles.AGENT ? `## ${title}` : title;
 
-	const content =
-		options.profile === profiles.AGENT && listItems ? lines.map((line) => `- ${line}`) : lines;
+	const content = listItems
+		? bulletList(lines, {
+				profile: options.profile,
+				unicode: options.unicode,
+				width: options.width,
+			})
+		: lines.join("\n");
 
-	return [heading, ...content].join("\n");
+	return [heading, content].join("\n");
 }
 
 /**

package/src/patterns/next-step-block.js

@@ -49,15 +49,13 @@ export function nextStepBlock(nextStep, options = {}) {
 
 	const commands = renderCommands(nextStep.commands, options);
 
-	const alternatives = normaliseStringList(nextStep.alternatives).map(
-		(alternative) => `- ${alternative}`,
-	);
+	const alternatives = normaliseStringList(nextStep.alternatives);
 
 	const sections = [
 		next,
 		reason,
 		commands,
-		renderSection("Alternatives", alternatives, options, false),
+		renderSection("Alternatives", alternatives, options, true),
 	].filter((section) => section !== "");
 
 	return [renderTitle(title, options), ...sections].join("\n\n");

package/src/patterns/task-summary.js

@@ -47,13 +47,13 @@ export function taskSummary(summary, options = {}) {
 	const title = isNonEmptyString(summary.title) ? summary.title : defaultTitle;
 	const task = isNonEmptyString(summary.task) ? summary.task : "";
 	const detail = formatLabel(task, summary.summary, options);
-	const completed = normaliseStringList(summary.completed).map((item) => `- ${item}`);
-	const remaining = normaliseStringList(summary.remaining).map((item) => `- ${item}`);
+	const completed = normaliseStringList(summary.completed);
+	const remaining = normaliseStringList(summary.remaining);
 
 	const sections = [
 		status(summary.result ?? resultTypes.UNKNOWN, detail, options),
-		renderSection("Completed", completed, options, false),
-		renderSection("Remaining", remaining, options, false),
+		renderSection("Completed", completed, options, true),
+		renderSection("Remaining", remaining, options, true),
 	].filter((section) => section !== "");
 
 	return [renderTitle(title, options), ...sections].join("\n\n");

package/src/primitives/bullet-list.js

@@ -0,0 +1,150 @@
+import { wrapText } from "../formatters/wrap.js";
+import { getBulletSymbol } from "../theme/bullets.js";
+
+/**
+ * Render items as a bullet list, wrapping each item's text beside its bullet.
+ *
+ * @param  {object[]}  items
+ *     Item text, or `{ text, items }` for an item with nested items. Empty and
+ *     malformed items are skipped.
+ * @param  {object}  options
+ *     Rendering and wrapping options.
+ * @param  {number}  options.width
+ *     Total line width used to calculate the available item width.
+ * @param  {number}  options.wrapWidth
+ *     Explicit text width for each item.
+ * @returns  {string}
+ *     Rendered bullet list, or an empty string when no usable items exist.
+ */
+export function bulletList(items = [], options = {}) {
+	const normalisedItems = normaliseItems(items);
+
+	if (normalisedItems.length === 0) {
+		return "";
+	}
+
+	return renderItems(normalisedItems, options, 0).join("\n");
+}
+
+/**
+ * Render one level of items and its nested children.
+ *
+ * @param  {object[]}  items
+ *     Normalised entries at the current nesting level.
+ * @param  {object}  options
+ *     Rendering and wrapping options.
+ * @param  {number}  depth
+ *     Zero-based nesting depth.
+ * @returns  {string[]}
+ *     Rendered lines for this level and its children.
+ */
+function renderItems(items, options, depth) {
+	const lines = [];
+
+	for (const entry of items) {
+		const prefix = createPrefix(depth, options);
+		const itemLines = wrapText(entry.text, resolveWrapWidth(prefix, options));
+
+		lines.push(
+			...itemLines.map((line, index) => {
+				if (index === 0) {
+					return `${prefix}${line}`;
+				}
+
+				return `${" ".repeat(prefix.length)}${line}`;
+			}),
+		);
+
+		const childItems = normaliseItems(entry.items);
+
+		if (childItems.length > 0) {
+			lines.push(...renderItems(childItems, options, depth + 1));
+		}
+	}
+
+	return lines;
+}
+
+/**
+ * Build the plain-text prefix used for one item and its continuations.
+ *
+ * @param  {number}  depth
+ *     Zero-based nesting depth.
+ * @param  {object}  options
+ *     Symbol rendering options.
+ * @returns  {string}
+ *     Uncoloured indentation, bullet, and trailing space.
+ */
+function createPrefix(depth, options) {
+	const symbol = getBulletSymbol(depth, options);
+	const gutter = `${symbol} `;
+	const indentation = " ".repeat(depth * gutter.length);
+
+	return `${indentation}${gutter}`;
+}
+
+/**
+ * Resolve the text width available after the item prefix.
+ *
+ * @param  {string}  prefix
+ *     Plain-text item prefix.
+ * @param  {object}  options
+ *     Rendering and wrapping options.
+ * @returns  {number|undefined}
+ *     Explicit text width, derived text width, or undefined for wrapText's 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);
+	}
+
+	return undefined;
+}
+
+/**
+ * Convert a list value into renderable entries, dropping unusable items.
+ *
+ * @param  {*}  items
+ *     Requested list entries.
+ * @returns  {object[]}
+ *     Non-empty strings and valid nested entries.
+ */
+function normaliseItems(items) {
+	if (!Array.isArray(items)) {
+		return [];
+	}
+
+	return items.map(normaliseItem).filter((entry) => entry !== null);
+}
+
+/**
+ * Convert one supported input value into a list entry.
+ *
+ * @param  {*}  item
+ *     Requested list value.
+ * @returns  {object|null}
+ *     Original object or a new entry for a string, or null when the value has no usable text.
+ */
+function normaliseItem(item) {
+	if (typeof item === "string" && item.trim() !== "") {
+		return {
+			items: [],
+			text: item,
+		};
+	}
+
+	if (
+		item !== null &&
+		typeof item === "object" &&
+		typeof item.text === "string" &&
+		item.text.trim() !== ""
+	) {
+		return item;
+	}
+
+	return null;
+}

package/src/primitives/table.js

@@ -1,9 +1,7 @@
 import { foreground } from "../formatters/ansi.js";
+import { defaultWidth, minimumWidth, normaliseWidth } from "../formatters/width.js";
 import { tableColours } from "../theme/colours.js";
 
-// Tables assume a standard terminal width when no capability is provided.
-const defaultWidth = 80;
-
 // Columns use a compact but readable gap.
 const columnSeparator = "  ";
 
@@ -15,7 +13,9 @@ const columnSeparator = "  ";
  * @param  {boolean}  options.colour
  *     Whether ANSI colour should be applied.
  * @param  {object[]}  options.columns
- *     Column keys and labels.
+ *     Column keys and labels. A column may set maxWidth to cap its width,
+ *     with overflow ('truncate', the default, or 'wrap') controlling how
+ *     values beyond that width render.
  * @param  {object[]}  options.rows
  *     Table records.
  * @param  {boolean}  options.unicode
@@ -39,7 +39,18 @@ export function table(options = {}) {
 		widths.reduce((total, width) => total + width, 0) +
 		columnSeparator.length * (columns.length - 1);
 
-	const availableWidth = Number.isFinite(options.width) ? options.width : defaultWidth;
+	const requestedWidth = Number.isFinite(options.width) ? options.width : undefined;
+
+	// Let a requested width smaller than minimumWidth pass through unclamped.
+	const minimumTableWidth =
+		requestedWidth === undefined
+			? minimumWidth
+			: Math.max(1, Math.min(requestedWidth, minimumWidth));
+
+	const availableWidth = normaliseWidth(requestedWidth, {
+		defaultWidth,
+		minWidth: minimumTableWidth,
+	});
 
 	if (naturalWidth > availableWidth) {
 		return renderBlocks(columns, rows, options);
@@ -99,9 +110,65 @@ function normaliseRows(rows) {
  *     Column widths.
  */
 function columnWidths(columns, rows) {
-	return columns.map((column) =>
-		Math.max(column.label.length, ...rows.map((row) => cellValue(row[column.key]).length)),
-	);
+	return columns.map((column) => {
+		const naturalWidth = Math.max(
+			column.label.length,
+			...rows.map((row) => cellValue(row[column.key]).length),
+		);
+
+		const maxWidth = columnMaxWidth(column);
+
+		return maxWidth === null ? naturalWidth : Math.min(naturalWidth, maxWidth);
+	});
+}
+
+/**
+ * Return a column's configured width cap, if any.
+ *
+ * @param  {object}  column
+ *     Table column.
+ * @returns  {number|null}
+ *     Normalised maxWidth, or null when the column has none.
+ */
+function columnMaxWidth(column) {
+	if (!Number.isFinite(column.maxWidth) || column.maxWidth < 1) {
+		return null;
+	}
+
+	return normaliseWidth(column.maxWidth, {
+		defaultWidth: 1,
+		minWidth: 1,
+	});
+}
+
+/**
+ * Split a cell's value into the lines it renders as within a fixed-width column.
+ *
+ * @param  {string}  value
+ *     Cell value.
+ * @param  {object}  column
+ *     Table column, read for its overflow mode.
+ * @param  {number}  width
+ *     Column width.
+ * @returns  {string[]}
+ *     Lines the cell renders as; truncated to one line with a trailing
+ *     ellipsis unless the column's overflow is 'wrap'.
+ */
+function columnLines(value, column, width) {
+	if (value.length <= width) {
+		return [value];
+	}
+
+	if (column.overflow === "wrap") {
+		return Array.from(
+			{
+				length: Math.ceil(value.length / width),
+			},
+			(_, index) => value.slice(index * width, (index + 1) * width),
+		);
+	}
+
+	return [`${value.slice(0, width - 1)}…`];
 }
 
 /**
@@ -120,9 +187,11 @@ function columnWidths(columns, rows) {
  */
 function renderTable(columns, rows, widths, options) {
 	const header = columns
-		.map((column, index) =>
-			renderHeader(padColumn(column.label, widths[index], index, columns.length), options),
-		)
+		.map((column, index) => {
+			const headerLine = columnLines(column.label, { overflow: "truncate" }, widths[index])[0];
+
+			return renderHeader(padColumn(headerLine, widths[index], index, columns.length), options);
+		})
 		.join(columnSeparator);
 
 	const ruleCharacter = options.unicode === false ? "-" : "─";
@@ -131,17 +200,29 @@ function renderTable(columns, rows, widths, options) {
 	const renderedRule =
 		options.colour === true ? foreground(rule, tableColours.border, options) : rule;
 
-	const body = rows.map((row) =>
-		columns
-			.map((column, index) =>
-				renderCell(
-					padColumn(cellValue(row[column.key]), widths[index], index, columns.length),
-					index,
-					options,
-				),
-			)
-			.join(columnSeparator),
-	);
+	const body = rows.flatMap((row) => {
+		const lines = columns.map((column, index) =>
+			columnLines(cellValue(row[column.key]), column, widths[index]),
+		);
+
+		const lineCount = Math.max(...lines.map((column) => column.length));
+
+		return Array.from(
+			{
+				length: lineCount,
+			},
+			(_, lineIndex) =>
+				columns
+					.map((column, index) =>
+						renderCell(
+							padColumn(lines[index][lineIndex] ?? "", widths[index], index, columns.length),
+							index,
+							options,
+						),
+					)
+					.join(columnSeparator),
+		);
+	});
 
 	return [header, renderedRule, ...body].join("\n");
 }

package/src/theme/bullets.js

@@ -0,0 +1,41 @@
+import { profiles } from "../profiles/profiles.js";
+
+// Bullet symbols for Unicode, ASCII, and Markdown-compatible agent output.
+export const bulletTokens = {
+	agent: "-",
+	ascii: "*",
+	unicode: {
+		nested: "◦",
+		root: "•",
+	},
+};
+
+/**
+ * Resolve the display symbol for one bullet depth.
+ *
+ * @param  {number}  depth
+ *     Zero-based nesting depth.
+ * @param  {object}  options
+ *     Symbol rendering options.
+ * @param  {string}  options.profile
+ *     Active output profile.
+ * @param  {boolean}  options.unicode
+ *     Whether to return the Unicode symbol.
+ * @returns  {string}
+ *     Display symbol for the requested bullet depth and profile.
+ */
+export function getBulletSymbol(depth = 0, options = {}) {
+	if (options.profile === profiles.AGENT) {
+		return bulletTokens.agent;
+	}
+
+	if (
+		options.profile === profiles.CI ||
+		options.profile === profiles.PLAIN ||
+		options.unicode === false
+	) {
+		return bulletTokens.ascii;
+	}
+
+	return depth === 0 ? bulletTokens.unicode.root : bulletTokens.unicode.nested;
+}