chore: strengthen CLI quality gates

Author: alexkroman-assembly

.gitignore

@@ -10,6 +10,7 @@ build/
 .coverage
 coverage.xml
 htmlcov/
+mutants/
 
 # Editor/agent local artifacts: keep personal settings local, but track the
 # team-shared bits (.claude/settings.json, agents/, skills/).

.importlinter

@@ -0,0 +1,64 @@
+[importlinter]
+root_package = aai_cli
+include_external_packages = True
+
+[importlinter:contract:1]
+name = Core modules do not import command modules
+type = forbidden
+source_modules =
+    aai_cli.agent
+    aai_cli.auth
+    aai_cli.client
+    aai_cli.code_gen
+    aai_cli.config
+    aai_cli.config_builder
+    aai_cli.context
+    aai_cli.environments
+    aai_cli.errors
+    aai_cli.follow
+    aai_cli.help_panels
+    aai_cli.help_text
+    aai_cli.init
+    aai_cli.llm
+    aai_cli.microphone
+    aai_cli.output
+    aai_cli.render
+    aai_cli.stdio
+    aai_cli.streaming
+    aai_cli.theme
+    aai_cli.transcribe_render
+    aai_cli.youtube
+forbidden_modules =
+    aai_cli.commands
+
+[importlinter:contract:2]
+name = Command modules are independent
+type = independence
+modules =
+    aai_cli.commands.account
+    aai_cli.commands.agent
+    aai_cli.commands.audit
+    aai_cli.commands.claude
+    aai_cli.commands.doctor
+    aai_cli.commands.init
+    aai_cli.commands.keys
+    aai_cli.commands.llm
+    aai_cli.commands.login
+    aai_cli.commands.samples
+    aai_cli.commands.sessions
+    aai_cli.commands.stream
+    aai_cli.commands.transcribe
+    aai_cli.commands.transcripts
+
+[importlinter:contract:3]
+name = Library layers do not depend on Rich rendering
+type = forbidden
+source_modules =
+    aai_cli.client
+    aai_cli.config
+    aai_cli.config_builder
+    aai_cli.environments
+    aai_cli.errors
+    aai_cli.llm
+forbidden_modules =
+    rich

.semgrep.yml

@@ -0,0 +1,105 @@
+rules:
+  - id: aai-cli.subprocess-shell-true
+    languages: [python]
+    severity: ERROR
+    message: Use argument lists and explicit executables; shell=True expands the attack surface.
+    patterns:
+      - pattern-either:
+          - pattern: subprocess.run(..., shell=True, ...)
+          - pattern: subprocess.Popen(..., shell=True, ...)
+          - pattern: subprocess.call(..., shell=True, ...)
+          - pattern: subprocess.check_call(..., shell=True, ...)
+          - pattern: subprocess.check_output(..., shell=True, ...)
+    paths:
+      exclude:
+        - /tests/**
+
+  - id: aai-cli.subprocess-string-command
+    languages: [python]
+    severity: ERROR
+    message: Pass subprocess commands as argv lists, not shell-like strings.
+    patterns:
+      - pattern-either:
+          - pattern: subprocess.run("...", ...)
+          - pattern: subprocess.Popen("...", ...)
+          - pattern: subprocess.call("...", ...)
+          - pattern: subprocess.check_call("...", ...)
+          - pattern: subprocess.check_output("...", ...)
+    paths:
+      exclude:
+        - /tests/**
+
+  - id: aai-cli.swallowed-broad-exception
+    languages: [python]
+    severity: ERROR
+    message: Do not silently swallow broad exceptions; catch a narrower type or surface a clean error.
+    pattern-either:
+      - pattern: |
+          try:
+              ...
+          except Exception:
+              pass
+      - pattern: |
+          try:
+              ...
+          except Exception as $EXC:
+              pass
+      - pattern: |
+          try:
+              ...
+          except BaseException:
+              pass
+      - pattern: |
+          try:
+              ...
+          except BaseException as $EXC:
+              pass
+    paths:
+      exclude:
+        - /tests/**
+
+  - id: aai-cli.raw-urlopen-or-module-request
+    languages: [python]
+    severity: ERROR
+    message: Route external HTTP through typed client helpers with fixed hosts and timeout handling.
+    pattern-either:
+      - pattern: urllib.request.urlopen($URL, ...)
+      - pattern: requests.$METHOD($URL, ...)
+      - pattern: httpx.$METHOD($URL, ...)
+      - pattern: httpx2.$METHOD($URL, ...)
+    paths:
+      exclude:
+        - /aai_cli/init/templates/**
+        - /tests/**
+
+  - id: aai-cli.secret-like-value-to-stdout
+    languages: [python]
+    severity: ERROR
+    message: Secret-like values must be masked or kept on stderr/internal channels before printing.
+    patterns:
+      - pattern-either:
+          - pattern: print($VALUE, ...)
+          - pattern: $CONSOLE.print($VALUE, ...)
+          - pattern: output.emit_text($VALUE)
+      - metavariable-regex:
+          metavariable: $VALUE
+          regex: (?i).*(api_?key|session_?jwt|session_?token|token|secret|password).*
+    paths:
+      exclude:
+        - /aai_cli/code_gen/**
+        - /tests/**
+
+  - id: aai-cli.browser-asset-secret-reference
+    languages: [generic]
+    severity: ERROR
+    message: Browser-visible template assets must not reference server secrets or auth headers.
+    pattern-either:
+      - pattern: ASSEMBLYAI_API_KEY
+      - pattern: Authorization
+      - pattern: "Bearer "
+      - pattern: sk_live
+      - pattern: sk_test
+    paths:
+      include:
+        - /aai_cli/init/templates/**/index.html
+        - /aai_cli/init/templates/**/static/**

aai_cli/agent/audio.py

@@ -7,7 +7,7 @@
 from typing import Any
 
 from aai_cli.errors import CLIError
-from aai_cli.microphone import _default_rate, _resample, audio_missing_error
+from aai_cli.microphone import audio_missing_error, default_rate, resample_pcm16
 
 SAMPLE_RATE = 24000  # Voice Agent native PCM16 mono rate
 
@@ -19,7 +19,7 @@ def _output_default_rate(device: int | None = None) -> int:
     'paramErr' (-50) from forcing an unsupported one; agent audio (24 kHz) is
     resampled to it. Falls back to a safe default when the device can't be queried.
     """
-    return _default_rate("output", device)
+    return default_rate("output", device)
 
 
 class NullPlayer:
@@ -141,7 +141,7 @@ def start(self) -> None:
     def feed(self, pcm: bytes) -> None:
         """Queue target-rate PCM for playback, resampled to the device rate."""
         if self._device_rate != self._target:
-            pcm, self._out_state = _resample(
+            pcm, self._out_state = resample_pcm16(
                 pcm, self._out_state, src_rate=self._target, dst_rate=self._device_rate
             )
         with self._lock:
@@ -163,7 +163,7 @@ def capture_frames(self) -> Iterator[bytes]:
             if chunk is None:
                 return
             if self._device_rate != self._target:
-                chunk, state = _resample(
+                chunk, state = resample_pcm16(
                     chunk, state, src_rate=self._device_rate, dst_rate=self._target
                 )
             yield chunk

aai_cli/agent/session.py

@@ -71,41 +71,41 @@ def dispatch(self, event: dict[str, Any]) -> None:
         if handler is not None:
             handler(self, event)
 
-    def _on_session_ready(self, _event: dict[str, Any]) -> None:
+    def on_session_ready(self, _event: dict[str, Any]) -> None:
         with self._lock:
             self.ready = True
         if self.ready_event is not None:
             self.ready_event.set()
         self.renderer.connected()
 
-    def _on_speech_started(self, _event: dict[str, Any]) -> None:
+    def on_speech_started(self, _event: dict[str, Any]) -> None:
         if self.full_duplex:
             self.player.flush()
 
-    def _on_user_delta(self, event: dict[str, Any]) -> None:
+    def on_user_delta(self, event: dict[str, Any]) -> None:
         self.renderer.user_partial(event.get("text", ""))
 
-    def _on_user_final(self, event: dict[str, Any]) -> None:
+    def on_user_final(self, event: dict[str, Any]) -> None:
         self._saw_user = True
         self.renderer.user_final(event.get("text", ""))
 
-    def _on_reply_started(self, _event: dict[str, Any]) -> None:
+    def on_reply_started(self, _event: dict[str, Any]) -> None:
         if not self.full_duplex:
             with self._lock:
                 self.muted = True
         self.renderer.reply_started()
 
-    def _on_reply_audio(self, event: dict[str, Any]) -> None:
+    def on_reply_audio(self, event: dict[str, Any]) -> None:
         data = event.get("data")
         if data:
             self.player.enqueue(base64.b64decode(data))
 
-    def _on_agent_transcript(self, event: dict[str, Any]) -> None:
+    def on_agent_transcript(self, event: dict[str, Any]) -> None:
         self.renderer.agent_transcript(
             event.get("text", ""), interrupted=bool(event.get("interrupted", False))
         )
 
-    def _on_reply_done(self, event: dict[str, Any]) -> None:
+    def on_reply_done(self, event: dict[str, Any]) -> None:
         if not self.full_duplex:
             with self._lock:
                 self.muted = False
@@ -117,7 +117,7 @@ def _on_reply_done(self, event: dict[str, Any]) -> None:
         if self.exit_after_reply and self._saw_user and not interrupted:
             self.finished = True
 
-    def _raise_error(self, event: dict[str, Any]) -> None:
+    def raise_error(self, event: dict[str, Any]) -> None:
         code = event.get("code", "")
         message = event.get("message") or code or "Voice agent error."
         if code in _AUTH_ERROR_CODES:
@@ -132,15 +132,15 @@ def _raise_error(self, event: dict[str, Any]) -> None:
 # Server event type -> the VoiceAgentSession method that handles it. Types absent
 # here (input.speech.stopped, tool.call, anything unrecognized) are ignored.
 _EVENT_HANDLERS: dict[str, Callable[[VoiceAgentSession, dict[str, Any]], None]] = {
-    "session.ready": VoiceAgentSession._on_session_ready,
-    "input.speech.started": VoiceAgentSession._on_speech_started,
-    "transcript.user.delta": VoiceAgentSession._on_user_delta,
-    "transcript.user": VoiceAgentSession._on_user_final,
-    "reply.started": VoiceAgentSession._on_reply_started,
-    "reply.audio": VoiceAgentSession._on_reply_audio,
-    "transcript.agent": VoiceAgentSession._on_agent_transcript,
-    "reply.done": VoiceAgentSession._on_reply_done,
-    "session.error": VoiceAgentSession._raise_error,
+    "session.ready": VoiceAgentSession.on_session_ready,
+    "input.speech.started": VoiceAgentSession.on_speech_started,
+    "transcript.user.delta": VoiceAgentSession.on_user_delta,
+    "transcript.user": VoiceAgentSession.on_user_final,
+    "reply.started": VoiceAgentSession.on_reply_started,
+    "reply.audio": VoiceAgentSession.on_reply_audio,
+    "transcript.agent": VoiceAgentSession.on_agent_transcript,
+    "reply.done": VoiceAgentSession.on_reply_done,
+    "session.error": VoiceAgentSession.raise_error,
 }