refactor(cli): group subcommand handlers under cli/commands/

Move the eleven per-command modules (backend, cleanup, commit, edit,
info, init, list, login, resume, start, supervise) into a new
bot_bottle/cli/commands/ package, leaving the dispatcher (__init__),
entrypoint (__main__), and shared helpers (_common, tui) at the cli
root. Makes the command surface obvious at a glance and separates
handlers from the plumbing that registers them.

Updated the dispatcher's COMMANDS imports to .commands.*, bumped the
moved files' relative-import depths (.._common, .. import tui, sibling
.start unchanged), and repointed test references to
bot_bottle.cli.commands.*. Full unit suite green (2243); CLI dispatch
verified via `python -m bot_bottle.cli --help`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

bot_bottle/cli/__init__.py

@@ -12,17 +12,17 @@ from ..log import Die, die, error
 from ..manifest import ManifestError
 from ..orchestrator.store.store_manager import StoreManager
 from ._common import PROG
-from . import list as _list_mod
-from .backend import cmd_backend
-from .cleanup import cmd_cleanup
-from .commit import cmd_commit
-from .edit import cmd_edit
-from .info import cmd_info
-from .init import cmd_init
-from .login import cmd_login
-from .resume import cmd_resume
-from .start import cmd_start
-from .supervise import cmd_supervise
+from .commands import list as _list_mod
+from .commands.backend import cmd_backend
+from .commands.cleanup import cmd_cleanup
+from .commands.commit import cmd_commit
+from .commands.edit import cmd_edit
+from .commands.info import cmd_info
+from .commands.init import cmd_init
+from .commands.login import cmd_login
+from .commands.resume import cmd_resume
+from .commands.start import cmd_start
+from .commands.supervise import cmd_supervise
 
 cmd_list = _list_mod.cmd_list
 

bot_bottle/cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""CLI subcommand handlers — one module per `bot-bottle <command>`.
+
+Each module exposes a `cmd_<name>(argv)` handler that the dispatcher
+(`bot_bottle.cli`) registers in its COMMANDS table. Shared CLI helpers
+(`_common`, `tui`) stay one level up in the `cli` package.
+"""

bot_bottle/cli/commands/backend.py

@@ -15,8 +15,8 @@ from __future__ import annotations
 
 import argparse
 
-from ..backend import get_bottle_backend, known_backend_names
-from ._common import PROG
+from ...backend import get_bottle_backend, known_backend_names
+from .._common import PROG
 
 
 def cmd_backend(args: list[str]) -> int:

bot_bottle/cli/commands/cleanup.py

@@ -21,9 +21,9 @@ from __future__ import annotations
 
 import sys
 
-from ..backend import get_bottle_backend, has_backend, known_backend_names
-from ..log import info
-from ._common import read_tty_line
+from ...backend import get_bottle_backend, has_backend, known_backend_names
+from ...log import info
+from .._common import read_tty_line
 
 
 def cmd_cleanup(_argv: list[str]) -> int:

bot_bottle/cli/commands/commit.py

@@ -12,12 +12,12 @@ from __future__ import annotations
 
 import argparse
 
-from ..backend import enumerate_active_agents
-from ..backend.freeze import CommitCancelled, get_freezer
-from ..bottle_state import read_metadata
-from ..log import die
-from ._common import PROG
-from . import tui
+from ...backend import enumerate_active_agents
+from ...backend.freeze import CommitCancelled, get_freezer
+from ...bottle_state import read_metadata
+from ...log import die
+from .._common import PROG
+from .. import tui
 
 
 def cmd_commit(argv: list[str]) -> int:

bot_bottle/cli/commands/edit.py

@@ -7,8 +7,8 @@ import json
 import os
 from pathlib import Path
 
-from ..log import die
-from ._common import PROG, USER_CWD
+from ...log import die
+from .._common import PROG, USER_CWD
 
 
 def cmd_edit(argv: list[str]) -> int:

bot_bottle/cli/commands/info.py

@@ -4,9 +4,9 @@ from __future__ import annotations
 
 import argparse
 
-from ..log import info
-from ..manifest import ManifestIndex
-from ._common import PROG, USER_CWD
+from ...log import info
+from ...manifest import ManifestIndex
+from .._common import PROG, USER_CWD
 
 
 def cmd_info(argv: list[str]) -> int:

bot_bottle/cli/commands/init.py

@@ -10,8 +10,8 @@ import sys
 from pathlib import Path
 from typing import Any
 
-from ..log import die, info, warn
-from ._common import PROG, USER_CWD, read_tty_line
+from ...log import die, info, warn
+from .._common import PROG, USER_CWD, read_tty_line
 
 
 def cmd_init(argv: list[str]) -> int:

bot_bottle/cli/commands/list.py

@@ -6,9 +6,9 @@ import argparse
 import os
 import sys
 
-from ..backend import enumerate_active_agents
-from ..manifest import ManifestIndex
-from ._common import PROG, USER_CWD
+from ...backend import enumerate_active_agents
+from ...manifest import ManifestIndex
+from .._common import PROG, USER_CWD
 
 _ANSI_COLOR_CODES: dict[str, str] = {
     "red": "\033[91m",

bot_bottle/cli/commands/login.py

@@ -25,7 +25,7 @@ import urllib.request
 from pathlib import Path
 from typing import Any
 
-from ..paths import bot_bottle_root
+from ...paths import bot_bottle_root
 
 _CONSOLE_URL_ENV = "BB_CONSOLE_URL"
 _POLL_SLEEP = 2  # seconds between polls; matches console's poll_interval default

bot_bottle/cli/commands/resume.py

@@ -16,11 +16,11 @@ from __future__ import annotations
 
 import argparse
 
-from ..backend import BottleSpec
-from ..bottle_state import read_metadata
-from ..log import die
-from ..manifest import ManifestIndex
-from ._common import PROG, USER_CWD
+from ...backend import BottleSpec
+from ...bottle_state import read_metadata
+from ...log import die
+from ...manifest import ManifestIndex
+from .._common import PROG, USER_CWD
 from .start import _launch_bottle
 
 

bot_bottle/cli/commands/start.py

@@ -22,25 +22,25 @@ import tempfile
 from pathlib import Path
 from typing import Callable
 
-from ..agent_provider import get_provider, runtime_for
-from ..backend import (
+from ...agent_provider import get_provider, runtime_for
+from ...backend import (
     Bottle,
     BottleSpec,
     enumerate_active_agents,
     get_bottle_backend,
 )
-from ..backend.docker import util as docker_mod
-from ..backend.docker.bottle_plan import DockerBottlePlan
-from ..bottle_state import (
+from ...backend.docker import util as docker_mod
+from ...backend.docker.bottle_plan import DockerBottlePlan
+from ...bottle_state import (
     cleanup_state,
     is_preserved,
     mark_preserved,
 )
-from ..image_cache import StaleImageError
-from ..log import info, die
-from ..manifest import Manifest, ManifestIndex
-from ._common import PROG, USER_CWD, read_tty_line
-from . import tui
+from ...image_cache import StaleImageError
+from ...log import info, die
+from ...manifest import Manifest, ManifestIndex
+from .._common import PROG, USER_CWD, read_tty_line
+from .. import tui
 
 
 def cmd_start(argv: list[str]) -> int:
@@ -380,8 +380,8 @@ def _peek_agent_bottle(manifest: ManifestIndex, agent_name: str) -> str:
             return manifest.agents[agent_name].bottle
         return ""
 
-    from ..manifest.loader import scan_agent_names
-    from ..yaml_subset import YamlSubsetError, parse_frontmatter
+    from ...manifest.loader import scan_agent_names
+    from ...yaml_subset import YamlSubsetError, parse_frontmatter
 
     home_agents = scan_agent_names(manifest.home_md / "agents")
     cwd_agents: dict[str, Path] = {}
@@ -449,7 +449,7 @@ def _bottle_lineage(manifest: ManifestIndex) -> dict[str, str]:
     if not bottles_dir.is_dir():
         return {}
 
-    from ..yaml_subset import YamlSubsetError, parse_frontmatter
+    from ...yaml_subset import YamlSubsetError, parse_frontmatter
 
     extends_of: dict[str, str] = {}
     for path in bottles_dir.glob("*.md"):

bot_bottle/cli/commands/supervise.py

@@ -19,22 +19,22 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
-from ..paths import bot_bottle_root
-from ..log import Die, error, info
-from ..orchestrator.client import (
+from ...paths import bot_bottle_root
+from ...log import Die, error, info
+from ...orchestrator.client import (
     OrchestratorClient,
     OrchestratorClientError,
     discover_orchestrator_url,
 )
 
-from ..supervisor.types import (
+from ...supervisor.types import (
     Proposal,
     TOOL_EGRESS_ALLOW,
     TOOL_EGRESS_BLOCK,
     TOOL_GITLEAKS_ALLOW,
     TOOL_EGRESS_TOKEN_ALLOW,
 )
-from ._common import PROG
+from .._common import PROG
 
 
 _REFRESH_INTERVAL_MS = 1000
@@ -81,7 +81,7 @@ def _resolve_orchestrator_url() -> str:
     try:
         return discover_orchestrator_url()
     except OrchestratorClientError:
-        from ..backend import get_bottle_backend
+        from ...backend import get_bottle_backend
         backend = get_bottle_backend()
         info(f"no orchestrator control plane running; starting one ({backend.name})…")
         return backend.ensure_orchestrator()