Fold per-command run-logic into commands/<cmd>/ packages

Each command that owns private run-logic becomes a package instead of a
flat module plus a sibling *_exec.py at the package root: __init__.py holds
the Typer app + SPEC, and its support modules sit beside it underscore-
prefixed (_exec.py for the run_<cmd> body, plus _select/_data/_hf_api/_listen
helpers). This colocates a command's exec with the command file and follows
the Prefect/spaCy convention (flat file by default; promote to a folder only
when a command has earned multiple modules; underscore-prefix private modules,
which also dodges the webhooks `listen` command-vs-module name collision).

13 commands folded: stream, agent, speak, llm, clip, dictate, caption, dub,
evaluate, deploy, dev, share, webhooks. transcribe and init stay at the root
alongside doctor_checks/setup_exec because the onboarding wizard
(onboard/sections.py) reuses transcribe_exec/render/batch and init_exec, so
they are shared beyond a single command.

command_registry already discovers packages (pkgutil.iter_modules), so
registration, help ordering, and the snapshot partition are unchanged.
import-linter contract 1 drops the folded execs (now covered by contract 2's
independence rule) and contract 3 points at the new _select/_data paths; all
three contracts stay green. AGENTS.md documents the module-or-package rule.

https://claude.ai/code/session_01XfcMSCxZPLJgg2UQBy8a4v

Author: claude

.importlinter

@@ -5,32 +5,27 @@ include_external_packages = True
 [importlinter:contract:1]
 name = Core modules do not import command modules
 type = forbidden
+; A command's private run-logic now lives inside its own package
+; (aai_cli/commands/<cmd>/_exec.py, …) and is governed by contract 2's
+; independence rule, so those modules are intentionally absent here. The
+; *_exec modules that remain are the ones still at the package root because
+; they're shared beyond their command (transcribe_exec/render/batch and
+; init_exec are reused by the onboarding wizard; setup_exec/doctor_checks too).
 source_modules =
     aai_cli.agent
-    aai_cli.agent_exec
     aai_cli.argscan
     aai_cli.auth
-    aai_cli.caption_exec
     aai_cli.choices
     aai_cli.client
-    aai_cli.clip_exec
-    aai_cli.clip_select
     aai_cli.code_gen
     aai_cli.coding_agent
     aai_cli.config
     aai_cli.config_builder
     aai_cli.context
     aai_cli.debuglog
-    aai_cli.deploy_exec
-    aai_cli.dev_exec
-    aai_cli.dictate_exec
     aai_cli.doctor_checks
-    aai_cli.dub_exec
     aai_cli.environments
     aai_cli.errors
-    aai_cli.eval_data
-    aai_cli.eval_hf_api
-    aai_cli.evaluate_exec
     aai_cli.follow
     aai_cli.help_panels
     aai_cli.help_text
@@ -39,7 +34,6 @@ source_modules =
     aai_cli.init_exec
     aai_cli.jsonshape
     aai_cli.llm
-    aai_cli.llm_exec
     aai_cli.mediafile
     aai_cli.microphone
     aai_cli.onboard
@@ -49,11 +43,8 @@ source_modules =
     aai_cli.remotefs
     aai_cli.render
     aai_cli.setup_exec
-    aai_cli.share_exec
-    aai_cli.speak_exec
     aai_cli.stdio
     aai_cli.steps
-    aai_cli.stream_exec
     aai_cli.streaming
     aai_cli.sync_stt
     aai_cli.telemetry
@@ -65,7 +56,6 @@ source_modules =
     aai_cli.tts
     aai_cli.typer_patches
     aai_cli.update_check
-    aai_cli.webhook_listen
     aai_cli.wer
     aai_cli.ws
     aai_cli.youtube
@@ -87,13 +77,13 @@ type = forbidden
 source_modules =
     aai_cli.argscan
     aai_cli.client
-    aai_cli.clip_select
+    aai_cli.commands.clip._select
+    aai_cli.commands.evaluate._data
     aai_cli.config
     aai_cli.config_builder
     aai_cli.debuglog
     aai_cli.environments
     aai_cli.errors
-    aai_cli.eval_data
     aai_cli.hotkey
     aai_cli.llm
     aai_cli.remotefs

aai_cli/AGENTS.md

@@ -16,12 +16,30 @@ pipe → exit 0).
 
 ### Command layer & the registration convention
 
-Each file in `aai_cli/commands/` is a Typer sub-app (`transcribe`, `stream`,
+Each entry under `aai_cli/commands/` is a Typer sub-app (`transcribe`, `stream`,
 `dictate`, `agent`, `speak`, `llm`, `clip`, `dub`, `caption`, `eval`,
 `transcripts`, `login` (login/logout/whoami), `doctor`, `init`, `dev`, `share`,
 `deploy`, `setup`, `onboard`, `account` (balance/usage/limits), `keys`,
 `sessions`, `audit`, `telemetry` (status/enable/disable), `webhooks` (listen)).
 
+**A command is either a single module *or* a package** — `command_registry`
+discovers both (it iterates `pkgutil.iter_modules`, which enumerates packages
+too). A simple command stays a flat `commands/<cmd>.py`. A command with private
+run-logic becomes a package `commands/<cmd>/`: `__init__.py` holds the Typer
+`app` + `SPEC` (and is what gets imported as `aai_cli.commands.<cmd>`), and its
+support modules sit beside it **underscore-prefixed** — `_exec.py` for the
+`run_<cmd>` body, plus any private helpers (`clip/_select.py`,
+`evaluate/_data.py`, `evaluate/_hf_api.py`). The underscore both marks them
+private and avoids colliding with the package's own command functions (the
+`webhooks` package binds a `listen` command, so its module is `_listen.py`, not
+`listen.py`). This is the Prefect/spaCy convention: flat file by default,
+promote to a folder only when the command has earned multiple modules. Run-logic
+that's **shared beyond one command stays at the package root**, not inside a
+command package — `transcribe_exec`/`transcribe_render`/`transcribe_batch` and
+`init_exec` are reused by the onboarding wizard (`onboard/sections.py`), so they
+live at the root alongside `doctor_checks`/`setup_exec` rather than under
+`commands/transcribe/` or `commands/init/`.
+
 **Adding a command is purely additive — no shared file edits.** Every command
 module declares a module-level
 `SPEC = command_registry.CommandModuleSpec(panel=…, order=…, commands=…)`:
@@ -61,9 +79,10 @@ command module from another.
 function only parses argv into a frozen `<Cmd>Options` dataclass and hands it
 to a module-level `run_<cmd>(opts, state, *, json_mode)` through a thin lambda
 adapter in `run_command(ctx, ..., json=...)`. The run commands follow it —
-`aai_cli/stream_exec.py` (the reference implementation), `transcribe_exec.py`,
-`agent_exec.py`, `speak_exec.py`, `llm_exec.py`, `clip_exec.py`,
-`dictate_exec.py`. Because the run path is a plain function of data, tests
+`commands/stream/_exec.py` (the reference implementation), `transcribe_exec.py`
+(at the root — shared with onboarding), `commands/agent/_exec.py`,
+`commands/speak/_exec.py`, `commands/llm/_exec.py`, `commands/clip/_exec.py`,
+`commands/dictate/_exec.py`. Because the run path is a plain function of data, tests
 construct options directly (`dataclasses.replace` off a defaults instance, see
 `tests/test_stream_exec.py` and `tests/test_command_options_seam.py`) instead
 of round-tripping argv through `CliRunner` — which is also the cheap way to

aai_cli/commands/agent.py aai_cli/commands/agent/__init__.pyaai_cli/commands/agent.py renamed to aai_cli/commands/agent/__init__.py

@@ -4,14 +4,15 @@
 
 import typer
 
-from aai_cli import agent_exec, choices, command_registry, help_panels, options, output
+from aai_cli import choices, command_registry, help_panels, options, output
 from aai_cli.agent.session import DEFAULT_GREETING, DEFAULT_PROMPT
 from aai_cli.agent.voices import (
     DEFAULT_VOICE,
     VOICES,
     complete_voice,
     format_voice_list,
 )
+from aai_cli.commands.agent import _exec as agent_exec
 from aai_cli.context import AppState, run_command
 from aai_cli.help_text import examples_epilog
 

aai_cli/agent_exec.py aai_cli/commands/agent/_exec.pyaai_cli/agent_exec.py renamed to aai_cli/commands/agent/_exec.py

@@ -1,6 +1,6 @@
 """Run logic for `assembly agent`: the options/run split (see AGENTS.md).
 
-The command module (aai_cli/commands/agent.py) only parses argv — it builds an
+The command module (aai_cli/commands/agent/__init__.py) only parses argv — it builds an
 ``AgentOptions`` and hands it to ``run_agent`` via ``context.run_command``, so tests
 can drive validation, --show-code, and session wiring by constructing options
 directly, with no CliRunner argv round-trip.

aai_cli/commands/caption.py aai_cli/commands/caption/__init__.pyaai_cli/commands/caption.py renamed to aai_cli/commands/caption/__init__.py

@@ -4,7 +4,8 @@
 
 import typer
 
-from aai_cli import caption_exec, command_registry, help_panels, options
+from aai_cli import command_registry, help_panels, options
+from aai_cli.commands.caption import _exec as caption_exec
 from aai_cli.context import run_command
 from aai_cli.help_text import examples_epilog
 

aai_cli/caption_exec.py aai_cli/commands/caption/_exec.pyaai_cli/caption_exec.py renamed to aai_cli/commands/caption/_exec.py

@@ -1,6 +1,6 @@
 """Run logic for `assembly caption`: transcribe → SRT export → ffmpeg burn-in.
 
-The command module (aai_cli/commands/caption.py) only parses argv — it builds a
+The command module (aai_cli/commands/caption/__init__.py) only parses argv — it builds a
 ``CaptionOptions`` and hands it to ``run_caption`` via ``context.run_command``
 (the options/run split, see AGENTS.md), so tests drive the whole pipeline by
 constructing options directly.

aai_cli/commands/clip.py aai_cli/commands/clip/__init__.pyaai_cli/commands/clip.py renamed to aai_cli/commands/clip/__init__.py

@@ -4,7 +4,8 @@
 
 import typer
 
-from aai_cli import clip_exec, command_registry, help_panels, llm, options
+from aai_cli import command_registry, help_panels, llm, options
+from aai_cli.commands.clip import _exec as clip_exec
 from aai_cli.context import run_command
 from aai_cli.help_text import examples_epilog
 

aai_cli/clip_exec.py aai_cli/commands/clip/_exec.pyaai_cli/clip_exec.py renamed to aai_cli/commands/clip/_exec.py

@@ -1,6 +1,6 @@
 """Run logic for `assembly clip`: cut a media file by transcript content.
 
-The command module (aai_cli/commands/clip.py) only parses argv — it builds a
+The command module (aai_cli/commands/clip/__init__.py) only parses argv — it builds a
 ``ClipOptions`` and hands it to ``run_clip`` via ``context.run_command`` (the
 options/run split, see AGENTS.md), so tests drive transcript resolution and the
 ffmpeg orchestration by constructing options directly. The pure selection logic
@@ -27,8 +27,9 @@
 
 from rich.markup import escape
 
-from aai_cli import clip_select, jsonshape, llm, mediafile, output, stdio, youtube
-from aai_cli.clip_select import Segment
+from aai_cli import jsonshape, llm, mediafile, output, stdio, youtube
+from aai_cli.commands.clip import _select as clip_select
+from aai_cli.commands.clip._select import Segment
 from aai_cli.context import AppState
 from aai_cli.errors import CLIError, UsageError
 

aai_cli/clip_select.py aai_cli/commands/clip/_select.pyaai_cli/clip_select.py renamed to aai_cli/commands/clip/_select.py

@@ -1,9 +1,10 @@
-# aai_cli/commands/deploy.py
+# aai_cli/commands/deploy/__init__.py
 from __future__ import annotations
 
 import typer
 
-from aai_cli import command_registry, deploy_exec, help_panels, options
+from aai_cli import command_registry, help_panels, options
+from aai_cli.commands.deploy import _exec as deploy_exec
 from aai_cli.context import run_command
 from aai_cli.help_text import examples_epilog