tweek 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

tweek/skill_template/scripts/check_installed.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+Tweek Installation Status Checker
+
+Checks whether tweek is installed and operational on this system.
+Returns structured JSON for deterministic parsing by AI assistants.
+
+Usage:
+    python3 check_installed.py              # Check status (read-only)
+    python3 check_installed.py --decline     # Record that user declined install
+    python3 check_installed.py --reset       # Clear the decline preference
+
+This script uses ONLY Python stdlib — no tweek imports, no pip imports.
+"""
+
+import json
+import os
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _preferences_path():
+    """Path to the preferences file stored alongside this script."""
+    return Path(__file__).resolve().parent.parent / ".preferences.json"
+
+
+def _load_preferences():
+    """Load preferences from disk. Returns empty dict if missing/corrupt."""
+    path = _preferences_path()
+    if not path.is_file():
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def _save_preferences(prefs):
+    """Write preferences to disk."""
+    path = _preferences_path()
+    with open(path, "w") as f:
+        json.dump(prefs, f, indent=2)
+
+
+def decline_install():
+    """Record that the user declined tweek installation."""
+    prefs = _load_preferences()
+    prefs["install_declined"] = True
+    prefs["declined_at"] = datetime.now(timezone.utc).isoformat()
+    _save_preferences(prefs)
+    print(json.dumps({"action": "decline_saved", "path": str(_preferences_path())}))
+
+
+def reset_preference():
+    """Clear the decline preference so the offer can be made again."""
+    prefs = _load_preferences()
+    prefs.pop("install_declined", None)
+    prefs.pop("declined_at", None)
+    _save_preferences(prefs)
+    print(json.dumps({"action": "preference_reset", "path": str(_preferences_path())}))
+
+
+def check_installation():
+    """Check tweek installation status across multiple signals."""
+
+    result = {
+        "tweek_in_path": False,
+        "tweek_path": None,
+        "tweek_data_dir": False,
+        "hooks_registered": False,
+        "hooks_detail": {
+            "pre_tool_use": False,
+            "post_tool_use": False,
+        },
+        "install_declined": False,
+        "declined_at": None,
+        "pip_available": False,
+        "pipx_available": False,
+        "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        "status": "not_installed",
+        "install_command": None,
+    }
+
+    # Check user preferences
+    prefs = _load_preferences()
+    if prefs.get("install_declined"):
+        result["install_declined"] = True
+        result["declined_at"] = prefs.get("declined_at")
+
+    # Check 1: Is tweek in PATH?
+    tweek_path = shutil.which("tweek")
+    if tweek_path:
+        result["tweek_in_path"] = True
+        result["tweek_path"] = tweek_path
+
+    # Check 2: Does ~/.tweek/ data directory exist?
+    tweek_dir = Path.home() / ".tweek"
+    if tweek_dir.is_dir():
+        result["tweek_data_dir"] = True
+
+    # Check 3: Are hooks registered in ~/.claude/settings.json?
+    for settings_path in [
+        Path.home() / ".claude" / "settings.json",
+        Path.cwd() / ".claude" / "settings.json",
+    ]:
+        if settings_path.is_file():
+            try:
+                with open(settings_path) as f:
+                    settings = json.load(f)
+                hooks = settings.get("hooks", {})
+
+                pre_hooks = hooks.get("PreToolUse", [])
+                for hook_group in pre_hooks:
+                    for hook in hook_group.get("hooks", []):
+                        cmd = hook.get("command", "")
+                        if "pre_tool_use.py" in cmd and "tweek" in cmd:
+                            result["hooks_detail"]["pre_tool_use"] = True
+
+                post_hooks = hooks.get("PostToolUse", [])
+                for hook_group in post_hooks:
+                    for hook in hook_group.get("hooks", []):
+                        cmd = hook.get("command", "")
+                        if "post_tool_use.py" in cmd and "tweek" in cmd:
+                            result["hooks_detail"]["post_tool_use"] = True
+
+                if result["hooks_detail"]["pre_tool_use"] or result["hooks_detail"]["post_tool_use"]:
+                    result["hooks_registered"] = True
+                    break
+
+            except (json.JSONDecodeError, IOError, KeyError):
+                pass
+
+    # Check 4: Package manager availability
+    if shutil.which("pip") or shutil.which("pip3"):
+        result["pip_available"] = True
+    if shutil.which("pipx"):
+        result["pipx_available"] = True
+
+    # Determine overall status
+    if result["tweek_in_path"] and result["hooks_registered"]:
+        result["status"] = "fully_operational"
+    elif result["tweek_in_path"] and not result["hooks_registered"]:
+        result["status"] = "installed_no_hooks"
+        result["install_command"] = "tweek install"
+    elif not result["tweek_in_path"] and result["hooks_registered"]:
+        result["status"] = "hooks_only"
+        result["install_command"] = "pip install tweek"
+    else:
+        result["status"] = "not_installed"
+        if result["pipx_available"]:
+            result["install_command"] = "pipx install tweek && tweek install"
+        elif result["pip_available"]:
+            result["install_command"] = "pip install tweek && tweek install"
+        else:
+            result["install_command"] = "python3 -m pip install tweek && tweek install"
+
+    return result
+
+
+if __name__ == "__main__":
+    if "--decline" in sys.argv:
+        decline_install()
+    elif "--reset" in sys.argv:
+        reset_preference()
+    else:
+        status = check_installation()
+        print(json.dumps(status, indent=2))

tweek/skills/__init__.py

@@ -0,0 +1,38 @@
+"""
+Tweek Skill Isolation Chamber
+
+Security quarantine layer for Claude Code skills. Skills are placed in an
+isolation chamber, scanned by a multi-layer pipeline, and either auto-installed
+or jailed based on scan results.
+
+Components:
+- config: IsolationConfig dataclass and loader
+- scanner: 7-layer security scanning pipeline
+- isolation: Chamber lifecycle management
+- guard: Self-protection against AI circumvention
+- fingerprints: SHA-256 fingerprint cache for git-arrived skill detection
+"""
+
+from pathlib import Path
+
+# Directory constants
+TWEEK_HOME = Path.home() / ".tweek"
+SKILLS_DIR = TWEEK_HOME / "skills"
+CHAMBER_DIR = SKILLS_DIR / "chamber"
+JAIL_DIR = SKILLS_DIR / "jail"
+REPORTS_DIR = SKILLS_DIR / "reports"
+
+# Claude's actual skill install locations
+CLAUDE_GLOBAL_SKILLS = Path.home() / ".claude" / "skills"
+
+
+def get_claude_project_skills(working_dir: Path = None) -> Path:
+    """Get the project-level Claude skills directory."""
+    base = working_dir or Path.cwd()
+    return base / ".claude" / "skills"
+
+
+def ensure_directories():
+    """Create all required isolation chamber directories."""
+    for d in (CHAMBER_DIR, JAIL_DIR, REPORTS_DIR):
+        d.mkdir(parents=True, exist_ok=True)

tweek/skills/config.py

@@ -0,0 +1,150 @@
+"""
+Isolation Chamber Configuration
+
+Defines the IsolationConfig dataclass and loading logic.
+Configuration is stored in ~/.tweek/config.yaml under the 'isolation_chamber' key.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+import yaml
+
+
+# Default allowed file extensions for skills
+DEFAULT_ALLOWED_EXTENSIONS = [
+    ".md", ".py", ".json", ".yaml", ".yml", ".txt", ".sh", ".toml",
+]
+
+# Extensions that should never appear in a skill
+DEFAULT_BLOCKED_EXTENSIONS = [
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".msi", ".dmg",
+    ".com", ".bat", ".cmd", ".scr", ".pif",
+]
+
+
+@dataclass
+class IsolationConfig:
+    """Configuration for the Skill Isolation Chamber."""
+
+    enabled: bool = True
+    mode: str = "auto"  # "auto" or "manual"
+    scan_timeout_seconds: float = 30.0
+    llm_review_enabled: bool = True
+    max_skill_size_bytes: int = 1_048_576  # 1MB
+    max_file_count: int = 50
+    max_directory_depth: int = 3
+    allowed_file_extensions: List[str] = field(
+        default_factory=lambda: list(DEFAULT_ALLOWED_EXTENSIONS)
+    )
+    blocked_file_extensions: List[str] = field(
+        default_factory=lambda: list(DEFAULT_BLOCKED_EXTENSIONS)
+    )
+    trusted_sources: List[str] = field(default_factory=list)
+
+    # Verdict thresholds
+    fail_on_critical: bool = True
+    fail_on_high_count: int = 3
+    review_on_high_count: int = 1
+
+    # Notifications
+    notify_on_jail: bool = True
+
+    def validate(self) -> List[str]:
+        """Validate configuration values. Returns list of issues."""
+        issues = []
+        if self.mode not in ("auto", "manual"):
+            issues.append(f"Invalid mode '{self.mode}': must be 'auto' or 'manual'")
+        if self.scan_timeout_seconds <= 0:
+            issues.append("scan_timeout_seconds must be positive")
+        if self.max_skill_size_bytes <= 0:
+            issues.append("max_skill_size_bytes must be positive")
+        if self.fail_on_high_count < 1:
+            issues.append("fail_on_high_count must be >= 1")
+        if self.review_on_high_count < 1:
+            issues.append("review_on_high_count must be >= 1")
+        return issues
+
+
+def load_isolation_config(config_path: Optional[Path] = None) -> IsolationConfig:
+    """
+    Load isolation chamber configuration from ~/.tweek/config.yaml.
+
+    Falls back to defaults if file is missing or section is absent.
+
+    Args:
+        config_path: Override config file path (for testing)
+
+    Returns:
+        IsolationConfig with loaded or default values
+    """
+    if config_path is None:
+        config_path = Path.home() / ".tweek" / "config.yaml"
+
+    if not config_path.exists():
+        return IsolationConfig()
+
+    try:
+        with open(config_path) as f:
+            full_config = yaml.safe_load(f) or {}
+    except Exception:
+        return IsolationConfig()
+
+    section = full_config.get("isolation_chamber", {})
+    if not section or not isinstance(section, dict):
+        return IsolationConfig()
+
+    return _config_from_dict(section)
+
+
+def _config_from_dict(data: Dict[str, Any]) -> IsolationConfig:
+    """Build IsolationConfig from a dict, ignoring unknown keys."""
+    known_fields = {f.name for f in IsolationConfig.__dataclass_fields__.values()}
+    filtered = {k: v for k, v in data.items() if k in known_fields}
+    return IsolationConfig(**filtered)
+
+
+def save_isolation_config(
+    config: IsolationConfig,
+    config_path: Optional[Path] = None,
+) -> None:
+    """
+    Save isolation chamber configuration to ~/.tweek/config.yaml.
+
+    Preserves other sections in the config file.
+
+    Args:
+        config: The configuration to save
+        config_path: Override config file path (for testing)
+    """
+    if config_path is None:
+        config_path = Path.home() / ".tweek" / "config.yaml"
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load existing config to preserve other sections
+    full_config = {}
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                full_config = yaml.safe_load(f) or {}
+        except Exception:
+            full_config = {}
+
+    # Update just the isolation_chamber section
+    section = {}
+    for field_name in IsolationConfig.__dataclass_fields__:
+        value = getattr(config, field_name)
+        default_value = getattr(IsolationConfig(), field_name)
+        # Only write non-default values to keep config clean
+        if value != default_value:
+            section[field_name] = value
+
+    if section:
+        full_config["isolation_chamber"] = section
+    elif "isolation_chamber" in full_config:
+        del full_config["isolation_chamber"]
+
+    with open(config_path, "w") as f:
+        yaml.dump(full_config, f, default_flow_style=False, sort_keys=False)

tweek/skills/fingerprints.py

@@ -0,0 +1,198 @@
+"""
+Tweek Skill Fingerprint Cache
+
+Tracks SHA-256 hashes of known-approved SKILL.md files to detect
+new or modified skills that arrive via git pull, clone, or branch switch.
+
+When the PreToolUse hook encounters a SKILL.md with no fingerprint or a
+changed hash, it routes the skill through the isolation chamber.
+"""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from tweek.skills import SKILLS_DIR, get_claude_project_skills
+
+
+FINGERPRINT_PATH = SKILLS_DIR / "fingerprints.json"
+
+
+class SkillFingerprints:
+    """
+    SHA-256 fingerprint cache for known-approved skills.
+
+    Format:
+    {
+        "schema_version": 1,
+        "skills": {
+            "/abs/path/.claude/skills/my-skill/SKILL.md": {
+                "sha256": "abc123...",
+                "scanned_at": "2026-02-01T15:30:00Z",
+                "verdict": "pass",
+                "report_path": "..."
+            }
+        }
+    }
+    """
+
+    def __init__(self, cache_path: Optional[Path] = None):
+        self.cache_path = cache_path or FINGERPRINT_PATH
+        self._data = self._load()
+
+    def _load(self) -> Dict:
+        """Load fingerprints from disk."""
+        if not self.cache_path.exists():
+            return {"schema_version": 1, "skills": {}}
+        try:
+            data = json.loads(self.cache_path.read_text())
+            if not isinstance(data, dict) or "skills" not in data:
+                return {"schema_version": 1, "skills": {}}
+            return data
+        except (json.JSONDecodeError, IOError):
+            return {"schema_version": 1, "skills": {}}
+
+    def _save(self) -> None:
+        """Persist fingerprints to disk."""
+        self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+        self.cache_path.write_text(json.dumps(self._data, indent=2))
+
+    @staticmethod
+    def _hash_file(file_path: Path) -> str:
+        """Compute SHA-256 hash of a file."""
+        h = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                h.update(chunk)
+        return h.hexdigest()
+
+    def is_known(self, skill_md_path: Path) -> bool:
+        """
+        Check if a SKILL.md file is known and unchanged.
+
+        Args:
+            skill_md_path: Absolute path to a SKILL.md file
+
+        Returns:
+            True if the file hash matches the stored fingerprint
+        """
+        key = str(skill_md_path.resolve())
+        entry = self._data["skills"].get(key)
+        if not entry:
+            return False
+
+        try:
+            current_hash = self._hash_file(skill_md_path)
+        except (IOError, OSError):
+            return False
+
+        return entry.get("sha256") == current_hash
+
+    def register(
+        self,
+        skill_md_path: Path,
+        verdict: str = "pass",
+        report_path: Optional[str] = None,
+    ) -> None:
+        """
+        Register a SKILL.md file as known-approved.
+
+        Args:
+            skill_md_path: Absolute path to the SKILL.md
+            verdict: The scan verdict that approved it
+            report_path: Path to the scan report
+        """
+        key = str(skill_md_path.resolve())
+        try:
+            current_hash = self._hash_file(skill_md_path)
+        except (IOError, OSError):
+            return
+
+        self._data["skills"][key] = {
+            "sha256": current_hash,
+            "scanned_at": datetime.now(timezone.utc).isoformat(),
+            "verdict": verdict,
+            "report_path": report_path or "",
+        }
+        self._save()
+
+    def remove(self, skill_md_path: Path) -> None:
+        """Remove a fingerprint entry."""
+        key = str(skill_md_path.resolve())
+        if key in self._data["skills"]:
+            del self._data["skills"][key]
+            self._save()
+
+    def check_project_skills(
+        self, working_dir: Optional[Path] = None
+    ) -> List[Tuple[Path, str]]:
+        """
+        Check all SKILL.md files in a project's .claude/skills/ directory.
+
+        Returns a list of (path, status) tuples where status is:
+        - "known": file hash matches fingerprint
+        - "new": file has no fingerprint
+        - "modified": file hash differs from fingerprint
+
+        Args:
+            working_dir: Project working directory (defaults to cwd)
+
+        Returns:
+            List of (skill_md_path, status) tuples for unknown/modified skills
+        """
+        skills_dir = get_claude_project_skills(working_dir)
+        if not skills_dir.exists():
+            return []
+
+        results = []
+        for skill_md in skills_dir.rglob("SKILL.md"):
+            resolved = skill_md.resolve()
+            key = str(resolved)
+            entry = self._data["skills"].get(key)
+
+            if not entry:
+                results.append((skill_md, "new"))
+            else:
+                try:
+                    current_hash = self._hash_file(skill_md)
+                    if current_hash != entry.get("sha256"):
+                        results.append((skill_md, "modified"))
+                    # "known" skills are not returned (nothing to do)
+                except (IOError, OSError):
+                    results.append((skill_md, "new"))
+
+        return results
+
+    def cleanup_stale(self) -> int:
+        """
+        Remove fingerprints for files that no longer exist.
+
+        Returns:
+            Number of stale entries removed
+        """
+        stale_keys = []
+        for key in self._data["skills"]:
+            if not Path(key).exists():
+                stale_keys.append(key)
+
+        for key in stale_keys:
+            del self._data["skills"][key]
+
+        if stale_keys:
+            self._save()
+
+        return len(stale_keys)
+
+
+# Module-level singleton
+_fingerprints: Optional[SkillFingerprints] = None
+
+
+def get_fingerprints() -> SkillFingerprints:
+    """Get the singleton SkillFingerprints instance."""
+    global _fingerprints
+    if _fingerprints is None:
+        _fingerprints = SkillFingerprints()
+    return _fingerprints