feat(cli): omoios completion show / install — zsh / bash / fish

Phase 3 of the four-piece roadmap. Wraps cyclopts' built-in completion
generator (`app.generate_completion`, `app.install_completion`) with
two user-facing modes per the design call:

- `omoios completion show [zsh|bash|fish]`
  Prints the script to stdout (raw, no Rich formatting) so it can be
  eval'd from a dotfile:
      eval "$(omoios completion show zsh)"
  Auto-detects $SHELL when the argument is omitted.
- `omoios completion install [zsh|bash|fish] [--output PATH] [--no-startup]`
  Writes to the shell's standard completion location and (by default)
  appends a `source` line to the matching RC file. `--no-startup`
  skips the RC write for users who manage their fpath manually.

Both rely on cyclopts ≥4.4 — earlier versions don't expose these
methods. Lazy-imports the root `app` from `omoios.cli.main` to dodge
the circular import.

Generated zsh script discovered via `omoios completion show zsh`:
  #compdef omoios
  _omoios() {
    ... 'workspaces:…' 'environments:…' 'providers:…' 'sessions:…'
        'webhooks:…' 'artifacts:…' 'connections:…' 'usage:…' ...
  }
Bash variant covers options-with-values + per-subcommand argument
lists. Fish supported the same way.

Tests: 14/14 still green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kivo360

sdk/python/omoios/cli/completion.py

@@ -0,0 +1,94 @@
+"""`omoios completion` — shell completion management.
+
+Two modes (per the design call): eval-friendly + file-install. Cyclopts
+ships the actual completion-script generation; this module is just the
+user-facing CLI wrapper that exposes both shapes.
+
+  - `omoios completion show [SHELL]` — print the script to stdout
+    (for `eval "$(omoios completion show zsh)"` in dotfiles).
+  - `omoios completion install [SHELL]` — write the completion script
+    to the shell's standard location and append a source line to the
+    matching RC file. Uses cyclopts' built-in `install_completion`.
+
+Both auto-detect `$SHELL` when the argument is omitted.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Optional
+
+from cyclopts import App, Parameter
+
+from omoios.cli._ui import CliError, console, ok
+
+
+completion_app = App(
+    name="completion",
+    help="Generate or install shell completion (zsh / bash / fish).",
+)
+
+
+@completion_app.command(name="show")
+def show_cmd(
+    shell: Annotated[
+        Optional[Literal["zsh", "bash", "fish"]],
+        Parameter(help="Target shell. Auto-detected from $SHELL if omitted."),
+    ] = None,
+) -> None:
+    """Print the completion script to stdout (eval-friendly)."""
+    # Lazy import to avoid circulating with `omoios.cli.main`.
+    from omoios.cli.main import app
+
+    try:
+        script = app.generate_completion(shell=shell, prog_name="omoios")
+    except Exception as exc:  # noqa: BLE001 — translate cyclopts' own errors
+        raise CliError(f"could not generate completion: {exc}") from exc
+
+    # `console.print` would Rich-format; we want raw shell so it's eval-able.
+    print(script)
+
+
+@completion_app.command(name="install")
+def install_cmd(
+    shell: Annotated[
+        Optional[Literal["zsh", "bash", "fish"]],
+        Parameter(help="Target shell. Auto-detected from $SHELL if omitted."),
+    ] = None,
+    output: Annotated[
+        Optional[str],
+        Parameter(
+            name=["--output", "-o"],
+            help=(
+                "Override the install location. Defaults to the shell's "
+                "standard completion path."
+            ),
+        ),
+    ] = None,
+    no_startup: Annotated[
+        bool,
+        Parameter(
+            name="--no-startup",
+            help="Skip appending a source line to the shell RC file.",
+        ),
+    ] = False,
+) -> None:
+    """Install the completion script to the shell's standard location."""
+    from pathlib import Path
+
+    from omoios.cli.main import app
+
+    try:
+        path = app.install_completion(
+            shell=shell,
+            output=Path(output) if output else None,
+            add_to_startup=not no_startup,
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise CliError(f"could not install completion: {exc}") from exc
+
+    ok(f"installed completion → [dim]{path}[/dim]")
+    if not no_startup:
+        console.print(
+            "  [dim]source line appended to your shell rc; restart the "
+            "shell or `source` it to activate.[/dim]"
+        )

sdk/python/omoios/cli/main.py

@@ -28,6 +28,7 @@
 from omoios.cli._ui import CliError, die, err_console
 from omoios.cli.artifacts import artifacts_app
 from omoios.cli.auth import auth_app
+from omoios.cli.completion import completion_app
 from omoios.cli.config import config_app
 from omoios.cli.connections import connections_app
 from omoios.cli.environments import environments_app
@@ -60,6 +61,7 @@
 app.command(usage_app)
 app.command(auth_app)
 app.command(config_app)
+app.command(completion_app)
 app.command(signup)
 app.command(whoami)