bps-kit 1.0.1 → 1.0.2

package/templates/vault/skill-creator/scripts/package_skill.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"❌ Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+import yaml
+from pathlib import Path
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    # Parse YAML frontmatter
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    # Define allowed properties
+    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}
+
+    # Check for unexpected properties (excluding nested keys under metadata)
+    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+    if unexpected_keys:
+        return False, (
+            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+        )
+
+    # Check required fields
+    if 'name' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    # Extract name for validation
+    name = frontmatter.get('name', '')
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        # Check naming convention (hyphen-case: lowercase with hyphens)
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+        # Check name length (max 64 characters per spec)
+        if len(name) > 64:
+            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+    # Extract and validate description
+    description = frontmatter.get('description', '')
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
+        # Check for angle brackets
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        # Check description length (max 1024 characters per spec)
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+    return True, "Skill is valid!"
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+    
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

package/templates/vault/skill-installer/scripts/detect_skills.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+Skill Detector - Find uninstalled skills in common locations.
+
+Scans known directories where skills might have been created
+(skill-creator workspaces, Desktop, Downloads, temp dirs) and
+identifies candidates that are not yet installed in the ecosystem.
+
+Usage:
+    python detect_skills.py                          # Scan default locations
+    python detect_skills.py --path "C:\\some\\dir"   # Scan specific path
+    python detect_skills.py --all                    # Scan all known locations
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# ── Configuration ──────────────────────────────────────────────────────────
+
+SKILLS_ROOT = Path(r"C:\Users\renat\skills")
+USER_HOME = Path(os.path.expanduser("~"))
+TEMP_DIR = Path(os.environ.get("TEMP", os.environ.get("TMP", str(USER_HOME / "AppData" / "Local" / "Temp"))))
+
+# Where we consider skills "installed"
+INSTALLED_LOCATIONS = [
+    SKILLS_ROOT,
+    SKILLS_ROOT / ".claude" / "skills",
+]
+
+# Default locations to scan for uninstalled skills
+DEFAULT_SCAN_LOCATIONS = [
+    USER_HOME / "Desktop",
+    USER_HOME / "Downloads",
+    USER_HOME / "Documents",
+    TEMP_DIR,
+]
+
+# Additional locations for --all mode
+EXTENDED_SCAN_LOCATIONS = [
+    USER_HOME,
+    USER_HOME / "Projects",
+    USER_HOME / "dev",
+    USER_HOME / "repos",
+    USER_HOME / "workspace",
+    USER_HOME / "code",
+    Path(r"C:\temp"),
+    Path(r"C:\projects"),
+]
+
+MAX_SCAN_DEPTH = 5
+WORKSPACE_PATTERN = re.compile(r".*-workspace[/\\]v\d+[/\\]skill$", re.IGNORECASE)
+
+
+# ── YAML Frontmatter Parser ───────────────────────────────────────────────
+
+def parse_yaml_frontmatter(path: Path) -> dict:
+    """Extract YAML frontmatter from a SKILL.md file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return {}
+
+    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return {}
+
+    try:
+        import yaml
+        return yaml.safe_load(match.group(1)) or {}
+    except Exception:
+        result = {}
+        block = match.group(1)
+        for key in ("name", "description", "version"):
+            m = re.search(rf'^{key}:\s*["\']?(.+?)["\']?\s*$', block, re.MULTILINE)
+            if m:
+                result[key] = m.group(1).strip()
+            else:
+                m2 = re.search(
+                    rf'^{key}:\s*>-?\s*\n((?:\s+.+\n?)+)', block, re.MULTILINE
+                )
+                if m2:
+                    lines = m2.group(1).strip().split("\n")
+                    result[key] = " ".join(line.strip() for line in lines)
+        return result
+
+
+# ── Core Functions ─────────────────────────────────────────────────────────
+
+def get_installed_skill_names() -> set:
+    """Get set of skill names already installed in the ecosystem."""
+    names = set()
+
+    for base in INSTALLED_LOCATIONS:
+        if not base.exists():
+            continue
+        for root, dirs, files in os.walk(base):
+            depth = len(Path(root).relative_to(base).parts)
+            if depth > 3:
+                dirs.clear()
+                continue
+
+            # Skip certain directories
+            skip = {"agent-orchestrator", "skill-installer", ".git", "__pycache__", "node_modules"}
+            if any(part in skip for part in Path(root).parts):
+                continue
+
+            if "SKILL.md" in files:
+                skill_md = Path(root) / "SKILL.md"
+                meta = parse_yaml_frontmatter(skill_md)
+                name = meta.get("name", Path(root).name)
+                names.add(name.lower())
+
+    return names
+
+
+def find_skill_candidates(scan_locations: list[Path]) -> list[dict]:
+    """Find SKILL.md files in given locations."""
+    candidates = []
+    seen_paths = set()
+    installed_names = get_installed_skill_names()
+
+    for base in scan_locations:
+        if not base.exists():
+            continue
+
+        # Skip the skills root itself (those are already installed)
+        try:
+            base.resolve().relative_to(SKILLS_ROOT.resolve())
+            continue
+        except ValueError:
+            pass
+
+        for root, dirs, files in os.walk(base):
+            root_path = Path(root)
+            depth = len(root_path.relative_to(base).parts)
+
+            if depth > MAX_SCAN_DEPTH:
+                dirs.clear()
+                continue
+
+            # Skip heavy directories
+            skip_dirs = {".git", "__pycache__", "node_modules", ".venv", "venv", ".tox"}
+            dirs[:] = [d for d in dirs if d not in skip_dirs]
+
+            if "SKILL.md" in files:
+                skill_md = root_path / "SKILL.md"
+                resolved = skill_md.resolve()
+
+                # Skip if already seen
+                if str(resolved) in seen_paths:
+                    continue
+                seen_paths.add(str(resolved))
+
+                # Skip if inside SKILLS_ROOT
+                try:
+                    resolved.relative_to(SKILLS_ROOT.resolve())
+                    continue
+                except ValueError:
+                    pass
+
+                # Parse metadata
+                meta = parse_yaml_frontmatter(skill_md)
+                name = meta.get("name", root_path.name)
+                description = meta.get("description", "")
+                has_valid = bool(name and description)
+
+                # Check if already installed
+                already_installed = name.lower() in installed_names
+
+                # Detect if in a workspace
+                is_workspace = bool(WORKSPACE_PATTERN.match(str(root_path)))
+
+                desc_str = str(description)
+
+                # Get modification timestamp and size
+                try:
+                    mtime = skill_md.stat().st_mtime
+                    mtime_str = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M")
+                except Exception:
+                    mtime = 0.0
+                    mtime_str = "unknown"
+
+                # Calculate directory size
+                total_size = 0
+                file_count = 0
+                for r2, _, f2 in os.walk(root_path):
+                    for ff in f2:
+                        try:
+                            total_size += os.path.getsize(os.path.join(r2, ff))
+                            file_count += 1
+                        except OSError:
+                            pass
+                size_kb = round(total_size / 1024, 1)
+
+                candidates.append({
+                    "name": name,
+                    "source_path": str(root_path),
+                    "skill_md_path": str(skill_md),
+                    "already_installed": already_installed,
+                    "valid_frontmatter": has_valid,
+                    "description": desc_str[:120] + ("..." if len(desc_str) > 120 else ""),
+                    "version": meta.get("version", ""),
+                    "is_workspace": is_workspace,
+                    "location_type": _classify_location(root_path),
+                    "last_modified": mtime_str,
+                    "last_modified_ts": mtime,
+                    "size_kb": size_kb,
+                    "file_count": file_count,
+                })
+
+    return candidates
+
+
+def _classify_location(path: Path) -> str:
+    """Classify where the skill was found."""
+    path_str = str(path).lower()
+
+    if "desktop" in path_str:
+        return "desktop"
+    if "download" in path_str:
+        return "downloads"
+    if "document" in path_str:
+        return "documents"
+    if "temp" in path_str or "tmp" in path_str:
+        return "temp"
+    if "workspace" in path_str:
+        return "workspace"
+    return "other"
+
+
+# ── Main Logic ─────────────────────────────────────────────────────────────
+
+def detect(paths: list[Path] = None, scan_all: bool = False) -> dict:
+    """
+    Detect uninstalled skills.
+
+    Args:
+        paths: Specific paths to scan. If None, uses defaults.
+        scan_all: If True, scan extended locations too.
+
+    Returns:
+        dict with candidates list and summary.
+    """
+    scan_locations = []
+
+    if paths:
+        scan_locations.extend(paths)
+    else:
+        scan_locations.extend(DEFAULT_SCAN_LOCATIONS)
+
+    if scan_all:
+        scan_locations.extend(EXTENDED_SCAN_LOCATIONS)
+
+    # Deduplicate
+    seen = set()
+    unique_locations = []
+    for loc in scan_locations:
+        resolved = str(loc.resolve())
+        if resolved not in seen:
+            seen.add(resolved)
+            unique_locations.append(loc)
+
+    candidates = find_skill_candidates(unique_locations)
+
+    # Sort: uninstalled first, then by most recently modified
+    candidates.sort(key=lambda c: (
+        c["already_installed"],
+        -c.get("last_modified_ts", 0),
+        c["name"].lower(),
+    ))
+
+    not_installed = [c for c in candidates if not c["already_installed"]]
+    already = [c for c in candidates if c["already_installed"]]
+
+    return {
+        "total_found": len(candidates),
+        "not_installed": len(not_installed),
+        "already_installed": len(already),
+        "scanned_locations": [str(p) for p in unique_locations if p.exists()],
+        "candidates": candidates,
+    }
+
+
+# ── CLI Entry Point ───────────────────────────────────────────────────────
+
+def main():
+    paths = []
+    scan_all = "--all" in sys.argv
+
+    if "--path" in sys.argv:
+        idx = sys.argv.index("--path")
+        if idx + 1 < len(sys.argv):
+            p = Path(sys.argv[idx + 1]).resolve()
+            if p.exists():
+                paths.append(p)
+            else:
+                print(json.dumps({
+                    "error": f"Path does not exist: {p}",
+                    "total_found": 0,
+                    "candidates": [],
+                }, indent=2))
+                sys.exit(1)
+
+    result = detect(paths=paths if paths else None, scan_all=scan_all)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    # Exit with 0 if candidates found, 1 if none
+    sys.exit(0 if result["total_found"] > 0 else 1)
+
+
+if __name__ == "__main__":
+    main()