@lewishowles/cli-style 0.13.0 → 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";
@@ -776,6 +777,9 @@ function renderPrimitives(options) {
 			width: 18,
 		}),
 		"",
+		"Bullet lists",
+		renderBulletListExamples(options),
+		"",
 		"Feedback",
 		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
 		labelledLine("Notice", "Reusable labelled output", {
@@ -872,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.
  *

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/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;
+}