Fix mypy type checking errors

- Add mypy configuration to pyproject.toml with overrides for third-party
  libraries (typer, rich, httpx, readchar, truststore, platformdirs)
- Add TypedDict definitions for AgentConfigItem and StepInfo
- Fix implicit Optional type annotations in function signatures
- Add proper type annotations for StepTracker class attributes
- Fix variable shadowing issue (rename loop variable 'f' to 'failure')
- Remove unused sys._specify_tracker_active attribute
- Add assertion for Optional[str] to Path conversion

Author: claude

pyproject.toml

@@ -22,3 +22,21 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/specify_cli"]
 
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "typer.*",
+    "rich.*",
+    "httpx.*",
+    "readchar.*",
+    "truststore.*",
+    "platformdirs.*",
+]
+ignore_missing_imports = true
+

src/specify_cli/__init__.py

@@ -33,7 +33,7 @@
 import shlex
 import json
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Callable, Optional, Tuple, TypedDict
 
 import typer
 import httpx
@@ -56,6 +56,22 @@
 ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
 client = httpx.Client(verify=ssl_context)
 
+
+class AgentConfigItem(TypedDict):
+    """Type definition for agent configuration entries."""
+    name: str
+    folder: str
+    install_url: Optional[str]
+    requires_cli: bool
+
+
+class StepInfo(TypedDict):
+    """Type definition for step tracking entries."""
+    key: str
+    label: str
+    status: str
+    detail: str
+
 def _github_token(cli_token: str | None = None) -> str | None:
     """Return sanitized GitHub token (cli arg takes precedence) or None."""
     return ((cli_token or os.getenv("GH_TOKEN") or os.getenv("GITHUB_TOKEN") or "").strip()) or None
@@ -123,7 +139,7 @@ def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str)
     return "\n".join(lines)
 
 # Agent configuration with name, folder, install URL, and CLI tool requirement
-AGENT_CONFIG = {
+AGENT_CONFIG: dict[str, AgentConfigItem] = {
     "copilot": {
         "name": "GitHub Copilot",
         "folder": ".github/",
@@ -236,11 +252,11 @@ class StepTracker:
     """
     def __init__(self, title: str):
         self.title = title
-        self.steps = []  # list of dicts: {key, label, status, detail}
+        self.steps: list[StepInfo] = []
         self.status_order = {"pending": 0, "running": 1, "done": 2, "error": 3, "skipped": 4}
-        self._refresh_cb = None  # callable to trigger UI refresh
+        self._refresh_cb: Optional[Callable[[], None]] = None
 
-    def attach_refresh(self, cb):
+    def attach_refresh(self, cb: Callable[[], None]) -> None:
         self._refresh_cb = cb
 
     def add(self, key: str, label: str):
@@ -335,7 +351,7 @@ def get_key():
 
     return key
 
-def select_with_arrows(options: dict, prompt_text: str = "Select an option", default_key: str = None) -> str:
+def select_with_arrows(options: dict[str, str], prompt_text: str = "Select an option", default_key: Optional[str] = None) -> str:
     """
     Interactive selection using arrow keys with Rich Live display.
     
@@ -469,7 +485,7 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False
             raise
         return None
 
-def check_tool(tool: str, tracker: StepTracker = None) -> bool:
+def check_tool(tool: str, tracker: Optional["StepTracker"] = None) -> bool:
     """Check if a tool is installed. Optionally update tracker.
     
     Args:
@@ -500,7 +516,7 @@ def check_tool(tool: str, tracker: StepTracker = None) -> bool:
 
     return found
 
-def is_git_repo(path: Path = None) -> bool:
+def is_git_repo(path: Optional[Path] = None) -> bool:
     """Check if the specified path is inside a git repository."""
     if path is None:
         path = Path.cwd()
@@ -622,7 +638,7 @@ def deep_merge(base: dict, update: dict) -> dict:
 
     return merged
 
-def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = "sh", verbose: bool = True, show_progress: bool = True, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Tuple[Path, dict]:
+def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = "sh", verbose: bool = True, show_progress: bool = True, client: Optional[httpx.Client] = None, debug: bool = False, github_token: Optional[str] = None) -> Tuple[Path, dict]:
     repo_owner = "github"
     repo_name = "spec-kit"
     if client is None:
@@ -736,7 +752,7 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri
     }
     return zip_path, metadata
 
-def download_and_extract_template(project_path: Path, ai_assistant: str, script_type: str, is_current_dir: bool = False, *, verbose: bool = True, tracker: StepTracker | None = None, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Path:
+def download_and_extract_template(project_path: Path, ai_assistant: str, script_type: str, is_current_dir: bool = False, *, verbose: bool = True, tracker: Optional["StepTracker"] = None, client: Optional[httpx.Client] = None, debug: bool = False, github_token: Optional[str] = None) -> Path:
     """Download the latest release and extract it to create a new project.
     Returns project_path. Uses tracker if provided (with keys: fetch, download, extract, cleanup)
     """
@@ -927,22 +943,22 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None =
             console.print(f"[cyan]Updated execute permissions on {updated} script(s) recursively[/cyan]")
         if failures:
             console.print("[yellow]Some scripts could not be updated:[/yellow]")
-            for f in failures:
-                console.print(f"  - {f}")
+            for failure in failures:
+                console.print(f"  - {failure}")
 
 @app.command()
 def init(
-    project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
-    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, shai, or q"),
-    script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"),
+    project_name: Optional[str] = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
+    ai_assistant: Optional[str] = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, shai, or q"),
+    script_type: Optional[str] = typer.Option(None, "--script", help="Script type to use: sh or ps"),
     ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"),
     no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"),
     here: bool = typer.Option(False, "--here", help="Initialize project in the current directory instead of creating a new one"),
     force: bool = typer.Option(False, "--force", help="Force merge/overwrite when using --here (skip confirmation)"),
     skip_tls: bool = typer.Option(False, "--skip-tls", help="Skip SSL/TLS verification (not recommended)"),
     debug: bool = typer.Option(False, "--debug", help="Show verbose diagnostic output for network and extraction failures"),
-    github_token: str = typer.Option(None, "--github-token", help="GitHub token to use for API requests (or set GH_TOKEN or GITHUB_TOKEN environment variable)"),
-):
+    github_token: Optional[str] = typer.Option(None, "--github-token", help="GitHub token to use for API requests (or set GH_TOKEN or GITHUB_TOKEN environment variable)"),
+) -> None:
     """
     Initialize a new Specify project from the latest template.
     
@@ -998,6 +1014,7 @@ def init(
                     console.print("[yellow]Operation cancelled[/yellow]")
                     raise typer.Exit(0)
     else:
+        assert project_name is not None  # Validated above
         project_path = Path(project_name).resolve()
         if project_path.exists():
             error_panel = Panel(
@@ -1081,8 +1098,6 @@ def init(
 
     tracker = StepTracker("Initialize Specify Project")
 
-    sys._specify_tracker_active = True
-
     tracker.add("precheck", "Check required tools")
     tracker.complete("precheck", "ok")
     tracker.add("ai-select", "Select AI assistant")