Enhance CLI commands and improve user feedback

- Updated CLI commands (`init`, `client-check`, `server-check`, `get-logs`, `test-clientlog`, `test-serverlog`) to provide clearer prompts and error messages, improving user experience.
- Introduced new functions for better handling of missing credentials and session filters.
- Enhanced logging and feedback mechanisms with additional context and recovery hints.
- Refactored command outputs to include more informative messages and structured logging.
- Improved the overall modularity and clarity of the CLI command structure.

Author: Bhanu-Vardhan-Reddy

auralogger/cli/aside_pools.py

@@ -1,82 +1,183 @@
-"""CLI entrypoint for `auralogger` (mirrors node/src/bin/auralogger.ts)."""
+"""CLI entrypoint for `auralogger` — parity with node/src/cli/bin/auralogger.ts."""
 
+import random
 import sys
-from typing import TextIO
-
-from auralogger.cli.cli_load_env import load_cli_env_files
+from typing import List, TextIO
+
+from auralogger.cli.aside_pools import (
+    BIN_UNKNOWN_COMMAND_TEMPLATES,
+    BIN_USAGE_ASIDES,
+    BIN_USAGE_LEGENDARY_ASIDES,
+    BIN_USAGE_RARE_MULTI_ASIDES,
+    CLI_VETERAN_USAGE_ASIDES,
+    DEFAULT_SILENCE_ASIDE_CHANCE,
+    ENV_SETUP_RECOVERY_ASIDES,
+    WOLVERINE_NUDGE_ASIDES,
+    classify_error_for_aside,
+    format_aside_template,
+    pick_adaptive_fatal_aside,
+    pick_aside,
+    pick_tiered_aside,
+)
+from auralogger.cli.cli_load_env import ensure_utf8_stdio, load_cli_env_files
+from auralogger.cli.cli_personality_state import (
+    get_consecutive_failures,
+    get_total_successful_commands,
+    note_command_dispatch,
+    record_cli_failure,
+    record_cli_success,
+)
+from auralogger.cli.cli_style import bold, bold_hex, dim, hex_color, red, red_bold, white
+from auralogger.cli.cli_tone import maybe_print_generic_spice, print_aside, print_aside_maybe
 from auralogger.cli.commands.client_check import run_client_check
 from auralogger.cli.commands.get_logs_cmd import run_get_logs_command
 from auralogger.cli.commands.init import run_init
 from auralogger.cli.commands.server_check import run_server_check
 from auralogger.cli.commands.test_clientlog import run_test_clientlog
 from auralogger.cli.commands.test_serverlog import run_test_serverlog
 
+KNOWN_COMMANDS = {
+    "init",
+    "get-logs",
+    "server-check",
+    "client-check",
+    "test-serverlog",
+    "test-clientlog",
+}
+
 
 def print_usage(stream: TextIO = sys.stdout) -> None:
-    print("Usage:", file=stream)
-    print("  auralogger init", file=stream)
-    print("  auralogger server-check", file=stream)
-    print("  auralogger client-check", file=stream)
-    print("  auralogger test-serverlog", file=stream)
-    print("  auralogger test-clientlog", file=stream)
-    print("  auralogger get-logs [filters...]", file=stream)
     print("", file=stream)
-    print("See user-docs/commands.md (in the python package source tree) for filter syntax.", file=stream)
+    print(
+        bold_hex("#ffa657", "✨ Auralogger CLI") + dim(" — pick a command:"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  init") + dim("           wire up secrets + copy-paste client config"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  server-check") + dim("    make sure the server logger can talk"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  client-check") + dim("   same vibes, browser-style pipe"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  test-serverlog") + dim("  five fake server logs, just for kicks"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  test-clientlog") + dim("  five fake client logs, same deal"),
+        file=stream,
+    )
+    print(
+        hex_color("#7ee787", "  get-logs") + dim("       hunt past logs (filters optional)"),
+        file=stream,
+    )
+    print("", file=stream)
+    print(
+        dim("Docs live on npm: auralogger-cli — filter cheat sheet is there."),
+        file=stream,
+    )
+    veteran = get_total_successful_commands() >= 4 and random.random() < 0.28
+    if veteran:
+        a = pick_aside(CLI_VETERAN_USAGE_ASIDES)
+    else:
+        a = pick_tiered_aside(
+            {
+                "common": BIN_USAGE_ASIDES,
+                "rare": BIN_USAGE_RARE_MULTI_ASIDES,
+                "legendary": BIN_USAGE_LEGENDARY_ASIDES,
+            }
+        )
+    print_aside_maybe(a["emoji"], a["line"], DEFAULT_SILENCE_ASIDE_CHANCE)
+    print("", file=stream)
 
 
 def main() -> None:
+    ensure_utf8_stdio()
     load_cli_env_files()
 
-    args = sys.argv[1:]
+    args: List[str] = sys.argv[1:]
     command = args[0] if args else None
 
     if not command:
         print_usage()
         return
 
+    if command not in KNOWN_COMMANDS:
+        record_cli_failure()
+        print(
+            red("🤔 Hmm, never heard of ") + bold(command) + red("."),
+            file=sys.stderr,
+        )
+        t = pick_aside(BIN_UNKNOWN_COMMAND_TEMPLATES)
+        print_aside_maybe(
+            t["emoji"],
+            format_aside_template(t["line"], {"cmd": command}),
+            DEFAULT_SILENCE_ASIDE_CHANCE,
+        )
+        print_usage(sys.stderr)
+        sys.exit(1)
+
+    note_command_dispatch(command)
+
     if command == "init":
         run_init()
+        record_cli_success(command)
         return
 
     if command == "get-logs":
         run_get_logs_command(args)
+        record_cli_success(command)
         return
 
     if command == "server-check":
         run_server_check()
+        record_cli_success(command)
         return
 
     if command == "client-check":
         run_client_check()
+        record_cli_success(command)
         return
 
     if command == "test-serverlog":
         run_test_serverlog()
+        record_cli_success(command)
         return
 
     if command == "test-clientlog":
         run_test_clientlog()
+        record_cli_success(command)
         return
 
-    print(f"Unknown command: {command}", file=sys.stderr)
-    print(
-        "Valid commands: init, server-check, client-check, test-serverlog, test-clientlog, get-logs",
-        file=sys.stderr,
-    )
-    print_usage(sys.stderr)
-    sys.exit(1)
-
 
 def _entrypoint() -> None:
+    ensure_utf8_stdio()
     try:
         main()
     except SystemExit:
         raise
     except Exception as exc:
-        print(
-            f"auralogger: {exc}",
-            file=sys.stderr,
-        )
+        record_cli_failure()
+        message = str(exc) if isinstance(exc, Exception) else repr(exc)
+        print("", file=sys.stderr)
+        print(red_bold("💥 That didn't work."), file=sys.stderr)
+        print(dim("   ") + white(message), file=sys.stderr)
+        fails = get_consecutive_failures()
+        if fails >= 2 and random.random() < 0.45:
+            n = pick_aside(WOLVERINE_NUDGE_ASIDES)
+            print_aside(n["emoji"], n["line"])
+        aside = pick_adaptive_fatal_aside(fails, message)
+        print_aside_maybe(aside["emoji"], aside["line"], 0.08)
+        err_kind = classify_error_for_aside(message)
+        if err_kind in ("network", "auth-env") and random.random() < 0.42:
+            e = pick_aside(ENV_SETUP_RECOVERY_ASIDES)
+            print_aside(e["emoji"], e["line"])
+        maybe_print_generic_spice()
         sys.exit(1)
 
 

auralogger/cli/cli.py

@@ -5,6 +5,14 @@
 from dataclasses import dataclass
 from typing import Any, Dict, cast
 
+from auralogger.cli.aside_pools import (
+    ENV_RECOVERY_HINT_PLAIN,
+    PROMPT_MISSING_CREDENTIAL_TEMPLATES,
+    format_aside_template,
+    pick_aside,
+)
+from auralogger.cli.cli_style import cyan
+from auralogger.cli.cli_tone import print_aside
 from auralogger.server.proj_auth import fetch_proj_auth_payload
 from auralogger.utils.env_config import ENV_PROJECT_TOKEN
 from auralogger.utils.env_config import (
@@ -23,19 +31,27 @@ class CliProjectContext:
     session: str
 
 
+def _print_missing_credential_hint(env_key: str) -> None:
+    print()
+    t = pick_aside(PROMPT_MISSING_CREDENTIAL_TEMPLATES)
+    print_aside(t["emoji"], format_aside_template(t["line"], {"envKey": env_key}))
+
+
 def prompt_for_project_token() -> str:
-    entered = input(f"Paste {ENV_PROJECT_TOKEN} (your project token): ")
+    _print_missing_credential_hint(ENV_PROJECT_TOKEN)
+    entered = input(cyan("🔐 ") + f"Paste {ENV_PROJECT_TOKEN} (your project token): ")
     token = entered.strip()
     if not token:
-        raise ValueError("Project token cannot be empty.")
+        raise ValueError(f"Project token cannot be empty. {ENV_RECOVERY_HINT_PLAIN}")
     return token
 
 
 def prompt_for_user_secret() -> str:
-    entered = input(f"Paste {ENV_USER_SECRET} (your user secret): ")
+    _print_missing_credential_hint(ENV_USER_SECRET)
+    entered = input(cyan("🙍 ") + f"Paste {ENV_USER_SECRET} (your user secret): ")
     secret = entered.strip()
     if not secret:
-        raise ValueError("User secret cannot be empty.")
+        raise ValueError(f"User secret cannot be empty. {ENV_RECOVERY_HINT_PLAIN}")
     return secret
 
 
@@ -67,7 +83,8 @@ def resolve_project_context_for_cli_checks() -> CliProjectContext:
     session = session_raw.strip() if isinstance(session_raw, str) else ""
     if not project_id or not session:
         raise ValueError(
-            f"{ENV_PROJECT_TOKEN} looks invalid, or proj_auth did not return project_id/session."
+            f"{ENV_PROJECT_TOKEN} looks invalid, or proj_auth did not return project_id/session. "
+            f"{ENV_RECOVERY_HINT_PLAIN}"
         )
 
     return CliProjectContext(

auralogger/cli/cli_auth.py

@@ -5,13 +5,28 @@
 code stays free of filesystem env loading (same split as the Node package).
 """
 
+import io
 import os
+import sys
 from pathlib import Path
 from typing import Optional
 
 from dotenv import load_dotenv
 
 
+def ensure_utf8_stdio() -> None:
+    """Match Node/chalk emoji output on Windows (cp1252 default breaks Unicode)."""
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.StringIO):
+            continue
+        reconf = getattr(stream, "reconfigure", None)
+        if callable(reconf):
+            try:
+                reconf(encoding="utf-8", errors="replace")
+            except (OSError, ValueError, AttributeError, TypeError):
+                pass
+
+
 def load_cli_env_files(cwd: Optional[str] = None) -> None:
     base = Path(cwd or os.getcwd())
     verbose = os.environ.get("DOTENV_CONFIG_QUIET") == "false"

auralogger/cli/cli_load_env.py

@@ -0,0 +1,40 @@
+"""In-process CLI session memory — parity with node/src/cli/utility/cli-personality-state.ts."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+_consecutive_failures = 0
+_attempt_count_by_command: Dict[str, int] = {}
+_success_count_by_command: Dict[str, int] = {}
+
+
+def note_command_dispatch(command: str) -> None:
+    _attempt_count_by_command[command] = _attempt_count_by_command.get(command, 0) + 1
+
+
+def get_command_attempt_count(command: str) -> int:
+    return _attempt_count_by_command.get(command, 0)
+
+
+def record_cli_success(command: str) -> None:
+    global _consecutive_failures
+    _consecutive_failures = 0
+    _success_count_by_command[command] = _success_count_by_command.get(command, 0) + 1
+
+
+def record_cli_failure() -> None:
+    global _consecutive_failures
+    _consecutive_failures += 1
+
+
+def get_consecutive_failures() -> int:
+    return _consecutive_failures
+
+
+def get_successful_run_count(command: str) -> int:
+    return _success_count_by_command.get(command, 0)
+
+
+def get_total_successful_commands() -> int:
+    return sum(_success_count_by_command.values())