codee-agent 0.1.0__py3-none-any.whl

codee_agent_github_copilot/test.py

@@ -0,0 +1,176 @@
+import json
+import queue
+import subprocess
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from codee_agent_github_copilot.provider import GitHubCopilotAgent, _await_result
+from codee_main_context.context import Settings
+
+SESSION = "82232f47-df60-4cb3-8c3a-de12074c9205"
+
+
+def _event(kind: str, data: dict | None = None, **extra) -> str:
+    event = {"type": kind, **extra}
+    if data is not None:
+        event["data"] = data
+    return json.dumps(event)
+
+
+def _stream(*lines: str) -> str:
+    return "\n".join(lines) + "\n"
+
+
+def _completed(stdout: str = "", stderr: str = "", returncode: int = 0):
+    return subprocess.CompletedProcess(
+        args=["copilot"], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+class CopilotRunTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.agent = GitHubCopilotAgent(Settings(), Path("/repo"))
+
+    def _run(self, completed, model: str = "") -> str:
+        with patch("subprocess.run", return_value=completed) as run:
+            self.captured = run
+            return self.agent.run("/do-it CORE-1", SESSION, model)
+
+    def test_returns_the_last_assistant_message(self) -> None:
+        stdout = _stream(
+            _event("assistant.message", {"content": "Looking at it", "toolRequests": [{}]}),
+            _event("tool.execution_complete", {}),
+            _event("assistant.message", {"content": "Done, PR is up.\n"}),
+            _event("result", exitCode=0, sessionId=SESSION),
+        )
+
+        self.assertEqual(self._run(_completed(stdout)), "Done, PR is up.")
+
+    def test_ignores_trailing_messages_that_only_call_tools(self) -> None:
+        stdout = _stream(
+            _event("assistant.message", {"content": "The answer is 42."}),
+            _event("assistant.message", {"content": "", "toolRequests": [{}]}),
+            _event("result", exitCode=0),
+        )
+
+        self.assertEqual(self._run(_completed(stdout)), "The answer is 42.")
+
+    def test_passes_the_session_id_and_runs_headless(self) -> None:
+        stdout = _stream(_event("assistant.message", {"content": "ok"}),
+                         _event("result", exitCode=0))
+
+        self._run(_completed(stdout))
+
+        cmd = self.captured.call_args.args[0]
+        self.assertEqual(cmd[:2], ["copilot", "-p"])
+        self.assertEqual(cmd[2], "/do-it CORE-1")
+        self.assertIn("--session-id", cmd)
+        self.assertEqual(cmd[cmd.index("--session-id") + 1], SESSION)
+        for flag in ("--allow-all", "--no-ask-user", "--output-format"):
+            self.assertIn(flag, cmd)
+        self.assertEqual(self.captured.call_args.kwargs["cwd"], Path("/repo"))
+
+    def test_the_skill_model_is_passed_on_the_command_line(self) -> None:
+        stdout = _stream(_event("assistant.message", {"content": "ok"}),
+                         _event("result", exitCode=0))
+
+        self._run(_completed(stdout), model="claude-opus-5")
+
+        cmd = self.captured.call_args.args[0]
+        self.assertEqual(cmd[cmd.index("--model") + 1], "claude-opus-5")
+
+    def test_no_model_leaves_the_agent_on_its_default(self) -> None:
+        stdout = _stream(_event("assistant.message", {"content": "ok"}),
+                         _event("result", exitCode=0))
+
+        self._run(_completed(stdout))
+
+        self.assertNotIn("--model", self.captured.call_args.args[0])
+
+    def test_a_non_zero_exit_raises_with_the_stderr_reason(self) -> None:
+        completed = _completed(
+            stderr='Error: Model "nope" from --model flag is not available.',
+            returncode=1)
+
+        with self.assertRaises(RuntimeError) as caught:
+            self._run(completed)
+
+        self.assertIn("is not available", str(caught.exception))
+
+    def test_a_failed_run_raises_with_the_session_error(self) -> None:
+        stdout = _stream(
+            _event("session.error", {"errorType": "quota", "message": "quota exceeded"}),
+            _event("result", exitCode=1),
+        )
+
+        with self.assertRaises(RuntimeError) as caught:
+            self._run(_completed(stdout))
+
+        self.assertIn("quota exceeded", str(caught.exception))
+
+    def test_a_run_with_no_response_raises(self) -> None:
+        with self.assertRaises(RuntimeError):
+            self._run(_completed(_stream(_event("result", exitCode=0))))
+
+    def test_output_that_is_not_the_event_stream_is_passed_through(self) -> None:
+        self.assertEqual(self._run(_completed("plain text reply\n")),
+                         "plain text reply\n")
+
+    def test_a_timeout_raises(self) -> None:
+        with patch("subprocess.run",
+                   side_effect=subprocess.TimeoutExpired(cmd="copilot", timeout=7200)):
+            with self.assertRaises(RuntimeError):
+                self.agent.run("/do-it CORE-1", SESSION)
+
+
+class CopilotModelCatalogTest(unittest.TestCase):
+    def _queue(self, *lines: str) -> "queue.Queue[str]":
+        lines_queue: queue.Queue[str] = queue.Queue()
+        for line in lines:
+            lines_queue.put(line)
+        return lines_queue
+
+    def test_reads_the_session_new_result_past_other_traffic(self) -> None:
+        lines = self._queue(
+            json.dumps({"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": 1}}),
+            json.dumps({"jsonrpc": "2.0", "method": "session/update", "params": {}}),
+            json.dumps({"jsonrpc": "2.0", "id": 2, "result": {"sessionId": "s1"}}),
+        )
+
+        result = _await_result(Mock(poll=Mock(return_value=None)), lines, 2)
+
+        self.assertEqual(result["sessionId"], "s1")
+
+    def test_an_early_exit_raises_instead_of_waiting_out_the_deadline(self) -> None:
+        process = Mock(poll=Mock(return_value=1), returncode=1,
+                       stderr=Mock(read=Mock(return_value="not logged in")))
+
+        with self.assertRaises(RuntimeError) as caught:
+            _await_result(process, self._queue(), 2)
+
+        self.assertIn("not logged in", str(caught.exception))
+
+    def test_a_catalog_becomes_id_and_name_pairs(self) -> None:
+        result = {"models": {"availableModels": [
+            {"modelId": "claude-opus-5", "name": "Claude Opus 5"},
+            {"modelId": "gpt-5.4"},          # no display name: falls back to the id
+            {"name": "nameless"},            # no id at all: unusable, skipped
+        ]}}
+
+        with patch("codee_agent_github_copilot.provider.subprocess.Popen"), \
+                patch("codee_agent_github_copilot.provider._send"), \
+                patch("codee_agent_github_copilot.provider._await_result",
+                      return_value=result):
+            models = GitHubCopilotAgent.list_models()
+
+        self.assertEqual([(m.id, m.name) for m in models],
+                         [("claude-opus-5", "Claude Opus 5"), ("gpt-5.4", "gpt-5.4")])
+
+    def test_an_unavailable_cli_yields_no_models_rather_than_raising(self) -> None:
+        with patch("codee_agent_github_copilot.provider.subprocess.Popen",
+                   side_effect=FileNotFoundError("copilot")):
+            self.assertEqual(GitHubCopilotAgent.list_models(), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

codee_database/database.py

@@ -0,0 +1,13 @@
+from sqlite3 import Connection
+import sqlite3
+
+from anyio import Path
+from codee_main_context.context import CodeeMainContext
+
+
+def _get_db_path(main_context: CodeeMainContext) -> Path:
+    return main_context.data_dir / "codee.db"
+
+
+def get_db_connection(main_context: CodeeMainContext) -> Connection:
+    return sqlite3.connect(_get_db_path(main_context))

codee_database/oauth_tokens.py

@@ -0,0 +1,148 @@
+"""SQLite storage for OAuth tokens, keyed by tasks provider.
+
+Tokens are kept out of ``settings.json`` because that file is written by the
+admin UI on every save and is easy to hand-edit or copy around; a refresh token
+is a long-lived credential and belongs next to the rest of the runtime state.
+
+Unlike :mod:`codee.lib.runs_db` these calls raise rather than swallow errors:
+losing a token write silently would leave the UI claiming a connection that
+doesn't exist, and a read that quietly returns ``None`` would look like "never
+connected" and send the user through the whole consent flow again.
+"""
+from contextlib import closing
+from datetime import datetime, timedelta, timezone
+
+from codee_main_context.context import CodeeMainContext
+
+from codee_database.database import get_db_connection
+
+# An authorization redirect that hasn't come back within this window is treated
+# as abandoned, so a stale row can't be replayed later.
+PENDING_TTL = timedelta(minutes=10)
+
+_TOKEN_COLUMNS = ("provider", "access_token", "refresh_token", "expires_at",
+                  "scope", "account", "updated_at")
+_PENDING_COLUMNS = ("state", "provider", "code_verifier",
+                    "redirect_uri", "created_at")
+
+
+def init(main_context: CodeeMainContext) -> None:
+    """Create the token and pending-authorization tables if absent. Idempotent."""
+    with closing(get_db_connection(main_context)) as conn, conn:
+        conn.execute(
+            """CREATE TABLE IF NOT EXISTS oauth_tokens (
+                provider TEXT PRIMARY KEY,
+                access_token TEXT NOT NULL,
+                refresh_token TEXT,
+                expires_at TEXT,
+                scope TEXT,
+                account TEXT,
+                updated_at TEXT NOT NULL
+            )"""
+        )
+        # One row per authorization in flight: the CSRF state we handed to the
+        # identity provider, plus the PKCE verifier the callback has to send back.
+        conn.execute(
+            """CREATE TABLE IF NOT EXISTS oauth_pending (
+                state TEXT PRIMARY KEY,
+                provider TEXT NOT NULL,
+                code_verifier TEXT NOT NULL,
+                redirect_uri TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            )"""
+        )
+
+
+def save_tokens(
+    provider: str,
+    access_token: str,
+    refresh_token: str | None,
+    expires_at: str | None,
+    scope: str = "",
+    account: str = "",
+    main_context: CodeeMainContext = None,
+) -> None:
+    """Store (or replace) the tokens for a provider."""
+    init(main_context)
+    with closing(get_db_connection(main_context)) as conn, conn:
+        conn.execute(
+            "INSERT INTO oauth_tokens (provider, access_token, refresh_token,"
+            " expires_at, scope, account, updated_at)"
+            " VALUES (?, ?, ?, ?, ?, ?, ?)"
+            " ON CONFLICT(provider) DO UPDATE SET"
+            " access_token = excluded.access_token,"
+            " refresh_token = excluded.refresh_token,"
+            " expires_at = excluded.expires_at,"
+            " scope = excluded.scope,"
+            " account = excluded.account,"
+            " updated_at = excluded.updated_at",
+            (provider, access_token, refresh_token, expires_at, scope, account,
+             datetime.now(timezone.utc).isoformat()),
+        )
+
+
+def load_tokens(provider: str, main_context: CodeeMainContext = None) -> dict | None:
+    """Return the stored tokens for a provider, or None if it was never connected."""
+    init(main_context)
+    with closing(get_db_connection(main_context)) as conn:
+        row = conn.execute(
+            "SELECT provider, access_token, refresh_token, expires_at, scope,"
+            " account, updated_at FROM oauth_tokens WHERE provider = ?",
+            (provider,),
+        ).fetchone()
+    return dict(zip(_TOKEN_COLUMNS, row)) if row else None
+
+
+def delete_tokens(provider: str, main_context: CodeeMainContext = None) -> None:
+    """Forget a provider's tokens, so the UI reports it as disconnected."""
+    init(main_context)
+    with closing(get_db_connection(main_context)) as conn, conn:
+        conn.execute("DELETE FROM oauth_tokens WHERE provider = ?", (provider,))
+
+
+def create_pending(
+    provider: str,
+    state: str,
+    code_verifier: str,
+    redirect_uri: str,
+    main_context: CodeeMainContext = None,
+) -> None:
+    """Record an authorization we're about to send the browser off to."""
+    init(main_context)
+    with closing(get_db_connection(main_context)) as conn, conn:
+        _purge_expired_pending(conn)
+        conn.execute(
+            "INSERT OR REPLACE INTO oauth_pending (state, provider, code_verifier,"
+            " redirect_uri, created_at) VALUES (?, ?, ?, ?, ?)",
+            (state, provider, code_verifier, redirect_uri,
+             datetime.now(timezone.utc).isoformat()),
+        )
+
+
+def consume_pending(
+    provider: str,
+    state: str,
+    main_context: CodeeMainContext = None,
+) -> dict | None:
+    """Take the pending authorization matching ``state``, removing it.
+
+    Returns None when the state is unknown, belongs to another provider, or has
+    expired — all of which mean the callback must be rejected. Single-use by
+    construction: the row is deleted whether or not the exchange later succeeds,
+    so a replayed callback finds nothing.
+    """
+    init(main_context)
+    with closing(get_db_connection(main_context)) as conn, conn:
+        _purge_expired_pending(conn)
+        row = conn.execute(
+            "SELECT state, provider, code_verifier, redirect_uri, created_at"
+            " FROM oauth_pending WHERE state = ? AND provider = ?",
+            (state, provider),
+        ).fetchone()
+        conn.execute("DELETE FROM oauth_pending WHERE state = ?", (state,))
+    return dict(zip(_PENDING_COLUMNS, row)) if row else None
+
+
+def _purge_expired_pending(conn) -> None:
+    cutoff = (datetime.now(timezone.utc) - PENDING_TTL).isoformat()
+    conn.execute("DELETE FROM oauth_pending WHERE created_at < ?", (cutoff,))

codee_main_context/context.py

@@ -0,0 +1,127 @@
+import json
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+def project_root() -> Path:
+    """Directory holding the content Codee operates on: ``.claude/skills`` and ``memory/``.
+
+    Defaults to the working directory, so a project that installs Codee as a
+    package supplies its own skills and memories rather than reaching into the
+    installed package. Override with ``CODEE_PROJECT_ROOT``.
+    """
+    return Path(os.environ.get("CODEE_PROJECT_ROOT") or os.getcwd())
+
+
+def skills_dir(root: Path | None = None) -> Path:
+    return (root or project_root()) / ".claude" / "skills"
+
+
+def memory_dir(root: Path | None = None) -> Path:
+    return (root or project_root()) / "memory"
+
+
+def data_dir(root: Path | None = None) -> Path:
+    """Codee's own state directory (settings.json, runs db). Override with ``CODEE_DATA_DIR``."""
+    override = os.environ.get("CODEE_DATA_DIR")
+    return Path(override) if override else (root or project_root()) / ".codee"
+
+
+class TasksProvider(str, Enum):
+    JIRA = "jira"
+    AZURE_DEVOPS = "azure_devops"
+
+
+class CodingAgent(str, Enum):
+    CLAUDE_CODE = "claude_code"
+    GITHUB_COPILOT = "github_copilot"
+
+
+@dataclass(frozen=True)
+class CredentialField:
+    key: str
+    label: str
+    secret: bool = False
+    default: str = ""
+
+
+# Credential fields each provider needs. Keyed by provider so the admin UI can
+# render the right inputs and settings.json can store per-provider values.
+TASKS_PROVIDER_FIELDS: dict[TasksProvider, list[CredentialField]] = {
+    TasksProvider.JIRA: [
+        CredentialField("base_url", "Base URL"),
+        CredentialField("account_email", "Account email"),
+        CredentialField("api_token", "API token", secret=True),
+        CredentialField("project", "Project key"),
+    ],
+    # Azure DevOps authenticates through an Entra ID app registration, so the
+    # stored credentials describe the app; the tokens it yields live in SQLite
+    # (codee_database.oauth_tokens) rather than in settings.json.
+    TasksProvider.AZURE_DEVOPS: [
+        CredentialField("organization_url", "Organization URL"),
+        CredentialField("project", "Project"),
+        CredentialField("tenant_id", "Directory (tenant) ID"),
+        CredentialField("client_id", "Application (client) ID"),
+        CredentialField("client_secret", "Client secret", secret=True),
+    ],
+}
+
+
+@dataclass
+class Settings:
+    tasks_provider: TasksProvider = TasksProvider.JIRA
+    # Which coding agent the executor drives to work on tasks.
+    coding_agent: CodingAgent = CodingAgent.CLAUDE_CODE
+    # Per-provider credentials, keyed by provider value -> {field key: value}.
+    # Values for all providers are kept so switching provider preserves them.
+    credentials: dict[str, dict[str, str]] = field(default_factory=dict)
+    # Max coding-agent runs the executor keeps in flight at once (>= 1).
+    max_parallel_agents: int = 3
+
+
+@dataclass
+class CodeeMainContext:
+    data_dir: Path
+    settings: Settings = field(default_factory=Settings)
+
+
+def settings_file(data_dir: Path) -> Path:
+    return Path(data_dir) / "settings.json"
+
+
+def load_settings(data_dir: Path) -> Settings:
+    """Load Settings from ``settings.json`` in data_dir, or defaults if absent."""
+    path = settings_file(data_dir)
+    if path.exists():
+        try:
+            data = json.loads(path.read_text())
+            return Settings(
+                tasks_provider=TasksProvider(data["tasks_provider"]),
+                coding_agent=CodingAgent(
+                    data.get("coding_agent", CodingAgent.CLAUDE_CODE.value)),
+                credentials=data.get("credentials", {}),
+                max_parallel_agents=max(1, int(data.get("max_parallel_agents", 3))))
+        except (json.JSONDecodeError, OSError, KeyError, ValueError):
+            pass
+    return Settings()
+
+
+def save_settings(data_dir: Path, settings: Settings) -> None:
+    """Persist Settings to ``settings.json`` in data_dir.
+
+    Written through a temp file and renamed into place: the executor re-reads
+    this file on every poll, and a torn read there would look like "no settings"
+    and silently reset it to the defaults.
+    """
+    path = settings_file(data_dir)
+    payload = json.dumps({
+        "tasks_provider": settings.tasks_provider.value,
+        "coding_agent": settings.coding_agent.value,
+        "credentials": settings.credentials,
+        "max_parallel_agents": settings.max_parallel_agents,
+    }, indent=2) + "\n"
+    temp = path.with_name(path.name + ".tmp")
+    temp.write_text(payload)
+    os.replace(temp, path)

codee_main_context/logging.py

@@ -0,0 +1,111 @@
+"""Process-wide logging for Codee's entry points.
+
+Codee runs as several processes -- ``codee-start`` launches the executor and
+the admin UI as subprocesses -- so debug mode is carried in the environment:
+``CODEE_DEBUG=1`` switches this package to ``DEBUG`` level, and because
+subprocesses inherit the environment, one flag on the launcher turns on debug
+logging everywhere.
+
+Logging in any module::
+
+    from codee_main_context.logging import get_logger
+
+    log = get_logger(__name__)
+    log.debug("fetched %d task(s) from %s", len(tasks), provider.describe())
+
+Only entry points (``main()`` functions) call :func:`configure_logging`, and
+they call it once, before doing any work. Everything else just asks for a
+logger and logs; the handler is the entry point's business.
+"""
+import logging
+import os
+import sys
+from typing import TextIO
+
+# Set to "1"/"true"/"yes"/"on" for Codee debug output, or "all" to also
+# un-mute the chatty third-party libraries listed below.
+DEBUG_ENV_VAR = "CODEE_DEBUG"
+
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+_VERBOSE = "all"
+
+# Libraries whose DEBUG output would bury ours (a single boto3 call emits
+# dozens of lines). Held at INFO unless CODEE_DEBUG=all asks for everything.
+_NOISY_LOGGERS = (
+    "asyncio",
+    "boto3",
+    "botocore",
+    "httpcore",
+    "httpx",
+    "reflex",
+    "s3transfer",
+    "urllib3",
+    "watchdog",
+    "watchfiles",
+)
+
+_FORMAT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
+_DEBUG_FORMAT = "%(asctime)s %(levelname)-7s %(name)s:%(lineno)d %(funcName)s: %(message)s"
+_DATE_FORMAT = "%H:%M:%S"
+
+
+def _flag() -> str:
+    return os.environ.get(DEBUG_ENV_VAR, "").strip().lower()
+
+
+def debug_enabled() -> bool:
+    """True when ``CODEE_DEBUG`` asks for debug output."""
+    return _flag() in _TRUTHY or _flag() == _VERBOSE
+
+
+def verbose_debug_enabled() -> bool:
+    """True for ``CODEE_DEBUG=all``: our debug output plus the noisy libraries'."""
+    return _flag() == _VERBOSE
+
+
+def enable_debug(*, verbose: bool = False) -> None:
+    """Turn debug on for this process and every subprocess it goes on to spawn.
+
+    Writing to ``os.environ`` rather than to a module global is what makes
+    ``codee-start --debug`` reach the executor and admin processes, which are
+    separate interpreters that inherit the environment.
+    """
+    os.environ[DEBUG_ENV_VAR] = _VERBOSE if verbose else "1"
+
+
+def configure_logging(debug: bool | None = None, *,
+                      stream: TextIO | None = None) -> None:
+    """Install Codee's log handler. Call once, from an entry point.
+
+    ``debug=None`` (the default) takes the level from ``CODEE_DEBUG``; passing
+    ``debug=True`` also exports the flag so subprocesses inherit it. Safe to
+    call more than once -- the previous handler is replaced, not stacked.
+    """
+    if debug:
+        enable_debug()
+    if debug is None:
+        debug = debug_enabled()
+
+    logging.basicConfig(
+        level=logging.DEBUG if debug else logging.INFO,
+        format=_DEBUG_FORMAT if debug else _FORMAT,
+        datefmt=_DATE_FORMAT,
+        # stdout, not the logging default of stderr: the code around these logs
+        # still prints to stdout, and splitting the two streams would scramble
+        # their order as soon as the output is piped to a file.
+        stream=stream or sys.stdout,
+        force=True,
+    )
+
+    if not verbose_debug_enabled():
+        for name in _NOISY_LOGGERS:
+            logging.getLogger(name).setLevel(logging.INFO)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Logger for a module; pass ``__name__``.
+
+    A thin wrapper over ``logging.getLogger`` so modules have one import for
+    logging and never touch handler configuration by accident.
+    """
+    return logging.getLogger(name)

codee_main_context/test_logging.py

@@ -0,0 +1,90 @@
+import io
+import logging
+import os
+import unittest
+from unittest.mock import patch
+
+from codee_main_context.logging import (
+    DEBUG_ENV_VAR, configure_logging, debug_enabled, enable_debug, get_logger,
+    verbose_debug_enabled)
+
+
+class LoggingTest(unittest.TestCase):
+    def setUp(self) -> None:
+        root = logging.getLogger()
+        self._handlers = root.handlers[:]
+        self._level = root.level
+        self.stream = io.StringIO()
+
+    def tearDown(self) -> None:
+        root = logging.getLogger()
+        root.handlers[:] = self._handlers
+        root.setLevel(self._level)
+        logging.getLogger("botocore").setLevel(logging.NOTSET)
+
+    def test_debug_enabled_reads_the_environment(self) -> None:
+        for value in ("1", "true", "TRUE", "yes", " on ", "all"):
+            with patch.dict(os.environ, {DEBUG_ENV_VAR: value}):
+                self.assertTrue(debug_enabled(), value)
+
+        for value in ("", "0", "false", "no"):
+            with patch.dict(os.environ, {DEBUG_ENV_VAR: value}):
+                self.assertFalse(debug_enabled(), value)
+
+    def test_verbose_only_for_all(self) -> None:
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: "1"}):
+            self.assertFalse(verbose_debug_enabled())
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: "all"}):
+            self.assertTrue(verbose_debug_enabled())
+
+    def test_enable_debug_exports_the_flag_for_subprocesses(self) -> None:
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop(DEBUG_ENV_VAR, None)
+            enable_debug()
+            self.assertEqual(os.environ[DEBUG_ENV_VAR], "1")
+            enable_debug(verbose=True)
+            self.assertEqual(os.environ[DEBUG_ENV_VAR], "all")
+
+    def test_debug_messages_are_dropped_by_default(self) -> None:
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: ""}):
+            configure_logging(stream=self.stream)
+            log = get_logger("codee.sample")
+            log.debug("hidden detail")
+            log.info("visible line")
+
+        output = self.stream.getvalue()
+        self.assertNotIn("hidden detail", output)
+        self.assertIn("visible line", output)
+
+    def test_debug_messages_appear_when_enabled(self) -> None:
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: "1"}):
+            configure_logging(stream=self.stream)
+            get_logger("codee.sample").debug("task %s queued", "NIM-1")
+
+        output = self.stream.getvalue()
+        self.assertIn("DEBUG", output)
+        self.assertIn("task NIM-1 queued", output)
+        self.assertIn("codee.sample", output)
+
+    def test_explicit_debug_also_exports_the_flag(self) -> None:
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop(DEBUG_ENV_VAR, None)
+            configure_logging(debug=True, stream=self.stream)
+            self.assertEqual(os.environ[DEBUG_ENV_VAR], "1")
+            self.assertEqual(logging.getLogger().level, logging.DEBUG)
+
+    def test_noisy_libraries_stay_quiet_until_debug_all(self) -> None:
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: "1"}):
+            configure_logging(stream=self.stream)
+            self.assertEqual(logging.getLogger(
+                "botocore").level, logging.INFO)
+
+        with patch.dict(os.environ, {DEBUG_ENV_VAR: "all"}):
+            logging.getLogger("botocore").setLevel(logging.NOTSET)
+            configure_logging(stream=self.stream)
+            self.assertEqual(logging.getLogger(
+                "botocore").level, logging.NOTSET)
+
+
+if __name__ == "__main__":
+    unittest.main()