solokit 0.1.1__py3-none-any.whl

solokit/init/claude_commands_installer.py

@@ -0,0 +1,87 @@
+"""
+Claude Commands Installer Module
+
+Installs Claude Code slash commands to project .claude/commands directory.
+This enables project-specific slash commands like /start, /end, /work-new, etc.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError, TemplateNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+def install_claude_commands(project_root: Path | None = None) -> list[Path]:
+    """
+    Install Claude Code slash commands from package to project .claude/commands directory.
+
+    This enables users who installed via PyPI to use slash commands in their project
+    without the /sk: prefix (e.g., /start instead of /sk:start).
+
+    Args:
+        project_root: Root directory of the project. Defaults to current working directory.
+
+    Returns:
+        List of installed command file paths
+
+    Raises:
+        TemplateNotFoundError: If .claude/commands directory is not found in package.
+        FileOperationError: If command installation fails.
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Destination: project's .claude/commands directory
+    commands_dest_dir = project_root / ".claude" / "commands"
+
+    # Source: .claude/commands from the installed package templates
+    # Commands are stored in templates/.claude/commands to ensure they're packaged in the wheel
+    package_dir = Path(__file__).parent.parent
+    commands_source_dir = package_dir / "templates" / ".claude" / "commands"
+
+    # Check if source commands directory exists
+    if not commands_source_dir.exists():
+        raise TemplateNotFoundError(
+            template_name=".claude/commands",
+            template_path=str(package_dir),
+        )
+
+    installed_commands = []
+
+    try:
+        # Create .claude/commands directory in project
+        commands_dest_dir.mkdir(parents=True, exist_ok=True)
+        logger.debug(f"Created directory: {commands_dest_dir.relative_to(project_root)}")
+
+        # Copy all .md command files
+        command_files = list(commands_source_dir.glob("*.md"))
+
+        if not command_files:
+            logger.warning(
+                f"No .md files found in {commands_source_dir}. "
+                "Slash commands may not work properly."
+            )
+
+        for cmd_file in command_files:
+            dest_file = commands_dest_dir / cmd_file.name
+            shutil.copy2(cmd_file, dest_file)
+            installed_commands.append(dest_file)
+            logger.debug(f"Installed command: {cmd_file.name}")
+
+        logger.info(f"Installed {len(installed_commands)} Claude Code slash commands")
+        logger.info("You can now use slash commands like /start, /end, /work-new in Claude Code")
+
+    except Exception as e:
+        raise FileOperationError(
+            operation="install",
+            file_path=str(commands_dest_dir),
+            details=f"Failed to install Claude Code commands: {str(e)}",
+            cause=e,
+        )
+
+    return installed_commands

solokit/init/dependency_installer.py

@@ -0,0 +1,313 @@
+"""
+Dependency Installer Module
+
+Handles dependency installation using exact versions from stack-versions.yaml.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import yaml
+
+from solokit.core.command_runner import CommandRunner
+from solokit.core.exceptions import CommandExecutionError, FileOperationError
+
+logger = logging.getLogger(__name__)
+
+
+def load_stack_versions() -> dict[str, Any]:
+    """
+    Load validated versions from stack-versions.yaml.
+
+    Returns:
+        Stack versions dictionary
+
+    Raises:
+        FileOperationError: If file not found or invalid YAML
+    """
+    versions_file = Path(__file__).parent.parent / "templates" / "stack-versions.yaml"
+
+    if not versions_file.exists():
+        raise FileOperationError(
+            operation="load",
+            file_path=str(versions_file),
+            details="stack-versions.yaml not found",
+        )
+
+    try:
+        with open(versions_file) as f:
+            return cast(dict[str, Any], yaml.safe_load(f))
+    except yaml.YAMLError as e:
+        raise FileOperationError(
+            operation="parse",
+            file_path=str(versions_file),
+            details=f"Invalid YAML: {str(e)}",
+            cause=e,
+        )
+
+
+def get_installation_commands(
+    stack_id: str,
+    tier: str,
+) -> dict[str, Any]:
+    """
+    Get installation commands for a stack and tier.
+
+    Args:
+        stack_id: Stack identifier (e.g., "saas_t3")
+        tier: Tier level (e.g., "tier-1")
+
+    Returns:
+        Installation commands dictionary from stack-versions.yaml
+
+    Raises:
+        FileOperationError: If stack or tier not found
+    """
+    versions = load_stack_versions()
+
+    if stack_id not in versions["stacks"]:
+        raise FileOperationError(
+            operation="lookup",
+            file_path="stack-versions.yaml",
+            details=f"Stack '{stack_id}' not found in versions file",
+        )
+
+    stack = versions["stacks"][stack_id]
+
+    if "installation" not in stack:
+        raise FileOperationError(
+            operation="lookup",
+            file_path="stack-versions.yaml",
+            details=f"No installation commands found for stack '{stack_id}'",
+        )
+
+    return cast(dict[str, Any], stack["installation"])
+
+
+def install_npm_dependencies(
+    template_id: str,
+    tier: Literal[
+        "tier-1-essential", "tier-2-standard", "tier-3-comprehensive", "tier-4-production"
+    ],
+    project_root: Path | None = None,
+) -> bool:
+    """
+    Install npm dependencies for a Next.js-based stack.
+
+    Args:
+        template_id: Template identifier (e.g., "saas_t3")
+        tier: Quality tier
+        project_root: Project root directory
+
+    Returns:
+        True if installation succeeded
+
+    Raises:
+        CommandExecutionError: If npm installation fails critically
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Map template_id to stack_id
+    template_to_stack = {
+        "saas_t3": "saas_t3",
+        "dashboard_refine": "dashboard_refine",
+        "fullstack_nextjs": "fullstack_nextjs",
+    }
+
+    stack_id = template_to_stack.get(template_id)
+    if not stack_id:
+        logger.warning(f"Unknown template ID: {template_id}")
+        return False
+
+    # Get installation commands
+    installation = get_installation_commands(stack_id, tier)
+
+    logger.info("Installing npm dependencies...")
+    logger.info("This may take several minutes...")
+
+    runner = CommandRunner(default_timeout=600, working_dir=project_root)  # 10 min timeout
+
+    # Map tier to command keys
+    tier_to_command_key = {
+        "tier-1-essential": ["base", "tier1"],
+        "tier-2-standard": ["base", "tier1", "tier2"],
+        "tier-3-comprehensive": ["base", "tier1", "tier2", "tier3"],
+        "tier-4-production": ["base", "tier1", "tier2", "tier3", "tier4_dev", "tier4_prod"],
+    }
+
+    command_keys = tier_to_command_key.get(tier, ["base"])
+
+    # Run installation commands sequentially
+    for command_key in command_keys:
+        if command_key not in installation["commands"]:
+            logger.warning(f"Command key '{command_key}' not found for {stack_id}")
+            continue
+
+        command_str = installation["commands"][command_key]
+        logger.info(f"Running: {command_key}...")
+
+        # Parse command string and run
+        result = runner.run(["sh", "-c", command_str], check=False)
+
+        if not result.success:
+            logger.error(f"Failed to install {command_key}: {result.stderr}")
+            raise CommandExecutionError(
+                command=command_str,
+                returncode=result.returncode,
+                stderr=result.stderr,
+                context={"tier": tier, "command_key": command_key},
+            )
+
+        logger.info(f"✓ Installed {command_key}")
+
+    logger.info("✅ All npm dependencies installed successfully")
+    return True
+
+
+def install_python_dependencies(
+    tier: Literal[
+        "tier-1-essential", "tier-2-standard", "tier-3-comprehensive", "tier-4-production"
+    ],
+    python_binary: str | None = None,
+    project_root: Path | None = None,
+) -> bool:
+    """
+    Install Python dependencies for ML/AI FastAPI stack.
+
+    Args:
+        tier: Quality tier
+        python_binary: Python binary to use (e.g., "python3.11")
+        project_root: Project root directory
+
+    Returns:
+        True if installation succeeded
+
+    Raises:
+        CommandExecutionError: If pip installation fails critically
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    if python_binary is None:
+        python_binary = sys.executable
+
+    # Get installation commands
+    installation = get_installation_commands("ml_ai_fastapi", tier)
+
+    logger.info("Setting up Python virtual environment...")
+
+    runner = CommandRunner(default_timeout=600, working_dir=project_root)
+
+    # Create virtual environment
+    venv_path = project_root / "venv"
+    if not venv_path.exists():
+        result = runner.run([python_binary, "-m", "venv", "venv"], check=False)
+        if not result.success:
+            raise CommandExecutionError(
+                command=f"{python_binary} -m venv venv",
+                returncode=result.returncode,
+                stderr=result.stderr,
+            )
+        logger.info("✓ Created virtual environment")
+    else:
+        logger.info("Virtual environment already exists")
+
+    # Determine pip path
+    pip_path = venv_path / "bin" / "pip"
+    if not pip_path.exists():
+        # Windows
+        pip_path = venv_path / "Scripts" / "pip"
+
+    # Upgrade pip
+    logger.info("Upgrading pip...")
+    result = runner.run([str(pip_path), "install", "--upgrade", "pip"], check=False)
+    if result.success:
+        logger.info("✓ Upgraded pip")
+
+    # Install dependencies
+    logger.info("Installing Python dependencies...")
+    logger.info("This may take several minutes...")
+
+    # Map tier to command keys (incremental installation)
+    tier_to_command_key = {
+        "tier-1-essential": ["base", "tier1"],
+        "tier-2-standard": ["base", "tier1", "tier2"],
+        "tier-3-comprehensive": ["base", "tier1", "tier2", "tier3"],
+        "tier-4-production": ["base", "tier1", "tier2", "tier3", "tier4_dev", "tier4_prod"],
+    }
+
+    command_keys = tier_to_command_key.get(tier, ["base"])
+
+    for command_key in command_keys:
+        if command_key not in installation["commands"]:
+            logger.warning(f"Command key '{command_key}' not found for ml_ai_fastapi")
+            continue
+
+        command_str = installation["commands"][command_key]
+        # Replace 'pip install' with full pip path
+        command_str = command_str.replace("pip install", f"{pip_path} install")
+
+        logger.info(f"Running: {command_key}...")
+
+        result = runner.run(["sh", "-c", command_str], check=False)
+
+        if not result.success:
+            logger.error(f"Failed to install {command_key}: {result.stderr}")
+            raise CommandExecutionError(
+                command=command_str,
+                returncode=result.returncode,
+                stderr=result.stderr,
+                context={"tier": tier, "command_key": command_key},
+            )
+
+        logger.info(f"✓ Installed {command_key}")
+
+    # Run security fixes if available
+    if "security_fixes" in installation["commands"]:
+        logger.info("Applying security fixes...")
+        command_str = installation["commands"]["security_fixes"]
+        command_str = command_str.replace("pip install", f"{pip_path} install")
+
+        result = runner.run(["sh", "-c", command_str], check=False)
+        if result.success:
+            logger.info("✓ Applied security fixes")
+        else:
+            logger.warning("Security fixes failed (non-critical)")
+
+    logger.info("✅ All Python dependencies installed successfully")
+    return True
+
+
+def install_dependencies(
+    template_id: str,
+    tier: Literal[
+        "tier-1-essential", "tier-2-standard", "tier-3-comprehensive", "tier-4-production"
+    ],
+    python_binary: str | None = None,
+    project_root: Path | None = None,
+) -> bool:
+    """
+    Install dependencies for a template based on its package manager.
+
+    Args:
+        template_id: Template identifier
+        tier: Quality tier
+        python_binary: Python binary for Python projects
+        project_root: Project root directory
+
+    Returns:
+        True if installation succeeded
+
+    Raises:
+        CommandExecutionError: If installation fails critically
+    """
+    # Determine package manager from template ID
+    if template_id == "ml_ai_fastapi":
+        return install_python_dependencies(tier, python_binary, project_root)
+    else:
+        return install_npm_dependencies(template_id, tier, project_root)

solokit/init/docs_structure.py

@@ -0,0 +1,90 @@
+"""
+Documentation Structure Module
+
+Creates documentation directory structure.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError
+
+logger = logging.getLogger(__name__)
+
+
+def create_docs_structure(project_root: Path | None = None) -> list[Path]:
+    """
+    Create documentation directory structure.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of created directory paths
+
+    Raises:
+        FileOperationError: If directory creation fails
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    docs_dir = project_root / "docs"
+    created_dirs = []
+
+    directories = [
+        docs_dir / "architecture",
+        docs_dir / "architecture" / "decisions",  # ADRs
+        docs_dir / "api",
+        docs_dir / "guides",
+    ]
+
+    try:
+        for dir_path in directories:
+            dir_path.mkdir(parents=True, exist_ok=True)
+            created_dirs.append(dir_path)
+            logger.debug(f"Created {dir_path.relative_to(project_root)}")
+
+        # Create placeholder README files
+        (docs_dir / "architecture" / "README.md").write_text(
+            "# Architecture\n\nArchitecture documentation and decisions.\n"
+        )
+        (docs_dir / "api" / "README.md").write_text(
+            "# API Documentation\n\nAPI documentation goes here.\n"
+        )
+        (docs_dir / "guides" / "development.md").write_text(
+            "# Development Guide\n\nDevelopment setup and workflow.\n"
+        )
+        (docs_dir / "guides" / "deployment.md").write_text(
+            "# Deployment Guide\n\nDeployment instructions.\n"
+        )
+
+        # Create SECURITY.md
+        security_path = docs_dir / "SECURITY.md"
+        security_path.write_text(
+            """# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it to the project maintainers.
+
+## Security Best Practices
+
+- Never commit secrets or credentials
+- Use environment variables for sensitive configuration
+- Keep dependencies up to date
+- Follow secure coding practices
+"""
+        )
+
+        logger.info(f"Created docs/ structure with {len(created_dirs)} directories")
+        return created_dirs
+
+    except Exception as e:
+        raise FileOperationError(
+            operation="create",
+            file_path=str(docs_dir),
+            details=f"Failed to create documentation structure: {str(e)}",
+            cause=e,
+        )

solokit/init/env_generator.py

@@ -0,0 +1,160 @@
+"""
+Environment File Generator Module
+
+Generates .env.example and .editorconfig files.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError
+
+logger = logging.getLogger(__name__)
+
+
+def generate_editorconfig(project_root: Path | None = None) -> Path:
+    """
+    Generate .editorconfig for universal editor configuration.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Path to .editorconfig file
+
+    Raises:
+        FileOperationError: If file creation fails
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    editorconfig_path = project_root / ".editorconfig"
+
+    content = """root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+"""
+
+    try:
+        editorconfig_path.write_text(content)
+        logger.info("Generated .editorconfig")
+        return editorconfig_path
+    except Exception as e:
+        raise FileOperationError(
+            operation="write",
+            file_path=str(editorconfig_path),
+            details=f"Failed to write .editorconfig: {str(e)}",
+            cause=e,
+        )
+
+
+def generate_env_example_nextjs(project_root: Path) -> Path:
+    """Generate .env.example for Next.js stacks."""
+    env_path = project_root / ".env.example"
+
+    content = """# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+
+# Next.js
+NEXTAUTH_SECRET=""
+NEXTAUTH_URL="http://localhost:3000"
+
+# API
+API_BASE_URL="http://localhost:3000/api"
+
+# Optional: Error Tracking (Tier 4)
+SENTRY_DSN=""
+
+# Optional: Analytics (Tier 4)
+NEXT_PUBLIC_VERCEL_ANALYTICS_ID=""
+"""
+
+    env_path.write_text(content)
+    return env_path
+
+
+def generate_env_example_python(project_root: Path) -> Path:
+    """Generate .env.example for Python stacks."""
+    env_path = project_root / ".env.example"
+
+    content = """# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+
+# API
+API_HOST="0.0.0.0"
+API_PORT=8000
+API_RELOAD=true
+
+# Security
+SECRET_KEY="your-secret-key-here"
+ALLOWED_ORIGINS="http://localhost:3000,http://localhost:8000"
+
+# Optional: Monitoring (Tier 4)
+SENTRY_DSN=""
+PROMETHEUS_PORT=9090
+"""
+
+    env_path.write_text(content)
+    return env_path
+
+
+def generate_env_files(template_id: str, project_root: Path | None = None) -> list[Path]:
+    """
+    Generate environment template files.
+
+    Args:
+        template_id: Template identifier
+        project_root: Project root directory
+
+    Returns:
+        List of created file paths
+
+    Raises:
+        FileOperationError: If file creation fails
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    created_files = []
+
+    try:
+        # Generate .editorconfig (universal)
+        editorconfig_path = generate_editorconfig(project_root)
+        created_files.append(editorconfig_path)
+
+        # Generate .env.example based on template type
+        if template_id == "ml_ai_fastapi":
+            env_path = generate_env_example_python(project_root)
+        else:
+            env_path = generate_env_example_nextjs(project_root)
+
+        created_files.append(env_path)
+        logger.info("Generated .env.example")
+
+        logger.info(f"Generated {len(created_files)} environment files")
+        return created_files
+
+    except Exception as e:
+        raise FileOperationError(
+            operation="create",
+            file_path=str(project_root),
+            details=f"Failed to generate environment files: {str(e)}",
+            cause=e,
+        )