beautiful-python-cli 0.0.0-stage → 1.0.0

package/examples/showcase.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""A compact Rich showcase: panels, tables, status, and measurable progress."""
+
+from __future__ import annotations
+
+import argparse
+import time
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+from rich.theme import Theme
+
+THEME = Theme(
+    {
+        "success": "bold green",
+        "warning": "bold yellow",
+        "error": "bold red",
+        "info": "cyan",
+        "muted": "dim",
+        "accent": "bold bright_magenta",
+    }
+)
+
+
+def make_console(no_color: bool = False) -> Console:
+    return Console(theme=THEME, no_color=no_color)
+
+
+def render_summary(console: Console) -> None:
+    summary = Table.grid(padding=(0, 2))
+    summary.add_column(style="muted")
+    summary.add_column()
+    summary.add_row("Target", "demo.internal")
+    summary.add_row("Mode", "read-only demonstration")
+    summary.add_row("Result", "[success]COMPLETED[/success]")
+    console.print(
+        Panel(
+            summary,
+            title="[accent]Python CLI[/accent]",
+            subtitle="[muted]Rich interface showcase[/muted]",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+
+
+def render_results(console: Console) -> None:
+    table = Table(title="Example results", expand=True)
+    table.add_column("ID", style="muted", no_wrap=True)
+    table.add_column("Check", ratio=2)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Duration", justify="right", no_wrap=True)
+
+    table.add_row("CHK-001", "Configuration loaded", "[success]PASS[/success]", "0.02s")
+    table.add_row("CHK-002", "Dependency check", "[success]PASS[/success]", "0.11s")
+    table.add_row("CHK-003", "Optional integration", "[warning]SKIPPED[/warning]", "—")
+    console.print(table)
+
+
+def run_progress(console: Console, count: int) -> None:
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TimeElapsedColumn(),
+        console=console,
+        transient=False,
+        disable=not console.is_terminal,
+    ) as progress:
+        task = progress.add_task("Processing demonstration items", total=count)
+        for _ in range(count):
+            time.sleep(0.08)
+            progress.advance(task)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Showcase a polished Rich CLI.")
+    parser.add_argument("--no-color", action="store_true", help="Disable terminal colors.")
+    parser.add_argument("--items", type=int, default=20, help="Number of demo progress items.")
+    args = parser.parse_args()
+
+    if args.items < 1:
+        parser.error("--items must be at least 1")
+
+    console = make_console(no_color=args.no_color)
+    console.print()
+    render_summary(console)
+    console.print()
+    render_results(console)
+    console.print()
+
+    if console.is_terminal:
+        run_progress(console, args.items)
+    else:
+        console.print(f"Processing {args.items} demonstration items (progress animation disabled).")
+
+    console.print("\n[success]Demo finished.[/success]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/tui_layout.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Demonstration of a multi-pane Terminal Layout (TUI) with responsive panes."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from rich.align import Align
+from rich.console import Console
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.theme import Theme
+
+THEME = Theme(
+    {
+        "success": "bold green",
+        "warning": "bold yellow",
+        "error": "bold red",
+        "info": "cyan",
+        "muted": "dim",
+        "accent": "bold magenta",
+    }
+)
+
+console = Console(theme=THEME)
+
+
+def make_layout() -> Layout:
+    layout = Layout()
+    layout.split_column(
+        Layout(name="header", size=3),
+        Layout(name="main", ratio=1),
+        Layout(name="footer", size=3),
+    )
+    layout["main"].split_row(
+        Layout(name="sidebar", ratio=1),
+        Layout(name="content", ratio=2),
+    )
+    return layout
+
+
+def render_sidebar(iteration: int) -> Panel:
+    table = Table.grid(padding=(0, 1))
+    table.add_column(style="muted")
+    table.add_column(justify="right")
+    table.add_row("Uptime:", f"{iteration * 0.5:.1f}s")
+    table.add_row("Memory:", "42.8 MB")
+    table.add_row("Active Tasks:", "[accent]4[/accent]")
+    table.add_row("Queue Depth:", "[info]12[/info]")
+    table.add_row("Health:", "[success]OPTIMAL[/success]")
+    return Panel(table, title="[bold]System Status[/bold]", border_style="cyan")
+
+
+def render_content(iteration: int) -> Panel:
+    table = Table(expand=True, box=None)
+    table.add_column("Event ID", style="muted", no_wrap=True)
+    table.add_column("Source")
+    table.add_column("Level")
+    table.add_column("Message")
+
+    events = [
+        ("EVT-101", "ingest-service", "[success]INFO[/success]", "Payload batch parsed successfully"),
+        ("EVT-102", "auth-gateway", "[success]INFO[/success]", "TLS handshake verified with mutual cert"),
+        ("EVT-103", "worker-pool", "[warning]WARN[/warning]", "Memory buffer above 70% threshold"),
+        ("EVT-104", "storage-node", "[success]INFO[/success]", f"Snapshot #{iteration} committed to disk"),
+    ]
+    for eid, src, lvl, msg in events:
+        table.add_row(eid, src, lvl, msg)
+
+    return Panel(table, title="[bold]Real-Time Stream[/bold]", border_style="magenta")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Demonstrate Rich Layout TUI.")
+    parser.add_argument("--seconds", type=float, default=2.0, help="Duration to run demonstration")
+    args = parser.parse_args()
+
+    layout = make_layout()
+    layout["header"].update(
+        Align.center("[accent]─── CLUSTER SURVEILLANCE & TELEMETRY TUI ───[/accent]")
+    )
+    layout["footer"].update(
+        Align.center("[muted]Press Ctrl+C to disconnect • Live stream frequency: 2 Hz[/muted]")
+    )
+
+    if not console.is_terminal:
+        layout["sidebar"].update(render_sidebar(1))
+        layout["content"].update(render_content(1))
+        console.print(layout)
+        return
+
+    with Live(layout, console=console, screen=False, refresh_per_second=4) as live:
+        start = time.time()
+        iteration = 0
+        try:
+            while time.time() - start < args.seconds:
+                iteration += 1
+                layout["sidebar"].update(render_sidebar(iteration))
+                layout["content"].update(render_content(iteration))
+                time.sleep(0.5)
+        except KeyboardInterrupt:
+            pass
+
+    console.print("[success]TUI session terminated cleanly.[/success]")
+
+
+if __name__ == "__main__":
+    main()

package/install.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SKILL_NAME="beautiful-python-cli"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+INSTALL_OMP=0
+INSTALL_PI=0
+INSTALL_CODEX=0
+INSTALL_CLAUDE=0
+INSTALL_CURSOR=0
+INSTALL_ANTIGRAVITY=0
+INSTALL_WINDSURF=0
+EXPLICIT_SELECTION=0
+
+usage() {
+  cat <<'EOF'
+Install the Beautiful Python CLI skill for AI coding agents.
+
+Usage:
+  ./install.sh --all
+  ./install.sh --claude
+  ./install.sh --cursor
+  ./install.sh --antigravity
+  ./install.sh --codex
+  ./install.sh --windsurf
+  ./install.sh --pi
+  ./install.sh --omp
+
+Targets:
+  Claude Code   ~/.claude/skills/
+  Cursor        ~/.cursor/skills/
+  Antigravity   ~/.gemini/antigravity-cli/skills/
+  Codex         ~/.agents/skills/
+  Windsurf      ~/.codeium/windsurf/skills/
+  Pi            ~/.pi/agent/skills/
+  OMP           ~/.omp/agent/skills/
+
+With no target flags, --all is used.
+Existing installations are backed up before replacement.
+EOF
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --all)
+      EXPLICIT_SELECTION=1
+      INSTALL_OMP=1
+      INSTALL_PI=1
+      INSTALL_CODEX=1
+      INSTALL_CLAUDE=1
+      INSTALL_CURSOR=1
+      INSTALL_ANTIGRAVITY=1
+      INSTALL_WINDSURF=1
+      ;;
+    --omp)
+      EXPLICIT_SELECTION=1
+      INSTALL_OMP=1
+      ;;
+    --pi)
+      EXPLICIT_SELECTION=1
+      INSTALL_PI=1
+      ;;
+    --codex)
+      EXPLICIT_SELECTION=1
+      INSTALL_CODEX=1
+      ;;
+    --claude)
+      EXPLICIT_SELECTION=1
+      INSTALL_CLAUDE=1
+      ;;
+    --cursor)
+      EXPLICIT_SELECTION=1
+      INSTALL_CURSOR=1
+      ;;
+    --antigravity|--gemini)
+      EXPLICIT_SELECTION=1
+      INSTALL_ANTIGRAVITY=1
+      ;;
+    --windsurf)
+      EXPLICIT_SELECTION=1
+      INSTALL_WINDSURF=1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown option: %s\n\n' "$arg" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "$EXPLICIT_SELECTION" -eq 0 ]]; then
+  INSTALL_OMP=1
+  INSTALL_PI=1
+  INSTALL_CODEX=1
+  INSTALL_CLAUDE=1
+  INSTALL_CURSOR=1
+  INSTALL_ANTIGRAVITY=1
+  INSTALL_WINDSURF=1
+fi
+
+install_to() {
+  local parent="$1"
+  local destination="${parent}/${SKILL_NAME}"
+  local temporary="${parent}/.${SKILL_NAME}.tmp.$$"
+  local backup=""
+
+  mkdir -p "$parent"
+  rm -rf "$temporary"
+  mkdir -p "$temporary"
+  cp -R "${SOURCE_DIR}/." "$temporary/"
+
+  if [[ -e "$destination" ]]; then
+    backup="${destination}.backup.$(date +%Y%m%d-%H%M%S)-$$"
+    mv "$destination" "$backup"
+  fi
+
+  if ! mv "$temporary" "$destination"; then
+    if [[ -n "$backup" && -e "$backup" ]]; then
+      mv "$backup" "$destination"
+    fi
+    printf 'Failed to install into %s\n' "$destination" >&2
+    return 1
+  fi
+
+  printf 'Installed: %s\n' "$destination"
+  if [[ -n "$backup" ]]; then
+    printf 'Previous copy backed up: %s\n' "$backup"
+  fi
+}
+
+if [[ "$INSTALL_CLAUDE" -eq 1 ]]; then
+  install_to "${HOME}/.claude/skills"
+fi
+if [[ "$INSTALL_CURSOR" -eq 1 ]]; then
+  install_to "${HOME}/.cursor/skills"
+fi
+if [[ "$INSTALL_ANTIGRAVITY" -eq 1 ]]; then
+  install_to "${HOME}/.gemini/antigravity-cli/skills"
+fi
+if [[ "$INSTALL_CODEX" -eq 1 ]]; then
+  install_to "${HOME}/.agents/skills"
+fi
+if [[ "$INSTALL_WINDSURF" -eq 1 ]]; then
+  install_to "${HOME}/.codeium/windsurf/skills"
+fi
+if [[ "$INSTALL_PI" -eq 1 ]]; then
+  install_to "${HOME}/.pi/agent/skills"
+fi
+if [[ "$INSTALL_OMP" -eq 1 ]]; then
+  install_to "${HOME}/.omp/agent/skills"
+fi
+
+printf '\nDone. Start a new agent session if the skill is not discovered automatically.\n'

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "beautiful-python-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Agent Skill for designing, implementing, and refactoring Python terminal UIs using Rich",
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "skills-sh",
+    "rich",
+    "python",
+    "cli",
+    "terminal-ui",
+    "tui",
+    "claude-code",
+    "cursor",
+    "codex",
+    "windsurf",
+    "antigravity"
+  ],
+  "homepage": "https://github.com/syrex1013/beautiful-python-cli#readme",
+  "bugs": {
+    "url": "https://github.com/syrex1013/beautiful-python-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syrex1013/beautiful-python-cli.git"
+  },
+  "license": "MIT",
+  "author": "syrex1013",
+  "main": "SKILL.md",
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "references",
+    "examples",
+    "install.sh",
+    "requirements.txt"
+  ],
+  "scripts": {
+    "test": "python3 -m unittest discover -s tests -p 'test_*.py'"
+  }
+}

package/references/activation-tests.md

@@ -0,0 +1,34 @@
+# Skill routing and quality checks
+
+Use these prompts to evaluate whether the skill is discoverable and stays within its intended scope.
+
+## Prompts that should activate the skill
+
+1. "Make this Python CLI output look professional with Rich panels and tables."
+2. "Add a spinner while the API connection is being established."
+3. "Show real progress for this file-processing loop, including elapsed time."
+4. "Build a live terminal dashboard for my concurrent workers."
+5. "Improve the CLI's colors, status indicators, logging, and error messages."
+6. "Make this scanner's terminal output readable over SSH and in CI."
+7. "Add a clean JSON mode without progress bars contaminating stdout."
+8. "Refactor the CLI output into reusable Rich components."
+
+## Prompts that should not activate the skill by default
+
+1. "Build a React dashboard for this Python service." — this is a web UI.
+2. "Create a Tkinter desktop application." — this is a GUI.
+3. "Explain what a Python generator is." — no CLI presentation work.
+4. "Write a one-line Python script that prints hello." — plain output is sufficient.
+5. "Optimize this SQL query." — unrelated to terminal UX.
+
+## Review criteria
+
+For an activation test, verify both routing and execution:
+
+- Did the agent inspect the existing CLI and dependency setup first?
+- Did it preserve the current CLI framework and output contract?
+- Did it select a spinner for unknown progress and a bar only for measurable progress?
+- Did it avoid fabricated progress, ETA, or throughput?
+- Did it account for TTY, redirected output, JSON, and `NO_COLOR`?
+- Did it add only necessary dependencies?
+- Did it test errors, empty results, narrow widths, and cleanup?

package/references/concurrent-progress.md

@@ -0,0 +1,69 @@
+# Concurrent and Multi-Threaded Progress
+
+When tasks run across multiple threads, processes, or asynchronous coroutines, coordinate progress bars safely through a single `rich.progress.Progress` instance.
+
+## 1. Multi-Threaded Workers (`ThreadPoolExecutor`)
+
+```python
+import concurrent.futures
+import time
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+)
+
+def worker_task(progress: Progress, task_id: int, total_steps: int) -> str:
+    for _ in range(total_steps):
+        time.sleep(0.05)  # Simulate real work
+        progress.advance(task_id, advance=1)
+    return "done"
+
+with Progress(
+    SpinnerColumn(),
+    TextColumn("[progress.description]{task.description}"),
+    BarColumn(),
+    TaskProgressColumn(),
+    TimeRemainingColumn(),
+    console=console,
+) as progress:
+    with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
+        futures = []
+        for i in range(4):
+            task_id = progress.add_task(f"Worker {i+1}", total=20)
+            futures.append(executor.submit(worker_task, progress, task_id, 20))
+        
+        # Wait for all workers to complete
+        for future in concurrent.futures.as_completed(futures):
+            _ = future.result()
+```
+
+## 2. Asyncio Workers
+
+```python
+import asyncio
+from rich.progress import Progress
+
+async def async_worker(progress: Progress, task_id: int, count: int):
+    for _ in range(count):
+        await asyncio.sleep(0.1)
+        progress.advance(task_id)
+
+async def main():
+    with Progress(console=console) as progress:
+        tasks = [
+            async_worker(progress, progress.add_task(f"Stream {i}", total=15), 15)
+            for i in range(3)
+        ]
+        await asyncio.gather(*tasks)
+
+asyncio.run(main())
+```
+
+## 3. Important Rules
+- **Never call `print()` inside workers**: Interleaved output will break the progress bar rendering lines. Use `progress.console.log()` or `progress.console.print()` if log output is required.
+- **One `Progress` per console**: Do not create multiple active `Progress` context managers at the same time.
+- **Update descriptions dynamically**: Use `progress.update(task_id, description="...")` to communicate changing sub-phases.

package/references/interaction-patterns.md

@@ -0,0 +1,109 @@
+# Interaction patterns: loading, progress, and live output
+
+## 1. Indeterminate operation: spinner
+
+Use when duration is unknown and there is no honest measurable denominator.
+
+```python
+with console.status("[info]Connecting to service…[/info]", spinner="dots"):
+    client.connect()
+```
+
+The context manager stops the spinner even if the operation raises. Keep the message action-oriented and update it when the phase changes.
+
+## 2. Measurable operation: progress bar
+
+```python
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+
+with Progress(
+    SpinnerColumn(),
+    TextColumn("[progress.description]{task.description}"),
+    BarColumn(),
+    TaskProgressColumn(),
+    TimeElapsedColumn(),
+    TimeRemainingColumn(),
+    console=console,
+    transient=False,
+    disable=not console.is_terminal,
+) as progress:
+    task = progress.add_task("Processing files", total=len(files))
+    for path in files:
+        process(path)
+        progress.advance(task)
+```
+
+Use `total=None` only when the total is genuinely unknown. Do not estimate progress by elapsed time unless the task is explicitly time-based and the estimate is clearly labeled.
+
+## 3. Multiple tasks
+
+Use one `Progress` object with a task per independently progressing operation. Give each task a stable, concise description. Keep a separate final summary after the context manager exits.
+
+For worker threads or async tasks, route progress events through a shared coordinator or lock if updates can race. Do not let workers write arbitrary text directly into the terminal.
+
+## 4. Download/transfer progress
+
+For transfers, prefer `DownloadColumn`, `TransferSpeedColumn`, and `FileSizeColumn`. Update completed bytes from actual transfer callbacks. Do not display an ETA until there is enough observed throughput to make it meaningful.
+
+## 5. Live dashboard
+
+```python
+from rich.live import Live
+from rich.table import Table
+
+def build_dashboard(snapshot):
+    table = Table(title="Worker status", expand=True)
+    table.add_column("Worker")
+    table.add_column("State")
+    table.add_column("Completed", justify="right")
+    for worker in snapshot:
+        table.add_row(worker.name, worker.state, str(worker.completed))
+    return table
+
+with Live(
+    build_dashboard(initial_snapshot),
+    console=console,
+    refresh_per_second=4,
+    screen=False,
+) as live:
+    while running:
+        snapshot = read_current_state()
+        live.update(build_dashboard(snapshot), refresh=True)
+```
+
+Use a dashboard only when live state helps the operator make decisions. Keep the refresh rate modest. Use `screen=True` only for a deliberately full-screen TUI, and ensure keyboard/cancellation behavior is designed accordingly.
+
+While a `Live` display is active, use `console.log()` for log messages so Rich can preserve the live region. Do not mix in built-in `print()` calls.
+
+## 6. Async tasks
+
+Use the project's existing async architecture. Update progress after awaited work completes, not when it is merely scheduled. Cancel child tasks cleanly and close the progress/live context in `finally` or with context managers.
+
+## 7. Stage-based work
+
+For operations with named phases but no measurable subtask counts, show a concise stage indicator or spinner message:
+- `1/4 Validate configuration`
+- `2/4 Connect`
+- `3/4 Execute`
+- `4/4 Summarize`
+
+Only use `N/M` when the number and order of stages are fixed and real.
+
+## 8. Final state
+
+After loading/progress ends, show a durable summary:
+- outcome (success, partial, failed, cancelled)
+- actual completed/failed counts
+- elapsed time if measured
+- output paths or next action
+- concise warnings
+
+Do not leave the user with only a completed progress bar and no result.