codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/notifications_config.py

@@ -0,0 +1,183 @@
+"""Per-workspace outbound webhook notification config (issue #560).
+
+Stored alongside other workspace UI settings under ``.codeframe/`` as a JSON
+file. Headless — no FastAPI or HTTP imports.
+
+Schema (``.codeframe/notifications_config.json``):
+
+    {
+      "webhook_url": "https://hooks.example.com/...",  // or null
+      "webhook_enabled": true
+    }
+
+Defense-in-depth: ``is_webhook_active`` re-validates the URL scheme/host
+because the JSON file can be hand-edited or migrated from an older
+deployment that didn't enforce validation at write time. The router PUT
+endpoint validates too — never trust just one layer.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Optional, TypedDict
+
+from codeframe.core.workspace import Workspace
+
+logger = logging.getLogger(__name__)
+
+NOTIFICATIONS_CONFIG_FILENAME = "notifications_config.json"
+
+# Intentionally duplicated with codeframe/ui/routers/settings_v2.py's
+# ``_ALLOWED_WEBHOOK_SCHEMES``: core cannot import from the UI layer
+# (architecture rule #1 — core must be headless). Keep both values in
+# sync if extended.
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+class NotificationsConfig(TypedDict):
+    webhook_url: Optional[str]
+    webhook_enabled: bool
+
+
+_DEFAULT: NotificationsConfig = {"webhook_url": None, "webhook_enabled": False}
+
+
+def _config_path(workspace: Workspace) -> Path:
+    return workspace.state_dir / NOTIFICATIONS_CONFIG_FILENAME
+
+
+def _is_safe_webhook_url(url: str) -> bool:
+    """Defence-in-depth: scheme/host check on a stored URL before we POST.
+
+    The router PUT validates too, but a hand-edited or pre-migration JSON
+    file could carry a ``file://`` or schemeless URL. Used by
+    ``is_webhook_active`` to fail-safe to ``None``.
+
+    TODO: This does NOT block RFC-1918 (10/8, 172.16/12, 192.168/16) or
+    loopback (127/8) addresses. For a self-hosted single-user tool that is
+    intentional — users want to point at local receivers. If CodeFRAME ever
+    runs as a shared / multi-tenant service, add a socket-level check here
+    that resolves the host and rejects private/loopback ranges.
+    """
+    from urllib.parse import urlparse
+
+    try:
+        parsed = urlparse(url)
+    except (TypeError, ValueError):
+        return False
+    return parsed.scheme.lower() in _ALLOWED_SCHEMES and bool(parsed.netloc)
+
+
+def load_notifications_config(workspace: Workspace) -> NotificationsConfig:
+    """Read notifications config, returning defaults on missing/corrupt file.
+
+    Never raises — a broken config should not break the triggering operation.
+    Non-object JSON (``[]``, ``null``, a bare integer) is treated as corrupt
+    and falls back to defaults rather than raising ``AttributeError`` from
+    a downstream ``.get()`` call.
+    """
+    path = _config_path(workspace)
+    if not path.exists():
+        return dict(_DEFAULT)  # type: ignore[return-value]
+    try:
+        data = json.loads(path.read_text())
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Expected JSON object, got {type(data).__name__}"
+            )
+        return {
+            "webhook_url": data.get("webhook_url") or None,
+            "webhook_enabled": bool(data.get("webhook_enabled", False)),
+        }
+    except (OSError, json.JSONDecodeError, ValueError) as e:
+        logger.warning(
+            "Invalid notifications_config.json — falling back to defaults: %s", e
+        )
+        return dict(_DEFAULT)  # type: ignore[return-value]
+
+
+def save_notifications_config(
+    workspace: Workspace, config: NotificationsConfig
+) -> None:
+    """Atomically persist notifications config to disk."""
+    path = _config_path(workspace)
+    payload = {
+        "webhook_url": config.get("webhook_url") or None,
+        "webhook_enabled": bool(config.get("webhook_enabled", False)),
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(payload, indent=2))
+        os.replace(tmp_name, path)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def is_webhook_active(workspace: Workspace) -> Optional[str]:
+    """Return the webhook URL if URL is set, enabled flag is on, AND the URL
+    passes basic safety checks (``http(s)`` scheme + non-empty host).
+
+    Returns ``None`` otherwise — callers should short-circuit on ``None`` to
+    avoid instantiating the webhook service for nothing. The safety check is
+    intentionally redundant with the PUT-endpoint validation: it protects
+    against hand-edited config files and pre-migration data.
+    """
+    cfg = load_notifications_config(workspace)
+    url = (cfg["webhook_url"] or "").strip()
+    if not url or not cfg["webhook_enabled"]:
+        return None
+    if not _is_safe_webhook_url(url):
+        logger.warning(
+            "Refusing to dispatch webhook to unsafe URL: %s",
+            _redact_url_for_log(url),
+        )
+        return None
+    return url
+
+
+def _redact_url_for_log(url: str) -> str:
+    """Return a logging-safe representation of a webhook URL.
+
+    Slack/Discord/GitHub-style webhook URLs commonly embed secrets in:
+
+    * the path or query (Slack's ``T*/B*/...`` token, signed Zapier hooks)
+    * basic-auth credentials in ``user:password@host`` form
+
+    ``parsed.netloc`` preserves the userinfo segment, so we use
+    ``parsed.hostname`` (which strips auth and port) and re-attach the
+    port explicitly. Returns ``scheme://host[:port]`` when parsable, else
+    ``"<unparseable>"``.
+    """
+    from urllib.parse import urlparse
+
+    try:
+        parsed = urlparse(url)
+    except (TypeError, ValueError):
+        return "<unparseable>"
+    if not parsed.scheme or not parsed.hostname:
+        return "<unparseable>"
+    host = parsed.hostname
+    # ``parsed.port`` raises ValueError for malformed ports (e.g.
+    # ``file://host:abc/x``). Without this guard the "fail-safe" branch
+    # in ``is_webhook_active`` could end up raising instead of returning
+    # None, which would bubble through every dispatch site's broad
+    # ``except Exception``.
+    try:
+        port = parsed.port
+    except ValueError:
+        return "<unparseable>"
+    if port is not None:
+        host = f"{host}:{port}"
+    return f"{parsed.scheme}://{host}"

codeframe/core/planner.py

@@ -0,0 +1,437 @@
+"""Agent planning module for CodeFRAME v2.
+
+Transforms task context into an executable implementation plan.
+Uses LLM to analyze requirements and decompose into actionable steps.
+
+This module is headless - no FastAPI or HTTP dependencies.
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+from codeframe.core.context import TaskContext
+from codeframe.adapters.llm import LLMProvider, Purpose
+
+
+class StepType(str, Enum):
+    """Type of implementation step."""
+
+    FILE_CREATE = "file_create"  # Create a new file
+    FILE_EDIT = "file_edit"  # Edit an existing file
+    FILE_DELETE = "file_delete"  # Delete a file
+    SHELL_COMMAND = "shell_command"  # Run a shell command
+    VERIFICATION = "verification"  # Run tests/linting
+
+
+class Complexity(str, Enum):
+    """Estimated task complexity."""
+
+    LOW = "low"  # Simple change, < 50 lines
+    MEDIUM = "medium"  # Moderate change, 50-200 lines
+    HIGH = "high"  # Complex change, > 200 lines or architectural
+
+
+@dataclass
+class PlanStep:
+    """A single step in an implementation plan.
+
+    Attributes:
+        index: Step number (1-based)
+        type: Type of operation
+        description: What this step accomplishes
+        target: File path or command target
+        details: Additional details (e.g., what to change)
+        depends_on: Indices of steps this depends on
+    """
+
+    index: int
+    type: StepType
+    description: str
+    target: str
+    details: str = ""
+    depends_on: list[int] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "index": self.index,
+            "type": self.type.value,
+            "description": self.description,
+            "target": self.target,
+            "details": self.details,
+            "depends_on": self.depends_on,
+        }
+
+
+@dataclass
+class ImplementationPlan:
+    """Complete plan for implementing a task.
+
+    Attributes:
+        task_id: ID of the task this plan is for
+        summary: Brief summary of the approach
+        steps: Ordered list of implementation steps
+        files_to_create: New files that will be created
+        files_to_modify: Existing files that will be changed
+        estimated_complexity: Overall complexity estimate
+        considerations: Important notes or warnings
+    """
+
+    task_id: str
+    summary: str
+    steps: list[PlanStep]
+    files_to_create: list[str] = field(default_factory=list)
+    files_to_modify: list[str] = field(default_factory=list)
+    estimated_complexity: Complexity = Complexity.MEDIUM
+    considerations: list[str] = field(default_factory=list)
+
+    @property
+    def total_steps(self) -> int:
+        """Total number of steps."""
+        return len(self.steps)
+
+    @property
+    def file_operations(self) -> list[PlanStep]:
+        """Steps that involve file operations."""
+        return [
+            s for s in self.steps
+            if s.type in {StepType.FILE_CREATE, StepType.FILE_EDIT, StepType.FILE_DELETE}
+        ]
+
+    @property
+    def commands(self) -> list[PlanStep]:
+        """Steps that involve shell commands."""
+        return [s for s in self.steps if s.type == StepType.SHELL_COMMAND]
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for serialization."""
+        return {
+            "task_id": self.task_id,
+            "summary": self.summary,
+            "steps": [s.to_dict() for s in self.steps],
+            "files_to_create": self.files_to_create,
+            "files_to_modify": self.files_to_modify,
+            "estimated_complexity": self.estimated_complexity.value,
+            "considerations": self.considerations,
+        }
+
+    def to_markdown(self) -> str:
+        """Convert to markdown format for display."""
+        lines = [
+            "# Implementation Plan",
+            "",
+            f"**Task:** {self.task_id}",
+            f"**Complexity:** {self.estimated_complexity.value}",
+            "",
+            "## Summary",
+            f"{self.summary}",
+            "",
+        ]
+
+        if self.files_to_create:
+            lines.append("## Files to Create")
+            for f in self.files_to_create:
+                lines.append(f"- `{f}`")
+            lines.append("")
+
+        if self.files_to_modify:
+            lines.append("## Files to Modify")
+            for f in self.files_to_modify:
+                lines.append(f"- `{f}`")
+            lines.append("")
+
+        lines.append("## Steps")
+        for step in self.steps:
+            deps = f" (depends on: {step.depends_on})" if step.depends_on else ""
+            lines.append(f"{step.index}. **[{step.type.value}]** {step.description}{deps}")
+            lines.append(f"   - Target: `{step.target}`")
+            if step.details:
+                lines.append(f"   - Details: {step.details[:200]}")
+            lines.append("")
+
+        if self.considerations:
+            lines.append("## Considerations")
+            for c in self.considerations:
+                lines.append(f"- {c}")
+
+        return "\n".join(lines)
+
+
+PLANNING_SYSTEM_PROMPT = """You are an expert software implementation planner. Your job is to analyze a task and its context, then create a detailed implementation plan.
+
+## CRITICAL: Decision-Making Autonomy
+
+You are an agent - keep going until the task is completely resolved. Make tactical decisions independently:
+
+ALWAYS decide autonomously (without asking):
+- Choose between equivalent implementation approaches
+- Decide file organization and naming conventions
+- Select library versions (prefer latest stable)
+- Handle existing files (overwrite, merge, or extend as appropriate)
+- Choose test frameworks and configurations
+- Make code style decisions following existing patterns
+- Install dependencies using the project's package manager
+- Create directories and files as needed
+- Fix linting errors automatically
+
+ONLY flag as a blocker when:
+- Requirements genuinely conflict or are underspecified
+- Security policies need clarification
+- Business logic requires domain expertise the context doesn't provide
+- Access credentials are missing
+
+NEVER stop to ask about:
+- Tooling choices (use project preferences or best practices)
+- File handling (existing files should be updated, not blocked on)
+- Configuration details (use sensible defaults)
+- Minor implementation decisions
+- "Which approach should I use?" - pick the best one and proceed
+
+When multiple valid options exist, choose the simpler approach. Trust your expertise.
+
+## Output Format
+
+You must return a valid JSON object with this structure:
+{
+    "summary": "Brief description of the implementation approach",
+    "steps": [
+        {
+            "index": 1,
+            "type": "file_create|file_edit|file_delete|shell_command|verification",
+            "description": "What this step accomplishes",
+            "target": "see target rules below",
+            "details": "Specific changes or command arguments",
+            "depends_on": []
+        }
+    ],
+    "files_to_create": ["path/to/new/file.py"],
+    "files_to_modify": ["path/to/existing/file.py"],
+    "estimated_complexity": "low|medium|high",
+    "considerations": ["Important note or warning"]
+}
+
+TARGET RULES (critical - follow exactly):
+- file_create: target = file path to create (e.g., "src/utils.py")
+- file_edit: target = file path to edit (e.g., "main.py")
+- file_delete: target = file path to delete
+- shell_command: target = the actual command to run (e.g., "python main.py --help", "pytest tests/")
+- verification: target = the actual command to run (e.g., "python script.py --help", "pytest -v")
+  DO NOT put "shell_command" as the target. Put the actual command string.
+
+## Planning Guidelines
+
+1. Break work into small, focused steps (each step should do ONE thing)
+2. Order steps by dependency (later steps can depend on earlier ones)
+3. Include verification steps after significant changes
+4. Be specific about what files to modify and what changes to make
+5. Consider edge cases and potential issues
+6. Keep the plan achievable - don't over-engineer
+7. IMPORTANT: Before choosing file_create, verify the file does not already exist in the repository structure. If it exists, use file_edit instead. Never use file_create for files listed in the Repository Structure section.
+8. Run tests after implementation to verify correctness
+
+Return ONLY the JSON object, no additional text."""
+
+
+class Planner:
+    """Creates implementation plans from task context.
+
+    Uses LLM to analyze requirements and generate structured plans.
+    """
+
+    def __init__(self, llm_provider: LLMProvider):
+        """Initialize the planner.
+
+        Args:
+            llm_provider: LLM provider for generating plans
+        """
+        self.llm = llm_provider
+
+    def create_plan(self, context: TaskContext) -> ImplementationPlan:
+        """Create an implementation plan from task context.
+
+        Args:
+            context: Loaded task context
+
+        Returns:
+            ImplementationPlan with steps to execute
+
+        Raises:
+            ValueError: If plan generation fails
+        """
+        # Build the planning prompt
+        prompt = self._build_prompt(context)
+
+        # Call LLM with planning purpose (uses stronger model)
+        response = self.llm.complete(
+            messages=[{"role": "user", "content": prompt}],
+            purpose=Purpose.PLANNING,
+            system=PLANNING_SYSTEM_PROMPT,
+            max_tokens=4096,
+            temperature=0.0,
+        )
+
+        # Parse the response into a plan
+        return self._parse_plan(response.content, context.task.id)
+
+    def _build_prompt(self, context: TaskContext) -> str:
+        """Build the planning prompt from context.
+
+        Args:
+            context: Task context
+
+        Returns:
+            Formatted prompt string
+        """
+        sections = []
+
+        # Task information
+        sections.append("## Task to Implement")
+        sections.append(f"Title: {context.task.title}")
+        if context.task.description:
+            sections.append(f"Description: {context.task.description}")
+        sections.append("")
+
+        # Project preferences from AGENTS.md/CLAUDE.md
+        if context.preferences and context.preferences.has_preferences():
+            pref_section = context.preferences.to_prompt_section()
+            if pref_section:
+                sections.append(pref_section)
+                sections.append("")
+
+        # Tech stack configuration
+        if context.has_tech_stack:
+            sections.append("## Project Tech Stack")
+            sections.append(f"**Technology:** {context.tech_stack}")
+            sections.append("")
+            sections.append("Use appropriate commands and patterns for this technology stack.")
+            sections.append("When generating shell_command steps, use the correct tools for this stack.")
+            sections.append("")
+
+        # PRD if available
+        if context.prd:
+            sections.append("## Product Requirements")
+            # Limit PRD content to avoid overwhelming the plan
+            prd_content = context.prd.content[:5000]
+            sections.append(prd_content)
+            sections.append("")
+
+        # Previous clarifications
+        if context.answered_blockers:
+            sections.append("## Clarifications")
+            for b in context.answered_blockers:
+                sections.append(f"Q: {b.question}")
+                sections.append(f"A: {b.answer}")
+            sections.append("")
+
+        # Repository structure
+        if context.file_tree:
+            sections.append("## Repository Structure")
+            sections.append(f"Total files: {len(context.file_tree)}")
+            # Show top relevant files
+            for f in context.relevant_files[:20]:
+                sections.append(f"  - {f.path}")
+            sections.append("")
+
+        # Existing files warning for planner
+        if context.file_tree:
+            sections.append("## Existing Files Warning")
+            sections.append(
+                "The following files already exist in the workspace. "
+                "Use file_edit (NOT file_create) for these:"
+            )
+            for f_info in context.file_tree[:50]:
+                sections.append(f"  - {f_info.path}")
+            sections.append("")
+
+        # Loaded file contents
+        if context.loaded_files:
+            sections.append("## Relevant Source Files")
+            for f in context.loaded_files[:5]:  # Limit to top 5
+                sections.append(f"### {f.path}")
+                sections.append("```")
+                # Truncate large files in prompt
+                content = f.content[:3000]
+                sections.append(content)
+                if len(f.content) > 3000:
+                    sections.append("... (truncated)")
+                sections.append("```")
+                sections.append("")
+
+        sections.append("## Instructions")
+        sections.append("Create an implementation plan for this task.")
+        sections.append("Return a JSON object with the plan structure.")
+
+        return "\n".join(sections)
+
+    def _parse_plan(self, response_text: str, task_id: str) -> ImplementationPlan:
+        """Parse LLM response into an ImplementationPlan.
+
+        Args:
+            response_text: Raw LLM response
+            task_id: Task ID for the plan
+
+        Returns:
+            Parsed ImplementationPlan
+
+        Raises:
+            ValueError: If parsing fails
+        """
+        # Try to extract JSON from response
+        try:
+            # Find JSON object in response
+            json_match = re.search(r"\{[\s\S]*\}", response_text)
+            if not json_match:
+                raise ValueError("No JSON object found in response")
+
+            data = json.loads(json_match.group())
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse plan JSON: {e}")
+
+        # Build plan from parsed data
+        steps = []
+        for step_data in data.get("steps", []):
+            step_type = self._parse_step_type(step_data.get("type", "file_edit"))
+            steps.append(PlanStep(
+                index=step_data.get("index", len(steps) + 1),
+                type=step_type,
+                description=step_data.get("description", ""),
+                target=step_data.get("target", ""),
+                details=step_data.get("details", ""),
+                depends_on=step_data.get("depends_on", []),
+            ))
+
+        complexity = self._parse_complexity(
+            data.get("estimated_complexity", "medium")
+        )
+
+        return ImplementationPlan(
+            task_id=task_id,
+            summary=data.get("summary", "No summary provided"),
+            steps=steps,
+            files_to_create=data.get("files_to_create", []),
+            files_to_modify=data.get("files_to_modify", []),
+            estimated_complexity=complexity,
+            considerations=data.get("considerations", []),
+        )
+
+    def _parse_step_type(self, type_str: str) -> StepType:
+        """Parse step type string to enum."""
+        type_map = {
+            "file_create": StepType.FILE_CREATE,
+            "file_edit": StepType.FILE_EDIT,
+            "file_delete": StepType.FILE_DELETE,
+            "shell_command": StepType.SHELL_COMMAND,
+            "verification": StepType.VERIFICATION,
+        }
+        return type_map.get(type_str.lower(), StepType.FILE_EDIT)
+
+    def _parse_complexity(self, complexity_str: str) -> Complexity:
+        """Parse complexity string to enum."""
+        complexity_map = {
+            "low": Complexity.LOW,
+            "medium": Complexity.MEDIUM,
+            "high": Complexity.HIGH,
+        }
+        return complexity_map.get(complexity_str.lower(), Complexity.MEDIUM)