@lewishowles/cli-style 0.8.1 → 0.10.0

package/src/capability/terminal.js

@@ -1,6 +1,11 @@
+import { isTheme, themes } from "../theme/colours.js";
+
 // Default terminal width when no stream width is available.
 const defaultWidth = 80;
 
+// Known terminal signals support a conservative dark palette when no theme is explicit.
+const terminalThemeSignals = ["COLORTERM", "TERM_PROGRAM"];
+
 /**
  * Resolve terminal output capabilities from injected args, env, and stream data.
  *
@@ -47,11 +52,104 @@ export function resolveTerminalCapabilities(options = {}) {
 		isCi,
 		isDumb,
 		isTty,
+		theme: resolveTheme({
+			argv,
+			env,
+			theme: options.theme,
+		}),
 		unicode,
 		width,
 	};
 }
 
+/**
+ * Resolve a terminal theme from explicit overrides and terminal signals.
+ *
+ * @param  {object}  options
+ *     Theme resolution inputs.
+ * @returns  {string}
+ *     Resolved light or dark theme.
+ */
+export function resolveTheme(options = {}) {
+	const flagTheme = readThemeFlag(options.argv ?? []);
+
+	if (flagTheme !== undefined) {
+		return flagTheme;
+	}
+
+	if (isTheme(options.theme) && options.theme !== themes.AUTO) {
+		return options.theme;
+	}
+
+	const colourFgBgTheme = resolveColourFgBgTheme(options.env?.COLORFGBG);
+
+	if (colourFgBgTheme !== themes.AUTO) {
+		return colourFgBgTheme;
+	}
+
+	return resolveTerminalSignalTheme(options.env) ?? themes.DARK;
+}
+
+/**
+ * Resolve a conservative theme from best-effort terminal signals.
+ *
+ * @param  {object}  env
+ *     Environment values to inspect.
+ * @returns  {string|undefined}
+ *     Dark theme when a known terminal signal is present.
+ */
+function resolveTerminalSignalTheme(env = {}) {
+	if (terminalThemeSignals.some((signal) => env[signal])) {
+		return themes.DARK;
+	}
+
+	return undefined;
+}
+
+/**
+ * Resolve known COLORFGBG background slots without guessing custom palettes.
+ *
+ * @param  {string}  colourFgBg
+ *     Terminal foreground and background capability string.
+ * @returns  {string}
+ *     Resolved light, dark, or automatic theme.
+ */
+function resolveColourFgBgTheme(colourFgBg) {
+	const background = colourFgBg?.split(";").at(-1);
+
+	if (background === "0" || background === "8") {
+		return themes.DARK;
+	}
+
+	if (background === "7" || background === "15") {
+		return themes.LIGHT;
+	}
+
+	return themes.AUTO;
+}
+
+/**
+ * Read the final explicit theme flag so later command arguments can override earlier ones.
+ *
+ * @param  {string[]}  argv
+ *     CLI arguments to inspect.
+ * @returns  {string|undefined}
+ *     Explicit theme when present.
+ */
+function readThemeFlag(argv) {
+	let theme;
+
+	for (const argument of argv) {
+		if (argument === "--dark") {
+			theme = themes.DARK;
+		} else if (argument === "--light") {
+			theme = themes.LIGHT;
+		}
+	}
+
+	return theme;
+}
+
 /**
  * Resolve colour support from explicit flags and terminal state.
  *

package/src/catalogue/renderer-catalogue.js

@@ -0,0 +1,62 @@
+// Static renderer metadata shared by CLI discovery and render validation.
+export const rendererCatalogue = [
+	["agent-transcript", "pattern", "agentTranscript", ["entries"], "agent-transcript"],
+	["audit-finding", "pattern", "auditFinding", ["finding", "result"], "audit-finding"],
+	["bar-chart", "primitive", "barChart", ["rows"], undefined],
+	["chip", "primitive", "chip", ["label", "tone"], undefined],
+	["command-result", "pattern", "commandResult", ["result", "summary"], "command-result"],
+	["compact-data-table", "pattern", "compactDataTable", ["columns", "rows"], "compact-data-table"],
+	[
+		"confirmation-result",
+		"pattern",
+		"confirmationResult",
+		["action", "state"],
+		"confirmation-result",
+	],
+	[
+		"diagnostic-report",
+		"pattern",
+		"diagnosticReport",
+		["findings", "summary"],
+		"diagnostic-report",
+	],
+	["diff-block", "pattern", "diffBlock", ["lines"], "diff-block"],
+	["divider", "primitive", "divider", ["label"], undefined],
+	["empty-state", "primitive", "emptyState", ["detail", "title"], undefined],
+	["error-block", "primitive", "errorBlock", ["lines", "title"], undefined],
+	["hint", "primitive", "hint", ["message"], 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],
+	["sparkline", "primitive", "sparkline", ["values"], "sparkline"],
+	["span", "primitive", "span", ["tone", "value"], undefined],
+	["status", "primitive", "status", ["detail", "type"], undefined],
+	["step", "primitive", "step", ["label", "state"], undefined],
+	["step-progress", "primitive", "stepProgress", ["current", "steps"], undefined],
+	["table", "primitive", "table", ["columns", "rows"], undefined],
+	["task-summary", "pattern", "taskSummary", ["result", "task"], "task-summary"],
+].map(([name, category, api, fields, fixture]) => ({
+	api,
+	category,
+	fields,
+	fixture,
+	name,
+	purpose: `${api} renderer.`,
+}));
+
+// Stable CLI names derived from the catalogue.
+export const rendererNames = rendererCatalogue.map((renderer) => renderer.name);
+
+/**
+ * Find renderer metadata by its stable CLI name.
+ *
+ * @param  {string}  name
+ *     Renderer name to look up.
+ * @returns  {object|undefined}
+ *     Renderer metadata when found.
+ */
+export function getRendererMetadata(name) {
+	return rendererCatalogue.find((renderer) => renderer.name === name);
+}

package/src/cli/catalogue-command.js

@@ -0,0 +1,108 @@
+import { getRendererMetadata, rendererCatalogue } from "../catalogue/renderer-catalogue.js";
+
+// Rendering flags are resolved before catalogue command parsing.
+const globalRenderingFlags = new Set([
+	"--dark",
+	"--json",
+	"--light",
+	"--no-color",
+	"--no-colour",
+	"--no-unicode",
+	"--plain",
+]);
+
+/**
+ * Parse a catalogue discovery request.
+ *
+ * @param  {string}  command
+ *     Catalogue command name.
+ * @param  {string[]}  args
+ *     Arguments after the command.
+ * @returns  {object}
+ *     Parsed catalogue request.
+ */
+export function parseCatalogueRequest(command, args = []) {
+	const commandArgs = args.filter((argument) => !globalRenderingFlags.has(argument));
+
+	if (command === "list" && commandArgs.length === 0) {
+		return {
+			command,
+		};
+	}
+
+	if (
+		command === "describe" &&
+		commandArgs.length === 1 &&
+		getRendererMetadata(commandArgs[0]) !== undefined
+	) {
+		return {
+			command,
+			renderer: commandArgs[0],
+		};
+	}
+
+	if (command === "describe" && commandArgs.length === 1) {
+		throw new Error(`Unknown renderer: ${commandArgs[0]}`);
+	}
+
+	throw new Error(
+		command === "describe" ? "Usage: cli-style describe <renderer>" : "Usage: cli-style list",
+	);
+}
+
+/**
+ * Render catalogue data for the requested output profile.
+ *
+ * @param  {object}  request
+ *     Parsed catalogue request.
+ * @param  {object}  options
+ *     Resolved rendering options.
+ * @returns  {string}
+ *     Text or JSON catalogue output.
+ */
+export function renderCatalogue(request, options = {}) {
+	const data =
+		request.command === "list" ? rendererCatalogue : getRendererMetadata(request.renderer);
+
+	if (options.profile === "json") {
+		return JSON.stringify(data, null, 2);
+	}
+
+	if (request.command === "describe") {
+		return renderDescription(data);
+	}
+
+	return ["primitive", "pattern"]
+		.flatMap((category) => [
+			category,
+			...rendererCatalogue
+				.filter((renderer) => renderer.category === category)
+				.map((renderer) => `  ${renderer.name}  ${renderer.api}`),
+			"",
+		])
+		.slice(0, -1)
+		.join("\n");
+}
+
+/**
+ * Render one renderer's discovery details.
+ *
+ * @param  {object}  renderer
+ *     Renderer metadata.
+ * @returns  {string}
+ *     Human-readable renderer description.
+ */
+function renderDescription(renderer) {
+	const gallery =
+		renderer.fixture === undefined
+			? "No focused fixture."
+			: `cli-style gallery --fixture ${renderer.fixture}`;
+
+	return [
+		renderer.name,
+		`Category: ${renderer.category}`,
+		`JavaScript: ${renderer.api}`,
+		`Fields: ${renderer.fields.join(", ")}`,
+		`Gallery: ${gallery}`,
+	].join("\n");
+}

package/src/cli/gallery-command.js

@@ -4,7 +4,14 @@ import { galleryFixtures, gallerySections, galleryVariants } from "../gallery/re
 import { isProfile, profiles } from "../profiles/profiles.js";
 
 // Global rendering flags accepted after `gallery` for focused review commands.
-const globalRenderingFlags = new Set(["--no-color", "--no-colour", "--no-unicode", "--plain"]);
+const globalRenderingFlags = new Set([
+	"--dark",
+	"--light",
+	"--no-color",
+	"--no-colour",
+	"--no-unicode",
+	"--plain",
+]);
 
 /**
  * Parse gallery command arguments.

package/src/cli/help.js

@@ -5,18 +5,23 @@ const helpLines = [
 	"Usage:",
 	"  cli-style --help",
 	"  cli-style adapter-path bash|python",
+	"  cli-style list [options]",
+	"  cli-style describe <renderer> [options]",
 	"  cli-style gallery [variant] [options]",
 	"  cli-style render <renderer> [options] < input.json",
 	"",
 	"Commands:",
 	"  adapter-path    Print a Bash or Python adapter path.",
 	"  gallery    Print the read-only style gallery.",
+	"  list       List available primitives and patterns.",
+	"  describe   Describe one renderer and its input fields.",
 	"  render     Render caller-provided JSON from stdin.",
 	"",
 	"Gallery variants:",
 	"  current, no-colour, no-unicode, plain",
 	"",
 	"Options:",
+	"  --light, --dark     Override automatic terminal-theme detection.",
 	"  --section <name>    Show primitives or patterns.",
 	"  --fixture <name>    Show one named pattern fixture.",
 	"  --profile <name>    Render with a text profile.",

package/src/cli/render-command.js

@@ -4,6 +4,7 @@ import { commandResult } from "../patterns/command-result.js";
 import { compactDataTable } from "../patterns/compact-data-table.js";
 import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
+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";
@@ -13,11 +14,14 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { rowGroup } from "../primitives/row-group.js";
+import { sparkline } from "../primitives/sparkline.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress } from "../primitives/step-progress.js";
 import { table } from "../primitives/table.js";
 import { isProfile, profiles } from "../profiles/profiles.js";
+export { rendererNames } from "../catalogue/renderer-catalogue.js";
 
 // Renderer names accepted by the custom-input render command.
 const renderers = {
@@ -37,6 +41,7 @@ const renderers = {
 	"compact-data-table": (input, options) => compactDataTable(input, options),
 	"confirmation-result": (input, options) => confirmationResult(input, options),
 	"diagnostic-report": (input, options) => diagnosticReport(input, options),
+	"diff-block": (input, options) => diffBlock(input, options),
 	divider: (input, options) =>
 		divider({
 			...input,
@@ -73,6 +78,16 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	"row-group": (input, options) =>
+		rowGroup({
+			...input,
+			...options,
+		}),
+	sparkline: (input, options) =>
+		sparkline({
+			...input,
+			...options,
+		}),
 	span: (input, options) =>
 		span(input.value, input.tone, {
 			...input,
@@ -102,10 +117,16 @@ const renderers = {
 };
 
 // Global rendering flags accepted after `render <renderer>`.
-const globalRenderingFlags = new Set(["--no-color", "--no-colour", "--no-unicode", "--plain"]);
+const globalRenderingFlags = new Set([
+	"--dark",
+	"--light",
+	"--no-color",
+	"--no-colour",
+	"--no-unicode",
+	"--plain",
+]);
 
 // Renderer names exposed for help text and tests.
-export const rendererNames = Object.keys(renderers);
 
 /**
  * Parse render command arguments.

package/src/formatters/ansi.js

@@ -100,7 +100,7 @@ export function stripAnsi(value) {
  *     Coloured text, or the original text when colour is disabled.
  */
 function wrapColour(value, colour, options, createCode) {
-	const resolvedColour = resolveColourValue(colour);
+	const resolvedColour = resolveColourValue(colour, options);
 
 	if (options.colour !== true || resolvedColour === null) {
 		return value;
@@ -118,6 +118,14 @@ function wrapColour(value, colour, options, createCode) {
  *     ANSI foreground sequence.
  */
 function createForegroundCode(colour) {
+	if (colour === "default-foreground") {
+		return "\u001b[39m";
+	}
+
+	if (colour.startsWith("ansi-256:")) {
+		return `\u001b[38;5;${colour.slice("ansi-256:".length)}m`;
+	}
+
 	const { blue, green, red } = parseHexColour(colour);
 
 	return `\u001b[38;2;${red};${green};${blue}m`;
@@ -132,6 +140,14 @@ function createForegroundCode(colour) {
  *     ANSI background sequence.
  */
 function createBackgroundCode(colour) {
+	if (colour === "default-background") {
+		return "\u001b[49m";
+	}
+
+	if (colour.startsWith("ansi-256:")) {
+		return `\u001b[48;5;${colour.slice("ansi-256:".length)}m`;
+	}
+
 	const { blue, green, red } = parseHexColour(colour);
 
 	return `\u001b[48;2;${red};${green};${blue}m`;

package/src/gallery/render-gallery.js

@@ -4,6 +4,7 @@ import { commandResult } from "../patterns/command-result.js";
 import { compactDataTable } from "../patterns/compact-data-table.js";
 import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
+import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
 import { stripAnsi } from "../formatters/ansi.js";
@@ -14,6 +15,8 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { rowGroup } from "../primitives/row-group.js";
+import { sparkline } from "../primitives/sparkline.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
@@ -114,7 +117,7 @@ export const galleryVariants = ["current", "no-colour", "no-unicode", "plain"];
 // Gallery sections available for focused output.
 export const gallerySections = ["primitives", "patterns"];
 
-// Pattern fixtures available for focused output and interactive search.
+// Fixtures available for focused output and interactive search.
 export const galleryFixtures = [
 	"diagnostic-report",
 	"reporter",
@@ -126,6 +129,8 @@ export const galleryFixtures = [
 	"compact-data-table-narrow",
 	"confirmation-result",
 	"next-step-block",
+	"diff-block",
+	"sparkline",
 ];
 
 /**
@@ -178,7 +183,11 @@ function renderVariant(variant, options, request) {
 	const sections = [];
 
 	if (request.fixture !== undefined) {
-		sections.push(renderPatterns(resolvedVariant.options, request.fixture));
+		sections.push(
+			request.fixture === "sparkline"
+				? renderSparklineFixture(resolvedVariant.options)
+				: renderPatterns(resolvedVariant.options, request.fixture),
+		);
 	} else {
 		if (request.section === undefined || request.section === "primitives") {
 			sections.push(renderPrimitives(resolvedVariant.options));
@@ -433,6 +442,36 @@ function renderPatterns(options, fixture) {
 		options,
 	);
 
+	const diff = diffBlock(
+		{
+			lines: [
+				{
+					text: "render()",
+					type: "header",
+				},
+				{
+					newLineNumber: 102,
+					text: "return nextStep;",
+					type: "added",
+				},
+				{
+					oldLineNumber: 101,
+					text: "return currentStep;",
+					type: "removed",
+				},
+				{
+					newLineNumber: 100,
+					oldLineNumber: 100,
+					text: "const currentStep = getStep();",
+					type: "context",
+				},
+			],
+			path: "src/render.js",
+			title: "Renderer change",
+		},
+		options,
+	);
+
 	const reporter = createReporter(options);
 
 	reporter.divider("Project setup", "Claude + Codex");
@@ -560,6 +599,7 @@ function renderPatterns(options, fixture) {
 		"compact-data-table-narrow": ["Compact data table (narrow)", narrowCompactTable],
 		"confirmation-result": ["Confirmation result", confirmation],
 		"diagnostic-report": ["Diagnostic report", report],
+		"diff-block": ["Diff block", diff],
 		"next-step-block": ["Next-step block", nextStep],
 		reporter: ["Reporter", reporterOutput],
 		"task-summary": ["Task summary", summary],
@@ -593,6 +633,9 @@ function renderPatterns(options, fixture) {
 		"Audit finding",
 		frameExample(audit, options),
 		"",
+		"Diff block",
+		frameExample(diff, options),
+		"",
 		"Compact data table",
 		frameExample(compactTable, options),
 		"",
@@ -621,6 +664,18 @@ function renderPatternFixture(fixture, options) {
 	return [fixture[0], frameExample(fixture[1], options)].join("\n");
 }
 
+/**
+ * Render the focused sparkline fixture.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed sparkline fixture output.
+ */
+function renderSparklineFixture(options) {
+	return ["Sparkline", frameExample(renderSparklineExample(options), options)].join("\n");
+}
+
 /**
  * Add gallery-only framing around one rendered example.
  *
@@ -667,6 +722,9 @@ function renderPrimitives(options) {
 		"Bar charts",
 		renderBarChartExample(options),
 		"",
+		"Sparklines",
+		renderSparklineExample(options),
+		"",
 		"Tables",
 		renderTableExample(options),
 		"",
@@ -715,6 +773,30 @@ function renderPrimitives(options) {
 			labelWidth: 8,
 			result: resultTypes.FAILED,
 		}),
+		"",
+		"Row groups",
+		rowGroup({
+			...options,
+			rows: [
+				{
+					label: "Package",
+					value: "@lewishowles/components",
+				},
+				{
+					label: "Version",
+					value: "minor: 2.7.4 -> 2.8.0",
+				},
+				{
+					label: "Checks",
+					value: "type-check, unit, build",
+				},
+				{
+					label: "Bundle",
+					result: resultTypes.FAILED,
+					value: "is 22.3 KB, above the 12.0 KB budget",
+				},
+			],
+		}),
 	].join("\n");
 }
 
@@ -781,6 +863,55 @@ function renderBarChartExample(options) {
 	});
 }
 
+/**
+ * Render representative sparkline sequences.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Sparkline examples.
+ */
+function renderSparklineExample(options) {
+	const examples = [
+		{
+			label: "Rising",
+			tone: "success",
+			values: [1, 2, 3, 4, 5, 6],
+		},
+		{
+			label: "Falling",
+			tone: "danger",
+			values: [6, 5, 4, 3, 2, 1],
+		},
+		{
+			label: "Flat",
+			tone: "info",
+			values: [4, 4, 4, 4, 4, 4],
+		},
+		{
+			label: "Negative",
+			tone: "warning",
+			values: [-6, -4, -5, -2, -3, -1],
+		},
+		{
+			label: "Narrow mixed",
+			tone: "info",
+			values: [0, 10, -5, 5, 2, 8, -2],
+			width: 4,
+		},
+	];
+
+	return examples
+		.map((example) =>
+			sparkline({
+				...options,
+				...example,
+				width: example.width ?? 16,
+			}),
+		)
+		.join("\n");
+}
+
 /**
  * Render common progress values and tones.
  *