tunectl 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunectl",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Battle-tested VPS performance tuning toolkit for Ubuntu 24.04 LTS",
   "bin": {
     "tunectl": "./bin/tunectl"

package/scripts/benchmark.sh

@@ -96,41 +96,35 @@ while [[ $# -gt 0 ]]; do
 done
 
 # -------------------------------------------------------
-# Check dependencies
+# Check dependencies — graceful degradation
+# Sets HAS_SYSBENCH and HAS_FIO globals (0=available, 1=missing)
+# Exits 1 only if BOTH tools are missing
 # -------------------------------------------------------
+HAS_SYSBENCH=1
+HAS_FIO=1
+
 check_dependencies() {
   local missing=()
 
-  if ! command -v sysbench &>/dev/null; then
+  if command -v sysbench &>/dev/null; then
+    HAS_SYSBENCH=0
+  else
     missing+=("sysbench")
+    echo "▲  sysbench not found. Install: sudo apt install sysbench" >&2
   fi
 
-  if ! command -v fio &>/dev/null; then
+  if command -v fio &>/dev/null; then
+    HAS_FIO=0
+  else
     missing+=("fio")
+    echo "▲  fio not found. Install: sudo apt install fio" >&2
   fi
 
-  if [[ ${#missing[@]} -gt 0 ]]; then
-    echo "Installing missing dependencies: ${missing[*]}..." >&2
-    if command -v apt-get &>/dev/null; then
-      if [[ $EUID -eq 0 ]]; then
-        apt-get update -qq >/dev/null 2>&1
-        apt-get install -y -qq "${missing[@]}" >/dev/null 2>&1
-      else
-        echo "Error: Cannot install ${missing[*]} without root. Run: sudo apt-get install ${missing[*]}" >&2
-        exit 1
-      fi
-    else
-      echo "Error: apt-get not available. Install manually: ${missing[*]}" >&2
-      exit 1
-    fi
-
-    # Verify installation
-    for tool in "${missing[@]}"; do
-      if ! command -v "$tool" &>/dev/null; then
-        echo "Error: Failed to install $tool" >&2
-        exit 1
-      fi
-    done
+  if [[ ${#missing[@]} -eq 2 ]]; then
+    echo "" >&2
+    echo "Error: No benchmark tools available. Install at least one:" >&2
+    echo "  sudo apt install sysbench fio" >&2
+    exit 1
   fi
 }
 
@@ -327,37 +321,53 @@ except Exception:
 # -------------------------------------------------------
 # Run all benchmarks and collect results
 # Returns results as key=value pairs
-# Exits 1 if any benchmark command failed (ERROR sentinel)
+# Skips benchmarks for missing tools (uses HAS_SYSBENCH/HAS_FIO)
+# Exits 1 if any executed benchmark command failed (ERROR sentinel)
 # -------------------------------------------------------
 run_all_benchmarks() {
   local failed_benchmarks=()
+  local step=0 total=0
 
-  echo "Running benchmarks..." >&2
-
-  echo "  [1/5] CPU single-thread..." >&2
-  local cpu_st
-  cpu_st=$(run_cpu_single)
-  [[ "$cpu_st" == "ERROR" ]] && failed_benchmarks+=("CPU single-thread")
+  # Count total benchmarks to run
+  [[ $HAS_SYSBENCH -eq 0 ]] && total=$((total + 4))
+  [[ $HAS_FIO -eq 0 ]] && total=$((total + 1))
 
-  echo "  [2/5] CPU multi-thread..." >&2
-  local cpu_mt
-  cpu_mt=$(run_cpu_multi)
-  [[ "$cpu_mt" == "ERROR" ]] && failed_benchmarks+=("CPU multi-thread")
-
-  echo "  [3/5] Memory read..." >&2
-  local mem_read
-  mem_read=$(run_mem_read)
-  [[ "$mem_read" == "ERROR" ]] && failed_benchmarks+=("Memory read")
+  echo "Running benchmarks..." >&2
 
-  echo "  [4/5] Memory write..." >&2
-  local mem_write
-  mem_write=$(run_mem_write)
-  [[ "$mem_write" == "ERROR" ]] && failed_benchmarks+=("Memory write")
+  local cpu_st="SKIPPED" cpu_mt="SKIPPED" mem_read="SKIPPED" mem_write="SKIPPED" disk_rr="SKIPPED"
+
+  if [[ $HAS_SYSBENCH -eq 0 ]]; then
+    step=$((step + 1))
+    echo "  [$step/$total] CPU single-thread..." >&2
+    cpu_st=$(run_cpu_single)
+    [[ "$cpu_st" == "ERROR" ]] && failed_benchmarks+=("CPU single-thread")
+
+    step=$((step + 1))
+    echo "  [$step/$total] CPU multi-thread..." >&2
+    cpu_mt=$(run_cpu_multi)
+    [[ "$cpu_mt" == "ERROR" ]] && failed_benchmarks+=("CPU multi-thread")
+
+    step=$((step + 1))
+    echo "  [$step/$total] Memory read..." >&2
+    mem_read=$(run_mem_read)
+    [[ "$mem_read" == "ERROR" ]] && failed_benchmarks+=("Memory read")
+
+    step=$((step + 1))
+    echo "  [$step/$total] Memory write..." >&2
+    mem_write=$(run_mem_write)
+    [[ "$mem_write" == "ERROR" ]] && failed_benchmarks+=("Memory write")
+  else
+    echo "  Skipping sysbench tests (sysbench not installed)" >&2
+  fi
 
-  echo "  [5/5] Disk random read..." >&2
-  local disk_rr
-  disk_rr=$(run_disk_rand_read)
-  [[ "$disk_rr" == "ERROR" ]] && failed_benchmarks+=("Disk random read")
+  if [[ $HAS_FIO -eq 0 ]]; then
+    step=$((step + 1))
+    echo "  [$step/$total] Disk random read..." >&2
+    disk_rr=$(run_disk_rand_read)
+    [[ "$disk_rr" == "ERROR" ]] && failed_benchmarks+=("Disk random read")
+  else
+    echo "  Skipping fio tests (fio not installed)" >&2
+  fi
 
   echo "Done." >&2
 
@@ -406,8 +416,10 @@ display_results() {
       disk_rand_read_iops)   label="Disk Random Read" ;;
       *)                     label="$metric" ;;
     esac
-    # Show N/A for ERROR values instead of the sentinel
-    if [[ "$value" == "ERROR" ]]; then
+    # Show N/A for ERROR values, show skipped for SKIPPED
+    if [[ "$value" == "SKIPPED" ]]; then
+      printf "  %-30s %15s %s\n" "$label" "N/A" "(skipped)"
+    elif [[ "$value" == "ERROR" ]]; then
       printf "  %-30s %15s %s\n" "$label" "N/A" "(failed)"
     else
       printf "  %-30s %15s %s\n" "$label" "$value" "$unit"
@@ -442,8 +454,8 @@ for line in sys.stdin:
     parts = line.strip().split(None, 2)
     if len(parts) >= 2:
         metric = parts[0]
-        if parts[1] == 'ERROR':
-            results[metric] = {'value': None, 'unit': 'ERROR'}
+        if parts[1] in ('ERROR', 'SKIPPED'):
+            results[metric] = {'value': None, 'unit': parts[1]}
             continue
         value = float(parts[1])
         unit = parts[2] if len(parts) > 2 else ''
@@ -476,8 +488,8 @@ try:
             val = data['value']
             unit = data.get('unit', '')
             # Handle ERROR metrics saved with None value
-            if val is None or unit == 'ERROR':
-                print(f'{metric} ERROR {unit}')
+            if val is None or unit in ('ERROR', 'SKIPPED'):
+                print(f'{metric} {unit} {unit}')
             else:
                 print(f'{metric} {val} {unit}')
         else:
@@ -523,16 +535,16 @@ display_comparison() {
       *)                     label="$metric" ;;
     esac
 
-    # Handle ERROR in current value — show N/A instead of bogus computation
-    if [[ "$value" == "ERROR" ]]; then
+    # Handle SKIPPED or ERROR in current value — show N/A instead of bogus computation
+    if [[ "$value" == "SKIPPED" || "$value" == "ERROR" ]]; then
       local bval="${baseline_vals[$metric]:-N/A}"
       printf "  %-25s %12s %12s %12s %8s\n" "$label" "$bval" "N/A" "N/A" "N/A"
       continue
     fi
 
     local bval="${baseline_vals[$metric]:-}"
-    # Handle missing or ERROR baseline — show N/A for comparison
-    if [[ -z "$bval" || "$bval" == "None" || "$bval" == "ERROR" ]]; then
+    # Handle missing, ERROR, or SKIPPED baseline — show N/A for comparison
+    if [[ -z "$bval" || "$bval" == "None" || "$bval" == "ERROR" || "$bval" == "SKIPPED" ]]; then
       printf "  %-25s %12s %12s %12s %8s\n" "$label" "N/A" "$value" "N/A" "N/A"
       continue
     fi

package/tunectl/__init__.py

@@ -1,3 +1,3 @@
 """tunectl — VPS Performance Tuning Toolkit."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"

package/tunectl/cli.py

@@ -18,6 +18,7 @@ import subprocess
 import sys
 
 from tunectl import __version__
+from tunectl.ui import print_banner, Pipeline
 
 # Valid tier choices for plan/apply
 VALID_TIERS = ("conservative", "balanced", "aggressive")
@@ -129,7 +130,8 @@ def _format_discover_output(data: dict) -> str:
         ("Virt type", data.get("virt_type", "unknown")),
     ]
     for label, value in info_fields:
-        lines.append(f"  {_cyan(label + ':'):>30s}  {value}")
+        padded = f"{label + ':':>28}"
+        lines.append(f"  {_cyan(padded)}  {value}")
 
     # --- Swap status ---
     lines.append("")
@@ -141,11 +143,15 @@ def _format_discover_output(data: dict) -> str:
     swap_total = data.get("swap_total_mb", 0)
 
     if swap_configured:
-        lines.append(f"  {_cyan('Configured:'):>30s}  {_green('yes')}")
-        lines.append(f"  {_cyan('Type:'):>30s}  {swap_type}")
-        lines.append(f"  {_cyan('Total:'):>30s}  {swap_total} MB")
+        padded = f"{'Configured:':>28}"
+        lines.append(f"  {_cyan(padded)}  {_green('yes')}")
+        padded = f"{'Type:':>28}"
+        lines.append(f"  {_cyan(padded)}  {swap_type}")
+        padded = f"{'Total:':>28}"
+        lines.append(f"  {_cyan(padded)}  {swap_total} MB")
     else:
-        lines.append(f"  {_cyan('Configured:'):>30s}  {_yellow('no')}")
+        padded = f"{'Configured:':>28}"
+        lines.append(f"  {_cyan(padded)}  {_yellow('no')}")
 
     # --- Key sysctl values ---
     sysctl = data.get("sysctl_values", {})
@@ -173,7 +179,8 @@ def _format_discover_output(data: dict) -> str:
         ]
         for param in key_params:
             if param in sysctl:
-                lines.append(f"  {_cyan(param + ':'):>48s}  {sysctl[param]}")
+                padded = f"{param + ':':>42}"
+                lines.append(f"  {_cyan(padded)}  {sysctl[param]}")
 
     # --- Mount options ---
     mount_opts = data.get("mount_options", "")
@@ -186,6 +193,88 @@ def _format_discover_output(data: dict) -> str:
     return "\n".join(lines)
 
 
+# -------------------------------------------------------
+# Interactive tier selection
+# -------------------------------------------------------
+
+# Entry counts per tier (from tune-manifest.json tiered filtering)
+_TIER_INFO = {
+    "conservative": {"entries": 51, "desc": "safe, minimal changes"},
+    "balanced":     {"entries": 80, "desc": "recommended balance"},
+    "aggressive":   {"entries": 86, "desc": "maximum performance"},
+}
+
+
+def _detect_ram_mb() -> int:
+    """Run discover.sh and extract RAM in MB from the JSON output."""
+    rc, stdout, _stderr = _run_script("discover.sh", capture=True)
+    if rc != 0:
+        return 0
+    try:
+        data = json.loads(stdout)
+        return int(data.get("ram_mb", 0))
+    except (json.JSONDecodeError, ValueError, TypeError):
+        return 0
+
+
+def _recommend_tier(ram_mb: int) -> str:
+    """Return the recommended tier name based on system RAM."""
+    if ram_mb < 2048:
+        return "conservative"
+    elif ram_mb <= 8192:
+        return "balanced"
+    else:
+        return "aggressive"
+
+
+def _select_tier_interactive() -> str:
+    """Auto-discover system RAM and present an interactive tier menu.
+
+    Returns the selected tier string.  Uses only ``input()`` for prompts
+    (no external dependencies).
+    """
+    ram_mb = _detect_ram_mb()
+    recommended = _recommend_tier(ram_mb)
+
+    # Map tier names to a stable ordered list
+    tier_order = ["conservative", "balanced", "aggressive"]
+    rec_idx = tier_order.index(recommended)  # 0-based
+    default_choice = rec_idx + 1             # 1-based for display
+
+    # Header
+    if ram_mb > 0:
+        print(f"\nSystem RAM: {ram_mb} MB\n")
+    else:
+        print()
+
+    print("Select tuning tier:")
+    for i, tier in enumerate(tier_order, start=1):
+        info = _TIER_INFO[tier]
+        label = f"{tier:14s} ({info['entries']} entries - {info['desc']})"
+        if tier == recommended:
+            label = f"{tier:14s} ({info['entries']} entries - recommended for this system)"
+        print(f"  {i}) {label}")
+
+    # Prompt
+    print()
+    raw = input(f"Enter choice [1-3] (default: {default_choice}): ").strip()
+
+    if raw == "":
+        chosen = default_choice
+    else:
+        try:
+            chosen = int(raw)
+        except ValueError:
+            chosen = default_choice
+
+    if chosen < 1 or chosen > 3:
+        chosen = default_choice
+
+    selected = tier_order[chosen - 1]
+    print(f"\n→ Selected tier: {selected}\n")
+    return selected
+
+
 # -------------------------------------------------------
 # Subcommand handlers
 # -------------------------------------------------------
@@ -194,40 +283,60 @@ def cmd_discover(args: argparse.Namespace) -> int:
     """Run discover.sh and show formatted system info."""
     rc, stdout, stderr = _run_script("discover.sh", capture=True)
 
-    if rc != 0:
-        # Pass through errors from the script
-        if stderr:
-            print(stderr, end="", file=sys.stderr)
-        if stdout:
-            print(stdout, end="")
-        return rc
-
-    # --json: emit raw JSON
+    # --json: emit raw JSON (no banner/pipeline)
     if getattr(args, "json", False):
+        if rc != 0:
+            if stderr:
+                print(stderr, end="", file=sys.stderr)
         print(stdout, end="")
-        return 0
+        return rc
 
-    # Parse JSON and render formatted summary
-    try:
-        data = json.loads(stdout)
-    except json.JSONDecodeError as exc:
-        print(f"Error: Failed to parse discover output: {exc}",
-              file=sys.stderr)
-        # Fall back to raw output so the user still sees something
-        print(stdout, end="")
-        return 1
+    with Pipeline("Discover") as p:
+        if rc != 0:
+            if stderr:
+                p.fail(stderr.strip().split("\n")[0])
+            return rc
+
+        try:
+            data = json.loads(stdout)
+        except json.JSONDecodeError as exc:
+            p.fail(f"Failed to parse discover output: {exc}")
+            print(stdout, end="")
+            return 1
+
+        p.step(f"OS: {data.get('os_version', 'unknown')}")
+        p.step(f"Kernel: {data.get('kernel_version', 'unknown')}")
+        p.step(f"RAM: {data.get('ram_mb', 0)} MB ({data.get('cpu_count', 0)} CPUs)")
+
+        swap = data.get("swap_configured", False)
+        if swap:
+            p.step(f"Swap: {data.get('swap_type', 'unknown')} ({data.get('swap_total_mb', 0)} MB)")
+        else:
+            p.step("Swap: not configured")
+
+        p.step(f"Disk: {data.get('disk_type', 'unknown')} ({data.get('virt_type', 'unknown')})")
+        p.ok("Discovery complete")
 
-    print(_format_discover_output(data))
     return 0
 
 
 def cmd_plan(args: argparse.Namespace) -> int:
     """Run tune.sh in dry-run mode for the specified tier."""
+    if args.tier is None:
+        args.tier = _select_tier_interactive()
+    with Pipeline(f"Plan ({args.tier})") as p:
+        p.step(f"Previewing {args.tier} tier changes...")
+    print()
     return _run_script("tune.sh", ["--dry-run", "--tier", args.tier])
 
 
 def cmd_apply(args: argparse.Namespace) -> int:
     """Run tune.sh in apply mode for the specified tier."""
+    if args.tier is None:
+        args.tier = _select_tier_interactive()
+    with Pipeline(f"Apply ({args.tier})") as p:
+        p.step(f"Applying {args.tier} tier tuning...")
+    print()
     return _run_script("tune.sh", ["--apply", "--tier", args.tier])
 
 
@@ -236,13 +345,26 @@ def cmd_rollback(args: argparse.Namespace) -> int:
     script_args: list[str] = []
     if args.list:
         script_args.append("--list")
+        with Pipeline("Rollback (list)") as p:
+            p.step("Listing available backups...")
+        print()
     elif args.backup:
         script_args.extend(["--backup", args.backup])
+        with Pipeline(f"Rollback ({args.backup})") as p:
+            p.step(f"Restoring from backup {args.backup}...")
+        print()
+    else:
+        with Pipeline("Rollback (latest)") as p:
+            p.step("Restoring from most recent backup...")
+        print()
     return _run_script("rollback.sh", script_args)
 
 
 def cmd_audit(args: argparse.Namespace) -> int:
     """Run audit.sh to verify applied tuning."""
+    with Pipeline("Audit") as p:
+        p.step("Verifying 86 manifest entries against live system...")
+    print()
     return _run_script("audit.sh")
 
 
@@ -251,8 +373,15 @@ def cmd_benchmark(args: argparse.Namespace) -> int:
     script_args: list[str] = []
     if args.baseline:
         script_args.append("--baseline")
+        label = "Benchmark (baseline)"
     elif args.compare:
         script_args.append("--compare")
+        label = "Benchmark (compare)"
+    else:
+        label = "Benchmark"
+    with Pipeline(label) as p:
+        p.step("Running sysbench + fio benchmarks...")
+    print()
     return _run_script("benchmark.sh", script_args)
 
 
@@ -327,9 +456,10 @@ def build_parser() -> argparse.ArgumentParser:
     sub_plan.add_argument(
         "--tier",
         type=_validate_tier,
-        required=True,
+        required=False,
+        default=None,
         metavar="TIER",
-        help="Tuning tier: conservative, balanced, or aggressive",
+        help="Tuning tier: conservative, balanced, or aggressive (interactive if omitted)",
     )
     sub_plan.set_defaults(func=cmd_plan)
 
@@ -345,9 +475,10 @@ def build_parser() -> argparse.ArgumentParser:
     sub_apply.add_argument(
         "--tier",
         type=_validate_tier,
-        required=True,
+        required=False,
+        default=None,
         metavar="TIER",
-        help="Tuning tier: conservative, balanced, or aggressive",
+        help="Tuning tier: conservative, balanced, or aggressive (interactive if omitted)",
     )
     sub_apply.set_defaults(func=cmd_apply)
 
@@ -422,6 +553,7 @@ def main() -> None:
     args = parser.parse_args()
 
     if args.command is None:
+        print_banner()
         parser.print_help()
         sys.exit(2)
 

package/tunectl/ui.py

@@ -0,0 +1,282 @@
+"""tunectl UI — Unicode banner and pipeline output in the opencode style.
+
+Provides:
+  - print_banner()   — block-letter "tunectl" banner with two-tone coloring
+  - Pipeline context  — ┌/│/●/◇/▲/└ vertical status output
+
+Style reference: opencode CLI (https://github.com/nicholasgriffintn/opencode)
+  - First half "tune" rendered in dim gray  (ANSI 90)
+  - Second half "ctl" rendered in bright white (ANSI 0/reset)
+  - Hollow letter interiors use 256-color backgrounds (235/238)
+  - Shadow accents on bottom row use fg 235
+  - Pipeline uses box-drawing characters with double-space indent
+
+Letter alphabet (4-wide cells, 4 rows each):
+  Row 0 = top accent (only special letters like 'l' use ▄)
+  Row 1 = upper body  (█▀▀█, █▀▀▄, █▀▀▀, etc.)
+  Row 2 = middle body (█  █, █▀▀▀, █   , etc.)  — hollows get bg fill
+  Row 3 = bottom      (▀▀▀▀, █▀▀▀, etc.)
+"""
+
+import sys
+
+# ---------------------------------------------------------------------------
+# ANSI helpers
+# ---------------------------------------------------------------------------
+
+def _use_color() -> bool:
+    return sys.stdout.isatty()
+
+
+def _esc(code: str) -> str:
+    return f"\033[{code}m" if _use_color() else ""
+
+
+R   = property(lambda self: _esc("0"))     # reset
+DIM = property(lambda self: _esc("90"))    # dim gray
+
+# We use module-level functions so the color check happens at call time.
+
+def _r():
+    return _esc("0")
+
+def _d():
+    return _esc("90")
+
+def _bg_dim():
+    return _esc("48;5;235")
+
+def _bg_bright():
+    return _esc("48;5;238")
+
+def _fg_shadow():
+    return _esc("38;5;235")
+
+def _green():
+    return _esc("32")
+
+def _yellow():
+    return _esc("33")
+
+def _red():
+    return _esc("31")
+
+def _cyan():
+    return _esc("36")
+
+
+# ---------------------------------------------------------------------------
+# Block-letter alphabet  (4 cols x 4 rows per glyph)
+#
+# Each letter is a tuple of 4 strings.  Characters:
+#   █ = U+2588 full block      ▀ = U+2580 upper half
+#   ▄ = U+2584 lower half      ' ' = space (hollow interior)
+#
+# Row 0 is the top-accent row (usually blank).
+# Hollow interiors (spaces inside row 1-2) get background-color fills
+# at render time — the alphabet stores plain spaces.
+# ---------------------------------------------------------------------------
+
+LETTERS = {
+    "t": (
+        "    ",
+        "█▀▀█",
+        "▀██▀",
+        " ▀▀ ",
+    ),
+    "u": (
+        "    ",
+        "█  █",
+        "█  █",
+        "▀▀▀█",
+    ),
+    "n": (
+        "    ",
+        "█▀▀▄",
+        "█  █",
+        "▀  ▀",
+    ),
+    "e": (
+        "    ",
+        "█▀▀█",
+        "█▀▀▀",
+        "▀▀▀▀",
+    ),
+    "c": (
+        "    ",
+        "█▀▀▀",
+        "█   ",
+        "▀▀▀▀",
+    ),
+    "l": (
+        "   ▄",
+        "█▀▀█",
+        "█  █",
+        "▀▀▀▀",
+    ),
+}
+
+# ---------------------------------------------------------------------------
+# Banner renderer
+# ---------------------------------------------------------------------------
+
+# "tune" = dim half, "ctl" = bright half
+_DIM_LETTERS = "tune"
+_BRIGHT_LETTERS = "ctl"
+_WORD = _DIM_LETTERS + _BRIGHT_LETTERS  # "tunectl"
+
+
+def _render_char(ch: str, fg_fn, bg_fn, shadow_fn, row: int) -> str:
+    """Render one character of a letter cell with proper ANSI coloring.
+
+    fg_fn    — returns the foreground escape for solid glyphs (█ ▀ ▄)
+    bg_fn    — returns the background escape for hollow interiors (spaces)
+    shadow_fn — returns the fg escape for shadow accents on the bottom row
+    row      — which row (0-3) we are rendering
+    """
+    r = _r()
+
+    if ch == " ":
+        # Hollow interior — fill with background color (rows 1-2 only)
+        if row in (1, 2):
+            return f"{bg_fn()}{ch}{r}"
+        return ch
+
+    if ch == "▀" and row == 3:
+        # Bottom row: check if this is an interior accent (shadow)
+        # We handle this at a higher level; default to fg
+        return f"{fg_fn()}{ch}{r}"
+
+    # Solid glyph
+    return f"{fg_fn()}{ch}{r}"
+
+
+def _render_row(row_idx: int) -> str:
+    """Render one row of the full 'tunectl' banner."""
+    r = _r()
+    parts = []
+
+    for i, letter_ch in enumerate(_WORD):
+        glyph = LETTERS[letter_ch]
+        row_str = glyph[row_idx]
+
+        if letter_ch in _DIM_LETTERS and _WORD.index(letter_ch) == i and i < len(_DIM_LETTERS):
+            fg_fn = _d
+            bg_fn = _bg_dim
+            shadow_fn = _fg_shadow
+        elif i >= len(_DIM_LETTERS):
+            fg_fn = _r
+            bg_fn = _bg_bright
+            shadow_fn = _r
+        else:
+            # Duplicate letter in dim section
+            fg_fn = _d
+            bg_fn = _bg_dim
+            shadow_fn = _fg_shadow
+
+        cell = ""
+        for j, ch in enumerate(row_str):
+            if ch == " " and row_idx in (1, 2):
+                cell += f"{bg_fn()}{ch}{_r()}"
+            elif ch == "▀" and row_idx == 3:
+                # Shadow: inner chars of dim-half bottom row get subtle shadow
+                if fg_fn == _d and 0 < j < 3:
+                    cell += f"{shadow_fn()}{ch}{_r()}"
+                else:
+                    cell += f"{fg_fn()}{ch}{_r()}"
+            else:
+                if ch == " ":
+                    cell += ch
+                else:
+                    cell += f"{fg_fn()}{ch}{_r()}"
+
+        parts.append(cell)
+
+    return "  " + " ".join(parts)
+
+
+def banner() -> str:
+    """Return the full tunectl banner string (4 rows + surrounding newlines)."""
+    lines = [""]
+    for row_idx in range(4):
+        lines.append(_render_row(row_idx))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def print_banner() -> None:
+    """Print the tunectl banner to stdout."""
+    print(banner())
+
+
+# ---------------------------------------------------------------------------
+# Pipeline output  (┌ │ ● ◇ ▲ └)
+# ---------------------------------------------------------------------------
+
+_SYM_START  = "\u250C"  # ┌
+_SYM_PIPE   = "\u2502"  # │
+_SYM_DOT    = "\u25CF"  # ●
+_SYM_OK     = "\u25C7"  # ◇
+_SYM_WARN   = "\u25B2"  # ▲
+_SYM_END    = "\u2514"  # └
+
+
+class Pipeline:
+    """Context-manager for styled vertical pipeline output.
+
+    Usage:
+        with Pipeline("Discover") as p:
+            p.step("OS: Ubuntu 24.04 LTS")
+            p.step("Kernel: 6.8.0-101-generic")
+            p.ok("Discovery complete")
+    """
+
+    def __init__(self, title: str, show_banner: bool = True):
+        self.title = title
+        self.show_banner = show_banner
+        self._started = False
+
+    def __enter__(self):
+        if self.show_banner:
+            print_banner()
+        print(f"{_SYM_START}  {self.title}")
+        self._started = True
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None:
+            self.fail(f"Error: {exc_val}")
+        self._end()
+        return False
+
+    def _line(self):
+        print(_SYM_PIPE)
+
+    def step(self, msg: str) -> None:
+        self._line()
+        c = _cyan() if _use_color() else ""
+        r = _r() if _use_color() else ""
+        print(f"{_SYM_DOT}  {msg}")
+
+    def ok(self, msg: str) -> None:
+        self._line()
+        g = _green() if _use_color() else ""
+        r = _r() if _use_color() else ""
+        print(f"{g}{_SYM_OK}{r}  {msg}")
+
+    def warn(self, msg: str) -> None:
+        self._line()
+        y = _yellow() if _use_color() else ""
+        r = _r() if _use_color() else ""
+        print(f"{y}{_SYM_WARN}{r}  {msg}")
+
+    def fail(self, msg: str) -> None:
+        self._line()
+        rd = _red() if _use_color() else ""
+        r = _r() if _use_color() else ""
+        print(f"{rd}{_SYM_DOT}{r}  {msg}")
+
+    def _end(self) -> None:
+        self._line()
+        print(f"{_SYM_END}  Done")
+        print()