@lewishowles/cli-style 0.1.0

package/src/capability/terminal.js

@@ -0,0 +1,105 @@
+// Default terminal width when no stream width is available.
+const defaultWidth = 80;
+
+/**
+ * Resolve terminal output capabilities from injected args, env, and stream data.
+ *
+ * @param  {object}  options
+ *     Terminal capability inputs.
+ * @param  {string[]}  options.argv
+ *     CLI arguments to inspect.
+ * @param  {object}  options.env
+ *     Environment values to inspect.
+ * @param  {object}  options.stdout
+ *     Stream-like object with `isTTY` and `columns`.
+ * @returns  {object}
+ *     Resolved terminal capabilities.
+ */
+export function resolveTerminalCapabilities(options = {}) {
+	const argv = options.argv ?? [];
+	const env = options.env ?? {};
+	const stdout = options.stdout ?? {};
+
+	const isTty = stdout.isTTY === true;
+	const isCi = env.CI === "true" || env.CI === "1";
+	const isDumb = env.TERM === "dumb";
+	const width = resolveWidth(stdout.columns);
+	const usesPlain = argv.includes("--plain");
+
+	const colour = resolveColour({
+		argv,
+		env,
+		isDumb,
+		isTty,
+		usesPlain,
+	});
+
+	const unicode = resolveUnicode({
+		argv,
+		isDumb,
+		usesPlain,
+	});
+
+	return {
+		colour,
+		isCi,
+		isDumb,
+		isTty,
+		unicode,
+		width,
+	};
+}
+
+/**
+ * Resolve colour support from explicit flags and terminal state.
+ *
+ * @param  {object}  options
+ *     Colour resolution inputs.
+ * @returns  {boolean}
+ *     Whether coloured output should be used.
+ */
+function resolveColour(options) {
+	if (
+		options.usesPlain ||
+		options.argv.includes("--no-colour") ||
+		options.argv.includes("--no-color") ||
+		options.env.NO_COLOR !== undefined ||
+		options.isDumb
+	) {
+		return false;
+	}
+
+	return options.isTty;
+}
+
+/**
+ * Resolve Unicode support from explicit flags and terminal state.
+ *
+ * @param  {object}  options
+ *     Unicode resolution inputs.
+ * @returns  {boolean}
+ *     Whether Unicode symbols should be used.
+ */
+function resolveUnicode(options) {
+	if (options.usesPlain || options.argv.includes("--no-unicode") || options.isDumb) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Resolve terminal width with a stable fallback.
+ *
+ * @param  {number}  width
+ *     Stream-reported column count.
+ * @returns  {number}
+ *     Usable terminal width.
+ */
+function resolveWidth(width) {
+	if (Number.isInteger(width) && width > 0) {
+		return width;
+	}
+
+	return defaultWidth;
+}

package/src/cli/gallery-command.js

@@ -0,0 +1,238 @@
+import { spawnSync } from "node:child_process";
+
+import {
+	galleryFixtures,
+	gallerySections,
+	galleryVariants,
+} from "../gallery/render-gallery.js";
+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",
+]);
+
+/**
+ * Parse gallery command arguments.
+ *
+ * @param  {string[]}  args
+ *     Arguments after the gallery command.
+ * @returns  {object}
+ *     Gallery rendering request.
+ */
+export function parseGalleryRequest(args = []) {
+	let hasVariant = false;
+	const request = {
+		fixture: undefined,
+		interactive: false,
+		section: undefined,
+		variant: "current",
+		variants: false,
+		width: undefined,
+	};
+
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+
+		if (argument === "--variants" || argument === "--matrix") {
+			request.variants = true;
+		} else if (argument === "--interactive") {
+			request.interactive = true;
+		} else if (argument === "--section") {
+			request.section = readOptionValue(args, index, argument);
+			index += 1;
+		} else if (argument === "--fixture") {
+			request.fixture = readOptionValue(args, index, argument);
+			index += 1;
+		} else if (argument === "--profile") {
+			validateGalleryProfile(readOptionValue(args, index, argument));
+			index += 1;
+		} else if (argument.startsWith("--profile=")) {
+			validateGalleryProfile(readInlineOptionValue(argument, "--profile"));
+		} else if (argument === "--width") {
+			request.width = readWidthValue(readOptionValue(args, index, argument));
+			index += 1;
+		} else if (argument.startsWith("--width=")) {
+			request.width = readWidthValue(readInlineOptionValue(argument, "--width"));
+		} else if (argument === "--json") {
+			throw new Error("Gallery does not support json output");
+		} else if (globalRenderingFlags.has(argument)) {
+			// Accepted here because createCliStyle() has already resolved these flags.
+		} else if (argument.startsWith("-")) {
+			throw new Error(`Unknown gallery option: ${argument}`);
+		} else if (hasVariant) {
+			throw new Error(`Unexpected gallery argument: ${argument}`);
+		} else {
+			request.variant = argument;
+			hasVariant = true;
+		}
+	}
+
+	validateRequest(request);
+
+	return request;
+}
+
+/**
+ * Select a gallery section or fixture through fzf when available.
+ *
+ * @param  {object}  request
+ *     Parsed gallery request.
+ * @returns  {object}
+ *     Selected or unchanged request.
+ */
+export function selectInteractiveGalleryRequest(request) {
+	if (request.interactive !== true || !hasFzf()) {
+		return {
+			...request,
+			interactive: false,
+		};
+	}
+
+	const choices = [
+		...gallerySections.map((section) => `section:${section}`),
+		...galleryFixtures.map((fixture) => `fixture:${fixture}`),
+	];
+	const selection = spawnSync("fzf", [
+		"--height=60%",
+		"--layout=reverse",
+		"--prompt=Gallery > ",
+	], {
+		encoding: "utf8",
+		input: choices.join("\n"),
+		stdio: ["pipe", "pipe", "inherit"],
+	});
+	const value = selection.status === 0 ? selection.stdout.trim() : "";
+
+	if (value === "") {
+		return {
+			...request,
+			interactive: false,
+		};
+	}
+
+	const [type, name] = value.split(":");
+
+	return {
+		...request,
+		fixture: type === "fixture" ? name : undefined,
+		interactive: false,
+		section: type === "section" ? name : undefined,
+	};
+}
+
+/**
+ * Read a required inline option value.
+ *
+ * @param  {string}  argument
+ *     Full `--option=value` argument.
+ * @param  {string}  option
+ *     Option name.
+ * @returns  {string}
+ *     Option value.
+ */
+function readInlineOptionValue(argument, option) {
+	const value = argument.slice(`${option}=`.length);
+
+	if (value === "") {
+		throw new Error(`Missing value for ${option}`);
+	}
+
+	return value;
+}
+
+/**
+ * Read a required option value.
+ *
+ * @param  {string[]}  args
+ *     Command arguments.
+ * @param  {number}  index
+ *     Option index.
+ * @param  {string}  option
+ *     Option name.
+ * @returns  {string}
+ *     Option value.
+ */
+function readOptionValue(args, index, option) {
+	const value = args[index + 1];
+
+	if (value === undefined || value.startsWith("-")) {
+		throw new Error(`Missing value for ${option}`);
+	}
+
+	return value;
+}
+
+/**
+ * Validate a gallery text profile.
+ *
+ * @param  {string}  profile
+ *     Requested output profile.
+ * @returns  {void}
+ */
+function validateGalleryProfile(profile) {
+	if (!isProfile(profile)) {
+		throw new Error(`Unknown profile: ${profile}`);
+	}
+
+	if (profile === profiles.JSON) {
+		throw new Error("Gallery does not support json output");
+	}
+}
+
+/**
+ * Parse a gallery width option.
+ *
+ * @param  {string}  value
+ *     Width argument value.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function readWidthValue(value) {
+	const width = Number(value);
+
+	if (!Number.isInteger(width) || width <= 0) {
+		throw new Error("Gallery width must be a positive integer");
+	}
+
+	return width;
+}
+
+/**
+ * Validate gallery request values.
+ *
+ * @param  {object}  request
+ *     Parsed gallery request.
+ * @returns  {void}
+ */
+function validateRequest(request) {
+	if (!galleryVariants.includes(request.variant)) {
+		throw new Error(`Unknown gallery variant: ${request.variant}`);
+	}
+
+	if (request.section !== undefined && !gallerySections.includes(request.section)) {
+		throw new Error(`Unknown gallery section: ${request.section}`);
+	}
+
+	if (request.fixture !== undefined && !galleryFixtures.includes(request.fixture)) {
+		throw new Error(`Unknown gallery fixture: ${request.fixture}`);
+	}
+}
+
+/**
+ * Check whether the optional fzf binary is available.
+ *
+ * @returns  {boolean}
+ *     Whether fzf can be invoked.
+ */
+function hasFzf() {
+	const result = spawnSync("fzf", ["--version"], {
+		encoding: "utf8",
+		stdio: "ignore",
+	});
+
+	return result.status === 0;
+}

package/src/cli/help.js

@@ -0,0 +1,35 @@
+// Help text for the package binary.
+const helpLines = [
+	"cli-style",
+	"",
+	"Usage:",
+	"  cli-style --help",
+	"  cli-style gallery [variant] [options]",
+	"  cli-style render <renderer> [options] < input.json",
+	"",
+	"Commands:",
+	"  gallery    Print the read-only style gallery.",
+	"  render     Render caller-provided JSON from stdin.",
+	"",
+	"Gallery variants:",
+	"  current, no-colour, no-unicode, plain",
+	"",
+	"Options:",
+	"  --section <name>    Show primitives or patterns.",
+	"  --fixture <name>    Show one named pattern fixture.",
+	"  --profile <name>    Render with a text profile.",
+	"  --width <columns>   Render with a fixed terminal width.",
+	"  --interactive       Select a section or fixture with fzf when available.",
+	"  --variants          Show every capability variant.",
+	"  -h, --help          Show this help.",
+];
+
+/**
+ * Render command help text.
+ *
+ * @returns  {string}
+ *     CLI help output.
+ */
+export function renderHelp() {
+	return helpLines.join("\n");
+}

package/src/cli/render-command.js

@@ -0,0 +1,283 @@
+import { agentTranscript } from "../patterns/agent-transcript.js";
+import { auditFinding } from "../patterns/audit-finding.js";
+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 { nextStepBlock } from "../patterns/next-step-block.js";
+import { taskSummary } from "../patterns/task-summary.js";
+import { barChart } from "../primitives/bar-chart.js";
+import { chip } from "../primitives/chip.js";
+import { divider } from "../primitives/divider.js";
+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 { 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";
+
+// Renderer names accepted by the custom-input render command.
+const renderers = {
+	"agent-transcript": (input, options) => agentTranscript(input, options),
+	"audit-finding": (input, options) => auditFinding(input, options),
+	"bar-chart": (input, options) => barChart({
+		...input,
+		...options,
+	}),
+	chip: (input, options) => chip(input.label, input.tone, {
+		...input,
+		...options,
+	}),
+	"command-result": (input, options) => commandResult(input, options),
+	"compact-data-table": (input, options) => compactDataTable(input, options),
+	"confirmation-result": (input, options) => confirmationResult(input, options),
+	"diagnostic-report": (input, options) => diagnosticReport(input, options),
+	divider: (input, options) => divider({
+		...input,
+		...options,
+	}),
+	"empty-state": (input, options) => emptyState(input.title, input.detail, {
+		...input,
+		...options,
+	}),
+	"error-block": (input, options) => errorBlock(input.title, input.lines, {
+		...input,
+		...options,
+	}),
+	hint: (input, options) => hint(input.message, {
+		...input,
+		...options,
+	}),
+	"next-step-block": (input, options) => nextStepBlock(input, options),
+	panel: (input, options) => panel({
+		...input,
+		...options,
+	}),
+	"progress-bar": (input, options) => progressBar({
+		...input,
+		...options,
+	}),
+	row: (input, options) => row(input.label, input.value, {
+		...input,
+		...options,
+	}),
+	status: (input, options) => status(input.type, input.detail, {
+		...input,
+		...options,
+	}),
+	step: (input, options) => step(input.label, input.state, {
+		...input,
+		...options,
+	}),
+	"step-progress": (input, options) => stepProgress({
+		...input,
+		...options,
+	}),
+	table: (input, options) => table({
+		...input,
+		...options,
+	}),
+	"task-summary": (input, options) => taskSummary(input, options),
+};
+
+// Global rendering flags accepted after `render <renderer>`.
+const globalRenderingFlags = new Set([
+	"--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.
+ *
+ * @param  {string[]}  args
+ *     Arguments after the render command.
+ * @returns  {object}
+ *     Render request.
+ */
+export function parseRenderRequest(args = []) {
+	const request = {
+		renderer: undefined,
+		width: undefined,
+	};
+
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+
+		if (argument === "--profile") {
+			validateRenderProfile(readOptionValue(args, index, argument));
+			index += 1;
+		} else if (argument.startsWith("--profile=")) {
+			validateRenderProfile(readInlineOptionValue(argument, "--profile"));
+		} else if (argument === "--width") {
+			request.width = readWidthValue(readOptionValue(args, index, argument));
+			index += 1;
+		} else if (argument.startsWith("--width=")) {
+			request.width = readWidthValue(readInlineOptionValue(argument, "--width"));
+		} else if (argument === "--json") {
+			throw new Error("Render does not support json output");
+		} else if (globalRenderingFlags.has(argument)) {
+			// Accepted here because createCliStyle() has already resolved these flags.
+		} else if (argument.startsWith("-")) {
+			throw new Error(`Unknown render option: ${argument}`);
+		} else if (request.renderer !== undefined) {
+			throw new Error(`Unexpected render argument: ${argument}`);
+		} else {
+			request.renderer = argument;
+		}
+	}
+
+	validateRequest(request);
+
+	return request;
+}
+
+/**
+ * Render caller-provided JSON through a named renderer.
+ *
+ * @param  {string}  json
+ *     JSON input from stdin.
+ * @param  {object}  request
+ *     Parsed render request.
+ * @param  {object}  options
+ *     Resolved render options.
+ * @returns  {string}
+ *     Rendered text.
+ */
+export function renderJsonInput(json, request, options = {}) {
+	if (options.profile === profiles.JSON) {
+		throw new Error("Render does not support json output");
+	}
+
+	const input = parseJsonObject(json);
+	const renderer = renderers[request.renderer];
+
+	return renderer(input, {
+		...options,
+		width: request.width ?? options.width,
+	});
+}
+
+/**
+ * Read a required inline option value.
+ *
+ * @param  {string}  argument
+ *     Full `--option=value` argument.
+ * @param  {string}  option
+ *     Option name.
+ * @returns  {string}
+ *     Option value.
+ */
+function readInlineOptionValue(argument, option) {
+	const value = argument.slice(`${option}=`.length);
+
+	if (value === "") {
+		throw new Error(`Missing value for ${option}`);
+	}
+
+	return value;
+}
+
+/**
+ * Read a required option value.
+ *
+ * @param  {string[]}  args
+ *     Command arguments.
+ * @param  {number}  index
+ *     Option index.
+ * @param  {string}  option
+ *     Option name.
+ * @returns  {string}
+ *     Option value.
+ */
+function readOptionValue(args, index, option) {
+	const value = args[index + 1];
+
+	if (value === undefined || value.startsWith("-")) {
+		throw new Error(`Missing value for ${option}`);
+	}
+
+	return value;
+}
+
+/**
+ * Parse a render width option.
+ *
+ * @param  {string}  value
+ *     Width argument value.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function readWidthValue(value) {
+	const width = Number(value);
+
+	if (!Number.isInteger(width) || width <= 0) {
+		throw new Error("Render width must be a positive integer");
+	}
+
+	return width;
+}
+
+/**
+ * Validate a render text profile.
+ *
+ * @param  {string}  profile
+ *     Requested output profile.
+ * @returns  {void}
+ */
+function validateRenderProfile(profile) {
+	if (!isProfile(profile)) {
+		throw new Error(`Unknown profile: ${profile}`);
+	}
+
+	if (profile === profiles.JSON) {
+		throw new Error("Render does not support json output");
+	}
+}
+
+/**
+ * Validate render request values.
+ *
+ * @param  {object}  request
+ *     Parsed render request.
+ * @returns  {void}
+ */
+function validateRequest(request) {
+	if (request.renderer === undefined) {
+		throw new Error("Missing renderer");
+	}
+
+	if (!Object.hasOwn(renderers, request.renderer)) {
+		throw new Error(`Unknown renderer: ${request.renderer}`);
+	}
+}
+
+/**
+ * Parse JSON stdin into an object accepted by renderers.
+ *
+ * @param  {string}  json
+ *     JSON input.
+ * @returns  {object}
+ *     Parsed input object.
+ */
+function parseJsonObject(json) {
+	let input;
+
+	try {
+		input = JSON.parse(json);
+	} catch {
+		throw new Error("Render input must be valid JSON");
+	}
+
+	if (input === null || Array.isArray(input) || typeof input !== "object") {
+		throw new Error("Render input must be a JSON object");
+	}
+
+	return input;
+}

package/src/create-cli-style.js

@@ -0,0 +1,53 @@
+import { resolveProfile } from "./capability/resolve-profile.js";
+import { resolveTerminalCapabilities } from "./capability/terminal.js";
+import { profiles } from "./profiles/profiles.js";
+
+/**
+ * Create a CLI style renderer with stable, testable defaults.
+ *
+ * @param  {object}  options
+ *     Output profile, terminal capability, stream, environment, and width options.
+ * @returns  {object}
+ *     Renderer helpers and resolved options.
+ */
+export function createCliStyle(options = {}) {
+	const capabilities = resolveTerminalCapabilities(options);
+
+	const resolvedOptions = {
+		...capabilities,
+		profile: resolveProfile(options),
+	};
+
+	applyExplicitOption(resolvedOptions, options, "colour");
+	applyExplicitOption(resolvedOptions, options, "unicode");
+	applyExplicitOption(resolvedOptions, options, "width");
+
+	return {
+		options: resolvedOptions,
+		print: (value) => {
+			console.log(value);
+		},
+		write: (value) => {
+			process.stdout.write(value);
+		},
+	};
+}
+
+/**
+ * Apply an explicit option override when provided.
+ *
+ * @param  {object}  target
+ *     Resolved options to update.
+ * @param  {object}  source
+ *     Caller-provided options.
+ * @param  {string}  key
+ *     Option key to copy.
+ * @returns  {void}
+ */
+function applyExplicitOption(target, source, key) {
+	if (Object.hasOwn(source, key)) {
+		target[key] = source[key];
+	}
+}
+
+export { profiles };