npm - xtrm-tools - Versions diffs - 0.7.0 → 0.7.2 - Mend

xtrm-tools 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (633) hide show

package/plugins/xtrm-tools/skills/using-serena-lsp/REFERENCE.md DELETED Viewed

@@ -1,194 +0,0 @@
-# Serena Tool Reference
-Detailed documentation for Serena MCP semantic tools.
-## Contents
-- [1. Exploration & Navigation](#1-exploration--navigation-tools)
-- [2. Editing Tools](#2-editing-tools)
-- [3. Memory Management](#3-memory-management-tools)
-- [4. Meta & Thinking](#4-meta--thinking-tools)
----
-## 1. Exploration & Navigation Tools
-### `list_dir`
-List files and directories with optional recursion.
-```python
-mcp__serena__list_dir(
-    relative_path=".",  # or "src/analysis"
-    recursive=true,
-    skip_ignored_files=true
-)
-```
-### `find_file`
-Find files by name pattern (wildcards supported).
-```python
-mcp__serena__find_file(
-    file_mask="*volatility*.py",
-    relative_path="scripts"
-)
-```
-### `get_symbols_overview`
-Get high-level code structure (symbol tree) without reading the file body.
-```python
-mcp__serena__get_symbols_overview(
-    relative_path="scripts/core/analytics.py",
-    depth=1  # 0=top-level, 1=include children (methods)
-)
-```
-### `find_symbol`
-Locate specific symbols (functions, classes, methods) semantically.
-```python
-mcp__serena__find_symbol(
-    name_path_pattern="VolatilityCalculator/analyze_rv_trend",
-    relative_path="scripts/core/volatility_suite.py",
-    depth=1,
-    include_body=true,  # Set true only when needing source code
-    substring_matching=true,
-    include_kinds=[5, 6, 12]  # 5=Class, 6=Method, 12=Function
-)
-```
-**LSP Symbol Kinds Reference**:
-```
-1=file, 2=module, 3=namespace, 4=package, 5=class, 6=method,
-7=property, 8=field, 9=constructor, 10=enum, 11=interface,
-12=function, 13=variable, 14=constant, 15=string, 16=number,
-17=boolean, 18=array, 19=object, 20=key, 21=null,
-22=enum member, 23=struct, 24=event, 25=operator, 26=type parameter
-```
-### `find_referencing_symbols`
-Find all places that reference a symbol. Essential before editing.
-```python
-mcp__serena__find_referencing_symbols(
-    name_path="calculate_volatility",
-    relative_path="scripts/core/analytics.py"
-)
-```
-### `search_for_pattern`
-Flexible regex/substring search in code.
-```python
-mcp__serena__search_for_pattern(
-    substring_pattern="def.*volatility",  # Regex (DOTALL enabled)
-    relative_path="scripts/core",
-    restrict_search_to_code_files=true,
-    context_lines_before=2,
-    context_lines_after=2
-)
-```
----
-## 2. Editing Tools
-### `replace_symbol_body`
-Replace entire symbol definition atomically.
-```python
-mcp__serena__replace_symbol_body(
-    name_path="get_db_engine",
-    relative_path="scripts/core/volatility_suite.py",
-    body="def get_db_engine(): ..."
-)
-```
-### `insert_after_symbol`
-Insert code after a symbol's definition ends.
-```python
-mcp__serena__insert_after_symbol(
-    name_path="VolatilityCalculator",
-    relative_path="scripts/core/analytics.py",
-    body="
-class RiskCalculator: ..."
-)
-```
-### `insert_before_symbol`
-Insert code before a symbol's definition starts (e.g., imports).
-```python
-mcp__serena__insert_before_symbol(
-    name_path="VolatilityCalculator",
-    relative_path="scripts/core/analytics.py",
-    body="from typing import Protocol
-"
-)
-```
-### `rename_symbol`
-Rename symbol across entire codebase using LSP.
-```python
-mcp__serena__rename_symbol(
-    name_path="calculate_volatility",
-    relative_path="scripts/core/analytics.py",
-    new_name="compute_volatility"
-)
-```
----
-## 3. Memory Management Tools
-### `write_memory`
-Store project decisions, patterns, architecture notes.
-```python
-mcp__serena__write_memory(
-    memory_file_name="architecture_decision_auth",
-    content="# Auth Pattern
-..."
-)
-```
-### `read_memory`
-Retrieve stored project knowledge.
-```python
-mcp__serena__read_memory(memory_file_name="architecture_decision_auth")
-```
-### `list_memories`
-Discover available project knowledge.
-```python
-mcp__serena__list_memories()
-```
-### `edit_memory`
-Update existing memory files.
-```python
-mcp__serena__edit_memory(
-    memory_file_name="architecture_decision_auth",
-    mode="regex",
-    needle="Old",
-    repl="New"
-)
-```
-### `delete_memory`
-Remove obsolete memory files.
-```python
-mcp__serena__delete_memory(memory_file_name="deprecated_pattern")
-```
----
-## 4. Meta & Thinking Tools
-### `check_onboarding_performed`
-Check if project onboarding was completed.
-### `onboarding`
-Get instructions for project onboarding.
-### `think_about_collected_information`
-Reflect after exploration/search operations.
-### `think_about_task_adherence`
-Verify you're still on track for the task.
-### `think_about_whether_you_are_done`
-Assess task completion.

package/plugins/xtrm-tools/skills/using-serena-lsp/SKILL.md DELETED Viewed

@@ -1,82 +0,0 @@
----
-name: using-serena-lsp
-description: Explores and edits code using semantic tools and LSP plugins. Use when reading code, understanding structure, finding symbols, or performing surgical edits to functions and classes.
-allowed-tools: mcp__serena__*, Read, Edit, Bash
-priority: high
----
-# Using Serena LSP Workflow
-**Core Principle**: Use semantic, symbol-level access to understand and edit code without reading entire files. Combine with LSP plugins for real-time analysis.
-## Tools Reference
-**Full Tool Documentation**: See [REFERENCE.md](REFERENCE.md)
-| Tool | Purpose |
-|------|---------|
-| `get_symbols_overview` | **Start here.** See high-level structure of a file. |
-| `find_symbol` | Read specific functions/classes (set `include_body=true`). |
-| `find_referencing_symbols` | Find usages before editing. |
-| `replace_symbol_body` | Surgically replace a function/class. |
-| `insert_after_symbol` | Add new code after an existing symbol. |
-| `search_for_pattern` | Regex search when symbol names are unknown. |
-## Standard Workflows
-**🚨 MANDATORY FIRST STEP FOR ALL WORKFLOWS:**
-Before using ANY Serena semantic tools (`get_symbols_overview`, `find_symbol`, `replace_symbol_body`, etc.), you MUST activate the project:
-```javascript
-mcp__plugin_serena_serena__activate_project({ project: "/path/to/current/working/directory" })
-```
-**Why this is critical**: Without project activation, Serena cannot locate code symbols and will fail or loop indefinitely. This step establishes the working context for all symbolic operations.
----
-### 1. Explore Code (The "Overview First" Pattern)
-Avoid reading full files >300 LOC.
-1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()`
-2.  **Understand Structure**: `get_symbols_overview(depth=1)`
-3.  **Drill Down**: `find_symbol(name_path="...", include_body=true)`
-4.  **Reflect**: `think_about_collected_information()`
-### 2. Surgical Editing
-1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
-2.  **Locate**: `find_symbol(include_body=true)` to get current code.
-3.  **Check Impact**: `find_referencing_symbols()` to find usages.
-4.  **Edit**: `replace_symbol_body(...)` to update.
-5.  **Verify**: Run tests or syntax checks (e.g., `python -m py_compile`).
-### 3. Adding Features
-1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
-2.  **Context**: `read_memory()` or `get_symbols_overview()` to understand patterns.
-3.  **Locate Anchor**: `find_symbol()` to find where to insert.
-4.  **Insert**: `insert_after_symbol(...)` to add new class/function.
-## File Size Guidelines
-| Lines of Code | Recommended Approach |
-|---------------|----------------------|
-| < 100 LOC | `Read` is acceptable. |
-| 100-300 LOC | `get_symbols_overview` → `find_symbol`. |
-| > 300 LOC | **Semantic only.** Do not read full file. |
-## Quick Tips
-*   **LSP Integration**: `Read()` on a Python file automatically triggers Pyright analysis. Use the feedback to fix type errors surgically.
-*   **Symbol Names**: Use `substring_matching=true` if you aren't sure of the exact name.
-*   **Safety**: Always find references before renaming or changing signatures.
-## ⚠️ Critical Constraints
-1. **NEVER skip project activation** - It must be the first Serena operation in any workflow
-2. **Use the current working directory** - Pass the actual project path, not a placeholder
-3. **Activate once per session** - After activation, all subsequent Serena tools will work correctly
-4. **Check activation status** - If Serena tools fail with "symbol not found" errors, you likely forgot to activate

package/plugins/xtrm-tools/skills/using-service-skills/SKILL.md DELETED Viewed

@@ -1,108 +0,0 @@
----
-name: using-service-skills
-description: >-
-  Service catalog discovery and expert persona activation.
-  At session start, a catalog of registered expert personas is injected
-  automatically. Use this skill to discover, understand, and activate
-  the right expert for any task.
-allowed-tools: Read, Glob
----
-# Using Service Skills
-## Role: The Concierge
-You are the **Service Skills Concierge**. Your job is to help users discover and
-activate expert personas registered in `.claude/skills/service-registry.json`.
----
-## How the Catalog Works
-At session start, the `SessionStart` hook (configured in `.claude/settings.json`)
-runs `cataloger.py` and injects a lightweight XML block into your context:
-```xml
-<project_service_catalog>
-Available expert personas:
-- db-expert: SQL & schema optimization (Path: .claude/skills/db-expert/SKILL.md)
-- auth-service: JWT authentication expert (Path: .claude/skills/auth-service/SKILL.md)
-</project_service_catalog>
-<instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>
-```
-This costs ~150 tokens per session regardless of how many experts are registered
-(Progressive Disclosure: full skill bodies are loaded only when needed).
----
-## Workflow
-### 1. Check the Injected Catalog
-When a user asks about a service or starts a related task, check whether a
-`<project_service_catalog>` block is present in your context.
-If no catalog was injected (e.g. first run, no services registered), generate one:
-```bash
-python3 "$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py"
-```
-### 2. Activate an Expert Persona
-When a task matches an expert's domain, read that skill's SKILL.md:
-```
-Read: .claude/skills/<service-id>/SKILL.md
-```
-Then adopt the expert's persona, constraints, and knowledge for the duration
-of the task.
-**Example:**
-```
-User: "Optimize this database query"
-You:  [Catalog shows db-expert matches]
-      [Read .claude/skills/db-expert/SKILL.md]
-      [Apply Senior Database Engineer persona and expertise]
-```
-### 3. Handle Missing Experts
-If no registered expert covers the user's need:
-1. Inform the user no expert exists for this domain
-2. Offer to create one: "I can create a service skill using `/creating-service-skills`"
----
-## Session Start Hook
-The catalog injection is not handled by skill frontmatter hooks. Configure it in
-`.claude/settings.json` using `SessionStart`:
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""
-      }]
-    }]
-  }
-}
-```
----
-## Tool Restrictions
-Read-only — no write access:
-- ✅ `Read` — read SKILL.md files to activate expert personas
-- ✅ `Glob` — browse `.claude/skills/` directory
-## Related Skills
-- `/creating-service-skills` — Scaffold new expert personas
-- `/updating-service-skills` — Sync skills when implementation drifts

package/plugins/xtrm-tools/skills/using-service-skills/scripts/cataloger.py DELETED Viewed

@@ -1,74 +0,0 @@
-#!/usr/bin/env python3
-"""
-Cataloger — SessionStart hook for using-service-skills.
-Reads .claude/skills/service-registry.json and prints a lightweight XML
-service catalog block (~150 tokens) to stdout. The SessionStart hook
-injects this as additional context so Claude knows which expert personas
-are available without loading full skill bodies (Progressive Disclosure).
-Configured in .claude/settings.json:
-  "SessionStart": [{"hooks": [{"type": "command",
-    "command": "python3 \\"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\\""}]}]
-Output format:
-  <project_service_catalog>
-  Available expert personas:
-  - db-expert: SQL & schema expert (Path: .claude/skills/db-expert/SKILL.md)
-  </project_service_catalog>
-  <instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>
-"""
-import sys
-from pathlib import Path
-# Bootstrap lives in creating-service-skills — shared utility
-BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
-sys.path.insert(0, str(BOOTSTRAP_DIR))
-from bootstrap import RootResolutionError, list_services  # noqa: E402
-def generate_catalog() -> str:
-    """
-    Generate the service catalog XML block.
-    Returns empty string if no services are registered or project root
-    cannot be determined (fails gracefully — never breaks session start).
-    """
-    try:
-        services = list_services()
-    except (RootResolutionError, Exception):
-        return ""
-    if not services:
-        return ""
-    lines = [
-        "<project_service_catalog>",
-        "Available expert personas:",
-    ]
-    for service_id, data in sorted(services.items()):
-        description = data.get("description", data.get("name", service_id))
-        skill_path = data.get("skill_path", f".claude/skills/{service_id}/SKILL.md")
-        lines.append(f"- {service_id}: {description} (Path: {skill_path})")
-    lines.append("</project_service_catalog>")
-    lines.append(
-        "<instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>"
-    )
-    return "\n".join(lines)
-def main() -> None:
-    """Print catalog to stdout — injected as SessionStart additional context."""
-    catalog = generate_catalog()
-    if catalog:
-        print(catalog)
-    # Silent if no services registered — don't break session start
-if __name__ == "__main__":
-    main()

package/plugins/xtrm-tools/skills/using-service-skills/scripts/skill_activator.py DELETED Viewed

@@ -1,152 +0,0 @@
-#!/usr/bin/env python3
-"""
-PreToolUse hook: skill activator.
-Fires before Read, Write, Edit, Glob, Grep, or Bash operations.
-Checks whether the operation touches a registered service territory.
-If it does, injects additionalContext telling Claude to load the skill
-before proceeding — ensuring expert knowledge is always applied.
-Configured in .claude/settings.json PreToolUse hook.
-Must be fast: pure file I/O + string matching, no subprocess.
-"""
-import fnmatch
-import json
-import sys
-from pathlib import Path
-BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
-sys.path.insert(0, str(BOOTSTRAP_DIR))
-from bootstrap import RootResolutionError, get_project_root, load_registry  # noqa: E402  # type: ignore[import-not-found]
-def match_territory(file_path: str, territory: list[str], project_root: Path) -> bool:
-    """Check if a file path matches any territory glob pattern."""
-    # Normalize to relative path
-    fp = Path(file_path)
-    if fp.is_absolute():
-        try:
-            fp = fp.relative_to(project_root)
-        except ValueError:
-            return False
-    rel = str(fp)
-    for pattern in territory:
-        # fnmatch handles * and ?, but not ** — handle ** manually
-        if "**" in pattern:
-            # Split on **/ and check prefix + suffix
-            parts = pattern.split("**/")
-            if len(parts) == 2:
-                prefix, suffix = parts
-                rel_check = rel[len(prefix) :] if rel.startswith(prefix) else rel
-                if fnmatch.fnmatch(rel_check, suffix) or fnmatch.fnmatch(
-                    rel, f"{prefix}*/{suffix}"
-                ):
-                    return True
-                # Also check if file is anywhere under the prefix dir
-                if prefix and rel.startswith(prefix.rstrip("/")):
-                    return True
-        else:
-            if fnmatch.fnmatch(rel, pattern):
-                return True
-        # Direct prefix match for broad patterns
-        base = pattern.split("/*")[0].split("/**")[0]
-        if base and (rel.startswith(base + "/") or rel == base):
-            return True
-    return False
-def find_service_for_file(
-    file_path: str, services: dict, project_root: Path
-) -> tuple[str, dict] | None:
-    """Return (service_id, service_data) if file is in any territory, else None."""
-    for service_id, data in services.items():
-        if match_territory(file_path, data.get("territory", []), project_root):
-            return service_id, data
-    return None
-def find_service_for_command(command: str, services: dict) -> tuple[str, dict] | None:
-    """Return (service_id, service_data) if command mentions a service name."""
-    cmd_lower = command.lower()
-    for service_id, data in services.items():
-        # Match service_id directly or as a container name in docker commands
-        if service_id in cmd_lower:
-            return service_id, data
-        # Match the container name pattern (service name with dashes/underscores)
-        if data.get("name") and data.get("name", "").lower().replace(" ", "-") in cmd_lower:
-            return service_id, data
-    return None
-def build_context(service_id: str, data: dict) -> str:
-    skill_path = data.get("skill_path", f".claude/skills/{service_id}/SKILL.md")
-    desc = data.get("description", "")
-    desc_line = f"\n  What it covers: {desc}" if desc else ""
-    return (
-        f"[Service Skill] You are about to work with the '{service_id}' service territory."
-        f"{desc_line}\n"
-        f"  Load the expert skill before proceeding: Read {skill_path}\n"
-        f"  The skill contains: operational knowledge, failure modes, diagnostic scripts, "
-        f"and the correct methods for managing this service.\n"
-        f"  Do not use ad-hoc approaches (raw SQL, improvised docker commands) "
-        f"when the skill defines the correct method."
-    )
-def main() -> None:
-    try:
-        data = json.load(sys.stdin)
-    except (json.JSONDecodeError, EOFError):
-        sys.exit(0)
-    tool_name = data.get("tool_name", "")
-    tool_input = data.get("tool_input", {})
-    try:
-        project_root = Path(get_project_root())
-        services = load_registry().get("services", {})
-    except (RootResolutionError, Exception):
-        sys.exit(0)
-    if not services:
-        sys.exit(0)
-    match = None
-    # File-based tools: check file_path against territory
-    if tool_name in ("Read", "Write", "Edit", "Glob", "Grep", "NotebookRead", "NotebookEdit"):
-        file_path = (
-            tool_input.get("file_path")
-            or tool_input.get("path")
-            or tool_input.get("notebook_path")
-            or ""
-        )
-        if file_path:
-            match = find_service_for_file(file_path, services, project_root)
-    # Bash: check command string for service names
-    elif tool_name == "Bash":
-        command = tool_input.get("command", "")
-        if command:
-            match = find_service_for_command(command, services)
-    if match:
-        service_id, service_data = match
-        output = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "additionalContext": build_context(service_id, service_data),
-            }
-        }
-        print(json.dumps(output))
-    sys.exit(0)
-if __name__ == "__main__":
-    main()

package/plugins/xtrm-tools/skills/using-service-skills/scripts/test_skill_activator.py DELETED Viewed

@@ -1,58 +0,0 @@
-"""Tests for skill_activator.py — load_registry integration."""
-import io
-import json
-import sys
-import unittest
-from pathlib import Path
-from unittest.mock import patch
-scripts_dir = Path(__file__).parent
-sys.path.insert(0, str(scripts_dir))
-sys.path.insert(0, str(scripts_dir.parent.parent / "creating-service-skills" / "scripts"))
-import skill_activator
-REGISTRY_WITH_VERSION = {
-    "version": "1.0",
-    "services": {
-        "my-service": {
-            "territory": ["src/my-service/**"],
-            "name": "My Service",
-            "skill_path": ".claude/skills/my-service/SKILL.md",
-        }
-    },
-}
-HOOK_INPUT = json.dumps({
-    "tool_name": "Write",
-    "tool_input": {"file_path": "src/my-service/foo.py"},
-    "hook_event_name": "PreToolUse",
-    "session_id": "test",
-    "cwd": "/fake/project",
-})
-class TestMainWithVersionedRegistry(unittest.TestCase):
-    def test_main_does_not_crash_when_registry_has_version_key(self):
-        """main() must not crash with AttributeError when load_registry returns
-        {"version": ..., "services": {...}} — the full registry dict.
-        It should output valid JSON context for the matched service.
-        """
-        with patch("skill_activator.load_registry", return_value=REGISTRY_WITH_VERSION), \
-             patch("skill_activator.get_project_root", return_value="/fake/project"), \
-             patch("sys.stdin", io.StringIO(HOOK_INPUT)), \
-             patch("sys.stdout", new_callable=io.StringIO) as mock_stdout:
-            try:
-                skill_activator.main()
-            except SystemExit:
-                pass
-            output = mock_stdout.getvalue()
-        self.assertTrue(output, "Expected JSON output but got nothing")
-        result = json.loads(output)
-        self.assertIn("hookSpecificOutput", result)
-if __name__ == "__main__":
-    unittest.main()