@lewishowles/cli-style 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.16.0 - 2026-09-21
+
+### Breaking changes
+
+- BREAKING: Removed the `panelWidth` option from `panel()` and the `panel` renderer. Use `width` instead.
+- BREAKING: Panels now honour the requested total `width`, raise widths below 6 to the minimum usable width, and wrap long lines to fit.
+
+### Fixed
+
+- An explicit JSON `width` now takes precedence over the terminal width for width-aware renderers, so piped output stays within the caller's requested bounds.
+
+## 0.15.0 - 2026-09-20
+
+### Added
+
+- The Python adapter is published to PyPI as `lewishowles-cli-style`, so Python projects can install it with `pip install lewishowles-cli-style` instead of from a local path or this repository. The name it is imported under is unchanged: `import cli_style`.
+- `bun run check:adapters` now fails when `package.json` and the Python package declare different versions, or when the Python package's copy of the licence differs from the one at the repository root.
+- Releasing a tag whose version does not match `package.json` now fails before anything is published.
+
 ## 0.14.0 - 2026-09-20
 
 ### Added

package/README.md

@@ -17,16 +17,22 @@ JavaScript projects can install the package directly:
 bun add @lewishowles/cli-style
 ```
 
-Python projects can install the adapter from a local path with `uv`:
+Python projects can install the published package from PyPI:
+
+```bash
+pip install lewishowles-cli-style
+```
+
+They can also install the adapter from a local path with `uv`:
 
 ```bash
 uv add --editable ../cli-style/adapters/python
 ```
 
-They can also install it from this repository:
+Or install it straight from this repository:
 
 ```bash
-uv add "cli-style @ git+https://github.com/lewishowles/cli-style.git#subdirectory=adapters/python"
+uv add "lewishowles-cli-style @ git+https://github.com/lewishowles/cli-style.git#subdirectory=adapters/python"
 ```
 
 Swift projects can add `adapters/swift` as a local package dependency and use its `CliStyle` product.
@@ -80,6 +86,10 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
+For `render` commands, width follows this priority: JSON payload `width`, `--width`,
+`stdout.columns`, positive `COLUMNS`, then `80`, so piped output stays within the caller's requested
+size when the payload supplies a width.
+
 ### CLI render
 
 Use `cli-style render <renderer>` when a script needs rendered text from JSON input:
@@ -377,19 +387,19 @@ Pre-render a `span` when only part of the hint needs emphasis.
 
 ### Structured primitives
 
-| Renderer        | Main fields                            |
-| --------------- | -------------------------------------- |
-| `divider`       | `label`, `dividerWidth`, `character`   |
-| `chip`          | `label`, `tone`                        |
-| `panel`         | `title`, `lines`, `tone`, `panelWidth` |
-| `table`         | `columns`, `rows`, `width`             |
-| `progress-bar`  | `value`, `max`, `barWidth`, `tone`     |
-| `bar-chart`     | `rows`, `barWidth`                     |
-| `sparkline`     | `values`, `label`, `tone`, `width`     |
-| `step`          | `label`, `state`                       |
-| `step-progress` | `steps`, `current`                     |
-| `empty-state`   | `title`, `detail`                      |
-| `error-block`   | `title`, `lines`                       |
+| Renderer        | Main fields                          |
+| --------------- | ------------------------------------ |
+| `divider`       | `label`, `dividerWidth`, `character` |
+| `chip`          | `label`, `tone`                      |
+| `panel`         | `title`, `lines`, `tone`, `width`    |
+| `table`         | `columns`, `rows`, `width`           |
+| `progress-bar`  | `value`, `max`, `barWidth`, `tone`   |
+| `bar-chart`     | `rows`, `barWidth`                   |
+| `sparkline`     | `values`, `label`, `tone`, `width`   |
+| `step`          | `label`, `state`                     |
+| `step-progress` | `steps`, `current`                   |
+| `empty-state`   | `title`, `detail`                    |
+| `error-block`   | `title`, `lines`                     |
 
 For visual examples, run `cli-style gallery --section primitives`.
 

package/adapters/python/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lewis Howles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/adapters/python/README.md

@@ -0,0 +1,29 @@
+# lewishowles-cli-style
+
+`lewishowles-cli-style` is a Python adapter for the shared `cli-style` command-line renderer. It lets Python programs use the same terminal output styles as the JavaScript package.
+
+## Install
+
+```sh
+python -m pip install lewishowles-cli-style
+```
+
+The package supports Python 3.9 and later. The installed distribution is named `lewishowles-cli-style`, and you import it as `cli_style`.
+
+Rendering happens in the separate `cli-style` binary, so that needs to be on your `PATH`. The [main readme](https://github.com/lewishowles/cli-style#install) covers the ways to install it.
+
+## Usage
+
+```python
+from cli_style import render
+
+print(render("status", {"type": "success", "label": "Build passed"}))
+```
+
+If the `cli-style` binary is not available, `render()` returns sorted plain `key: value` text by default. Pass `raise_on_missing=True` to raise `CliStyleNotFoundError` instead.
+
+## More information
+
+- [Repository](https://github.com/lewishowles/cli-style)
+- [Issue tracker](https://github.com/lewishowles/cli-style/issues)
+- [MIT licence](https://github.com/lewishowles/cli-style/blob/main/LICENSE)

package/adapters/python/cli_style/_wrappers.py

@@ -297,7 +297,7 @@ def panel(
 	lines: list[str] | None = None,
 	title: str | None = None,
 	tone: str = "info",
-	panel_width: int | float | None = None,
+	width: int | float | None = None,
 	**kwargs: Any,
 ) -> str:
 	"""Return panel output; extra keyword arguments go to render()."""
@@ -308,8 +308,8 @@ def panel(
 
 	if title is not None:
 		data["title"] = title
-	if panel_width is not None:
-		data["panelWidth"] = panel_width
+	if width is not None:
+		data["width"] = width
 
 	return render("panel", data, **kwargs)
 

package/adapters/python/pyproject.toml

@@ -1,11 +1,28 @@
 [project]
-name = "cli-style"
-version = "0.14.0"
+name = "lewishowles-cli-style"
+version = "0.16.0"
 description = "Python adapter for the shared cli-style binary."
 authors = [{ name = "Lewis Howles" }]
 license = { text = "MIT" }
+license-files = ["LICENSE"]
+readme = "README.md"
 requires-python = ">=3.9"
 dependencies = []
+classifiers = [
+	"License :: OSI Approved :: MIT License",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3 :: Only",
+	"Programming Language :: Python :: 3.9",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Repository = "https://github.com/lewishowles/cli-style"
+Issues = "https://github.com/lewishowles/cli-style/issues"
 
 [build-system]
 requires = ["hatchling"]

package/adapters/swift/Sources/CliStyle/Wrappers.swift

@@ -341,7 +341,7 @@ extension CliStyle {
 		lines: [String]? = nil,
 		title: String? = nil,
 		tone: String = "info",
-		panelWidth: Int? = nil,
+		width: Int? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
 		var data: [String: Any] = [
@@ -352,8 +352,8 @@ extension CliStyle {
 		if let title = title {
 			data["title"] = title
 		}
-		if let panelWidth = panelWidth {
-			data["panelWidth"] = panelWidth
+		if let width = width {
+			data["width"] = width
 		}
 
 		return try render("panel", data: data, options: options)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

package/scripts/build-binary.sh

@@ -6,6 +6,8 @@
 #   dist/adapters/bash/cli-style.sh
 #   dist/adapters/python/cli_style/
 #   dist/adapters/python/pyproject.toml
+#   dist/adapters/python/README.md
+#   dist/adapters/python/LICENSE
 #   dist/adapters/swift/Package.swift
 #   dist/adapters/swift/Sources/
 
@@ -29,6 +31,6 @@ cp adapters/bash/cli-style.sh dist/adapters/bash/cli-style.sh
 # Copy the Python package without the __pycache__ folders Python leaves behind.
 tar -C "adapters/python" \
 	--exclude="__pycache__" \
-	-cf - cli_style pyproject.toml | tar -C "dist/adapters/python" -xf -
+	-cf - cli_style pyproject.toml README.md LICENSE | tar -C "dist/adapters/python" -xf -
 
 cp -R adapters/swift/Package.swift adapters/swift/Sources dist/adapters/swift/

package/scripts/generate-adapters.js

@@ -4,16 +4,19 @@ import { fileURLToPath } from "node:url";
 
 import { rendererCatalogue } from "../src/catalogue/renderer-catalogue.js";
 
+const scriptsDirectoryPath = dirname(fileURLToPath(import.meta.url));
+const repositoryRootPath = join(scriptsDirectoryPath, "..");
+
 // Generated adapter modules are kept beside their hand-written language cores.
-const pythonOutputPath = join(
-	dirname(fileURLToPath(import.meta.url)),
-	"../adapters/python/cli_style/_wrappers.py",
-);
+const pythonOutputPath = join(repositoryRootPath, "adapters/python/cli_style/_wrappers.py");
+
+const swiftOutputPath = join(repositoryRootPath, "adapters/swift/Sources/CliStyle/Wrappers.swift");
 
-const swiftOutputPath = join(
-	dirname(fileURLToPath(import.meta.url)),
-	"../adapters/swift/Sources/CliStyle/Wrappers.swift",
-);
+// Package metadata and licence files checked alongside generated adapter modules.
+const packageJsonPath = join(repositoryRootPath, "package.json");
+const pythonProjectPath = join(repositoryRootPath, "adapters/python/pyproject.toml");
+const repositoryLicensePath = join(repositoryRootPath, "LICENSE");
+const pythonLicensePath = join(repositoryRootPath, "adapters/python/LICENSE");
 
 // Map catalogue types to the closest useful Python annotations.
 const pythonTypes = {
@@ -379,10 +382,59 @@ const generatedFiles = [
 	},
 ];
 
+/**
+ * Read a licence file, treating an absent file as a reportable state rather than a crash.
+ *
+ * @param  {string}  path
+ *     The licence file to read.
+ * @returns  {Buffer|null}
+ *     The file contents, or null when the file is not there.
+ */
+function readLicenseFile(path) {
+	try {
+		return readFileSync(path);
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			return null;
+		}
+
+		throw error;
+	}
+}
+
 // `--check` reports committed wrappers that differ from the generated source and writes nothing.
 const checkOnly = process.argv.includes("--check");
 
 if (checkOnly) {
+	// Both packages are released from one tag, so a version edited in one file and
+	// forgotten in the other would publish a Python package claiming a version that
+	// was never released.
+	const packageManifest = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	const packageVersion = packageManifest.version;
+
+	// The version is the only field read out of pyproject.toml, and the file is ours, so
+	// a pattern match avoids taking on a TOML parser for one line.
+	const pythonVersionMatch = readFileSync(pythonProjectPath, "utf8").match(
+		/^version\s*=\s*"([^"]+)"/m,
+	);
+
+	const pythonVersion = pythonVersionMatch?.[1];
+	const versionsMatch = packageVersion === pythonVersion;
+
+	// The Python package carries its own copy of the licence, because a wheel built from
+	// the published source archive cannot reach the one at the repository root.
+	const repositoryLicense = readLicenseFile(repositoryLicensePath);
+	const pythonLicense = readLicenseFile(pythonLicensePath);
+
+	const missingLicensePaths = [
+		["LICENSE", repositoryLicense],
+		["adapters/python/LICENSE", pythonLicense],
+	]
+		.filter(([, contents]) => contents === null)
+		.map(([path]) => path);
+
+	const licensesMatch = missingLicensePaths.length === 0 && repositoryLicense.equals(pythonLicense);
+
 	// A committed wrapper is stale when its contents differ from the generated source; a missing file counts as stale.
 	const staleFiles = generatedFiles.filter(({ path, source }) => {
 		try {
@@ -396,13 +448,33 @@ if (checkOnly) {
 		}
 	});
 
+	if (!versionsMatch) {
+		console.error("Package versions do not match:");
+		console.error(`- package.json: ${packageVersion ?? "missing"}`);
+		console.error(`- adapters/python/pyproject.toml: ${pythonVersion ?? "missing"}`);
+	}
+
+	if (missingLicensePaths.length > 0) {
+		console.error("Licence files are missing:");
+
+		for (const path of missingLicensePaths) {
+			console.error(`- ${path}`);
+		}
+	} else if (!licensesMatch) {
+		console.error("Licence files do not match:");
+		console.error("- LICENSE");
+		console.error("- adapters/python/LICENSE");
+	}
+
 	if (staleFiles.length > 0) {
 		console.error("Generated adapters are stale:");
 
 		for (const { path } of staleFiles) {
 			console.error(`- ${path}`);
 		}
+	}
 
+	if (staleFiles.length > 0 || !versionsMatch || !licensesMatch) {
 		process.exitCode = 1;
 	}
 } else {

package/scripts/package-binary.sh

@@ -6,6 +6,8 @@
 #   adapters/bash/cli-style.sh
 #   adapters/python/cli_style/
 #   adapters/python/pyproject.toml
+#   adapters/python/README.md
+#   adapters/python/LICENSE
 #   adapters/swift/Package.swift
 #   adapters/swift/Sources/
 

package/src/capability/terminal.js

@@ -29,7 +29,7 @@ export function resolveTerminalCapabilities(options = {}) {
 	const isCi = env.CI === "true" || env.CI === "1";
 	const isDumb = env.TERM === "dumb";
 	const forceColour = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
-	const width = resolveWidth(stdout.columns);
+	const width = resolveWidth(stdout.columns, env.COLUMNS);
 	const usesPlain = argv.includes("--plain");
 
 	const colour = resolveColour({
@@ -189,16 +189,25 @@ function resolveUnicode(options) {
 }
 
 /**
- * Resolve terminal width with a stable fallback.
+ * Resolve the terminal width from the output stream, then `COLUMNS`, then a fixed fallback.
  *
- * @param  {number}  width
- *     Stream-reported column count.
+ * @param  {number}  streamWidth
+ *     The column count the output stream reports when it is a terminal.
+ * @param  {string}  columns
+ *     The `COLUMNS` environment value, used when the stream reports no width, such as when
+ *     output is piped. Anything other than a positive whole number is ignored.
  * @returns  {number}
  *     Usable terminal width.
  */
-function resolveWidth(width) {
-	if (Number.isInteger(width) && width > 0) {
-		return width;
+function resolveWidth(streamWidth, columns) {
+	if (Number.isInteger(streamWidth) && streamWidth > 0) {
+		return streamWidth;
+	}
+
+	const environmentWidth = Number(columns);
+
+	if (Number.isInteger(environmentWidth) && environmentWidth > 0) {
+		return environmentWidth;
 	}
 
 	return defaultWidth;

package/src/catalogue/renderer-catalogue.js

@@ -595,7 +595,7 @@ const rendererDefinitions = [
 				default: "info",
 			},
 			{
-				name: "panelWidth",
+				name: "width",
 				type: "number",
 				required: false,
 				default: null,

package/src/cli/render-command.js

@@ -38,6 +38,7 @@ const renderers = {
 		bulletList(input.items, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	chip: (input, options) =>
 		chip(input.label, input.tone, {
@@ -63,6 +64,7 @@ const renderers = {
 		errorBlock(input.title, input.lines, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	hint: (input, options) =>
 		hint(input.message, {
@@ -73,12 +75,14 @@ const renderers = {
 		labelledLine(input.label, input.message, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
 	panel: (input, options) =>
 		panel({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"progress-bar": (input, options) =>
 		progressBar({
@@ -89,16 +93,19 @@ const renderers = {
 		row(input.label, input.value, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"row-group": (input, options) =>
 		rowGroup({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	sparkline: (input, options) =>
 		sparkline({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	span: (input, options) =>
 		span(input.value, input.tone, {
@@ -124,6 +131,7 @@ const renderers = {
 		table({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"task-summary": (input, options) => taskSummary(input, options),
 };

package/src/gallery/render-gallery.js

@@ -280,7 +280,6 @@ function galleryWidthOptions(width) {
 	return {
 		barWidth: Math.max(width - 18, 1),
 		dividerWidth: width,
-		panelWidth: width,
 	};
 }
 
@@ -790,7 +789,7 @@ function renderPrimitives(options) {
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
-			panelWidth: 40,
+			width: 40,
 		}),
 		"",
 		"Steps",

package/src/primitives/panel.js

@@ -1,10 +1,14 @@
 import { background, foreground, style } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
 import { profiles } from "../profiles/profiles.js";
 import { panelColours } from "../theme/colours.js";
 
-// Panels use a stable width so grouped output aligns across a report.
+// The width used when no width is given, such as a direct library call outside a terminal.
 const defaultWidth = 40;
 
+// The narrowest panel that still leaves one column for content beside the accent and padding.
+const minimumWidth = 6;
+
 // Info is the neutral semantic accent for grouped explanatory content.
 const defaultTone = "info";
 
@@ -17,8 +21,9 @@ const defaultTone = "info";
  *     Whether ANSI colour should be applied.
  * @param  {string[]}  options.lines
  *     Content lines to render.
- * @param  {number}  options.panelWidth
- *     Total panel width.
+ * @param  {number}  options.width
+ *     Total panel width, including the accent and padding. Widths below 6 are raised to 6,
+ *     which leaves room for one character of content. Longer lines wrap to fit.
  * @param  {string}  options.profile
  *     Active output profile.
  * @param  {string}  options.title
@@ -37,18 +42,18 @@ export function panel(options = {}) {
 		return [...(options.title === undefined ? [] : [options.title]), ...lines].join("\n");
 	}
 
-	const width = Math.max(options.panelWidth ?? defaultWidth, 4);
+	const width = Math.max(options.width ?? defaultWidth, minimumWidth);
 	const panelLines = ["", ...(options.title === undefined ? [] : [options.title]), ...lines, ""];
 
 	return panelLines
-		.map((line, index) =>
+		.flatMap((line, index) =>
 			renderLine(line, width, index === 1 && options.title !== undefined, options),
 		)
 		.join("\n");
 }
 
 /**
- * Render one fixed-width panel line.
+ * Render one content line, wrapped across as many panel lines as it needs.
  *
  * @param  {string}  line
  *     Content line.
@@ -58,28 +63,30 @@ export function panel(options = {}) {
  *     Whether the line is the panel title.
  * @param  {object}  options
  *     Rendering options.
- * @returns  {string}
- *     Rendered content line.
+ * @returns  {string[]}
+ *     The panel lines, each exactly `width` columns wide.
  */
 function renderLine(line, width, isTitle, options) {
 	const accent = options.unicode === false ? "|" : "▌";
 	const contentWidth = width - 5;
-	const visibleLine = line.slice(0, contentWidth);
-	const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
 
-	if (options.colour !== true) {
-		return `${accent}${content}`;
-	}
+	return wrapText(line, contentWidth).map((visibleLine) => {
+		const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
+
+		if (options.colour !== true) {
+			return `${accent}${content}`;
+		}
 
-	const renderedAccent = renderPanelColour(accent, options);
+		const renderedAccent = renderPanelColour(accent, options);
 
-	const renderedContent = foreground(
-		background(content, panelColours.background, options),
-		panelColours.body,
-		options,
-	);
+		const renderedContent = foreground(
+			background(content, panelColours.background, options),
+			panelColours.body,
+			options,
+		);
 
-	return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+		return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+	});
 }
 
 /**