@lewishowles/cli-style 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased
+## 0.7.0 - 2026-07-05
+
+### Added
+
+- Added Python adapter convenience functions for scalar pattern usage: `command_result`, `audit_finding`, `task_summary`, `confirmation_result`, and `next_step_block`.
+- Added Python adapter convenience functions for common primitives: `status`, `row`, `span`, `hint`, and `divider`.
+- Added Bash adapter convenience functions for scalar pattern usage: `cli_style_command_result`, `cli_style_audit_finding`, `cli_style_task_summary`, `cli_style_confirmation_result`, and `cli_style_next_step_block`.
+- Added Bash adapter helpers for JSON string arrays and integer/null fields, so pattern wrappers can safely pass single-item list fields and exit codes.
+
+### Changed
+
+- Extended the README renderer table with a Python helper column covering all 20 renderers, including convenience functions and `render()` fallbacks for aggregate patterns.
+
+## 0.6.0 - 2026-07-03
+
+### Added
+
+- Added result-state support to `row()` and `cli_style_row`, so label/value rows can render failed, warning, success, or other status cues while keeping column alignment.
+- Added the `span()` inline emphasis primitive and `cli_style_span` Bash helper for highlighting commands, files, or values inside existing line renderers such as `hint()`.
+- Added `span` support to `cli-style render` and the public JavaScript export.
+
+### Changed
+
+- Reworked the README around integration paths, available renderers, primitive data shapes, patterns, options, profiles, result types, and gallery commands.
 
 ## 0.5.0 - 2026-07-02
 

package/README.md

@@ -1,11 +1,13 @@
 # CLI style
 
-Shared terminal output styles for tools, diagnostics, and package CLIs.
+Shared terminal output styles for local tools, diagnostics, agent-facing reports, and package CLIs.
+
+Use it directly from JavaScript, or call the same renderers from Bash and Python through the `cli-style` binary.
 
 ## Requirements
 
 - Bun and Node.js 20 or newer for JavaScript projects and local binary builds
-- The standalone binary for Bash or Python projects that should not install Bun
+- The standalone `cli-style` binary for Bash or Python projects that should not install Bun
 
 ## Install
 
@@ -21,7 +23,29 @@ Bash and Python projects call the `cli-style` binary through thin adapters. If t
 export PATH="/path/to/cli-style/bin:$PATH"
 ```
 
-## JavaScript
+Build a standalone binary when a repo should not need Bun at runtime:
+
+```bash
+bun run build:binary
+bun run smoke:binary
+```
+
+Create a binary install tarball:
+
+```bash
+bun run package:binary
+tar -tzf dist/release/cli-style-*.tar.gz
+```
+
+The package contains `bin/cli-style` and `adapters/`.
+
+## Choose an integration
+
+All renderers return text. JavaScript imports functions directly. CLI, Bash, and Python integrations pass JSON-compatible data to a named renderer.
+
+### JavaScript
+
+Create the `ui` instance at the CLI entrypoint, then pass `ui.options` to renderers. That keeps flag, environment, stream, colour, Unicode, and width detection in one place.
 
 ```js
 import { createCliStyle, status } from "@lewishowles/cli-style";
@@ -42,170 +66,428 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
-Create the `ui` instance at the CLI entrypoint, then pass it to command handlers. That keeps flag, environment, stream, colour, Unicode, and width detection in one place.
+### CLI render
 
-## Reporter
+Use `cli-style render <renderer>` when a script needs rendered text from JSON input:
 
-Use a reporter when a script needs grouped output rather than one row per file.
+```bash
+cli-style render status --profile diagnostic <<'JSON'
+{
+  "type": "success",
+  "label": "Build passed",
+  "detail": "184 tests"
+}
+JSON
+```
 
-```js
-import { createReporter } from "@lewishowles/cli-style";
+Use renderer names from the tables below, for example `status`, `row`, `diagnostic-report`, or `task-summary`.
 
-const reporter = createReporter({
-	colour: false,
-});
+### Bash
 
-reporter.divider("Project setup", "Claude + Codex");
-reporter.group(
-	"Agent scripts",
-	[
-		{
-			label: "project-diagnostics.py",
-			result: "unchanged",
-		},
-		{
-			label: "repo-context.py",
-			result: "unchanged",
-		},
-	],
-	{
-		summary: "2 already linked",
-	},
-);
-reporter.status("success", "Done.");
+Source the Bash adapter, then use convenience helpers for common primitive and per-script pattern renderers:
 
-console.log(reporter.render());
-```
+```bash
+source "$(cli-style adapter-path bash)"
 
-Use `reporter.divider()` for major phases. Use `reporter.section()` when you want a normal `info` status row inside a phase. Panels are for framed content blocks, not headings.
+label='Build "passed"'
+detail="/path/to/project"
 
-Groups can include verbose detail rows when a caller opts in:
+cli_style_status success "$label" "$detail" --profile diagnostic
+cli_style_row "Workspace" "$detail" --plain
+cli_style_row "Bundle" "is 22.3 KB, above the 12.0 KB budget" failed --plain
+command="$(cli_style_span "npm run docs:readme" info --plain)"
+cli_style_hint "Run $command before release" --plain
+cli_style_divider "Project setup" --plain
 
-```js
-const reporter = createReporter({
-	verbose: process.env.AGENTS_VERBOSE === "1",
-});
+cli_style_command_result success "Build passed" "bun run test:unit" 0 "1.2s" "184 tests" --plain
+cli_style_task_summary partial "Adopt cli-style" "Bash wrappers added" "Updated adapter" "Update scripts" --plain
+cli_style_confirmation_result confirmed "Publish release" "v0.6.0" "Tag push starts npm publish" --plain
+cli_style_next_step_block "Update helpers scripts" "Wrappers are now available" "scripts/setup.sh --check" "" --plain
 ```
 
-## CLI
+The convenience functions build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
 
-Use `cli-style render <renderer>` when a script needs rendered text from JSON input.
+Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
 
 ```bash
-cli-style render status --profile diagnostic <<'JSON'
-{
-  "type": "success",
-  "label": "Build passed",
-  "detail": "184 tests"
-}
-JSON
+CLI_STYLE_BIN="/path/to/cli-style" cli_style_status success "Build passed" "" --plain
 ```
 
+Use `cli_style_render` for literal or prebuilt JSON, especially for aggregate patterns or multi-item pattern fields:
+
 ```bash
-cli-style render task-summary --plain <<'JSON'
+cli_style_render diagnostic-report --profile diagnostic <<'JSON'
 {
-  "title": "Task summary",
-  "completed": ["Added render command"],
-  "remaining": ["Add adapters"]
+  "title": "Release checks",
+  "checks": [
+    {
+      "name": "README",
+      "result": "success"
+    }
+  ]
 }
 JSON
 ```
 
-`render` supports `--profile`, `--plain`, `--no-colour`, `--no-color`, `--no-unicode`, and `--width`. It rejects `--json`; JSON profile behaviour is for library calls and machine-readable commands.
+### Python
 
-Build a local standalone binary when a repo should not need Bun at runtime:
+Add the adapter directory to `PYTHONPATH`, then import the generic `render()` helper or convenience functions:
 
 ```bash
-bun run build:binary
-bun run smoke:binary
+export PYTHONPATH="$(cli-style adapter-path python):$PYTHONPATH"
 ```
 
-Create a binary install tarball:
+```python
+from cli_style import status, row, span, hint, divider
 
-```bash
-bun run package:binary
-tar -tzf dist/release/cli-style-*.tar.gz
+kwargs = {"binary": "./bin/cli-style.js", "plain": True}
+
+print(status("success", "Build passed", "184 tests", **kwargs))
+print(row("Workspace", "/path/to/project", **kwargs))
+print(row("Bundle", "over budget", "failed", **kwargs))
+command = span("npm run docs:readme", "info", **kwargs)
+print(hint(f"Run {command} before release", **kwargs))
+print(divider("Project setup", **kwargs))
 ```
 
-The package contains `bin/cli-style` and `adapters/`. Install it into a repo-local tools directory, then call that repo-local `bin/cli-style` from scripts.
+Convenience functions build the renderer payload internally, so callers pass plain Python strings without hand-building JSON.
 
-## Bash
+Pass `binary=` when `cli-style` is not on `PATH`. The generic `render()` helper remains for aggregate patterns or multi-item fields:
 
-```bash
-source "$(cli-style adapter-path bash)"
+```python
+from cli_style import render
 
-label='Build "passed"'
-detail="/path/to/project"
+output = render(
+	"diagnostic-report",
+	{
+		"title": "Release checks",
+		"checks": [{"name": "README", "result": "success"}],
+	},
+	profile="diagnostic",
+)
 
-cli_style_status success "$label" "$detail" --profile diagnostic
-cli_style_row "Workspace" "$detail" --plain
-cli_style_hint "Run \"check\" before release" --plain
-cli_style_divider "Project setup" --plain
+print(output)
+```
+
+## Available renderers
+
+Renderer names are stable for `cli-style render`, `cli_style_render`, and Python `render()`. JavaScript uses camel-case function names.
+
+| Renderer              | JavaScript                            | Bash helper                          | Python helper                      | Purpose                                                         |
+| --------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
+| `status`              | `status(resultType, detail, options)` | `cli_style_status type label detail` | `status(type, label, detail)`      | Result line with symbol, label, and detail.                     |
+| `row`                 | `row(label, value, options)`          | `cli_style_row label value [result]` | `row(label, value, result)`        | Aligned label/value row, optionally marked with a result state. |
+| `span`                | `span(value, tone, options)`          | `cli_style_span value [tone]`        | `span(value, tone)`                | Inline colour or weight for a word, command, file, or value.    |
+| `hint`                | `hint(message, options)`              | `cli_style_hint message`             | `hint(message)`                    | Informational hint line.                                        |
+| `divider`             | `divider(options)`                    | `cli_style_divider label`            | `divider(label)`                   | Section divider with an optional label.                         |
+| `command-result`      | `commandResult(options)`              | `cli_style_command_result ...`       | `command_result(...)`              | Command execution outcome with exit code and duration.          |
+| `audit-finding`       | `auditFinding(options)`               | `cli_style_audit_finding ...`        | `audit_finding(...)`               | Structured audit finding with evidence and recommendation.      |
+| `task-summary`        | `taskSummary(options)`                | `cli_style_task_summary ...`         | `task_summary(...)`                | Task progress with completed and remaining items.               |
+| `confirmation-result` | `confirmationResult(options)`         | `cli_style_confirmation_result ...`  | `confirmation_result(...)`         | Confirmation outcome with action and item.                      |
+| `next-step-block`     | `nextStepBlock(options)`              | `cli_style_next_step_block ...`      | `next_step_block(...)`             | Next-step guidance with command and alternative.                |
+| `chip`                | `chip(label, tone, options)`          | Use `cli_style_render`               | Use `render("chip", ...)`          | Compact labelled state.                                         |
+| `panel`               | `panel(options)`                      | Use `cli_style_render`               | Use `render("panel", ...)`         | Framed content block for grouped output.                        |
+| `table`               | `table(options)`                      | Use `cli_style_render`               | Use `render("table", ...)`         | Tabular records with narrow-width fallback.                     |
+| `progress-bar`        | `progressBar(options)`                | Use `cli_style_render`               | Use `render("progress-bar", ...)`  | Single progress value with numeric text.                        |
+| `bar-chart`           | `barChart(options)`                   | Use `cli_style_render`               | Use `render("bar-chart", ...)`     | Multi-row bar chart.                                            |
+| `step`                | `step(label, state, options)`         | Use `cli_style_render`               | Use `render("step", ...)`          | One workflow step.                                              |
+| `step-progress`       | `stepProgress(options)`               | Use `cli_style_render`               | Use `render("step-progress", ...)` | Numbered workflow steps.                                        |
+| `empty-state`         | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Use `render("empty-state", ...)`   | Empty result message.                                           |
+| `error-block`         | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Use `render("error-block", ...)`   | Structured error block.                                         |
+
+Use `render("<renderer>", data, ...)` for aggregate patterns (`diagnostic-report`, `agent-transcript`, `compact-data-table`) or any renderer with multi-item fields.
+
+## Primitive data shapes
+
+Use these shapes with `cli-style render`, `cli_style_render`, or Python `render()`. JavaScript callers pass the listed function arguments directly.
+
+### `status`
+
+```json
+{
+	"type": "success",
+	"label": "Build passed",
+	"detail": "184 tests"
+}
 ```
 
-Use the convenience functions for dynamic Bash values. They build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
+- `type`: one of the result types listed below
+- `label`: optional label override
+- `detail`: optional text after the label
 
-`cli_style_status` accepts `type`, `label`, `detail`, then render flags. Pass an empty detail when you only need a label:
+### `row`
 
-```bash
-cli_style_status success "Done" "" --plain
+```json
+{
+	"label": "Bundle",
+	"value": "is 22.3 KB, above the 12.0 KB budget",
+	"result": "failed",
+	"labelWidth": 8
+}
 ```
 
-Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
+- `label`: left-hand label
+- `value`: right-hand value
+- `result`: optional result type for a symbol and tone
+- `labelWidth`: optional minimum label width
+- `labelColour`, `valueColour`, `separator`: optional presentation overrides
 
-```bash
-CLI_STYLE_BIN="/path/to/cli-style" cli_style_status success "Build passed" "" --plain
+### `span`
+
+```json
+{
+	"value": "npm run docs:readme",
+	"tone": "info"
+}
 ```
 
-Keep `cli_style_render` for literal or prebuilt JSON:
+- `value`: inline text to emphasise
+- `tone`: optional tone, defaulting to `info`
+- `weight`: optional ANSI style, defaulting to `bold`
 
-```bash
-cli_style_render status --plain <<'JSON'
+### `hint`
+
+```json
 {
-  "type": "success",
-  "label": "Build passed"
+	"message": "Run npm run docs:readme before release"
 }
-JSON
 ```
 
-## Python
+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`                     |
+| `step`          | `label`, `state`                       |
+| `step-progress` | `steps`, `current`                     |
+| `empty-state`   | `title`, `detail`                      |
+| `error-block`   | `title`, `lines`                       |
+
+For visual examples, run `cli-style gallery --section primitives`.
+
+## Patterns
+
+Patterns are built-in composite renderers for common report shapes. They use the same lower-level primitives internally, but accept structured objects so callers do not need to assemble panels, statuses, tables, and rows by hand.
+
+| Renderer              | JavaScript                                  | Purpose                               | Main fields                                                                          |
+| --------------------- | ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `diagnostic-report`   | `diagnosticReport(report, options)`         | Aggregate check report.               | `title`, `checks`, `findings`, `skippedChecks`, `nextActions`                        |
+| `command-result`      | `commandResult(result, options)`            | Single command outcome with metadata. | `title`, `result`, `summary`, `command`, `exitCode`, `duration`, `details`           |
+| `audit-finding`       | `auditFinding(finding, options)`            | Single audit finding.                 | `title`, `result`, `finding`, `location`, `evidence`, `recommendation`, `references` |
+| `task-summary`        | `taskSummary(summary, options)`             | Completed and remaining task summary. | `title`, `task`, `result`, `summary`, `completed`, `remaining`                       |
+| `agent-transcript`    | `agentTranscript(transcript, options)`      | User, agent, and tool transcript.     | `title`, `entries`                                                                   |
+| `confirmation-result` | `confirmationResult(confirmation, options)` | Confirmation outcome with detail.     | `title`, `state`, `action`, `item`, `detail`                                         |
+| `next-step-block`     | `nextStepBlock(nextStep, options)`          | Next-step guidance.                   | `title`, `next`, `reason`, `commands`, `alternatives`                                |
+| `compact-data-table`  | `compactDataTable(data, options)`           | Titled compact data table.            | `title`, `summary`, `columns`, `rows`                                                |
 
-Add the adapter directory to `PYTHONPATH`, then import the helper:
+For visual examples, run `cli-style gallery --section patterns`.
+
+The Bash adapter also exposes scalar convenience wrappers for per-script usage:
+
+| Bash helper                     | Renderer              | Arguments before render flags                                              |
+| ------------------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `cli_style_command_result`      | `command-result`      | `result`, `summary`, `command`, `exit_code`, `duration`, `detail`          |
+| `cli_style_audit_finding`       | `audit-finding`       | `result`, `finding`, `location`, `recommendation`, `evidence`, `reference` |
+| `cli_style_task_summary`        | `task-summary`        | `result`, `task`, `summary`, `completed`, `remaining`                      |
+| `cli_style_confirmation_result` | `confirmation-result` | `state`, `action`, `item`, `detail`                                        |
+| `cli_style_next_step_block`     | `next-step-block`     | `next`, `reason`, `command`, `alternative`                                 |
+
+Pass an empty string for optional positional fields you want to skip. Use `cli_style_render` or `cli_style_render_json` for aggregate reports, tables, transcripts, and multi-item arrays.
+
+### Pattern example
+
+JavaScript:
+
+```js
+import { createCliStyle, diagnosticReport } from "@lewishowles/cli-style";
+
+const ui = createCliStyle({
+	argv: process.argv.slice(2),
+	env: process.env,
+	stdout: process.stdout,
+});
+
+const output = diagnosticReport(
+	{
+		title: "Release checks",
+		checks: [
+			{
+				name: "README",
+				result: "success",
+			},
+			{
+				detail: "object-BmsQavd_.js over budget",
+				name: "Package size",
+				result: "failed",
+			},
+		],
+		findings: [
+			{
+				message: "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget",
+				result: "failed",
+			},
+		],
+		nextActions: ["Reduce package size, or raise the budget with a release-note-worthy reason."],
+	},
+	ui.options,
+);
+
+ui.print(output);
+```
+
+CLI:
 
 ```bash
-export PYTHONPATH="$(cli-style adapter-path python):$PYTHONPATH"
+cli-style render diagnostic-report --profile diagnostic <<'JSON'
+{
+  "title": "Release checks",
+  "checks": [
+    {
+      "name": "README",
+      "result": "success"
+    },
+    {
+      "name": "Package size",
+      "result": "failed",
+      "detail": "object-BmsQavd_.js over budget"
+    }
+  ],
+  "findings": [
+    {
+      "result": "failed",
+      "message": "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget"
+    }
+  ],
+  "nextActions": [
+    "Reduce package size, or raise the budget with a release-note-worthy reason."
+  ]
+}
+JSON
 ```
 
+Python:
+
 ```python
 from cli_style import render
 
 output = render(
-	"status",
+	"diagnostic-report",
 	{
-		"type": "success",
-		"label": "Build passed",
-		"detail": "184 tests",
+		"title": "Release checks",
+		"checks": [
+			{
+				"name": "README",
+				"result": "success",
+			},
+			{
+				"name": "Package size",
+				"result": "failed",
+				"detail": "object-BmsQavd_.js over budget",
+			},
+		],
+		"findings": [
+			{
+				"result": "failed",
+				"message": "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget",
+			},
+		],
+		"nextActions": [
+			"Reduce package size, or raise the budget with a release-note-worthy reason.",
+		],
 	},
 	profile="diagnostic",
 )
-
-print(output)
 ```
 
-Pass `binary=` when `cli-style` is not on `PATH`:
+## Reporter
 
-```python
-output = render(
-	"status",
+Use a reporter when a JavaScript script needs grouped output built over time.
+
+```js
+import { createReporter } from "@lewishowles/cli-style";
+
+const reporter = createReporter({
+	colour: false,
+});
+
+reporter.divider("Project setup", "Claude + Codex");
+reporter.group(
+	"Agent scripts",
+	[
+		{
+			label: "project-diagnostics.py",
+			result: "unchanged",
+		},
+		{
+			label: "repo-context.py",
+			result: "unchanged",
+		},
+	],
 	{
-		"type": "success",
-		"label": "Build passed",
+		summary: "2 already linked",
 	},
-	binary="/path/to/cli-style",
-	plain=True,
-)
+);
+reporter.status("success", "Done.");
+
+console.log(reporter.render());
 ```
 
+Use `reporter.divider()` for major phases. Use `reporter.section()` for a normal `info` status row inside a phase. Panels are for framed content blocks, not headings.
+
+Groups can include verbose detail rows when a caller opts in:
+
+```js
+const reporter = createReporter({
+	verbose: process.env.AGENTS_VERBOSE === "1",
+});
+```
+
+## Options and flags
+
+### JavaScript options
+
+Most renderers accept the same output options:
+
+| Option    | Purpose                                                                   |
+| --------- | ------------------------------------------------------------------------- |
+| `profile` | Output profile: `human`, `agent`, `diagnostic`, `ci`, `plain`, or `json`. |
+| `colour`  | Whether ANSI colour should be applied.                                    |
+| `unicode` | Whether Unicode symbols should be used.                                   |
+| `width`   | Available output width for renderers that adapt layout.                   |
+
+Use `createCliStyle()` to resolve these options from `argv`, `env`, `stdout`, CI, TTY, `NO_COLOR`, and terminal capability.
+
+### CLI and Bash flags
+
+| Flag                         | Purpose                                |
+| ---------------------------- | -------------------------------------- |
+| `--profile <name>`           | Render with a named profile.           |
+| `--plain`                    | Disable colour and Unicode decoration. |
+| `--no-colour` / `--no-color` | Disable ANSI colour.                   |
+| `--no-unicode`               | Use ASCII symbols.                     |
+| `--width <columns>`          | Override detected output width.        |
+
+`cli-style render` rejects `--json`. JSON profile behaviour is for library calls and machine-readable commands.
+
+### Python options
+
+| Argument     | Purpose                                          |
+| ------------ | ------------------------------------------------ |
+| `profile`    | Render with a named profile.                     |
+| `width`      | Override detected output width.                  |
+| `plain`      | Disable colour and Unicode decoration.           |
+| `no_colour`  | Disable ANSI colour.                             |
+| `no_unicode` | Use ASCII symbols.                               |
+| `binary`     | Path or command name for the `cli-style` binary. |
+| `extra_args` | Extra CLI arguments to pass through.             |
+
 ## Profiles
 
 | Profile      | Behaviour                                                                         |
@@ -217,11 +499,31 @@ output = render(
 | `plain`      | No ANSI, no Unicode dependency, simple text layout.                               |
 | `json`       | Machine-readable only; library calls return structured data unchanged.            |
 
+## Result types and tones
+
+Result types drive symbols, labels, priority, and semantic colour:
+
+| Result      | Label     | Unicode | ASCII | Tone      |
+| ----------- | --------- | ------- | ----- | --------- |
+| `success`   | Success   | `✓`     | `OK`  | `success` |
+| `info`      | Info      | `→`     | `>`   | `info`    |
+| `warning`   | Warning   | `⚠`     | `!`   | `warning` |
+| `partial`   | Partial   | `◐`     | `!`   | `warning` |
+| `unchanged` | Unchanged | `↪`     | `-`   | `muted`   |
+| `skipped`   | Skipped   | `–`     | `-`   | `muted`   |
+| `unknown`   | Unknown   | `?`     | `?`   | `muted`   |
+| `failed`    | Failed    | `×`     | `x`   | `danger`  |
+
+Tone values used by public APIs include `info`, `success`, `warning`, `danger`, and `muted`.
+
 ## Gallery
 
+Use the gallery to review current renderer output:
+
 ```bash
 cli-style gallery
 cli-style gallery no-colour
+cli-style gallery --section primitives
 cli-style gallery --section patterns
 cli-style gallery --fixture audit-finding
 cli-style gallery --profile agent
@@ -229,4 +531,4 @@ cli-style gallery --width 64
 cli-style gallery --variants
 ```
 
-Use the gallery to review current renderer output. Use `--interactive` to select a section or fixture with `fzf` when it is installed.
+Use `--interactive` to select a section or fixture with `fzf` when it is installed.

package/adapters/bash/cli-style.sh

@@ -41,6 +41,41 @@ cli_style_json_string() {
 	printf '"%s"' "$value"
 }
 
+# Escape Bash strings for a JSON string array.
+#
+# @param  {string}  ...
+#     String values to encode. Empty values are skipped.
+cli_style_json_string_array() {
+	local item
+	local separator=""
+
+	printf '['
+
+	for item in "$@"; do
+		if [[ "$item" != "" ]]; then
+			printf '%s' "$separator"
+			cli_style_json_string "$item"
+			separator=","
+		fi
+	done
+
+	printf ']'
+}
+
+# Render a Bash value as a JSON integer or null.
+#
+# @param  {string}  value
+#     Integer value to encode.
+cli_style_json_integer_or_null() {
+	local value="${1:-}"
+
+	if [[ "$value" =~ ^-?[0-9]+$ ]]; then
+		printf '%s' "$value"
+	else
+		printf 'null'
+	fi
+}
+
 # Render a JSON object through the shared cli-style command.
 #
 # @param  {string}  renderer
@@ -116,24 +151,57 @@ cli_style_status() {
 #     Row label.
 # @param  {string}  value
 #     Row value.
+# @param  {string}  result
+#     Optional result type before render flags.
 # @param  {string}  ...
 #     Render flags passed through to `cli-style render`.
 cli_style_row() {
 	local label="${1:-}"
 	local value="${2:-}"
+	local result=""
 	local json
 
-	if (($# >= 2)); then
+	if (($# >= 3)) && [[ "${3:-}" != --* ]]; then
+		result="${3:-}"
+		shift 3
+	elif (($# >= 2)); then
 		shift 2
 	else
 		set --
 	fi
 
-	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value")}"
+	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value"),\"result\":$(cli_style_json_string "$result")}"
 
 	cli_style_render_json row "$json" "$@"
 }
 
+# Render an inline span from Bash string values.
+#
+# @param  {string}  value
+#     Span text.
+# @param  {string}  tone
+#     Optional colour tone.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_span() {
+	local value="${1:-}"
+	local tone="info"
+	local json
+
+	if (($# >= 2)) && [[ "${2:-}" != --* ]]; then
+		tone="${2:-}"
+		shift 2
+	elif (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"value\":$(cli_style_json_string "$value"),\"tone\":$(cli_style_json_string "$tone")}"
+
+	cli_style_render_json span "$json" "$@"
+}
+
 # Render a divider from a Bash string value.
 #
 # @param  {string}  label
@@ -175,3 +243,168 @@ cli_style_hint() {
 
 	cli_style_render_json hint "$json" "$@"
 }
+
+# Render a command result pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  summary
+#     Summary line.
+# @param  {string}  command
+#     Optional command text.
+# @param  {string}  exit_code
+#     Optional integer exit code.
+# @param  {string}  duration
+#     Optional duration text.
+# @param  {string}  detail
+#     Optional detail line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_command_result() {
+	local result="${1:-}"
+	local summary="${2:-}"
+	local command="${3:-}"
+	local exit_code="${4:-}"
+	local duration="${5:-}"
+	local detail="${6:-}"
+	local json
+
+	if (($# >= 6)); then
+		shift 6
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"summary\":$(cli_style_json_string "$summary"),\"command\":$(cli_style_json_string "$command"),\"exitCode\":$(cli_style_json_integer_or_null "$exit_code"),\"duration\":$(cli_style_json_string "$duration"),\"details\":$(cli_style_json_string_array "$detail")}"
+
+	cli_style_render_json command-result "$json" "$@"
+}
+
+# Render an audit finding pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  finding
+#     Finding summary.
+# @param  {string}  location
+#     Optional source location.
+# @param  {string}  recommendation
+#     Optional recommendation text.
+# @param  {string}  evidence
+#     Optional evidence line.
+# @param  {string}  reference
+#     Optional reference line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_audit_finding() {
+	local result="${1:-}"
+	local finding="${2:-}"
+	local location="${3:-}"
+	local recommendation="${4:-}"
+	local evidence="${5:-}"
+	local reference="${6:-}"
+	local json
+
+	if (($# >= 6)); then
+		shift 6
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"finding\":$(cli_style_json_string "$finding"),\"location\":$(cli_style_json_string "$location"),\"recommendation\":$(cli_style_json_string "$recommendation"),\"evidence\":$(cli_style_json_string_array "$evidence"),\"references\":$(cli_style_json_string_array "$reference")}"
+
+	cli_style_render_json audit-finding "$json" "$@"
+}
+
+# Render a task summary pattern from Bash string values.
+#
+# @param  {string}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  task
+#     Task label.
+# @param  {string}  summary
+#     Optional summary detail.
+# @param  {string}  completed
+#     Optional completed item.
+# @param  {string}  remaining
+#     Optional remaining item.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_task_summary() {
+	local result="${1:-}"
+	local task="${2:-}"
+	local summary="${3:-}"
+	local completed="${4:-}"
+	local remaining="${5:-}"
+	local json
+
+	if (($# >= 5)); then
+		shift 5
+	else
+		set --
+	fi
+
+	json="{\"result\":$(cli_style_json_string "$result"),\"task\":$(cli_style_json_string "$task"),\"summary\":$(cli_style_json_string "$summary"),\"completed\":$(cli_style_json_string_array "$completed"),\"remaining\":$(cli_style_json_string_array "$remaining")}"
+
+	cli_style_render_json task-summary "$json" "$@"
+}
+
+# Render a confirmation result pattern from Bash string values.
+#
+# @param  {string}  state
+#     Confirmation state such as confirmed, cancelled, or skipped.
+# @param  {string}  action
+#     Action label.
+# @param  {string}  item
+#     Optional item label.
+# @param  {string}  detail
+#     Optional detail text.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_confirmation_result() {
+	local state="${1:-}"
+	local action="${2:-}"
+	local item="${3:-}"
+	local detail="${4:-}"
+	local json
+
+	if (($# >= 4)); then
+		shift 4
+	else
+		set --
+	fi
+
+	json="{\"state\":$(cli_style_json_string "$state"),\"action\":$(cli_style_json_string "$action"),\"item\":$(cli_style_json_string "$item"),\"detail\":$(cli_style_json_string "$detail")}"
+
+	cli_style_render_json confirmation-result "$json" "$@"
+}
+
+# Render a next-step block pattern from Bash string values.
+#
+# @param  {string}  next
+#     Next step text.
+# @param  {string}  reason
+#     Optional reason text.
+# @param  {string}  command
+#     Optional command line.
+# @param  {string}  alternative
+#     Optional alternative line.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_next_step_block() {
+	local next="${1:-}"
+	local reason="${2:-}"
+	local command="${3:-}"
+	local alternative="${4:-}"
+	local json
+
+	if (($# >= 4)); then
+		shift 4
+	else
+		set --
+	fi
+
+	json="{\"next\":$(cli_style_json_string "$next"),\"reason\":$(cli_style_json_string "$reason"),\"commands\":$(cli_style_json_string_array "$command"),\"alternatives\":$(cli_style_json_string_array "$alternative")}"
+
+	cli_style_render_json next-step-block "$json" "$@"
+}

package/adapters/python/cli_style.py

@@ -83,6 +83,221 @@ def render(
 	return result.stdout.rstrip("\n")
 
 
+# Render a result status line from Python values.
+#
+# @param  {str}  type
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  label
+#     Status label.
+# @param  {str}  detail
+#     Optional detail text.
+def status(
+	type: str,
+	label: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("status", {"type": type, "label": label, "detail": detail}, **kwargs)
+
+
+# Render a labelled value row from Python values.
+#
+# @param  {str}  label
+#     Row label.
+# @param  {str}  value
+#     Row value.
+# @param  {str}  result
+#     Optional result type for a symbol and tone.
+def row(
+	label: str,
+	value: str,
+	result: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("row", {"label": label, "value": value, "result": result}, **kwargs)
+
+
+# Render an inline span from Python values.
+#
+# @param  {str}  value
+#     Span text.
+# @param  {str}  tone
+#     Optional colour tone, defaulting to info.
+def span(
+	value: str,
+	tone: str = "info",
+	**kwargs: Any,
+) -> str:
+	return render("span", {"value": value, "tone": tone}, **kwargs)
+
+
+# Render a divider from a Python value.
+#
+# @param  {str}  label
+#     Optional divider label.
+def divider(
+	label: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("divider", {"label": label}, **kwargs)
+
+
+# Render a hint from a Python value.
+#
+# @param  {str}  message
+#     Hint message.
+def hint(
+	message: str,
+	**kwargs: Any,
+) -> str:
+	return render("hint", {"message": message}, **kwargs)
+
+
+# Render a command result pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  summary
+#     Summary line.
+# @param  {str}  command
+#     Optional command text.
+# @param  {int|None}  exit_code
+#     Optional integer exit code.
+# @param  {str}  duration
+#     Optional duration text.
+# @param  {str}  detail
+#     Optional detail line.
+def command_result(
+	result: str,
+	summary: str,
+	command: str = "",
+	exit_code: int | None = None,
+	duration: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("command-result", {
+		"result": result,
+		"summary": summary,
+		"command": command,
+		"exitCode": exit_code,
+		"duration": duration,
+		"details": [detail] if detail else [],
+	}, **kwargs)
+
+
+# Render an audit finding pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  finding
+#     Finding summary.
+# @param  {str}  location
+#     Optional source location.
+# @param  {str}  recommendation
+#     Optional recommendation text.
+# @param  {str}  evidence
+#     Optional evidence line.
+# @param  {str}  reference
+#     Optional reference line.
+def audit_finding(
+	result: str,
+	finding: str,
+	location: str = "",
+	recommendation: str = "",
+	evidence: str = "",
+	reference: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("audit-finding", {
+		"result": result,
+		"finding": finding,
+		"location": location,
+		"recommendation": recommendation,
+		"evidence": [evidence] if evidence else [],
+		"references": [reference] if reference else [],
+	}, **kwargs)
+
+
+# Render a task summary pattern from Python values.
+#
+# @param  {str}  result
+#     Result type such as success, failed, warning, or skipped.
+# @param  {str}  task
+#     Task label.
+# @param  {str}  summary
+#     Optional summary detail.
+# @param  {str}  completed
+#     Optional completed item.
+# @param  {str}  remaining
+#     Optional remaining item.
+def task_summary(
+	result: str,
+	task: str,
+	summary: str = "",
+	completed: str = "",
+	remaining: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("task-summary", {
+		"result": result,
+		"task": task,
+		"summary": summary,
+		"completed": [completed] if completed else [],
+		"remaining": [remaining] if remaining else [],
+	}, **kwargs)
+
+
+# Render a confirmation result pattern from Python values.
+#
+# @param  {str}  state
+#     Confirmation state such as confirmed, cancelled, or skipped.
+# @param  {str}  action
+#     Action label.
+# @param  {str}  item
+#     Optional item label.
+# @param  {str}  detail
+#     Optional detail text.
+def confirmation_result(
+	state: str,
+	action: str,
+	item: str = "",
+	detail: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("confirmation-result", {
+		"state": state,
+		"action": action,
+		"item": item,
+		"detail": detail,
+	}, **kwargs)
+
+
+# Render a next-step block pattern from Python values.
+#
+# @param  {str}  next_step
+#     Next step text.
+# @param  {str}  reason
+#     Optional reason text.
+# @param  {str}  command
+#     Optional command line.
+# @param  {str}  alternative
+#     Optional alternative line.
+def next_step_block(
+	next_step: str,
+	reason: str = "",
+	command: str = "",
+	alternative: str = "",
+	**kwargs: Any,
+) -> str:
+	return render("next-step-block", {
+		"next": next_step,
+		"reason": reason,
+		"commands": [command] if command else [],
+		"alternatives": [alternative] if alternative else [],
+	}, **kwargs)
+
+
 # Resolve a command name or executable path for subprocess use.
 #
 # @param  {str}  binary

package/package.json

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

package/src/cli/render-command.js

@@ -13,6 +13,7 @@ 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 { 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";
@@ -72,6 +73,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	span: (input, options) =>
+		span(input.value, input.tone, {
+			...input,
+			...options,
+		}),
 	status: (input, options) =>
 		status(input.type, input.detail, {
 			...input,

package/src/gallery/render-gallery.js

@@ -14,6 +14,7 @@ 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 { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
 import { table } from "../primitives/table.js";
@@ -676,7 +677,7 @@ function renderPrimitives(options) {
 		}),
 		"",
 		"Feedback",
-		hint("tone: info", options),
+		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
@@ -709,6 +710,11 @@ function renderPrimitives(options) {
 			...options,
 			labelWidth: 8,
 		}),
+		row("Bundle", "is 22.3 KB, above the 12.0 KB budget", {
+			...options,
+			labelWidth: 8,
+			result: resultTypes.FAILED,
+		}),
 	].join("\n");
 }
 

package/src/index.js

@@ -35,6 +35,7 @@ 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 { span } from "./primitives/span.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";
 export { table } from "./primitives/table.js";

package/src/primitives/row.js

@@ -1,4 +1,5 @@
 import { foreground } from "../formatters/ansi.js";
+import { getResultSymbol, getResultToken } from "../theme/results.js";
 
 // Row labels use the same subdued tone as table headers by default.
 const defaultLabelColour = "muted";
@@ -21,6 +22,8 @@ const defaultSeparator = "  ";
  *     Colour token for the label.
  * @param  {number}  options.labelWidth
  *     Minimum label width before the separator.
+ * @param  {string}  options.result
+ *     Optional semantic result state for the row.
  * @param  {string}  options.separator
  *     Text between label and value.
  * @param  {string}  options.valueColour
@@ -29,8 +32,10 @@ const defaultSeparator = "  ";
  *     Rendered row.
  */
 export function row(label, value = "", options = {}) {
-	const labelWidth = Math.max(label.length, options.labelWidth ?? 0);
-	const labelText = label.padEnd(labelWidth, " ");
+	const resultToken = resolveResultToken(options);
+	const displayLabel = renderDisplayLabel(label, resultToken, options);
+	const labelWidth = Math.max(displayLabel.length, options.labelWidth ?? 0);
+	const labelText = displayLabel.padEnd(labelWidth, " ");
 	const renderedLabel = renderLabel(labelText, options);
 
 	if (value === "") {
@@ -43,6 +48,44 @@ export function row(label, value = "", options = {}) {
 	return `${renderedLabel}${separator}${renderedValue}`;
 }
 
+/**
+ * Resolve the row's optional result token.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|null}
+ *     Result token when a row result is provided.
+ */
+function resolveResultToken(options) {
+	if (typeof options.result !== "string" || options.result === "") {
+		return null;
+	}
+
+	return getResultToken(options.result);
+}
+
+/**
+ * Render the visible row label, including any result symbol.
+ *
+ * @param  {string}  label
+ *     Label text to render.
+ * @param  {object|null}  resultToken
+ *     Optional result token.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Label text with any result prefix.
+ */
+function renderDisplayLabel(label, resultToken, options) {
+	if (resultToken === null) {
+		return label;
+	}
+
+	const symbol = getResultSymbol(options.result, options);
+
+	return `${symbol} ${label}`;
+}
+
 /**
  * Render a row label.
  *
@@ -58,7 +101,7 @@ function renderLabel(label, options) {
 		return label;
 	}
 
-	return foreground(label, options.labelColour ?? defaultLabelColour, options);
+	return foreground(label, getLabelColour(options), options);
 }
 
 /**
@@ -72,9 +115,55 @@ function renderLabel(label, options) {
  *     Rendered value.
  */
 function renderValue(value, options) {
-	if (options.colour !== true || options.valueColour === undefined) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	const colour = getValueColour(options);
+
+	if (colour === undefined) {
 		return value;
 	}
 
-	return foreground(value, options.valueColour, options);
+	return foreground(value, colour, options);
+}
+
+/**
+ * Resolve the colour token for the row label.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Colour token for the label.
+ */
+function getLabelColour(options) {
+	if (options.labelColour !== undefined) {
+		return options.labelColour;
+	}
+
+	if (typeof options.result === "string" && options.result !== "") {
+		return getResultToken(options.result).tone;
+	}
+
+	return defaultLabelColour;
+}
+
+/**
+ * Resolve the colour token for the row value.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string|undefined}
+ *     Colour token for the value.
+ */
+function getValueColour(options) {
+	if (options.valueColour !== undefined) {
+		return options.valueColour;
+	}
+
+	if (typeof options.result === "string" && options.result !== "") {
+		return getResultToken(options.result).tone;
+	}
+
+	return undefined;
 }

package/src/primitives/span.js

@@ -0,0 +1,33 @@
+import { foreground, style } from "../formatters/ansi.js";
+
+// Inline spans use the same informational tone as hints by default.
+const defaultTone = "info";
+
+// Inline emphasis should remain visible without forcing a block-level renderer.
+const defaultWeight = "bold";
+
+/**
+ * Render an inline text span.
+ *
+ * @param  {string}  value
+ *     Text to render.
+ * @param  {string}  tone
+ *     Colour tone for the span.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.weight
+ *     Optional ANSI text weight.
+ * @returns  {string}
+ *     Rendered span.
+ */
+export function span(value = "", tone = defaultTone, options = {}) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	const renderedValue = foreground(value, tone, options);
+
+	return style(renderedValue, options.weight ?? defaultWeight, options);
+}