solokit 0.1.1__py3-none-any.whl

solokit/init/gitignore_updater.py

@@ -0,0 +1,195 @@
+"""
+Gitignore Updater Module
+
+Updates .gitignore with Solokit and stack-specific entries.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError
+
+logger = logging.getLogger(__name__)
+
+
+def get_stack_specific_gitignore_entries(template_id: str) -> list[str]:
+    """
+    Get stack-specific .gitignore entries.
+
+    Args:
+        template_id: Template identifier
+
+    Returns:
+        List of gitignore patterns
+    """
+    # Common entries for all stacks
+    common_entries = [
+        ".session/briefings/",
+        ".session/history/",
+        "coverage/",
+        "coverage.json",
+    ]
+
+    # Node.js/Next.js stacks
+    if template_id in ["saas_t3", "dashboard_refine", "fullstack_nextjs"]:
+        return common_entries + [
+            "node_modules/",
+            ".next/",
+            "out/",
+            "build/",
+            "dist/",
+            "*.tsbuildinfo",
+            ".env",
+            ".env.local",
+            ".env.*.local",
+        ]
+
+    # Python stacks
+    elif template_id == "ml_ai_fastapi":
+        return common_entries + [
+            "venv/",
+            ".venv/",
+            "*.pyc",
+            "__pycache__/",
+            "*.py[cod]",
+            "*$py.class",
+            ".pytest_cache/",
+            ".coverage",
+            "htmlcov/",
+            ".env",
+            ".env.local",
+        ]
+
+    else:
+        return common_entries
+
+
+def get_os_specific_gitignore_entries() -> list[str]:
+    """
+    Get OS-specific .gitignore entries.
+
+    Returns:
+        List of gitignore patterns with comments
+    """
+    return [
+        "# OS-specific files",
+        ".DS_Store           # macOS",
+        ".DS_Store?          # macOS",
+        "._*                 # macOS resource forks",
+        ".Spotlight-V100     # macOS",
+        ".Trashes            # macOS",
+        "Thumbs.db           # Windows",
+        "ehthumbs.db         # Windows",
+        "Desktop.ini         # Windows",
+        "$RECYCLE.BIN/       # Windows",
+        "*~                  # Linux backup files",
+    ]
+
+
+def update_gitignore(template_id: str, project_root: Path | None = None) -> Path:
+    """
+    Add Solokit and stack-specific patterns to .gitignore.
+
+    Args:
+        template_id: Template identifier
+        project_root: Project root directory
+
+    Returns:
+        Path to .gitignore file
+
+    Raises:
+        FileOperationError: If .gitignore read/write operations fail.
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    gitignore = project_root / ".gitignore"
+
+    # Get entries to add
+    stack_entries = get_stack_specific_gitignore_entries(template_id)
+    os_entries = get_os_specific_gitignore_entries()
+
+    try:
+        existing_content = gitignore.read_text() if gitignore.exists() else ""
+    except Exception as e:
+        raise FileOperationError(
+            operation="read",
+            file_path=str(gitignore),
+            details=f"Failed to read .gitignore: {str(e)}",
+            cause=e,
+        )
+
+    # Determine which entries need to be added
+    entries_to_add = []
+    for entry in stack_entries:
+        if entry not in existing_content:
+            entries_to_add.append(entry)
+
+    # Check which OS patterns need to be added
+    # First, extract existing patterns (lines without comments)
+    existing_lines = [line.strip() for line in existing_content.split("\n")]
+    existing_patterns = set()
+    for line in existing_lines:
+        # Extract pattern (part before comment if any)
+        pattern = line.split("#")[0].strip()
+        if pattern:
+            # Normalize pattern - remove trailing ? for comparison
+            normalized = pattern.rstrip("?")
+            existing_patterns.add(normalized)
+
+    os_patterns_needed = []
+    for entry in os_entries:
+        if entry.startswith("#"):
+            continue  # Skip header in first pass
+        # Skip comment-only lines in first pass
+        pattern = entry.split("#")[0].strip()
+        if pattern:
+            # Normalize pattern for comparison
+            normalized = pattern.rstrip("?")
+            if normalized not in existing_patterns:
+                os_patterns_needed.append(entry)
+
+    # If we need to add any OS patterns, include the header
+    os_entries_to_add = []
+    if os_patterns_needed:
+        # Add the section header first
+        if "# OS-specific files" not in existing_content:
+            os_entries_to_add.append("# OS-specific files")
+        # Then add all the patterns
+        os_entries_to_add.extend(os_patterns_needed)
+
+    # Write updates
+    if entries_to_add or os_entries_to_add:
+        logger.info("Updating .gitignore...")
+        try:
+            with open(gitignore, "a") as f:
+                if existing_content and not existing_content.endswith("\n"):
+                    f.write("\n")
+
+                if entries_to_add:
+                    f.write("\n# Solokit-related patterns\n")
+                    for entry in entries_to_add:
+                        f.write(f"{entry}\n")
+
+                if os_entries_to_add:
+                    f.write("\n")
+                    for entry in os_entries_to_add:
+                        f.write(f"{entry}\n")
+
+            total_added = len(entries_to_add) + len(
+                [e for e in os_entries_to_add if not e.startswith("#")]
+            )
+            logger.info(f"Added {total_added} entries to .gitignore")
+        except Exception as e:
+            raise FileOperationError(
+                operation="write",
+                file_path=str(gitignore),
+                details=f"Failed to update .gitignore: {str(e)}",
+                cause=e,
+            )
+    else:
+        logger.info(".gitignore already up to date")
+
+    return gitignore

solokit/init/initial_commit.py

@@ -0,0 +1,145 @@
+"""
+Initial Commit Module
+
+Creates initial git commit after template initialization.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.command_runner import CommandRunner
+from solokit.core.constants import GIT_STANDARD_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+def create_commit_message(
+    template_name: str,
+    tier: str,
+    coverage_target: int,
+    additional_options: list[str],
+    stack_info: dict[str, str],
+) -> str:
+    """
+    Create commit message for initial commit.
+
+    Args:
+        template_name: Template display name
+        tier: Quality tier
+        coverage_target: Coverage target percentage
+        additional_options: List of additional options
+        stack_info: Stack information dictionary
+
+    Returns:
+        Formatted commit message
+    """
+    # Format additional options
+    options_str = ", ".join(
+        opt.replace("_", " ").title() if isinstance(opt, str) else str(opt)
+        for opt in additional_options
+    )
+    if not options_str:
+        options_str = "None"
+
+    # Format stack info
+    stack_lines = []
+    for key, value in stack_info.items():
+        formatted_key = key.replace("_", " ").title()
+        stack_lines.append(f"- {formatted_key}: {value}")
+    stack_str = "\n".join(stack_lines)
+
+    # Format tier name
+    tier_name = tier.replace("tier-", "Tier ").replace("-", " ").title()
+
+    message = f"""chore: Initialize project with Solokit template system
+
+Template: {template_name}
+Quality Tier: {tier_name}
+Coverage Target: {coverage_target}%
+Additional Options: {options_str}
+
+Stack:
+{stack_str}
+
+Generated files:
+- Project configuration and structure
+- Quality gate configs ({tier_name})
+- Session tracking infrastructure
+- Documentation templates
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"""
+
+    return message
+
+
+def create_initial_commit(
+    template_name: str,
+    tier: str,
+    coverage_target: int,
+    additional_options: list[str],
+    stack_info: dict[str, str],
+    project_root: Path | None = None,
+) -> bool:
+    """
+    Create initial commit after project initialization.
+
+    Args:
+        template_name: Template display name
+        tier: Quality tier
+        coverage_target: Coverage target percentage
+        additional_options: List of additional options
+        stack_info: Stack information dictionary
+        project_root: Root directory of the project
+
+    Returns:
+        True if initial commit was created or already exists.
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    runner = CommandRunner(default_timeout=GIT_STANDARD_TIMEOUT, working_dir=project_root)
+
+    try:
+        # Check if repository has any commits by trying to count them
+        # This will fail gracefully if no commits exist yet
+        result = runner.run(["git", "rev-list", "--count", "--all"], check=False)
+
+        if result.success and result.stdout.strip() and int(result.stdout.strip()) > 0:
+            logger.info("Git repository already has commits, skipping initial commit")
+            return True
+
+    except Exception:
+        # If command fails (e.g., no commits yet), continue to create initial commit
+        pass
+
+    try:
+        # Stage all initialized files
+        result = runner.run(["git", "add", "-A"], check=True)
+        if not result.success:
+            logger.warning(f"Git add failed: {result.stderr}")
+            logger.warning("You may need to commit manually before starting sessions")
+            return False
+
+        # Create commit message
+        commit_message = create_commit_message(
+            template_name, tier, coverage_target, additional_options, stack_info
+        )
+
+        # Create initial commit
+        result = runner.run(["git", "commit", "-m", commit_message], check=True)
+        if not result.success:
+            logger.warning(f"Git commit failed: {result.stderr}")
+            logger.warning("You may need to commit manually before starting sessions")
+            return False
+
+        logger.info("Created initial commit on main branch")
+        return True
+
+    except Exception as e:
+        logger.warning(f"Failed to create initial commit: {e}")
+        logger.warning("You may need to commit manually before starting sessions")
+        return False

solokit/init/initial_scans.py

@@ -0,0 +1,109 @@
+"""
+Initial Scans Module
+
+Runs initial stack and tree scans to populate .session/tracking/.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.command_runner import CommandRunner
+from solokit.core.constants import GIT_STANDARD_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+def run_stack_scan(project_root: Path | None = None) -> bool:
+    """
+    Run stack scan to generate stack.txt.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        True if scan succeeded
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Get Solokit installation directory
+    script_dir = Path(__file__).parent.parent / "project"
+    stack_script = script_dir / "stack.py"
+
+    if not stack_script.exists():
+        logger.warning(f"Stack script not found: {stack_script}")
+        return False
+
+    runner = CommandRunner(default_timeout=GIT_STANDARD_TIMEOUT, working_dir=project_root)
+
+    try:
+        result = runner.run(["python", str(stack_script)], check=True)
+        if result.success:
+            logger.info("Generated stack.txt")
+            return True
+        else:
+            logger.warning("Could not generate stack.txt")
+            if result.stderr:
+                logger.warning(f"Error: {result.stderr.strip()}")
+            return False
+    except Exception as e:
+        logger.warning(f"Stack generation failed: {e}")
+        return False
+
+
+def run_tree_scan(project_root: Path | None = None) -> bool:
+    """
+    Run tree scan to generate tree.txt.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        True if scan succeeded
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Get Solokit installation directory
+    script_dir = Path(__file__).parent.parent / "project"
+    tree_script = script_dir / "tree.py"
+
+    if not tree_script.exists():
+        logger.warning(f"Tree script not found: {tree_script}")
+        return False
+
+    runner = CommandRunner(default_timeout=GIT_STANDARD_TIMEOUT, working_dir=project_root)
+
+    try:
+        result = runner.run(["python", str(tree_script)], check=True)
+        if result.success:
+            logger.info("Generated tree.txt")
+            return True
+        else:
+            logger.warning("Could not generate tree.txt")
+            if result.stderr:
+                logger.warning(f"Error: {result.stderr.strip()}")
+            return False
+    except Exception as e:
+        logger.warning(f"Tree generation failed: {e}")
+        return False
+
+
+def run_initial_scans(project_root: Path | None = None) -> dict[str, bool]:
+    """
+    Run initial stack and tree scans.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Dictionary with scan results: {"stack": bool, "tree": bool}
+    """
+    logger.info("Generating project context...")
+
+    stack_success = run_stack_scan(project_root)
+    tree_success = run_tree_scan(project_root)
+
+    return {"stack": stack_success, "tree": tree_success}

solokit/init/orchestrator.py

@@ -0,0 +1,246 @@
+"""
+Template-Based Init Orchestrator
+
+Main orchestration logic for template-based project initialization.
+Implements the complete 18-step initialization flow.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Literal, Optional, cast
+
+from solokit.init.claude_commands_installer import install_claude_commands
+from solokit.init.dependency_installer import install_dependencies
+from solokit.init.docs_structure import create_docs_structure
+from solokit.init.env_generator import generate_env_files
+from solokit.init.environment_validator import validate_environment
+from solokit.init.git_hooks_installer import install_git_hooks
+from solokit.init.git_setup import check_blank_project_or_exit, check_or_init_git
+from solokit.init.gitignore_updater import update_gitignore
+from solokit.init.initial_commit import create_initial_commit
+from solokit.init.initial_scans import run_initial_scans
+from solokit.init.readme_generator import generate_readme
+from solokit.init.session_structure import create_session_directories, initialize_tracking_files
+from solokit.init.template_installer import get_template_info, install_template
+
+logger = logging.getLogger(__name__)
+
+
+def run_template_based_init(
+    template_id: str,
+    tier: str,
+    coverage_target: int,
+    additional_options: list[str] | None = None,
+    project_root: Path | None = None,
+) -> int:
+    """
+    Run complete template-based initialization with 18-step flow.
+
+    Args:
+        template_id: Template identifier (e.g., "saas_t3")
+        tier: Quality tier (e.g., "tier-2-standard")
+        coverage_target: Test coverage target percentage (60, 80, 90)
+        additional_options: List of additional options (e.g., ["ci_cd", "docker"])
+        project_root: Project root directory (defaults to current directory)
+
+    Returns:
+        0 on success, non-zero on failure
+
+    Raises:
+        Various exceptions from individual init modules on critical failures
+    """
+    if additional_options is None:
+        additional_options = []
+
+    if project_root is None:
+        project_root = Path.cwd()
+
+    logger.info("🚀 Initializing Session-Driven Development with Template System...\n")
+
+    # =========================================================================
+    # PHASE 1: PRE-FLIGHT CHECKS & VALIDATION
+    # =========================================================================
+
+    # Step 1-2: Check if already initialized + Check if blank project
+    logger.info("Step 1-2: Pre-flight validation...")
+    check_blank_project_or_exit(project_root)
+    logger.info("✓ Project directory is blank\n")
+
+    # Step 3: Initialize/verify git repository
+    logger.info("Step 3: Git initialization...")
+    check_or_init_git(project_root)
+    logger.info("")
+
+    # Step 4: Validate AND auto-update environment
+    logger.info(f"Step 4: Environment validation for {template_id}...")
+
+    # Map template_id to stack_type for environment validation
+    template_to_stack_type = {
+        "saas_t3": "saas_t3",
+        "ml_ai_fastapi": "ml_ai_fastapi",
+        "dashboard_refine": "dashboard_refine",
+        "fullstack_nextjs": "fullstack_nextjs",
+    }
+    stack_type = template_to_stack_type.get(template_id)
+
+    python_binary = None
+    if stack_type:
+        env_result = validate_environment(
+            cast(
+                Literal["saas_t3", "ml_ai_fastapi", "dashboard_refine", "fullstack_nextjs"],
+                stack_type,
+            ),
+            auto_update=True,
+        )
+        logger.info(f"✓ Environment validated for {template_id}")
+        if env_result.get("node_version"):
+            logger.info(f"  Node.js: {env_result['node_version']}")
+        if env_result.get("python_version"):
+            logger.info(f"  Python: {env_result['python_version']}")
+            python_binary = cast(Optional[str], env_result.get("python_binary"))
+    logger.info("")
+
+    # Get template information
+    template_info = get_template_info(template_id)
+
+    # =========================================================================
+    # PHASE 3: INSTALLATION & SETUP (Phase 2 is interactive, done in CLI)
+    # =========================================================================
+
+    # Step 6: Install template files (base + tier + options)
+    logger.info("Step 6: Installing template files...")
+    install_result = install_template(template_id, tier, additional_options, project_root)
+    logger.info(f"✓ Installed {install_result['files_installed']} template files\n")
+
+    # Step 7: Generate README.md
+    logger.info("Step 7: Generating README.md...")
+    generate_readme(template_id, tier, coverage_target, additional_options, project_root)
+    logger.info("✓ Generated README.md\n")
+
+    # Step 8: Config files (handled by template installation)
+    logger.info("Step 8: Config files installed via template\n")
+
+    # Step 9: Install dependencies
+    logger.info("Step 9: Installing dependencies...")
+    logger.info("⏳ This may take several minutes...\n")
+
+    try:
+        install_dependencies(
+            template_id,
+            cast(
+                Literal[
+                    "tier-1-essential",
+                    "tier-2-standard",
+                    "tier-3-comprehensive",
+                    "tier-4-production",
+                ],
+                tier,
+            ),
+            python_binary,
+            project_root,
+        )
+        logger.info("✓ Dependencies installed successfully\n")
+    except Exception as e:
+        logger.warning(f"Dependency installation encountered an issue: {e}")
+        logger.warning("You can install dependencies manually later\n")
+
+    # Step 10: Create docs directory structure
+    logger.info("Step 10: Creating documentation structure...")
+    create_docs_structure(project_root)
+    logger.info("✓ Created docs/ structure\n")
+
+    # Step 11: Starter code (handled by template)
+    logger.info("Step 11: Starter code installed via template\n")
+
+    # Step 12: Smoke tests (handled by template)
+    logger.info("Step 12: Smoke tests installed via template\n")
+
+    # Step 13: Create .env files
+    if "env_templates" in additional_options:
+        logger.info("Step 13: Generating environment files...")
+        generate_env_files(template_id, project_root)
+        logger.info("✓ Generated .env.example and .editorconfig\n")
+    else:
+        logger.info("Step 13: Skipped (environment templates not selected)\n")
+
+    # Step 14: Create .session structure
+    logger.info("Step 14: Creating .session structure...")
+    create_session_directories(project_root)
+    logger.info("✓ Created .session/ directories\n")
+
+    # Step 15: Initialize tracking files
+    logger.info("Step 15: Initializing tracking files...")
+    initialize_tracking_files(tier, coverage_target, project_root)
+    logger.info("✓ Initialized tracking files with tier-specific config\n")
+
+    # Step 16: Run initial scans (stack.txt, tree.txt)
+    logger.info("Step 16: Running initial scans...")
+    scan_results = run_initial_scans(project_root)
+    if scan_results["stack"]:
+        logger.info("✓ Generated stack.txt")
+    if scan_results["tree"]:
+        logger.info("✓ Generated tree.txt")
+    logger.info("")
+
+    # Step 17: Install git hooks
+    logger.info("Step 17: Installing git hooks...")
+    install_git_hooks(project_root)
+    logger.info("✓ Installed git hooks\n")
+
+    # Step 17.5: Install Claude Code slash commands
+    logger.info("Step 17.5: Installing Claude Code slash commands...")
+    try:
+        installed_commands = install_claude_commands(project_root)
+        logger.info(f"✓ Installed {len(installed_commands)} slash commands to .claude/commands/\n")
+    except Exception as e:
+        logger.warning(f"Claude commands installation failed: {e}")
+        logger.warning("Slash commands may not be available. You can install them manually.\n")
+
+    # Step 18: Update .gitignore
+    logger.info("Step 18: Updating .gitignore...")
+    update_gitignore(template_id, project_root)
+    logger.info("✓ Updated .gitignore\n")
+
+    # Step 19: Create initial commit
+    logger.info("Step 19: Creating initial commit...")
+    commit_success = create_initial_commit(
+        template_name=template_info["display_name"],
+        tier=tier,
+        coverage_target=coverage_target,
+        additional_options=additional_options,
+        stack_info=template_info["stack"],
+        project_root=project_root,
+    )
+    if commit_success:
+        logger.info("✓ Created initial commit\n")
+    else:
+        logger.warning("Initial commit failed (you can commit manually later)\n")
+
+    # =========================================================================
+    # SUCCESS SUMMARY
+    # =========================================================================
+
+    logger.info("=" * 70)
+    logger.info("✅ Solokit Template Initialization Complete!")
+    logger.info("=" * 70)
+    logger.info("")
+    logger.info(f"📦 Template: {template_info['display_name']}")
+    logger.info(f"🎯 Quality Tier: {tier}")
+    logger.info(f"📊 Coverage Target: {coverage_target}%")
+    logger.info("")
+    logger.info("✓ Project structure created")
+    logger.info("✓ Dependencies installed")
+    logger.info("✓ Quality gates configured")
+    logger.info("✓ Documentation structure created")
+    logger.info("✓ Session tracking initialized")
+    logger.info("✓ Git repository configured")
+    logger.info("")
+    logger.info("🚀 Next Steps:")
+    logger.info("   1. Review README.md for getting started guide")
+    logger.info("   2. Create your first work item: /sk:work-new")
+    logger.info("   3. Start working: /sk:start")
+    logger.info("")
+
+    return 0