@runa-cmd/help 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Runa CLI Contributors
+
+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/README.md

@@ -0,0 +1,279 @@
+# @runa-cmd/help
+
+Themeable help output for Runa CLIs with composable layout primitives.
+
+Three layers of customization: zero-config defaults, theme colors, or build your own layout with primitives.
+
+## Install
+
+```bash
+pnpm add @runa-cmd/help
+```
+
+> Peer dependencies: `@runa-cmd/core` and `zod ^4.0.0`.
+
+## Quick Start
+
+```ts
+import { defineCLI } from '@runa-cmd/core';
+import { helpPlugin } from '@runa-cmd/help';
+
+const cli = defineCLI({
+  meta: { name: 'my-tool', version: '1.0.0', description: 'My CLI tool' },
+  commands: { deploy, init },
+  plugins: [helpPlugin()],
+});
+
+cli.run();
+```
+
+```
+$ my-tool --help
+$ my-tool deploy --help
+```
+
+The plugin adds a `--help` / `-h` global flag. When triggered, it renders formatted help and exits.
+
+## Three Layers
+
+### Layer 1: Zero Config
+
+Just add the plugin — sensible defaults with auto-detected terminal colors:
+
+```ts
+plugins: [helpPlugin()]
+```
+
+### Layer 2: Custom Theme
+
+Override any of the 6 color slots:
+
+```ts
+plugins: [
+  helpPlugin({
+    theme: {
+      primary: '#00BFFF',   // Headings, command names
+      secondary: '#FF6B6B', // Flags, options
+      muted: 'dim',         // Descriptions, defaults
+      error: '#FF0000',     // Error messages
+      warning: '#FFAA00',   // Deprecation notices
+      success: '#00FF00',   // Success indicators
+    },
+  }),
+]
+```
+
+Colors are automatically downsampled to match terminal capabilities: truecolor, 256-color, 16-color, or no color (`NO_COLOR` respected).
+
+### Layer 3: Custom Renderer
+
+Full control — use the layout primitives to build your own help output:
+
+```ts
+import { helpPlugin, box, styled, table, join, bold, fg } from '@runa-cmd/help';
+
+plugins: [
+  helpPlugin({
+    render({ schema, theme, termWidth }) {
+      return join.vertical([
+        box({
+          content: `${bold(schema.meta.name)} v${schema.meta.version}`,
+          border: 'rounded',
+          borderColor: theme.primary,
+        }),
+        styled(schema.meta.description ?? '', { color: theme.muted }),
+        table(
+          schema.commands.map((cmd) => [
+            styled(cmd.name, { bold: true, color: theme.primary }),
+            styled(cmd.description, { color: theme.muted }),
+          ]),
+          { headers: ['Command', 'Description'] },
+        ),
+      ]);
+    },
+  }),
+]
+```
+
+## Layout Primitives
+
+All primitives return a `Block` (a plain string, possibly with ANSI codes). They're composable — the output of one can be the input to another.
+
+### `box(options)`
+
+Renders a bordered container with word wrapping.
+
+```ts
+import { box } from '@runa-cmd/help';
+
+box({
+  content: 'Hello from a box!',
+  border: 'rounded',        // 'single' | 'double' | 'rounded' | 'none'
+  borderColor: '#7D56F4',   // Hex or named ANSI color
+  padding: [1, 2],          // [vertical, horizontal] or [top, right, bottom, left]
+  width: 40,                // Fixed width (auto if omitted)
+});
+```
+
+### `styled(text, options)`
+
+Applies text formatting. Does not word-wrap.
+
+```ts
+import { styled } from '@runa-cmd/help';
+
+styled('Important!', {
+  bold: true,
+  italic: true,
+  color: '#FF6B6B',
+  padding: [0, 1],
+});
+```
+
+### `columns(blocks, options)`
+
+Distributes blocks evenly across terminal width:
+
+```ts
+import { columns, styled } from '@runa-cmd/help';
+
+columns([
+  styled('Left column'),
+  styled('Right column'),
+], { gap: 4 });
+```
+
+### `table(rows, options)`
+
+Renders a 2D array as aligned columns with automatic width sizing:
+
+```ts
+import { table, styled } from '@runa-cmd/help';
+
+table([
+  [styled('--verbose', { bold: true }), 'Enable verbose output'],
+  [styled('--env', { bold: true }),     'Target environment'],
+], {
+  padding: [0, 2],
+  headers: ['Flag', 'Description'],
+});
+```
+
+### `list(items, options)`
+
+Renders a bulleted list:
+
+```ts
+import { list } from '@runa-cmd/help';
+
+list(['First item', 'Second item', 'Third item'], {
+  bullet: '>', // Default: '•'
+  indent: 4,   // Default: 2
+});
+```
+
+### `join.vertical(blocks, options)` / `join.horizontal(blocks, options)`
+
+Composes blocks together:
+
+```ts
+import { join, box, styled } from '@runa-cmd/help';
+
+// Stack vertically with gap
+join.vertical([
+  styled('Header', { bold: true }),
+  styled('Body text'),
+  styled('Footer', { dim: true }),
+], { gap: 1 });
+
+// Place side by side
+join.horizontal([
+  box({ content: 'Left', border: 'single' }),
+  box({ content: 'Right', border: 'single' }),
+], { gap: 2, align: 'top' }); // 'top' | 'center' | 'bottom'
+```
+
+## ANSI Utilities
+
+Low-level text formatting functions:
+
+```ts
+import {
+  bold, dim, italic, underline, // Text decorators
+  fg, reset, strip,              // Color and cleanup
+  visibleWidth,                  // Width without ANSI codes
+  downsampleColor,               // Hex → terminal-appropriate ANSI
+  detectColorDepth,              // Terminal color capability
+  detectTermWidth,               // Terminal width (default 80)
+  getRenderContext,              // Lazy-detected { colorDepth, termWidth }
+  resetRenderContext,            // Clear cached detection (for tests)
+} from '@runa-cmd/help';
+```
+
+### Color Downsampling
+
+Colors automatically adapt to terminal capabilities:
+
+```ts
+import { downsampleColor } from '@runa-cmd/help';
+
+downsampleColor('#7D56F4', 'truecolor'); // '\x1b[38;2;125;86;244m'
+downsampleColor('#7D56F4', '256');        // '\x1b[38;5;99m'
+downsampleColor('#7D56F4', '16');         // '\x1b[35m' (magenta)
+downsampleColor('#7D56F4', 'none');       // '' (no color)
+```
+
+Respects `NO_COLOR`, `FORCE_COLOR`, and `COLORTERM` environment variables.
+
+## Theme
+
+The default theme:
+
+```ts
+import { defaultTheme, resolveTheme } from '@runa-cmd/help';
+
+// defaultTheme = {
+//   primary: '#7D56F4',    // Lipgloss purple
+//   secondary: '#FF6B6B',
+//   muted: 'dim',
+//   error: '#FF0000',
+//   warning: '#FFAA00',
+//   success: '#00FF00',
+// }
+
+// Resolve a partial override to ANSI-ready strings:
+const resolved = resolveTheme({ primary: '#00BFFF' }, getRenderContext());
+// resolved.primary = '\x1b[38;2;0;191;255m' (on truecolor terminals)
+```
+
+## Default Renderer
+
+The built-in renderer (`defaultRenderer`) produces output with these sections (each skipped if empty):
+
+1. **Header** — Name, version, description
+2. **Usage** — `name [command] [options]`
+3. **Arguments** — Positional args table
+4. **Options** — Named options table, grouped by `group` metadata
+5. **Commands** — Subcommands table
+
+The renderer is subcommand-aware: `my-tool deploy --help` shows help for the `deploy` command specifically.
+
+## Types
+
+```ts
+import type {
+  HelpPluginOptions,
+  RenderFnCtx,
+  Theme, ResolvedTheme,
+  Block,
+  RenderContext, ColorDepth,
+  BoxOptions, StyledOptions, ColumnsOptions,
+  TableOptions, ListOptions,
+  VerticalJoinOptions, HorizontalJoinOptions, HorizontalAlign,
+  BorderStyle,
+} from '@runa-cmd/help';
+```
+
+## License
+
+MIT

package/dist/ansi/codes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @runa-cmd/help — ANSI escape code builders
+ *
+ * Low-level helpers for applying text styles via ANSI escape sequences.
+ * These produce raw escape strings — color downsampling is handled by downsample.ts.
+ */
+/** ANSI reset — clears all styles */
+export declare const reset = "\u001B[0m";
+/** Apply bold style */
+export declare function bold(text: string): string;
+/** Apply dim style */
+export declare function dim(text: string): string;
+/** Apply italic style */
+export declare function italic(text: string): string;
+/** Apply underline style */
+export declare function underline(text: string): string;
+/**
+ * Apply foreground color.
+ * Accepts a pre-computed ANSI escape string (from downsample.ts).
+ * If empty string (no color mode), returns text unchanged.
+ */
+export declare function fg(text: string, ansiColor: string): string;
+/**
+ * Strip all ANSI escape codes from a string.
+ * Useful for raw mode testing and width calculations.
+ */
+export declare function strip(text: string): string;
+/**
+ * Get the visible width of a string (excluding ANSI codes).
+ * Note: does NOT handle Unicode wide characters (CJK, emoji) — deferred to future package.
+ */
+export declare function visibleWidth(text: string): number;
+//# sourceMappingURL=codes.d.ts.map

package/dist/ansi/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/ansi/codes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qCAAqC;AACrC,eAAO,MAAM,KAAK,cAAa,CAAC;AAEhC,uBAAuB;AACvB,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,sBAAsB;AACtB,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExC;AAED,yBAAyB;AACzB,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,4BAA4B;AAC5B,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG1D;AAQD;;;GAGG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/ansi/codes.js

@@ -0,0 +1,54 @@
+/**
+ * @runa-cmd/help — ANSI escape code builders
+ *
+ * Low-level helpers for applying text styles via ANSI escape sequences.
+ * These produce raw escape strings — color downsampling is handled by downsample.ts.
+ */
+const ESC = '\x1b[';
+/** ANSI reset — clears all styles */
+export const reset = `${ESC}0m`;
+/** Apply bold style */
+export function bold(text) {
+    return `${ESC}1m${text}${reset}`;
+}
+/** Apply dim style */
+export function dim(text) {
+    return `${ESC}2m${text}${reset}`;
+}
+/** Apply italic style */
+export function italic(text) {
+    return `${ESC}3m${text}${reset}`;
+}
+/** Apply underline style */
+export function underline(text) {
+    return `${ESC}4m${text}${reset}`;
+}
+/**
+ * Apply foreground color.
+ * Accepts a pre-computed ANSI escape string (from downsample.ts).
+ * If empty string (no color mode), returns text unchanged.
+ */
+export function fg(text, ansiColor) {
+    if (!ansiColor)
+        return text;
+    return `${ansiColor}${text}${reset}`;
+}
+// ─── ANSI stripping regex ───────────────────────────────────
+// Matches all ANSI escape sequences (CSI sequences + OSC sequences)
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape detection requires control characters
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/**
+ * Strip all ANSI escape codes from a string.
+ * Useful for raw mode testing and width calculations.
+ */
+export function strip(text) {
+    return text.replace(ANSI_RE, '');
+}
+/**
+ * Get the visible width of a string (excluding ANSI codes).
+ * Note: does NOT handle Unicode wide characters (CJK, emoji) — deferred to future package.
+ */
+export function visibleWidth(text) {
+    return strip(text).length;
+}
+//# sourceMappingURL=codes.js.map

package/dist/ansi/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../src/ansi/codes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,GAAG,GAAG,OAAO,CAAC;AAEpB,qCAAqC;AACrC,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC;AAEhC,uBAAuB;AACvB,MAAM,UAAU,IAAI,CAAC,IAAY;IAChC,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,KAAK,EAAE,CAAC;AAClC,CAAC;AAED,sBAAsB;AACtB,MAAM,UAAU,GAAG,CAAC,IAAY;IAC/B,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,KAAK,EAAE,CAAC;AAClC,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,MAAM,CAAC,IAAY;IAClC,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,KAAK,EAAE,CAAC;AAClC,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,SAAS,CAAC,IAAY;IACrC,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,EAAE,CAAC,IAAY,EAAE,SAAiB;IACjD,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC;AACtC,CAAC;AAED,+DAA+D;AAE/D,oEAAoE;AACpE,6GAA6G;AAC7G,MAAM,OAAO,GAAG,iBAAiB,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAC3B,CAAC"}

package/dist/ansi/detect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @runa-cmd/help — Terminal detection
+ *
+ * Detects terminal color depth and width from environment variables
+ * and process.stdout capabilities.
+ */
+import type { ColorDepth, RenderContext } from '../types.js';
+/**
+ * Detect terminal color depth from env vars and stdout capabilities.
+ *
+ * Priority order:
+ * 1. NO_COLOR → 'none'
+ * 2. FORCE_COLOR → minimum '16'
+ * 3. COLORTERM=truecolor|24bit → 'truecolor'
+ * 4. TERM=xterm-256color → '256'
+ * 5. process.stdout.hasColors(256) → '256'
+ * 6. process.stdout.hasColors(16) → '16'
+ * 7. fallback → 'none'
+ */
+export declare function detectColorDepth(): ColorDepth;
+/**
+ * Detect terminal width in columns.
+ * Falls back to 80 if unavailable (e.g. piped output).
+ */
+export declare function detectTermWidth(): number;
+/**
+ * Get the current RenderContext (lazy singleton — auto-detected once).
+ * All primitives use this internally when no explicit ctx is passed.
+ */
+export declare function getRenderContext(): RenderContext;
+/**
+ * Reset the cached RenderContext.
+ * Used in tests to force re-detection.
+ */
+export declare function resetRenderContext(): void;
+//# sourceMappingURL=detect.d.ts.map

package/dist/ansi/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/ansi/detect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAyC7C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/ansi/detect.js

@@ -0,0 +1,82 @@
+/**
+ * Detect terminal color depth from env vars and stdout capabilities.
+ *
+ * Priority order:
+ * 1. NO_COLOR → 'none'
+ * 2. FORCE_COLOR → minimum '16'
+ * 3. COLORTERM=truecolor|24bit → 'truecolor'
+ * 4. TERM=xterm-256color → '256'
+ * 5. process.stdout.hasColors(256) → '256'
+ * 6. process.stdout.hasColors(16) → '16'
+ * 7. fallback → 'none'
+ */
+export function detectColorDepth() {
+    const env = process.env;
+    // NO_COLOR takes absolute priority (https://no-color.org/)
+    if (env.NO_COLOR !== undefined) {
+        return 'none';
+    }
+    // FORCE_COLOR forces color output (e.g. in CI or piped contexts)
+    const forceColor = env.FORCE_COLOR;
+    if (forceColor !== undefined) {
+        if (forceColor === '3')
+            return 'truecolor';
+        if (forceColor === '2')
+            return '256';
+        return '16';
+    }
+    // Non-TTY (piped) → no color unless FORCE_COLOR was set (handled above)
+    if (!process.stdout.isTTY) {
+        return 'none';
+    }
+    // COLORTERM for truecolor detection
+    const colorTerm = env.COLORTERM;
+    if (colorTerm === 'truecolor' || colorTerm === '24bit') {
+        return 'truecolor';
+    }
+    // TERM for 256 color detection
+    const term = env.TERM;
+    if (term?.includes('256color')) {
+        return '256';
+    }
+    // process.stdout.hasColors() as additional signal
+    if (typeof process.stdout.hasColors === 'function') {
+        if (process.stdout.hasColors(16_777_216))
+            return 'truecolor';
+        if (process.stdout.hasColors(256))
+            return '256';
+        if (process.stdout.hasColors(16))
+            return '16';
+    }
+    return 'none';
+}
+/**
+ * Detect terminal width in columns.
+ * Falls back to 80 if unavailable (e.g. piped output).
+ */
+export function detectTermWidth() {
+    return process.stdout.columns ?? 80;
+}
+// ─── Lazy Singleton ─────────────────────────────────────────
+let _cached;
+/**
+ * Get the current RenderContext (lazy singleton — auto-detected once).
+ * All primitives use this internally when no explicit ctx is passed.
+ */
+export function getRenderContext() {
+    if (!_cached) {
+        _cached = {
+            colorDepth: detectColorDepth(),
+            termWidth: detectTermWidth(),
+        };
+    }
+    return _cached;
+}
+/**
+ * Reset the cached RenderContext.
+ * Used in tests to force re-detection.
+ */
+export function resetRenderContext() {
+    _cached = undefined;
+}
+//# sourceMappingURL=detect.js.map

package/dist/ansi/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/ansi/detect.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAExB,2DAA2D;IAC3D,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,iEAAiE;IACjE,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,CAAC;IACnC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,UAAU,KAAK,GAAG;YAAE,OAAO,WAAW,CAAC;QAC3C,IAAI,UAAU,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QACrC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,wEAAwE;IACxE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC;IACf,CAAC;IAED,oCAAoC;IACpC,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IAChC,IAAI,SAAS,KAAK,WAAW,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QACxD,OAAO,WAAW,CAAC;IACpB,CAAC;IAED,+BAA+B;IAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,kDAAkD;IAClD,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;YAAE,OAAO,WAAW,CAAC;QAC7D,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/C,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,+DAA+D;AAE/D,IAAI,OAAkC,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,GAAG;YACT,UAAU,EAAE,gBAAgB,EAAE;YAC9B,SAAS,EAAE,eAAe,EAAE;SAC5B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IACjC,OAAO,GAAG,SAAS,CAAC;AACrB,CAAC"}

package/dist/ansi/downsample.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @runa-cmd/help — Color downsampling
+ *
+ * Converts hex colors (#RRGGBB) to the appropriate ANSI escape sequence
+ * based on the terminal's color depth. Named attributes (e.g. 'dim')
+ * pass through unchanged.
+ *
+ * ANSI 256 palette: 6×6×6 RGB cube (indices 16-231) + 24 grayscale (232-255).
+ * Computed programmatically at module load, not hardcoded.
+ */
+import type { ColorDepth } from '../types.js';
+/**
+ * Downsample a color to an ANSI escape string based on terminal color depth.
+ *
+ * - Hex colors (#RRGGBB) → converted to nearest ANSI code for the depth
+ * - Named attributes ('dim', 'red', etc.) → passed through as ANSI escape
+ * - If depth is 'none' → returns '' (empty, no color)
+ *
+ * Returns the ANSI escape STRING (without reset) — caller wraps text with it.
+ */
+export declare function downsampleColor(color: string, depth: ColorDepth): string;
+//# sourceMappingURL=downsample.d.ts.map

package/dist/ansi/downsample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downsample.d.ts","sourceRoot":"","sources":["../../src/ansi/downsample.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8G9C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAiCxE"}

package/dist/ansi/downsample.js

@@ -0,0 +1,126 @@
+// ─── Hex Parsing ────────────────────────────────────────────
+const HEX_RE = /^#([0-9a-f]{6})$/i;
+function parseHex(hex) {
+    const match = HEX_RE.exec(hex);
+    if (!match)
+        return null;
+    const val = Number.parseInt(match[1], 16);
+    return [(val >> 16) & 0xff, (val >> 8) & 0xff, val & 0xff];
+}
+const PALETTE_256 = [];
+// Standard 16 colors (indices 0-15)
+const STANDARD_16 = [
+    [0, 0, 0], // 0: black
+    [128, 0, 0], // 1: red
+    [0, 128, 0], // 2: green
+    [128, 128, 0], // 3: yellow
+    [0, 0, 128], // 4: blue
+    [128, 0, 128], // 5: magenta
+    [0, 128, 128], // 6: cyan
+    [192, 192, 192], // 7: white
+    [128, 128, 128], // 8: bright black (gray)
+    [255, 0, 0], // 9: bright red
+    [0, 255, 0], // 10: bright green
+    [255, 255, 0], // 11: bright yellow
+    [0, 0, 255], // 12: bright blue
+    [255, 0, 255], // 13: bright magenta
+    [0, 255, 255], // 14: bright cyan
+    [255, 255, 255], // 15: bright white
+];
+// Build standard 16
+for (let i = 0; i < 16; i++) {
+    const [r, g, b] = STANDARD_16[i];
+    PALETTE_256.push({ r, g, b, index: i });
+}
+// 6×6×6 RGB cube (indices 16-231)
+const CUBE_STEPS = [0, 95, 135, 175, 215, 255];
+for (let ri = 0; ri < 6; ri++) {
+    for (let gi = 0; gi < 6; gi++) {
+        for (let bi = 0; bi < 6; bi++) {
+            PALETTE_256.push({
+                r: CUBE_STEPS[ri],
+                g: CUBE_STEPS[gi],
+                b: CUBE_STEPS[bi],
+                index: 16 + ri * 36 + gi * 6 + bi,
+            });
+        }
+    }
+}
+// Grayscale ramp (indices 232-255)
+for (let i = 0; i < 24; i++) {
+    const v = 8 + i * 10;
+    PALETTE_256.push({ r: v, g: v, b: v, index: 232 + i });
+}
+// ─── Nearest Color Search ───────────────────────────────────
+function nearestIndex(r, g, b, palette) {
+    let bestDist = Number.POSITIVE_INFINITY;
+    let bestIndex = 0;
+    for (const entry of palette) {
+        const dr = r - entry.r;
+        const dg = g - entry.g;
+        const db = b - entry.b;
+        const dist = dr * dr + dg * dg + db * db;
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestIndex = entry.index;
+        }
+    }
+    return bestIndex;
+}
+// ─── Named ANSI Attributes ─────────────────────────────────
+const ESC = '\x1b[';
+const NAMED_ATTRS = {
+    bold: `${ESC}1m`,
+    dim: `${ESC}2m`,
+    italic: `${ESC}3m`,
+    underline: `${ESC}4m`,
+    red: `${ESC}31m`,
+    green: `${ESC}32m`,
+    yellow: `${ESC}33m`,
+    blue: `${ESC}34m`,
+    magenta: `${ESC}35m`,
+    cyan: `${ESC}36m`,
+    white: `${ESC}37m`,
+};
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Downsample a color to an ANSI escape string based on terminal color depth.
+ *
+ * - Hex colors (#RRGGBB) → converted to nearest ANSI code for the depth
+ * - Named attributes ('dim', 'red', etc.) → passed through as ANSI escape
+ * - If depth is 'none' → returns '' (empty, no color)
+ *
+ * Returns the ANSI escape STRING (without reset) — caller wraps text with it.
+ */
+export function downsampleColor(color, depth) {
+    if (depth === 'none')
+        return '';
+    // Named attribute passthrough
+    const named = NAMED_ATTRS[color];
+    if (named)
+        return named;
+    // Parse hex
+    const rgb = parseHex(color);
+    if (!rgb)
+        return '';
+    const [r, g, b] = rgb;
+    switch (depth) {
+        case 'truecolor':
+            return `${ESC}38;2;${r};${g};${b}m`;
+        case '256': {
+            // Search full 256 palette (16 + cube + grayscale)
+            const idx = nearestIndex(r, g, b, PALETTE_256);
+            return `${ESC}38;5;${idx}m`;
+        }
+        case '16': {
+            // Search only the standard 16 colors
+            const idx = nearestIndex(r, g, b, PALETTE_256.slice(0, 16));
+            if (idx >= 8) {
+                // Bright colors: use 90-97 range
+                return `${ESC}${90 + (idx - 8)}m`;
+            }
+            return `${ESC}${30 + idx}m`;
+        }
+    }
+}
+//# sourceMappingURL=downsample.js.map