nexcoder 0.1.0__py3-none-any.whl

nex/memory/project.py

@@ -0,0 +1,158 @@
+"""Project memory manager for .nex/memory.md.
+
+The project memory file is a human-readable markdown document that stores
+project context (overview, tech stack, architecture, conventions). It is
+loaded into the system prompt on every agent invocation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from rich.console import Console
+
+from nex.exceptions import NexMemoryError
+
+console: Final[Console] = Console(stderr=True)
+
+_MEMORY_TEMPLATE: Final[str] = """\
+# Project Overview
+
+{project_name}
+
+## Tech Stack
+
+{tech_stack}
+
+## Architecture
+
+<!-- Describe the high-level architecture of this project. -->
+
+## Conventions
+
+<!-- List coding conventions, naming rules, and style preferences. -->
+
+## Notes
+
+<!-- Anything else the agent should remember between sessions. -->
+"""
+
+
+@dataclass
+class ProjectMemory:
+    """Manages persistent project memory stored in .nex/memory.md.
+
+    Attributes:
+        project_dir: Root directory of the project containing the .nex folder.
+    """
+
+    project_dir: Path
+
+    @property
+    def memory_path(self) -> Path:
+        """Return the absolute path to the memory file."""
+        return self.project_dir / ".nex" / "memory.md"
+
+    def exists(self) -> bool:
+        """Check whether the memory file exists on disk."""
+        return self.memory_path.is_file()
+
+    def load(self) -> str:
+        """Read and return the contents of memory.md.
+
+        Returns:
+            The full text of the memory file, or an empty string if not found.
+
+        Raises:
+            NexMemoryError: If the file exists but cannot be read.
+        """
+        if not self.exists():
+            return ""
+        try:
+            return self.memory_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise NexMemoryError(
+                f"Failed to read project memory at {self.memory_path}: {exc}"
+            ) from exc
+
+    def save(self, content: str) -> None:
+        """Write content to memory.md, creating parent dirs if needed.
+
+        Args:
+            content: The full markdown text to persist.
+
+        Raises:
+            NexMemoryError: If the file cannot be written.
+        """
+        try:
+            self.memory_path.parent.mkdir(parents=True, exist_ok=True)
+            self.memory_path.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            raise NexMemoryError(
+                f"Failed to save project memory at {self.memory_path}: {exc}"
+            ) from exc
+
+    def initialize(self, project_name: str, tech_stack: str = "") -> None:
+        """Create an initial memory.md from the built-in template.
+
+        Does not overwrite if already exists.
+
+        Args:
+            project_name: Human-readable project name.
+            tech_stack: Optional tech stack description.
+
+        Raises:
+            NexMemoryError: If the file cannot be written.
+        """
+        if self.exists():
+            console.print("[yellow]Memory file already exists — skipping.[/yellow]")
+            return
+
+        rendered = _MEMORY_TEMPLATE.format(
+            project_name=project_name,
+            tech_stack=tech_stack or "<!-- Add your tech stack here. -->",
+        )
+        self.save(rendered)
+        console.print(f"[green]Initialized project memory[/green] for [bold]{project_name}[/bold]")
+
+    def append(self, section: str, content: str) -> None:
+        """Append content under a given section heading.
+
+        If the section is not found, a new section is appended at EOF.
+
+        Args:
+            section: Section title without the # prefix (e.g. "Notes").
+            content: Markdown text to append.
+
+        Raises:
+            NexMemoryError: If the file cannot be read or written.
+        """
+        existing = self.load()
+        lines = existing.splitlines(keepends=True)
+
+        section_idx: int | None = None
+        for idx, line in enumerate(lines):
+            stripped = line.strip().lstrip("#").strip()
+            if stripped.lower() == section.lower():
+                section_idx = idx
+                break
+
+        if section_idx is not None:
+            insert_idx = len(lines)
+            for idx in range(section_idx + 1, len(lines)):
+                if lines[idx].lstrip().startswith("#"):
+                    insert_idx = idx
+                    break
+
+            while insert_idx > section_idx + 1 and lines[insert_idx - 1].strip() == "":
+                insert_idx -= 1
+
+            lines.insert(insert_idx, f"\n{content}\n")
+        else:
+            if existing and not existing.endswith("\n"):
+                lines.append("\n")
+            lines.append(f"\n## {section}\n\n{content}\n")
+
+        self.save("".join(lines))

nex/planner.py

@@ -0,0 +1,122 @@
+"""Task decomposition using Claude Haiku."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console
+
+from nex.api_client import AnthropicClient
+
+console = Console(stderr=True)
+
+_PLANNER_SYSTEM_PROMPT = """\
+You are a task planner for a coding agent. Given a task description and project context, \
+decompose the task into a list of concrete subtasks.
+
+Respond with a JSON array of objects, each with:
+- "description": what to do (be specific)
+- "file_paths": list of files likely to be touched
+- "priority": 1 = do first, 2 = do second, etc.
+
+Keep the list concise (3-7 subtasks). Order by dependency — things that must happen first \
+get lower priority numbers.
+
+Respond ONLY with the JSON array, no other text.
+"""
+
+
+@dataclass
+class Subtask:
+    """A single subtask from the planner.
+
+    Attributes:
+        description: What to do.
+        file_paths: Expected files to touch.
+        priority: 1 = highest priority.
+    """
+
+    description: str
+    file_paths: list[str]
+    priority: int
+
+
+class Planner:
+    """Decomposes a task into subtasks using Claude Haiku."""
+
+    def __init__(
+        self,
+        api_client: AnthropicClient,
+        haiku_model: str = "claude-haiku-4-5-20251001",
+    ) -> None:
+        """Initialize the planner.
+
+        Args:
+            api_client: The Anthropic API client.
+            haiku_model: Model to use for planning.
+        """
+        self._client = api_client
+        self._model = haiku_model
+
+    async def plan(self, task: str, project_context: str) -> list[Subtask]:
+        """Decompose a task into subtasks.
+
+        Args:
+            task: The user's task description.
+            project_context: Project memory and relevant context.
+
+        Returns:
+            List of Subtask instances sorted by priority.
+        """
+        messages: list[dict[str, Any]] = [
+            {
+                "role": "user",
+                "content": f"Project context:\n{project_context}\n\nTask: {task}",
+            }
+        ]
+
+        console.print("[dim]Planning task decomposition...[/dim]")
+
+        response = await self._client.send_message(
+            messages=messages,
+            system=_PLANNER_SYSTEM_PROMPT,
+            model=self._model,
+            max_tokens=2048,
+        )
+
+        # Extract text response
+        text = ""
+        for block in response.content:
+            if block.get("type") == "text":
+                text = block.get("text", "")
+                break
+
+        # Parse JSON
+        try:
+            # Handle markdown code fences
+            if "```" in text:
+                text = text.split("```")[1]
+                if text.startswith("json"):
+                    text = text[4:]
+
+            raw: list[dict[str, Any]] = json.loads(text.strip())
+            subtasks = [
+                Subtask(
+                    description=item.get("description", ""),
+                    file_paths=item.get("file_paths", []),
+                    priority=item.get("priority", 99),
+                )
+                for item in raw
+                if isinstance(item, dict)
+            ]
+            subtasks.sort(key=lambda s: s.priority)
+            console.print(f"[green]Planned[/green] {len(subtasks)} subtasks")
+            return subtasks
+
+        except (json.JSONDecodeError, KeyError, TypeError):
+            console.print(
+                "[yellow]Warning[/yellow]: Could not parse plan, proceeding without decomposition"
+            )
+            return [Subtask(description=task, file_paths=[], priority=1)]

nex/reviewer.py

@@ -0,0 +1,111 @@
+"""Independent code reviewer — separate API call, no access to the plan."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console
+
+from nex.api_client import AnthropicClient
+
+console = Console(stderr=True)
+
+_REVIEWER_SYSTEM_PROMPT = """\
+You are an independent code reviewer. You will be shown a git diff of changes made by a \
+coding agent. Review the diff for:
+
+1. Correctness: Does the code do what the task asks?
+2. Bugs: Any obvious logic errors, off-by-one errors, null/undefined issues?
+3. Security: Any injection vulnerabilities, hardcoded secrets, unsafe operations?
+4. Style: Does it match the project's existing conventions?
+5. Tests: Were tests added or updated for the changes?
+
+Respond with a JSON object:
+{
+    "approved": true/false,
+    "issues": ["list of problems found"],
+    "suggestions": ["list of improvement suggestions"]
+}
+
+Be concise. Only flag real issues, not style nitpicks. If the code looks good, approve it.
+Respond ONLY with the JSON object, no other text.
+"""
+
+
+@dataclass
+class ReviewResult:
+    """Result of an independent code review.
+
+    Attributes:
+        approved: Whether the changes pass review.
+        issues: List of problems found.
+        suggestions: List of improvement suggestions.
+    """
+
+    approved: bool
+    issues: list[str]
+    suggestions: list[str]
+
+
+class Reviewer:
+    """Independent code reviewer using a separate API call."""
+
+    def __init__(self, api_client: AnthropicClient) -> None:
+        """Initialize the reviewer.
+
+        Args:
+            api_client: The Anthropic API client.
+        """
+        self._client = api_client
+
+    async def review(self, diff: str, task: str) -> ReviewResult:
+        """Review a git diff against the original task.
+
+        Args:
+            diff: The git diff to review.
+            task: The original task description.
+
+        Returns:
+            Structured ReviewResult.
+        """
+        if not diff.strip():
+            return ReviewResult(approved=True, issues=[], suggestions=[])
+
+        messages: list[dict[str, Any]] = [
+            {
+                "role": "user",
+                "content": f"Original task: {task}\n\nGit diff:\n```\n{diff}\n```",
+            }
+        ]
+
+        console.print("[dim]Reviewing changes...[/dim]")
+
+        response = await self._client.send_message(
+            messages=messages,
+            system=_REVIEWER_SYSTEM_PROMPT,
+            max_tokens=2048,
+        )
+
+        text = ""
+        for block in response.content:
+            if block.get("type") == "text":
+                text = block.get("text", "")
+                break
+
+        try:
+            if "```" in text:
+                text = text.split("```")[1]
+                if text.startswith("json"):
+                    text = text[4:]
+
+            raw: dict[str, Any] = json.loads(text.strip())
+            return ReviewResult(
+                approved=bool(raw.get("approved", False)),
+                issues=raw.get("issues", []),
+                suggestions=raw.get("suggestions", []),
+            )
+        except (json.JSONDecodeError, KeyError, TypeError):
+            console.print("[yellow]Warning[/yellow]: Could not parse review, assuming approval")
+            return ReviewResult(approved=True, issues=[], suggestions=[])

nex/safety.py

@@ -0,0 +1,235 @@
+"""Safety layer — destructive operation detection and user approval.
+
+Detects rm -rf, DROP TABLE, force push, etc. and requires explicit user
+confirmation before execution. In dry-run mode, dangerous actions are
+always blocked.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.text import Text
+
+from nex.exceptions import SafetyError
+
+console = Console()
+
+_SENSITIVE_FILENAMES: frozenset[str] = frozenset(
+    {
+        ".env",
+        ".env.local",
+        ".env.production",
+        ".env.development",
+        "credentials.json",
+        "service-account.json",
+        "secrets.yaml",
+        "secrets.yml",
+        "id_rsa",
+        "id_ed25519",
+        ".npmrc",
+        ".pypirc",
+    }
+)
+
+
+@dataclass(frozen=True)
+class SafetyCheck:
+    """Result of a safety evaluation.
+
+    Attributes:
+        is_safe: True when the operation is allowed without prompting.
+        reason: Explanation when the check fails.
+        requires_approval: True when user must explicitly confirm.
+    """
+
+    is_safe: bool
+    reason: str | None = None
+    requires_approval: bool = False
+
+
+class SafetyLayer:
+    """Detects destructive operations and requires user approval."""
+
+    DESTRUCTIVE_PATTERNS: ClassVar[list[tuple[str, str]]] = [
+        (r"rm\s+-rf?\s+", "Recursive file deletion"),
+        (r"rm\s+-r\s+/", "Deleting from root"),
+        (r"DROP\s+TABLE", "SQL table drop"),
+        (r"DROP\s+DATABASE", "SQL database drop"),
+        (r"DELETE\s+FROM\s+\w+\s*;?\s*$", "SQL delete without WHERE"),
+        (r"TRUNCATE\s+TABLE", "SQL table truncation"),
+        (r"git\s+push\s+--force", "Force push"),
+        (r"git\s+push\s+-f\s+", "Force push"),
+        (r"git\s+clean\s+-[fd]", "Git clean"),
+        (r"git\s+reset\s+--hard", "Hard reset"),
+        (r"chmod\s+-R\s+777", "Insecure permissions"),
+        (r">\s*/dev/sd[a-z]", "Writing to disk device"),
+        (r"mkfs\.", "Formatting filesystem"),
+        (r"dd\s+if=", "Direct disk operation"),
+        (r"curl.*\|\s*bash", "Piping curl to bash"),
+        (r"wget.*\|\s*bash", "Piping wget to bash"),
+    ]
+
+    _compiled: ClassVar[list[tuple[re.Pattern[str], str]] | None] = None
+
+    def __init__(self, dry_run: bool = False) -> None:
+        """Initialize the safety layer.
+
+        Args:
+            dry_run: If True, always block dangerous actions without prompting.
+        """
+        self._dry_run = dry_run
+
+        if SafetyLayer._compiled is None:
+            SafetyLayer._compiled = [
+                (re.compile(pattern, re.IGNORECASE), label)
+                for pattern, label in self.DESTRUCTIVE_PATTERNS
+            ]
+
+    def check_command(self, command: str) -> SafetyCheck:
+        """Evaluate a shell command against destructive patterns.
+
+        Args:
+            command: The shell command to inspect.
+
+        Returns:
+            SafetyCheck indicating whether the command is safe.
+        """
+        assert self._compiled is not None
+        for pattern, label in self._compiled:
+            if pattern.search(command):
+                return SafetyCheck(
+                    is_safe=False,
+                    reason=f"Destructive operation detected: {label}",
+                    requires_approval=True,
+                )
+        return SafetyCheck(is_safe=True)
+
+    def check_file_write(self, path: str, project_dir: Path) -> SafetyCheck:
+        """Evaluate whether writing to path is allowed.
+
+        Args:
+            path: The file path to write to.
+            project_dir: The project root directory.
+
+        Returns:
+            SafetyCheck with the evaluation result.
+        """
+        traversal = self.check_path_traversal(path, project_dir)
+        if not traversal.is_safe:
+            return traversal
+
+        filename = Path(path).name.lower()
+        if filename in _SENSITIVE_FILENAMES:
+            return SafetyCheck(
+                is_safe=False,
+                reason=f"Writing to sensitive file '{filename}' which may contain secrets.",
+                requires_approval=True,
+            )
+
+        suffix = Path(path).suffix.lower()
+        if suffix in {".pem", ".key", ".p12", ".pfx"}:
+            return SafetyCheck(
+                is_safe=False,
+                reason=f"Writing to cryptographic key file ('{suffix}').",
+                requires_approval=True,
+            )
+
+        return SafetyCheck(is_safe=True)
+
+    def check_path_traversal(self, path: str, project_dir: Path) -> SafetyCheck:
+        """Detect path-traversal attempts escaping the project root.
+
+        Args:
+            path: Target file path.
+            project_dir: Project root directory.
+
+        Returns:
+            SafetyCheck — unsafe if resolved path is outside project.
+        """
+        try:
+            resolved = (project_dir / path).resolve()
+            project_resolved = project_dir.resolve()
+            if not str(resolved).startswith(str(project_resolved)):
+                return SafetyCheck(
+                    is_safe=False,
+                    reason=f"Path traversal: '{path}' resolves outside project directory.",
+                    requires_approval=False,
+                )
+        except (OSError, ValueError) as exc:
+            return SafetyCheck(is_safe=False, reason=f"Invalid path '{path}': {exc}")
+
+        return SafetyCheck(is_safe=True)
+
+    async def request_approval(self, action: str, reason: str) -> bool:
+        """Prompt user for explicit approval of a dangerous action.
+
+        In dry-run mode, always returns False.
+
+        Args:
+            action: Description of the action.
+            reason: Why it was flagged.
+
+        Returns:
+            True if user approves, False otherwise.
+        """
+        if self._dry_run:
+            console.print(
+                Panel(
+                    Text.assemble(
+                        ("BLOCKED (dry-run): ", "bold red"),
+                        (action, "white"),
+                        ("\nReason: ", "bold yellow"),
+                        (reason, "yellow"),
+                    ),
+                    title="[bold red]Safety Layer[/bold red]",
+                    border_style="red",
+                )
+            )
+            return False
+
+        console.print(
+            Panel(
+                Text.assemble(
+                    ("Action: ", "bold white"),
+                    (action, "white"),
+                    ("\nReason: ", "bold yellow"),
+                    (reason, "yellow"),
+                ),
+                title="[bold red]Dangerous Operation[/bold red]",
+                border_style="red",
+            )
+        )
+
+        answer = Prompt.ask("[bold]Allow?[/bold]", choices=["y", "n"], default="n")
+        return answer.lower() == "y"
+
+    async def guard_command(self, command: str) -> bool:
+        """Check command and prompt for approval if needed.
+
+        Args:
+            command: Shell command to evaluate.
+
+        Returns:
+            True if command may proceed.
+
+        Raises:
+            SafetyError: If command is blocked.
+        """
+        check = self.check_command(command)
+        if check.is_safe:
+            return True
+
+        if not check.requires_approval:
+            raise SafetyError(check.reason or "Operation blocked")
+
+        approved = await self.request_approval(command, check.reason or "Destructive operation")
+        if not approved:
+            raise SafetyError(f"User denied: {check.reason}")
+        return True