dulus 0.2.0__py3-none-any.whl

skill/__init__.py

@@ -0,0 +1,14 @@
+"""skill package — reusable prompt templates (skills)."""
+from .loader import (  # noqa: F401
+    SkillDef,
+    load_skills,
+    find_skill,
+    substitute_arguments,
+    register_builtin_skill,
+    _parse_skill_file,
+    _parse_list_field,
+)
+from .executor import execute_skill  # noqa: F401
+
+# Importing builtin registers the built-in skills
+from . import builtin as _builtin  # noqa: F401

skill/builtin.py

@@ -0,0 +1,100 @@
+"""Built-in skills that ship with dulus."""
+from __future__ import annotations
+
+from .loader import SkillDef, register_builtin_skill
+
+# ── /commit ────────────────────────────────────────────────────────────────
+
+_COMMIT_PROMPT = """\
+Review the current git state and create a well-structured commit.
+
+## Steps
+
+1. Run `git status` and `git diff --staged` to see what is staged.
+   - If nothing is staged, run `git diff` to see unstaged changes, then stage relevant files.
+2. Analyze the changes:
+   - Summarize the nature of the change (feature, bug fix, refactor, docs, etc.)
+   - Write a concise commit title (≤72 chars) focusing on *why*, not just *what*.
+   - If multiple logical changes exist, ask the user whether to split them.
+3. Create the commit:
+   ```
+   git commit -m "<title>"
+   ```
+   If additional context is needed, add a body separated by a blank line.
+4. Print the commit hash and summary when done.
+
+**Rules:**
+- Never use `--no-verify`.
+- Never commit files that likely contain secrets (.env, credentials, keys).
+- Prefer imperative mood in the title: "Add X", "Fix Y", "Refactor Z".
+
+User context: $ARGUMENTS
+"""
+
+_REVIEW_PROMPT = """\
+Review the code or pull request and provide structured feedback.
+
+## Steps
+
+1. Understand the scope:
+   - If a PR number or URL is given in $ARGUMENTS, use `gh pr view $ARGUMENTS --patch` to get the diff.
+   - Otherwise, use `git diff main...HEAD` (or `git diff HEAD~1`) for local changes.
+2. Analyze the diff:
+   - Correctness: Are there bugs, edge cases, or logic errors?
+   - Security: Injection, auth issues, exposed secrets, unsafe operations?
+   - Performance: N+1 queries, unnecessary allocations, blocking calls?
+   - Style: Does it follow existing conventions in the codebase?
+   - Tests: Are new behaviors tested? Do existing tests cover the change?
+3. Write a structured review:
+   ```
+   ## Summary
+   One-line overview of what the change does.
+
+   ## Issues
+   - [CRITICAL/MAJOR/MINOR] Description and location
+
+   ## Suggestions
+   - Nice-to-have improvements
+
+   ## Verdict
+   APPROVE / REQUEST CHANGES / COMMENT
+   ```
+4. If changes are needed, list specific file:line references.
+
+User context: $ARGUMENTS
+"""
+
+
+def _register_builtins() -> None:
+    register_builtin_skill(SkillDef(
+        name="commit",
+        description="Review staged changes and create a well-structured git commit",
+        triggers=["/commit"],
+        tools=["Bash", "Read"],
+        prompt=_COMMIT_PROMPT,
+        file_path="<builtin>",
+        when_to_use="Use when the user wants to commit changes. Triggers: '/commit', 'commit changes', 'make a commit'.",
+        argument_hint="[optional context]",
+        arguments=[],
+        user_invocable=True,
+        context="inline",
+        source="builtin",
+    ))
+
+    register_builtin_skill(SkillDef(
+        name="review",
+        description="Review code changes or a pull request and provide structured feedback",
+        triggers=["/review", "/review-pr"],
+        tools=["Bash", "Read", "Grep"],
+        prompt=_REVIEW_PROMPT,
+        file_path="<builtin>",
+        when_to_use="Use when the user wants a code review. Triggers: '/review', '/review-pr', 'review this PR'.",
+        argument_hint="[PR number or URL]",
+        arguments=["pr"],
+        user_invocable=True,
+        context="inline",
+        source="builtin",
+    ))
+
+
+_register_builtins()

skill/clawhub.py

@@ -0,0 +1,270 @@
+"""ClawHub + local Anthropic skill importer for Dulus.
+
+Sources:
+  - LOCAL      : ~/.claude/plugins/marketplaces/claude-plugins-official/  (Anthropic, on-disk)
+  - AWESOME    : ~/.claude/plugins/marketplaces/alireza-claude-skills/    (alirezarezvani/claude-skills, ~235 skills across 9 domains)
+  - CLAWHUB    : https://clawhub.ai  (community, 52k+ skills, via API)
+"""
+from __future__ import annotations
+
+import json
+import re
+import urllib.request
+import urllib.parse
+from pathlib import Path
+from typing import Optional
+
+# ── Paths ──────────────────────────────────────────────────────────────────
+
+DULUS_SKILLS_DIR = Path.home() / ".dulus" / "skills"
+ANTHROPIC_PLUGINS = (
+    Path.home() / ".claude" / "plugins" / "marketplaces" / "claude-plugins-official"
+)
+AWESOME_SKILLS = (
+    Path.home() / ".claude" / "plugins" / "marketplaces" / "alireza-claude-skills"
+)
+
+# ── ClawHub API (Convex HTTP) ──────────────────────────────────────────────
+# TODO: reverse-engineer exact endpoint from clawhub.ai/openclaw/clawhub repo
+CLAWHUB_API_BASE = "https://clawhub.ai"          # placeholder
+CLAWHUB_SEARCH   = f"{CLAWHUB_API_BASE}/api/search"  # placeholder
+CLAWHUB_GET      = f"{CLAWHUB_API_BASE}/api/skill"   # placeholder — /api/skill/<slug>
+
+
+# ── LOCAL (Anthropic marketplace on disk) ─────────────────────────────────
+
+def list_local(query: Optional[str] = None) -> list[dict]:
+    """Return all SKILL.md entries from local marketplaces (Anthropic + Awesome Skills)."""
+    skills = []
+    q = query.lower() if query else None
+
+    # Anthropic: .../plugins/<plugin>/skills/<skill>/SKILL.md
+    plugins_dir = ANTHROPIC_PLUGINS / "plugins"
+    external_dir = ANTHROPIC_PLUGINS / "external_plugins"
+    for base, prefix in [(plugins_dir, ""), (external_dir, "external/")]:
+        if not base.exists():
+            continue
+        for skill_md in sorted(base.glob("*/skills/*/SKILL.md")):
+            parts = skill_md.parts
+            plugin = parts[-4]
+            skill  = parts[-2]
+            meta   = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+            desc   = meta.get("description", "")
+            id_str = f"{prefix}{plugin}/{skill}"
+            
+            if q and q not in id_str.lower() and q not in desc.lower():
+                continue
+
+            skills.append({
+                "id":          id_str,
+                "plugin":      plugin,
+                "skill":       skill,
+                "description": desc,
+                "path":        str(skill_md),
+                "source":      "anthropic",
+            })
+
+    # alirezarezvani/claude-skills — ~235 skills nested under domain folders
+    # (engineering/, marketing-skill/, product-team/, etc.). Skip top-level
+    # docs / scaffolding folders that aren't real skills.
+    _AWESOME_EXCLUDE = {"docs", "documentation", "tests", "scripts", "templates", "standards", "eval-workspace"}
+    if AWESOME_SKILLS.exists():
+        for skill_md in sorted(AWESOME_SKILLS.glob("**/SKILL.md")):
+            # Look only at parts RELATIVE to the marketplace root, otherwise
+            # the home dir component ".claude" trips the dot-prefix filter.
+            try:
+                rel_parts = skill_md.relative_to(AWESOME_SKILLS).parts
+            except ValueError:
+                continue
+            # Skip dot-prefixed folders (.gemini/, .claude/, .codex/, etc. — tool configs that
+            # mirror the canonical skills) and excluded scaffolding folders.
+            if any(p.startswith(".") for p in rel_parts):
+                continue
+            if _AWESOME_EXCLUDE.intersection(rel_parts):
+                continue
+
+            skill = skill_md.parent.name
+            try:
+                raw = skill_md.read_text(encoding="utf-8")
+            except (FileNotFoundError, OSError):
+                continue
+            meta  = _parse_frontmatter(raw)
+            desc  = meta.get("description", "")
+            # Encode the domain path (e.g. "engineering/foo") so skills with
+            # the same name in different domains don't collide.
+            try:
+                rel = skill_md.parent.relative_to(AWESOME_SKILLS).as_posix()
+            except ValueError:
+                rel = skill
+            id_str = f"awesome/{rel}"
+
+            if q and q not in id_str.lower() and q not in desc.lower():
+                continue
+
+            skills.append({
+                "id":          id_str,
+                "plugin":      "awesome",
+                "skill":       skill,
+                "description": desc,
+                "path":        str(skill_md),
+                "source":      "awesome",
+            })
+
+
+    return skills
+
+
+def get_local(slug: str) -> Optional[dict]:
+    """Find a local skill by its id (plugin/skill or external/plugin/skill)."""
+    for s in list_local():
+        if s["id"] == slug or s["skill"] == slug:
+            return s
+    return None
+
+
+def install_local(slug: str) -> tuple[bool, str]:
+    """Copy a local Anthropic skill (SKILL.md + all support files) into ~/.dulus/skills/<name>/"""
+    import shutil
+    entry = get_local(slug)
+    if not entry:
+        return False, f"Skill '{slug}' not found in local marketplaces (Anthropic / Awesome)."
+
+    skill_dir = Path(entry["path"]).parent  # dir containing SKILL.md + support files
+    name = entry["skill"]
+    dest_dir = DULUS_SKILLS_DIR / name
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy all files from the skill directory
+    copied = []
+    for src in skill_dir.rglob("*"):
+        if src.is_file():
+            rel = src.relative_to(skill_dir)
+            dst = dest_dir / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+            copied.append(str(rel))
+
+    # Rewrite SKILL.md with Dulus frontmatter prepended
+    skill_md = dest_dir / "SKILL.md"
+    if skill_md.exists():
+        raw = skill_md.read_text(encoding="utf-8")
+        body = _strip_frontmatter(raw)
+        skill_md.write_text(_dulus_frontmatter(entry) + body, encoding="utf-8")
+
+    return True, f"Installed '{name}' → {dest_dir}  ({len(copied)} files: {', '.join(copied[:5])}{'...' if len(copied)>5 else ''})"
+
+
+# ── CLAWHUB (remote) ───────────────────────────────────────────────────────
+
+def search_clawhub(query: str, limit: int = 10) -> list[dict]:
+    """Search ClawHub for skills matching query.
+    TODO: fill in real Convex endpoint once reversed.
+    """
+    # PLACEHOLDER — returns empty until endpoint is confirmed
+    _ = query, limit
+    return []
+
+
+def install_clawhub(slug: str) -> tuple[bool, str]:
+    """Download a skill from ClawHub by slug and save to ~/.dulus/skills/.
+    TODO: fill in real endpoint.
+    """
+    # PLACEHOLDER
+    return False, f"ClawHub API endpoint not yet mapped. Try: /skill get local/{slug}"
+
+
+# ── Installed skills ───────────────────────────────────────────────────────
+
+def list_installed(query: Optional[str] = None) -> list[dict]:
+    """Return skills already saved in ~/.dulus/skills/."""
+    DULUS_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    skills = []
+    seen = set()
+    q = query.lower() if query else None
+
+    # New format: subdirs with SKILL.md
+    for f in sorted(DULUS_SKILLS_DIR.glob("*/SKILL.md")):
+        name = f.parent.name
+        meta = _parse_frontmatter(f.read_text(encoding="utf-8"))
+        desc = meta.get("description", "")
+        
+        if q and q not in name.lower() and q not in desc.lower():
+            continue
+
+        files = list(f.parent.rglob("*"))
+        skills.append({
+            "name":        name,
+            "description": desc,
+            "source":      meta.get("clawhub_source", "unknown"),
+            "path":        str(f.parent),
+            "files":       len([x for x in files if x.is_file()]),
+        })
+        seen.add(name)
+
+    # Old format: flat .md files
+    for f in sorted(DULUS_SKILLS_DIR.glob("*.md")):
+        name = f.stem
+        if name not in seen:
+            meta = _parse_frontmatter(f.read_text(encoding="utf-8"))
+            desc = meta.get("description", "")
+
+            if q and q not in name.lower() and q not in desc.lower():
+                continue
+
+            skills.append({
+                "name":        name,
+                "description": desc,
+                "source":      meta.get("clawhub_source", "unknown"),
+                "path":        str(f),
+                "files":       1,
+            })
+    return skills
+
+
+def read_skill(name: str) -> Optional[str]:
+    """Return the body (no frontmatter) of an installed skill."""
+    # New format: subdirectory with SKILL.md
+    subdir = DULUS_SKILLS_DIR / name / "SKILL.md"
+    if subdir.exists():
+        raw = subdir.read_text(encoding="utf-8")
+        return _strip_frontmatter(raw)
+    # Old format: flat .md file
+    path = DULUS_SKILLS_DIR / f"{name}.md"
+    if path.exists():
+        raw = path.read_text(encoding="utf-8")
+        return _strip_frontmatter(raw)
+    # Fuzzy match
+    matches = list(DULUS_SKILLS_DIR.glob(f"*{name}*/SKILL.md")) + list(DULUS_SKILLS_DIR.glob(f"*{name}*.md"))
+    if not matches:
+        return None
+    raw = matches[0].read_text(encoding="utf-8")
+    return _strip_frontmatter(raw)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+def _parse_frontmatter(text: str) -> dict:
+    m = re.match(r"^---\n(.*?)\n---\n?", text, re.DOTALL)
+    if not m:
+        return {}
+    result = {}
+    for line in m.group(1).splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            result[k.strip()] = v.strip()
+    return result
+
+
+def _strip_frontmatter(text: str) -> str:
+    return re.sub(r"^---\n.*?\n---\n?", "", text, count=1, flags=re.DOTALL).strip()
+
+
+def _dulus_frontmatter(entry: dict) -> str:
+    return (
+        f"---\n"
+        f"name: {entry['skill']}\n"
+        f"description: {entry.get('description', '')}\n"
+        f"clawhub_source: {entry.get('source', 'anthropic')}\n"
+        f"triggers: [/{entry['skill']}]\n"
+        f"---\n\n"
+    )

skill/executor.py

@@ -0,0 +1,66 @@
+"""Skill execution: inline (current conversation) or forked (sub-agent)."""
+from __future__ import annotations
+
+from typing import Generator
+
+from .loader import SkillDef, substitute_arguments
+
+
+def execute_skill(
+    skill: SkillDef,
+    args: str,
+    state,
+    config: dict,
+    system_prompt: str,
+) -> Generator:
+    """Execute a skill.
+
+    If skill.context == "fork", runs as an isolated sub-agent and yields its events.
+    Otherwise (inline), injects the rendered prompt into the current agent loop.
+
+    Args:
+        skill: SkillDef to execute
+        args: raw argument string from user (after the trigger word)
+        state: AgentState
+        config: config dict (may contain _depth, model, etc.)
+        system_prompt: current system prompt string
+    Yields:
+        agent events (TextChunk, ToolStart, ToolEnd, TurnDone, …)
+    """
+    rendered = substitute_arguments(skill.prompt, args, skill.arguments)
+    message = f"[Skill: {skill.name}]\n\n{rendered}"
+
+    if skill.context == "fork":
+        yield from _execute_forked(skill, message, config, system_prompt)
+    else:
+        yield from _execute_inline(message, state, config, system_prompt)
+
+
+def _execute_inline(message: str, state, config: dict, system_prompt: str) -> Generator:
+    """Run skill prompt inline in the current conversation."""
+    import agent as _agent
+    yield from _agent.run(message, state, config, system_prompt)
+
+
+def _execute_forked(
+    skill: SkillDef,
+    message: str,
+    config: dict,
+    system_prompt: str,
+) -> Generator:
+    """Run skill as an isolated sub-agent (separate conversation context)."""
+    import agent as _agent
+
+    # Build a sub-agent config with depth tracking
+    depth = config.get("_depth", 0) + 1
+    sub_config = {**config, "_depth": depth, "_system_prompt": system_prompt}
+    if skill.model:
+        sub_config["model"] = skill.model
+
+    # Restrict tools if skill specifies allowed-tools
+    if skill.tools:
+        sub_config["_allowed_tools"] = skill.tools
+
+    # Run in fresh state (no shared history)
+    sub_state = _agent.AgentState()
+    yield from _agent.run(message, sub_state, sub_config, system_prompt)

skill/loader.py

@@ -0,0 +1,199 @@
+"""Skill loading: parse markdown files with YAML frontmatter into SkillDef objects."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class SkillDef:
+    name: str
+    description: str
+    triggers: list[str]          # ["/commit", "commit changes"]
+    tools: list[str]             # ["Bash", "Read"]  (allowed-tools)
+    prompt: str                  # full prompt body after frontmatter
+    file_path: str
+    # Enhanced fields
+    when_to_use: str = ""        # when Claude should auto-invoke this skill
+    argument_hint: str = ""      # e.g. "[branch] [description]"
+    arguments: list[str] = field(default_factory=list)  # named arg names
+    model: str = ""              # model override
+    user_invocable: bool = True  # appears in /skills list
+    context: str = "inline"      # "inline" or "fork" (fork = sub-agent)
+    source: str = "user"         # "user", "project", "builtin"
+
+
+# ── Directory paths ────────────────────────────────────────────────────────
+
+def _get_skill_paths() -> list[Path]:
+    return [
+        Path.cwd() / ".dulus-context" / "skills",   # project-level (priority)
+        Path.home() / ".dulus" / "skills",   # user-level
+    ]
+
+
+# ── List field parser ──────────────────────────────────────────────────────
+
+def _parse_list_field(value: str) -> list[str]:
+    """Parse YAML-like list: ``[a, b, c]`` or ``"a, b, c"``."""
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        value = value[1:-1]
+    return [item.strip().strip('"').strip("'") for item in value.split(",") if item.strip()]
+
+
+# ── Single-file parser ─────────────────────────────────────────────────────
+
+def _parse_skill_file(path: Path, source: str = "user") -> Optional[SkillDef]:
+    """Parse a markdown file with ``---`` frontmatter into a SkillDef.
+
+    Frontmatter fields:
+        name, description, triggers, tools / allowed-tools,
+        when_to_use, argument-hint, arguments, model,
+        user-invocable, context
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+
+    if not text.startswith("---"):
+        return None
+
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return None
+
+    frontmatter_raw = parts[1].strip()
+    prompt = parts[2].strip()
+
+    fields: dict[str, str] = {}
+    for line in frontmatter_raw.splitlines():
+        line = line.strip()
+        if not line or ":" not in line:
+            continue
+        key, _, val = line.partition(":")
+        fields[key.strip().lower()] = val.strip()
+
+    name = fields.get("name", "")
+    if not name:
+        return None
+
+    # allowed-tools wins over tools if present
+    tools_raw = fields.get("allowed-tools", fields.get("tools", ""))
+    tools = _parse_list_field(tools_raw) if tools_raw else []
+
+    triggers_raw = fields.get("triggers", "")
+    triggers = _parse_list_field(triggers_raw) if triggers_raw else [f"/{name}"]
+
+    arguments_raw = fields.get("arguments", "")
+    arguments = _parse_list_field(arguments_raw) if arguments_raw else []
+
+    user_invocable_raw = fields.get("user-invocable", "true")
+    user_invocable = user_invocable_raw.lower() not in ("false", "0", "no")
+
+    context = fields.get("context", "inline").strip().lower()
+    if context not in ("inline", "fork"):
+        context = "inline"
+
+    return SkillDef(
+        name=name,
+        description=fields.get("description", ""),
+        triggers=triggers,
+        tools=tools,
+        prompt=prompt,
+        file_path=str(path),
+        when_to_use=fields.get("when_to_use", ""),
+        argument_hint=fields.get("argument-hint", ""),
+        arguments=arguments,
+        model=fields.get("model", ""),
+        user_invocable=user_invocable,
+        context=context,
+        source=source,
+    )
+
+
+# ── Registry of built-in skills (registered by builtin.py) ────────────────
+
+_BUILTIN_SKILLS: list[SkillDef] = []
+
+
+def register_builtin_skill(skill: SkillDef) -> None:
+    _BUILTIN_SKILLS.append(skill)
+
+
+# ── Load all skills ────────────────────────────────────────────────────────
+
+def load_skills(include_builtins: bool = True) -> list[SkillDef]:
+    """Return skills from disk + builtins, deduplicated (project > user > builtin)."""
+    seen: dict[str, SkillDef] = {}
+
+    # Builtins go in first (lowest priority)
+    if include_builtins:
+        for sk in _BUILTIN_SKILLS:
+            seen[sk.name] = sk
+
+    # User-level next, project-level last (highest priority)
+    skill_paths = _get_skill_paths()
+    for i, skill_dir in enumerate(reversed(skill_paths)):
+        src = "user" if i == 0 else "project"
+        if not skill_dir.is_dir():
+            continue
+        # Support both flat files and directories (new style)
+        for md_file in sorted(skill_dir.rglob("SKILL.md")):
+            skill = _parse_skill_file(md_file, source=src)
+            if skill:
+                seen[skill.name] = skill
+        # Legacy: flat md files
+        for md_file in sorted(skill_dir.glob("*.md")):
+            if md_file.name == "SKILL.md": continue
+            skill = _parse_skill_file(md_file, source=src)
+            if skill:
+                seen[skill.name] = skill
+
+    return list(seen.values())
+
+
+def find_skill(query: str) -> Optional[SkillDef]:
+    """Find a skill whose trigger matches the first word (or whole string) of query."""
+    query = query.strip()
+    if not query:
+        return None
+
+    first_word = query.split()[0]
+    for skill in load_skills():
+        for trigger in skill.triggers:
+            if first_word == trigger:
+                return skill
+            if trigger.startswith(first_word + " "):
+                return skill
+    return None
+
+
+# ── Argument substitution ─────────────────────────────────────────────────
+
+_PLACEHOLDER_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+def substitute_arguments(prompt: str, args: str, arg_names: list[str]) -> str:
+    """Replace $ARGUMENTS (whole args string) and $ARG_NAME placeholders.
+
+    Named args are positional: first word → first name, etc.
+    Values are substituted literally; placeholder *names* are validated to
+    avoid pathological replace() chains, but values are NOT shell-escaped —
+    callers using the result in shells must quote it themselves.
+    """
+    result = prompt.replace("$ARGUMENTS", args)
+
+    arg_values = args.split()
+    for i, arg_name in enumerate(arg_names):
+        upper = arg_name.upper()
+        if not _PLACEHOLDER_RE.match(upper):
+            continue  # skip suspicious placeholder names
+        placeholder = f"${upper}"
+        value = arg_values[i] if i < len(arg_values) else ""
+        result = result.replace(placeholder, value)
+
+    return result