cli.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/cli.py
 
"""
Command-line shell helpers — argparse, presenter selection, terminal clear.
 
Purpose
-------
The argparse front end, the ``--ui`` / ``--log-events`` resolution
that picks between :class:`ConsolePresenter`, ``RichPresenter`` and
:class:`LoggingPresenter`, and the cross-platform terminal-clear
helper. These are pure shell concerns — sub-agents and headless
:class:`~oc_chat.core.agent.Agent` callers never need them, so they
sit one layer above the runtime rather than tangled inside
``main.py`` (G.6.C separation per Plan G.6 §2).
 
Responsibilities
----------------
- :func:`build_arg_parser` — construct the CLI ``argparse.ArgumentParser``
  with ``--ui``, ``--no-color``, ``--workdir``, ``--verbose``, ``--log-events`` flags.
- :func:`select_presenter` — resolve the presenter from the parsed
  args (or env vars) with graceful fallback when ``rich`` is missing.
- :func:`clear_terminal` — cross-platform terminal-clear; the REPL
  calls it once at startup before printing the banner.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events (presenter resolution decisions).
    L3 — semantic details.
    L4 — deep tracing.
 
Contracts
---------
- Presenter resolution precedence: ``--ui`` flag > ``OC_CHAT_UI``
  env > built-in default, which is ``rich`` for an interactive launch
  (the package imports AND stdout is a tty) and ``plain`` otherwise —
  non-tty stdout, batch mode, or ``rich`` not installed. The previous
  ``plain`` default stays reachable at any time via ``--ui plain`` or
  ``OC_CHAT_UI=plain``; the full matrix is on
  :func:`select_presenter` (plan 147 D3, pinned by plan 188 T3 in
  ``tests/unit/test_188_rich_default.py``).
- ``--log-events PATH`` wraps the resolved presenter in a
  :class:`LoggingPresenter` that tees every event to PATH.
- ``--workdir PATH`` is declared for documentation and ``--help``
  display only; the actual ``os.chdir`` happens in the preflight
  inside ``__main__.py`` before any ``oc_chat`` imports.
- Falls back from ``rich`` → ``plain`` with a single stderr warning
  when the optional dep is missing — never raises.
- ``clear_terminal`` is best-effort; failure is silently ignored
  (the banner that follows is fine even with a non-clearing
  terminal).
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_ui.terminal.presenter (ConsolePresenter — plain-text fallback)
- oc_ui.terminal.logging_presenter (lazy; LoggingPresenter — JSON-lines tee)
- oc_chat.core.config (DEFAULT_CONTEXT_WINDOW_SIZE - the enhanced presenter's context-window fallback)
- oc_chat.core.settings (lazy; load_settings - the settings verbose default)
- oc_ui.presenter_base (lazy; Presenter - type hint for select_presenter's return)
- oc_ui.terminal.enhanced_presenter (lazy; EnhancedPresenter - the enhanced UI with real-time statistics)
- oc_ui.terminal.rich_presenter (lazy; RichPresenter - the rich UI, falling back to plain when rich is missing)
- rich (lazy; presence probe for the implicit rich default)
"""
from __future__ import annotations
 
import argparse
import os
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
from oc_chat.core.config import DEFAULT_CONTEXT_WINDOW_SIZE
 
from oc_ui.terminal.presenter import ConsolePresenter
 
if TYPE_CHECKING:
    from oc_ui.presenter_base import Presenter
 
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
def clear_terminal() -> None:
    """Clear the terminal screen in a cross-platform way."""
    import sys
    if "--input" in sys.argv or "--output" in sys.argv:
        return
    if os.name == 'nt':
        os.system('cls')
    else:
        os.system('clear')
 
 
def build_arg_parser() -> argparse.ArgumentParser:
    """Construct the CLI argument parser.
 
    Precedence for any presenter / colour decision:
    CLI flag > environment variable > config file > built-in default.
    """
    p = argparse.ArgumentParser(
        prog="oc_chat",
        description="Interactive Option C chat client with ReAct agentic loop.",
    )
    p.add_argument(
        "--ui",
        choices=["plain", "rich", "enhanced"],
        default=None,
        help="presenter mode (default: rich when the rich package is "
             "installed and stdout is a tty, else plain; batch mode "
             "(--input/--output) always defaults to plain; enhanced: "
             "real-time statistics)",
    )
    p.add_argument(
        "--enhanced-ui",
        action="store_true",
        help="Enable enhanced terminal UI with real-time statistics",
    )
    p.add_argument(
        "--no-color", action="store_true",
        help="No ANSI colours."
             "Honoured by the standard NO_COLOR env var as well.",
    )
    p.add_argument(
        "--workdir",
        metavar="PATH",
        default=None,
        help="chdir here before anchoring (sandbox root, state dir, and "
             "session anchors all follow); applied at preflight — lets "
             "oc_chat be launched from anywhere",
    )
    # Plan 134 C1: tri-state so the settings `verbose` knob can drive the
    # launch default. default=None means "unset" → fall back to settings;
    # --verbose forces on, --no-verbose forces off (CLI wins over settings).
    p.add_argument(
        "--verbose", dest="verbose", action="store_true", default=None,
        help="Show per-iteration token usage in addition to the compact "
             "turn summary. Overrides the settings `verbose` default.",
    )
    p.add_argument(
        "--no-verbose", dest="verbose", action="store_false",
        help="Suppress per-iteration token usage (overrides the settings "
             "`verbose` default).",
    )
    p.add_argument(
        "--log-events", metavar="PATH", default=None,
        help="Tee every presenter event to a JSON-lines log at PATH. "
             "Useful for replay, CI diffing, and debugging UI glitches. "
             "The wrapped presenter still renders normally.",
    )
    p.add_argument(
        "--session",
        metavar="NAME",
        default=None,
        help="Load or create a named session for this run.",
    )
    p.add_argument(
        "--input",
        metavar="PATH",
        default=None,
        help="Read the user prompt from this file, or '-' for stdin. "
             "When set, OC Chat runs one turn non-interactively and skips the REPL.",
    )
    p.add_argument(
        "--output",
        metavar="PATH",
        default=None,
        help="Write the assistant response to this file, or '-' for stdout. "
             "When set, OC Chat runs one turn non-interactively and silences banners.",
    )
    p.add_argument(
        "--stats-file", metavar="PATH", default=None,
        help="Write per-iteration stats as CSV lines to PATH. ",
    )
    p.add_argument(
        "--max-context-size", metavar="SIZE", type=int, default=None,
        # OCT-LINT: disable=no_hardcoded_secrets reason="argparse --help prose mis-flagged as a high-entropy string; not a secret"
        help="Context-window size (tokens) for the enhanced-UI context gauge. "
             "Default: auto-derive from the active model (plan 134 N5). An "
             "explicit value overrides the model-derived window.",
    )
    p.add_argument(
        "--no-iteration-stats", action="store_true",
        help="Suppress per-iteration stat lines from terminal. ",
    )
    p.add_argument(
        "--mode", metavar="NAME", default=None,
        help="System-prompt composition mode from .oc_chat/oc_chat-settings.json "
             "(e.g. standard, option-c). Overrides the file's default for this launch.",
    )
    p.add_argument(
        "--option-c", action="store_true",
        help="Convenience alias for --mode option-c (full Option C working context).",
    )
    # Plan 283 (SHELL-04). The plan spells this "--mode auto", but --mode was
    # already taken above by the system-prompt COMPOSITION mode (standard /
    # option-c), so the launch spelling of "/mode auto" is its own flag rather
    # than a second meaning for an occupied one.
    p.add_argument(
        "--auto", action="store_true",
        help="Start in Auto confirmation mode: the routine Tier-2 and "
             "external-content asks are answered without a keystroke (the "
             "launch spelling of /mode auto). A protected write still always "
             "reaches you, and the mode applies only under the permissive risk "
             "profile. /mode ask switches back at any time.",
    )
    return p
 
 
def _resolve_verbose(args: argparse.Namespace) -> bool:
    """Resolve effective verbosity (plan 134 C1, N1).
 
    Precedence: explicit CLI flag (``--verbose`` / ``--no-verbose``) >
    ``.local`` settings > committed settings > built-in default. ``args.verbose``
    is tri-state: ``None`` means "unset" → fall back to the settings ``verbose``
    knob; ``True``/``False`` came from an explicit flag and win.
    """
    cli = getattr(args, "verbose", None)
    if cli is not None:
        return bool(cli)
    try:
        from oc_chat.core.settings import load_settings
        return bool(load_settings().verbose)
    except Exception:  # noqa: BLE001 — settings load is best-effort; default quiet
        return False
 
 
def _rich_importable() -> bool:
    """True iff the optional ``rich`` package can be imported.
 
    A cheap presence probe for the plan 147 D3 implicit-default matrix —
    deliberately separate from actually constructing a ``RichPresenter``
    (the explicit-``--ui rich`` path below still owns its own
    ImportError-to-plain fallback + stderr warning).
    """
    try:
        import rich  # noqa: F401
        return True
    except ImportError:
        return False
 
 
def select_presenter(args: argparse.Namespace) -> "Presenter":
    """Resolve the presenter to use — the plan 147 D3 pinned selection matrix.
 
    Precedence:
 
    - Explicit ``--ui`` flag or ``OC_CHAT_UI`` env var: honoured whenever
      ``rich``/``enhanced`` import — even non-tty and even in batch mode
      (uniform precedence, a defined outcome for captured/test runs) — via
      the existing ImportError-to-plain fallback + stderr warning below.
    - Implicit (neither set) + batch mode (``--input``/``--output`` present):
      ``plain`` regardless of tty — batch is non-interactive by definition;
      a globally exported ``OC_CHAT_UI`` would otherwise silently pollute
      CI/headless captured output with implicit chrome (the explicit row
      above still opts in deliberately).
    - Implicit + interactive: ``rich`` when the package imports AND
      ``sys.stdout.isatty()`` (stdout, not stdin, governs — Rich renders to
      stdout); else ``plain``.
    - ``NO_COLOR``: MONOCHROME-RICH (ratified 2026-07-12) — deliberately NOT
      checked here. Whatever presenter the rows above resolve stays
      resolved; ``rich.console.Console`` honours ``NO_COLOR`` natively
      (verified: no_color=True / color_system=None with no explicit pass-
      through needed), so this is never a presenter downgrade.
    - The legacy ``--enhanced-ui`` flag keeps its pre-existing absolute-
      override precedence (checked independently of ``want`` below,
      unchanged from before D3).
 
    Lazy-imports :class:`RichPresenter` on demand so the optional ``rich``
    dependency is not required at module-import time.
 
    If ``--log-events PATH`` was passed, the resolved presenter is
    wrapped in a :class:`LoggingPresenter` that tees every event to PATH
    in JSON-lines format.
    """
    import sys
    func = "select_presenter"
    verbose = _resolve_verbose(args)
 
    explicit = args.ui or os.getenv("OC_CHAT_UI")
    if explicit:
        want = explicit
        _dbg("OC_CHAT.MAIN", func, f"explicit ui={want!r}", 3)
    else:
        is_batch = getattr(args, "input", None) is not None or getattr(args, "output", None) is not None
        if is_batch:
            want = "plain"
        else:
            want = "rich" if (_rich_importable() and sys.stdout.isatty()) else "plain"
        _dbg("OC_CHAT.MAIN", func, f"implicit ui={want!r} batch={is_batch}", 3)
 
    if want == "rich":
        try:
            from oc_ui.terminal.rich_presenter import RichPresenter
            inner = RichPresenter(verbose=verbose)
            _dbg("OC_CHAT.MAIN", func, "selected RichPresenter", 2)
        except ImportError as exc:
            # VALIDATION_ERROR — optional dep missing; fall back to plain
            _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: rich not installed: {exc}", 3)
            print(
                f"[--ui rich requested but `rich` is not installed ({exc}). "
                f"Install with: pip install -e .[rich].  Falling back to plain.]",
                file=sys.stderr,
            )
            inner = ConsolePresenter(verbose=verbose)
    elif want == "enhanced" or getattr(args, "enhanced_ui", False):
        try:
            from oc_ui.terminal.enhanced_presenter import EnhancedPresenter
            inner = EnhancedPresenter(
                model="deepseek-v4-pro",
                max_context_size=getattr(args, "max_context_size", DEFAULT_CONTEXT_WINDOW_SIZE),
                verbose=verbose,
            )
            _dbg("OC_CHAT.MAIN", func, "selected EnhancedPresenter", 2)
        except ImportError as exc:
            # VALIDATION_ERROR — optional dep missing; fall back to plain
            _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: enhanced UI not available: {exc}", 3)
            print(
                f"[--ui enhanced requested but components missing ({exc}). "
                f"Falling back to plain.]",
                file=sys.stderr,
            )
            inner = ConsolePresenter(verbose=verbose)
    else:
        inner = ConsolePresenter(verbose=verbose)
        _dbg("OC_CHAT.MAIN", func, "selected ConsolePresenter", 2)
 
    log_path = getattr(args, "log_events", None)
    if log_path:
        from oc_ui.terminal.logging_presenter import LoggingPresenter
        return LoggingPresenter(inner, log_path)
    return inner