spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/cli/ui.py

@@ -0,0 +1,192 @@
+"""Reusable UI helpers for Spec Kitty CLI interactions."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import readchar
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+
+from .step_tracker import StepTracker
+
+
+def get_key() -> str:
+    """Get a single keypress in a cross-platform way using readchar."""
+    key = readchar.readkey()
+
+    if key == readchar.key.UP or key == readchar.key.CTRL_P:
+        return "up"
+    if key == readchar.key.DOWN or key == readchar.key.CTRL_N:
+        return "down"
+
+    if key == readchar.key.ENTER:
+        return "enter"
+
+    if key == readchar.key.ESC or key == "\x1b":
+        return "escape"
+
+    if key == readchar.key.CTRL_C:
+        raise KeyboardInterrupt
+
+    return key
+
+
+def _resolve_console(console: Optional[Console]) -> Console:
+    return console or Console()
+
+
+def select_with_arrows(
+    options: Dict,
+    prompt_text: str = "Select an option",
+    default_key: str | None = None,
+    console: Console | None = None,
+) -> str:
+    """
+    Interactive selection using arrow keys with Rich Live display.
+    """
+    console = _resolve_console(console)
+    option_keys = list(options.keys())
+    if default_key and default_key in option_keys:
+        selected_index = option_keys.index(default_key)
+    else:
+        selected_index = 0
+
+    selected_key = None
+
+    def create_selection_panel():
+        """Create the selection panel with current selection highlighted."""
+        table = Table.grid(padding=(0, 2))
+        table.add_column(style="cyan", justify="left", width=3)
+        table.add_column(style="white", justify="left")
+
+        for i, key in enumerate(option_keys):
+            if i == selected_index:
+                table.add_row("▶", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
+            else:
+                table.add_row(" ", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
+
+        table.add_row("", "")
+        table.add_row("", "[dim]Use ↑/↓ to navigate, Enter to select, Esc to cancel[/dim]")
+
+        return Panel(
+            table,
+            title=f"[bold]{prompt_text}[/bold]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+
+    console.print()
+
+    def run_selection_loop():
+        nonlocal selected_key, selected_index
+        with Live(create_selection_panel(), console=console, transient=True, auto_refresh=False) as live:
+            while True:
+                try:
+                    key = get_key()
+                    if key == "up":
+                        selected_index = (selected_index - 1) % len(option_keys)
+                    elif key == "down":
+                        selected_index = (selected_index + 1) % len(option_keys)
+                    elif key == "enter":
+                        selected_key = option_keys[selected_index]
+                        break
+                    elif key == "escape":
+                        console.print("\n[yellow]Selection cancelled[/yellow]")
+                        raise typer.Exit(1)
+
+                    live.update(create_selection_panel(), refresh=True)
+
+                except KeyboardInterrupt:
+                    console.print("\n[yellow]Selection cancelled[/yellow]")
+                    raise typer.Exit(1)
+
+    run_selection_loop()
+
+    if selected_key is None:
+        console.print("\n[red]Selection failed.[/red]")
+        raise typer.Exit(1)
+
+    return selected_key
+
+
+def multi_select_with_arrows(
+    options: Dict[str, str],
+    prompt_text: str = "Select options",
+    default_keys: Optional[List[str]] = None,
+    console: Console | None = None,
+) -> List[str]:
+    """Allow selecting one or more options using arrow keys + space to toggle."""
+
+    console = _resolve_console(console)
+    option_keys = list(options.keys())
+    selected_indices: set[int] = set()
+    if default_keys:
+        for key in default_keys:
+            if key in option_keys:
+                selected_indices.add(option_keys.index(key))
+    if not selected_indices and option_keys:
+        selected_indices.add(0)
+
+    cursor_index = next(iter(selected_indices)) if selected_indices else 0
+
+    def build_panel():
+        table = Table.grid(padding=(0, 2))
+        table.add_column(style="cyan", justify="left", width=3)
+        table.add_column(style="white", justify="left")
+
+        for i, key in enumerate(option_keys):
+            indicator = "[cyan]☑" if i in selected_indices else "[bright_black]☐"
+            pointer = "▶" if i == cursor_index else " "
+            table.add_row(pointer, f"{indicator} [cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
+
+        table.add_row("", "")
+        table.add_row(
+            "",
+            "[dim]Use ↑/↓ to move, Space to toggle, Enter to confirm, Esc to cancel[/dim]",
+        )
+
+        return Panel(table, title=f"[bold]{prompt_text}[/bold]", border_style="cyan", padding=(1, 2))
+
+    def normalize_selection() -> List[str]:
+        return [option_keys[i] for i in range(len(option_keys)) if i in selected_indices]
+
+    console.print()
+
+    with Live(build_panel(), console=console, transient=True, auto_refresh=False) as live:
+        while True:
+            try:
+                key = get_key()
+                if key == "up":
+                    cursor_index = (cursor_index - 1) % len(option_keys)
+                elif key == "down":
+                    cursor_index = (cursor_index + 1) % len(option_keys)
+                elif key in (" ", readchar.key.SPACE):
+                    if cursor_index in selected_indices:
+                        selected_indices.remove(cursor_index)
+                    else:
+                        selected_indices.add(cursor_index)
+                elif key == "enter":
+                    current = normalize_selection()
+                    if current:
+                        return current
+                elif key == "escape":
+                    console.print("\n[yellow]Selection cancelled[/yellow]")
+                    raise typer.Exit(1)
+
+                live.update(build_panel(), refresh=True)
+
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Selection cancelled[/yellow]")
+                raise typer.Exit(1)
+
+
+__all__ = [
+    "StepTracker",
+    "get_key",
+    "select_with_arrows",
+    "multi_select_with_arrows",
+]

specify_cli/core/__init__.py

@@ -0,0 +1,53 @@
+"""Core utilities and configuration exports."""
+
+from .config import (
+    AGENT_COMMAND_CONFIG,
+    AGENT_TOOL_REQUIREMENTS,
+    AI_CHOICES,
+    BANNER,
+    DEFAULT_MISSION_KEY,
+    DEFAULT_TEMPLATE_REPO,
+    MISSION_CHOICES,
+    SCRIPT_TYPE_CHOICES,
+)
+from .utils import format_path, ensure_directory, safe_remove, get_platform
+from .git_ops import run_command, is_git_repo, init_git_repo, get_current_branch
+from .project_resolver import (
+    locate_project_root,
+    resolve_template_path,
+    resolve_worktree_aware_feature_dir,
+    get_active_mission_key,
+)
+from .tool_checker import (
+    check_tool,
+    check_tool_for_tracker,
+    check_all_tools,
+    get_tool_version,
+)
+
+__all__ = [
+    "AGENT_COMMAND_CONFIG",
+    "AGENT_TOOL_REQUIREMENTS",
+    "AI_CHOICES",
+    "BANNER",
+    "DEFAULT_MISSION_KEY",
+    "DEFAULT_TEMPLATE_REPO",
+    "MISSION_CHOICES",
+    "SCRIPT_TYPE_CHOICES",
+    "format_path",
+    "ensure_directory",
+    "safe_remove",
+    "get_platform",
+    "run_command",
+    "is_git_repo",
+    "init_git_repo",
+    "get_current_branch",
+    "locate_project_root",
+    "resolve_template_path",
+    "resolve_worktree_aware_feature_dir",
+    "get_active_mission_key",
+    "check_tool",
+    "check_tool_for_tracker",
+    "check_all_tools",
+    "get_tool_version",
+]

specify_cli/core/agent_context.py

@@ -0,0 +1,311 @@
+"""Agent context file management for updating CLAUDE.md, GEMINI.md, etc."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+import re
+
+
+# Agent types and their file paths
+AGENT_CONFIGS = {
+    "claude": "CLAUDE.md",
+    "gemini": "GEMINI.md",
+    "copilot": ".github/copilot-instructions.md",
+    "cursor": ".cursor/rules/specify-rules.mdc",
+    "qwen": "QWEN.md",
+    "opencode": "AGENTS.md",
+    "codex": "AGENTS.md",
+    "windsurf": ".windsurf/rules/specify-rules.md",
+    "kilocode": ".kilocode/rules/specify-rules.md",
+    "auggie": ".augment/rules/specify-rules.md",
+    "roo": ".roo/rules/specify-rules.md",
+    "q": "AGENTS.md",
+}
+
+
+def parse_plan_for_tech_stack(plan_path: Path) -> Dict[str, Optional[str]]:
+    """
+    Extract tech stack information from plan.md Technical Context section.
+
+    Args:
+        plan_path: Path to plan.md file
+
+    Returns:
+        Dictionary with language, dependencies, storage, testing, project_type keys
+
+    Example return:
+        {
+            "language": "Python 3.11+",
+            "dependencies": "Typer, Rich, pathlib, subprocess",
+            "storage": "Filesystem only (no database)",
+            "testing": "pytest with unit + integration tests",
+            "project_type": "Single Python package"
+        }
+    """
+    if not plan_path.exists():
+        raise FileNotFoundError(f"Plan file not found: {plan_path}")
+
+    content = plan_path.read_text()
+
+    # Extract fields from Technical Context section using markdown patterns
+    def extract_field(pattern: str) -> Optional[str]:
+        # Match pattern like "**Language/Version**: Python 3.11+"
+        match = re.search(rf"\*\*{pattern}\*\*:\s*(.+?)(?:\n|$)", content, re.MULTILINE)
+        if match:
+            value = match.group(1).strip()
+            # Filter out placeholders
+            if value and value != "NEEDS CLARIFICATION" and value != "N/A":
+                return value
+        return None
+
+    return {
+        "language": extract_field("Language/Version"),
+        "dependencies": extract_field("Primary Dependencies"),
+        "storage": extract_field("Storage"),
+        "testing": extract_field("Testing"),
+        "project_type": extract_field("Project Type"),
+    }
+
+
+def format_technology_stack(tech_stack: Dict[str, Optional[str]], feature_slug: str) -> List[str]:
+    """
+    Format tech stack data into markdown bullet points for Active Technologies section.
+
+    Args:
+        tech_stack: Dictionary from parse_plan_for_tech_stack()
+        feature_slug: Current feature branch/slug (e.g., "008-unified-python-cli")
+
+    Returns:
+        List of formatted markdown lines
+
+    Example:
+        ["- Python 3.11+ (existing spec-kitty requirement) (008-unified-python-cli)",
+         "- Filesystem only (no database) (008-unified-python-cli)"]
+    """
+    entries = []
+
+    # Add language + dependencies as one line
+    parts = []
+    if tech_stack.get("language"):
+        parts.append(tech_stack["language"])
+    if tech_stack.get("dependencies"):
+        parts.append(tech_stack["dependencies"])
+
+    if parts:
+        tech_line = " + ".join(parts)
+        entries.append(f"- {tech_line} ({feature_slug})")
+
+    # Add storage as separate line if present
+    if tech_stack.get("storage"):
+        entries.append(f"- {tech_stack['storage']} ({feature_slug})")
+
+    return entries
+
+
+def preserve_manual_additions(old_content: str, new_content: str) -> str:
+    """
+    Preserve content between <!-- MANUAL ADDITIONS START/END --> markers.
+
+    Args:
+        old_content: Original file content with manual additions
+        new_content: New generated content
+
+    Returns:
+        Merged content with manual additions from old_content injected into new_content
+
+    Note:
+        If markers are not found in old_content, returns new_content unchanged.
+        If markers are not found in new_content, manual section is appended.
+    """
+    # Extract manual additions from old content
+    start_marker = "<!-- MANUAL ADDITIONS START -->"
+    end_marker = "<!-- MANUAL ADDITIONS END -->"
+
+    # Find manual additions in old content
+    start_idx = old_content.find(start_marker)
+    end_idx = old_content.find(end_marker)
+
+    if start_idx == -1 or end_idx == -1:
+        # No manual additions to preserve
+        return new_content
+
+    # Extract the manual section (including markers)
+    manual_section = old_content[start_idx:end_idx + len(end_marker)]
+
+    # Find where to inject in new content
+    new_start_idx = new_content.find(start_marker)
+    new_end_idx = new_content.find(end_marker)
+
+    if new_start_idx == -1 or new_end_idx == -1:
+        # New content doesn't have markers, append at end
+        return new_content.rstrip() + "\n\n" + manual_section + "\n"
+
+    # Replace the section in new content with the preserved manual section
+    before = new_content[:new_start_idx]
+    after = new_content[new_end_idx + len(end_marker):]
+
+    return before + manual_section + after
+
+
+def update_agent_context(
+    agent_type: str,
+    tech_stack: Dict[str, Optional[str]],
+    feature_slug: str,
+    repo_root: Path,
+    feature_dir: Optional[Path] = None,
+) -> None:
+    """
+    Update agent context file with tech stack from plan.md.
+
+    Args:
+        agent_type: One of the keys in AGENT_CONFIGS (claude, gemini, etc.)
+        tech_stack: Dictionary from parse_plan_for_tech_stack()
+        feature_slug: Current feature branch/slug
+        repo_root: Repository root directory
+        feature_dir: Feature directory path (for worktree-local updates)
+
+    Raises:
+        ValueError: If agent_type is not supported
+        FileNotFoundError: If agent file doesn't exist
+    """
+    if agent_type not in AGENT_CONFIGS:
+        raise ValueError(
+            f"Unsupported agent type: {agent_type}. "
+            f"Supported types: {', '.join(AGENT_CONFIGS.keys())}"
+        )
+
+    agent_file_path = repo_root / AGENT_CONFIGS[agent_type]
+
+    # If it's a worktree-local file, use feature_dir
+    if feature_dir and agent_file_path.is_relative_to(repo_root):
+        worktree_agent_file = feature_dir / AGENT_CONFIGS[agent_type]
+        if worktree_agent_file.exists():
+            agent_file_path = worktree_agent_file
+
+    if not agent_file_path.exists():
+        raise FileNotFoundError(f"Agent file not found: {agent_file_path}")
+
+    # Read existing content
+    old_content = agent_file_path.read_text()
+
+    # Format new tech entries
+    new_tech_entries = format_technology_stack(tech_stack, feature_slug)
+
+    # Prepare change entry for Recent Changes section
+    tech_parts = []
+    if tech_stack.get("language"):
+        tech_parts.append(tech_stack["language"])
+    if tech_stack.get("dependencies"):
+        tech_parts.append(tech_stack["dependencies"])
+
+    tech_description = " + ".join(tech_parts) if tech_parts else tech_stack.get("storage", "")
+    new_change_entry = f"- {feature_slug}: Added {tech_description}" if tech_description else ""
+
+    # Process file line by line to update sections
+    lines = old_content.splitlines(keepends=True)
+    new_lines = []
+
+    in_tech_section = False
+    in_changes_section = False
+    tech_entries_added = False
+    existing_changes_count = 0
+    current_date = datetime.now().strftime("%Y-%m-%d")
+
+    for line in lines:
+        # Handle Active Technologies section
+        if line.strip() == "## Active Technologies":
+            new_lines.append(line)
+            in_tech_section = True
+            continue
+
+        # Handle Recent Changes section - MUST come before generic section exit checks
+        if line.strip() == "## Recent Changes":
+            # If we were in tech section, close it first
+            if in_tech_section and not tech_entries_added and new_tech_entries:
+                for entry in new_tech_entries:
+                    new_lines.append(entry + "\n")
+                tech_entries_added = True
+                in_tech_section = False
+
+            new_lines.append(line)
+            in_changes_section = True
+            # Add new change entry right after heading
+            if new_change_entry:
+                new_lines.append(new_change_entry + "\n")
+            continue
+
+        # Check if we're exiting tech section
+        if in_tech_section and line.strip().startswith("##"):
+            # Add new tech entries before closing section
+            if not tech_entries_added and new_tech_entries:
+                for entry in new_tech_entries:
+                    new_lines.append(entry + "\n")
+                tech_entries_added = True
+            new_lines.append(line)
+            in_tech_section = False
+            continue
+
+        # Check if we're exiting changes section
+        if in_changes_section and line.strip().startswith("##"):
+            new_lines.append(line)
+            in_changes_section = False
+            continue
+
+        # In changes section: keep only first 2 existing changes, skip empty lines
+        if in_changes_section:
+            if line.strip().startswith("- "):
+                if existing_changes_count < 2:
+                    new_lines.append(line)
+                    existing_changes_count += 1
+                continue
+            elif line.strip() == "":
+                # Skip empty lines in changes section
+                continue
+
+        # Update last updated timestamp
+        if "**Last updated**:" in line or "*Last updated*:" in line:
+            # Replace date in format YYYY-MM-DD
+            line = re.sub(r'\d{4}-\d{2}-\d{2}', current_date, line)
+
+        new_lines.append(line)
+
+    # Post-loop: if still in tech section and haven't added entries
+    if in_tech_section and not tech_entries_added and new_tech_entries:
+        for entry in new_tech_entries:
+            new_lines.append(entry + "\n")
+
+    new_content = "".join(new_lines)
+
+    # Preserve manual additions
+    final_content = preserve_manual_additions(old_content, new_content)
+
+    # Write updated content
+    agent_file_path.write_text(final_content)
+
+
+def get_supported_agent_types() -> List[str]:
+    """Return list of supported agent types."""
+    return list(AGENT_CONFIGS.keys())
+
+
+def get_agent_file_path(agent_type: str, repo_root: Path) -> Path:
+    """
+    Get the file path for a specific agent type.
+
+    Args:
+        agent_type: One of the keys in AGENT_CONFIGS
+        repo_root: Repository root directory
+
+    Returns:
+        Path to the agent configuration file
+
+    Raises:
+        ValueError: If agent_type is not supported
+    """
+    if agent_type not in AGENT_CONFIGS:
+        raise ValueError(
+            f"Unsupported agent type: {agent_type}. "
+            f"Supported types: {', '.join(AGENT_CONFIGS.keys())}"
+        )
+
+    return repo_root / AGENT_CONFIGS[agent_type]

specify_cli/core/config.py

@@ -0,0 +1,96 @@
+"""Configuration constants shared across the Spec Kitty CLI."""
+
+from __future__ import annotations
+
+AI_CHOICES = {
+    "copilot": "GitHub Copilot",
+    "claude": "Claude Code",
+    "gemini": "Gemini CLI",
+    "cursor": "Cursor",
+    "qwen": "Qwen Code",
+    "opencode": "opencode",
+    "codex": "Codex CLI",
+    "windsurf": "Windsurf",
+    "kilocode": "Kilo Code",
+    "auggie": "Auggie CLI",
+    "roo": "Roo Code",
+    "q": "Amazon Q Developer CLI",
+}
+
+MISSION_CHOICES = {
+    "software-dev": "Software Dev Kitty",
+    "research": "Deep Research Kitty",
+}
+
+DEFAULT_MISSION_KEY = "software-dev"
+
+AGENT_TOOL_REQUIREMENTS: dict[str, tuple[str, str]] = {
+    "claude": ("claude", "https://docs.anthropic.com/en/docs/claude-code/setup"),
+    "gemini": ("gemini", "https://github.com/google-gemini/gemini-cli"),
+    "qwen": ("qwen", "https://github.com/QwenLM/qwen-code"),
+    "opencode": ("opencode", "https://opencode.ai"),
+    "codex": ("codex", "https://github.com/openai/codex"),
+    "auggie": ("auggie", "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli"),
+    "q": ("q", "https://aws.amazon.com/developer/learning/q-developer-cli/"),
+}
+
+SCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}
+
+DEFAULT_TEMPLATE_REPO = "spec-kitty/spec-kitty"
+
+# IDE-integrated agents that don't require CLI installation
+IDE_AGENTS = {"cursor", "windsurf", "copilot", "kilocode"}
+
+AGENT_COMMAND_CONFIG: dict[str, dict[str, str]] = {
+    "claude": {"dir": ".claude/commands", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "gemini": {"dir": ".gemini/commands", "ext": "toml", "arg_format": "{{args}}"},
+    "copilot": {"dir": ".github/prompts", "ext": "prompt.md", "arg_format": "$ARGUMENTS"},
+    "cursor": {"dir": ".cursor/commands", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "qwen": {"dir": ".qwen/commands", "ext": "toml", "arg_format": "{{args}}"},
+    "opencode": {"dir": ".opencode/command", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "windsurf": {"dir": ".windsurf/workflows", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "codex": {"dir": ".codex/prompts", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "kilocode": {"dir": ".kilocode/workflows", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "auggie": {"dir": ".augment/commands", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "roo": {"dir": ".roo/commands", "ext": "md", "arg_format": "$ARGUMENTS"},
+    "q": {"dir": ".amazonq/prompts", "ext": "md", "arg_format": "$ARGUMENTS"},
+}
+
+BANNER = """
+`````````````````````````````````````````````````````````
+
+           ▄█▄_                            ╓▄█_
+          ▐█ └▀█▄_                      ▄█▀▀ ╙█
+          █"    `▀█▄                  ▄█▀     █▌
+         ▐█        ▀█▄▄▄██████████▄▄▄█"       ▐█
+         ║█          "` ╟█  ╫▌  █" '"          █
+         ║█              ▀  ╚▀  ▀             J█
+          █                                   █▌
+          █▀   ,▄█████▄           ,▄█████▄_   █▌
+         █▌  ▄█"      "██       ╓█▀      `▀█_  █▌
+        ▐█__▐▌    ▄██▄  ╙█_____╒█   ▄██,   '█__'█
+        █▀▀▀█M    ████   █▀╙\"\"\"██  ▐████    █▀▀"█▌
+        █─  ╟█    ╙▀▀"  ██      █╕  ╙▀▀    ╓█   ║▌
+   ╓▄▄▄▄█▌,_ ╙█▄_    _▄█▀╒██████ ▀█╥     ▄█▀ __,██▄▄▄▄
+        ╚█'`"  `╙▀▀▀▀▀"   `▀██▀    "▀▀▀▀▀"   ""▐█
+     _,▄▄███▀               █▌              ▀▀███▄▄,_
+    ▀"`   ▀█_         '▀█▄▄█▀▀█▄▄█▀          ▄█"  '"▀"
+           ╙██_                            ▄█▀
+             └▀█▄_                      ,▓█▀
+                └▀▀██▄,__        __╓▄██▀▀
+                     `"▀▀▀▀▀▀▀▀▀▀▀╙"`
+
+`````````````````````````````````````````````````````````
+"""
+
+__all__ = [
+    "AI_CHOICES",
+    "MISSION_CHOICES",
+    "DEFAULT_MISSION_KEY",
+    "AGENT_TOOL_REQUIREMENTS",
+    "SCRIPT_TYPE_CHOICES",
+    "DEFAULT_TEMPLATE_REPO",
+    "AGENT_COMMAND_CONFIG",
+    "IDE_AGENTS",
+    "BANNER",
+]