bps-kit 1.0.1 → 1.0.2

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

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Create ZIP files for Claude.ai web/desktop upload.
+
+Claude Code (CLI) and Claude.ai (web/desktop) have SEPARATE skill systems.
+Skills in .claude/skills/ work in the terminal but do NOT appear in the
+Claude.ai web Habilidades (Skills) settings page.
+
+To install a skill in Claude.ai web/desktop, you need to upload a ZIP file
+through Settings > Capabilities > Skills > Upload skill.
+
+This script packages skills into the correct ZIP format.
+
+Usage:
+    python package_skill.py --source "C:\\path\\to\\skill"
+    python package_skill.py --source "C:\\path\\to\\skill" --output "C:\\Users\\renat\\Desktop"
+    python package_skill.py --all
+    python package_skill.py --all --output "C:\\Users\\renat\\Desktop"
+"""
+
+import os
+import sys
+import json
+import re
+import zipfile
+from pathlib import Path
+
+# ── Configuration ──────────────────────────────────────────────────────────
+
+SKILLS_ROOT = Path(r"C:\Users\renat\skills")
+DEFAULT_OUTPUT = Path(os.path.expanduser("~")) / "Desktop"
+
+# Directories to exclude from ZIP
+EXCLUDE_DIRS = {
+    ".git", "__pycache__", "node_modules", ".venv", "venv",
+    ".tox", ".mypy_cache", ".pytest_cache", "data",
+}
+
+# File patterns to exclude
+EXCLUDE_FILES = {
+    ".env", ".gitignore", ".DS_Store", "Thumbs.db",
+    "credentials.json", "token.json",
+}
+
+EXCLUDE_EXTENSIONS = {
+    ".pyc", ".pyo", ".db", ".sqlite", ".sqlite3",
+    ".log", ".tmp", ".bak",
+}
+
+
+# ── 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
+
+
+# ── Validation ─────────────────────────────────────────────────────────────
+
+def validate_for_web(skill_dir: Path) -> dict:
+    """Validate skill meets Claude.ai web upload requirements."""
+    errors = []
+    warnings = []
+
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        errors.append("SKILL.md not found")
+        return {"valid": False, "errors": errors, "warnings": warnings}
+
+    meta = parse_yaml_frontmatter(skill_md)
+
+    # Name: required, lowercase, letters/numbers/hyphens only, max 64 chars
+    name = meta.get("name", "")
+    if not name:
+        errors.append("Missing 'name' field in frontmatter")
+    else:
+        if name != name.lower():
+            warnings.append(f"Name '{name}' should be lowercase: '{name.lower()}'")
+        name_lower = name.lower()
+        if len(name_lower) == 1:
+            if not re.match(r'^[a-z0-9]$', name_lower):
+                warnings.append(f"Name '{name}' should only contain lowercase letters or numbers")
+        elif not re.match(r'^[a-z0-9][a-z0-9-]*[a-z0-9]$', name_lower):
+            warnings.append(f"Name '{name}' should only contain lowercase letters, numbers, and hyphens")
+        if len(name) > 64:
+            errors.append(f"Name exceeds 64 characters: {len(name)}")
+        if "anthropic" in name_lower or "claude" in name_lower:
+            errors.append(f"Name cannot contain reserved words 'anthropic' or 'claude'")
+
+    # Description: required, max 1024 chars
+    desc = meta.get("description", "")
+    if not desc:
+        errors.append("Missing 'description' field in frontmatter")
+    elif len(desc) > 1024:
+        warnings.append(f"Description exceeds 1024 chars ({len(desc)}), may be truncated")
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "name": name,
+        "description": desc[:120] if desc else "",
+    }
+
+
+def should_include(file_path: Path, skill_dir: Path) -> bool:
+    """Check if a file should be included in the ZIP."""
+    rel = file_path.relative_to(skill_dir)
+
+    # Check directory exclusions
+    for part in rel.parts[:-1]:
+        if part in EXCLUDE_DIRS:
+            return False
+
+    # Check file exclusions
+    if file_path.name in EXCLUDE_FILES:
+        return False
+
+    # Check extension exclusions
+    if file_path.suffix.lower() in EXCLUDE_EXTENSIONS:
+        return False
+
+    return True
+
+
+# ── Packaging ──────────────────────────────────────────────────────────────
+
+def package_skill(skill_dir: Path, output_dir: Path = None) -> dict:
+    """
+    Package a skill directory into a ZIP file for Claude.ai upload.
+
+    The ZIP format required by Claude.ai:
+        skill-name.zip
+        └── skill-name/
+              ├── SKILL.md
+              ├── scripts/
+              ├── references/
+              └── ...
+    """
+    skill_dir = Path(skill_dir).resolve()
+
+    if not skill_dir.exists():
+        return {"success": False, "error": f"Directory not found: {skill_dir}"}
+
+    # Validate
+    validation = validate_for_web(skill_dir)
+    if not validation["valid"]:
+        return {
+            "success": False,
+            "error": f"Validation failed: {'; '.join(validation['errors'])}",
+            "validation": validation,
+        }
+
+    skill_name = validation["name"] or skill_dir.name
+    skill_name_lower = skill_name.lower()
+
+    # Determine output path
+    if output_dir is None:
+        output_dir = DEFAULT_OUTPUT
+    output_dir = Path(output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    zip_path = output_dir / f"{skill_name_lower}.zip"
+
+    # Collect files
+    files_to_include = []
+    for root, dirs, files in os.walk(skill_dir):
+        # Filter directories in-place to skip excluded ones
+        dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS]
+
+        for f in files:
+            fp = Path(root) / f
+            if should_include(fp, skill_dir):
+                files_to_include.append(fp)
+
+    if not files_to_include:
+        return {"success": False, "error": "No files to package"}
+
+    # Create ZIP with skill folder as root
+    # CRITICAL: ZIP paths MUST use forward slashes, not Windows backslashes
+    try:
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for fp in sorted(files_to_include):
+                rel_path = fp.relative_to(skill_dir)
+                # Convert Windows backslash to forward slash for ZIP compatibility
+                rel_posix = rel_path.as_posix()
+                archive_path = f"{skill_name_lower}/{rel_posix}"
+                zf.write(fp, archive_path)
+
+        # Verify ZIP is not empty and valid
+        with zipfile.ZipFile(zip_path, "r") as zf_check:
+            entries = zf_check.namelist()
+            if not entries:
+                zip_path.unlink(missing_ok=True)
+                return {"success": False, "error": "ZIP was created empty (no files written)"}
+            # Verify no backslash paths leaked through
+            bad_paths = [e for e in entries if "\\" in e]
+            if bad_paths:
+                zip_path.unlink(missing_ok=True)
+                return {
+                    "success": False,
+                    "error": f"ZIP contains backslash paths (invalid): {bad_paths[:3]}",
+                }
+
+        # Get ZIP size
+        zip_size = zip_path.stat().st_size
+        zip_size_kb = zip_size / 1024
+
+    except Exception as e:
+        return {"success": False, "error": f"ZIP creation failed: {e}"}
+
+    return {
+        "success": True,
+        "zip_path": str(zip_path),
+        "skill_name": skill_name_lower,
+        "files_count": len(files_to_include),
+        "zip_size_kb": round(zip_size_kb, 1),
+        "validation": validation,
+        "upload_instructions": (
+            "Para instalar no Claude.ai web/desktop:\n"
+            "1. Abra claude.ai > Settings > Capabilities > Skills\n"
+            "2. Clique em 'Upload skill'\n"
+            f"3. Selecione o arquivo: {zip_path}\n"
+            "4. A skill aparecera na lista de Habilidades"
+        ),
+    }
+
+
+def package_all(output_dir: Path = None) -> dict:
+    """Package all installed skills."""
+    results = []
+
+    # Find all skill directories with SKILL.md
+    for item in sorted(SKILLS_ROOT.iterdir()):
+        if not item.is_dir():
+            continue
+        if item.name.startswith("."):
+            continue
+        if item.name == "agent-orchestrator":
+            continue  # Meta-skill, not for web upload
+
+        skill_md = item / "SKILL.md"
+        if skill_md.exists():
+            result = package_skill(item, output_dir)
+            results.append(result)
+
+    # Also check nested skills
+    for parent in SKILLS_ROOT.iterdir():
+        if not parent.is_dir() or parent.name.startswith("."):
+            continue
+        for child in parent.iterdir():
+            if child.is_dir() and (child / "SKILL.md").exists():
+                if child.name != "agent-orchestrator":
+                    result = package_skill(child, output_dir)
+                    results.append(result)
+
+    success = sum(1 for r in results if r["success"])
+    failed = sum(1 for r in results if not r["success"])
+
+    return {
+        "total": len(results),
+        "success": success,
+        "failed": failed,
+        "results": results,
+    }
+
+
+# ── Verify Existing ZIPs ──────────────────────────────────────────────────
+
+def verify_zips(output_dir: Path = None) -> dict:
+    """Verify all existing skill ZIPs for integrity.
+
+    Checks:
+    - ZIP is valid and not corrupted
+    - Contains SKILL.md
+    - No backslash paths
+    - Not empty
+    - Matches a known skill name
+    """
+    if output_dir is None:
+        output_dir = DEFAULT_OUTPUT
+
+    results = []
+    zip_files = sorted(output_dir.glob("*.zip"))
+
+    for zip_path in zip_files:
+        entry = {
+            "file": str(zip_path),
+            "name": zip_path.stem,
+            "size_kb": round(zip_path.stat().st_size / 1024, 1),
+            "valid": False,
+            "issues": [],
+        }
+
+        try:
+            with zipfile.ZipFile(zip_path, "r") as zf:
+                entries = zf.namelist()
+
+                if not entries:
+                    entry["issues"].append("ZIP is empty")
+                    results.append(entry)
+                    continue
+
+                # Check for backslash paths
+                bad_paths = [e for e in entries if "\\" in e]
+                if bad_paths:
+                    entry["issues"].append(f"Contains backslash paths: {bad_paths[:3]}")
+
+                # Check for SKILL.md
+                has_skill_md = any(e.endswith("SKILL.md") for e in entries)
+                if not has_skill_md:
+                    entry["issues"].append("Missing SKILL.md")
+
+                # Test integrity
+                bad_file = zf.testzip()
+                if bad_file:
+                    entry["issues"].append(f"Corrupted file in ZIP: {bad_file}")
+
+                entry["file_count"] = len(entries)
+                entry["valid"] = len(entry["issues"]) == 0
+
+        except zipfile.BadZipFile:
+            entry["issues"].append("Not a valid ZIP file")
+        except Exception as e:
+            entry["issues"].append(f"Error reading ZIP: {e}")
+
+        results.append(entry)
+
+    valid = sum(1 for r in results if r["valid"])
+    invalid = sum(1 for r in results if not r["valid"])
+
+    return {
+        "total": len(results),
+        "valid": valid,
+        "invalid": invalid,
+        "output_dir": str(output_dir),
+        "results": results,
+    }
+
+
+# ── CLI Entry Point ───────────────────────────────────────────────────────
+
+def main():
+    args = sys.argv[1:]
+
+    source = None
+    output_dir = None
+    do_all = "--all" in args
+    do_verify = "--verify" in args
+
+    if "--source" in args:
+        idx = args.index("--source")
+        if idx + 1 < len(args):
+            source = args[idx + 1]
+
+    if "--output" in args:
+        idx = args.index("--output")
+        if idx + 1 < len(args):
+            output_dir = Path(args[idx + 1])
+
+    if do_verify:
+        result = verify_zips(Path(output_dir) if output_dir else None)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        sys.exit(0 if result["invalid"] == 0 else 1)
+
+    if not source and not do_all:
+        print(json.dumps({
+            "error": "Usage: python package_skill.py <command>",
+            "commands": {
+                "--source <path>": "Package a single skill",
+                "--source <path> --output <dir>": "Package to specific directory",
+                "--all": "Package all installed skills",
+                "--all --output <dir>": "Package all to specific directory",
+                "--verify": "Verify integrity of all existing ZIPs",
+                "--verify --output <dir>": "Verify ZIPs in specific directory",
+            },
+        }, indent=2))
+        sys.exit(1)
+
+    if source:
+        result = package_skill(Path(source), output_dir)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        sys.exit(0 if result["success"] else 1)
+    elif do_all:
+        result = package_all(output_dir)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        sys.exit(0 if result["failed"] == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/skill-installer/scripts/requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0