ripperdoc 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

ripperdoc/core/skills.py

@@ -0,0 +1,295 @@
+"""Agent Skill loading helpers for Ripperdoc.
+
+Skills are small capability bundles defined by SKILL.md files that live under
+`~/.ripperdoc/skills` or `.ripperdoc/skills` in a project. Only the skill
+metadata (name + description) should be added to the system prompt up front;
+the full content is loaded on demand via the Skill tool. Optional frontmatter
+fields include:
+- allowed-tools: Comma-separated list of tools that are allowed/preferred.
+- model: Model pointer hint for this skill.
+- max-thinking-tokens: Reasoning budget hint for this skill.
+- disable-model-invocation: If true, block the Skill tool from loading this
+  skill.
+- type: Skill kind (defaults to "prompt").
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import yaml
+
+from ripperdoc.utils.coerce import parse_boolish, parse_optional_int
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+SKILL_DIR_NAME = "skills"
+SKILL_FILE_NAME = "SKILL.md"
+_SKILL_NAME_RE = re.compile(r"^[a-z0-9-]{1,64}$")
+
+
+class SkillLocation(str, Enum):
+    """Where a skill definition is sourced from."""
+
+    USER = "user"
+    PROJECT = "project"
+    OTHER = "other"
+
+
+@dataclass
+class SkillDefinition:
+    """Parsed representation of a skill."""
+
+    name: str
+    description: str
+    content: str
+    path: Path
+    base_dir: Path
+    location: SkillLocation
+    allowed_tools: List[str]
+    model: Optional[str] = None
+    max_thinking_tokens: Optional[int] = None
+    skill_type: str = "prompt"
+    disable_model_invocation: bool = False
+
+
+@dataclass
+class SkillLoadError:
+    """Error encountered while loading a skill file."""
+
+    path: Path
+    reason: str
+
+
+@dataclass
+class SkillLoadResult:
+    """Aggregated result of loading skills."""
+
+    skills: List[SkillDefinition]
+    errors: List[SkillLoadError]
+
+
+def _split_frontmatter(raw_text: str) -> Tuple[Dict[str, Any], str]:
+    """Extract YAML frontmatter and body content from a markdown file."""
+    lines = raw_text.splitlines()
+    if len(lines) >= 3 and lines[0].strip() == "---":
+        for idx in range(1, len(lines)):
+            if lines[idx].strip() == "---":
+                frontmatter_text = "\n".join(lines[1:idx])
+                body = "\n".join(lines[idx + 1 :])
+                try:
+                    frontmatter = yaml.safe_load(frontmatter_text) or {}
+                except (yaml.YAMLError, ValueError, TypeError) as exc:  # pragma: no cover - defensive
+                    logger.warning(
+                        "[skills] Invalid frontmatter in SKILL.md: %s: %s",
+                        type(exc).__name__, exc,
+                    )
+                    return {"__error__": f"Invalid frontmatter: {exc}"}, body
+                return frontmatter, body
+    return {}, raw_text
+
+
+def _normalize_allowed_tools(value: object) -> List[str]:
+    """Normalize allowed-tools values to a clean list of tool names."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [item.strip() for item in value.split(",") if item.strip()]
+    if isinstance(value, Iterable):
+        tools: List[str] = []
+        for item in value:
+            if isinstance(item, str) and item.strip():
+                tools.append(item.strip())
+        return tools
+    return []
+
+
+def _load_skill_file(
+    path: Path, location: SkillLocation
+) -> Tuple[Optional[SkillDefinition], Optional[SkillLoadError]]:
+    """Parse a single SKILL.md file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, IOError, UnicodeDecodeError) as exc:
+        logger.warning(
+            "[skills] Failed to read skill file: %s: %s",
+            type(exc).__name__, exc,
+            extra={"path": str(path)},
+        )
+        return None, SkillLoadError(path=path, reason=f"Failed to read file: {exc}")
+
+    frontmatter, body = _split_frontmatter(text)
+    if "__error__" in frontmatter:
+        return None, SkillLoadError(path=path, reason=str(frontmatter["__error__"]))
+
+    raw_name = frontmatter.get("name")
+    raw_description = frontmatter.get("description")
+    if not isinstance(raw_name, str) or not raw_name.strip():
+        return None, SkillLoadError(path=path, reason='Missing required "name" field')
+    if not _SKILL_NAME_RE.match(raw_name.strip()):
+        return None, SkillLoadError(
+            path=path,
+            reason='Invalid "name" format. Use lowercase letters, numbers, and hyphens only (max 64 chars).',
+        )
+    if not isinstance(raw_description, str) or not raw_description.strip():
+        return None, SkillLoadError(path=path, reason='Missing required "description" field')
+
+    allowed_tools = _normalize_allowed_tools(
+        frontmatter.get("allowed-tools") or frontmatter.get("allowed_tools")
+    )
+    model_value = frontmatter.get("model")
+    model = model_value if isinstance(model_value, str) and model_value.strip() else None
+    max_thinking_tokens = parse_optional_int(
+        frontmatter.get("max-thinking-tokens") or frontmatter.get("max_thinking_tokens")
+    )
+    raw_type = (
+        frontmatter.get("type")
+        or frontmatter.get("skill-type")
+        or frontmatter.get("skill_type")
+        or "prompt"
+    )
+    skill_type = str(raw_type).strip().lower() if isinstance(raw_type, str) else "prompt"
+    disable_model_invocation = parse_boolish(
+        frontmatter.get("disable-model-invocation") or frontmatter.get("disable_model_invocation")
+    )
+
+    skill = SkillDefinition(
+        name=raw_name.strip(),
+        description=raw_description.strip(),
+        content=body.strip(),
+        path=path,
+        base_dir=path.parent,
+        location=location,
+        allowed_tools=allowed_tools,
+        model=model,
+        max_thinking_tokens=max_thinking_tokens,
+        skill_type=skill_type or "prompt",
+        disable_model_invocation=disable_model_invocation,
+    )
+    return skill, None
+
+
+def _load_skill_dir(
+    path: Path, location: SkillLocation
+) -> Tuple[List[SkillDefinition], List[SkillLoadError]]:
+    """Load skills from a directory that either contains SKILL.md or subdirectories."""
+    skills: List[SkillDefinition] = []
+    errors: List[SkillLoadError] = []
+    if not path.exists() or not path.is_dir():
+        return skills, errors
+
+    single_skill = path / SKILL_FILE_NAME
+    if single_skill.exists():
+        skill, error = _load_skill_file(single_skill, location)
+        if skill:
+            skills.append(skill)
+        elif error:
+            errors.append(error)
+        return skills, errors
+
+    for entry in sorted(path.iterdir()):
+        try:
+            if not entry.is_dir() and not entry.is_symlink():
+                continue
+        except OSError:
+            continue
+
+        candidate = entry / SKILL_FILE_NAME
+        if not candidate.exists():
+            continue
+        skill, error = _load_skill_file(candidate, location)
+        if skill:
+            skills.append(skill)
+        elif error:
+            errors.append(error)
+    return skills, errors
+
+
+def skill_directories(
+    project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> List[Tuple[Path, SkillLocation]]:
+    """Return the standard skill directories for user and project scopes."""
+    home_dir = (home or Path.home()).expanduser()
+    project_dir = (project_path or Path.cwd()).resolve()
+    return [
+        (home_dir / ".ripperdoc" / SKILL_DIR_NAME, SkillLocation.USER),
+        (project_dir / ".ripperdoc" / SKILL_DIR_NAME, SkillLocation.PROJECT),
+    ]
+
+
+def load_all_skills(
+    project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> SkillLoadResult:
+    """Load skills from user and project directories.
+
+    Project skills override user skills with the same name.
+    """
+    skills_by_name: Dict[str, SkillDefinition] = {}
+    errors: List[SkillLoadError] = []
+
+    # Load user first so project overrides take precedence.
+    for directory, location in skill_directories(project_path=project_path, home=home):
+        loaded, dir_errors = _load_skill_dir(directory, location)
+        errors.extend(dir_errors)
+        for skill in loaded:
+            if skill.name in skills_by_name:
+                logger.debug(
+                    "[skills] Overriding skill",
+                    extra={
+                        "skill_name": skill.name,
+                        "previous_location": str(skills_by_name[skill.name].location),
+                        "new_location": str(location),
+                    },
+                )
+            skills_by_name[skill.name] = skill
+    return SkillLoadResult(skills=list(skills_by_name.values()), errors=errors)
+
+
+def find_skill(
+    skill_name: str, project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> Optional[SkillDefinition]:
+    """Find a skill by name (case-sensitive match)."""
+    normalized = skill_name.strip().lstrip("/")
+    if not normalized:
+        return None
+    result = load_all_skills(project_path=project_path, home=home)
+    return next((skill for skill in result.skills if skill.name == normalized), None)
+
+
+def build_skill_summary(skills: Sequence[SkillDefinition]) -> str:
+    """Render a concise instruction block listing available skills."""
+    if not skills:
+        return (
+            "# Skills\n"
+            "No skills detected. Add SKILL.md under ~/.ripperdoc/skills or ./.ripperdoc/skills "
+            "to extend capabilities, then load them with the Skill tool when relevant."
+        )
+    lines = [
+        "# Skills",
+        "Skills extend your capabilities with reusable instructions stored in SKILL.md files.",
+        'Call the Skill tool with {"skill": "<name>"} to load a skill when it matches the user request.',
+        "Available skills:",
+    ]
+    for skill in skills:
+        location = f" ({skill.location.value})" if skill.location else ""
+        lines.append(f"- {skill.name}{location}: {skill.description}")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "SkillDefinition",
+    "SkillLoadError",
+    "SkillLoadResult",
+    "SkillLocation",
+    "SKILL_DIR_NAME",
+    "SKILL_FILE_NAME",
+    "load_all_skills",
+    "find_skill",
+    "build_skill_summary",
+    "skill_directories",
+]

ripperdoc/core/system_prompt.py

@@ -32,7 +32,7 @@ DEFENSIVE_SECURITY_GUIDELINE = (
     "IMPORTANT: Assist with defensive security tasks only. Refuse to create, modify, or improve code that may be used maliciously. "
     "Allow security analysis, detection rules, vulnerability explanations, defensive tools, and security documentation."
 )
-FEEDBACK_URL = "https://github.com/jstzwj/Ripperdoc/issues"
+FEEDBACK_URL = "https://github.com/quantmew/Ripperdoc/issues"
 
 
 def _detect_git_repo(cwd: Path) -> bool:
@@ -46,8 +46,12 @@ def _detect_git_repo(cwd: Path) -> bool:
             check=False,
         )
         return result.returncode == 0 and result.stdout.strip().lower() == "true"
-    except Exception:
-        logger.exception("[system_prompt] Failed to detect git repository", extra={"cwd": str(cwd)})
+    except (OSError, subprocess.SubprocessError) as exc:
+        logger.warning(
+            "[system_prompt] Failed to detect git repository: %s: %s",
+            type(exc).__name__, exc,
+            extra={"cwd": str(cwd)},
+        )
         return False
 
 
@@ -220,7 +224,7 @@ def build_system_prompt(
         - NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
 
         # Professional objectivity
-        Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if Claude honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
+        Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if you honestly apply the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
 
         # Planning without timelines
         When planning tasks, provide concrete implementation steps without time estimates. Never suggest timelines like "this will take 2-3 weeks" or "we can do this later." Focus on what needs to be done, not when. Break work into actionable steps and let users decide scheduling.
@@ -386,8 +390,11 @@ def build_system_prompt(
 
                     Provide detailed prompts so the agent can work autonomously and return a concise report."""
                 ).strip()
-        except Exception as exc:
-            logger.exception("Failed to load agent definitions", extra={"error": str(exc)})
+        except (OSError, ValueError, RuntimeError) as exc:
+            logger.warning(
+                "Failed to load agent definitions: %s: %s",
+                type(exc).__name__, exc,
+            )
             agent_section = (
                 "# Subagents\nTask tool available, but agent definitions could not be loaded."
             )
@@ -413,7 +420,6 @@ def build_system_prompt(
         tool_usage_section,
         agent_section,
         build_environment_prompt(),
-        DEFENSIVE_SECURITY_GUIDELINE,
         always_use_todo,
         build_commit_workflow_prompt(shell_tool_name, todo_tool_name, TASK_TOOL_NAME),
         code_references,

ripperdoc/core/tool.py

@@ -208,9 +208,10 @@ async def build_tool_description(
 
         if parts:
             return f"{description_text}\n\nInput examples:\n" + "\n\n".join(parts)
-    except Exception:
-        logger.exception(
-            "[tool] Failed to build input example section",
+    except (TypeError, ValueError, AttributeError, KeyError) as exc:
+        logger.warning(
+            "[tool] Failed to build input example section: %s: %s",
+            type(exc).__name__, exc,
             extra={"tool": getattr(tool, "name", None)},
         )
         return description_text
@@ -227,9 +228,10 @@ def tool_input_examples(tool: Tool[Any, Any], limit: int = 5) -> List[Dict[str,
     for example in examples[:limit]:
         try:
             results.append(example.example)
-        except Exception:
-            logger.exception(
-                "[tool] Failed to format tool input example",
+        except (TypeError, ValueError, AttributeError) as exc:
+            logger.warning(
+                "[tool] Failed to format tool input example: %s: %s",
+                type(exc).__name__, exc,
                 extra={"tool": getattr(tool, "name", None)},
             )
             continue

ripperdoc/sdk/client.py

@@ -27,6 +27,7 @@ from ripperdoc.core.default_tools import get_default_tools
 from ripperdoc.core.query import QueryContext, query as _core_query
 from ripperdoc.core.permissions import PermissionResult
 from ripperdoc.core.system_prompt import build_system_prompt
+from ripperdoc.core.skills import build_skill_summary, load_all_skills
 from ripperdoc.core.tool import Tool
 from ripperdoc.tools.task_tool import TaskTool
 from ripperdoc.tools.mcp_tools import load_dynamic_mcp_tools_async, merge_tools_with_dynamic
@@ -42,6 +43,7 @@ from ripperdoc.utils.mcp import (
     load_mcp_servers_async,
     shutdown_mcp_runtime,
 )
+from ripperdoc.utils.log import get_logger
 
 MessageType = Union[UserMessage, AssistantMessage, ProgressMessage]
 PermissionChecker = Callable[
@@ -67,6 +69,8 @@ QueryRunner = Callable[
 
 _END_OF_STREAM = object()
 
+logger = get_logger()
+
 
 def _coerce_to_path(path: Union[str, Path]) -> Path:
     return path if isinstance(path, Path) else Path(path)
@@ -281,12 +285,21 @@ class RipperdocClient:
             return self.options.system_prompt
 
         instructions: List[str] = []
+        project_path = _coerce_to_path(self.options.cwd or Path.cwd())
+        skill_result = load_all_skills(project_path)
+        for err in skill_result.errors:
+            logger.warning(
+                "[skills] Failed to load skill",
+                extra={"path": str(err.path), "reason": err.reason},
+            )
+        skill_instructions = build_skill_summary(skill_result.skills)
+        if skill_instructions:
+            instructions.append(skill_instructions)
         instructions.extend(self.options.extra_instructions())
         memory = build_memory_instructions()
         if memory:
             instructions.append(memory)
 
-        project_path = _coerce_to_path(self.options.cwd or Path.cwd())
         dynamic_tools = await load_dynamic_mcp_tools_async(project_path)
         if dynamic_tools:
             self._tools = merge_tools_with_dynamic(self._tools, dynamic_tools)

ripperdoc/tools/ask_user_question_tool.py

@@ -117,9 +117,7 @@ def format_option_display(option: OptionInput, index: int) -> str:
     return f"  {index}. {option.label}{desc}"
 
 
-def format_question_prompt(
-    question: QuestionInput, question_num: int, total: int
-) -> str:
+def format_question_prompt(question: QuestionInput, question_num: int, total: int) -> str:
     """Format a question for terminal display."""
     header = truncate_header(question.header)
     lines = [
@@ -137,9 +135,7 @@ def format_question_prompt(
 
     if question.multiSelect:
         lines.append("")
-        lines.append(
-            "  Enter numbers separated by commas (e.g., 1,3), or 'o' for other: "
-        )
+        lines.append("  Enter numbers separated by commas (e.g., 1,3), or 'o' for other: ")
     else:
         lines.append("")
         lines.append("  Enter choice (1-{}) or 'o' for other: ".format(len(question.options) + 1))
@@ -204,9 +200,7 @@ async def prompt_user_for_answer(
                             f"  Invalid selection. Enter numbers from 1 to {len(question.options) + 1}."
                         )
                     except ValueError:
-                        print(
-                            "  Invalid input. Enter numbers separated by commas."
-                        )
+                        print("  Invalid input. Enter numbers separated by commas.")
                 else:
                     # Single selection
                     try:
@@ -231,8 +225,11 @@ async def prompt_user_for_answer(
             return None
         except EOFError:
             return None
-        except Exception as e:
-            logger.exception("[ask_user_question_tool] Error during prompt", extra={"error": str(e)})
+        except (OSError, RuntimeError, ValueError) as e:
+            logger.warning(
+                "[ask_user_question_tool] Error during prompt: %s: %s",
+                type(e).__name__, e,
+            )
             return None
 
     return await loop.run_in_executor(None, _prompt)
@@ -291,7 +288,8 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
         return True
 
     def needs_permissions(
-        self, input_data: Optional[AskUserQuestionToolInput] = None  # noqa: ARG002
+        self,
+        input_data: Optional[AskUserQuestionToolInput] = None,  # noqa: ARG002
     ) -> bool:
         return False
 
@@ -305,9 +303,7 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
 
         for question in input_data.questions:
             if question.question in seen_questions:
-                return ValidationResult(
-                    result=False, message="Question texts must be unique"
-                )
+                return ValidationResult(result=False, message="Question texts must be unique")
             seen_questions.add(question.question)
 
             option_labels: set[str] = set()
@@ -338,7 +334,9 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
         )
 
     def render_tool_use_message(
-        self, input_data: AskUserQuestionToolInput, verbose: bool = False  # noqa: ARG002
+        self,
+        input_data: AskUserQuestionToolInput,
+        verbose: bool = False,  # noqa: ARG002
     ) -> str:
         """Render the tool use message for display."""
         question_count = len(input_data.questions)
@@ -359,7 +357,7 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
         if context.pause_ui:
             try:
                 context.pause_ui()
-            except Exception:
+            except (RuntimeError, ValueError, OSError):
                 logger.debug("[ask_user_question_tool] Failed to pause UI")
 
         try:
@@ -409,10 +407,10 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
                 result_for_assistant=self.render_result_for_assistant(output),
             )
 
-        except Exception as exc:
-            logger.exception(
-                "[ask_user_question_tool] Error collecting answers",
-                extra={"error": str(exc)},
+        except (OSError, RuntimeError, ValueError, KeyError) as exc:
+            logger.warning(
+                "[ask_user_question_tool] Error collecting answers: %s: %s",
+                type(exc).__name__, exc,
             )
             output = AskUserQuestionToolOutput(
                 questions=questions,
@@ -429,5 +427,5 @@ class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutp
             if context.resume_ui:
                 try:
                     context.resume_ui()
-                except Exception:
+                except (RuntimeError, ValueError, OSError):
                     logger.debug("[ask_user_question_tool] Failed to resume UI")

ripperdoc/tools/background_shell.py

@@ -47,11 +47,13 @@ _background_loop: Optional[asyncio.AbstractEventLoop] = None
 _background_thread: Optional[threading.Thread] = None
 _loop_lock = threading.Lock()
 _shutdown_registered = False
+
+
 def _safe_log_exception(message: str, **extra: Any) -> None:
     """Log an exception but never let logging failures bubble up."""
     try:
         logger.exception(message, extra=extra)
-    except Exception:
+    except (OSError, RuntimeError, ValueError):
         pass
 
 
@@ -112,7 +114,9 @@ async def _pump_stream(stream: asyncio.StreamReader, sink: List[str]) -> None:
             text = chunk.decode("utf-8", errors="replace")
             with _tasks_lock:
                 sink.append(text)
-    except Exception as exc:
+    except (OSError, RuntimeError, asyncio.CancelledError) as exc:
+        if isinstance(exc, asyncio.CancelledError):
+            return  # Normal cancellation
         # Best effort; ignore stream read errors to avoid leaking tasks.
         logger.debug(
             f"Stream pump error for background task: {exc}",
@@ -155,9 +159,10 @@ async def _monitor_task(task: BackgroundTask) -> None:
             task.exit_code = -1
     except asyncio.CancelledError:
         return
-    except Exception:
-        logger.exception(
-            "Error monitoring background task",
+    except (OSError, RuntimeError, ProcessLookupError) as exc:
+        logger.warning(
+            "Error monitoring background task: %s: %s",
+            type(exc).__name__, exc,
             extra={"task_id": task.id, "command": task.command},
         )
         with _tasks_lock:
@@ -327,12 +332,13 @@ async def _shutdown_loop(loop: asyncio.AbstractEventLoop) -> None:
                 with contextlib.suppress(asyncio.TimeoutError, ProcessLookupError):
                     await asyncio.wait_for(task.process.wait(), timeout=0.5)
             task.exit_code = task.process.returncode or -1
-        except Exception:
-            _safe_log_exception(
-                "Error shutting down background task",
-                task_id=task.id,
-                command=task.command,
-            )
+        except (OSError, RuntimeError, asyncio.CancelledError) as exc:
+            if not isinstance(exc, asyncio.CancelledError):
+                _safe_log_exception(
+                    "Error shutting down background task",
+                    task_id=task.id,
+                    command=task.command,
+                )
         finally:
             await _finalize_reader_tasks(task.reader_tasks)
             task.done_event.set()
@@ -366,11 +372,11 @@ def shutdown_background_shell() -> None:
             try:
                 fut = asyncio.run_coroutine_threadsafe(_shutdown_loop(loop), loop)
                 fut.result(timeout=3)
-            except Exception:
+            except (RuntimeError, TimeoutError, concurrent.futures.TimeoutError):
                 logger.debug("Failed to cleanly shutdown background loop", exc_info=True)
             try:
                 loop.call_soon_threadsafe(loop.stop)
-            except Exception:
+            except (RuntimeError, OSError):
                 logger.debug("Failed to stop background loop", exc_info=True)
         else:
             loop.run_until_complete(_shutdown_loop(loop))