steerdev 0.4.27__py3-none-any.whl

steerdev_agent/setup/__init__.py

@@ -0,0 +1,5 @@
+"""Setup module for configuring Claude Code integration."""
+
+from steerdev_agent.setup.claude_setup import ClaudeSetup
+
+__all__ = ["ClaudeSetup"]

steerdev_agent/setup/claude_setup.py

@@ -0,0 +1,560 @@
+"""Claude Code setup utilities for steerdev integration."""
+
+import json
+import random
+import re
+import uuid
+from importlib import resources
+from pathlib import Path
+
+from loguru import logger
+
+from steerdev_agent.config.platform import PlatformConfig
+
+# Word lists for generating agent names
+ADJECTIVES = [
+    "bright",
+    "swift",
+    "calm",
+    "bold",
+    "keen",
+    "wise",
+    "warm",
+    "cool",
+    "kind",
+    "fair",
+    "brave",
+    "quick",
+    "sharp",
+    "clear",
+    "pure",
+    "firm",
+    "soft",
+    "deep",
+    "high",
+    "vast",
+]
+
+ANIMALS = [
+    "falcon",
+    "eagle",
+    "wolf",
+    "bear",
+    "lion",
+    "tiger",
+    "hawk",
+    "owl",
+    "fox",
+    "deer",
+    "swan",
+    "crane",
+    "raven",
+    "otter",
+    "lynx",
+    "heron",
+    "finch",
+    "badger",
+    "panda",
+    "koala",
+]
+
+
+def generate_agent_name() -> str:
+    """Generate a random agent name in adjective-animal-id format.
+
+    Returns:
+        A name like "bright-falcon-abc123"
+    """
+    adjective = random.choice(ADJECTIVES)
+    animal = random.choice(ANIMALS)
+    short_id = uuid.uuid4().hex[:6]
+    return f"{adjective}-{animal}-{short_id}"
+
+
+class ClaudeSetupError(Exception):
+    """Error during Claude Code setup."""
+
+    pass
+
+
+class ClaudeSetup:
+    """Handles Claude Code configuration setup for a project.
+
+    This class manages the creation and configuration of Claude Code
+    settings, skills, and CLAUDE.md sections for steerdev.com integration.
+
+    Note: Scripts and hooks are now part of the steerdev CLI,
+    so setup_scripts() and setup_hooks() methods have been removed.
+    """
+
+    def __init__(
+        self,
+        project_dir: Path | None = None,
+        install_target: str = "project",
+    ) -> None:
+        """Initialize the setup utility.
+
+        Args:
+            project_dir: Target project directory. Uses current directory if not specified.
+            install_target: Where to install Claude configs - "project" for .claude/ in
+                project_dir, or "user" for ~/.claude/ (user-level).
+        """
+        self.project_dir = project_dir or Path.cwd()
+        self.install_target = install_target
+
+        if install_target == "user":
+            self.claude_dir = Path.home() / ".claude"
+        else:
+            self.claude_dir = self.project_dir / ".claude"
+
+        self.skills_dir = self.claude_dir / "skills"
+
+    def _get_template_path(self) -> Path:
+        """Get the path to the templates directory."""
+        # Use importlib.resources to locate templates relative to this module
+        with resources.as_file(
+            resources.files("steerdev_agent.setup") / "templates"
+        ) as templates_path:
+            return templates_path
+
+    def _read_template(self, template_name: str) -> str:
+        """Read a template file from the package.
+
+        Args:
+            template_name: Name of the template file relative to templates directory.
+
+        Returns:
+            Template content as string.
+        """
+        template_ref = resources.files("steerdev_agent.setup").joinpath("templates", template_name)
+        return template_ref.read_text()
+
+    def setup_settings(self, force: bool = False, include_hooks: bool = True) -> Path:
+        """Create or update .claude/settings.json.
+
+        Args:
+            force: Overwrite existing settings if True.
+            include_hooks: Include hooks configuration in settings.
+
+        Returns:
+            Path to the created settings file.
+        """
+        settings_path = self.claude_dir / "settings.json"
+        new_settings = json.loads(self._read_template("settings.json"))
+
+        # Remove hooks from new_settings if not including them
+        if not include_hooks:
+            new_settings.pop("hooks", None)
+
+        if settings_path.exists() and not force:
+            # Merge with existing settings
+            existing = json.loads(settings_path.read_text())
+
+            # Merge permissions.allow lists
+            if "permissions" not in existing:
+                existing["permissions"] = {}
+            if "allow" not in existing["permissions"]:
+                existing["permissions"]["allow"] = []
+
+            for rule in new_settings.get("permissions", {}).get("allow", []):
+                if rule not in existing["permissions"]["allow"]:
+                    existing["permissions"]["allow"].append(rule)
+
+            # Merge hooks configuration if include_hooks=True
+            if include_hooks and "hooks" in new_settings:
+                if "hooks" not in existing:
+                    existing["hooks"] = {}
+                for hook_event, hook_configs in new_settings["hooks"].items():
+                    if hook_event not in existing["hooks"]:
+                        existing["hooks"][hook_event] = hook_configs
+
+            settings_path.write_text(json.dumps(existing, indent=2) + "\n")
+            logger.info(f"Updated existing settings: {settings_path}")
+        else:
+            # Create new settings
+            self.claude_dir.mkdir(parents=True, exist_ok=True)
+            settings_path.write_text(json.dumps(new_settings, indent=2) + "\n")
+            logger.info(f"Created settings: {settings_path}")
+
+        return settings_path
+
+    def setup_skills(self, force: bool = False) -> Path:
+        """Create all skills (task-management, specs, context, activity, git-workflow).
+
+        Args:
+            force: Overwrite existing skills if True.
+
+        Returns:
+            Path to the skills directory.
+        """
+        # List of all skills to install
+        skills = [
+            "task-management",
+            "specs-management",
+            "context",
+            "activity",
+            "git-workflow",
+        ]
+
+        for skill_name in skills:
+            skill_dir = self.skills_dir / skill_name
+            skill_file = skill_dir / "SKILL.md"
+
+            if skill_file.exists() and not force:
+                logger.info(f"Skill already exists: {skill_file}")
+                continue
+
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_content = self._read_template(f"skills/{skill_name}/SKILL.md")
+            skill_file.write_text(skill_content)
+            logger.info(f"Created skill: {skill_file}")
+
+        return self.skills_dir
+
+    def setup_steerdev_config(self, force: bool = False) -> tuple[Path, bool]:
+        """Create steerdev.yaml configuration file.
+
+        Args:
+            force: Overwrite existing config if True.
+
+        Returns:
+            Tuple of (path to config file, True if file was created).
+        """
+        config_path = self.project_dir / "steerdev.yaml"
+
+        if config_path.exists() and not force:
+            logger.info(f"Config already exists: {config_path}")
+            return config_path, False
+
+        config_content = self._read_template("steerdev.yaml")
+        config_path.write_text(config_content)
+        logger.info(f"Created config: {config_path}")
+        return config_path, True
+
+    def setup_env(
+        self,
+        project_id: str | None = None,
+        api_key: str | None = None,
+        agent_name: str | None = None,
+    ) -> tuple[Path, bool]:
+        """Create or update .env file with steerdev environment variables.
+
+        If .env doesn't exist, creates a new one with steerdev variables.
+        If .env exists, appends steerdev variables if not already present,
+        or updates existing values if provided.
+
+        Args:
+            project_id: SteerDev project ID to configure.
+            api_key: SteerDev API key to configure.
+            agent_name: Agent name for identification. If not provided, generates one.
+
+        Returns:
+            Tuple of (path to .env file, True if file was created/updated).
+        """
+        env_path = self.project_dir / ".env"
+
+        # Generate agent name if not provided
+        if agent_name is None:
+            agent_name = generate_agent_name()
+
+        # Build the env vars content based on provided values
+        api_key_line = (
+            f"STEERDEV_API_KEY={api_key}" if api_key else "# STEERDEV_API_KEY=your-api-key-here"
+        )
+        project_id_line = (
+            f"STEERDEV_PROJECT_ID={project_id}"
+            if project_id
+            else "# STEERDEV_PROJECT_ID=your-project-id-here"
+        )
+        agent_name_line = f"STEERDEV_AGENT_NAME={agent_name}"
+
+        steerdev_env_vars = f"""
+# SteerDev Configuration
+{api_key_line}
+{project_id_line}
+{agent_name_line}
+"""
+
+        if env_path.exists():
+            existing_content = env_path.read_text()
+            updated = False
+
+            # Check if we need to update existing values or add new ones
+            has_api_key = "STEERDEV_API_KEY" in existing_content
+            has_project_id = "STEERDEV_PROJECT_ID" in existing_content
+            has_agent_name = "STEERDEV_AGENT_NAME" in existing_content
+
+            if has_api_key and has_project_id and has_agent_name:
+                # All exist - update if new values provided
+                lines = existing_content.split("\n")
+                new_lines = []
+
+                for line in lines:
+                    if line.startswith("STEERDEV_API_KEY=") or line.startswith(
+                        "# STEERDEV_API_KEY="
+                    ):
+                        if api_key:
+                            new_lines.append(f"STEERDEV_API_KEY={api_key}")
+                            updated = True
+                        else:
+                            new_lines.append(line)
+                    elif line.startswith("STEERDEV_PROJECT_ID=") or line.startswith(
+                        "# STEERDEV_PROJECT_ID="
+                    ):
+                        if project_id:
+                            new_lines.append(f"STEERDEV_PROJECT_ID={project_id}")
+                            updated = True
+                        else:
+                            new_lines.append(line)
+                    else:
+                        new_lines.append(line)
+
+                if updated:
+                    env_path.write_text("\n".join(new_lines))
+                    logger.info(f"Updated steerdev variables in: {env_path}")
+                else:
+                    logger.info(".env already contains steerdev variables")
+                return env_path, updated
+            else:
+                # Append missing steerdev variables
+                missing_vars = []
+                if not has_api_key:
+                    missing_vars.append(api_key_line)
+                if not has_project_id:
+                    missing_vars.append(project_id_line)
+                if not has_agent_name:
+                    missing_vars.append(agent_name_line)
+
+                if missing_vars:
+                    with env_path.open("a") as f:
+                        if not existing_content.endswith("\n"):
+                            f.write("\n")
+                        if not has_api_key and not has_project_id and not has_agent_name:
+                            f.write("\n# SteerDev Configuration\n")
+                        f.write("\n".join(missing_vars) + "\n")
+                    logger.info(f"Added steerdev variables to: {env_path}")
+                return env_path, bool(missing_vars)
+        else:
+            # Create new .env file
+            env_path.write_text(steerdev_env_vars.lstrip())
+            logger.info(f"Created .env file: {env_path}")
+            return env_path, True
+
+    def update_claude_md(self, force: bool = False) -> bool:
+        """Append task management section to CLAUDE.md.
+
+        Args:
+            force: Add section even if it appears to exist.
+
+        Returns:
+            True if CLAUDE.md was updated, False otherwise.
+        """
+        claude_md = self.project_dir / "CLAUDE.md"
+
+        # Read the section template
+        section_content = self._read_template("claude_md_section.md")
+        section_marker = "## Task Management"
+
+        if claude_md.exists():
+            existing_content = claude_md.read_text()
+
+            # Check if section already exists
+            if section_marker in existing_content and not force:
+                logger.info("Task management section already exists in CLAUDE.md")
+                return False
+
+            # Append section
+            with claude_md.open("a") as f:
+                f.write("\n\n" + section_content)
+            logger.info(f"Appended task management section to: {claude_md}")
+        else:
+            # Create new CLAUDE.md with just the section
+            claude_md.write_text(section_content)
+            logger.info(f"Created CLAUDE.md with task management section: {claude_md}")
+
+        return True
+
+    def setup_all(self, force: bool = False) -> dict[str, Path | bool]:
+        """Run complete setup for Claude Code integration.
+
+        Args:
+            force: Overwrite existing files if True.
+
+        Returns:
+            Dictionary with paths/status for each component.
+        """
+        results: dict[str, Path | bool] = {}
+
+        # Create .claude directory
+        self.claude_dir.mkdir(parents=True, exist_ok=True)
+
+        # Setup each component
+        results["settings"] = self.setup_settings(force=force)
+        results["skills"] = self.setup_skills(force=force)
+        results["claude_md"] = self.update_claude_md(force=force)
+
+        return results
+
+    # ========================================================================
+    # Platform Config Sync
+    # ========================================================================
+
+    _SHARED_START = "<!-- STEERDEV:SHARED:START -->"
+    _SHARED_END = "<!-- STEERDEV:SHARED:END -->"
+    _ENV_START = "# Shared Variables (Synced)"
+    _ENV_END = "# End Shared Variables"
+
+    def apply_platform_configs(self, config: PlatformConfig) -> dict[str, int]:
+        """Apply synced platform configs to the local project.
+
+        Writes system prompts to CLAUDE.md, skills to .claude/skills/,
+        MCP servers to .claude/settings.json, and env vars to .env.
+
+        Args:
+            config: Platform configuration from sync API.
+
+        Returns:
+            Dictionary with counts of applied configs per type.
+        """
+        counts: dict[str, int] = {
+            "system_prompts": 0,
+            "skills": 0,
+            "mcps": 0,
+            "env_vars": 0,
+        }
+
+        if config.system_prompts:
+            counts["system_prompts"] = self._apply_system_prompts(config)
+
+        if config.skills:
+            counts["skills"] = self._apply_skills(config)
+
+        if config.mcps:
+            counts["mcps"] = self._merge_mcp_configs(config)
+
+        if config.env_vars:
+            counts["env_vars"] = self._merge_env_vars(config)
+
+        return counts
+
+    def _apply_system_prompts(self, config: PlatformConfig) -> int:
+        """Append system prompts to CLAUDE.md between markers.
+
+        Replaces any existing shared section, or appends if not present.
+        """
+        claude_md = self.project_dir / "CLAUDE.md"
+        combined = config.get_combined_system_prompt()
+        if not combined:
+            return 0
+
+        shared_block = (
+            f"{self._SHARED_START}\n## Shared Agent Instructions\n\n{combined}\n{self._SHARED_END}"
+        )
+
+        if claude_md.exists():
+            content = claude_md.read_text()
+            # Replace existing shared block
+            pattern = re.compile(
+                re.escape(self._SHARED_START) + r".*?" + re.escape(self._SHARED_END),
+                re.DOTALL,
+            )
+            if pattern.search(content):
+                content = pattern.sub(shared_block, content)
+            else:
+                content = content.rstrip() + "\n\n" + shared_block + "\n"
+            claude_md.write_text(content)
+        else:
+            claude_md.write_text(shared_block + "\n")
+
+        logger.info(f"Applied {len(config.system_prompts)} system prompt(s) to CLAUDE.md")
+        return len(config.system_prompts)
+
+    def _apply_skills(self, config: PlatformConfig) -> int:
+        """Write skills to .claude/skills/{slug}/SKILL.md."""
+        count = 0
+        for skill in config.skills:
+            # Slugify the skill name
+            slug = re.sub(r"[^a-z0-9]+", "-", skill.name.lower()).strip("-")
+            skill_dir = self.skills_dir / slug
+            skill_dir.mkdir(parents=True, exist_ok=True)
+
+            skill_file = skill_dir / "SKILL.md"
+            instructions = skill.content.get("instructions", "")
+            if not instructions:
+                continue
+
+            # Build skill content
+            lines = [f"# {skill.name}"]
+            if skill.description:
+                lines.append(f"\n{skill.description}")
+            lines.append(f"\n{instructions}")
+
+            skill_file.write_text("\n".join(lines) + "\n")
+            count += 1
+            logger.info(f"Wrote skill: {skill_file}")
+
+        return count
+
+    def _merge_mcp_configs(self, config: PlatformConfig) -> int:
+        """Merge MCP server configs into .claude/settings.json."""
+        settings_path = self.claude_dir / "settings.json"
+        self.claude_dir.mkdir(parents=True, exist_ok=True)
+
+        settings = json.loads(settings_path.read_text()) if settings_path.exists() else {}
+
+        if "mcpServers" not in settings:
+            settings["mcpServers"] = {}
+
+        count = 0
+        for mcp in config.mcps:
+            server_name = re.sub(r"[^a-z0-9]+", "-", mcp.name.lower()).strip("-")
+            server_config: dict = {}
+
+            if "command" in mcp.content:
+                server_config["command"] = mcp.content["command"]
+            if "args" in mcp.content:
+                server_config["args"] = mcp.content["args"]
+            if mcp.content.get("env"):
+                server_config["env"] = mcp.content["env"]
+
+            if server_config:
+                settings["mcpServers"][server_name] = server_config
+                count += 1
+
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+        logger.info(f"Merged {count} MCP server(s) into settings.json")
+        return count
+
+    def _merge_env_vars(self, config: PlatformConfig) -> int:
+        """Merge shared env vars into .env between markers."""
+        env_path = self.project_dir / ".env"
+        combined = config.get_combined_env_vars()
+        if not combined:
+            return 0
+
+        # Build the env block
+        env_lines = [self._ENV_START]
+        for key, value in sorted(combined.items()):
+            env_lines.append(f"{key}={value}")
+        env_lines.append(self._ENV_END)
+        env_block = "\n".join(env_lines)
+
+        if env_path.exists():
+            content = env_path.read_text()
+            # Replace existing shared block
+            pattern = re.compile(
+                re.escape(self._ENV_START) + r".*?" + re.escape(self._ENV_END),
+                re.DOTALL,
+            )
+            if pattern.search(content):
+                content = pattern.sub(env_block, content)
+            else:
+                if not content.endswith("\n"):
+                    content += "\n"
+                content += "\n" + env_block + "\n"
+            env_path.write_text(content)
+        else:
+            env_path.write_text(env_block + "\n")
+
+        logger.info(f"Merged {len(combined)} shared env var(s) into .env")
+        return len(combined)

steerdev_agent/setup/templates/claude_md_section.md

@@ -0,0 +1,140 @@
+## Task Management
+
+This project uses steerdev.com for task management. **You must respect the task lifecycle.**
+
+### Task Lifecycle
+
+Tasks follow this Linear-compatible lifecycle:
+
+```
+BACKLOG → TODO → IN-PROGRESS → DONE
+```
+
+| Status | Description | Your Action |
+|--------|-------------|-------------|
+| `backlog` | Task is queued, not ready for work | Do not work on these tasks |
+| `todo` | Ready to be worked on | Pick up task and move to `in-progress` |
+| `in-progress` | Currently being worked on | Implement the task |
+| `done` | Task completed | No action needed |
+| `cancelled` | Task was cancelled | No action needed |
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `steerdev tasks next` | Get the next task to work on |
+| `steerdev tasks list` | List all tasks with optional filters |
+| `steerdev tasks get TASK_ID` | Get details of a specific task |
+| `steerdev tasks update TASK_ID --status STATUS` | Update task status |
+| `steerdev tasks create --title "..." --prompt "..."` | Create a new task |
+
+### Workflow
+
+1. Run `steerdev tasks next` to get the next task
+2. Update task to `in-progress` before starting work
+3. **Create a feature branch** using the task ID: `git checkout -b task/<task-id-short>`
+4. Implement the task
+5. **Commit your changes** with clear, descriptive commit messages
+6. **Create a pull request** using GitHub CLI: `gh pr create`
+7. Update task to `done` with a result summary and PR URL: `--result "Summary of work done. PR: <url>"`
+
+### Git Workflow (Required)
+
+**You MUST use Git and GitHub CLI to manage your work.** Every task implementation must result in a pull request.
+
+#### Branch Naming
+
+Create a branch before starting any implementation work:
+
+```bash
+# Use task ID for branch name (use first 8 chars of UUID)
+git checkout -b task/<short-task-id>
+
+# Example
+git checkout -b task/abc12345
+```
+
+#### Committing Changes
+
+Make atomic commits with clear messages:
+
+```bash
+# Stage and commit your changes
+git add .
+git commit -m "feat: implement user authentication
+
+- Add JWT token generation
+- Create login/logout endpoints
+- Add auth middleware"
+```
+
+Follow conventional commit format:
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `refactor:` - Code refactoring
+- `docs:` - Documentation changes
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks
+
+#### Creating Pull Requests
+
+**Always create a PR when completing a task:**
+
+```bash
+# Push branch and create PR
+git push -u origin HEAD
+gh pr create --title "Task: <title>" --body "## Summary
+
+<description of changes>
+
+## Task Reference
+Task ID: <task-id>
+
+## Changes Made
+- Change 1
+- Change 2
+
+## Testing
+- How to test the changes"
+```
+
+#### Complete Workflow Example
+
+```bash
+# 1. Get next task
+steerdev tasks next
+
+# 2. Mark as in-progress
+steerdev tasks update abc123-... --status in-progress
+
+# 3. Create feature branch
+git checkout -b task/abc12345
+
+# 4. Implement the feature (make commits as you go)
+git add .
+git commit -m "feat: add new endpoint for user data"
+
+# 5. Push and create PR
+git push -u origin HEAD
+gh pr create --title "Add user data endpoint" --body "Implementation for task abc123..."
+
+# 6. Update task to done with PR link
+steerdev tasks update abc123-... --status done --result "Implemented user data endpoint. PR: https://github.com/org/repo/pull/42"
+```
+
+**IMPORTANT:** Never leave work uncommitted. Always create a PR before marking a task as `done`.
+
+### Status Values
+
+- `backlog` - Task queued, not ready for work
+- `todo` - Ready to be worked on
+- `in-progress` - Currently working on task
+- `done` - Task completed
+- `cancelled` - Task was cancelled
+
+### Environment Variables
+
+- `STEERDEV_API_KEY` - Required for API authentication
+- `STEERDEV_PROJECT_ID` - Optional, default project ID
+- `STEERDEV_AGENT_ID` - Optional, agent identifier for tracking
+- `STEERDEV_API_ENDPOINT` - Optional, defaults to https://steerdev.com/api/v1