solokit 0.1.1__py3-none-any.whl

solokit/init/readme_generator.py

@@ -0,0 +1,207 @@
+"""
+README Generator Module
+
+Generates project README.md with stack-specific information.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError
+from solokit.init.template_installer import get_template_info, load_template_registry
+
+logger = logging.getLogger(__name__)
+
+
+def generate_readme(
+    template_id: str,
+    tier: str,
+    coverage_target: int,
+    additional_options: list[str],
+    project_root: Path | None = None,
+) -> Path:
+    """
+    Generate README.md for the project.
+
+    Args:
+        template_id: Template identifier
+        tier: Quality tier
+        coverage_target: Test coverage target percentage
+        additional_options: List of additional options installed
+        project_root: Project root directory
+
+    Returns:
+        Path to generated README.md
+
+    Raises:
+        FileOperationError: If README generation fails
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    template_info = get_template_info(template_id)
+    registry = load_template_registry()
+
+    tier_info = registry["quality_tiers"].get(tier, {})
+
+    # Get project name from directory
+    project_name = project_root.name
+
+    # Build README content
+    readme_content = f"""# {project_name}
+
+A {template_info["display_name"]} project built with Session-Driven Development.
+
+## Tech Stack
+
+"""
+
+    # Add stack information
+    for key, value in template_info["stack"].items():
+        formatted_key = key.replace("_", " ").title()
+        readme_content += f"- **{formatted_key}**: {value}\n"
+
+    readme_content += f"\n## Quality Gates: {tier_info.get('name', tier)}\n\n"
+
+    if "includes" in tier_info:
+        for item in tier_info["includes"]:
+            readme_content += f"- ✓ {item}\n"
+
+    if "adds" in tier_info:
+        for item in tier_info["adds"]:
+            readme_content += f"- ✓ {item}\n"
+
+    readme_content += f"\n**Test Coverage Target**: {coverage_target}%\n"
+
+    # Add getting started section
+    readme_content += "\n## Getting Started\n\n"
+
+    if template_info["package_manager"] == "npm":
+        readme_content += """```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+```
+
+Visit http://localhost:3000
+
+"""
+    else:  # Python
+        readme_content += """```bash
+# Activate virtual environment
+source venv/bin/activate  # Unix
+# or
+venv\\Scripts\\activate  # Windows
+
+# Run development server
+uvicorn main:app --reload
+```
+
+Visit http://localhost:8000
+
+"""
+
+    # Add testing section
+    readme_content += "## Testing\n\n"
+
+    if template_info["package_manager"] == "npm":
+        readme_content += """```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run linting
+npm run lint
+
+# Run type checking
+npm run type-check
+```
+"""
+    else:  # Python
+        readme_content += """```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov --cov-report=html
+
+# Run linting
+ruff check .
+
+# Run type checking
+pyright
+```
+"""
+
+    # Add additional options documentation
+    if additional_options:
+        readme_content += "\n## Additional Features\n\n"
+        for option in additional_options:
+            option_key = option.replace("_", " ").title()
+            readme_content += f"- ✓ {option_key}\n"
+
+    # Add known issues if any
+    if template_info.get("known_issues"):
+        critical_issues = [
+            issue
+            for issue in template_info["known_issues"]
+            if issue["severity"] in ["CRITICAL", "HIGH"]
+        ]
+        if critical_issues:
+            readme_content += "\n## Known Issues\n\n"
+            for issue in critical_issues:
+                readme_content += (
+                    f"**{issue['package']}** ({issue['severity']}): {issue['description']}\n\n"
+                )
+
+    # Add Session-Driven Development section
+    readme_content += """## Session-Driven Development
+
+This project uses Session-Driven Development (Solokit) for organized, AI-augmented development.
+
+### Commands
+
+- `/sk:work-new` - Create a new work item
+- `/sk:work-list` - List all work items
+- `/sk:start` - Start working on a work item
+- `/sk:status` - Check current session status
+- `/sk:validate` - Validate quality gates
+- `/sk:end` - Complete current session
+- `/sk:learn` - Capture a learning
+
+### Documentation
+
+See `.session/` directory for:
+- Work item specifications (`.session/specs/`)
+- Session briefings (`.session/briefings/`)
+- Session summaries (`.session/history/`)
+- Captured learnings (`.session/tracking/learnings.json`)
+
+"""
+
+    # Add footer
+    readme_content += """---
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+"""
+
+    # Write README
+    readme_path = project_root / "README.md"
+
+    try:
+        readme_path.write_text(readme_content)
+        logger.info(f"Generated {readme_path.name}")
+        return readme_path
+    except Exception as e:
+        raise FileOperationError(
+            operation="write",
+            file_path=str(readme_path),
+            details=f"Failed to write README.md: {str(e)}",
+            cause=e,
+        )

solokit/init/session_structure.py

@@ -0,0 +1,239 @@
+"""
+Session Structure Module
+
+Creates .session directory structure and tracking files.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from solokit.core.exceptions import FileOperationError
+
+logger = logging.getLogger(__name__)
+
+
+def create_session_directories(project_root: Path | None = None) -> list[Path]:
+    """
+    Create .session 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()
+
+    session_dir = project_root / ".session"
+    created_dirs = []
+
+    directories = [
+        session_dir / "tracking",
+        session_dir / "briefings",
+        session_dir / "history",
+        session_dir / "specs",
+    ]
+
+    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)}")
+
+        logger.info(f"Created .session/ structure with {len(created_dirs)} directories")
+        return created_dirs
+
+    except Exception as e:
+        raise FileOperationError(
+            operation="create",
+            file_path=str(session_dir),
+            details=f"Failed to create .session directory structure: {str(e)}",
+            cause=e,
+        )
+
+
+def initialize_tracking_files(
+    tier: str, coverage_target: int, project_root: Path | None = None
+) -> list[Path]:
+    """
+    Initialize tracking files from templates with tier-specific config.
+
+    Args:
+        tier: Quality tier (e.g., "tier-2-standard")
+        coverage_target: Test coverage target percentage
+        project_root: Project root directory
+
+    Returns:
+        List of created file paths
+
+    Raises:
+        FileOperationError: If file operations fail
+        TemplateNotFoundError: If required template files are missing
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    session_dir = project_root / ".session"
+    template_dir = Path(__file__).parent.parent / "templates"
+    created_files = []
+
+    logger.info("Initializing tracking files...")
+
+    # Copy template tracking files
+    tracking_files = [
+        ("work_items.json", "tracking/work_items.json"),
+        ("learnings.json", "tracking/learnings.json"),
+        ("status_update.json", "tracking/status_update.json"),
+    ]
+
+    for src, dst in tracking_files:
+        src_path = template_dir / src
+        dst_path = session_dir / dst
+        if src_path.exists():
+            try:
+                shutil.copy(src_path, dst_path)
+                created_files.append(dst_path)
+                logger.debug(f"Created {dst}")
+            except Exception as e:
+                raise FileOperationError(
+                    operation="copy",
+                    file_path=str(dst_path),
+                    details=f"Failed to copy tracking file template: {str(e)}",
+                    cause=e,
+                )
+
+    # Create empty update tracking files
+    try:
+        updates_files = [
+            session_dir / "tracking" / "stack_updates.json",
+            session_dir / "tracking" / "tree_updates.json",
+        ]
+        for update_file in updates_files:
+            update_file.write_text(json.dumps({"updates": []}, indent=2))
+            created_files.append(update_file)
+            logger.debug(f"Created {update_file.name}")
+    except Exception as e:
+        raise FileOperationError(
+            operation="create",
+            file_path=str(session_dir / "tracking"),
+            details=f"Failed to create tracking files: {str(e)}",
+            cause=e,
+        )
+
+    # Create config.json with tier-specific settings
+    config_data = {
+        "curation": {
+            "auto_curate": True,
+            "frequency": 5,
+            "dry_run": False,
+            "similarity_threshold": 0.7,
+            "categories": [
+                "architecture_patterns",
+                "gotchas",
+                "best_practices",
+                "technical_debt",
+                "performance_insights",
+                "security",
+            ],
+        },
+        "quality_gates": {
+            "tier": tier,
+            "coverage_threshold": coverage_target,
+            "test_execution": {"enabled": True, "required": True},
+            "linting": {"enabled": True, "required": True},
+            "formatting": {"enabled": True, "required": True},
+            "security": {"enabled": True, "required": True},
+            "documentation": {
+                "enabled": True,
+                "required": True,
+                "check_changelog": True,
+                "check_docstrings": True,
+                "check_readme": False,
+            },
+            "context7": {
+                "enabled": False,
+                "required": True,
+                "important_libraries": [],
+            },
+            "custom_validations": {"rules": []},
+        },
+        "integration_tests": {
+            "enabled": True,
+            "docker_compose_file": "docker-compose.integration.yml",
+            "environment_validation": True,
+            "health_check_timeout": 300,
+            "test_data_fixtures": True,
+            "parallel_execution": True,
+            "performance_benchmarks": {
+                "enabled": True,
+                "required": True,
+                "regression_threshold": 0.10,
+                "baseline_storage": ".session/tracking/performance_baselines.json",
+                "load_test_tool": "wrk",
+                "metrics": ["response_time", "throughput", "resource_usage"],
+            },
+            "api_contracts": {
+                "enabled": True,
+                "required": True,
+                "contract_format": "openapi",
+                "breaking_change_detection": True,
+                "version_storage": ".session/tracking/api_contracts/",
+                "fail_on_breaking_changes": True,
+            },
+            "documentation": {
+                "architecture_diagrams": True,
+                "sequence_diagrams": True,
+                "contract_documentation": True,
+                "performance_baseline_docs": True,
+            },
+        },
+        "git_workflow": {
+            "mode": "pr",
+            "auto_push": True,
+            "auto_create_pr": True,
+            "delete_branch_after_merge": True,
+            "pr_title_template": "{type}: {title}",
+            "pr_body_template": "## Summary\n\n{description}\n\n## Work Item\n- ID: {work_item_id}\n- Type: {type}\n- Session: {session_num}\n\n## Changes\n{commit_messages}\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
+        },
+    }
+
+    try:
+        config_path = session_dir / "config.json"
+        config_path.write_text(json.dumps(config_data, indent=2))
+        created_files.append(config_path)
+        logger.info("Created config.json with tier-specific settings")
+    except Exception as e:
+        raise FileOperationError(
+            operation="create",
+            file_path=str(session_dir / "config.json"),
+            details=f"Failed to create config.json: {str(e)}",
+            cause=e,
+        )
+
+    # Copy config schema file
+    schema_source = template_dir / "config.schema.json"
+    schema_dest = session_dir / "config.schema.json"
+
+    if schema_source.exists() and not schema_dest.exists():
+        try:
+            shutil.copy(schema_source, schema_dest)
+            created_files.append(schema_dest)
+            logger.info("Created config.schema.json")
+        except Exception as e:
+            raise FileOperationError(
+                operation="copy",
+                file_path=str(schema_dest),
+                details=f"Failed to copy config schema: {str(e)}",
+                cause=e,
+            )
+
+    logger.info(f"Initialized {len(created_files)} tracking files")
+    return created_files