xtrm-tools 0.7.16 → 0.7.18

package/.xtrm/skills/default/creating-service-skills/scripts/bootstrap.py

@@ -5,69 +5,55 @@ Bootstrap module for Service Skill Trinity.
 Provides root-discovery and registry CRUD operations shared across all
 service-skill workflow scripts. All scripts in the trinity import from here.
 
-Registry location: service-registry.json (preferred) or .claude/skills/service-registry.json (legacy)
-Skills location:   .claude/skills/<service-id>/
+Registry resolution order:
+  1) $SERVICE_REGISTRY_PATH override
+  2) <root>/service-registry.json
+  3) <root>/.claude/skills/service-registry.json
+  4) <root>/.xtrm/skills/user/packs/*/service-registry.json
+
+For pack glob, first hit wins after disambiguation:
+- If active pack discoverable, matching pack registry preferred
+- Else lexicographically first registry used with stderr warning
+
+Skills location: .xtrm/skills/user/packs/<pack>/<service-id>/
 """
 
 import json
 import os
+import re
 import subprocess  # nosec B404
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+SERVICE_ID_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-_]{0,63}$")
+PACKS_ROOT_SUFFIX = Path(".xtrm") / "skills" / "user" / "packs"
 
-class BootstrapError(Exception):
-    """Base exception for bootstrap operations."""
 
+class BootstrapError(Exception):
     pass
 
 
 class RootResolutionError(BootstrapError):
-    """Raised when project root cannot be determined."""
-
     pass
 
 
 class RegistryError(BootstrapError):
-    """Raised when registry operations fail."""
-
     pass
 
 
 def get_project_root() -> str:
-    """
-    Resolve project root via git.
-
-    Returns:
-        Absolute path to project root
-
-    Raises:
-        RootResolutionError: If git command fails or returns invalid path
-    """
     try:
-        result = subprocess.run(  # nosec B603 B607
-            ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True,
-            text=True,
-            check=True,
-            timeout=5,
-        )
+        result = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=True, timeout=5)  # nosec B603 B607
         root = result.stdout.strip()
-
         if not root:
             raise RootResolutionError("Git returned empty path")
-
         if not os.path.isdir(root):
             raise RootResolutionError(f"Resolved path is not a directory: {root}")
-
         return root
-
     except subprocess.CalledProcessError as e:
-        raise RootResolutionError(
-            f"Git root resolution failed: {e.stderr.strip() if e.stderr else str(e)}"
-        ) from e
+        raise RootResolutionError(f"Git root resolution failed: {e.stderr.strip() if e.stderr else str(e)}") from e
     except subprocess.TimeoutExpired as e:
         raise RootResolutionError("Git command timed out") from e
     except FileNotFoundError as e:
@@ -75,35 +61,68 @@ def get_project_root() -> str:
 
 
 def get_skills_root(project_root: str | None = None) -> Path:
-    """
-    Get the .claude/skills/ directory path.
+    if project_root is None:
+        project_root = get_project_root()
+    return Path(project_root) / ".claude" / "skills"
 
-    Args:
-        project_root: Optional project root (uses get_project_root() if not provided)
 
-    Returns:
-        Path to .claude/skills/ directory
-    """
+def _packs_root(project_root: str | None = None) -> Path:
     if project_root is None:
         project_root = get_project_root()
-    return Path(project_root) / ".claude" / "skills"
+    return Path(project_root) / PACKS_ROOT_SUFFIX
 
 
-def get_registry_path(project_root: str | None = None) -> Path:
-    """
-    Get the service-registry.json path.
+def _ensure_within_root(candidate: Path, root: Path, label: str) -> Path:
+    resolved_root = root.resolve()
+    resolved_candidate = candidate.resolve(strict=False)
+    if resolved_root not in resolved_candidate.parents and resolved_candidate != resolved_root:
+        raise RootResolutionError(f"{label} must stay within {resolved_root}")
+    return resolved_candidate
+
+
+def get_pack_path(project_root: str | None = None) -> Path | None:
+    if project_root is None:
+        env_root = os.environ.get("CLAUDE_PROJECT_DIR")
+        project_root = env_root or get_project_root()
+
+    root = Path(project_root)
+    packs_root = _packs_root(project_root)
+    env_pack = os.environ.get("XTRM_PACK")
+
+    if env_pack:
+        pack_path = Path(env_pack)
+        if not pack_path.is_absolute():
+            pack_path = packs_root / env_pack
+        return _ensure_within_root(pack_path, packs_root, "XTRM_PACK path")
 
-    Resolution order:
-      1. SERVICE_REGISTRY_PATH env var (explicit override)
-      2. <project-root>/service-registry.json (preferred)
-      3. <project-root>/.claude/skills/service-registry.json (legacy fallback)
+    if not packs_root.exists():
+        return None
 
-    Args:
-        project_root: Optional project root
+    pack_dirs = [path for path in packs_root.iterdir() if path.is_dir()]
+    if len(pack_dirs) == 1:
+        return pack_dirs[0].resolve()
 
-    Returns:
-        Path to service registry
-    """
+    return None
+
+
+def _select_pack_registry(pack_registries: list[Path], project_root: str) -> Path:
+    active_pack = get_pack_path(project_root)
+    if active_pack is not None:
+        active_candidate = active_pack / "service-registry.json"
+        if active_candidate in pack_registries:
+            return active_candidate
+
+    chosen = sorted(pack_registries)[0]
+    if len(pack_registries) > 1:
+        candidates = ", ".join(str(p) for p in sorted(pack_registries))
+        print(
+            f"Warning: multiple pack registries found, using {chosen}. Candidates: {candidates}",
+            file=sys.stderr,
+        )
+    return chosen
+
+
+def get_registry_path(project_root: str | None = None) -> Path:
     env_registry = os.environ.get("SERVICE_REGISTRY_PATH")
     if env_registry:
         return Path(env_registry)
@@ -114,32 +133,24 @@ def get_registry_path(project_root: str | None = None) -> Path:
 
     root = Path(project_root)
     preferred = root / "service-registry.json"
-    legacy = root / ".claude" / "skills" / "service-registry.json"
-
-    if preferred.exists() or not legacy.exists():
+    if preferred.exists():
         return preferred
 
-    return legacy
-
+    legacy = root / ".claude" / "skills" / "service-registry.json"
+    if legacy.exists():
+        return legacy
 
-def load_registry(project_root: str | None = None) -> dict[str, Any]:
-    """
-    Load the service registry.
+    pack_registries = sorted(root.glob(".xtrm/skills/user/packs/*/service-registry.json"))
+    if pack_registries:
+        return _select_pack_registry(pack_registries, project_root)
 
-    Args:
-        project_root: Optional project root
+    return preferred
 
-    Returns:
-        Registry contents as dict
 
-    Raises:
-        RegistryError: If registry cannot be loaded
-    """
+def load_registry(project_root: str | None = None) -> dict[str, Any]:
     registry_path = get_registry_path(project_root)
-
     if not registry_path.exists():
         return {"version": "1.0", "services": {}}
-
     try:
         with open(registry_path, encoding="utf-8") as f:
             return json.load(f)
@@ -150,19 +161,8 @@ def load_registry(project_root: str | None = None) -> dict[str, Any]:
 
 
 def save_registry(data: dict[str, Any], project_root: str | None = None) -> None:
-    """
-    Save the service registry.
-
-    Args:
-        data: Registry contents
-        project_root: Optional project root
-
-    Raises:
-        RegistryError: If registry cannot be saved
-    """
     registry_path = get_registry_path(project_root)
     registry_path.parent.mkdir(parents=True, exist_ok=True)
-
     try:
         with open(registry_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
@@ -178,25 +178,9 @@ def register_service(
     description: str = "",
     project_root: str | None = None,
 ) -> None:
-    """
-    Register a new service in the registry.
-
-    Args:
-        service_id: Unique identifier (e.g., "db-expert")
-        name: Display name (e.g., "Database Expert")
-        territory: List of glob patterns for files this service owns
-        skill_path: Path to SKILL.md relative to project root
-        description: Optional description
-        project_root: Optional project root
-
-    Raises:
-        RegistryError: If registration fails
-    """
     registry = load_registry(project_root)
-
     if "services" not in registry:
         registry["services"] = {}
-
     registry["services"][service_id] = {
         "name": name,
         "territory": territory,
@@ -204,101 +188,46 @@ def register_service(
         "description": description,
         "last_sync": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
     }
-
     save_registry(registry, project_root)
 
 
 def unregister_service(service_id: str, project_root: str | None = None) -> bool:
-    """
-    Remove a service from the registry.
-
-    Args:
-        service_id: Service identifier to remove
-        project_root: Optional project root
-
-    Returns:
-        True if service was removed, False if it didn't exist
-    """
     registry = load_registry(project_root)
-
     if "services" not in registry or service_id not in registry["services"]:
         return False
-
     del registry["services"][service_id]
     save_registry(registry, project_root)
     return True
 
 
 def get_service(service_id: str, project_root: str | None = None) -> dict[str, Any] | None:
-    """
-    Get a service by ID.
-
-    Args:
-        service_id: Service identifier
-        project_root: Optional project root
-
-    Returns:
-        Service dict or None if not found
-    """
     registry = load_registry(project_root)
     return registry.get("services", {}).get(service_id)
 
 
 def list_services(project_root: str | None = None) -> dict[str, dict[str, Any]]:
-    """
-    List all registered services.
-
-    Args:
-        project_root: Optional project root
-
-    Returns:
-        Dict of service_id -> service_data
-    """
     registry = load_registry(project_root)
     return registry.get("services", {})
 
 
 def find_service_for_path(file_path: str, project_root: str | None = None) -> str | None:
-    """
-    Find which service (if any) owns a given file path.
-
-    Uses glob matching against territory patterns.
-
-    Args:
-        file_path: Relative path to check
-        project_root: Optional project root
-
-    Returns:
-        Service ID or None if no match
-    """
     registry = load_registry(project_root)
-
     if project_root is None:
         try:
             project_root = get_project_root()
         except RootResolutionError:
             return None
-
     project_root = Path(project_root)
     file_path_obj = Path(file_path)
-
-    if not file_path_obj.is_absolute():
-        test_path = project_root / file_path_obj
-    else:
-        test_path = file_path_obj
-
+    test_path = project_root / file_path_obj if not file_path_obj.is_absolute() else file_path_obj
     for service_id, service_data in registry.get("services", {}).items():
-        territory = service_data.get("territory", [])
-        for pattern in territory:
-            # Direct glob match
+        for pattern in service_data.get("territory", []):
             for glob_match in Path(project_root).glob(pattern):
                 if glob_match == test_path:
                     return service_id
-            # Prefix match for directory patterns
             base = pattern.replace("/**/*", "").replace("/**", "").rstrip("/")
             if str(file_path).startswith(base + "/") or str(file_path) == base:
                 return service_id
-
     return None
 
 
@@ -307,16 +236,13 @@ if __name__ == "__main__":
         print("Usage: python bootstrap.py <command> [args...]")
         print("Commands: root, registry, list, find <path>")
         sys.exit(1)
-
     command = sys.argv[1]
-
     if command == "root":
         print(get_project_root())
     elif command == "registry":
         print(json.dumps(load_registry(), indent=2))
     elif command == "list":
-        services = list_services()
-        for sid, data in services.items():
+        for sid, data in list_services().items():
             print(f"- {sid}: {data.get('name', 'N/A')} ({data.get('description', 'N/A')})")
     elif command == "find" and len(sys.argv) > 2:
         result = find_service_for_path(sys.argv[2])