@lewishowles/cli-style 0.1.0

package/src/index.js

@@ -0,0 +1,52 @@
+export { createCliStyle, profiles } from "./create-cli-style.js";
+
+export { resolveProfile } from "./capability/resolve-profile.js";
+export { resolveTerminalCapabilities } from "./capability/terminal.js";
+export { isProfile } from "./profiles/profiles.js";
+
+export { renderHelp } from "./cli/help.js";
+export {
+	parseRenderRequest,
+	rendererNames,
+	renderJsonInput,
+} from "./cli/render-command.js";
+export {
+	galleryFixtures,
+	gallerySections,
+	galleryVariants,
+	renderGallery,
+} from "./gallery/render-gallery.js";
+
+export { background, foreground, stripAnsi, style } from "./formatters/ansi.js";
+export { agentTranscript } from "./patterns/agent-transcript.js";
+export { auditFinding } from "./patterns/audit-finding.js";
+export { commandResult } from "./patterns/command-result.js";
+export { compactDataTable } from "./patterns/compact-data-table.js";
+export { confirmationResult } from "./patterns/confirmation-result.js";
+export { diagnosticReport } from "./patterns/diagnostic-report.js";
+export { nextStepBlock } from "./patterns/next-step-block.js";
+export { taskSummary } from "./patterns/task-summary.js";
+export { barChart } from "./primitives/bar-chart.js";
+export { chip } from "./primitives/chip.js";
+export { divider } from "./primitives/divider.js";
+export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
+export { panel } from "./primitives/panel.js";
+export { progressBar } from "./primitives/progress-bar.js";
+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 {
+	chartColours,
+	chipColours,
+	colourTokens,
+	getColourToken,
+	getToneColour,
+	panelColours,
+	promptColours,
+	resolveColourValue,
+	tableColours,
+	terminalColours,
+	toneColours,
+} from "./theme/colours.js";
+export { getResultSymbol, getResultToken, resultTokens, resultTypes } from "./theme/results.js";

package/src/patterns/agent-transcript.js

@@ -0,0 +1,180 @@
+import { profiles } from "../profiles/profiles.js";
+import { chip } from "../primitives/chip.js";
+import {
+	isNonEmptyString,
+	isRecord,
+	normaliseStringList,
+	renderTitle,
+} from "./helpers.js";
+
+// Transcript roles map machine-facing values to stable textual labels and tones.
+const transcriptRoles = {
+	agent: {
+		label: "Agent",
+		tone: "agent",
+	},
+	system: {
+		label: "System",
+		tone: "neutral",
+	},
+	tool: {
+		label: "Tool",
+		tone: "info",
+	},
+	user: {
+		label: "User",
+		tone: "user",
+	},
+};
+
+// Unsupported roles remain visible without inventing new semantics.
+const fallbackRole = {
+	label: "Participant",
+	tone: "neutral",
+};
+
+// Agent transcripts use a stable title when the caller does not provide one.
+const defaultTitle = "Agent transcript";
+
+/**
+ * Render role-labelled agent exchanges and tool output.
+ *
+ * @param  {object}  transcript
+ *     Structured transcript.
+ * @param  {object[]}  transcript.entries
+ *     Role-labelled transcript entries.
+ * @param  {string}  transcript.title
+ *     Transcript title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered transcript.
+ */
+export function agentTranscript(transcript, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return transcript;
+	}
+
+	if (!isRecord(transcript)) {
+		return "";
+	}
+
+	const entries = normaliseEntries(transcript.entries);
+	const title = isNonEmptyString(transcript.title) ? transcript.title : defaultTitle;
+
+	if (entries.length === 0) {
+		return renderTitle(title, options);
+	}
+
+	return [
+		renderTitle(title, options),
+		...entries.map((entry) => renderEntry(entry, options)),
+	].join("\n\n");
+}
+
+/**
+ * Return transcript entries with usable content.
+ *
+ * @param  {*}  entries
+ *     Entries to normalise.
+ * @returns  {object[]}
+ *     Valid transcript entries.
+ */
+function normaliseEntries(entries) {
+	if (!Array.isArray(entries)) {
+		return [];
+	}
+
+	return entries
+		.filter(isRecord)
+		.map((entry) => ({
+			...entry,
+			content: normaliseContent(entry.content),
+		}))
+		.filter((entry) => entry.content.length > 0);
+}
+
+/**
+ * Return transcript content as non-empty lines.
+ *
+ * @param  {*}  content
+ *     Entry content.
+ * @returns  {string[]}
+ *     Content lines.
+ */
+function normaliseContent(content) {
+	if (isNonEmptyString(content)) {
+		return content.split("\n").filter(isNonEmptyString);
+	}
+
+	return normaliseStringList(content);
+}
+
+/**
+ * Render one transcript entry for the active profile.
+ *
+ * @param  {object}  entry
+ *     Transcript entry.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered transcript entry.
+ */
+function renderEntry(entry, options) {
+	const role = transcriptRoles[entry.role] ?? fallbackRole;
+	const label = formatRoleLabel(role.label, entry.name);
+
+	if (options.profile === profiles.AGENT) {
+		return renderAgentEntry(label, entry.content, entry.role);
+	}
+
+	const renderedLabel = chip(label, role.tone, options);
+
+	if (entry.content.length === 1) {
+		return `${renderedLabel} ${entry.content[0]}`;
+	}
+
+	return [
+		renderedLabel,
+		...entry.content.map((line) => `  ${line}`),
+	].join("\n");
+}
+
+/**
+ * Render one Markdown transcript entry.
+ *
+ * @param  {string}  label
+ *     Entry role label.
+ * @param  {string[]}  content
+ *     Entry content lines.
+ * @param  {string}  role
+ *     Machine-facing entry role.
+ * @returns  {string}
+ *     Markdown transcript entry.
+ */
+function renderAgentEntry(label, content, role) {
+	if (role === "tool") {
+		return [
+			`## ${label}`,
+			"```text",
+			...content,
+			"```",
+		].join("\n");
+	}
+
+	return [`## ${label}`, ...content].join("\n");
+}
+
+/**
+ * Add a source name to a role label when provided.
+ *
+ * @param  {string}  label
+ *     Base role label.
+ * @param  {*}  name
+ *     Optional source name.
+ * @returns  {string}
+ *     Complete role label.
+ */
+function formatRoleLabel(label, name) {
+	return isNonEmptyString(name) ? `${label}: ${name}` : label;
+}

package/src/patterns/audit-finding.js

@@ -0,0 +1,107 @@
+import { profiles } from "../profiles/profiles.js";
+import { row } from "../primitives/row.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+import {
+	isNonEmptyString,
+	isRecord,
+	normaliseStringList,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Audit findings use a stable title when the caller does not provide one.
+const defaultTitle = "Audit finding";
+
+/**
+ * Render one audit finding with evidence and remediation guidance.
+ *
+ * @param  {object}  finding
+ *     Structured audit finding.
+ * @param  {string[]}  finding.evidence
+ *     Evidence supporting the finding.
+ * @param  {string}  finding.finding
+ *     Finding summary.
+ * @param  {string}  finding.location
+ *     Source location or affected area.
+ * @param  {string}  finding.recommendation
+ *     Recommended remediation.
+ * @param  {string[]}  finding.references
+ *     Supporting standards or documentation.
+ * @param  {string}  finding.result
+ *     Semantic severity state.
+ * @param  {string}  finding.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered audit finding.
+ */
+export function auditFinding(finding, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return finding;
+	}
+
+	if (!isRecord(finding)) {
+		return "";
+	}
+
+	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 sections = [
+		status(finding.result ?? resultTypes.UNKNOWN, summary, options),
+		renderLocation(finding.location, options),
+		renderSection("Evidence", evidence, options, false),
+		renderTextSection("Recommendation", finding.recommendation, options),
+		renderSection("References", references, options, false),
+	].filter((section) => section !== "");
+
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}
+
+/**
+ * Render the finding location for the active profile.
+ *
+ * @param  {*}  location
+ *     Finding location.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered location.
+ */
+function renderLocation(location, options) {
+	if (!isNonEmptyString(location)) {
+		return "";
+	}
+
+	if (options.profile === profiles.AGENT) {
+		return renderSection("Location", [location], options, false);
+	}
+
+	return row("Location", location, {
+		...options,
+		labelWidth: 8,
+	});
+}
+
+/**
+ * Render a section containing one text value.
+ *
+ * @param  {string}  title
+ *     Section title.
+ * @param  {*}  value
+ *     Section content.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered text section.
+ */
+function renderTextSection(title, value, options) {
+	if (!isNonEmptyString(value)) {
+		return "";
+	}
+
+	return renderSection(title, [value], options, false);
+}

package/src/patterns/command-result.js

@@ -0,0 +1,91 @@
+import { profiles } from "../profiles/profiles.js";
+import { row } from "../primitives/row.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+import {
+	isNonEmptyString,
+	isRecord,
+	normaliseStringList,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Command results use a stable title when the caller does not provide one.
+const defaultTitle = "Command result";
+
+/**
+ * Render one command outcome with metadata and supporting details.
+ *
+ * @param  {object}  result
+ *     Structured command result.
+ * @param  {string}  result.command
+ *     Executed command.
+ * @param  {string[]}  result.details
+ *     Supporting result details.
+ * @param  {string}  result.duration
+ *     Human-readable command duration.
+ * @param  {number}  result.exitCode
+ *     Command exit code.
+ * @param  {string}  result.result
+ *     Semantic result state.
+ * @param  {string}  result.summary
+ *     Short outcome summary.
+ * @param  {string}  result.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered command result.
+ */
+export function commandResult(result, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return result;
+	}
+
+	if (!isRecord(result)) {
+		return "";
+	}
+
+	const title = isNonEmptyString(result.title) ? result.title : defaultTitle;
+	const metadata = renderMetadata(result, options);
+	const details = normaliseStringList(result.details).map((detail) => `- ${detail}`);
+	const summary = isNonEmptyString(result.summary) ? result.summary : "";
+	const sections = [
+		status(result.result ?? resultTypes.UNKNOWN, summary, options),
+		metadata,
+		renderSection("Details", details, options, false),
+	].filter((section) => section !== "");
+
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}
+
+/**
+ * Render command metadata for human or agent output.
+ *
+ * @param  {object}  result
+ *     Structured command result.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered metadata.
+ */
+function renderMetadata(result, options) {
+	const entries = [
+		isNonEmptyString(result.command) ? ["Command", result.command] : null,
+		Number.isInteger(result.exitCode) ? ["Exit code", String(result.exitCode)] : null,
+		isNonEmptyString(result.duration) ? ["Duration", result.duration] : null,
+	].filter((entry) => entry !== null);
+
+	if (options.profile === profiles.AGENT) {
+		const lines = entries.map(([label, value]) => `- ${label}: ${value}`);
+
+		return renderSection("Metadata", lines, options, false);
+	}
+
+	return entries
+		.map(([label, value]) => row(label, value, {
+			...options,
+			labelWidth: 9,
+		}))
+		.join("\n");
+}

package/src/patterns/compact-data-table.js

@@ -0,0 +1,67 @@
+import { profiles } from "../profiles/profiles.js";
+import { table } from "../primitives/table.js";
+import {
+	isNonEmptyString,
+	isRecord,
+	renderTitle,
+} from "./helpers.js";
+
+// Compact data tables use a stable title when the caller does not provide one.
+const defaultTitle = "Data";
+
+/**
+ * Render dense records with optional summary context.
+ *
+ * @param  {object}  data
+ *     Structured table data.
+ * @param  {object[]}  data.columns
+ *     Table column keys and labels.
+ * @param  {object[]}  data.rows
+ *     Table records.
+ * @param  {string}  data.summary
+ *     Optional summary context.
+ * @param  {string}  data.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered compact table.
+ */
+export function compactDataTable(data, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return data;
+	}
+
+	if (!isRecord(data) || !hasEntries(data.columns) || !hasEntries(data.rows)) {
+		return "";
+	}
+
+	const title = isNonEmptyString(data.title) ? data.title : defaultTitle;
+	const summary = isNonEmptyString(data.summary) ? data.summary : "";
+	const renderedTable = table({
+		...options,
+		columns: data.columns,
+		rows: data.rows,
+	});
+	const heading = summary === ""
+		? renderTitle(title, options)
+		: [renderTitle(title, options), summary].join("\n");
+
+	if (renderedTable === "") {
+		return "";
+	}
+
+	return [heading, renderedTable].join("\n\n");
+}
+
+/**
+ * Check whether a value is a non-empty array.
+ *
+ * @param  {*}  value
+ *     Value to check.
+ * @returns  {boolean}
+ *     Whether the value contains entries.
+ */
+function hasEntries(value) {
+	return Array.isArray(value) && value.length > 0;
+}

package/src/patterns/confirmation-result.js

@@ -0,0 +1,88 @@
+import { profiles } from "../profiles/profiles.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+import {
+	formatLabel,
+	isNonEmptyString,
+	isRecord,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Confirmation states map workflow outcomes onto shared result semantics.
+const confirmationStates = {
+	cancelled: {
+		label: "Cancelled",
+		result: resultTypes.SKIPPED,
+	},
+	confirmed: {
+		label: "Confirmed",
+		result: resultTypes.SUCCESS,
+	},
+	declined: {
+		label: "Declined",
+		result: resultTypes.WARNING,
+	},
+	failed: {
+		label: "Failed",
+		result: resultTypes.FAILED,
+	},
+};
+
+// Unsupported confirmation states remain visibly unknown.
+const fallbackState = {
+	label: "Unknown",
+	result: resultTypes.UNKNOWN,
+};
+
+// Confirmation results use a stable title when the caller does not provide one.
+const defaultTitle = "Confirmation result";
+
+/**
+ * Render one confirmation workflow outcome.
+ *
+ * @param  {object}  confirmation
+ *     Structured confirmation result.
+ * @param  {string}  confirmation.action
+ *     Action requested or completed.
+ * @param  {string}  confirmation.detail
+ *     Supporting outcome detail.
+ * @param  {string}  confirmation.item
+ *     Affected item.
+ * @param  {string}  confirmation.state
+ *     Confirmation state.
+ * @param  {string}  confirmation.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered confirmation result.
+ */
+export function confirmationResult(confirmation, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return confirmation;
+	}
+
+	if (!isRecord(confirmation)) {
+		return "";
+	}
+
+	const title = isNonEmptyString(confirmation.title)
+		? confirmation.title
+		: defaultTitle;
+	const action = isNonEmptyString(confirmation.action) ? confirmation.action : "";
+	const summary = formatLabel(action, confirmation.item, options);
+	const state = confirmationStates[confirmation.state] ?? fallbackState;
+	const detail = isNonEmptyString(confirmation.detail)
+		? renderSection("Detail", [confirmation.detail], options, false)
+		: "";
+	const sections = [
+		status(state.result, summary, {
+			...options,
+			label: state.label,
+		}),
+		detail,
+	].filter((section) => section !== "");
+
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}