@intentsolutionsio/cli-ux-tester 3.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@intentsolutionsio/cli-ux-tester",
+  "version": "3.1.0",
+  "description": "Expert UX evaluator for command-line interfaces, CLIs, terminal tools, shell scripts, and developer APIs",
+  "keywords": [
+    "cli",
+    "ux",
+    "testing",
+    "developer-experience",
+    "terminal",
+    "usability",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/testing/cli-ux-tester"
+  },
+  "homepage": "https://tonsofskills.com/plugins/cli-ux-tester",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Alister Lewis-Bowen",
+    "url": "https://github.com/ali5ter"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install cli-ux-tester\\\\n  or /plugin install cli-ux-tester@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/cli-ux-tester/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: cli-ux-tester
+description: Expert UX evaluator for CLIs, terminal tools, and developer APIs. Use when reviewing command usability, error messages, help systems, or developer experience.
+version: 3.0.0
+allowed-tools: Read, Bash, AskUserQuestion, Agent
+---
+
+# CLI UX Tester
+
+This skill evaluates the usability of command-line interfaces and developer tools. It identifies the target CLI,
+asks clarifying questions if needed, runs three evaluation agents in parallel, then passes the collected results
+to a synthesizer agent to produce artifacts.
+
+**Architecture:** The skill spawns all evaluation sub-agents directly (one Explore agent and two test agents in
+parallel). This works around the platform constraint that sub-agents cannot spawn further sub-agents. The
+`cli-ux-tester:cli-ux-tester` agent acts as a pure synthesizer — it receives the pre-collected test data and
+produces the scored report and artifacts.
+
+## Step 1: Detect target CLI
+
+Try to identify the CLI to evaluate from the user's message and current directory context.
+
+**From the user's message:**
+
+- If the user names a specific command or tool (e.g., "review my-tool"), use that as the target.
+
+**From the current directory:**
+
+```bash
+# Check for executable entry points
+ls -la *.sh bin/ scripts/ 2>/dev/null | head -20
+
+# Check for package.json with a bin field (Node.js CLI)
+cat package.json 2>/dev/null | grep -A5 '"bin"'
+
+# Check for Python CLI setup
+cat setup.py pyproject.toml 2>/dev/null | grep -A5 'console_scripts\|entry_points' | head -20
+
+# Check for Go main package
+ls main.go cmd/ 2>/dev/null
+
+# Check README for CLI name and usage
+head -50 README.md 2>/dev/null
+```
+
+## Step 2: Ask clarifying questions if needed
+
+Skip this step if the target CLI was already identified from the user's message in Step 1.
+
+Otherwise, ask exactly one AskUserQuestion using the appropriate form below:
+
+**Entry point(s) detected in current directory** → ask which to evaluate:
+
+```text
+Question: "Which CLI should I evaluate?"
+Options:
+  - [Each detected entry point]
+  - A different installed command (provide the name)
+  - A different path (provide the path)
+```
+
+**No entry points detected** → ask the user to specify:
+
+```text
+Question: "Which CLI tool should I evaluate?"
+Options:
+  - An installed command available in $PATH (provide the name)
+  - A path to an executable (provide the path)
+```
+
+Proceed directly to Step 3 with whatever the user provides.
+
+## Step 3: Run evaluation agents in parallel
+
+Locate the reference files first:
+
+- Use Glob (`**/testing-checklist.md`) to find `testing-checklist.md`; note the path
+- Use Glob (`**/test-scenarios.md`) to find `test-scenarios.md`; note the path
+
+Then spawn these three agents simultaneously, substituting the actual `{cli_command}` and `{working_dir}`:
+
+**Explore agent** — codebase mapping:
+
+```text
+subagent_type: Explore
+prompt: "Map the {cli_command} CLI codebase in {working_dir}. Find: all commands and subcommands,
+help text locations, error handling code, version output, README and docs files, entry point(s),
+flag/argument parsing. Return a structured summary: command tree, key file locations, patterns
+observed."
+```
+
+**Test agent A** — discovery and help:
+
+```text
+subagent_type: general-purpose
+prompt: "Test {cli_command}'s help system and discoverability (run from {working_dir}).
+Run: {cli_command} --help, {cli_command} -h, {cli_command} help, {cli_command} (no args),
+{cli_command} --version, {cli_command} -v, {cli_command} version, {cli_command} invalid-subcommand,
+{cli_command} --invalid-flag. For each subcommand found, also run: {cli_command} subcommand --help.
+Capture exact output. Note: what works, what fails, what's missing."
+```
+
+**Test agent B** — error handling and consistency:
+
+```text
+subagent_type: general-purpose
+prompt: "Test {cli_command}'s error handling and consistency (run from {working_dir}).
+Run: commands with missing required args, invalid flag values, nonexistent files, wrong syntax.
+Check whether flag names are consistent across subcommands (--verbose always means the same thing).
+Check exit codes with echo $?. Capture exact outputs. Note every inconsistency."
+```
+
+Wait for all three agents to complete and collect their full outputs before proceeding.
+
+## Step 4: Launch synthesizer agent
+
+Once all evaluation results are collected, launch the `cli-ux-tester:cli-ux-tester` agent.
+
+Pass:
+
+- The working directory
+- The CLI entry point (command name, script path, or executable)
+- Any relevant context from the user's message (e.g., "focus on error messages")
+- The full output from all three evaluation agents (Explore, Test A, Test B)
+- Path to `testing-checklist.md`
+- Path to `test-scenarios.md`
+
+## Step 5: Report results
+
+When the agent completes, inform the user:
+
+```text
+✅ Evaluation complete!
+📁 Results saved to: {timestamped_directory}
+📊 Overall score: {overall_score}/5
+🔍 Top issues: {brief_summary}
+
+Clean up with: rm -rf CLI_UX_EVALUATION_*/
+```
+
+## Error handling
+
+- **CLI not found**: Ask the user to confirm the command name or path
+- **Permission denied**: Note the issue and ask if they want to test a different entry point
+- **No CLI in current directory**: Ask the user to specify which tool to evaluate

package/skills/cli-ux-tester/scripts/example-test.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+
+# @file example-test.sh
+# @brief This script demonstrates how to test a CLI tool for UX issues.
+#        Adapt this template for your specific tool.
+# @usage ./example-test.sh
+# @author Alister Lewis-Bowen <alister@lewis-bowen.org>
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Test counter
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Function to print test results
+print_result() {
+    local test_name="$1"
+    local result="$2"
+    local details="${3:-}"
+
+    TESTS_RUN=$((TESTS_RUN + 1))
+
+    if [[ "$result" == "PASS" ]]; then
+        echo -e "${GREEN}✓${NC} $test_name"
+        TESTS_PASSED=$((TESTS_PASSED + 1))
+    elif [[ "$result" == "FAIL" ]]; then
+        echo -e "${RED}✗${NC} $test_name"
+        if [[ -n "$details" ]]; then
+            echo -e "  ${YELLOW}Details:${NC} $details"
+        fi
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+    else
+        echo -e "${BLUE}•${NC} $test_name"
+    fi
+}
+
+# Function to run a command and capture output
+run_test() {
+    local description="$1"
+    local command="$2"
+    local expected_pattern="${3:-}"
+
+    echo -e "\n${BLUE}Testing:${NC} $description"
+    echo -e "${BLUE}Command:${NC} $command"
+
+    # Run command and capture output and exit code
+    set +e
+    read -ra cmd_array <<< "$command"
+    output=$("${cmd_array[@]}" 2>&1)
+    exit_code=$?
+    set -e
+
+    echo -e "${BLUE}Exit code:${NC} $exit_code"
+    echo -e "${BLUE}Output:${NC}"
+    echo "$output" | head -20
+
+    # Check against expected pattern if provided
+    if [[ -n "$expected_pattern" ]]; then
+        if echo "$output" | grep -q "$expected_pattern"; then
+            print_result "$description" "PASS"
+        else
+            print_result "$description" "FAIL" "Expected pattern '$expected_pattern' not found"
+        fi
+    fi
+
+    return $exit_code
+}
+
+# ==============================================================================
+# Test Suite Configuration
+# ==============================================================================
+
+# Set your CLI command here
+CLI_COMMAND="${CLI_COMMAND:-mytool}"
+
+# Path to the CLI tool (if it needs to be sourced)
+CLI_SOURCE="${CLI_SOURCE:-}"
+
+echo "========================================================================"
+echo "CLI UX Testing Suite"
+echo "========================================================================"
+echo "Command: $CLI_COMMAND"
+echo "Time: $(date)"
+echo "========================================================================"
+echo ""
+
+# Source the CLI if needed
+if [[ -n "$CLI_SOURCE" ]]; then
+    echo "Sourcing: $CLI_SOURCE"
+    source "$CLI_SOURCE"
+    echo ""
+fi
+
+# ==============================================================================
+# Test 1: Help Discovery
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Help Discovery ===${NC}\n"
+
+run_test "Help flag --help" "$CLI_COMMAND --help" "Usage:"
+run_test "Help flag -h" "$CLI_COMMAND -h" "Usage:"
+run_test "Help command" "$CLI_COMMAND help" ""
+
+# ==============================================================================
+# Test 2: Version Information
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Version Information ===${NC}\n"
+
+run_test "Version flag --version" "$CLI_COMMAND --version" ""
+run_test "Version flag -v" "$CLI_COMMAND -v" ""
+
+# ==============================================================================
+# Test 3: Error Handling
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Error Handling ===${NC}\n"
+
+run_test "No arguments" "$CLI_COMMAND" ""
+run_test "Invalid command" "$CLI_COMMAND invalid_command_xyz" "Error:"
+run_test "Invalid flag" "$CLI_COMMAND --invalid-flag-xyz" "Error:"
+run_test "Missing required argument" "$CLI_COMMAND command" ""
+
+# ==============================================================================
+# Test 4: Basic Functionality
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Basic Functionality ===${NC}\n"
+
+# Add your specific command tests here
+# Example:
+# run_test "Info message" "$CLI_COMMAND info 'test'" "test"
+# run_test "Warning message" "$CLI_COMMAND warn 'test'" "test"
+
+# ==============================================================================
+# Test 5: Interactive Features
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Interactive Features ===${NC}\n"
+
+# Note: Interactive features require special handling
+echo "ℹ️  Interactive features require manual testing or expect/pexpect"
+
+# ==============================================================================
+# Test 6: Output Formats
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Output Formats ===${NC}\n"
+
+# Test different output formats if your tool supports them
+# Example:
+# run_test "JSON output" "$CLI_COMMAND list --format json" "{"
+# run_test "YAML output" "$CLI_COMMAND list --format yaml" ""
+
+# ==============================================================================
+# Test 7: Performance
+# ==============================================================================
+
+echo -e "\n${YELLOW}=== Test Group: Performance ===${NC}\n"
+
+# Test startup performance
+start_time=$(date +%s%N)
+$CLI_COMMAND --help > /dev/null 2>&1 || true
+end_time=$(date +%s%N)
+duration_ms=$(( (end_time - start_time) / 1000000 ))
+
+echo "Help command response time: ${duration_ms}ms"
+if [[ $duration_ms -lt 100 ]]; then
+    print_result "Help response time (<100ms)" "PASS"
+elif [[ $duration_ms -lt 500 ]]; then
+    print_result "Help response time (<500ms)" "INFO" "${duration_ms}ms"
+else
+    print_result "Help response time" "FAIL" "${duration_ms}ms (too slow)"
+fi
+
+# ==============================================================================
+# Summary
+# ==============================================================================
+
+echo ""
+echo "========================================================================"
+echo "Test Summary"
+echo "========================================================================"
+echo -e "Total tests:  $TESTS_RUN"
+echo -e "${GREEN}Passed:${NC}       $TESTS_PASSED"
+echo -e "${RED}Failed:${NC}       $TESTS_FAILED"
+echo ""
+
+if [[ $TESTS_FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All tests passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some tests failed${NC}"
+    exit 1
+fi