kedacode 0.2.0__py3-none-any.whl

backend/__init__.py

@@ -0,0 +1 @@
+"""Backend package boundary for the four-layer Python application."""

backend/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for ``python -m backend``."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", "8000"))
+    uvicorn.run("backend.api.app:app", host="0.0.0.0", port=port)

backend/api/__init__.py

@@ -0,0 +1,9 @@
+"""请求接入层（api）。
+
+负责接收 HTTP、WebSocket、CLI 等外部请求。
+只做参数校验、DTO 转换和用例调用，不写业务规则。
+
+依赖规则：
+    - 只能向内调用 backend/core/ 暴露的用例和 DTO
+    - 不得直接依赖 backend/engines/ 或 backend/infrastructure/
+"""

backend/api/app.py

@@ -0,0 +1,48 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from backend.api.routes import (
+    agent_runner,
+    agent_runner_console,
+    agent_runner_idea_inbox,
+    agent_runner_roadmap,
+    local_auth,
+)
+
+_logger = logging.getLogger(__name__)
+
+app = FastAPI(title="keda backend")
+app.include_router(agent_runner.router, prefix="/api/v1")
+app.include_router(agent_runner_console.router, prefix="/api/v1")
+app.include_router(agent_runner_roadmap.router, prefix="/api/v1")
+app.include_router(agent_runner_idea_inbox.router, prefix="/api/v1")
+app.include_router(local_auth.router, prefix="/api")
+
+
+def _mount_console_static() -> None:
+    """挂载随 wheel 分发的前端静态产物（源码模式缺产物时安静跳过）。
+
+    必须在全部 ``include_router`` 之后调用：``/`` 挂载是兜底路由，先注册
+    的 ``/api/*`` 路由优先匹配，不会被静态文件遮蔽。
+    """
+    from importlib.resources import files
+
+    console_dir = files("backend.api.static").joinpath("console")
+    if not console_dir.is_dir():
+        _logger.warning(
+            "Console static assets not found at backend.api.static/console; "
+            "serving API-only mode. Use a release wheel (assets bundled) or "
+            "build frontend-public first: pnpm --filter frontend-public build "
+            "&& copy out/ into src/backend/api/static/console/."
+        )
+        return
+    app.mount("/", StaticFiles(directory=str(console_dir), html=True), name="console")
+
+
+_mount_console_static()

backend/api/cli.py

@@ -0,0 +1,291 @@
+"""Command-line interface for issue-agent-runner.
+
+NOTE: This argparse-based parser is still the execution backend for
+``backend.api.cli_typer``. When adding or changing CLI options, defaults, or
+argument structure, keep ``cli_typer.py`` in sync so the actual ``iar`` entry
+point and its help text stay consistent.
+
+After the line-split refactor the per-subcommand bodies of
+``_run_parsed_command`` live in :mod:`backend.api.cli_parsed_commands`. The
+top-level dispatch table maps each ``parsed.command`` to its focused
+handler; the helpers and the public ``main()`` entrypoint stay here.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from backend.api.cli_console import error_console
+from backend.api.cli_helpers import (
+    _handle_not_initialized_error,
+    _resolve_default_daemon_target,
+)
+from backend.api.cli_parsed_commands import (
+    ParsedCommandContext,
+    dispatch_parsed_command,
+)
+from backend.engines.agent_runner.factory import (
+    create_github_client,
+    create_process_runner,
+    logger,
+)
+from backend.engines.agent_runner.repository_local import (
+    IARRepositoryNotInitializedError,
+)
+
+if TYPE_CHECKING:
+    from backend.core.shared.interfaces.agent_runner import IGitHubClient
+
+
+def _resolve_loop_target_repository(
+    *,
+    loop_repo_id: str | None,
+    loop_repo_path: str | None,
+    runner_settings,
+) -> "object | None":
+    """Resolve the repository that the loop command targets.
+
+    Loops may carry their own ``repo_id`` (resolved from the recipe when
+    not overridden on the CLI). When the user did not pass ``--repo-id``
+    or ``--repo``, we infer the target from the current working directory
+    the same way ``iar daemon`` does, falling back to ``None`` so the
+    per-loop ``repo_id`` is honored.
+    """
+    if loop_repo_path:
+        contexts = resolve_repository_targets(
+            runner_settings,
+            repo_path_override=loop_repo_path,
+            fallback_path=loop_repo_path,
+        )
+        return contexts[0] if contexts else None
+    if loop_repo_id:
+        contexts = resolve_repository_targets(
+            runner_settings,
+            repo_id=loop_repo_id,
+        )
+        return contexts[0] if contexts else None
+    cwd_target = _resolve_default_daemon_target()
+    if cwd_target.repo_id:
+        contexts = resolve_repository_targets(
+            runner_settings,
+            repo_id=cwd_target.repo_id,
+        )
+        return contexts[0] if contexts else None
+    return None
+
+
+def _run_loop_command(parsed: argparse.Namespace, process_runner) -> int:
+    """Dispatch ``iar loop ...`` and ``iar loop-daemon`` commands."""
+    from backend.api.cli_loop import build_schedule_from_args, logger as loop_logger
+
+    runner_settings = get_agent_runner_settings()
+
+    def _state_store_factory():
+        return create_loop_state_store()
+
+    def _github_client_factory(repo_path: Path) -> "IGitHubClient":
+        return create_github_client(repo_path, process_runner)
+
+    def _content_generator_factory(repo_path: Path):
+        return create_content_generator(process_runner)
+
+    def _repo_resolver(task):
+        """Resolve the on-disk path of the repository a loop targets."""
+        explicit_repo_id = getattr(parsed, "loop_repo_id", None)
+        explicit_repo = getattr(parsed, "loop_repo", None)
+        context = _resolve_loop_target_repository(
+            loop_repo_id=explicit_repo_id or task.repo_id,
+            loop_repo_path=explicit_repo,
+            runner_settings=runner_settings,
+        )
+        if context is None:
+            raise ValueError(
+                f"Loop '{task.id}' targets repo_id {task.repo_id!r} which is "
+                "not registered. Run `iar registry list` or pass "
+                "`--repo-id` / `--repo` to target a specific repository."
+            )
+        return context.repo_path
+
+    command = parsed.command
+
+    if command == "loop create":
+        return run_loop_create_command(parsed, state_store_factory=_state_store_factory)
+
+    if command == "loop list":
+        return run_loop_list_command(state_store_factory=_state_store_factory)
+
+    if command == "loop cancel":
+        return run_loop_cancel_command(parsed, state_store_factory=_state_store_factory)
+
+    # The remaining commands need clock + repo resolution. Validate the
+    # --cron/--every combination up front so the user gets a friendly
+    # error before we touch the loop state.
+    if command == "loop run":
+        try:
+            build_schedule_from_args(parsed)
+        except ValueError as exc:
+            loop_logger.error("%s", exc)
+            return 1
+        return run_loop_run_now_command(
+            parsed,
+            state_store_factory=_state_store_factory,
+            github_client_factory=_github_client_factory,
+            process_runner=process_runner,
+            clock=create_loop_clock(),
+            repo_resolver=_repo_resolver,
+            content_generator_factory=_content_generator_factory,
+            labels_config=None,
+        )
+
+    if command == "loop-daemon":
+        return run_loop_daemon_command(
+            parsed,
+            state_store_factory=_state_store_factory,
+            github_client_factory=_github_client_factory,
+            process_runner=process_runner,
+            clock=create_loop_clock(),
+            repo_resolver=_repo_resolver,
+            content_generator_factory=_content_generator_factory,
+            labels_config=None,
+        )
+
+    loop_logger.error("Unsupported loop command: %s", command)
+    return 1
+
+
+def _run_parsed_command(parsed: argparse.Namespace) -> int:
+    """Run a command after CLI arguments have been parsed.
+
+    Pre-dispatch validation runs here (deprecated flag warnings,
+    ``--repo``/``--repo-id`` exclusivity, the cwd-based default for
+    daemon / review-daemon / logs), then the matching handler from
+    :mod:`backend.api.cli_parsed_commands` is invoked through
+    :func:`dispatch_parsed_command`.
+    """
+    from backend.api.cli_utils import _format_cli_exception
+
+    if parsed.config:
+        logger.warning("The --config flag is deprecated. Use config.toml or env vars instead.")
+
+    repo_id: str | None = getattr(parsed, "repo_id", None)
+    repo_override: str | None = getattr(parsed, "repo", None)
+
+    # ``container up`` 把 ``--repo`` 用作容器挂载路径、``--repo-id`` 用作仓库
+    # registry id，二者语义互补（与其它命令里二者互为仓库选择器不同），
+    # 不适用互斥校验；否则文档主路径 ``iar container up --repo <path>
+    # --repo-id <id>`` 会被误拦。
+    if repo_id is not None and repo_override is not None and parsed.command != "container up":
+        logger.error("--repo and --repo-id are mutually exclusive.")
+        return 1
+
+    # daemon / review-daemon 在未指定仓库时：
+    # 1. cwd 命中唯一 enabled 注册仓 → 仅处理该仓（与 --repo-id 等价）
+    # 2. cwd 命中 disabled 注册仓 → 报错
+    # 3. cwd 命中多个 enabled 注册仓 → 报错，要求显式选择
+    # 4. cwd 未命中任何注册仓或未初始化 → 报错，不再回退到 --all
+    if parsed.command in ("daemon", "review-daemon", "logs"):
+        if (
+            repo_id is None
+            and repo_override is None
+            and not getattr(parsed, "all_repositories", False)
+        ):
+            default_target = _resolve_default_daemon_target()
+            if default_target.error:
+                logger.error(default_target.error)
+                return 1
+            repo_id = default_target.repo_id
+
+    process_runner = create_process_runner()
+    runner_settings = get_agent_runner_settings()
+
+    def github_client_factory(repo_path: Path) -> "IGitHubClient":
+        return create_github_client(repo_path, process_runner)
+
+    parsed_ctx = ParsedCommandContext(
+        parsed=parsed,
+        process_runner=process_runner,
+        runner_settings=runner_settings,
+        repo_id=repo_id,
+        repo_override=repo_override,
+        github_client_factory=github_client_factory,
+    )
+
+    try:
+        exit_code = dispatch_parsed_command(parsed_ctx)
+    except IARRepositoryNotInitializedError as exc:
+        return _handle_not_initialized_error(exc)
+    except Exception as exc:  # noqa: BLE001 - CLI should print concise failures.
+        error_detail = _format_cli_exception(exc)
+        logger.error("iar failed:\n%s", error_detail)
+        error_console.print("[red]iar failed:[/]")
+        error_console.print(error_detail, markup=False)
+        return 1
+
+    if exit_code is None:
+        logger.error("Unsupported command: %s", parsed.command)
+        return 1
+    return exit_code
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the Typer-powered CLI."""
+    from backend.api.cli_typer import main as typer_main
+
+    return typer_main(argv)
+
+
+# Backward-compatible re-exports. After the line-split refactor these
+# helpers live in dedicated modules; tests and downstream callers can
+# keep importing them through ``backend.api.cli``. The actual symbols are
+# in :mod:`backend.api.cli_reexports` so that ``cli_parsed_commands`` and
+# ``cli`` share a single module-level name binding — that way a test
+# ``patch("backend.api.cli.run_agent_daemon")`` correctly shadows the
+# function the handler will call.
+from backend.api.cli_reexports import (  # noqa: E402,F401
+    DaemonAlreadyRunningError,
+    DeliberationRequest,
+    IssueFromPrdRequest,
+    ReplSessionDeps,
+    ReplSessionInputs,
+    _ensure_gh_auth_or_prompt,
+    _expand_prd_paths,
+    _prompt_and_publish_prd_if_needed,
+    _resolve_cli_repository_targets,
+    _resolve_run_trigger,
+    acquire_daemon_locks,
+    create_content_generator,
+    create_default_session_id,
+    create_event_sink,
+    create_issue_from_prd,
+    create_loop_clock,
+    create_loop_state_store,
+    create_planner_runner,
+    create_repl_command_executor,
+    create_transcript_runner,
+    daemon_lock_dir,
+    get_agent_runner_settings,
+    release_daemon_locks,
+    require_iar_repository_initialized,
+    resolve_issue_from_prd_target,
+    resolve_prd_paths,
+    resolve_repository_targets,
+    review_once,
+    run_agent_daemon,
+    run_agent_deliberation,
+    run_agent_repositories_once,
+    run_loop_cancel_command,
+    run_loop_create_command,
+    run_loop_daemon_command,
+    run_loop_list_command,
+    run_loop_run_now_command,
+    run_repl_session,
+    run_review_daemon,
+    sync_labels,
+    write_deliberation_outputs,
+)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backend/api/cli_completion.py

@@ -0,0 +1,100 @@
+"""Shell completion helpers and command registration for the Typer CLI.
+
+Keeping completion logic in a dedicated module prevents ``cli_typer.py`` from
+ growing with installation utilities that are only exercised once per shell.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+import typer
+from typer.completion import get_completion_script
+
+
+class CompletionShellChoice(str, Enum):
+    """Shells supported by the explicit completion installer."""
+
+    bash = "bash"
+    zsh = "zsh"
+    fish = "fish"
+
+
+def _completion_script(shell: CompletionShellChoice) -> str:
+    """Return the shell completion script for the iAR executable."""
+    return get_completion_script(
+        prog_name="iar",
+        complete_var="_IAR_COMPLETE",
+        shell=shell.value,
+    )
+
+
+def _append_unique_line(file_path: Path, line: str) -> bool:
+    """Append a shell profile line when it is not already present."""
+    existing_text = ""
+    if file_path.exists():
+        existing_text = file_path.read_text(encoding="utf-8")
+        if line in existing_text.splitlines():
+            return False
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    with file_path.open("a", encoding="utf-8") as profile_file:
+        if existing_text and not existing_text.endswith("\n"):
+            profile_file.write("\n")
+        profile_file.write(f"{line}\n")
+    return True
+
+
+def _install_completion_script(
+    shell: CompletionShellChoice,
+) -> tuple[Path, Path | None]:
+    """Install iAR shell completion and return the script/profile paths."""
+    script_content = _completion_script(shell)
+    home_path = Path.home()
+    if shell is CompletionShellChoice.zsh:
+        completion_dir = home_path / ".zsh" / "completions"
+        completion_path = completion_dir / "_iar"
+        completion_path.parent.mkdir(parents=True, exist_ok=True)
+        completion_path.write_text(f"{script_content}\n", encoding="utf-8")
+        zshrc_path = home_path / ".zshrc"
+        _append_unique_line(zshrc_path, "autoload -Uz compinit && compinit")
+        source_line = f'[ -f "{completion_path}" ] && source "{completion_path}"'
+        _append_unique_line(zshrc_path, source_line)
+        return completion_path, zshrc_path
+    if shell is CompletionShellChoice.bash:
+        completion_path = home_path / ".config" / "iar" / "iar_completion.bash"
+        completion_path.parent.mkdir(parents=True, exist_ok=True)
+        completion_path.write_text(f"{script_content}\n", encoding="utf-8")
+        bashrc_path = home_path / ".bashrc"
+        source_line = f'[ -f "{completion_path}" ] && source "{completion_path}"'
+        _append_unique_line(bashrc_path, source_line)
+        return completion_path, bashrc_path
+    completion_path = home_path / ".config" / "fish" / "completions" / "iar.fish"
+    completion_path.parent.mkdir(parents=True, exist_ok=True)
+    completion_path.write_text(f"{script_content}\n", encoding="utf-8")
+    return completion_path, None
+
+
+def register_completion_commands(completion_app: typer.Typer) -> None:
+    """Register ``completion show`` and ``completion install`` commands."""
+
+    @completion_app.command("show")
+    def completion_show_command(
+        shell: CompletionShellChoice = CompletionShellChoice.zsh,
+    ) -> int:
+        """Print a shell completion script."""
+        typer.echo(_completion_script(shell))
+        return 0
+
+    @completion_app.command("install")
+    def completion_install_command(
+        shell: CompletionShellChoice = CompletionShellChoice.zsh,
+    ) -> int:
+        """Install shell completion for the current user."""
+        completion_path, profile_path = _install_completion_script(shell)
+        typer.echo(f"Installed {shell.value} completion: {completion_path}")
+        if profile_path is not None:
+            typer.echo(f"Reload your shell with: source {profile_path}")
+        else:
+            typer.echo("Open a new terminal session to activate completion.")
+        return 0

backend/api/cli_console.py

@@ -0,0 +1,12 @@
+"""Shared Rich console instances for the IAR CLI.
+
+Centralising ``Console`` instances avoids circular imports when CLI command
+implementations are split into separate modules.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+console = Console()
+error_console = Console(stderr=True)

backend/api/cli_helpers.py

@@ -0,0 +1,205 @@
+"""Shared CLI helper utilities used by ``backend.api.cli``.
+
+These helpers are thin presentation-layer adapters (auth checks, output
+formatting, target resolution) that do not themselves invoke long-running
+business logic. Keeping them in a dedicated module lets the main dispatch
+file stay focused on command wiring.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from backend.api.cli_console import console, error_console
+from backend.core.use_cases.worktree_cleanup import (
+    WorktreeCleanupResult,
+    WorktreeCleanupStatus,
+)
+from backend.engines.agent_runner.factory import (
+    create_console_store,
+    create_github_client,
+    find_repository_match_for_path,
+    load_fresh_agent_runner_settings,
+    logger,
+    resolve_repository_targets,
+)
+from backend.engines.agent_runner.repository_local import (
+    IARRepositoryNotInitializedError,
+    detect_git_repository_root,
+    require_iar_repository_initialized,
+)
+
+if TYPE_CHECKING:
+    from backend.core.shared.interfaces.agent_runner import IProcessRunner
+    from backend.core.shared.models.agent_runner import RepositoryRunContext
+
+
+def _ensure_gh_auth_or_prompt(repo_path: Path, process_runner: "IProcessRunner") -> None:
+    """Check gh auth status and exit with a friendly message if not authenticated."""
+    if os.environ.get("IAR_SKIP_GH_AUTH_CHECK") == "1":
+        return
+    github_client = create_github_client(repo_path, process_runner)
+    auth_status = github_client.check_auth_status()
+    if auth_status.authenticated:
+        return
+    error_console.print("[red]GitHub CLI 认证失败。[/]")
+    if auth_status.failure_reason:
+        error_console.print(f"[red]{auth_status.failure_reason}[/]")
+    error_console.print("[yellow]请运行: gh auth login -h github.com[/]")
+    raise SystemExit(1)
+
+
+def _print_worktree_cleanup_result(cleanup_result: WorktreeCleanupResult) -> None:
+    """Print a concise branch cleanup summary."""
+    if not cleanup_result.branches:
+        console.print("[green]No local iAR issue branches found.[/]")
+        return
+
+    for branch_result in cleanup_result.branches:
+        worktree_suffix = f" ({branch_result.worktree_path})" if branch_result.worktree_path else ""
+        if branch_result.status is WorktreeCleanupStatus.WOULD_DELETE:
+            console.print(
+                f"[yellow]Would delete:[/] {branch_result.branch}{worktree_suffix} - "
+                f"{branch_result.reason}"
+            )
+        elif branch_result.status is WorktreeCleanupStatus.DELETED:
+            console.print(
+                f"[green]Deleted:[/] {branch_result.branch}{worktree_suffix} - "
+                f"{branch_result.reason}"
+            )
+        elif branch_result.status is WorktreeCleanupStatus.FAILED:
+            console.print(
+                f"[red]Failed:[/] {branch_result.branch}{worktree_suffix} - {branch_result.reason}"
+            )
+        else:
+            console.print(
+                f"[dim]Skipped:[/] {branch_result.branch}{worktree_suffix} - {branch_result.reason}"
+            )
+
+    console.print(
+        "Cleanup summary: "
+        f"deleted={cleanup_result.deleted_count}, "
+        f"would_delete={cleanup_result.would_delete_count}, "
+        f"skipped={cleanup_result.skipped_count}, "
+        f"failed={cleanup_result.failed_count}"
+    )
+
+
+def _resolve_cli_repository_targets(
+    *,
+    parsed: argparse.Namespace,
+    runner_settings: Any,
+    repo_id: str | None,
+    repo_override: str | None,
+) -> list["RepositoryRunContext"]:
+    """Resolve repository targets for parsed CLI selectors."""
+    return resolve_repository_targets(
+        runner_settings,
+        repo_id=repo_id,
+        repo_path_override=repo_override,
+        all_repositories=getattr(parsed, "all_repositories", False),
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class _DefaultDaemonTarget:
+    """Result of inferring a daemon target from cwd."""
+
+    repo_id: str | None
+    error: str
+
+
+def _resolve_default_daemon_target() -> _DefaultDaemonTarget:
+    """Infer the daemon target repository from the current working directory.
+
+    Returns:
+        _DefaultDaemonTarget: when ``repo_id`` is set, use that repository;
+        when ``error`` is set, fail early with the error message. This function
+        no longer falls back to ``--all``; callers must explicitly request all
+        enabled registry entries.
+    """
+    try:
+        cwd_git_root = detect_git_repository_root(Path.cwd())
+    except ValueError:
+        return _DefaultDaemonTarget(
+            repo_id=None,
+            error=(
+                "Current directory is not a Git repository. "
+                "Run from an initialized iAR repository, or use --all to target all enabled registry entries."
+            ),
+        )
+    settings = load_fresh_agent_runner_settings()
+    match = find_repository_match_for_path(settings, cwd_git_root)
+    if match.is_unique_enabled:
+        assert match.matched_repo_id is not None  # noqa: S101
+        try:
+            require_iar_repository_initialized(cwd_git_root)
+        except IARRepositoryNotInitializedError:
+            return _DefaultDaemonTarget(
+                repo_id=None,
+                error=(
+                    f"Repository '{match.matched_repo_id}' is not initialized. "
+                    "Run 'iar init' in the repository root, or use --all to target all enabled registry entries."
+                ),
+            )
+        return _DefaultDaemonTarget(repo_id=match.matched_repo_id, error="")
+    if match.is_disabled:
+        assert match.disabled_repo_id is not None  # noqa: S101
+        return _DefaultDaemonTarget(
+            repo_id=None,
+            error=(
+                f"Repository '{match.disabled_repo_id}' is disabled. "
+                "Use --repo-id to target it explicitly, or enable it in config.toml."
+            ),
+        )
+    if match.is_ambiguous:
+        candidates = ", ".join(repo_id for repo_id, _ in match.enabled_candidates)
+        return _DefaultDaemonTarget(
+            repo_id=None,
+            error=(
+                f"Current directory matches multiple enabled repositories: {candidates}. "
+                "Use --repo-id to target one, or --all to target all."
+            ),
+        )
+    return _DefaultDaemonTarget(
+        repo_id=None,
+        error=(
+            "Current directory is not an enabled iAR registry target. "
+            "Use --repo-id to target a registered repository, or --all to target all enabled registry entries."
+        ),
+    )
+
+
+def _resolve_run_trigger(command_kind: str) -> str:
+    """解析运行记录的 trigger 来源。
+
+    管理终端托管的子进程带有 ``IAR_CONSOLE=1`` 环境标记，记为
+    ``console_*``；否则记为 ``cli_*``。
+
+    Args:
+        command_kind: ``"run"`` 或 ``"daemon"``。
+    """
+    prefix = "console" if os.environ.get("IAR_CONSOLE") == "1" else "cli"
+    return f"{prefix}_{command_kind}"
+
+
+def _create_run_history_store_or_none():
+    """创建运行历史存储；初始化失败时降级为 None（不阻断 CLI）。"""
+    try:
+        return create_console_store()
+    except Exception as exc:  # noqa: BLE001 - history is a side channel.
+        logger.warning("Run history store unavailable: %s", exc)
+        return None
+
+
+def _handle_not_initialized_error(exc: IARRepositoryNotInitializedError) -> int:
+    """Print a friendly error and suggest running `iar init`."""
+    error_console.print("[red]Repository is not initialized for iar.[/]")
+    error_console.print(f"Expected local config: {exc.config_path}", soft_wrap=True)
+    error_console.print("Run the following command from the repository root:")
+    error_console.print("  iar init")
+    return 1