@lewishowles/cli-style 0.1.0

package/src/primitives/table.js

@@ -0,0 +1,239 @@
+import { foreground } from "../formatters/ansi.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 = "  ";
+
+/**
+ * Render tabular data with a narrow-width key/value fallback.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {object[]}  options.columns
+ *     Column keys and labels.
+ * @param  {object[]}  options.rows
+ *     Table records.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode rule characters should be used.
+ * @param  {number}  options.width
+ *     Available output width.
+ * @returns  {string}
+ *     Rendered table.
+ */
+export function table(options = {}) {
+	const columns = normaliseColumns(options.columns);
+	const rows = normaliseRows(options.rows);
+
+	if (columns.length === 0 || rows.length === 0) {
+		return "";
+	}
+
+	const widths = columnWidths(columns, rows);
+	const naturalWidth = widths.reduce((total, width) => total + width, 0)
+		+ (columnSeparator.length * (columns.length - 1));
+	const availableWidth = Number.isFinite(options.width) ? options.width : defaultWidth;
+
+	if (naturalWidth > availableWidth) {
+		return renderBlocks(columns, rows, options);
+	}
+
+	return renderTable(columns, rows, widths, options);
+}
+
+/**
+ * Return columns with usable keys and labels.
+ *
+ * @param  {object[]}  columns
+ *     Requested columns.
+ * @returns  {object[]}
+ *     Valid columns.
+ */
+function normaliseColumns(columns) {
+	if (!Array.isArray(columns)) {
+		return [];
+	}
+
+	return columns.filter((column) => (
+		column !== null
+		&& typeof column === "object"
+		&& typeof column.key === "string"
+		&& column.key !== ""
+		&& typeof column.label === "string"
+		&& column.label !== ""
+	));
+}
+
+/**
+ * Return object records suitable for rendering.
+ *
+ * @param  {object[]}  rows
+ *     Requested rows.
+ * @returns  {object[]}
+ *     Valid rows.
+ */
+function normaliseRows(rows) {
+	if (!Array.isArray(rows)) {
+		return [];
+	}
+
+	return rows.filter((row) => row !== null && typeof row === "object");
+}
+
+/**
+ * Calculate the display width of each column.
+ *
+ * @param  {object[]}  columns
+ *     Table columns.
+ * @param  {object[]}  rows
+ *     Table records.
+ * @returns  {number[]}
+ *     Column widths.
+ */
+function columnWidths(columns, rows) {
+	return columns.map((column) => Math.max(
+		column.label.length,
+		...rows.map((row) => cellValue(row[column.key]).length),
+	));
+}
+
+/**
+ * Render a wide aligned table.
+ *
+ * @param  {object[]}  columns
+ *     Table columns.
+ * @param  {object[]}  rows
+ *     Table records.
+ * @param  {number[]}  widths
+ *     Column widths.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered table.
+ */
+function renderTable(columns, rows, widths, options) {
+	const header = columns
+		.map((column, index) => renderHeader(
+			padColumn(column.label, widths[index], index, columns.length),
+			options,
+		))
+		.join(columnSeparator);
+	const ruleCharacter = options.unicode === false ? "-" : "─";
+	const rule = widths
+		.map((width) => ruleCharacter.repeat(width))
+		.join(columnSeparator);
+	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));
+
+	return [header, renderedRule, ...body].join("\n");
+}
+
+/**
+ * Pad columns except the final visible value.
+ *
+ * @param  {string}  value
+ *     Column text.
+ * @param  {number}  width
+ *     Calculated column width.
+ * @param  {number}  index
+ *     Zero-based column position.
+ * @param  {number}  columnCount
+ *     Total visible columns.
+ * @returns  {string}
+ *     Padded column text.
+ */
+function padColumn(value, width, index, columnCount) {
+	return index === columnCount - 1 ? value : value.padEnd(width, " ");
+}
+
+/**
+ * Render records as separated key/value blocks.
+ *
+ * @param  {object[]}  columns
+ *     Table columns.
+ * @param  {object[]}  rows
+ *     Table records.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered key/value blocks.
+ */
+function renderBlocks(columns, rows, options) {
+	const labelWidth = Math.max(...columns.map((column) => column.label.length));
+
+	return rows.map((row) => columns
+		.map((column) => {
+			const label = renderHeader(column.label.padEnd(labelWidth, " "), options);
+			const value = renderCell(cellValue(row[column.key]), 0, options);
+
+			return `${label}${columnSeparator}${value}`;
+		})
+		.join("\n"))
+		.join("\n\n");
+}
+
+/**
+ * Convert a cell value to display text.
+ *
+ * @param  {*}  value
+ *     Cell value.
+ * @returns  {string}
+ *     Display text.
+ */
+function cellValue(value) {
+	return value === null || value === undefined ? "" : String(value);
+}
+
+/**
+ * Render table header text.
+ *
+ * @param  {string}  value
+ *     Header text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered header.
+ */
+function renderHeader(value, options) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	return foreground(value, tableColours.header, options);
+}
+
+/**
+ * Render table cell text.
+ *
+ * @param  {string}  value
+ *     Cell text.
+ * @param  {number}  columnIndex
+ *     Zero-based column position.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered cell.
+ */
+function renderCell(value, columnIndex, options) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	const colour = columnIndex === 0
+		? tableColours.primaryText
+		: tableColours.secondaryText;
+
+	return foreground(value, colour, options);
+}

package/src/profiles/profiles.js

@@ -0,0 +1,24 @@
+// Supported output profiles for terminal rendering.
+export const profiles = {
+	AGENT: "agent",
+	CI: "ci",
+	DIAGNOSTIC: "diagnostic",
+	HUMAN: "human",
+	JSON: "json",
+	PLAIN: "plain",
+};
+
+// Profile names accepted by public APIs and CLI flags.
+const profileValues = new Set(Object.values(profiles));
+
+/**
+ * Check whether a profile name is supported.
+ *
+ * @param  {string}  profile
+ *     Profile name to check.
+ * @returns  {boolean}
+ *     Whether the profile is supported.
+ */
+export function isProfile(profile) {
+	return profileValues.has(profile);
+}

package/src/theme/colours.js

@@ -0,0 +1,141 @@
+// Semantic colour tokens for terminal output and generated previews.
+export const colourTokens = {
+	accent: "#c58cff",
+	background: "#070b0d",
+	border: "#2a3a42",
+	danger: "#ff7272",
+	info: "#8bbdff",
+	muted: "#94a3aa",
+	success: "#8fdf72",
+	surface: "#0f181b",
+	surfaceRaised: "#132024",
+	text: "#e8eef0",
+	warning: "#f4bd5f",
+};
+
+// Terminal frame colours for gallery-style previews.
+export const terminalColours = {
+	background: "background",
+	border: "border",
+	title: "muted",
+	trafficLights: {
+		close: "#ff7272",
+		minimise: "#f4bd5f",
+		zoom: "#8fdf72",
+	},
+};
+
+// Chip and pill colour pairs for speaker labels and compact states.
+export const chipColours = {
+	agent: {
+		background: "#3a2815",
+		foreground: "warning",
+	},
+	danger: {
+		background: "#3c1d22",
+		foreground: "danger",
+	},
+	info: {
+		background: "#14273b",
+		foreground: "info",
+	},
+	neutral: {
+		background: "#172126",
+		foreground: "muted",
+	},
+	success: {
+		background: "#18351f",
+		foreground: "success",
+	},
+	user: {
+		background: "#1f3b1f",
+		foreground: "success",
+	},
+	warning: {
+		background: "#3a2815",
+		foreground: "warning",
+	},
+};
+
+// Panel colours for grouped reports and agent responses.
+export const panelColours = {
+	background: "surface",
+	border: "border",
+	danger: "danger",
+	info: "info",
+	success: "success",
+	warning: "warning",
+};
+
+// Table colours for dense operational data.
+export const tableColours = {
+	border: "border",
+	header: "muted",
+	primaryText: "text",
+	secondaryText: "muted",
+};
+
+// Chart colours for simple bars and positive/negative trend segments.
+export const chartColours = {
+	barNegative: "#c48745",
+	barPositive: "success",
+	barWarning: "warning",
+	label: "muted",
+	value: "text",
+};
+
+// Prompt colours for lightweight interactive flows.
+export const promptColours = {
+	active: "success",
+	inactive: "text",
+	marker: "success",
+};
+
+// Result tones map semantic outcomes onto colour token names.
+export const toneColours = {
+	danger: "danger",
+	info: "info",
+	muted: "muted",
+	success: "success",
+	warning: "warning",
+};
+
+/**
+ * Resolve a colour token by name.
+ *
+ * @param  {string}  colourName
+ *     Colour token name.
+ * @returns  {string|null}
+ *     Hex colour value when supported.
+ */
+export function getColourToken(colourName) {
+	return colourTokens[colourName] ?? null;
+}
+
+/**
+ * Resolve a tone to a colour token value.
+ *
+ * @param  {string}  tone
+ *     Tone name to resolve.
+ * @returns  {string|null}
+ *     Hex colour value when supported.
+ */
+export function getToneColour(tone) {
+	return getColourToken(toneColours[tone]);
+}
+
+/**
+ * Resolve a direct hex colour or colour token reference.
+ *
+ * @param  {string}  colour
+ *     Hex colour value or colour token name.
+ * @returns  {string|null}
+ *     Hex colour value when supported.
+ */
+export function resolveColourValue(colour) {
+	if (colour?.startsWith("#")) {
+		return colour;
+	}
+
+	return getColourToken(colour);
+}

package/src/theme/results.js

@@ -0,0 +1,98 @@
+// Result states shared by primitive and pattern renderers.
+export const resultTypes = {
+	FAILED: "failed",
+	PARTIAL: "partial",
+	SKIPPED: "skipped",
+	SUCCESS: "success",
+	UNKNOWN: "unknown",
+	WARNING: "warning",
+};
+
+// Display tokens for result states before colour rendering exists.
+export const resultTokens = {
+	[resultTypes.FAILED]: {
+		exitCode: 1,
+		label: "Failed",
+		symbols: {
+			ascii: "x",
+			unicode: "×",
+		},
+		tone: "danger",
+	},
+	[resultTypes.PARTIAL]: {
+		exitCode: null,
+		label: "Partial",
+		symbols: {
+			ascii: "!",
+			unicode: "◐",
+		},
+		tone: "warning",
+	},
+	[resultTypes.SKIPPED]: {
+		exitCode: null,
+		label: "Skipped",
+		symbols: {
+			ascii: "-",
+			unicode: "–",
+		},
+		tone: "muted",
+	},
+	[resultTypes.SUCCESS]: {
+		exitCode: 0,
+		label: "Success",
+		symbols: {
+			ascii: "OK",
+			unicode: "✓",
+		},
+		tone: "success",
+	},
+	[resultTypes.UNKNOWN]: {
+		exitCode: null,
+		label: "Unknown",
+		symbols: {
+			ascii: "?",
+			unicode: "?",
+		},
+		tone: "muted",
+	},
+	[resultTypes.WARNING]: {
+		exitCode: null,
+		label: "Warning",
+		symbols: {
+			ascii: "!",
+			unicode: "⚠",
+		},
+		tone: "warning",
+	},
+};
+
+/**
+ * Resolve the token for a result type.
+ *
+ * @param  {string}  resultType
+ *     Result type to resolve.
+ * @returns  {object}
+ *     Matching result token, or the unknown token for unsupported values.
+ */
+export function getResultToken(resultType) {
+	return resultTokens[resultType] ?? resultTokens[resultTypes.UNKNOWN];
+}
+
+/**
+ * Resolve the display symbol for a result type.
+ *
+ * @param  {string}  resultType
+ *     Result type to resolve.
+ * @param  {object}  options
+ *     Symbol rendering options.
+ * @param  {boolean}  options.unicode
+ *     Whether to return the Unicode symbol.
+ * @returns  {string}
+ *     Display symbol for the requested symbol mode.
+ */
+export function getResultSymbol(resultType, options = {}) {
+	const token = getResultToken(resultType);
+	const usesUnicode = options.unicode ?? true;
+
+	return usesUnicode ? token.symbols.unicode : token.symbols.ascii;
+}