comate-cli 0.7.6__tar.gz → 0.7.8__tar.gz

{comate_cli-0.7.6 → comate_cli-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.7.6
+Version: 0.7.8
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk

{comate_cli-0.7.6 → comate_cli-0.7.8}/comate_cli/main.py

@@ -7,7 +7,12 @@ import os
 import signal
 import subprocess
 import sys
+import time
 import warnings
+
+# 进程启动锚点：在任何重三方库 import（anthropic/prompt_toolkit/rich）之前捕获，
+# 交给 StartupProfiler 测量「run() 之前的 import」这段以往不可见的启动成本。
+_PROCESS_START_PERF = time.perf_counter()
 try:
     import termios
 except ImportError:
@@ -268,7 +273,9 @@ def main(argv: list[str] | None = None) -> None:
     atexit.register(term_guard.restore, reason="atexit")
     atexit.register(noise_guard.begin_shutdown)
 
+    _app_import_start_perf = time.perf_counter()
     from comate_cli.terminal_agent.app import run
+    _app_import_done_perf = time.perf_counter()
 
     try:
         rpc_stdio, resume_session_id, resume_select, print_prompt = _parse_args(run_argv)
@@ -295,6 +302,9 @@ def main(argv: list[str] | None = None) -> None:
                 resume_session_id=resume_session_id,
                 resume_select=resume_select,
                 print_message=print_message,
+                process_start_perf=_PROCESS_START_PERF,
+                app_import_start_perf=_app_import_start_perf,
+                app_import_done_perf=_app_import_done_perf,
             )
         )
     except KeyboardInterrupt:

{comate_cli-0.7.6 → comate_cli-0.7.8}/comate_cli/terminal_agent/app.py

@@ -11,34 +11,18 @@ import time
 from collections.abc import Iterator
 from contextlib import contextmanager, suppress
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from rich.console import Console
 
-from comate_agent_sdk.agent import Agent, AgentConfig, ChatSession, TextEvent
-from comate_agent_sdk.context import EnvOptions
-from comate_agent_sdk.tools import tool
-
-from comate_cli.terminal_agent.event_renderer import EventRenderer
-from comate_cli.terminal_agent.logo import print_logo
-from comate_cli.terminal_agent.preflight import run_preflight_if_needed
-from comate_cli.terminal_agent.resume_selector import select_resume_session_id
-from comate_cli.terminal_agent.rpc_stdio import StdioRPCBridge
 from comate_cli.terminal_agent.startup_profile import StartupProfiler
-from comate_cli.terminal_agent.status_bar import StatusBar
-from comate_cli.terminal_agent.tui import TerminalAgentTUI
-from comate_cli.terminal_agent.update_check import (
-    UpdateInfo,
-    UpdatePromptChoice,
-    UpdatePromptDecision,
-    check_update,
-    decide_update_prompt,
-    format_update_hint,
-    get_pending_update_prompt_info,
-    mark_update_seen,
-    record_skip_until_next_version,
-    run_update_command,
-    show_update_prompt,
-)
+
+if TYPE_CHECKING:
+    from comate_agent_sdk.agent.chat_session import ChatSession
+    from comate_agent_sdk.agent.core.template import AgentTemplate as Agent
+    from comate_agent_sdk.agent.events import TextEvent
+    from comate_cli.terminal_agent.event_renderer import EventRenderer
+    from comate_cli.terminal_agent.update_check import UpdateInfo
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -54,6 +38,7 @@ async def _check_update(*, profiler: StartupProfiler | None = None) -> UpdateInf
     if profiler is not None:
         profiler.mark("impl.start")
     try:
+        check_update, _, _, _ = _import_update_check_core()
         return await check_update(log=logger, profiler=profiler)
     finally:
         if profiler is not None:
@@ -65,6 +50,16 @@ async def _handle_update_on_launch(info: UpdateInfo) -> bool:
 
     Returns True when launch should stop after a successful update.
     """
+    (
+        UpdatePromptChoice,
+        UpdatePromptDecision,
+        decide_update_prompt,
+        format_update_hint,
+        mark_update_seen,
+        record_skip_until_next_version,
+        run_update_command,
+        show_update_prompt,
+    ) = _import_update_prompt_components()
     try:
         decision = decide_update_prompt(info)
         if decision == UpdatePromptDecision.SKIP:
@@ -87,21 +82,31 @@ async def _handle_update_on_launch(info: UpdateInfo) -> bool:
 async def _handle_background_update_on_launch(
     info: UpdateInfo,
     *,
-    status_bar: StatusBar,
+    renderer: EventRenderer,
     profiler: StartupProfiler,
 ) -> None:
+    (
+        _UpdatePromptChoice,
+        UpdatePromptDecision,
+        decide_update_prompt,
+        format_update_hint,
+        mark_update_seen,
+        _record_skip_until_next_version,
+        _run_update_command,
+        _show_update_prompt,
+    ) = _import_update_prompt_components()
     try:
         decision = decide_update_prompt(info)
         if decision == UpdatePromptDecision.SKIP:
             profiler.mark("update_check.skip")
             return
         if decision == UpdatePromptDecision.SHOW_HINT:
-            status_bar.show_transient(format_update_hint(info), duration_s=8.0)
+            renderer.append_system_message(format_update_hint(info))
             mark_update_seen(info)
             profiler.mark("update_check.hint")
             return
 
-        status_bar.show_transient(format_update_hint(info), duration_s=8.0)
+        renderer.append_system_message(format_update_hint(info))
         profiler.mark("update_check.prompt_deferred")
     except Exception:
         logger.debug("startup background update handling failed", exc_info=True)
@@ -110,7 +115,7 @@ async def _handle_background_update_on_launch(
 
 def _schedule_update_check_on_launch(
     *,
-    status_bar: StatusBar,
+    renderer: EventRenderer,
     profiler: StartupProfiler,
 ) -> asyncio.Task[None]:
     async def _run() -> None:
@@ -124,7 +129,7 @@ def _schedule_update_check_on_launch(
             if update_info is not None:
                 await _handle_background_update_on_launch(
                     update_info,
-                    status_bar=status_bar,
+                    renderer=renderer,
                     profiler=profiler,
                 )
         except asyncio.CancelledError:
@@ -196,6 +201,121 @@ def _sigint_guard() -> Iterator[None]:
             logger.warning(f"Failed to restore SIGINT handler: {exc}", exc_info=True)
 
 
+@contextmanager
+def _profile_section(
+    profiler: StartupProfiler | None,
+    phase: str,
+) -> Iterator[None]:
+    if profiler is not None:
+        profiler.mark(f"{phase}.start")
+    try:
+        yield
+    finally:
+        if profiler is not None:
+            profiler.mark(f"{phase}.done")
+
+
+def _import_preflight_runner():
+    from comate_cli.terminal_agent.preflight import run_preflight_if_needed
+
+    return run_preflight_if_needed
+
+
+def print_logo(*args, **kwargs) -> None:
+    from comate_cli.terminal_agent.logo import print_logo as _print_logo
+
+    _print_logo(*args, **kwargs)
+
+
+def _import_sdk_agent_components(
+    profiler: StartupProfiler | None = None,
+) -> tuple[type, type, type, type]:
+    with _profile_section(profiler, "main.import.sdk_agent"):
+        from comate_agent_sdk.agent.compaction import CompactionConfig
+        from comate_agent_sdk.agent.options import AgentConfig
+        from comate_agent_sdk.agent.service import Agent
+        from comate_agent_sdk.context import EnvOptions
+
+    return Agent, AgentConfig, CompactionConfig, EnvOptions
+
+
+def _import_chat_session() -> type:
+    from comate_agent_sdk.agent.chat_session import ChatSession
+
+    return ChatSession
+
+
+def _import_print_mode_components() -> tuple[type, type]:
+    from comate_agent_sdk.agent.chat_session import ChatSession
+    from comate_agent_sdk.agent.events import TextEvent
+
+    return ChatSession, TextEvent
+
+
+def _import_rpc_bridge() -> type:
+    from comate_cli.terminal_agent.rpc_stdio import StdioRPCBridge
+
+    return StdioRPCBridge
+
+
+def _import_resume_selector():
+    from comate_cli.terminal_agent.resume_selector import select_resume_session_id
+
+    return select_resume_session_id
+
+
+def _import_interactive_tui_components(
+    profiler: StartupProfiler | None = None,
+):
+    with _profile_section(profiler, "main.import.tui"):
+        from comate_cli.terminal_agent.event_renderer import EventRenderer
+        from comate_cli.terminal_agent.logging_adapter import setup_tui_logging
+        from comate_cli.terminal_agent.status_bar import StatusBar
+        from comate_cli.terminal_agent.tui import TerminalAgentTUI
+
+    return EventRenderer, setup_tui_logging, StatusBar, TerminalAgentTUI
+
+
+def _import_update_check_core():
+    from comate_cli.terminal_agent.update_check import (
+        check_update,
+        get_pending_update_prompt_info,
+        record_update_check_attempt,
+        should_check_for_update,
+    )
+
+    return (
+        check_update,
+        get_pending_update_prompt_info,
+        record_update_check_attempt,
+        should_check_for_update,
+    )
+
+
+def _import_update_prompt_components():
+    from comate_cli.terminal_agent.update_check import (
+        UpdatePromptChoice,
+        UpdatePromptDecision,
+        decide_update_prompt,
+        format_update_hint,
+        mark_update_seen,
+        record_skip_until_next_version,
+        run_update_command,
+        show_update_prompt,
+    )
+
+    return (
+        UpdatePromptChoice,
+        UpdatePromptDecision,
+        decide_update_prompt,
+        format_update_hint,
+        mark_update_seen,
+        record_skip_until_next_version,
+        run_update_command,
+        show_update_prompt,
+    )
+
+
 async def _shutdown_session(session: ChatSession, *, label: str) -> None:
     start = time.monotonic()
     try:
@@ -233,17 +353,12 @@ async def _graceful_shutdown(*sessions: ChatSession) -> None:
     logger.info(f"Graceful shutdown completed in {elapsed:.3f}s")
 
 
-@tool("Add two numbers 涉及到加法运算 必须使用这个工具")
-async def add(a: int, b: int) -> int:
-    return a + b
-
-
 def _build_agent(
     *,
     project_root: Path | None = None,
     profiler: StartupProfiler | None = None,
 ) -> Agent:
-    from comate_agent_sdk.agent.compaction import CompactionConfig
+    Agent, AgentConfig, CompactionConfig, EnvOptions = _import_sdk_agent_components(profiler)
     from comate_cli.terminal_agent.config import store
 
     resolved_project_root = project_root or _resolve_cli_project_root()
@@ -281,6 +396,7 @@ def _resolve_session(
     cwd: Path | None = None,
     profiler: StartupProfiler | None = None,
 ) -> tuple[ChatSession, str]:
+    ChatSession = _import_chat_session()
     if resume_session_id:
         if profiler is not None:
             profiler.mark("session.resume.construct.start")
@@ -387,6 +503,7 @@ async def _run_print_mode(
     *,
     project_root: Path,
 ) -> None:
+    ChatSession, TextEvent = _import_print_mode_components()
     session = ChatSession(agent, cwd=project_root, persistent=False)
     try:
         await _preload_mcp_in_tui(session)
@@ -440,13 +557,25 @@ async def run(
     resume_session_id: str | None = None,
     resume_select: bool = False,
     print_message: str | None = None,
+    process_start_perf: float | None = None,
+    app_import_start_perf: float | None = None,
+    app_import_done_perf: float | None = None,
 ) -> None:
     _install_event_loop_exception_handler()
-    profiler = StartupProfiler.from_env(logger=logger)
+    # process_start_perf 由入口 main() 在模块 import 之前捕获，使 profiler 能测到
+    # 「run() 之前的重三方库 import」这段以往不可见的启动成本（柱子 A）。
+    profiler = StartupProfiler.from_env(logger=logger, started_at=process_start_perf)
+    if app_import_start_perf is not None:
+        profiler.mark_at("main.app_import.start", app_import_start_perf)
+        profiler.mark_at("main.import.app.start", app_import_start_perf)
+    if app_import_done_perf is not None:
+        profiler.mark_at("main.app_import.done", app_import_done_perf)
+        profiler.mark_at("main.import.app.done", app_import_done_perf)
     profiler.mark("cli_project_root.start")
     project_root = _resolve_cli_project_root()
     profiler.mark("cli_project_root.done")
     profiler.mark("preflight.start")
+    run_preflight_if_needed = _import_preflight_runner()
     preflight_result = await run_preflight_if_needed(
         console=console,
         project_root=project_root,
@@ -462,6 +591,12 @@ async def run(
         print_logo(console, project_root=project_root)
         profiler.mark("logo.printed")
 
+        (
+            _check_update_func,
+            get_pending_update_prompt_info,
+            _record_update_check_attempt,
+            _should_check_for_update,
+        ) = _import_update_check_core()
         pending_info = get_pending_update_prompt_info()
         if pending_info is not None:
             should_stop = await _handle_update_on_launch(pending_info)
@@ -483,6 +618,7 @@ async def run(
             cwd=project_root,
             profiler=profiler,
         )
+        StdioRPCBridge = _import_rpc_bridge()
         bridge = StdioRPCBridge(session)
         try:
             await bridge.run()
@@ -496,6 +632,7 @@ async def run(
         return
 
     if resume_select and not resume_session_id:
+        select_resume_session_id = _import_resume_selector()
         selected_session_id = await select_resume_session_id(console, cwd=project_root)
         if not selected_session_id:
             return
@@ -504,8 +641,8 @@ async def run(
     # 在 _resolve_session 前安装 TUILoggingHandler，确保 session 初始化期间
     # 的 logger.warning()（如 user_instruction token 超限）能被 TUI 系统捕获，
     # 而非 fallthrough 到 Python lastResort StreamHandler 以原始文本输出到 stderr。
+    EventRenderer, setup_tui_logging, StatusBar, TerminalAgentTUI = _import_interactive_tui_components(profiler)
     renderer = EventRenderer(project_root=project_root)
-    from comate_cli.terminal_agent.logging_adapter import setup_tui_logging
     profiler.mark("logging.setup.start")
     logging_session = setup_tui_logging(renderer, project_root=project_root)
     profiler.mark("logging.setup.done")
@@ -538,10 +675,22 @@ async def run(
     tui = TerminalAgentTUI(session, status_bar, renderer)
     profiler.mark("tui.init.done")
     tui.add_resume_history(mode)
-    update_check_task = _schedule_update_check_on_launch(
-        status_bar=status_bar,
-        profiler=profiler,
-    )
+    update_check_task: asyncio.Task[None] | None = None
+    (
+        _check_update_func,
+        _get_pending_update_prompt_info,
+        record_update_check_attempt,
+        should_check_for_update,
+    ) = _import_update_check_core()
+    if should_check_for_update():
+        # attempt 语义：先记录尝试时间，确保 interval 内最多发起一次网络检查
+        record_update_check_attempt()
+        update_check_task = _schedule_update_check_on_launch(
+            renderer=renderer,
+            profiler=profiler,
+        )
+    else:
+        profiler.mark("update_check.throttled")
 
     async def _mcp_loader() -> None:
         await _preload_mcp_in_tui(session, profiler=profiler.child("mcp"))
@@ -569,11 +718,12 @@ async def run(
             )
     finally:
         try:
-            await _cancel_background_task(
-                update_check_task,
-                timeout_s=0.1,
-                task_name="terminal-update-check",
-            )
+            if update_check_task is not None:
+                await _cancel_background_task(
+                    update_check_task,
+                    timeout_s=0.1,
+                    task_name="terminal-update-check",
+                )
             if active_session is session:
                 await _graceful_shutdown(active_session)
             else:

{comate_cli-0.7.6 → comate_cli-0.7.8}/comate_cli/terminal_agent/event_renderer.py

@@ -1128,15 +1128,17 @@ class EventRenderer:
         diff_lines: list[str] | None = None,
         model_name: str = "",
         subtitle: str | None = None,
+        file_path: str | None = None,
     ) -> None:
         """Append a tool result to history as a static entry (no timer).
 
         Args:
             signature: 工具签名，例如 "Read(path=xxx)"
             is_error: 是否为错误结果
-            diff_lines: optional diff lines for Edit
+            diff_lines: optional diff lines for Edit/Write
             model_name: model name for Agent tools (rendered dim)
             subtitle: optional subtitle rendered as `⎿ ...`
+            file_path: optional source path used for syntax highlighting diff body
         """
         sev: Literal["info", "warning", "error"] = "error" if is_error else "info"
         sub_sty: Literal["error", "warning", "dim"] = "dim"
@@ -1145,7 +1147,7 @@ class EventRenderer:
             if model_name:
                 text_obj.append(f" {BULLET_OPERATOR} {model_name}", style="dim")
             text_obj.append("\n")
-            text_obj.append(render_diff_text(diff_lines))
+            text_obj.append(render_diff_text(diff_lines, file_path=file_path))
             self._append_history_entry(
                 HistoryEntry(entry_type="tool_result", text=text_obj, severity="info", subtitle=subtitle)
             )

comate_cli-0.7.8/comate_cli/terminal_agent/preflight.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import logging
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, Mapping, Sequence
+
+from rich.console import Console
+
+from comate_agent_sdk.agent.llm_levels import ALL_LEVELS
+from comate_agent_sdk.agent.settings import (
+    USER_SETTINGS_PATH,
+    read_settings_json_object,
+    write_settings_json_atomic,
+)
+from comate_agent_sdk.facade.config.providers import (
+    PROVIDER_PRESETS,
+    LevelConfigDraft,
+    PreflightCheckResult,
+    ProviderPreset,
+    build_preview_payload,
+    evaluate_preflight_state,
+    get_provider_env_var,
+    merge_user_settings,
+    resolve_provider_presets,
+)
+
+from comate_cli.terminal_agent.figures import BULLET_OPERATOR
+from comate_cli.terminal_agent.config.store import (
+    apply_cli_config_snapshot_to_settings,
+    snapshot_from_settings_dict,
+)
+from comate_cli.terminal_agent.statusline.model import StatuslineConfig
+from comate_cli.terminal_agent.statusline.store import build_statusline_settings
+
+logger = logging.getLogger(__name__)
+
+_LEVEL_LABEL_WIDTH = 6
+_FIELD_LABEL_WIDTH = 9
+_VALUE_MAX_WIDTH = 96
+@dataclass(frozen=True, slots=True)
+class PreflightResult:
+    status: Literal[
+        "skipped",
+        "configured",
+        "cancelled",
+        "blocked_non_interactive",
+        "failed",
+    ]
+    detail: str | None = None
+
+    @property
+    def should_abort_launch(self) -> bool:
+        return self.status in {"cancelled", "blocked_non_interactive", "failed"}
+
+async def run_preflight_if_needed(
+    *,
+    console: Console,
+    project_root: Path,
+    interactive: bool,
+    provider_presets: Sequence[ProviderPreset] | None = None,
+) -> PreflightResult:
+    check = evaluate_preflight_state(project_root=project_root)
+    if not check.needs_preflight:
+        return PreflightResult(status="skipped")
+
+    if not interactive:
+        _print_preflight_block_message(console=console, check=check)
+        return PreflightResult(status="blocked_non_interactive", detail="missing_llm_config")
+
+    from comate_cli.terminal_agent.preflight_wizard import _run_preflight_wizard
+
+    flow = await _run_preflight_wizard(
+        check=check,
+        project_root=project_root,
+        provider_presets=provider_presets,
+    )
+    if flow.cancel_detail is not None:
+        console.print("[yellow]Setup cancelled. Session was not started.[/]")
+        return PreflightResult(status="cancelled", detail=flow.cancel_detail)
+    draft_with_keys = flow.levels
+    if draft_with_keys is None:
+        console.print("[yellow]Setup cancelled. Session was not started.[/]")
+        return PreflightResult(status="cancelled", detail="unknown_cancelled")
+
+    settings_path = USER_SETTINGS_PATH.expanduser()
+    try:
+        merged = merge_user_settings(
+            existing=_load_user_settings_json(settings_path),
+            levels=draft_with_keys,
+        )
+        merged = _hydrate_cli_default_settings(merged)
+        write_user_settings_atomic(path=settings_path, data=merged)
+    except Exception as exc:
+        logger.exception("Failed to save pre-flight settings")
+        console.print(f"[red]Failed to save provider settings: {exc}[/]")
+        return PreflightResult(status="failed", detail="write_failed")
+
+    recheck = evaluate_preflight_state(project_root=project_root)
+    if recheck.needs_preflight:
+        console.print(
+            "[red]Settings were saved to user scope, but effective configuration is still incomplete. "
+            "Please check project/local overrides.[/]"
+        )
+        return PreflightResult(status="failed", detail="still_missing_after_write")
+
+    console.print(f"[green]Provider settings saved: {settings_path}[/]")
+    return PreflightResult(status="configured")
+
+
+def write_user_settings_atomic(*, path: Path, data: Mapping[str, Any]) -> None:
+    write_settings_json_atomic(path=path, data=data)
+
+
+def _load_user_settings_json(path: Path) -> dict[str, Any]:
+    return read_settings_json_object(path)
+
+
+def _deep_merge_missing_settings(
+    existing: Mapping[str, Any] | dict[str, Any],
+    defaults: Mapping[str, Any],
+) -> dict[str, Any]:
+    result: dict[str, Any] = deepcopy(dict(existing))
+    for key, default_value in defaults.items():
+        current_value = result.get(key)
+        if key not in result:
+            result[key] = deepcopy(default_value)
+        elif isinstance(current_value, dict) and isinstance(default_value, dict):
+            result[key] = _deep_merge_missing_settings(current_value, default_value)
+    return result
+
+
+def _hydrate_cli_default_settings(data: Mapping[str, Any]) -> dict[str, Any]:
+    """Fill missing CLI-owned defaults during settings writes.
+
+    This is write-path-only. `store.load()` remains read-only, so CLI startup
+    does not create ~/.agent/settings.json unless preflight or a picker saves.
+    """
+    hydrated: dict[str, Any] = deepcopy(dict(data))
+    cli_raw = hydrated.get("comate_cli")
+    cli = deepcopy(cli_raw) if isinstance(cli_raw, dict) else {}
+
+    statusline_raw = cli.get("statusline")
+    if isinstance(statusline_raw, dict):
+        statusline_existing = statusline_raw
+    else:
+        legacy_statusline = hydrated.get("statusline")
+        statusline_existing = legacy_statusline if isinstance(legacy_statusline, dict) else {}
+    cli["statusline"] = _deep_merge_missing_settings(
+        statusline_existing,
+        build_statusline_settings(StatuslineConfig.default()),
+    )
+
+    hydrated["comate_cli"] = cli
+    hydrated.pop("statusline", None)
+    snapshot = snapshot_from_settings_dict(hydrated)
+    return apply_cli_config_snapshot_to_settings(hydrated, snapshot)
+
+
+def _truncate_value(value: str, max_width: int = _VALUE_MAX_WIDTH) -> str:
+    text = value.strip()
+    if len(text) <= max_width:
+        return text
+    if max_width <= 3:
+        return text[:max_width]
+    return f"{text[:max_width - 3]}..."
+
+
+def _format_level_summary(*, level: str, entry: LevelConfigDraft) -> str:
+    model_value = _truncate_value(f"{entry.provider}:{entry.model}")
+    endpoint_value = _truncate_value(entry.base_url or "(default)")
+    level_cell = f"{level:<{_LEVEL_LABEL_WIDTH}}"
+    model_label = f"{'Model':<{_FIELD_LABEL_WIDTH}}"
+    endpoint_label = f"{'Endpoint':<{_FIELD_LABEL_WIDTH}}"
+    return (
+        f"{level_cell}{model_label}{model_value}\n"
+        f"{'':<{_LEVEL_LABEL_WIDTH}}{endpoint_label}{endpoint_value}"
+    )
+
+
+def _format_missing_reasons(reasons: tuple[str, ...], *, bullet_indent: str = "  ") -> str:
+    if not reasons:
+        return "What's missing:\n  - Unknown issue"
+    lines = ["What's missing:"]
+    lines.extend(f"{bullet_indent}- {reason}" for reason in reasons)
+    return "\n".join(lines)
+
+
+def _print_preflight_block_message(*, console: Console, check: PreflightCheckResult) -> None:
+    reason_lines = _format_missing_reasons(check.reasons)
+    console.print("[red]Provider setup required[/]")
+    console.print("[dim]You need to configure an API provider before you can continue.[/]")
+    console.print(f"[dim]{reason_lines}[/]")
+    console.print("[dim]Run `comate` in interactive mode to complete provider setup.[/]")
+
+
+def _build_preflight_entry_options() -> list[dict[str, str]]:
+    return [
+        {
+            "value": "continue",
+            "label": "Start setup now",
+            "description": "",
+        },
+        {
+            "value": "cancel",
+            "label": "Exit",
+            "description": "",
+        },
+    ]