release: v1.2.0 — setup UX polish (completion install + creds validation)

Features
- orca completion install [shell]: auto-install shell completion (bash/zsh:
  append idempotent eval line to ~/.bashrc or ~/.zshrc; fish: write
  ~/.config/fish/completions/orca.fish via 'orca' subprocess). Auto-detects
  shell from $SHELL when omitted. Legacy 'orca completion <shell>' still
  prints instructions for backward compatibility.
- orca setup: at the end of the wizard, offer to auto-install shell
  completion for the detected shell; then validate the just-saved profile
  by hitting Keystone so typos / wrong auth URLs surface immediately.
  Both steps are skipped in non-TTY contexts (CI, piped input, tests).
- profile list: new 'Auth' column (password / app-cred) and 'User /
  Credential' column that shows the AC id for application-credential
  profiles (previously empty); project cell shows '(pre-scoped)' for AC.

Refactor
- Shell completion helpers moved from commands/setup.py to
  core/shell_completion.py and shared by both 'setup' and 'completion'.

Tests
- 2245 passing, coverage 85.59% (gate 85%).

Co-Authored-By: Claude Opus 4.7 <[email protected]>

Author: Kevin Allioli

orca_cli/commands/completion.py

@@ -1,10 +1,16 @@
-"""``orca completion`` — generate shell auto-completion scripts."""
+"""``orca completion`` — install shell auto-completion or print instructions."""
 
 from __future__ import annotations
 
 import click
 from rich.console import Console
 
+from orca_cli.core.shell_completion import (
+    SUPPORTED_SHELLS,
+    detect_shell,
+    install_completion,
+)
+
 console = Console()
 
 INSTRUCTIONS = {
@@ -23,14 +29,87 @@
 }
 
 
-@click.command()
-@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"], case_sensitive=False))
-def completion(shell: str) -> None:
-    """Generate shell completion script and display installation instructions.
-
-    Supported shells: bash, zsh, fish.
-    """
-    shell = shell.lower()
+def _print_instructions(shell: str) -> None:
     console.print(f"\n[bold cyan]Shell completion for {shell}[/bold cyan]\n")
     console.print(INSTRUCTIONS[shell])
-    console.print()
+    console.print(
+        f"\n[dim]Or run 'orca completion install {shell}' "
+        f"to install automatically.[/dim]\n"
+    )
+
+
+class _CompletionGroup(click.Group):
+    """Group that accepts a bare shell name as shorthand for ``show <shell>``.
+
+    Lets users keep the legacy ``orca completion bash`` UX while also exposing
+    the newer ``orca completion install <shell>`` subcommand.
+    """
+
+    def resolve_command(self, ctx, args):
+        if args and args[0].lower() in SUPPORTED_SHELLS:
+            return super().resolve_command(ctx, ["show", *args])
+        return super().resolve_command(ctx, args)
+
+
+@click.group(cls=_CompletionGroup, invoke_without_command=True)
+@click.pass_context
+def completion(ctx: click.Context) -> None:
+    """Shell completion: print instructions or install automatically.
+
+    \b
+    Examples:
+      orca completion                    # auto-detect shell, print instructions
+      orca completion bash               # print instructions for bash (legacy)
+      orca completion show zsh           # same, explicit
+      orca completion install            # auto-detect shell, install
+      orca completion install fish       # install for fish
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    # Bare ``orca completion`` → auto-detect + print
+    detected = detect_shell()
+    if not detected:
+        console.print(
+            "[yellow]Could not auto-detect your shell.[/yellow] "
+            "Pass one explicitly: [cyan]orca completion <bash|zsh|fish>[/cyan]."
+        )
+        ctx.exit(1)
+    _print_instructions(detected)
+
+
+@completion.command("show")
+@click.argument("shell", required=False,
+                type=click.Choice(list(SUPPORTED_SHELLS), case_sensitive=False))
+@click.pass_context
+def completion_show(ctx: click.Context, shell: str | None) -> None:
+    """Print manual installation instructions for the given shell."""
+    resolved = shell.lower() if shell else detect_shell()
+    if not resolved:
+        console.print(
+            "[yellow]Could not auto-detect your shell.[/yellow] "
+            "Pass one explicitly: [cyan]orca completion show <bash|zsh|fish>[/cyan]."
+        )
+        ctx.exit(1)
+    _print_instructions(resolved)
+
+
+@completion.command("install")
+@click.argument("shell", required=False,
+                type=click.Choice(list(SUPPORTED_SHELLS), case_sensitive=False))
+@click.pass_context
+def completion_install(ctx: click.Context, shell: str | None) -> None:
+    """Install orca shell completion (auto-detects shell when omitted).
+
+    \b
+    - bash/zsh: appends an eval line to ~/.bashrc / ~/.zshrc (idempotent).
+    - fish: writes ~/.config/fish/completions/orca.fish.
+    """
+    resolved = shell.lower() if shell else detect_shell()
+    if not resolved:
+        console.print(
+            "[red]Could not auto-detect your shell.[/red] "
+            "Pass one explicitly: [cyan]orca completion install <bash|zsh|fish>[/cyan]."
+        )
+        ctx.exit(1)
+    msg = install_completion(resolved)
+    console.print(f"[green]✓ {msg}[/green]")

orca_cli/commands/profile.py

@@ -87,6 +87,8 @@ def profile_list() -> None:
     """List all profiles."""
     from rich.table import Table
 
+    from orca_cli.core.config import _is_app_cred
+
     profiles = list_profiles()
     active = get_active_profile_name()
 
@@ -97,8 +99,9 @@ def profile_list() -> None:
     table = Table(title="Profiles", show_lines=False)
     table.add_column("", no_wrap=True)
     table.add_column("Name", style="bold")
+    table.add_column("Auth")
     table.add_column("Auth URL")
-    table.add_column("Username")
+    table.add_column("User / Credential")
     table.add_column("Project")
     table.add_column("Color")
 
@@ -107,12 +110,27 @@ def profile_list() -> None:
         marker = "[green bold]●[/green bold]" if name == active else " "
         display_name = f"[{color}]{name}[/{color}]" if color else name
         color_preview = f"[{color}]●[/{color}] {color}" if color else "—"
-        project = cfg.get("project_name") or cfg.get("project_id") or "—"
+
+        if _is_app_cred(cfg):
+            auth_label = "[magenta]app-cred[/magenta]"
+            user_cell = (
+                cfg.get("application_credential_id")
+                or cfg.get("application_credential_name")
+                or "—"
+            )
+            # AC is pre-scoped — project lives in the token, not the config.
+            project = "[dim](pre-scoped)[/dim]"
+        else:
+            auth_label = "[cyan]password[/cyan]"
+            user_cell = cfg.get("username") or "—"
+            project = cfg.get("project_name") or cfg.get("project_id") or "—"
+
         table.add_row(
             marker,
             display_name,
+            auth_label,
             cfg.get("auth_url", "—"),
-            cfg.get("username", "—"),
+            user_cell,
             project,
             color_preview,
         )

orca_cli/commands/setup.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import sys
+
 import click
 from rich.console import Console
 
@@ -13,9 +15,74 @@
     set_active_profile,
 )
 from orca_cli.core.context import OrcaContext
+from orca_cli.core.shell_completion import detect_shell, install_completion
 
 console = Console()
 
+
+def _maybe_install_completion() -> None:
+    """Offer to install shell completion for the detected shell.
+
+    Skipped when stdin isn't a TTY (CI, piped input, test harness) so the
+    wizard stays non-destructive outside interactive sessions.
+    """
+    if not sys.stdin.isatty():
+        return
+    shell = detect_shell()
+    if not shell:
+        console.print(
+            "[dim]Could not auto-detect your shell. "
+            "Run 'orca completion install <bash|zsh|fish>' if you want completion.[/dim]"
+        )
+        return
+    console.print(
+        f"\n[bold]Shell completion[/bold] (detected: [cyan]{shell}[/cyan])"
+    )
+    if not click.confirm("  Install orca completion now?", default=True):
+        console.print(
+            f"[dim]Skipped. Run 'orca completion install {shell}' later if you change your mind.[/dim]"
+        )
+        return
+    msg = install_completion(shell)
+    console.print(f"[green]✓ {msg}[/green]")
+
+
+def _maybe_validate_credentials(name: str) -> None:
+    """Attempt a fresh Keystone authentication with the just-saved profile.
+
+    Skipped when stdin isn't a TTY (test harness, piped input). This is a
+    read-only check: it authenticates, prints success/failure, then closes.
+    """
+    if not sys.stdin.isatty():
+        return
+    console.print(f"\n[bold]Validating credentials for '{name}'...[/bold]")
+    from orca_cli.core.client import OrcaClient
+    from orca_cli.core.exceptions import APIError, AuthenticationError, OrcaCLIError
+    cfg = load_config(profile_name=name)
+    client = None
+    try:
+        client = OrcaClient(cfg)
+        # Force a fresh auth to actually hit Keystone (bypasses any cached
+        # token that might belong to a prior profile with the same key).
+        client._authenticate()
+        console.print(f"[green]✓ Authentication successful[/green] "
+                      f"(catalog: {len(client._catalog)} services)")
+    except AuthenticationError as exc:
+        console.print(f"[red]✗ Authentication failed:[/red] {exc.message}")
+        console.print("[dim]Re-run 'orca setup' to fix the credentials.[/dim]")
+    except APIError as exc:
+        console.print(f"[red]✗ Keystone error ({exc.status_code}):[/red] {exc.message}")
+    except OrcaCLIError as exc:
+        console.print(f"[yellow]⚠ {exc.message}[/yellow]")
+    except Exception as exc:  # pragma: no cover — safety net
+        console.print(f"[yellow]⚠ Could not validate: {exc}[/yellow]")
+    finally:
+        if client is not None:
+            try:
+                client.close()
+            except Exception:
+                pass
+
 _PASSWORD_FIELDS = [
     ("auth_url", "Auth URL (Keystone)", "https://keystone.example.com:5000"),
     ("username", "Username", ""),
@@ -125,3 +192,6 @@ def setup(ctx: click.Context, profile_name: str | None) -> None:
             console.print(f"[green]Switched to '{name}'.[/green]\n")
     else:
         console.print()
+
+    _maybe_install_completion()
+    _maybe_validate_credentials(name)

orca_cli/core/shell_completion.py

@@ -0,0 +1,84 @@
+"""Shell completion install helpers.
+
+Used by both ``orca setup`` (offers auto-install at the end of the wizard)
+and ``orca completion`` (dedicated command to install or print instructions).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+_COMPLETION_EVAL = {
+    "bash": 'eval "$(_ORCA_COMPLETE=bash_source orca)"',
+    "zsh": 'eval "$(_ORCA_COMPLETE=zsh_source orca)"',
+}
+_COMPLETION_MARKER = "_ORCA_COMPLETE="  # presence = already installed
+
+_RC_FILE = {
+    "bash": Path("~/.bashrc"),
+    "zsh": Path("~/.zshrc"),
+}
+_FISH_COMPLETION_FILE = Path("~/.config/fish/completions/orca.fish")
+
+SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+
+
+def detect_shell() -> str | None:
+    """Return ``bash``/``zsh``/``fish`` based on ``$SHELL``, or ``None``."""
+    shell_env = os.environ.get("SHELL", "")
+    if not shell_env:
+        return None
+    name = Path(shell_env).name
+    return name if name in SUPPORTED_SHELLS else None
+
+
+def install_completion_bashzsh(shell: str) -> str:
+    """Append the completion eval line to the shell rc file (idempotent).
+
+    Returns a human-readable status message.
+    """
+    line = _COMPLETION_EVAL[shell]
+    rc = _RC_FILE[shell].expanduser()
+    if rc.exists() and _COMPLETION_MARKER in rc.read_text():
+        return f"Already present in {rc}."
+    rc.parent.mkdir(parents=True, exist_ok=True)
+    with rc.open("a") as fh:
+        fh.write(f"\n# orca-cli shell completion\n{line}\n")
+    return f"Appended to {rc}. Open a new shell or run: source {rc}"
+
+
+def install_completion_fish() -> str:
+    """Generate the fish completion script via ``orca`` and write it to
+    ``~/.config/fish/completions/orca.fish``.
+    """
+    target = _FISH_COMPLETION_FILE.expanduser()
+    if target.exists() and _COMPLETION_MARKER in target.read_text():
+        return f"Already present at {target}."
+    exe = shutil.which("orca")
+    if not exe:
+        return "orca not on PATH — run 'orca completion fish' for manual install."
+    target.parent.mkdir(parents=True, exist_ok=True)
+    env = os.environ.copy()
+    env["_ORCA_COMPLETE"] = "fish_source"
+    try:
+        result = subprocess.run(
+            [exe], env=env, capture_output=True, text=True, timeout=10, check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return f"Failed to generate fish completion: {exc}"
+    if result.returncode != 0 or not result.stdout.strip():
+        return f"orca completion generation failed: {result.stderr.strip() or 'empty output'}"
+    target.write_text(result.stdout)
+    return f"Wrote {target}. Start a new fish session."
+
+
+def install_completion(shell: str) -> str:
+    """Install completion for ``shell``. Dispatches to the right helper."""
+    if shell == "fish":
+        return install_completion_fish()
+    if shell in ("bash", "zsh"):
+        return install_completion_bashzsh(shell)
+    raise ValueError(f"Unsupported shell: {shell}")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "orca-openstackclient"
-version = "1.1.0"
+version = "1.2.0"
 description = "orca — OpenStack Rich Command-line Alternative"
 authors = ["Kevin Allioli"]
 license = "Apache-2.0"